Detailed Description

Defines the Array Object Interface.

Array is a strongly-typed container, which provides random access by index to its elements in constant time. It uses value semantics for its own elements and holds copies of data. This is an example for loop over an Array:

        vx_size i, stride = 0ul;
        void *base = NULL;
        /* access entire array at once */
        vxAccessArrayRange(array, 0, num_items, &stride, &base, VX_READ_AND_WRITE);
        for (i = 0; i < num_items; i++)
        {
            vxArrayItem(mystruct, base, i, stride).some_uint += i;
            vxArrayItem(mystruct, base, i, stride).some_double = 3.14f;
        }
        vxCommitArrayRange(array, 0, num_items, base);

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

#define	vxFormatArrayPointer(ptr, index, stride) (&(((vx_uint8)(ptr))[(index) (stride)]))
	Accesses a specific indexed element in an array. More...

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

Enumerations
enum	vx_array_attribute_e { VX_ARRAY_ATTRIBUTE_ITEMTYPE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_ARRAY << 8)) + 0x0, VX_ARRAY_ATTRIBUTE_NUMITEMS = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_ARRAY << 8)) + 0x1, VX_ARRAY_ATTRIBUTE_CAPACITY = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_ARRAY << 8)) + 0x2, VX_ARRAY_ATTRIBUTE_ITEMSIZE = ((( VX_ID_KHRONOS ) << 20) \| ( VX_TYPE_ARRAY << 8)) + 0x3 }
	The array object attributes. More...

Functions
vx_status	vxAccessArrayRange (vx_array arr, vx_size start, vx_size end, vx_size stride, void *ptr, vx_enum usage)
	Grants access to a sub-range of an Array. More...

vx_status	vxAddArrayItems (vx_array arr, vx_size count, void *ptr, vx_size stride)
	Adds items to the Array. More...

vx_status	vxCommitArrayRange (vx_array arr, vx_size start, vx_size end, void *ptr)
	Commits data back to the Array object. More...

vx_array	vxCreateArray (vx_context context, vx_enum item_type, vx_size capacity)
	Creates a reference to an Array object. More...

vx_array	vxCreateVirtualArray (vx_graph graph, vx_enum item_type, vx_size capacity)
	Creates an opaque reference to a virtual Array with no direct user access. More...

vx_status	vxQueryArray (vx_array arr, vx_enum attribute, void *ptr, vx_size size)
	Queries the Array for some specific information. More...

vx_status	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. More...

vx_status	vxTruncateArray (vx_array arr, vx_size new_num_items)
	Truncates an Array (remove items from the end). More...

Macro Definition Documentation

#define vxFormatArrayPointer	(	ptr,
		index,
		stride
	)	(&(((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 stride of the array range given by `vxAccessArrayRange`.

Definition at line 1728 of file vx_api.h.

#define vxArrayItem	(	type,
		ptr,
		index,
		stride
	)	((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 stride of the array range given by `vxAccessArrayRange`.

Definition at line 1739 of file vx_api.h.

Enumeration Type Documentation

enum vx_array_attribute_e

The array object attributes.

Enumerator
VX_ARRAY_ATTRIBUTE_ITEMTYPE	The type of the Array items. Use a `vx_enum` parameter.
VX_ARRAY_ATTRIBUTE_NUMITEMS	The number of items in the Array. Use a `vx_size` parameter.
VX_ARRAY_ATTRIBUTE_CAPACITY	The maximal number of items that the Array can hold. Use a `vx_size` parameter.
VX_ARRAY_ATTRIBUTE_ITEMSIZE	Queries an array item size. Use a `vx_size` parameter.

Definition at line 928 of file vx_types.h.

Function Documentation

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

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 objects to hold. Use: `VX_TYPE_RECTANGLE` for `vx_rectangle_t`. `VX_TYPE_KEYPOINT` for `vx_keypoint_t`. `VX_TYPE_COORDINATES2D` for `vx_coordinates2d_t`. `VX_TYPE_COORDINATES3D` for `vx_coordinates3d_t`. `vx_enum` Returned from `vxRegisterUserStruct`.
[in]	capacity	The maximal number of items that the array can hold.

Returns: vx_array.

Return values

0	No Array was created.
*	An Array was created.

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

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 objects to hold. 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: vx_array.

Return values

0	No Array was created.
*	An Array was created or an error occurred. Use `vxGetStatus` to determine.

vx_status 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.

Parameters

[in] arr The pointer to the Array to release.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If graph is not a `vx_graph`.

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

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 of the container to which ptr points.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the arr is not a `vx_array`.
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.

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

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 at which to store the input values.
[in]	stride	The stride in bytes between elements. User can pass 0, which means that stride is equal to item size.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_INVALID_REFERENCE	If the arr is not a `vx_array`.
VX_FAILURE	If the Array is full.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

vx_status vxTruncateArray	(	vx_array	arr,
		vx_size	new_num_items
	)

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.
VX_ERROR_INVALID_REFERENCE	If the arr is not a `vx_array`.
VX_ERROR_INVALID_PARAMETERS	The new_size is greater than the current size.

vx_status vxAccessArrayRange	(	vx_array	arr,
		vx_size	start,
		vx_size	end,
		vx_size *	stride,
		void **	ptr,
		vx_enum	usage
	)

Grants access to a sub-range of an Array.

Parameters

[in]	arr	The reference to the Array.
[in]	start	The start index.
[in]	end	The end index.
[out]	stride	The stride in bytes between elements.
[out]	ptr	The user-supplied pointer to a pointer, via which the requested contents are returned. If (ptr) is non-NULL, data is copied to it, else (ptr) is set to the address of existing internal memory, allocated, or mapped memory. (*ptr) must be given to `vxCommitArrayRange`. Use a `vx_rectangle_t` for `VX_TYPE_RECTANGLE` and a `vx_keypoint_t` for `VX_TYPE_KEYPOINT`.
[in]	usage	This declares the intended usage of the pointer using the `vx_accessor_e` enumeration.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_OPTIMIZED_AWAY	If the reference is a virtual array and cannot be accessed or committed.
VX_ERROR_INVALID_REFERENCE	If the arr is not a `vx_array`.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

Postcondition: vxCommitArrayRange

vx_status vxCommitArrayRange	(	vx_array	arr,
		vx_size	start,
		vx_size	end,
		void *	ptr
	)

Commits data back to the Array object.

This allows a user to commit data to a sub-range of an Array.

Parameters

[in]	arr	The reference to the Array.
[in]	start	The start index.
[in]	end	The end index.
[in]	ptr	The user supplied pointer.

Returns: A vx_status_e enumeration.

Return values

VX_SUCCESS	No errors.
VX_ERROR_OPTIMIZED_AWAY	If the reference is a virtual array and cannot be accessed or committed.
VX_ERROR_INVALID_REFERENCE	If the arr is not a `vx_array`.
VX_ERROR_INVALID_PARAMETERS	If any of the other parameters are incorrect.

Detailed Description

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation