An abstract representation of a generic 1D array. More...
Data Structures | |
struct | VPIArrayData |
Stores information about array characteristics and content. More... | |
Typedefs | |
typedef struct VPIArrayImpl * | VPIArray |
A handle to an array. | |
Enumerations | |
enum | VPIArrayType |
Array element formats. More... | |
Functions | |
VPIStatus | vpiArrayCreate (int32_t capacity, VPIArrayType type, uint32_t flags, VPIArray *array) |
Create an empty array instance. More... | |
void | vpiArrayDestroy (VPIArray array) |
Destroy an array instance. More... | |
VPIStatus | vpiArrayInvalidate (VPIArray array) |
Informs that the array's wrapped memory was updated outside VPI. More... | |
VPIStatus | vpiArrayGetSize (VPIArray array, int32_t *size) |
Returns the array size in elements. More... | |
VPIStatus | vpiArraySetSize (VPIArray array, int32_t size) |
Set the array size in elements. More... | |
VPIStatus | vpiArrayGetCapacity (VPIArray array, int32_t *capacity) |
Returns the array capacity in elements. More... | |
VPIStatus | vpiArrayGetStrideBytes (VPIArray array, int32_t *strideBytes) |
Returns the array stride (distance between two consecutive elements) in bytes. More... | |
VPIStatus | vpiArrayGetFlags (VPIArray array, uint32_t *flags) |
Returns the array flags. More... | |
VPIStatus | vpiArrayGetType (VPIArray array, VPIArrayType *type) |
Returns the array type. More... | |
VPIStatus | vpiArrayLock (VPIArray array, VPILockMode mode, VPIArrayData *arrayData) |
Acquires the lock on array object and returns a pointer to array data. More... | |
VPIStatus | vpiArrayUnlock (VPIArray array) |
Releases the lock on array object. More... | |
An abstract representation of a generic 1D array.
There are two ways of creating 1D array containers with the API. The most basic one is to use vpiArrayCreate to allocate and initialize an empty (zeroed) VPIArray object. The memory for the array data is allocated and managed by the backend implementation. Parameters such as capacity and type are immutable and specified at the construction time. The internal memory layout is also backend-specific. More importantly, efficient exchange of array data between different hardware blocks might force the implementation to allocate the memory in multiple memory pools (e.g. dGPU and system DRAM). In some scenarios (to optimize performance and memory use) it might be beneficial to constrain the internal allocation policy to support only a particular set of backends.
To enable interop with existing host- or gpu-side code, the user can also create an array object that wraps a user-allocated (and managed) array data. Similarly to vpiArrayCreate, array parameters passed to vpiArrayCreate*Wrapper()
are fixed. To prevent excessive copying, users can point to array data that resides directly in the CUDA device memory with vpiArrayCreateCUDAMemWrapper.
The wrapped memory can be redefined by calling vpiArraySetWrappedHostMem or vpiArraySetWrappedCUDAMem as long as the new wrapped memory has the same capacity and type as the one originally wrapped. It's more efficient to create the VPIArray wrapper once and reuse it later then creating and destroying it all the time.
The set of vpiArrayLock / vpiArrayUnlock allows to read from/write to the array data from host. These functions are non-blocking and oblivious to the stream command queue so it's up to the user to make sure that all pending operations using this array as input or output are finished. Also, depending on which device the memory is allocated, lock/unlock operation might be time-consuming and, for example, involve copying data over PCIe bus for dGPUs.
VPI allows array interoperability with the following memory types:
struct VPIArrayData |
Data Fields | ||
---|---|---|
int32_t | capacity | Maximum number of elements that the array can hold. |
void * | data | Points to the first element of the array. |
int32_t * | sizePointer | Points to the number of elements in the array. |
int32_t | strideBytes | Size in bytes of each array element. |
VPIArrayType | type | Type of each array element. |
enum VPIArrayType |
#include <vpi/ArrayType.h>
Array element formats.
Enumerator | |
---|---|
VPI_ARRAY_TYPE_INVALID | Signal type conversion errors. |
VPI_ARRAY_TYPE_S8 | signed 8-bit. |
VPI_ARRAY_TYPE_U8 | unsigned 8-bit. |
VPI_ARRAY_TYPE_S16 | signed 16-bit. |
VPI_ARRAY_TYPE_U16 | unsigned 16-bit. |
VPI_ARRAY_TYPE_U32 | unsigned 32-bit. |
VPI_ARRAY_TYPE_KEYPOINT | VPIKeypoint element. |
VPI_ARRAY_TYPE_HOMOGRAPHY_TRANSFORM_2D | VPIHomographyTransform2D element. |
VPI_ARRAY_TYPE_KLT_TRACKED_BOUNDING_BOX | VPIKLTTrackedBoundingBox element. |
Definition at line 68 of file ArrayType.h.
VPIStatus vpiArrayCreate | ( | int32_t | capacity, |
VPIArrayType | type, | ||
uint32_t | flags, | ||
VPIArray * | array | ||
) |
#include <vpi/Array.h>
Create an empty array instance.
Array data is zeroed. Maximum capacity of the array is fixed and defined at the construction-time. The VPIArray object owns the allocated memory.
[in] | capacity | Array capacity in elements. |
[in] | type | Type of each element. |
[in] | flags | Array flags. Here it can be specified in what backends the array can be used by or-ing together VPIBackend flags. Set flags to 0 to enable it in all backends supported by the active VPI context. |
[out] | array | Pointer to memory that will receive the created array handle. |
void vpiArrayDestroy | ( | VPIArray | array | ) |
#include <vpi/Array.h>
Destroy an array instance.
This function deallocates all resources allocated by the array creation function. When destroying an VPIArray wrapper, the wrapped memory itself isn't deallocated.
[in] | array | Array handle to be destroyed. Passing NULL is allowed, to which the function simply does nothing. |
#include <vpi/Array.h>
Returns the array capacity in elements.
[in] | array | A valid array handle |
[out] | capacity | A pointer to a variable which will be set to the capacity of the array. |
#include <vpi/Array.h>
Returns the array flags.
[in] | array | A valid array handle. |
[out] | flags | A pointer where the flags will be written to. |
#include <vpi/Array.h>
Returns the array size in elements.
[in] | array | A valid array handle. |
[out] | size | A pointer to a variable which will be set to the size of the array. |
#include <vpi/Array.h>
Returns the array stride (distance between two consecutive elements) in bytes.
[in] | array | A valid array handle. |
[out] | strideBytes | A pointer to a variable which will be set to the stride of the array element, in bytes. |
VPIStatus vpiArrayGetType | ( | VPIArray | array, |
VPIArrayType * | type | ||
) |
#include <vpi/Array.h>
Returns the array type.
[in] | array | A valid array handle. |
[out] | type | A pointer where the array type will be written to. |
#include <vpi/Array.h>
Informs that the array's wrapped memory was updated outside VPI.
This method is used with wrapped arrays only, i.e. created with 'vpiArrayCreate*Wrapper*` functions. If the underlying array data has been modified outside VPI, use this method to mark the array as invalid. This will force the API to update its internal representation (e.g., re-upload to CUDA memory) when necessary.
[in] | array | An array handle created by one of the wrapper array creation functions. |
VPIStatus vpiArrayLock | ( | VPIArray | array, |
VPILockMode | mode, | ||
VPIArrayData * | arrayData | ||
) |
#include <vpi/Array.h>
Acquires the lock on array object and returns a pointer to array data.
Depending on the internal array representation, as well as the actual location in memory, this function might have a significant performance overhead (type conversion, layout conversion, device-to-host memory copy).
The array can be locked multiple times. Each lock operation increments a counter and must be matched by a corresponding vpiArrayUnlock call. Lock will fail if the array is being used by an algorithm.
[in] | array | A valid array handle. |
[in] | mode | Lock mode, depending on whether the memory will be written to and/or read from. |
[out] | arrayData | A pointer to a structure that will be filled with information about the array memory. If it's NULL, the array will still be locked. This is useful to make sure wrapped array is updated. |
#include <vpi/Array.h>
Set the array size in elements.
[in] | array | A valid array handle. |
[in] | size | The new size of the array. Must be less or equal than array's capacity. |
#include <vpi/Array.h>
Releases the lock on array object.
This function might have a significant performance overhead (type conversion, layout conversion, host-to-device memory copy).
The array is effectively unlocked when the internal lock counter reaches 0.
[in] | array | A valid array handle. |