J5 DVB实战教程（6）-基于J5芯片的GDC模块功能详解及API调用说明

模块概述

1. 硬件特性

• GDC GUI Tools
  一种方便用户设置转换参数的工具。仿真成功后，可生成配置文件参数。
• GDC cfg bin 二进制序列
  系统软件使用配置文件参数，调用libgdcbin库生成GDC cfg bin 二进制序列，供GDC硬件读取处理。
• GDC硬件
  执行存储器到存储器转换的硬件；即GDC的输入输出方式都是offline模式。

三者流程上的关系图如下：

2. 功能描述

3.接口使用说明

• 接口函数列表

• hb_vio_gen_gdc_cfg
  【函数声明】
  int hb_vio_gen_gdc_cfg(param_t *gdc_param, window_t *windows, uint32_t wnd_num, void **cfg_buf, uint64_t *cfg_size)；
  【功能描述】
  u3000生成GDC配置。
  【参数描述】

  参数名称	描述	输入/输出
  param_t *gdc_param	图像基本信息	输入
  window_t *windows	图像处理参数信息	输入
  uint32_t wnd_num	图像处理信息数量，若有1个window则填写1。	输入
  void **cfg_buf	生成的bin buffer, buffer 由函数内部分配，使用完成后需要释放。	输出
  uint64_t *cfg_siz	生成bin buffer 长度。	输出

• hb_vio_set_gdc_cfg
  【函数声明】
  int hb_vio_set_gdc_cfg(uint32_t pipeline_id, uint32_t* cfg_buf, uint64_t cfg_size)
  【功能描述】
  u3000设置GDC参数。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	pipe_line 号	输入
  uint32_t* cfg_buf	gdc-bin buf	输入
  uint64_t cfg_size	gdc-bin buf 长度	输入

• hb_vio_free_gdc_cfg
  【函数声明】
  u3000void hb_vio_free_gdc_cfg(uint32_t* cfg_buf)
  【功能描述】
  u3000释放之前分配的，用于存放GDC配置的内存。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t* cfg_buf	gdc-bin buf	输入

• hb_vio_run_gdc
  【函数声明】
  u3000u3000int32_t hb_vio_run_gdc(uint32_t pipeline_id,
  u3000u3000 hb_vio_buffer_t * src_img_info,
  u3000u3000 hb_vio_buffer_t * dst_img_info,
  u3000u3000 int32_t rotate)
  【功能描述】
  u3000u3000进行GDC图像处理。
  u3000u3000注：src_img_info，即输入buffer，通过调用hb_vio_get_data获取。dst_img_info，即输出buffer，是从hb_vio_run_gdc函数内部获取到，并传递给用户。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	软件通道号	输入
  hb_vio_buffer_t * src_img_info	输入数据图像信息	输入
  hb_vio_buffer_t * dst_img_info	输出数据图像信息	输出
  int32_t rotate	要翻转的角度	输入

• hb_vio_free_gdcbuf
  【函数声明】
  u3000int32_t hb_vio_free_gdcbuf(uint32_t pipeline_id, hb_vio_buffer_t * dst_img_info)
  【功能描述】
  u3000u3000释放GDC图像的buffer。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	软件通道号	输入
  hb_vio_buffer_t * dst_img_info	数据图像信息	输入

• hb_vio_set_gdc_cfg_opt
  u3000【函数声明】
  u3000u3000int32_t hb_vpm_set_gdc_cfg_opt(uint32_t pipeline_id,
  u3000u3000 uint32_t gdc_id,
  u3000u3000 const uint32_t* cfg_buf,
  u3000u3000 uint64_t cfg_size)
  u3000【功能描述】
  u3000u3000设置GDC参数。
  u3000u3000J5 GDC硬件只有一个； id号固定是0，和hb_vio_set_gdc_cfg功能没有区别。
  u3000【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	pipe_line 号	输入
  uint32_t gdc_id	GDC硬件id	输入
  uint32_t* cfg_buf	gdc-bin buf	输入
  uint64_t cfg_size	gdc-bin buf 长度	输入

