SetDIBitsToDevice-Funktion (wingdi.h)

Artikel
03/08/2023

Die SetDIBitsToDevice-Funktion legt die Pixel im angegebenen Rechteck auf dem Gerät, das dem Zielgerätekontext zugeordnet ist, mithilfe von Farbdaten aus einem DIB-, JPEG- oder PNG-Bild fest.

Syntax

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

Parameter

[in] hdc

Ein Handle für den Gerätekontext.

[in] xDest

Die x-Koordinate in logischen Einheiten der oberen linken Ecke des Zielrechtecks.

[in] yDest

Die y-Koordinate in logischen Einheiten der oberen linken Ecke des Zielrechtecks.

[in] w

Die Breite des Bilds in logischen Einheiten.

[in] h

Die Höhe des Bilds in logischen Einheiten.

[in] xSrc

Die x-Koordinate in logischen Einheiten der linken unteren Ecke des Bilds.

[in] ySrc

Die y-Koordinate in logischen Einheiten der unteren linken Ecke des Bilds.

[in] StartScan

Die starte Scanzeile im Bild.

[in] cLines

Die Anzahl der DIB-Scanzeilen, die in dem Array enthalten sind, auf das der lpvBits-Parameter verweist.

[in] lpvBits

Ein Zeiger auf die Farbdaten, die als Bytearray gespeichert sind. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] lpbmi

Ein Zeiger auf eine BITMAPINFO-Struktur , die Informationen zum DIB enthält.

[in] ColorUse

Gibt an, ob das bmiColors-Element der BITMAPINFO-Struktur explizite rote, grüne, blaue (RGB)-Werte oder Indizes in einer Palette enthält. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

Der fuColorUse-Parameter muss einer der folgenden Werte sein.

Wert	Bedeutung
DIB_PAL_COLORS	Die Farbtabelle besteht aus einem Array von 16-Bit-Indizes in der derzeit ausgewählten logischen Palette.
DIB_RGB_COLORS	Die Farbtabelle enthält RGB-Literalwerte.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der festgelegten Scanzeilen.

Wenn null Scanzeilen festgelegt sind (z. B. wenn dwHeight 0 ist) oder die Funktion fehlschlägt, gibt die Funktion null zurück.

Wenn der Treiber das an SetDIBitsToDevice übergebene JPEG- oder PNG-Dateibild nicht unterstützen kann, schlägt die Funktion fehl und gibt GDI_ERROR zurück. Wenn ein Fehler auftritt, muss die Anwendung auf ihre eigene JPEG- oder PNG-Unterstützung zurückgreifen, um das Bild in eine Bitmap zu dekomprimieren, und die Bitmap dann an SetDIBitsToDevice übergeben.

Hinweise

Die optimale Bitmapzeichnungsgeschwindigkeit wird erreicht, wenn die Bitmapbits Indizes in der Systempalette sind.

Anwendungen können die Farben und Indizes der Systempalette abrufen, indem sie die GetSystemPaletteEntries-Funktion aufrufen. Nachdem die Farben und Indizes abgerufen wurden, kann die Anwendung den DIB erstellen. Weitere Informationen zur Systempalette finden Sie unter Farben.

Die Scanzeilen müssen auf einem DWORD ausgerichtet werden, mit Ausnahme von RLE-komprimierten Bitmaps.

Der Ursprung eines DIB von unten nach oben ist die linke untere Ecke der Bitmap. Der Ursprung eines DIB von oben nach unten ist die obere linke Ecke.

Um die Menge an Arbeitsspeicher zu reduzieren, die zum Festlegen von Bits aus einem großen DIB auf einer Geräteoberfläche erforderlich ist, kann eine Anwendung die Ausgabe banden, indem sie SetDIBitsToDevice wiederholt aufruft und jedes Mal einen anderen Teil der Bitmap im lpvBits-Array platziert. Die Werte der Parameter uStartScan und cScanLines identifizieren den Teil der Bitmap, der im lpvBits-Array enthalten ist.

Die SetDIBitsToDevice-Funktion gibt einen Fehler zurück, wenn sie von einem Prozess aufgerufen wird, der im Hintergrund ausgeführt wird, während eine VOLLBILD-MS-DOS-Sitzung im Vordergrund ausgeführt wird.

Wenn das biCompression-Element von BITMAPINFOHEADER BI_JPEG oder BI_PNG ist, verweist lpvBits auf einen Puffer, der ein JPEG- oder PNG-Bild enthält. Das biSizeImage-Element von gibt die Größe des Puffers an. Der fuColorUse-Parameter muss auf DIB_RGB_COLORS festgelegt werden.
Um eine ordnungsgemäße Metafile-Spooling während des Druckens sicherzustellen, müssen Anwendungen den ESCAPE-Wert CHECKJPEGFORMAT oder CHECKPNGFORMAT aufrufen, um zu überprüfen, ob der Drucker das JPEG- bzw. PNG-Bild erkennt, bevor SetDIBitsToDevice aufgerufen wird.

ICM: Die Farbverwaltung wird ausgeführt, wenn die Farbverwaltung mit einem Aufruf von SetICMMode aktiviert wurde, wobei der Parameter iEnableICM auf ICM_ON festgelegt ist. Wenn die von lpbmi angegebene Bitmap über einen BITMAPV4HEADER verfügt, der die Gamma- und Endpunktmitglieder angibt, oder über einen BITMAPV5HEADER , der entweder die Gamma- und Endpunktmitglieder oder die ProfileData- und profileSize-Member angibt, behandelt der Aufruf die Pixel der Bitmap so, als würden sie im von diesen Membern beschriebenen Farbraum und nicht im Quellfarbraum des Gerätekontexts ausgedrückt.

Beispiele

Ein Beispiel finden Sie unter Testen eines Druckers für JPEG- oder PNG-Unterstützung.

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 (einschließlich Windows.h)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll