六、API 参考

6.1 libdmabufheap 接口详解

本节覆盖内存管理相关 API，按功能分组说明，并在每组下给出 C++/C 对应接口。

6.1.1 分配器生命周期管理

以下接口来自 include/BufferAllocator/BufferAllocatorWrapper.h，用于 C 侧生命周期管理。 这些接口仅在 C API 提供，C++ API 无一一对应项，原因如下：

• CreateDmabufHeapBufferAllocator / FreeDmabufHeapBufferAllocator：C++ 通过 BufferAllocator 对象构造与析构管理生命周期，不需要显式创建/释放函数。
• GetStaticAllocator / ReleaseStaticAllocator：这是 C 封装层为兼容 C 调用方式提供的进程级静态实例访问接口；C++ 侧可直接在调用方管理对象或使用静态对象模式。

6.1.1.1 CreateDmabufHeapBufferAllocator

描述

创建分配器实例。

语法

BufferAllocator* CreateDmabufHeapBufferAllocator();

返回值

返回值	描述
非 NULL	成功，返回分配器 BufferAllocator 句柄
NULL	失败

6.1.1.2 FreeDmabufHeapBufferAllocator

描述

释放通过 CreateDmabufHeapBufferAllocator 创建的实例。

语法

void FreeDmabufHeapBufferAllocator(BufferAllocator* buffer_allocator);

参数说明

参数名称	描述	输入/输出
buffer_allocator	分配器 BufferAllocator 句柄（可为 NULL）	输入

6.1.1.3 GetStaticAllocator

描述

获取进程级静态分配器实例。

语法

BufferAllocator* GetStaticAllocator();

返回值

返回值	描述
非 NULL	返回分配器 BufferAllocator 句柄实例

注意事项

• 静态实例在进程生命周期内有效，调用方不应释放。

6.1.1.4 ReleaseStaticAllocator

描述

静态分配器释放占位接口（当前实现为 no-op）。

语法

void ReleaseStaticAllocator(BufferAllocator* buffer_allocator);

参数说明

参数名称	描述	输入/输出
buffer_allocator	分配器 BufferAllocator 句柄指针	输入

6.1.2 缓冲区分配

6.1.2.1 C++：BufferAllocator::Alloc

描述

从指定 DMA-BUF heap 分配缓冲区。

语法

int Alloc(const std::string& heap_name, size_t len);

参数说明

参数名称	描述	输入/输出
heap_name	heap 名称，如 carveout-heap、linux,cma、system	输入
len	申请大小（字节）	输入

返回值

返回值	描述
>= 0	成功，返回 dmabuf fd
< 0	失败，返回错误码

注意事项

• 返回的 fd 由调用方负责 close()。
• heap_name 需要是系统已存在的 /dev/dma_heap/* 设备名。

6.1.2.2 C：DmabufHeapAlloc

描述

从指定 heap 分配 DMA-BUF。

语法

int DmabufHeapAlloc(BufferAllocator* buffer_allocator, const char* heap_name, size_t len);

参数说明

参数名称	描述	输入/输出
buffer_allocator	分配器 BufferAllocator 句柄，不能为 NULL	输入
heap_name	heap 名称	输入
len	申请大小（字节）	输入

返回值

返回值	描述
>= 0	成功，返回 dmabuf fd
< 0	失败，返回错误值

6.1.3 缓冲区元信息与调试

6.1.3.1 C++：BufferAllocator::GetPhysAddr

描述

查询 DMA-BUF 的物理地址及物理连续长度。

语法

int GetPhysAddr(unsigned int dmabuf_fd, uint64_t* addr, uint64_t* len);

参数说明

参数名称	描述	输入/输出
dmabuf_fd	目标缓冲区 dmabuf fd	输入
addr	输出物理地址	输出
len	输出物理连续长度	输出

返回值

返回值	描述
0	成功
< 0	失败，返回负错误码

注意事项

• 仅在底层 heap 与内核支持物理地址查询时有效。
• addr 和 len 必须为有效指针。

6.1.3.2 C：DmabufHeapGetPhysAddr

描述

获取 DMA-BUF 物理地址与物理连续长度。

语法

int DmabufHeapGetPhysAddr(BufferAllocator* buffer_allocator, unsigned int dmabuf_fd,
                          uint64_t* addr, uint64_t* len);

参数说明

参数名称	描述	输入/输出
buffer_allocator	分配器 BufferAllocator 句柄，不能为 NULL	输入
dmabuf_fd	目标缓冲区 dmabuf fd	输入
addr	输出物理地址	输出
len	输出物理连续长度	输出

返回值

返回值	描述
0	成功
< 0	失败，返回负错误码

6.1.3.3 C++：BufferAllocator::DmabufSetName

描述

设置 DMA-BUF 调试名称。

语法

static int DmabufSetName(unsigned int dmabuf_fd, const std::string& name);

参数说明

参数名称	描述	输入/输出
dmabuf_fd	目标缓冲区 dmabuf fd	输入
name	调试名称字符串	输入

返回值

返回值	描述
0	成功
-1	失败，errno 指示原因

6.1.3.4 C：DmabufSetName

描述

设置 DMA-BUF 调试名称。

语法

int DmabufSetName(BufferAllocator* buffer_allocator, unsigned int dmabuf_fd, const char* name);

参数说明

参数名称	描述	输入/输出
buffer_allocator	分配器 BufferAllocator 句柄，不能为 NULL	输入
dmabuf_fd	目标缓冲区 dmabuf fd	输入
name	调试名称	输入

返回值

返回值	描述
0	成功
-1	失败，errno 指示原因

6.1.3.5 C++：BufferAllocator::GetDmabufHeapList

描述

获取系统可用的 DMA-BUF heap 名称列表。

语法

static std::unordered_set<std::string> GetDmabufHeapList();

返回值

返回值	描述
std::unordered_set<std::string>	可用 heap 名称集合

6.1.4 类型与句柄说明

dmabuf fd（int）

• 本库返回的 fd 是 Linux 文件描述符（File Descriptor），代表一个 DMA-BUF 内核对象引用。
• fd 在“创建它的进程”内直接有效；跨进程使用时，需要通过 FD 传递机制（如 Unix Domain Socket + SCM_RIGHTS）发送给目标进程。
• fd 不是虚拟地址；CPU 访问内存需先执行 mmap，并在完成后 munmap。
• 每次成功分配得到的 fd，都应在不再使用时调用 close(fd)，否则会造成句柄泄漏。
• 一个 fd 可被复制（dup/dup2），每个副本都需要独立 close 才会真正释放引用。

BufferAllocator*

• 在 C 接口中，BufferAllocator* 是不透明句柄（opaque handle），外部不应访问其内部结构。
• 动态实例使用方式：CreateDmabufHeapBufferAllocator 创建，FreeDmabufHeapBufferAllocator 释放。
• 静态实例使用方式：GetStaticAllocator 获取进程级单例；ReleaseStaticAllocator 当前实现为 no-op。

---

6.1.5 libdmabufheap 示例程序

// C++ usage example (Alloc + SetName + mmap + GetPhysAddr)
#include <BufferAllocator/BufferAllocator.h>

#include <sys/mman.h>
#include <unistd.h>
#include <stdint.h>

int main() {
    BufferAllocator allocator;

    const size_t size = 4096;
    int fd = allocator.Alloc("carveout-heap", size); // or "system", "linux,cma"
    if (fd < 0) return -1;

    (void)BufferAllocator::DmabufSetName((unsigned int)fd, "demo_cpp_dmabuf");

    void* vaddr = mmap(nullptr, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (vaddr != MAP_FAILED) {
        ((volatile uint8_t*)vaddr)[0] = 0x5A;
        munmap(vaddr, size);
    }

    uint64_t phys = 0, phys_len = 0;
    (void)allocator.GetPhysAddr((unsigned int)fd, &phys, &phys_len);

    close(fd);
    return 0;
}

/* C usage example (Create + Alloc + SetName + mmap + GetPhysAddr + close + Free) */
#include <BufferAllocator/BufferAllocatorWrapper.h>

#include <sys/mman.h>
#include <unistd.h>
#include <stdint.h>

int main(void) {
    BufferAllocator* allocator = CreateDmabufHeapBufferAllocator();
    if (!allocator) return -1;

    size_t size = 4096;
    int fd = DmabufHeapAlloc(allocator, "carveout-heap", size);
    if (fd < 0) {
        FreeDmabufHeapBufferAllocator(allocator);
        return -1;
    }

    (void)DmabufSetName(allocator, (unsigned int)fd, "demo_c_dmabuf");

    void* vaddr = mmap(NULL, size, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
    if (vaddr != MAP_FAILED) {
        ((volatile uint8_t*)vaddr)[0] = 0x5A;
        munmap(vaddr, size);
    }

    uint64_t phys = 0, phys_len = 0;
    (void)DmabufHeapGetPhysAddr(allocator, (unsigned int)fd, &phys, &phys_len);

    close(fd);
    FreeDmabufHeapBufferAllocator(allocator);
    return 0;
}

6.2 taCV 接口详解

模块提供的所有接口都是同步接口，用户在调用接口时需要同时提供输入输出 buffer，如果接口返回成功，则输出 buffer 中已含有输出图像。接口依赖 dmabufheap 模块提供帧缓存，用户在创建公共缓存池时，应为本模块预留合适大小和数量的帧缓存。taCV 提供图像处理 SPP 硬件加速接口，可以对图像做 crop、resize 和格式转换的操作。

6.2.1 ta_cv_image_create_ext()

描述

创建并填充一个 ta_image_t 结构体。建议使用该接口创建ta_image_t结构体。

语法

tacv_status_t ta_cv_image_create_ext(
    int                   img_h,
    int                   img_w,
    ta_image_format_ext_t image_format,
    ta_image_t*           p_image, 
    unsigned int          blk_id
);

参数说明

参数名称	描述	输入/输出
img_h	图像高度	输入
img_w	图像宽度	输入
image_format	图像格式	输入
data_type	图像的数据格式	输入
p_image	指向 ta_image_t 结构体的指针	输出
blk_id	从 dmabuffer 中申请的内存描述符	输入

返回值

返回值	描述
0	成功
非 0	失败

注意事项

• 强烈建议用户通过专用 API 来创建/销毁 ta_image_t 结构体
• 创建和销毁接口必须成对使用

---

6.2.2 ta_cv_image_destroy_ext()

描述

销毁一个 ta_image_t 结构体。

语法

tacv_status_t ta_cv_image_destroy_ext(
    ta_image_t *p_image
);

参数说明

参数名称	描述	输入/输出
p_image	指向 ta_image_t 结构体的指针	输入

返回值

返回值	描述
0	成功
非 0	失败

注意事项

• 强烈建议用户通过专用 API 来创建/销毁 ta_image_t 结构体
• 创建和销毁接口必须成对使用
• 如果 p_image 引用的帧存是 SDK 申请的，则会在此接口内回收；如果是用户自己申请的，则需要用户自己负责回收

好的，我来帮你将这两个接口文档转换成 Markdown 格式：

6.2.3 ta_cv_image_create()

描述

通过ta_avframe_t结构体创建并填充一个 ta_image_t 结构体。推荐使用ta_cv_image_create_ext()。

语法

tacv_status_t ta_cv_image_create(
    int               img_h,
    int               img_w,
    ta_image_format_t image_format,
    ta_data_type_t    data_type,
    ta_image_t        *p_image,
    ta_avframe_t*     frame
);

参数说明

参数名称	描述	输入/输出
img_h	图像高度，单位是行	输入
img_w	图像宽度，单位是像素	输入
image_format	图像格式 ta_image_format_t	输入
data_type	图像的数据格式	输入
p_image	指向 ta_image_t 结构体的指针	输出
frame	ta_avframe_t 结构体指针(AVFrame)	输出

返回值

返回值	描述
0	成功
非 0	失败

注意事项

• 强烈建议用户通过专用 API 来创建/销毁 ta_image_t 结构体
• 创建和销毁接口必须成对使用

---

6.2.4 ta_cv_image_destroy()

描述

销毁一个 ta_image_t 结构体。

语法

tacv_status_t ta_cv_image_destroy(
    ta_image_t *p_image
);

参数说明

参数名称	描述	输入/输出
p_image	指向 ta_image_t 结构体的指针	输出

返回值

返回值	描述
0	成功
非 0	失败

注意事项

• 强烈建议用户通过专用 API 来创建/销毁 ta_image_t 结构体
• 创建和销毁接口必须成对使用
• 如果 p_image 引用的帧存是 SDK 申请的，则会在此接口内回收；如果是用户自己申请的，则需要用户自己负责回收

6.2.5 ta_cv_image_resize

描述

对输入图像进行缩放处理，当前仅支持图像下采样（downscale），不支持上采样（upscale）。

语法

tacv_status_t ta_cv_image_resize(
    ta_cv_resize_image_t* resize_attr,
    ta_image_t input,
    ta_image_t output);

参数说明

参数名称	描述	输入/输出
resize_attr	ta_cv_resize_image_t指针，保存resize信息	输入
input	输入图像信息	输入
output	输出图像信息	输出

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format	Output_Image_Format
FORMAT_NV12	FORMAT_NV12

注意事项

• 最大缩放比为 128，最大输入输出分辨率为 4096×2160
• 只支持缩小
• crop_width >= resize_width
• 宽/高需为 16 的倍数

6.2.6 ta_cv_image_crop

描述

对输入图像执行裁剪操作。根据指定的裁剪区域，从输入图像中裁剪出一个或多个目标图像。

语法

tacv_status_t ta_cv_image_crop(
    int crop_num,
    ta_cv_rect_t* rects,
    ta_image_t input,
    ta_image_t* output);

参数说明

参数名称	描述	输入/输出
crop_num	需要 crop 的数量	输入
rects	ta_cv_rect_t指针,保存裁剪区域信息	输入
input	输入图像信息	输入
output	输出图像信息指针	输出

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format	Output_Image_Format
FORMAT_NV12	FORMAT_NV12

注意事项

• 输入图像与输出图像的最大分辨率为 4096 × 2016。
• 裁剪区域的宽度 crop_width 和高度 crop_height 必须为偶数。
• 裁剪区域必须位于输入图像有效范围内，即： start_x + crop_width <= input_width start_y + crop_height <= input_height
• 输出图像缓冲区大小 size 必须为 16 的整数倍。

6.2.7 ta_cv_image_csc_convert_to

描述

对输入图像进行预处理，支持裁剪（crop）、缩放（resize）和颜色空间转换（CSC）操作，可单独或组合使用，并将处理结果输出到目标图像。

语法

tacv_status_t ta_cv_image_csc_convert_to(
    ta_image_t input,
    ta_image_t output,
    ta_cv_rect_t crop_rect,
    ta_cv_resize_image_t* resize,
    csc_type_t csc_typ);

参数说明

参数名称	描述	输入/输出
input	输入图像信息	输入
output	输出图像信息	输出
crop_rect	ta_cv_rect_t结构体,保存裁剪区域信息	输入
resize	ta_cv_resize_image_t指针，保存resize信息	输入
csc_typ	csc_type_t颜色空间转换类型	输入

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format	Output_Image_Format
FORMAT_NV12	FORMAT_NV12
FORMAT_NV12	FORMAT_NV21
FORMAT_NV12	FORMAT_RGB_PACKED
FORMAT_NV12	FORMAT_BGR_PACKED
FORMAT_NV12	FORMAT_RGB_PLANAR
FORMAT_NV12	FORMAT_BGR_PLANAR
FORMAT_NV12	FORMAT_ABGR_PACKED
FORMAT_NV12	FORMAT_ARGB_PACKED

注意事项

• 最大缩放比为 128，最大输入输出分辨率为 4096×2160
• 只支持缩小
• crop_width >= resize_width
• 宽/高需为 16 的倍数

6.2.8 ta_cv_image_jpeg_enc

描述

实现对图像进行 JPEG 编码操作。

语法

tacv_status_t ta_cv_image_jpeg_enc(
    ta_image_t* src,
    unsigned int jpeg_data_blk,
    size_t* out_size,
    int quality_factor);

参数说明

参数名称	描述	输入/输出
src	输入图像指针	输入
jpeg_data_blk	输出 buffer 的 blk_id	输入
out_size	输出 buffer 的 size 指针	输入/输出
quality_factor	图像质量因子	输入

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format
FORMAT_NV12
FORMAT_YUV420P

注意事项

• 申请输出 buffer 的大小要大于等于输入 buffer 的大小
• 支持大小 96×32 到 8192×8192（宽×高）
• width 和 height 必须为偶数
• 图像质量因子 quality_factor 的取值范围为 (0, 100]

6.2.9 ta_cv_image_jpeg_dec

描述

实现对 JPEG 图像进行解码操作。

语法

tacv_status_t ta_cv_image_jpeg_dec(
    size_t in_size,
    unsigned int jpeg_in_blk_id,
    ta_image_t *dst);

参数说明

参数名称	描述	输入/输出
in_size	输入图像 buffer 大小	输入
jpeg_in_blk_id	输入图像 block_id	输入
dst	输出图像信息指针	输入/输出

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Output_Image_Format
FORMAT_NV12
FORMAT_NV21
FORMAT_RGB_PACKED
FORMAT_BGR_PACKED
FORMAT_BGR_PLANAR
FORMAT_RGB_PLANAR

注意事项

• 最大输入输出分辨率 32768×32768
• 宽/高需为 16 的倍数
• 调用接口前需要创建输出图像
• 调用接口前需要准备好输入输出 buffer

6.2.10 ta_cv_image_convert_padding

描述

实现对图像进行裁剪（crop）、缩放（resize）、颜色空间转换（CSC）和填充（padding）操作,可单独或组合使用。

语法

tacv_status_t ta_cv_image_convert_padding(
  ta_image_t              input,
  ta_image_t              output,
  ta_cv_rect_t            crop_rect,
  ta_cv_padding_attr_t    padding_attr,
  ta_cv_resize_algorithm_t   algorithm
);

参数说明

参数名称	描述	输入/输出
input	输入图像	输入
output	输出图像	输出
crop_rect	ta_cv_rect_t结构体保存输入图像的裁剪信息	输入
padding_attr	ta_cv_padding_attr_t结构体输出图像位置信息	输入
algorithm	ta_cv_resize_algorithm_t枚举保存缩放算法类型	输入

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format	Output_Image_Format
FORMAT_NV12	FORMAT_NV12
	FORMAT_NV12
	FORMAT_BGR_PACKED
	FORMAT_RGB_PACKED
	FORMAT_BGR_PLANAR
	FORMAT_RGB_PLANAR
	FORMAT_RGBA_PACKED
	FORMAT_BGRA_PACKED

注意事项

• 输出为 NV12 格式最大分辨率为 4096×2160
• 输出 RGB 系列格式最大分辨率为 1920×1080

6.2.11 ta_cv_image_stitch

描述

实现图像拼接的效果，支持裁剪（crop）、缩放（resize）、颜色空间转换（CSC）和填充（padding）操作，可单独或组合使用，可将两张或多张图像拼接到一张图像并输出。

语法

tacv_status_t ta_cv_image_stitch(
  int                     input_num,
  ta_image_t*             input,
  ta_image_t              output,
  ta_cv_rect_t*           dst_crop_rect,
  ta_cv_rect_t*           src_crop_rect,
  ta_cv_resize_algorithm_t algorithm
);

参数说明

参数名称	描述	输入/输出
input_num	输入图像数量	输入
input	输入图像指针	输入
output	输出图像	输出
dst_crop_rect	ta_cv_rect_t结构体保存输出图像中小图的坐标和宽高信息	输入
src_crop_rect	ta_cv_rect_t结构体目标小图的坐标和宽高信息	输入
algorithm	ta_cv_resize_algorithm_t枚举保存缩放算法类型	输入

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Input_Image_Format	Output_Image_Format
FORMAT_NV12	FORMAT_NV12
	FORMAT_NV12
	FORMAT_BGR_PACKED
	FORMAT_RGB_PACKED
	FORMAT_BGR_PLANAR
	FORMAT_RGB_PLANAR
	FORMAT_RGBA_PACKED
	FORMAT_BGRA_PACKED

注意事项

• 输出为 NV12 格式最大分辨率为 4096×2160
• 输出 RGB 系列格式最大分辨率为 1920×1080

6.2.12 ta_cv_copy_to

描述

对输入图像做拷贝操作，把输入图像拷贝到输出图像的指定位置。

语法

tacv_status_t ta_cv_image_copy_to(
  ta_image_t      input,
  ta_image_t      output,
  ta_cv_copy_to_t copy_to_attr
);

参数说明

参数名称	描述	输入/输出
input	输入图像	输入
output	输出图像	输出
copy_to_attr	ta_cv_copy_to_t结构体保存copy 图像位置信息	输入

返回值

返回值	描述
0	成功
非 0	失败

格式支持

Num	Input_Image_Format	Output_Image_Format
1	FORMAT_NV12	FORMAT_NV12

注意事项

• 输入图片分辨率必须小于输出图片分辨率

6.2.13 taCV 结构体说明

关于图像帧

ta_image_t

语法

typedef struct ta_image_s {
    int                      width;
    int                      height;
    int                      plane_num;
    ta_image_format_ext_t    image_format;
    ta_image_data_format_ext_t data_type;
    ta_image_private_t *     image_private;
    ta_image_frame_t         frame;
} ta_image_t;

参数说明

参数名称	描述	备注
width	image 宽
height	image 高
plane_num	image 平面数
image_format	image 格式
data_type	image 数据类型	在 tacv 中，单通道单个像素都为 8bit(即 1N_BYTE)
image_private	image 私有数据	保留参数，暂时没有使用
frame	帧结构体	描述图像 buffer 信息

---

ta_image_frame_t

语法

typedef struct ta_image_frame_s {
    uint8_t *data[8];
    int      width;
    int      height;
    unsigned int  blk_id;
    uint64_t      phy_addr;
    int           size[4];
    int           format;
    uint64_t      phy_len;
} ta_image_frame_t;

参数说明

参数名称	描述	备注
data	各平面的虚拟地址
width	图像宽度
height	图像高度
blk_id	dmabuf 描述符
phy_addr	图片内存物理地址
size	各平面占字节数
format	图片格式
phy_len	图像内存实际物理地址长度

---

ta_image_format_ext_t

语法

typedef enum ta_image_format_ext_e {
    FORMAT_YUV420P,
    FORMAT_YUV422P,
    FORMAT_YUV444P,
    FORMAT_NV12,
    FORMAT_NV21,
    FORMAT_NV16,
    FORMAT_NV61,
    FORMAT_NV24,
    FORMAT_RGB_PLANAR,
    FORMAT_BGR_PLANAR,
    FORMAT_RGB_PACKED,
    FORMAT_BGR_PACKED,
    FORMAT_RGBP_SEPARATE,
    FORMAT_BGRP_SEPARATE,
    FORMAT_GRAY,
    FORMAT_HSV_PLANAR,
    FORMAT_ARGB_PACKED,
    FORMAT_ABGR_PACKED,
    FORMAT_YUV444_PACKED,
    FORMAT_YVU444_PACKED,
    FORMAT_YUV422_YUYV,
    FORMAT_YUV422_YVYU,
    FORMAT_YUV422_UYVY,
    FORMAT_YUV422_VYUY,
    FORMAT_RGBYP_PLANAR,
    FORMAT_HSV180_PACKED,
    FORMAT_HSV256_PACKED,
    FORMAT_BAYER,
} ta_image_format_ext_t;

参数说明

枚举值	描述
FORMAT_YUV420P	三平面 YUV420 格式图片
FORMAT_YUV422P	三平面 YUV422 格式图片
FORMAT_YUV444P	三平面 YUV444 格式图片
FORMAT_NV12	两平面 NV12 格式图片，Y 单独一个平面，UV 交错排列在一个平面
FORMAT_NV21	两平面 NV21 格式图片，Y 单独一个平面，VU 交错排列在一个平面
FORMAT_NV16	两平面 NV16 格式图片，Y 单独一个平面，VU 交错排列在一个平面
FORMAT_NV61	两平面 NV61 格式图片，Y 单独一个平面，VU 交错排列在一个平面
FORMAT_NV24	两平面 NV24 格式图片，Y 单独一个平面，UV 交错排列在一个平面
FORMAT_RGB_PLANAR	单平面 RGB 格式图片，RGB 分开排列（RRR....GGG...BBB）
FORMAT_BGR_PLANAR	单平面 BGR 格式图片，BGR 分开排列（BBB....GGG...RRR）
FORMAT_RGB_PACKED	单平面 RGB 格式图片，RGB 交错排列（RGBRGB...RGB）
FORMAT_BGR_PACKED	单平面 BGR 格式图片，BGR 交错排列（BGRBGR...BGR）
FORMAT_RGBP_SEPARATE	三平面 RGB 格式图片，RGB 分开排列各占一个平面
FORMAT_BGRP_SEPARATE	三平面 BGR 格式图片，BGR 分开排列各占一个平面
FORMAT_GRAY	单平面灰度图格式的图片
FORMAT_HSV_PLANAR	三平面 HSV 格式图片，H 范围 0~180
FORMAT_ARGB_PACKED	单平面 ARGB 格式图片，ARGB 交错排列（ARGBARGB....ARGB）
FORMAT_ABGR_PACKED	单平面 ABGR 格式图片，ABGR 交错排列（ABGRABGR...ABGR）
FORMAT_YUV444_PACKED	单平面 YUV444 格式图片，YUV 交错排列（YUVYUV...YUV）
FORMAT_YVU444_PACKED	单平面 YVU444 格式图片，YVU 交错排列（YVUYVU...YVU）
FORMAT_YUV422_YUYV	单平面 YUV422 格式图片，YUYV 交错排列
FORMAT_YUV422_YVYU	单平面 YUV422 格式图片，YVYU 交错排列
FORMAT_YUV422_UYVY	单平面 YUV422 格式图片，UYVY 交错排列
FORMAT_YUV422_VYUY	单平面 YUV422 格式图片，VYUY 交错排列
FORMAT_RGBYP_PLANAR	四平面 RGBY 格式图片
FORMAT_HSV180_PACKED	单平面的 HSV 格式，HSV 交错排列，H 范围 0~180
FORMAT_HSV256_PACKED	单平面的 HSV 格式，HSV 交错排列，H 范围 0~255
FORMAT_BAYER	单平面 bayer 格式图片，排列方式：RGGBRGGB...RGGB。宽高为偶数

---

关于图像处理

ta_cv_resize_image_t

语法

typedef struct ta_cv_resize_s {
    int  start_x;
    int  start_y;
    int  in_width;
    int  in_height;
    int  out_width;
    int  out_height;
} ta_cv_resize_t;

typedef struct ta_cv_resize_image_s {
    ta_cv_resize_t *resize_img_attr;
    unsigned int   interpolation;
    int            stretch_fit;
} ta_cv_resize_image_t;

参数说明

参数名称	描述	备注
start_x	resize 起始 x 坐标
start_y	resize 起始 y 坐标
in_width	输入图像的 width
in_height	输入图像的 height
out_width	resize 后图像的 width
out_height	resize 后图像的 height
interpolation	缩图所使用的算法
stretch_fit	是否等比例缩放

插值算法枚举

typedef enum ta_cv_resize_algorithm_e {
    TA_CV_INTER_NONE = 0,       // 默认为线性插值
    TA_CV_INTER_LINEAR,
    TA_CV_INTER_LANCZOS,
    TA_CV_INTER_NEAREST,
    TA_CV_INTER_BILINEAR,
    TA_CV_INTER_BICUBIC,
    TA_CV_INTER_SPLINE,
    TA_CV_INTER_BOX,
    TA_CV_INTER_FAST_LINEAR,
    TA_CV_INTER_FAST_BICUBIC,
} ta_cv_resize_algorithm_t;

参数说明

枚举值	描述
TA_CV_INTER_NONE	默认为线性插值
TA_CV_INTER_LINEAR	线性插值算法
TA_CV_INTER_LANCZOS	Lanczos 插值算法
TA_CV_INTER_NEAREST	最邻插值算法
TA_CV_INTER_BILINEAR	双线性插值算法
TA_CV_INTER_BICUBIC	双三次插值算法
TA_CV_INTER_SPLINE	样条插值算法
TA_CV_INTER_BOX	区域插值算法
TA_CV_INTER_FAST_LINEAR	快速线性插值算法
TA_CV_INTER_FAST_BICUBIC	快速双三次插值算法

---

ta_cv_rect_t

语法

typedef struct ta_cv_rect_s {
    int  start_x;
    int  start_y;
    int  crop_w;
    int  crop_h;
} ta_cv_rect_t;

参数说明

参数名称	描述	备注
start_x	crop 起始 x 坐标
start_y	crop 起始 y 坐标
crop_w	crop 的宽度
crop_h	crop 的高度

---

ta_cv_copy_to_t

语法

typedef struct ta_cv_copy_to_s {
    int  start_x;
    int  start_y;
} ta_cv_copy_to_t;

参数说明

参数名称	描述	备注
start_x	copy 至目标图的 x 坐标
start_y	copy 至目标图的 y 坐标

---

ta_cv_padding_attr_t

语法

typedef struct ta_cv_padding_attr_s {
    unsigned int  dst_crop_stx;
    unsigned int  dst_crop_sty;
    unsigned int  dst_crop_w;
    unsigned int  dst_crop_h;
} ta_cv_padding_attr_t;

参数说明

参数名称	描述	备注
dst_crop_stx	输出图像 crop 起始 x 坐标
dst_crop_sty	输出图像 crop 起始 y 坐标
dst_crop_w	输出图像 crop 的宽度
dst_crop_h	输出图像 crop 的高度

---

csc_type_t

语法

typedef enum csc_type_e {
    CSC_NONE = 0,
    CSC_YCbCr2RGB_BT601,    // NV12 转 RGB 的协议
    CSC_RGB2YCbCr_BT601,
    CSC_YCbCr2RGsB_BT709,
    CSC_RGB2YCbCr_BT709,
    CSC_YCbCr2RGB_BT2020,
    CSC_RGB2YCbCr_BT2020
} csc_type_t;

参数说明

枚举值	描述
CSC_NONE	无颜色空间转换
CSC_YCbCr2RGB_BT601	YCbCr 转 RGB (BT.601)
CSC_RGB2YCbCr_BT601	RGB 转 YCbCr (BT.601)
CSC_YCbCr2RGsB_BT709	YCbCr 转 RGB (BT.709)
CSC_RGB2YCbCr_BT709	RGB 转 YCbCr (BT.709)
CSC_YCbCr2RGB_BT2020	YCbCr 转 RGB (BT.2020)
CSC_RGB2YCbCr_BT2020	RGB 转 YCbCr (BT.2020)

---

ta_select_t

语法

typedef enum ta_hw_select_e {
    ENABLE_CPU = 0,   // 使用 cpu
    ENABLE_PPU,       // 使用 ppu 计算
    ENABLE_PP         // 使用 PP 硬件
} ta_hw_select_t;

参数说明

枚举值	描述
ENABLE_CPU	使用 CPU
ENABLE_PPU	使用 PPU 计算
ENABLE_PP	使用 PP 硬件

6.2.7 taCV 示例程序

#include "ta_cv_api_ext_c.h"
#include <stdio.h>
#include <string.h>
#include <BufferAllocator/BufferAllocatorWrapper.h>

int main(int argc, const char** argv)
{
    int ret = 0;
    int width = atoi(argv[2]);
    int height = atoi(argv[3]);
    int out_width = atoi(argv[4]);
    int out_height = atoi(argv[5]);
    int format = FORMAT_NV12;
    int total_size_in = width * height * 1.5;
    int total_size_out = out_width * out_height * 1.5;
    
    unsigned long long physAddr_in = 0;
    unsigned long long physAddr_out = 0;
    ta_image_t image_in,image_out;
    ta_cv_resize_image_t resize_attr = {0};
    ta_cv_resize_t resize = {0};
    
    // 初始化 dmabufheap，获取 block
    BufferAllocator* dmabuf_allocator = CreateDmabufHeapBufferAllocator();
    if (!dmabuf_allocator) {
        return -1;
    }
    
    unsigned int  input_fd = DmabufHeapAlloc(dmabuf_allocator, "carveout-heap", total_size_in);
    unsigned int  output_fd = DmabufHeapAlloc(dmabuf_allocator, "carveout-heap", total_size_out);
    if(input_fd < 0 || output_fd < 0){
        FreeDmabufHeapBufferAllocator(dmabuf_allocator);
        close(input_fd);
        close(output_fd);
        return -1;
    }
    // 创建图像结构体
    
    ret = ta_cv_image_create_ext(height,width,(ta_image_format_ext_t)format,&image_in,input_fd);
    
    ret |= ta_cv_image_create_ext(out_height,out_width,(ta_image_format_ext_t)format,&image_out,output_fd);
    if(ret != TACV_SUCCESS){
        ta_cv_image_destroy_ext(&image_in);
        ta_cv_image_destroy_ext(&image_out);
        close(input_fd);
        close(output_fd);
        return -1;
    }
    FILE *fd = fopen(argv[1], "rb");
    if(fd == NULL){
        goto failed;
    }
    fread(image_in.frame.data[0], total_size_in, 1, fd);
    fclose(fd);

    
    resize.in_height = height;
    resize.in_width = width;
    resize.out_height = out_height;
    resize.out_width = out_width;
    resize.start_x = 0;
    resize.start_y = 0;
    resize_attr.resize_img_attr = &resize;
    resize_attr.interpolation = 3;
    
    // 调用函数
    ret = ta_cv_image_resize(&resize_attr, image_in, image_out);
    
    fd = fopen("resize_output.bin", "wb");
    fwrite(image_out.frame.data[0], total_size_out, 1, fd);
    fclose(fd);
failed:    
    // 释放 block
    ta_cv_image_destroy_ext(&image_in);
    ta_cv_image_destroy_ext(&image_out);
    close(input_fd);
    close(output_fd);
    
    return ret;
}

6.3 taRuntime 接口详解

6.3.1 ta_runtime_init

描述

实现模块初始化流程，为后续模型加载与推理运行做好软硬件准备。

详情

该接口完成硬件和软件相关资源的初始化操作。主要包括初始化 NPU 硬件资源和驱动程序。 本函数应在其他接口调用前执行，每个进程仅需调用一次，且需要与 ta_runtime_deinit 接口配对使用。若未调用该接口即尝试加载模型或进行推理，相关接口会返回失败。

语法

taco_status_t ta_runtime_init();

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 支持多进程、多线程，每个进程都应调用一次，最先调用的生效
• 每个进程仅调用一次即可，不应每个线程都调用

6.3.2 ta_runtime_deinit

描述

实现模块反初始化流程，包括释放已分配的各种资源，关闭 NPU 服务。

详情

本接口用于在应用程序退出前对各种资源进行清理，释放初始化和运行阶段所申请的资源。

语法

taco_status_t ta_runtime_deinit();

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 支持多进程、多线程，每个进程都应调用一次，最后调用的生效
• 每个进程仅调用一次即可，不应每个线程都调用

6.3.3 ta_runtime_load_model_from_file

描述

从文件系统中读取模型文件，解析文件信息并创建可在板端运行的网络模型。

详情

接口从文件系统中读取的是 NB 格式的模型文件，加载到系统域内存区。接口内部对 NB 文件进行解析，提取出 NPU 推理所需的指令流和权重数据，保存在 NN 域内存区。文件解析完毕后，系统域的输入数据就不再需要了，用户可以释放该 buffer。

语法

taco_status_t ta_runtime_load_model_from_file(
    ta_runtime_context *context, 
    const char *model_path, 
    uint32_t core_index);

参数说明

参数	描述	输入/输出
context	ta_runtime_context 类型的结构体指针。该结构体由 SDK 内部逻辑维护，用户需要在相关接口中传递该指针，除此之外无需使用该结构体	输入/输出
model_path	模型路径	输入
core_index	NPU 设备支持两个 cluster，编号为 0 和 1。此参数用于指定模型部署至哪个 cluster 上运行。若模型类型为 dual-core，则该参数必须设置为 0	输入

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 确保在调用该接口前某个进程执行了模块初始化操作

6.3.4 ta_runtime_load_model_at_ddr

描述

从 DDR 内存中读取模型信息，解析并创建可在板端运行的网络。

详情

接口从系统域输入 buffer 读取的是 NB 格式的模型信息，接口内部对 NB 信息进行解析，提取出 NPU 推理所需的指令流和权重数据，保存在 NN 域内存区。解析完成后，系统域输入 buffer 就不再需要了，用户可以释放该 buffer。

语法

taco_status_t ta_runtime_load_model_at_ddr(
    ta_runtime_context *context, 
    void* model, 
    const uint64_t model_size, 
    uint32_t core_index);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
model	模型数据指针	输入
model_size	模型尺寸	输入
core_index	同 ta_runtime_load_model_from_file	输入

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 确保在调用该接口前某个进程执行了模块初始化操作

6.3.5 ta_runtime_query

描述

查询模型输入输出信息、模型推理的总时间，以及模型相关信息。

语法

taco_status_t ta_runtime_query(
    ta_runtime_context *context, 
    const uint32_t property, 
    void *value);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
property	查询指令	输入
value	存放返回结果的 buffer 地址	输入/输出

返回值

错误码	描述
0	成功
非 0	失败

查询命令

查询命令	描述	返回值类型
TACONN_QUERY_DRIVER_VERSION	查询驱动版本	uint32_t
TACONN_QUERY_IN_OUT_NUM	查询输入输出 tensor 个数	taconn_input_ouput_num_t
TACONN_QUERY_INPUT_ATTR	查询输入 tensor 属性	taconn_inout_attr_t
TACONN_QUERY_OUTPUT_ATTR	查询输出 tensor 属性	taconn_inout_attr_t
TACONN_QUERY_LAYER_COUNT	查询网络模型总层数	uint32_t
TACONN_QUERY_NETWORK_NAME	查询网络名称	char[]
TACONN_QUERY_PROFILING	查询模型推理性能数据	taconn_profile_t
TACONN_NETWORK_MEMORY_POOL_SIZE	查询模型占用的 video_memory 内存大小	taconn_memory_size_t

6.3.6 ta_runtime_set_input_cva

描述

用于设置模型的输入数据（图像或张量），输入地址类型为 CPU 虚拟地址，支持拷贝和映射两种访问方式。

详情

所谓输入数据，具体是指模型的第一层算子所需的输入数据，它的具体形式取决于模型的要求。多数模型需要一幅图像作为输入，有些模型可能需要两幅或者更多图像。而图像格式可以有 NV12、RGB、Tensor 等多种选项，图像的数据精度一般是 INT8。 该接口支持一次设置多个输入，因此用户需要提供一个 taconn_input_t 结构体的数组，并且确保结构体的所有参数均已正确赋值，未使用的参数应清零。 如果使用拷贝方式，本接口会在 NN 域申请一个 buffer（涉及存储空间+虚拟地址两种资源），将输入数据拷贝到 NN 域 buffer，所以接口返回后输入 buffer 可以立即释放。NN 域 buffer 会在推理结束后由 SDK 自动释放。 如果使用映射方式，本接口会在 NN 域申请一段虚拟地址，并与输入数据所在的内存页面建立映射关系。接口返回后输入 buffer 不能立即释放，必须等推理结束后才能释放。NN 域虚拟地址会在推理结束后由 SDK 自动释放。

语法

taco_status_t ta_runtime_set_input_cva(
    ta_runtime_context *context, 
    uint32_t input_num, 
    taconn_input_t *input);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
input_num	模型输入的个数	输入
input	指针，指向一个taconn_input_t类型的数组	输入

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 结构体在赋值前应整体清零，在参数有误的情况下，清零有利于故障现象的一致性
• 输入数量不应超过模型所需的输入个数，否则接口会报错
• 输入数据的地址必须是 256 对齐（地址指针的低 8 位全为 0），否则接口会报错

6.3.7 ta_runtime_set_input_pha

描述

用于设置模型的输入数据，输入地址类型为物理地址。

详情

本接口内部将输入的物理地址映射为 NPU 虚拟地址，一次推理结束后，接口内部会尝试把虚拟地址缓存到内部查找表中，待模块卸载时统一释放。 该接口支持多个输入，因此用户需要提供一个 taconn_input_phy_t 结构体的数组，并且确保结构体的所有参数均已正确赋值，未使用的参数应清零。 本接口内部在 NN 域申请一段虚拟地址，并与输入数据所在的内存页面建立映射关系。接口返回后输入 buffer 不能立即释放，必须等推理结束后才能释放。NN 域虚拟地址会优先缓存在接口内部的查找表中，待模块销毁时由 SDK 自动释放；如果未能缓存到查找表则会立即释放。

语法

taco_status_t ta_runtime_set_input_pha(
    ta_runtime_context *context, 
    uint32_t input_num, 
    taconn_input_phy_t *input);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
input_num	模型输入的个数	输入
input	指向taconn_input_phy_t类型结构体数组。每个元素代表一个输入的物理地址段信息，包括物理地址表和对应大小表	输入

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 用户应在开始推理前完成输入 buffer 的设置，如果设置不全，推理接口会报错
• 本接口允许用户针对同一目标通道多次设置输入 buffer，旧的设置自动失效
• 结构体在赋值前应整体清零，在参数有误的情况下，清零有利于故障现象的一致性
• 输入数量不应超过模型所需的输入个数，否则接口会报错
• 输入数据的地址必须是 256 对齐（地址指针的低 8 位全为 0），否则接口会报错

6.3.8 ta_runtime_create_buffer

描述

用于在 NN 域创建一个保存推理输出结果的缓冲区。

详情

本接口与 ta_runtime_set_output() 接口配合使用，作为该接口的前序接口，用于准备模型输出 buffer。 用户在调用本接口时，仅需传入所需 buffer 的大小，接口内部会自动分配内存并填充taconn_buffer_t结构体内容，包括数据指针、buffer size 等信息。结构体 data 字段指向的地址是一个可供 CPU 访问的虚拟地址指针，用户可通过该指针读取推理输出结果。

语法

taco_status_t ta_runtime_create_buffer(
    ta_runtime_context *context, 
    uint32_t size, 
    taconn_buffer_t *buffer);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
size	需要创建的 buffer 大小	输入
buffer	指针，指向一个taconn_buffer_t结构体	输出

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 用户需要根据模型情况计算 buffer 大小，如果 buffer 不够大，后序接口会失败
• 本接口应与 ta_runtime_destroy_buffer() 接口成对使用

6.3.9 ta_runtime_destroy_buffer

描述

销毁由 ta_runtime_create_buffer() 创建的 NN 域 buffer，并释放对应的 CPU 虚拟地址资源。

语法

taco_status_t ta_runtime_destroy_buffer(
    ta_runtime_context *context,
    taconn_buffer_t *buffer);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
buffer	指向待销毁的taconn_buffer_t类型结构体。该结构体需由 ta_runtime_create_buffer() 创建，函数调用后其内部数据指针即失效	输入&输出

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 本接口应与 ta_runtime_create_buffer() 接口成对使用
• 用户程序应在销毁前停止访问 taconn_buffer_t 的成员变量
• 应避免多次调用销毁同一 buffer 结构体，或销毁未初始化的 buffer，否则产生 UB 行为

6.3.10 ta_runtime_set_output

描述

设置模型推理的输出 buffer。

详情

本接口为模型的指定输出通道设置一个 NN 域输出 buffer，模型推理结束后，用户通过 NN 域 buffer 对应的 CPU 虚拟地址读取推理结果。 本接口与 ta_runtime_create_buffer() 接口配合使用，作为该接口的后序接口。

语法

taco_status_t ta_runtime_set_output(
    ta_runtime_context *context, 
    uint32_t output_num, 
    taconn_buffer_t *buffer);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
output_num	模型的输出个数	输入
buffer	taconn_buffer_t结构体指针	输入

返回值

错误码	描述
0	成功
非 0	失败

注意事项

• 用户应在开始推理前设置输出 buffer，否则推理接口会报错

6.3.11 ta_runtime_invalidate_buffer

描述

将 CPU cache 中与 NN 域 buffer 对应的虚拟地址标记为 invalid，确保下次会从 DDR 中读取数据。

详情

NPU 完成推理后，用户程序读取推理结果前需调用本接口，确保 CPU 能够读取到 DDR 中的最新数据，而不是从缓存中读取旧数据。

语法

taco_status_t ta_runtime_invalidate_buffer(
    ta_runtime_context *context,
    taconn_buffer_t *buffer);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入
buffer	指向taconn_buffer_t类型结构体的指针，表示待刷新缓存的一块 NN 域缓冲区。该结构体应由 ta_runtime_create_buffer() 创建并合法初始化	输入

返回值

错误码	描述
0	成功
非 0	失败

6.3.12 ta_runtime_run_network

描述

执行一次模型推理。

详情

在调用本接口进行推理前，需要先设置好模型的输入输出 buffer。

语法

taco_status_t ta_runtime_run_network(ta_runtime_context *context);

参数说明

参数	描述	输入/输出
context	同 ta_runtime_load_model_from_file	输入

返回值

错误码	描述
0	成功
非 0	失败

6.3.13 ta_runtime_destroy_context

描述

销毁 NNRT 上下文对象，并释放其关联的所有资源。

详情

该接口用于释放上下文对象 ta_runtime_context 及其内部管理的所有资源。 调用后，传入的 context 指针将被置为 0，表示已无效，不可再被用于任何 NNRT 操作。

语法

taco_status_t ta_runtime_destroy_context(ta_runtime_context *context);

参数说明

参数	描述	输入/输出
context	指向要销毁的 ta_runtime_context 结构体指针	输入/输出

返回值

错误码	描述
0	成功
非 0	失败

6.3.14 taRuntime结构体说明

taconn_input_ouput_num_t

结构体 taconn_input_ouput_num_t 用来表示输入输出 tensor 个数，其结构体成员变量如下表所示：

成员变量	数据类型	含义
input_num	uint32_t	输入 tensor 个数
output_num	uint32_t	输出 tensor 个数

taconn_inout_attr_t

结构体 taconn_inout_attr_t 用来表示输入输出 tensor 属性，包含了输入输出的维度、数据类型、量化格式以及量化参数等，其结构体成员变量如下表所示：

成员变量	数据类型	含义
index	uint32_t	输入输出索引
dim_count	uint32_t	输入或输出 tensor 的维度数量
dim_size	unsigned long	输入输出 tensor 在每个维度上的大小
data_format	uint32_t	输入或者输出数据的格式
quant_format	uint32_t	输入输出 tensor 的量化类型
quant_data	union	输入输出的量化数据
quant_data.dfp.fixed_point_pos	int32_t	量化格式为 dfp 时，量化参数
quant_data.affine.tf_scale	float	量化格式为 affine 时，scale 参数
quant_data.affine.tf_zero_point	int32_t	量化格式为 affine 时，zero point 参数

taconn_input_t

结构体 taconn_input_t 表示模型的一个数据输入，用来作为参数传给 taco_nnrt_set_input_cva。

结构体定义如下：

成员变量	数据类型	含义
index	uint32_t	输入索引
data	void *	模型输入数据地址
size	uint32_t	buffer 大小

taconn_input_phy_t

结构体 taconn_input_phy_t 表示模型的一个数据输入，用来作为参数传给 taco_nnrt_set_input_pha。

成员变量	数据类型	含义
physical_num	uint32_t	物理地址数量。表示 physical_table 和 size_table 中有效条目的个数。
physical_table	uint64_t *	指向物理地址数组的指针，每个地址为 64 位物理地址。可用于直接映射到 NN 域内存。
size_table	uint32_t *	描述每段物理内存的有效数据长度。

taconn_buffer_t

结构体 taconn_buffer_t 表示一个创建的 nn buffer，用来作为参数传给 taco_nnrt_create_buffer 和 taco_nnrt_set_output。

成员变量	数据类型	含义
data	void *	NN 域 buffer 对应的 cpu 虚指针
size	uint32_t	buffer 大小

taconn_profile_t

结构体 taconn_profile_t 用于表示模型在推理时的性能指标。

成员变量	数据类型	含义
inference_time	uint32_t	模型推理一帧数据的总耗时
total_cycle	uint32_t	模型推理一帧使用的 cycle 总数

6.4 taOpenCV 接口说明

TACO SDK提供的taOpenCV基于社区版OpenCV进行扩展，并对部分常用图像处理与视觉算法实现了硬件加速和向量加速。其中一部分优化基于玄铁的C920 CPU的RVV扩展指令集，对图像缩放、插值滤波、颜色空间变换、通道分离合并、二值化、LK 光流、金字塔等常用算子算法进行了向量加速。另一类优化则面向专用硬件处理路径，对 JPEG 编解码、图像缩放、格式转换及裁剪等功能提供了硬件加速支持

TACO SDK 中提供的 taOpenCV 相关版本信息如下。

OpenCV 版本	OS 版本	CPU 版本	RVV 版本
4.5.4	Linux 6.6	玄铁 C920V2	1.0

关于 OpenCV 库的使用说明可参考 「OpenCV 官方网站」，关于 RISC-V RVV 的版本差异情况可参考 「RISC-V 官方 GitHub」。

6.4.1 硬件加速内存分配

为支持硬件加速，需要为相关数据分配满足硬件访问要求的内存。在本方案中，对 OpenCV 的 MatAllocator 分配机制进行了扩展，实现了其子类 DmaBufMatAllocator。该分配器基于底层 dmabufheap 接口申请可供硬件直接访问的内存资源，并重写了 allocate 方法，在分配过程中以 dmaMalloc 替代默认的 fastMalloc，同时完成缓冲区描述符及相关物理地址信息的初始化与绑定。 在 OpenCV 内部流程中，可通过校验该内存块关联的描述符等元数据，识别当前 Mat 是否具备硬件加速所需的内存属性，从而决定是否进入对应的硬件加速处理路径。

相关结构体扩展

struct CV_EXPORTS UMatData
{
    ...
    uint64 addr;
    unsigned int blk_id;
    ...
}

u->addr = physAddr; 
u->blk_id = dmabuf_fd;

其中：

• addr：物理地址
• blk_id：内存块描述符（dmabuf fd）

获取dmabuf heap分配器

int width = 640;
int height = 640;
Mat img;
//方法一
img.allocator = hal::getAllocator()；
img.create(height*3/2,width,CV_8UC1)；
//方法二
Mat::setDefaultAllocator(hal::getAllocator());//全局内存分配器设置
Mat img2(height*3/2,width,CV_8UC1);

• 上述方式可为 Mat对象指定Dmabuf heap分配器，以便后续硬件加速接口直接使用，推荐使用方法一。

6.4.2 taOpenCV API 功能扩展

OpenCV 原生支持的一些 API 函数，如 imread()、imwrite()，可以自动识别 JPEG 格式并进行编解码处理。SDK 对这些 API 函数进行了扩展，使其能够自动选择合适的芯片硬件来完成任务。

Mat(AVFrame *frame)

描述 通过 AVFrame 创建 Mat 对象。 参数说明

参数	描述	输入/输出
frame	与ffmpeg 的 AVFrame 对象对应。	输入

返回值

返回Mat 对象。

imread( const String& filename, int flags = IMREAD_COLOR )

描述

读取并解码输入的JPEG图片，并返回解码后的Mat对象。 当前仅对输入的JPEG图片提供硬件加速支持，输出格式支持RGB和NV12。

参数说明

参数	描述	输入/输出
filename	输入的文件名	输入
flags	输入的标志位	输入

自定义flags说明

枚举值	描述
IMREAD_COLOR_YUV	将 JPEG 解码结果以 NV12 格式存入返回的 Mat 对象中。
IMREAD_RETRY_SOFTDEC	默认优先使用硬件解码；当希望强制回退时，可设置该标志位以启用软件解码。

返回值

返回Mat 对象。

注意

• 接口解码JPEG文件时默认硬件加速
• 若需强制回退成软件解码，可将flags标志位设置成IMREAD_COLOR|IMREAD_RETRY_SOFTDEC。
• 将标志位设置为IMREAD_COLOR_YUV解码出NV12格式图像。

示例

Mat img = imread("test.jpg");//JPEG解码输出bgr格式
Mat img = imread("test.jpg",IMREAD_COLOR_YUV);//JPEG解码输出NV12格式
Mat img = imread("test.jpg",IMREAD_COLOR|IMREAD_RETRY_SOFTDEC);不使用硬件解码加速

imwrite( const String& filename, InputArray img,const std::vector<int>& params = std::vector<int>());

描述

对输入图像进行编码并保存为指定文件格式。 当前仅支持 基于 NV12 输入的 JPEG 编码硬件加速。

参数说明

参数	描述	输入/输出
filename	输入的文件名	输入
img	输入的mat	输入
params	编码参数	输入

返回值

参数	描述
true	成功
flase	失败

注意

• 当 params 设置为 IMWRITE_JPEG_SAMPLING_FACTOR 和 IMWRITE_JPEG_SAMPLING_FACTOR_NV12 对应参数对时，启用 NV12 格式 JPEG 编码硬件加速。

示例

vector<int> param;
param.push_back(cv::IMWRITE_JPEG_SAMPLING_FACTOR); // 指定为NV12格式
param.push_back(cv::IMWRITE_JPEG_SAMPLING_FACTOR_NV12);
Mat img;
img.allocator = hal::getAllocator;
img.create(640*3/2,640,CV_8UC1);
imwrite("test.jpg",img,param);

resize( InputArray _src, OutputArray _dst, Size dsize,double inv_scale_x, double inv_scale_y, int interpolation )

描述

对图像进行缩放处理。当前对 NV12 格式图像的缩放提供硬件加速支持。

参数说明

参数名称	描述	输入/输出	备注
_src	输入图像	输入	需为 NV12 格式以启用硬件加速
_dst	输出图像	输出	需预先分配足够大小的内存
dsize	输出尺寸，格式 (宽，高)	输入	设为 None 则由 fx/fy 计算
inv_scale_x	水平缩放因子	输入
inv_scale_y	垂直缩放因子	输入
interpolation	插值算法选择	输入	默认值为 INTER_LINEAR

插值算法

枚举值	描述
INTER_NEAREST	最邻插值算法
INTER_LINEAR	线性插值算法

返回值

无返回值（void）

注意事项

• 当前仅支持 NV12 格式图像使用硬件加速，其他格式将回退到软件实现
• 当前硬件加速路径仅支持缩小（downscale），不支持放大（upscale）

使用示例

// JPEG 解码输出 NV12 格式图像
cv::Mat img = cv::imread("test.jpg", cv::IMREAD_COLOR | cv::IMREAD_COLOR_YUV);

// 创建输出图像，使用 DmaBuf heap 分配器以启用硬件加速
cv::Mat img_out;
img_out.allocator = cv::hal::getAllocator();
img_out.create(640 * 3 / 2, 640, CV_8UC1);

// 执行缩放操作（输入分辨率需大于输出分辨率）
cv::resize(img, img_out, cv::Size(640, 640));

// 保存结果
cv::imwrite("output.jpg", img_out);

cvtColor(InputArray _src,OutputArray _dst,int code，int dcn = 0)

描述

对输入图像进行颜色空间格式转换。当前对 NV12 转 RGB24/BGR24 的场景提供硬件加速支持。

参数说明

参数名称	描述	输入/输出	备注
_src	输入图像	输入
_dst	输出图像	输出
code	色彩转换码	输入
dcn	输出图像通道数	输入

注意事项

• 仅当 code 为 COLOR_YUV2RGB_NV12 或 COLOR_YUV2BGR_NV12 时，才会启用硬件加速。
• 当前硬件加速路径仅支持 NV12 -> RGB24/BGR24 转换。

使用示例

Mat img = imread("test.jpg", IMREAD_COLOR_YUV);  // JPEG 解码输出 NV12 格式
Mat img_out;
img_out.allocator = hal::getAllocator;
img_out.create(640, 640, CV_8UC3);
cvtColor(img, img_out, COLOR_YUV2RGB_NV12);

Crop(Mat &m,OutputArray dst,Rect rect)

描述

对图像进行裁剪。当前只对 NV12 格式图像的裁剪提供硬件加速支持。

参数说明

参数名称	描述	输入/输出	备注
m	输入图像	输入
dst	输出图像	输出
rect	裁剪区域信息	输入

注意事项

• 只支持 NV12 的图片格式进行硬件加速。

使用示例

Mat img = imread("test.jpg", IMREAD_COLOR_YUV);  // JPEG 解码输出 NV12 格式
Mat img_out;
img_out.allocator = hal::getAllocator();
img_out.create(640*3/2,640,CV_8UC1);
Crop(img, img_out, Rect(0, 0, 640, 640));

6.4.3 RVV 加速接口

TACO SDK 提供的 taOpenCV 库对部分接口进行了优化，其中，有些接口是使用了 RISC-V RVV 向量指令集实现的加速，下表对此类接口进行了汇总。

优化算子	支持数据类型	参数说明
add	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素做加运算
sub	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素做减运算
max	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素求最大值
min	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素求最小值
mul	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素做乘法运算
absdiff	u8/s8/u16/s16/s32/f32/f64	两个数组差值的绝对值（求帧差）
div	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素做除法运算
recip	u8/s8/u16/s16/s32/f32/f64	数组元素的倒数运算
addWeighted	u8/s8/u16/s16/s32/f32/f64	两个数组逐个元素做加权相加运算（alpha 运算）
and/or/xor/not	u8	按位做逻辑操作（与/或/异或/非）
cmp	u8/s8/u16/s16/s32/f32/f64	数组元素比较运算
split	u8/s8/u16/s32/s64	将一个多通道数组分割成多个单通道数组
merge	u8/s8/u16/s32/s64	将几个单通道数组合并成一个多通道数组
fastAtan	f32/f64	快速计算反正切值
BoxFilter	u8	3x3, cn=1, norm
Resize	u8	INTER_LINEAR, Area, Nearest
Threshold	u8/s8/u16/s16/f32/f64	图像阈值化
Sobel	u8->s16, u8->f32	Sobel 边缘检测算子，3x3, cn=1; 5x5, cn=1
MedianBlur	u8	3x3, 5x5
BGRtoBGR	u8	bgr/bgra/rgb/rgba
BGRtoBGR5x5	u8	bgr/bgra/rgb/rgba->bgr565/bgr555
BGR5x5toBGR	u8	bgr565/bgr555->bgr/bgra/rgb/rgba
BGRtoGray	u8	bgr/bgra/rgb/rgba->gray
GraytoBGR	u8	gray->bgr/bgra/rgb/rgba
BGRtoYUV	u8	bgr/bgra/rgb/rgba->YUV Planar
YUVtoBGR	u8	YUV Planar->bgr/bgra/rgb/rgba
BGRtoXYZ	u8	bgr/bgra/rgb/rgba->XYZ
XYZtoBGR	u8	XYZ->bgr/bgra/rgb/rgba
TwoPlaneYUVtoBGR	u8	YUV Semi-Planar (NV12/NV21/etc.)
ThreePlaneYUVtoBGR	u8	YUV Planar (YUV420P/etc.)
BGRtoThreePlaneYUV	u8	YUV Planar (YUV420P/etc.)
BGRtoTwoPlaneYUV	u8	YUV Semi-Planar (NV12/NV21/etc.)
OnePlaneYUVtoBGR	u8	单平面 YUV 转 BGR
Dilate	u8	3x3, cn=1,4; 4x4, cn=1; 5x5, cn=1; 15x15, cn=1
Erode	u8	3x3, cn=1,4; 4x4, cn=1; 5x5, cn=1; 15x15, cn=1
WarpAffine	u8	INTER_LINEAR (BORDER_REPLIATE/CONSTANT) NEAREST (BORDER_REPLIATE/CONSTANT)
WarpPrespective	u8	INTER_LINEAR (BORDER_REPLIATE/CONSTANT)
GaussianBlur	u8	7x7, cn=1
PyrDown	u8	BORDER_CONSTANT, cn=1/2/3/4
OptFlowPyrLK	u8	光流金字塔 LK 算法
countNTaonZero	u8	cn=1
convert	u8/s8/u16/s16/s32/f32/f64	数据类型转换
norm1	u8	L2, no mask
minMaxLo	f32	max_val, no mask
calcMinEigenVal	f32	计算最小特征值
calcHarris	f32	Harris 角点检测

6.4.4 taOpenCV 示例程序

#include "opencv2/opencv.hpp"
#include <iostream>

//推荐用法
int main( int argc, const char** argv )
{
    std::string filename = "./fruits.jpg";
    image = cv::imread(filename,IMREAD_COLOR_YUV);
    //error handling skipped
    Crop(image,);
    Mat scaled;
    scaled.allocator = hal::getAllocator();
    scaled.create(100 * 3 /2,100,CV_8UC1);

    cv::resize(image_nv12, scaled, cv::Size(100,100), 0, 0, cv::INTER_LINEAR);

    vector<int> param;
    param.push_back(cv::IMWRITE_JPEG_SAMPLING_FACTOR); // 指定为NV12格式
    param.push_back(cv::IMWRITE_JPEG_SAMPLING_FACTOR_NV12);
    cv::imwrite("./output.jpg", scaled, param);

    return 0;
}

6.5 taFFmpeg 接口说明

TACO SDK 提供的 taFFmpeg 基于 FFmpeg 官方的 4.3.2 版本，我们对 FFmpeg 进行了一些扩展，使其能够自动选择合适的芯片硬件来完成任务。前文已经对 taFFmpeg 有了一些描述，这个章节对支持的编解码器进行补充说明。

6.5.1 视频解码器

用户可通过如下命令来查询 taFFmpeg 支持的解码器。

ffmpeg -decoders

其结果中应包含由 TACO SDK 提供的硬件加速版 H.264 解码器，名称为 h264_taco。 用户可以通过如下命令行查询硬件解码器提供的一些额外选项：

ffmpeg -h decoder=h264_taco
ffmpeg -h decoder=hevc_taco

目前已经支持的选项有：

参数名称	功能描述	取值范围	默认值
vdec_output_semi_planar	指定输出图像的平面格式	0 ~ 输出 YUV420 Planar 图像；1 ~ 输出 YUV420 Semi-planar 图像	0
vdec_extra_frame_buffer_num	额外提供的帧缓存数量	大于等于 1 的整数	2
vdec_stream_addr_type	Bitstream 数据指针的类型	0 ~ 物理地址，页面连续；1 ~ 虚拟地址，页面连续；2 ~ 虚拟地址，页面不保证连续	0
vdec_fps_decimation	解码后哪些帧需要写入 DDR	0 ~ 全部写入 DDR；1 ~ 写一帧跳一帧；2 ~ 写一帧跳两帧	0

这些选项可以使用 taFFmpeg 提供的 av_dict_set() 接口进行设置。

6.5.2 视频编码器

用户可通过如下命令来查询 taFFmpeg 支持的编码器。

ffmpeg -encoders

其结果中应包含由 TACO SDK 提供的硬件加速版 H.264 编码器，名称为 h264_taco。 用户可以通过如下命令行查询硬件编码器提供的一些额外选项：

ffmpeg -h encoder=h264_taco

目前已经支持的选项有：

参数名称	功能描述	取值范围	默认值
venc_quality_mode	指定编码的质量模式	0 ~ 速度优先，质量低；1 ~ 均衡模式；2 ~ 质量优先，速度低	2
venc_gop_size	设置一个 GOP 包含的帧数	大于等于 1 的整数	30
venc_rc_mode	码率控制算法	0 ~ fixed qp；1 ~ vbr；2 ~ cbr	2
venc_yuv_addr_type	YUV 数据指针的类型	0 ~ 物理地址，页面连续；1 ~ 虚拟地址，页面连续；2 ~ 虚拟地址，页面不保证连续	0

这些选项可以使用 taFFmpeg 提供的 av_dict_set() 接口进行设置。

6.5.3 JPEG 解码器

用户可以通过如下命令行查询硬件 JPEG 解码器是否已安装：

ffmpeg -decoders | grep jpeg_taco

用户可以通过如下命令行查询 JPEG 硬件解码器提供的一些额外选项：

ffmpeg -h decoder=jpeg_taco

目前已经支持的选项有：

参数名称	功能描述	取值范围	默认值
jdec_bs_buffer_size	设置输入流缓冲区的大小	大于 0 的整数	2
jdec_extra_frame_buffer_num	额外提供的帧缓存数量	大于等于 0 的整数，建议：Jpeg 可以为 0，mjpeg 大于 0	2
jdec_stream_addr_type	Bitstream 数据指针的类型	0 ~ 物理地址，页面连续；1 ~ 虚拟地址，页面连续；2 ~ 虚拟地址，页面不保证连续	0

这些选项可以使用 taFFmpeg 提供的 av_dict_set() 接口进行设置。

6.5.4 JPEG 编码器

用户可以通过如下命令行查询硬件编码器提供的一些额外选项：

ffmpeg -encoders | grep jpeg_taco

用户可以通过如下命令行查询 JPEG 硬件解码器提供的一些额外选项：

ffmpeg -h encoder=jpeg_taco

目前已经支持的选项有：

参数名称	功能描述	取值范围	默认值
jenc_bs_buffer_size	设置输出流缓冲区的大小	大于 0 的整数	500*1024
jenc_yuv_addr_type	YUV 数据指针的类型	0 ~ 物理地址，页面连续；1 ~ 虚拟地址，页面连续；2 ~ 虚拟地址，页面不保证连续	0

6.5.5 结构体定义

AVFrame 结构体的定义位于 libavutil/frame.h 中，它封装了一个视频帧的多种信息，包括图像数据（编码前或解码后的未压缩数据）、时间戳、像素格式、分辨率等。

下面是一些关键字段的介绍：

• data: 指针数组，每个指针指向视频帧数据的一个颜色通道（数据平面）。例如，对于 ffmpeg 默认的 YUV420P 格式，data[0] 指向 Y 分量，data[1] 和 data[2] 分别指向 U 和 V 分量
• linesize: 数组，对于图像的每个颜色通道，记录它的一行数据在内存中实际占用的字节数。它的大小取决于像素格式以及数据对齐要求。而数据对齐要求一般是源于生成或者消费这帧图像的硬件的特性
• format: 视频帧的像素格式（例如 AV_PIX_FMT_YUV420P）
• width, height: 视频帧的宽度和高度
• pts, pkt_dts: 时间戳信息，用于表示帧的显示时间

在使用 taFFmpeg 进行视频处理时，通常会涉及到以下接口：

1. 解码: 使用 avcodec_receive_frame() 接口从解码器获取解码后的视频帧
2. 处理: 使用 sws_scale() 接口对 AVFrame 中的数据进行缩放、裁剪或格式转换等视频处理操作
3. 编码: 使用 avcodec_send_frame() 接口将处理后的 AVFrame 帧编码为压缩格式
4. 释放: 使用 av_frame_free() 释放 AVFrame 结构体占用的内存

AVPacket 是 taFFmpeg 中很重要的一个数据结构，其中 A 代表 Audio，V 代表 Video。AVPacket 用于保存解复用之后、解压缩之前的音视频数据，以及关于这些数据的一些附加信息（side data），例如，显示时间戳（pts）、解码时间戳（dts）、数据时长（duration）、所在流媒体的索引（stream_index）等。

在使用 AVPacket 时有几个重要事项需要注意：

1. AVPacket 的本质是一个数据描述体，它本身并不随身携带媒体数据，而是通过 data 指针指向音视频数据的缓存位置。所以，当对 AVPacket 结构体进行复制的时候，它所描述的音视频数据并没有被复制
2. AVPacket 结构体描述视频时，它通常只包含一个完整的 Frame，而音频则有可能包含多个 Frame
3. 允许存在一种特殊的 AVPacket，它只含有附加信息（side data）而没有音视频数据（data）

6.6 ta-vo 接口说明

6.6.1 设备管理 (ta_vo_dev)

6.6.1.1 ta_vo_dev_create()

描述

创建视频输出设备上下文，并进行设备初始化。

语法

ta_vo_dev_ctx *ta_vo_dev_create(ta_vo_dev dev);

参数说明

参数	类型	说明
dev	ta_vo_dev	视频输出设备标识，指定要创建的设备类型。

返回值

返回值	描述
指向新创建的 ta_vo_dev_ctx 结构体的指针	成功
NULL	失败

---

6.6.1.2 ta_vo_dev_set_attr()

描述

设置视频输出设备的公共属性。

语法

int ta_vo_dev_set_attr(ta_vo_dev_ctx *dev_ctx, const ta_vo_dev_attr *attr);

参数说明

参数	类型	说明
dev_ctx	ta_vo_dev_ctx *	视频输出设备上下文指针
attr	const ta_vo_dev_attr *	设备属性结构体指针，包含设备配置参数

返回值

返回值	描述
0	成功
非0	失败

---

6.6.1.3 ta_vo_dev_get_attr()

描述

获取视频输出设备的公共属性。

语法

int ta_vo_dev_get_attr(ta_vo_dev_ctx *dev_ctx, ta_vo_dev_attr **attr);

参数说明

参数	类型	说明
dev_ctx	ta_vo_dev_ctx *	视频输出设备上下文指针
attr	ta_vo_dev_attr **	用于接收设备属性结构体指针的二级指针

返回值

返回值	描述
0	成功
非0	失败

---

6.6.2 图层管理 (ta_vo_layer)

6.6.2.1 ta_vo_layer_set_attr()

描述

设置图层属性，并进行硬件初始化和资源配置。

语法

int ta_vo_layer_set_attr(ta_vo_layer_ctx *layer_ctx, const ta_vo_layer_attr *layer_attr);

参数说明

参数	类型	说明
layer_ctx	ta_vo_layer_ctx *	视频图层上下文指针
layer_attr	const ta_vo_layer_attr *	图层属性结构体指针，包含图层配置参数

返回值

返回值	描述
0	成功
负错误码（-ENODEV, -ENOMEM, ... ）	失败(帧缓冲设备未找到或打开失败, 内存分配失败, ...)

---

6.6.2.2 ta_vo_layer_get_attr()

描述

获取视频图层的属性。

语法

int ta_vo_layer_get_attr(ta_vo_layer_ctx *layer_ctx, ta_vo_layer_attr *layer_attr);

参数说明

参数	类型	说明
layer_ctx	ta_vo_layer_ctx *	视频图层上下文指针
layer_attr	ta_vo_layer_attr *	图层属性结构体指针，用于接收图层配置参数

返回值

返回值	描述
0	成功
非0	失败

---

6.6.2.3 ta_vo_layer_create()

描述

创建并初始化一个图层上下文。

语法

ta_vo_layer_ctx *ta_vo_layer_create(ta_vo_layer layer);

参数说明

参数	类型	说明
layer	ta_vo_layer	图层标识，指定要创建的图层号。取值范围参考 ta_vo_layer 枚举定义

返回值

返回值	描述
ta_vo_layer_ctx * (非NULL)	成功，返回指向新创建的图层上下文结构体的指针
NULL	失败，内存分配失败（通过日志输出错误信息）

---

6.6.2.4 ta_vo_layer_destroy()

描述

销毁视频图层上下文，释放所有相关资源。

语法

int ta_vo_layer_destroy(ta_vo_layer_ctx *layer_ctx);

参数说明

参数	类型	说明
layer_ctx	ta_vo_layer_ctx *	要销毁的视频图层上下文指针

返回值

返回值	描述
0	成功
非0	失败

---

6.6.2.5 ta_vo_layer_enable()

描述

启用视频图层，配置缩放器（如果启用），并启动显示线程。

语法

int ta_vo_layer_enable(ta_vo_layer_ctx *layer_ctx);

参数说明

参数	类型	说明
layer_ctx	ta_vo_layer_ctx *	视频图层上下文指针

返回值

返回值	描述
0	成功
-1	失败，定时器创建或设置失败

---

6.6.2.6 ta_vo_layer_bind_to_dev()

描述

绑定视频层或图形层到指定设备。

语法

int ta_vo_layer_bind_to_dev(ta_vo_layer_ctx *layer_ctx, ta_vo_dev_ctx *dev_ctx);

参数说明

参数	类型	说明
layer_ctx	ta_vo_layer_ctx *	视频图层上下文指针
dev_ctx	ta_vo_dev_ctx *	视频输出设备上下文指针

返回值

返回值	描述
0	成功
-EPERM	失败: dev_ctx 或 layer_ctx 为 NULL

---

6.6.3 通道管理 (ta_vo_chn)

6.6.3.1 ta_vo_chn_create()

描述

创建一个视频通道。

语法

ta_vo_chn_ctx *ta_vo_chn_create(ta_vo_chn chn);

参数说明

参数	类型	说明
chn	ta_vo_chn	通道编号，指定要创建的通道号。取值范围：[0, TA_VO_MAX_CHN_NUMS]

返回值

返回值	描述
ta_vo_chn_ctx * (非NULL)	成功，返回指向新创建的通道上下文结构体的指针
NULL	失败，内存分配失败（通过日志输出错误信息）

---

6.6.3.2 ta_vo_chn_set_attr()

描述

设置指定视频输出通道的属性，并根据帧率配置定时器。

语法

int ta_vo_chn_set_attr(ta_vo_chn_ctx *chn_ctx, ta_vo_chn_attr *chn_attr);

参数说明

参数	类型	说明
chn_ctx	ta_vo_chn_ctx *	视频通道上下文指针
chn_attr	ta_vo_chn_attr *	视频通道属性结构体指针，包含帧率等配置参数

返回值

返回值	描述
0	成功
-1	失败，定时器创建或设置失败
0（特殊）	当帧率（chn_attr->fps）为0时，立即返回（不创建定时器）

---

6.6.3.3 ta_vo_chn_bind_to_layer()

描述

将指定输出通道绑定到图层。

语法

int ta_vo_chn_bind_to_layer(ta_vo_chn_ctx *chn_ctx, ta_vo_layer_ctx *layer_ctx);

参数说明

参数	类型	说明
chn_ctx	ta_vo_chn_ctx *	要绑定的视频通道上下文指针
layer_ctx	ta_vo_layer_ctx *	目标视频图层上下文指针

返回值

返回值	描述
0	成功
-EPERM	失败，通道上下文或图层上下文指针为空

---

6.6.3.4 ta_vo_chn_send_frame()

描述

将帧数据送入指定视频输出通道进行显示。

语法

int ta_vo_chn_send_frame(ta_vo_chn_ctx *chn_ctx, const ta_vo_frame *frame);

参数说明

参数	类型	说明
chn_ctx	ta_vo_chn_ctx *	通道上下文指针
frame	const ta_vo_frame *	要显示的帧数据指针

返回值

返回值	描述
0	成功
-1	失败，帧数据无效

---

6.6.4 回写管理 (ta_vo_wb)

6.6.4.1 ta_vo_wb_create()

描述

创建回写设备。

语法

ta_vo_wb_ctx *ta_vo_wb_create(ta_vo_wb wb);

参数说明

参数	类型	说明
wb	ta_vo_wb	回写设备标识

返回值

返回值	描述
ta_vo_wb_ctx * (非NULL)	成功，返回指向新创建的回写设备上下文结构体的指针
NULL	失败，内存分配失败

---

6.6.4.2 ta_vo_wb_set_attr()

描述

设置指定回写设备的回写源属性。

语法

int ta_vo_wb_set_attr(ta_vo_wb_ctx *wb_ctx, const ta_vo_wb_attr *wb_attr);

参数说明

参数	类型	说明
wb_ctx	ta_vo_wb_ctx *	回写设备上下文指针
wb_attr	const ta_vo_wb_attr *	回写属性结构体指针，包含回写源等配置参数

返回值

返回值	描述
0	成功
-1	失败: wb_ctx 或 wb_attr 为 NULL

---

6.6.4.3 ta_vo_wb_enable()

描述

启用指定的回写设备。

语法

int ta_vo_wb_enable(ta_vo_wb_ctx *wb_ctx);

参数说明

参数	类型	说明
wb_ctx	ta_vo_wb_ctx *	回写设备上下文指针

返回值

返回值	描述
0	成功

---

6.6.4.4 ta_vo_wb_bind_to_layer()

描述

将回写设备绑定到指定图层。

语法

int ta_vo_wb_bind_to_layer(ta_vo_wb_ctx *wb_ctx, ta_vo_layer_ctx *layer_ctx);

参数说明

参数	类型	说明
wb_ctx	ta_vo_wb_ctx *	回写设备上下文指针
layer_ctx	ta_vo_layer_ctx *	目标视频图层上下文指针

返回值

返回值	描述
0	成功
-1	失败: wb_ctx 或 layer_ctx 为 NULL

---

6.6.4.5 ta_vo_wb_get_frame()

描述

获取回写视频数据。

语法

ta_vo_wb_frame *ta_vo_wb_get_frame(ta_vo_wb_ctx *wb_ctx);

参数说明

参数	类型	说明
wb_ctx	ta_vo_wb_ctx *	回写设备上下文指针

返回值

返回值	描述
ta_vo_wb_frame * (非NULL)	成功，返回指向回写帧结构体的指针
NULL	失败: wb_ctx 或 layer_ctx 无效，或内存分配失败

---

6.6.4.6 ta_vo_wb_put_frame()

描述

释放回写视频数据。

语法

int ta_vo_wb_put_frame(ta_vo_wb_ctx *wb_ctx, ta_vo_wb_frame *frame);

参数说明

参数	类型	说明
wb_ctx	ta_vo_wb_ctx *	回写设备上下文指针
frame	ta_vo_wb_frame *	要释放的回写帧结构体指针

返回值

返回值	描述
0	成功
-1	失败: wb_ctx、frame 或 layer_ctx 为 NULL

---

6.6.5 ta-vo 结构体及相关字段说明

1. ta_vo_chn_ctx

说明

视频通道上下文结构体，封装了单个视频输出通道的所有运行时状态和配置信息，包括帧数据、属性设置、定时器及绑定关系等。

定义

typedef struct {
    ta_vo_frame *frame;
    ta_vo_chn chn;
    ta_vo_chn_attr *chn_attr;
    int frame_processed;
    int timer_fd;
    void *layer_ctx;
} ta_vo_chn_ctx;

成员

字段名	类型	说明
frame	ta_vo_frame *	指向当前视频帧的指针
chn	ta_vo_chn	通道编号。取值范围：[0, TA_VO_MAX_CHN_NUMS]
chn_attr	ta_vo_chn_attr *	指向通道属性的指针
frame_processed	int	帧处理状态标志（0:未处理, 1:已处理）
timer_fd	int	定时器文件描述符，用于帧率同步。当 chn_attr->fps > 0 时由 ta_vo_chn_set_attr 自动创建
layer_ctx	void *	指向绑定图层的上下文指针。通过 ta_vo_chn_bind_to_layer 函数设置

---

2. ta_vo_chn

说明

定义通道号

定义

typedef unsigned int ta_vo_chn;

---

3. ta_vo_layer_ctx

说明

视频图层上下文结构体，封装了单个显示图层的完整硬件和软件状态，包括帧缓冲设备管理、内存映射、双缓冲机制、通道绑定关系及显示线程控制等。

定义

typedef struct {
	int fd;
	int fmt;
	ta_vo_layer virtual_layer_id;
	unsigned char *smem_start;
	unsigned long smem_start_phys_addr;
	int buffer_nums;
	ta_vo_frame *frame[MAX_QUEUES];
	unsigned int disp_blk_id[MAX_QUEUES];
	unsigned long disp_blk_size;
	int enabled;
	ta_vo_dev_ctx *dev_ctx;
	TA_AVDictionaryEntry elems[MAX_QUEUES];
	TA_AVDictionary metadata[MAX_QUEUES];
	struct fb_fix_screeninfo fix; // fb固定参数
	pthread_t show_thread_id;
	int timer_fd;
	ta_vo_layer_attr attr;
	char str_blk_id[MAX_QUEUES][TA_VO_LAYER_MAX][16];
	int chn_nums;
	ta_vo_chn_ctx *chn_ctx[TA_VO_CHN_MAX];
	unsigned int fb_size;
	int idle_buf_id;
	void *wb_ctx;
	volatile unsigned int back_buf_id;
	volatile unsigned int front_buf_id;
	volatile unsigned int buf_locked[MAX_QUEUES];
	pthread_cond_t cond;
	volatile unsigned int dev_can_continue;
	volatile unsigned int wb_can_continue;
	pthread_mutex_t mutex;
	pthread_t dev_show_thread_id;
} ta_vo_layer_ctx;

成员

字段名	类型	说明
fd	int	帧缓冲设备文件描述符。取值：>0表示有效，≤0表示无效或未打开
fmt	int	像素格式标识。取值：TA_AV_PIX_FMT_NV12, TA_AV_PIX_FMT_ARGB, TA_AV_PIX_FMT_RGB24
virtual_layer_id	ta_vo_layer	虚拟图层 ID（如 TA_VO_LAYER_VIDEO_0）
fb_node_name	char[16]	帧缓冲设备节点名称（如 "/dev/fb0"）
disp_area	ta_vo_rect	显示区域信息（位置和大小）

| smem_start | unsigned char * | 显示缓冲区的虚拟起始地址。通过taco_sys_mmap_noncache获得 | | smem_start_phys_addr | unsigned long | 显示缓冲区的物理起始地址。通过taco_sys_handle2_phys_addr转换 | | buffer_nums | int | 缓冲区数量（双缓冲=2，三缓冲=3） | | frame | ta_vo_frame | *[MAX_QUEUES] 帧数据指针数组 |

| disp_blk_id | unsigned int | 显示内存块ID，由taco_sys_get_block分配 | | disp_blk_size | unsigned long | 显示内存块大小 | | enabled | int | 图层启用状态（0:禁用, 1:启用） | | dev_ctx | ta_vo_dev_ctx * | 指向绑定设备的上下文指针。通过ta_vo_dev_bind_to_layer设置 | | elems | TA_AVDictionaryEntry | 元数据条目结构体，存储单个键值对形式的元数据。通过 key 和 value 两个字符串指针存储具体元数据信息，典型用途是传递内存块ID、物理地址等关键资源标识信息。应用层可通过此结构访问图层相关的扩展属性。 | | metadata | TA_AVDictionary | 元数据字典结构体，管理元数据条目的集合。包含 count 字段记录条目数量，elems 指针指向元数据条目数组。当前实现通常只管理单个条目，但结构设计支持扩展多个条目。该字典通过帧结构体传递到显示流水线，实现资源跟踪和属性传递。 |

| fix | struct fb_fix_screeninfo | 帧缓冲设备固定参数。重要字段：smem_start, smem_len, line_length。获取方式：ioctl(fd, FBIOGET_FSCREENINFO, &fix) | | show_thread_id | pthread_t | 显示线程ID。创建时机：图层启用且use_ta_cv=1时自动创建 | | timer_fd | int | 定时器文件描述符，用于帧率同步。创建时机：图层启用且需要精确帧率控制时。时钟类型：CLOCK_MONOTONIC单调时钟 | | attr | ta_vo_layer_attr * | 指向图层属性的指针。设置方式：通过ta_vo_layer_set_attr设置 | | str_blk_id | char[TA_VO_LAYER_MAX][16] | 内存块ID字符串表示。数组大小：每个图层支持多个内存块，但通常只使用一个。格式：十进制数字字符串 | | chn_nums | int | 绑定到该图层的通道数量。取值范围：[0, TA_VO_CHN_MAX] | | chn_ctx | ta_vo_chn_ctx *[TA_VO_CHN_MAX] | 绑定通道的指针数组。索引规则：以通道号作为数组索引 | | fb_size | unsigned int | 帧缓冲区大小：单个显示缓冲区的字节大小。单位：字节（bytes）。作用：1. 用于计算缓冲区偏移地址；2. 验证数据写入不越界；3. 内存分配和管理的依据 | | idle_buf_id | int | 空闲缓冲区索引 | | wb_ctx | void * | 回写上下文指针 | | back_buf_id | volatile unsigned int | 后缓冲区索引（当前可写入） | | front_buf_id | volatile unsigned int | 前缓冲区索引（当前显示） | | buf_locked | volatile unsigned int[MAX_QUEUES] | 缓冲区锁定标志数组 | | cond | pthread_cond_t | 条件变量（用于线程同步） | | dev_can_continue | volatile unsigned int | 设备是否可继续运行的标志 | | wb_can_continue | volatile unsigned int | 回写是否可继续的标志 | | mutex | pthread_mutex_t | 图层互斥锁（保护共享资源） | | dev_show_thread_id | pthread_t |设备显示线程 ID |

---

4. ta_vo_chn_attr

说明

通道属性配置结构体，用于定义视频输出通道的显示参数和行为特性。通过 ta_vo_chn_set_attr 函数设置，控制通道的视频显示位置、帧率控制和图形处理模式。

定义

typedef struct {
	int x;
	int y;
	int width;
	int height;
	int fps;
} ta_vo_chn_attr;

成员

字段名	类型	说明
x	int	通道显示区域左上角 X 坐标（像素）
y	int	通道显示区域左上角 Y 坐标（像素）
width	int	通道显示区域宽度（像素）
height	int	通道显示区域高度（像素）
fps	int	帧率控制：指定通道视频的播放帧率。单位：帧/秒（fps）。取值范围：- 0：不进行帧率控制，尽最大能力发送帧；- 1-60：常见视频帧率范围；- >60：高帧率应用，需硬件支持

---

5. ta_vo_frame

说明

视频帧数据结构体，基于FFmpeg的AVFrame结构扩展，用于承载视频图像数据及相关的元信息。该结构体作为视频数据在VO模块中的统一表示形式，支持多种像素格式、时间戳同步、内存管理和元数据传递。

定义

typedef struct {
	unsigned char *frame;
	ta_avframe_t *av_frame;
} ta_vo_frame;

核心成员

字段名	类型	说明
frame	unsigned char *	原始帧数据指针（通常指向 YUV 平面）
av_frame	ta_avframe_t *	FFmpeg AVFrame 扩展结构体指针，携带时间戳、格式等元数据

---

6. ta_vo_dev_ctx

说明

设备上下文结构体，作为物理显示设备的软件抽象，封装了设备类型标识和运行参数。该结构体是连接图层与硬件设备的关键桥梁，负责管理设备级别的显示控制、时序配置和资源分配。

定义

typedef struct {
    ta_vo_dev dev;
    ta_vo_dev_attr attr;
} ta_vo_dev_ctx;

成员

字段名	类型	说明
dev	ta_vo_dev	设备类型标识
attr	ta_vo_dev_attr	设备属性结构体

---

7. ta_vo_dev

说明

设备类型枚举，定义系统支持的物理显示硬件类型。每个枚举值对应一种特定的显示硬件单元，用于创建设备上下文时指定目标硬件。该枚举确保类型安全，防止无效设备类型的使用，同时为系统扩展提供清晰的版本管理。

定义

typedef enum {
    TA_VO_DEV_IDS = 0,
    TA_VO_DEV_USB_TO_HDMI = 1,
    TA_VO_DEV_MAX = 2
} ta_vo_dev;

成员

枚举值	数值	说明
TA_VO_DEV_IDS	0	IDS叠加层显示设备
TA_VO_DEV_USB_TO_HDMI	1	USB转HDMI显示设备
TA_VO_DEV_MAX	2	设备类型最大值，用于范围检查

---

8. ta_vo_dev_attr

说明

设备属性配置结构体，定义物理显示设备的运行时参数和行为特性。这些属性控制设备如何将图层内容输出到物理显示器，包括时序控制、图像处理和质量调节等功能。通过精细的设备属性配置，可以在不同硬件上实现一致的显示效果。

定义

typedef struct {
	int fps;
	int hw_layer_nums;
	hw_layer_attr layer[TA_VO_MAX_LAYER_NUMS];
	int scaler_width;
	int scaler_height;
	int scaler_x;
	int scaler_y;
	int colorkey_enable;
	int colorkey_x;
	int colorkey_y;
	int colorkey_width;
	int colorkey_height;
} ta_vo_dev_attr;

成员

字段名	类型	说明
fps	int 设备输出帧率（帧/秒），0=自适应
hw_layer_nums	int	硬件图层数量
layer	hw_layer_attr[TA_VO_MAX_LAYER_NUMS]	各硬件图层属性数组
scaler_width	int	硬件缩放器输出宽度（像素）
scaler_height	int	硬件缩放器输出高度（像素）
scaler_x	int	缩放器输出区域 X 坐标
scaler_y	int	缩放器输出区域 Y 坐标
colorkey_enable	int	颜色键功能开关（0=关闭，1=启用）
colorkey_x	int	颜色键区域左上角 X 坐标
colorkey_y	int	颜色键区域左上角 Y 坐标
colorkey_width	int	颜色键区域宽度（像素）
colorkey_height	int	颜色键区域高度（像素）

---

9. ta_vo_layer_attr

说明

图层属性配置结构体，定义视频/图形图层的显示特性、处理模式、缓冲区管理和高级合成功能。该结构体控制图层如何接收、处理和输出视觉内容，是决定显示效果和性能的关键配置。

定义

typedef struct {
	int format;
	unsigned char *buf;
	fb_format buf_format;
	void *wb_ctx;
	int use_av_frame;
	int hw_layer_id;
	int queue_size;
	int width;
	int height;
	int fps;
} ta_vo_layer_attr;

成员

字段名	类型	说明
format	int	输入像素格式（如 NV12、ARGB）
buf	unsigned char *	显示缓冲区指针（物理连续，64字节对齐）
buf_format	fb_format	帧缓冲格式（RGB565、ARGB8888 等）
wb_ctx	void *	回写上下文指针（用于图层内容捕获）
use_av_frame	int	是否使用 AVFrame 传递数据（0/1）
hw_layer_id	int	硬件图层 ID（对应硬件资源）
queue_size	int	帧队列大小（缓冲区数量）
width	int	图层宽度（像素）
height	int	图层高度（像素）
fps	int	图层帧率（帧/秒），0=不限

---

10. ta_vo_layer

说明

图层类型枚举，定义系统中可用的显示图层标识。每个枚举值对应一个逻辑显示平面，用于区分不同类型的显示内容和处理特性。系统通过此枚举管理有限的可视化资源，确保不同类型的视觉内容能够合理分配到适当的硬件平面。

定义

typedef enum {
    TA_VO_LAYER_VIDEO_0 = 0,
    TA_VO_LAYER_GRAPH_0 = 1,
    TA_VO_LAYER_MAX = 2
} ta_vo_layer;

成员

枚举值	数值	说明
TA_VO_LAYER_VIDEO_0	0	视频图层0 - 主要视频显示平面
TA_VO_LAYER_GRAPH_0	1	图形图层0 - 主要图形界面平面
TA_VO_LAYER_MAX	2	图层类型最大值 - 边界标识

---

11. ta_vo_wb

说明

回写设备标识类型，用于唯一标识视频回写（Write Back）设备实例。回写设备负责从显示流水线捕获视频帧数据，供录制、分析、编码或远程传输等应用使用。该类型本质上是无符号整数的别名，提供了类型安全性和代码可读性。

定义

typedef unsigned int ta_vo_wb;

---

12. ta_vo_wb_src

说明

回写数据源配置结构体，用于指定回写操作的具体数据来源。当回写源类型为图层时，该结构体提供目标图层的标识信息，确保回写设备从正确的位置捕获视频数据。

定义

typedef struct {
    ta_vo_layer layer;
} ta_vo_wb_src;

成员

字段名	类型	说明
layer	ta_vo_layer	目标图层标识，指定从哪个图层捕获显示内容

---

13. TA_VO_CHN_MAX

说明

视频通道数量上限宏定义，用于限定系统中同时可用的最大视频通道数量。该常量是系统资源规划、内存分配和运行时验证的关键参数，确保视频输出系统在已知的资源约束下稳定运行。

定义

#define TA_VO_CHN_MAX (16)

14. ta_vo_wb_ctx

说明

视频回写设备上下文结构体，封装了回写设备的所有运行时状态、属性配置、线程同步机制及帧数据队列管理。该结构体作为回写设备的核心控制块，负责协调从显示流水线捕获帧数据并传递给后续处理模块的完整流程。

定义

typedef struct {
    ta_vo_wb_attr attr;
    ta_vo_wb wb;
    pthread_mutex_t wb_mutex;
    pthread_mutex_t ref_lock;
    int enable;
    int ref_cnt;
    pthread_cond_t cond;
    void *layer_ctx;
    pthread_t thread;
    void *frame_queue[MAX_QUEUES];
    int queue_size;
    int queue_head;
    int queue_tail;
    int queue_count;
} ta_vo_wb_ctx;

成员

字段名	类型	说明
attr	ta_vo_wb_attr	回写设备属性配置结构体
wb	ta_vo_wb	回写设备标识
wb_mutex	pthread_mutex_t	回写设备操作互斥锁，保护设备状态的并发访问
ref_lock	pthread_mutex_t	引用计数锁，保护 ref_cnt 的原子性操作
enable	int	回写设备启用状态（0:禁用, 1:启用）
ref_cnt	int	引用计数，用于管理上下文的生命周期
cond	pthread_cond_t	线程条件变量，用于帧队列的同步等待
layer_ctx	void *	指向绑定图层的上下文指针
thread	pthread_t	回写处理线程ID
frame_queue	void *[MAX_QUEUES]	帧数据指针队列，用于存储捕获的视频帧
queue_size	int	队列总大小
queue_head	int	队列头索引（读位置）
queue_tail	int	队列尾索引（写位置）
queue_count	int	当前队列中的帧数

---

15. ta_vo_wb_attr

说明

回写设备属性配置结构体，定义视频回写设备的数据来源和工作模式。通过该结构体指定回写操作是从特定图层捕获还是从设备输出端捕获，是配置回写设备的核心参数。

定义

typedef struct {
    ta_vo_wb_src src;
} ta_vo_wb_attr;

成员

字段名	类型	说明
src	ta_vo_wb_src	回写数据源配置，指定数据来源类型及具体标识

---

16. ta_vo_wb_frame

说明

回写视频帧数据结构体，用于承载从显示流水线捕获的完整视频帧信息。该结构体包含图像数据的虚拟/物理地址、尺寸格式、 stride 信息及引用计数管理，是回写数据在系统中传递的标准载体。

定义

typedef struct {
    void *pVirAddr[3];
    unsigned long u64PhyAddr[3];
    int width;
    int height;
    int format;
    int stride[3];
    int ref_cnt;
    pthread_mutex_t ref_lock;
    void *buf;
    int layer_buf_id;
    unsigned int len;
    int id;
    ta_avframe_t *av_frame;
} ta_vo_wb_frame;

成员

字段名	类型	说明
pVirAddr	void *[3]	虚拟地址数组（Y/U/V 或 Y/UV 平面）
u64PhyAddr	unsigned long[3]	物理地址数组（可选，用于硬件编码）
width	int	帧宽度（像素）
height	int	帧高度（像素）
format	int	像素格式标识
stride	int[3]	每行字节数数组（stride），包含各平面的行跨度
ref_cnt	int	引用计数，用于管理帧数据的生命周期
ref_lock	pthread_mutex_t	引用计数锁，保护 ref_cnt 的原子性操作
buf	void *	用户自定义数据指针，可用于传递附加信息
layer_buf_id	int	图层缓冲区ID
len	unsigned int	数据总长度（字节）
id	int	帧标识ID

---