通用一维数组的抽象表示。更多...

数据结构
结构体	VPIArrayBufferAOS
	存储关于数组特性和内容的信息。更多...

结构体	VPIArrayBuffer
	表示访问数组内容的可用方法。更多...

结构体	VPIArrayData
	存储关于数组特性和内容的信息。更多...

类型定义
typedef struct VPIArrayImpl *	VPIArray
	数组的句柄。

枚举
枚举	VPIArrayBufferType
	表示数组数据的存储方式。更多...

枚举	VPIArrayType
	数组元素格式。更多...

函数
VPIStatus	vpiArrayCreate (int32_t capacity, VPIArrayType type, uint64_t flags, VPIArray *array)
	创建一个空的数组实例。更多...

VPIStatus	vpiArrayCreateWrapper (const VPIArrayData data, uint64_t flags, VPIArray array)
	通过封装现有的主机内存块来创建数组对象。更多...

VPIStatus	vpiArraySetWrapper (VPIArray array, const VPIArrayData *data)
	在现有的 VPIArray 封装器中重新定义封装的内存缓冲区。更多...

void	vpiArrayDestroy (VPIArray array)
	销毁数组实例。更多...

VPIStatus	vpiArrayGetSize (VPIArray array, int32_t *size)
	返回数组大小（以元素为单位）。更多...

VPIStatus	vpiArraySetSize (VPIArray array, int32_t size)
	设置数组大小（以元素为单位）。更多...

VPIStatus	vpiArrayGetCapacity (VPIArray array, int32_t *capacity)
	返回数组容量（以元素为单位）。更多...

VPIStatus	vpiArrayGetStrideBytes (VPIArray array, int32_t *strideBytes)
	返回数组步长（两个连续元素之间的距离），以字节为单位。更多...

VPIStatus	vpiArrayGetFlags (VPIArray array, uint64_t *flags)
	返回数组标志。更多...

VPIStatus	vpiArrayGetType (VPIArray array, VPIArrayType *type)
	返回数组类型。更多...

VPIStatus	vpiArrayLock (VPIArray array, VPILockMode mode)
	获取数组对象的锁。更多...

VPIStatus	vpiArrayLockData (VPIArray array, VPILockMode mode, VPIArrayBufferType bufType, VPIArrayData *data)
	获取数组对象的锁并返回数组内容。更多...

VPIStatus	vpiArrayUnlock (VPIArray array)
	释放数组对象的锁。更多...

详细描述

通用一维数组的抽象表示。

使用 API 创建一维数组容器有两种方法。最基本的方法是使用 vpiArrayCreate 来分配和初始化一个空的（零初始化的）VPIArray 对象。数组数据的内存由后端实现分配和管理。容量和类型等参数是不可变的，并在构造时指定。内部内存布局也是后端特定的。更重要的是，不同硬件块之间高效的数组数据交换可能迫使实现程序在多个内存池（例如，dGPU 和系统 DRAM）中分配内存。在某些情况下（为了优化性能和内存使用），限制内部分配策略以仅支持一组特定的后端可能是有益的。

为了实现与现有主机端或 GPU 端代码的互操作，用户还可以创建一个数组对象，该对象封装用户分配（和管理）的数组数据。与 vpiArrayCreate 类似，传递给 vpiArrayCreateWrapper 的数组参数是固定的。

只要新的封装内存具有与原始封装内存相同的缓冲区类型、容量和类型，就可以通过调用 vpiArraySetWrapper 来重新定义封装的内存。一次创建 VPIArray 封装器并在以后重用它，比一直创建和销毁它更有效。

vpiArrayLockData / vpiArrayUnlock 集合允许从主机读取/写入数组数据。这些函数是非阻塞的，并且忽略流命令队列，因此用户有责任确保所有使用此数组作为输入或输出的挂起操作都已完成。此外，根据内存分配在哪个设备上，锁定/解锁操作可能非常耗时，例如，对于 dGPU，可能涉及通过 PCIe 总线复制数据。

数据结构文档

◆ VPIArrayBufferAOS

struct VPIArrayBufferAOS

存储关于数组特性和内容的信息。

将数组信息表示为结构体数组（AOS）。

定义于文件 Array.h 的第 115 行。

VPIArrayBufferAOS 的协作图

数据字段
VPIArrayType	type	每个数组元素的类型。
int32_t *	sizePointer	指向数组中元素数量的指针。必须 >= 0。
int32_t	capacity	数组可以容纳的最大元素数量。必须 >= 0。
int32_t	strideBytes	每个数组元素的大小（以字节为单位）。必须 >= 0。必须至少与元素大小一样大。必须是元素大小的倍数。
void *	data	指向数组的第一个元素。

◆ VPIArrayBuffer

struct VPIArrayBuffer

表示访问数组内容的可用方法。

正确的方法取决于 VPIArrayData::bufferType 。

定义于文件 Array.h 的第 155 行。

VPIArrayBuffer 的协作图

数据字段

VPIArrayBufferAOS

aos

以结构体数组布局存储的数组。

当 VPIArrayData::bufferType 为

◆ VPIArrayData

struct VPIArrayData

存储关于数组特性和内容的信息。

定义于文件 Array.h 的第 167 行。

VPIArrayData 的协作图

数据字段
VPIArrayBufferType	bufferType	数组缓冲区类型。它定义了必须使用 VPIArrayBuffer 标记联合的哪个成员来访问数组内容。
VPIArrayBuffer	buffer	存储数组内容。

枚举类型文档

◆ VPIArrayBufferType

enum VPIArrayBufferType

#include <vpi/Array.h>

表示数组数据的存储方式。

枚举器

VPI_ARRAY_BUFFER_INVALID

无效的缓冲区类型。

通常用于表示未选择缓冲区类型。

VPI_ARRAY_BUFFER_HOST_AOS

主机可访问的结构体数组。

VPI_ARRAY_BUFFER_CUDA_AOS

CUDA 可访问的结构体数组。

定义于文件 Array.h 的第 139 行。

◆ VPIArrayType

enum VPIArrayType

#include <vpi/ArrayType.h>

数组元素格式。

枚举器
VPI_ARRAY_TYPE_INVALID	信号类型转换错误。
VPI_ARRAY_TYPE_S8	有符号 8 位。
VPI_ARRAY_TYPE_U8	无符号 8 位。
VPI_ARRAY_TYPE_S16	有符号 16 位。
VPI_ARRAY_TYPE_U16	无符号 16 位。
VPI_ARRAY_TYPE_U32	无符号 32 位。
VPI_ARRAY_TYPE_KEYPOINT_F32	VPIKeypointF32 元素。
VPI_ARRAY_TYPE_HOMOGRAPHY_TRANSFORM_2D	VPIHomographyTransform2D 元素。
VPI_ARRAY_TYPE_KLT_TRACKED_BOUNDING_BOX	VPIKLTTrackedBoundingBox 元素。
VPI_ARRAY_TYPE_F32	32 位浮点数。
VPI_ARRAY_TYPE_KEYPOINT_U32	VPIKeypointU32 元素，U32 格式。
VPI_ARRAY_TYPE_KEYPOINT_UQ1616	VPIKeypointU32 元素，UQ1616 定点格式。
VPI_ARRAY_TYPE_STATISTICS	VPIStats 元素。
VPI_ARRAY_TYPE_BRIEF_DESCRIPTOR	VPIBriefDescriptor 元素。
VPI_ARRAY_TYPE_MATCHES	VPIMatches 元素。
VPI_ARRAY_TYPE_DCF_TRACKED_BOUNDING_BOX	VPIDCFTrackedBoundingBox 元素。
VPI_ARRAY_TYPE_PYRAMIDAL_KEYPOINT_F32	VPIPyramidalKeypointF32 元素。
VPI_ARRAY_TYPE_APRILTAG_DETECTION	VPIAprilTagDetection 元素。
VPI_ARRAY_TYPE_POSE	VPIPose 元素。

定义于文件 ArrayType.h 的第 69 行。

函数文档

◆ vpiArrayCreate()

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

#include <vpi/Array.h>

创建一个空的数组实例。

数组数据被初始化为零。数组的最大容量是固定的，并在构造时定义。数组大小设置为零。 VPIArray 对象拥有分配的内存。

参数

[in]	capacity	capacity 必须 >= 0。
[in]	type	每个数组元素的类型。数组容量，以元素为单位。
[in]	flags	type 不能为 VPI_ARRAY_TYPE_INVALID。 flags 位字段，指定数组的期望特性。. 该字段必须是零个或多个以下标志的组合
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	通用对象标志	如果给定标志 VPI_REQUIRE_BACKENDS，则用户必须至少传递一个有效的后端，并且它们都必须在当前上下文中启用。

[out]

array	指向将接收创建的数组句柄的内存的指针。
返回值	VPI_ERROR_INVALID_ARRAY_TYPE
返回值	无效的 `type`。
返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	无效的 `flags`。
`capacity` 超出有效范围。	`array` 为 NULL 或不表示 VPIArray 实例。
未给出后端且设置了 VPI_REQUIRE_BACKENDS。	VPI_ERROR_OUT_OF_MEMORY
没有足够的资源来分配数组。	VPI_ERROR_INVALID_CONTEXT
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

请求的后端在当前上下文中未启用。

VPI_SUCCESS	(	操作成功执行。	data,
		uint64_t	flags,
		VPIArray *	array
	)

#include <vpi/Array.h>

◆ vpiArrayCreateWrapper()

VPIStatus vpiArrayCreateWrapper

const VPIArrayData *

参数

[in]

data

uint64_t

[in]

flags

VPIArray *	array
VPI_ARRAY_BUFFER_HOST_AOS	通过封装现有的主机内存块来创建数组对象。
VPI_ARRAY_BUFFER_CUDA_AOS	当不再使用返回的句柄时，必须通过调用 vpiArrayDestroy 来销毁它。

不能为 VPI_ARRAY_TYPE_INVALID。
- flags
- 位字段，指定数组的期望特性。.
该对象不拥有封装的内存。用户仍然负责封装内存的生命周期，该生命周期必须在数组对象销毁之前有效。
参数

参数

VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。通用对象标志如果给定标志 VPI_REQUIRE_BACKENDS，则用户必须至少传递一个有效的后端，并且它们都必须在当前上下文中启用。

[out]

返回值	[in]
返回值	data
返回值	指向要封装的内存缓冲区的结构的指针。
返回值	无效的 `flags`。
`capacity` 超出有效范围。	强制性，不能为 NULL。
未给出后端且设置了 VPI_REQUIRE_BACKENDS。	VPI_ERROR_OUT_OF_MEMORY
没有足够的资源来分配数组。	VPI_ERROR_INVALID_CONTEXT
没有足够的资源来分配数组。	flags
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

位字段，指定数组的期望特性。根据某些缓冲区类型，将自动添加以下标志

缓冲区类型	(	添加的标志	通用对象标志,
		操作成功执行。	VPI_ARRAY_BUFFER_HOST_AOS
	)

#include <vpi/Array.h>

VPI_BACKEND_CPU

VPI_ARRAY_BUFFER_CUDA_AOS

VPI_BACKEND_CUDA

参数

[in]	通用对象标志	如果给定了后端并且设置了 VPI_REQUIRE_BACKENDS，则它们都必须在当前上下文中启用。如果自动添加了后端，则它们必须在当前上下文中启用。 [out]
[in]	data	array uint64_t 指针，用于接收创建的数组句柄。返回值 VPI_ERROR_INVALID_ARGUMENT

[out]

返回值	`array` 为 NULL。
返回值	`data` 为 NULL 或包含无效/不支持的值。
返回值	`flags` 无效。
没有足够的资源来分配数组。	`capacity` 无效。
没有足够的资源来分配数组。	`type` 无效。
没有足够的资源来分配数组。	`strideBytes` 无效。
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

`sizePointer` 无效。

data 中的缓冲区类型不受支持。 ( 添加的标志 通用对象标志 )

#include <vpi/Array.h>

VPI_ERROR_OUT_OF_MEMORY

没有足够的资源来创建数组。

参数

[in]

通用对象标志

VPI_ERROR_INVALID_CONTEXT

当前上下文已销毁。

VPI_ERROR_INVALID_OPERATION

自动添加的后端标志在当前上下文中未启用。	(	添加的标志	通用对象标志,
		VPI_SUCCESS	操作成功执行。
	)

#include <vpi/Array.h>

◆ vpiArraySetWrapper()

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	VPIArray	array uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	const VPIArrayData *
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

data

在现有的 VPIArray 封装器中重新定义封装的内存缓冲区。	(	添加的标志	通用对象标志,
		int32_t	操作成功执行。
	)

#include <vpi/Array.h>

此操作是高效的，并且不分配内存。封装的内存将可被封装器创建期间指定的相同后端访问。

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
[in]	VPIArray	封装的内存在其仍然被封装时不得被释放。参数必须 >= 0。

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	[in]
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

array

数组句柄。	(	添加的标志	通用对象标志,
		VPI_SUCCESS	它必须由 vpiArrayCreateWrapper 创建。
	)

#include <vpi/Array.h>

数组不得被锁定。

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	capacity	data uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	指向要封装的主机内存的结构的指针。
当前上下文已销毁。	现有的封装数组和新数组必须具有相同的容量和元素类型。

旧的和新的缓冲区类型必须匹配。

封装的内存必须指向与给定缓冲区类型对应的缓冲区。	(	添加的标志	通用对象标志,
		VPI_SUCCESS	返回值
	)

#include <vpi/Array.h>

VPI_ERROR_INVALID_ARGUMENT

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	strideBytes	`data` 为 NULL。 uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	`data` 具有不受支持的缓冲区类型。
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

新旧缓冲区类型不匹配。

`array` 不是使用 vpiArrayCreateWrapper 创建的。	(	添加的标志	通用对象标志,
		`data` 容量和/或格式与 `array` 不匹配。	VPI_ERROR_BUFFER_LOCKED
	)

#include <vpi/Array.h>

array 被锁定。

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	flags	VPI_SUCCESS uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	操作成功执行。
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

◆ vpiArrayDestroy()

void vpiArrayDestroy	(	添加的标志	通用对象标志,
		VPIArray	array
	)

#include <vpi/Array.h>

销毁数组实例。

参数

[in]	通用对象标志	VPIStatus vpiArraySetWrapper uint64_t
VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。	type	此函数释放数组创建函数分配的所有资源。销毁 VPIArray 封装器时，封装的内存本身不会被释放。 uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	参数
当前上下文已销毁。	VPI_ERROR_INVALID_OPERATION

[in]

array	(	添加的标志	通用对象标志,
		要销毁的数组句柄。允许传递 NULL，函数对此不执行任何操作。	先决条件
	)

#include <vpi/Array.h>

数组不得被任何流使用，否则将导致未定义的行为。

◆ vpiArrayGetSize()

VPIStatus vpiArrayGetSize

参数

[in]	通用对象标志	VPIArray uint64_t array
[in]	int32_t *	size 返回数组大小（以元素为单位）。参数 [in] array

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
有效的数组句柄。	[out]
当前上下文已销毁。	现有的封装数组和新数组必须具有相同的容量和元素类型。

size

指向变量的指针，该变量将被设置为数组的大小。	(	添加的标志	通用对象标志,
		要销毁的数组句柄。允许传递 NULL，函数对此不执行任何操作。	int32_t * ,
		返回值	VPI_ERROR_INVALID_ARGUMENT,
		输出 `size` 指针为 NULL。	VPI_ARRAY_BUFFER_HOST_AOS
	)

#include <vpi/Array.h>

VPI_SUCCESS

操作成功执行。

VPIStatus vpiArrayGetSize

参数

[in]

通用对象标志

VPIArray

uint64_t
array

◆ vpiArraySetSize()

VPIArray *	VPIStatus vpiArraySetSize
VPI_ARRAY_BUFFER_HOST_AOS	通过封装现有的主机内存块来创建数组对象。
VPI_ARRAY_BUFFER_CUDA_AOS	当不再使用返回的句柄时，必须通过调用 vpiArrayDestroy 来销毁它。

[in]

VPI_ERROR_INVALID_ARGUMENT

VPIArray

[in]

int32_t *

size

返回数组大小（以元素为单位）。
- 参数
- [in]
- array

VPIBackend 标志。此数组可用于在这些后端中运行的算法。如果没有传递后端标志，并且 VPI_REQUIRE_BACKENDS 标志不存在，则它将考虑活动上下文支持的所有后端。

data

array

int32_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
返回值	`array` 为 NULL。
返回值	size
没有足够的资源来分配数组。	设置数组大小（以元素为单位）。
有效的数组句柄。	[out]
当前上下文已销毁。	现有的封装数组和新数组必须具有相同的容量和元素类型。

参数

[in] ( 添加的标志 通用对象标志 )

#include <vpi/Array.h>

array

有效的数组句柄。

size

参数

[in]

通用对象标志

VPIStatus vpiArraySetWrapper

uint64_t

[out]

返回值	VPI_ERROR_INVALID_ARGUMENT
没有足够的资源来分配数组。	数组的新大小。
当前上下文已销毁。	现有的封装数组和新数组必须具有相同的容量和元素类型。

VPI - 视觉编程接口

3.2 版本

数据结构

类型定义

枚举

函数

详细描述

数据结构文档

◆ VPIArrayBufferAOS

◆ VPIArrayBuffer

◆ VPIArrayData

枚举类型文档

◆ VPIArrayBufferType

◆ VPIArrayType

函数文档

◆ vpiArrayCreate()

请求的后端在当前上下文中未启用。

位字段，指定数组的期望特性。根据某些缓冲区类型，将自动添加以下标志

`sizePointer` 无效。

VPI_ERROR_INVALID_OPERATION

data

array

旧的和新的缓冲区类型必须匹配。

新旧缓冲区类型不匹配。

◆ vpiArrayDestroy()

[in]

size

参数

VPI - 视觉编程接口

3.2 版本

数据结构

类型定义

枚举

函数

详细描述

数据结构文档

◆ VPIArrayBufferAOS

◆ VPIArrayBuffer

◆ VPIArrayData

枚举类型文档

◆ VPIArrayBufferType

◆ VPIArrayType

函数文档

◆ vpiArrayCreate()

请求的后端在当前上下文中未启用。

位字段，指定数组的期望特性。根据某些缓冲区类型，将自动添加以下标志

sizePointer 无效。

VPI_ERROR_INVALID_OPERATION

data

array

旧的和新的缓冲区类型必须匹配。

新旧缓冲区类型不匹配。

◆ vpiArrayDestroy()

[in]

size

参数

`sizePointer` 无效。