CreateDIBSection 関数 (wingdi.h)

[アーティクル]
03/08/2023

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

ビットマップの寸法や色など、DIB のさまざまな属性を指定する BITMAPINFO 構造体へのポインター。

[in] usage

pbmi が指す BITMAPINFO 構造体の bmiColors 配列メンバーに含まれるデータの型 (論理パレットインデックスまたはリテラル RGB 値)。次の値が定義されています。

値	意味
DIB_PAL_COLORS	bmiColors メンバーは、hdc で指定されたデバイスコンテキストの論理パレットに 16 ビットインデックスの配列です。
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 の場合、この値は無視されます。ビットマップビット値は doubleword 境界に配置されるため、 dwOffset は DWORD のサイズの倍数である必要があります。

戻り値

関数が成功した場合、戻り値は新しく作成された DIB へのハンドルであり、*ppvBits は ビットマップビット値を指します。

関数が失敗した場合、戻り値は NULL、*ppvBits は NULL です。詳細なエラー情報を得るには、GetLastError を呼び出します。

GetLastError は次の値を返すことができます。

エラーコード	説明
ERROR_INVALID_PARAMETER	1 つ以上の入力パラメーターが無効です。

注釈

前述のように、 hSection が NULL の場合、システムは DIB にメモリを割り当てます。後で DeleteObject 関数を呼び出して DIB を削除すると、システムはそのメモリへのハンドルを閉じます。 hSection が NULL でない場合は、DeleteObject を呼び出してビットマップを削除した後、hSection メモリハンドルを閉じる必要があります。

あるアプリケーションから別のアプリケーションに DIB セクションを貼り付けることはできません。

CreateDIBSection は BITMAPINFOHEADER パラメーター biXPelsPerMeter または biYPelsPerMeter を 使用せず、 BITMAPINFO 構造体に解決情報を提供しません。

自分でビットマップに描画する前に、GDI サブシステムが CreateDIBSection によって作成されたビットマップへの描画を完了していることを確認する必要があります。ビットマップへのアクセスは同期する必要があります。これを行うには、 GdiFlush 関数を呼び出します。これは、 SetDIBits などの関数の呼び出しでポインターを渡すなど、ビットマップビット値へのポインターの使用に適用されます。

Icm： 色の管理は行われません。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	wingdi.h (Windows.h を含む)
Library	Gdi32.lib
[DLL]	Gdi32.dll