GetDIBits

La función GetDIBits recupera los bits de un mapa de bits especificado y los copia en un buffer usando el formato especificado.

Sintaxis

int GetDIBits(
    HDC hdc,           // manipulador de contexto de dispositivo
    HBITMAP hbmp,      // manipulador de mapa de bits
    UINT uStartScan,   // primera línea a colocar en el mapa de bits de destino
    UINT cScanLines,   // número de líneas a copias
    LPVOID lpvBits,    // dirección del array de bits del mapa de bits
    LPBITMAPINFO lpbi, // dirección de estructura con datos del mapa de bits
    UINT uUsage        // RGB o índices de paleta
   );

Parámetros

hdc: identifica el contexto de dispositivo.

hbmp: identifica el mapa de bits.

uStartScan: especifica la primera línea a recuperar.

cScanLines: especifica el número de líneas a recuperar.

lpvBits: apunta a un buffer para recibir los datos del mapa de bits. Si este parámetro es NULL, la función pasa las dimensiones y formato del mapa de bits a la estructura BITMAPINFO apuntada por el parámetro lpbi.

lpbi: apunta a una estructura BITMAPINFO que especifica el formato deseado para los datos del mapa de bits independiente del dispositivo (DIB).

uUsage: especifica el formato del miembro bmiColors de la estructura BITMAPINFO. Debe ser uno de los siguientes valores:

Valor de retorno

Si el parámetro lpvBits no es NULL y la función tiene éxito, el valor de retorno es el número de líneas copiadas desde el mapa de bits.

Windows 95: si el parámetro lpvBits es NULL y GetDIBits completa adecuadamente la estructura BITMAPINFO, el valor de retorno es el número total de líneas en el mapa de bits.

Windows NT: si el parámetro lpvBits es NULL y GetDIBits completa adecuadamente la estructura BITMAPINFO, el valor de retorno es distinto de cero.

Si la función falla, el valor de retorno es cero.

Observaciones

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

Si el parámetro lpvBits es un puntero válido, los primeros seis miembros de la estructura BITMAPINFOHEADER deben ser inicializados para especificar el tamaño y formato del DIB. Nótese que un DIB de abajo-arriba se especifica mediante un valor de altura positivo, mientras que uno de arriba-abajo se especifica mediante un valor de altura negativo. La tabla de colores de mapa de bits puede ser añadida a la estructura BITMAPINFO.

Si lpvBits es NULL, GetDIBits examina el primer miembro de la primera estructura apuntada por lpbi. Este miembro debe especifica el tamaño, en bytes, de una estructura BITMAPCOREHEADER o de una estructura BITMAPINFOHEADER. La función usa el tamaño especificado para determinar como se deben inicializar el resto de los miembros.

Si lpvBits es NULL y el miembro de cuenta de bits de BITMAPINFO se inicializa a cero, GetDIBits rellena la estructura BITMAPINFOHEADER o BITMAPCOREHEADER sin la tabla de colores. Esta técnica puede usarse para consultar los atributos de un mapa de bits.

El mapa de bits identificado por el parámetro hbmp no debe estar seleccionado dentro de un contexto de dispositivo cuando la aplicación llame a esta función.

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