| Microsoft DirectX 8.1 (C++) |
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 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