|
Harlequin RIP SDK
|
|
|
|
Harlequin RIP SDK
|
|
HVD tracker API functions. More...
#include "hvdtracker.h"
Data Fields | |
| size_t | size |
| The size of this structure. | |
| HVD_result(* | create )(const HVD_tracker_params *params, const SWMSG_RR_PAGE_DEFINE *msg, HVD_tracker **ppTracker) |
| The client's tracker create function. The default is HVD_tracker_create(). More... | |
| void(* | destroy )(HVD_tracker **ppTracker) |
| The client's tracker destroy function. The default is HVD_tracker_destroy(). More... | |
| HVD_result(* | page_ready )(HVD_tracker *tracker, uint32 page_index) |
| Function to process actions when that a page is ready for output. The default is HVD_tracker_page_ready(). More... | |
| HVD_result(* | element_add_raster )(HVD_tracker *tracker, const uint8 id[16], unsigned int nExpected, void *hraster, size_t size) |
| Function to add a raster to an element. The default is HVD_tracker_element_add_raster(). More... | |
| void(* | abort_job )(HVD_tracker *tracker, sw_tl_ref jobTimeline) |
| Function to process job aborts. The default is HVD_tracker_abort_job(). More... | |
HVD tracker API functions.
These functions are used to interface the HVD event monitor implementation to the HVD tracker. If this API pointer is passed in the HVD_monitor_params, the HVD tracker functions can be intercepted or replaced. The API pointer and function pointers must remain valid for the lifetime of the event monitor.
| void(* HVD_tracker_fns::abort_job) (HVD_tracker *tracker, sw_tl_ref jobTimeline) |
Function to process job aborts. The default is HVD_tracker_abort_job().
| [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_result(* HVD_tracker_fns::create) (const HVD_tracker_params *params, const SWMSG_RR_PAGE_DEFINE *msg, HVD_tracker **ppTracker) |
The client's tracker create function. The default is HVD_tracker_create().
| [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. |
| 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. |
| void(* HVD_tracker_fns::destroy) (HVD_tracker **ppTracker) |
The client's tracker destroy function. The default is HVD_tracker_destroy().
| [in,out] | ppTracker | The location to find the tracker. This will be reset to NULL on exit. |
| HVD_result(* HVD_tracker_fns::element_add_raster) (HVD_tracker *tracker, const uint8 id[16], unsigned int nExpected, void *hraster, size_t size) |
Function to add a raster to an element. The default is HVD_tracker_element_add_raster().
| [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. |
| 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. |
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_result(* HVD_tracker_fns::page_ready) (HVD_tracker *tracker, uint32 page_index) |
Function to process actions when that a page is ready for output. The default is HVD_tracker_page_ready().
| [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). |
| 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. |
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).