hvdtracker.h File Reference

HVD page and element define tracker. More...

#include "std.h"
#include "rrevents.h"
#include "swmemapi.h"
#include "timelineapi.h"
#include "hvdlib.h"
#include "hvdcache.h"

Data Structures
struct	HVD_element_output
	Element information structure for the page output callback function. The lifetime of this structure is the page output function call: any data that the backend wishes to store for a longer duration must be copied. More...
struct	HVD_page_output
	Page information for the page output callback function. More...
struct	HVD_tracker_params
	Parameters for the HVD tracker. More...
struct	HVD_tracker_fns
	HVD tracker API functions. More...

Macros
#define	HVD_TRACKER_PARAMS_INIT
	Default initialiser for HVD tracker params.

Typedefs
typedef struct HVD_element_output	HVD_element_output
	Element information structure for the page output callback function. The lifetime of this structure is the page output function call: any data that the backend wishes to store for a longer duration must be copied.
typedef struct HVD_page_output	HVD_page_output
	Page information for the page output callback function. More...
typedef HVD_result()	HVD_page_output_fn(HVD_page_output *output)
	Function type for page output callback. This is called when all of the elements for a page are ready and present in the cache. More...
typedef HqBool()	HVD_interrupt_poll_fn(void)
	Function type for interrupt polls. This is called when waiting for all of the rasters for all elements of a page to be delivered to the cache. More...
typedef struct HVD_tracker_params	HVD_tracker_params
	Parameters for the HVD tracker.

Functions
HVD_result	HVD_tracker_create (const HVD_tracker_params *params, const SWMSG_RR_PAGE_DEFINE *pagedef, HVD_tracker **ppTracker)
	Create an HVD page and element define tracker. More...
void	HVD_tracker_destroy (HVD_tracker **ppTracker)
	Destroy an HVD page and element tracker. More...
HVD_result	HVD_tracker_page_ready (HVD_tracker *tracker, uint32 page_index)
	Indicate that all elements for a page are in the cache or will be in the cache soon. More...
void	HVD_tracker_abort_job (HVD_tracker *tracker, sw_tl_ref jobTimeline)
	Indicate that a job was aborted. More...
HVD_result	HVD_tracker_element_add_raster (HVD_tracker *tracker, const uint8 id[16], unsigned int nExpected, void *hraster, size_t size)
	Inform the HVD tracker that we are adding raster data for an HVD element. More...

Detailed Description

HVD page and element define tracker.

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.

Typedef Documentation

HVD_interrupt_poll_fn

typedef HqBool() HVD_interrupt_poll_fn(void)

Function type for interrupt polls. This is called when waiting for all of the rasters for all elements of a page to be delivered to the cache.

Return values

TRUE	Stop waiting for page rasters.
FALSE	Continue waiting for page rasters.

HVD_page_output

typedef struct HVD_page_output HVD_page_output

Page information for the page output callback function.

The page output callback function is called when all of the rasters for all elements of a page are ready and present in the cache. The lifetime of this structure is the page output function call: any data that the backend wishes to store for a longer duration must be copied. The callee can modify the data in this structure and the elements and rasterData sub-structures, but any changes will not be reflected in the HVD cache or tracker after the page output function call finishes (for example, the callee may wish to sort rasters within a separation into a particular order).

HVD_page_output_fn

typedef HVD_result() HVD_page_output_fn(HVD_page_output *output)

Function type for page output callback. This is called when all of the elements for a page are ready and present in the cache.

Parameters

[in]

output

The page details to output. The lifetime of this structure is the duration of this callback: any data that the backend wishes to store for a longer duration must be copied.

Return values

HVD_SUCCESS

(0) The page was output successfully

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

Function Documentation

HVD_tracker_abort_job()

void HVD_tracker_abort_job	(	HVD_tracker *	tracker,
		sw_tl_ref	jobTimeline
	)

Indicate that a job was aborted.

Parameters

[in]	tracker	The tracker to test the aborted job's timeline against.
[in]	jobTimeline	The job timeline that is being aborted.

This will break out of any calls to HVD_tracker_page_ready() that are waiting for a page raster, returning a failure for those calls.

HVD_tracker_create()

HVD_result HVD_tracker_create	(	const HVD_tracker_params *	params,
		const SWMSG_RR_PAGE_DEFINE *	pagedef,
		HVD_tracker **	ppTracker
	)

