Driver Functions to Support Direct3D

A driver that supports Direct3D provides both Direct3D callback functions and DirectDraw DDI functions. The Direct3D DDI callbacks are prototyped as follows:

typedef DWORD (APIENTRY *LPD3DHAL_MYFUNCTIONCB) (LPD3DHAL_MYFUNCTIONDATA);

In the preceding syntax:

• LPD3DHAL_MYFUNCTIONCB points to a driver-implemented callback that can be called MyFunction. All callback names are pseudonames decided upon by the display driver writer.

• LPD3DHAL_MYFUNCTIONDATA is a pointer to a D3DHAL_MYFUNCTIONDATA structure being passed to the callback. Callback parameter structures are characterized as follows:

  • The first member of every structure, dwhContext, is the context handle that describes the 3D context in which the callback should operate. The only exception to this rule is the D3DHAL_CONTEXTCREATEDATA structure.
  • The last member of every structure is ddrval. This member is used to pass the callback's return value back to Direct3D so it can be returned to the calling application.

To determine how to initialize Direct3D callback functions, see Direct3D Driver Initialization.

The following table lists the Direct3D callback functions that are implemented in a Direct3D driver. All callback functions are required except for D3dValidateTextureStageState, which is optional depending on the hardware capabilities.

Function	Description
D3dContextCreate	Creates a context.
D3dContextDestroy	Destroys a context.
D3dCreateSurfaceEx	Creates an association between a texture handle and a surface.
D3dDestroyDDLocal	Destroys all the Direct3D surfaces previously created by D3dCreateSurfaceEx that belong to the same given local DirectDraw object.
D3dDrawPrimitives2	Renders primitives and returns updated state to Direct3D.
D3dGetDriverState	Returns state information about the driver to DirectDraw and Direct3D runtimes.
D3dValidateTextureStageState	Performs texture stage state validation, which is required for all drivers that support texturing.

In order to support Direct3D, a driver must minimally support Microsoft DirectDraw and must also implement certain DirectDraw DDI functions. The functions pertinent to Direct3D support are listed in the following table.

Function	Description
DrvGetDirectDrawInfo	This function retrieves the capabilities of the graphics hardware. In this initialization function the driver indicates that it supports Direct3D.
DdGetDriverInfo	The runtime queries this callback function with GUIDs for additional information about the driver. Several GUIDs pertain specifically to the driver's Direct3D support.

DirectDraw function and callback implementation details are discussed in DirectDraw.