Функция DrvEnablePDEV (winddi.h)

Статья
08/27/2023

Функция DrvEnablePDEV возвращает описание характеристик физического устройства в GDI.

Синтаксис

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

Параметры

[in] pdm

Указатель на структуру DEVMODEW , содержащую данные драйвера.

Для драйвера, поддерживающего Windows NT 4.0, DrvEnablePDEV должен возвращать режим по умолчанию оборудования, когда GDI вызывает его со следующими элементами DEVMODEW , равными нулю: dmBitsPerPel, dmPelsWidth, dmPelsHeight и dmDisplayFrequency.

[in] pwszLogAddress

Для драйверов принтера указывает на строку логического адреса, которая является именем пользователя для расположения, в которое записывает драйвер. Примеры: "LPT1" или "Мой принтер".

Драйверы отображения должны игнорировать этот параметр.

cPat

Для драйверов принтера указывает количество маркеров поверхности в буфере, на который указывает phsurfPatterns. Драйвер не может получить доступ к памяти за пределами буфера.

Драйверы отображения должны игнорировать этот параметр.

[in, optional] phsurfPatterns

Драйверы отображения должны игнорировать этот параметр.

Для драйверов принтера указывает на буфер, который драйвер будет заполнять маркерами поверхности, представляющими стандартные шаблоны заливки. Следующие шаблоны должны быть определены по порядку:

Шаблон	Описание
HS_HORIZONTAL	Горизонтальный люк.
HS_VERTICAL	Вертикальный люк.
HS_FDIAGONAL	Люк вверх на 45 градусов (слева направо).
HS_BDIAGONAL	45-градусный люк вниз (слева направо).
HS_CROSS	Горизонтальный и вертикальный перекрестный люк.
HS_DIAGCROSS	45-градусный перекрестие.

Примечание В предыдущей версии пакета средств разработки драйверов (DDK) было сокращено число шаблонов штриховок по умолчанию, требующих поддержки драйверов. Следовательно, HS_DDI_MAX, обычно используемая драйверами для объявления размера массива шаблонов, была уменьшена.

GDI вызывает DrvRealizeBrush с одной из этих поверхностей, чтобы реализовать кисть со стандартным шаблоном.

Каждая из этих поверхностей должна быть монохромным (1 бит на пиксель) растровым изображением GDI для растровых устройств. Драйвер устройства должен выбрать шаблоны, которые будут больше всего выглядеть как стандартные шаблоны при записи на поверхность устройства.

GDI никогда не требуется использовать эти кисти в подпрограммах поддержки для векторного устройства. Таким образом, поверхности могут быть поддерживаемыми устройствами поверхностями, которые DrvRealizeBrush распознает как стандартные шаблоны.

cjCaps

Задает размер буфера, на который указывает pdevcaps. Драйвер не должен обращаться к памяти за пределами буфера.

[out] pdevcaps

Указатель на структуру GDIINFO , которая будет использоваться для описания возможностей устройства. GDI инициализирует с нуля эту структуру, вызывая DrvEnablePDEV.

cjDevInfo

Указывает количество байтов в структуре DEVINFO, на которую указывает pdi. Драйвер должен изменять не более этого числа байтов в DEVINFO.

[out] pdi

Указатель на структуру DEVINFO , которая описывает драйвер и физическое устройство. Драйвер должен изменять только элементы, которые он понимает. GDI заполняет эту структуру нулями перед вызовом DrvEnablePDEV.

hdev

Дескриптор, предоставленный GDI для устройства. Этот дескриптор необходимо использовать в качестве входных данных для некоторых обратных вызовов GDI, таких как EngGetDriverName.

[in] pwszDeviceName

Указатель на строку, завершающуюся нулевым значением, которая является удобочитаемым пользователем именем устройства.

hDriver

Дескриптор для устройства вывода. Для драйвера дисплея это дескриптор устройства отображения. Для драйвера принтера этот параметр следует использовать в качестве дескриптора принтера в вызовах очереди очереди.

Возвращаемое значение

Возвращаемое значение — это дескриптор PDEV , который идентифицирует включенное устройство, если функция выполнена успешно. То есть DrvEnablePDEV возвращает дескриптор частным данным экземпляра устройства, определенного драйвером, после успешного выполнения. В противном случае возвращается значение NULL.

Драйвер графического устройства может поддерживать несколько физических устройств, подключенных к разным логическим адресам. Драйверы также должны поддерживать одновременное использование различных поверхностей рисования.

DrvEnablePDEV может быть следующим:

Для информирования GDI о физических характеристиках устройства.
Создание частной структуры PDEV, описывающей текущий экземпляр устройства (на основе полученной структуры DEVMODE и имени устройства).

Когда GDI впоследствии вызывает другие графические функции DDI, он предоставляет дескриптор, возвращенный DrvEnablePDEV , в качестве входных данных (обычно в структуре SURFOBJ), чтобы драйвер смог идентифицировать экземпляр устройства.

Одно логическое устройство может управлять несколькими PDEV, которые можно отличить следующим образом:

Тип оборудования. Один драйвер устройства может поддерживать "LaserWhiz", "LaserWhiz II" и "LaserWhiz Super".
Логический адрес — один драйвер устройства может поддерживать принтеры, подключенные к "LPT1", "COM2", "\SERVER1\PSLAZER" и т. д. Драйвер дисплея, поддерживающий одновременно несколько дисплеев VGA, может различать их по номерам портов; например, 0x3CE или 0x2CE.
Surfaces — драйвер принтера может одновременно обрабатывать два задания печати. Две поверхности представляют две страницы, которые будут напечатаны. Аналогичным образом драйвер устройства отображения может поддерживать два рабочих стола на одном устройстве.

При получении вызова этой функции драйвер должен выделить память для поддержки PDEV. Однако фактическая поверхность не должна поддерживаться до тех пор, пока GDI не вызовет DrvEnableSurface.

Если поверхности устройства требуется выделить растровое изображение, эти выделения не должны выполняться до тех пор, пока это не потребуется. Хотя приложения часто запрашивают сведения об устройстве задолго до фактической записи на устройство, ожидание выделения ресурсов, таких как большие растровые изображения, может сэкономить память.

GDI инициализирует буфер, на который указывает phsurfPatterns , перед вызовом этой функции.

DrvEnablePDEV требуется для графических драйверов.