VGS（视频图形系统）接口说明文档

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

---

1 概述

VGS 模块提供硬件加速的图像叠加与绘制能力，包括缩放（scale）、遮盖（cover）、画线（draw line）、OSD 字符叠加以及 Region 管理。所有操作需先通过 hi_mapi_vgs_begin_job 创建作业句柄，然后按序添加各类任务，最后通过 hi_mapi_vgs_end_job 提交整批任务到硬件执行；也可通过 hi_mapi_vgs_cancel_job 放弃本次作业。单次作业最多支持 20 个任务（HI_MAPI_VGS_TASK_MAX_CNT）。

2 接口总览

编号	接口	功能概述
1	hi_mapi_vgs_begin_job	开始一个 VGS 作业，获取作业句柄。
2	hi_mapi_vgs_add_scale_task	向 VGS 作业中添加一个缩放任务（将输入帧按目标尺寸缩放到输出帧）。
3	hi_mapi_vgs_add_cover_task	向 VGS 作业中添加一个遮盖任务（在输出帧上绘制四边形遮盖区域）。
4	hi_mapi_vgs_add_draw_line_task	向 VGS 作业中添加一个画线任务（在输出帧上绘制一条或多条线段）。
5	hi_mapi_vgs_create_rgn	批量创建 VGS OSD Region。Region 句柄从 HI_MAPI_OSD_MAX_CNT（16）开始分配。
6	hi_mapi_vgs_destroy_rgn	销毁所有通过 hi_mapi_vgs_create_rgn 创建的 Region。
7	hi_mapi_vgs_add_osd_task	向 VGS 作业中添加一个 OSD 字符叠加任务（将文本渲染到输出帧上）。
8	hi_mapi_vgs_end_job	提交 VGS 作业到硬件执行。
9	hi_mapi_vgs_cancel_job	取消 VGS 作业，不提交到硬件执行。

3 API 参考

1 hi_mapi_vgs_begin_job

【描述】 开始一个 VGS 作业，获取作业句柄。

【语法】

td_s32 hi_mapi_vgs_begin_job(td_handle *vgs_hdl);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输出	td_handle *	作业句柄输出指针。不可为 NULL。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_ENULL_PTR	vgs_hdl 为 NULL。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】

• 获取到的 vgs_hdl 需传递给后续的 add_*_task 及 end_job / cancel_job。

【举例】无

【相关主题】 hi_mapi_vgs_end_job、hi_mapi_vgs_cancel_job

---

2 hi_mapi_vgs_add_scale_task

【描述】 向 VGS 作业中添加一个缩放任务（将输入帧按目标尺寸缩放到输出帧）。

【语法】

td_s32 hi_mapi_vgs_add_scale_task(td_handle vgs_hdl, const hi_mapi_vgs_scale_task_attr *scale_task_attr);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。
scale_task_attr	输入	const hi_mapi_vgs_scale_task_attr *	缩放任务属性指针。不可为 NULL。

成员名称（hi_mapi_vgs_scale_task_attr）	描述
vgs_task_attr.frame_data_in	输入视频帧。
vgs_task_attr.frame_data_out	输出视频帧（目标尺寸）。
scale_coef_mode	缩放系数模式：NORMAL / TAP2 / TAP4 / TAP6 / TAP8。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENULL_PTR	scale_task_attr 为 NULL。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vgs_begin_job、hi_mapi_vgs_end_job

---

3 hi_mapi_vgs_add_cover_task

【描述】 向 VGS 作业中添加一个遮盖任务（在输出帧上绘制四边形遮盖区域）。

【语法】

td_s32 hi_mapi_vgs_add_cover_task(td_handle vgs_hdl, const hi_mapi_vgs_cover_task_attr *cover_task_attr);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。
cover_task_attr	输入	const hi_mapi_vgs_cover_task_attr *	遮盖任务属性指针。不可为 NULL，其成员 vgs_add_cover 也不可为 NULL。

成员名称（hi_mapi_vgs_cover_task_attr）	描述
vgs_task_attr	输入/输出帧。
vgs_add_cover	遮盖项数组指针。
num	遮盖项数量，范围 [1, 20]。

