CreateDIBSection

小甲鱼

注：本文档由 Diu 翻译，小甲鱼校对。

函数功能：

CreateDIBSection 函数用于创建一个应用程序可以直接写入的 DIB（设备无关位图文件）。

该函数返回一个指向位图位数据值的指针。你可以提供一个文件映射对象的句柄，该函数将会使用这个文件映射对象来创建位图，或者让系统为位图分配内存。


API 函数原型：

注释：_In_ 说明该参数是输入的，_Out_ 说明该参数是输出的。

HBITMAP CreateDIBSection(
  _In_        HDC        hdc,
  _In_  const BITMAPINFO *pbmi,
  _In_        UINT       iUsage,
  _Out_       VOID       **ppvBits,
  _In_        HANDLE     hSection,
  _In_        DWORD      dwOffset
);

参数解析：

参数	含义
hdc	1. 指定设备环境句柄 2. 如果 iUsage 参数的值是 DIB_PAL_COLORS，那么函数使用该设备环境的逻辑调色板来初始化 DIB 颜色
pbmi	指向 BITMAPINFO 结构体的指针，该结构体指定了 DIB 的各种属性，包括位图的维数和颜色
iUsage	1. 指定由 pbmi 参数（逻辑调色板索引值或是文本 RGB 值）指向的 BITMAPINFO 结构中的成员 bmiColors 数组包含的数据类型 2. 系统定义了下列值： 值 含义 DIB_PAL_COLORS 表示成员 bmiColors 是 hdc 指定的设备环境的逻辑调色板，使用的是 16 位索引值数组 DIB_RGB_COLORS 表示结构 BITMAPINFO 中包含一个文本 RGB 值的数组
ppvBits	指向一个变量的指针，该变量接收一个指向 DIB 位数据值的指针
hSection	1. 指定文件映射对象的句柄。该函数将会使用该文件映射对象来创建 DIB。该参数可以是 NULL 2. 如果 hSection 参数的值不是 NULL，那么它必须是文件映射对象的句柄。并且该文件映射对象是通过调用带有 PAGE_READWRITE 或 PAGE_WRITECOPY 标志的 CreateFileMapping 函数来创建的。不支持只读类型的 DIB 段。通过其他方法创建的句柄将会造成 CreateDIBSection 函数执行失败 3. 如果 hSection 参数的值不是 NULL，那么函数 CreateDIBSection 将在 hSection 引用的文件映射对象中偏移量为 dwOffset 处获取位图的位数据值。应用程序可以在以后通过调用 GetObject 函数来检索 hSection 句柄，并且 GetObject 函数使用了 GreateDIBSection 函数返回的 HBITMAP 4. 如果 hSection 参数的值为 NULL，那么系统将将会为 DIB 分配内存。在这种情况下，函数 CreateDIBSection 将忽略 dwOffset 参数，应用程序无法在以后获取指向内存的句柄。通过调用 GetObject 函数来填充的 DIBSECTION 结构体成员 dshSection 也将是 NULL
dwOffset	1. 指定从 hSection 引用的文件映射对象开始处算起的偏移量，并且这个偏移量指示位图的位数据值开始存放的地方 2. 如果 hSection 的值是 NULL，这个参数将被忽略 3. 图位的值是根据双字边界对齐，所以 dwOffset 必须是 DWORD 的倍数

返回值：

1. 如果函数调用成功，那么返回值是一个指向刚刚创建的 DIB 的句柄，并且 *ppvBits 指向该位图的位数据值；

2. 如果函数调用失败，那么返回值为 NULL，并且 *ppvBit 也为 NULL。

该函数能返回下列值：

返回码	描述
ERROR_INVALID_PARAMETER	一个或多个输入参数无效

备注：

1. 正如上面提到过的，如果 hSection 参数的值为 NULL，那么系统为 DIB 分配内存。当以后通过调用 DeleteObject 函数删除该 DIB 时，系统将关闭指向相应内存的句柄。如果 hSection 的值不为 NULL，那么在调用 DeleteObject 删除该位图之后，你必须自己关闭 hSection 内存句柄。

2.你不能将一个 DIB 段从一个应用程序粘贴到另一个应用程序。

3. CreateDIBSection 不使用 BITMAPINFOHEADER 结构的 biXPelsPerMeter 或 biYPelsPerMeter 成员
参数，并且将不提供在 BITMAPINFO 结构中的分辨率信息。

4.你必须确保在自己绘制位图之前，GDI 子系统已经完成对所有由 CreateDIBSection 创建的位图的绘制。访问位图必须是同步的。这可以通过调用 GdiFlush 函数来完成。这适用于任何指向位图的位数据值指针的情况，也包括在调用像 SetDIBits 这样的函数时传送指针的情形。

ICM：不进行颜色管理。


需求：

Minimum supported client	Windows 2000 专业版 [仅桌面应用程序]
Minimum supported server	Windows 2000 服务器版 [仅桌面应用程序]
Header	Wingdi.h (包含于 Windows.h)
Library	Gdi32.lib
DLL	Gdi32.dll

【API档案】版权归鱼C工作室(www.fishc.com)所有，转载请注明来源。