GetDIBits 函数 (wingdi.h)

  • 项目

GetDIBits 函数检索指定兼容位图的位，并使用指定格式将其作为 DIB 复制到缓冲区中。

语法

int GetDIBits(
  [in]      HDC          hdc,
  [in]      HBITMAP      hbm,
  [in]      UINT         start,
  [in]      UINT         cLines,
  [out]     LPVOID       lpvBits,
  [in, out] LPBITMAPINFO lpbmi,
  [in]      UINT         usage
);

参数

[in] hdc

设备上下文的句柄。

[in] hbm

位图的句柄。 这必须是兼容位图 (DDB) 。

[in] start

要检索的第一个扫描行。

[in] cLines

要检索的扫描行数。

[out] lpvBits

指向用于接收位图数据的缓冲区的指针。 如果此参数为 NULL，则该函数会将位图的尺寸和格式传递给 lpbmi 参数指向的 BITMAPINFO 结构。

[in, out] lpbmi

指向 BITMAPINFO 结构的指针，该结构指定 DIB 数据所需的格式。

[in] usage

BITMAPINFO 结构的 bmiColors 成员的格式。 必须是以下值之一。

值 含义
DIB_PAL_COLORS
 颜色表应包含当前逻辑调色板中的 16 位索引数组。
DIB_RGB_COLORS
 颜色表应包含文本红色、绿色、蓝色 (RGB) 值。

返回值

如果 lpvBits 参数为非 NULL 且函数成功，则返回值为从位图复制的扫描行数。

如果 lpvBits 参数为 NULL 且 GetDIBits 成功填充 BITMAPINFO 结构，则返回值为非零值。

如果函数失败，则返回值为零。

此函数可以返回以下值。

返回代码 说明
ERROR_INVALID_PARAMETER
 一个或多个输入参数无效。

注解

如果 DIB 请求的格式与其内部格式匹配，则会复制位图的 RGB 值。 如果请求的格式与内部格式不匹配，则会合成颜色表。 下表描述了针对每种格式合成的颜色表。

值 含义
1_BPP 颜色表由黑色和白色条目组成。
4_BPP 颜色表由与标准 VGA 调色板相同的颜色组合组成。
8_BPP 颜色表由 GDI 定义的 256 种颜色的常规混合组成。 (包含在这 256 种颜色中的是默认逻辑调色板中的 20 种颜色。)
24_BPP 不返回颜色表。
 

如果 lpvBits 参数是有效的指针，则必须初始化 BITMAPINFOHEADER 结构的前六个成员以指定 DIB 的大小和格式。 扫描行必须在 DWORD 上对齐，RLE 压缩位图除外。

自下而上 DIB 是通过将高度设置为正数来指定的，而自上而下 DIB 是通过将高度设置为负数来指定的。 位图颜色表将追加到 BITMAPINFO 结构中。

如果 lpvBits 为 NULL， 则 GetDIBits 将检查 lpbi 指向的第一个结构的第一个成员。 此成员必须指定 BITMAPCOREHEADER 或 BITMAPINFOHEADER 结构的大小（以字节为单位）。 函数使用指定的大小来确定应如何初始化剩余成员。

如果 lpvBits 为 NULL 且 BITMAPINFO 的位计数成员初始化为零， 则 GetDIBits 将填充 BITMAPINFOHEADER 结构或 BITMAPCOREHEADER ，而不填充颜色表。 此方法可用于查询位图属性。

应用程序调用此函数时，不得在设备上下文中选择 由 hbmp 参数标识的位图。

自下而上 DIB 的原点是位图的左下角;自上而下 DIB 的原点为左上角。

示例

有关示例，请参阅 捕获图像。

要求

   
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 wingdi.h (包括 Windows.h)
Library Gdi32.lib
DLL Gdi32.dll

另请参阅

BITMAPCOREHEADER

BITMAPINFO

BITMAPINFOHEADER

位图函数

位图概述

SetDIBits