createDIBSection 函式 (wingdi.h)

發行項
03/04/2024

CreateDIBSection 函式會建立可讓應用程式直接寫入的 DIB。函式提供位陣陣值的指標。您可以為函式用來建立位圖的檔案對應物件提供句柄，或讓系統配置位圖的記憶體。

語法

HBITMAP CreateDIBSection(
  [in]  HDC              hdc,
  [in]  const BITMAPINFO *pbmi,
  [in]  UINT             usage,
  [out] VOID             **ppvBits,
  [in]  HANDLE           hSection,
  [in]  DWORD            offset
);

參數

[in] hdc

裝置內容的控制代碼。如果 iUsage 的值DIB_PAL_COLORS，函式會使用此裝置內容的邏輯調色盤來初始化 DIB 色彩。

[in] pbmi

BITMAPINFO 結構的指標，指定 DIB 的各種屬性，包括位圖維度和色彩。

[in] usage

pbmi 所指向之 BITMAPINFO 結構的 bmiColors 陣列成員中所包含資料類型， (邏輯調色盤索引或常值 RGB 值) 。定義下列值。

值	意義
DIB_PAL_COLORS	bmiColors 成員是 16 位索引的陣列，位於 hdc 所指定裝置內容的邏輯選擇區中。
DIB_RGB_COLORS	BITMAPINFO 結構包含常值 RGB 值的陣列。

[out] ppvBits

接收 DIB 位值位置指標的變數指標。

[in] hSection

函式將用來建立 DIB 的檔案對應物件的句柄。此參數可以是 Null。

如果 hSection 不是 NULL，它必須是使用 PAGE_READWRITE 或 PAGE_WRITECOPY 旗標呼叫 CreateFileMapping 函式所建立之檔案對應物件的句柄。不支援只讀 DIB 區段。由其他方式建立的句柄會導致 CreateDIBSection 失敗。

如果 hSection 不是 NULL，CreateDIBSection 函式會在 hSection 所參考的檔案對應物件中，找出位移 dwOffset 上的位陣陣值。應用程式稍後可以使用 CreateDIBSection 傳回的 HBITMAP 呼叫 GetObject 函式，以擷取 hSection 句柄。

如果 hSection 為 NULL，則系統會為 DIB 配置記憶體。在此情況下， CreateDIBSection 函式會忽略 dwOffset 參數。應用程式稍後無法取得此記憶體的句柄。藉由呼叫 GetObject 函式來填入 DIBSECTION 結構的 dshSection 成員將會是 NULL。

[in] offset

hSection 所參考之檔案對應物件的開頭位移，其中位陣值的記憶體開始。如果 hSection 為 NULL，則會忽略此值。位圖位值會對齊雙字界限，因此 dwOffset 必須是 DWORD 大小的倍數。

傳回值

如果函式成功，則傳回值是新建立 DIB 的句柄，而 *ppvBits 會指向位陣陣元值。

如果函式失敗，則傳回值為 NULL，而 *ppvBits 為 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

GetLastError 可以傳回下列值：

錯誤碼	描述
ERROR_INVALID_PARAMETER	一或多個輸入參數無效。

備註

如上所述，如果 hSection 為 NULL，系統會為 DIB 配置記憶體。當您稍後藉由呼叫 DeleteObject 函式來刪除DIB時，系統會關閉該記憶體的句柄。如果 hSection 不是 NULL，您必須在呼叫 DeleteObject 以刪除點陣圖之後，自行關閉 hSection 記憶體句柄。

您無法將一個應用程式的 DIB 區段貼到另一個應用程式。

CreateDIBSection 不會使用 BITMAPINFOHEADER 參數 biXPelsPerMeter 或 biYPelsPerMeter ，而且不會在 BITMAPINFO 結構中提供解析資訊。

您必須先保證 GDI 子系統已完成 CreateDIBSection 所建立之位圖的任何繪圖，再自行繪製位圖。必須同步處理位圖的存取權。藉由呼叫 GdiFlush 函式來執行此動作。這適用於位陣陣值的任何使用指標，包括將指標傳遞至 SetDIBits 等函式的呼叫中。

Icm： 沒有色彩管理完成。

規格需求

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