Metodo IXpsRasterizer::RasterizeRect (xpsrassvc.h)

Articolo
08/08/2023

Il metodo RasterizeRect rasterizza un'area rettangolare allineata all'asse di una pagina fissa XPS.

Sintassi

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

Parametri

[in] x

Coordinata x, in pixel, sul bordo sinistro della bitmap di output.

[in] y

Coordinata y, in pixel, nel bordo superiore della bitmap di output.

[in] width

Larghezza, in pixel, della bitmap di output.

[in] height

Altezza, in pixel, della bitmap di output.

[in, optional] notificationCallback

Puntatore all'interfaccia IXpsRasterizerNotificationCallback di un oggetto notifica implementato dal chiamante. Questo parametro è facoltativo e può essere NULL se il chiamante non richiede callback di notifica.

[out, optional] bitmap

Puntatore a una posizione in cui il metodo scrive un puntatore nell'interfaccia IWICBitmap dell'oggetto bitmap appena creato. Se il metodo ha esito negativo, scrive NULL in questo percorso e restituisce un codice di errore.

Valore restituito

RasterizeRect restituisce S_OK se la chiamata ha avuto esito positivo. In caso contrario, il metodo restituisce un codice di errore. I valori restituiti di errore possibili includono:

Codice restituito	Descrizione
E_POINTER	La bitmap dei parametri è NULL.
E_INVALIDARG	La larghezza o l'altezza del parametro è minore o uguale a 0.

Commenti

Questo metodo è supportato in Windows 7 e versioni successive. Non è supportato nelle versioni del sistema operativo Windows precedenti a Windows 7.

In caso di esito positivo, questo metodo crea un oggetto bitmap wic (Windows Imaging Component) e passa al chiamante un riferimento contato all'interfaccia IWICBitmap dell'oggetto. Quando l'oggetto non è più necessario, il chiamante è responsabile del rilascio dell'oggetto chiamando il metodo Release sull'interfaccia IWICBitmap dell'oggetto.

La bitmap WIC creata da questo metodo ha un formato pixel a 32 bit che contiene canali rosso, verde e blu a 8 bit e usa lo spazio dei colori RGB (sRGB) standard. Inoltre, il formato contiene un componente alfa a 8 bit. I componenti di colore in ogni valore pixel vengono pre-moltiplicati per il componente alfa. Il formato pixel viene specificato dal valore GUID GUID_WICPixelFormat32bppPBGRA, definito nel file di intestazione Wincodec.h. Per altre informazioni su questo formato, vedere Cenni preliminari sui formati pixel nativi.

Il parametro DPI del metodo IXpsRasterizationFactory::CreateRasterizer specifica la risoluzione, espressa in punti per pollice, in cui deve essere eseguito il rendering della bitmap. Come descritto nella specifica XPS, la larghezza e l'altezza di una pagina fissa in un documento XPS sono specificate in unità da 1/96 pollici. Per determinare le dimensioni (in pixel) della bitmap necessaria per rappresentare l'intera pagina fissa, moltiplicare la larghezza e l'altezza per DPI/96.

Per supportare le stampanti che richiedono la rasterizzazione di una pagina fissa come serie di bande orizzontali o verticali, parametri x, y, larghezza e altezza specificano un'area rettangolare della pagina fissa che deve essere rasterizzata. Tutti e quattro i valori dei parametri vengono specificati in pixel. I parametri x e y sono le coordinate dell'angolo superiore sinistro dell'area rettangolare; vengono specificati come spostamenti in pixel dall'origine della coordinata (0, 0). La larghezza e l'altezza dei parametri sono le dimensioni dell'area rettangolare.

Ad esempio, se wXPS e hXPS sono la larghezza e l'altezza di una pagina fissa XPS in unità di misura da 1/96 pollici, RasterizeRect genera una rappresentazione bitmap della metà inferiore della pagina fissa se i parametri x, y, larghezza e altezza vengono impostati sui valori seguenti:

xyhlarghezzaDPIw DPI heighthDPI

Se il parametro notificationCallback è diverso da NULL, il metodo RasterizeRect accetta un riferimento conteggiato all'interfaccia IXpsRasterizerNotificationCallback dell'oggetto di notifica. A tale scopo, chiamare il metodo AddRef sull'interfaccia prima di effettuare qualsiasi chiamata al metodo IXpsRasterizerNotificationCallback::Continue . Prima che RasterizeRect restituisca, rilascia l'oggetto notifica chiamando il metodo Release nell'interfaccia *IXpsRasterizerNotificationCallback .

Come illustrato nella specifica XPS, l'attributo BleedBox facoltativo può specificare una casella smarginata che si estende all'esterno dei limiti di una pagina fissa. Per contenere caselle smarginate, il rettangolo definito dai parametri x, y, larghezza e altezza può anche estendersi oltre i limiti della pagina fissa. Il metodo accetta valori, positivi o negativi, per x e y e accetta tutti i valori positivi e diversi da zero per larghezza e altezza. Il rettangolo specificato da questi parametri definisce l'area di ritaglio per l'operazione di rasterizzazione. Se il rettangolo si estende oltre i limiti della pagina fissa, l'area di ritaglio si estende anche oltre questi limiti.

Se il metodo ha esito negativo e bitmap non è NULL, il metodo imposta *bitmap = NULL.

Per un esempio di codice che chiama il metodo RasterizeRect , vedere l'esempio XPSRasFilter in WDK. Questo esempio si trova nella cartella Src\Print\Xpsrasfilter nell'installazione di WDK.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive del sistema operativo Windows.
Piattaforma di destinazione	Desktop
Intestazione	xpsrassvc.h