VCAP（视频采集）接口说明文档

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

1 概述

VCAP 模块封装 sensor / MIPI / VI pipe / VI pipe CHN / ISP 的完整视频采集通路，对外提供设备、pipe、通道的启动/停止、属性设置、ISP 控制以及帧获取/释放接口。HI3516CV610 上最多支持 2 路 VCAP 设备、每设备最多绑定 2 路 pipe、每 pipe 最多 1 路通道。

2 接口总览

编号	接口	功能概述
1	`hi_mapi_vcap_init_sensor`	初始化指定 VCAP 设备对应的 sensor，完成 combo_dev_attr 构造与 MIPI Rx 启动（sensor 时钟与 reset 由 `reset_sensor` 控制）。
2	`hi_mapi_vcap_deinit_sensor`	去初始化 sensor，关闭 MIPI Rx 并停止 sensor 时钟。
3	`hi_mapi_vcap_set_sensor_frame_rate`	在 ISP 启动后设置 sensor 输出帧率。
4	`hi_mapi_vcap_get_sensor_frame_rate`	获取当前 sensor 输出帧率。
5	`hi_mapi_vcap_start_dev`	启动 VCAP 设备：按 `set_attr` 时保存的属性创建 VI 设备、绑定 pipe、创建 pipe 并建立 WDR 融合组（若启用）。
6	`hi_mapi_vcap_stop_dev`	停止 VCAP 设备：依次停止绑定到该设备的 pipe 上所有通道、停止 pipe、销毁 pipe 与 VB 池、最后 disable 设备并清空全局状态。
7	`hi_mapi_vcap_start_pipe`	启动 VCAP pipe：设置帧中断属性并调用底层 `start_pipe`。
8	`hi_mapi_vcap_stop_pipe`	停止 VCAP pipe。
9	`hi_mapi_vcap_init_isp`	初始化 ISP：注册 sensor 回调、绑定 ISP 到 sensor（i2c/spi 总线）、注册 3A、设置 ISP init 属性（若通过 `set_config` 配置过）、mem_init、设置 pub attr、调用底层 ISP init。
10	`hi_mapi_vcap_deinit_isp`	反初始化 ISP：若 ISP 已 `start`，返回 `ENOT_PERM`；否则调用底层 ISP stop、注销 3A、注销 sensor 回调。
11	`hi_mapi_vcap_start_isp`	启动 ISP 固件（开启 ISP 运行线程）。
12	`hi_mapi_vcap_stop_isp`	停止 ISP 运行线程。
13	`hi_mapi_vcap_set_attr`	设置 VCAP 设备及其绑定 pipe、chn 的属性；若设备已在运行，仅接受动态属性（帧率、分辨率等）修改，静态属性（`pipe_type`、`pixel_format`、dev/pipe 绑定关系）修改返回 `ENOT_PERM`。
14	`hi_mapi_vcap_get_attr`	获取 VCAP 设备当前已配置（含运行中动态修改后）的属性。
15	`hi_mapi_vcap_set_param`	动态设置 VCAP 扩展属性，按 `command` 分派到具体处理函数；支持 ISP 属性（曝光、白平衡、锐化等）、通道属性（旋转、镜像/翻转、LDC、深度、低延时）及 sensor 场景切换（standby/restart）。
16	`hi_mapi_vcap_get_param`	动态获取 VCAP 扩展属性，按 `command` 分派到具体查询函数。
17	`hi_mapi_vcap_set_config`	设置 VCAP 静态配置（启动前生效）：ISP 3A init 属性、sensor OB 行数、VI pipe buffer wrap 等。可在 `start_dev` 之前调用。
18	`hi_mapi_vcap_get_config`	获取 VCAP 静态配置（缓存值；pipe 已创建后 `PIPE_BUF_WRAP` 从底层 SDK 读取权威值）。
19	`hi_mapi_vcap_start_chn`	启动 VCAP 通道：设置通道属性、创建 VB 池并在 VPSS offline 模式下 enable 通道。
20	`hi_mapi_vcap_stop_chn`	停止 VCAP 通道并销毁其 VB 池。
21	`hi_mapi_vcap_get_chn_frame`	从 VCAP 通道获取一帧图像数据。
22	`hi_mapi_vcap_release_chn_frame`	释放由 `hi_mapi_vcap_get_chn_frame` 获取的帧。
23	`hi_mapi_vcap_probe_sensor`	SENSOR0 自动匹配场景下探测真实 sensor 型号；返回命中的sensor型号 ID；

3 API 参考

1 hi_mapi_vcap_init_sensor

【描述】初始化指定 VCAP 设备对应的 sensor，完成 combo_dev_attr 构造与 MIPI Rx 启动（sensor 时钟与 reset 由 reset_sensor 控制）。

【语法】

td_s32 hi_mapi_vcap_init_sensor(td_handle vcap_dev_hdl, const hi_mapi_vcap_sensor_attr *sensor_attr, td_bool reset_sensor);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。
`sensor_attr`	输入	`const hi_mapi_vcap_sensor_attr *`	sensor 属性指针，不能为 `NULL`。
`reset_sensor`	输入	`td_bool`	是否对 sensor 执行 reset；`TD_TRUE` 为 reset。

hi_mapi_vcap_sensor_attr 成员：

成员名称	描述
`sns_mode`	sensor 工作模式序号（与 sensor 驱动相关）。
`wdr_mode`	WDR 模式（`HI_MAPI_VCAP_WDR_MODE_NONE` 等）。
`size`	sensor 输出分辨率（宽×高）。
`input_dev_attr`	设备级输入属性（`input_mode`、`input_data_type`、`use_serdes_dev`）。
`sns_dev_attr`	sensor 自身属性（`sensor_obj`、`data_rate`、`input_attr`、`lane_id[4]`）。
`combo_dev_attr`	MIPI/LVDS 组合设备属性（`lane_id_mode`、`sns_clk_source`、`sns_rst_source`、`bus_id`）。

【返回值】

返回值	描述
`0`	成功。若 sensor 属性未变化，也返回成功（幂等）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENULL_PTR`	`sensor_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化（`hi_mapi_sys_init_media` 未调用）。
`HI_MAPI_VCAP_ENOT_PERM`	该 VCAP 设备已处于 `RUNNING` 状态，必须先 `stop_dev`。
`HI_MAPI_VCAP_EINVALID_FD`	MIPI 设备节点打开失败。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须在 hi_mapi_sys_init_media 之后、hi_mapi_vcap_set_attr 之前调用。
与 hi_mapi_vcap_deinit_sensor 配对。

【举例】

hi_mapi_vcap_sensor_attr sns_attr = {0};
sns_attr.sns_mode = 0;
sns_attr.wdr_mode = HI_MAPI_VCAP_WDR_MODE_NONE;
sns_attr.size.width = 2560; sns_attr.size.height = 1440;
sns_attr.input_dev_attr.input_mode      = HI_MAPI_VCAP_INPUT_MODE_MIPI;
sns_attr.input_dev_attr.input_data_type = HI_MAPI_VCAP_INPUT_DATA_TYPE_RAW_12BIT;
sns_attr.sns_dev_attr.sensor_obj = (td_void *)hy006_3814_0011_get_obj();
sns_attr.sns_dev_attr.data_rate  = HI_MAPI_VCAP_MIPI_DATA_RATE_X1;
sns_attr.sns_dev_attr.input_attr.bayer_format    = HI_MAPI_VCAP_BAYER_FORMAT_RGGB;
sns_attr.sns_dev_attr.input_attr.comm_bus_type   = HI_MAPI_SENSOR_COMMBUS_TYPE_I2C;
sns_attr.combo_dev_attr.lane_id_mode = HI_MAPI_VCAP_LANE_DIVIDE_MODE_0;
sns_attr.combo_dev_attr.bus_id       = 0;
ret = hi_mapi_vcap_init_sensor(0, &sns_attr, TD_TRUE);

【相关主题】 hi_mapi_vcap_deinit_sensor、hi_mapi_vcap_sensor_attr

2 hi_mapi_vcap_deinit_sensor

【描述】去初始化 sensor，关闭 MIPI Rx 并停止 sensor 时钟。

【语法】

