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

指向 BITMAPINFO 结构的指针，该结构指定 DIB 的各种属性，包括位图尺寸和颜色。

[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，则忽略此值。位图位值在双字边界上对齐，因此 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 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	wingdi.h (包括 Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll