stretchDIBits 函式 (wingdi.h)

發行項
03/04/2024

StretchDIBits 函式會將 DIB、JPEG 或 PNG 影像中圖元矩形的色彩數據複製到指定的目的地矩形。如果目的矩形大於來源矩形，此函式會延展色彩數據的數據列和數據行，以符合目的矩形。如果目的矩形小於來源矩形，此函式會使用指定的點陣作業來壓縮數據列和數據行。

語法

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
);

參數

[in] hdc

目的地裝置內容的句柄。

[in] xDest

目的地矩形左上角的 X 座標，以邏輯單位表示。

[in] yDest

目的地矩形左上角的 Y 座標，以邏輯單位表示。

[in] DestWidth

目的地矩形的寬度，以邏輯單位表示。

[in] DestHeight

目的地矩形的高度，以邏輯單位表示。

[in] xSrc

影像中來源矩形的 X 座標，以像素為單位。

[in] ySrc

影像中來源矩形的 Y 座標，以像素為單位。

[in] SrcWidth

影像中來源矩形的寬度，以像素為單位。

[in] SrcHeight

影像中來源矩形的高度，以像素為單位。

[in] lpBits

影像位的指標，儲存為位元組陣列。如需詳細資訊，請參閱＜備註＞一節。

[in] lpbmi

BITMAPINFO 結構的指標，其中包含 DIB 的相關信息。

[in] iUsage

指定是否提供 BITMAPINFO 結構的 bmiColors 成員，如果是的話，bmiColors 是否包含明確的紅色、綠色、藍色 (RGB) 值或索引。 iUsage 參數必須是下列其中一個值。

值	意義
DIB_PAL_COLORS	陣列在來源裝置內容的邏輯調色盤中包含16位索引。
DIB_RGB_COLORS	色彩表格包含常值 RGB 值。

如需詳細資訊，請參閱＜備註＞一節。

[in] rop

點陣作業程式代碼，指定來源圖元、目的地裝置內容的目前筆刷，以及要結合目的地圖元以形成新的影像。如需一些常見點陣作業程式代碼的清單，請參閱 BitBlt。

傳回值

如果函式成功，則傳回值是複製的掃描行數。請注意，這個值可以是鏡像內容的負值。

如果函式失敗，或未複製掃描行，則傳回值為 0。

如果驅動程式不支持傳遞至 StretchDIBits 的 JPEG 或 PNG 檔案映像，函式將會失敗並傳回GDI_ERROR。如果發生失敗，應用程式必須回復自己的 JPEG 或 PNG 支援，才能將影像解壓縮到位圖，然後將點陣圖傳遞至 StretchDIBits。

備註

由下而下 DIB 的原點是左下角;由上而下 DIB 的原點是左上角。

如果 nSrcWidth 和 nDestWidth 參數的符號不同，StretchDIBits 會建立位圖的鏡像影像，或者 nSrcHeight 和 nDestHeight 參數不同時。如果 nSrcWidth 和 nDestWidth 有不同的符號，函式會沿著 X 軸建立位圖的鏡像影像。如果 nSrcHeight 和 nDestHeight 有不同的符號，此函式會沿著 Y 軸建立位圖的鏡像影像。

如果 DIB 之 BITMAPINFOHEADER 結構的 biHeight 成員正負號，StretchDIBits 會建立由上而下影像。如需程式代碼範例，請參閱調整 JPEG 或 PNG 映像的大小。

此函式允許將 JPEG 或 PNG 影像當做來源影像傳遞。每個參數的使用方式維持不變，但下列情況除外：

如果 BITMAPINFOHEADER 的 biCompression 成員BI_JPEG或BI_PNG，lpBits 會分別指向包含 JPEG 或 PNG 影像的緩衝區。 BITMAPINFOHEADER 結構的 biSizeImage 成員會指定緩衝區的大小。 iUsage 參數必須設定為 DIB_RGB_COLORS。 dwRop 參數必須設定為 SRCCOPY。
若要在列印時確保適當的中繼檔多任務緩衝處理，應用程式必須先呼叫 CHECKJPEGFORMAT 或 CHECKPNGFORMAT 逸出，以確認列印機會分別辨識 JPEG 或 PNG 影像，再呼叫 StretchDIBits。

Icm： 如果色彩管理已啟用對SetICMMode 的呼叫，且 iEnableICM 參數設定為 ICM_ON，則會執行色彩管理。如果 lpBitsInfo 指定的位圖具有指定 gamma 和 endpoints 成員的BITMAPV4HEADER ，或指定 gamma 和 endpoints 成員或 profileData 和 profileSize 成員的 BITMAPV5HEADER ，則呼叫會將位圖的圖元視為以這些成員所描述的色彩空間表示，而不是在裝置內容的來源色彩空間中表示。

範例

如需範例，請參閱調整 JPEG 或 PNG 映像的大小。

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	wingdi.h (包含 Windows.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll