Microsoft DirectX 8.0 |
Note This interface has been deprecated. New applications should not use it.
The IDirectDraw3 interface is available to applications that have created a DirectDraw object through the IDirectDrawFactory::CreateDirectDraw method. This method retrieves the address of a pointer to an IDirectDraw interface, which your application can use to query for the IDirectDraw3 interface.
The IDirectDraw3 interface extends the IDirectDraw and the IDirectDraw2 interfaces by adding the IDirectDraw3::GetSurfaceFromDC method and providing new behavior for the IDirectDraw3::CreateSurface method.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IDirectDraw3 methods Description CreateSurface Creates a DirectDrawSurface object from a DirectDraw object. GetSurfaceFromDC Retrieves a pointer to an IDirectDrawSurface interface from a handle to a device context.
Creates a DirectDrawSurface object from a DirectDraw object.
Syntax
STDMETHOD CreateSurface( LPDDSURFACEDESC lpDDSurfaceDesc, LPDIRECTDRAWSURFACE FAR *lplpDDSurface, IUnknown FAR *pUnkOuter ) PURE;
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.
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.
Retrieves a pointer to an IDirectDrawSurface interface from a handle to a device context.
Syntax
STDMETHOD GetSurfaceFromDC(
HDC hdc,
IDirectDrawSurface **ppSurface
) PURE;
Parameters
- hdc
- [in] Handle of the device context (DC).
- ppSurface
- [out] Address of a pointer to an IDirectDrawSurface interface.
Return Value
Returns S_OK if successful, or one of the following values otherwise.
E_POINTER Invalid pointer to IDirectDrawSurface. DDERR_NOTFOUND The requested item wasn't found.