(v13) Consuming the output data

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

A plugin should only attempt to consume an entire band of output data when it can guarantee that it will do so without blocking. See (v13) How long should a plugin call take? .

Some output devices cannot make this sort of guarantee without extra buffering, but it is sometimes appropriate for plugins writing output to a file rather than a physical device for example, a TIFF plugin.

A plugin indicates how many scanlines it has consumed by setting a combination of d_linescopied and d_linesprinted in the deviceDefinition structure described in (v13) The deviceDefinition structure . For more information see (v13) D_OUTPUT and (v13) D_IDLE .

When setting d_linescopied and d_linesprinted , you must ensure that their values are between 0 and d_page->imageHeight * d_frames .

You must also always ensure that:

d_linesripped >= d_linescopied >= d_linesprinted

The plugin could notify the RIP asynchronously using the lines copied timeline or the lines printed timeline.

Currently available timelines

There are two timelines defined for communication between the plugin and the RIP:

TL_PLUGAPI_LINES_COPIED

(Has the same purpose as d_linescopied ). This may be used by the plugin to speed up the RIPʹs response to asynchronous consumption of data: the plugin may set progress on this timeline from any thread, to indicate that it has copied data. The plugin should defer updating of the d_linescopied deviceDefinition field until a plugin selector is called.

TL_PLUGAPI_LINES_PRINTED

(Has the same purpose as d_linesprinted ). This may be used by the plugin to speed up the RIP's response to the completion of printing: the plugin may set progress on this timeline from any thread, to indicate that it has copied data. The plugin should defer updating of the d_linesprinted deviceDefinition field until a plugin selector is called. The only time it is used is when feeding at the end of a page.

Having got hold of the timeline reference, the following is how you can update TL_PLUGAPI_LINES_PRINTED and TL_PLUGAPI_LINES_COPIED .

(void)SwTimelineSetProgress(linescopied_tl_ref, (sw_tl_extent)lines);

This is how you can say, asynchronously, that TL_PLUGAPI_LINES_COPIED (or indeed TL_PLUGAPI_LINES_PRINTED ) is completed.

You should note that the two timelines TL_PLUGAPI_LINES_COPIED and TL_PLUGAPI_LINES_PRINTED are only created when the RIP is running in a “Single” mode. In “Multiple” modes they are never created, so any plugin registering an event handler for EVENT_TIMELINE_START , in order to obtain references to those timelines (for example to use when calling SwTimelineSetProgress() ), will never get such an event and so never initialize its references.

If you need to obtain a timeline reference for interrupting jobs, register a handler in your plugin for the EVENT_TIMELINE_START event and make a note of the timeline reference in each successive message with message type SWTLT_JOB .

For more information see Timelines .