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.

Functions
VPIStatus	vpiArrayCreate (uint32_t capacity, VPIArrayType fmt, 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, uint32_t *size)
	Returns the array size in elements. More...

VPIStatus	vpiArraySetSize (VPIArray array, uint32_t size)
	Set the array size in elements. More...

VPIStatus	vpiArrayGetCapacity (VPIArray array, uint32_t *capacity)
	Returns the array capacity in elements. More...

VPIStatus	vpiArrayGetStrideBytes (VPIArray array, uint32_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...

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

CUDA memory: vpiArrayCreateCudaMemWrapper
Host/CPU memory: vpiArrayCreateHostMemWrapper

Data Structure Documentation

◆ VPIArrayData

struct VPIArrayData

Stores information about array characteristics and content.

Definition at line 116 of file Array.h.

Collaboration diagram for VPIArrayData:

Data Fields
uint32_t	capacity	Maximum number of elements that the array can hold.
void *	data	Points to the first element of the array.
uint32_t	size	Number of elements in the array.
uint32_t	strideBytes	Size in bytes of each array element.
VPIArrayType	type	Type of each array element.

Function Documentation

◆ vpiArrayCreate()

VPIStatus vpiArrayCreate	(	uint32_t	capacity,
		VPIArrayType	fmt,
		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]	capacity	Array capacity in elements.
[in]	fmt	Format 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.

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] array Array handle to be destroyed. Passing NULL is allowed, to which the function simply does nothing.

◆ vpiArrayGetCapacity()

VPIStatus vpiArrayGetCapacity	(	VPIArray	array,
		uint32_t *	capacity
	)

#include <vpi/Array.h>

Returns the array capacity in elements.

Parameters

[in]	array	A valid array handle
[out]	capacity	A 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]	array	A valid array handle.
[out]	flags	A pointer where the flags will be written to.

Returns: an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetSize()

VPIStatus vpiArrayGetSize	(	VPIArray	array,
		uint32_t *	size
	)

#include <vpi/Array.h>

Returns the array size in elements.

Parameters

[in]	array	A valid array handle.
[out]	size	A 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,
		uint32_t *	strideBytes
	)

#include <vpi/Array.h>

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

Parameters

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

Returns: an error code on failure else VPI_SUCCESS.

◆ vpiArrayGetType()

VPIStatus vpiArrayGetType	(	VPIArray	array,
		VPIArrayType *	type
	)

#include <vpi/Array.h>

Returns the array type.

Parameters

[in]	array	A valid array handle.
[out]	type	A pointer where the array type will be written to.

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] array An 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]	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.

Returns: an error code on failure else VPI_SUCCESS.

◆ vpiArraySetSize()

VPIStatus vpiArraySetSize	(	VPIArray	array,
		uint32_t	size
	)

#include <vpi/Array.h>

Set the array size in elements.

Parameters

[in]	array	A valid array handle.
[in]	size	The 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] array A valid array handle.

Returns: an error code on failure else VPI_SUCCESS.

VPI - Vision Programming Interface

0.4.4 Release

Data Structures

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ VPIArrayData

Function Documentation

◆ vpiArrayCreate()

◆ vpiArrayDestroy()

◆ vpiArrayGetCapacity()

◆ vpiArrayGetFlags()

◆ vpiArrayGetSize()

◆ vpiArrayGetStrideBytes()

◆ vpiArrayGetType()

◆ vpiArrayInvalidate()

◆ vpiArrayLock()

◆ vpiArraySetSize()

◆ vpiArrayUnlock()