SDK support for eHVD output

Raster backend support for eHVD output. More...

Files
file	hvdmemfb.h
	Support for local memory framebuffers for eHVD elements.
file	hvdoutput.h
	This file declares functions that can be used to composite eHVD elements and output the composed raster through the raster backend API.
file	hvdrstore.h
	Support for using the Raster Store API for eHVD elements.
file	hvdshmfb.h
	Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller.
file	phvdshmfb.c
	Platform functions to support shared memory framebuffers for eHVD elements.
file	hvdmemfb.c
	Support for local memory framebuffers for eHVD elements.
file	hvdoutput.c
	Support for raster output of composited external Harlequin VariData elements.
file	hvdrstore.c
	Support for raster store API for eHVD elements.
file	hvdshmfb.c
	Support for shared memory framebuffers for eHVD elements. This allows a Scalable RIP to share eHVD elements across the entire RIP farm, without needing coordination from a raster manager or central controller.

Data Structures
struct	hvd_output_page_params
	Structure to carry parameters and callback functions for compositing and outputting an eHVD page. More...

Typedefs
typedef struct hvd_output_page_params	hvd_output_page_params
	Structure to carry parameters and callback functions for compositing and outputting an eHVD page.

Enumerations
enum	{ HVD_LOG_TIMING = 1 }
	Bitmask of options for the hvd_output_page_params::progress field. More...

Functions
void	memfb_raster_release (HVD_element *pElement, void *hraster)
	Function to use as HVD_raster_release_fn callback when using local memory elements. More...
HqBool	memfb_recovery_filter (HVD_element *pElement, HVD_recovery_reason_t reason)
	Function to use as HVD_recovery_filter_fn callback when using local memory elements. More...
const RasterDescription *	memfb_raster_description (void *elementRaster)
	Function to use as hvd_output_page_params::raster_description_fn when using local memory elements. More...
void *	memfb_element_raster_open (void *elementRaster, struct RASTER_PLANE *plane, HqnResult *perr)
	Function to use as hvd_output_page_params::element_raster_open when using local memory elements. More...
const uint8 *	memfb_element_raster_map (void *context, void *elementRaster, unsigned int *pstartline, unsigned int *pnlines, HqnResult *perr)
void	memfb_element_raster_close (void *context, void *elementRaster)
HVD_result	hvd_output_page (const struct HVD_page_output *page, hvd_output_page_params *params)
	Common support callback function for raster backends implementing libHVD to output an HVD page. More...
int	hvd_default_cache_policy (void)
	Get the default cache policy, allowing overriding of default values to avoid having to recompile debug RIPs.
void	rstore_raster_release (HVD_element *pElement, void *hraster)
	Function to use as HVD_raster_release_fn callback when using raster store elements. More...
HqBool	rstore_recovery_filter (HVD_element *pElement, HVD_recovery_reason_t reason)
	Function to use as HVD_recovery_filter_fn callback when using raster store elements. More...
size_t	rstore_raster_purge (HVD_element *pElement, void *hraster, size_t *recover)
	Function to use as HVD_raster_purge_fn callback when using raster store elements. More...
const RasterDescription *	rstore_raster_description (void *elementRaster)
	Function to use as hvd_output_page_params::raster_description_fn when using raster store elements. More...
void *	rstore_element_raster_open (void *elementRaster, struct RASTER_PLANE *plane, HqnResult *perr)
	Function to use as hvd_output_page_params::element_raster_open when using raster store elements. More...
const uint8 *	rstore_element_raster_map (void *context, void *elementRaster, unsigned int *pstartline, unsigned int *pnlines, HqnResult *perr)
void	rstore_element_raster_close (void *context, void *elementRaster)
void	shmfb_raster_release (HVD_element *pElement, void *hraster)
	Function to use as HVD_raster_release_fn callback when using shared memory elements. More...
HqBool	shmfb_recovery_filter (HVD_element *pElement, HVD_recovery_reason_t reason)
	Function to use as HVD_recovery_filter_fn callback when using shared memory elements. More...
