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 叠加功能。

image-20241224-211604

  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 区域叠加方式 ，右图展示了不支持的叠加方式。

image-20241224-115426

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 - 统计区域高度 是