DrvEnablePDEV (Compact 2013)

3/26/2014

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.

Syntax

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 "COM1" 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 Value

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.

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

See Also

Reference

Display Driver Functions
DrvEnableSurface