VPI - Vision Programming Interface

1.0 Release

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 vpiArrayGetFormat (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...
 

Detailed Description

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 format 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 format 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:


Data Structure Documentation

◆ VPIArrayData

struct VPIArrayData

Stores information about array characteristics and content.

Definition at line 118 of file Array.h.

+ Collaboration diagram for 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.
VPIArrayType format Format of each array element.
int32_t * sizePointer Points to the number of elements in the array.
int32_t strideBytes Size in bytes of each array element.

Enumeration Type Documentation

◆ 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 66 of file ArrayType.h.

Function Documentation

◆ vpiArrayCreate()

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.

Parameters
[in]capacityArray capacity in elements.
[in]typeType of each element.
[in]flagsArray 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]arrayPointer to memory that will receive the created array handle.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiArrayDestroy()

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.

Parameters
[in]arrayArray handle to be destroyed. Passing NULL is allowed, to which the function simply does nothing.

◆ vpiArrayGetCapacity()

VPIStatus vpiArrayGetCapacity ( VPIArray  array,
int32_t *  capacity 
)

#include <vpi/Array.h>

Returns the array capacity in elements.

Parameters
[in]arrayA valid array handle
[out]capacityA pointer to a variable which will be set to the capacity of the array.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetFlags()

VPIStatus vpiArrayGetFlags ( VPIArray  array,
uint32_t *  flags 
)

#include <vpi/Array.h>

Returns the array flags.

Parameters
[in]arrayA valid array handle.
[out]flagsA pointer where the flags will be written to.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetFormat()

VPIStatus vpiArrayGetFormat ( VPIArray  array,
VPIArrayType type 
)

#include <vpi/Array.h>

Returns the array type.

Parameters
[in]arrayA valid array handle.
[out]typeA pointer where the array type will be written to.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetSize()

VPIStatus vpiArrayGetSize ( VPIArray  array,
int32_t *  size 
)

#include <vpi/Array.h>

Returns the array size in elements.

Parameters
[in]arrayA valid array handle.
[out]sizeA pointer to a variable which will be set to the size of the array.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetStrideBytes()

VPIStatus vpiArrayGetStrideBytes ( VPIArray  array,
int32_t *  strideBytes 
)

#include <vpi/Array.h>

Returns the array stride (distance between two consecutive elements) in bytes.

Parameters
[in]arrayA valid array handle.
[out]strideBytesA pointer to a variable which will be set to the stride of the array element, in bytes.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayInvalidate()

VPIStatus vpiArrayInvalidate ( VPIArray  array)

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

Parameters
[in]arrayAn array handle created by one of the wrapper array creation functions.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayLock()

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 (format 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.

Parameters
[in]arrayA valid array handle.
[in]modeLock mode, depending on whether the memory will be written to and/or read from.
[out]arrayDataA 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.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArraySetSize()

VPIStatus vpiArraySetSize ( VPIArray  array,
int32_t  size 
)

#include <vpi/Array.h>

Set the array size in elements.

Parameters
[in]arrayA valid array handle.
[in]sizeThe new size of the array. Must be less or equal than array's capacity.
Returns
an error code on failure else VPI_SUCCESS.

◆ vpiArrayUnlock()

VPIStatus vpiArrayUnlock ( VPIArray  array)

#include <vpi/Array.h>

Releases the lock on array object.

This function might have a significant performance overhead (format conversion, layout conversion, host-to-device memory copy).

The array is effectively unlocked when the internal lock counter reaches 0.

Parameters
[in]arrayA valid array handle.
Returns
an error code on failure else VPI_SUCCESS.