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 (formerly IDirectDraw2::CreateSurface). This section provides information on the new behavior of the CreateSurface method. Consult the DirectX SDK for information on the original behavior of this and all other IDirectDraw and IDirectDraw2 methods as they relate to DirectDraw objects.
For more information on additional functionality provided by DirectDrawEx, see Using DirectDrawEx.
When to Implement
Do not implement this interface; DirectDrawEx implements it for you.
When to Use
Applications use this interface when they have created a DirectDraw object through a successful call to the IDirectDrawFactory::CreateDirectDraw method. Applications can use this interface to get an IDirectDrawSurface interface pointer directly from a handle to a device context.
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.
STDMETHOD CreateSurface(
LPDDSURFACEDESC lpDDSurfaceDesc,
LPDIRECTDRAWSURFACE FAR *lpDDSurface,
IUnknown FAR *pUnkOuter
) PURE;
Returns DD_OK if successful, or one of the following error values otherwise:
Value | Meaning |
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 bitmap 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. |
Passing in NULL for the pUnkOuter parameter will return the address of a DirectDraw surface in the lpDDSurface 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 lpDDSurface parameter.
DirectDrawEx now also provides the DDSCAPS_DATAEXCHANGE flag for the dwcaps member of the DDSCAPS structure, which is defined as DDSCAPS_SYSTEMMEMORY|DDSCAPS_VIDEOMEMORY in Ddrawex.h. 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.
STDMETHOD GetSurfaceFromDC(
HDC hdc,
IDirectDrawSurface **ppSurface
) PURE;
Returns S_OK if successful, or one of the following values otherwise:
Value | Meaning |
E_POINTER | Invalid pointer to IDirectDrawSurface. |
DDERR_NOTFOUND | The requested item wasn't found. |
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.