中文 EN

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 未知错误