Microsoft DirectX 9.0

IDirectDraw::CreateSurface

The CreateSurface method creates a DirectDrawSurface object for this DirectDraw object.

Syntax

HRESULT CreateSurface(
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPDIRECTDRAWSURFACE FAR *lplpDDSurface,
  IUnknown FAR *pUnkOuter
  );

Parameters

lpDDSurfaceDesc

Points to the DDSURFACEDESC structure describing the requested surface.

lplpDDSurface

Points to a pointer to be initialized with a valid IDirectDrawSurface interface pointer if the call succeeds.

pUnkOuter

Provided for future compability with COM aggregation features. Presently, however, CreateSurface returns an error if it is anything but NULL.

Return Values

Value Description
DD_OK The method succeeded.
DERR_INVALIDOBJECT DirectDraw received a pointer that was an invalid DirectDraw object.
DDERR_INVALIDPARAMS One or more of the input parameters is invalid.
DDERR_OUTOFVIDEOMEMORY DirectDraw does not have enough memory to perform the operation.
DDERR_NODIRECTDRAWHW A hardware-only DirectDraw object creation was attempted but the driver did not support any hardware.
DDERR_NOCOOPERATIVELEVELSET Create function called without SetCooperativeLevel being called.
DDERR_INVALIDCAPS One or more of the caps bits passed to the callback are incorrect.
DDERR_INVALIDPIXELFORMAT The pixel format was invalid as specified.
DDERR_NOALPHAHW Operation could not be carried out because there is no alpha accleration hardware present or available.
DDERR_NOFLIPHW Flipping visible surfaces is not supported.
DDERR_NOZBUFFERHW Operation could not be carried out because there is no hardware support for zbuffer blitting.
DDERR_NOEXCLUSIVEMODE Operation requires the application to have exclusive mode but the application does not have exclusive mode.
DDERR_OUTOFMEMORY DirectDraw does not have enough memory to perform the operation.
DDERR_PRIMARYSURFACEALREADYEXISTS This process already has created a primary surface.
DDERR_NOEMULATION Software emulation not available.
DDERR_INCOMPATIBLEPRIMARY Unable to match primary surface creation request with existing primary surface.

Remarks

The DirectDrawSurface object represents a surface (pixel memory), which usually resides in video card memory but may exist in system memory if video memory is exhausted or if explicitly requested. The method will fail if the hardware cannot provide support for the capabilities requested or has previously allocated those resources to another DirectDrawSurface object.

CreateSurface usually creates one DirectDrawSurface object. However, if the DDSCAPS_FLIP flag is set in the dwCaps member of the DDCAPS structure included in the DDSURFACEDESC structure, CreateSurface will create several DirectDrawSurface objects which are referred to collectively as a complex structure. The additional surfaces created are also referred to as implicit surfaces.

Note   DirectDraw does not permit the creation of surfaces that are wider than the primary surface.

See Also