Función GetDIBits (wingdi.h)

Artículo
08/27/2023

La función GetDIBits recupera los bits del mapa de bits compatible especificado y los copia en un búfer como DIB con el formato especificado.

Sintaxis

int GetDIBits(
  [in]      HDC          hdc,
  [in]      HBITMAP      hbm,
  [in]      UINT         start,
  [in]      UINT         cLines,
  [out]     LPVOID       lpvBits,
  [in, out] LPBITMAPINFO lpbmi,
  [in]      UINT         usage
);

Parámetros

[in] hdc

Identificador del contexto del dispositivo.

[in] hbm

Identificador del mapa de bits. Debe ser un mapa de bits compatible (DDB).

[in] start

Primera línea de examen que se va a recuperar.

[in] cLines

Número de líneas de examen que se van a recuperar.

[out] lpvBits

Puntero a un búfer para recibir los datos del mapa de bits. Si este parámetro es NULL, la función pasa las dimensiones y el formato del mapa de bits a la estructura BITMAPINFO a la que apunta el parámetro lpbmi .

[in, out] lpbmi

Puntero a una estructura BITMAPINFO que especifica el formato deseado para los datos DIB.

[in] usage

Formato del miembro imcColors de la estructura BITMAPINFO . Debe tener uno de los siguientes valores.

Value	Significado
DIB_PAL_COLORS	La tabla de colores debe constar de una matriz de índices de 16 bits en la paleta lógica actual.
DIB_RGB_COLORS	La tabla de colores debe constar de valores literales de color rojo, verde, azul (RGB).

Valor devuelto

Si el parámetro lpvBits no es NULL y la función se ejecuta correctamente, el valor devuelto es el número de líneas de examen copiadas del mapa de bits.

Si el parámetro lpvBits es NULL y GetDIBits rellena correctamente la estructura BITMAPINFO , el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero.

Esta función puede devolver el valor siguiente.

Código devuelto	Descripción
ERROR_INVALID_PARAMETER	Uno o varios de los parámetros de entrada no son válidos.

Comentarios

Si el formato solicitado para la DIB coincide con su formato interno, se copian los valores RGB del mapa de bits. Si el formato solicitado no coincide con el formato interno, se sintetiza una tabla de colores. En la tabla siguiente se describe la tabla de colores sintetizada para cada formato.

Value	Significado
1_BPP	La tabla de colores consta de una entrada negra y blanca.
4_BPP	La tabla de colores consta de una combinación de colores idénticos a la paleta VGA estándar.
8_BPP	La tabla de colores consta de una combinación general de 256 colores definidos por GDI. (Incluidos en estos 256 colores son los 20 colores que se encuentran en la paleta lógica predeterminada).
24_BPP	No se devuelve ninguna tabla de colores.

Si el parámetro lpvBits es un puntero válido, se deben inicializar los seis primeros miembros de la estructura BITMAPINFOHEADER para especificar el tamaño y el formato de la DIB. Las líneas de examen deben alinearse en un DWORD , excepto en los mapas de bits comprimidos de RLE.

Se especifica una DIB de abajo arriba estableciendo el alto en un número positivo, mientras que una DIB de arriba abajo se especifica estableciendo el alto en un número negativo. La tabla de colores del mapa de bits se anexará a la estructura BITMAPINFO .

Si lpvBits es NULL, GetDIBits examina el primer miembro de la primera estructura a la que apunta lpbi. Este miembro debe especificar el tamaño, en bytes, de una estructura BITMAPCOREHEADER o BITMAPINFOHEADER . La función usa el tamaño especificado para determinar cómo se deben inicializar los miembros restantes.

Si lpvBits es NULL y el miembro de recuento de bits de BITMAPINFO se inicializa en cero, GetDIBits rellena una estructura BITMAPINFOHEADER o BITMAPCOREHEADER sin la tabla de colores. Esta técnica se puede usar para consultar atributos de mapa de bits.

El mapa de bits identificado por el parámetro hbmp no debe seleccionarse en un contexto de dispositivo cuando la aplicación llama a esta función.

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.

Ejemplos

Para obtener un ejemplo, vea Capturar una imagen.

Requisitos


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