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	hvdtracker.h
	HVD page and element define tracker.
file	hvdutil.h
	Utility functions for manipulating HVD elements.

Typedefs
typedef struct HVD_element	HVD_element
	An opaque typedef for cached HVD elements.
typedef struct HVD_cache	HVD_cache
	An opaque typedef for the HVD cache instance.
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_t
	Type for the reason parameter to the HVD_recovery_filter_fn callback. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover().

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 }
	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_RECOVER_ALL = 0 , HVD_RECOVER_MPS_ARENA , HVD_RECOVER_MALLOC_FREE , HVD_RECOVER_SHARED_MEMORY }
	Values of the HVD_recovery_reason_t type parameter reason of HVD_recovery_filter_fn. This parameter can be used to exclude elements from low-memory recovery, if they do not contribute to the type of memory requested. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover(). 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.
• 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.
• 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.
• 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 the HVD_recovery_reason_t type parameter reason of HVD_recovery_filter_fn. This parameter can be used to exclude elements from low-memory recovery, if they do not contribute to the type of memory requested. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover().

Enumerator
HVD_RECOVER_ALL	Recover elements from all caches. 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.

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.