HVD cache API functions. More...

#include "hvdcache.h"

Data Fields
size_t	size
	The size of this structure.

HVD_result(*	create )(const HVD_cache_params params, HVD_cache *ppCache)
	The client's cache create function. The default is HVD_cache_create(). More...

void(*	destroy )(HVD_cache **pcache, HqBool force)
	The client's cache destroy function. The default is HVD_cache_destroy(). More...

void(*	get_ids )(const HVD_cache cache, const uint8 pCacheId, const uint8 *pSetupId)
	Getter for the cache's cache ID and setup ID. The default is HVD_cache_get_ids(). More...

HVD_result(*	element_add )(HVD_cache cache, const SWMSG_RR_ELEMENT_DEFINE eldef, HVD_element **ppElement)

HVD_element (	element_lookup )(HVD_cache *cache, const uint8 id[16])

void(*	element_release )(HVD_element **ppElement)

HVD_result(*	element_lock )(HVD_element *pElement)

HVD_result(*	element_unlock )(HVD_element *pElement)

int(*	element_hits )(HVD_element *pElement, int delta)

HVD_result(*	element_pending )(HVD_element *pElement)

void(*	element_set_data )(HVD_element pElement, void data)

void (	element_get_data )(const HVD_element *pElement)

HVD_result(*	element_add_raster )(HVD_element pElement, unsigned int nExpected, void hraster, size_t size)
	Function to add a raster to an element. The default is HVD_element_add_raster(). More...

HVD_result(*	element_has_rasters )(const HVD_element element, unsigned int nRasters, unsigned int *nRastersExpected)

void (	element_get_raster )(const HVD_element *element, unsigned int index)

void(*	element_get_extent )(const HVD_element *element, int32 extent[4])

Detailed Description

HVD cache API functions.

These functions are used to interface the HVD event monitor and tracker implementation to the HVD cache. If this API pointer is passed in the HVD_monitor_params or HVD_tracker_params, the HVD cache functions can be intercepted or replaced. The API pointer and function pointers must remain valid for the lifetime of the event monitor.

Field Documentation

◆ create

HVD_result(* HVD_cache_fns::create) (const HVD_cache_params *params, HVD_cache **ppCache)

The client's cache create function. The default is HVD_cache_create().

Parameters

[in]	params	The parameters for this HVD cache instance.
[out]	ppCache	A location to store the HVD cache created.

Return values

HVD_SUCCESS	The HVD cache instance was found or created successfully, and a handle was stored in ppCache. If this function succeeds, HVD_cache_destroy() must be called to destroy it when the connection is disconnected.
HVD_ERROR_INVALID_PARAMS	The HVD cache instance could not be created because the parameters were invalid.
HVD_ERROR_NO_MEMORY	The HVD cache instance could not be created because of memory exhaustion.

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 of the params fields must match in order to return an existing cache instance. If the setup_id is empty, then existing cache instances will never be returned.

◆ destroy

void(* HVD_cache_fns::destroy) (HVD_cache **pcache, HqBool force)

The client's cache destroy function. The default is HVD_cache_destroy().

Parameters

[in,out]	ppCache	The location to find the cache instance. This will be reset to NULL on exit.
[in]	force	Force destruction of the cache content and structures. This option is intended for use in error conditions or at shutdown, to ensure shared resources are recovered.

◆ element_add

HVD_result(* HVD_cache_fns::element_add) (HVD_cache *cache, const SWMSG_RR_ELEMENT_DEFINE *eldef, HVD_element **ppElement)

Function to define elements, adding them to the cache. The default is HVD_cache_element_add().

Parameters

[in]	cache	The cache instance to add the element to
[in]	elementdef	The definition of the HVD element to add. If the extent of this element is (0,0,0,0), then the element ID is known, but the extent is not yet known. A further call to update the element will be expected in future.
[out]	ppElement	A location to store a reference to the element. This may be NULL, in which case no reference is stored. If non-NULL and the function is successful, then any existing element reference at this location is released, and the element reference stored must be released when the caller has done with it. If non-NULL and this function is not successful, no change is made to any existing element reference at this location.

Return values

HVD_SUCCESS	The element was added to the cache successfully.
HVD_ERROR_NO_MEMORY	The element could not be added to the cache, because the cache could not allocate memory.
HVD_ERROR_ELEMENT_MISMATCH	The element was already found in the cache, but had a different extent.

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.

◆ element_add_raster

HVD_result(* HVD_cache_fns::element_add_raster) (HVD_element *pElement, unsigned int nExpected, void *hraster, size_t size)

Function to add a raster to an element. The default is HVD_element_add_raster().

Parameters

