5.10.2. GDC API

5.10.2.1. Module Description

The GDC (Geometrical Distortion Correction) module performs distortion correction, perspective transformation, and rotation at specified angles (0, 90, 180, 270) on input images.

Basic Specifications

Supported input image resolutions typically include: 3840*2160, 2688*1944, 1920*1080, 1280*720, 640*480, and 480*320.

Hardware features are as follows:

Maximum resolution: 4096x2160
Minimum resolution: 100x100 (odd number of rows or columns not supported)
Performance: 4096x2160@60fps
Input format: YUV420 semi-planar
Output format: YUV420 semi-planar

5.10.2.2. Reference Examples

Partial example code for GDC can be found in the sample_gdc section.

5.10.2.3. API Reference

API Interface	Functionality
hbn_vnode_open	Open vnode
hbn_vnode_close	Close vnode
hbn_vnode_set_attr	Set vnode attributes
hbn_vnode_set_ochn_attr	Set GDC vnode output channel attributes
hbn_vnode_get_ochn_attr	Get GDC vnode output channel attributes
hbn_vnode_set_ichn_attr	Set GDC vnode input channel attributes
hbn_vnode_get_ichn_attr	Get GDC vnode input channel attributes
hbn_vnode_set_ochn_buf_attr	Set GDC vnode output buffer attributes
hbn_vnode_start	Start vnode
hbn_vnode_stop	Stop vnode
hbn_vnode_getframe	Retrieve frame data from vnode
hbn_vnode_sendframe	Send frame data to vnode
hbn_vnode_releaseframe	Release frame data

5.10.2.4. Interface Descriptions

hbn_vnode_open

【Function Declaration】

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

【Functional Description】

Initialize the vnode, open the vnode device node, and return the vnode handle for this module.

【Parameter Description】

[IN] hb_vnode_type vnode_type: Vnode type; for GDC, use HB_GDC
[IN] uint32_t hw_id: Hardware ID of the module; for GDC, hw_id is 0
[IN] int32_t ctx_id: Context ID of the module; a software concept. Can be specified manually or set to AUTO_ALLOC_ID for automatic allocation by the HBN framework
[OUT] hbn_vnode_handle_t *vnode_fd: Returns the vnode handle of the module

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_close

【Function Declaration】

void hbn_vnode_close(hbn_vnode_handle_t vnode_fd);

【Functional Description】

Close the module’s device node.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module

【Return Value】

None

【Notes】

Must be used in pair with hbn_vnode_open.

【Compatibility】

Hardware: X5

hbn_vnode_set_attr

【Function Declaration】

hobot_status hbn_vnode_set_attr(hbn_vnode_handle_t vnode_fd, void *attr);

【Functional Description】

Set basic attributes of the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] void *attr: Pointer to the attribute structure of the module; for GDC, this is gdc_attr_t

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_set_ochn_attr

【Function Declaration】

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

【Functional Description】

Set output channel attributes of the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ochn_id: Output channel ID of the module; for GDC, the output channel ID is 0
[IN] void *attr: Pointer to the output channel attribute structure; for GDC, this is gdc_ochn_attr_t

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_get_ochn_attr

【Function Declaration】

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

【Functional Description】

Get output channel attributes of the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ochn_id: Output channel ID of the module; for GDC, the output channel ID is 0
[OUT] void *attr: Pointer to the output channel attribute structure; for GDC, this is gdc_ochn_attr_t

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_set_ichn_attr

【Function Declaration】

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

【Functional Description】

Set input channel attributes of the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ichn_id: Input channel ID of the module; for GDC, the input channel ID is 0
[IN] void *attr: Pointer to the input channel attribute structure; for GDC, this is gdc_ichn_attr_t

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_get_ichn_attr

【Function Declaration】

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

【Functional Description】

Get input channel attributes of the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ichn_id: Input channel ID of the module; for GDC, the input channel ID is 0
[OUT] void *attr: Pointer to the input channel attribute structure; for GDC, this is gdc_ichn_attr_t

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_set_ochn_buf_attr

【Function Declaration】

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);

【Functional Description】

Set output channel buffer attributes, including the number of buffers and whether buffer addresses are contiguous.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ochn_id: Output channel ID of the module; for GDC, the output channel ID is 0
[IN] hbn_buf_alloc_attr_t *alloc_attr: Buffer allocation attributes

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_start

