CreateDIBSection

関数

アプリが直接アクセス可能なメモリを持つDIBセクションを作成する。

DLLGDI32.dll呼出規約winapiSetLastErrorあり対応OSWindows 2000 以降

シグネチャ

// GDI32.dll
#include <windows.h>

HBITMAP CreateDIBSection(
    HDC hdc,   // optional
    const BITMAPINFO* pbmi,
    DIB_USAGE usage,
    void** ppvBits,
    HANDLE hSection,   // optional
    DWORD offset
);

パラメーター

名前

型

方向

説明

hdc

HDC

inoptional

デバイスコンテキストへのハンドル。iUsage の値が DIB_PAL_COLORS の場合、関数はこのデバイスコンテキストの論理パレットを使用して DIB の色を初期化します。

pbmi

BITMAPINFO*

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

usage

DIB_USAGE

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

値	意味
DIB_PAL_COLORS	bmiColors メンバーは、hdc で指定されたデバイスコンテキストの論理パレットへの 16 ビットインデックスの配列です。
DIB_RGB_COLORS	BITMAPINFO 構造体は、リテラルな RGB 値の配列を含みます。

ppvBits

void**

out

DIB ビット値の位置へのポインターを受け取る変数へのポインター。

hSection

HANDLE

inoptional

関数が 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 になります。

offset

DWORD

hSection が参照するファイルマッピングオブジェクトの先頭から、ビットマップのビット値の格納を開始する位置までのオフセット。hSection が NULL の場合、この値は無視されます。ビットマップのビット値はダブルワード境界に整列されるため、dwOffset は DWORD のサイズの倍数でなければなりません。

戻り値の型: HBITMAP

公式ドキュメント

CreateDIBSection 関数は、アプリケーションが直接書き込める DIB を作成します。

戻り値

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

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

GetLastError は次の値を返すことがあります。

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

解説(Remarks)

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

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

CreateDIBSection は BITMAPINFOHEADER のパラメーター biXPelsPerMeter および biYPelsPerMeter を使用せず、BITMAPINFO 構造体に解像度情報を提供しません。

CreateDIBSection で作成したビットマップに自分で描画する前に、GDI サブシステムがそのビットマップへの描画をすべて完了していることを保証する必要があります。ビットマップへのアクセスは同期しなければなりません。これは GdiFlush 関数を呼び出すことで行います。これは、ビットマップのビット値へのポインターを使用するあらゆる場合に適用され、SetDIBits などの関数の呼び出しでポインターを渡す場合も含まれます。

ICM: カラーマネジメントは行われません。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// GDI32.dll
#include <windows.h>

HBITMAP CreateDIBSection(
    HDC hdc,   // optional
    const BITMAPINFO* pbmi,
    DIB_USAGE usage,
    void** ppvBits,
    HANDLE hSection,   // optional
    DWORD offset
);

[DllImport("GDI32.dll", SetLastError = true, ExactSpelling = true)]
static extern IntPtr CreateDIBSection(
    IntPtr hdc,   // HDC optional
    IntPtr pbmi,   // BITMAPINFO*
    uint usage,   // DIB_USAGE
    IntPtr ppvBits,   // void** out
    IntPtr hSection,   // HANDLE optional
    uint offset   // DWORD
);

<DllImport("GDI32.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function CreateDIBSection(
    hdc As IntPtr,   ' HDC optional
    pbmi As IntPtr,   ' BITMAPINFO*
    usage As UInteger,   ' DIB_USAGE
    ppvBits As IntPtr,   ' void** out
    hSection As IntPtr,   ' HANDLE optional
    offset As UInteger   ' DWORD
) As IntPtr
End Function

' hdc : HDC optional
' pbmi : BITMAPINFO*
' usage : DIB_USAGE
' ppvBits : void** out
' hSection : HANDLE optional
' offset : DWORD
Declare PtrSafe Function CreateDIBSection Lib "gdi32" ( _
    ByVal hdc As LongPtr, _
    ByVal pbmi As LongPtr, _
    ByVal usage As Long, _
    ByVal ppvBits As LongPtr, _
    ByVal hSection As LongPtr, _
    ByVal offset As Long) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

CreateDIBSection = ctypes.windll.gdi32.CreateDIBSection
CreateDIBSection.restype = ctypes.c_void_p
CreateDIBSection.argtypes = [
    wintypes.HANDLE,  # hdc : HDC optional
    ctypes.c_void_p,  # pbmi : BITMAPINFO*
    wintypes.DWORD,  # usage : DIB_USAGE
    ctypes.c_void_p,  # ppvBits : void** out
    wintypes.HANDLE,  # hSection : HANDLE optional
    wintypes.DWORD,  # offset : DWORD
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
CreateDIBSection = Fiddle::Function.new(
  lib['CreateDIBSection'],
  [
    Fiddle::TYPE_VOIDP,  # hdc : HDC optional
    Fiddle::TYPE_VOIDP,  # pbmi : BITMAPINFO*
    -Fiddle::TYPE_INT,  # usage : DIB_USAGE
    Fiddle::TYPE_VOIDP,  # ppvBits : void** out
    Fiddle::TYPE_VOIDP,  # hSection : HANDLE optional
    -Fiddle::TYPE_INT,  # offset : DWORD
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "gdi32")]
extern "system" {
    fn CreateDIBSection(
        hdc: *mut core::ffi::c_void,  // HDC optional
        pbmi: *const BITMAPINFO,  // BITMAPINFO*
        usage: u32,  // DIB_USAGE
        ppvBits: *mut *mut (),  // void** out
        hSection: *mut core::ffi::c_void,  // HANDLE optional
        offset: u32  // DWORD
    ) -> *mut core::ffi::c_void;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("GDI32.dll", SetLastError = true)]
public static extern IntPtr CreateDIBSection(IntPtr hdc, IntPtr pbmi, uint usage, IntPtr ppvBits, IntPtr hSection, uint offset);
"@
$api = Add-Type -MemberDefinition $sig -Name 'GDI32_CreateDIBSection' -Namespace Win32 -PassThru
# $api::CreateDIBSection(hdc, pbmi, usage, ppvBits, hSection, offset)

#uselib "GDI32.dll"
#func global CreateDIBSection "CreateDIBSection" sptr, sptr, sptr, sptr, sptr, sptr
; CreateDIBSection hdc, varptr(pbmi), usage, ppvBits, hSection, offset   ; 戻り値は stat
; hdc : HDC optional -> "sptr"
; pbmi : BITMAPINFO* -> "sptr"
; usage : DIB_USAGE -> "sptr"
; ppvBits : void** out -> "sptr"
; hSection : HANDLE optional -> "sptr"
; offset : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "GDI32.dll"
#cfunc global CreateDIBSection "CreateDIBSection" sptr, var, int, sptr, sptr, int
; res = CreateDIBSection(hdc, pbmi, usage, ppvBits, hSection, offset)
; hdc : HDC optional -> "sptr"
; pbmi : BITMAPINFO* -> "var"
; usage : DIB_USAGE -> "int"
; ppvBits : void** out -> "sptr"
; hSection : HANDLE optional -> "sptr"
; offset : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "GDI32.dll"
#cfunc global CreateDIBSection "CreateDIBSection" sptr, sptr, int, sptr, sptr, int
; res = CreateDIBSection(hdc, varptr(pbmi), usage, ppvBits, hSection, offset)
; hdc : HDC optional -> "sptr"
; pbmi : BITMAPINFO* -> "sptr"
; usage : DIB_USAGE -> "int"
; ppvBits : void** out -> "sptr"
; hSection : HANDLE optional -> "sptr"
; offset : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。