# GDC API

## 模块描述

GDC（ Geometrical Distortion Correction ）模块可将输入的图像进行畸变校正、视角变换和指定角度 ( 0,90,180,270 ) 的旋转。

### 基础规格

模式支持的输入图像典型尺寸为 3840\*2160，2688\*1944 ， 1920\*1080，1280\*720 ， 640\*480，480\*320 。

硬件特性如下 :

- 最大分辨率 : 4096x2160
- 最小分辨率 : 100x100( 奇数行或者列不支持 )
- 性能 : 4096x2160@60fps
- 输入格式 : YUV420 semi-planar
- 输出格式 : YUV420 semi-planar

## 参考示例

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

## API 参考

| 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) | 设置 GDC vnode 输出通道属性 |
[hbn_vnode_get_ochn_attr](#hbn_vnode_get_ochn_attr) | 获取 GDC vnode 输出通道属性 |
[hbn_vnode_set_ichn_attr](#hbn_vnode_set_ichn_attr) | 设置 GDC vnode 输入通道属性 |
[hbn_vnode_get_ichn_attr](#hbn_vnode_get_ichn_attr) | 获取 GDC vnode 输入通道属性 |
[hbn_vnode_set_ochn_buf_attr](#hbn_vnode_set_ochn_buf_attr) | 设置 GDC 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

#### 【函数声明】

```c
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 类型，对于 GDC，取值为 HB_GDC
- [IN] uint32_t hw_id : 模块的硬件 id，对于 GDC，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

#### 【函数声明】

```c
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

#### 【函数声明】

```c
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：模块的基本属性结构体指针，对于 GDC，其属性结构体为 [gdc_attr_t](#gdc_attr_t)；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5

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

### hbn_vnode_set_ochn_attr

#### 【函数声明】

```c
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，对于 GDC，输出通道为0；
- [IN] void *attr：模块的输出通道属性结构体指针。对于 GDC，输出通道属性结构体为 [gdc_ochn_attr_t](#gdc_ochn_attr_t)；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5

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

### hbn_vnode_get_ochn_attr

#### 【函数声明】

```c
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，对于 GDC，输出通道为0；
- [OUT] void *attr：模块输出通道属性结构体指针。对于 GDC，输出通道属性结构体为 [gdc_ochn_attr_t](#gdc_ochn_attr_t)；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5

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

### hbn_vnode_set_ichn_attr

#### 【函数声明】

```c
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，对于 GDC，输入通道为0；
- [IN] void *attr：模块的输入通道属性结构体指针。对于 GDC，输入通道属性结构体为 [gdc_ichn_attr_t](#gdc_ichn_attr_t)；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5

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

### hbn_vnode_get_ichn_attr

#### 【函数声明】

```c
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，对于 GDC，输入通道为0；
- [OUT] void *attr：模块的输入通道属性结构体指针。对于 GDC，输入通道属性结构体为 [gdc_ichn_attr_t](#gdc_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

#### 【函数声明】

```c
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，对于 GDC，输出通道为0；
- [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

#### 【函数声明】

```c
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

#### 【函数声明】

```c
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

#### 【函数声明】

```c
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，对于 GDC，输出通道为0；
- [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

#### 【函数声明】

```c
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，对于 GDC，输入通道为0；
- [IN] hbn_vnode_image_t *img：输入图像 buffer 地址；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5

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

### hbn_vnode_releaseframe

#### 【函数声明】

```c
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，对于 GDC，输出通道为0；
- [IN] hbn_vnode_image_t *img：图像 buffer 结构体地址；

#### 【返回值】

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

#### 【注意事项】

无
#### 【兼容性】

硬件: X5


## 数据结构

<span id="gdc_attr_t"/> </span>

#### gdc_attr_t

| 名称          | 类型     | 最小值 | 最大值 | 默认值 | 含义                         | 必选 |
|---------------|----------|--------|--------|--------|------------------------------|------|
|  config_addr  | uint64_t | -      | -      | -      | gdc 配置文件的地址           | 是   |
|  config_size  | uint32_t | -      | -      | -      | gdc 配置文件的大小           | 是   |
|  div_width    | uint8_t  | 8      | -      | 0      | 暂时不用                     | 是   |
|  div_height   | uint8_t  | 0      | -      | 0      | 暂时不用                     | 否   |
|  total_planes | uint32_t | 0      | -      | 0      | yuv 图层数量                 | 是   |
|  binary_ion_id | int32_t | 0      | -      | 0      | 配置文件的物理地址的 shareid | 是   |
|  binary_offset | uint64_t | 0     | -      | 0      | 配置文件所在物理地址的 offset | 是   |

---

<span id="gdc_ichn_attr_t"/> </span>

#### gdc_ichn_attr_t

| 名称         | 类型     | 最小值 | 最大值 | 默认值 | 含义               | 必选 |
|--------------|----------|--------|--------|--------|--------------------|------|
|  input_width | uint32_t | 0      | 4096   | 0      | 输入图像的宽度     | 是   |
|  input_height | uint32_t | 0     | 2160   | 0      | 输入图像的高度     | 是   |
|  input_stride | uint32_t | 0     | -      | 0      | 输入图像的 stride  | 是   |
|  n_in_one    | uint32_t | 0      | -      | 0      | 回灌 n 帧合成 1 帧 | 是   |

---

<span id="gdc_ochn_attr_t"/> </span>

#### gdc_ochn_attr_t

| 名称          | 类型     | 最小值 | 最大值 | 默认值 | 含义               | 必选 |
|---------------|----------|--------|--------|--------|--------------------|------|
|  output_width | uint32_t | 0      | -      | 0      | 输出图像的宽度     | 是   |
|  output_height | uint32_t | 0     | -      | 0      | 输出图像的高度     | 是   |
|  output_stride | uint32_t | 0     | -      | 0      | 输出图像的 stride  | 是   |

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

## 返回值说明

| 错误码 | 宏定义                           | 描述                             | 常见原因及解决方法 |
| :---------- | :------- | :------ | :------ |
| 0      | HBN_STATUS_SUCESS                | 成功                             | |
| 1      | HBN_STATUS_INVALID_NODE          | vnode 无效，找不到对应的 vnode     | |
| 2      | HBN_STATUS_INVALID_NODETYPE      | vnode 类型无效，找不到对应的 vnode | 对于 GDC，vnode 类型为 HB_GDC |
| 3      | HBN_STATUS_INVALID_HWID          | 无效的硬件模块 id                 | 对于 GDC，hw_id 取值为 0 |
| 4      | HBN_STATUS_INVALID_CTXID         | 无效的 context id                 | 可设置为 AUTO_ALLOC_ID，由 HBN 框架自动分配 |
| 5      | HBN_STATUS_INVALID_OCHNID        | 无效的输出通道 id                 | GDC 输出通道为 0 |
| 6      | HBN_STATUS_INVALID_ICHNID        | 无效的输入通道 id                 | GDC 仅支持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            | 未知错误                         | |