[in]	pElement	The element to add a raster for. This function does not change the reference count for the element.
[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. Raster release calls 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.

◆ element_get_data

void*(* HVD_cache_fns::element_get_data) (const HVD_element *pElement)

Function to get data associated with an element. The default is HVD_element_get_data().

Parameters

[in] pElement The element to get element information for. This function does not change the reference count for the element.

Returns: The data attached to the element by the HVD_element_set_data() function.

◆ element_get_extent

void(* HVD_cache_fns::element_get_extent) (const HVD_element *element, int32 extent[4])

Function to get the extent of an element. The default is HVD_element_get_extent().

Parameters

[in]	pElement	The element to get raster information for. This function does not change the reference count for the element.
[out]	extent	An array updated with the device space extent of the element.

◆ element_get_raster

void*(* HVD_cache_fns::element_get_raster) (const HVD_element *element, unsigned int index)

Function to get raster data added to an element. The default is HVD_element_get_raster().

Parameters

[in]	pElement	The element to get raster information for. This function does not change the reference count for the element.
[in]	index	An index into the rasters in the element. This must be less than the nRasters output value of HVD_element_has_rasters().

Returns: The raster handle for raster index.

◆ element_has_rasters

HVD_result(* HVD_cache_fns::element_has_rasters) (const HVD_element *element, unsigned int *nRasters, unsigned int *nRastersExpected)

Function to determine if an element has all of its raster data. The default is HVD_element_has_rasters().

Parameters

[in]	element	The element to test. This function does not change the reference count for the element.
[out]	nRasters	If non-NULL, a location to store the number of rasters currently ready. This is updated even if not all of the rasters have been received.
[out]	nRastersExpected	If non-NULL, a location to store the number of rasters currently expected. This is updated even if not all of the rasters have been received.

Return values

HVD_SUCCESS	All of the rasters for the element have been received.
HVD_SUCCESS_INCOMPLETE	More rasters are expected for this element.
HVD_ERROR_NO_ELEMENT	There was no element to check for rasters.
HVD_ERROR_*	There was an error with element or raster creation, this element will never have all of its rasters present.

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 HVD cache always expects at least one raster per element, so if there have been no calls to HVD_element_add_raster() and no errors, this function will return HVD_SUCCESS_INCOMPLETE.

◆ element_hits

int(* HVD_cache_fns::element_hits) (HVD_element *pElement, int delta)

Function to update the element hit count. The default is HVD_element_hits().

Parameters

[in]	pElement	The element to change the hit count on. This function does not change the reference count for the element.
[in]	delta	The change in the number of hits

Returns: The current hit count of the element, or a negative number for an error (MININT for no element, otherwise underflow; the caller probably doesn't care which, either indicates a programming error).

◆ element_lock

HVD_result(* HVD_cache_fns::element_lock) (HVD_element *pElement)

Function to lock elements, preventing purging of data. The default is HVD_element_lock().

Parameters

[in] pElement The element to lock. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was locked successfully.
HVD_ERROR_NO_ELEMENT	There was no element to lock.
HVD_ERROR_NOT_PENDING	The element was not pending; no rasters have been requested for it. The element was not locked.

◆ element_lookup

HVD_element*(* HVD_cache_fns::element_lookup) (HVD_cache *cache, const uint8 id[16])

Function to lookup and update existing elements in cache. The default is HVD_cache_element_lookup().

Parameters

[in]	cache	The cache containing element id.
[in]	id	The ID of the element to lookup.

Returns: A pointer to the element, or NULL if the element was not discovered. If the element is discovered, a reference to it is acquired. This reference must be released by passing the element to a function that releases the reference.

◆ element_pending

HVD_result(* HVD_cache_fns::element_pending) (HVD_element *pElement)

Function to mark an element as pending, awaiting rasters. The default is HVD_element_pending().

Parameters

[in] pElement The element to mark pending. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was marked pending.
HVD_ERROR_NO_ELEMENT	There was no element to mark.
HVD_ERROR_ALREADY_PENDING	The element was already pending.

◆ element_release

void(* HVD_cache_fns::element_release) (HVD_element **ppElement)

Function to release a reference to an elements. The default is HVD_element_release().

Parameters

[in,out] ppElement The reference to the element to release. This function is safe to call if *ppElement is NULL.

◆ element_set_data

void(* HVD_cache_fns::element_set_data) (HVD_element *pElement, void *data)

Function to set data associated with an element. The default is HVD_element_set_data().

Parameters

[in]	pElement	The element to set element information for. This function does not change the reference count for the element.
[in]	data	The data to set in the element

◆ element_unlock

HVD_result(* HVD_cache_fns::element_unlock) (HVD_element *pElement)

Function to unlock elements, allowing purging of data. The default is HVD_element_unlock().

Parameters

[in] pElement The element to unlock. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was unlocked.
HVD_ERROR_NO_ELEMENT	There was no element to unlock
HVD_ERROR_NOT_LOCKED	The element was not previously locked.

◆ get_ids

void(* HVD_cache_fns::get_ids) (const HVD_cache *cache, const uint8 **pCacheId, const uint8 **pSetupId)

Getter for the cache's cache ID and setup ID. The default is HVD_cache_get_ids().

Parameters

[in]	cache	The cache instance to get the IDs for.
[out]	pCacheId	A location to store the cache ID, or NULL if it should not be returned.
[out]	pSetupId	A location to store the setup ID, or NULL if it should not be returned.

This may be used for debug output, or to construct file or object names unique to the cache or its elements.

The documentation for this struct was generated from the following file:

lib/interface/hvdcache.h

Data Fields

Detailed Description

Field Documentation

◆ create

◆ destroy

◆ element_add

◆ element_add_raster

◆ element_get_data

◆ element_get_extent

◆ element_get_raster

◆ element_has_rasters

◆ element_hits

◆ element_lock

◆ element_lookup

◆ element_pending

◆ element_release

◆ element_set_data

◆ element_unlock

◆ get_ids