DDSURFACEDESC2

The DDSURFACEDESC2 structure contains a description of a surface. This structure is used to pass surface parameters to the IDirectDraw4::CreateSurface and IDirectDrawSurface4::SetSurfaceDesc methods. It is also used to retrieve information about a surface in calls to IDirectDrawSurface4::Lock and IDirectDrawSurface4::GetSurfaceDesc. The relevant members differ for each potential type of surface.

typedef struct _DDSURFACEDESC2 {
    DWORD         dwSize;
    DWORD         dwFlags;
    DWORD         dwHeight;
    DWORD         dwWidth;
    union
    {
        LONG      lPitch;
        DWORD     dwLinearSize;
    } DUMMYUNIONNAMEN(1);
    DWORD         dwBackBufferCount;
    union
    {
        DWORD     dwMipMapCount;
        DWORD     dwRefreshRate;
    } DUMMYUNIONNAMEN(2);
    DWORD         dwAlphaBitDepth;
    DWORD         dwReserved;
    LPVOID        lpSurface;
    DDCOLORKEY    ddckCKDestOverlay;
    DDCOLORKEY    ddckCKDestBlt;
    DDCOLORKEY    ddckCKSrcOverlay;
    DDCOLORKEY    ddckCKSrcBlt;
    DDPIXELFORMAT ddpfPixelFormat;
    DDSCAPS2      ddsCaps;
    DWORD         dwTextureStage;
} DDSURFACEDESC2, FAR* LPDDSURFACEDESC2; 
 

Members

dwSize

Size of the structure, in bytes. This member must be initialized before the structure is used.

dwFlags

Optional control flags. One or more of the following flags:

DDSD_ALL

Indicates that all input members are valid.

DDSD_ALPHABITDEPTH

Indicates that the dwAlphaBitDepth member is valid.

DDSD_BACKBUFFERCOUNT

Indicates that the dwBackBufferCount member is valid.

DDSD_CAPS

Indicates that the ddsCaps member is valid.

DDSD_CKDESTBLT

Indicates that the ddckCKDestBlt member is valid.

DDSD_CKDESTOVERLAY

Indicates that the ddckCKDestOverlay member is valid.

DDSD_CKSRCBLT

Indicates that the ddckCKSrcBlt member is valid.

DDSD_CKSRCOVERLAY

Indicates that the ddckCKSrcOverlay member is valid.

DDSD_HEIGHT

Indicates that the dwHeight member is valid.

DDSD_LINEARSIZE

Indicates that the dwLinearSize member is valid.

DDSD_LPSURFACE

Indicates that the lpSurface member is valid.

DDSD_MIPMAPCOUNT

Indicates that the dwMipMapCount member is valid.

DDSD_PITCH

Indicates that the lPitch member is valid.

DDSD_PIXELFORMAT

Indicates that the ddpfPixelFormat member is valid.

DDSD_REFRESHRATE

Indicates that the dwRefreshRate member is valid.

DDSD_TEXTURESTAGE

Indicates that the dwTextureStage member is valid.

DDSD_WIDTH

Indicates that the dwWidth member is valid.

DDSD_ZBUFFERBITDEPTH

Obsolete; see remarks.

dwHeight and dwWidth

Dimensions of the surface to be created, in pixels.

lPitch

Distance, in bytes, to the start of next line. When used with the IDirectDrawSurface4::GetSurfaceDesc method, this is a return value. When used with the IDirectDrawSurface4::SetSurfaceDesc method, this is an input value that must be a DWORD multiple. See remarks for more information.

dwLinearSize

The size of the buffer. Currently returned only for compressed texture surfaces.

dwBackBufferCount

Number of back buffers.

dwMipMapCount

Number of mipmap levels.

dwRefreshRate

Refresh rate (used when the display mode is described). The value of 0 indicates an adapter fault.

dwAlphaBitDepth

Depth of alpha buffer.

dwReserved

Reserved.

lpSurface

Address of the associated surface memory. When calling IDirectDrawSurface4::Lock, this member is a valid pointer to surface memory. When calling IDirectDrawSurface4::SetSurfaceDesc, this member is a pointer to system memory that the caller explicitly allocates for the DirectDrawSurface object. See remarks for more information.

ddckCKDestOverlay

DDCOLORKEY structure that describes the destination color key to be used for an overlay surface.

ddckCKDestBlt

DDCOLORKEY structure that describes the destination color key for blit operations.

ddckCKSrcOverlay

DDCOLORKEY structure that describes the source color key to be used for an overlay surface.

ddckCKSrcBlt

DDCOLORKEY structure that describes the source color key for blit operations.

ddpfPixelFormat

DDPIXELFORMAT structure that describes the surface's pixel format.

ddsCaps

DDSCAPS2 structure containing the surface's capabilities.

dwTextureStage

Stage identifier used to bind a texture to a specific stage in 3-D device's multitexture cascade. Although not required for all hardware, setting this member is recommended for best performance on the largest variety of 3-D accelerators. Hardware that requires explicitly assigned textures will expose the D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D device capability in the D3DDEVICEDESC structure that is filled by the IDirect3DDevice3::GetCaps method.

Remarks

The lPitch and lpSurface members are output values when calling the IDirectDrawSurface4::GetSurfaceDesc method. When creating surfaces from existing memory, or updating surface characteristics, these members are input values that describe the pitch and location of memory allocated by the calling application for use by DirectDraw. DirectDraw does not attempt to manage or free memory allocated by the application. For more information, see Creating Client Memory Surfaces and Updating Surface Characteristics.

This structure is nearly identical to the DDSURFACEDESC structure, but contains a DDSCAPS2 structure as the ddsCaps member. Unlike DDSURFACEDESC, this structure doesn't contain the dwZBufferBitDepth member. Z-buffer depth is provided in the ddpfPixelFormat member.

The unions in this structure were written to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in ddraw.h.