setDIBitsToDevice 函数 (wingdi.h)

项目
03/09/2024

SetDIBitsToDevice 函数使用 DIB、JPEG 或 PNG 图像中的颜色数据设置设备上与目标设备上下文关联的指定矩形中的像素。

语法

int SetDIBitsToDevice(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] DWORD            w,
  [in] DWORD            h,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] UINT             StartScan,
  [in] UINT             cLines,
  [in] const VOID       *lpvBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             ColorUse
);

参数

[in] hdc

设备上下文的句柄。

[in] xDest

目标矩形左上角的 x 坐标（以逻辑单元为单位）。

[in] yDest

目标矩形左上角的 y 坐标（以逻辑单元为单位）。

[in] w

图像的宽度（以逻辑单位为单位）。

[in] h

图像的高度（以逻辑单位为单位）。

[in] xSrc

图像左下角的 x 坐标（以逻辑单位表示）。

[in] ySrc

图像左下角的 y 坐标（以逻辑单位表示）。

[in] StartScan

映像中的起始扫描行。

[in] cLines

lpvBits 参数指向的数组中包含的 DIB 扫描行数。

[in] lpvBits

指向存储为字节数组的颜色数据的指针。有关更多信息，请参见下面的“备注”部分。

[in] lpbmi

指向包含 DIB 相关信息的 BITMAPINFO 结构的指针。

[in] ColorUse

指示 BITMAPINFO 结构的 bmiColors 成员是否包含显式的红色、绿色、蓝色 (RGB) 值或调色板中的索引。有关更多信息，请参见下面的“备注”部分。

fuColorUse 参数必须是下列值之一。

值	含义
DIB_PAL_COLORS	颜色表由当前所选逻辑调色板中的 16 位索引数组组成。
DIB_RGB_COLORS	颜色表包含文字 RGB 值。

返回值

如果函数成功，则返回值为设置的扫描行数。

如果 (设置零个扫描行，例如 当 dwHeight 为 0) 或函数失败时，该函数将返回零。

如果驱动程序不支持传递给 SetDIBitsToDevice 的 JPEG 或 PNG 文件映像，则函数将失败并返回GDI_ERROR。如果失败，应用程序必须回退到自己的 JPEG 或 PNG 支持上，才能将图像解压缩为位图，然后将位图传递给 SetDIBitsToDevice。

注解

当位图位成为系统调色板中的索引时，可获得最佳位图绘制速度。

应用程序可以通过调用 GetSystemPaletteEntries 函数来检索系统调色板颜色和索引。检索颜色和索引后，应用程序可以创建 DIB。有关系统调色板的详细信息，请参阅颜色。

扫描行必须在 DWORD 上对齐，RLE 压缩位图除外。

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

为了减少在设备图面上从大型 DIB 设置位所需的内存量，应用程序可以通过重复调用 SetDIBitsToDevice 来对输出进行带区，每次将位图的不同部分放入 lpvBits 数组。 uStartScan 和 cScanLines 参数的值标识 lpvBits 数组中包含的位图部分。

如果当全屏 MS-DOS 会话在前台运行时，在后台运行的进程调用 SetDIBitsToDevice 函数将返回错误。

如果 BITMAPINFOHEADER 的 biCompression 成员BI_JPEG或BI_PNG，则 lpvBits 指向包含 JPEG 或 PNG 图像的缓冲区。的 biSizeImage 成员指定缓冲区的大小。 fuColorUse 参数必须设置为 DIB_RGB_COLORS。
若要确保在打印时正确执行图元文件假脱机，应用程序必须在调用 SetDIBitsToDevice 之前调用 CHECKJPEGFORMAT 或 CHECKPNGFORMAT 转义以验证打印机是否分别识别 JPEG 或 PNG 图像。

Icm： 如果已通过调用 SetICMMode 启用了颜色管理，且 iEnableICM 参数设置为 ICM_ON，则执行颜色管理。如果 lpbmi 指定的位图具有指定 gamma 和 endpoints 成员的BITMAPV4HEADER ，或指定 gamma 和 endpoints 成员或 profileData 和 profileSize 成员的 BITMAPV5HEADER ，则调用会将位图的像素视为在这些成员描述的颜色空间中表示，而不是在设备上下文的源颜色空间中表示。

示例

有关示例，请参阅测试 JPEG 或 PNG 支持的打印机。

要求

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