This topic contains functions that represent the kernel mode entry points for Microsoft Windows NT platforms, and some user-mode helper routines in Gdi32.dll that wrap these entry points. The Windows NT 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

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 Microsoft 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

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)

DdGetDxHandle

The DdGetDxHandle returns the kernel-mode DirectX

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 device context (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 DirectDraw 7.0 and does nothing on 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

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.