Función DrvStretchBlt (winddi.h)

Artículo
08/27/2023

La función DrvStretchBlt proporciona funcionalidades de transferencia de bloques de bits extendidas entre cualquier combinación de superficies administradas por el dispositivo y administradas por GDI.

Sintaxis

BOOL DrvStretchBlt(
  [in, out]      SURFOBJ         *psoDest,
  [in, out]      SURFOBJ         *psoSrc,
  [in, optional] SURFOBJ         *psoMask,
  [in]           CLIPOBJ         *pco,
  [in, optional] XLATEOBJ        *pxlo,
  [in, optional] COLORADJUSTMENT *pca,
  [in]           POINTL          *pptlHTOrg,
  [in]           RECTL           *prclDest,
  [in]           RECTL           *prclSrc,
  [in, optional] POINTL          *pptlMask,
  [in]           ULONG           iMode
);

Parámetros

[in, out] psoDest

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

[in, out] psoSrc

Puntero a la estructura SURFOBJ que define el origen de la operación de transferencia de bloques de bits.

[in, optional] psoMask

Puntero opcional a una estructura SURFOBJ que define una superficie que proporciona una máscara para el origen. La máscara se define mediante un mapa lógico, que es un mapa de bits con 1 bit por píxel.

La máscara limita el área del origen que se copia. Si se especifica este parámetro, tiene un rop4 implícito de 0xCCAA, lo que significa que el origen debe copiarse dondequiera que la máscara sea una, pero el destino debe dejarse solo donde la máscara sea cero.

Cuando este parámetro es NULL, hay un rop4 implícito de 0xCCCC, lo que significa que el origen debe copiarse en todas partes en el rectángulo de origen.

La máscara siempre será lo suficientemente grande como para contener el origen pertinente; El mosaico no es necesario.

[in] pco

Puntero a una estructura CLIPOBJ que limita el área que se va a modificar en el destino. Los servicios GDI se proporcionan para enumerar la región del clip como un conjunto de rectángulos.

Siempre que sea posible, GDI simplifica el recorte implicado. Sin embargo, a diferencia de DrvBitBlt, se puede llamar a DrvStretchBlt con un único rectángulo de recorte. Esto evita errores de redondeo en el recorte de la salida.

[in, optional] pxlo

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

La estructura XLATEOBJ también se puede consultar para buscar el color RGB de cualquier índice de origen. Una transferencia de bloques de bits de alta calidad deberá interpolar colores en algunos casos.

[in, optional] pca

Puntero a una estructura COLORADJUSTMENT que define los valores de ajuste de color que se aplicarán al mapa de bits de origen antes de estirar los bits. (Consulte la documentación de Microsoft Windows SDK).

[in] pptlHTOrg

Puntero a una estructura POINTL que especifica el origen del pincel de media tono. Los controladores de dispositivo que usan pinceles de medio tono deben alinear el píxel superior izquierdo del patrón del pincel con este punto en la superficie del dispositivo.

[in] prclDest

Puntero a una estructura RECTL que define el área que se va a modificar en el sistema de coordenadas de la superficie de destino. Este rectángulo se define mediante dos puntos que no están necesariamente bien ordenados, lo que significa que las coordenadas del segundo punto no son necesariamente mayores que las del primer punto. El rectángulo que describen no incluye los bordes inferior y derecho. Nunca se llama a esta función con un rectángulo de destino vacío.

DrvStretchBlt debe intercambiar los dos valores x o los dos valores y cuando el rectángulo de destino no está bien ordenado.

[in] prclSrc

Puntero a una estructura RECTL que define el área que se copiará en el sistema de coordenadas de la superficie de origen. El rectángulo se define mediante dos puntos y se asignará al rectángulo definido por prclDest. Los puntos del rectángulo de origen están bien ordenados. Esta función nunca recibe un rectángulo de origen vacío.

La asignación se define mediante prclSrc y prclDest. Los puntos especificados en prclDest y prclSrc se encuentran en coordenadas enteras, que corresponden a los centros de píxeles. Un rectángulo definido por dos puntos de este tipo se considera un rectángulo geométrico con dos vértices cuyas coordenadas son los puntos dados, pero con 0,5 restado de cada coordenada. (Las estructuras POINTL deben considerarse una notación abreviada para especificar estos vértices de coordenada fraccionaria).

Los bordes de cualquier rectángulo nunca intersecan un píxel, pero van alrededor de un conjunto de píxeles. Los píxeles dentro del rectángulo son los esperados para un rectángulo "exclusivo inferior derecho". DrvStretchBlt asignará el rectángulo de origen geométrico exactamente al rectángulo de destino geométrico.

[in, optional] pptlMask

Puntero a una estructura POINTL que especifica qué píxel de la máscara especificada corresponde al píxel superior izquierdo del rectángulo de origen. Omita este parámetro si no se especifica ninguna máscara.

[in] iMode

Especifica cómo se combinan los píxeles de origen para obtener píxeles de salida. El modo HALFTONE es más lento que los demás modos, pero genera imágenes de mayor calidad.

Valor	Significado
BLACKONWHITE	En una transferencia de bloques de bits de reducción, los píxeles deben combinarse con una operación BOOLEAN AND. En una transferencia de bloques de bits de extensión, se deben replicar píxeles.
COLORONCOLOR	En una transferencia de bloque de bits de reducción, se deben omitir suficientes píxeles para que no sea necesario combinar píxeles. En una transferencia de bloques de bits de extensión, se deben replicar píxeles.
SEMITONOS	El controlador puede usar grupos de píxeles en la superficie de salida para aproximar mejor el nivel de color o gris de la entrada.
WHITEONBLACK	En una transferencia de bloques de bits de reducción, los píxeles deben combinarse con una operación OR booleana. En una transferencia de bloques de bits de extensión, se deben replicar píxeles.

Valor devuelto

El valor devuelto es TRUE si la función es correcta. De lo contrario, es FALSE y se registra un código de error.

Comentarios

DrvStretchBlt permite que el controlador del dispositivo escriba en mapas de bits GDI, especialmente cuando el controlador puede realizar el halftoning. Esta función permite aplicar el mismo algoritmo de halftoning a mapas de bits GDI y superficies de dispositivo.

Esta función se puede proporcionar para controlar solo ciertas formas de extensión, como el número entero múltiplo. Si el controlador ha conectado la llamada y se le pide que realice una operación que no admita, el controlador debe reenviar los datos a EngStretchBlt para que GDI lo controle.

Si el controlador quiere que GDI controle el halftoning y quiere asegurar el valor iMode adecuado, el controlador puede enlazar DrvStretchBlt, establecer iMode en HALFTONE y volver a llamar a GDI con EngStretchBlt con el valor de iMode establecido.

DrvStretchBlt es opcional para los controladores de pantalla.