Reference APIs

Detailed Description

APIs for handling references, handles, and data pointers.

Functions
vx_bool	tivxIsReferenceVirtual (vx_reference ref)
	Utility function to check if the given reference is virtual or not. More...
vx_reference	tivxGetReferenceParent (vx_reference child_ref)
	Utility function to extract the parent reference from an element. More...
VX_API_ENTRY vx_status VX_API_CALL	tivxSetReferenceAttribute (vx_reference ref, vx_enum attribute, const void *ptr, vx_size size)
	Sets reference attributes for the below enums: TIVX_REFERENCE_TIMESTAMP. More...
VX_API_ENTRY vx_bool VX_API_CALL	tivxIsReferenceMetaFormatEqual (vx_reference ref1, vx_reference ref2)
	Check for equivalence between the meta formats of two reference objects. More...
VX_API_ENTRY vx_status VX_API_CALL	tivxReferenceImportHandle (vx_reference ref, const void *addr[], const uint32_t size[], uint32_t num_entries)
	Updates a reference object with the supplied handles (pointers to memory). More...
VX_API_ENTRY vx_status VX_API_CALL	tivxReferenceExportHandle (const vx_reference ref, void *addr[], uint32_t size[], uint32_t max_num_entries, uint32_t *num_entries)
	Exports the handles from a reference object. More...
VX_API_ENTRY vx_reference VX_API_CALL	tivxCreateReferenceFromExemplar (vx_context context, vx_reference exemplar)
	Create reference from a exemplar object. More...

Function Documentation

tivxIsReferenceVirtual()

vx_bool tivxIsReferenceVirtual

(

vx_reference

ref

)

Utility function to check if the given reference is virtual or not.

Parameters

[in]

ref

Reference to query

Returns

A vx_bool value.

Return values

vx_true_e	The reference is virtual.
vx_false_e	The reference is not virtual.

tivxGetReferenceParent()

vx_reference tivxGetReferenceParent

(

vx_reference

child_ref

)

Utility function to extract the parent reference from an element.

Parameters

[in]

child_ref

Child reference to query

Returns

vx_reference in case of success, else NULL

tivxSetReferenceAttribute()

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

Sets reference attributes for the below enums: TIVX_REFERENCE_TIMESTAMP.

Parameters

[in]	ref	The reference object.
[in]	attribute	The attribute of the reference to be set.
[in]	ptr	The value of the reference attribute to be set.
[in]	size	The size of the value of the reference attribute to be set.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS

if the attribute was set correctly.

tivxIsReferenceMetaFormatEqual()

VX_API_ENTRY vx_bool VX_API_CALL tivxIsReferenceMetaFormatEqual	(	vx_reference	ref1,
		vx_reference	ref2
	)

Check for equivalence between the meta formats of two reference objects.

This API is used to check for equivalence between the meta formats of two reference objects. The function returns true if they are equal and false if not.

Parameters

[in]	ref1	First reference object to be compared.
[in]	ref2	Second reference object to be compared.

Returns

A _vx_bool_e enumeration.

vx_true_e in case of equal meta formats, vx_false else

tivxReferenceImportHandle()

VX_API_ENTRY vx_status VX_API_CALL tivxReferenceImportHandle	(	vx_reference	ref,
		const void *	addr[],
		const uint32_t	size[],
		uint32_t	num_entries
	)

Updates a reference object with the supplied handles (pointers to memory).

Any existing handles in the reference object will be over-written with the new handles provided. No error will be reported. If the caller chooses to preserve the existing handles then the caller should use tivxReferenceExportHandle for retrieving the current handles before invoking this function.

The following conditions regarding 'addr' must be TRUE:

• allocated using appMemAlloc or tivxMemAlloc on OpenVX Host core using the APP_MEM_HEAP_DDR_SHARED or TIVX_MEM_EXTERNAL_SHARED memory region respectively
  • This API ensures that the memory is allocated in the necessary shared memory region which can be used by OpenVX
• freed using appMemFree or tivxMemFree on OpenVX Host core
• memory block is contiguous

Only the following reference object types are supported:

• VX_TYPE_IMAGE (note: subimages of images are not supported; also, subimages of an image will not be retained across export/import)
• VX_TYPE_TENSOR
• VX_TYPE_USER_DATA_OBJECT
• VX_TYPE_ARRAY
• VX_TYPE_DISTRIBUTION
• VX_TYPE_MATRIX
• VX_TYPE_CONVOLUTION
• VX_TYPE_PYRAMID
• TIVX_TYPE_RAW_IMAGE