成员名称（hi_mapi_vgs_add_cover）	描述
quad_rangle	四边形区域（实心或空心，含四个顶点坐标），thick 范围 [2, 8]。
color	颜色值，范围 [0, 0xFFFFFF]（RGB 888）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENULL_PTR	cover_task_attr 或其 vgs_add_cover 成员为 NULL。
HI_MAPI_VGS_EILLEGAL_PARAM	num 超出 [1, 20] 范围。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vgs_begin_job、hi_mapi_vgs_end_job

---

4 hi_mapi_vgs_add_draw_line_task

【描述】 向 VGS 作业中添加一个画线任务（在输出帧上绘制一条或多条线段）。

【语法】

td_s32 hi_mapi_vgs_add_draw_line_task(td_handle vgs_hdl, const hi_mapi_vgs_draw_line_task_attr *draw_line_task_attr);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。
draw_line_task_attr	输入	const hi_mapi_vgs_draw_line_task_attr *	画线任务属性指针。不可为 NULL，其成员 vgs_draw_line 也不可为 NULL。

成员名称（hi_mapi_vgs_draw_line_task_attr）	描述
vgs_task_attr	输入/输出帧。
vgs_draw_line	画线段数组指针。
num	线段数量，范围 [1, 20]。

成员名称（hi_mapi_vgs_draw_line）	描述
start_point	线段起点坐标。
end_point	线段终点坐标。
thick	线宽（像素）。
color	颜色值，范围 [0, 0xFFFFFF]（RGB 888）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENULL_PTR	draw_line_task_attr 或其 vgs_draw_line 成员为 NULL。
HI_MAPI_VGS_EILLEGAL_PARAM	num 超出 [1, 20] 范围。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】 无

【举例】无

【相关主题】 hi_mapi_vgs_begin_job、hi_mapi_vgs_end_job

---

5 hi_mapi_vgs_create_rgn

【描述】 批量创建 VGS OSD Region。Region 句柄从 HI_MAPI_OSD_MAX_CNT（16）开始分配。

【语法】

td_s32 hi_mapi_vgs_create_rgn(const hi_mapi_vgs_rgn_task_attr *rgn_task_attr);

【参数】

参数名称	输入/输出	类型	描述
rgn_task_attr	输入	const hi_mapi_vgs_rgn_task_attr *	Region 创建任务属性指针。不可为 NULL。

成员名称（hi_mapi_vgs_rgn_task_attr）	描述
rgn_attr	Region 属性数组，最多 HI_MAPI_VGS_TASK_MAX_CNT（20）项。
num	要创建的 Region 数量，范围 [1, 20]。

成员名称（hi_mapi_vgs_rgn_attr）	描述
bg_color	Region 背景色。
size	Region 尺寸（W/H 范围 [2, RGN_OVERLAY_MAX_WIDTH/HEIGHT]，2 像素对齐）。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。创建过程中任一项失败会自动回滚（调用 hi_mapi_vgs_destroy_rgn）。
HI_MAPI_VGS_ENULL_PTR	rgn_task_attr 为 NULL。
HI_MAPI_VGS_EILLEGAL_PARAM	num 超出 [1, 20] 范围。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】

• 若某个 Region 创建失败，会自动销毁所有已创建的 Region。
• Region 句柄 = 索引 + HI_MAPI_OSD_MAX_CNT（16），即从 16 开始。

【举例】无

【相关主题】 hi_mapi_vgs_destroy_rgn、hi_mapi_vgs_add_osd_task

---

6 hi_mapi_vgs_destroy_rgn

【描述】 销毁所有通过 hi_mapi_vgs_create_rgn 创建的 Region。

【语法】

td_s32 hi_mapi_vgs_destroy_rgn(td_void);

【参数】 无

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。若某个 Region 销毁失败，会继续销毁其余 Region，最后返回最后一个错误码。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】

• 若没有任何 Region 需要销毁，会打印告警信息并返回成功。

【举例】无