HVD_cache_fns *	shmfb_HVD_cache_fns (void)
const RasterDescription *	shmfb_raster_description (void *elementRaster)
	Function to use as hvd_output_page_params::raster_description_fn when using shared memory elements. More...
void *	shmfb_element_raster_open (void *elementRaster, struct RASTER_PLANE *plane, HqnResult *perr)
	Function to use as hvd_output_page_params::element_raster_open when using shared memory elements. More...
const uint8 *	shmfb_element_raster_map (void *context, void *elementRaster, unsigned int *pstartline, unsigned int *pnlines, HqnResult *perr)
void	shmfb_element_raster_close (void *context, void *elementRaster)

Detailed Description

Raster backend support for eHVD output.

These support functions can be used to composite eHVD elements and output the composed raster through the raster backend API (Raster backend output API). This allows the same raster backend implementation to be used for eHVD output as non-eHVD output.

Enabling eHVD in Raster output backends

The Harlequin SDK provides functions to make it easy to enable eHVD output in raster backends using libHVD (see eHVD support library and SDK support for eHVD output). In the simplest case this involves:

• Decide how to store elements. The Harlequin RIP SDK contains specialisations of eHVD element storage for local memory framebuffers (declared in hvdmemfb.h); shared memory framebuffers (declared in hvdshmfb.h); and compressible, purgeable raster stores (declared in hvdrstore.h). Each of these headers declares functions that will be used in some of the remaining steps below.
• Add a page output function of the HVD_page_output_fn type to the raster backend. This will usually be a small trampoline function that constructs an hvd_output_page_params structure, and calls hvd_output_page().
• Add a connection verification function of the HVD_connect_verify_fn type to the raster backend. This will usually be a simple function that calls GetPageBufferType(), and compares the result to the expected raster backend's name. This function is used to ensure that a configuration that targets eHVD is connected to the correct event monitor, tracker and cache handler for the raster backend it is serving.
• Construct an HVD_monitor_params structure containing an eHVD cache ID chosen for the raster back end; the page output and verification functions; and the appropriate raster release, recovery, and purge functions for the element storage methods chosen. During SDK initialisation, call HVD_monitor_start() with this parameter structure, and save the HVD monitor reference returned.
• In the raster backend's raster start function (RASTER_START_EX), check if the raster being presented has an OptimizedPDFId, and call HVD_monitor_connected() to check whether the HVD monitor created in the previous step is connected. If so, this is an eHVD element targetted at this backend. Create the element storage using the create function for the storage type chosen, and save the element storage handle returned.
• In the raster backend's raster data function (RASTER_WRITE_DATA_EX), call the appropriate function to write data to the element storage. If using a framebuffer storage method, the raster backend's SwLeRASTERDESTINATION function will be set instead to enable the RIP to write data directly into the framebuffer memory.
• In the raster backend's raster finish function (RASTER_FINISH_EX), call HVD_monitor_add_raster() with the element handle to make libHVD aware that the element is now complete. Alternatively, if there was an error constructing the element, the element storage methods provide functions to indicate that an element handle is invalid, and should be destroyed.

There are worked examples of this process present in several of the raster backends provided with the distributed application layers.

Using local memory framebuffers for eHVD

To use local memory framebuffers for storage and output of eHVD elements, the libHVD event monitor needs to be configured to use the local memory framebuffer raster release and recovery functions, and the HVD output function should be called with the local memory framebuffer access functions.

Before calling the libHVD HVD_monitor_start() function, the HVD_monitor_params::raster_release_fn field should be set to the memfb_raster_release function pointer, and the HVD_monitor_params::recovery_filter_fn field should be set to the memfb_recovery_filter function pointer.

Before calling hvd_output_page(), the hvd_output_page_params::raster_description_fn field should be set to the memfb_raster_description function pointer, hvd_output_page_params::element_raster_open should be set to the memfb_element_raster_open function pointer, hvd_output_page_params::element_raster_map should be set to the memfb_element_raster_map function pointer, and hvd_output_page_params::element_raster_close should be set to the memfb_element_raster_close function pointer.

Using raster stores for eHVD

To use raster stores for storage and output of eHVD elements, the libHVD event monitor needs to be configured to use the raster store release and recovery functions, and the HVD output function should be called with the raster store framebuffer access functions.

Before calling the libHVD HVD_monitor_start() function, the HVD_monitor_params::raster_release_fn field should be set to the rstore_raster_release function pointer, the HVD_monitor_params::recovery_filter_fn field should be set to the rstore_recovery_filter function pointer, and the HVD_monitor_params::raster_purge_fn field should be set to the rstore_raster_purge function pointer.

Before calling hvd_output_page(), the hvd_output_page_params::raster_description_fn field should be set to the rstore_raster_description function pointer, hvd_output_page_params::element_raster_open should be set to the rstore_element_raster_open function pointer, hvd_output_page_params::element_raster_map should be set to the rstore_element_raster_map function pointer, and hvd_output_page_params::element_raster_close should be set to the rstore_element_raster_close function pointer.

Using shared memory framebuffers for eHVD

To use shared memory framebuffers for storage and output of eHVD elements, the libHVD event monitor needs to be configured to use the shared memory framebuffer raster release and recovery functions, and the HVD output function should be called with the shared memory framebuffer access functions.

Before calling the libHVD HVD_monitor_start() function, the HVD_monitor_params::cache_fns field should be set to the return value of shmfb_HVD_cache_fns(). The HVD_monitor_params::raster_release_fn field should be set to the shmfb_raster_release function pointer, and the HVD_monitor_params::recovery_filter_fn field should be set to the shmfb_recovery_filter function pointer.

Before calling hvd_output_page(), the hvd_output_page_params::raster_description_fn field should be set to the shmfb_raster_description function pointer, hvd_output_page_params::element_raster_open should be set to the shmfb_element_raster_open function pointer, hvd_output_page_params::element_raster_map should be set to the shmfb_element_raster_map function pointer, and hvd_output_page_params::element_raster_close should be set to the shmfb_element_raster_close function pointer.

Enumeration Type Documentation

anonymous enum

anonymous enum

Bitmask of options for the hvd_output_page_params::progress field.

Enumerator
HVD_LOG_TIMING	Log separation and page combined compositing and output timing information on MON_CHANNEL_PROGRESS.

Function Documentation

hvd_output_page()

HVD_result hvd_output_page	(	const struct HVD_page_output *	page,
		hvd_output_page_params *	params
	)

Common support callback function for raster backends implementing libHVD to output an HVD page.

Parameters

[in]	page	The output page description from libHVD.
[in,out]	params	Callback functions and parameter data.

Return values

HVD_SUCCESS

The page was output successfully

Returns

One of the HVD_ERROR_* error codes, or any other return value greater than MON_CLASS_ERROR is an error UID. HVD_ERROR_* codes should be translated to monitor UID errors using HVD_result_translate(). The error subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

memfb_element_raster_close()

void memfb_element_raster_close	(	void *	context,
		void *	elementRaster
	)

Function to use as hvd_output_page_params::element_raster_close when using local memory elements.

The context parameter will previously have been created by shmfb_element_raster_open().

The elementRaster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by hvd_output_page_params::element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

memfb_element_raster_map()

