# GDC_Overview

## 概述

- GDC API 属于 HBN 框架的一部分， 作为一个 vnode，可以和其他 vnode 连接起来形成 vflow。关于 HBN 框架，可以参考 [ HBN 框架 ](../multimedia_development/1-HBN_API_zh_CN.html)。
- GDC 模块只支持 offline 的模式，从 DDR 读数据，处理完再写到 DDR。
- GDC 模块的使用需要提前准备配置 GDC 的模块的配置参数文件 bin 文件，这个文件由 GDC Tool 进行仿真直接保存生成 GDC bin 文件 或者 保存为 json 后通过 GDC bin API 生成。

使用 GDC 模块主要涉及以下三个部分：

| 模块     | 功能描述                      |
|-------------|------------------------------|
| GDC Tool  | 用于效果仿真，并生成 GDC 配置参数文件（layout.json 或 config.bin）。|
| GDC bin API | 用于 GDC bin 生成。 |
| GDC API     | 遵循 HBN 框架，用于打开、关闭 GDC 节点及配置 GDC 属性。 |

### GDC Tool

- GDC Tool 用于效果仿真，仿真完成后可以保存 GDC 配置参数文件（layout.json 或 config.bin）。
- GDC Tool 提供六种变换模式： Affine， Equisolid， Equisolid(cylinder)， Equidistant， Custom， Keystone+dewarping。
- GDC Tool 使用请参考 [ GDC Tool 介绍 ](../multimedia_development/8.2-GDC_Tool_zh_CN.html)。

### GDC bin API

- GDC bin API 用于生成 GDC bin 文件。
- 支持通过`hbn_gen_gdc_bin_json`或者`hbn_gen_gdc_bin`接口生成 GDC bin。
- GDC bin API 经常和 GDC Tool 一起搭配使用，使用 GDC Tool 生成 `layout.json`后，需要使用 GDC bin API 生成 GDC bin。
- 有关 GDC bin API 使用，请参考 [ GDC bin API ](../multimedia_development/8.1-GDC_Bin_API_zh_CN.html)。

### GDC API

- GDC API 用于打开和配置 GDC 节点、创建 vflow，以及处理 GDC 数据。
- 下图是两种 GDC 场景的 vflow 例子（场景 1 中 回灌 的含义：数据源来自 DDR 的情况）：

![image-20250106-165816](./_static/_images/8.1-GDC_Bin_API_zh_CN/image-20250106-165816.png)

- 有关 GDC API 使用请参考 [ GDC API ](../multimedia_development/8.3-GDC_API_zh_CN.html)。


## 使用方法

在使用 GDC 时，GDC Tool、GDC bin API 和 GDC API 是相辅相成的工具。以下是生成并使用 GDC bin 的四种常用方法：

1. **方法 1**：
   - 使用 GDC Tool 生成 `layout.json` 文件。
   - 通过 `hbn_gen_gdc_bin_json` 接口解析 JSON 文件，生成并保存为 GDC bin 文件。
   - 使用时，将 GDC bin 文件读取到 hbmem 分配的内存中，通过 `hbn_vnode_set_attr` 接口应用到 GDC 节点。

2. **方法 2**：
   - 使用 GDC Tool 生成 `layout.json` 文件。
   - 通过 `hbn_gen_gdc_bin_json` 接口解析 JSON 文件，生成 GDC bin 并保存到外部缓冲区（buf）。
   - 使用 `hbn_vnode_set_attr` 接口配置并应用到 GDC 节点。

3. **方法 3**：
   - 使用 GDC Tool 生成 `layout.json` 文件。
   - 通过 `hbn_gen_gdc_bin` 接口直接读取 JSON 文件中的参数，生成 GDC bin 并保存到外部缓冲区（buf），该过程无需解析 JSON 文件。
   - 使用 `hbn_vnode_set_attr` 接口配置并应用到 GDC 节点。

4. **方法 4**：
   - 使用 GDC Tool 直接生成 `config.bin`（即 GDC bin 文件）。
   - 将 `config.bin` 文件读取到 hbmem 分配的内存中，通过 `hbn_vnode_set_attr` 接口应用到 GDC 节点，此过程无需使用 `GDC bin API` 接口。

### 场景推荐

- **固定效果场景**：如果场景效果较为简单且固定（例如鱼眼矫正），建议使用 `方法 4` GDC Tool 提前生成 GDC bin 文件，并将其读取到 hbmem 分配的内存中并应用到 GDC 节点。

- **动态效果场景**：如果场景需要每帧动态调整效果，建议使用  GDC bin API 实时生成配置文件。
