Graphics Low-Level Client Support

[These functions are subject to change with each operating system revision. Instead, use the Microsoft DirectDraw and Microsoft Direct3DAPIs; these APIs insulate applications from such operating system changes, and hide many other difficulties involved in interacting directly with display drivers. For more information, see Introduction to Display.]

DirectDraw and Direct3D use some kernel-mode routines to communicate with the operating system and the display driver.

The operating system kernel appears to be a DirectDraw/Direct3D display driver from the point of view of user-mode components. Some differences between kernel and display drivers do exist however. The kernel mode components keep a copy of structures representing DirectDraw/Direct3D objects, such as devices and surfaces. The user mode component of DirectDraw/Direct3D request the creation of those structures, which are referred to with handles returned by kernel mode. Consequently, the differences are mostly in the arguments passed to the routines: kernel accepts handles whereas drivers typically accept pointers.

• Evolution of Kernel Mode Entry Points
• Calling the Kernel
• Writing Portable Applications
• Device Creation
• Kernel Objects
• Functions
• Related topics

Evolution of Kernel Mode Entry Points

DirectDraw makes all of its connections to kernel mode through the Gdi32.dll using several entry points. These entry points typically just marshal parameters. As part of device creation, the Gdi32.dll returns pointers to routines within itself that are then used by DirectDraw and Direct3D 7.0.

Direct3D 8.x makes a clean break from Gdi32.dll, and calls into the kernel-mode entry points directly.

Calling the Kernel

These entry points are similar and, in many cases, identical to entry points in the display driver itself, so an understanding of the Driver Development Kit (DDK) materials for DirectDraw and Direct3D is an essential prerequisite to using these functions.

Calling these functions differs between operating systems. On Windows 2000, the W2KUMODE.LIB library contains routines that enable the calling thread to make the transition to kernel-mode. These routines do no parameter marshalling, and are the ideal calling mechanism on Windows 2000. The mechanism that makes the transition to kernel mode relies on the ordering of a table. This ordering will change across operating system revisions. Therefore, it is not advisable to build an application that relies on W2KUMODE.LIB for Windows 2000 and expect it to run un-modified on Windows XP. A mechanism for creating operating system portability is described in the following section.

On Windows XP, D3D8THK.DLL exports all of the kernel mode functions, but with a slightly decorated name. The following example shows how applications can alias the low-level client functions using the preprocessor. Before doing this, dynamically link to D3D8THK.DLL.

#define NtGdiDdUnlock OsThunkDdUnlock
#include "ntgdi.h"      // Brings in the definition of "NtGdiDdUnlock", 
.                       //   which is now seen as OsThunkDdUnlock.
.
.
OsThunkDdUnlock(hSurface, puUnlockData);

Writing Portable Applications

Several techniques are available to make an application portable across operating systems. The most robust is to install the Microsoft DirectX 8.x redistributable package on Windows 2000 as part of your own application's install process. This guarantees that D3D8THK.DLL will be available on Windows 2000 systems and allows a single code-path in the application, because you can use the same technique as described for Windows XP above.

Applications can also build their own insulating DLL and implement two versions of that DLL, one for Windows 2000 using the technique shown above and one for Windows XP that uses D3D8THK.DLL.

Device Creation

DirectDraw and Direct3D first must create an instance of the kernel's abstraction of the driver object. In Gdi32.dll and Ddraw.dll, this is achieved by calling DdCreateDirectDrawObject, DdQueryDirectDrawObject and DdReenableDirectDrawObject. In Direct3D 8.x, this is achieved by calling NtGdiDdCreateDirectDrawObject, NtGdiDdQueryDirectDrawObject and NtGdiDdReenableDirectDrawObject. Note that the GdiEntry* entry points are merely marshallers for the kernel-mode entry points.

After calling these functions, a handle is returned that represents the kernel object's abstraction of a DirectDraw device. This kernel object represents a driver instance owned by the display driver. This handle can be used in subsequent calls such as DdCreateSurfaceObject (or NtGdiDdCreateSurfaceObject in Direct3D 8.x) to build further objects.

Kernel Objects

A few entry points are used to manage the kernel mode representations of certain objects. DdCreateSurfaceObject (or NtGdiDdCreateSurfaceObject in Direct3D 8.x) is a good example. This entry point creates a kernel mode object representing a piece of system memory. The entry point returns a handle, and this handle can be used in subsequent drawing calls. The kernel derives a pointer to its own structure from these handles, and passes that pointer to the display driver, which then carries out the operation.

Functions

This table lists functions that represent kernel-mode entry points, and the user-mode helper routines in Gdi32.dll that wrap these entry points.

Related topics

Command and Vertex Buffer Allocation

Introduction to Display