|Microsoft DirectX 9.0|
Note The IDirectDraw3 interface is deprecated.
Creates a DirectDrawSurface object from a DirectDraw object.
STDMETHOD CreateSurface( LPDDSURFACEDESC lpDDSurfaceDesc, LPDIRECTDRAWSURFACE FAR *lplpDDSurface, IUnknown FAR *pUnkOuter );
[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.
[out] Address of a pointer to be initialized with a valid DirectDrawSurface pointer if the call succeeds.
[in] Pointer to an IUnknown interface on an outer object that will be aggregated with an inner object's IUnknown interface.
Returns DD_OK if successful, or one of the following error values otherwise.
|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
|DDERR_UNSUPPORTED||The operation isn't supported.|
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.