IXpsRasterizer：：RasterizeRect 方法 (xpsrassvc.h)

發行項
02/27/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。否則，方法會傳回錯誤碼。可能的錯誤傳回值包括：

傳回碼	Description
E_POINTER	參數位圖為 NULL。
E_INVALIDARG	參數寬度或高度小於或等於 0。

備註

Windows 7 和更新版本支援此方法。 Windows 7 之前的 Windows 作業系統版本不支援它。

如果成功，這個方法會在 WIC) 位圖物件 (建立 Windows 映射元件，並將計數參考傳遞給呼叫端的 IWICBitmap 介面。不再需要物件時，呼叫端會負責在物件的 IWICBitmap 介面上呼叫 Release 方法來釋放物件。

此方法建立的 WIC 位圖具有 32 位像素格式，其中包含 8 位紅色、綠色和藍色通道，並使用標準 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 是 1/96 英吋單位之 XPS 固定頁面的寬度和高度， RasterizeRect 會在參數 x、 y、 width 和 height 設定為下列值時，產生固定頁面下半部的位圖表示：

xyhDPI寬度wDPI高度hDPI

如果 notificationCallback 參數不是 NULL，RasterizeRect 方法會採用通知物件的 IXpsRasterizerNotificationCallback 介面的計數參考。其做法是先在介面上呼叫 AddRef 方法，再對 IXpsRasterizerNotificationCallback：：Continue 方法進行任何呼叫。在 RasterizeRect 傳回之前，它會在 *IXpsRasterizerNotificationCallback 介面上呼叫 Release 方法，以釋放通知物件。

如 XPS 規格中所述，選擇性 的 BleedBox 屬性可以指定延伸至固定頁面界限之外的移轉方塊。為了容納擷取的方塊，參數 x、 y、 width 和 height 所定義的矩形也可以延伸到固定頁面的界限之外。方法接受 x 和 y 的任何值、正值或負值，並且接受寬度和高度的任何正數、非零值。這些參數所指定的矩形會定義點陣化作業的裁剪區域。如果矩形超出固定頁面的界限，裁剪區域也會延伸超過這些界限。

如果方法失敗，且 點陣圖 為非 NULL，則方法會設定 *位圖 = NULL。

如需呼叫 RasterizeRect 方法的程式代碼範例，請參閱 WDK 中的 XPSRasFilter 範例。此範例位於 WDK 安裝的 Src\Print\Xpsrasfilter 資料夾中。