【Function Declaration】

hobot_status hbn_vnode_start(hbn_vnode_handle_t vnode_fd);

【Functional Description】

Start the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

The module must be opened before starting.

【Compatibility】

Hardware: X5

hbn_vnode_stop

【Function Declaration】

hobot_status hbn_vnode_stop(hbn_vnode_handle_t vnode_fd);

【Functional Description】

Stop the module.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_getframe

【Function Declaration】

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

【Functional Description】

Retrieve image from the module’s output channel. This is a blocking interface.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ochn_id: Output channel ID of the module; for GDC, the output channel ID is 0
[IN] uint32_t millisecondTimeout: Timeout duration in milliseconds
[OUT] hbn_vnode_image_t *out_img: Pointer to the output image buffer structure

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_sendframe

【Function Declaration】

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

【Functional Description】

Send an image to the module’s input channel, triggering processing. This is a blocking interface that waits for hardware processing to complete before returning, with a default timeout of 1 second.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ichn_id: Input channel ID of the module; for GDC, the input channel ID is 0
[IN] hbn_vnode_image_t *img: Pointer to the input image buffer

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

hbn_vnode_releaseframe

【Function Declaration】

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

【Functional Description】

Release the image buffer; the buffer will be returned to the specified output channel.

【Parameter Description】

[IN] hbn_vnode_handle_t vnode_fd: The vnode handle of the module
[IN] uint32_t ochn_id: Output channel ID of the module; for GDC, the output channel ID is 0
[IN] hbn_vnode_image_t *img: Pointer to the image buffer structure

【Return Value】

Success: returns HBN_STATUS_SUCCESS 0
Failure: negative error code; refer to Return Value Description

【Notes】

None

【Compatibility】

Hardware: X5

5.10.2.5. Data Structures

gdc_attr_t

Name	Type	Min Value	Max Value	Default	Description	Required
config_addr	uint64_t	-	-	-	Address of the GDC configuration file	Yes
config_size	uint32_t	-	-	-	Size of the GDC configuration file	Yes
div_width	uint8_t	8	-	0	Reserved (not used)	Yes
div_height	uint8_t	0	-	0	Reserved (not used)	No
total_planes	uint32_t	0	-	0	Number of YUV planes	Yes
binary_ion_id	int32_t	0	-	0	Share ID of the physical address of the configuration file	Yes
binary_offset	uint64_t	0	-	0	Offset of the physical address where the configuration file resides	Yes

gdc_ichn_attr_t

Name	Type	Max Value	Description	Required
input_width	uint32_t	4096	Width of input image	Yes
input_height	uint32_t	2160	Height of input image	Yes
input_stride	uint32_t	-	Stride of input image	Yes
n_in_one	uint32_t	-	Merge n frames into one	Yes

gdc_ochn_attr_t

Name	Type	Max Value	Description	Required
output_width	uint32_t	-	Width of output image	Yes
output_height	uint32_t	-	Height of output image	Yes
output_stride	uint32_t	-	Stride of output image	Yes

5.10.2.6. Return Value Description

