Description

  This document describes the contents and use of the XPS Rasterization Service Filter sample included in the Windows 7 WDK. This document will serve as a point-of-reference to gather and draft the information required for the MSDN entries to accompany the sample prior to flowing this text and information into the appropriate MSDN format.

Theory of Operation

  This sample implements an XPSDrv filter that rasterizes fixed pages in an XPS document. Hardware vendors can modify this sample to build an XPSDrv filter that produces bitmap images for their printers or other display devices. The sample uses the XPS Rasterization Service in Windows 7. The sample does not run in versions of Windows before Windows 7.

The XPS Rasterization Service creates rasterizer objects for use by XPSDrv filters. A rasterizer object takes an XPS Object Model (XPS OM) page object and creates a bitmap of a specified region of the page. The sample implements an XPSDrv filter (xpsrasfilter.dll) that can be inserted into the XPS Filter Pipeline. For each fixed page in an XPS document, the sample filter does the following:

• Uses the XPS rasterization service to create a rasterizer object for the fixed page.
• Partitions the fixed page into several horizontal bands.
• Uses the rasterizer object to render each horizontal band as a bitmap image.

Implementation and Design

  The Print Filter Pipeline is part of the XPS Print Path Windows Vista Print Path Overview. Fixed pages are sent as an XPS data stream from the XPS Spooler to the print filter pipeline. The print filter pipeline manager takes the XPS fixed page, calls each filter in the order defined in the pipeline configuration file, and then sends either Fixed Page OM objects or a data stream to each filter as required. The filters process the data and return either Fixed Page OM objects or a data stream back to the print filter pipeline manager. (See MSDN entry for Filter Pipeline Interfaces items IXpsDocumentProvider, IXpsDocumentConsumer, IPrintWriteStream, and IPrintReadStream.)

As a print filter pipeline service, the XPS Rasterization Service can be loaded into the filter pipeline when the pipeline is initialized by adding a filter service provider tag to the configuration XML file (for example, <FilterServiceProvider dll="XpsRasterService.dll"/>). The service is then available to be called by the filters when they are initialized and called by the print filter pipeline manager.

The XPS Rasterization Service operates as follows:

• The calling filter initializes an instance of the rasterizer by passing in the XPS OM for the fixed page.
• The calling filter calls the RasterizeRect method of the rasterizer to render a specified rectangle area of the fixed page.
• RasterizeRect writes the WIC (Windows Imaging Component) bitmap data to memory. (The address is specified as a parameter to RasterizeRect.)

The default parameters in this sample are as follows:

• Letter-sized physical page (can override in print ticket).
• 0.25-inch margins (creating an 8-inch by 10.5-inch imageable area).
• Scaling is set to FitApplicationBleedSizeToImageableSize.
• Destination resolution set to 96 dpi (can override in print ticket).

The maximum memory size for rasterized bands in the sample is set to 64 megabytes. This can be changed by editing \src\rasinterface.h and changing the following line of code:

const static LONG ms_targetBandSize = 1024 * 1024 * 64;

Recompile the DLL and reload the printer driver (if already installed) to implement the change.

The sample filter demonstrates a minimum implementation of a print pipeline filter that uses the XPS Rasterization Service. This filter performs the following tasks:

• Converts the passed in IFixedPage object into an IXpsOMPage.
• Calls XPS Rasterization Service to create rasterized bands (WIC bitmaps).
• Uses WIC to encode each band as an individual TIFF.
• Returns each TIFF as a data stream to the Print Filter Manager, which in turn sends it to the designated port.

For use outside of this sample, we strongly recommend that users work directly with the WIC bitmaps returned from the XPS Rasterization Service. The calls into WIC to encode each band as a TIFF are provided solely for demonstration purposes and do not represent a recommended use. Furthermore, using the sample as-is in a larger application, and trying to work with the stream of concatenated per-band TIFFs, would be inefficient and unnecessarily difficult.

For maximum flexibility and reuse, each filter in a printer driver should perform a specific print processing function. For example, a filter might perform color conversion, while another might apply a watermark. For an example of an XPSDrv driver that uses multiple pipeline filters, refer to the XPS Driver Sample (XPSDrvSmpl) in the WDK. In particular, compare the pipeline configuration XML files, xdsmpl-PipelineConfig.xml and xpsrassmpl-PipelineConfig.xml, for the two samples. Notice that the configuration file for the XPS Rasterization Service sample requires the <FilterServiceProvider…/> tag.

Software Requirements

The sample runs on the following Windows operating systems:

• Windows 7
• Windows Vista SP2 with Platform Update for Windows Vista (KB 971644)

Note  If you want to use this sample with Windows Vista SP2 Platform Update, follow these steps:

1. Build the sample using Windows 7 as the target operating system.
2. Make the following edits in the Xpsrassmpl.inf file:
   • Change the Manufacturer section to read:

     [Manufacturer]%Microsoft%=Microsoft,NTx86.6.1,NTia64.6.1,NTamd64.6.1,NTx86.6.0,NTia64.6.0,NTamd64.6.0
     

   • Add the following sections after the Manufacturer section:

     [Microsoft.NTx86.6.0]
     "XPSRas WDK Sample Driver" = INSTALL_FILTER
     [Microsoft.NTia64.6.0]
     "XPSRas WDK Sample Driver" = INSTALL_FILTER
     [Microsoft.NTamd64.6.0]
     "XPSRas WDK Sample Driver" = INSTALL_FILTER
     

3. Install the driver on Windows Vista SP2 with Platform Update.

Processor Requirements

The sample runs on the following processor architectures:

• x86
• x64
• IA64

Installation

  After downloading the WDK Windows Hardware Developer Central, follow these steps:

1. Run KitSetup.exe.
2. Select the components to install:
   Minimum configuration recommendation: Select Build Environments and Samples.
3. Click “apply” to install to the designated directory.
4. After setup is completed, go to Start/All Programs/Windows Driver Kit/[installed WDK build]/Build Environments/[target OS]/ and select the appropriate “Open a build window…” item for the desired binary.
5. A command window will appear that points to the root installation directory. Change to directory src\print\XpsRasFilter.
6. Type “build” and hit enter to build the sample filter (xpsrasfilter.dll). The compiled filter will be found in src\print\XpsRasFilter\install\[Targeted architecture]\.
7. After verifying the filter was built successfully, open the printer control panel.
8. Click on “Add a printer”.
9. Add a local printer with the port set to “FILE”. In the “Install the printer driver” dialog, click the “Have Disk…” button and browse to src\print\\XpsRasFilter\install\xpsrassmpl.inf. “XPSRas WDK Sample Driver” will appear in the printers list. Select this driver and finish the installation.
10. NOTE: When the output files print to this driver, they are made up of a series of per-band TIFFs instead of a flavor of PDL. Because the file contains a series of complete TIFFs and not a single, multi-page TIFF, opening the file in an image viewer will only display the first band of the first page. More details can be found in the file bitmaphandler.cpp included with the sample’s source code.

Code Tour

File Manifest

Files in src\print\\XpsRasFilter\src directory:

Files in src\print\\XpsRasFilter\install directory:

Related Samples

Print Pipeline Simple Filter