VPI - Vision Programming Interface

3.0 Release

An abstract representation of a generic 1D array. More...

Data Structures

struct  VPIArrayBufferAOS
 Stores information about array characteristics and content. More...
 
struct  VPIArrayBuffer
 Represents the availablemethods to access array contents. More...
 
struct  VPIArrayData
 Stores information about array characteristics and contents. More...
 

Typedefs

typedef struct VPIArrayImpl * VPIArray
 A handle to an array.
 

Enumerations

enum  VPIArrayBufferType
 Represents how the array data is stored. More...
 
enum  VPIArrayType
 Array element formats. More...
 

Functions

VPIStatus vpiArrayCreate (int32_t capacity, VPIArrayType type, uint64_t flags, VPIArray *array)
 Create an empty array instance. More...
 
VPIStatus vpiArrayCreateWrapper (const VPIArrayData *data, uint64_t flags, VPIArray *array)
 Create an array object by wrapping an existing host memory block. More...
 
VPIStatus vpiArraySetWrapper (VPIArray array, const VPIArrayData *data)
 Redefines the wrapped memory buffer in an existing VPIArray wrapper. More...
 
void vpiArrayDestroy (VPIArray array)
 Destroy an array instance. 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, uint64_t *flags)
 Returns the array flags. More...
 
VPIStatus vpiArrayGetType (VPIArray array, VPIArrayType *type)
 Returns the array type. More...
 
VPIStatus vpiArrayLock (VPIArray array, VPILockMode mode)
 Acquires the lock on an array object. More...
 
VPIStatus vpiArrayLockData (VPIArray array, VPILockMode mode, VPIArrayBufferType bufType, VPIArrayData *data)
 Acquires the lock on an array object and returns the array contents. 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 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 vpiArrayCreateWrapper are fixed.

The wrapped memory can be redefined by calling vpiArraySetWrapper as long as the new wrapped memory has the same buffer type, capacity, 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 vpiArrayLockData / 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.


Data Structure Documentation

◆ VPIArrayBufferAOS

struct VPIArrayBufferAOS

Stores information about array characteristics and content.

Represents array information as an array of structures (AOS).

Definition at line 115 of file Array.h.

+ Collaboration diagram for VPIArrayBufferAOS:
Data Fields
VPIArrayType type Type of each array element.
int32_t * sizePointer Points to the number of elements in the array.
  • Must be >= 0.
int32_t capacity Maximum number of elements that the array can hold.
  • Must be >= 0.
int32_t strideBytes Size in bytes of each array element.
  • Must be >= 0.
  • Must be at least as large as the element size.
  • Must be a multiple of the element size.
void * data Points to the first element of the array.

◆ VPIArrayBuffer

struct VPIArrayBuffer

Represents the availablemethods to access array contents.

The correct method depends on VPIArrayData::bufferType .

Definition at line 155 of file Array.h.

+ Collaboration diagram for VPIArrayBuffer:
Data Fields
VPIArrayBufferAOS aos Array stored in array-of-structures layout.

To be used when VPIArrayData::bufferType is:

◆ VPIArrayData

struct VPIArrayData

Stores information about array characteristics and contents.

Definition at line 167 of file Array.h.

+ Collaboration diagram for VPIArrayData:
Data Fields
VPIArrayBufferType bufferType Type of array buffer.

It defines which member of the VPIArrayBuffer tagged union that must be used to access the array contents.

VPIArrayBuffer buffer Stores the array contents.

Enumeration Type Documentation

◆ VPIArrayBufferType

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Represents how the array data is stored.

Enumerator
VPI_ARRAY_BUFFER_INVALID 

Invalid buffer type.

This is commonly used to inform that no buffer type was selected.

VPI_ARRAY_BUFFER_HOST_AOS 

Host-accessible array-of-structures.

VPI_ARRAY_BUFFER_CUDA_AOS 

CUDA-accessible array-of-structures.

Definition at line 139 of file Array.h.

◆ VPIArrayType

#include </opt/nvidia/vpi3/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_F32 

VPIKeypointF32 element.

VPI_ARRAY_TYPE_HOMOGRAPHY_TRANSFORM_2D 

VPIHomographyTransform2D element.

VPI_ARRAY_TYPE_KLT_TRACKED_BOUNDING_BOX 

VPIKLTTrackedBoundingBox element.

VPI_ARRAY_TYPE_F32 

Floating point 32-bit.

VPI_ARRAY_TYPE_KEYPOINT_U32 

VPIKeypointU32 element in U32 format.

VPI_ARRAY_TYPE_KEYPOINT_UQ1616 

VPIKeypointU32 element in UQ1616 fixed-point format.

VPI_ARRAY_TYPE_STATISTICS 

VPIStats element.

VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR 

VPIBriefDescriptor element.

VPI_ARRAY_TYPE_MATCHES 

VPIMatches element.

VPI_ARRAY_TYPE_DCF_TRACKED_BOUNDING_BOX 

VPIDCFTrackedBoundingBox element.

Definition at line 69 of file ArrayType.h.

Function Documentation

◆ vpiArrayCreate()

VPIStatus vpiArrayCreate ( int32_t  capacity,
VPIArrayType  type,
uint64_t  flags,
VPIArray array 
)

#include </opt/nvidia/vpi3/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. Array size is set to zero. The VPIArray object owns the allocated memory.

Parameters
[in]capacityArray capacity in elements.
  • Must be >= 0.
[in]typeType of each array element.
[in]flagsBit field specifying the desired characteristics of the array.
  • The field must be a combination of zero or more of the following flags:
  • If flag VPI_REQUIRE_BACKENDS is given, user must pass at least one valid backend, and they all must be enabled in current context.
[out]arrayPointer to memory that will receive the created array handle.
Return values
VPI_ERROR_INVALID_ARRAY_TYPEInvalid type.
VPI_ERROR_INVALID_ARGUMENTInvalid flags.
VPI_ERROR_INVALID_ARGUMENTcapacity outside valid range.
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTNo backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORYNot enough resources to allocate array.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_ERROR_INVALID_OPERATIONRequested backend isn't enabled in current context.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayCreateWrapper()

VPIStatus vpiArrayCreateWrapper ( const VPIArrayData data,
uint64_t  flags,
VPIArray array 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Create an array object by wrapping an existing host memory block.

The returned handle must be destroyed when not being used anymore by calling vpiArrayDestroy.

The object doesn't own the wrapped memory. The user is still responsible for wrapped memory lifetime, which must be valid until the array object is destroyed.

Parameters
[in]dataPointer to structure with memory buffer to be wrapped.
  • Mandatory, it can't be NULL.
[in]flagsBit field specifying the desired characteristics of the array. Depending on some buffer types, the following flags will be added automatically:
Buffer type Added flag
VPI_ARRAY_BUFFER_HOST_AOS VPI_BACKEND_CPU
VPI_ARRAY_BUFFER_CUDA_AOS VPI_BACKEND_CUDA
  • The field must be a combination of zero or more of the following flags:
  • If backends are given and VPI_REQUIRE_BACKENDS is set, they all must enabled in current context.
  • If backends are automatically added, they must be enabled in current context.
Parameters
[out]arrayPointer to memory that will receive the created array handle.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL.
VPI_ERROR_INVALID_ARGUMENTdata is NULL or contains invalid/unsupported values.
VPI_ERROR_INVALID_ARGUMENTBuffer type in data isn't supported.
VPI_ERROR_INVALID_ARGUMENTNo backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORYNot enough resources to create array.
VPI_ERROR_INVALID_CONTEXTCurrent context is destroyed.
VPI_ERROR_INVALID_OPERATIONRequested backend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATIONAutomatically added backend flags aren't enabled in current context.
VPI_SUCCESSOperation executed successfully.

◆ vpiArraySetWrapper()

VPIStatus vpiArraySetWrapper ( VPIArray  array,
const VPIArrayData data 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Redefines the wrapped memory buffer in an existing VPIArray wrapper.

This operation is efficient and does not allocate memory. The wrapped memory will be accessible to the same backends specified during wrapper creation.

The wrapped memory must not be deallocated while it's still being wrapped.

Parameters
[in]arrayHandle to array.
[in]dataPointer to structure with host memory to be wrapped.
  • Mandatory, it can't be NULL.
  • The existing wrapped array and the new one must have same capacity and element type.
  • The old and new buffer types must match.
  • The wrapped memory must point to a buffer that corresponds to the given buffer type.
Return values
VPI_ERROR_INVALID_ARGUMENTdata is NULL.
VPI_ERROR_INVALID_ARGUMENTdata has an unsupported buffer type.
VPI_ERROR_INVALID_ARGUMENTNew and old buffer types don't match.
VPI_ERROR_INVALID_OPERATIONarray is not created suing vpiArrayCreateWrapper.
VPI_ERROR_INVALID_OPERATIONdata capacity and/or format don't match array.
VPI_ERROR_INVALID_OPERATIONarray is locked.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayDestroy()

void vpiArrayDestroy ( VPIArray  array)

#include </opt/nvidia/vpi3/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.
  • Array must not be in use by any stream, or else undefined behavior will ensue.

◆ vpiArrayGetSize()

VPIStatus vpiArrayGetSize ( VPIArray  array,
int32_t *  size 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Returns the array size in elements.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[out]sizeA pointer to a variable which will be set to the size of the array.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTOutput size pointer is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiArraySetSize()

VPIStatus vpiArraySetSize ( VPIArray  array,
int32_t  size 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Set the array size in elements.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[in]sizeThe new size of the array.
  • Must be less than or equal to array's capacity.
  • Must be >= 0.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTInput size outside valid range.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayGetCapacity()

VPIStatus vpiArrayGetCapacity ( VPIArray  array,
int32_t *  capacity 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Returns the array capacity in elements.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[out]capacityA pointer to a variable which will be set to the capacity of the array.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTOutput capacity pointer is NULL.
VPI_SUCCESSOperation executed successfully

◆ vpiArrayGetStrideBytes()

VPIStatus vpiArrayGetStrideBytes ( VPIArray  array,
int32_t *  strideBytes 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

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

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[out]strideBytesA pointer to a variable which will be set to the stride of the array element, in bytes.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTOutput strideBytes pointer is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayGetFlags()

VPIStatus vpiArrayGetFlags ( VPIArray  array,
uint64_t *  flags 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Returns the array flags.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[out]flagsA pointer where the flags will be written to.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTOutput flags pointer is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayGetType()

VPIStatus vpiArrayGetType ( VPIArray  array,
VPIArrayType type 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Returns the array type.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
[out]typeA pointer where the array type will be written to.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTOutput type pointer is NULL.
VPI_SUCCESSOperation executed successfully.

◆ vpiArrayLock()

VPIStatus vpiArrayLock ( VPIArray  array,
VPILockMode  mode 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Acquires the lock on an array object.

Array locking is required when the array object wraps externally-accessible buffers, and these buffers will be accessed outside VPI. As long as the lock is held, any attempt of VPI to access the array in a mode not compatible with the lock mode will result in asynchronous stream errors, VPI_ERROR_BUFFER_LOCKED.

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 a stream.

Parameters
[in]arrayArray to be locked.
  • Mandatory, it can't be NULL.
  • Array must not be locked in a mode that is incompatible with given mode.
[in]modeLock mode, depending on whether the memory will be written to and/or read from.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_BUFFER_LOCKEDArray is already locked by either a stream or the user.
VPI_SUCCESSOperation executed successfully

◆ vpiArrayLockData()

VPIStatus vpiArrayLockData ( VPIArray  array,
VPILockMode  mode,
VPIArrayBufferType  bufType,
VPIArrayData data 
)

#include </opt/nvidia/vpi3/include/vpi/Array.h>

Acquires the lock on an array object and returns the array contents.

Depending on the internal array representation, as well as the actual location in memory, this function might have a significant performance overhead due to type conversion, memory copies, etc.

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 a stream.

Parameters
[in]arrayArray to be locked.
[in]bufTypeThe type of buffer returned in data. It defines how the array contents can be accessed by the caller. Valid types are:
[in]modeLock mode, depending on whether the memory will be written to and/or read from.
[out]dataA pointer to a structure that will be filled with array memory information..
  • The buffer it points to are valid until the array is unlocked.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENTdata is NULL.
VPI_ERROR_INVALID_ARGUMENTbufType isn't supported.
VPI_ERROR_INVALID_OPERATIONarray doesn't have required backends enabled.
VPI_ERROR_BUFFER_LOCKEDArray is already locked by either a stream or the user.
VPI_SUCCESSOperation executed successfully

◆ vpiArrayUnlock()

VPIStatus vpiArrayUnlock ( VPIArray  array)

#include </opt/nvidia/vpi3/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.

Parameters
[in]arrayA valid array handle.
  • Mandatory, it can't be NULL.
Return values
VPI_ERROR_INVALID_ARGUMENTarray is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_OPERATIONarray isn't locked.
VPI_SUCCESSOperation executed successfully