VDEC（视频解码）接口说明文档

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

---

1 概述

⚠ 本模块在 HI3516CV610 上不可用

本章接口在 hi_mapi_vdec.h 中有完整声明，但 无法在 HI3516CV610 上调用：

• libhi_mapi.so / libhi_mapi.a 未编入该模块——components/media/pipeline/src/vdec/ 下无 CMakeLists.txt，src/CMakeLists.txt 也未将 ms_vdec 纳入构建目标。
• 该芯片 SDK 未提供视频解码 MPI，sdk/Hi3516CV610 全部库文件中不存在任何 ss_mpi_vdec_* 符号（对照：ss_mpi_venc_* 存在）。

即使自行补齐构建脚本亦无法链接。视频解码能力目前仅在 DV500 等其他芯片上提供。

本章及第 4 章数据类型、第 5 章错误码予以保留，仅用于说明头文件中这批声明的来源与适用范围，不代表本芯片具备该能力。 VDEC 模块负责将 H.264 / H.265 / JPEG / MJPEG 码流解码为 YUV 视频帧。支持流模式（STREAM）和帧模式（FRAME）两种送流方式，获取解码帧支持普通模式（COMMON，基于消息）和快速模式（FAST，基于 datafifo）。VDEC 模块在首次 init 通道时自动初始化。以下描述基于头文件声明与支持该模块的芯片行为。

2 接口总览

★ = 该模块在 HI3516CV610 上不可用。声明存在于头文件，但未编入 libhi_mapi，且 SDK 未提供对应 MPI。

编号	接口	功能概述
1	hi_mapi_vdec_get_default_attr	根据基础属性（解码类型、分辨率）派生出一套可用的默认解码属性。
2	hi_mapi_vdec_init	初始化指定通道的视频解码实例（首次调用时自动初始化 VDEC 模块，并创建 SDK 解码通道）。
3	hi_mapi_vdec_deinit	去初始化指定通道的视频解码实例；若所有通道均已去初始化，则自动去初始化 VDEC 模块。
4	hi_mapi_vdec_start	启动指定 VDEC 通道的解码接收。
5	hi_mapi_vdec_stop	停止指定 VDEC 通道的解码接收，并解绑 VB pool。
6	hi_mapi_vdec_query_status	查询指定 VDEC 通道的解码状态（剩余码流字节数/帧数、待输出图像数、当前解码分辨率等）。
7	hi_mapi_vdec_set_attr	设置指定 VDEC 通道的解码属性（送流模式、buffer 大小、VB 绑定等）。get_frame_mode 为静态属性，不可修改。
8	hi_mapi_vdec_get_attr	获取指定 VDEC 通道当前的解码属性。
9	hi_mapi_vdec_set_param	设置 VDEC 通道的扩展参数（解码模式、显示帧数、错误阈值等）。
10	hi_mapi_vdec_get_param	获取 VDEC 通道的扩展参数。
11	hi_mapi_vdec_send_stream	向指定 VDEC 通道发送一帧/一段码流数据。
12	hi_mapi_vdec_get_frame	从指定 VDEC 通道获取一帧解码后的视频数据。
13	hi_mapi_vdec_release_frame	释放通过 hi_mapi_vdec_get_frame 获取的解码帧资源。

3 API 参考

1 hi_mapi_vdec_get_default_attr

【描述】 根据基础属性（解码类型、分辨率）派生出一套可用的默认解码属性。

【语法】

td_s32 hi_mapi_vdec_get_default_attr(const hi_mapi_vdec_base_attr *base_attr, hi_mapi_vdec_attr *vdec_attr);

【参数】

参数名称	输入/输出	类型	描述
base_attr	输入	const hi_mapi_vdec_base_attr *	基础属性指针。不可为 NULL。
vdec_attr	输出	hi_mapi_vdec_attr *	解码属性输出指针。不可为 NULL。

成员名称（hi_mapi_vdec_base_attr）	描述
type	负载类型：HI_MAPI_PAYLOAD_TYPE_H264 / H265 / JPEG / MJPEG。
width	最大解码图像宽度（像素）。
height	最大解码图像高度（像素）。

