(v13) Harlequin VariData API - External mode
This page applies to Harlequin v13.1r0 and later; and to Harlequin Core but not Harlequin MultiRIP
The RIP supplies page descriptions and rasters for sub-page collections of graphical elements to OEM code through the VariData API and two-page device parameters.
NOTE: From Harlequin v13, the API for using Harlequin VariData in external mode has been changed and is not backward compatible. For information see API events for eHVD
There are more details on the exact nature of the API in the file swevents.h or rrevents.h
if present in your distribution.
The following should be added to the SW/Sys/ExtraPageDeviceKeys:
/OptimizedPDFId ()
and
/OptimizedPDFUsageCount 0
For Harlequin MultiRIP, the OEM code is expected to implement plugin parameters that enable it to store and combine the raster elements appropriately.
Implement the following two page device parameters:
{STIO_INLINE_STRING, szNull, szNull, (uint8 *)"/OptimizedPDFId", Stio_Offset(TestDevParams, OptimizedPDFId[0]), 33, 0, 0, 0 },
and
{STIO_INT, szNull, szNull, (uint8 *)"/OptimizedPDFUsageCount", Stio_Offset(TestDevParams, OptimizedPDFUsageCount), 0, 0, 0, MAXINT32 },
In Harlequin Core, these pagedevice parameters are implemented in the skinkit PGB device, and passed through to the raster description structure.
Having done this, the RIP will pass these two parameters through to the OEM code for each raster element. The parameters are:
| This is either an empty string (if HVD is turned off), or a 32-character hex string, representing a unique ID for this raster element. The IDs tie in with the IDs in the SWEVT_RR_PAGE_DEFINE event. Thus, plugin or Harlequin Core back-end developers should store what is in the SWEVT_RR_PAGE_DEFINE event as a table. As rasters arrive they are associated with a slot in the table with the same ID and the next time it is referenced it is simply played back. |
| This integer indicates how many times this raster element is used at the time of the raster's delivery. This parameter pre-dates the hit count maintenance which is done via the events API, and generally OEMs should use those to maintain a hit-count in their caches rather than this parameter which is retained for backwards compatibility. The OEM code can use this to determine how many times a page uses this raster element, and delete the raster element once all of the pages using it have been processed. The OEM code needs to note all of the pages and raster elements associated with a job, and remove them all once the job is complete or fails. When outputting separations, the IDs are the same across all separations. It is up to the OEM code to identify the right separations to combine. NOTE: Rather than using this quantity to determine whether a given element is a candidate for flushing from the cache, Global Graphics recommends that the OEM instead uses the hit count maintained via the SWEVT_RR_ELEMENT_UPDATE_HITS event. |
Sub-page raster elements are delivered for all parts of every page where HVD external mode is active. The variable data elements of each page are supplied with an OptimizedPDFId as well as those elements which are intended to be cached. The OptimizedPDFUsageCount is 1 for variable data parts of the page.
The OEM code receives a series of PGBs with associated IDs that it must store for later retrieval.
The delivery of raster to the plugin or Harlequin Core back end, however, provides no information about how to assemble the raster elements into final pages for output, and because of this an API is supplied, as described here.