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:
void *base = NULL;
for (i = 0; i < num_items; i++)
{
vxArrayItem(mystruct, base, i, stride).some_double = 3.14f;
}
|
typedef struct _vx_array * | vx_array |
| The Array Object. Array is a strongly-typed container for other data structures.
|
|
|
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 | 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. 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 | 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. 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...
|
|
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. More...
|
|
#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 2876 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 2887 of file vx_api.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.
|
Definition at line 1145 of file vx_types.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
.
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.
1 vx_context context = vxCreateContext();
2 vx_graph graph = vxCreateGraph(context);
4 vxCreateVirtualArray(graph, 0, 0), // totally unspecified
5 vxCreateVirtualArray(graph, VX_TYPE_KEYPOINT, 0), // unspecified capacity
6 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
.
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. |
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. |
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. |
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. |
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. |
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.
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