CreateBitmap-Funktion (wingdi.h)

Artikel
08/27/2023

Die CreateBitmap-Funktion erstellt eine Bitmap mit der angegebenen Breite, Höhe und dem angegebenen Farbformat (Farbebenen und Bits pro Pixel).

Syntax

HBITMAP CreateBitmap(
  [in] int        nWidth,
  [in] int        nHeight,
  [in] UINT       nPlanes,
  [in] UINT       nBitCount,
  [in] const VOID *lpBits
);

Parameter

[in] nWidth

Die Bitmapbreite in Pixel.

[in] nHeight

Die Bitmaphöhe in Pixel.

[in] nPlanes

Die Anzahl der vom Gerät verwendeten Farbebenen.

[in] nBitCount

Die Anzahl der Bits, die zum Identifizieren der Farbe eines einzelnen Pixels erforderlich sind.

[in] lpBits

Ein Zeiger auf ein Array von Farbdaten, das zum Festlegen der Farben in einem Rechteck von Pixeln verwendet wird. Jede Scanzeile im Rechteck muss wortbündig ausgerichtet sein (Scanzeilen, die nicht wortbündig ausgerichtet sind, müssen mit Nullen aufgefüllt werden). Die erwartete Puffergröße cj kann mithilfe der Formel berechnet werden:

cj = (((nWidth * nPlanes * nBitCount + 15) >> 4) << 1) * nHeight;

Wenn dieser Parameter NULL ist, ist der Inhalt der neuen Bitmap undefiniert.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für eine Bitmap.

Wenn bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL.

Diese Funktion kann den folgenden Wert zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_BITMAP	Die berechnete Größe der Bitmap ist kleiner als 0 (null).

Hinweise

Die CreateBitmap-Funktion erstellt eine geräteabhängige Bitmap.

Nachdem eine Bitmap erstellt wurde, kann sie in einem Gerätekontext ausgewählt werden, indem sie die SelectObject-Funktion aufruft . Die Bitmap kann jedoch nur in einem Gerätekontext ausgewählt werden, wenn die Bitmap und der DC das gleiche Format haben.

Die CreateBitmap-Funktion kann zum Erstellen von Farbbitbitbits verwendet werden. Aus Leistungsgründen sollten Anwendungen jedoch CreateBitmap verwenden, um monochrome Bitmaps und CreateCompatibleBitmap zum Erstellen von Farbbitbitbits zu erstellen. Wenn eine von CreateBitmap zurückgegebene Farbbit in einem Gerätekontext ausgewählt wird, überprüft das System, ob die Bitmap dem Format des ausgewählten Gerätekontexts entspricht. Da CreateCompatibleBitmap einen Gerätekontext verwendet, wird eine Bitmap zurückgegeben, die das gleiche Format wie der angegebene Gerätekontext aufweist. Daher sind nachfolgende Aufrufe von SelectObject mit einer Farbbit von CreateCompatibleBitmap schneller als mit einer farblichen Bitmap, die von CreateBitmap zurückgegeben wird.

Wenn die Bitmap monochrom ist, stellen Nullen die Vordergrundfarbe und eins die Hintergrundfarbe für den Kontext des Zielgeräts dar.

Wenn eine Anwendung den nWidth - oder nHeight-Parameter auf 0 (null) festlegt, gibt CreateBitmap das Handle auf eine 1 x 1 pixelige, monochrome Bitmap zurück.

Wenn Sie die Bitmap nicht mehr benötigen, rufen Sie die DeleteObject-Funktion auf, um sie zu löschen.

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