【相关主题】 hi_mapi_vgs_create_rgn

---

7 hi_mapi_vgs_add_osd_task

【描述】 向 VGS 作业中添加一个 OSD 字符叠加任务（将文本渲染到输出帧上）。

【语法】

td_s32 hi_mapi_vgs_add_osd_task(td_handle vgs_hdl, const hi_mapi_vgs_osd_task_attr *osd_task_attr);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。
osd_task_attr	输入	const hi_mapi_vgs_osd_task_attr *	OSD 任务属性指针。不可为 NULL，其成员 vgs_add_osd 也不可为 NULL。

成员名称（hi_mapi_vgs_osd_task_attr）	描述
vgs_task_attr	输入/输出帧。
vgs_add_osd	OSD 项数组指针。
num	OSD 项数量，范围 [1, 20]。

成员名称（hi_mapi_vgs_add_osd）	描述
rgn_hdl	目标 Region 句柄。
start_point	OSD 在帧上的起始坐标。
bg_alpha	背景 alpha，范围 [0, 255]。
fg_alpha	前景 alpha，范围 [0, 255]。
str_content	字符串内容（最大长度 HI_MAPI_MAX_STR_LEN = 64 字节），含字体大小、背景色。
color	字符颜色。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENULL_PTR	osd_task_attr 或其 vgs_add_osd 成员为 NULL。
HI_MAPI_VGS_EILLEGAL_PARAM	num 超出 [1, 20] 范围。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。
HI_MAPI_VGS_ENOFONT	字体模块尚未初始化。

【需求】

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

【注意】

• 必须先通过系统接口完成字体模块初始化，否则返回 HI_MAPI_VGS_ENOFONT。

【举例】无

【相关主题】 hi_mapi_vgs_create_rgn、hi_mapi_vgs_begin_job、hi_mapi_vgs_end_job

---

8 hi_mapi_vgs_end_job

【描述】 提交 VGS 作业到硬件执行。

【语法】

td_s32 hi_mapi_vgs_end_job(td_handle vgs_hdl);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】

• 提交后作业句柄失效，不可再向该作业添加任务。

【举例】无

【相关主题】 hi_mapi_vgs_begin_job、hi_mapi_vgs_cancel_job

---

9 hi_mapi_vgs_cancel_job

【描述】 取消 VGS 作业，不提交到硬件执行。

【语法】

td_s32 hi_mapi_vgs_cancel_job(td_handle vgs_hdl);

【参数】

参数名称	输入/输出	类型	描述
vgs_hdl	输入	td_handle	VGS 作业句柄，不可为 OT_INVALID_HANDLE。

【返回值】

返回值	描述
0	成功。
非0	失败，其值为错误码。
HI_MAPI_VGS_EHANDLE_ILLEGAL	vgs_hdl 为 OT_INVALID_HANDLE。
HI_MAPI_VGS_ENOINITED	media 系统尚未初始化。

【需求】

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

【注意】

• 取消后作业句柄失效。

【举例】无

【相关主题】 hi_mapi_vgs_begin_job、hi_mapi_vgs_end_job

4 数据类型

1 hi_mapi_vgs_scale_coef_mode

【说明】 定义 VGS 缩放任务的插值系数模式，决定缩放时使用的滤波器抽头数。

【定义】

typedef enum {
    HI_MAPI_VGS_SCLCOEF_NORMAL  = 0,
    HI_MAPI_VGS_SCLCOEF_TAP2    = 1,
    HI_MAPI_VGS_SCLCOEF_TAP4    = 2,
    HI_MAPI_VGS_SCLCOEF_TAP6    = 3,
    HI_MAPI_VGS_SCLCOEF_TAP8    = 4,
    HI_MAPI_VGS_SCLCOEF_BUTT
} hi_mapi_vgs_scale_coef_mode;

【成员】

