User Facing Array API

The Public Array API. More...

Macros
#define	vxFormatArrayPointer(ptr, index, stride)
	Accesses a specific indexed element in an array.
#define	vxArrayItem(type, ptr, index, stride)
	Allows access to an array item as a typecast pointer deference.

Typedefs
typedef struct Array *	vx_array
	The Array Object. Array is a strongly-typed container for other data structures.

Enumerations
enum	vx_array_attribute_e {   VX_ARRAY_ITEMTYPE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_ARRAY) + 0x0 ,   VX_ARRAY_NUMITEMS = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_ARRAY) + 0x1 ,   VX_ARRAY_CAPACITY = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_ARRAY) + 0x2 ,   VX_ARRAY_ITEMSIZE = VX_ATTRIBUTE_BASE(VX_ID_KHRONOS, VX_TYPE_ARRAY) + 0x3 }
	The array object attributes. More...

Functions
VX_API_ENTRY vx_array VX_API_CALL	vxCreateArray (vx_context context, vx_enum item_type, vx_size capacity)
	Creates a reference to an Array object.
VX_API_ENTRY vx_array VX_API_CALL	vxCreateVirtualArray (vx_graph graph, vx_enum item_type, vx_size capacity)
	Creates an opaque reference to a virtual Array with no direct user access.
VX_API_ENTRY vx_status VX_API_CALL	vxReleaseArray (vx_array *arr)
	Releases a reference of an Array object. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed.
VX_API_ENTRY vx_status VX_API_CALL	vxQueryArray (vx_array arr, vx_enum attribute, void *ptr, vx_size size)
	Queries the Array for some specific information.
VX_API_ENTRY vx_status VX_API_CALL	vxAddArrayItems (vx_array arr, vx_size count, const void *ptr, vx_size stride)
	Adds items to the Array.
VX_API_ENTRY vx_status VX_API_CALL	vxTruncateArray (vx_array arr, vx_size new_num_items)
	Truncates an Array (remove items from the end).
VX_API_ENTRY vx_status VX_API_CALL	vxCopyArrayRange (vx_array array, vx_size range_start, vx_size range_end, vx_size user_stride, void *user_ptr, vx_enum usage, vx_enum user_mem_type)
	Allows the application to copy a range from/into an array object.
VX_API_ENTRY vx_status VX_API_CALL	vxMapArrayRange (vx_array array, vx_size range_start, vx_size range_end, vx_map_id *map_id, vx_size *stride, void **ptr, vx_enum usage, vx_enum mem_type, vx_uint32 flags)
	Allows the application to get direct access to a range of an array object.
VX_API_ENTRY vx_status VX_API_CALL	vxUnmapArrayRange (vx_array array, vx_map_id map_id)
	Unmap and commit potential changes to an array object range that was previously mapped. Unmapping an array range invalidates the memory location from which the range could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.

Detailed Description

The Public Array API.

Macro Definition Documentation

vxArrayItem

#define vxArrayItem	(		type,
			ptr,
			index,
			stride )

#include <vx_api.h>

Value:

    (*(type *)(vxFormatArrayPointer((ptr), (index), (stride))))

Allows access to an array item as a typecast pointer deference.

Parameters

[in]	type	The type of the item to access.
[in]	ptr	The base pointer for the array range.
[in]	index	The index of the element, not byte, to access.
[in]	stride	The 'number of bytes' between the beginning of two consecutive elements.

vxFormatArrayPointer

#define vxFormatArrayPointer	(		ptr,
			index,
			stride )

#include <vx_api.h>

Value:

    (&(((vx_uint8*)(ptr))[(index) * (stride)]))

Accesses a specific indexed element in an array.

Parameters

[in]	ptr	The base pointer for the array range.
[in]	index	The index of the element, not byte, to access.
[in]	stride	The 'number of bytes' between the beginning of two consecutive elements.

Typedef Documentation

vx_array

typedef struct Array* vx_array

#include <vx_types.h>

The Array Object. Array is a strongly-typed container for other data structures.

Enumeration Type Documentation

vx_array_attribute_e

enum vx_array_attribute_e

#include <vx_types.h>

The array object attributes.

Enumerator
VX_ARRAY_ITEMTYPE	The type of the Array items. Read-only. Use a vx_enum parameter.
VX_ARRAY_NUMITEMS	The number of items in the Array. Read-only. Use a vx_size parameter.
VX_ARRAY_CAPACITY	The maximal number of items that the Array can hold. Read-only. Use a vx_size parameter.
VX_ARRAY_ITEMSIZE	Queries an array item size. Read-only. Use a vx_size parameter.

Function Documentation

vxAddArrayItems()

VX_API_ENTRY vx_status VX_API_CALL vxAddArrayItems	(	vx_array	arr,
		vx_size	count,
		const void *	ptr,
		vx_size	stride )

