PDEV Initialization and Cleanup

Each kernel-mode graphics driver represents a single logical device managed by GDI. In turn, a driver might manage one or more PDEVs. A PDEV is a logical representation of the physical device. It is characterized by the type of hardware, logical address, and surfaces that can be supported:

In response to a call to DrvEnablePDEV, the driver returns information about the capabilities of the hardware device to GDI through several structures.

The GDIINFO structure is zero-filled before GDI calls DrvEnablePDEV. The driver fills in GDIINFO to communicate the following information to GDI:

 

The driver should fill only the fields it supports and ignore the rest.

The DEVINFO structure is filled in by the driver with flags that describe the graphics capabilities of this PDEV. In nearly all cases, the information from DEVINFO tells GDI the level of graphics support the driver can provide. For example, if a drawing of a treble clef is needed, information within DEVINFO tells GDI if the driver can handle Bezier curves or whether GDI must send multiple line segments instead. The driver should fill in as many fields as it supports and leave the others untouched.

Another important piece of information the driver must provide is a pointer (phsurfPatterns) to a buffer filled with handles for surfaces representing the standard fill patterns. Besides the standard fill patterns, phsurfPatterns can contain a null, which causes GDI to create the pattern surface automatically according to the device resolution and the pixel size. When GDI needs to realize a brush with a standard pattern, it calls DrvRealizeBrush to realize the brush defined for the requested pattern.

DrvEnablePDEV is passed a handle, hDriver, for the kernel driver that supports the device. For a printer driver, hDriver provides the handle to the printer and is used in calls, such as EngWritePrinter, to the spooler.

Whenever GDI calls DrvEnablePDEV, the driver must allocate the memory required to support the PDEV that is created, even if DrvEnablePDEV is called to create other PDEV structures for different modes. (A driver can have several active PDEVs enabled at the same time.) However, an actual surface is not supported until GDI calls DrvEnableSurface.

If a device surface requires the allocation of a bitmap, the allocation is not necessary until the surface is enabled (usually during the DrvEnableSurface function). Although applications often request device information before actually writing to the device, waiting to allocate a large bitmap can save valuable resources and improve driver performance during system initialization.

When the installation of the PDEV is complete, GDI calls DrvCompletePDEV to inform the driver that installation of the physical device is complete. This function also provides the driver with GDI’s logical handle to the PDEV, which the driver uses in calls to GDI functions.

A call to the driver’s DrvDisablePDEV entry point indicates that the given physical device is no longer needed. In this function, the driver should free any memory and resources used by the physical device.

Refer also to Enabling and Disabling the Surface.