The memory being imported to an OpenVX reference must adhere to the semantics of how the framework allocates memory. This is of particular note for a few OpenVX objects listed below.

• For VX_TYPE_IMAGE references, multi-plane images shall be imported as a single entry. The reason for this is that the framework allocates multi-plane images as a single contiguous memory buffer. Therefore, if this is exported, it can also be freed as a single contiguous memory buffer rather than as separate buffers.
• For VX_TYPE_PYRAMID objects, each pyramid level is allocated as a separate buffer and thus must be imported as a single entry per level. Additionally, in the case that the pyramid levels are multi-plane images, these entries must be allocated as a single contiguous buffer with a size of all planes of the image.
• For TIVX_TYPE_RAW_IMAGE objects with multiple exposures, these are allocated by the framework as separate buffers and thus must be imported as separate entries.

Please note the important details below on semantics about the usage of the reference import and export. Errors will occur if the below requirements are not adhered to.

• When calling the tivxReferenceExportHandle API on a vx_reference to obtain a handle and subsequently calling the tivxReferenceImportHandle API to import the handle to a separate vx_reference, the two references must be of the same type and have the same meta information. This can be confirmed by using the tivxIsReferenceMetaFormatEqual API.
• The handle exported by the tivxReferenceExportHandle API will only be valid while the originally allocated handle is valid. For example, if a handle is exported from ref1 and imported into ref2, and then ref1 is released access to ref2 will result in attempting to access memory which has already been freed. It is therefore the responsibility of the application to ensure that the original memory allocation lifetime exceeds the lifetime of exported handle.
• In the example in the bullet above, in the case that ref1 must be released prior to ref2, the suggested approach is to import a NULL pointer to ref1, followed by a release of the reference. At this point, ref2 has sole possession of the buffer while ref1 has no buffer dedicated to that reference. An implementation of this approach can be found in the associated test cases located at tiovx/conformance_tests/test_tiovx/test_tivxMem.c.
• If memory has already been allocated to a vx_reference and the tivxReferenceImportHandle API is called on the vx_reference, the previous buffer will be discarded and the vx_reference will now use the imported buffer. A log in the VX_ZONE_INFO log level will be thrown on the console in this scenario to note that a buffer is being overridden. Because this can be a dangerous situation, the tivxReferenceExportHandle API shall be called on the vx_reference in question. The previous buffer can be used as required in the application before ultimately being freed by way of the tivxMemFree API.
• The tivxReferenceExportHandle API and tivxReferenceImportHandle API must not be called if the reference has been enqueued to a vx_graph. This can cause a scenario where the graph overwrites the buffer contents and is thus is not in a state where it can be read by the application.

Finally, please refer to the usage section of the TIOVX documentation for further information and diagrams showcasing the proper usage of these API's.

Parameters

[in,out]	ref	The reference object to be updated.
[in]	addr	An array of pointers for holding the handles. The entries can be NULL.
[in]	size	An array of sizes corresponding to handles. The entries will be looked at if the corresponding handle is not NULL.
[in]	num_entries	Number of valid entries in addr[]. This should match the number of handles expected to be maintained internally by 'ref' (ex:- for an image object with multiple planes, num_extries > 1).

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	if the import operation is successful. The 'ref' object will have the internal handles updated.
VX_FAILURE	if the operation is unsuccessful. The state of the reference object is not changed. A failure can occur for the following reasons: Unsupported reference object type The argument check fails The handle check fails i.e. the handles have not been allocated using appMemAlloc()/tivxMemAlloc() The number of handles specified is less than the number expected by the reference object.

tivxReferenceExportHandle()

VX_API_ENTRY vx_status VX_API_CALL tivxReferenceExportHandle	(	const vx_reference	ref,
		void *	addr[],
		uint32_t	size[],
		uint32_t	max_num_entries,
		uint32_t *	num_entries
	)

Exports the handles from a reference object.

It is the responsibility of the caller to make sure that the addr array is dimensioned to hold all the handles expected from the reference object.

Only the following reference object types are supported:

