GetDIBits-Funktion (wingdi.h)

Artikel
08/27/2023

Die GetDIBits-Funktion ruft die Bits der angegebenen kompatiblen Bitmap ab und kopiert sie unter Verwendung des angegebenen Formats als DIB in einen Puffer.

Syntax

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

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] hbm

Ein Handle für die Bitmap. Hierbei muss es sich um eine kompatible Bitmap (DDB) handeln.

[in] start

Die erste abzurufende Scanzeile.

[in] cLines

Die Anzahl der abzurufenden Scanzeilen.

[out] lpvBits

Ein Zeiger auf einen Puffer zum Empfangen der Bitmapdaten. Wenn dieser Parameter NULL ist, übergibt die Funktion die Abmessungen und das Format der Bitmap an die BITMAPINFO-Struktur , auf die der lpbmi-Parameter verweist.

[in, out] lpbmi

Ein Zeiger auf eine BITMAPINFO-Struktur , die das gewünschte Format für die DIB-Daten angibt.

[in] usage

Das Format des bmiColors-Elements der BITMAPINFO-Struktur . Er muss einen der folgenden Werte aufweisen.

Wert	Bedeutung
DIB_PAL_COLORS	Die Farbtabelle sollte aus einem Array von 16-Bit-Indizes in der aktuellen logischen Palette bestehen.
DIB_RGB_COLORS	Die Farbtabelle sollte aus Literalwerten rot, grün, blau (RGB) bestehen.

Rückgabewert

Wenn der lpvBits-Parameter nicht NULL ist und die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der Scanzeilen, die aus der Bitmap kopiert wurden.

Wenn der lpvBits-ParameterNULL ist und GetDIBits die BITMAPINFO-Struktur erfolgreich ausfüllt, ist der Rückgabewert ungleich null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null.

Diese Funktion kann den folgenden Wert zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Mindestens einer der Eingabeparameter ist ungültig.

Hinweise

Wenn das angeforderte Format für das DIB mit dem internen Format übereinstimmt, werden die RGB-Werte für die Bitmap kopiert. Wenn das angeforderte Format nicht mit dem internen Format übereinstimmt, wird eine Farbtabelle synthetisiert. In der folgenden Tabelle wird die Farbtabelle beschrieben, die für jedes Format synthetisiert wird.

Wert	Bedeutung
1_BPP	Die Farbtabelle besteht aus einem schwarzen und einem weißen Eintrag.
4_BPP	Die Farbtabelle besteht aus einer Farbmischung, die mit der Standard-VGA-Palette identisch ist.
8_BPP	Die Farbtabelle besteht aus einer allgemeinen Mischung aus 256 Farben, die von GDI definiert werden. (In diesen 256 Farben sind die 20 Farben enthalten, die in der logischen Standardpalette enthalten sind.)
24_BPP	Es wird keine Farbtabelle zurückgegeben.

Wenn der lpvBits-Parameter ein gültiger Zeiger ist, müssen die ersten sechs Member der BITMAPINFOHEADER-Struktur initialisiert werden, um die Größe und das Format des DIB anzugeben. Die Scanzeilen müssen mit Ausnahme von RLE-komprimierten Bitmaps auf einem DWORD ausgerichtet werden.

Ein DIB von unten nach oben wird angegeben, indem die Höhe auf eine positive Zahl festgelegt wird, während ein DIB von oben nach unten angegeben wird, indem die Höhe auf eine negative Zahl festgelegt wird. Die Bitmapfarbtabelle wird an die BITMAPINFO-Struktur angefügt.

Wenn lpvBitsNULL ist, untersucht GetDIBits den ersten Member der ersten Struktur, auf die lpbi verweist. Dieser Member muss die Größe einer BITMAPCOREHEADER - oder BITMAPINFOHEADER-Struktur in Bytes angeben. Die Funktion verwendet die angegebene Größe, um zu bestimmen, wie die verbleibenden Member initialisiert werden sollen.

Wenn lpvBitsNULL ist und der Bitanzahlmember von BITMAPINFO auf null initialisiert wird, füllt GetDIBits eine BITMAPINFOHEADER-Struktur oder BITMAPCOREHEADER ohne die Farbtabelle aus. Diese Technik kann verwendet werden, um Bitmapattribute abzufragen.

Die durch den hbmp-Parameter identifizierte Bitmap darf nicht in einem Gerätekontext ausgewählt werden, wenn die Anwendung diese Funktion aufruft.

Der Ursprung für einen DIB von unten nach oben ist die untere linke Ecke der Bitmap. Der Ursprung für einen DIB von oben nach unten ist die obere linke Ecke.

Beispiele

Ein Beispiel finden Sie unter Erfassen eines Bilds.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wingdi.h (windows.h einschließen)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll