PDD_CREATESURFACE callback function

The DdCreateSurface callback function creates a DirectDraw surface.

Syntax


PDD_CREATESURFACE DdCreateSurface;

DWORD APIENTRY DdCreateSurface(
   PDD_CREATESURFACEDATA lpCreateSurface
)
{ ... }

Parameters

lpCreateSurface

Points to a DD_CREATESURFACEDATA structure that contains the information required to create a surface.

Return value

DdCreateSurface returns one of the following callback codes:

DDHAL_DRIVER_HANDLED
DDHAL_DRIVER_NOTHANDLED

Remarks

The driver can allocate the surface memory itself, request that DirectDraw perform the memory management, or specify that it does not support creating the surface at all. The following items describe these scenarios:

  • If the driver performs the allocation, it returns the DDHAL_DRIVER_HANDLED callback code and specifies DD_OK in the ddRVal member of the DD_CREATESURFACEDATA structure at lpCreateSurface. The driver also must do the following:
    • Perform the allocation and write the offset into display memory in the fpVidMem member of the DD_SURFACE_GLOBAL structure. A pointer to this DD_SURFACE_GLOBAL structure is stored in the lpGbl member of the surface's DD_SURFACE_LOCAL structure at the lplpSList member of DD_CREATESURFACEDATA.
    • If the surface has a FOURCC format, write the pitch in the lPitch member of the DD_SURFACE_GLOBAL and DDSURFACEDESC structures, and update the flags accordingly. A pointer to this DDSURFACEDESC structure is stored in the lpDDSurfaceDesc member of DD_CREATESURFACEDATA.
  • Otherwise, the driver can have the DirectDraw memory manager allocate the surface. To do so, the driver returns the DDHAL_DRIVER_NOTHANDLED callback code. The value that the driver sets in ddRVal is irrelevant. The driver sets fpVidMem to one of the following values to specify whether the driver is involved in the allocation and how DirectDraw should allocate the surface memory:

    • DDHAL_PLEASEALLOC_USERMEM. The driver is involved in the allocation in that it must return the size in bytes of the memory region in the dwUserMemSize member of DD_SURFACE_GLOBAL. DirectDraw should allocate from user memory.
    • DDHAL_PLEASEALLOC_BLOCKSIZE. The driver is involved in the allocation in that it must return the size in bytes of the memory region in the dwBlockSizeX and dwBlockSizeY members of the DD_SURFACE_GLOBAL structure. DirectDraw should allocate from offscreen memory.
    • Any value except DDHAL_PLEASEALLOC_USERMEM and DDHAL_PLEASEALLOC_BLOCKSIZE. The driver is not involved.

    If the driver specifies DDHAL_PLEASEALLOC_USERMEM or DDHAL_PLEASEALLOC_BLOCKSIZE in fpVidMem, the driver can also store pointers to private surface structures in the dwReserved1 members of the surface's DD_SURFACE_GLOBAL and DD_SURFACE_LOCAL structures. In these cases, because the driver is involved in the allocation, DirectDraw subsequently calls the driver's DdDestroySurface function to release the private surface structures.

    To prevent memory leaks, if the driver specifies any value except DDHAL_PLEASEALLOC_USERMEM and DDHAL_PLEASEALLOC_BLOCKSIZE in fpVidMem, the driver should not store pointers to private surface structures in dwReserved1 members. In this case, because the driver is not involved in the allocation, DirectDraw does not call the driver's DdDestroySurface function to release memory for the surface. The driver cannot release memory for these private surface structures. Therefore, memory leaks could occur.

    For DirectDraw to perform the allocation of a surface with a FourCC format, the driver must return the pitch, width, and height sizes in the lPitch, dwBlockSizeX, and dwBlockSizeY members, respectively, of the DD_SURFACE_GLOBAL structure. The pitch also must be returned in the lPitch member of the DDSURFACEDESC structure. For linear memory, the driver should set dwBlockSizeX to the size in bytes of the memory region and set dwBlockSizeY to 1.

    To specify that the DirectDraw runtime can create a volume texture in a heap that the runtime manages, the driver must set the indicated members of the DD_SURFACE_GLOBAL structure to the following values:

    • fpVidMem to DDHAL_PLEASEALLOC_BLOCKSIZE.
    • dwBlockSizeX and dwBlockSizeY to such values that their multiplied product is the size in bytes of the requested volume texture.
  • If the driver determines that it cannot create the surface or that its device has insufficient memory available to create the surface, then DdCreateSurface should return the DDHAL_DRIVER_HANDLED callback code and should specify in ddRVal the DDERR_Xxx error code that best describes why the surface is not supported. For example, the driver should specify the following error codes in ddRVal for the following reasons:

    • DDERR_OUTOFVIDEOMEMORY, indicating that the driver's device has insufficient memory.
    • DDERR_GENERIC, indicating that the driver does not support video memory vertex buffers. DirectDraw can then allocate vertex buffers in system memory.

    By returning this combination of codes, the driver indicates that it does not support creating the surface. The DirectDraw runtime then either creates the surface on its own or terminates the surface creation process and returns the error code to the application that requested the creation.

By default, the driver is not notified when a primary surface is created on Windows 2000 and later. However, if the driver supports GUID_NTPrivateDriverCaps in a DdGetDriverInfo call and the DDHAL_PRIVATECAP_NOTIFYPRIMARYCREATION flag is set in the dwPrivateCaps member of the DD_NTPRIVATEDRIVERCAPS structure, then the driver is notified.

Requirements

Target platform

Desktop

Header

Ddrawint.h (include Winddi.h)

See also

DD_CREATESURFACEDATA
DD_NTPRIVATEDRIVERCAPS
DdDestroySurface
DdGetDriverInfo

 

 

Send comments about this topic to Microsoft

Show: