# 区域处理 - OSD

## 模块描述

OSD（ On-Screen Display ）模块是一个重要的图像处理工具，通过配置操作区域 Region，并将 Region 在图像上进行叠加操作，如填色、绘制、马赛克等。其主要应用场景包括：
- 视频图像增强：对实时视频或静态图像叠加特定区域的标注、信息展示。
- 隐私保护：通过叠加马赛克或遮挡区域，对特定区域进行模糊处理或遮盖，保护敏感信息。

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

### 基础规格

- 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 功能支持情况如下：

<span id="osd"/> </span>

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

<font color=red> 备注：</font>
VSE 通道 4 默认采用软件 使用 NEON 指令集 实现 OSD 叠加功能。

![image-20241224-211604](./_static/_images/7-OSD_API_zh_CN/image-20241224-211604.png)

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 指令集 操作图像数据完成。

### 注意事项

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

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

![image-20241224-115426](./_static/_images/7-OSD_API_zh_CN/image-20241224-115426.png)

**OSD 支持的叠加类型如下：**
- OVERLAY: 叠加区域 , 可以在矩形区域自行填充内容 , 例如写字画线。
- COVER: 遮挡区域 , 纯色块 , 支持矩形和多边形，不支持圆形。
- MOSAIC: 马赛克区域 , 矩形区域以马赛克形式遮挡。

## 参考示例

- OSD 部分示例代码可以参考 [sample_osd](../samples/sample_osd.html)  章节

## API 参考

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


<span id="hbn_rgn_create"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。


#### 【功能描述】

用于创建一块 region 区域。

#### 【注意事项】

无

<span id="hbn_rgn_destroy"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

用于销毁一块 region 区域。

#### 【注意事项】

无

<span id="hbn_rgn_getattr"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_setattr"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_setbitmap"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_attach_to_chn"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。。
#### 【功能描述】

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

#### 【注意事项】

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

<span id="hbn_rgn_detach_from_chn"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_set_displayattr"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_get_displayattr"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无


<span id="hbn_rgn_draw_word"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_draw_line"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

无

<span id="hbn_rgn_set_colormap"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

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

<span id="hbn_rgn_set_sta"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

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

#### 【注意事项】

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

<span id="hbn_rgn_get_sta"/> </span>

### 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 。
- 失败：异常为负值错误码，参考 [ 返回值说明 ](./6-VSE_API_zh_CN.html#return_val)。
#### 【功能描述】

获取最多 8 个区域的统计数据，该数据以亮度直方图的形式输出，配和设置的 3 个阈值，输出 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    | -      | 统计区域高度   | 是   |
