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.
| Topic | Contents |
|---|---|
| DdAttachSurface | The DdAttachSurface function attaches two kernel-mode surface representations. |
| DdCreateDIBSection | Creates a DIBSECTION structure that shares its color table with the device. GdiEntry9 is #defined as an alias for this function. |
| DdCreateDirectDrawObject | Wrapper for the NtGdiDdCreateDirectDrawObject function and creates a kernel-side representation of the DirectDraw object. A handle to this representation will be stored in pDirectDrawGlobal->hDD. GdiEntry1 is defined as an alias for this function. |
| DdCreateSurfaceObject | Wrapper for the NtGdiDdCreateSurfaceObject function and creates a kernel-mode surface object. GdiEntry4 is defined as an alias for this function. |
| DdDeleteDirectDrawObject | Wrapper for the NtGdiDdDeleteDirectDrawObject function and deletes a kernel-mode DirectDraw object that was previously created using DdCreateDirectDrawObject. GdiEntry3 is defined as an alias for this function. |
| DdDeleteSurfaceObject | Wrapper for the NtGdiDdDeleteSurfaceObject function and deletes a kernel-mode surface object previously created by NtGdiDdCreateSurfaceObject. GdiEntry5 is defined as an alias for this function. |
| DdGetDC | Wrapper for the NtGdiDdGetDC function and returns a Windows Graphics Device Interface (GDI) device context (DC) that represents the DirectDraw surface indicated. GdiEntry7 is defined as an alias for this function. |
| DdGetDxHandle | The DdGetDxHandle returns the kernel-mode Microsoft DirectX API handle to use in subsequent calls to the kernel-mode entry points that control the DirectX API mechanism. |
| DdQueryDirectDrawObject | Wrapper for the NtGdiDdQueryDirectDrawObject function and queries a previously created kernel-mode representation for capabilities. GdiEntry2 is defined as an alias for this function. |
| DdQueryDisplaySettingsUniqueness | Returns the current value of an integer that is incremented whenever a mode switch occurs, such as when there is a desktop switch, a Fast User Switch, or a full-screen Microsoft MS-DOS box. The application can call this function repeatedly and compare the old and new values of the return value to determine whether display settings have changed. GdiEntry13 is defined as an alias for this function. |
| DdReenableDirectDrawObject | Wrapper for the NtGdiDdReenableDirectDrawObject function. It re-enables a DirectDraw driver instance after a mode switch-style event such as a true mode switch, appearance of a full-screen MS-DOS box, or change of display driver. GdiEntry10 is defined as an alias for this function. |
| DdReleaseDC | Wrapper for the NtGdiDdReleaseDC function and releases a DC previously obtained through DdGetDC or GdiEntry7. GdiEntry8 is defined as an alias for this function. |
| DdResetVisrgn | Wrapper for the NtGdiDdResetVisrgn function and enables timely user-mode information on the clipping region for windows on the desktop. GdiEntry6 is defined as an alias for this function. |
| DdSetGammaRamp | The DdSetGammaRamp function sets the gamma ramp for the device. |
| DdSwapTextureHandles | Developed for device driver interfaces (DDIs) prior to Microsoft DirectDraw 7.0 and does nothing on Microsoft Windows NT systems. All parameters are ignored. GdiEntry16 is defined as an alias for this function. |
| DdUnattachSurface | The DdUnattachSurface function removes an attachment, created with DdAttachSurface, between two kernel-mode surface objects. |
| NtGdiD3DContextCreate | Creates a context. |
| NtGdiD3DContextDestroy | Deletes the specified context. |
| NtGdiD3DContextDestroyAll | Queries the amount of free memory in the driver-managed memory heap. |
| NtGdiD3DDrawPrimitives2 | Renders primitives and returns the updated render state. |
| NtGdiD3DGetDriverState | Used by both the DirectDraw and Direct3D runtimes to obtain information from the driver about its current state. |
| NtGdiD3DValidateTextureStageState | Returns the number of passes where the hardware can perform the blending operations specified in the current state. |
| NtGdiDdAddAlphaBlt | Not implemented. |
| NtGdiDdAddAttachedSurface | Attaches a surface to another surface. |
| NtGdiDdAttachSurface | Attaches two kernel-mode surface representations. |
| NtGdiDdBeginMoCompFrame | Starts decoding a new frame. |
| NtGdiDdBlt | Performs a bit-block transfer. |
| NtGdiDdCanCreateD3DBuffer | Determines whether the driver can create a driver-level command or vertex buffer of the specified description. |
| NtGdiDdCanCreateSurface | Indicates whether the driver can create a surface of the specified surface description. |
| NtGdiDdColorControl | Controls the luminance and brightness controls of an overlay surface. |
| NtGdiDdCreateD3DBuffer | Used to create a driver-level command or vertex buffer of the specified description. |
| NtGdiDdCreateDirectDrawObject | Creates a kernel-side representation of the DirectDraw object. |
| NtGdiDdCreateMoComp | Notifies the driver that a software decoder will start using motion compensation with the specified GUID. |
| NtGdiDdCreateSurface | Attaches a surface to another surface. |
| NtGdiDdCreateSurfaceEx | Creates a Direct3D surface from a DirectDraw surface and associates a requested handle value to it. |
| NtGdiDdCreateSurfaceObject | Creates a kernel-mode surface object that represents the user-mode surface object referenced by puSurfaceLocal. |
| NtGdiDdDeleteDirectDrawObject | Destroys a previously created kernel-mode DirectDraw device object. |
| NtGdiDdDeleteSurfaceObject | NtGdiDdDeleteSurfaceObject deletes a previously created kernel-mode surface object. |
| NtGdiDdDestroyD3DBuffer | Destroys a previously allocated kernel-mode DirectDraw surface object that was created with the dwCaps member of the DDSCAPS structure set to DDSCAPS_EXECUTEBUFFER. |
| NtGdiDdDestroyMoComp | Notifies the driver that this motion compensation object will no longer be used. The driver now needs to perform any necessary cleanup. |
| NtGdiDdDestroySurface | Destroys a previously allocated kernel-mode DirectDraw surface object. |
| NtGdiDdEndMoCompFrame | Completes a decoded frame. |
| NtGdiDdFlip | Causes the surface memory associated with the target and current surfaces to be interchanged. |
| NtGdiDdFlipToGDISurface | Notifies the driver when DirectDraw is flipping to or from a GDI surface. |
| NtGdiDdGetAvailDriverMemory | Queries the amount of free memory in all video memory heaps. |
| NtGdiDdGetBltStatus | Queries the blit status of the specified surface. |
| NtGdiDdGetDC | Creates a DC for the specified surface. |
| NtGdiDdGetDriverInfo | Queries the driver for additional DirectDraw and Direct3D functionality that the driver supports. |
| NtGdiDdGetDxHandle | Returns the kernel-mode DirectX API handle to use in subsequent calls to the kernel-mode entry points that control the DirectX API mechanism. |
| NtGdiDdGetFlipStatus | Determines whether the most recently requested flip on a surface has occurred. |
| NtGdiDdGetInternalMoCompInfo | Allows the driver to report that it internally allocates display memory to perform motion compensation. |
| NtGdiDdGetMoCompBuffInfo | Allows the driver to specify how many interim surfaces are required to support the specified GUID, and the size, location, and format of each of these surfaces. |
| NtGdiDdGetMoCompFormats | Indicates the uncompressed formats to which the hardware can decode the data. |
| NtGdiDdGetMoCompGuids | Retrieves the number of GUIDs the driver supports. |
| NtGdiDdGetScanLine | Returns the number of the current physical scan line. |
| NtGdiDdLock | Locks a specified area of surface memory and provides a valid pointer to a block of memory associated with a surface. |
| NtGdiDdLockD3D | Used to lock a specified area of buffer memory and to provide a valid pointer to a block of memory associated with the buffer. |
| NtGdiDdQueryDirectDrawObject | Queries a previously created kernel-mode representation of a DirectDraw object for its capabilities. |
| NtGdiDdQueryMoCompStatus | Queries the status of the most recent rendering operation to the specified surface. |
| NtGdiDdReenableDirectDrawObject | Re-enables a DirectDraw kernel-mode device object after a mode switch. |
| NtGdiDdReleaseDC | Releases the previously created DC for the indicated kernel-mode DirectDraw surface object. |
| NtGdiDdRenderMoComp | Tells the driver what macroblocks to render by specifying the surfaces containing the macroblocks, the offsets in each surface where the macroblocks exist, and the size of the macroblock data to be rendered. |
| NtGdiDdResetVisrgn | Used to enable the user mode to gain a valid understanding of the clipping region for windows on the desktop. This clipping can change asynchronously from the point of view of user-mode threads. |
| NtGdiDdSetColorKey | Sets the color key value for the specified surface. |
| NtGdiDdSetExclusiveMode | Notifies the driver when a DirectDraw application is switching to or from exclusive mode. |
| NtGdiDdSetGammaRamp | Sets the gamma ramp for the device. |
| NtGdiDdSetOverlayPosition | Sets the position for an overlay. |
| NtGdiDdUnattachSurface | Removes an attachment, created with NtGdiDdAttachSurface, between two kernel-mode surface objects. |
| NtGdiDdUnlock | Releases the lock held on the specified surface. |
| NtGdiDdUnlockD3D | Used to release a lock held on a specified area of buffer memory. |
| NtGdiDdUpdateOverlay | Repositions or modifies the visual attributes of an overlay surface. |
| NtGdiDdWaitForVerticalBlank | Returns the vertical blank status of the device. |
Related topics