IDirectDrawFactory Interface

The IDirectDrawFactory interface is used to create and enumerate DirectDraw objects that support the extended features of DirectDrawEx (see Using DirectDrawEx for more information).

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

Use this interface in an application when you want to create a DirectDrawEx object.

Methods in Vtable Order

IUnknown methods Description

QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IDirectDrawFactory methods Description

CreateDirectDraw Creates a DirectDraw object and retrieves pointers to the IUnknown and the IDirectDraw interfaces.
DirectDrawEnumerate Enumerates the DirectDraw surfaces installed on the system.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDirectDrawFactory methods	Description
CreateDirectDraw	Creates a DirectDraw object and retrieves pointers to the IUnknown and the IDirectDraw interfaces.
DirectDrawEnumerate	Enumerates the DirectDraw surfaces installed on the system.

IDirectDrawFactory::CreateDirectDraw

IDirectDrawFactory Interface

Creates a DirectDraw object and retrieves a pointer to its IDirectDraw interface.

Syntax

STDMETHOD CreateDirectDraw(
    GUID *pGUID,
    HWND hWnd,
    DWORD dwCoopLevelFlags,
    DWORD dwReserved,
    IUnknown *pUnkOuter,
    IDirectDraw **ppDirectDraw
) PURE;

Parameters

pGUID
[out] Pointer to the globally unique identifier (GUID) that represents the driver to be created. Set this to NULL to indicate the active display driver, or you can pass one of the following flags to restrict the active display driver's behavior for debugging purposes.

DDCREATE_EMULATIONONLY The DirectDraw object will use emulation for all features; it will not take advantage of any hardware-supported features.
DDCREATE_HARDWAREONLY The DirectDraw object will never emulate features not supported by the hardware. Attempts to call methods that require unsupported features will fail, returning DDERR_UNSUPPORTED (operation not supported).

hWnd
[in] Window handle to the application.
dwCoopLevelFlags
[in] Application's top-level behavior. Specify one or more of the following flags.

DDSCL_ALLOWMODEX Enables the use of Mode X display modes. You must use this flag with the DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN flags.
DDSCL_ALLOWREBOOT Enables the user to reboot by pressing CTRL+ALT+DEL while the application is in full-screen exclusive mode.
DDSCL_EXCLUSIVE Requests the exclusive level. You must use this flag with the DDSCL_FULLSCREEN flag. At the full screen and exclusive cooperative level, you can use the hardware to its fullest. In this mode, you can set custom and dynamic palettes, change display resolutions, compact memory, and implement page flipping. The exclusive (full-screen) mode does not prevent other applications from allocating surfaces, nor does it exclude them from using DirectDraw or GDI. However, it does prevent applications other than the one currently with exclusive access from changing the display mode or palette.
DDSCL_FULLSCREEN Indicates that the exclusive-mode owner will be in control of the entire primary surface. You must use this flag with the DDSCL_EXCLUSIVE flag.
DDSCL_NORMAL Indicates that the application will function as a regular Microsoft® Windows® application. You can't use this flag with the DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, or DDSCL_FULLSCREEN flags.
DDSCL_NOWINDOWCHANGES Indicates that DirectDraw can't minimize or restore the application window when the application is activated.

dwReserved
[in] Reserved for future use. Must be NULL.
pUnkOuter
[in] Must be NULL. Created for future compatibility with COM aggregation features. Currently, CreateDirectDraw returns an error if this parameter is anything but NULL.
ppDirectDraw
[out] Address of a pointer to an IDirectDraw interface.

Return Value

Returns DD_OK if successful, or one of the following error values otherwise.

E_OUTOFMEMORY There isn't enough memory available to create a DirectDraw object.
DDERR_GENERIC There is an undefined error condition.
DDERR_UNSUPPORTED DirectDraw doesn't support the operation.
DDERR_DIRECTDRAWALREADYCREATED A DirectDrawEx object representing this driver has already been created for this process.
DDERR_INVALIDDIRECTDRAWGUID The GUID passed to this method is not a valid DirectDrawEx driver identifier.
DDERR_INVALIDPARAMS One or more of the parameters passed to the method are incorrect.
DDERR_NODIRECTDRAWHW Hardware-only DirectDrawEx object creation isn't possible; the driver doesn't support any hardware.