成员名称（hi_mapi_vdec_attr）	描述
type	负载类型，复制自 base_attr->type。
mode	送流模式，默认 HI_MAPI_VDEC_VIDEO_MODE_STREAM。
get_frame_mode	取帧模式，默认 HI_MAPI_VDEC_MODE_COMMON。
pic_width / pic_height	最大图像宽/高，复制自 base_attr。
stream_buf_size	码流 buffer 大小，默认 = width * height * 3 / 4（字节）。
frame_buf_size	帧 buffer 大小，根据分辨率/格式自动计算。
frame_buf_cnt	帧 buffer 数量。
user_vb_flag	是否使用用户 VB，默认 TD_FALSE。
vdec_video_attr	视频扩展属性（仅 H.264/H.265 有效），默认 ref_frame_num = 3、temporal_mvp_enable = TD_FALSE，tmv_buf_size 按分辨率计算。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_ENULL_PTR	base_attr 或 vdec_attr 为 NULL。

【需求】

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

【注意】

• 默认像素格式为 HI_MAPI_PIXEL_FORMAT_YVU_SEMIPLANAR_420，位宽 8。
• 默认压缩模式 HI_MAPI_COMPRESS_MODE_NONE，视频格式 HI_MAPI_VIDEO_FORMAT_LINEAR。

【举例】无

【相关主题】 hi_mapi_vdec_init、hi_mapi_vdec_set_attr

---

2 hi_mapi_vdec_init

【描述】 初始化指定通道的视频解码实例（首次调用时自动初始化 VDEC 模块，并创建 SDK 解码通道）。

【语法】

td_s32 hi_mapi_vdec_init(td_handle vdec_hdl, const hi_mapi_vdec_attr *vdec_attr);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
vdec_attr	输入	const hi_mapi_vdec_attr *	解码属性指针。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	vdec_attr 为 NULL。
HI_MAPI_VDEC_EILLEGAL_PARAM	get_frame_mode 非法（必须为 COMMON 或 FAST）。
HI_MAPI_VDEC_ENOT_INITED	media 系统尚未初始化。

【需求】

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

【注意】

• get_frame_mode 为静态属性，初始化后不可通过 set_attr 修改。
• 同一通道重复初始化视为成功直接返回。

【举例】无

【相关主题】 hi_mapi_vdec_deinit、hi_mapi_vdec_get_default_attr

---

3 hi_mapi_vdec_deinit

【描述】 去初始化指定通道的视频解码实例；若所有通道均已去初始化，则自动去初始化 VDEC 模块。

【语法】

td_s32 hi_mapi_vdec_deinit(td_handle vdec_hdl);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENOT_INITED	media 系统尚未初始化。
HI_MAPI_VDEC_EBUSY	停止/复位/销毁通道时存在子步骤失败（已尽力完成）。

【需求】

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

【注意】

• 若通道处于 started 状态，内部会先调用 hi_mapi_vdec_stop。
• 会释放通道绑定的 VB pool（图片 buffer 和 TMV buffer）。
• 当最后一个通道去初始化完成后，VDEC 模块随之去初始化。

【举例】无

【相关主题】 hi_mapi_vdec_init

---

4 hi_mapi_vdec_start

【描述】 启动指定 VDEC 通道的解码接收。

【语法】

td_s32 hi_mapi_vdec_start(td_handle vdec_hdl);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】

• 通道已处于 started 状态时，视为成功直接返回。

【举例】无

【相关主题】 hi_mapi_vdec_stop

---

5 hi_mapi_vdec_stop

【描述】 停止指定 VDEC 通道的解码接收，并解绑 VB pool。

【语法】

td_s32 hi_mapi_vdec_stop(td_handle vdec_hdl);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】

• 通道未处于 started 状态时，视为成功直接返回。
• 若通道绑定了 VB pool，会调用 SDK 解绑。

【举例】无

【相关主题】 hi_mapi_vdec_start

---

6 hi_mapi_vdec_query_status

【描述】 查询指定 VDEC 通道的解码状态（剩余码流字节数/帧数、待输出图像数、当前解码分辨率等）。

