中文 EN

5.9. 区域处理 - OSD

5.9.1. 模块描述

OSD（ On-Screen Display ）模块是一个重要的图像处理工具，通过配置操作区域 Region，并将 Region 在图像上进行叠加操作，如填色、绘制、马赛克等。其主要应用场景包括：

• 视频图像增强：对实时视频或静态图像叠加特定区域的标注、信息展示。

• 隐私保护：通过叠加马赛克或遮挡区域，对特定区域进行模糊处理或遮盖，保护敏感信息。

因为 OSD 属于 VSE 的辅助功能，所以 OSD 无法单独使用，使用时需要调用 hbn_rgn_attach_to_chn 接口 attach 到 VSE 的输出通道上使用。

5.9.1.1. 基础规格

• OSD 支持填色、绘制点线和文字、马赛克等功能

• 绘制文字支持点阵 16x16 的 HZK16 中文字库 和 点阵 16x8 的 ASC16 英文 字库

• OSD 中叠加 Region 的宽度为 32 的倍数 , 高度为偶数 , 最小 size 为 32x2

• 支持叠加区域数据格式 VGA_8 ， colormap 支持 16 种

• 每个 OSD 支持 8 个面积大小 2x2 到 256x256 直方图统计区域

• VSE 硬件支持 OSD 功能 , 除通道 4 外 , 其他通道均支持 OSD, 最大支持 4 个区域 , 软件 OSD 最多支持 255 个区域

• OSD 使用时需要与 VSE 输出通道绑定，每路 VSE 输出通道对应 OSD 功能支持情况如下：

vse 输出通道编号	硬件 OSD 叠加功能	软件 OSD 叠加功能
0	支持	支持
1	支持	支持
2	支持	支持
3	支持	支持
4	不支持	支持
5	支持	支持

备注： VSE 通道 4 默认采用软件 使用 NEON 指令集 实现 OSD 叠加功能。

1. VSE 的输入通道（ Ichn0 ）的数据源来自两种方式，一种 VFLOW 的方式，另一种是回灌的方式。

2. region buf 通过 hbn_rgn_create 创建，使用 hbn_rgn_attach_to_chn 将创建好的 region buf 绑定到 VSE 的指定通道上。

3. OSD 绑定到 VSE 的指定的输出通道（ Ochnx）以后， OSD 硬件会自动把 region buf 的数据叠加到经过 VSE 的视频帧上。

4. VSE 的输出通道 4 （ Ochn4 ） 不支持 OSD，默认使用 NEON 实现 OSD 叠加功能。

5. VSE 的输出通道超过 4 个 Region 时，超出 4 个 Region 的部分使用软件 NEON 指令集 操作图像数据完成。

5.9.1.2. 注意事项

区域限制： 硬件上每路 VSE 通道最多支持 4 个不重叠的 OSD 区域（即 4 个 Region 在垂直方向上不能互相重叠）。以下是示例图：

左图展示了支持的 OSD 区域叠加方式 ，右图展示了不支持的叠加方式。

OSD 支持的叠加类型如下：

• OVERLAY: 叠加区域 , 可以在矩形区域自行填充内容 , 例如写字画线。

• COVER: 遮挡区域 , 纯色块 , 支持矩形和多边形，不支持圆形。

• MOSAIC: 马赛克区域 , 矩形区域以马赛克形式遮挡。

5.9.2. 参考示例

• OSD 部分示例代码可以参考 sample_osd 章节

5.9.3. API 参考

API 接口	接口功能
hbn_rgn_create	区域创建
hbn_rgn_destroy	区域销毁
hbn_rgn_getattr	获取区域属性
hbn_rgn_setattr	设置区域属性
hbn_rgn_setbitmap	设置区域 buffer
hbn_rgn_attach_to_chn	叠加区域到通道
hbn_rgn_detach_from_chn	解除叠加区域到通道
hbn_rgn_set_displayattr	设置显示属性
hbn_rgn_get_displayattr	获取显示属性
hbn_rgn_draw_word	在 buffer 中写入字符串
hbn_rgn_draw_line	在 buffer 中绘制线条
hbn_rgn_set_colormap	设置 osd 颜色索引对应表
hbn_rgn_get_sta	获取亮度的区域
hbn_rgn_set_sta	设置获取亮度的区域

5.9.3.1. hbn_rgn_create()

【函数声明】

int32_t hbn_rgn_create(hbn_rgn_handle_t handle, const hbn_rgn_attr_t *region)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_rgn_attr_t region： region 区域属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

用于创建一块 region 区域。

【注意事项】

无

5.9.3.2. hbn_rgn_destroy

【函数声明】

int32_t hbn_rgn_destroy(hbn_rgn_handle_t handle)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

用于销毁一块 region 区域。

【注意事项】

无

5.9.3.3. hbn_rgn_getattr

【函数声明】

int32_t hbn_rgn_getattr(hbn_rgn_handle_t handle, hbn_rgn_attr_t *region)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_rgn_attr_t *region： region 区域属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

用于创建区域后，获取一块 region 区域的属性。

【注意事项】

无

5.9.3.4. hbn_rgn_setattr

【函数声明】

int32_t hbn_rgn_setattr(hbn_rgn_handle_t handle, const hbn_rgn_attr_t *region)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_rgn_attr_t *region：区域属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

用于创建区域后，设置一块 region 区域的属性。

【注意事项】

无

5.9.3.5. hbn_rgn_setbitmap

【函数声明】

int32_t hbn_rgn_setbitmap(hbn_rgn_handle_t handle, const hbn_rgn_bitmap_t *bitmap_attr)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_rgn_bitmap_t *bitmap_attr：区域 buffer 属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

在创建好一个 region 区域之后，用户可以自己申请一块 buffer 作画，然后将其设置为该区域的 buffer。

【注意事项】

无

5.9.3.6. hbn_rgn_attach_to_chn

【函数声明】

