IXpsRasterizer::RasterizeRect-Methode (xpsrassvc.h)

Artikel
02/27/2024

Die RasterizeRect-Methode rastert einen achsenorientierten, rechteckigen Bereich einer festen XPS-Seite.

Syntax

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

Parameter

[in] x

Die x-Koordinate in Pixel am linken Rand der Ausgabebittebit.

[in] y

Die y-Koordinate in Pixel am oberen Rand der Ausgabe-Bitmap.

[in] width

Die Breite der Ausgabebitbitbit in Pixel.

[in] height

Die Höhe der Ausgabe-Bitmap in Pixel.

[in, optional] notificationCallback

Zeiger auf die IXpsRasterizerNotificationCallback-Schnittstelle eines Benachrichtigungsobjekts, das vom Aufrufer implementiert wird. Dieser Parameter ist optional und kann NULL sein, wenn der Aufrufer keine Benachrichtigungsrückrufe erfordert.

[out, optional] bitmap

Zeiger auf eine Position, an der die Methode einen Zeiger auf die IWICBitmap-Schnittstelle des neu erstellten Bitmapobjekts schreibt. Wenn die Methode fehlschlägt, schreibt sie NULL an diesen Speicherort und gibt einen Fehlercode zurück.

Rückgabewert

RasterizeRect gibt S_OK zurück, wenn der Aufruf erfolgreich war. Andernfalls gibt die Methode einen Fehlercode zurück. Mögliche Fehlerrückgabewerte sind:

Rückgabecode	Beschreibung
E_POINTER	Die Bitmap des Parameters ist NULL.
E_INVALIDARG	Die Breite oder Höhe des Parameters ist kleiner oder gleich 0.

Hinweise

Diese Methode wird in Windows 7 und höher unterstützt. Es wird in Versionen des Windows-Betriebssystems vor Windows 7 nicht unterstützt.

Bei erfolgreicher Ausführung erstellt diese Methode ein WiC-Bitmapobjekt (Windows Imaging Component) und übergibt einen gezählten Verweis auf die IWICBitmap-Schnittstelle des Objekts an den Aufrufer. Wenn das Objekt nicht mehr benötigt wird, ist der Aufrufer für die Freigabe des Objekts verantwortlich, indem er die Release-Methode auf der IWICBitmap-Schnittstelle des Objekts aufruft .

Die mit dieser Methode erstellte WIC-Bitmap weist ein 32-Bit-Pixelformat auf, das rote, grüne und blaue 8-Bit-Kanäle enthält und den standardmäßigen RGB-Farbraum (sRGB) verwendet. Darüber hinaus enthält das Format eine 8-Bit-Alphakomponente. Die Farbkomponenten in jedem Pixelwert werden mit der Alphakomponente vorab multipliziert. Das Pixelformat wird durch den GUID-Wert GUID_WICPixelFormat32bppPBGRA angegeben, der in der Headerdatei Wincodec.h definiert ist. Weitere Informationen zu diesem Format finden Sie unter Übersicht über native Pixelformate.

Der DPI-Parameter der IXpsRasterizationFactory::CreateRasterizer-Methode gibt die Auflösung in Punkt pro Zoll an, mit der die Bitmap gerendert werden soll. Wie in der XPS-Spezifikation beschrieben, werden die Breite und Höhe einer festen Seite in einem XPS-Dokument in 1/96-Zoll-Einheiten angegeben. Um die Dimensionen (in Pixel) der Bitmap zu bestimmen, die für die Darstellung der gesamten festen Seite erforderlich ist, multiplizieren Sie die Breite und Höhe mit DPI/96.

Um Drucker unterzubringen, für die eine feste Seite als Eine Reihe horizontaler oder vertikaler Bänder gerastert werden muss, geben die Parameter x, y, Breite und Höhe einen rechteckigen Bereich der festen Seite an, die gerastert werden soll. Alle vier Parameterwerte werden in Pixel angegeben. Die Parameter x und y sind die Koordinaten der oberen linken Ecke des rechteckigen Bereichs. sie werden als Pixelverschiebungen vom Koordinatenursprung (0, 0) angegeben. Die Parameter Breite und Höhe sind die Dimensionen des rechteckigen Bereichs.

Wenn wXPS und hXPS beispielsweise die Breite und Höhe einer festen XPS-Seite in 1/96-Zoll-Einheiten sind, generiert RasterizeRect eine Bitmapdarstellung der unteren Hälfte der festen Seite, wenn die Parameter x, y, width und height auf die folgenden Werte festgelegt sind:

xyhDPIBreitewDPI-Höheh DPI

Wenn der notificationCallback-Parameter nicht NULL ist, nimmt die RasterizeRect-Methode einen gezählten Verweis auf die IXpsRasterizerNotificationCallback-Schnittstelle des Benachrichtigungsobjekts an. Dazu wird die AddRef-Methode auf der Schnittstelle aufgerufen, bevor die IXpsRasterizerNotificationCallback::Continue-Methode aufgerufen wird. Bevor RasterizeRect zurückgibt, gibt es das Benachrichtigungsobjekt durch Aufrufen der Release-Methode auf der *IXpsRasterizerNotificationCallback-Schnittstelle frei.

Wie in der XPS-Spezifikation erläutert, kann das optionale BleedBox-Attribut ein Beschnittfeld angeben, das sich über die Grenzen einer festen Seite hinaus erstreckt. Um Beschnittfelder aufzunehmen, kann das rechteck, das durch die Parameter x, y, width und height definiert wird, auch über die Grenzen der festen Seite hinaus reichen. Die -Methode akzeptiert alle positiven oder negativen Werte für x und y und akzeptiert alle positiven, nichtzero-Werte für Breite und Höhe. Das durch diese Parameter angegebene Rechteck definiert den Abschneidebereich für den Rastervorgang. Wenn das Rechteck über die Grenzen der festen Seite hinausgeht, erstreckt sich der Beschneidungsbereich auch über diese Grenzen hinaus.

Wenn die Methode fehlschlägt und die Bitmap nicht NULL ist, legt die Methode *bitmap = NULL fest.

Ein Codebeispiel, das die RasterizeRect-Methode aufruft, finden Sie im XPSRasFilter-Beispiel im WDK. Dieses Beispiel befindet sich im Ordner Src\Print\Xpsrasfilter in Ihrer WDK-Installation.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und höheren Versionen des Windows-Betriebssystems.
Zielplattform	Desktop
Kopfzeile	xpsrassvc.h