【语法】

td_s32 hi_mapi_vdec_query_status(td_handle vdec_hdl, hi_mapi_vdec_status *status);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
status	输出	hi_mapi_vdec_status *	解码状态输出指针。不可为 NULL。

成员名称（hi_mapi_vdec_status）	描述
type	视频类型。
left_stream_bytes	等待解码的剩余码流字节数。
left_stream_frames	等待解码的剩余码流帧数（仅 VIDEO_MODE_FRAME 有效）。
left_pics	等待输出的图像数。
start_recv_stream	是否已开始接收码流。
recv_stream_frames	已接收的码流帧数（仅帧模式有效）。
decode_stream_frames	已解码的码流帧数（仅帧模式有效）。
width / height	当前解码出的码流宽/高。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	status 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vdec_send_stream

---

7 hi_mapi_vdec_set_attr

【描述】 设置指定 VDEC 通道的解码属性（送流模式、buffer 大小、VB 绑定等）。get_frame_mode 为静态属性，不可修改。

【语法】

td_s32 hi_mapi_vdec_set_attr(td_handle vdec_hdl, const hi_mapi_vdec_attr *vdec_attr);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
vdec_attr	输入	const hi_mapi_vdec_attr *	解码属性指针。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	vdec_attr 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。
HI_MAPI_VDEC_ENOT_PERM	尝试修改 get_frame_mode（静态属性）。

【需求】

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

【注意】

• get_frame_mode 不可在 set_attr 中修改，否则返回 ENOT_PERM。
• 当 user_vb_flag == TD_TRUE 且 frame_buf_size/frame_buf_cnt > 0 时，会自动创建并绑定图片 VB pool；类似处理 TMV VB pool。

【举例】无

【相关主题】 hi_mapi_vdec_get_attr

---

8 hi_mapi_vdec_get_attr

【描述】 获取指定 VDEC 通道当前的解码属性。

【语法】

td_s32 hi_mapi_vdec_get_attr(td_handle vdec_hdl, hi_mapi_vdec_attr *vdec_attr);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
vdec_attr	输出	hi_mapi_vdec_attr *	解码属性输出指针。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	vdec_attr 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】

• 返回的 get_frame_mode 来自内部缓存（init 时记录），不从 SDK 回读。

【举例】无

【相关主题】 hi_mapi_vdec_set_attr

---

9 hi_mapi_vdec_set_param

【描述】 设置 VDEC 通道的扩展参数（解码模式、显示帧数、错误阈值等）。

【语法】

td_s32 hi_mapi_vdec_set_param(td_handle vdec_hdl, const hi_mapi_vdec_param *vdec_param);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
vdec_param	输入	const hi_mapi_vdec_param *	扩展参数指针。不可为 NULL。

成员名称（hi_mapi_vdec_param）	描述
type	视频类型。
display_frame_num	显示帧数，范围 [0, 16]。
vdec_video_param	视频扩展参数（H.264/H.265），含复合解码使能、slice 输入、错误阈值、解码模式、输出顺序、压缩模式、视频格式、快速标记模式。
vdec_picture_param	图像扩展参数（JPEG/MJPEG），含像素格式、alpha。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	vdec_param 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vdec_get_param

---

10 hi_mapi_vdec_get_param

【描述】 获取 VDEC 通道的扩展参数。

【语法】

td_s32 hi_mapi_vdec_get_param(td_handle vdec_hdl, hi_mapi_vdec_param *vdec_param);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
vdec_param	输出	hi_mapi_vdec_param *	扩展参数输出指针。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	vdec_param 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vdec_set_param

---

11 hi_mapi_vdec_send_stream

【描述】 向指定 VDEC 通道发送一帧/一段码流数据。

【语法】

td_s32 hi_mapi_vdec_send_stream(td_handle vdec_hdl, const hi_mapi_vdec_stream *stream, td_s32 timeout);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
stream	输入	const hi_mapi_vdec_stream *	码流数据指针。不可为 NULL。
timeout	输入	td_s32	超时时间（毫秒）。

成员名称（hi_mapi_vdec_stream）	描述
stream_addr	码流地址（虚拟地址，带对齐属性）。
stream_len	码流长度（字节）。
time_stamp	时间戳。
private_data	私有数据（仅 VIDEO_MODE_FRAME / COMPAT 有效）。
end_of_frame	是否为一帧结束。
end_of_stream	是否为全部码流结束。
display	当前帧是否显示（仅 VIDEO_MODE_FRAME 有效）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	stream 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vdec_get_frame

---

12 hi_mapi_vdec_get_frame

【描述】 从指定 VDEC 通道获取一帧解码后的视频数据。

【语法】

td_s32 hi_mapi_vdec_get_frame(td_handle vdec_hdl, hi_mapi_frame_data *frame_data, td_u32 timeout);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
frame_data	输出	hi_mapi_frame_data *	解码帧数据输出指针。不可为 NULL。
timeout	输入	td_u32	超时时间（毫秒）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	frame_data 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】

• 取到的帧必须通过 hi_mapi_vdec_release_frame 释放。

【举例】无

【相关主题】 hi_mapi_vdec_release_frame、hi_mapi_vdec_send_stream

---

13 hi_mapi_vdec_release_frame

【描述】 释放通过 hi_mapi_vdec_get_frame 获取的解码帧资源。

【语法】

td_s32 hi_mapi_vdec_release_frame(td_handle vdec_hdl, const hi_mapi_frame_data *frame_data);

【参数】

参数名称	输入/输出	类型	描述
vdec_hdl	输入	td_handle	VDEC 通道号，范围 [0, 7]。
frame_data	输入	const hi_mapi_frame_data *	要释放的帧数据指针（需与 get_frame 取回的一致）。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VDEC_EHANDLE_ILLEGAL	vdec_hdl 超出范围。
HI_MAPI_VDEC_ENULL_PTR	frame_data 为 NULL。
HI_MAPI_VDEC_ENOT_INITED	media 系统或通道尚未初始化。

【需求】

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

【注意】

• 必须与 get_frame 成对使用，否则会造成 VB 泄漏。

【举例】无

【相关主题】 hi_mapi_vdec_get_frame

4 数据类型

⚠ HI3516CV610 不支持 VDEC 模块，本节类型仅随头文件声明存在。 详见 第 3 章 API 参考 开头说明。

1 hi_mapi_vdec_base_attr

【说明】 VDEC 基础属性，用于 hi_mapi_vdec_get_default_attr 中传入解码类型与分辨率以派生完整的 hi_mapi_vdec_attr。

【定义】

typedef struct {
    hi_mapi_payload_type type;
    td_u32 width;
    td_u32 height;
} hi_mapi_vdec_base_attr;

【成员】

成员名称	描述
type	解码协议类型，详见 hi_mapi_payload_type。
width	最大图像宽度，单位像素。
height	最大图像高度，单位像素。

【注意事项】

• 通过 hi_mapi_vdec_get_default_attr 派生出完整的 hi_mapi_vdec_attr。

【相关数据类型及接口】 hi_mapi_vdec_attr；hi_mapi_vdec_get_default_attr。

2 hi_mapi_vdec_get_frame_mode

【说明】 VDEC 获取解码帧的模式枚举。

【定义】

typedef enum {
    HI_MAPI_VDEC_MODE_COMMON = 0,
    HI_MAPI_VDEC_MODE_FAST,
    HI_MAPI_VDEC_MODE_BUTT
} hi_mapi_vdec_get_frame_mode;

【成员】

枚举值	描述
HI_MAPI_VDEC_MODE_COMMON	普通模式，通过消息获取帧。
HI_MAPI_VDEC_MODE_FAST	快速模式，通过 DataFIFO 获取帧。
HI_MAPI_VDEC_MODE_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vdec_attr。

3 hi_mapi_vdec_video_mode

【说明】 VDEC 视频送流模式枚举。

【定义】

typedef enum {
    HI_MAPI_VDEC_VIDEO_MODE_STREAM = 0,
    HI_MAPI_VDEC_VIDEO_MODE_FRAME,
    HI_MAPI_VDEC_VIDEO_MODE_COMPAT,
    HI_MAPI_VDEC_VIDEO_MODE_BUTT
} hi_mapi_vdec_video_mode;

