Funzione GetDIBits (wingdi.h)

Articolo
08/27/2023

La funzione GetDIBits recupera i bit della bitmap compatibile specificata e li copia in un buffer come DIB usando il formato specificato.

Sintassi

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

Parametri

[in] hdc

Handle per il contesto del dispositivo.

[in] hbm

Handle per la bitmap. Deve trattarsi di una bitmap compatibile (DDB).

[in] start

Prima riga di analisi da recuperare.

[in] cLines

Numero di righe di analisi da recuperare.

[out] lpvBits

Puntatore a un buffer per ricevere i dati bitmap. Se questo parametro è NULL, la funzione passa le dimensioni e il formato della bitmap alla struttura BITMAPINFO a cui punta il parametro lpbmi .

[in, out] lpbmi

Puntatore a una struttura BITMAPINFO che specifica il formato desiderato per i dati DIB.

[in] usage

Formato del membro bmiColors della struttura BITMAPINFO . Deve essere uno dei valori seguenti.

Valore	Significato
DIB_PAL_COLORS	La tabella dei colori deve essere costituita da una matrice di indici a 16 bit nella tavolozza logica corrente.
DIB_RGB_COLORS	La tabella dei colori deve essere costituita da valori letterali rosso, verde, blu (RGB).

Valore restituito

Se il parametro lpvBits è diverso da NULL e la funzione ha esito positivo, il valore restituito corrisponde al numero di righe di analisi copiate dalla bitmap.

Se il parametro lpvBits è NULL e GetDIBits riempie correttamente la struttura BITMAPINFO , il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero.

Questa funzione può restituire il valore seguente.

Codice restituito	Descrizione
ERROR_INVALID_PARAMETER	Uno o più parametri di input non sono validi.

Commenti

Se il formato richiesto per DIB corrisponde al formato interno, i valori RGB per la bitmap vengono copiati. Se il formato richiesto non corrisponde al formato interno, viene sintetizzata una tabella dei colori. Nella tabella seguente viene descritta la tabella dei colori sintetizzata per ogni formato.

Valore	Significato
1_BPP	La tabella dei colori è costituita da una voce nera e una voce bianca.
4_BPP	La tabella dei colori è costituita da una combinazione di colori identici alla tavolozza VGA standard.
8_BPP	La tabella dei colori è costituita da una combinazione generale di 256 colori definiti da GDI. (Inclusi in questi 256 colori sono i 20 colori disponibili nella tavolozza logica predefinita).
24_BPP	Non viene restituita alcuna tabella dei colori.

Se il parametro lpvBits è un puntatore valido, i primi sei membri della struttura BITMAPINFOHEADER devono essere inizializzati per specificare le dimensioni e il formato del DIB. Le linee di analisi devono essere allineate su un DWORD ad eccezione delle bitmap compresse RLE.

Un DIB inferiore viene specificato impostando l'altezza su un numero positivo, mentre viene specificato un DIB dall'alto verso il basso impostando l'altezza su un numero negativo. La tabella dei colori bitmap verrà aggiunta alla struttura BITMAPINFO .

Se lpvBits è NULL, GetDIBits esamina il primo membro della prima struttura a cui punta lpbi. Questo membro deve specificare le dimensioni, in byte, di una struttura BITMAPCOREHEADER o BITMAPINFOHEADER . La funzione usa le dimensioni specificate per determinare la modalità di inizializzazione dei membri rimanenti.

Se lpvBits è NULL e il membro del numero di bit di BITMAPINFO viene inizializzato su zero, GetDIBits compila una struttura BITMAPINFOHEADER o BITMAPCOREHEADER senza la tabella dei colori. Questa tecnica può essere usata per eseguire query sugli attributi bitmap.

La bitmap identificata dal parametro hbmp non deve essere selezionata in un contesto di dispositivo quando l'applicazione chiama questa funzione.

L'origine di un DIB inferiore verso l'alto è l'angolo inferiore sinistro della bitmap; l'origine di un DIB dall'alto verso il basso è l'angolo superiore sinistro.

Esempio

Per un esempio, vedere Acquisizione di un'immagine.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	wingdi.h (include Windows.h)
Libreria	Gdi32.lib
DLL	Gdi32.dll