This page applies to Harlequin v13.1r0 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.


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.


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 backend 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 ).


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 (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, and 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.


Optional Boolean

Default: false

From Harlequin Core v13.2r3, OptimizedPDFCompactMemory is deprecated and will be removed from Harlequin Core v14.0.

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.


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 and so 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%).


Optional Boolean

Default: false

Available from Harlequin v13) A boolean that only has effect when both HVDPage and HVDElement methods are defined in 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 re-used between HVDPage tiles, but 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, but may result in fewer elements intersecting each tile.


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.


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.




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.



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 the 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), and for many applications a value of 1.0 is recommended 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).


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.


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.




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.


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, and 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.



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 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.


Optional string 

Default: ()

A string to enable different RIP configurations to be distinguished.

The value used should be a unique string, and 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).


(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 2 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.


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.