IXpsOMObjectFactory：：CreateImageBrush 方法 (xpsobjectmodel.h)

發行項
03/05/2024

語法

HRESULT CreateImageBrush(
  [in]          IXpsOMImageResource *image,
  [in]          const XPS_RECT      *viewBox,
  [in]          const XPS_RECT      *viewPort,
  [out, retval] IXpsOMImageBrush    **imageBrush
);

參數

[in] image

IXpsOMImageResource 介面，其中包含要當做筆刷來源影像使用的影像。

[in] viewBox

定義檢視框的XPS_RECT結構，這是筆刷所使用的來源影像區域。

[in] viewPort

定義檢視區XPS_RECT結構，這是輸出區域中第一個圖格所涵蓋的區域。

[out, retval] imageBrush

新 IXpsOMImageBrush 介面的指標。

傳回值

方法會傳回 HRESULT。可能的值包括下列數據表中的值，但不限於這些值。如需此表格中未列出的 XPS 檔 API 傳回值的相關信息，請參閱 XPS 檔錯誤。

傳回碼	描述
S_OK	此方法已成功。
E_POINTER	image、 viewBox、 viewPort 或 imageBrush 為 NULL。
E_INVALIDARG	viewBox 或 viewPort 包含無效的矩形或值。

備註

筆刷的檢視方塊會指定要做為磚影像的來源影像或視覺效果部分。

筆刷檢視框的座標相對於來源內容，因此 (0,0) 指定來源內容的左上角。對於影像，筆刷檢視方塊所指定的維度是以 1/96“ 的單位表示。來源影像中的對應圖元座標會計算如下：

在下圖中，左側的影像是來源影像的範例，而最右邊的筆刷則是選取檢視框之後的結果筆刷。

如果來源影像解析度是每英吋 96 到 96 點，而影像維度為 96 x 96 像素， 則 viewbox 參數中的欄位值如下所示：

上述參數值會對應至來源影像，如下所示：

SourceLeft = (96 × 48) / 96 = 左側 48 像素

SourceTop = (96 × 24) / 96 = 頂端 24 像素

SourceWidth = (96 × 24) / 96 = 24 像素寬

SourceHeight = (96 × 48) / 96 = 48 像素高

影像筆刷是一個磚筆刷，會擷取影像或其中一部分，轉換影像以建立磚、將產生的磚放在檢視區 (圖格的目的地幾何) ，並填入圖格模式所述的輸出區域。

檢視區是輸出區域中第一個圖格所涵蓋的區域。檢視區影像會在輸出區域中重複，如磚模式所述。

下圖顯示影像筆刷如何用來填滿輸出區域。從左至右，原始影像會轉換成填滿檢視區，然後將它放在輸出區域的檢視區區域中，然後並排以填滿輸出區域。

下列程式代碼範例說明如何使用這個方法來建立新的介面。


IXpsOMImageBrush            *newInterface;
// The following values are defined outside of 
// this example.
//  IXpsOMImageResource     *image;
//  XPS_RECT                viewBox;
//  XPS_RECT                viewPort;

// Note the implicit requirement that CoInitializeEx 
//  has previously been called from this thread.

hr = CoCreateInstance(
    __uuidof(XpsOMObjectFactory),
    NULL,
    CLSCTX_INPROC_SERVER,
    _uuidof(IXpsOMObjectFactory),
    reinterpret_cast<LPVOID*>(&xpsFactory)
    );

if (SUCCEEDED(hr))
{
    hr = xpsFactory->CreateImageBrush (
        image,
        &viewBox,
        &viewPort,
        &newInterface);

    if (SUCCEEDED(hr))
    {
        // use newInterface

        newInterface->Release();
    }
    xpsFactory->Release();
}
else
{
    // evaluate HRESULT error returned in hr
}

規格需求

需求	值
最低支援的用戶端	適用於 Windows Vista 的 Windows 7、Windows Vista SP2 和平臺更新 [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 R2、Windows Server 2008 SP2 和 Platform Update for Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	xpsobjectmodel.h