5.10.2. GDC API
5.10.2.1. 模块描述
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
5.10.2.2. 参考示例
GDC 部分示例代码可以参考 sample_gdc 章节
5.10.2.3. API 参考
| API 接口 | 接口功能 |
|---|---|
| hbn_vnode_open | 打开 vnode |
| hbn_vnode_close | 关闭 vnode |
| hbn_vnode_set_attr | 设置 vnode 属性 |
| hbn_vnode_set_ochn_attr | 设置 GDC vnode 输出通道属性 |
| hbn_vnode_get_ochn_attr | 获取 GDC vnode 输出通道属性 |
| hbn_vnode_set_ichn_attr | 设置 GDC vnode 输入通道属性 |
| hbn_vnode_get_ichn_attr | 获取 GDC vnode 输入通道属性 |
| hbn_vnode_set_ochn_buf_attr | 设置 GDC vnode 输出 buffer 属性 |
| hbn_vnode_start | 启动 vnode |
| hbn_vnode_stop | 停止 vnode |
| hbn_vnode_getframe | 从 vnode 获取帧数据 |
| hbn_vnode_sendframe | 将帧数据传入 vnode |
| hbn_vnode_releaseframe | 释放帧数据 |
5.10.2.4. 接口说明
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 类型，对于 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
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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
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：模块的基本属性结构体指针，对于 GDC，其属性结构体为 gdc_attr_t；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输出通道为0；
[IN] void *attr：模块的输出通道属性结构体指针。对于 GDC，输出通道属性结构体为 gdc_ochn_attr_t；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输出通道为0；
[OUT] void *attr：模块输出通道属性结构体指针。对于 GDC，输出通道属性结构体为 gdc_ochn_attr_t；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输入通道为0；
[IN] void *attr：模块的输入通道属性结构体指针。对于 GDC，输入通道属性结构体为 gdc_ichn_attr_t；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输入通道为0；
[OUT] void *attr：模块的输入通道属性结构体指针。对于 GDC，输入通道属性结构体为 gdc_ichn_attr_t；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输出通道为0；
[IN] hbn_buf_alloc_attr_t *alloc_attr：buffer 分配属性；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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
失败：异常为负值错误码，参考返回值说明
【注意事项】
启动前需要先打开模块。
【兼容性】
硬件: X5
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
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输出通道为0；
[IN] uint32_t millisecondTimeout：超时等待时间；
[OUT] hbn_vnode_image_t *out_img：输出图像 buffer 结构体地址；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输入通道为0；
[IN] hbn_vnode_image_t *img：输入图像 buffer 地址；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
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，对于 GDC，输出通道为0；
[IN] hbn_vnode_image_t *img：图像 buffer 结构体地址；
【返回值】
成功，返回 HBN_STATUS_SUCESS 0
失败：异常为负值错误码，参考返回值说明
【注意事项】
无
【兼容性】
硬件: X5
5.10.2.5. 数据结构
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 | 是 |
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 帧 | 是 |
gdc_ochn_attr_t
| 名称 | 类型 | 最小值 | 最大值 | 默认值 | 含义 | 必选 |
|---|---|---|---|---|---|---|
| output_width | uint32_t | 0 | - | 0 | 输出图像的宽度 | 是 |
| output_height | uint32_t | 0 | - | 0 | 输出图像的高度 | 是 |
| output_stride | uint32_t | 0 | - | 0 | 输出图像的 stride | 是 |
5.10.2.6. 返回值说明
| 错误码 | 宏定义 | 描述 | 常见原因及解决方法 |
|---|---|---|---|
| 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 | 未知错误 |