Error Code	Macro Definition	Description	Common Causes and Solutions
0	HBN_STATUS_SUCESS	Success
1	HBN_STATUS_INVALID_NODE	Invalid vnode, corresponding vnode not found
2	HBN_STATUS_INVALID_NODETYPE	Invalid vnode type, corresponding vnode not found	For GDC, the vnode type should be HB_GDC
3	HBN_STATUS_INVALID_HWID	Invalid hardware module ID	For GDC, hw_id should be 0
4	HBN_STATUS_INVALID_CTXID	Invalid context ID	Can be set to AUTO_ALLOC_ID, automatically assigned by the HBN framework
5	HBN_STATUS_INVALID_OCHNID	Invalid output channel ID	GDC output channel ID is 0
6	HBN_STATUS_INVALID_ICHNID	Invalid input channel ID	GDC supports only one input channel
7	HBN_STATUS_INVALID_FORMAT	Invalid format
8	HBN_STATUS_INVALID_NULL_PTR	Null pointer
9	HBN_STATUS_INVALID_PARAMETER	Invalid parameter, version check failed
10	HBN_STATUS_ILLEGAL_ATTR	Invalid parameter
11	HBN_STATUS_INVALID_FLOW	Invalid flow, corresponding flow not found
12	HBN_STATUS_FLOW_EXIST	Flow already exists
13	HBN_STATUS_FLOW_UNEXIST	Flow does not exist
14	HBN_STATUS_NODE_EXIST	Node already exists
15	HBN_STATUS_NODE_UNEXIST	Node does not exist
16	HBN_STATUS_NOT_CONFIG	Reserved
17	HBN_STATUS_CHN_NOT_ENABLED	Channel not enabled
18	HBN_STATUS_CHN_ALREADY_ENABLED	Channel already enabled
19	HBN_STATUS_ALREADY_BINDED	Node already bound
20	HBN_STATUS_NOT_BINDED	Node not bound
21	HBN_STATUS_TIMEOUT	Timeout
22	HBN_STATUS_NOT_INITIALIZED	Not initialized
23	HBN_STATUS_NOT_SUPPORT	Channel not supported or not activated
24	HBN_STATUS_NOT_PERM	Operation not allowed
25	HBN_STATUS_NOMEM	Insufficient memory
26	HBN_STATUS_INVALID_VNODE_FD	Invalid node file descriptor
27	HBN_STATUS_INVALID_ICHNID_FD	Invalid input channel file descriptor
28	HBN_STATUS_INVALID_OCHNID_FD	Invalid output channel file descriptor
29	HBN_STATUS_OPEN_OCHN_FAIL	Failed to open output channel
30	HBN_STATUS_OPEN_ICHN_FAIL	Failed to open input channel
31	HBN_STATUS_JSON_PARSE_FAIL	JSON parsing failed
32	HBN_STATUS_REQ_BUF_FAIL	Failed to request buffer
33	HBN_STATUS_QUERY_BUF_FAIL	Failed to query buffer information
34	HBN_STATUS_SET_CONTROL_FAIL	Failed to set module control or adjustment parameters (e.g., ISP effect parameters)
35	HBN_STATUS_GET_CONTROL_FAIL	Failed to get module control or adjustment parameters (e.g., ISP effect parameters)
36	HBN_STATUS_NODE_START_FAIL	Failed to start node
37	HBN_STATUS_NODE_STOP_FAIL	Failed to stop node
38	HBN_STATUS_NODE_POLL_ERROR	Node channel poll error
39	HBN_STATUS_NODE_POLL_TIMEOUT	Node channel poll timeout
40	HBN_STATUS_NODE_POLL_FRAME_DROP	Frame drop occurred during node channel poll
41	HBN_STATUS_NODE_POLL_HUP	Descriptor hang-up during node channel poll
42	HBN_STATUS_NODE_ILLEGAL_EVENT	Illegal event during node channel poll
43	HBN_STATUS_NODE_DEQUE_ERROR	Node channel dequeue buffer error
44	HBN_STATUS_ILLEGAL_BUF_INDEX	Invalid buffer index
45	HBN_STATUS_NODE_QUE_ERROR	Node channel queue buffer error
46	HBN_STATUS_FLUSH_FRAME_ERROR	Node channel frame flush error
47	HBN_STATUS_INIT_BIND_ERROR	Error occurred during JSON parsing and binding
48	HBN_STATUS_ADD_NODE_FAIL	Failed to add node to flow
49	HBN_STATUS_WRONG_CONFIG_ID	Node ID not supported by system
50	HBN_STATUS_BIND_NODE_FAIL	Error occurred when binding node to flow
51	HBN_STATUS_INVALID_VERSION	Version mismatch between low-level driver module and upper-layer library
52	HBN_STATUS_GET_VERSION_ERROR	Failed to get version number of low-level driver module
53	HBN_STATUS_MEM_INIT_FAIL	hbmem memory initialization failed
54	HBN_STATUS_MEM_IMPORT_FAIL	hbmem memory import failed
55	HBN_STATUS_MEM_FREE_FAIL	hbmem memory release failed
56	HBN_STATUS_SYSFS_OPEN_FAIL	Failed to open system file
57	HBN_STATUS_STRUCT_SIZE_NOT_MATCH	Structure size in HAL layer does not match kernel layer
58	HBN_STATUS_RGN_UNEXIST	Unable to retrieve corresponding rgn data
59	HBN_STATUS_RGN_INVALID_OPERATION	Invalid rgn operation
60	HBN_STATUS_RGN_OPEN_FILE_FAIL	Failed to open file in rgn module
128	HBN_STATUS_ERR_UNKNOW	Unknown error