CreateDIBSection

描述

CreateDIBSection函数创建一个DIB，应用程序可以直接写入。该函数提供了指向位图位值位置的指针。您可以为函数用于创建位图的文件映射对象提供一个句柄，也可以让系统为位图分配内存。

C++ 语法

HBITMAP CreateDIBSection(

__in HDC hdc,

__in const BITMAPINFO *pbmi,

__in UINT iUsage,

__out VOID **ppvBits,

__in HANDLE hSection,

__in DWORD dwOffset

);

PowerBASIC 语法

FUNCTION CreateDIBSection( _

BYVAL hdc AS DWORD, _

BYREF pbmi AS BITMAPINFO, _

BYVAL iUsage AS DWORD, _

BYVAL ppvBits AS DWORD, _

BYVAL hSection AS DWORD, _

BYVAL dwOffset AS DWORD _

) AS DWORD

参数

hdc

[in]处理设备上下文。如果iUsage的值为DIB_PAL_COLORS，则该函数使用该设备上下文的逻辑调色板来初始化DIB颜色。

pbmi

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

iUsage

[in]指定由PBMI（逻辑调色板索引或文字RGB值）指向的BITMAPINFO结构bmiColors结构的bmiColors数组成员中包含的数据类型。定义了以下值。

值	含义
DIB_PAL_COLORS	bmiColors成员是由hDC指定的设备上下文的逻辑调色板中的16位索引数组。
DIB_RGB_COLORS	BITMAPINFO结构包含一系列文字RGB值。

ppvBits

[out]指向接收指向DIB位值位置的指针的变量的指针。

hSection

[in]处理函数将用于创建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。

dwOffset

[in]指定从hSection引用的文件映射对象开头的偏移量，其中位图位值的存储将开始。如果hSection为NULL，则忽略此值。位图位值在双字边界上对齐，因此dwOffset必须是DWORD大小的倍数。

返回值

如果函数成功，则返回值是新创建的DIB的句柄，ppvBitsru-Latn指向位图位值。

如果函数失败，则返回值为NULL，并且ppvBitsru-Latn为NULL。

Windows NT / 2000 / XP / Vista / Windows 7：要获取扩展错误信息，请调用GetLastError.这可以是以下值。

值	含义
ERROR_INVALID_PARAMETER	一个或多个输入参数无效。

备注

如上所述，如果hSection为NULL，系统将为DIB分配内存。当您稍后通过调用DeleteObject功能删除DIB时，系统将关闭该内存的句柄。如果hSection不为NULL，则必须在调用DeleteObject后关闭hSection内存句柄才能删除位图。

您不能将DIB部分从一个应用程序粘贴到另一个应用程序。

CreateDIBSection不使用BITMAPINFOHEADER参数biXPelsPerMeter或biYPelsPerMeter，并且不会在BITMAPINFO结构中提供解析信息。

Windows NT / 2000 / XP / Vista / Windows 7：您需要保证GDI子系统在您自己绘制位图之前已经完成了由CreateDIBSection创建的位图的任何绘图。访问位图必须同步。通过调用GdiFlush函数来执行此操作。这适用于指向位图位值的指针的任何使用，包括将指针传递给诸如SetDIBits之类的函数。

ICM：没有颜色管理完成。

引用文件 #INCLUDE Once

WinGdi.inc（包括Windows.inc）