Create an HVD page and element define tracker.

Parameters

[in]	params	The parameters for this HVD tracker instance.
[in]	pagedef	The page definition to track.
[out]	ppTracker	A location to store the HVD tracker created.

Return values

HVD_SUCCESS	The tracker was created, and a handle was stored in ppTracker. If this function succeeds, HVD_tracker_destroy() must be called to destroy it when the connection is disconnected or when a new page definition replaces this one.
HVD_CACHE_NO_MEMORY	The HVD tracker could not be created because of memory exhaustion.
HVD_CACHE_INVALID_PARAMS	The HVD tracker could not be created because the parameters were invalid.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

HVD_tracker_destroy()

void HVD_tracker_destroy

(

HVD_tracker **

ppTracker

)

Destroy an HVD page and element tracker.

Parameters

[in,out]

ppTracker

The location to find the tracker. This will be reset to NULL on exit.

HVD_tracker_element_add_raster()

HVD_result HVD_tracker_element_add_raster	(	HVD_tracker *	tracker,
		const uint8	id[16],
		unsigned int	nExpected,
		void *	hraster,
		size_t	size
	)

Inform the HVD tracker that we are adding raster data for an HVD element.

Parameters

[in]	tracker	The tracker that uses the element.
[in]	id	The ID of the element to append the raster to.
[in]	nExpected	The total number of rasters that we expect to add for this element. In general, this number should be set on the first call of this function for an element, and the same value should be used for all calls on the same element thereafter. It is possible to revise the expected number downwards if some rasters are omitted, or upwards if more rasters are added, but it should never be less than the number of rasters added (including this one), and it should never be increased after all of the expected rasters have been received. When all of the rasters that are expected have been received, the element is marked as ready for use, and pages using this element may be output immediately.
[in]	hraster	A raster handle. This is used to identify the raster data when the page is output, or the element is destroyed.
[in]	size	The size of the raster data stored. This is counted against the cache limit.

Return values

HVD_SUCCESS	The raster handle was added to the element successfully. This was the final raster expected.
HVD_SUCCESS_INCOMPLETE	The raster handle was added to the element successfully. This was not the final raster expected.
HVD_ERROR_NO_ELEMENT	There was no element to add the raster to.
HVD_ERROR_EXCESS_RASTERS	The number of rasters is more than the number expected, including the raster currently being added.
HVD_ERROR_NO_MEMORY	The raster handle could not be added to the element, because the cache could not allocate memory.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

All elements expect to have at least one raster, and will not be marked as complete until nExpected rasters have been delivered.

If the return value is HVD_SUCCESS or HVD_SUCCESS_INCOMPLETE, the raster handle has been retained by the HVD element, and must remain valid until the HVD cache calls the raster release callback function with the handle. This will happen during the HVD disconnect call if rendering is aborted, or when the element is purged from the cache.

For any other return value, the caller should dispose of the raster data.

Raster handles will be provided to the output function callback, so the client can identify all of the rasters for each element output.

HVD_tracker_page_ready()

HVD_result HVD_tracker_page_ready	(	HVD_tracker *	tracker,
		uint32	page_index
	)

Indicate that all elements for a page are in the cache or will be in the cache soon.

Parameters

[in]	tracker	The tracker to test the aborted job's timeline against.
[in]	page_index	The page index (cumulative over across all page defines for the job).

Return values

HVD_SUCCESS	The page was output.
HVD_SUCCESS_ALREADY	The page has been output already. This may happen if the HVD_tracker_params::allow_early_output field was TRUE when the tracker was created.
HVD_ERROR_NO_PAGE	The page index is not valid for the tracker.
HVD_ERROR_NO_ELEMENT	An element of the page was not defined.
HVD_ERROR_NO_MEMORY	The page output could not be performed because of memory exhaustion.
HVD_ERROR_ABORTED	The wait for all page element rasters was aborted by calling HVD_tracker_abort().
HVD_ERROR_INTERRUPTED	The wait for all page element rasters was interrupted by the interrupt poll function.
HVD_ERROR_OUTPUT_FAILED	The page output function was called, but returned FALSE.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

The tracker will respond by waiting for the elements of the page to be ready, and will call the page output function supplied when the tracker was created (if it exists).