• hb_vio_run_gdc_opt
  u3000【函数声明】
  u3000u3000int32_t hb_vio_run_gdc_opt(uint32_t pipeline_id,
  u3000u3000 uint32_t gdc_id,
  u3000u3000 const hb_vio_buffer_t * src_img_info,
  u3000u3000 hb_vio_buffer_t * dst_img_info,
  u3000u3000 int32_t rotate)
  u3000【功能描述】
  u3000u3000进行GDC图像处理。
  u3000u3000但J5 GDC硬件只有一个； id号固定是0，和hb_vio_run_gdc功能没有区别。
  u3000【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	软件通道号	输入
  uint32_t gdc_id	GDC硬件id	输入
  hb_vio_buffer_t * src_img_info	输入数据图像信息	输入
  hb_vio_buffer_t * dst_img_info	输出数据图像信息	输出
  int32_t rotate	要翻转的角度	输入

• hb_vio_run_gdc_adv
  u3000【函数声明】
  u3000u3000int32_t hb_vio_run_gdc_adv(
  u3000u3000 uint32_t pipeline_id,
  u3000u3000 uint32_t gdc_id,
  u3000u3000 const gdc_config_t *gdc_cfg,
  u3000u3000 const hb_vio_buffer_t * src_img_info,
  u3000u3000 hb_vio_buffer_t * dst_img_info,
  u3000u3000 int32_t rotate)
  u3000【功能描述】
  u3000u3000使用用户自定义的配置，进行GDC图像处理。
  注：与hb_vio_run_gdc_adv_user的差异是，该接口的输出buffer由函数内部获取。相对于 hb_vio_run_gdc，该接口多一个可自定义配置的功能，hb_vio_set_gdc_cfg无需调用。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	软件通道号	输入
  uint32_t gdc_id	GDC硬件id	输入
  const gdc_config_t *gdc_cfg	用户自定义的配置	输入
  hb_vio_buffer_t * src_img_info	输入数据图像信息	输入
  hb_vio_buffer_t * dst_img_info	输出数据图像信息	输出
  int32_t rotate	要翻转的角度	输入

• hb_vio_run_gdc_adv_user
  【函数声明】
  u3000int32_t hb_vio_run_gdc_adv_user(
  u3000u3000 uint32_t pipeline_id,
  u3000u3000 uint32_t gdc_id,
  u3000u3000 const gdc_config_t *gdc_cfg,
  u3000u3000 const hb_vio_buffer_t * src_img_info,
  u3000u3000 hb_vio_buffer_t * dst_img_info,
  u3000u3000 int32_t rotate)
  【功能描述】
  u3000使用用户自定义的配置，并且指定输出buffer的地址，进行GDC图像处理。
  注：与hb_vio_run_gdc_adv的差异是，该接口的输出buffer由外部分配。相对于hb_vio_run_gdc，该接口多一个可自定义配置的功能，hb_vio_set_gdc_cfg无需调用。
  【参数描述】

  参数名称	描述	输入/输出
  uint32_t pipeline_id	软件通道号	输入
  uint32_t gdc_id	GDC硬件id	输入
  const gdc_config_t *gdc_cfg	用户自定义的配置	输入
  hb_vio_buffer_t * src_img_info	输入数据图像信息	输入
  hb_vio_buffer_t * dst_img_info	输出数据图像信息	输出

4. 接口调用流程

• 回灌流程
  回灌流程，指的是系统存储中读取文件，作为GDC的输入图像，进行处理。
  典型调用流程图如下：
  
• 使用自定义GDC配置，和默认使用的区别，主要是hb_vio_set_gdc_cfg 的内容由接口直接带入，无需hb_vio_set_gdc_cfg接口。
  调用流程图如下：
  
• 使用自定义GDC配置，加上层分配输出buffer的调用流程图如下：
  u3000
• 模块间处理流程
  模块间处理流程，指的是从其他硬件IP模块输出的数据拿来作为GDC的输入图像，进行处理。
  典型的是从PYM 输出某一层的YUV数据，拿来作为GDC图像处理的输入。处理流程图如下：
  
• GDC driver与PYM driver底层联动功能
  该功能有关的Json配置如下：

  layer_num_transfer_gdc代表选取PYM输出层直接传递给GDC进行处理，PYM输出层的枚举如下：

  在已生成GDC binary的情况下，实际软件工作流程如下：
  

  5. 关键数据结构体

• frame_format_t
  【结构定义】
  u3000u3000typedef enum {
  u3000u3000FMT_UNKNOWN,
  u3000u3000FMT_LUMINANCE,
  FMT_PLANAR_444,
  FMT_PLANAR_420,
  FMT_SEMIPLANAR_420
  u3000u3000} frame_format_t;
  【功能描述】
  u3000u3000数据处理格式
  【成员说明】

  成员	含义
  FMT_UNKNOWN	暂不支持
  FMT_LUMINANCE	暂不支持
  FMT_PLANAR_444	暂不支持
  FMT_PLANAR_420	暂不支持
  FMT_SEMIPLANAR_420	nv12格式使用该项

