GetDIBits()函数

函数功能:GetDIBits函数检取指定位图的信息,并将其以指定格式复制到一个缓冲区中。

参数:

hdc:设备环境句柄。

hbmp:位图句柄。

uStartScan:指定检索的第一个扫描线。

cScanLines:指定检索的扫描线数。

lpvBits:指向用来检索位图数据的缓冲区的指针。如果此参数为NULL,那么函数将把位图的维数与格式传递给lpbi参数指向的BITMAPINFO结构。

lpbi:指向一个BITMAPINFO结构的指外,此结构确定了设备无在位图的数据格式。

uUsage:指定BITMAPINFO结构的bmiColors成员的格式。它必须为下列取值:

DIB_PAL_COLORS:颜色表由指向当前逻辑调色板的16位索引值数组构成。

DIB_RGB_COLORS:颜色表由红、绿、蓝(RGB)三个直接值构成。

返回值:如果lpvBits参数非空,并且函数调用成功,那么返回值为从位图复制的扫描线数。

Windows 95和Windows 98:如果lpvBits参数为NULL并且GetDIBits成功地填充了BITMAPINFO结构,那么返回值为位图中总共的扫描线数。

Windows NT:如果lpvBits参数为NULL并且GetDIBits成功地填充了BITMAPINFO结构,那么返回值为非0。如果函数执行失败,那么将返回0值。Windows NT:若想获得更多错误信息,请调用callGetLastError函数。

注释:如果所需要的DIB格式与其内部格式相匹配,那么位图的RGB值将被复制。如果不匹配,那么将合成一个颜色表。下表描述了针对每一种颜色格式所合成的颜色表。

1_BPP:颜色表中仅包含黑白表项。

4_BPP:颜色表由标准VGA定义的颜色组合而成。

8_BPP:颜色表由GDI定义的256色组合而成。

24_BPP:不返回颜色表。

如果lpvBits参数为一个有效指针,那么位图信息头结构的前6个成员必须初始化为DIB的大小和格式。

注意:位图信息头结构可为以下几种格式:

操作系统位图信息头结构(Operating System Bitmap Information Header)

Windows NT 3.51及早期的BITMAPINFOHEADER

Windows NT 4.0及Windows 95中的BITMAPV4HEADER

Windows NT 5.0及Windows 98中的BITMAPV5HEADER

通过将高度设为正数来指定一个自下而上的DIB,而自上而下的DIB则通过设置一个负的高度值来指定。位图的颜色表将附加在BITMAPINFO结构的后面。

如果lpvBits为NULL,那么GetDIBits将检查lpbi所指向的第一个结构的第一个成员。这一成员必须指定BITMAPCOREHEADER结构或位图信息头结构的字节数。函数将通过指定的大小来确定剩余成员如何被初始化。

如果lpvBits为NULL,并且BITMAPINFO结构的bit count成员初始化为0,那么GetDIBits将不填充BITMAPCOREHEADER结构或位图信息头结构的颜色表部分。这一技术可用来查询位图属性。

应用程序调用这个函数时必须将hbmp参数所标识的位图选择到一个设备环境中。

自下而上DIB的原点为位图的左下角,自上而下DIB的原点为其左上角。

速查:Windows NT:3.1及以上版本;Windows:95及以上版本;Windows CE:不支持;头文件:wingdi.h;库文件:gdi32.lib。