(v13) Extending media selection

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

Media selection is the process of selecting a source of media for the printing process and selecting its destination after printing. (For example, specifying which paper tray and which output tray to use.) In PostScript-language terms, this means determining a number representing the source or destination, the number being the key of a dictionary in InputAttributes or OutputAttributes, which contains an abstract description of the source or destination.

The number is determined by the media matching process described in [RB2]. This is a complex algorithm, but in principle amounts to matching requests presented in the form of keys in the page device to attributes, represented as keys in the InputAttributes and OutputAttributes constituent dictionaries.

Some possible InputAttributes keys are listed in [RB2]: PageSize is always present (and treated as a somewhat special case; page sizes are discussed further in (v13) Page sizes and orientations); MediaWeight, MediaColor, and MediaType may also be present. OutputAttributes has no pre-defined keys. In both cases, however, additional keys can be used for matching as appropriate.

Consider a device that has a set of punch registers in different configurations. If each configuration is named, the appropriate one could be selected from a job by:

            << /PunchRegister (Press #3) >> setpagedevice

The page device could be set up in advance (say by a page feature in the GUI version) to offer the set of available punch registers in OutputAttributes:

            <<
            /OutputAttributes <<
                << /PunchRegister () >>
                << /PunchRegister (Press #3) >>
              ...
              5 << /PunchRegister (Press #5) >>
            >>
            >> setpagedevice

Provided /PunchRegister has been made known as a media selection key as described below, this would select output attribute number 1 (in this example) and transmit this information to the %pagebuffer% device, and in the GUI version on to the plugin, to allow the output device to do whatever is necessary to select that particular combination.

All new media selection keys are new page device keys too, so they must be added as extra page device keys as described in (v13) Adding custom page device keys. They must then be identified as media selection keys as well.

This is done by the key /ExtraMediaSelectionKeys. Its value is a dictionary containing the keys required. The value of the keys is either the name /InputAttributes or the name /OutputAttributes according to whether the key contributes to the input or output media matching (the same key cannot be used for both).

For example, add /PunchRegister as follows:

            <<
            /ExtraPageDeviceKeys <<
              /PunchRegister ()
            >>
            /ExtraMediaSelectionKeys <<
              /PunchRegister /OutputAttributes
            >>
            >> setpagedevice

Where the parameter is introduced in a plugin, this can be done automatically by marking the parameter with the SF_INPUTATTRIB or SF_OUTPUTATTRIB flag, as appropriate in the C data structure DICTSTRUCTION.

The number of the dictionary selected for InputAttributes is placed in the mediaSelect field of the pageHeader structure, and for OutputAttributes in the outputAttributes field (mediaSelect is so named for historical reasons).

The file Sys/ExtraMediaSelectionKeys is executed as the Harlequin RIP starts. It must leave on the operand stack key/value pairs (not a dictionary), where the keys are the names of the new media selection keys (which must also have been added in the file Sys/ExtraPageDeviceKeys as described in (v13) Adding custom page device keys), and the values are either the name /InputAttributes or the name /OutputAttributes.