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"
#include "hvdpageoutput.h"

Data Structures
struct	HVD_tracker_params
	Parameters for the HVD tracker. More...

Macros
#define	HVD_TRACKER_PARAMS_INIT
	Default initializer for HVD tracker params.

Typedefs
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 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...
void	HVD_tracker_page_ready (HVD_tracker *tracker, uint32 page_index, HVD_page_completion_fn *completion_fn, void *completion_data)
	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, const char *rasterId, size_t size)
	Inform the HVD tracker that we are adding raster data for an HVD element. More...
HVD_result	HVD_details_from_page_output (const HVD_page_output *output, HVD_tracker **ppTracker, HVD_cache **ppCache, const HVD_cache_fns **ppCacheFns, void **ppStore)
	Inquiry function usable by clients to get tracker, cache, and/or store pointers back from the page output data. This may be necessary to get a local proxy context when sending data to a remote client. 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_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.

Return values

HVD_SUCCESS	(0) The page was output successfully. The page output function should not call HVD_page_output::completion_fn().
HVD_SUCCESS_INCOMPLETE	The page will be output asynchronously. The output function has copied all necessary information to output the page asynchronously. The page output function must ensure that HVD_page_output::completion_fn() is called with HVD_page_output::completion_data as the first argument when the output is complete or fails.

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 page output function should not call HVD_page_output::completion_fn().

Function Documentation

HVD_details_from_page_output()

HVD_result HVD_details_from_page_output	(	const HVD_page_output *	output,
		HVD_tracker **	ppTracker,
		HVD_cache **	ppCache,
		const HVD_cache_fns **	ppCacheFns,
		void **	ppStore
	)

Inquiry function usable by clients to get tracker, cache, and/or store pointers back from the page output data. This may be necessary to get a local proxy context when sending data to a remote client.

Parameters

[in]	output	The page output structure passed to HVD_tracker_params::page_output_fn().
[out]	ppTracker	An optional location to return the HVD tracker reference used to output this page.
[out]	ppCache	An optional location to return the HVD cache reference used to output this page.
[out]	ppCacheFns	An optional location to return the HVD cache functions used in the HVD cache.
[out]	ppStore	An optional location to return the HVD cache element store used to output this page.

Return values

HVD_SUCCESS	All of the object references requested have been stored in their respective locations.
HVD_ERROR_INVALID_PARAMS	The page output parameter was invalid, none of the object references requested were extracted.

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,
		const char *	rasterId,
		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]	rasterId	A raster handle identifier. This is a zero-terminated string used when the HVD cache is hosted in a different Scalable RIP HVD process. The raster handle identifier is passed to the process hosting the HVD cache, to allow it to identify and retain the raster, and may be passed to other processes to allow them to identify and access the raster data for output. For local HVD cache implementations, this may be NULL.
[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()

void HVD_tracker_page_ready	(	HVD_tracker *	tracker,
		uint32	page_index,
		HVD_page_completion_fn *	completion_fn,
		void *	completion_data
	)

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).
[in]	completion_fn	A page completion function. This function will be called to report the result of outputting the page. If page output is asynchronous, this function may be called before returning from HVD_tracker_page_ready(). If page output is synchronous, this function must be called before returning from HVD_tracker_page_ready(). The completion function will issue the SWEVT_RR_PAGE_COMPLETE event that reports page completion to the RIP, if necessary. See HVD_page_completion_fn for the meaning of the status parameter values passed to completion_fn.

Parameters

[in]

completion_data

An opaque data pointer for the page completion function. This data pointer must be passed to completion_fn when it is called.

The tracker will queue an operation to wait for the elements of the page to be ready, and then call the page output function supplied when the tracker was created (if it exists).