Note : J5中使用FMT_SEMIPLANAR_420类型，若图像类型使用不当会造成输出异常。

• resolution_t
  u3000【结构定义】
  u3000u3000typedef struct {
  uint32_t w;
  uint32_t h;
  u3000u3000} resolution_t;
  u3000【功能描述】
  u3000u3000分辨率。
  u3000【成员说明】

  成员	含义
  uint32_t w	width in pixels
  uint32_t h	height in pixels

  • param_t

Note : 一般情况下diameter应保持与input.height一致。

• rect_t
  u3000【结构定义】
  u3000u3000typedef struct {
  int32_t x;
  int32_t y;
  int32_t w;
  int32_t h;
  u3000u3000} rect_t;
  u3000【功能描述】
  u3000u3000区域信息结构体。
  u3000【成员说明】

  成员	含义
  int32_t x	Start x coordinate
  int32_t y	Start y coordinate
  int32_t w	width
  int32_t h	height

• point_t
  u3000【结构定义】
  typedef struct {
  double x;
  double y;
  u3000u3000} point_t;
  u3000【功能描述】
  u3000u3000坐标点信息结构体。
  u3000【成员说明】

  成员	含义
  double x	x coordinate
  double y	y coordinate

• transformation_t
  u3000【结构定义】
  u3000u3000typedef enum {
  PANORAMIC,
  CYLINDRICAL,
  STEREOGRAPHIC,
  UNIVERSAL,
  CUSTOM,
  AFFINE,
  DEWARP_KEYSTONE
  u3000u3000} transformation_t;
  u3000【功能描述】
  u3000u3000转换模式的枚举。
  u3000【成员说明】

• custom_tranformation_t
  【结构定义】
  u3000u3000typedef struct {
  uint8_t full_tile_calc;
  uint16_t tile_incr_x;
  uint16_t tile_incr_y;
  int32_t w;
  int32_t h;
  double centerx;
  double centery;
  point_t* points;
  u3000u3000} custom_tranformation_t;
  【功能描述】
  【成员说明】

  成员	含义
  uint8_t full_tile_calc	full tile calculation flag
  uint16_t tile_incr_x	tile increment in x
  uint16_t tile_incr_y	tile increment in y
  int32_t w	自定义转换网格中水平方向上的数字或点
  int32_t h	自定义转换网格中垂直方向的数字或点
  double centerx	center along x axis
  double centery	center along y axis
  point_t* points	config.txt转换序列, 数量 = w*h

• window_t
  u3000【结构定义】
  u3000u3000typedef struct {
  rect_t out_r;
  transformation_t transform;
  rect_t input_roi_r;
  int32_t pan;
  int32_t tilt;
  double zoom;
  double strength;
  double strengthY;
  double angle;
  double elevation;
  double azimuth;
  int32_t keep_ratio;
  double FOV_h;
  double FOV_w;
  double cylindricity_y;
  double cylindricity_x;
  char custom_file[128];
  custom_tranformation_t custom;
  double trapezoid_left_angle;
  double trapezoid_right_angle;
  u3000u3000} window_t;
  【功能描述】
  【成员说明】

  成员	含义
  rect_t out_r	Output window position and size
  transformation_t transform	Used transformation
  rect_t input_roi_r	roi 区域
  int32_t pan	沿变换曲面沿水平方向以给定数量的像素偏移变换网格。
  int32_t tilt	沿变换曲面沿垂直方向将变换网格偏移给定数量的像素。
  zoom	按提供的因子缩放转换输出
  double strength	沿X轴的变换强度（非负参数）
  double strengthY	沿Y轴的变换强度（非负参数）。
  double angle(rotation)	区域将在其轴上旋转的角度
  double elevation	指定主投影轴的角度（度）
  double azimuth	指定主投影轴的角度，从北向（正向东）顺时针计数
  int32_t keep_ratio	在水平和垂直方向上保持相同的拉伸强度（enable/disable）
  double FOV_h	垂直尺寸输出视场的大小（度）
  double FOV_w	水平尺寸输出视场的大小（度）
  double cylindricity_y	垂直方向目标投影形状的圆柱度水平
  double cylindricity_x	水平方向目标投影形状的圆柱度水平
  char custom_file[128]	File name of the file containing custom transformation description
  custom_tranformation_t custom	Parsed custom transformation structure
  double trapezoid_left_angle	Left Acute angle in degrees between trapezoid base and leg
  double trapezoid_right_angle	Right Acute angle in degrees between trapezoid base and leg

