Microsoft DirectX 9.0

IDirectDraw3::CreateSurface

Note   The IDirectDraw3 interface is deprecated.

Creates a DirectDrawSurface object from a DirectDraw object.

Syntax

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

Parameters

lpDDSurfaceDesc

[in] Pointer to the DDSURFACEDESC structure that describes the requested surface. You should set any unused members of DDSURFACEDESC to zero before calling this method. A DDSCAPS structure is a member of DDSURFACEDESC.

lplpDDSurface

[out] Address of a pointer to be initialized with a valid DirectDrawSurface pointer if the call succeeds.

pUnkOuter

[in] Pointer to an IUnknown interface on an outer object that will be aggregated with an inner object's IUnknown interface.

Return Value

Returns DD_OK if successful, or one of the following error values otherwise.

Value Description
DDERR_INCOMPATIBLEPRIMARY The primary surface creation request does not match the existing primary surface.
DDERR_INVALIDCAPS One or more of the capability bits passed to the callback function are incorrect.
DDERR_INVALIDOBJECT DirectDraw received a pointer to an invalid DirectDraw object.
DDERR_INVALIDPARAMS One or more of the parameters passed to the method are incorrect.
DDERR_INVALIDPIXELFORMAT The pixel format was invalid as specified.
DDERR_NOALPHAHW No alpha acceleration hardware is present or available, which caused the requested operation to fail.
DDERR_NOCOOPERATIVELEVELSET The IDirectDraw2::SetCooperativeLevel method was not called before the surface was created.
DDERR_NODIRECTDRAWHW Hardware-only DirectDraw object creation isn't possible; the driver doesn't support any hardware.
DDERR_NOEMULATION Software emulation isn't available.
DDERR_NOEXCLUSIVEMODE The operation requires the application to have exclusive mode, but the application doesn't have exclusive mode.
DDERR_NOFLIPHW Flipping visible surfaces isn't supported.
DDERR_NOMIPMAPHW The operation can't be carried out because no mipmap texture mapping hardware is present or available.
DDERR_NOOVERLAYHW The operation can't be carried out because no overlay hardware is present or available.
DDERR_NOZBUFFERHW The operation to create a z-buffer in display memory or to perform a blit using a z-buffer can't be carried out because there is no hardware support for z-buffers.
DDERR_OUTOFMEMORY DirectDraw doesn't have enough available memory to perform the operation.
DDERR_OUTOFVIDEOMEMORY DirectDraw doesn't have enough display memory to perform the operation.
DDERR_PRIMARYSURFACEALREADYEXISTS The application has already created a primary surface.
DDERR_UNSUPPORTEDMODE The display is currently in an unsupported

mode.

DDERR_UNSUPPORTED The operation isn't supported.

Remarks

Passing in NULL for the pUnkOuter parameter will return the address of a DirectDraw surface in the lplpDDSurface parameter. However, if you pass in a pointer to an outer interface you want to aggregate with an inner interface, you will get back an IUnknown pointer for the lplpDDSurface parameter.

DirectDrawEx now also provides the DDSCAPS_DATAEXCHANGE flag for the dwcaps member of the DDSCAPS structure, which is defined as a combination of DDSCAPS_SYSTEMMEMORY and DDSCAPS_VIDEOMEMORY in Ddrawex.h. When a surface is created using the DDSCAPS_DATAEXCHANGE flag, the surface will be automatically moved into video memory if there is enough video memory available; otherwise, a system memory surface will be created. Also, setting this flag in conjunction with the DDSCAPS_OWNDC flag enables applications to call the IDirectDrawSurface::GetDC method to lock the device context for as long they require, without holding a lock on the surface.

This method calls the IDirectDraw::CreateSurface and IDirectDraw2::CreateSurface methods.

See Also