【成员】

枚举值	描述
HI_MAPI_VDEC_VIDEO_MODE_STREAM	按码流送流。
HI_MAPI_VDEC_VIDEO_MODE_FRAME	按帧送流。
HI_MAPI_VDEC_VIDEO_MODE_COMPAT	兼容模式，一帧支持多包发送，当 bEndOfFrame 为 TD_TRUE 时认为当前帧结束。
HI_MAPI_VDEC_VIDEO_MODE_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vdec_attr。

4 hi_mapi_vdec_video_dec_mode

【说明】 VDEC 视频解码模式枚举。

【定义】

typedef enum {
    HI_MAPI_VDEC_VIDEO_DEC_MODE_IPB = 0,
    HI_MAPI_VDEC_VIDEO_DEC_MODE_IP,
    HI_MAPI_VDEC_VIDEO_DEC_MODE_I,
    HI_MAPI_VDEC_VIDEO_DEC_MODE_BUTT
} hi_mapi_vdec_video_dec_mode;

【成员】

枚举值	描述
HI_MAPI_VDEC_VIDEO_DEC_MODE_IPB	解码 IPB 帧。
HI_MAPI_VDEC_VIDEO_DEC_MODE_IP	仅解码 I 帧和 P 帧。
HI_MAPI_VDEC_VIDEO_DEC_MODE_I	仅解码 I 帧。
HI_MAPI_VDEC_VIDEO_DEC_MODE_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vdec_video_param。

5 hi_mapi_vdec_video_output_order

【说明】 VDEC 视频帧输出顺序枚举。

【定义】

typedef enum {
    HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_DISP = 0,
    HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_DEC,
    HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_BUTT
} hi_mapi_vdec_video_output_order;

【成员】

枚举值	描述
HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_DISP	按显示顺序输出。
HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_DEC	按解码顺序输出。
HI_MAPI_VDEC_VIDEO_OUTPUT_ORDER_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vdec_video_param。

6 hi_mapi_vdec_quick_mark_mode

【说明】 VDEC 快进标记模式枚举。

【定义】

typedef enum {
    HI_MAPI_VDEC_QUICK_MARK_ADAPT = 0,
    HI_MAPI_VDEC_QUICK_MARK_FORCE,
    HI_MAPI_VDEC_QUICK_MARK_NONE,
    HI_MAPI_VDEC_QUICK_MARK_BUTT
} hi_mapi_vdec_quick_mark_mode;

【成员】

枚举值	描述
HI_MAPI_VDEC_QUICK_MARK_ADAPT	自适应快进标记。
HI_MAPI_VDEC_QUICK_MARK_FORCE	强制快进标记。
HI_MAPI_VDEC_QUICK_MARK_NONE	不快进。
HI_MAPI_VDEC_QUICK_MARK_BUTT	哨兵值，无效。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vdec_video_param。

7 hi_mapi_vdec_video_attr

【说明】 VDEC 视频解码通道视频属性，包含参考帧数与 TMV buffer 配置。

【定义】

typedef struct {
    td_u32  ref_frame_num;
    td_bool temporal_mvp_enable;
    td_u32  tmv_buf_size;
} hi_mapi_vdec_video_attr;

【成员】

成员名称	描述
ref_frame_num	参考帧数量；取值范围 [0, 16]。
temporal_mvp_enable	是否启用时域运动向量预测（TMVP）；TD_TRUE 启用。
tmv_buf_size	TMV buffer 大小，单位字节。

【注意事项】

• 作为 hi_mapi_vdec_attr 联合体成员使用。

【相关数据类型及接口】 hi_mapi_vdec_attr。

8 hi_mapi_vdec_video_param

【说明】 VDEC 视频解码扩展参数，包含解码模式、输出顺序、错误阈值等。

【定义】

