VPSS（视频处理子系统）接口说明文档

文档版本	V1.1
修订日期	2026-08-21
代码基线	hi_aiot_solution 8.18
对应头文件	components/media/pipeline/include/hi_mapi_vpss.h
类型定义	components/media/pipeline/include/hi_mapi_vpss_define.h、include/adapt/*_adapt_define.h
适用模块	VPSS / HI3516CV610

---

1 概述

VPSS 模块负责对输入 YUV 图像进行缩放、旋转、镜像、翻转、LDC、GDC、裁剪等处理。HI3516CV610 上最多支持 6 个 VPSS 组，每组 3 个物理通道（[0, 2]）和 2 个扩展通道（[3, 4]），共计 5 个可用通道。

2 接口总览

编号	接口	功能概述
1	hi_mapi_vpss_init	创建 VPSS 组并按 grp_attr 配置静态属性，随后启动该组。
2	hi_mapi_vpss_deinit	停止并销毁 VPSS 组。
3	hi_mapi_vpss_set_chn_attr	设置 VPSS 物理通道属性（动态）：分辨率、帧率、像素格式、压缩模式、宽高比、低延时等。内部会根据通道与组的分辨率比自动决定是否启用二级缩放。
4	hi_mapi_vpss_get_chn_attr	获取 VPSS 物理通道属性。
5	hi_mapi_vpss_set_ext_chn_attr	设置 VPSS 扩展通道属性：绑定到指定物理通道并按指定分辨率/帧率输出。
6	hi_mapi_vpss_get_ext_chn_attr	获取 VPSS 扩展通道属性。
7	hi_mapi_vpss_start_chn	启动 VPSS 通道：物理通道会应用低延时与 buffer wrap（若配置），然后 enable；扩展通道类似。
8	hi_mapi_vpss_stop_chn	停止 VPSS 通道并销毁其 VB 池。
9	hi_mapi_vpss_set_param	按 command 设置 VPSS 扩展属性：组裁剪、通道镜像/翻转/旋转/LDC/LDCv2/LDCv3/LDCv4/GDC/裁剪/帧队列深度。
10	hi_mapi_vpss_get_param	按 command 获取 VPSS 扩展属性。
11	hi_mapi_vpss_set_config	设置 VPSS 静态配置（启动通道前生效）。当前仅支持 HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP，仅对物理通道 0 有效。
12	hi_mapi_vpss_get_config	获取 VPSS 静态配置。
13	hi_mapi_vpss_get_chn_frame	从 VPSS 通道获取一帧 YUV 图像数据（默认超时 MAPI_VPSS_DATA_PROC_TIMEOUTS_MS ms）。
14	hi_mapi_vpss_release_chn_frame	释放由 hi_mapi_vpss_get_chn_frame 获取的帧。
15	hi_mapi_vpss_send_frame	向 VPSS 组发送一帧 YUV 图像（外部输入模式）。内部维护 frm_time_ref 序列号（每次 +2）。

3 API 参考

1 hi_mapi_vpss_init

【描述】 创建 VPSS 组并按 grp_attr 配置静态属性，随后启动该组。

【语法】

td_s32 hi_mapi_vpss_init(td_handle grp_hdl, const hi_mapi_vpss_grp_attr *grp_attr);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
grp_attr	输入	const hi_mapi_vpss_grp_attr *	组属性指针，不能为 NULL。

hi_mapi_vpss_grp_attr 成员：

成员名称	描述
max_width	组最大输入宽度（像素）。
max_height	组最大输入高度（像素）。
frame_rate_ctrl	帧率控制（src_frame_rate/dst_frame_rate）。
pixel_format	输入像素格式。
is_nr_en	是否开启降噪。

【返回值】

返回值	描述
0	成功（含已启动时幂等返回成功）。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_ENULL_PTR	grp_attr 为 NULL。
其他错误码	底层 create_grp 或 start_grp 失败。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 与 hi_mapi_vpss_deinit 配对。

【举例】

hi_mapi_vpss_grp_attr grp_attr = {0};
grp_attr.max_width  = 2560;
grp_attr.max_height = 1440;
grp_attr.frame_rate_ctrl.src_frame_rate = -1;
grp_attr.frame_rate_ctrl.dst_frame_rate = -1;
grp_attr.pixel_format = OT_PIXEL_FORMAT_YVU_SEMIPLANAR_420;
grp_attr.is_nr_en = TD_FALSE;
ret = hi_mapi_vpss_init(0, &grp_attr);

【相关主题】 hi_mapi_vpss_deinit、hi_mapi_vpss_grp_attr

2 hi_mapi_vpss_deinit

【描述】 停止并销毁 VPSS 组。

【语法】

td_s32 hi_mapi_vpss_deinit(td_handle grp_hdl);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。

【返回值】

返回值	描述
0	成功（含已 deinit 时幂等返回成功）。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 调用前应先 stop_chn 所有通道。

【举例】 无

【相关主题】 hi_mapi_vpss_init

3 hi_mapi_vpss_set_chn_attr

【描述】 设置 VPSS 物理通道属性（动态）：分辨率、帧率、像素格式、压缩模式、宽高比、低延时等。内部会根据通道与组的分辨率比自动决定是否启用二级缩放。

【语法】

td_s32 hi_mapi_vpss_set_chn_attr(td_handle grp_hdl, td_handle chn_hdl, const hi_mapi_vpss_chn_attr *chn_attr);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，取值范围 [0, 2]。
chn_attr	输入	const hi_mapi_vpss_chn_attr *	通道属性指针，不能为 NULL，且 width/height 必须 > 0。

hi_mapi_vpss_chn_attr 成员：

成员名称	描述
width / height	通道输出分辨率，必须 > 0。
support_buffer_share	是否支持 buffer 共享。
frame_rate_ctrl	帧率控制。
video_format	视频格式（linear/tile 等）。
pixel_format	像素格式。
compress_mode	压缩模式。
aspect_ratio	宽高比控制。
low_delay_info	低延时属性。
vb_pool_blk_cnt	私有 VB 池块数（0 表示使用公共池）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	chn_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	width == 0 或 height == 0。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init。

【举例】

hi_mapi_vpss_chn_attr chn_attr = {0};
chn_attr.width  = 1920;
chn_attr.height = 1080;
chn_attr.frame_rate_ctrl.src_frame_rate = 30;
chn_attr.frame_rate_ctrl.dst_frame_rate = 15;
chn_attr.video_format  = HI_MAPI_VIDEO_FORMAT_LINEAR;
chn_attr.pixel_format  = OT_PIXEL_FORMAT_YUV_SEMIPLANAR_420;
chn_attr.compress_mode = HI_MAPI_COMPRESS_MODE_NONE;
chn_attr.aspect_ratio.mode = HI_MAPI_ASPECT_RATIO_NONE;
ret = hi_mapi_vpss_set_chn_attr(0, 0, &chn_attr);

【相关主题】 hi_mapi_vpss_get_chn_attr、hi_mapi_vpss_chn_attr

4 hi_mapi_vpss_get_chn_attr

【描述】 获取 VPSS 物理通道属性。

【语法】

td_s32 hi_mapi_vpss_get_chn_attr(td_handle grp_hdl, td_handle chn_hdl, hi_mapi_vpss_chn_attr *chn_attr);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，取值范围 [0, 2]。
chn_attr	输出	hi_mapi_vpss_chn_attr *	输出通道属性，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	chn_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_vpss_set_chn_attr

5 hi_mapi_vpss_set_ext_chn_attr

【描述】 设置 VPSS 扩展通道属性：绑定到指定物理通道并按指定分辨率/帧率输出。

【语法】

td_s32 hi_mapi_vpss_set_ext_chn_attr(td_handle grp_hdl, td_handle chn_hdl,
    const hi_mapi_vpss_ext_chn_attr *ext_chn_attr);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	扩展通道句柄，取值范围 [3, 4]（即 HI_MAPI_VPSS_PHY_CHN_MAX_NUM 起）。
ext_chn_attr	输入	const hi_mapi_vpss_ext_chn_attr *	扩展通道属性指针，不能为 NULL，且 width/height 必须 > 0，bind_chn_hdl 必须为合法物理通道句柄。

hi_mapi_vpss_ext_chn_attr 成员：

成员名称	描述
bind_chn_hdl	绑定的源物理通道句柄，取值 [0, 2]。
width / height	扩展通道输出分辨率，必须 > 0。
frame_rate_ctrl	帧率控制。
video_format	视频格式。
pixel_format	像素格式。
compress_mode	压缩模式。
low_delay_info	低延时属性。
vb_pool_blk_cnt	私有 VB 池块数。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl 不在 [3, 4]。
HI_MAPI_VPSS_ENULL_PTR	ext_chn_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	width == 0 或 height == 0，或 bind_chn_hdl 非法。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init。

【举例】 无

【相关主题】 hi_mapi_vpss_get_ext_chn_attr、hi_mapi_vpss_ext_chn_attr

6 hi_mapi_vpss_get_ext_chn_attr

【描述】 获取 VPSS 扩展通道属性。

【语法】

td_s32 hi_mapi_vpss_get_ext_chn_attr(td_handle grp_hdl, td_handle chn_hdl,
    hi_mapi_vpss_ext_chn_attr *ext_chn_attr);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	扩展通道句柄，取值范围 [3, 4]。
ext_chn_attr	输出	hi_mapi_vpss_ext_chn_attr *	输出扩展通道属性，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl 不在 [3, 4]。
HI_MAPI_VPSS_ENULL_PTR	ext_chn_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】 无

【举例】 无

【相关主题】 hi_mapi_vpss_set_ext_chn_attr

7 hi_mapi_vpss_start_chn

【描述】 启动 VPSS 通道：物理通道会应用低延时与 buffer wrap（若配置），然后 enable；扩展通道类似。

【语法】

td_s32 hi_mapi_vpss_start_chn(td_handle grp_hdl, td_handle chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	通道句柄，物理通道 [0, 2] 或扩展通道 [3, 4]。

【返回值】

返回值	描述
0	成功（含已启动时幂等返回成功）。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 4。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init 并 set_chn_attr/set_ext_chn_attr。

【举例】

ret = hi_mapi_vpss_init(0, &grp_attr);
(void)hi_mapi_sys_bind(&src, &dst); // VCAP -> VPSS
ret = hi_mapi_vpss_set_chn_attr(0, 0, &chn_attr);
ret = hi_mapi_vpss_start_chn(0, 0);

【相关主题】 hi_mapi_vpss_stop_chn

8 hi_mapi_vpss_stop_chn

【描述】 停止 VPSS 通道并销毁其 VB 池。

【语法】

td_s32 hi_mapi_vpss_stop_chn(td_handle grp_hdl, td_handle chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	通道句柄，物理通道 [0, 2] 或扩展通道 [3, 4]。

【返回值】

返回值	描述
0	成功（含已停止时幂等返回成功）。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 4。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 与 hi_mapi_vpss_start_chn 配对。

【举例】 无

【相关主题】 hi_mapi_vpss_start_chn

9 hi_mapi_vpss_set_param

【描述】 按 command 设置 VPSS 扩展属性：组裁剪、通道镜像/翻转/旋转/LDC/LDCv2/LDCv3/LDCv4/GDC/裁剪/帧队列深度。

【语法】

td_s32 hi_mapi_vpss_set_param(td_handle grp_hdl, td_handle chn_hdl, hi_mapi_vpss_cmd command,
    const td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，取值范围 [0, 2]（CMD_GRP_CROP 忽略 chn_hdl）。
command	输入	hi_mapi_vpss_cmd	命令，取值范围 [0, HI_MAPI_VPSS_CMD_BUTT-1]。
cmd_attr	输入	const td_void *	命令参数指针，不能为 NULL。
len	输入	td_u32	命令参数结构体大小。

command	cmd_attr 类型	描述
HI_MAPI_VPSS_CMD_GRP_CROP	hi_mapi_vpss_crop_info *	组级裁剪。
HI_MAPI_VPSS_CMD_CHN_MIRROR	hi_mapi_vpss_mirror_attr *	通道镜像。
HI_MAPI_VPSS_CMD_CHN_FLIP	hi_mapi_vpss_flip_attr *	通道翻转。
HI_MAPI_VPSS_CMD_CHN_ROTATE	hi_mapi_rotation *	通道旋转。
HI_MAPI_VPSS_CMD_CHN_LDC / LDCV2 / LDCV3 / LDCV4	对应 hi_mapi_vpss_ldc*_attr *	通道鱼眼矫正。
HI_MAPI_VPSS_CMD_CHN_GDC	hi_mapi_vpss_gdc_param *	通道 GDC。
HI_MAPI_VPSS_CMD_CHN_CROP	hi_mapi_vpss_crop_info *	通道裁剪。
HI_MAPI_VPSS_CMD_CHN_DEPTH	hi_mapi_vpss_depth_attr *	通道帧队列深度。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	cmd_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	len 不足或参数非法。
HI_MAPI_VPSS_ENOT_SUPPORT	不支持的命令。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init（组启动后）；LDC 首次设置时会自动配置 GDC。
• 扩展通道不支持该接口（只接受物理通道）。

【举例】 无

【相关主题】 hi_mapi_vpss_get_param、hi_mapi_vpss_cmd

10 hi_mapi_vpss_get_param

【描述】 按 command 获取 VPSS 扩展属性。

【语法】

td_s32 hi_mapi_vpss_get_param(td_handle grp_hdl, td_handle chn_hdl, hi_mapi_vpss_cmd command,
    td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，取值范围 [0, 2]（CMD_GRP_CROP 忽略 chn_hdl）。
command	输入	hi_mapi_vpss_cmd	命令，取值范围 [0, HI_MAPI_VPSS_CMD_BUTT-1]。
cmd_attr	输出	td_void *	输出缓冲，不能为 NULL。
len	输入	td_u32	输出缓冲大小。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	cmd_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	len 不足。
HI_MAPI_VPSS_ENOT_SUPPORT	不支持的命令。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init。

【举例】 无

【相关主题】 hi_mapi_vpss_set_param

11 hi_mapi_vpss_set_config

【描述】 设置 VPSS 静态配置（启动通道前生效）。当前仅支持 HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP，仅对物理通道 0 有效。

【语法】

td_s32 hi_mapi_vpss_set_config(td_handle grp_hdl, td_handle chn_hdl, hi_mapi_vpss_config_cmd command,
    const td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，必须为 0（仅 chn0 支持 wrap）。
command	输入	hi_mapi_vpss_config_cmd	静态配置命令，当前仅 HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP。
cmd_attr	输入	const td_void *	配置参数指针，不能为 NULL。
len	输入	td_u32	配置参数结构体大小，至少为 sizeof(hi_mapi_vpss_buf_wrap_attr)。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	cmd_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	len 不足。
HI_MAPI_VPSS_ENOT_SUPPORT	chn_hdl != 0 或不支持的命令。
HI_MAPI_VPSS_ENOT_PERM	通道已启动（wrap 是静态属性，不可运行时修改）。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须在 set_chn_attr 之后、start_chn 之前调用。
• 与 low_delay_info.enable / support_buffer_share 互斥，不能同时开启。

【举例】 无

【相关主题】 hi_mapi_vpss_get_config、hi_mapi_vpss_buf_wrap_attr

12 hi_mapi_vpss_get_config

【描述】 获取 VPSS 静态配置。

【语法】

td_s32 hi_mapi_vpss_get_config(td_handle grp_hdl, td_handle chn_hdl, hi_mapi_vpss_config_cmd command,
    td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	物理通道句柄，必须为 0。
command	输入	hi_mapi_vpss_config_cmd	静态配置命令。
cmd_attr	输出	td_void *	输出缓冲，不能为 NULL。
len	输入	td_u32	输出缓冲大小。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 2。
HI_MAPI_VPSS_ENULL_PTR	cmd_attr 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	len 不足。
HI_MAPI_VPSS_ENOT_SUPPORT	chn_hdl != 0 或不支持的命令。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 通道已启动时从 SDK 读取权威值；未启动时返回缓存值。

【举例】 无

【相关主题】 hi_mapi_vpss_set_config

13 hi_mapi_vpss_get_chn_frame

【描述】 从 VPSS 通道获取一帧 YUV 图像数据（默认超时 MAPI_VPSS_DATA_PROC_TIMEOUTS_MS ms）。

【语法】

td_s32 hi_mapi_vpss_get_chn_frame(td_handle grp_hdl, td_handle chn_hdl,
    hi_mapi_frame_data *yuv_frame_data);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	通道句柄，物理通道 [0, 2] 或扩展通道 [3, 4]。
yuv_frame_data	输出	hi_mapi_frame_data *	输出帧数据，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_ENULL_PTR	yuv_frame_data 为 NULL。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 4。
HI_MAPI_VPSS_EBUF_EMPTY	取帧超时。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先通过 HI_MAPI_VPSS_CMD_CHN_DEPTH 设置通道 depth > 0。
• 必须与 hi_mapi_vpss_release_chn_frame 配对。

【举例】 无

【相关主题】 hi_mapi_vpss_release_chn_frame

14 hi_mapi_vpss_release_chn_frame

【描述】 释放由 hi_mapi_vpss_get_chn_frame 获取的帧。

【语法】

td_s32 hi_mapi_vpss_release_chn_frame(td_handle grp_hdl, td_handle chn_hdl,
    const hi_mapi_frame_data *yuv_frame_data);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
chn_hdl	输入	td_handle	通道句柄，取值 [0, 4]。
yuv_frame_data	输入	const hi_mapi_frame_data *	待释放帧数据，不能为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_ENULL_PTR	yuv_frame_data 为 NULL。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_EINVALID_CHNID	chn_hdl > 4。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 不得重复释放同一帧。

【举例】 无

【相关主题】 hi_mapi_vpss_get_chn_frame

15 hi_mapi_vpss_send_frame

【描述】 向 VPSS 组发送一帧 YUV 图像（外部输入模式）。内部维护 frm_time_ref 序列号（每次 +2）。

【语法】

td_s32 hi_mapi_vpss_send_frame(td_handle grp_hdl, const hi_mapi_frame_data *frame_data);

【参数】

参数名称	输入/输出	类型	描述
grp_hdl	输入	td_handle	VPSS 组句柄，HI3516CV610 取值范围 [0, 5]。
frame_data	输入	const hi_mapi_frame_data *	帧数据指针，不能为 NULL，且 frame_data_type 必须为 HI_MAPI_FRAME_DATA_TYPE_YUV。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VPSS_EINVALID_DEVID	grp_hdl > 5。
HI_MAPI_VPSS_ENULL_PTR	frame_data 为 NULL。
HI_MAPI_VPSS_EUNEXIST	VPSS 组未 init。
HI_MAPI_VPSS_EILLEGAL_PARAM	frame_data_type != HI_MAPI_FRAME_DATA_TYPE_YUV。

【需求】

• 头文件：hi_mapi_vpss.h
• 库文件：libhi_mapi.so

【注意】

• 必须先 hi_mapi_vpss_init。
• 仅接受 YUV 类型帧数据。

【举例】 无

【相关主题】 hi_mapi_vpss_get_chn_frame

4 数据类型

1 hi_mapi_vpss_grp_attr

【说明】 VPSS 组属性，描述一个 VPSS group 的最大输入分辨率、帧率控制、输入像素格式及降噪使能。

【定义】

typedef struct {
    td_u32 max_width;
    td_u32 max_height;
    hi_mapi_frame_rate_ctrl frame_rate_ctrl;
    hi_mapi_pixel_format pixel_format;
    td_bool is_nr_en;
} hi_mapi_vpss_grp_attr;

【成员】

成员名称	描述
max_width	组内最大输入宽度，单位像素。
max_height	组内最大输入高度，单位像素。
frame_rate_ctrl	帧率控制（src_frame_rate / dst_frame_rate），详见 hi_mapi_frame_rate_ctrl。
pixel_format	输入像素格式，详见 hi_mapi_pixel_format。
is_nr_en	是否启用降噪；TD_TRUE 启用，TD_FALSE 关闭。

【注意事项】

• 在 hi_mapi_vpss_init 时传入，设置后不可动态修改。
• HI3516CV610 平台最多支持 HI_MAPI_VPSS_MAX_NUM（6）个 VPSS 组。

【相关数据类型及接口】 hi_mapi_frame_rate_ctrl、hi_mapi_pixel_format；hi_mapi_vpss_init。

2 hi_mapi_vpss_chn_attr

【说明】 VPSS 物理通道属性，描述通道的输出分辨率、帧率、像素格式、压缩模式、宽高比、低延时等。

【定义】

typedef struct {
    td_u32 width;
    td_u32 height;
    td_bool support_buffer_share;
    hi_mapi_frame_rate_ctrl frame_rate_ctrl;
    hi_mapi_video_format video_format;
    hi_mapi_pixel_format pixel_format;
    hi_mapi_compress_mode compress_mode;
    hi_mapi_aspect_ratio_attr aspect_ratio;
    hi_mapi_vpss_low_delay_info low_delay_info;
    td_u32 vb_pool_blk_cnt;
} hi_mapi_vpss_chn_attr;

【成员】

成员名称	描述
width	通道输出宽度，单位像素。
height	通道输出高度，单位像素。
support_buffer_share	是否支持 buffer 复用；TD_TRUE 启用。
frame_rate_ctrl	帧率控制，详见 hi_mapi_frame_rate_ctrl。
video_format	视频内存排布格式，详见 hi_mapi_video_format。
pixel_format	输出像素格式，详见 hi_mapi_pixel_format。
compress_mode	压缩模式，详见 hi_mapi_compress_mode。
aspect_ratio	宽高比属性，详见 hi_mapi_aspect_ratio_attr。
low_delay_info	低延时信息，详见 hi_mapi_vpss_low_delay_info。
vb_pool_blk_cnt	通道 VB 池块数；0 表示使用系统默认值。

【注意事项】

• HI3516CV610 平台物理通道编号范围 [0, HI_MAPI_VPSS_PHY_CHN_MAX_NUM - 1]（即 [0, 2]）。
• 通过 hi_mapi_vpss_set_chn_attr / hi_mapi_vpss_get_chn_attr 动态设置/获取。

【相关数据类型及接口】 hi_mapi_vpss_low_delay_info、hi_mapi_aspect_ratio_attr；hi_mapi_vpss_set_chn_attr、hi_mapi_vpss_get_chn_attr。

3 hi_mapi_vpss_ext_chn_attr

【说明】 VPSS 扩展通道属性，描述扩展通道绑定的源物理通道及输出参数。

【定义】

typedef struct {
    td_handle bind_chn_hdl;
    td_u32 width;
    td_u32 height;
    hi_mapi_frame_rate_ctrl frame_rate_ctrl;
    hi_mapi_video_format video_format;
    hi_mapi_pixel_format pixel_format;
    hi_mapi_compress_mode compress_mode;
    hi_mapi_vpss_low_delay_info low_delay_info;
    td_u32 vb_pool_blk_cnt;
} hi_mapi_vpss_ext_chn_attr;

【成员】

成员名称	描述
bind_chn_hdl	绑定的源物理通道句柄。
width	扩展通道输出宽度，单位像素。
height	扩展通道输出高度，单位像素。
frame_rate_ctrl	帧率控制，详见 hi_mapi_frame_rate_ctrl。
video_format	视频内存排布格式，详见 hi_mapi_video_format。
pixel_format	输出像素格式，详见 hi_mapi_pixel_format。
compress_mode	压缩模式，详见 hi_mapi_compress_mode。
low_delay_info	低延时信息，详见 hi_mapi_vpss_low_delay_info。
vb_pool_blk_cnt	通道 VB 池块数；0 表示使用系统默认值。

【注意事项】

• HI3516CV610 平台扩展通道编号范围 [0, HI_MAPI_VPSS_EXT_CHN_MAX_NUM - 1]（即 [0, 1]）。
• 通过 hi_mapi_vpss_set_ext_chn_attr / hi_mapi_vpss_get_ext_chn_attr 设置/获取。

【相关数据类型及接口】 hi_mapi_vpss_low_delay_info；hi_mapi_vpss_set_ext_chn_attr、hi_mapi_vpss_get_ext_chn_attr。

4 hi_mapi_vpss_cmd

【说明】 VPSS 动态扩展属性命令枚举，用于 hi_mapi_vpss_set_param / hi_mapi_vpss_get_param 中标识要操作的属性类型。

【定义】

typedef enum {
    HI_MAPI_VPSS_CMD_GRP_CROP,
    HI_MAPI_VPSS_CMD_CHN_MIRROR,
    HI_MAPI_VPSS_CMD_CHN_FLIP,
    HI_MAPI_VPSS_CMD_CHN_ROTATE,
    HI_MAPI_VPSS_CMD_CHN_LDC,
    HI_MAPI_VPSS_CMD_CHN_LDCV2,
    HI_MAPI_VPSS_CMD_CHN_LDCV3,
    HI_MAPI_VPSS_CMD_CHN_LDCV4,
    HI_MAPI_VPSS_CMD_CHN_GDC,
    HI_MAPI_VPSS_CMD_CHN_CROP,
    HI_MAPI_VPSS_CMD_CHN_DEPTH,
    HI_MAPI_VPSS_CMD_BUTT
} hi_mapi_vpss_cmd;

【成员】

枚举值	描述
HI_MAPI_VPSS_CMD_GRP_CROP	组裁剪，对应 hi_mapi_vpss_crop_info。
HI_MAPI_VPSS_CMD_CHN_MIRROR	通道镜像，对应 hi_mapi_vpss_mirror_attr。
HI_MAPI_VPSS_CMD_CHN_FLIP	通道翻转，对应 hi_mapi_vpss_flip_attr。
HI_MAPI_VPSS_CMD_CHN_ROTATE	通道旋转，对应 hi_mapi_rotation（公共类型）。
HI_MAPI_VPSS_CMD_CHN_LDC	通道鱼眼矫正（LDC v1），对应 hi_mapi_vpss_ldc_attr。
HI_MAPI_VPSS_CMD_CHN_LDCV2	通道鱼眼矫正（LDC v2），对应 hi_mapi_vpss_ldc_v2_attr。
HI_MAPI_VPSS_CMD_CHN_LDCV3	通道鱼眼矫正（LDC v3），对应 hi_mapi_vpss_ldc_v3_attr。
HI_MAPI_VPSS_CMD_CHN_LDCV4	通道鱼眼矫正（LDC v4），对应 hi_mapi_vpss_ldc_v4_attr。
HI_MAPI_VPSS_CMD_CHN_GDC	通道 GDC 修正，对应 hi_mapi_vpss_gdc_param。
HI_MAPI_VPSS_CMD_CHN_CROP	通道裁剪，对应 hi_mapi_vpss_crop_info。
HI_MAPI_VPSS_CMD_CHN_DEPTH	通道帧队列深度，对应 hi_mapi_vpss_depth_attr。
HI_MAPI_VPSS_CMD_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

5 hi_mapi_vpss_config_cmd

【说明】 VPSS 静态配置命令枚举，用于 hi_mapi_vpss_set_config / hi_mapi_vpss_get_config；必须在通道启动前设置。

【定义】

typedef enum {
    HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP,
    HI_MAPI_VPSS_CONFIG_CMD_BUTT
} hi_mapi_vpss_config_cmd;

【成员】

枚举值	描述
HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP	物理通道 0 的 buffer 卷绕配置，对应 hi_mapi_vpss_buf_wrap_attr。
HI_MAPI_VPSS_CONFIG_CMD_BUTT	哨兵值，无效。

【注意事项】

• 静态配置必须在 hi_mapi_vpss_start_chn 之前调用 hi_mapi_vpss_set_config 设置。

【相关数据类型及接口】 hi_mapi_vpss_buf_wrap_attr；hi_mapi_vpss_set_config、hi_mapi_vpss_get_config。

6 hi_mapi_vpss_buf_wrap_attr

【说明】 VPSS 通道 0 的 buffer 卷绕属性，启用后使用卷绕方式复用 buffer 以降低内存占用。

【定义】

typedef struct {
    td_bool enable;
} hi_mapi_vpss_buf_wrap_attr;

【成员】

成员名称	描述
enable	是否启用 buffer 卷绕；TD_TRUE 启用，TD_FALSE 关闭。应用层仅需配置此字段，buf_line/buf_size 由内部计算。

【注意事项】

• 仅作用于物理通道 0。
• 必须在通道启动前通过 HI_MAPI_VPSS_CONFIG_CMD_CHN_BUF_WRAP 设置。

【相关数据类型及接口】 hi_mapi_vpss_config_cmd；hi_mapi_vpss_set_config。

7 hi_mapi_vpss_mirror_attr

【说明】 VPSS 通道镜像属性，控制通道输出是否做水平镜像。

【定义】

typedef struct {
    td_bool enable;
} hi_mapi_vpss_mirror_attr;

【成员】

成员名称	描述
enable	是否启用镜像；TD_TRUE 启用，TD_FALSE 关闭。

【注意事项】 无

【相关数据类型及接口】 HI_MAPI_VPSS_CMD_CHN_MIRROR；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

8 hi_mapi_vpss_flip_attr

【说明】 VPSS 通道翻转属性，控制通道输出是否做垂直翻转。

【定义】

typedef struct {
    td_bool enable;
} hi_mapi_vpss_flip_attr;

【成员】

成员名称	描述
enable	是否启用翻转；TD_TRUE 启用，TD_FALSE 关闭。

【注意事项】 无

【相关数据类型及接口】 HI_MAPI_VPSS_CMD_CHN_FLIP；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

9 hi_mapi_vpss_depth_attr

【说明】 VPSS 通道帧队列深度属性，控制通道内部缓存的帧数。

【定义】

typedef struct {
    td_u32 depth;
} hi_mapi_vpss_depth_attr;

【成员】

成员名称	描述
depth	帧队列深度；0 表示不缓存（默认），> 0 表示缓存帧数。

【注意事项】

• 设置为 0 时，get_chn_frame 会阻塞等待新帧；设置为 > 0 时，内部缓冲指定数量的帧。

【相关数据类型及接口】 HI_MAPI_VPSS_CMD_CHN_DEPTH；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

10 hi_mapi_vpss_low_delay_info

【说明】 VPSS 通道低延时属性，启用后通道按行输出而非等待整帧完成，降低处理延时。

【定义】

typedef struct {
    td_bool enable;
    td_u32  line_cnt;
} hi_mapi_vpss_low_delay_info;

【成员】

成员名称	描述
enable	是否启用低延时；TD_TRUE 启用，TD_FALSE 关闭。
line_cnt	低延时 shoreline 行数；取值范围 [16, 16384]，仅在 enable 为 TD_TRUE 时有效。

【注意事项】

• 低延时模式下，输出帧在指定行数处理完成后即推送给下游。

【相关数据类型及接口】 hi_mapi_vpss_chn_attr、hi_mapi_vpss_ext_chn_attr。

11 hi_mapi_vpss_crop_info

【说明】 VPSS 裁剪信息，用于组裁剪（GRP_CROP）或通道裁剪（CHN_CROP）。

【定义】

typedef struct {
    td_bool enable;
    hi_mapi_vpss_crop_coordonate crop_coordinate;
    hi_mapi_rect crop_rect;
} hi_mapi_vpss_crop_info;

【成员】

成员名称	描述
enable	是否启用裁剪；TD_TRUE 启用，TD_FALSE 关闭。
crop_coordinate	裁剪起点坐标模式，详见 hi_mapi_vpss_crop_coordonate。
crop_rect	裁剪矩形区域，详见 hi_mapi_rect。

hi_mapi_vpss_crop_coordonate 枚举：

枚举值	描述
HI_MAPI_VPSS_CROP_ABS_COOR	绝对坐标（像素）。
HI_MAPI_VPSS_CROP_RATIO_COOR	比例坐标（取值范围 [0, 16384]，16384 表示 100%）。
HI_MAPI_VPSS_CROP_BUTT	哨兵值，无效。

【注意事项】

• 组裁剪通过 HI_MAPI_VPSS_CMD_GRP_CROP 设置，通道裁剪通过 HI_MAPI_VPSS_CMD_CHN_CROP 设置。

【相关数据类型及接口】 hi_mapi_rect；HI_MAPI_VPSS_CMD_GRP_CROP、HI_MAPI_VPSS_CMD_CHN_CROP；hi_mapi_vpss_set_param。

12 hi_mapi_vpss_ldc_attr

【说明】 VPSS 通道鱼眼矫正（LDC v1）属性，包含使能开关与 LDC 参数。

【定义】

typedef struct {
    td_bool enable;
    hi_mapi_ldc_attr ldc_attr;
} hi_mapi_vpss_ldc_attr;

【成员】

成员名称	描述
enable	是否启用 LDC v1 矫正；TD_TRUE 启用，TD_FALSE 关闭。
ldc_attr	LDC v1 参数，详见公共类型 hi_mapi_ldc_attr。

【注意事项】

• 通过 HI_MAPI_VPSS_CMD_CHN_LDC 设置/获取。

【相关数据类型及接口】 hi_mapi_ldc_attr；HI_MAPI_VPSS_CMD_CHN_LDC；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

13 hi_mapi_vpss_ldc_v2_attr

【说明】 VPSS 通道鱼眼矫正（LDC v2）属性，基于镜头标定系数的矫正方式。

【定义】

typedef struct {
    td_bool enable;
    hi_mapi_ldc_v2_attr attr;
} hi_mapi_vpss_ldc_v2_attr;

【成员】

成员名称	描述
enable	是否启用 LDC v2 矫正；TD_TRUE 启用，TD_FALSE 关闭。
attr	LDC v2 参数，详见公共类型 hi_mapi_ldc_v2_attr。

【注意事项】

• 通过 HI_MAPI_VPSS_CMD_CHN_LDCV2 设置/获取。

【相关数据类型及接口】 hi_mapi_ldc_v2_attr；HI_MAPI_VPSS_CMD_CHN_LDCV2；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

14 hi_mapi_vpss_ldc_v3_attr

【说明】 VPSS 通道鱼眼矫正（LDC v3）属性，支持分段插值的镜头矫正。

【定义】

typedef struct {
    td_bool enable;
    hi_mapi_ldc_v3_attr attr;
} hi_mapi_vpss_ldc_v3_attr;

【成员】

成员名称	描述
enable	是否启用 LDC v3 矫正；TD_TRUE 启用，TD_FALSE 关闭。
attr	LDC v3 参数，详见公共类型 hi_mapi_ldc_v3_attr。

【注意事项】

• 通过 HI_MAPI_VPSS_CMD_CHN_LDCV3 设置/获取。

【相关数据类型及接口】 hi_mapi_ldc_v3_attr；HI_MAPI_VPSS_CMD_CHN_LDCV3；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

15 hi_mapi_vpss_ldc_v4_attr

【说明】 VPSS 通道鱼眼矫正（LDC v4）属性，支持全图/裁剪视图模式。

【定义】

typedef struct {
    td_bool enable;
    hi_mapi_ldc_v4_attr attr;
} hi_mapi_vpss_ldc_v4_attr;

【成员】

成员名称	描述
enable	是否启用 LDC v4 矫正；TD_TRUE 启用，TD_FALSE 关闭。
attr	LDC v4 参数，详见公共类型 hi_mapi_ldc_v4_attr。

【注意事项】

• 通过 HI_MAPI_VPSS_CMD_CHN_LDCV4 设置/获取。

【相关数据类型及接口】 hi_mapi_ldc_v4_attr；HI_MAPI_VPSS_CMD_CHN_LDCV4；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

16 hi_mapi_vpss_gdc_param

【说明】 VPSS 通道 GDC（Global Distortion Correction）参数，用于全局畸变矫正的查表配置。

【定义】

typedef struct {
    td_u32  in_width;
    td_u32  in_height;
    hi_mapi_vpss_lut_cell_size cell_size;
} hi_mapi_vpss_gdc_param;

【成员】

成员名称	描述
in_width	输入图像宽度，单位像素。
in_height	输入图像高度，单位像素。
cell_size	LUT 网格大小，详见 hi_mapi_vpss_lut_cell_size。

hi_mapi_vpss_lut_cell_size 枚举：

枚举值	描述
HI_MAPI_VPSS_LUT_CELL_SIZE_16	网格大小 16。
HI_MAPI_VPSS_LUT_CELL_SIZE_32	网格大小 32。
HI_MAPI_VPSS_LUT_CELL_SIZE_64	网格大小 64。
HI_MAPI_VPSS_LUT_CELL_SIZE_128	网格大小 128。
HI_MAPI_VPSS_LUT_CELL_SIZE_256	网格大小 256。
HI_MAPI_VPSS_LUT_CELL_SIZE_BUTT	哨兵值，无效。

【注意事项】

• 通过 HI_MAPI_VPSS_CMD_CHN_GDC 设置/获取。

【相关数据类型及接口】 HI_MAPI_VPSS_CMD_CHN_GDC；hi_mapi_vpss_set_param、hi_mapi_vpss_get_param。

5 错误码

模块编号 mod=2，错误码基址 0xA3028000。

错误代码	宏定义	描述
0xA3028001	HI_MAPI_VPSS_EINVALID_DEVID	设备号无效。
0xA3028002	HI_MAPI_VPSS_EINVALID_CHNID	通道号无效。
0xA3028004	HI_MAPI_VPSS_EEXIST	资源已存在。
0xA3028006	HI_MAPI_VPSS_ENULL_PTR	空指针。
0xA3028010	HI_MAPI_VPSS_ENOTREADY	系统未就绪。