6.错误返回值说明

• 错误描述
  以下表格列出GDC API可能出现的错误返回值及原因。

  VPM GDC API	可能产生的返回值码	错误码说明
  int32_t hb_vio_free_gdcbuf(uint32_t pipeline_id, hb_vio_buffer_t * dst_img_info)	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_GDC_BUF_NULL	输入的GDC buffer参数指针为空
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始化过。
  	HB_VIO_INVALID_DATATYPE	数据类型无效
  	HB_VIO_PIPE_ENTITY_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_INVALID_DATATYPE	获取GDC 数据的时候，设置的数据类型是无效的
  	HB_VIO_BUF_TYPE_INVALID	无效的内存类型
  	HB_VIO_BUF_NO_MARK_IN_USER_QUEUE	未在GDC 内存 user 队列找到对应的buffer
  	HB_VIO_GET_PEEK_BUF_NULL	获取GDC内存 user 队列的buffer失败
  	HB_VIO_GDC_BUF_MANAGER_NULL_POINTER	GDC的buffer 管理器指针为空
  int32_t hb_vio_run_gdc(uint32_t pipeline_id,hb_vio_buffer_t * src_img_info,hb_vio_buffer_t * dst_img_info,int32_t rotate)	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_GDC_RUN_SRC_BUF_NULL	GDC 源内存指针为空
  	HB_VIO_GDC_RUN_DST_BUF_NULL	GDC目标内存指针为空
  	HB_VIO_GDC_RUN_INVALID_DEGREE	输入的GDC 旋转角度无效
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始化 过。
  	HB_VIO_GDC_NULL_POINTER	GDC 实例体指针为空
  	HB_VIO_GDC_BUF_MANAGER_NULL_POINTER	GDC内存管理器指针为空
  	HB_VIO_GDC_RUN_INVALID_BUF	GDC的buffer 信息配置不对
  	HB_VIO_GDC_BUF_MGR_FAIL	获取GDC输出buffer 失败
  	HB_VIO_GDC_INVALID_CONFIG	GDC的配置信息不对
  	HB_VIO_GDC_BUF_PLANE_COUNT_INVALID	GDC 内存的plane count 非法
  	HB_VIO_GDC_PROCESS_FAIL	GDC底层设备处理失败
  int32_t hb_vio_gen_gdc_cfg(param_t *gdc_parm, window_t *wnds,uint32_t wnd_num, void **cfg_buf, uint64_t *cfg_size)	HB_VIO_GDC_GEN_PARAM_NULL	输入的GDC 参数的指针为空
  	HB_VIO_GDC_GEN_WINDOW_NULL	输入的GDC窗口指针为空
  	HB_VIO_GDC_GEN_CFG_NULL	输入的GDC配置内存的指针为空
  	HB_VIO_GDC_GEN_CFG_SIZE_NULL	输入的GDC 配置大小的指针为空
  	HB_VIO_GDC_GEN_INVALID_PARAMETER	GDC参数的不对
  	HB_VIO_GDC_GEN_WIN_NUM_ZERO	输入的窗口数量为0
  	HB_VIO_GDC_GEN_NULL_POINTER	输入的GDC 窗口的custom 指针为空
  	HB_VIO_GDC_GEN_INIT_FAIL	GDC初始化失败
  int32_t hb_vio_set_gdc_cfg(uint32_t pipeline_id, uint32_t* cfg_buf, uint64_t cfg_size)	HB_VIO_GDC_SET_CFG_NULL	输入GDC配置内存的指针为空
  	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始化过。
  	HB_VIO_INVALID_OPERATION	操作Pipeline 的状态不对
  	HB_VIO_GDC_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_SET_CFG_SIZE_INVALID	GDC输入的配置size 大小非法
  	HB_VIO_GDC_CFG_BIN_NULL	GDC配置的bin文件指针为空
  	HB_VIO_GDC_UPDATE_FAIL	GDC配置bin文件刷新失败
  int32_t hb_vio_set_gdc_cfg_opt(uint32_t pipeline_id, uint32_t* cfg_buf, uint64_t cfg_size)	HB_VIO_GDC_SET_CFG_NULL	输入GDC配置内存的指针为空
  	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始化过。
  	HB_VIO_INVALID_OPERATION	操作Pipeline 的状态不对
  	HB_VIO_GDC_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_SET_CFG_SIZE_INVALID	GDC输入的配置size 大小非法
  	HB_VIO_GDC_CFG_BIN_NULL	GDC配置的bin文件指针为空
  	HB_VIO_GDC_UPDATE_FAIL	GDC配置bin文件刷新失败
  	HB_VIO_GDC_INVALID_HW_ID	无效的GDC硬件id
  int32_t hb_vio_run_gdc_opt(uint32_t pipeline_id, uint32_t gdc_id, hb_vio_buffer_t * src_img_info, hb_vio_buffer_t * dst_img_info,int32_t rotate)	HB_VIO_GDC_INVALID_HW_ID	无效的GDC硬件id
  	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_GDC_RUN_SRC_BUF_NULL	GDC源内存指针为空
  	HB_VIO_GDC_RUN_DST_BUF_NULL	GDC目标内存指针为空
  	HB_VIO_GDC_RUN_INVALID_DEGREE	输入的GDC 旋转角度无效
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始化过。
  	HB_VIO_GDC_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_BUF_MGR_FAIL	获取GDC输出buffer 失败
  	HB_VIO_GDC_RUN_INVALID_BUF	GDC的buffer 信息配置不对
  	HB_VIO_GDC_GET_OUTPUT_BUF_FAIL	获取GDC的输出buffer 失败
  	HB_VIO_GDC_INVALID_CONFIG	GDC的配置信息不对
  	HB_VIO_GDC_BUF_PLANE_COUNT_INVALID	GDC内存的plane count 非法
  	HB_VIO_GDC_PROCESS_FAIL	GDC 底层设备处理失败
  int32_t hb_vio_run_gdc_adv(uint32_t pipeline_id, uint32_t gdc_id,const gdc_config_t *gdc_cfg,hb_vio_buffer_t *src_img_info,hb_vio_buffer_t *dst_img_info,int32_t rotate)	HB_VIO_GDC_INVALID_HW_ID	无效的GDC硬件id
  	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_GDC_RUN_SRC_BUF_NULL	GDC 源内存指针为空
  	HB_VIO_GDC_RUN_DST_BUF_NULL	GDC 目标内存指针为空
  	HB_VIO_GDC_RUN_INVALID_DEGREE	输入的GDC旋转角度无效
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始过。
  	HB_VIO_GDC_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_BUF_MGR_FAIL	获取GDC输出buffer 失败
  	HB_VIO_GDC_RUN_INVALID_BUF	GDC的buffer 信息配置不对
  	HB_VIO_GDC_INVALID_CONFIG	GDC的配置信息不对
  	HB_VIO_GDC_BUF_PLANE_COUNT_INVALID	GDC内存的plane count 非法
  	HB_VIO_GDC_PROCESS_FAIL	GDC底层设备处理失败
  	HB_VIO_GDC_RUN_ADV_CFG_NULL	GDC输入的高级配置的指针为空
  int32_t hb_vio_run_gdc_adv_user(uint32_t pipeline_id, uint32_t gdc_id,const gdc_config_t *gdc_cfg,hb_vio_buffer_t *src_img_info,hb_vio_buffer_t *dst_img_info,int32_t rotate)	HB_VIO_GDC_INVALID_HW_ID	无效的GDC硬件id
  	HB_VIO_PIPELINE_ID_INVALID	输入的pipeline id 非法
  	HB_VIO_GDC_RUN_SRC_BUF_NULL	GDC 源内存指针为空
  	HB_VIO_GDC_RUN_DST_BUF_NULL	GDC 目标内存指针为空
  	HB_VIO_GDC_RUN_INVALID_DEGREE	输入的GDC旋转角度无效
  	HB_VIO_PIPELINE_NULL_POINTER	配置的pipeline id 对应的数据管理指针为空，一般是输入的pipeline id 没有初始过。
  	HB_VIO_GDC_NULL_POINTER	GDC实例体指针为空
  	HB_VIO_GDC_BUF_MGR_FAIL	获取GDC输出buffer 失败
  	HB_VIO_GDC_RUN_INVALID_BUF	GDC的buffer 信息配置不对
  	HB_VIO_GDC_INVALID_CONFIG	GDC的配置信息不对
  	HB_VIO_GDC_BUF_PLANE_COUNT_INVALID	GDC内存的plane count 非法
  	HB_VIO_GDC_PROCESS_FAIL	GDC底层设备处理失败
  	HB_VIO_GDC_RUN_ADV_CFG_NULL	GDC输入的高级配置的指针为空