eHVD support library

libHVD provides support for monitoring HVD events, tracking page and element composition, caching HVD elements, and compositing HVD elements. Using libHVD simplifies construction of raster backends that can output fully-composited eHVD pages. More...

Files
file	hvdblit.h
	Interface for HVD element blitters.
file	hvdcache.h
	eHVD cache for raster backends.
file	hvdevmon.h
	eHVD event monitor and responder.
file	hvdlibinit.h
	Functions for registering and deregistering the HVD cache implementations provided by eHVD support library.
file	hvdpageoutput.h
	HVD page output structure define.
file	hvdtracker.h
	HVD page and element define tracker.
file	hvdutil.h
	Utility functions for manipulating HVD elements.

Typedefs
typedef struct HVD_cache	HVD_cache
	An opaque typedef for the HVD cache instance.
typedef struct HVD_cache_fns	HVD_cache_fns
	Typedef for the HVD cache implementation functions.
typedef struct HVD_tracker	HVD_tracker
	An opaque typedef for the HVD tracker.
typedef HqnResult	HVD_result
	Type for return values from HVD functions. More...
typedef int	HVD_recovery_reason
	Type for the reason parameter to the HVD_cache_fns::recovery_filter method. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover(). Values are combined bitmasks from the HVD_recovery_reason_values enumeration.
typedef int	HVD_destroy_reason
	Type of variables containing HVD_destroy_reason_values.
typedef int	HVD_element_state
	Type of variables containing HVD_element_state_values.

Enumerations
enum	{   HVD_SUCCESS_ALREADY = -2 , HVD_SUCCESS_INCOMPLETE = -1 , HVD_SUCCESS = HQN_RESULT_SUCCESS , HVD_ERROR_INVALID_PARAMS ,   HVD_ERROR_API_MEMORY , HVD_ERROR_API_RDR , HVD_ERROR_API_PTHREADS , HVD_ERROR_API_EVENTS ,   HVD_ERROR_NO_MEMORY , HVD_ERROR_NO_PAGE , HVD_ERROR_NO_ELEMENT , HVD_ERROR_ELEMENT_MISMATCH ,   HVD_ERROR_ELEMENT_REFUSED , HVD_ERROR_EXCESS_RASTERS , HVD_ERROR_RASTER_REFUSED , HVD_ERROR_NOT_LOCKED ,   HVD_ERROR_NOT_PENDING , HVD_ERROR_ALREADY_PENDING , HVD_ERROR_UNDERFLOW_HITS , HVD_ERROR_INTERRUPTED ,   HVD_ERROR_ABORTED , HVD_ERROR_MUTEX_FAILED , HVD_ERROR_CACHE_FNS , HVD_ERROR_CACHE_FULL }
	Values of HVD_result. These values are organised so a generic test for success can be made as less than or equal to HVD_SUCCESS, a generic test for failure is greater than HVD_SUCCESS. More...
enum	HVD_recovery_reason_values {   HVD_RECOVER_ALL = -1 , HVD_RECOVER_MPS_ARENA = 1 , HVD_RECOVER_MALLOC_FREE = 2 , HVD_RECOVER_SHARED_MEMORY = 4 ,   HVD_RECOVER_DISK = 8 , HVD_COUNT_ALL = 0 }
	Values of the HVD_recovery_reason type parameter reason of HVD_cache_fns::recovery_filter, also used by HVD_cache_size() and HVD_cache_recover(). This parameter can be used to exclude elements from low-memory recovery, if they do not contribute to the type of memory requested. The values may be combined in a bitmask for calls to HVD_cache_size() and HVD_cache_recover(). More...
enum	HVD_destroy_reason_values {   HVD_DESTROY_NORMAL , HVD_DESTROY_PURGE , HVD_DESTROY_ERROR , HVD_DESTROY_JOB_END ,   HVD_DESTROY_RIP_END }
	Reasons for destroying libHVD objects. Values of the HVD_destroy_reason type. More...
enum	HVD_element_state_values {   HVD_ELEMENT_UNSET , HVD_ELEMENT_DEFINED , HVD_ELEMENT_PENDING , HVD_ELEMENT_READY ,   HVD_ELEMENT_ERROR }
	Values for HVD element states, stored in the HVD_element_state type. These are used in multiple cache implementations. More...

