Platform SDK: DirectX

Creating an Off-Screen Surface

[C++]

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 dwWidth and dwHeight members. Additionally, you must include the DDSCAPS_OFFSCREENPLAIN flag in the accompanying DDSCAPS2 structure.

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 dwCaps member of the DDSCAPS2 structure. The method fails, returning an error, if it can't create the surface in the specified location.

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

DDSURFACEDESC2 ddsd; 
ddsd.dwSize = sizeof(ddsd); 
 
// Tell DirectDraw which members are valid. 
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH; 
 
// Request a simple off-screen surface, sized 
// 100 by 100 pixels. 
//
// (This assumes that the off-screen surface we are about
// to create will match the pixel format of the 
// primary surface.)
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN; 
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. The following code fragment shows how to prepare the DDSURFACEDESC2 structure members in order to create an 8-bit palettized surface (assuming that the current display mode is something other than 8-bits per pixel).

ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize  = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | 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;
[Visual Basic]

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 lWidth and lHeight members. Additionally, you must include the DDSCAPS_OFFSCREENPLAIN flag in the accompanying DDSCAPS2 type.

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 lCaps member of the DDSCAPS2 type. The method fails, returning an error, if it can't create the surface in the specified location.

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

Dim ddsd As DDSURFACEDESC2
 
' Tell DirectDraw which members are valid.
ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH
 
' Request a simple off-screen surface, sized
' 100 by 100 pixels.
'
' (This assumes that the off-screen surface we are about
' to create will match the pixel format of the
' primary surface.)
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN
ddsd.lHeight = 100
ddsd.lWidth = 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. The following code fragment shows how to prepare the DDSURFACEDESC2 type members in order to create an 8-bit palettized surface (assuming that the current display mode is something other than 8-bits per pixel).

ddsd.lFlags = DDSD_CAPS Or DDSD_HEIGHT Or DDSD_WIDTH Or DDSD_PIXELFORMAT
ddsd.ddsCaps.lCaps = DDSCAPS_OFFSCREENPLAIN Or DDSCAPS_SYSTEMMEMORY
ddsd.lHeight = 100
ddsd.lWidth = 100
ddsd.ddpfPixelFormat.lFlags = DDPF_RGB Or 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.lRGBBitCount = 8

In previous versions of DirectX, the maximum width of off-screen surfaces was limited to the width of the primary surface. Beginning with DirectX 5.0, you can create surfaces as wide as you need, permitting that the display hardware can support them. Be careful when declaring wide off-screen surfaces; if the video card memory cannot hold a surface as wide as you request, the surface is created in system memory. If you explicitly choose video memory and the hardware can't support it, the call fails. For more information, see Creating Wide Surfaces.