typedef struct {
    td_bool                           enable_composite_dec;
    td_bool                           enable_slice_input;
    td_s32                            err_threshold;
    hi_mapi_vdec_video_dec_mode       dec_mode;
    hi_mapi_vdec_video_output_order   output_order;
    hi_mapi_compress_mode             compress_mode;
    hi_mapi_video_format              video_format;
    hi_mapi_vdec_quick_mark_mode      quick_mark_mode;
} hi_mapi_vdec_video_param;

【成员】

成员名称	描述
enable_composite_dec	是否输出增强层；TD_FALSE 输出基础层（默认），TD_TRUE 输出增强层。
enable_slice_input	是否支持 Slice 低延时输入；TD_TRUE 启用，默认 TD_FALSE。
err_threshold	码流错误处理阈值；取值范围 [0, 100]，0 表示遇到任何错误即丢弃，100 表示遇到任何错误仍保留。
dec_mode	解码模式，详见 hi_mapi_vdec_video_dec_mode。
output_order	帧输出顺序，详见 hi_mapi_vdec_video_output_order。
compress_mode	压缩模式，详见 hi_mapi_compress_mode。
video_format	视频格式，详见 hi_mapi_video_format。
quick_mark_mode	快进标记模式，详见 hi_mapi_vdec_quick_mark_mode。

【注意事项】

• 作为 hi_mapi_vdec_param 联合体成员使用。

【相关数据类型及接口】 hi_mapi_vdec_param。

9 hi_mapi_vdec_picture_param

【说明】 VDEC 图片解码（JPEG/MJPEG）扩展参数。

【定义】

typedef struct {
    hi_mapi_pixel_format pxel_format;
    td_u32 alpha;
} hi_mapi_vdec_picture_param;

【成员】

成员名称	描述
pxel_format	输出像素格式，详见 hi_mapi_pixel_format。
alpha	透明度值；取值范围 [0, 255]，0 为全透明。对于 ARGB1555/ABGR1555 格式，[0, 127] 为透明，[128, 256] 为不透明。

【注意事项】

• 作为 hi_mapi_vdec_param 联合体成员使用。

【相关数据类型及接口】 hi_mapi_vdec_param。

10 hi_mapi_vdec_attr

【说明】 VDEC 解码通道完整属性，包含解码类型、送流模式、buffer 配置及视频/图片特有参数。

【定义】

typedef struct {
    hi_mapi_payload_type        type;
    hi_mapi_vdec_video_mode     mode;
    hi_mapi_vdec_get_frame_mode get_frame_mode;
    td_u32                      pic_width;
    td_u32                      pic_height;
    td_u32                      stream_buf_size;
    td_u32                      frame_buf_size;
    td_u32                      frame_buf_cnt;
    td_bool                     user_vb_flag;
    union {
        hi_mapi_vdec_video_attr vdec_video_attr;
    };
} hi_mapi_vdec_attr;

【成员】

成员名称	描述
type	解码协议类型，详见 hi_mapi_payload_type。
mode	送流模式，详见 hi_mapi_vdec_video_mode。
get_frame_mode	获取帧模式，详见 hi_mapi_vdec_get_frame_mode。
pic_width	最大图像宽度，单位像素。
pic_height	最大图像高度，单位像素。
stream_buf_size	码流缓冲区大小，单位字节。
frame_buf_size	帧缓冲区大小，单位字节。
frame_buf_cnt	帧缓冲区数量。
user_vb_flag	是否使用用户 VB；TD_TRUE 使用用户自有 VB。
vdec_video_attr	视频解码属性，详见 hi_mapi_vdec_video_attr。

【注意事项】

• HI3516CV610 平台最多支持 OT_VDEC_MAX_CHN_NUM（8）个 VDEC 通道。
• 通过 hi_mapi_vdec_set_attr / hi_mapi_vdec_get_attr 设置/获取。

【相关数据类型及接口】 hi_mapi_vdec_video_attr；hi_mapi_vdec_init、hi_mapi_vdec_set_attr、hi_mapi_vdec_get_attr。

11 hi_mapi_vdec_param

【说明】 VDEC 解码通道扩展参数，包含显示帧数及视频/图片解码参数的联合体。

【定义】