#include <vx_api.h>

Adds items to the Array.

This function increases the container size.

By default, the function does not reallocate memory, so if the container is already full (number of elements is equal to capacity) or it doesn't have enough space, the function returns VX_FAILURE error code.

Parameters

[in]	arr	The reference to the Array.
[in]	count	The total number of elements to insert.
[in]	ptr	The location from which to read the input values.
[in]	stride	The number of bytes between the beginning of two consecutive elements.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	arr is not a valid vx_array reference.
VX_FAILURE	If the Array is full.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

vxCopyArrayRange()

VX_API_ENTRY vx_status VX_API_CALL vxCopyArrayRange	(	vx_array	array,
		vx_size	range_start,
		vx_size	range_end,
		vx_size	user_stride,
		void *	user_ptr,
		vx_enum	usage,
		vx_enum	user_mem_type )

#include <vx_api.h>

Allows the application to copy a range from/into an array object.

Parameters

[in]	array	The reference to the array object that is the source or the destination of the copy.
[in]	range_start	The index of the first item of the array object to copy.
[in]	range_end	The index of the item following the last item of the array object to copy. (range_end range_start) items are copied from index range_start included. The range must be within the bounds of the array: 0 <= range_start < range_end <= number of items in the array.
[in]	user_stride	The number of bytes between the beginning of two consecutive items in the user memory pointed by user_ptr. The layout of the user memory must follow an item major order: user_stride >= element size in bytes.
[in]	user_ptr	The address of the memory location where to store the requested data if the copy was requested in read mode, or from where to get the data to store into the array object if the copy was requested in write mode. The accessible memory must be large enough to contain the specified range with the specified stride: accessible memory in bytes >= (range_end range_start) * user_stride.
[in]	usage	This declares the effect of the copy with regard to the array object using the vx_accessor_e enumeration. Only VX_READ_ONLY and VX_WRITE_ONLY are supported: VX_READ_ONLY means that data are copied from the array object into the user memory. VX_WRITE_ONLY means that data are copied into the array object from the user memory.
[in]	user_mem_type	A vx_memory_type_e enumeration that specifies the memory type of the memory referenced by the user_addr.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual array that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	array is not a valid vx_array reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

vxCreateArray()

VX_API_ENTRY vx_array VX_API_CALL vxCreateArray	(	vx_context	context,
		vx_enum	item_type,
		vx_size	capacity )

#include <vx_api.h>

Creates a reference to an Array object.

User must specify the Array capacity (i.e., the maximal number of items that the array can hold).

Parameters

[in]	context	The reference to the overall Context.
[in]	item_type	The type of data to hold. Must be greater than VX_TYPE_INVALID and less than or equal to VX_TYPE_VENDOR_STRUCT_END. Or must be a vx_enum returned from vxRegisterUserStruct.
[in]	capacity	The maximal number of items that the array can hold. This value must be greater than zero.

Returns

An array reference vx_array. Any possible errors preventing a successful creation should be checked using vxGetStatus.

Examples

optical_flow.cpp, and orb.cpp.

vxCreateVirtualArray()

VX_API_ENTRY vx_array VX_API_CALL vxCreateVirtualArray	(	vx_graph	graph,
		vx_enum	item_type,
		vx_size	capacity )

#include <vx_api.h>

Creates an opaque reference to a virtual Array with no direct user access.

Virtual Arrays are useful when item type or capacity are unknown ahead of time and the Array is used as internal graph edge. Virtual arrays are scoped within the parent graph only.

All of the following constructions are allowed.

vx_context context = vxCreateContext();
vx_graph graph = vxCreateGraph(context);
vx_array virt[] = {
    vxCreateVirtualArray(graph, 0, 0), // totally unspecified
    vxCreateVirtualArray(graph, VX_TYPE_KEYPOINT, 0), // unspecified capacity
    vxCreateVirtualArray(graph, VX_TYPE_KEYPOINT, 1000), // no access
};

Parameters

[in]	graph	The reference to the parent graph.
[in]	item_type	The type of data to hold. Must be greater than VX_TYPE_INVALID and less than or equal to VX_TYPE_VENDOR_STRUCT_END. Or must be a vx_enum returned from vxRegisterUserStruct. This may to set to zero to indicate an unspecified item type.
[in]	capacity	The maximal number of items that the array can hold. This may be to set to zero to indicate an unspecified capacity.

See also

vxCreateArray for a type list.

Returns

A array reference vx_array. Any possible errors preventing a successful creation should be checked using vxGetStatus.

vxMapArrayRange()

VX_API_ENTRY vx_status VX_API_CALL vxMapArrayRange	(	vx_array	array,
		vx_size	range_start,
		vx_size	range_end,
		vx_map_id *	map_id,
		vx_size *	stride,
		void **	ptr,
		vx_enum	usage,
		vx_enum	mem_type,
		vx_uint32	flags )

