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.
A version of this page is also available for
4/8/2010

An off-screen surface is often used to cache bitmaps that will later be blitted to the primary surface or a back buffer.

You must declare the dimensions of an off-screen surface by including the DDSD_WIDTH and DDSD_HEIGHT flags and the corresponding values in the dwWidthand dwHeightmembers.

By default, DirectDraw creates a surface in display memory unless it will not fit, in which case it creates the surface in system memory.

You can explicitly choose display or system memory by including the DDSCAPS_SYSTEMMEMORY or DDSCAPS_VIDEOMEMORY flags in the dwCapsmember of the DDSCAPSstructure. The method fails, returning an error, if it cannot create the surface in the specified location.

Code Example

The following code example demonstrates how to prepare for creating a simple off-screen surface.

Note:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
Copy Code 
DDSURFACEDESC ddsd; 
ddsd.dwSize = sizeof(ddsd); 
 
// Tell DirectDraw which members are valid. 
ddsd.dwFlags = DDSD_HEIGHT | DDSD_WIDTH; 
 
// Request a simple off-screen surface, sized 
// 100 by 100 pixels. 
//
// (This assumes that the off-screen surface that is about 
// to be created will match the pixel format of the 
// primary surface.)
ddsd.dwHeight = 100; 
ddsd.dwWidth = 100;

Additionally, you can create surfaces whose pixel format differs from the primary surface's pixel format. However, in this case there is one drawback — you are limited to using system memory.

Code Example

The following code example demonstrates how to prepare the DDSURFACEDESCstructure members in order to create an 8-bit palettized surface (assuming that the current display mode is something other than 8-bits per pixel).

Note:
To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.
Copy Code 
memset(&ddsd, 0, sizeof(ddsd));
ddsd.dwSize  = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH |
DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_SYSTEMMEMORY;
ddsd.dwHeight = 100;
ddsd.dwWidth  = 100;
ddsd.ddpfPixelFormat.dwSize  = sizeof(DDPIXELFORMAT);
ddsd.ddpfPixelFormat.dwFlags = DDPF_RGB | DDPF_PALETTEINDEXED8;
 
// Set the bit depth for an 8-bit surface, but DO NOT 
// specify any RGB mask values. The masks must be zero
// for a palettized surface.
ddsd.ddpfPixelFormat.dwRGBBitCount = 8;