User Facing Reference API

The Public Reference API. More...

Macros
#define	VX_MAX_REFERENCE_NAME   (64)
	Defines the length of the reference name string, including the trailing zero.

Enumerations
enum	vx_reference_attribute_e {   VX_REFERENCE_COUNT = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_REFERENCE) + 0x0 ,   VX_REFERENCE_TYPE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_REFERENCE) + 0x1 ,   VX_REFERENCE_NAME = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_REFERENCE) + 0x2 }
	The reference attributes list. More...

Functions
VX_API_ENTRY vx_status VX_API_CALL	vxQueryReference (vx_reference ref, vx_enum attribute, void *ptr, vx_size size)
	Queries any reference type for some basic information like count or type.
VX_API_ENTRY vx_status VX_API_CALL	vxReleaseReference (vx_reference *ref_ptr)
	Releases a reference. The reference may potentially refer to multiple OpenVX objects of different types. This function can be used instead of calling a specific release function for each individual object type (e.g. vxRelease<object>). The object will not be destroyed until its total reference count is zero.
VX_API_ENTRY vx_status VX_API_CALL	vxRetainReference (vx_reference ref)
	Increments the reference counter of an object This function is used to express the fact that the OpenVX object is referenced multiple times by an application. Each time this function is called for an object, the application will need to release the object one additional time before it can be destructed.
VX_API_ENTRY vx_status VX_API_CALL	vxSetReferenceName (vx_reference ref, const vx_char *name)
	Name a reference.

Detailed Description

The Public Reference API.

Macro Definition Documentation

VX_MAX_REFERENCE_NAME

#define VX_MAX_REFERENCE_NAME   (64)

#include <vx.h>

Defines the length of the reference name string, including the trailing zero.

See also

vxSetReferenceName

Enumeration Type Documentation

vx_reference_attribute_e

enum vx_reference_attribute_e

#include <vx_types.h>

The reference attributes list.

Enumerator
VX_REFERENCE_COUNT	Returns the reference count of the object. Read-only. Use a vx_uint32 parameter.
VX_REFERENCE_TYPE	Returns the vx_type_e of the reference. Read-only. Use a vx_enum parameter.
VX_REFERENCE_NAME	Used to query the reference for its name. Read-write. Use a *vx_char parameter.

Function Documentation

vxQueryReference()

VX_API_ENTRY vx_status VX_API_CALL vxQueryReference	(	vx_reference	ref,
		vx_enum	attribute,
		void *	ptr,
		vx_size	size )

#include <vx_api.h>

Queries any reference type for some basic information like count or type.

Parameters

[in]	ref	The reference to query.
[in]	attribute	The value for which to query. Use vx_reference_attribute_e.
[out]	ptr	The location at which to store the resulting value.
[in]	size	The size in bytes of the container to which ptr points.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	ref is not a valid vx_reference reference.

vxReleaseReference()

VX_API_ENTRY vx_status VX_API_CALL vxReleaseReference

(

vx_reference *

ref_ptr

)

#include <vx_api.h>

Releases a reference. The reference may potentially refer to multiple OpenVX objects of different types. This function can be used instead of calling a specific release function for each individual object type (e.g. vxRelease<object>). The object will not be destroyed until its total reference count is zero.

Note

After returning from this function the reference is zeroed.

Parameters

[in]

ref_ptr

The pointer to the reference of the object to release.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	ref_ptr is not a valid vx_reference reference.

vxRetainReference()

VX_API_ENTRY vx_status VX_API_CALL vxRetainReference

(

vx_reference

ref

)

#include <vx_api.h>

Increments the reference counter of an object This function is used to express the fact that the OpenVX object is referenced multiple times by an application. Each time this function is called for an object, the application will need to release the object one additional time before it can be destructed.

Parameters

[in]

ref

The reference to retain.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	ref is not a valid vx_reference reference.

vxSetReferenceName()

VX_API_ENTRY vx_status VX_API_CALL vxSetReferenceName	(	vx_reference	ref,
		const vx_char *	name )

#include <vx_api.h>

Name a reference.

This function is used to associate a name to a referenced object. This name can be used by the OpenVX implementation in log messages and any other reporting mechanisms.

The OpenVX implementation will not check if the name is unique in the reference scope (context or graph). Several references can then have the same name.

Parameters

[in]	ref	The reference to the object to be named.
[in]	name	Pointer to the '\0' terminated string that identifies the referenced object. The string is copied by the function so that it stays the property of the caller. NULL means that the reference is not named. The length of the string shall be lower than VX_MAX_REFERENCE_NAME bytes.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	ref is not a valid vx_reference reference.