DDSURFACEDESC2 structure

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

Note  Rather than use this structure to decode files with the DirectDraw Surface (DDS) file format (.dds), you should use an alternative structure that does not rely on Ddraw.h. For more information about alternative structures for DDS, see DDS.
 

Syntax


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

Members

dwSize

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

dwFlags

The following flags to describe optional controls for this structure:

DDSD_ALL

All input members are valid.

DDSD_ALPHABITDEPTH

The dwAlphaBitDepth member is valid.

DDSD_BACKBUFFERCOUNT

The dwBackBufferCount member is valid.

DDSD_CAPS

The ddsCaps member is valid.

DDSD_CKDESTBLT

The ddckCKDestBlt member is valid.

DDSD_CKDESTOVERLAY

The ddckCKDestOverlay member is valid.

DDSD_CKSRCBLT

The ddckCKSrcBlt member is valid.

DDSD_CKSRCOVERLAY

The ddckCKSrcOverlay member is valid.

DDSD_HEIGHT

The dwHeight member is valid.

DDSD_LINEARSIZE

The dwLinearSize member is valid.

DDSD_LPSURFACE

The lpSurface member is valid.

DDSD_MIPMAPCOUNT

The dwMipMapCount member is valid.

DDSD_PITCH

The lPitch member is valid.

DDSD_PIXELFORMAT

The ddpfPixelFormat member is valid.

DDSD_REFRESHRATE

The dwRefreshRate member is valid.

DDSD_TEXTURESTAGE

The dwTextureStage member is valid.

DDSD_WIDTH

The dwWidth member is valid.

DDSD_ZBUFFERBITDEPTH

Obsolete; see Remarks.

dwHeight

Height of the surface to be created, in pixels.

dwWidth

Width of the surface to be created, in pixels.

DUMMYUNIONNAMEN(1)
lPitch

Distance, in bytes, to the start of the next line. When used with the IDirectDrawSurface7::GetSurfaceDesc method, this is a return value. When creating a surface from existing memory or when calling the IDirectDrawSurface7::SetSurfaceDesc method, this is an input value that must be a DWORD multiple. For more information, see Remarks.

dwLinearSize

Size of the buffer. Currently returned only for compressed texture surfaces.

DUMMYUNIONNAMEN(5)
dwBackBufferCount

Number of back buffers.

dwDepth

The depth, in pixels, of the surface if it is a volume texture.

DUMMYUNIONNAMEN(2)
dwMipMapCount

Number of mipmap levels.

dwRefreshRate

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

dwSrcVBHandle

Not used.

dwAlphaBitDepth

Depth of the alpha buffer.

dwReserved

Reserved

lpSurface

Address of the associated surface memory. When calling IDirectDrawSurface7::Lock, this member contains a valid pointer to surface memory after the call returns. When creating a surface from existing memory or using the IDirectDrawSurface7::SetSurfaceDesc method, this member is an input value that is the address of system memory allocated by the calling application. Do not set this member if your application needs DirectDraw to allocate and manage surface memory.

DUMMYUNIONNAMEN(3)
ddckCKDestOverlay

A DDCOLORKEY structure that describes the destination color key for an overlay surface.

dwEmptyFaceColor

Physical color for empty cubemap faces.

ddckCKDestBlt

A DDCOLORKEY structure that describes the destination color key for bit-block transfer (bitblt) operations.

ddckCKSrcOverlay

A DDCOLORKEY structure that describes the source color key for an overlay surface.

ddckCKSrcBlt

A DDCOLORKEY structure that describes the source color key for bitblt operations.

DUMMYUNIONNAMEN(4)
ddpfPixelFormat

A DDPIXELFORMAT structure that describes the surface's pixel format.

dwFVF

Vertex format description of vertex buffers.

ddsCaps

A DDSCAPS2 structure that contains the surface's capabilities.

dwTextureStage

Stage identifier that is used to bind a texture to a specific stage in a multitexture cascade 3-D device. Although not required for all hardware, you should set this member for best performance on the largest variety of 3-D accelerators. Hardware that requires explicitly assigned textures exposes the D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D device capability in the DEVCAPS member of the D3DCAPS9 structure that is filled by the GetDeviceCaps method.

Remarks

The lPitch and lpSurface members are output values when you call the IDirectDrawSurface7::GetSurfaceDesc method. When you create surfaces from existing memory or update surface characteristics, these members are input values that describe the pitch and location of memory that was allocated by the calling application for use by DirectDraw. DirectDraw does not attempt to manage or free memory that was 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 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

Header

Ddraw.h

 

 

Show: