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

enum VPIArrayBufferType

#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

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_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.
VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32	VPIPyramidalKeypointF32 element.
VPI_ARRAY_TYPE_APRILTAG_DETECTION	VPIAprilTagDetection element.
VPI_ARRAY_TYPE_POSE	VPIPose 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 <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]	capacity	Array capacity in elements. Must be >= 0.
[in]	type	Type of each array element. Can't be VPI_ARRAY_TYPE_INVALID.
[in]	flags	Bit field specifying the desired characteristics of the array. The field must be a combination of zero or more of the following flags: VPIBackend flags. This array can be used in algorithms running in these backends. If no backend flags are passed and VPI_REQUIRE_BACKENDS flag isn't present, it'll consider all backends supported by the active context. Common object 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]	array	Pointer to memory that will receive the created array handle.

Return values

VPI_ERROR_INVALID_ARRAY_TYPE	Invalid `type`.
VPI_ERROR_INVALID_ARGUMENT	Invalid `flags`.
VPI_ERROR_INVALID_ARGUMENT	`capacity` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to allocate array.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArrayCreateWrapper()

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

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

data

Pointer to structure with memory buffer to be wrapped.

Mandatory, it can't be NULL.

[in]

flags

Bit 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:
- VPIBackend flags. This array can be used in algorithms running in these backends. If no backend flags are passed and VPI_REQUIRE_BACKENDS flag isn't present, it'll consider all backends supported by the active context.
- Common object 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] array Pointer to memory that will receive the created array handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`data` is NULL or contains invalid/unsupported values.
VPI_ERROR_INVALID_ARGUMENT	Buffer type in `data` isn't supported.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to create array.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATION	Automatically added backend flags aren't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArraySetWrapper()

VPIStatus vpiArraySetWrapper	(	VPIArray	array,
		const VPIArrayData *	data
	)

#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]	array	Handle to array. It must have been created by vpiArrayCreateWrapper. Array must not be locked.
[in]	data	Pointer 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_ARGUMENT	`data` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`data` has an unsupported buffer type.
VPI_ERROR_INVALID_ARGUMENT	New and old buffer types don't match.
VPI_ERROR_INVALID_OPERATION	`array` is not created suing vpiArrayCreateWrapper.
VPI_ERROR_INVALID_OPERATION	`data` capacity and/or format don't match `array`.
VPI_ERROR_INVALID_OPERATION	`array` is locked.
VPI_SUCCESS	Operation executed successfully.

◆ 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]

array

Array 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 <vpi/Array.h>

Returns the array size in elements.

Parameters

[in]	array	A valid array handle. Mandatory, it can't be NULL.
[out]	size	A 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_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Output `size` pointer is NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArraySetSize()

VPIStatus vpiArraySetSize	(	VPIArray	array,
		int32_t	size
	)

#include <vpi/Array.h>

Set the array size in elements.

Parameters

[in]	array	A valid array handle. Mandatory, it can't be NULL.
[in]	size	The new size of the array. Must be less than or equal to array's capacity. Must be >= 0.

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Input `size` outside valid range.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArrayGetCapacity()

VPIStatus vpiArrayGetCapacity	(	VPIArray	array,
		int32_t *	capacity
	)

#include <vpi/Array.h>

Returns the array capacity in elements.

Parameters

[in]	array	A valid array handle. Mandatory, it can't be NULL.
[out]	capacity	A 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_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Output `capacity` pointer is NULL.
VPI_SUCCESS	Operation executed successfully

◆ 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]	array	A valid array handle. Mandatory, it can't be NULL.
[out]	strideBytes	A 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_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Output `strideBytes` pointer is NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArrayGetFlags()

VPIStatus vpiArrayGetFlags	(	VPIArray	array,
		uint64_t *	flags
	)

#include <vpi/Array.h>

Returns the array flags.

Parameters

[in]	array	A valid array handle. Mandatory, it can't be NULL.
[out]	flags	A pointer where the flags will be written to. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Output `flags` pointer is NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArrayGetType()

VPIStatus vpiArrayGetType	(	VPIArray	array,
		VPIArrayType *	type
	)

#include <vpi/Array.h>

Returns the array type.

Parameters

[in]	array	A valid array handle. Mandatory, it can't be NULL.
[out]	type	A pointer where the array type will be written to. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	Output `type` pointer is NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiArrayLock()

VPIStatus vpiArrayLock	(	VPIArray	array,
		VPILockMode	mode
	)

#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]	array	Array to be locked. Mandatory, it can't be NULL. Array must not be locked in a mode that is incompatible with given `mode`.
[in]	mode	Lock mode, depending on whether the memory will be written to and/or read from. Valid values are: VPI_LOCK_READ VPI_LOCK_WRITE VPI_LOCK_READ_WRITE

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_BUFFER_LOCKED	Array is already locked by either a stream or the user.
VPI_SUCCESS	Operation executed successfully

◆ vpiArrayLockData()

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

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

array

Array to be locked.

Mandatory, it can't be NULL.
Array must not be locked in a mode that is incompatible with given mode.
For some buffer types, the image must have the following backend enabled:

Buffer type Required backend flags

VPI_ARRAY_BUFFER_HOST_AOS VPI_BACKEND_CPU

VPI_ARRAY_BUFFER_CUDA_AOS VPI_BACKEND_CUDA

[in]

bufType

The type of buffer returned in data. It defines how the array contents can be accessed by the caller. Valid types are:

[in]

mode

Lock mode, depending on whether the memory will be written to and/or read from.

Valid values are:

[out]

data

A 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_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_ARGUMENT	`data` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`bufType` isn't supported.
VPI_ERROR_INVALID_OPERATION	`array` doesn't have required backends enabled.
VPI_ERROR_BUFFER_LOCKED	Array is already locked by either a stream or the user.
VPI_SUCCESS	Operation executed successfully

◆ vpiArrayUnlock()

VPIStatus vpiArrayUnlock ( VPIArray array )

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

array

A valid array handle.

Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`array` is NULL or doesn't represent a VPIArray instance.
VPI_ERROR_INVALID_OPERATION	`array` isn't locked.
VPI_SUCCESS	Operation executed successfully

VPI - Vision Programming Interface

3.2 Release

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ VPIArrayBufferAOS

◆ VPIArrayBuffer

◆ VPIArrayData

Enumeration Type Documentation

◆ VPIArrayBufferType

◆ VPIArrayType

Function Documentation

◆ vpiArrayCreate()

◆ vpiArrayCreateWrapper()

◆ vpiArraySetWrapper()

◆ vpiArrayDestroy()

◆ vpiArrayGetSize()

◆ vpiArraySetSize()

◆ vpiArrayGetCapacity()

◆ vpiArrayGetStrideBytes()

◆ vpiArrayGetFlags()

◆ vpiArrayGetType()

◆ vpiArrayLock()

◆ vpiArrayLockData()

◆ vpiArrayUnlock()