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. More...
|
|
|
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...
|
|
#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.
The Array Object. Array is a strongly-typed container for other data structures.
Definition at line 279 of file vx_types.h.
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 984 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 objects to hold. Use:
|
[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
.
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.
- 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
.
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 . |
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. |
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. |
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. |
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
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. |