Detailed Description

libHVD provides support for monitoring HVD events, tracking page and element composition, caching HVD elements, and compositing HVD elements. Using libHVD simplifies construction of raster backends that can output fully-composited eHVD pages.

There are four main components in libHVD:

• The event monitor declared in hvdevmon.h. The event monitor is responsible for capturing eHVD events, and calling libHVD tracker and cache functions to connect a producer of elements and pages to an element cache and output page compositor. This component will only be used if libHVD is built into a RIP or another process that uses RDR-based events (documented in Events system) to create variable data pages using eHVD elements and page definitions. Connections to eHVD made through the event monitor may be specialized using parameters supplied in the /OptimizedPDFCacheId, if the cache implementation supports it.
• The page and element tracker declared in hvdtracker.h. The tracker is responsible for managing element and page definitions, presenting rasters for elements to the cache, waiting for elements to be presented, and initiating the output page compositing. HVD trackers are instantiated and connected to HVD clients by event monitors.

• The element cache declared in hvdcache.h. The element cache is responsible for managing eHVD elements: tracking creation, locking, unlocking, and hit counting on cached elements, purging unused elements to stay within specified storage limits, responding to cache size and purging requests, and responding to queries about elements present in the cache. The element cache may be specialised to use different storage methods for elements. Cache implementations are registered in RDR as named RDRs of class RDR_NAMES_LIBHVD_CACHE_API, and discovered and connected to HVD clients by event monitors. libHVD contains two built-in cache base classes:

  • LIBHVD_BASE is a process-memory cache suitable for creation of single-RIP eHVD solutions.
  • LIBHVD_SHM_BASE is a shared-memory distributed cache that may be suitable for Scalable RIP eHVD solutions. This cache supports one parameter, specifying the number of elements that may be stored in the cache. The parameter is supplied by instantiating the cache with an ID that contains a query character '?' followed by the number of elements storable in the cache (see HVD_monitor_params::cache_id).

  Neither of these caches are instantiable. They must be discovered, copied, suitable raster storage methods implemented, and the modified cache registered in RDR in order to be usable by HVD event monitors. The Harlequin RIP SDK implements instantiable specializations of these caches:

  • RSTORE_CACHEAPI_NAME is a specialization of LIBHVD_BASE for use with the Raster store interface. Raster memory is allocated from the RIP, but may be compressed and purged to disk in low memory.
  • MEMFB_CACHEAPI_NAME is a specialization of LIBHVD_BASE for use with process-memory framebuffers. Framebuffers may be allocated from RIP memory or system memory.
  • SHMFB_CACHEAPI_NAME is a specialization of LIBHVD_SHM_BASE for use with shared-memory framebuffers. These framebuffers may be shared between multiple RIPs or other processes on the same machine.

• The blitter interface declared in hvdblit.h. The blitter interface contains functions that can be used to composite eHVD elements together, but does not itself implement a full compositor. There are too many aspects of output memory handling, output post-processing and integration to provide a single solution.

libHVD itself does not implement a page output function, it leaves that for the application to provide. The Harlequin RIP SDK contains such an output function (declared in hvdoutput.h) that the application can used to composite eHVD elements and output the composed raster through the raster backend API. It allows the same raster backend implementation to be used for eHVD output as non-eHVD output. See Enabling eHVD in Raster output backends for details on how to enable eHVD output in raster output backends.

Typedef Documentation

HVD_result

typedef HqnResult HVD_result

Type for return values from HVD functions.

HVD_result is a subclass of HqnResult that also supports some specific extra success and error codes generated and used in the libHVD library. Before assigning to values of HqnResult type or any of its other subclasses, HVD_result values must be converted using HVD_result_translate() to change the libHVD specific values to HQN_RESULT_SUCCESS or a monitor UID error code greater than MON_CLASS_ERROR.

Enumeration Type Documentation

anonymous enum

anonymous enum

Values of HVD_result. These values are organised so a generic test for success can be made as less than or equal to HVD_SUCCESS, a generic test for failure is greater than HVD_SUCCESS.

