setDIBitsToDevice 函式 (wingdi.h)

發行項
03/13/2024

SetDIBitsToDevice 函式會使用 DIB、JPEG 或 PNG 影像中的色彩數據，在裝置上設定與目的地裝置內容相關聯的指定矩形中的圖元。

語法

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

參數

[in] hdc

裝置內容的句柄。

[in] xDest

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

[in] yDest

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

[in] w

影像的寬度，以邏輯單位表示。

[in] h

影像的高度，以邏輯單位表示。

[in] xSrc

影像左下角的 X 座標，以邏輯單位表示。

[in] ySrc

影像左下角的 Y 座標，以邏輯單位表示。

[in] StartScan

影像中的開始掃描行。

[in] cLines

lpvBits 參數所指向數位中包含的 DIB 掃描行數。

[in] lpvBits

儲存為位元組陣列之色彩數據的指標。如需詳細資訊，請參閱接下來的＜備註＞一節。

[in] lpbmi

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

[in] ColorUse

指出 BITMAPINFO 結構的 bmiColors 成員是否包含明確的紅色、綠色、藍色 (RGB) 值或索引到調色盤中。如需詳細資訊，請參閱接下來的＜備註＞一節。

fuColorUse 參數必須是下列其中一個值。

值	意義
DIB_PAL_COLORS	色彩數據表是由目前選取之邏輯調色盤中的 16 位索引陣列所組成。
DIB_RGB_COLORS	色彩表格包含常值 RGB 值。

傳回值

如果函式成功，則傳回值是設定的掃描行數。

如果 (設定零掃描行，例如 dwHeight 為 0) 或函式失敗時，函式會傳回零。

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

備註

當點陣圖位為系統調色盤的索引時，會取得最佳的點陣圖繪製速度。

應用程式可以藉由呼叫 GetSystemPaletteEntries 函式來擷取系統調色盤色彩和索引。擷取色彩和索引之後，應用程式可以建立 DIB。如需系統調色盤的詳細資訊，請參閱色彩。

掃描行必須對齊 DWORD ，但 RLE 壓縮點圖除外。

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

若要減少從裝置介面上大型 DIB 設定位所需的記憶體數量，應用程式可以重複呼叫 SetDIBitsToDevice，將點陣圖的不同部分放在 lpvBits 陣列中，以帶狀顯示輸出。 uStartScan 和 cScanLines 參數的值會識別 lpvBits 陣列中包含的點陣圖部分。

如果 SetDIBitsToDevice 函式是由在前景執行全螢幕 MS-DOS 作業階段時在背景中執行的進程所呼叫，則會傳回錯誤。

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

Icm： 如果色彩管理已啟用對SetICMMode 的呼叫，且 iEnableICM 參數設定為 ICM_ON，則會執行色彩管理。如果 lpbmi 指定的位陣圖具有指定 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