How to retrieve and change Direct2D print settings (DirectX)

Article
02/11/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Here's how to get and set Direct2D print settings in your Windows Store apps using C++ and DirectX.

Your app specifies what print options are available to the user—at load time and at print time— by using the PrintTaskOptions class, as shown in How to change standard options in the print preview UI. PrintTaskOptions specifies the user’s choices when it renders content for preview and for printing, as shown in How to format content for printing.

In addition, your app also has direct access to three properties of the print job when creating the Direct2D print control using ID2D1Device.CreatePrintControl. You set these properties by using the D2D1_PRINT_CONTROL_PROPERTIES structure to affect how the Direct2D print control handles certain Direct2D commands. Here are those three properties.

Property	Description
D2D1_PRINT_CONTROL_PROPERTIES.fontSubset	Sets the font subset mode for the Direct2D print control. Font subsetting is a technique the app can use to embed in a document only a subset of the characters in the font, reducing the size of the files sent to the printer and speeding up print time. Can be one of the D2D1_PRINT_FONT_SUBSET_MODE enumeration values.
D2D1_PRINT_CONTROL_PROPERTIES.rasterDpi	Sets the rasterization resolution (in dpi) for the Direct2D print control. When the Direct2D print control needs to rasterize Direct2D commands during Direct2D-to-XPS conversion, it uses this resolution for the rasterization. Can be one of the following: 150 The default value if no value is specified. This balances printing quality and printing performance best in most cases. Above 150 Higher dpi values mean better printing quality but lower performance. A dpi value greater than 300 is not recommended because it will not increase printing quality on paper in a visually noticeable way. Below 150 Lower dpi values mean better performance but lower quality.
D2D1_PRINT_CONTROL_PROPERTIES.colorSpace	Sets the color space for the Direct2D print control. Color space affects the Direct2D print control in drawing simple geometries with solid color brushes and in drawing Direct2D bitmaps. D2D1_COLOR_SPACE_SRGB The default value if no value is specified. D2D1_COLOR_SPACE_SCRGB Choose this option to specify a larger color gamut. Note The Direct2D print control does not support the D2D1_COLOR_SPACE_CUSTOM value. Using it causes creation of the Direct2D print control to fail.

What you need to know

Technologies

Prerequisites

You must:

Be familiar with C++, Direct2D APIs, Windows events, and event handling.
Have Microsoft Visual Studio installed.
Have a printer installed (or use the Microsoft XPS Document Writer).
Have an app in which you want to change print settings. If you don't have your own app, you can download the Direct2D printing for Windows Store apps sample and use that. Note You can find all of the code examples mentioned here in the Direct2D printing for Windows Store apps sample.

Instructions

Step 1: Open your app's source code for editing

This step shows you how to open the Direct2D printing for Windows Store apps sample. If you are using your own app, just open hat in Visual Studio and skip to the next step.

Note The code examples shown in this tutorial refer to the Direct2D printing for Windows Store apps sample. You might need to add more code from the sample app to use these examples in your own app.

Go to the Direct2D printing for Windows Store apps sample and download the C++ example to your computer.
In Visual Studio, click File > Open Project and go to the folder that contains the solution file of the sample app that you just downloaded.
Select the D2DPrinting solution file and click Open.

Step 2: Build and test the app

Click Build > Build Solution to build the app you are working on. Make sure that there are no error messages in the Output pane at the bottom of the screen.
Click Debug > Start Without Debugging.
Verify that, after a few seconds, the D2DPrinting app starts.
If the app runs without error, return to Visual Studio and click Debug > Stop Debugging.

Step 3: Set available printing options

Set the print options by using the PrintTaskOptions class. To do this, follow the steps from How to change standard options in the print preview UI. Here the app tells Windows what printing options are available to the user based on the printer that the user chose.

Step 4: Get print settings

If you have not already done so, create a method called CDocumentSource::MakeDocument. In that method, create a PrintTaskOptions object and a PrintPageDescription object to get the print settings. This example uses the PrintTaskOptions to get print settings and the PrintPageDescription object to get the description of the first page.

IFACEMETHODIMP
CDocumentSource::MakeDocument(
    _In_ IInspectable*                docOptions,
    _In_ IPrintDocumentPackageTarget* docPackageTarget
    )
{
        // ...
        // Get print settings from PrintTaskOptions for printing, such as page description, which contains page size, printable area, DPI.
        PrintTaskOptions^ option = reinterpret_cast<PrintTaskOptions^>(docOptions);
        PrintPageDescription pageDesc = option->GetPageDescription(1); 

        // ...

}

Create a D2D1_PRINT_CONTROL_PROPERTIES structure and set the print-control properties using the settings from PrintPageDescription. In this example, rasterDPI is set for all unsupported Direct2D commands or options, and colorSpace is set for vector graphics. The fontSubset property is a subset for the glyphs that are actually used for printing; the example sends and discards font resources after every five pages.





    D2D1_PRINT_CONTROL_PROPERTIES printControlProperties;

    // DPI for rasterization of all unsupported D2D commands or options    
    printControlProperties.rasterDPI  = 
        (float)(min(pageDesc.DpiX, pageDesc.DpiY)); 

    // Color space for vector graphics in D2D print control.
    printControlProperties.colorSpace = D2D1_COLOR_SPACE_SRGB;                  

    // Subset for used glyphs, send and discard font resource after every five pages.
    printControlProperties.fontSubset = D2D1_PRINT_FONT_SUBSET_MODE_DEFAULT;

Finally, close the print control even if the AddPage() method from within PrintPage() fails, like this.
```
       HRESULT hrClose = m_renderer->ClosePrintControl();
```