IXpsRasterizer：：RasterizeRect 方法 (xpsrasvc.h)

项目
03/05/2024

RasterizeRect 方法光栅化 XPS 固定页的轴对齐矩形区域。

语法

HRESULT RasterizeRect(
  [in]            INT                                x,
  [in]            INT                                y,
  [in]            INT                                width,
  [in]            INT                                height,
  [in, optional]  IXpsRasterizerNotificationCallback *notificationCallback,
  [out, optional] IWICBitmap                         **bitmap
);

参数

[in] x

输出位图左边缘的 x 坐标（以像素为单位）。

[in] y

输出位图上边缘的 y 坐标（以像素为单位）。

[in] width

输出位图的宽度（以像素为单位）。

[in] height

输出位图的高度（以像素为单位）。

[in, optional] notificationCallback

指向调用方实现的通知对象的 IXpsRasterizerNotificationCallback 接口的指针。此参数是可选的，如果调用方不需要通知回调，则可以为 NULL 。

[out, optional] bitmap

指向方法将指针写入到新创建的位图对象的 IWICBitmap 接口的位置的指针。如果方法失败，它会将 NULL 写入此位置并返回错误代码。

返回值

如果调用成功，RasterizeRect 将返回S_OK。否则，该方法将返回错误代码。可能的错误返回值包括：

返回代码	说明
E_POINTER	参数位图为 NULL。
E_INVALIDARG	参数宽度或高度小于或等于 0。

注解

Windows 7 及更高版本支持此方法。在 Windows 7 之前的 Windows 操作系统版本中不支持它。

如果成功，此方法 (WIC) 位图对象创建 Windows 图像处理组件，并将对对象的 IWICBitmap 接口的计数引用传递给调用方。当不再需要对象时，调用方负责通过在对象的 IWICBitmap 接口上调用 Release 方法来释放对象。

此方法创建的 WIC 位图具有包含 8 位红色、绿色和蓝色通道的 32 位像素格式，并使用标准 RGB (sRGB) 颜色空间。此外，格式包含 8 位 alpha 分量。每个像素值中的颜色分量都预先乘以 alpha 分量。像素格式由 GUID 值 GUID_WICPixelFormat32bppPBGRA指定，该值在头文件 Wincodec.h 中定义。有关此格式的详细信息，请参阅本机像素格式概述。

IXpsRasterizationFactory：：CreateRasterizer 方法的 DPI 参数指定要呈现位图的分辨率（以每英寸点为单位）。如 XPS 规范中所述，XPS 文档中固定页面的宽度和高度以 1/96 英寸为单位指定。若要确定表示整个固定页面所需的位图的尺寸 (像素) ，请将宽度和高度乘以 DPI/96。

若要容纳需要将固定页面光栅化为一系列水平或垂直带的打印机，参数 x、 y、宽度和高度指定要光栅化的固定页的矩形区域。所有四个参数值均以像素为单位指定。参数 x 和 y 是矩形区域左上角的坐标;它们指定为坐标原点 (0， 0) 的像素位移。参数宽度和高度是矩形区域的尺寸。

例如，如果 wXPS 和 hXPS 是 XPS 固定页的宽度和高度（以 1/96 英寸为单位），则如果参数 x、y、width 和 height 设置为以下值，则 RasterizeRect 将生成固定页下半部分的位图表示形式：

xyhDPI宽度， dpi高度hDPI

如果 notificationCallback 参数为非 NULL， 则 RasterizeRect 方法接受对通知对象的 IXpsRasterizerNotificationCallback 接口的计数引用。它通过在调用 IXpsRasterizerNotificationCallback：：Continue 方法之前对接口调用 AddRef 方法来执行此操作。 在 RasterizeRect 返回之前，它会通过在 *IXpsRasterizerNotificationCallback 接口上调用 Release 方法释放通知对象。

如 XPS 规范中所述，可选的 BleedBox 属性可以指定在固定页面边界之外扩展的出血框。为了容纳出血框，由 x、y、width 和 height 参数定义的矩形也可以超出固定页的边界。方法接受 x 和 y 的任何值（正值或负值），并接受宽度和高度的任何正值、非零值。这些参数指定的矩形定义光栅化操作的剪裁区域。如果矩形超出固定页的边界，剪裁区域也会超出这些边界。

如果方法失败且位图为非 NULL，则该方法将设置位图 = NULL。

有关调用 RasterizeRect 方法的代码示例，请参阅 WDK 中的 XPSRasFilter 示例。此示例位于 WDK 安装的 Src\Print\Xpsrasfilter 文件夹中。