Values greater than MON_CLASS_ERROR with a valid subclass, PS error type, and UID for an error may also be returned to give more specific error details. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

Enumerator
HVD_SUCCESS_ALREADY	A page was output before requested.
HVD_SUCCESS_INCOMPLETE	More rasters expected.
HVD_SUCCESS	Function returned successfully.
HVD_ERROR_INVALID_PARAMS	Invalid parameters to function.
HVD_ERROR_API_MEMORY	Missing or invalid memory API pointer.
HVD_ERROR_API_RDR	Missing RDR API pointer.
HVD_ERROR_API_PTHREADS	Missing pthreads API pointer.
HVD_ERROR_API_EVENTS	Missing Event API pointer.
HVD_ERROR_NO_MEMORY	Memory allocation failed.
HVD_ERROR_NO_PAGE	Page index supplied is invalid.
HVD_ERROR_NO_ELEMENT	No element supplied to a function.
HVD_ERROR_ELEMENT_MISMATCH	Mismatched element is already cached.
HVD_ERROR_ELEMENT_REFUSED	Element addition refused.
HVD_ERROR_EXCESS_RASTERS	More rasters than expected.
HVD_ERROR_RASTER_REFUSED	Raster creation had an error.
HVD_ERROR_NOT_LOCKED	Element is not locked.
HVD_ERROR_NOT_PENDING	Element is not pending.
HVD_ERROR_ALREADY_PENDING	Element is already pending.
HVD_ERROR_UNDERFLOW_HITS	Element hit count underflowed.
HVD_ERROR_INTERRUPTED	Wait for page output was interrupted.
HVD_ERROR_ABORTED	Wait for page output was aborted.
HVD_ERROR_MUTEX_FAILED	Mutex lock failed.
HVD_ERROR_CACHE_FNS	Cache implementation invalid.
HVD_ERROR_CACHE_FULL	Cache cannot accept element.

HVD_destroy_reason_values

enum HVD_destroy_reason_values

Reasons for destroying libHVD objects. Values of the HVD_destroy_reason type.

Enumerator
HVD_DESTROY_NORMAL	This object is not needed by the HVD monitor.
HVD_DESTROY_PURGE	This object is being purged to recover memory.
HVD_DESTROY_ERROR	The job or RIP has encountered an error.
HVD_DESTROY_JOB_END	The job is ending.
HVD_DESTROY_RIP_END	The RIP is quitting.

HVD_element_state_values

enum HVD_element_state_values

Values for HVD element states, stored in the HVD_element_state type. These are used in multiple cache implementations.

Enumerator
HVD_ELEMENT_UNSET	Invalid initial state of element storage.
HVD_ELEMENT_DEFINED	Element is defined.
HVD_ELEMENT_PENDING	Element is pending rasterisation.
HVD_ELEMENT_READY	Element is complete.
HVD_ELEMENT_ERROR	Element creation or rasterisation failed.

HVD_recovery_reason_values

enum HVD_recovery_reason_values

Values of the HVD_recovery_reason type parameter reason of HVD_cache_fns::recovery_filter, also used by HVD_cache_size() and HVD_cache_recover(). This parameter can be used to exclude elements from low-memory recovery, if they do not contribute to the type of memory requested. The values may be combined in a bitmask for calls to HVD_cache_size() and HVD_cache_recover().

Enumerator
HVD_RECOVER_ALL	Recover elements from all memory types. Using this reason in HVD_cache_recover() or HVD_cache_size() bypasses calling the recovery filter function (so recovery filter functions will never be called with a zero reason code).
HVD_RECOVER_MPS_ARENA	Recover elements allocated from the RIP's MPS arena. This includes elements allocated using SwAlloc() or MemInit().
HVD_RECOVER_MALLOC_FREE	Recover elements allocated using system malloc/free.
HVD_RECOVER_SHARED_MEMORY	Recover elements allocated using shared memory.
HVD_RECOVER_DISK	Recover elements in secondary storage.
HVD_COUNT_ALL	Count all memory in an eHVD cache, not just recoverable memory. This reason should not be used in HVD_cache_recover(). When used in HVD_cache_size(), it bypasses calling the recovery filter function, and counts the size of memory in all store types.