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 = sizeof(vx_size);
        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 VX_API_CALL	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. The number of elements in the sub-range is given by (end - start). More...

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

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

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

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

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

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

vx_status VX_API_CALL	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 'number of bytes' between the beginning of two consecutive elements.

Definition at line 1846 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 'number of bytes' between the beginning of two consecutive elements.

Definition at line 1857 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 964 of file vx_types.h.

Function Documentation

vx_array VX_API_CALL 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: An array reference vx_array. Any possible errors preventing a successful creation should be checked using vxGetStatus.

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.

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: A array reference vx_array. Any possible errors preventing a successful creation should be checked using vxGetStatus.

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.

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 arr is not a `vx_array`.

vx_status VX_API_CALL 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 in bytes 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 VX_API_CALL vxAddArrayItems	(	vx_array	arr,
		vx_size	count,
		const 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 number of bytes between the beginning of two consecutive elements.

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 VX_API_CALL 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 VX_API_CALL 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. The number of elements in the sub-range is given by (end - start).

Parameters

[in]	arr	The reference to the Array.
[in]	start	The start index.
[in]	end	The end index. (end - start) elements are accessed from start.
[in,out]	stride	A pointer to 'number of bytes' between the beginning of two consequent elements. Input case: ptr is a pointer to a non-NULL pointer. The stride parameter must be the address of a vx_size scalar that describes how the user will access the requested array data at address (ptr). Output Case: ptr is a pointer to a NULL pointer. The function fills the vx_size scalar pointed by stride with the element stride information that the user must consult to access the array elements at address (ptr).
[out]	ptr	A pointer to a pointer to a location to store the requested data. Input Case: ptr is a pointer to a non-NULL pointer to a valid buffer. This buffer will be used in one of two ways, depending on the value of the usage parameter. If usage is VX_WRITE_ONLY, then the buffer must contain element data that the user wants to replace the array's element data with. Otherwise (i.e., usage is not VX_WRITE_ONLY), the array's current element data will be written to the memory starting at address (ptr) as storage memory for the access request. The caller must ensure enough memory has been allocated for the requested array range with the requested stride. Output Case: ptr is a pointer to a NULL pointer. This NULL pointer will be overwritten with a pointer to the address where the requested data can be accessed. (ptr) must eventually be provided as the ptr parameter of a call to vxCommitArrayRange.
[in]	usage	This declares the intended usage of the pointer using the `vx_accessor_e` enumeration.

Note: The stride and ptr parameters must both be input, or both be output, otherwise the behavior is undefined.

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 VX_API_CALL vxCommitArrayRange	(	vx_array	arr,
		vx_size	start,
		vx_size	end,
		const void *	ptr
	)

Commits data back to the Array object.

This allows a user to commit data to a sub-range of an Array. The number of elements in the sub-range is given by (end - start).

Parameters

[in]	arr	The reference to the Array.
[in]	start	The start index.
[in]	end	The end index. (end - start) elements are accessed from start.
[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