const uint8* memfb_element_raster_map	(	void *	context,
		void *	elementRaster,
		unsigned int *	pstartline,
		unsigned int *	pnlines,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_map when using local memory elements.

The context parameter will previously have been created by memfb_element_raster_open().

The elementRaster parameter will previously have been created by memfb_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in,out]	pstartline	A pointer to the first line of data requested from the element raster. On a successful exit, this is updated to the first line of data represented in the buffer. This may be larger than the first line requested, if the element raster did not store data for the requested start line.
[in,out]	pnlines	A pointer to the number of lines of data requested from the element raster. On a successful exit, this is updated to the number of lines of data represented in the buffer. This may be smaller than the number of lines requested, if the element raster did not have data stored for all of the requested lines.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A pointer to data representing the lines in the updated pstartline and *pnlines range, or NULL if there was an error getting the data. This data is owned by the element, and must not be modified by the client. This pointer remains valid until the next call to hvd_output_page_params::element_raster_map() using the same raster mapping context, or until hvd_output_page_params::element_raster_close() is called.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is either HQN_RESULT_SUCCESS, indicating there was no data in the range requested; or it is a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

If there was no data in the range requested, then NULL is returned, *perr is set to HQN_RESULT_SUCCESS, *pnlines is updated to zero and *pstartline is updated to the end of the requested range.

In all cases the element raster mapping context is still open, and requires closing using hvd_output_page_params::element_raster_close().

memfb_element_raster_open()

void* memfb_element_raster_open	(	void *	elementRaster,
		struct RASTER_PLANE *	plane,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_open when using local memory elements.

The elementRaster parameter will previously have been created by memfb_raster_create().

Parameters

[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in]	plane	A raster plane to map buffers from.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A raster context that will be passed to hvd_output_page_params::element_raster_map(), or NULL on error. If this is non-NULL, a corresponding call to hvd_output_page_params::element_raster_close() will be made after mapping buffers for plane.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is set to a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

memfb_raster_description()

const RasterDescription* memfb_raster_description

(

void *

elementRaster

)

Function to use as hvd_output_page_params::raster_description_fn when using local memory elements.

The elementRaster parameter will previously have been created by memfb_raster_create().

Parameters

[in]

elementRaster

A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

Returns

A packed raster description associated with the raster handle. The internal pointers (including the raster layout) of a packed raster description are invalid. It may be unpacked using RasterDescriptionUnpack() if the pointers need to be accessed.

memfb_raster_release()

void memfb_raster_release	(	HVD_element *	pElement,
		void *	hraster
	)

Function to use as HVD_raster_release_fn callback when using local memory elements.

The hraster parameter will previously have been created by memfb_raster_create().

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().

memfb_recovery_filter()

HqBool memfb_recovery_filter	(	HVD_element *	pElement,
		HVD_recovery_reason_t	reason
	)

Function to use as HVD_recovery_filter_fn callback when using local memory elements.

Parameters

[in]	pElement	The element that might be removed from the cache.
[in]	reason	The reason supplied to the call to HVD_cache_size() or HVD_cache_recover(). This parameter may be used to exclude elements or rasters from low-memory recovery, if they do not contribute to the type of memory requested.

Return values

TRUE	The HVD raster is eligible for purging or removal.
FALSE	The HVD raster is not eligible for purging or removal.

rstore_element_raster_close()

void rstore_element_raster_close	(	void *	context,
		void *	elementRaster
	)

Function to use as hvd_output_page_params::element_raster_close when using raster store elements.

The context parameter will previously have been created by rstore_element_raster_open().

The elementRaster parameter will previously have been created by rstore_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by hvd_output_page_params::element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

rstore_element_raster_map()

const uint8* rstore_element_raster_map	(	void *	context,
		void *	elementRaster,
		unsigned int *	pstartline,
		unsigned int *	pnlines,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_map when using raster store elements.

The context parameter will previously have been created by rstore_element_raster_open().

The elementRaster parameter will previously have been created by rstore_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in,out]	pstartline	A pointer to the first line of data requested from the element raster. On a successful exit, this is updated to the first line of data represented in the buffer. This may be larger than the first line requested, if the element raster did not store data for the requested start line.
[in,out]	pnlines	A pointer to the number of lines of data requested from the element raster. On a successful exit, this is updated to the number of lines of data represented in the buffer. This may be smaller than the number of lines requested, if the element raster did not have data stored for all of the requested lines.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A pointer to data representing the lines in the updated pstartline and *pnlines range, or NULL if there was an error getting the data. This data is owned by the element, and must not be modified by the client. This pointer remains valid until the next call to hvd_output_page_params::element_raster_map() using the same raster mapping context, or until hvd_output_page_params::element_raster_close() is called.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is either HQN_RESULT_SUCCESS, indicating there was no data in the range requested; or it is a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

If there was no data in the range requested, then NULL is returned, *perr is set to HQN_RESULT_SUCCESS, *pnlines is updated to zero and *pstartline is updated to the end of the requested range.

In all cases the element raster mapping context is still open, and requires closing using hvd_output_page_params::element_raster_close().

rstore_element_raster_open()

void* rstore_element_raster_open	(	void *	elementRaster,
		struct RASTER_PLANE *	plane,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_open when using raster store elements.

The elementRaster parameter will previously have been created by rstore_raster_create().

Parameters

[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in]	plane	A raster plane to map buffers from.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A raster context that will be passed to hvd_output_page_params::element_raster_map(), or NULL on error. If this is non-NULL, a corresponding call to hvd_output_page_params::element_raster_close() will be made after mapping buffers for plane.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is set to a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

rstore_raster_description()

const RasterDescription* rstore_raster_description

(

void *

elementRaster

)

Function to use as hvd_output_page_params::raster_description_fn when using raster store elements.

The elementRaster parameter will previously have been created by rstore_raster_create().

Parameters

[in]

elementRaster

A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

Returns

A packed raster description associated with the raster handle. The internal pointers (including the raster layout) of a packed raster description are invalid. It may be unpacked using RasterDescriptionUnpack() if the pointers need to be accessed.

rstore_raster_purge()

size_t rstore_raster_purge	(	HVD_element *	pElement,
		void *	hraster,
		size_t *	recover
	)

Function to use as HVD_raster_purge_fn callback when using raster store elements.

The hraster parameter will previously have been created by rstore_raster_create().

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().
[in,out]	recover	A location where the amount of memory the purge operation still needs to recover is stored. On exit, the raster purge function should update this to the amount that is still needed after compressing, purging to storage, or otherwise reducing memory consumption. The reduction in memory may exceed the amount needed, in which case the raster purge function should set *recover to zero on exit.

Returns

The new size of the raster data after compressing, purging to storage, or otherwise reducing memory consumption.

The purge function, if present, may be called while an element is locked. It must not discard raster data, but may make it slower to access.

rstore_raster_release()

void rstore_raster_release	(	HVD_element *	pElement,
		void *	hraster
	)

Function to use as HVD_raster_release_fn callback when using raster store elements.

The hraster parameter will previously have been created by rstore_raster_create().

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().

rstore_recovery_filter()

HqBool rstore_recovery_filter	(	HVD_element *	pElement,
		HVD_recovery_reason_t	reason
	)

Function to use as HVD_recovery_filter_fn callback when using raster store elements.

Parameters

[in]	pElement	The element that might be removed from the cache.
[in]	reason	The reason supplied to the call to HVD_cache_size() or HVD_cache_recover(). This parameter may be used to exclude elements or rasters from low-memory recovery, if they do not contribute to the type of memory requested.

Return values

TRUE	The HVD raster is eligible for purging or removal.
FALSE	The HVD raster is not eligible for purging or removal.

shmfb_element_raster_close()

void shmfb_element_raster_close	(	void *	context,
		void *	elementRaster
	)

Function to use as hvd_output_page_params::element_raster_close when using shared memory elements.

The context parameter will previously have been created by shmfb_element_raster_open().

The elementRaster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by hvd_output_page_params::element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

shmfb_element_raster_map()

const uint8* shmfb_element_raster_map	(	void *	context,
		void *	elementRaster,
		unsigned int *	pstartline,
		unsigned int *	pnlines,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_map when using shared memory elements.

The context parameter will previously have been created by shmfb_element_raster_open().

The elementRaster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]	context	A raster mapping context previously returned by element_raster_open().
[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in,out]	pstartline	A pointer to the first line of data requested from the element raster. On a successful exit, this is updated to the first line of data represented in the buffer. This may be larger than the first line requested, if the element raster did not store data for the requested start line.
[in,out]	pnlines	A pointer to the number of lines of data requested from the element raster. On a successful exit, this is updated to the number of lines of data represented in the buffer. This may be smaller than the number of lines requested, if the element raster did not have data stored for all of the requested lines.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A pointer to data representing the lines in the updated pstartline and *pnlines range, or NULL if there was an error getting the data. This data is owned by the element, and must not be modified by the client. This pointer remains valid until the next call to hvd_output_page_params::element_raster_map() using the same raster mapping context, or until hvd_output_page_params::element_raster_close() is called.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is either HQN_RESULT_SUCCESS, indicating there was no data in the range requested; or it is a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

If there was no data in the range requested, then NULL is returned, *perr is set to HQN_RESULT_SUCCESS, *pnlines is updated to zero and *pstartline is updated to the end of the requested range.

In all cases the element raster mapping context is still open, and requires closing using hvd_output_page_params::element_raster_close().

shmfb_element_raster_open()

void* shmfb_element_raster_open	(	void *	elementRaster,
		struct RASTER_PLANE *	plane,
		HqnResult *	perr
	)

Function to use as hvd_output_page_params::element_raster_open when using shared memory elements.

The elementRaster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]	elementRaster	A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.
[in]	plane	A raster plane to map buffers from.
[out]	perr	A location in which an error code is stored, if the raster context could not be acquired or created.

Returns

A raster context that will be passed to hvd_output_page_params::element_raster_map(), or NULL on error. If this is non-NULL, a corresponding call to hvd_output_page_params::element_raster_close() will be made after mapping buffers for plane.

If the pointer returned is non-NULL, then *perr is not modified. If the pointer returned is NULL, then *perr is set to a code greater than MON_CLASS_ERROR indicating the error that occurred. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

shmfb_HVD_cache_fns()

HVD_cache_fns* shmfb_HVD_cache_fns

(

void

)

Return cache functions to use for shared memory elements with libHVD.

The pointer returned should be stored in the HVD_monitor_params::cache_fns field before calling HVD_monitor_start(), or the functions unpacked and stored in individual fields of HVD_cache_params before calling HVD_cache_create().

shmfb_raster_description()

const RasterDescription* shmfb_raster_description

(

void *

elementRaster

)

Function to use as hvd_output_page_params::raster_description_fn when using shared memory elements.

The elementRaster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]

elementRaster

A raster handle previously attached to an HVD element using one of libHVD's HVD_tracker_element_add_raster(), HVD_element_add_raster() or HVD_monitor_add_raster() functions.

Returns

A packed raster description associated with the raster handle. The internal pointers (including the raster layout) of a packed raster description are invalid. It may be unpacked using RasterDescriptionUnpack() if the pointers need to be accessed.

shmfb_raster_release()

void shmfb_raster_release	(	HVD_element *	pElement,
		void *	hraster
	)

Function to use as HVD_raster_release_fn callback when using shared memory elements.

The hraster parameter will previously have been created by shmfb_raster_create().

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().

shmfb_recovery_filter()

HqBool shmfb_recovery_filter	(	HVD_element *	pElement,
		HVD_recovery_reason_t	reason
	)

Function to use as HVD_recovery_filter_fn callback when using shared memory elements.

Parameters

[in]	pElement	The element that might be removed from the cache.
[in]	reason	The reason supplied to the call to HVD_cache_size() or HVD_cache_recover(). This parameter may be used to exclude elements or rasters from low-memory recovery, if they do not contribute to the type of memory requested.

Return values

TRUE	The HVD raster is eligible for purging or removal.
FALSE	The HVD raster is not eligible for purging or removal.