td_s32 hi_mapi_vcap_deinit_sensor(td_handle vcap_dev_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（若 sensor 未初始化，也返回成功，幂等）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	VCAP 设备处于 `RUNNING`，必须先 `stop_dev`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

调用前必须已 hi_mapi_vcap_stop_dev。

【举例】无

【相关主题】 hi_mapi_vcap_init_sensor

3 hi_mapi_vcap_set_sensor_frame_rate

【描述】在 ISP 启动后设置 sensor 输出帧率。

【语法】

td_s32 hi_mapi_vcap_set_sensor_frame_rate(td_handle vcap_dev_hdl, td_float frame_rate);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。
`frame_rate`	输入	`td_float`	目标帧率（单位 fps）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	sensor 未初始化或 VCAP 设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须在 hi_mapi_vcap_start_isp 之后调用。

【举例】无

【相关主题】 hi_mapi_vcap_get_sensor_frame_rate

4 hi_mapi_vcap_get_sensor_frame_rate

【描述】获取当前 sensor 输出帧率。

【语法】

td_s32 hi_mapi_vcap_get_sensor_frame_rate(td_handle vcap_dev_hdl, td_float *frame_rate);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。
`frame_rate`	输出	`td_float *`	输出帧率（fps），不能为 `NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENULL_PTR`	`frame_rate` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	sensor 未初始化或 VCAP 设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须在 hi_mapi_vcap_start_dev（实际为 ISP 启动）之后调用。

【举例】无

【相关主题】 hi_mapi_vcap_set_sensor_frame_rate

5 hi_mapi_vcap_start_dev

【描述】启动 VCAP 设备：按 set_attr 时保存的属性创建 VI 设备、绑定 pipe、创建 pipe 并建立 WDR 融合组（若启用）。

【语法】

td_s32 hi_mapi_vcap_start_dev(td_handle vcap_dev_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含已启动时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	sensor 未初始化。
`HI_MAPI_VCAP_ENOT_CONFIG`	未先调用 `hi_mapi_vcap_set_attr`。
`HI_MAPI_VCAP_EOPERATE_FAIL`	底层启动失败。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先调用 hi_mapi_vcap_init_sensor 与 hi_mapi_vcap_set_attr。
与 hi_mapi_vcap_stop_dev 配对。

【举例】

ret = hi_mapi_vcap_init_sensor(0, &sns_attr, TD_TRUE);
ret = hi_mapi_vcap_set_attr(0, &vcap_attr);
ret = hi_mapi_vcap_start_dev(0);

【相关主题】 hi_mapi_vcap_stop_dev、hi_mapi_vcap_set_attr

6 hi_mapi_vcap_stop_dev

【描述】停止 VCAP 设备：依次停止绑定到该设备的 pipe 上所有通道、停止 pipe、销毁 pipe 与 VB 池、最后 disable 设备并清空全局状态。

【语法】

td_s32 hi_mapi_vcap_stop_dev(td_handle vcap_dev_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含已停止时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

停止后必须重新 set_attr 才能再次启动。

【举例】无

【相关主题】 hi_mapi_vcap_start_dev

7 hi_mapi_vcap_start_pipe

【描述】启动 VCAP pipe：设置帧中断属性并调用底层 start_pipe。

【语法】

td_s32 hi_mapi_vcap_start_pipe(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 尚未由 `start_dev` 创建，或对应 VCAP 设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 hi_mapi_vcap_start_dev，再 start_pipe。

【举例】无

【相关主题】 hi_mapi_vcap_stop_pipe

8 hi_mapi_vcap_stop_pipe

【描述】停止 VCAP pipe。

【语法】

td_s32 hi_mapi_vcap_stop_pipe(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建或设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

与 hi_mapi_vcap_start_pipe 配对使用。

【举例】无

【相关主题】 hi_mapi_vcap_start_pipe

9 hi_mapi_vcap_init_isp

【描述】初始化 ISP：注册 sensor 回调、绑定 ISP 到 sensor（i2c/spi 总线）、注册 3A、设置 ISP init 属性（若通过 set_config 配置过）、mem_init、设置 pub attr、调用底层 ISP init。

【语法】

td_s32 hi_mapi_vcap_init_isp(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含已初始化时幂等返回成功；WDR 模式下非主 pipe 也直接返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建、或对应设备未处于 `RUNNING`、或 sensor 未初始化。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 start_dev；与 hi_mapi_vcap_deinit_isp 配对。

【举例】无

【相关主题】 hi_mapi_vcap_deinit_isp、hi_mapi_vcap_start_isp

10 hi_mapi_vcap_deinit_isp

【描述】反初始化 ISP：若 ISP 已 start，返回 ENOT_PERM；否则调用底层 ISP stop、注销 3A、注销 sensor 回调。

【语法】

td_s32 hi_mapi_vcap_deinit_isp(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含未初始化时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	ISP 仍在运行（需先 `stop_isp`），或设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 stop_isp 再 deinit_isp。

【举例】无

【相关主题】 hi_mapi_vcap_init_isp

11 hi_mapi_vcap_start_isp

【描述】启动 ISP 固件（开启 ISP 运行线程）。

【语法】

td_s32 hi_mapi_vcap_start_isp(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含已启动时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	ISP 未初始化或设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 init_isp；调用后 ISP 线程开始运行，set_sensor_frame_rate 才能生效。

【举例】无

【相关主题】 hi_mapi_vcap_stop_isp、hi_mapi_vcap_init_isp

12 hi_mapi_vcap_stop_isp

【描述】停止 ISP 运行线程。

【语法】

td_s32 hi_mapi_vcap_stop_isp(td_handle vcap_pipe_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。

【返回值】

返回值	描述
`0`	成功（含未启动时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

与 hi_mapi_vcap_start_isp 配对。

【举例】无

【相关主题】 hi_mapi_vcap_start_isp

13 hi_mapi_vcap_set_attr

【描述】设置 VCAP 设备及其绑定 pipe、chn 的属性；若设备已在运行，仅接受动态属性（帧率、分辨率等）修改，静态属性（pipe_type、pixel_format、dev/pipe 绑定关系）修改返回 ENOT_PERM。

【语法】

td_s32 hi_mapi_vcap_set_attr(td_handle vcap_dev_hdl, const hi_mapi_vcap_attr *vcap_attr);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。
`vcap_attr`	输入	`const hi_mapi_vcap_attr *`	VCAP 属性指针，不能为 `NULL`。

hi_mapi_vcap_attr 成员：

成员名称	描述
`vcap_dev_attr`	设备级属性（`wdr_mode`、`intf_mode`、`data_seq`、`data_type`）。
`pipe_bind_num`	绑定 pipe 数量，HI3516CV610 上取值范围 `[1, 2]`。
`pipe_id_bind[pipe_bind_num]`	绑定的 pipe 句柄数组，每个取值范围 `[0, 1]`。
`vcap_pipe_attr[pipe_id]`	每个 pipe 的属性（`pipe_type`、`frame_rate_ctrl`、`isp_pub_attr`、`vb_pool_blk_cnt`、`pipe_chn_attr`）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENULL_PTR`	`vcap_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	sensor 未初始化；或运行中修改静态属性/绑定关系。
`HI_MAPI_VCAP_EILLEGAL_PARA`	`pipe_bind_num > 2`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须在 init_sensor 之后、start_dev 之前调用；运行中可修改动态属性。

【举例】见 sample_pipeline_vio.c 中 fill_vcap_attr()。

【相关主题】 hi_mapi_vcap_get_attr、hi_mapi_vcap_attr

14 hi_mapi_vcap_get_attr

【描述】获取 VCAP 设备当前已配置（含运行中动态修改后）的属性。

【语法】

td_s32 hi_mapi_vcap_get_attr(td_handle vcap_dev_hdl, hi_mapi_vcap_attr *vcap_attr);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，HI3516CV610 取值范围 `[0, 1]`。
`vcap_attr`	输出	`hi_mapi_vcap_attr *`	输出 VCAP 属性，不能为 `NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENULL_PTR`	`vcap_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_CONFIG`	尚未 `set_attr`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】无

【举例】无

【相关主题】 hi_mapi_vcap_set_attr

15 hi_mapi_vcap_set_param

【描述】动态设置 VCAP 扩展属性，按 command 分派到具体处理函数；支持 ISP 属性（曝光、白平衡、锐化等）、通道属性（旋转、镜像/翻转、LDC、深度、低延时）及 sensor 场景切换（standby/restart）。

【语法】

td_s32 hi_mapi_vcap_set_param(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl, hi_mapi_vcap_cmd command,
                              const td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值范围 `[0, 0]`（HI3516CV610 每 pipe 1 个通道）。
`command`	输入	`hi_mapi_vcap_cmd`	扩展命令，取值范围 `[0, HI_MAPI_VCAP_CMD_BUTT-1]`。
`cmd_attr`	输入	`const td_void *`	命令参数指针；`ENTER_STANDBY`/`EXIT_STANDBY`/`RESTART_SENSOR` 时可为 `NULL`，其它命令不能为 `NULL`。
`len`	输入	`td_u32`	命令参数结构体大小；`ENTER_STANDBY`/`EXIT_STANDBY`/`RESTART_SENSOR` 时可为 0，其它命令必须 `> 0`。

常用 command 与 cmd_attr 类型：

command	cmd_attr 类型	描述
`HI_MAPI_VCAP_CMD_ISP_EXPOURSEATTR`	`hi_mapi_vcap_exposure_attr *`	曝光属性。
`HI_MAPI_VCAP_CMD_ISP_WBATTR`	`hi_mapi_vcap_wb_attr *`	白平衡属性。
`HI_MAPI_VCAP_CMD_ISP_SHARPEN`	`hi_mapi_vcap_sharpen *`	锐化。
`HI_MAPI_VCAP_CMD_ISP_LUMA`	`hi_mapi_vcap_luma *`	亮度。
`HI_MAPI_VCAP_CMD_ISP_SATURATION`	`hi_mapi_vcap_saturation *`	饱和度。
`HI_MAPI_VCAP_CMD_ISP_CONTRAST`	`hi_mapi_vcap_contrast *`	对比度。
`HI_MAPI_VCAP_CMD_ISP_METERINGMODE`	`hi_mapi_vcap_metering_mode *`	测光模式。
`HI_MAPI_VCAP_CMD_ROTATE`	`hi_mapi_rotation *`	通道旋转。
`HI_MAPI_VCAP_CMD_MIRRORFLIP`	`hi_mapi_vcap_mirror_flip_attr *`	镜像/翻转。
`HI_MAPI_VCAP_CMD_CHN_DEPTH`	`hi_mapi_vcap_chn_depth *`	通道帧队列深度 `[0, 8]`。
`HI_MAPI_VCAP_CMD_ENTER_STANDBY`	（可 `NULL`）	sensor 进入 standby。
`HI_MAPI_VCAP_CMD_EXIT_STANDBY`	（可 `NULL`）	sensor 退出 standby。
`HI_MAPI_VCAP_CMD_RESTART_SENSOR`	（可 `NULL`）	重启 sensor（需先进 standby）。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1` 或 `pipe_chn_hdl > 0`。
`HI_MAPI_VCAP_ENULL_PTR`	非 standby/restart 命令但 `cmd_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建或设备未处于 `RUNNING`。
`HI_MAPI_VCAP_EILLEGAL_PARA`	命令值越界或参数本身非法（例如曝光增益低于下限）。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 start_dev；WDR 模式下仅主 pipe 生效。
旋转/镜像翻转在 online/parallel 工作模式下不支持。

【举例】无

【相关主题】 hi_mapi_vcap_get_param、hi_mapi_vcap_cmd

16 hi_mapi_vcap_get_param

【描述】动态获取 VCAP 扩展属性，按 command 分派到具体查询函数。

【语法】

td_s32 hi_mapi_vcap_get_param(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl, hi_mapi_vcap_cmd command,
                              td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值范围 `[0, 0]`。
`command`	输入	`hi_mapi_vcap_cmd`	扩展命令，取值范围 `[0, HI_MAPI_VCAP_CMD_BUTT-1]`。
`cmd_attr`	输出	`td_void *`	命令输出缓冲，不能为 `NULL`。
`len`	输入	`td_u32`	命令输出缓冲大小，必须 `> 0`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_pipe_hdl > 1` 或 `pipe_chn_hdl > 0`。
`HI_MAPI_VCAP_ENULL_PTR`	`cmd_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建或设备未处于 `RUNNING`。
`HI_MAPI_VCAP_EILLEGAL_PARA`	命令值越界或 `len` 过小。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 start_dev。

【举例】无

【相关主题】 hi_mapi_vcap_set_param

17 hi_mapi_vcap_set_config

【描述】设置 VCAP 静态配置（启动前生效）：ISP 3A init 属性、sensor OB 行数、VI pipe buffer wrap 等。可在 start_dev 之前调用。

【语法】

td_s32 hi_mapi_vcap_set_config(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl, hi_mapi_vcap_config_cmd command,
                               const td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄（`ISP_3AINIT`/`PIPE_BUF_WRAP`）或 dev 句柄（`OB_HEIGHT`），HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄（本接口暂未使用，填 0）。
`command`	输入	`hi_mapi_vcap_config_cmd`	静态配置命令，取值范围 `[0, HI_MAPI_VCAP_CONFIG_CMD_BUTT-1]`。
`cmd_attr`	输入	`const td_void *`	配置参数指针，不能为 `NULL`。
`len`	输入	`td_u32`	配置参数结构体大小，必须 `> 0`。

command	cmd_attr 类型	描述
`HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT`	`hi_mapi_vcap_isp_init_attr *`	ISP AE/AWB 初始属性，在 `init_isp` 之前生效。
`HI_MAPI_VCAP_CONFIG_CMD_OB_HEIGHT`	`hi_mapi_vcap_ob_height_cfg *`	sensor OB 行数，调用时 `vcap_pipe_hdl` 实际为 dev 句柄，需在 `init_sensor` 之前设置。
`HI_MAPI_VCAP_CONFIG_CMD_PIPE_BUF_WRAP`	`hi_mapi_vcap_buf_wrap_attr *`	VI pipe 卷绕开关，必须在 `start_dev` 之前设置。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	句柄越界。
`HI_MAPI_VCAP_ENULL_PTR`	`cmd_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_EILLEGAL_PARA`	命令值越界或 `len` 小于对应结构体大小。
`HI_MAPI_VCAP_ENOT_PERM`	`PIPE_BUF_WRAP` 在 `start_dev` 之后再设置。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

是静态配置：PIPE_BUF_WRAP 必须在 start_dev 之前；OB_HEIGHT 必须在 init_sensor 之前。

【举例】无

【相关主题】 hi_mapi_vcap_get_config、hi_mapi_vcap_config_cmd

18 hi_mapi_vcap_get_config

【描述】获取 VCAP 静态配置（缓存值；pipe 已创建后 PIPE_BUF_WRAP 从底层 SDK 读取权威值）。

【语法】

td_s32 hi_mapi_vcap_get_config(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl, hi_mapi_vcap_config_cmd command,
                               td_void *cmd_attr, td_u32 len);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 或 dev 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄（暂未使用，填 0）。
`command`	输入	`hi_mapi_vcap_config_cmd`	静态配置命令，取值范围 `[0, HI_MAPI_VCAP_CONFIG_CMD_BUTT-1]`。
`cmd_attr`	输出	`td_void *`	配置输出缓冲，不能为 `NULL`。
`len`	输入	`td_u32`	输出缓冲大小，必须 `> 0`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	句柄越界。
`HI_MAPI_VCAP_ENULL_PTR`	`cmd_attr` 为 `NULL`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_EILLEGAL_PARA`	命令值越界或 `len` 不足。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

可在 start_dev 之前调用获取缓存值。

【举例】无

【相关主题】 hi_mapi_vcap_set_config

19 hi_mapi_vcap_start_chn

【描述】启动 VCAP 通道：设置通道属性、创建 VB 池并在 VPSS offline 模式下 enable 通道。

【语法】

td_s32 hi_mapi_vcap_start_chn(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值 `[0, 0]`。

【返回值】

返回值	描述
`0`	成功（WDR 模式非主 pipe 直接返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	句柄越界。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建或设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先 start_dev；与 hi_mapi_vcap_stop_chn 配对。

【举例】无

【相关主题】 hi_mapi_vcap_stop_chn

20 hi_mapi_vcap_stop_chn

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

【语法】

td_s32 hi_mapi_vcap_stop_chn(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值 `[0, 0]`。

【返回值】

返回值	描述
`0`	成功（含未启动时幂等返回成功）。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	句柄越界。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化。
`HI_MAPI_VCAP_ENOT_PERM`	pipe 未由 `start_dev` 创建或设备未处于 `RUNNING`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

与 hi_mapi_vcap_start_chn 配对。

【举例】无

【相关主题】 hi_mapi_vcap_start_chn

21 hi_mapi_vcap_get_chn_frame

【描述】从 VCAP 通道获取一帧图像数据。

【语法】

td_s32 hi_mapi_vcap_get_chn_frame(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl,
                                  hi_mapi_frame_data *frame_data);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值 `[0, 0]`。
`frame_data`	输出	`hi_mapi_frame_data *`	输出帧数据，不能为 `NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_ENULL_PTR`	`frame_data` 为 `NULL`。
`HI_MAPI_VCAP_ETIME_OUT`	取帧超时（默认超时 `MAPI_VCAP_GET_CHN_FRAME_TIMEOUT` ms）。
其他错误码	底层取帧失败。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

必须先设置 HI_MAPI_VCAP_CMD_CHN_DEPTH 将 depth 设为 > 0，否则本接口取不到帧。
必须与 hi_mapi_vcap_release_chn_frame 配对，避免 VB 泄漏。

【举例】无

【相关主题】 hi_mapi_vcap_release_chn_frame

22 hi_mapi_vcap_release_chn_frame

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

【语法】

td_s32 hi_mapi_vcap_release_chn_frame(td_handle vcap_pipe_hdl, td_handle pipe_chn_hdl,
                                      const hi_mapi_frame_data *frame_data);

【参数】

参数名称	输入/输出	类型	描述
`vcap_pipe_hdl`	输入	`td_handle`	VCAP pipe 句柄，HI3516CV610 取值范围 `[0, 1]`。
`pipe_chn_hdl`	输入	`td_handle`	pipe 通道句柄，取值 `[0, 0]`。
`frame_data`	输入	`const hi_mapi_frame_data *`	待释放帧数据，不能为 `NULL`。

【返回值】

返回值	描述
`0`	成功。
`非0`	失败，其值为错误码。
`HI_MAPI_VCAP_ENULL_PTR`	`frame_data` 为 `NULL`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

不得重复释放同一帧。

【举例】无

【相关主题】 hi_mapi_vcap_get_chn_frame

23 hi_mapi_vcap_probe_sensor

【描述】 SENSOR0 自动匹配场景下，对预加载的候选 sensor 列表执行 I2C ChipID 探测，返回命中的sensor型号（match_type）。

【语法】

td_s32 hi_mapi_vcap_probe_sensor(td_handle vcap_dev_hdl,
    const hi_mapi_vcap_sensor_attr *bootstrap_attr,
    const hi_mapi_vcap_sensor_candidate *candidates,
    td_u32 candidate_num, td_s32 *match_type, td_bool reset_sensor);

【参数】

参数名称	输入/输出	类型	描述
`vcap_dev_hdl`	输入	`td_handle`	VCAP 设备句柄，取值范围 `[0, 1]`；仅 dev0 支持自动匹配。
`bootstrap_attr`	输入	`const hi_mapi_vcap_sensor_attr *`	初始化的 sensor 基础属性指针，提供探测 power-on 所需参数，不能为 `NULL`。
`candidates`	输入	`const hi_mapi_vcap_sensor_candidate *`	候选 sensor 数组，不能为 `NULL`。
`candidate_num`	输入	`td_u32`	有效候选sensor个数，不能为 `0`。
`match_type`	输出	`td_s32 *`	输出探测结果：命中时写入对应候选的 `match_type`；无匹配或未提供有效候选时返回`-1`；
`reset_sensor`	输入	`td_bool`	sensor 复位标志，决定探测起始状态：填 `TD_TRUE` 用于首次探测或 sensor 供电/复位状态未知的场景，探测从复位后的干净状态开始；填 `TD_FALSE` 仅在确认 sensor 已上电且需保持其当前非复位状态时使用。

hi_mapi_vcap_sensor_candidate 成员：

成员名称	描述
`sensor_attr`	完整候选 sensor 属性（`sensor_obj`/输入属性/分辨率/bayer/combo）。
`probe`	探测候选sensor的配置（I2C 地址、寄存器宽度、ChipID 寄存器与期望值），参见 `hi_mapi_vcap_sensor_probe_cfg`。
`match_type`	业务型号 ID，命中后原样输出到 `*match_type`。

hi_mapi_vcap_sensor_probe_cfg 成员：

成员名称	描述
`enable`	是否参与探测：`TD_TRUE` 探测 ChipID；`TD_FALSE` 跳过（不探测、不匹配）
`dev_addr`	8-bit I2C 从机地址。
`addr_bytes`	寄存器地址宽度（字节），取值 `1`/`2`/`4`。
`data_bytes`	寄存器数据宽度（字节），取值 `1`/`2`/`4`，所有 ChipID 条目共用
`id_num`	需要匹配的sensor寄存器个数
`id_reg[i]`	寄存器地址列表
`id_expect[i]`	寄存器期望值，用作内部检测精准匹配

【返回值】

返回值	描述
`0`	探测成功。
`非0`	探测失败，其值为错误码。
`HI_MAPI_VCAP_EILLEGAL_HANDLE`	`vcap_dev_hdl > 1`。
`HI_MAPI_VCAP_ENULL_PTR`	`bootstrap_attr` 或 `candidates` 为 `NULL`。
`HI_MAPI_VCAP_EILLEGAL_PARA`	`candidate_num == 0`。
`HI_MAPI_VCAP_ENOT_INITED`	媒体未初始化（`hi_mapi_sys_init_media` 未调用）。
`HI_MAPI_VCAP_ENOT_PERM`	执行流程错误，如 VCAP 设备已处于 `RUNNING` 状态，必须先 `stop_dev`。
`HI_MAPI_VCAP_EINVALID_FD`	MIPI 设备节点打开失败。
`HI_MAPI_VCAP_EOPERATE_FAIL`	全部候选均未命中，`*match_type` 由接口显式置为 `-1`。

【需求】

头文件：hi_mapi_vcap.h
库文件：libhi_mapi.so

【注意】

如需开启自动检测sensor，可以在 hi_mapi_vcap_init_sensor 之前调用此接口；命中后将对应候选的 sensor_attr（或按 match_type 回填后的属性）传给 hi_mapi_vcap_init_sensor 完成真实型号初始化。
当前版本仅 dev0 支持自动匹配，dev1 始终使用编译期固定型号。
本接口不能在运行中调用，直接返回失败。
enable == TD_FALSE 的候选sensor不会被探测，也不会被匹配。

【举例】

hi_mapi_vcap_sensor_candidate candidates[MEDIA_SENSOR_MAX_CANDIDATES] = {0};
td_s32 match_type = -1;
td_u32 candidate_num = media_sensor_fill_candidates(&vcap_cfg, 0,
    candidates, MEDIA_SENSOR_MAX_CANDIDATES);   /* 按 SENSOR0_TYPE_LIST 填充候选 */

/* 1. 探测：遍历候选，按各自 probe 配置读 ChipID，命中即返回该候选的 match_type */
td_s32 ret = hi_mapi_vcap_probe_sensor(0, &vcap_cfg.vcap_cam_attr[0].sensor_attr,
    candidates, candidate_num, &match_type, TD_TRUE);
if (ret != TD_SUCCESS || match_type < 0) {
    /* 探测流程失败，或全部候选均未命中（无匹配型号），终止初始化 */
    return TD_FAILURE;
}

/* 2. 回填：把命中的 match_type 对应的该型号 sensor 参数（sensor_obj/bayer/bayer_format/分辨率/input_data_type 等）
 *    覆盖写入 vcap_cfg，此步之后 vcap_cfg 中即为真实型号的参数 */
media_sensor_apply_match(&vcap_cfg, 0, (media_sensor_type)match_type);

/* 3. 初始化：sensor_attr 已被回填为真实型号属性，按首次初始化执行 */
ret = hi_mapi_vcap_init_sensor(0, &vcap_cfg.vcap_cam_attr[0].sensor_attr, TD_TRUE);

【相关主题】 hi_mapi_vcap_init_sensor

4 数据类型

1 hi_mapi_vcap_sensor_attr

【说明】描述 sensor 的综合属性，包含 sensor 模式、WDR、分辨率、输入设备属性、sensor 设备属性与组合设备属性，作为 hi_mapi_vcap_init_sensor 的入参。

【定义】

typedef struct {
    td_u32                       sns_mode;
    hi_mapi_vcap_wdr_mode        wdr_mode;
    hi_mapi_size                 size;
    hi_mapi_vcap_input_dev_attr  input_dev_attr;
    hi_mapi_vcap_sensor_dev_attr sns_dev_attr;
    hi_mapi_vcap_combo_dev_attr  combo_dev_attr;
} hi_mapi_vcap_sensor_attr;

【成员】

成员名称	描述
`sns_mode`	sensor 工作模式索引，与具体 sensor 驱动相关。
`wdr_mode`	WDR 模式，参见 `hi_mapi_vcap_wdr_mode`（`WDR_MODE_NONE` / `BUILT_IN` / `QUDRA` / `2To1_LINE` / `2To1_FRAME` 等）。
`size`	sensor 输出分辨率（宽 × 高，单位像素）。
`input_dev_attr`	设备输入属性，参见 `hi_mapi_vcap_input_dev_attr`。
`sns_dev_attr`	sensor 自身属性，参见 `hi_mapi_vcap_sensor_dev_attr`。
`combo_dev_attr`	组合设备属性（MIPI lane 分配、时钟/复位源、总线号），参见 `hi_mapi_vcap_combo_dev_attr`。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_input_dev_attr、hi_mapi_vcap_sensor_dev_attr、hi_mapi_vcap_combo_dev_attr、hi_mapi_vcap_wdr_mode；hi_mapi_vcap_init_sensor。

2 hi_mapi_vcap_input_dev_attr

【说明】描述 VCAP 设备的输入属性（输入模式、数据类型、是否使用 serdes 设备）。

【定义】

typedef struct {
    hi_mapi_vcap_input_mode     input_mode;
    hi_mapi_vcap_input_datatype input_data_type;
    td_bool                     use_serdes_dev;
} hi_mapi_vcap_input_dev_attr;

【成员】

成员名称	描述
`input_mode`	输入模式，参见 `hi_mapi_vcap_input_mode`（`INPUT_MODE_MIPI` / `SUBLVDS` / `LVDS` / `HISPI`）。
`input_data_type`	输入数据类型，参见 `hi_mapi_vcap_input_datatype`（`RAW_8BIT` / `RAW_10BIT` / `RAW_12BIT` / `RAW_14BIT` / `RAW_16BIT` / `YUV420_8BIT_NORMAL` / `YUV420_8BIT_LEGACY` / `YUV422_8BIT` / `YUV422_PACKED`）。
`use_serdes_dev`	是否使用 serdes 设备，`HI_TRUE` 使用 / `HI_FALSE` 不使用。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_input_mode、hi_mapi_vcap_input_datatype；hi_mapi_vcap_sensor_attr。

3 hi_mapi_vcap_sensor_dev_attr

【说明】描述 sensor 自身属性，包含 sensor 对象指针、MIPI 数据速率、输入属性、lane 分配。

【定义】

typedef struct {
    td_void                     *sensor_obj;
    hi_mapi_vcap_mipi_data_rate data_rate;
    hi_mapi_vcap_sensor_input_attr input_attr;
    td_s16                       lane_id[HI_MAPI_SENSOR_MAX_LANE_NUM];
} hi_mapi_vcap_sensor_dev_attr;

HI_MAPI_SENSOR_MAX_LANE_NUM = 4（CV610）。

【成员】

成员名称	描述
`sensor_obj`	sensor 驱动对象指针，由 sensor 库提供，通常填 `HI_NULL` 由内部解析。
`data_rate`	MIPI 数据速率，参见 `hi_mapi_vcap_mipi_data_rate`（`MIPI_DATA_RATE_X1` = 1 像素/时钟，`MIPI_DATA_RATE_X2` = 2 像素/时钟）。
`input_attr`	sensor 输入属性（bayer 格式、总线类型、设备地址），参见 `hi_mapi_vcap_sensor_input_attr`。
`lane_id[i]`	MIPI lane `i` 的映射 ID，`i ∈ [0, 3]`；`-1` 表示该 lane 未使用。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_sensor_input_attr、hi_mapi_vcap_mipi_data_rate；hi_mapi_vcap_sensor_attr。

4 hi_mapi_vcap_sensor_input_attr

【说明】描述 sensor 的输入属性：bayer 格式、控制总线类型（I2C/SPI）与 sensor 设备地址。

【定义】

typedef struct {
    hi_mapi_vcap_bayer_format       bayer_format;
    hi_mapi_vcap_sensor_comm_bus_type comm_bus_type;
    td_u32                          sensor_dev_addr;
} hi_mapi_vcap_sensor_input_attr;

【成员】

成员名称	描述
`bayer_format`	bayer 排列格式，参见 `hi_mapi_vcap_bayer_format`（`RGGB` / `GRBG` / `GBRG` / `BGGR`）。
`comm_bus_type`	sensor 控制总线类型，参见 `hi_mapi_vcap_sensor_comm_bus_type`（`COMMBUS_TYPE_I2C` / `COMMBUS_TYPE_SPI`）。
`sensor_dev_addr`	sensor 设备地址（I2C 地址或 SPI 片选号）。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_bayer_format、hi_mapi_vcap_sensor_comm_bus_type；hi_mapi_vcap_sensor_dev_attr。

5 hi_mapi_vcap_combo_dev_attr

【说明】描述 VCAP 组合设备（combo dev）属性，包括 MIPI lane 划分模式、sensor 时钟/复位源、总线号。

【定义】

typedef struct {
    hi_mapi_vcap_lane_divide_mode lane_id_mode;
    hi_mapi_sns_clk_source        sns_clk_source;
    hi_mapi_sns_rst_source        sns_rst_source;
    td_s32                        bus_id;
} hi_mapi_vcap_combo_dev_attr;

【成员】

成员名称	描述
`lane_id_mode`	MIPI lane 划分模式，参见 `hi_mapi_vcap_lane_divide_mode`（`LANE_DIVIDE_MODE_0` = 4lane、`LANE_DIVIDE_MODE_1` = 2lane + 2lane）。
`sns_clk_source`	sensor 时钟源编号，类型 `unsigned int`。
`sns_rst_source`	sensor 复位源编号，类型 `unsigned int`。
`bus_id`	控制总线号（I2C bus 索引）。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_lane_divide_mode；hi_mapi_vcap_sensor_attr。

6 hi_mapi_vcap_attr

【说明】描述 VCAP 设备的综合属性，包含设备属性、绑定的 pipe 数量、各 pipe ID 及各 pipe 的属性。

【定义】

typedef struct {
    hi_mapi_vcap_dev_attr  vcap_dev_attr;
    td_u32                 pipe_bind_num;
    td_handle              pipe_id_bind[HI_MAPI_VCAP_MAX_PIPE_NUM];
    hi_mapi_vcap_pipe_attr vcap_pipe_attr[HI_MAPI_VCAP_MAX_PIPE_NUM];
} hi_mapi_vcap_attr;

HI_MAPI_VCAP_MAX_PIPE_NUM = 2（CV610）。

【成员】

成员名称	描述
`vcap_dev_attr`	VCAP 设备属性（WDR 模式、接口模式、数据顺序、数据类型），参见 `hi_mapi_vcap_dev_attr`。
`pipe_bind_num`	绑定到该 VCAP 设备的 pipe 数量，范围 `[1, 2]`。
`pipe_id_bind[i]`	绑定到该设备的第 `i` 个 pipe 的句柄（ID），`i ∈ [0, 1]`。
`vcap_pipe_attr[i]`	第 `i` 个 pipe 的属性，参见 `hi_mapi_vcap_pipe_attr`。

【注意事项】

pipe_bind_num 必须与 pipe_id_bind 中实际填写的有效句柄数量一致。

【相关数据类型及接口】 hi_mapi_vcap_dev_attr、hi_mapi_vcap_pipe_attr；hi_mapi_vcap_set_attr、hi_mapi_vcap_get_attr。

7 hi_mapi_vcap_dev_attr

【说明】描述 VCAP 设备的静态属性：WDR 模式、接口模式、YUV 数据顺序、数据类型。

【定义】

typedef struct {
    hi_mapi_vcap_wdr_mode     wdr_mode;
    hi_mapi_vcap_intf_mode    intf_mode;
    hi_mapi_yuv_data_seq      data_seq;
    hi_mapi_vcap_data_type    data_type;
} hi_mapi_vcap_dev_attr;

【成员】

成员名称	描述
`wdr_mode`	WDR 模式，参见 `hi_mapi_vcap_wdr_mode`。
`intf_mode`	接口模式，参见 `hi_mapi_vcap_intf_mode`（`MODE_BT656` / `BT601` / `DIGITAL_CAMERA` / `BT1120` / `MIPI` / `MIPI_YUV420_NORM` / `MIPI_YUV420_LEGACY` / `MIPI_YUV422` / `INTF_MODE_THERMO`）。
`data_seq`	YUV 数据顺序（仅在 YUV 输入格式下有效），参见 `hi_mapi_yuv_data_seq`（`DATA_SEQ_VUVU` / `UVUV` / `UYVY` / `VYUY` / `YUYV` / `YVYU`）。
`data_type`	数据类型，参见 `hi_mapi_vcap_data_type`（`DATA_TYPE_YUV` / `DATA_TYPE_RGB`）。

【注意事项】

data_seq 仅在 intf_mode 为 YUV 类模式时有意义。

【相关数据类型及接口】 hi_mapi_vcap_wdr_mode、hi_mapi_vcap_intf_mode、hi_mapi_yuv_data_seq、hi_mapi_vcap_data_type；hi_mapi_vcap_attr。

8 hi_mapi_vcap_pipe_attr

【说明】描述 VCAP pipe 的属性，包含 pipe 类型、帧率控制、ISP 公共属性、VB 池块数及各通道属性。

【定义】

typedef struct {
    hi_mapi_vcap_pipe_type      pipe_type;
    hi_mapi_frame_rate_ctrl     frame_rate_ctrl;
    hi_mapi_vcap_pipe_isp_attr  isp_pub_attr;
    td_u32                      vb_pool_blk_cnt;
    td_bool                     nr_enable;
    hi_mapi_vcap_3dnr_attr      nr_attr;
    hi_mapi_vcap_pipe_chn_attr  pipe_chn_attr[HI_MAPI_VCAP_PIPE_MAX_CHN_NUM];
} hi_mapi_vcap_pipe_attr;

HI_MAPI_VCAP_PIPE_MAX_CHN_NUM = 1（CV610 上每个 pipe 只有 1 个通道）。

【成员】

成员名称	描述
`pipe_type`	pipe 类型（静态属性），参见 `hi_mapi_vcap_pipe_type`（`PIPE_TYPE_VIDEO` / `PIPE_TYPE_SNAP`）。
`frame_rate_ctrl`	帧率控制（动态属性），包含 `src_frame_rate` 与 `dst_frame_rate`，单位 fps。
`isp_pub_attr`	ISP 公共属性（帧率、分辨率、bayer 格式、sensor 镜像翻转），参见 `hi_mapi_vcap_pipe_isp_attr`。
`vb_pool_blk_cnt`	该 pipe 的 VB 池块数。
`nr_enable`	3DNR 使能开关。
`nr_attr`	3DNR 属性，参见 `hi_mapi_vcap_3dnr_attr`。
`pipe_chn_attr[i]`	第 `i` 个 pipe 通道的属性，`i ∈ [0, 0]`（CV610 仅 1 个通道），参见 `hi_mapi_vcap_pipe_chn_attr`。

【注意事项】

pipe_type 为静态属性，pipe 创建后不可修改。
frame_rate_ctrl 为动态属性，运行中可调整。

【相关数据类型及接口】 hi_mapi_vcap_pipe_type、hi_mapi_frame_rate_ctrl、hi_mapi_vcap_pipe_isp_attr、hi_mapi_vcap_pipe_chn_attr；hi_mapi_vcap_attr。

9 hi_mapi_vcap_pipe_chn_attr

【说明】描述 VCAP pipe 通道的属性：输出分辨率、帧率控制、像素格式、视频格式、VB 池块数。

【定义】

typedef struct {
    hi_mapi_size            dest_size;
    hi_mapi_frame_rate_ctrl frame_rate_ctrl;
    hi_mapi_pixel_format    pixel_format;
    hi_mapi_video_format    video_format;
    td_u32                  vb_pool_blk_cnt;
} hi_mapi_vcap_pipe_chn_attr;

【成员】

成员名称	描述
`dest_size`	通道输出分辨率（宽 × 高，单位像素），动态属性；使用 GDC 时不可动态修改。
`frame_rate_ctrl`	通道帧率控制，动态属性，包含 `src_frame_rate` 与 `dst_frame_rate`。
`pixel_format`	像素格式（静态属性），参见 `hi_mapi_pixel_format`，取值范围 `[8bit, 16bit]`。
`video_format`	视频格式，参见 `hi_mapi_video_format`。
`vb_pool_blk_cnt`	该通道的 VB 池块数。

【注意事项】无

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

10 hi_mapi_vcap_pipe_isp_attr

【说明】描述 ISP 公共属性：帧率、sensor 输出分辨率、bayer 格式、sensor 镜像翻转类型。

【定义】

typedef struct {
    td_float                             frame_rate;
    hi_mapi_size                         size;
    hi_mapi_vcap_isp_bayer_format        bayer;
    hi_mapi_vcap_isp_sns_mirror_flip_type sns_mirror_flip;
} hi_mapi_vcap_pipe_isp_attr;

【成员】

成员名称	描述
`frame_rate`	ISP 处理帧率，单位 fps。
`size`	sensor 输出分辨率（宽 × 高，单位像素）。
`bayer`	bayer 排列格式，参见 `hi_mapi_vcap_isp_bayer_format`（`BAYER_RGGB` / `GRBG` / `GBRG` / `BGGR`）。
`sns_mirror_flip`	sensor 镜像/翻转类型，参见 `hi_mapi_vcap_isp_sns_mirror_flip_type`（`SNS_NORMAL` / `SNS_MIRROR` / `SNS_FLIP` / `SNS_MIRROR_FLIP`）。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_isp_bayer_format、hi_mapi_vcap_isp_sns_mirror_flip_type；hi_mapi_vcap_pipe_attr。

11 hi_mapi_vcap_cmd

【说明】描述 VCAP 动态扩展命令枚举，用于 hi_mapi_vcap_set_param / hi_mapi_vcap_get_param 中分派到具体处理函数。

【定义】

href="#__codelineno-36-1">typedef enum { HI_MAPI_VCAP_CMD_ISP_EXPOURSEATTR, HI_MAPI_VCAP_CMD_ISP_METERINGMODE, HI_MAPI_VCAP_CMD_ISP_WBATTR, HI_MAPI_VCAP_CMD_ISP_SHARPEN, HI_MAPI_VCAP_CMD_ISP_LUMA, HI_MAPI_VCAP_CMD_ISP_SATURATION, HI_MAPI_VCAP_CMD_ISP_CAC, HI_MAPI_VCAP_CMD_ISP_DNGCOLORPARAM, HI_MAPI_VCAP_CMD_ISP_PIPEDIFFATTR, HI_MAPI_VCAP_CMD_ISP_WDR, HI_MAPI_VCAP_CMD_ISP_CONTRAST, HI_MAPI_VCAP_CMD_ISP_GET_DNGIMAGESTATICINFO, HI_MAPI_VCAP_CMD_ISP_GET_EXPOURSEINFO, HI_MAPI_VCAP_CMD_ISP_GET_AWBINFO, HI_MAPI_VCAP_CMD_ISP_GET_PUBINFO, HI_MAPI_VCAP_CMD_ISP_SET_3AINIT, HI_MAPI_VCAP_CMD_ISP_SET_AEDEBUG, HI_MAPI_VCAP_CMD_ISP_SET_AWBDEBUG, HI_MAPI_VCAP_CMD_LDC, HI_MAPI_VCAP_CMD_ROTATE, HI_MAPI_VCAP_CMD_MIRRORFLIP, HI_MAPI_VCAP_CMD_PIPE_GETCMPPARAM, HI_MAPI_VCAP_CMD_ENTER_STANDBY, HI_MAPI_VCAP_CMD_EXIT_STANDBY, HI_MAPI_VCAP_CMD_RESTART_SENSOR, HI_MAPI_VCAP_CMD_LDCV2, HI_MAPI_VCAP_CMD_LDCV3, HI_MAPI_VCAP_CMD_LDCV4, HI_MAPI_VCAP_CMD_CHN_DEPTH, HI_MAPI_VCAP_CMD_PIPE_LOW_DELAY, HI_MAPI_VCAP_CMD_CHN_LOW_DELAY, HI_MAPI_VCAP_CMD_PIPE_3DNR, HI_MAPI_VCAP_CMD_BUTT class="w"> hi_mapi_vcap_cmd;

【成员】

成员名称	描述
`HI_MAPI_VCAP_CMD_ISP_EXPOURSEATTR`	ISP 曝光属性，`cmd_attr` 为 `hi_mapi_vcap_exposure_attr`。
`HI_MAPI_VCAP_CMD_ISP_METERINGMODE`	ISP 测光模式，`cmd_attr` 为 `hi_mapi_vcap_metering_mode`。
`HI_MAPI_VCAP_CMD_ISP_WBATTR`	ISP 白平衡属性，`cmd_attr` 为 `hi_mapi_vcap_wb_attr`。
`HI_MAPI_VCAP_CMD_ISP_SHARPEN`	ISP 锐化属性，`cmd_attr` 为 `hi_mapi_vcap_sharpen`。
`HI_MAPI_VCAP_CMD_ISP_LUMA`	ISP 亮度，`cmd_attr` 为 `hi_mapi_vcap_luma`。
`HI_MAPI_VCAP_CMD_ISP_SATURATION`	ISP 饱和度，`cmd_attr` 为 `hi_mapi_vcap_saturation`。
`HI_MAPI_VCAP_CMD_ISP_CAC`	ISP 紫边矫正。
`HI_MAPI_VCAP_CMD_ISP_DNGCOLORPARAM`	ISP DNG 颜色参数。
`HI_MAPI_VCAP_CMD_ISP_PIPEDIFFATTR`	ISP 多 pipe 拼接差异属性。
`HI_MAPI_VCAP_CMD_ISP_WDR`	ISP WDR 属性（合成方法及其参数）。
`HI_MAPI_VCAP_CMD_ISP_CONTRAST`	ISP 对比度，`cmd_attr` 为 `hi_mapi_vcap_contrast`。
`HI_MAPI_VCAP_CMD_ISP_GET_DNGIMAGESTATICINFO`	获取 DNG 图像静态信息（只读）。
`HI_MAPI_VCAP_CMD_ISP_GET_EXPOURSEINFO`	查询 AE 曝光信息（只读）。
`HI_MAPI_VCAP_CMD_ISP_GET_AWBINFO`	查询 AWB 信息（只读）。
`HI_MAPI_VCAP_CMD_ISP_GET_PUBINFO`	获取 ISP 公共属性（只读）。
`HI_MAPI_VCAP_CMD_ISP_SET_3AINIT`	已弃用，请改用 `HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT`。
`HI_MAPI_VCAP_CMD_ISP_SET_AEDEBUG`	设置 AE 调试信息。
`HI_MAPI_VCAP_CMD_ISP_SET_AWBDEBUG`	设置 AWB 调试信息。
`HI_MAPI_VCAP_CMD_LDC`	通道 LDC 鱼眼矫正（v1），`cmd_attr` 为 `hi_mapi_vcap_ldc_attr`。
`HI_MAPI_VCAP_CMD_ROTATE`	通道旋转，`cmd_attr` 为 `hi_mapi_rotation`。
`HI_MAPI_VCAP_CMD_MIRRORFLIP`	通道镜像/翻转，`cmd_attr` 为 `hi_mapi_vcap_mirror_flip_attr`。
`HI_MAPI_VCAP_CMD_PIPE_GETCMPPARAM`	pipe 压缩参数（只读）。
`HI_MAPI_VCAP_CMD_ENTER_STANDBY`	sensor 进入待机模式。
`HI_MAPI_VCAP_CMD_EXIT_STANDBY`	sensor 退出待机模式。
`HI_MAPI_VCAP_CMD_RESTART_SENSOR`	sensor 重启。
`HI_MAPI_VCAP_CMD_LDCV2`	通道 LDCv2 鱼眼矫正。
`HI_MAPI_VCAP_CMD_LDCV3`	通道 LDCv3 鱼眼矫正。
`HI_MAPI_VCAP_CMD_LDCV4`	通道 LDCv4 鱼眼矫正（CV610 对应 MPP 中的 ldcv3）。
`HI_MAPI_VCAP_CMD_CHN_DEPTH`	通道用户帧队列深度，`cmd_attr` 为 `hi_mapi_vcap_chn_depth`。
`HI_MAPI_VCAP_CMD_PIPE_LOW_DELAY`	pipe 低延时属性，`cmd_attr` 为 `hi_mapi_vcap_low_delay_info`。
`HI_MAPI_VCAP_CMD_CHN_LOW_DELAY`	通道低延时属性，`cmd_attr` 为 `hi_mapi_vcap_low_delay_info`。
`HI_MAPI_VCAP_CMD_PIPE_3DNR`	pipe 3DNR 属性，`cmd_attr` 为 `hi_mapi_vcap_3dnr_attr`。
`HI_MAPI_VCAP_CMD_BUTT`	哨兵值，不可使用。

【注意事项】

HI_MAPI_VCAP_CMD_ISP_SET_3AINIT 已弃用，请在 hi_mapi_vcap_set_config 中使用 HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT。

【相关数据类型及接口】 hi_mapi_vcap_exposure_attr、hi_mapi_vcap_wb_attr、hi_mapi_vcap_sharpen、hi_mapi_vcap_luma、hi_mapi_vcap_saturation、hi_mapi_vcap_contrast、hi_mapi_vcap_metering_mode、hi_mapi_vcap_mirror_flip_attr、hi_mapi_vcap_chn_depth、hi_mapi_vcap_low_delay_info；hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

12 hi_mapi_vcap_config_cmd

【说明】描述 VCAP 静态配置命令枚举，用于 hi_mapi_vcap_set_config / hi_mapi_vcap_get_config 中分派到具体处理函数；配置必须在启动前生效。

【定义】

typedef enum {
    HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT,
    HI_MAPI_VCAP_CONFIG_CMD_OB_HEIGHT,
    HI_MAPI_VCAP_CONFIG_CMD_PIPE_BUF_WRAP,
    HI_MAPI_VCAP_CONFIG_CMD_BUTT
} hi_mapi_vcap_config_cmd;

【成员】

成员名称	描述
`HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT`	ISP AE/AWB 初始化属性，`cmd_attr` 为 `hi_mapi_vcap_isp_init_attr`；在 `init_isp`（ISP 内存初始化前）时消费。
`HI_MAPI_VCAP_CONFIG_CMD_OB_HEIGHT`	sensor OB 行数配置，`cmd_attr` 为 `hi_mapi_vcap_ob_height_cfg`；handle 为 dev/sensor（1:1）。
`HI_MAPI_VCAP_CONFIG_CMD_PIPE_BUF_WRAP`	VI pipe 卷绕开关，`cmd_attr` 为 `hi_mapi_vcap_buf_wrap_attr`；必须在 `start_dev` 前设置，仅 offline 模式有效。
`HI_MAPI_VCAP_CONFIG_CMD_BUTT`	哨兵值，不可使用。

【注意事项】

所有静态配置必须在相应模块启动前完成设置。

【相关数据类型及接口】 hi_mapi_vcap_isp_init_attr、hi_mapi_vcap_ob_height_cfg、hi_mapi_vcap_buf_wrap_attr；hi_mapi_vcap_set_config、hi_mapi_vcap_get_config。

13 hi_mapi_vcap_exposure_attr

【说明】描述 ISP 曝光属性，包含操作类型与手动/自动曝光模式。

【定义】

typedef struct {
    hi_mapi_vcap_op_type             op_type;
    hi_mapi_vcap_exposure_manual_mode manu_exposure_mode;
    hi_mapi_vcap_exposure_auto_mode  auto_exposure_mode;
} hi_mapi_vcap_exposure_attr;

其中子类型定义为：

typedef struct {
    hi_mapi_vcap_op_type exp_time_op_type;
    hi_mapi_vcap_op_type a_gain_op_type;
    hi_mapi_vcap_op_type d_gain_op_type;
    hi_mapi_vcap_op_type isp_dgain_op_type;
    td_u32               exposure_time;
    td_u32               a_gain;
    td_u32               d_gain;
    td_u32               isp_dgain;
} hi_mapi_vcap_exposure_manual_mode;

typedef struct {
    td_u32                 ev_bias;
    hi_mapi_vcap_ae_range  sys_gain_range;
} hi_mapi_vcap_exposure_auto_mode;

typedef struct {
    td_u32 min;
    td_u32 max;
} hi_mapi_vcap_ae_range;

【成员】

成员名称	描述
`op_type`	曝光操作类型，参见 `hi_mapi_vcap_op_type`（`OP_TYPE_AUTO` / `OP_TYPE_MANUAL` / `OP_TYPE_DISABLE`）。
`manu_exposure_mode`	手动曝光模式参数（仅 `op_type = OP_TYPE_MANUAL` 时生效）。
`manu_exposure_mode.exp_time_op_type`	曝光时间操作类型。
`manu_exposure_mode.a_gain_op_type`	模拟增益操作类型。
`manu_exposure_mode.d_gain_op_type`	数字增益（sensor 侧）操作类型。
`manu_exposure_mode.isp_dgain_op_type`	ISP 数字增益操作类型。
`manu_exposure_mode.exposure_time`	手动曝光时间值。
`manu_exposure_mode.a_gain`	手动模拟增益值。
`manu_exposure_mode.d_gain`	手动数字增益值。
`manu_exposure_mode.isp_dgain`	手动 ISP 数字增益值。
`auto_exposure_mode`	自动曝光模式参数（仅 `op_type = OP_TYPE_AUTO` 时生效）。
`auto_exposure_mode.ev_bias`	曝光补偿，取值范围 `[0, 0xFFFF]`。
`auto_exposure_mode.sys_gain_range`	ISO 增益范围（`min`、`max`）。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_op_type；HI_MAPI_VCAP_CMD_ISP_EXPOURSEATTR、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

14 hi_mapi_vcap_wb_attr

【说明】描述 ISP 白平衡属性，包含操作类型与手动白平衡模式（色温）。

【定义】

typedef struct {
    hi_mapi_vcap_op_type      op_type;
    hi_mapi_vcap_wb_manual_mode wb_mode;
} hi_mapi_vcap_wb_attr;

其中子类型定义为：

typedef struct {
    td_u32 color_temp;
} hi_mapi_vcap_wb_manual_mode;

【成员】

成员名称	描述
`op_type`	白平衡操作类型，参见 `hi_mapi_vcap_op_type`（`OP_TYPE_AUTO` / `OP_TYPE_MANUAL`）。
`wb_mode.color_temp`	手动色温值，单位 Kelvin，取值范围 `[1500, 15000]`。

【注意事项】无

【相关数据类型及接口】 hi_mapi_vcap_op_type；HI_MAPI_VCAP_CMD_ISP_WBATTR、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

15 hi_mapi_vcap_sharpen

【说明】描述 ISP 锐化属性，包含使能开关、运动锐化开关、操作类型、细节映射模式及手动/自动锐化参数。

【定义】

typedef struct {
    td_bool                         enable;
    td_bool                         motion_enable;
    td_u8                           motion_threshold0;
    td_u8                           motion_threshold1;
    td_u16                          motion_gain0;
    td_u16                          motion_gain1;
    td_u8                           skin_umin;
    td_u8                           skin_vmin;
    td_u8                           skin_umax;
    td_u8                           skin_vmax;
    hi_mapi_vcap_op_type            op_type;
    hi_mapi_vcap_sharpen_detail_map detail_map;
    hi_mapi_vcap_sharp_manual_attr  manual_attr;
    hi_mapi_vcap_sharp_auto_attr    auto_attr;
} hi_mapi_vcap_sharpen;

自动模式数组维度：HI_MAPI_VCAP_ISP_AUTO_ISO_NUM = 16、HI_MAPI_VCAP_ISP_SHARPEN_LUMA_NUM = 32、HI_MAPI_VCAP_ISP_SHARPEN_GAIN_NUM = 32。

【成员】

成员名称	描述
`enable`	锐化总开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。
`motion_enable`	运动锐化开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。
`motion_threshold0`	运动阈值 0。
`motion_threshold1`	运动阈值 1。
`motion_gain0`	运动增益 0。
`motion_gain1`	运动增益 1。
`skin_umin` / `skin_vmin` / `skin_umax` / `skin_vmax`	皮肤区域 UV 范围。
`op_type`	操作类型，参见 `hi_mapi_vcap_op_type`（`OP_TYPE_AUTO` / `OP_TYPE_MANUAL` / `OP_TYPE_DISABLE`）。
`detail_map`	细节映射模式，参见 `hi_mapi_vcap_sharpen_detail_map`（`NORMAL` / `DETAIL` / `OFF` / `DIFF_NORM` / `DIFF` / `TOTAL` / `TEXTURE` / `EDGE` 等）。
`manual_attr`	手动锐化参数，类型为 `hi_mapi_vcap_sharp_manual_attr`；含 `luma_wgt[32]`、`texture_strength[32]`、`edge_strength[32]`、`texture_freq`、`edge_freq`、`over_shoot`、`under_shoot` 以及运动 / 去毛刺 / 边缘滤波 / 颜色增益等多个字段。
`auto_attr`	自动锐化参数，类型为 `hi_mapi_vcap_sharp_auto_attr`；各字段按 ISO 分档（16 档）。

【注意事项】

manual_attr / auto_attr 仅在 op_type = OP_TYPE_MANUAL / OP_TYPE_AUTO 时生效。

【相关数据类型及接口】 hi_mapi_vcap_sharp_manual_attr、hi_mapi_vcap_sharp_auto_attr、hi_mapi_vcap_sharpen_detail_map；HI_MAPI_VCAP_CMD_ISP_SHARPEN、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

16 hi_mapi_vcap_luma

【说明】描述 ISP 亮度属性。

【定义】

typedef struct {
    td_u8 luma;
} hi_mapi_vcap_luma;

【成员】

成员名称	描述
`luma`	亮度值，取值范围 `[0, 100]`。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_ISP_LUMA、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

17 hi_mapi_vcap_saturation

【说明】描述 ISP 饱和度属性。

【定义】

typedef struct {
    td_u8 saturation;
} hi_mapi_vcap_saturation;

【成员】

成员名称	描述
`saturation`	饱和度值，取值范围 `[0, 100]`。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_ISP_SATURATION、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

18 hi_mapi_vcap_contrast

【说明】描述 ISP 对比度属性。

【定义】

typedef struct {
    td_u8 contrast;
} hi_mapi_vcap_contrast;

【成员】

成员名称	描述
`contrast`	对比度值，取值范围 `[0, 100]`。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_ISP_CONTRAST、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

19 hi_mapi_vcap_metering_mode

【说明】描述 ISP 测光模式权重表，按 AE 分区（15 行 × 17 列）指定各区域权重。

【定义】

typedef struct {
    td_u8 weight[HI_MAPI_VCAP_AE_ZONE_ROW][HI_MAPI_VCAP_AE_ZONE_COLUMN];
} hi_mapi_vcap_metering_mode;

HI_MAPI_VCAP_AE_ZONE_ROW = 15、HI_MAPI_VCAP_AE_ZONE_COLUMN = 17（CV610）。

【成员】

成员名称	描述
`weight[r][c]`	第 `r` 行第 `c` 列 AE 分区权重，`r ∈ [0, 14]`、`c ∈ [0, 16]`；取值范围 `[0x0, 0xF]`，格式 4.0。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_ISP_METERINGMODE、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

20 hi_mapi_vcap_mirror_flip_attr

【说明】描述 VCAP 通道的镜像与翻转属性。

【定义】

typedef struct {
    td_bool mirror;
    td_bool flip;
} hi_mapi_vcap_mirror_flip_attr;

【成员】

成员名称	描述
`mirror`	水平镜像开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。
`flip`	垂直翻转开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_MIRRORFLIP、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

21 hi_mapi_vcap_chn_depth

【说明】描述 VCAP 通道用户帧队列深度。

【定义】

typedef struct {
    td_u32 depth;
} hi_mapi_vcap_chn_depth;

【成员】

成员名称	描述
`depth`	用户帧队列深度，取值范围 `[0, 8]`；`depth > 0` 后 `hi_mapi_vcap_get_chn_frame` 才能返回帧。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_CHN_DEPTH、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param、hi_mapi_vcap_get_chn_frame。

22 hi_mapi_vcap_low_delay_info

【说明】描述 VCAP pipe / 通道的低延时属性。

【定义】

typedef struct {
    td_bool enable;
    td_u32  line_cnt;
    td_bool one_buf_en;
} hi_mapi_vcap_low_delay_info;

【成员】

成员名称	描述
`enable`	低延时开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。
`line_cnt`	低延时 shoreline 行数，取值范围 `[16, 8192]`。
`one_buf_en`	低延时单 buffer 开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CMD_PIPE_LOW_DELAY、HI_MAPI_VCAP_CMD_CHN_LOW_DELAY、hi_mapi_vcap_set_param、hi_mapi_vcap_get_param。

23 hi_mapi_vcap_isp_init_attr

【说明】描述 ISP 3A（AE/AWB/AF）初始化属性，作为 HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT 的 cmd_attr，在 init_isp 之前配置。

【定义】

typedef struct {
    td_bool is_ir_mode;
    td_u32  exp_time;
    td_u32  a_gain;
    td_u32  d_gain;
    td_u32  isp_dgain;
    td_u32  exposure;
    td_u32  init_iso;
    td_u32  lines_per500ms;
    td_u32  piris_fno;
    td_u16  wb_rgain;
    td_u16  wb_ggain;
    td_u16  wb_bgain;
    td_u16  sample_rgain;
    td_u16  sample_bgain;
    td_u16  ccm[HI_MAPI_VCAP_ISP_CCM_MATRIX_SIZE];
    td_u32  ae_stat_pos;
} hi_mapi_vcap_isp_init_attr;

HI_MAPI_VCAP_ISP_CCM_MATRIX_SIZE = 9。

【成员】

成员名称	描述
`is_ir_mode`	是否红外模式，`HI_TRUE` 启用 / `HI_FALSE` 禁用。
`exp_time`	初始曝光时间。
`a_gain`	初始模拟增益。
`d_gain`	初始数字增益（sensor 侧）。
`isp_dgain`	初始 ISP 数字增益。
`exposure`	初始曝光量。
`init_iso`	初始 ISO。
`lines_per500ms`	每 500ms 行数。
`piris_fno`	光圈 F 值。
`wb_rgain`	白平衡 R 通道增益。
`wb_ggain`	白平衡 G 通道增益。
`wb_bgain`	白平衡 B 通道增益。
`sample_rgain`	采样 R 通道增益。
`sample_bgain`	采样 B 通道增益。
`ccm[i]`	CCM 颜色校正矩阵，`i ∈ [0, 8]`（3×3 矩阵按行优先存储）。
`ae_stat_pos`	AE 统计位置。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CONFIG_CMD_ISP_3AINIT、hi_mapi_vcap_set_config、hi_mapi_vcap_get_config。

24 hi_mapi_vcap_ob_height_cfg

【说明】描述 sensor OB（optical black）行数配置，用于 MIPI RX 高度补偿。

【定义】

typedef struct {
    td_u32 ob_height;
} hi_mapi_vcap_ob_height_cfg;

【成员】

成员名称	描述
`ob_height`	sensor OB 行数，叠加到 MIPI RX 高度；取值范围 `[0, 32]`，默认 `0`。

【注意事项】无

【相关数据类型及接口】 HI_MAPI_VCAP_CONFIG_CMD_OB_HEIGHT、hi_mapi_vcap_set_config、hi_mapi_vcap_get_config。

25 hi_mapi_vcap_buf_wrap_attr

【说明】描述 VI pipe buffer 卷绕（wrap）开关。用户仅配置 enable，buf_line 由内部计算。

【定义】

typedef struct {
    td_bool enable;
} hi_mapi_vcap_buf_wrap_attr;

【成员】

成员名称	描述
`enable`	卷绕开关，`HI_TRUE` 启用 / `HI_FALSE` 禁用。

【注意事项】

仅 offline 模式有效，必须在 hi_mapi_vcap_start_dev 之前设置。

【相关数据类型及接口】 HI_MAPI_VCAP_CONFIG_CMD_PIPE_BUF_WRAP、hi_mapi_vcap_set_config、hi_mapi_vcap_get_config。

5 错误码

模块编号 mod=1，错误码基址 0xA3018000。

错误代码	宏定义	描述
`0xA3018003`	`HI_MAPI_VCAP_EILLEGAL_PARA`	参数非法。
`0xA3018006`	`HI_MAPI_VCAP_ENULL_PTR`	空指针。
`0xA3018008`	`HI_MAPI_VCAP_ENOTSUPPORT`	不支持的操作。
`0xA3018013`	`HI_MAPI_VCAP_EINVALID_FD`	文件描述符无效。
`0xA3018014`	`HI_MAPI_VCAP_EILLEGAL_HANDLE`	句柄非法（设备 / pipe / 通道号越界）。
`0xA3018015`	`HI_MAPI_VCAP_ENOT_INITED`	模块未初始化。