IDirectDraw3 Interface

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. See 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.

Do not implement this interface; DirectDrawEx implements it for you.

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.

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.

IDirectDraw3::CreateSurface

IDirectDraw3 Interface

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.

IDirectDraw3::GetSurfaceFromDC

IDirectDraw3 Interface

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.

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.

E_POINTER	Invalid pointer to IDirectDrawSurface.
DDERR_NOTFOUND	The requested item wasn't found.