# 视频处理 - VSE

## 模块描述

VSE (Video Scale Enginer) 用于图像缩放
支持 6 个缩放通道，通道特性如下

- 最大处理能力: 3840x2160@60fps
- 支持输入裁剪，分别在水平和垂直方向上进行缩放，并且对色度和亮度分量进行单独处理
- 5个 downscale 通道
  - 最大分辨率支持分别为 4K/1080P/1080P/720P/720P
  - 最小分辨率为 64x64，支持任意 downscale factor
  - 支持帧率控制，支持 OSD
- 1个 upscale 通道
  - 最大分辨率支持 4K，最大放大倍数 4X, 放大倍数支持 0 - 4
  - 支持帧率控制，支持 OSD

<span id="vse_ochn"/> </span>

| 输出通道编号 | 类型 | 通道功能 |
| :---------- | :------- | :------ |
| 0           | offline | 4K Downscale |
| 1           | offline | 1080P Downscale |
| 2           | offline | 1080P Downscale |
| 3           | offline | 720P Downscale |
| 4           | offline | 720P Downscale |
| 5           | offline | 4K Upscale |

输入输出数据格式

- 支持输入数据的格式
  - from DDR: YUV422sp, YUV422 interleave, YUV420sp
  - from ISP: YUV420sp, YUV422sp
- 支持输出数据的格式：YUV444, YUV422, YUV420, RGB888

OSD 特性如下

- 每个OSD支持最多4个叠加区域（4个ROI在垂直方向上不重叠）和8个直方图统计区域
- OSD 相关介绍可以参考 [区域处理 - OSD](./7-OSD_API_zh_CN.html)

## 参考示例

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

## API 参考

- [hbn_vnode_open](#hbn_vnode_open) : 打开 vnode
- [hbn_vnode_close](#hbn_vnode_close) : 关闭 vnode
- [hbn_vnode_set_attr](#hbn_vnode_set_attr) : 设置 vnode 属性
- [hbn_vnode_set_ochn_attr](#hbn_vnode_set_ochn_attr) : 设置 VSE vnode 输出通道属性
- [hbn_vnode_get_ochn_attr](#hbn_vnode_get_ochn_attr) : 获取 VSE vnode 输出通道属性
- [hbn_vnode_set_ichn_attr](#hbn_vnode_set_ichn_attr) : 设置 VSE vnode 输入通道属性
- [hbn_vnode_get_ichn_attr](#hbn_vnode_get_ichn_attr) : 获取 VSE vnode 输入通道属性
- [hbn_vnode_set_ochn_buf_attr](#hbn_vnode_set_ochn_buf_attr) : 设置 VSE vnode 输出 buffer 属性
- [hbn_vnode_start](#hbn_vnode_start) : 启动 vnode
- [hbn_vnode_stop](#hbn_vnode_stop) : 停止 vnode
- [hbn_vnode_getframe](#hbn_vnode_getframe) : 从 vnode 获取帧数据
- [hbn_vnode_sendframe](#hbn_vnode_sendframe) : 将帧数据传入 vnode
- [hbn_vnode_releaseframe](#hbn_vnode_releaseframe) : 释放帧数据

## 接口说明

<span id="hbn_vnode_open"/> </span>

### hbn_vnode_open

#### 【函数声明】

```
hobot_status hbn_vnode_open(hb_vnode_type vnode_type, uint32_t hw_id, int32_t ctx_id, hbn_vnode_handle_t *vnode_fd);
```

#### 【功能描述】

初始化 vnode，打开 vnode 设备节点，并返回该模块的 vnode handle

#### 【参数描述】

- [IN] hb_vnode_type vnode_type : vnode类型，对于 VSE，取值为 HB_VSE
- [IN] uint32_t hw_id : 模块的硬件 id，对于 VSE，hw_id 取值为0
- [IN] int32_t ctx_id : 模块的 context id，软件上的概念，可指定 context id 值，也可设置为 AUTO_ALLOC_ID，由 HBN 框架自动分配 context id
- [OUT] hbn_vnode_handle_t *vnode_fd : 返回模块的 vnode handle

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_close"/> </span>

### hbn_vnode_close

#### 【函数声明】

```
void hbn_vnode_close(hbn_vnode_handle_t vnode_fd);
```

#### 【功能描述】

关闭模块的设备节点。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；

#### 【返回值】

无

#### 【注意事项】

需要和hbn_vnode_open成对使用。

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_set_attr"/> </span>

### hbn_vnode_set_attr

#### 【函数声明】

```
hobot_status hbn_vnode_set_attr(hbn_vnode_handle_t vnode_fd, void *attr);
```

#### 【功能描述】

设置模块的基本属性。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] void *attr：模块的基本属性结构体指针，对于 VSE，其属性结构体为 [vse_attr_t](#vse_attr_t)；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_set_ochn_attr"/> </span>

### hbn_vnode_set_ochn_attr

#### 【函数声明】

```
hobot_status hbn_vnode_set_ochn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, void *attr);
```

#### 【功能描述】

设置模块的输出通道属性。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ochn_id：模块的输出通道 id，通道 id 见[VSE通道说明](#vse_ochn)；
- [IN] void *attr：模块的输出通道属性结构体指针。对于 VSE，输出通道属性结构体为 [vse_ochn_attr_t](#vse_ochn_attr_t)；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_get_ochn_attr"/> </span>

### hbn_vnode_get_ochn_attr

#### 【函数声明】

```
hobot_status hbn_vnode_get_ochn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, void *attr);
```

#### 【功能描述】

获取模块的输出通道属性。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ochn_id：模块的输出通道 id，通道 id 见[VSE通道说明](#vse_ochn)；
- [OUT] void *attr：模块输出通道属性结构体指针。对于 VSE，输出通道属性结构体为 [vse_ochn_attr_t](#vse_ochn_attr_t)；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_set_ichn_attr"/> </span>

### hbn_vnode_set_ichn_attr

#### 【函数声明】

```
hobot_status hbn_vnode_set_ichn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id, void *attr);
```

#### 【功能描述】

设置模块的输入通道属性。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ichn_id：模块的输入通道 id，通道 id 见[VSE通道说明](#vse_ochn)；
- [IN] void *attr：模块的输入通道属性结构体指针。对于 VSE，输入通道属性结构体为 [vse_ichn_attr_t](#vse_ichn_attr_t)；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_get_ichn_attr"/> </span>

### hbn_vnode_get_ichn_attr

#### 【函数声明】

```
hobot_status hbn_vnode_get_ichn_attr(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id, void *attr);
```

#### 【功能描述】

获取模块的输入通道属性。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ichn_id：模块的输入通道 id，对于 VSE，输入通道为0；
- [OUT] void *attr：模块的输入通道属性结构体指针。对于 VSE，输入通道属性结构体为 [vse_ichn_attr_t](#vse_ichn_attr_t)；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_set_ochn_buf_attr"/> </span>

### hbn_vnode_set_ochn_buf_attr

#### 【函数声明】

```
hobot_status hbn_vnode_set_ochn_buf_attr(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id,
					 hbn_buf_alloc_attr_t *alloc_attr);
```

#### 【功能描述】

设置输出通道 buffer 属性，包括 buffer 的数量以及 buffer 地址是否连续。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ochn_id：模块的输出通道id，通道 id 见[VSE通道说明](#vse_ochn)；
- [IN] hbn_buf_alloc_attr_t *alloc_attr：buffer分配属性；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_start"/> </span>

### hbn_vnode_start

#### 【函数声明】

```
hobot_status hbn_vnode_start(hbn_vnode_handle_t vnode_fd);
```

#### 【功能描述】

模块启动。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

启动前需要先打开模块。

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_stop"/> </span>

### hbn_vnode_stop

#### 【函数声明】

```
hobot_status hbn_vnode_stop(hbn_vnode_handle_t vnode_fd);
```

#### 【功能描述】

模块停止。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_getframe"/> </span>

### hbn_vnode_getframe

#### 【函数声明】

```
hobot_status hbn_vnode_getframe(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, uint32_t millisecondTimeout,
				hbn_vnode_image_t *out_img);
```

#### 【功能描述】

获取模块输出通道的图像，阻塞型接口。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ochn_id：模块的输出通道 id，通道 id 见[VSE通道说明](#vse_ochn)；
- [IN] uint32_t millisecondTimeout：超时等待时间；
- [OUT] hbn_vnode_image_t *out_img：输出图像 buffer 结构体地址；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_sendframe"/> </span>

### hbn_vnode_sendframe

#### 【函数声明】

```
hobot_status hbn_vnode_sendframe(hbn_vnode_handle_t vnode_fd, uint32_t ichn_id,
				 hbn_vnode_image_t *img);
```

#### 【功能描述】

发送图像到模块的输入通道，会触发模块进行处理。阻塞型接口，等待硬件处理完再返回，默认超时时间为1秒

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ichn_id：模块的输入通道id，对于 VSE，输入通道为0；
- [IN] hbn_vnode_image_t *img：输入图像buffer地址；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5

<span id="hbn_vnode_releaseframe"/> </span>

### hbn_vnode_releaseframe

#### 【函数声明】

```
hobot_status hbn_vnode_releaseframe(hbn_vnode_handle_t vnode_fd, uint32_t ochn_id, hbn_vnode_image_t *img);
```

#### 【功能描述】

释放图像buffer，buffer会归还到指定的输出通道。

#### 【参数描述】

- [IN] hbn_vnode_handle_t vnode_fd：模块的 vnode handle；
- [IN] uint32_t ochn_id：模块的输出通道 id，通道 id 见[VSE通道说明](#vse_ochn)；
- [IN] hbn_vnode_image_t *img：图像 buffer 结构体地址；

#### 【返回值】

- 成功，返回 HBN_STATUS_SUCESS 0
- 失败：异常为负值错误码，参考[返回值说明](#return_val)

#### 【注意事项】

无

#### 【兼容性】

硬件: X5


## 数据结构

<span id="vse_cfg_t"/> </span>

### vse_cfg_t

| 名称      | 类型            | 最小值 | 最大值 | 默认值 | 含义             |
| :-------- | :-------------- | :----- | :----- | :----- | :--------------- |
| vse_attr  | [vse_attr_t](#vse_attr_t)      | ·      | ·      | ·      | VSE 基本属性         |
| ichn_attr | [vse_ichn_attr_t](#vse_ichn_attr_t) | ·      | ·      | ·      | VSE 输入通道属性 |
| ochn_attr | [vse_ochn_attr_t](#vse_ochn_attr_t) | ·      | ·      | ·      | VSE 输出通道属性 |

<span id="vse_attr_t"/> </span>

### vse_attr_t

| 名称      | 类型            | 最小值 | 最大值 | 默认值 | 含义             |
| :-------- | :-------------- | :----- | :----- | :----- | :--------------- |
| fps  | frame_fps_ctrl_t      | ·      | ·      | 0      | 目前只支持配置输入图像src的fps， 该参数用于vse的帧率控制 |

<span id="vse_ichn_attr_t"/> </span>

### vse_ichn_attr_t

| 名称      | 类型           | 最小值 | 最大值 | 默认值 | 含义             |
| :-------- | :------------- | :----- | :----- | :----- | :--------------- |
| tpg_en    | cam_bool_e     | 0      | 1      | 0      | 使能tpg功能，暂时不支持   |
| width     | uint32_t       | 0      | 5432   | 0      | 输入图像原始的宽度 |
| height    | uint32_t       | 0      | 3076   | 0      | 输入图像原始的高度 |
| fmt       | frame_format_e | FRM_FMT_NV12 | FRM_FMT_NV12 | 0 | FRM_FMT_NULL - 无效值，FRM_FMT_RAW - RAW格式，FRM_FMT_NV12 - NV12格式，FRM_FMT_UYVY - UYVY格式，目前只支持nv12格式 |
| bit_width | uint32_t       | 8      | 8      | 0      | 输入图像bit宽度 |

<span id="vse_ochn_attr_t"/> </span>

### vse_ochn_attr_t

| 名称      | 类型             | 最小值 | 最大值 | 默认值 | 含义             |
| :-------- | :--------------- | :----- | :----- | :----- | :--------------- |
| chn_en    | cam_bool_e       | 0      | 1      | 0      | 使能通道   |
| roi       | common_rect_t    | ·      | ·      | ·      | 对输出图像的crop，值全为0，表示禁止crop   |
| target_w  | uint32_t         | 0      | 受通道能力限制   | 0      | 输出图像的宽度，值为0表示禁止scale |
| target_h  | uint32_t         | 0      | 受通道能力限制   | 0      | 输出图像的高度，值为0表示禁止scale |
| y_stride | uint32_t         | 0      | ·   | 0      | 输出图像y图层stride，暂时不支持 |
| uv_stride  | uint32_t         | 0      | ·   | 0      | 输出图像uv图层stride，暂时不支持 |
| fmt       | frame_format_e | FRM_FMT_NV12 | FRM_FMT_NV12 | 0 | FRM_FMT_NULL - 无效值，FRM_FMT_RAW - RAW格式，FRM_FMT_NV12 - NV12格式，FRM_FMT_UYVY - UYVY格式，目前只支持nv12格式 |
| bit_width | uint32_t         | 8      | 8      | 0      | 输入图像bit宽度 |
| fps       | frame_fps_ctrl_t | ·      | ·      | 0      | 目前只支持配置输出图像dst的fps， 该参数用于vse的帧率控制。该值为0时， 若输入fps为0，则不会开启帧率控制， 若输入fps不为0，则不会输出任何数据 |

<span id="return_val"/> </span>

## 返回值说明

| 错误码 | 宏定义                           | 描述                             | 常见原因及解决方法 |
| :---------- | :------- | :------ | :------ |
| 0      | HBN_STATUS_SUCESS                | 成功                             | |
| 1      | HBN_STATUS_INVALID_NODE          | vnode无效，找不到对应的vnode     | |
| 2      | HBN_STATUS_INVALID_NODETYPE      | vnode类型无效，找不到对应的vnode | 对于 VSE，vnode 类型为 HB_VSE |
| 3      | HBN_STATUS_INVALID_HWID          | 无效的硬件模块id                 | 对于 VSE，hw_id 取值为 0 |
| 4      | HBN_STATUS_INVALID_CTXID         | 无效的context id                 | 可设置为 AUTO_ALLOC_ID，由 HBN 框架自动分配 |
| 5      | HBN_STATUS_INVALID_OCHNID        | 无效的输出通道id                 | VSE 输出通道范围[0,5] |
| 6      | HBN_STATUS_INVALID_ICHNID        | 无效的输入通道id                 | VSE 仅支持1个输入通道 |
| 7      | HBN_STATUS_INVALID_FORMAT        | 无效的格式                       | |
| 8      | HBN_STATUS_INVALID_NULL_PTR      | 空指针                           | |
| 9      | HBN_STATUS_INVALID_PARAMETER     | 无效的参数，版本检查失败         | |
| 10     | HBN_STATUS_ILLEGAL_ATTR          | 无效的参数                       | |
| 11     | HBN_STATUS_INVALID_FLOW          | 无效的flow，找不到对应的flow     | |
| 12     | HBN_STATUS_FLOW_EXIST            | flow已经存在                     | |
| 13     | HBN_STATUS_FLOW_UNEXIST          | flow不存在                       | |
| 14     | HBN_STATUS_NODE_EXIST            | node已经存在                     | |
| 15     | HBN_STATUS_NODE_UNEXIST          | node不存在                       | |
| 16     | HBN_STATUS_NOT_CONFIG            | 预留                             | |
| 17     | HBN_STATUS_CHN_NOT_ENABLED       | 通道未使能                       | |
| 18     | HBN_STATUS_CHN_ALREADY_ENABLED   | 通道已使能                       | |
| 19     | HBN_STATUS_ALREADY_BINDED        | node已经绑定                     | |
| 20     | HBN_STATUS_NOT_BINDED            | node未绑定                       | |
| 21     | HBN_STATUS_TIMEOUT               | 超时                             | |
| 22     | HBN_STATUS_NOT_INITIALIZED       | 未初始化                         | |
| 23     | HBN_STATUS_NOT_SUPPORT           | 通道不支持或未激活               | |
| 24     | HBN_STATUS_NOT_PERM              | 操作不允许                       | |
| 25     | HBN_STATUS_NOMEM                 | 内存不足                         | |
| 26     | HBN_STATUS_INVALID_VNODE_FD      | 无效的node文件描述符             | |
| 27     | HBN_STATUS_INVALID_ICHNID_FD     | 无效的输入通道文件描述符         | |
| 28     | HBN_STATUS_INVALID_OCHNID_FD     | 无效的输出通道文件描述符         | |
| 29     | HBN_STATUS_OPEN_OCHN_FAIL        | 打开输出通道失败                 | |
| 30     | HBN_STATUS_OPEN_ICHN_FAIL        | 打开输入通道失败                 | |
| 31     | HBN_STATUS_JSON_PARSE_FAIL       | json解析失败                     | |
| 32     | HBN_STATUS_REQ_BUF_FAIL          | 请求buffer失败                   | |
| 33     | HBN_STATUS_QUERY_BUF_FAIL        | 查询buffer信息失败               | |
| 34     | HBN_STATUS_SET_CONTROL_FAIL      | 模块控制、调节参数（如ISP效果参数）设置失败 | |
| 35     | HBN_STATUS_GET_CONTROL_FAIL      | 模块控制、调节参数（如ISP效果参数）获取失败 | |
| 36     | HBN_STATUS_NODE_START_FAIL       | node开启失败                     | |
| 37     | HBN_STATUS_NODE_STOP_FAIL        | node停止失败                     | |
| 38     | HBN_STATUS_NODE_POLL_ERROR       | node通道poll错误                 | |
| 39     | HBN_STATUS_NODE_POLL_TIMEOUT     | node通道poll超时                 | |
| 40     | HBN_STATUS_NODE_POLL_FRAME_DROP  | node通道poll时发生丢帧           | |
| 41     | HBN_STATUS_NODE_POLL_HUP         | node通道poll时描述符挂起         | |
| 42     | HBN_STATUS_NODE_ILLEGAL_EVENT    | node通道poll时事件非法           | |
| 43     | HBN_STATUS_NODE_DEQUE_ERROR      | node通道dequeue buffer错误       | |
| 44     | HBN_STATUS_ILLEGAL_BUF_INDEX     | 无效的buffer索引                 | |
| 45     | HBN_STATUS_NODE_QUE_ERROR        | node通道queue buffer错误         | |
| 46     | HBN_STATUS_FLUSH_FRAME_ERROR     | node通道帧flush错误              | |
| 47     | HBN_STATUS_INIT_BIND_ERROR       | 用json解析并绑定时发生错误       | |
| 48     | HBN_STATUS_ADD_NODE_FAIL         | 向flow中添加node失败             | |
| 49     | HBN_STATUS_WRONG_CONFIG_ID       | 系统不支持的node id              | |
| 50     | HBN_STATUS_BIND_NODE_FAIL        | flow绑定node时发生错误           | |
| 51     | HBN_STATUS_INVALID_VERSION       | 底层驱动模块和上层库版本号不匹配错误 | |
| 52     | HBN_STATUS_GET_VERSION_ERROR     | 获取底层驱动模块版本号错误       | |
| 53     | HBN_STATUS_MEM_INIT_FAIL         | hbmem内存初始化失败              | |
| 54     | HBN_STATUS_MEM_IMPORT_FAIL       | hbmem内存引入失败                | |
| 55     | HBN_STATUS_MEM_FREE_FAIL         | hbmem内存释放失败                | |
| 56     | HBN_STATUS_SYSFS_OPEN_FAIL       | 系统文件打开失败                 | |
| 57     | HBN_STATUS_STRUCT_SIZE_NOT_MATCH | hal层结构体大小与kernel层不匹配  | |
| 58     | HBN_STATUS_RGN_UNEXIST           | 获取不到对应的rgn数据            | |
| 59     | HBN_STATUS_RGN_INVALID_OPERATION | rgn操作无效                      | |
| 60     | HBN_STATUS_RGN_OPEN_FILE_FAIL    | rgn模块打开文件失败              | |
| 128    | HBN_STATUS_ERR_UNKNOW            | 未知错误                         | |