Remarks

This method creates DirectDraw objects in the same way that the DirectDrawCreate function is used to create DirectDraw objects, and sets cooperative levels the same way the IDirectDraw2::SetCooperativeLevel method sets cooperative levels. However, in addition to creating a DirectDraw object, successful calls to the IDirectDrawFactory::CreateDirectDraw method will obtain a pointer to the IUnknown and IDirectDraw interfaces, which are exposed on the DirectDraw object. Applications can now query the DirectDraw object to obtain the address of a pointer to an IDirectDraw3 interface.

IDirectDrawFactory::DirectDrawEnumerate

IDirectDrawFactory Interface

Enumerates the available DirectDraw compatible devices in the system.

Syntax

STDMETHOD DirectDrawEnumerate(
    LPDDENUMCALLBACK lpCallback,
    LPVOID lpContext
) PURE;

Parameters

lpCallback
[in] Pointer to a DDEnumCallback function that will be called with a description of each DirectDrawEx-enabled hardware abstraction layer (HAL) installed in the system.
lpContext
[in] Address of an application-defined structure that the system will pass to the callback function each time the function is called.

Return Value

Returns DD_OK if successful, or DDERR_INVALIDPARAMS otherwise.

Remarks

This method functions in a similar manner to the DirectDraw function DirectDrawEnumerate, defined in the DirectX SDK.

DDCREATE_EMULATIONONLY	The DirectDraw object will use emulation for all features; it will not take advantage of any hardware-supported features.
DDCREATE_HARDWAREONLY	The DirectDraw object will never emulate features not supported by the hardware. Attempts to call methods that require unsupported features will fail, returning DDERR_UNSUPPORTED (operation not supported).

DDSCL_ALLOWMODEX	Enables the use of Mode X display modes. You must use this flag with the DDSCL_EXCLUSIVE and DDSCL_FULLSCREEN flags.
DDSCL_ALLOWREBOOT	Enables the user to reboot by pressing CTRL+ALT+DEL while the application is in full-screen exclusive mode.
DDSCL_EXCLUSIVE	Requests the exclusive level. You must use this flag with the DDSCL_FULLSCREEN flag. At the full screen and exclusive cooperative level, you can use the hardware to its fullest. In this mode, you can set custom and dynamic palettes, change display resolutions, compact memory, and implement page flipping. The exclusive (full-screen) mode does not prevent other applications from allocating surfaces, nor does it exclude them from using DirectDraw or GDI. However, it does prevent applications other than the one currently with exclusive access from changing the display mode or palette.
DDSCL_FULLSCREEN	Indicates that the exclusive-mode owner will be in control of the entire primary surface. You must use this flag with the DDSCL_EXCLUSIVE flag.
DDSCL_NORMAL	Indicates that the application will function as a regular Microsoft® Windows® application. You can't use this flag with the DDSCL_ALLOWMODEX, DDSCL_EXCLUSIVE, or DDSCL_FULLSCREEN flags.
DDSCL_NOWINDOWCHANGES	Indicates that DirectDraw can't minimize or restore the application window when the application is activated.

E_OUTOFMEMORY	There isn't enough memory available to create a DirectDraw object.
DDERR_GENERIC	There is an undefined error condition.
DDERR_UNSUPPORTED	DirectDraw doesn't support the operation.
DDERR_DIRECTDRAWALREADYCREATED	A DirectDrawEx object representing this driver has already been created for this process.
DDERR_INVALIDDIRECTDRAWGUID	The GUID passed to this method is not a valid DirectDrawEx driver identifier.
DDERR_INVALIDPARAMS	One or more of the parameters passed to the method are incorrect.
DDERR_NODIRECTDRAWHW	Hardware-only DirectDrawEx object creation isn't possible; the driver doesn't support any hardware.