成员名称	描述
HI_MAPI_VGS_SCLCOEF_NORMAL	默认缩放系数（值为 0）。
HI_MAPI_VGS_SCLCOEF_TAP2	2 tap 缩放系数（值为 1）。
HI_MAPI_VGS_SCLCOEF_TAP4	4 tap 缩放系数（值为 2）。
HI_MAPI_VGS_SCLCOEF_TAP6	6 tap 缩放系数（值为 3）。
HI_MAPI_VGS_SCLCOEF_TAP8	8 tap 缩放系数（值为 4）。
HI_MAPI_VGS_SCLCOEF_BUTT	枚举上界哨兵，不可使用。

【注意事项】 tap 数越大，缩放后图像质量越好，但硬件消耗越大。

【相关数据类型及接口】 hi_mapi_vgs_scale_task_attr；hi_mapi_vgs_add_scale_task。

2 hi_mapi_vgs_draw_line

【说明】 定义一条线段的起点、终点、线宽及颜色，用于 VGS 画线任务。

【定义】

typedef struct {
    hi_mapi_point start_point;
    hi_mapi_point end_point;
    td_u32 thick;
    td_u32 color;
} hi_mapi_vgs_draw_line;

【成员】

成员名称	描述
start_point	线段起点坐标（类型 hi_mapi_point）。
end_point	线段终点坐标（类型 hi_mapi_point）。
thick	线宽，单位像素。
color	线段颜色，RGB 888 格式，取值范围 [0, 0xFFFFFF]。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_point、hi_mapi_vgs_draw_line_task_attr；hi_mapi_vgs_add_draw_line_task。

3 hi_mapi_vgs_quadrangle_cover

【说明】 定义四边形遮盖区域的属性，包括实心/空心模式、线宽及四个顶点坐标。

【定义】

typedef struct {
    td_bool is_solid;
    td_u32 thick;
    hi_mapi_point point[HI_MAPI_VGS_QUADRANGLE_POINT_NUM];
} hi_mapi_vgs_quadrangle_cover;

【成员】

成员名称	描述
is_solid	是否为实心遮盖：TD_TRUE 为实心，TD_FALSE 为空心。
thick	空心四边形线宽，取值范围 [2, 8]，单位像素；仅 is_solid 为 TD_FALSE 时有效。
point[4]	四边形四个顶点坐标（HI_MAPI_VGS_QUADRANGLE_POINT_NUM = 4），类型 hi_mapi_point。

【注意事项】

• is_solid 为 TD_FALSE 时，thick 必须落在 [2, 8] 范围内。
• 四个顶点按顺序连线形成四边形。

【相关数据类型及接口】 hi_mapi_point、hi_mapi_vgs_add_cover、hi_mapi_vgs_cover_task_attr；hi_mapi_vgs_add_cover_task。

4 hi_mapi_vgs_task_attr

【说明】 定义 VGS 任务的基础属性，包含输入帧与输出帧数据，是所有 VGS 任务属性的公共基类。

【定义】

typedef struct {
    hi_mapi_frame_data frame_data_in;
    hi_mapi_frame_data frame_data_out;
} hi_mapi_vgs_task_attr;

【成员】

成员名称	描述
frame_data_in	输入视频帧数据（类型 hi_mapi_frame_data，参见公共数据类型）。
frame_data_out	输出视频帧数据（类型 hi_mapi_frame_data）。

【注意事项】

• 输入帧与输出帧可指向同一帧 buffer（原地处理），此时 frame_data_in 与 frame_data_out 的地址字段相同。
• 输出帧须提前由调用方分配或通过 VB 池获取。

【相关数据类型及接口】 hi_mapi_frame_data（公共数据类型）；hi_mapi_vgs_scale_task_attr、hi_mapi_vgs_cover_task_attr、hi_mapi_vgs_draw_line_task_attr、hi_mapi_vgs_osd_task_attr。

5 hi_mapi_vgs_scale_task_attr

【说明】 定义 VGS 缩放任务属性，在基础任务属性上增加缩放系数模式。

【定义】

typedef struct {
    hi_mapi_vgs_task_attr         vgs_task_attr;
    hi_mapi_vgs_scale_coef_mode   scale_coef_mode;
} hi_mapi_vgs_scale_task_attr;

【成员】