int32_t hbn_rgn_attach_to_chn(hbn_rgn_handle_t handle,hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_vnode_handle_t vnode_fd：要绑定到的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要绑定到的 VSE 的 channel id。

• [IN] hbn_rgn_chn_attr_t *rgn_chn：区域叠加在通道上的显示属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。。

【功能描述】

用于将创建好的 region 区域叠加到 VSE 的某个通道上。

【注意事项】

VSE 的通道 4 不具备硬件 OSD 功能，会使用软件处理图像的方式。其他通道最多支持 4 个硬件 OSD 的叠加，且叠加时不能重叠，不能硬件处理的部分，由软件实现。

5.9.3.7. hbn_rgn_detach_from_chn

【函数声明】

int32_t hbn_rgn_detach_from_chn(hbn_rgn_handle_t handle,hbn_vnode_handle_t vnode_fd, int32_t chnid)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_vnode_handle_t vnode_fd：要解绑的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要解绑到的 VSE 的 channel id。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

用于将创建好的 region 区域与某个 VSE 通道解绑。

【注意事项】

无

5.9.3.8. hbn_rgn_set_displayattr

【函数声明】

int32_t hbn_rgn_set_displayattr(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_vnode_handle_t vnode_fd：要操作的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要操作的 VSE 的 channel id。

• [IN] hbn_rgn_chn_attr_t *rgn_chn：区域叠加在通道上的显示属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

在将某个 region 区域绑定到通道后，通过该函数去修改设置绑定时的属性。

【注意事项】

无

5.9.3.9. hbn_rgn_get_displayattr

【函数声明】

int32_t hbn_rgn_get_displayattr(hbn_rgn_handle_t handle, hbn_vnode_handle_t vnode_fd, int32_t chnid, const hbn_rgn_chn_attr_t *rgn_chn)

【参数描述】

• [IN] hbn_rgn_handle_t handle： region handle，是 region 的唯一标识，最大值不能超过 255 。

• [IN] hbn_vnode_handle_t vnode_fd：要操作的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要操作的 VSE 的 channel id。

• [IN] hbn_rgn_chn_attr_t *rgn_chn：区域叠加在通道上的显示属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

在将某个 region 区域绑定到通道后，通过该函数去获取绑定时的属性。

【注意事项】

无

5.9.3.10. hbn_rgn_draw_word

【函数声明】

int32_t hbn_rgn_draw_word(const hbn_rgn_draw_word_t *draw_word)

【参数描述】

• [IN] hbn_rgn_draw_word_t *draw_word：画字的属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

在用户申请好的 buffer 上画字，配合 hbn_rgn_setbitmap() 函数，可以将这块 buffer 设置给某个 region 区域。

【注意事项】

无

5.9.3.11. hbn_rgn_draw_line

【函数声明】

int32_t hbn_rgn_draw_line(const hbn_rgn_draw_line_t \*draw_line)

【参数描述】

• [IN] hbn_rgn_draw_line_t *draw_line：画线的属性。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

在用户申请好的 buffer 上画线，配和 hbn_rgn_setbitmap() 函数，可以将这块 buffer 设置给某个 region 区域。

【注意事项】

无

5.9.3.12. hbn_rgn_set_colormap

【函数声明】

int32_t hbn_rgn_set_colormap(uint32_t color_map[16])

【参数描述】

• [IN] uint32_t color_map[16]：要设置的新的 color_map。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

设置新全局的 color_map。 color_map 需要遵循的规则： R 分量在 16-23bit， G 分量在 8-15bit， B 分量在 0-7bit。

【注意事项】

新设置的 color_map 会一直生效，直到重启系统。

5.9.3.13. hbn_rgn_set_sta

【函数声明】

int32_t hbn_rgn_set_sta(hbn_vnode_handle_t vnode_fd, int32_t chnid,uint8_t sta_level[3], hbn_rgn_sta_t sta_attr[8]);

【参数描述】

• [IN] hbn_vnode_handle_t vnode_fd：要操作的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要操作的 VSE 的 channel id。

• [IN] uint8_t sta_level[3]：统计值阈值，需要按照从小到大的顺序配置 3 个参数，参数范围为 1 到 254 。

• [IN] hbn_rgn_sta_t sta_attr[8]：统计值区域的属性，为区域的位置信息。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

设置统计值的 3 个阈值以及最多 8 个区域的位置信息，该区域独立于 region。需要与 hbn_rgn_get_sta() 配合使用。

【注意事项】

每次需要获取统计数据时，都需要调用一次该函数去重新设置。

5.9.3.14. hbn_rgn_get_sta

【函数声明】

int32_t hbn_rgn_get_sta(hbn_vnode_handle_t vnode_fd, int32_t chnid, uint16_t sta_value[8][4])

【参数描述】

• [IN] hbn_vnode_handle_t vnode_fd：要操作的 VSE handle，通过 hbn_vflow_get_vnode_handle() 获取。

• [IN] int32_t chnid：要操作的 VSE 的 channel id。

• [OUT] uint16_t sta_value[8][4]：统计值数据，获取区域使能位置的统计值。

【返回值】

• 成功： HBN_STATUS_SUCESS 0 。

• 失败：异常为负值错误码，参考 返回值说明 。

【功能描述】

获取最多 8 个区域的统计数据，该数据以亮度直方图的形式输出，配和设置的 3 个阈值，输出 4 个区间的像素个数。

【注意事项】

无。

5.9.4. 参数说明

typedef enum hbn_rgn_type_e hbn_rgn_type_t

名称	类型	最小值	最大值	默认值	含义	必选
OVERLAY_RGN	-	-	-	-	覆盖类型，将某一个图像覆盖到通道上	-
COVER_RGN	-	-	-	-	遮盖类型，将某一颜色遮盖到通道上	-
MOSAIC_RGN	-	-	-	-	马赛克类型，将某一区域变为马赛克（暂时不支持）	-
RGN_TYPE_MAX	-	-	-	-	最大支持的类型数量	-

typedef enum hbn_rgn_font_size_e hbn_rgn_font_size_t

名称	类型	最小值	最大值	默认值	含义	必选
FONT_SIZE_SMALL	-	-	-	-	小字号	-
FONT_SIZE_MEDIUM	-	-	-	-	中字号	-
FONT_SIZE_LARGE	-	-	-	-	大字号	-
FONT_SIZE_EXTRA_LARGE	-	-	-	-	超大字号	-

typedef enum hbn_rgn_font_color_e hbn_rgn_font_color_t

名称	类型	最小值	最大值	默认值	含义	必选
FONT_COLOR_WHITE	-	-	-	-	白色	-
FONT_COLOR_BLACK	-	-	-	-	黑色	-
FONT_COLOR_GREY	-	-	-	-	灰色	-
FONT_COLOR_BLUE	-	-	-	-	蓝色	-
FONT_COLOR_GREEN	-	-	-	-	绿色	-
FONT_COLOR_RED	-	-	-	-	红色	-
FONT_COLOR_CYAN	-	-	-	-	青色	-
FONT_COLOR_PURPLE	-	-	-	-	紫色	-
FONT_COLOR_YELLOW	-	-	-	-	黄色	-
FONT_COLOR_ORANGE	-	-	-	-	橙色	-
FONT_COLOR_BROWN	-	-	-	-	棕色	-
FONT_COLOR_PINK	-	-	-	-	粉色	-
FONT_COLOR_DARKBLUE	-	-	-	-	深蓝色	-
FONT_COLOR_DARKGREEN	-	-	-	-	深绿色	-
FONT_COLOR_DARKRED	-	-	-	-	深红色	-
FONT_COLOR_DARKGRAY	-	-	-	-	深灰色	-
FONT_KEY_COLOR_NUM	-	-	-	-	颜色数量	-

typedef enum hbn_rgn_pixel_format_e hbn_rgn_pixel_format_t

名称	类型	最小值	最大值	默认值	含义	必选
PIXEL_FORMAT_VGA_8	-	-	-	-	8bit 颜色 /alpha 数据格式	-
PIXEL_FORMAT_YUV420SP	-	-	-	-	YUV420SP 数据格式（暂时不支持）	-

typedef enum hbn_rgn_cover_type_e hbn_rgn_cover_type_t

名称	类型	最小值	最大值	默认值	含义	必选
COVER_RECT	-	-	-	-	矩形	-
COVER_POLYGON	-	-	-	-	多边形	-

typedef struct hbn_rgn_size_s hbn_rgn_size_t

名称	类型	最小值	最大值	默认值	含义	必选
width	uint32_t	-	-	-	宽	-
height	uint32_t	-	-	-	高	-

struct hbn_rgn_point_s hbn_rgn_point

名称	类型	最小值	最大值	默认值	含义	必选
x	uint32_t	-	-	-	x 坐标	-
y	uint32_t	-	-	-	y 坐标	-

typedef struct hbn_ren_overlay_s hbn_rgn_overlay_t

名称	类型	最小值	最大值	默认值	含义	必选
pixel_fmt	hbn_rgn_pixel_format_t	-	-	-	数据格式类型	是
size	hbn_rgn_size_t	-	-	-	尺寸大小，宽度为 32 的倍数，	是
					高度为 2 的倍数

struct hbn_rgn_polygon_s hbn_rgn_polygon

名称	类型	最小值	最大值	默认值	含义	必选
side_num	hbn_rgn_pixel_format_t	0	POLYGON_MAX_SIDE	-	多边形点的个数	是
vertex[POLYGON_MAX_SIDE]	hbn_rgn_point_t	-	-	-	多边形点的坐标 , 不支持内多边形	是

struct hbn_rgn_cover_attr_s hbn_rgn_cover

名称	类型	最小值	最大值	默认值	含义	必选
cover_type	hbn_rgn_cover_type_t	-	-	-	遮盖类型	是
-	union（ size polygon）	-	-	-	矩形的尺寸信息或者多边形坐标信息	是
					矩形时需要满足宽度为 32 的倍数，高度为 2 的倍数	是

struct hbn_rgn_mosaic_attr_s hbn_rgn_mosaic

名称	类型	最小值	最大值	默认值	含义	必选
size	hbn_rgn_size_t	-	-	-	需要满足宽度为 16 的倍数，高度为 2 的倍数	是
pixel_block	uint32_t	-	-	-	暂时无用	否

struct hbn_rgn_attr_s hbn_rgn_attr

名称	类型	最小值	最大值	默认值	含义	必选
type	hbn_rgn_type_t	OVERLAY_RGN	MOSAIC_RGN	-	区域类型	是
alpha	uint32_t	0	15	-	alpha 混合系数	否
color	hbn_rgn_font_color_t	FONT_COLOR_WHITE	FONT_COLOR_DARKGRAY	-	颜色	是
overlay_attr	hbn_rgn_overlay_t	-	-	-	叠加属性	是
cover_attr	hbn_rgn_cover_t	-	-	-	遮盖属性	是
mosaic_chn	hbn_rgn_mosaic_t	-	-	-	马赛克属性	否

struct hbn_rgn_chn_attr_s hbn_rgn_chn_attr

名称	类型	最小值	最大值	默认值	含义	必选
show	bool	-	-	-	是否显示	是
invert_en	bool	-	-	-	是否反色，暂时不支持	否
display_level	uint32_t	0	3	0	显示 level，硬件 osd 时需要为 0 ，软件为 1-3 ，	是
					目前需要设置以区分软硬件，暂时不支持显示 level
point	hbn_rgn_point_t	-	-	-	坐标信息	是

struct hbn_rgn_bitmap_attr_s hbn_rgn_bitmap

名称	类型	最小值	最大值	默认值	含义	必选
pixel_fmt	hbn_rgn_pixel_format_t	-	-	-	数据格式类型	是
size	hbn_rgn_size_t	-	-	-	尺寸信息	是
*paddr	void	-	-	-	要输入的 buffer 地址	是

struct hbn_rgn_draw_word_param_s hbn_rgn_draw_word

名称	类型	最小值	最大值	默认值	含义	必选
*paddr	void	-	-	-	画布的 buffer 地址	是
size	hbn_rgn_size_t	-	-	-	画布的大小	是
*draw_string	uint8_t	-	-	-	画字的字符串地址，需要以“\0”结尾，	是
					支持中（简）英文字符，需注意中文字符编码格式应为 gbk
font_color	hbn_rgn_font_color_t	0	FONT_COLOR_DARKGRAY	-	字体颜色	是
bg_color	uint32_t	0	FONT_COLOR_DARKGRAY	-	背景颜色	是
alpha	uint32_t	0	15	-	alpha 混合 index， 0 为完全透明， 15 为完全不透明，目前只有硬件支持	是
font_size	hbn_rgn_font_size_t	-	-	-	字体大小	是
flush_en	bool	-	-	-	是否刷新画布	是

typedef struct hbn_rgn_draw_line_param_s hbn_rgn_draw_line_t

名称	类型	最小值	最大值	默认值	含义	必选
*paddr	void	-	-	-	要画线的 buffer 地址	是
size	hbn_rgn_size_t	-	-	-	画布的大小	是
start_point	hbn_rgn_point_t	-	-	-	画线的起始坐标	是
end_point	hbn_rgn_point_t	-	-	-	画线的终止坐标	是
thick	uint32_t	-	-	-	线宽	是
color	hbn_rgn_font_color_t	FONT_COLOR_WHITE	FONT_COLOR_DARKGRAY	-	画线颜色	是
bg_color	uint32_t	FONT_COLOR_WHITE	FONT_COLOR_DARKGRAY	-	背景颜色	是
alpha	uint32_t	0	15	-	背景透明度，线的透明度默认为 15 ，硬件支持 背景半透明，软件目前只支持背景完全透明	是
flush_en	bool	-	-	-	是否刷新画布	是

typedef struct hbn_rgn_sta_attr_s hbn_rgn_sta_t

名称	类型	最小值	最大值	默认值	含义	必选
sta_en	uint8_t	-	-	-	是否使能该区域	是
start_x	uint16_t	-	-	-	起始坐标 x	是
start_y	uint16_t	-	-	-	起始坐标 y	是
width	uint16_t	2	255	-	统计区域宽度	是
height	uint16_t	2	255	-	统计区域高度	是