(wingdi.h) GetDIBits 函式

發行項
08/27/2023

GetDIBits函式會擷取指定相容點陣圖的位，並使用指定的格式將它們複製到緩衝區中作為 DIB。

語法

int GetDIBits(
  [in]      HDC          hdc,
  [in]      HBITMAP      hbm,
  [in]      UINT         start,
  [in]      UINT         cLines,
  [out]     LPVOID       lpvBits,
  [in, out] LPBITMAPINFO lpbmi,
  [in]      UINT         usage
);

參數

[in] hdc

裝置內容的控制碼。

[in] hbm

點陣圖的控制碼。這必須是相容的點陣圖 (DDB) 。

[in] start

要擷取的第一個掃描行。

[in] cLines

要擷取的掃描行數。

[out] lpvBits

要接收點陣圖資料的緩衝區指標。如果此參數為Null，函式會將點陣圖的維度和格式傳遞給lpbmi參數所指向的BITMAPINFO結構。

[in, out] lpbmi

BITMAPINFO結構的指標，指定 DIB 資料所需的格式。

[in] usage

BITMAPINFO結構的bmiColors成員格式。它必須是下列其中一個值。

值	意義
DIB_PAL_COLORS	色彩資料表應該包含目前邏輯調色盤中 16 位索引的陣列。
DIB_RGB_COLORS	色彩表格應包含常值紅色、綠色、藍色 (RGB) 值。

傳回值

如果 lpvBits 參數為非Null 且函式成功，則傳回值會是從點陣圖複製的掃描行數。

如果 lpvBits 參數為 Null ，且 GetDIBits 成功填滿 BITMAPINFO 結構，則傳回值為非零。

如果此函式失敗，則傳回值為零。

此函式可以傳回下列值。

傳回碼	描述
ERROR_INVALID_PARAMETER	一或多個輸入參數無效。

備註

如果 DIB 的要求格式符合其內部格式，則會複製點陣圖的 RGB 值。如果要求的格式不符合內部格式，則會合成色彩表格。下表描述針對每個格式合成的色彩資料表。

值	意義
1_BPP	色彩表格是由黑色和白色專案所組成。
4_BPP	色彩表格包含與標準 VGA 調色盤相同的色彩混合。
8_BPP	色彩表格是由 GDI 所定義的一般混合 256 種色彩所組成。 (包含在這些 256 種色彩中，是預設邏輯調色盤中找到的 20 種色彩。)
24_BPP	不會傳回任何色彩表格。

如果 lpvBits 參數是有效的指標，則必須初始化 BITMAPINFOHEADER 結構的前六個成員，以指定 DIB 的大小和格式。掃描行必須對齊 DWORD ，但 RLE 壓縮點陣圖除外。

將高度設定為正數，而由上而下 DIB 則藉由將高度設定為負數來指定由上而下 DIB。點陣圖色彩表格會附加至 BITMAPINFO 結構。

如果 lpvBits 為 Null， GetDIBits 會 檢查 lpbi所指向之第一個結構的第一個成員。這個成員必須指定 BITMAPCOREHEADER 或 BITMAPINFOHEADER 結構的大小，以位元組為單位。函式會使用指定的大小來決定剩餘成員的初始化方式。

如果 lpvBits 為 Null ，且 BITMAPINFO 的位元數目成員初始化為零， GetDIBits 就會填入 BITMAPINFOHEADER 結構或 BITMAPCOREHEADER ，而沒有色彩表格。這項技術可用來查詢點陣圖屬性。

當應用程式呼叫此函式時， 不得選取 hbmp 參數所識別的點陣圖到裝置內容中。

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

範例

如需範例，請參閱擷取映射。

規格需求


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