Función SetDIBitsToDevice (wingdi.h)

Artículo
03/04/2024

La función SetDIBitsToDevice establece los píxeles del rectángulo especificado en el dispositivo asociado al contexto del dispositivo de destino mediante datos de color de una imagen DIB, JPEG o PNG.

Sintaxis

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Parámetros

[in] hdc

Identificador del contexto del dispositivo.

[in] xDest

Coordenada x, en unidades lógicas, de la esquina superior izquierda del rectángulo de destino.

[in] yDest

Coordenada y, en unidades lógicas, de la esquina superior izquierda del rectángulo de destino.

[in] w

Ancho, en unidades lógicas, de la imagen.

[in] h

Alto, en unidades lógicas, de la imagen.

[in] xSrc

Coordenada x, en unidades lógicas, de la esquina inferior izquierda de la imagen.

[in] ySrc

Coordenada y, en unidades lógicas, de la esquina inferior izquierda de la imagen.

[in] StartScan

Línea de examen inicial de la imagen.

[in] cLines

Número de líneas de examen dib contenidas en la matriz a la que apunta el parámetro lpvBits .

[in] lpvBits

Puntero a los datos de color almacenados como una matriz de bytes. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[in] lpbmi

Puntero a una estructura BITMAPINFO que contiene información sobre la DIB.

[in] ColorUse

Indica si el miembro rgbColors de la estructura BITMAPINFO contiene valores o índices de color rojo, verde, azul (RGB) explícitos en una paleta. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

El parámetro fuColorUse debe ser uno de los valores siguientes.

Valor	Significado
DIB_PAL_COLORS	La tabla de colores consta de una matriz de índices de 16 bits en la paleta lógica seleccionada actualmente.
DIB_RGB_COLORS	La tabla de colores contiene valores RGB literales.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es el número de líneas de examen establecidas.

Si se establecen líneas de examen cero (como cuando dwHeight es 0) o se produce un error en la función, la función devuelve cero.

Si el controlador no puede admitir la imagen de archivo JPEG o PNG que se pasa a SetDIBitsToDevice, se producirá un error en la función y se devolverá GDI_ERROR. Si se produce un error, la aplicación debe revertirse a su propia compatibilidad con JPEG o PNG para descomprimir la imagen en un mapa de bits y, a continuación, pasar el mapa de bits a SetDIBitsToDevice.

Comentarios

La velocidad óptima del dibujo del mapa de bits se obtiene cuando los bits de mapa de bits se indexa en la paleta del sistema.

Las aplicaciones pueden recuperar los colores e índices de la paleta del sistema mediante una llamada a la función GetSystemPaletteEntries . Una vez recuperados los colores e índices, la aplicación puede crear la DIB. Para obtener más información sobre la paleta del sistema, vea Colores.

Las líneas de examen deben alinearse en un DWORD excepto en los mapas de bits comprimidos por RLE.

El origen de una DIB de abajo arriba es la esquina inferior izquierda del mapa de bits; el origen de una DIB de arriba abajo es la esquina superior izquierda.

Para reducir la cantidad de memoria necesaria para establecer bits de una DIB grande en una superficie de dispositivo, una aplicación puede agrupar la salida llamando repetidamente a SetDIBitsToDevice, colocando una parte diferente del mapa de bits en la matriz lpvBits cada vez. Los valores de los parámetros uStartScan y cScanLines identifican la parte del mapa de bits contenido en la matriz lpvBits .

La función SetDIBitsToDevice devuelve un error si lo llama un proceso que se ejecuta en segundo plano mientras una sesión ms-DOS de pantalla completa se ejecuta en primer plano.

Si el miembro biCompression de BITMAPINFOHEADER es BI_JPEG o BI_PNG, lpvBits apunta a un búfer que contiene una imagen JPEG o PNG. El miembro biSizeImage de especifica el tamaño del búfer. El parámetro fuColorUse debe establecerse en DIB_RGB_COLORS.
Para garantizar la puesta en cola de metarchivo adecuada durante la impresión, las aplicaciones deben llamar al escape CHECKJPEGFORMAT o CHECKPNGFORMAT para comprobar que la impresora reconoce la imagen JPEG o PNG, respectivamente, antes de llamar a SetDIBitsToDevice.

ICM: La administración de colores se realiza si se ha habilitado la administración de colores con una llamada a SetICMMode con el parámetro iEnableICM establecido en ICM_ON. Si el mapa de bits especificado por lpbmi tiene un BITMAPV4HEADER que especifica los miembros gamma y endpoints, o un BITMAPV5HEADER que especifica los miembros gamma y endpoints o los miembros profileData y profileSize, la llamada trata los píxeles del mapa de bits como se expresa en el espacio de colores descrito por esos miembros, en lugar de en el espacio de color de origen del contexto del dispositivo.

Ejemplos

Para obtener un ejemplo, consulte Probar una impresora para compatibilidad con JPEG o PNG.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wingdi.h (incluye Windows.h)
Library	Gdi32.lib
Archivo DLL	Gdi32.dll