stretchDIBits 函数 (wingdi.h)

  • 项目

StretchDIBits 函数将 DIB、JPEG 或 PNG 图像中像素矩形的颜色数据复制到指定的目标矩形。 如果目标矩形大于源矩形，此函数将拉伸颜色数据的行和列以适应目标矩形。 如果目标矩形小于源矩形，则此函数使用指定的光栅操作压缩行和列。

语法

int StretchDIBits(
  [in] HDC              hdc,
  [in] int              xDest,
  [in] int              yDest,
  [in] int              DestWidth,
  [in] int              DestHeight,
  [in] int              xSrc,
  [in] int              ySrc,
  [in] int              SrcWidth,
  [in] int              SrcHeight,
  [in] const VOID       *lpBits,
  [in] const BITMAPINFO *lpbmi,
  [in] UINT             iUsage,
  [in] DWORD            rop
);

参数

[in] hdc

目标设备上下文的句柄。

[in] xDest

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

[in] yDest

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

[in] DestWidth

目标矩形的宽度（以逻辑单元表示）。

[in] DestHeight

目标矩形的高度（以逻辑单元表示）。

[in] xSrc

图像中源矩形的 x 坐标（以像素为单位）。

[in] ySrc

图像中源矩形的 y 坐标（以像素为单位）。

[in] SrcWidth

图像中源矩形的宽度（以像素为单位）。

[in] SrcHeight

图像中源矩形的高度（以像素为单位）。

[in] lpBits

指向图像位的指针，这些图像位存储为字节数组。 有关详细信息，请参见“备注”部分。

[in] lpbmi

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

[in] iUsage

指定是否提供了 BITMAPINFO 结构的 bmiColors 成员，如果是，则指定 bmiColors 是否包含显式的红色、绿色、蓝色 (RGB) 值或索引。 iUsage 参数必须是以下值之一。

值 含义
DIB_PAL_COLORS
 数组包含源设备上下文逻辑调色板中的 16 位索引。
DIB_RGB_COLORS
 颜色表包含文字 RGB 值。
 

有关详细信息，请参见“备注”部分。

[in] rop

光栅操作代码，指定如何组合源像素、目标设备上下文的当前画笔和目标像素以形成新图像。 有关一些常见光栅操作代码的列表，请参阅 BitBlt。

返回值

如果函数成功，则返回值为复制的扫描行数。 请注意，对于镜像内容，此值可以为负值。

如果函数失败，或未复制扫描行，则返回值为 0。

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

注解

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

如果 nSrcWidth 和 nDestWidth 参数的符号，或者 nSrcHeight 和 nDestHeight 参数不同，StretchDIBits 将创建位图的镜像图像。 如果 nSrcWidth 和 nDestWidth 具有不同的符号，该函数将沿 x 轴创建位图的镜像图像。 如果 nSrcHeight 和 nDestHeight 具有不同的符号，该函数将沿 y 轴创建位图的镜像图像。

如果 DIB 的 BITMAPINFOHEADER 结构的 biHeight 成员的符号为负数，StretchDIBits 将创建一个自上而下的图像。 有关代码示例，请参阅 调整 JPEG 或 PNG 图像的大小。

此函数允许将 JPEG 或 PNG 图像作为源图像传递。 每个参数的使用方式保持不变，但以下情况除外：

  • 如果 BITMAPINFOHEADER 的双压缩成员BI_JPEG或BI_PNG，则 lpBits 分别指向包含 JPEG 或 PNG 图像的缓冲区。 BITMAPINFOHEADER 结构的 biSizeImage 成员指定缓冲区的大小。 iUsage 参数必须设置为 DIB_RGB_COLORS。 dwRop 参数必须设置为 SRCCOPY。
  • 为了确保在打印时图元文件后台打印正确，应用程序必须在调用 StretchDIBits 之前调用 CHECKJPEGFORMAT 或 CHECKPNGFORMAT 转义，以验证打印机是否分别识别 JPEG 或 PNG 图像。
Icm： 如果已通过调用 SetICMMode 启用了颜色管理，且 iEnableICM 参数设置为 ICM_ON，则执行颜色管理。 如果 lpBitsInfo 指定的位图具有指定 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

另请参阅

BITMAPINFO

位图函数

位图概述

SetMapMode

SetStretchBltMode