Partager via

DDSURFACEDESC (Compact 2013)

  • Article

3/26/2014

This structure contains a description of a surface.

This structure is used to pass surface parameters to the IDirectDraw::CreateSurface method.

It is also used to retrieve information about a surface in calls to IDirectDrawSurface::Lock and IDirectDrawSurface::GetSurfaceDesc.

The relevant members differ for each potential type of surface.

Syntax

typedef struct _DDSURFACEDESC {
  DWORD dwSize;
  DWORD dwFlags;
  DWORD dwHeight;
  DWORD dwWidth;
  LONG lPitch;
  LONG lXPitch;
  DWORD dwBackBufferCount;
  DWORD dwRefreshRate;
  LPVOID lpSurface;
  DDCOLORKEY ddckCKDestOverlay;
  DDCOLORKEY ddckCKDestBlt;
  DDCOLORKEY ddckCKSrcOverlay;
  DDCOLORKEY ddckCKSrcBlt;
  DDPIXELFORMAT ddpfPixelFormat;
  DDSCAPS ddsCaps;
  DWORD dwSurfaceSize;
} DDSURFACEDESC, FAR* LPDDSURFACEDESC;

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_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_LPSURFACE

    Indicates that the lpSurface 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_SURFACESIZE

    Indicates that the dwSurfaceSize member is valid.

    DDSD_WIDTH

    Indicates that the dwWidth member is valid.

    DDSD_XPITCH

    Indicates that the lXpitch member is valid.
  • 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 IDirectDrawSurface::GetSurfaceDesc method, this is a return value.

    See remarks for more information.

  • lXPitch
    Distance, in bytes, to next pixel to the right.
  • dwBackBufferCount
    Number of back buffers.

  • 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 Embedded Compact, therefore dwRefreshRate will always be 0.

  • lpSurface
    Address of the associated surface memory.

    When calling IDirectDrawSurface::Lock, this member is a valid pointer to surface memory.

    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
    DDSCAPS structure containing the surface's capabilities.
  • dwSurfaceSize
    Surface size, in bytes.

Remarks

The lPitch and lXPitch members are used to indicate the number of bytes between a pixel and the pixel directly below it onscreen and the pixel directly to the right of it onscreen. These will vary depending on the current rotation of the surface, and either value can be negative. For example:

On a 240x320 16bpp surface that is not rotated, lPitch will usually be 480 and lXPitch will be 2, and lpSurface will point to the first byte in memory of the surface.

Rotated to 90 degrees, lPitch becomes 2 and lXPitch becomes -480.

Rotated to 180 degrees, lPitch becomes -480 and lXPitch becomes -2.

Rotated to 270 degrees, lPitch becomes -2 and lXPitch becomes 480.

lpSurface always points to the memory for the pixel at (0,0), which when rotated is not going to be the first byte in memory of the surface.

The lPitch and lpSurface members are output values when calling the IDirectDrawSurface::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.

Requirements

Header

ddraw.h

See Also

Reference

DirectDraw Structures
DirectDraw Reference
IDirectDraw::CreateSurface
IDirectDrawSurface::Lock
IDirectDrawSurface::GetSurfaceDesc

Other Resources

DirectDraw