Função GetDIBits (wingdi.h)
A função GetDIBits recupera os bits do bitmap compatível especificado e os copia em um buffer como um DIB usando o formato especificado.
Sintaxe
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
Um identificador para o contexto do dispositivo.
[in] hbm
Um identificador para o bitmap. Deve ser um DDB (bitmap) compatível.
[in] start
A primeira linha de verificação a ser recuperada.
[in] cLines
O número de linhas de verificação a serem recuperadas.
[out] lpvBits
Um ponteiro para um buffer para receber os dados de bitmap. Se esse parâmetro for NULL, a função passará as dimensões e o formato do bitmap para a estrutura BITMAPINFO apontada pelo parâmetro lpbmi .
[in, out] lpbmi
Um ponteiro para uma estrutura BITMAPINFO que especifica o formato desejado para os dados DIB.
[in] usage
O formato do membro bmiColors da estrutura BITMAPINFO . Deve ser um dos valores a seguir.
Valor retornado
Se o parâmetro lpvBits não for NULL e a função for bem-sucedida, o valor retornado será o número de linhas de verificação copiadas do bitmap.
Se o parâmetro lpvBits for NULL e GetDIBits preencher com êxito a estrutura BITMAPINFO , o valor retornado não será zero.
Se a função falhar, o valor retornado será zero.
Essa função pode retornar o valor a seguir.
| Código de retorno | Descrição |
|---|---|
|
Um ou mais dos parâmetros de entrada são inválidos. |
Comentários
Se o formato solicitado para o DIB corresponder ao formato interno, os valores RGB para o bitmap serão copiados. Se o formato solicitado não corresponder ao formato interno, uma tabela de cores será sintetizada. A tabela a seguir descreve a tabela de cores sintetizada para cada formato.
| Valor | Significado |
|---|---|
| 1_BPP | A tabela de cores consiste em uma entrada preta e branca. |
| 4_BPP | A tabela de cores consiste em uma combinação de cores idênticas à paleta de VGA padrão. |
| 8_BPP | A tabela de cores consiste em uma combinação geral de 256 cores definidas pela GDI. (Incluídas nessas 256 cores estão as 20 cores encontradas na paleta lógica padrão.) |
| 24_BPP | Nenhuma tabela de cores é retornada. |
Se o parâmetro lpvBits for um ponteiro válido, os seis primeiros membros da estrutura BITMAPINFOHEADER deverão ser inicializados para especificar o tamanho e o formato do DIB. As linhas de verificação devem ser alinhadas em um DWORD , exceto para bitmaps compactados RLE.
Um DIB de baixo para cima é especificado definindo a altura como um número positivo, enquanto um DIB de cima para baixo é especificado definindo a altura como um número negativo. A tabela de cores bitmap será acrescentada à estrutura BITMAPINFO .
Se lpvBits for NULL, GetDIBits examinará o primeiro membro da primeira estrutura apontada por lpbi. Esse membro deve especificar o tamanho, em bytes, de uma estrutura BITMAPCOREHEADER ou BITMAPINFOHEADER . A função usa o tamanho especificado para determinar como os membros restantes devem ser inicializados.
Se lpvBits for NULL e o membro de contagem de bits de BITMAPINFO for inicializado como zero, GetDIBits preencherá uma estrutura BITMAPINFOHEADER ou BITMAPCOREHEADER sem a tabela de cores. Essa técnica pode ser usada para consultar atributos de bitmap.
O bitmap identificado pelo parâmetro hbmp não deve ser selecionado em um contexto de dispositivo quando o aplicativo chama essa função.
A origem de um DIB de baixo para cima é o canto inferior esquerdo do bitmap; a origem de um DIB de cima para baixo é o canto superior esquerdo.
Exemplos
Para obter um exemplo, consulte Capturando uma imagem.
Requisitos
| Cliente mínimo com suporte | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | wingdi.h (inclua Windows.h) |
| Biblioteca | Gdi32.lib |
| DLL | Gdi32.dll |