成员名称	描述
vgs_task_attr	基础 VGS 任务属性（输入/输出帧）。
scale_coef_mode	缩放系数模式（枚举 hi_mapi_vgs_scale_coef_mode），决定插值滤波器抽头数。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vgs_task_attr、hi_mapi_vgs_scale_coef_mode；hi_mapi_vgs_add_scale_task。

6 hi_mapi_vgs_draw_line_task_attr

【说明】 定义 VGS 画线任务属性，包含基础任务属性、线段数组及线段数量。

【定义】

typedef struct {
    hi_mapi_vgs_task_attr   vgs_task_attr;
    hi_mapi_vgs_draw_line  *vgs_draw_line;
    td_u32                  num;
} hi_mapi_vgs_draw_line_task_attr;

【成员】

成员名称	描述
vgs_task_attr	基础 VGS 任务属性（输入/输出帧）。
vgs_draw_line	指向 hi_mapi_vgs_draw_line 数组的指针，描述每条线段的起点、终点、线宽和颜色。
num	线段数量。

【注意事项】

• vgs_draw_line 不能为 NULL（当 num > 0 时）。
• 线段在输出帧上绘制。

【相关数据类型及接口】 hi_mapi_vgs_task_attr、hi_mapi_vgs_draw_line；hi_mapi_vgs_add_draw_line_task。

7 hi_mapi_vgs_add_cover

【说明】 定义单个遮盖区域，包含四边形遮盖属性与颜色。

【定义】

typedef struct {
    hi_mapi_vgs_quadrangle_cover quad_rangle;
    td_u32                       color;
} hi_mapi_vgs_add_cover;

【成员】

成员名称	描述
quad_rangle	四边形遮盖属性（类型 hi_mapi_vgs_quadrangle_cover），描述实心/空心、线宽及四个顶点。
color	遮盖颜色，RGB 888 格式，取值范围 [0, 0xFFFFFF]。

【注意事项】 无

【相关数据类型及接口】 hi_mapi_vgs_quadrangle_cover、hi_mapi_vgs_cover_task_attr；hi_mapi_vgs_add_cover_task。

8 hi_mapi_vgs_cover_task_attr

【说明】 定义 VGS 遮盖任务属性，包含基础任务属性、遮盖数组及遮盖数量。

【定义】

typedef struct {
    hi_mapi_vgs_task_attr   vgs_task_attr;
    hi_mapi_vgs_add_cover  *vgs_add_cover;
    td_u32                  num;
} hi_mapi_vgs_cover_task_attr;

【成员】

成员名称	描述
vgs_task_attr	基础 VGS 任务属性（输入/输出帧）。
vgs_add_cover	指向 hi_mapi_vgs_add_cover 数组的指针，描述每个遮盖区域。
num	遮盖区域数量。

【注意事项】

• vgs_add_cover 不能为 NULL（当 num > 0 时）。
• 遮盖在输出帧上绘制。

【相关数据类型及接口】 hi_mapi_vgs_task_attr、hi_mapi_vgs_add_cover；hi_mapi_vgs_add_cover_task。

9 hi_mapi_vgs_rgn_attr

【说明】 定义单个 VGS OSD Region 的属性，包括背景颜色与尺寸。

【定义】

typedef struct {
    td_u32       bg_color;
    hi_mapi_size size;
} hi_mapi_vgs_rgn_attr;

【成员】

成员名称	描述
bg_color	Region 背景颜色，RGB 888 格式。
size	Region 尺寸（类型 hi_mapi_size），宽取值范围 [2, 4096]（2 对齐），高取值范围 [2, 4096]（2 对齐）；上限对应 OT_RGN_OVERLAY_MAX_WIDTH / OT_RGN_OVERLAY_MAX_HEIGHT（CV610 均为 4096）。

【注意事项】

• 宽高均须为 2 的倍数。
• 宽高均不得小于 2。

【相关数据类型及接口】 hi_mapi_size（公共数据类型）、hi_mapi_vgs_rgn_task_attr；hi_mapi_vgs_create_rgn。

10 hi_mapi_vgs_rgn_task_attr

