(v13) Harlequin VariData parameters
This page applies to Harlequin v14.0r0 and later; and to Harlequin Core but not Harlequin MultiRIP.
Page content:
This section describes the various parameters that can be used with HVD.
Unless otherwise stated, these parameters may be set in pdfopen, setpdfparams, or pdfexec; they cannot be set in pdfexecid.
Also, unless otherwise stated, these parameters apply to both internal and external mode, including position independent.
EnableOptimizedPDFScan
Optional Boolean or Name or string
Default: /Never
Activates Harlequin VariData.
From v11.0r1, the /EnableOptimizedPDFScan can be used as a tri-state parameter allowing: /Always , /Never , or /Auto while also retaining the boolean options of true and false for backwards compatibility, where /Always is the same as true and /Never is the same as false.
From v11.0r2, the /EnableOptimizedPDFScan parameter can be set in a call to pdfexec. Previously, it could only be set from setpdfparams.
OptimizedPDFCacheID
Required string
This key is required when HVD is activated and is the identifier for the cache implementation to connect to (that is, it identifies the HVD back end that is to be used to perform raster element caching). It may be one of the built-in values (prefixed with GG_ ) or one defined by a custom OEM created back-end cache implementation. This could be a plugin, an HHR back end (see “HVDNONE” or “HVDRAW” as described in the Harlequin Core SDK Developer’s Guide ) or internal HVD (GGIRR ).
OptimizedPDFCoalesceLimitPercent
Optional Number
Default: -1
This option can only be used for eHVD.
This option provides less scanning flexibility and controls the way marks on the page are coalesced into raster elements. If this parameter is negative (that is, the default), there is no restriction: every eligible mark is coalesced. If it is zero, no coalescing at all takes place. If it is positive, coalescing is allowed.
The value used should be a unique string; we recommend that you prefix it with an abbreviation that identifies your company or product (for example: OEM_HHR_PDF_HVD).
For more information see the API Reference Manual, “HVD diagnostic mode”.
The higher the value, the more likely a mark is allowed to coalesce with other marks despite any growth in the overall bounding box it may lead to. Conversely, a small positive value means that coalescing happens only in those cases where there is little overall increase in the overall bounding box. In other words, large values of this parameter are likely to mean fewer elements per page, but larger areas of white space within them.
OptimizedPDFCompactMemory
Optional Boolean
Default: false
From Harlequin Core v13.2r3, OptimizedPDFCompactMemory is deprecated; it will be removed from Harlequin Core v14.0r0.
This is a Boolean switch-controlling memory behavior and decides between the option of using less memory or faster operation. When this flag is true, the RIP discards some bits of scanner state earlier than it otherwise would. This leads to a lower overall memory usage for many jobs at the possible expense of less flexible mark coalescing and therefore more raster elements per page on average. Also there is a scanning speed penalty for this lowering of memory consumption.
OptimizedPDFCoverageLimitPercent
Optional Integer
Default: 0 (no limit)
This option can only be used for eHVD.
This option only takes effect when OptimizedPDFExternal is true. When greater than zero, the RIP calculates the total area of the bounding boxes of the raster elements it has scanned on every page. When this area expressed as a percentage of the overall page area exceeds the value of this parameter, all marks for the page in question are coalesced into a single raster element. For example, if the scanner calculates that there are three elements on a given page and each is the same size as the page itself, the calculated total area is 300% of the page area; any value below 300 for this parameter would result in the page being limited to a single raster element (and thus the coverage would be reduced to 100%).
OptimizedPDFElementTileClip
Optional Boolean
Default: false
(Available from Harlequin v13) A boolean that only has effect when both HVDPage and HVDElement methods are defined in (v13) The settilingparams operator. It determines if HVDElement tiling is clipped to the bounding box of each HVDPage tile. The default value (false) allows elements to be reused between HVDPage tiles; however, doing so may result in more elements intersecting a particular HVDPage tile and having odd intersections with HVDPage tiles (depending on the element position).
Setting this value to true reduces the chance of being able to reuse elements between HVDPage tiles; however, doing so may result in fewer elements intersecting each tile.
OptimizedPDFExternal
Required Boolean
This controls whether external or internal HVD is used. When this PDF parameter is true, external HVD is used, and the RIP assumes that the OEM’s own code has a method to store and combine the output rasters to form a final page.
OptimizedPDFFormIntersectPixels
Optional Integer
Default: 3
From Harlequin v12.1r1. Number of device pixels to relax intersection test by for forms that are repeated multiple times on a single page.
Jobs printing elements such as labels or imposed postcards can have a few pixels of overlap between repeats of those elements. If the elements are transparent or contain transparent items, HVD would normally coalesce adjacent instances, even if they only overlap by a few pixels.
This parameter is for preventing such coalescing where the overlap is sufficiently small that it can be regarded as not being deliberate.
Using a large value runs the risk of processing deliberate overlaps incorrectly, but the maximum appropriate value depends on device resolution and the jobs being processed. Valid values are integers. 0 means to not relax the intersection test, which gives the same results as RIPs before Harlequin v12.1r1.
OptimizedPDFFormThreshold
Optional
Integer
Default: 512
This parameter sets the minimum stream length in bytes for an XObject form to be automatically treated as significant (and hence more likely to be retained) the second time it is encountered. This avoids forms which are, for example, just containers for very small fills or linework automatically being treated as significant, and can help avoid an excessive number of small rasters being retained. If the form contains significant marks or is being treated as significant (for example, due to PDF/VT hints), this parameter makes no difference.
This parameter was introduced for v12.0r2. Set to 0 to keep behavior the same as v12.0r1.
The value for OptimizedPDFFormThreshold is set in bytes, while the value for OptimizedPDFImageThreshold is set in kB.
OptimizedPDFGridEpsilon
Optional
Real number
Default: 0.000001
This option only takes effect when used with position-independent eHVD. It has no effect when either /OptimizedPDFExternal or /OptimizedPDFPositionIndependent is false.
This controls how sensitive HVD is to differences between the phase offsets of graphics with respect to the pixel grid. The smaller, the more sensitive, and more likely that eHVD output exactly matches rendering without HVD. The larger the value, the more likely the RIP is to identify two elements as identical and therefore to increase performance.
Positive real values up to a maximum of 1.0 can be used (or the integer value 1); for many applications we recommend a value of 1.0 as giving sufficiently accurate output.
Maximum valid value: 1.0 or 1
A value of 0 is taken to mean the default value.
OptimizedPDFGridX, OptimizedPDFGridY
Optional real numbers
Default: 1.0
The value for OptimizedPDFFormThreshold is set in bytes, while the value for OptimizedPDFFormThreshold is set in kB.
This option can only be used for eHVD.
This pair of parameters controls the grid size from which the HVD scanner calculates phase offsets. It is expressed in device pixels. By default this grid is set on single-device pixel boundaries but, for instance, if a customer code requirement exists where raster elements must be aligned on a grid which is larger than that, these parameters may be adjusted. Naturally, the larger these values are, the greater the probability that two elements which differ only in x ,y offset is given different ID values.
The values entered are rounded to the equivalent of the nearest positive integer (that is, a value of 4.2 is rounded to 4.0).
OptimizedPDFIgnoreHints
Optional Boolean
Default: false
From Harlequin v12.0r2. When set to true, all GTS and GGSL hint entries in XObjects are ignored. It is provided primarily for debugging files and for cases where hints have been set incorrectly. See Harlequin Technical Note Hqn101: Harlequin VariData hint tags.
OptimizedPDFIgnorePatternPhase
Optional Boolean
Default: false
This option only applies to position-independent eHVD.
From v11.0r6a, the OptimizedPDFIgnorePatternPhase parameter controls whether the HVD scanner should take account of the pattern tiling’s offset from the bounding box of a given mark on the page. When false, the presence of a pattern in the job being scanned disables position-independent HVD (if enabled) to achieve pixel-for-pixel matching between HVD and non-HVD output. When true, HVD allows position independence to remain on when there are patterns in the job, resulting in output in which pattern phase may vary from that obtained without HVD. The customer decides whether or not the differences are significant, but generally it is most obvious only when exact pixel-for-pixel outputs are being compared (for example, using checksumming).
From v12.1r0, if this parameter is set to false, the presence of a pattern in the job being scanned amends processing within the RIP if position independent HVD is enabled. The rasters and events output in the format expected for the value of the OptimizedPDFPositionIndependent flag, but multiple instances of the same graphic or collection of graphics at different positions on the page are no longer be treated as the same and are rendered separately. This parameter may also be specified in the parameter dictionary to pdfexec and pdfopen.
OptimizedPDFImageThreshold
Optional
Integer
Default: 32
This parameter sets the minimum stream length in kB for an image (or imagemask) XObject to be automatically treated as significant (and is more likely to be retained). This can help avoid an excessive number of small rasters being retained.
The value for OptimizedPDFFormThreshold is set in bytes, while the value for OptimizedPDFImageThreshold is set in kB.
OptimizedPDFPositionIndependent
Optional Boolean
Default: true
This option can only be used for eHVD.
This boolean flag, when set, enables position independent HVD. When in position-independent HVD mode, the RIP finds elements that appear on multiple pages drawn with gstates which are identical except for their x ,y translation values. That is, the elements passed to the customer code have extra position data alongside them, which is needed to reassemble the final page from the elements supplied by the RIP.
For example, a 2 x 2 imposed flat where each of the imposed pages has the same background uses a single cached element to represent that background; it appears four times in the API metadata for that page, each time with a different x ,y offset. When this flag is false, each element passed to the customer code by the RIP is the same size as the pages for which the element is intended. When it is true, each element is passed in a raster that is just large enough to contain the data. That is, none of the elements making up a page are necessarily the same size as the page.
The raster and metadata delivery to the back end is different between external HVD and position independent HVD; see the Harlequin API Reference Manual.
OptimizedPDFScanChunkSize1
Optional boolean
Default: false
From Harlequin v13.2r4.
When iHVD or NPI-eHVD are in effect, setting this parameter to true allows the HVD scan to take place with a chunk size of 1.
In combination with the /OptimizedStashPages parameter, this may allow reuse to take place for a multi-page job even with a chunk size as low as 1. In addition in a few cases, multi-page iHVD or NPI-eHVD jobs with suitable GGSL hints may reuse with a chunk size of 1. The parameter has no effect where the RIP is presented with a longer job or a bigger chunk size.
Before v14.0, when PI-eHVD is in effect with /OptimizedPDFIgnorePatternPhase false and the RIP detects patterns in the job, it would drop back to NPI-eHVD internally, in which case this parameter would prevent a single-page chunk from aborting the scan.
From v14.0 onwards this parameter has no effect when PI-eHVD is in use.
OptimizedPDFScanLimitPercent
Optional
Integer percentage
Default: 10
An integer percentage (that is, min. 0, max. 100). It controls whether the optimized PDF scan ends early or not.
This value is present to avoid the scanning overhead on jobs where the optimization is not going to be effective. The HVD scanning phase checks whether any reuse has been found on each page, and if not, then this page is considered a unique page. The accumulated number of unique pages in the current file (or chunk if PageRange is being used) so far is compared to the total number of pages in the file/chunk. If the percentage exceeds the OptimizedPDFScanLimitPercent the scan is aborted and the rest of the processing of the file/chunk is performed without HVD.
If position-independent HVD is not in use, the scanning is omitted entirely if: “100 / (pages in chunk) > OptimizedPDFScanLimitPercent ” as each element can be (re)-used at most once per page. (For example, if the OptimizedPDFScanLimitPercent is 25, then scanning would not be started for a file/chunk with fewer than four pages.
If a large job is split into “chunks” of data with the use of /PageRange (see (v13) Using HVD with page ranges), and the HVD scan in any chunk aborts because too many unique pages are encountered, then no scan at all is tried for any subsequent chunk in the job. Thus, if you are using small chunks of data and are seeing jobs aborting the HVD scan when you think there should be re-use of data, you should consider increasing the /OptimizedPDFScanLimitPercent value, possibly up to the maximum of 100% (in which case the HVD scan continues for the whole job).
This does not mean that the scanner scans the specified percentage of pages in the job. If the scan determines that the job benefits from HVD, then all pages are scanned.
OptimizedPDFSetupID
Optional string
Default: ()
A string to enable different RIP configurations to be distinguished.
The value used should be a unique string; we recommend that you prefix it with an abbreviation that identifies your company or product (for example, OEM_HHR_PDF_HVD).
This option can be used for both eHVD and iHVD. Its value is a string that affects the hashes of all the rasters produced. If rasters are retained between jobs, but the page setup changes in a way that may affect output, this value should change. This is to avoid a later job erroneously picking up an unsuitable raster that was created for an earlier job (for example, /OptimizedPDFSetupID (27B).
OptimizedPDFSingleForeground
(Available from Harlequin Core v13.2)
A boolean that has effect when /OptimizedPDFExternal is in use. It ensures that (when tiling is not in use), pages are split into at most two raster elements (that is, a background element and a foreground element, which when combined provide the full page content).
In addition, if a page needs to be initialized to a color other than white, a page background_id element is produced.
Setting this value to true tends to reduce reuse, although this depends on the job.
Default: false
OptimizedPDFSingleForeground should not be set to true when tiling is in use.
OptimizedPDFStashPages
Optional Integer
Default: 0, values outside the range [0, 32] are limited to being inside the range. (This restriction may change in future).
From Harlequin v13.2r4.
This parameter applies to all types of HVD and is useful when running jobs in small pdfexecid chunks.
When jobs are run in pdfexecid chunks in the absence of this parameter (or when the parameter value is 0), although rasters stored in one chunk may be reused in a later chunk, the scanning of each chunk starts afresh as if there had been no previous chunks. With a non-zero parameter set here, the RIP retains much of the scan information relating to pages from chunks before the one it is currently scanning.
This means that the scan tends to be faster, since there should be no need to rescan objects which are already known and which will have the same appearance, and in addition it is sometimes possible to make better reuse decisions based on information retained from previous pdfexecid chunks.
For example, when running a job for which the static data on the odd pages is different from those on the even pages, it may be decided to set a chunk size of 4. Setting a parameter value of 2 would mean that scan information is available for both an odd and an even page from the previous chunk, thereby likely speeding up the current chunk. If running a job with more than 1 rip with a proposed chunk size < 2 * the repetition period, (so with a proposed chunksize < 4 in this case), it will generally be better to set a somewhat higher parameter value.
This parameter does not have any effect for jobs that are run in pdfexec chunks.
This parameter also enables many more HVD jobs to reuse with a chunk size of 1, (although it is often faster to run with a larger chunk size).
In the case of iHVD and NPI-eHVD, the following parameter must be set in addition to /OptimizedPDFStashPages in order to avoid the RIP aborting the scan for a one-page chunk:
/OptimizedPDFScanChunkSize1 true
OptimizedPDFTestOpaqueHint
Optional Boolean
Default: true
From Harlequin v12.0r2. When set to true, a true value for the GGSL_Opaque hint key in an XObject is ignored. If OptimizedPDFTestOpaqueHint is set to false, then a true value for GGSL_Opaque is acted on. The OptimizedPDFTestOpaqueHint has no effect when the GGSL_Opaque hint has a value of false . See Harlequin Technical Note Hqn101: Harlequin VariData hint tags.