typedef struct {
    hi_mapi_payload_type type;
    td_u32 display_frame_num;
    union {
        hi_mapi_vdec_video_param   vdec_video_param;
        hi_mapi_vdec_picture_param vdec_picture_param;
    };
} hi_mapi_vdec_param;

【成员】

成员名称	描述
type	解码协议类型，详见 hi_mapi_payload_type。
display_frame_num	显示帧数；取值范围 [0, 16]。
vdec_video_param	视频解码扩展参数（H.264/H.265），详见 hi_mapi_vdec_video_param。
vdec_picture_param	图片解码扩展参数（JPEG/MJPEG），详见 hi_mapi_vdec_picture_param。

【注意事项】

• 通过 hi_mapi_vdec_set_param / hi_mapi_vdec_get_param 设置/获取。

【相关数据类型及接口】 hi_mapi_vdec_video_param、hi_mapi_vdec_picture_param；hi_mapi_vdec_set_param、hi_mapi_vdec_get_param。

12 hi_mapi_vdec_stream

【说明】 VDEC 送流数据结构，包含码流地址、长度、时间戳及帧结束/码流结束标志。

【定义】

typedef struct {
    td_u32  stream_len;
    td_u64  time_stamp;
    td_u64  private_data;
    td_bool end_of_frame;
    td_bool end_of_stream;
    td_bool display;
    td_u8   *stream_addr;
} hi_mapi_vdec_stream;

【成员】

成员名称	描述
stream_len	码流长度，单位字节。
time_stamp	时间戳。
private_data	用户私有数据；仅在 VIDEO_MODE_FRAME 或 VIDEO_MODE_COMPAT 模式下有效。
end_of_frame	帧结束标志；TD_TRUE 表示当前码流为帧末尾。
end_of_stream	码流结束标志；TD_TRUE 表示所有码流发送完毕。
display	是否显示当前帧；仅在 VIDEO_MODE_FRAME 模式下有效。
stream_addr	码流地址（对齐）。

【注意事项】

• 通过 hi_mapi_vdec_send_stream 送入解码通道。

【相关数据类型及接口】 hi_mapi_vdec_send_stream。

13 hi_mapi_vdec_status

【说明】 VDEC 解码通道状态信息，包含剩余码流/帧数、当前解码分辨率等。

【定义】

typedef struct {
    hi_mapi_payload_type type;
    td_u32 left_stream_bytes;
    td_u32 left_stream_frames;
    td_u32 left_pics;
    td_bool start_recv_stream;
    td_u32 recv_stream_frames;
    td_u32 decode_stream_frames;
    td_u32 width;
    td_u32 height;
} hi_mapi_vdec_status;

【成员】

成员名称	描述
type	解码协议类型。
left_stream_bytes	剩余等待解码的码流字节数。
left_stream_frames	剩余等待解码的帧数；仅在 VIDEO_MODE_FRAME 模式下有效。
left_pics	等待输出的图像数。
start_recv_stream	是否已开始接收码流。
recv_stream_frames	已接收的码流帧数；仅在按帧送流模式下有效。
decode_stream_frames	已解码的码流帧数；仅在按帧送流模式下有效。
width	当前解码码流的宽度，单位像素。
height	当前解码码流的高度，单位像素。

【注意事项】

• 通过 hi_mapi_vdec_query_status 获取。

【相关数据类型及接口】 hi_mapi_vdec_query_status。

5 错误码

模块编号 mod=10，错误码基址 0xA30A8000。

⚠ HI3516CV610 不支持 VDEC 模块，实际不会产生本节错误码。详见第 3 章 API 参考开头说明。

错误代码	宏定义	描述
0xA30A8002	HI_MAPI_VDEC_EHANDLE_ILLEGAL	通道号无效。
0xA30A8003	HI_MAPI_VDEC_EILLEGAL_PARAM	参数非法。
0xA30A8004	HI_MAPI_VDEC_EEXIST	资源已存在。
0xA30A8005	HI_MAPI_VDEC_EUNEXIST	资源不存在。
0xA30A8006	HI_MAPI_VDEC_ENULL_PTR	空指针。