• VX_TYPE_IMAGE (note: subimages of images are not supported; also, subimages of an image will not be retained across export/import)
• VX_TYPE_TENSOR
• VX_TYPE_USER_DATA_OBJECT
• VX_TYPE_ARRAY
• VX_TYPE_DISTRIBUTION
• VX_TYPE_MATRIX
• VX_TYPE_CONVOLUTION
• VX_TYPE_PYRAMID
• TIVX_TYPE_RAW_IMAGE

The memory exported from an OpenVX reference adheres to the semantics of how the framework allocates memory. This is of particular note for a few OpenVX objects listed below.

• For VX_TYPE_IMAGE references, multi-plane images are exported as a single entry. The reason for this is that the framework allocates multi-plane images as a single contiguous memory buffer. Therefore, once this is exported, it can also be freed as a single contiguous memory buffer rather than as separate buffers.
• For VX_TYPE_PYRAMID objects, each pyramid level is allocated as a separate buffer and will be exported as a single entry per level. Additionally, in the case that the pyramid levels are multi-plane images, these entries are provided as a single contiguous buffer with a size of all planes of the image.
• For TIVX_TYPE_RAW_IMAGE objects with multiple exposures, these are allocated by the framework as separate buffers and thus are exported as separate entries.

Please note the important details below on semantics about the usage of the reference import and export. Errors will occur if the below requirements are not adhered to.

• When calling the tivxReferenceExportHandle API on a vx_reference to obtain a handle and subsequently calling the tivxReferenceImportHandle API to import the handle to a separate vx_reference, the two references must be of the same type and have the same meta information. This can be confirmed by using the tivxIsReferenceMetaFormatEqual API.
• The handle exported by the tivxReferenceExportHandle API will only be valid while the originally allocated handle is valid. For example, if a handle is exported from ref1 and imported into ref2, and then ref1 is released access to ref2 will result in attempting to access memory which has already been freed. It is therefore the responsibility of the application to ensure that the original memory allocation lifetime exceeds the lifetime of exported handle.
• In the example in the bullet above, in the case that ref1 must be released prior to ref2, the suggested approach is to import a NULL pointer to ref1, followed by a release of the reference. At this point, ref2 has sole possession of the buffer while ref1 has no buffer dedicated to that reference. An implementation of this approach can be found in the associated test cases located at tiovx/conformance_tests/test_tiovx/test_tivxMem.c.
• If memory has already been allocated to a vx_reference and the tivxReferenceImportHandle API is called on the vx_reference, the previous buffer will be discarded and the vx_reference will now use the imported buffer. A log in the VX_ZONE_INFO log level will be thrown on the console in this scenario to note that a buffer is being overridden. Because this can be a dangerous situation, the tivxReferenceExportHandle API shall be called on the vx_reference in question. The previous buffer can be used as required in the application before ultimately being freed by way of the tivxMemFree API.
• The tivxReferenceExportHandle API and tivxReferenceImportHandle API must not be called if the reference has been enqueued to a vx_graph. This can cause a scenario where the graph overwrites the buffer contents and is thus is not in a state where it can be read by the application.

Finally, please refer to the usage section of the TIOVX documentation for further information and diagrams showcasing the proper usage of these API's.

Parameters

[in]	ref	The reference object to export the handles from.
[out]	addr	An array of pointers for holding the handles.
[out]	size	An array of sizes corresponding to handles. The entries will be looked
[in]	max_num_entries	Maximum number of entries to export.
[out]	num_entries	Number of valid entries in addr[]. This should match the number of handles expected to be maintained internally by 'ref' (ex:- for an image object with multiple planes, num_extries > 1).

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	if the export operation is successful. The 'addr' object will be populated with 'num_entries' handles. size[i] will correspond to the handle addr[i].
VX_FAILURE	if the operation is unsuccessful. The state of the reference object is not changed. A failure can occur for the following reasons: Unsupported reference object type The argument check fails The max number of handles specified is less than the number expected to be exported by the reference object.

tivxCreateReferenceFromExemplar()

VX_API_ENTRY vx_reference VX_API_CALL tivxCreateReferenceFromExemplar	(	vx_context	context,
		vx_reference	exemplar
	)

Create reference from a exemplar object.

This API is used to create a new reference using the same meta information as an already created reference object.

Parameters

[in]	context	The reference to the implementation context.
[in]	exemplar	The exemplar object.

Returns

vx_reference. Any possible errors preventing a successful creation should be checked using vxGetStatus.