IXpsRasterizer：：RasterizeRect 方法（xpsrassvc.h）

项目
02/07/2025

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作系统版本不支持它。

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

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

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

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

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

xyhDPI宽度DPI高度hDPI

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

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

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

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