DDSURFACEDESC2

  • Article

This structure contains a description of a surface. This structure is used to pass surface parameters to the IDirectDraw4::CreateSurface and IDirectDrawSurface5::SetSurfaceDesc methods. It is also used to retrieve information about a surface in calls to IDirectDrawSurface5::Lock and IDirectDrawSurface5::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. The following table shows the possible flags.
    Flag Description
    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, in pixels, of the surface to be created.
  • lPitch
    Distance, in bytes, to the start of next line. When used with the IDirectDrawSurface5::GetSurfaceDesc method, this is a return value. When used with the IDirectDrawSurface5::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 zero indicates that the adapter is using its default refresh rate. It is not possible to change an adapter's refresh rate in Windows CE, therefore dwRefreshRate will always be 0.
  • dwAlphaBitDepth
    Depth of alpha buffer.
  • dwReserved
    Reserved.
  • lpSurface
    Address of the associated surface memory. When calling IDirectDrawSurface5::Lock, this member is a valid pointer to surface memory. When calling IDirectDrawSurface5::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 IDirectDrawSurface5::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.

This structure is nearly identical to the DDSURFACEDESC structure, but contains a DDSCAPS2 structure as the ddsCaps member. Unlike DDSURFACEDESC, this structure does not 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 do not support nameless unions. If your compiler does not support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

Requirements

OS Versions: Windows CE 2.12 and later. Version 2.12 requires DXPAK 1.0 or later.
Header: Ddraw.h.

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.