Handling Device-Managed Surfaces

Important

The modern print platform is Windows' preferred means of communicating with printers. We recommend that you use Microsoft's IPP inbox class driver, along with Print Support Apps (PSA), to customize the print experience in Windows 10 and 11 for printer device development.

For more information, see Modern print platform and the Print support app design guide.

When Unidrv renders print page images, it uses GDI-managed drawing surfaces. All images are rendered as bitmaps. For devices with capabilities that cannot be exploited by this scenario, such as the ability to draw vectors, you can provide customized driver support for a device-managed drawing surface. To support a device-managed surface, you must provide a rendering plug-in that implements the following:

• A set of hooking functions for all the Unidrv-supported graphics DDI drawing functions. The following functions must be hooked:

  DrvAlphaBlend DrvBitBlt DrvCopyBits DrvDitherColor DrvFillPath DrvGradientFill DrvLineTo DrvPlgBlt DrvRealizeBrush DrvStretchBlt DrvStretchBltROP DrvStrokeAndFillPath DrvStrokePath DrvTextOut DrvTransparentBlt

• The IPrintOemUni::EnableDriver method, which is used to provide Unidrv with pointers to the graphics DDI hooking functions.

• The IPrintOemUni::DriverDMS method, which informs Unidrv that a device-managed surface is to be used, and specifies which of the defined hooking functions will be used for the surface.

The hooking functions cannot call back to GDI's Eng-prefixed support services when drawing on a device-managed surface. However, they can create a temporary bitmap surface, and then pass that surface's handle to Eng-prefixed drawing functions (see Rendering a Print Job).

The IPrintOemUni::DriverDMS method is called each time a print job is about to be rendered, so the rendering plug-in can specify the type of rendering surface (GDI-managed or device-managed) for each job. Basing the surface choice on a selectable option in the user interface requires you to also provide a user interface plug-in.

Drawing Text on a Device-Managed Surface

The rendering plug-in must hook out Unidrv's DrvTextOut function (along with all other graphics DDI drawing functions). Creating text for a device-managed surface involves interaction among the following four functions:

• Unidrv's DrvTextOut function

• Rendering plug-in's DrvTextOut hooking function

• Unidrv's IPrintOemDriverUni::DrvUniTextOut method

• Rendering plug-in's IPrintOemUni::TextOutAsBitmap method

The steps involved in displaying text on a device-managed surface are as follows:

1. GDI calls Unidrv's DrvTextOut function.

2. Unidrv calls the rendering plug-in's DrvTextOut hooking function.

3. The hooking function sends commands to the device to specify the text's brush, rotation, and clip region.

4. The hooking function calls Unidrv's IPrintOemDriverUni::DrvUniTextOut method, which uses downloaded fonts to output the text. This method also handles glyph-based clipping.

5. If IPrintOemDriverUni::DrvUniTextOut cannot use a downloadable font (because the font is not available or is rotated), it calls the rendering plug-in's IPrintOemUni::TextOutAsBitmap method, which draws the text as a bitmap.

6. After IPrintOemDriverUni::DrvUniTextOut returns, the DrvTextOut hooking function must draw underlines and strike-throughs, based on the rectangles specified by the DrvTextOut function's prclExtra parameter, using vector commands (if supported).