createDIBSection 函式 (wingdi.h)

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 值) 。 定義下列值。

[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 可以傳回下列值：

備註

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

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

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

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

Icm： 沒有色彩管理完成。

規格需求

另請參閱

BITMAPINFO

點陣圖函式

位圖概觀

CreateFileMapping

DIBSECTION

DeleteObject

GdiFlush

GetDIBColorTable

GetObject

SetDIBColorTable

SetDIBits