Creating a DirectDraw Object

[Previous] [Next]

The DirectDraw object is the object you'll use to operate on a particular display device. If any of the available display devices support hardware acceleration, the DirectDraw object can use this acceleration. You can use each of the unique DirectDraw objects available on the target system to manipulate the display device and to create clipper objects, surfaces, palettes, and so on for them.

In the first section (labeled STEP 1) of the DriverEnumCallback function shown above, the call to the DirectDrawCreateEx routine attempts to create the DirectDraw device. This function returns only the new IDirectDraw7 interface. If you want to use any of the earlier interfaces, you need to create the object by using DirectDrawCreate and querying for the interface you want to use. When you're developing new games, you should always use the newest interfaces; I recommend using DirectDrawCreateEx for all your new code. This function is declared as follows:

 HRESULT WINAPI DirectDrawCreateEx     GUID FAR *lpGUID,     LPDIRECTDRAW FAR *lplpDD,     REFIID iid,     IUnknown FAR *pUnkOuter ); 

Parameter	Description
lpGUID	Either the address of a globally unique identifier for the DirectDraw device to be used or one of the following values: NULL   Use the primary device (the active display driver). DDCREATE_EMULATIONONLY   Use the HEL device (for testing or debugging). DDCREATE_HARDWAREONLY   Use the HAL only with the default device (for testing and debugging).
lplpDD	The address of a variable to be initialized with a valid IDirectDraw7 interface pointer upon success of the call.
iid	Must be set to IID_IDirectDraw7; any other value will cause the function to fail.
pUnkOuter	Must be set to NULL; provided for future compatibility with COM aggregation features.

If the call to DirectDrawCreateEx fails, the DriverEnumCallback routine returns immediately and waits to be called again to determine whether another DirectDraw hardware device found during enumeration is available and might work. If the DirectDrawCreateEx call succeeds, you can query the object to see what capabilities it supports by using the DirectDraw method GetCaps (STEP 3 in the preceding code). The GetCaps method returns the cap bits that define which features the target system's hardware supports and which it only emulates. Note that this function only gets DirectDraw capabilities, not Direct3D capabilities (which are examined later). If the display device lacks the DirectDraw capabilities you need, you can decide not to use it for your application. Here's the declaration for GetCaps:

 HRESULT GetCaps(     LPDDCAPS lpDDDriverCaps,     LPDDCAPS lpDDHELCaps ); 

Parameter	Description
lpDDDriverCaps	The address of a DDCAPS structure to be filled with the device's hardware capabilities
lpDDHELCaps	The address of a DDCAPS structure to be filled with the HEL capabilities

You need to determine which features your code requires and which are just nice to have. Many display devices currently on the market don't support capabilities such as overlays, so you'd be wise to consider not requiring this feature. Your code should run on state-of-the-art accelerators and use whatever capabilities are available, but it should also be flexible enough to gracefully degrade the appearance of your 3D world while still running efficiently if some of these features aren't available.