 Important: |
|---|
| This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
You can update the characteristics of an existing surface by using the IDirectDrawSurface5::SetSurfaceDescmethod. With this method, you can change the pixel format and location of a DirectDrawSurface object's surface memory to system memory that your application has explicitly allocated. This is useful as it allows a surface to use data from a previously allocated buffer without copying. The new surface memory is allocated by the client application and, as such, the client application must also deallocate it.
When calling the IDirectDrawSurface5::SetSurfaceDescmethod, the lpddsdparameter must be the address of a DDSURFACEDESC2structure that describes the new surface memory as well as a pointer to that memory. Within the structure, you can only set the dwFlagsmember to reflect valid members for the location of the surface memory, dimensions, pitch, and pixel format. Therefore, dwFlagscan only contain combinations of the DDSD_WIDTH, DDSD_HEIGHT, DDSD_PITCH, DDSD_LPSURFACE, and DDSD_PIXELFORMAT flags, which you set to indicate valid structure members.
Before you set the values in the structure, you must allocate memory to hold the surface. The size of the memory you allocate is important. Not only do you need to allocate enough memory to accommodate the surface's width and height, but you need to have enough to make room for the surface pitch, which must be a QWORD(8 byte) multiple. Remember, pitch is measured in bytes, not pixels.
When setting surface values in the structure, the lpSurfacemember is a pointer to the memory you allocated and the dwHeightand dwWidthmembers describe the surface dimensions in pixels. If you specify surface dimensions, you must fill the lPitchmember to reflect the surface pitch as well. Pitch must be a DWORDmultiple. Likewise, if you specify pitch, you must also specify a width value. Lastly, the ddpfPixelFormatmember describes the pixel format for the surface. With the exception of the lpSurfacemember, if you don't specify a value for these members, the method defaults to using the value from the current surface.
There are some restrictions you must be aware of when using IDirectDrawSurface5::SetSurfaceDesc, some of which are common sense. For example, the lpSurfacemember of the DDSURFACEDESC2structure must be a valid pointer to a system memory (the method doesn't support video memory pointers at this time). Also, the dwWidthand dwHeightmembers must be nonzero values. Lastly, you cannot reassign the primary surface or any surfaces within the primary's flipping chain.
You can set the same memory for multiple DirectDrawSurface objects, but you must take care that the memory is not deallocated while it is assigned to any surface object.
Using the SetSurfaceDescmethod incorrectly will cause unpredictable behavior. The DirectDrawSurface object will not deallocate surface memory that it didn't allocate. Therefore, when the surface memory is no longer needed, it is your responsibility to deallocate it. However, when SetSurfaceDescis called, DirectDraw frees the original surface memory that it implicitly allocated when creating the surface.
Last updated on Tuesday, May 18, 2004