Función DrvBitBlt (winddi.h)

Artículo
08/27/2023

La función DrvBitBlt proporciona funcionalidades generales de transferencia de bloques de bits entre superficies administradas por dispositivos, entre mapas de bits de formato estándar administrados por GDI o entre una superficie administrada por el dispositivo y un mapa de bits de formato estándar administrado por GDI.

Sintaxis

BOOL DrvBitBlt(
  [in, out]      SURFOBJ  *psoTrg,
  [in, optional] SURFOBJ  *psoSrc,
  [in, optional] SURFOBJ  *psoMask,
  [in]           CLIPOBJ  *pco,
  [in, optional] XLATEOBJ *pxlo,
  [in]           RECTL    *prclTrg,
  [in, optional] POINTL   *pptlSrc,
  [in, optional] POINTL   *pptlMask,
  [in, optional] BRUSHOBJ *pbo,
  [in, optional] POINTL   *pptlBrush,
  [in]           ROP4     rop4
);

Parámetros

[in, out] psoTrg

Puntero a la estructura SURFOBJ que describe la superficie en la que se va a dibujar.

[in, optional] psoSrc

Puntero a una estructura SURFOBJ que describe el origen de la operación de transferencia de bloques de bits, si es necesario por el parámetro rop4 .

[in, optional] psoMask

Puntero a una estructura SURFOBJ que describe una superficie que se va a usar como máscara para el parámetro rop4 . La máscara es un mapa de bits con 1 bit por píxel. Normalmente, se usa una máscara para limitar el área que se va a modificar en la superficie de destino. El enmascaramiento se selecciona estableciendo el parámetro rop4 en el valor 0xAACC. La superficie de destino no se ve afectada si la máscara es 0x0000.

La máscara será lo suficientemente grande como para cubrir el rectángulo de destino.

Si este parámetro es NULL y el parámetro rop4 requiere una máscara, se usa la máscara implícita en el pincel.

[in] pco

Puntero a una estructura CLIPOBJ que limita el área que se va a modificar. Se proporcionan servicios GDI (CLIPOBJXxx) que enumeran la región del clip como un conjunto de rectángulos. Siempre que sea posible, GDI simplifica el recorte implicado; por ejemplo, nunca se llama a esta función con un único rectángulo de recorte. GDI recorta el rectángulo de destino antes de llamar a esta función, lo que hace que el recorte adicional sea innecesario.

[in, optional] pxlo

Puntero a una estructura XLATEOBJ que especifica cómo se deben traducir los índices de color entre las superficies de origen y destino. Si pxlo es NULL, no se necesita ninguna traducción.

Si la superficie de origen está administrada por paletas, sus colores se representan mediante índices en una tabla de búsqueda de valores RGB. La estructura XLATEOBJ se puede consultar para un vector de traducción que permita al controlador de dispositivo traducir cualquier índice de origen en un índice de color para el destino.

La situación es más complicada cuando, por ejemplo, el origen es RGB, pero el destino está administrado por paletas. En este caso, la coincidencia más cercana a cada valor RGB de origen debe encontrarse en la paleta de destino. El controlador puede llamar al servicio XLATEOBJ_iXlate para realizar esta operación.

Opcionalmente, el controlador de dispositivo puede coincidir con los colores cuando la paleta de destino es la paleta de dispositivos predeterminada.

[in] prclTrg

Puntero a una estructura RECTL que define el área que se va a modificar. Esta estructura usa el sistema de coordenadas de la superficie de destino. Los bordes inferior y derecho de este rectángulo no forman parte de la transferencia de bloques de bits, lo que significa que el rectángulo es exclusivo de la parte inferior derecha.

Nunca se llama a DrvBitBlt con un rectángulo de destino vacío. Los dos puntos que definen el rectángulo siempre están bien ordenados. Sin embargo, en sistemas multimonitor, el rectángulo puede definir una región mayor que la superficie de destino. Los controladores deben intersecar este rectángulo con su superficie.

[in, optional] pptlSrc

Puntero a una estructura POINTL que define la esquina superior izquierda del rectángulo de origen, si existe un origen. Este parámetro se omite si no hay ningún origen.

[in, optional] pptlMask

Puntero a una estructura POINTL que define qué píxel de la máscara corresponde a la esquina superior izquierda del rectángulo de origen, si existe un origen. Este parámetro se omite si el parámetro stackMask es NULL.

[in, optional] pbo

Puntero a una estructura BRUSHOBJ que define el patrón para la transferencia de bloques de bits. El servicio de BRUSHOBJ_pvGetRbrush de GDI se puede usar para recuperar la realización del pincel del dispositivo. Este parámetro se omite si el parámetro rop4 no requiere un patrón.

[in, optional] pptlBrush

Puntero a una estructura POINTL que define el origen del pincel en la superficie de destino. El píxel superior izquierdo del pincel se alinea en este punto y el pincel se repite según sus dimensiones. Este parámetro se omite si el parámetro rop4 no requiere un patrón.

[in] rop4

Especifica una operación de trama que define cómo se combinan los píxeles de máscara, patrón, origen y destino para escribir en la superficie de destino.

Se trata de una operación ráster cuaternaria, que es una extensión de la operación ternaria Rop3. Un Rop4 tiene 16 bits relevantes, que son similares a los 8 bits que definen un Rop3. La manera más sencilla de implementar un Rop4 es considerar sus 2 bytes por separado: el byte bajo especifica un Rop3 que se debe calcular si la máscara es una y el byte alto especifica un Rop3 que se puede calcular y aplicar si la máscara es 0.

Valor devuelto

DrvBitBlt devuelve TRUE si la operación de transferencia de bloques de bits se realiza correctamente. De lo contrario, la función devuelve FALSE y se registra un código de error.

Comentarios

Si el controlador enlaza DrvBitBlt, GDI llamará a esta función cuando necesite realizar una operación BitBlt donde una de las superficies sea una superficie administrada por el dispositivo. Si el controlador implementa mapas de bits opacos administrados por dispositivos, debe enlazar DrvBitBlt; De lo contrario, enlazar DrvBitBlt es opcional. Si el controlador no puede controlar la llamada especificada, puede puntar la devolución de llamada al motor de DIB llamando a EngBitBlt.

Los servicios CLIPOBJXxx de GDI permiten reducir el recorte a una serie de rectángulos de recorte. Un vector de traducción ayuda en la traducción de índices de color para paletas.

Nota No desreferenciar punteros de parámetro a menos que el ROP indique que son necesarios. Por ejemplo, nunca desreferenciar innecesariamente pbo-->iSolidColor porque hacerlo para un ROP como BLACKNESS puede provocar una infracción de acceso. (Esta regla también se aplica a cualquier función que incluya un parámetro MIX).

Si el controlador recibe una llamada a esta función en la que el parámetro rop4 se establece en 0XCCAA, el controlador debe puntar la llamada a EngBitBlt, exponiendo las superficies del dispositivo según corresponda para la llamada.

Para obtener más información sobre las operaciones de trama, consulte la documentación de Microsoft Windows SDK.