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

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.

###

IDirectDraw3::CreateSurface

IDirectDraw3 Interface

Creates a DirectDrawSurface object from a DirectDraw object.

STDMETHOD CreateSurface(
LPDDSURFACEDESC lpDDSurfaceDesc,
LPDIRECTDRAWSURFACE FAR *lpDDSurface,
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.
lpDDSurface
  [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 Values

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

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 Values

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.