StretchDIBits-Funktion (wingdi.h)

Artikel
08/27/2023

Die StretchDIBits-Funktion kopiert die Farbdaten für ein Rechteck von Pixeln in einem DIB-, JPEG- oder PNG-Bild in das angegebene Zielrechteck. Wenn das Zielrechteck größer als das Quellrechteck ist, dehnt diese Funktion die Zeilen und Spalten der Farbdaten so, dass sie dem Zielrechteck entsprechen. Wenn das Zielrechteck kleiner als das Quellrechteck ist, komprimiert diese Funktion die Zeilen und Spalten mithilfe des angegebenen Rastervorgangs.

Syntax

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

Parameter

[in] hdc

Ein Handle für den Zielgerä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] DestWidth

Die Breite des Zielrechtecks in logischen Einheiten.

[in] DestHeight

Die Höhe des Zielrechtecks in logischen Einheiten.

[in] xSrc

Die x-Koordinate in Pixel des Quellrechtecks im Bild.

[in] ySrc

Die y-Koordinate in Pixel des Quellrechtecks im Bild.

[in] SrcWidth

Die Breite des Quellrechtecks im Bild in Pixel.

[in] SrcHeight

Die Höhe des Quellrechtecks im Bild in Pixel.

[in] lpBits

Ein Zeiger auf die Bildbits, die als Bytearray gespeichert werden. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in] lpbmi

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

[in] iUsage

Gibt an, ob das bmiColors-Element der BITMAPINFO-Struktur bereitgestellt wurde und, falls ja, ob bmiColors explizite rote, grüne, blaue (RGB)-Werte oder Indizes enthält. Der iUsage-Parameter muss einer der folgenden Werte sein.

Wert	Bedeutung
DIB_PAL_COLORS	Das Array enthält 16-Bit-Indizes in der logischen Palette des Quellgerätekontexts.
DIB_RGB_COLORS	Die Farbtabelle enthält RGB-Literalwerte.

Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

[in] rop

Ein Rastervorgangscode, der angibt, wie die Quellpixel, der aktuelle Pinsel des Zielgerätekontexts und die Zielpixel kombiniert werden sollen, um das neue Bild zu bilden. Eine Liste einiger gängiger Rastervorgangscodes finden Sie unter BitBlt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert die Anzahl der kopierten Scanzeilen. Beachten Sie, dass dieser Wert für gespiegelte Inhalte negativ sein kann.

Wenn die Funktion fehlschlägt oder keine Scanzeilen kopiert werden, ist der Rückgabewert 0.

Wenn der Treiber das an StretchDIBits ü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 StretchDIBits zu übergeben.

Hinweise

Der Ursprung eines Bottom-Up-DIB ist die linke untere Ecke; Der Ursprung eines DIB von oben nach unten ist die obere linke Ecke.

StretchDIBits erstellt ein Spiegel Bild einer Bitmap, wenn die Zeichen der Parameter nSrcWidth und nDestWidth oder wenn sich die Parameter nSrcHeight und nDestHeight unterscheiden. Wenn nSrcWidth und nDestWidth unterschiedliche Vorzeichen aufweisen, erstellt die Funktion ein Spiegel Bild der Bitmap entlang der x-Achse. Wenn nSrcHeight und nDestHeight unterschiedliche Vorzeichen aufweisen, erstellt die Funktion ein Spiegel Bild der Bitmap entlang der y-Achse.

StretchDIBits erstellt ein Bild von oben nach unten, wenn das Vorzeichen des biHeight-Members der BITMAPINFOHEADER-Struktur für den DIB negativ ist. Ein Codebeispiel finden Sie unter Größenanpassung eines JPEG- oder PNG-Bilds.

Mit dieser Funktion kann ein JPEG- oder PNG-Bild als Quellbild übergeben werden. Wie die einzelnen Parameter verwendet werden, bleibt unverändert, außer:

Wenn das biCompression-Element von BITMAPINFOHEADER BI_JPEG oder BI_PNG ist, zeigt lpBits auf einen Puffer, der jeweils ein JPEG- oder PNG-Bild enthält. Das biSizeImage-Element der BITMAPINFOHEADER-Struktur gibt die Größe des Puffers an. Der iUsage-Parameter muss auf DIB_RGB_COLORS festgelegt werden. Der dwRop-Parameter muss auf SRCCOPY 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 StretchDIBits 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 lpBitsInfo 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, werden die Pixel der Bitmap durch den Aufruf als im von diesen Membern beschriebenen Farbraum und nicht im Quellfarbraum des Gerätekontexts ausgedrückt.

Beispiele

Ein Beispiel finden Sie unter Größenanpassung eines JPEG- oder PNG-Bilds.

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