#include <vx_api.h>

Allows the application to get direct access to a range of an array object.

Parameters

[in]	array	The reference to the array object that contains the range to map.
[in]	range_start	The index of the first item of the array object to map.
[in]	range_end	The index of the item following the last item of the array object to map. (range_end range_start) items are mapped, starting from index range_start included. The range must be within the bounds of the array: Must be 0 <= range_start < range_end <= number of items.
[out]	map_id	The address of a vx_map_id variable where the function returns a map identifier. (*map_id) must eventually be provided as the map_id parameter of a call to vxUnmapArrayRange.
[out]	stride	The address of a vx_size variable where the function returns the memory layout of the mapped array range. The function sets (*stride) to the number of bytes between the beginning of two consecutive items. The application must consult (*stride) to access the array items starting from address (*ptr). The layout of the mapped array follows an item major order: (*stride) >= item size in bytes.
[out]	ptr	The address of a pointer that the function sets to the address where the requested data can be accessed. The returned (*ptr) address is only valid between the call to the function and the corresponding call to vxUnmapArrayRange.
[in]	usage	This declares the access mode for the array range, using the vx_accessor_e enumeration. VX_READ_ONLY: after the function call, the content of the memory location pointed by (*ptr) contains the array range data. Writing into this memory location is forbidden and its behavior is undefined. VX_READ_AND_WRITE: after the function call, the content of the memory location pointed by (*ptr) contains the array range data; writing into this memory is allowed only for the location of items and will result in a modification of the affected items in the array object once the range is unmapped. Writing into a gap between items (when (*stride) > item size in bytes) is forbidden and its behavior is undefined. VX_WRITE_ONLY: after the function call, the memory location pointed by (*ptr) contains undefined data; writing each item of the range is required prior to unmapping. Items not written by the application before unmap will become undefined after unmap, even if they were well defined before map. Like for VX_READ_AND_WRITE, writing into a gap between items is forbidden and its behavior is undefined.
[in]	mem_type	A vx_memory_type_e enumeration that specifies the type of the memory where the array range is requested to be mapped.
[in]	flags	An integer that allows passing options to the map operation. Use the vx_map_flag_e enumeration.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_OPTIMIZED_AWAY	This is a reference to a virtual array that cannot be accessed by the application.
VX_ERROR_INVALID_REFERENCE	array is not a valid vx_array reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Postcondition

vxUnmapArrayRange with same (*map_id) value.

Examples

optical_flow.cpp.

vxQueryArray()

VX_API_ENTRY vx_status VX_API_CALL vxQueryArray	(	vx_array	arr,
		vx_enum	attribute,
		void *	ptr,
		vx_size	size )

#include <vx_api.h>

Queries the Array for some specific information.

Parameters

[in]	arr	The reference to the Array.
[in]	attribute	The attribute to query. Use a vx_array_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	arr is not a valid vx_array reference.
VX_ERROR_NOT_SUPPORTED	If the attribute is not a value supported on this implementation.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

Examples

optical_flow.cpp.

vxReleaseArray()

VX_API_ENTRY vx_status VX_API_CALL vxReleaseArray

(

vx_array *

arr

)

#include <vx_api.h>

Releases a reference of an Array object. The object may not be garbage collected until its total reference count is zero. After returning from this function the reference is zeroed.

Parameters

[in]

arr

The pointer to the Array to release.

Returns

A vx_status_e enumeration.

Return values

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

Examples

optical_flow.cpp.

vxTruncateArray()

VX_API_ENTRY vx_status VX_API_CALL vxTruncateArray	(	vx_array	arr,
		vx_size	new_num_items )

#include <vx_api.h>

Truncates an Array (remove items from the end).

Parameters

[in,out]	arr	The reference to the Array.
[in]	new_num_items	The new number of items for the Array.

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	arr is not a valid vx_array reference.
VX_ERROR_INVALID_PARAMETERS	The new_size is greater than the current size.

vxUnmapArrayRange()

VX_API_ENTRY vx_status VX_API_CALL vxUnmapArrayRange	(	vx_array	array,
		vx_map_id	map_id )

#include <vx_api.h>

Unmap and commit potential changes to an array object range that was previously mapped. Unmapping an array range invalidates the memory location from which the range could be accessed by the application. Accessing this memory location after the unmap function completes has an undefined behavior.

Parameters

[in]	array	The reference to the array object to unmap.
[out]	map_id	The unique map identifier that was returned when calling vxMapArrayRange .

Returns

A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors; any other value indicates failure.
VX_ERROR_INVALID_REFERENCE	array is not a valid vx_array reference.
VX_ERROR_INVALID_PARAMETERS	An other parameter is incorrect.

Precondition

vxMapArrayRange returning the same map_id value

Examples

optical_flow.cpp.