Función DrvEnablePDEV (winddi.h)

Artículo
08/27/2023

La función DrvEnablePDEV devuelve una descripción de las características del dispositivo físico a GDI.

Sintaxis

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
);

Parámetros

[in] pdm

Puntero a una estructura DEVMODEW que contiene datos del controlador.

Para un controlador que admita Windows NT 4.0, DrvEnablePDEV debe devolver el modo predeterminado del hardware cuando GDI lo llama con los siguientes miembros DEVMODEW establecidos en cero: dmBitsPerPel, dmPelsWidth, dmPelsHeight y dmDisplayFrequency.

[in] pwszLogAddress

En el caso de los controladores de impresora, apunta a la cadena de dirección lógica que es el nombre del usuario para la ubicación a la que está escribiendo el controlador. Algunos ejemplos son "LPT1" o "Mi impresora".

Los controladores de pantalla deben omitir este parámetro.

cPat

Para los controladores de impresora, especifica el número de controladores de superficie en el búfer a los que apunta phsurfPatterns. El controlador no puede acceder a la memoria más allá del final del búfer.

Los controladores de pantalla deben omitir este parámetro.

[in, optional] phsurfPatterns

Los controladores de pantalla deben omitir este parámetro.

En el caso de los controladores de impresora, apunta a un búfer que el controlador rellenará con identificadores de superficie que representan los patrones de relleno estándar. Los siguientes patrones deben definirse en orden:

Patrón	Descripción
HS_HORIZONTAL	Sombreado horizontal.
HS_VERTICAL	Sombreado vertical.
HS_FDIAGONAL	Sombreado ascendente de 45 grados (de izquierda a derecha).
HS_BDIAGONAL	Sombreado descendente de 45 grados (de izquierda a derecha).
HS_CROSS	Sombreado horizontal y vertical.
HS_DIAGCROSS	Bloqueo cruzado de 45 grados.

Nota El número de patrones de sombreado predeterminados que requieren compatibilidad con controladores se redujo en una versión anterior del Kit de desarrollo de controladores (DDK). Por lo tanto, HS_DDI_MAX, que normalmente usan los controladores para declarar el tamaño de la matriz de patrones, se redujo.

GDI llama a DrvRealizeBrush con una de estas superficies para obtener un pincel con un patrón estándar.

Cada una de estas superficies debe ser un mapa de bits GDI monocromo (1 bits por píxel) para dispositivos ráster. El controlador de dispositivo debe elegir patrones que tendrán el aspecto más parecido a los patrones estándar cuando se escriban en la superficie del dispositivo.

GDI nunca es necesario para usar estos pinceles en rutinas de soporte técnico para un dispositivo vectorial. Por lo tanto, las superficies pueden ser superficies compatibles con dispositivos que DrvRealizeBrush reconoce como patrones estándar.

cjCaps

Especifica el tamaño del búfer al que apunta pdevcaps. El controlador no debe tener acceso a la memoria más allá del final del búfer.

[out] pdevcaps

Puntero a una estructura GDIINFO que se usará para describir las funcionalidades del dispositivo. GDI inicializa esta estructura que llama a DrvEnablePDEV.

cjDevInfo

Especifica el número de bytes de la estructura DEVINFO a la que apunta pdi. El controlador no debe modificar más de este número de bytes en el DEVINFO.

[out] pdi

Puntero a la estructura DEVINFO , que describe el controlador y el dispositivo físico. El controlador solo debe modificar los miembros que comprende. GDI rellena esta estructura con ceros antes de llamar a DrvEnablePDEV.

hdev

Identificador proporcionado por GDI para el dispositivo. Este identificador se debe usar como entrada para algunas devoluciones de llamada GDI, como EngGetDriverName.

[in] pwszDeviceName

Puntero a una cadena terminada en null que es el nombre legible por el usuario del dispositivo.

hDriver

Identificador de un dispositivo de salida. Para un controlador de pantalla, este es el identificador del dispositivo de pantalla. Para un controlador de impresora, este parámetro se debe usar como identificador para la impresora en llamadas al colador.

Valor devuelto

El valor devuelto es un identificador del PDEV que identifica el dispositivo habilitado si la función es correcta. Es decir, DrvEnablePDEV devuelve un identificador a la información de la instancia de dispositivo privada definida por el controlador cuando se realiza correctamente. De lo contrario, devuelve NULL.

Comentarios

Un controlador de dispositivo gráfico puede admitir varios dispositivos físicos conectados a diferentes direcciones lógicas. Los controladores también deben admitir el uso simultáneo de diferentes superficies de dibujo.

Los propósitos de DrvEnablePDEV son los siguientes:

Para informar a GDI de las características físicas del dispositivo.
Para crear una estructura PDEV privada que describa la instancia de dispositivo actual (basada en la estructura DEVMODE y el nombre del dispositivo recibidos).

Cuando GDI llama posteriormente a otras funciones DDI de gráficos, proporciona el identificador devuelto por DrvEnablePDEV como entrada (normalmente dentro de una estructura SURFOBJ) para que el controlador pueda identificar la instancia del dispositivo.

Un único dispositivo lógico puede administrar varios PDEV que se pueden diferenciar mediante lo siguiente:

Tipo de hardware: un único controlador de dispositivo podría admitir "LaserWhiz", "LaserWhiz II" y "LaserWhiz Super".
Dirección lógica: un único controlador de dispositivo puede admitir impresoras conectadas a "LPT1", "COM2", "\SERVER1\PSLAZER", etc. Un controlador de pantalla que puede admitir más de una pantalla VGA simultáneamente podría diferenciarlos según los números de puerto; por ejemplo, 0x3CE o 0x2CE.
Superficies: un controlador de impresora puede procesar dos trabajos de impresión simultáneamente. Las dos superficies representan dos páginas que se imprimirán. De forma similar, un controlador de dispositivo de pantalla puede admitir dos escritorios en el mismo dispositivo.

Al recibir una llamada a esta función, el controlador debe asignar la memoria para admitir el PDEV. Sin embargo, no es necesario admitir la superficie real hasta que GDI llama a DrvEnableSurface.

Si una superficie de dispositivo requiere que se asigne un mapa de bits, estas asignaciones no se deben realizar hasta que sea necesario. Aunque las aplicaciones suelen solicitar información del dispositivo mucho antes de escribir realmente en el dispositivo, esperar a asignar recursos, como mapas de bits grandes, puede ahorrar memoria.

GDI inicializa el búfer al que apunta phsurfPatterns antes de llamar a esta función.

DrvEnablePDEV es necesario para los controladores de gráficos.