Overview

In this chapter...

• Printing process
• _doc_ctrl structure
• Printer library
• Render library
• Sample filters

Printing process

Here's an overview of Photon's printing process:

1. Photon applications create phs (Photon stream) files. These files consist of the Photon commands used to draw the selected objects.
2. The phs files are processed by a print filter (for example, phs-to-ps, phs-to-pcl, or phs-to-bmp) to create data that a particular printer understands. The print filter sends the data to stdout.
3. The configuration of Photon and Spooler redirects this data to the appropriate device.

The printer library can use one of the following modes:

raster mode

Data is drawn into a RAM buffer and the resulting RGB pixel information is sent to the printer. Most printers use this mode.

page mode

The print filter and/or printer process the drawing primitives directly. The sample PostScript filter uses page mode.

The data in the phs file is an unsorted stream of entities to be drawn on the page. The data is written in the order drawn by the program. For example, if you're printing a window, it might be drawn in this order:

• window frame
• title bar
• buttons
• title text
• window contents.

Most printers need graphics data that proceeds down the page -- printers rarely move the paper backwards, nor is it possible to print a light tone over a dark one. This means that the print filter needs to render the image and then process it from the top down.

A printer commonly has much greater resolution than a typical screen. For example, an 8.5" * 11" page at 300 dots per inch (DPI) would need 2550 * 3300 dots of information. If each pixel on the screen requires 3 bytes for RGB information, rendering this number of dots would require more than 25M of memory. To reduce the memory required, the printer library divides the page into a series of slices, the size of which depends on the amount of RAM made available in my_startdocument().

_doc_ctrl structure

A print filter uses a document-control structure of type _doc_ctrl, which is defined in <photon/PhRender.h>. Most of its members are filled in by the printer library based on data in the phs file. This section describes the members your print filter will need to use.

specified

Set of bits indicating which members in the structure are valid. If the value of a member is loaded from the phs file, the corresponding bit is set in specified.

Your print filter should be designed to use reasonable defaults for members that aren't specified. It should also make sure that the specified members are valid for the current printer.

The following constants can be used with the _doc_ctrl structure's specified member to determine which other members have are valid:

Related to the source

The members that relate to the source of the data to print are:

Here's how they relate to the source image:

_doc_ctrl members related to the source image

Related to the page

The members that relate to the printed page are:

Here's how they relate to the printed page:

_doc_ctrl members related to the printed page.

Printer library

The printer library, prlib, has code to:

• Read in the phs file and populate the struct _doc_ctrl structure.
• Break up the page into a series of slices that proceed down the page.
• Process the .phs file once for each slice.
• Return the rendered slice to be printed.

Your program must determine the maximum size of the ram_buffer member and create final values for margins, colors, dithering, etc.

There are default cover functions for all the functions in this library. When a function is defined in your code, the linker includes that version, rather than the prlib version.

For information about the functions in prlib, see the Printer Library chapter.

Render library

Most print filters let the Render engine convert the draw stream data from the phs file into RGB data and then send this pixel information to the printer.

A different approach is to take over the drawing process by overriding the default functions that:

• draw rectangles, circles, etc.
• print text
• perform dithering.

The default versions of these functions draw the required image in the ram_buffer member of the _doc_ctrl structure.

The _doc_ctrl structure includes pointers to the primitive functions. You can override the default functions by storing pointers to your own versions in the _doc_ctrl structure; do this in the my_startrender() function in the printer library. If you replace the default drawing routines, you won't need to allocate ram_buffer.

At the very least, you'll need to override the _Rect() function. The other functions attempt a more complex operation, but can pixelize the information if required.

For information about these functions, see the Render Library chapter.

Sample filters

This DDK includes sample PCL and PostScript print filters. The PCL sample includes:

These are listed in increasing importance; you shouldn't have to touch set_io, but you'll have to create a version of pcl3.c for your printer, and then interface appropriately to my.c.

The PostScript sample includes: