CreateDIBSection-Funktion (wingdi.h)

Artikel
03/09/2024

Die CreateDIBSection-Funktion erstellt eine DIB, in die Anwendungen direkt schreiben können. Die Funktion gibt Ihnen einen Zeiger auf die Position der Bitwerte der Bitmap. Sie können ein Handle für ein Dateizuordnungsobjekt bereitstellen, das die Funktion zum Erstellen der Bitmap verwendet, oder Sie können das System den Speicher für die Bitmap zuordnen lassen.

Syntax

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

Parameter

[in] hdc

Ein Handle für einen Gerätekontext. Wenn der Wert von iUsage DIB_PAL_COLORS ist, verwendet die Funktion die logische Palette dieses Gerätekontexts, um die DIB-Farben zu initialisieren.

[in] pbmi

Ein Zeiger auf eine BITMAPINFO-Struktur , die verschiedene Attribute des DIB angibt, einschließlich der Bitmapdimensionen und -farben.

[in] usage

Der Typ der Daten, die im bmiColors-Arraymember der BITMAPINFO-Struktur enthalten sind, auf die pbmi verweist (entweder logische Palettenindizes oder literale RGB-Werte). Die folgenden Werte werden definiert.

Wert	Bedeutung
DIB_PAL_COLORS	Der bmiColors-Member ist ein Array von 16-Bit-Indizes in der logischen Palette des von hdc angegebenen Gerätekontexts.
DIB_RGB_COLORS	Die BITMAPINFO-Struktur enthält ein Array von RGB-Literalwerten.

[out] ppvBits

Ein Zeiger auf eine Variable, die einen Zeiger auf die Position der DIB-Bitwerte empfängt.

[in] hSection

Ein Handle zu einem Dateizuordnungsobjekt, das die Funktion zum Erstellen des DIB verwendet. Dieser Parameter kann NULL sein.

Wenn hSection nicht NULL ist, muss es sich um ein Handle für ein Dateizuordnungsobjekt handeln, das durch Aufrufen der CreateFileMapping-Funktion mit dem flag PAGE_READWRITE oder PAGE_WRITECOPY erstellt wird. Schreibgeschützte DIB-Abschnitte werden nicht unterstützt. Mit anderen Mitteln erstellte Handles führen dazu, dass CreateDIBSection fehlschlägt.

Wenn hSection nicht NULL ist, sucht die CreateDIBSection-Funktion die Bitwerte der Bitmap im Offset dwOffset im Dateizuordnungsobjekt, auf das von hSection verwiesen wird. Eine Anwendung kann später das hSection-Handle abrufen, indem sie die GetObject-Funktion mit der von CreateDIBSection zurückgegebenen HBITMAP aufruft.

Wenn hSectionNULL ist, ordnet das System arbeitsspeicher für die DIB zu. In diesem Fall ignoriert die CreateDIBSection-Funktion den dwOffset-Parameter . Eine Anwendung kann später kein Handle für diesen Arbeitsspeicher abrufen. Der dshSection-Member der DIBSECTION-Struktur , die durch Aufrufen der GetObject-Funktion ausgefüllt wird, ist NULL.

[in] offset

Der Offset vom Anfang des Dateizuordnungsobjekts, auf das von hSection verwiesen wird, wobei der Speicher für die Bitwerte der Bitmap beginnen soll. Dieser Wert wird ignoriert, wenn hSectionNULL ist. Die Bitwerte der Bitmap werden an Doppelwortgrenzen ausgerichtet, sodass dwOffset ein Vielfaches der Größe eines DWORD sein muss.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für den neu erstellten DIB, und *ppvBits zeigt auf die Bitwerte der Bitmap.

Wenn die Funktion fehlschlägt, ist der Rückgabewert NULL, und *ppvBits ist NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

GetLastError kann den folgenden Wert zurückgeben:

Fehlercode	BESCHREIBUNG
ERROR_INVALID_PARAMETER	Mindestens einer der Eingabeparameter ist ungültig.

Hinweise

Wenn hSectionNULL ist, weist das System wie oben erwähnt Arbeitsspeicher für die DIB zu. Das System schließt das Handle mit diesem Speicher, wenn Sie später die DIB löschen, indem Sie die DeleteObject-Funktion aufrufen. Wenn hSection nicht NULL ist, müssen Sie das hSection-Speicherhandle selbst schließen, nachdem Sie DeleteObject aufgerufen haben, um die Bitmap zu löschen.

Sie können keinen DIB-Abschnitt aus einer Anwendung in eine andere Anwendung einfügen.

CreateDIBSection verwendet nicht die BITMAPINFOHEADER-ParameterbiXPelsPerMeter oder biYPelsPerMeter und stellt keine Auflösungsinformationen in der BITMAPINFO-Struktur bereit.

Sie müssen sicherstellen, dass das GDI-Subsystem jede Zeichnung für eine von CreateDIBSection erstellte Bitmap abgeschlossen hat, bevor Sie selbst auf die Bitmap zeichnen. Der Zugriff auf die Bitmap muss synchronisiert werden. Rufen Sie hierzu die GdiFlush-Funktion auf. Dies gilt für jede Verwendung des Zeigers auf die Bitwerte der Bitmap, einschließlich der Übergabe des Zeigers in Aufrufen von Funktionen wie SetDIBits.

ICM: Es wird keine Farbverwaltung durchgeführt.

Anforderungen

Anforderung	Wert
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