Bearbeiten

Graphics Low-Level Client Support

  • Artikel

[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

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.

 

Command and Vertex Buffer Allocation

Introduction to Display