【说明】 定义 VGS 批量创建 Region 的任务属性，包含一组 Region 属性及其数量。

【定义】

typedef struct {
    hi_mapi_vgs_rgn_attr rgn_attr[HI_MAPI_VGS_TASK_MAX_CNT];
    td_u32               num;
} hi_mapi_vgs_rgn_task_attr;

【成员】

成员名称	描述
rgn_attr[]	Region 属性数组，数组大小为 HI_MAPI_VGS_TASK_MAX_CNT（20），数组下标对应 Region 句柄索引。
num	本次创建的 Region 数量，取值范围 (0, 20]。

【注意事项】

• num 不得超过 HI_MAPI_VGS_TASK_MAX_CNT（20）。
• 每个 Region 句柄上限 OT_RGN_HANDLE_MAX 为 128（CV610）。

【相关数据类型及接口】 hi_mapi_vgs_rgn_attr；hi_mapi_vgs_create_rgn、hi_mapi_vgs_destroy_rgn。

11 hi_mapi_vgs_add_osd

【说明】 定义单个 OSD 叠加项，包含 Region 句柄、起始位置、前后景透明度、字符串内容及颜色。

【定义】

typedef struct {
    td_u32              rgn_hdl;
    hi_mapi_point       start_point;
    td_u32              bg_alpha;
    td_u32              fg_alpha;
    hi_mapi_str_content str_content;
    td_u32              color;
} hi_mapi_vgs_add_osd;

【成员】

成员名称	描述
rgn_hdl	目标 Region 句柄，须为 hi_mapi_vgs_create_rgn 已创建的句柄。
start_point	OSD 在 Region 中的起始绘制位置（类型 hi_mapi_point）。
bg_alpha	背景透明度，取值范围 [0, 255]，0 为全透明，255 为不透明。
fg_alpha	前景（字符）透明度，取值范围 [0, 255]。
str_content	字符串内容（类型 hi_mapi_str_content，定义于 hi_mapi_comm_define.h），包含字符串文本、字号及背景色。
color	字符颜色，RGB 888 格式。

【注意事项】

• 须先通过 hi_mapi_vgs_create_rgn 创建 Region，再添加 OSD。
• 透明度 0 表示完全透明，255 表示完全不透明。

【相关数据类型及接口】 hi_mapi_point（公共数据类型）、hi_mapi_str_content（hi_mapi_comm_define.h）、hi_mapi_vgs_osd_task_attr；hi_mapi_vgs_add_osd_task、hi_mapi_vgs_create_rgn。

12 hi_mapi_vgs_osd_task_attr

【说明】 定义 VGS OSD 叠加任务属性，包含基础任务属性、OSD 叠加项数组及数量。

【定义】

typedef struct {
    hi_mapi_vgs_task_attr  vgs_task_attr;
    hi_mapi_vgs_add_osd   *vgs_add_osd;
    td_u32                 num;
} hi_mapi_vgs_osd_task_attr;

【成员】

成员名称	描述
vgs_task_attr	基础 VGS 任务属性（输入/输出帧）。
vgs_add_osd	指向 hi_mapi_vgs_add_osd 数组的指针，描述每个 OSD 叠加项。
num	OSD 叠加项数量。

【注意事项】

• vgs_add_osd 不能为 NULL（当 num > 0 时）。
• OSD 在输出帧上绘制。

【相关数据类型及接口】 hi_mapi_vgs_task_attr、hi_mapi_vgs_add_osd；hi_mapi_vgs_add_osd_task。

5 错误码

模块编号 mod=12，错误码基址 0xA30C8000。

错误代码	宏定义	描述
0xA30C8002	HI_MAPI_VGS_EHANDLE_ILLEGAL	通道号无效。
0xA30C8003	HI_MAPI_VGS_EILLEGAL_PARAM	参数非法。
0xA30C8006	HI_MAPI_VGS_ENULL_PTR	空指针。
0xA30C8016	HI_MAPI_VGS_EOPERATE_FAIL	操作失败。
0xA30C8019	HI_MAPI_VGS_ENOFONT	无字体资源。