DrvEnablePDEV

Article
06/30/2006

This function enables a device context for drawing and returns device metrics for the target printer or display device in a GDIINFO structure. Printer drivers call a display driver's DrvEnablePDEV function to create and initialize the device context, and then substitute the printer's device metrics before returning the device context to the graphics device interface (GDI) for bitmap rendering.

DHPDEV APIENTRY DrvEnablePDEV(
  DEVMODEW* pdm,
  LPWSTR pwszLogAddress,
  ULONG cPat,
  HSURF* phsurfPatterns,
  ULONG cjCaps,
  ULONG* pdevcaps,
  ULONG cjDevInfo,
  DEVINFO* pdi,
  HDEV hdev,
  LPWSTR pwszDeviceName,
  HANDLE hDriver 
);

Parameters

pdm
[in] Pointer to a DEVMODEW structure that contains driver data. DrvEnablePDEV should return the default mode of the hardware when GDI calls it with the dmBitsPerPel, dmPelsWidth, dmPelsHeight, and dmDisplayFrequency members of DEVMODEW set to 0.
pwszLogAddress
[in] Display drivers should ignore this parameter. For printer drivers, a pointer to the logical address string that is the user's name for the location to which the driver is writing. Examples include "LPT1" or "My Printer."
cPat
[in] Display drivers should ignore this parameter. For printer drivers, the number of surface handles in the buffer pointed to by phsurfPatterns. The driver cannot access memory beyond the end of the buffer.

phsurfPatterns
[out] Display drivers should ignore this parameter. For printer drivers, this is a pointer to a buffer that the driver fills with surface handles that represent the standard fill patterns. GDI calls DrvRealizeBrush with one of these surfaces to realize a brush with a standard pattern.

Each of these surfaces must be a monochrome, 1 bit per pixel, GDI bitmap for raster devices. The device driver should choose patterns that will look most like standard patterns when written on the device surface.

GDI is never required to use these brushes in support routines for a vector device. Therefore, surfaces can be device-supported surfaces that DrvRealizeBrush recognizes as standard patterns.

The following table shows the patterns that you must define, in order.

Pattern	Description
HS_HORIZONTAL	Horizontal hatch.
HS_VERTICAL	Vertical hatch.
HS_FDIAGONAL	45-degree upward hatch from left to right.
HS_BDIAGONAL	45-degree downward hatch from left to right.
HS_CROSS	Horizontal and vertical cross hatch.
HS_DIAGCROSS	45-degree crosshatch.

cjCaps
[in] Size of the buffer pointed to by pdevcaps. The driver must not access memory beyond the end of the buffer.
pdevcaps
[out] Pointer to a GDIINFO structure that describes device capabilities. GDI zero-initializes this structure calling DrvEnablePDEV.
cjDevInfo
[in] Number of bytes in the DEVINFO structure pointed to by pdi. The driver should modify no more than this number of bytes in DEVINFO.
pdi
[out] Pointer to the DEVINFO structure, which describes the driver and the physical device. The driver should only alter the members it understands. GDI fills this structure with zeros before a call to DrvEnablePDEV.
hdev
[in] GDI-supplied handle to the device. This handle is the input to some GDI callbacks, such as EngGetDriverName.
pwszDeviceName
[in] Pointer to a zero-terminated string that is the user-readable name of the device.
hDriver
[in] Driver that supports the device. For a printer driver, use this parameter as a handle to the printer when calling the spooler.

Return Values

Handle to the PDEV that identifies the enabled device if the function succeeds. That is, DrvEnablePDEV returns a handle to the private, driver-defined device instance information upon success. Otherwise, it returns NULL.

Remarks

DrvEnablePDEV is required for graphics drivers.

A graphics device driver might support several physical devices attached to different logical addresses. Drivers must also support simultaneous use of different drawing surfaces.

The purposes of DrvEnablePDEV are to inform GDI of the physical characteristics of the device and to create a private PDEV structure describing the current device instance based on the received DEVMODE structure and device name. When GDI subsequently calls other graphics device driver interface (DDI) functions, it supplies the handle returned by DrvEnablePDEV as input, usually within a SURFOBJ structure, so the driver can identify the device instance.

A single logical device can manage several PDEV data structures. The following table shows how you can differentiate the PDEV data structures.

Differentiation method	Description
Type of hardware	A single device driver might support "LaserWhiz," "LaserWhiz II," and "LaserWhiz Super."
Logical address	A single device driver can support printers attached to "LPT1," "COM2," "\SERVER1\PSLAZER," and so on. A display driver that can support more than one VGA display simultaneously might differentiate them according to port numbers; for example, 0x3CE or 0x2CE.
Surfaces	A printer driver can process two print jobs simultaneously. The two surfaces represent two printed pages. Similarly, a display device driver might support two desktops on the same device.

When receiving a call to this function, the driver must allocate the memory to support the PDEV. However, then you do not need to support the actual surface until GDI calls DrvEnableSurface.

If a device surface requires an allocated bitmap, you do not need to make these allocations until you actually need them. Although applications often request device information long before actually writing to the device, waiting to allocate resources, such as large bitmaps, can conserve memory.

GDI zero-initializes the buffer pointed to by phsurfPatterns before calling this function.

Requirements

OS Versions: Windows CE 1.0 and later.
Header: Winddi.h.
Link Library: Ddi_ati_lib.lib, Ddi_flat_lib.lib, Ddi_gx_lib.lib, Ddi_mq200_lib.lib, Ddi_nop_lib.lib, Ddi_perm3_lib.lib, Ddi_rflat_lib.lib, Ddi_rgx_lib.lib, or Ddi_tvia5_lib.lib.

DrvEnablePDEV

Parameters

Return Values

Remarks

Requirements

See Also

Additional resources