# 二维图形处理 - 2D GPU

## 模块描述
2D GPU 支持如下功能（针对 2D 图像的处理）：<br>
- 位块传输（ BitBlt）
- 拉伸位图传输（ Stretch Blit）
- 矩形填充和清除（ Rectangle fill and clear）
- 单次滤波位块传输 （ One Pass Filter Blit）
- 透明度混合（ Alpha blending）
- 支持顺时针或逆时针方向的 90 ° 、 180 ° 、 270 ° 旋转
- 支持镜像翻转
- 支持 ROP（光栅操作码）
- 支持裁剪
- 支持色彩空间转换，即 YUV 转 RGB 和 RGB 转 YUV（ Color Space Convert）
- 多源融合

**注意**: 使用 GPU2D 做 YUV 之间数据转换时会存在误差：
1. YUV 与 RGB 之间格式转换是存在误差的
2. 由于硬件在完成 YUV 格式转换时（比如 YUYV 转 NV12 ），先做 YUYV 转 RGB，再从 RGB 转换为 NV12


### 基础规格
- 最大分辨率为 4k
- 处理性能 4k@90fps

**注意**： 4k 指的是 3840 * 2160
### 支持格式

| **格式**                           | **输入** | **输出** |
|:---------------------------------:|:------:|:------:|
| A8                                | Y      | Y      |
| R8                                | Y      | Y      |
| A1R5G5B5                          | Y      | Y      |
| A4R4G4B4                          | Y      | Y      |
| X1R5G5B5                          | Y      | Y      |
| X4R4G4B4                          | Y      | Y      |
| R5G6B5                            | Y      | Y      |
| RG16                              | Y      | Y      |
| X8R8G8B8                          | Y      | Y      |
| A8R8G8B8                          | Y      | Y      |
| A2R10G10B10                       | Y      | Y      |
| YUY2 (packed YUV422)              | Y      | Y      |
| UYVY (packed YUV422)              | Y      | Y      |
| YV12 (planar YUV420)              | Y      | Y      |
| I010(10bit planar YUV420)         | Y      | Y      |
| NV12 (semi-planar YUV420)         | Y      | Y      |
| NV16 (semi-planar YUV422)         | Y      | Y      |
| P010(semi-planar YUV420)          | Y      | Y      |
| NV12-10bit (semi-planar YUV420)   | Y      | Y      |
| NV16-10bit (semi-planar YUV422)   | Y      | **N**  |
| Planar RGB888/YUV444(8bit)        | Y      | Y      |

- Y：表示支持
- N：表示不支持

### 对齐要求

表格中部分标题解释如下（后面有详细描述）：
- **平面数量**：定义图像数据被分成几个部分。
- **平面每像素位数**：定义每个平面中每个像素使用的位数。
- **水平像素宽度 / 垂直像素高度**：定义每个平面中像素在水平方向和垂直方向的布局。
- **平面内行对齐**：定义每一行数据的内存对齐。
- **每平面地址对齐**：定义平面起始地址的内存对齐。

| 格式名称         | BPP | 平面数量 | 平面每像素位数    | 水平像素宽度 | 垂直像素高度 | 每平面字节对齐  | 每平面地址对齐 |
|------------------|------------|----------|-------------------|--------------|--------------|----------------|----------------|
| A8               | 8          | 1        | 8, 0, 0           | 1            | 1            | 1, 0, 0        | 1, 0, 0        |
| A1R5G5B5         | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| A4R4G4B4         | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| X1R5G5B5         | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| X4R4G4B4         | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| R5G6B5           | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| RG16             | 16         | 1        | 16, 0, 0          | 1            | 1            | 2, 0, 0        | 2, 0, 0        |
| X8R8G8B8         | 32         | 1        | 32, 0, 0          | 1            | 1            | 4, 0, 0        | 4, 0, 0        |
| A8R8G8B8         | 32         | 1        | 32, 0, 0          | 1            | 1            | 4, 0, 0        | 4, 0, 0        |
| A2R10G10B10      | 32         | 1        | 32, 0, 0          | 1            | 1            | 4, 0, 0        | 4, 0, 0        |
| YUYV             | 16         | 1        | 16, 0, 0          | 2            | 1            | 4, 0, 0        | 4, 0, 0        |
| UYVY             | 16         | 1        | 16, 0, 0          | 2            | 1            | 4, 0, 0        | 4, 0, 0        |
| YV12             | 24         | 3        | 8, 8, 8           | 2            | 2            | 64, 32, 32     | 64, 64, 64     |
| I010             | 48         | 3        | 16, 16, 16        | 2            | 2            | 128, 64, 64    | 128, 64, 64    |
| NV12             | 16         | 2        | 8, 8, 0           | 2            | 2            | 64, 64, 0      | 64, 64, 0      |
| NV16             | 16         | 2        | 8, 8, 0           | 2            | 1            | 64, 64, 0      | 64, 64, 0      |
| P010             | 32         | 2        | 16, 16, 0         | 2            | 2            | 128, 128, 0    | 128, 128, 0    |
| NV12_10BIT       | 24         | 2        | 16, 8, 0          | 4            | 2            | 80, 80, 0      | 80, 80, 0      |
| NV16_10BIT       | 32         | 2        | 16, 16, 0         | 2            | 1            | 40, 40, 0      | 80, 80, 0      |
| Planar RGB888    | 24         | 3        | 8, 8, 8           | 1            | 1            | 4, 4, 4        | 4, 4, 4        |

表格中标题详细解释如下：
#### 平面数量
- **定义**：指图像数据在内存中被分成的独立部分数量。
- **解释**：
  - 图像数据可以存储在一个或多个平面中。平面是指图像数据的一个独立部分，用于存储特定的颜色分量或亮度 / 色度信息。
  - **单平面格式**：图像数据全部存在一个平面中，通常用于 RGB 格式，如 A8R8G8B8 、 RGB888 。
  - **多平面格式**：图像数据被分成多个平面存储，通常用于 YUV 格式，如 YV12 、 NV12 等。
    - **双平面**：如 NV12 ， Y 分量在一个平面， UV 分量在另一个平面。
    - **三平面**：如 YV12 ， Y、 U、 V 分量分别存储在三个独立的平面中。

#### 平面每像素位数 （ BPP）
- **定义**：表示每个平面中每个像素使用的位数。
- **解释**：
  - 对于单平面格式，如 A8R8G8B8 ，每个像素的位数是 32 位，因此平面每像素位数为 32 。
  - 对于多平面格式，如 YV12 ， Y 平面是 8 位， U 平面和 V 平面也是 8 位。
  - 每个平面的位数可以不同，如 NV12 的 Y 平面是 8 位，而 UV 平面也是 8 位，但合在一起仍然为 16 位。

#### 水平像素宽度（ aWidthPixel）
- **定义**：指图像中每个平面在水平方向上所包含的像素数。
- **解释**：
  - 通常为 1 ，表示每个像素是独立存储的。
  - 在某些 YUV 格式中，色度分量的像素宽度可能是亮度分量的一半，比如 YUV 4:2:0 格式中， U 和 V 平面的宽度只有 Y 平面的一半。

#### 垂直像素高度（ aHeightPixel）
- **定义**：指图像中每个平面在垂直方向上所包含的像素数。
- **解释**：
  - 和水平像素宽度类似，通常为 1 。
  - 但是，在一些 YUV 格式（如 YUV 4:2:0 ）中，色度分量的高度是亮度分量的一半，这样可以减少存储空间。

#### 平面内行对齐（ aStrideByte）
- **定义**：指在存储每一行图像数据时，确保数据行在内存中的对齐字节数。
- **解释**：
  - 目的是为了提高访问效率，在 CPU 或 GPU 读取数据时减少内存访问的不连续性。
  - 例如， NV12 的 Y 平面和 UV 平面的字节对齐为 64 字节，这意味着每一行的数据长度会被填充至 64 的倍数。

#### 每平面地址对齐（ aAddressByte）
- **定义**：指每个平面的起始地址在内存中应当对齐的字节数。
- **解释**：
  - 用于确保图像平面的起始地址是某个特定字节边界的倍数（如 16 字节、 32 字节或 64 字节），从而提高内存访问的效率。
  - 例如， NV12 格式的 Y 和 UV 平面通常需要 64 字节的地址对齐，这可以减少内存访问时间。



## 参考示例
- GPU 2D 部分示例代码可以参考 [sample_gpu_2d](../samples/sample_gpu_2d.html)  章节

## API 参考

| API 接口                        | 接口功能                      |
|---------------------------------|------------------------------|
|n2d_open| 打开 GPU2D 模块，一个进程只能打开一次 |
|n2d_close| 关闭 GPU2D 模块 |
|n2d_commit| 将待执行的指令缓冲区送入 GPU 硬件 |
|n2d_commit_ex| 将待执行的指令缓冲区送入 GPU 硬件 |
|n2d_allocate| 申请一块内存空间，用于存储 GPU 操作时的上下文和资源 |
|n2d_free| 释放 n2d_allocate 申请的内存 |
|n2d_map| 将用户空间申请到的内存地址映射给 GPU 使用 |
|n2d_unmap| 释放之前由 `n2d_map` 映射的内存，并将映射关系解除 |
|n2d_is_feature_support| 查询硬件是否支持传入的功能 |
|n2d_blit| 执行 位块传输 操作 |
|n2d_filterblit| 执行 位块传输 操作并且使用 FIR 重采样滤波器进行高质量的图像缩放 |
|n2d_multisource_blit| 多个源进行多源位块传输 |
|n2d_fill| 用指定的颜色填充或清除指定的缓冲区 |
|n2d_set| 设置配置 |

## API 接口说明

<span id="n2d_open"/> </span>

### n2d_open
#### 【函数声明】
```c
n2d_error_t n2d_open(n2d_void)
```

#### 【功能描述】
 - 如果想使用 N2D 功能，必须先调用 `n2d_open` 获取 GPU 的上下文和资源。一个进程只能有一个 GPU 上下文。
 - 如果这是 N2D 硬件上第一次初始化， GPU 会被上电使能。
 - 如果在多进程使用的情况下，后调用的 `n2d_open` 会销毁前面进程调用 `n2d_open` 的获取的资源。

#### 【参数描述】
 - 无
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)

<span id="n2d_close"/> </span>

### n2d_close
#### 【函数声明】
```c
n2d_error_t n2d_close(n2d_void)
```

#### 【功能描述】
 - 这个函数会将之前将 `n2d_open` 打开的上下文关闭，然后销毁所有资源，并释放所有内存。
 - 如果这个函数释放了 GPU 硬件上面最后的资源， GPU 硬件将会被关闭 。

#### 【参数描述】
 - 无
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)


<span id="n2d_commit"/> </span>

### n2d_commit
#### 【函数声明】
```c
 n2d_error_t n2d_commit(n2d_void)
```

#### 【功能描述】
 - 将待执行的指令缓冲区送入 GPU 硬件。
 - **该函数会一直堵塞，直到 GPU 硬件完成处理才返回**。

#### 【参数描述】
 - 无

#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)

<span id="n2d_commit_ex"/> </span>

### n2d_commit_ex
#### 【函数声明】
```c
n2d_error_t n2d_commit_ex(n2d_bool_t stall)
```

#### 【功能描述】
 - 将待执行的指令缓冲区送入 GPU 硬件。

#### 【参数描述】
 -  [IN] `stall`
     - 当 `stall` 为 `N2D_TRUE` 时，该函数会一直堵塞，**直到 GPU 硬件完成处理才返回**。
     - 当 `stall` 位 `N2D_FALSE` 时，该函数会 **立刻** 返回。

#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)

<span id="n2d_allocate"/> </span>

### n2d_allocate
#### 【函数声明】
```c
n2d_error_t n2d_allocate (n2d_buffer_t *buffer)
```

#### 【功能描述】
 - 这个函数会申请一块内存空间，用于存储 GPU 操作时的上下文和资源。
 - 申请空间的高宽和格式等都要提前在 `buffer` 指向的结构体里面配置好。
 - 这个函数要和 `n2d_free` 配对使用。

#### 【参数描述】
 -  [IN] `buffer`
     - 指向 `n2d_buffer_t` 结构体的指针，该结构体应该提前配置好高宽和格式。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)


<span id="n2d_free"/> </span>

### n2d_free
#### 【函数声明】
```c
n2d_error_t n2d_free (n2d_buffer_t *buffer)
```

#### 【功能描述】
 - 这个函数会将之前由 `n2d_allocate` 申请的 `buffer` 内存资源释放。
 - 这个函数要和 `n2d_allocate` 配对使用。

#### 【参数描述】
 -  [IN] `buffer`
     - 指向 `n2d_buffer_t` 结构体的指针，该结构体需要使用过 `n2d_allocate` 申请内存。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)

<span id="n2d_map"/> </span>

### n2d_map
#### 【函数声明】
```c
n2d_error_t n2d_map (n2d_buffer_t *buffer)
```

#### 【功能描述】
 - 这个函数用于将用户空间申请到的内存地址映射给 GPU 使用。
 - 内存必须是连续的。
 - 需要和 `n2d_unmap` 成对使用。

#### 【参数描述】
 -  [IN] `buffer`
     - 指向 `n2d_buffer_t` 结构体的指针，需要配置好高宽和格式。
     - 如果内存地址是虚拟地址，则将 `memory` 属性赋值为虚拟地址，并将 `gpu` 属性置为 0 。
     - 如果内存地址是物理地址，则将 `gpu` 属性赋值为物理地址，并将 `memory` 属性置为 0 。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)

<span id="n2d_unmap"/> </span>

### n2d_unmap
#### 【函数声明】
```c
n2d_error_t n2d_unmap (n2d_buffer_t *buffer)
```

#### 【功能描述】
 - 这函数会释放之前由 `n2d_map` 映射的内存，并将映射关系解除。
 - 需要和 `n2d_map` 成对使用。

#### 【参数描述】
 -  [IN] `buffer`
     - 指向 `n2d_buffer_t` 结构体的指针，需要之前被 `n2d_map` 函数使用过。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)


<span id="n2d_is_feature_support"/> </span>

### n2d_is_feature_support
#### 【函数声明】
```c
n2d_bool_t n2d_is_feature_support (n2d_feature_t feature)
```

#### 【功能描述】
 - 这个函数会查询硬件是否支持传入的功能。

#### 【参数描述】
 -  [IN] `feature`
     - 指向 `n2d_feature_t` 枚举类型的指针，详情可见 `n2d_feature_t` 介绍。
#### 【返回值】
 - 成功：支持
 - 失败：其他，不支持

<span id="n2d_blit"/> </span>

### n2d_blit
#### 【函数声明】
```c
n2d_error_t n2d_blit(n2d_buffer_t *dst_buf, n2d_rectangle_t *dst_rect, n2d_buffer_t *src_buf, n2d_rectangle_t *src_rect, n2d_blend_t mode)
```

#### 【功能描述】
 - 这是一个 `blit` 函数。`blit` 操作使用源缓冲区和目标缓冲区进行。源缓冲区和目标缓冲区结构使用 `n2d_buffer_t` 结构定义。
 -  [IN] `blit` 将源图像的指定区域复制到目标缓冲区的指定区域，支持混合、旋转和格式转换。**如果区域大小不同，将自动执行缩放动作**。
 - 该函数会等待硬件完成，即它是同步的。一次只能有一个 `blit` 函数处于活动状态。驱动程序不支持多上下文，因此当前的 `blit` 函数必须完成并关闭，然后才能初始化另一个 `blit` 函数。
 -  [IN] `blit` 函数可以与混合功能一起使用，也可以不使用混合功能。
 -  [IN] `blit` 函数可以通过为源缓冲区和目标缓冲区指定适当的格式来进行颜色转换。
 - 当源或目标缓冲区格式为 `N2D_YUYV`、`N2D_UYVY`、`N2D_YV12`、`N2D_I420`、`N2D_NV12`、`N2D_NV21`、`N2D_NV16` 或 `N2D_NV61` 时，源矩形大小和目标矩形大小必须相等，否则将返回 `N2D_INVALID_ARGUMENT`，并且 `ROP` 或透明度将被忽略。

#### 【参数描述】
 -  [IN] `dst_buf`
     - 指向目标缓冲区的 `n2d_buffer_t` 结构体指针。`blit` 函数的有效目标格式包括 `n2d_buffer_format_t` 枚举中的大多数颜色格式。
     - 如果源缓冲区格式为 `N2D_YUYV`、`N2D_UYVY`、`N2D_YV12`、`N2D_I420`、`N2D_NV12`、`N2D_NV21`、`N2D_NV16` 或 `N2D_NV61`，则源矩形大小和目标矩形大小必须相等，否则 `n2d_blit` 将返回 `N2D_INVALID_ARGUMENT`。
 -  [IN] `src_buf`
     - 指向描述 `blit` 源的 `n2d_buffer_t` 结构体指针。`blit` 函数的有效源格式包括 `n2d_buffer_format_t` 枚举中的所有颜色格式。
 -  [IN] `dst_rect`
     - 可选参数，指向定义目标缓冲区内区域的 `n2d_rectangle_t` 结构体指针。如果未指定此矩形，则整个目标缓冲区将用作目标区域。
 -  [IN] `src_rect`
     - 可选参数，指向定义源缓冲区内区域的 `n2d_rectangle_t` 结构体指针。如果未指定此矩形，则整个源缓冲区将用作源区域。如果源缓冲区格式为 `N2D_YUYV` 或 `N2D_UYVY`，则源矩形大小和目标矩形大小必须相等，否则 `n2d_blit` 将返回 `N2D_INVALID_ARGUMENT`。
 -  [IN] `mode`
     - 指定要应用于每个图像像素的硬件支持的混合模式之一。如果不需要混合，则将此值设置为 `N2D_BLEND_NONE (0)`。参见 `n2d_blend_t` 枚举。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)


<span id="n2d_filterblit"/> </span>

### n2d_filterblit
#### 【函数声明】
```c
n2d_error_t n2d_filterblit(n2d_buffer_t *dst_buf, n2d_rectangle_t *dst_rect, n2d_rectangle_t *dst_subrect, n2d_buffer_t *src_buf, n2d_rectangle_t *src_rect, n2d_blend_t mode)
```

#### 【功能描述】
 -  [IN] `n2d_filterblit` 使用 FIR 重采样滤波器进行高质量的图像缩放。
 - 如果源图像的指定区域和目标缓冲区的指定区域大小相同，`n2d_filterblit` 将作为位块传输（ bitblit）工作。支持混合、旋转。
 - 该函数会等待硬件完成，即它是同步的。一次只能有一个 `n2d_filterblit` 函数处于活动状态。驱动程序不支持多上下文，因此当前的 `n2d_filterblit` 函数必须完成并关闭，然后才能初始化另一个 `n2d_filterblit` 函数。
 -  [IN] `n2d_filterblit` 函数可以与混合功能一起使用，也可以不使用混合功能。

#### 【参数描述】
 -  [IN] `dst_buf`
     - 指向目标缓冲区的 `n2d_buffer_t` 结构体指针。`n2d_filterblit` 函数的有效目标格式包括 `n2d_buffer_format_t` 枚举中的大多数颜色格式。
 -  [IN] `dst_rect`
     - 可选参数，指向定义目标缓冲区内子区域的 `n2d_rectangle_t` 结构体指针。如果未指定此矩形，则整个目标缓冲区将用作目标区域。
 -  [IN] `dst_subrect`
     - 指向 `n2d_rectangle_t` 结构体的指针，提供目标区域内子区域的坐标。如果 `dst_subrect` 为 `N2D_NULL`，则使用 `dst_rect` 设置的坐标渲染完整图像。如果 `dst_subrect` 不是 `N2D_NULL`，且 `dst_subrect` 和 `dst_rect` 不相等，则假定 `dst_subrect` 在 `dst_rect` 内，并仅用于渲染子区域。
 -  [IN] `src_buf`
     - 指向描述 `n2d_filterblit` 源的 `n2d_buffer_t` 结构体指针。`n2d_filterblit` 函数的有效源格式包括 `n2d_buffer_format_t` 枚举中的所有颜色格式。
 -  [IN] `src_rect`
     - 可选参数，指向定义源缓冲区内子区域的 `n2d_rectangle_t` 结构体指针。如果未指定此矩形，则整个源缓冲区将用作源区域。
 -  [IN] `mode`
     - 指定要应用于每个图像像素的硬件支持的混合模式之一。如果不需要混合，则将此值设置为 `N2D_BLEND_NONE (0)`。参见 `n2d_blend_t` 枚举。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)


<span id="n2d_multisource_blit"/> </span>

### n2d_multisource_blit
#### 【函数声明】
```c
n2d_error_t n2d_multisource_blit(n2d_buffer_t *dst_buf, n2d_int32_t mask)
```

#### 【功能描述】
 - 该函数使用多个源进行多源位块传输（ multi-blit）。

#### 【参数描述】
 - [IN] `dst_buf`
     - 指向定义目标缓冲区的 `n2d_buffer_t` 结构体指针。
 - [IN] `mask`
     - 指示八个可能源中的哪些源将用于执行多源位块传输（ MultiSrcBlit，即合成操作）。位 N 表示源索引 N。
#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)



<span id="n2d_fill"/> </span>

### n2d_fill
#### 【函数声明】
```c
n2d_error_t n2d_fill(n2d_buffer_t *dest, n2d_rectangle_t *rect, n2d_color_t color, n2d_blend_t mode)
```
#### 【参数描述】
 - [IN] `dest`
     - 指向要填充的目标缓冲区的 `n2d_buffer_t` 结构体指针。
 - [IN] `rect`
     - 指向指定填充区域的 `n2d_rectangle_t` 结构体指针。如果矩形为 NULL，则整个目标缓冲区将被指定颜色填充。
 - [IN] `color`
     - 用于填充 / 清除缓冲区的颜色值。参见 `n2d_color_t`。
 - [IN] `mode`
     - 应用于每个像素的混合模式。如果不需要混合，则将此值设置为 `N2D_BLEND_NONE (0)`。参见 `n2d_blend_t` 枚举。

#### 【功能描述】
 - 该函数用指定的颜色填充或清除指定的缓冲区（整个缓冲区或缓冲区中的部分矩形区域）。
 - 该函数会等待硬件完成，即它是同步的。

#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)




<span id="n2d_set"/> </span>

### n2d_set
#### 【函数声明】
```c
n2d_error_t n2d_set(n2d_state_config_t *config)
```

#### 【功能描述】
 - 该函数用于设置配置。

#### 【参数描述】
 -  [IN] `config`
     - 设置某些功能的属性状态。参见结构体 `n2d_state_config_t` 以了解支持的值。

#### 【返回值】
- 成功： N2D_SUCCESS  0

- 失败：异常为负值错误码，参考 [ 返回值说明 ](#return_val)



## 数据结构
### 类型定义

|     Name                |     Typedef                                                     |
|-------------------------|-----------------------------------------------------------------|
|     n2d_bool_t          |     int                                                         |
|     n2d_int8_t          |     char                                                        |
|     n2d_int16_t         |     short                                                       |
|     n2d_uint16_t        |     unsigned short                                              |
|     n2d_int_t           |     int                                                         |
|     n2d_int32_t         |     int                                                         |
|     n2d_uint_t          |     unsigned int                                                |
|     n2d_uint32_t        |     unsigned int                                                |
|     n2d_uint64_t        |     unsigned long long                                          |
|     n2d_float_t         |     float                                                       |
|     n2d_double_t        |     double                                                      |
|     n2d_string          |     char*                                                       |
|     n2d_void            |     void                                                        |
|     n2d_const_string    |     const char*                                                 |
|     n2d_size_t          |     unsigned long long (64-bit OS)                              |
|     n2d_uintptr_t       |     unsigned long long (64-bit OS)                              |
|     n2d_pointer         |     void*                                                       |
|     n2d_color_t         |     uint32_t                                                    |


### 枚举类型

#### n2d_error_t

- 说明
    - Nano2D API 函数通过 `n2d_error_` 返回状态码，如果成功，将返回 `N2D_SUCCESS`。`N2D_SUCCESS` 设置为零，因此如果任何函数返回非零值，则表示发生了错误。可能的错误值包括下表中的值。


| n2d_error_t value           | String Values                | Description                                  |
|-----------------------------|------------------------------|----------------------------------------------|
| 0                            | N2D_SUCCESS                  | 成功，无错误                                 |
| 1                            | N2D_INVALID_ARGUMENT         | 指定的参数无效                               |
| 2                            | N2D_OUT_OF_MEMORY            | 内存不足                                     |
| 3                            | N2D_NO_CONTEXT               | 没有打开的上下文                             |
| 4                            | N2D_TIMEOUT                  | 等待期间发生超时                             |
| 5                            | N2D_OUT_OF_RESOURCES         | 系统资源不足                                 |
| 6                            | N2D_GENERIC_IO               | 无法与内核驱动程序通信                       |
| 7                            | N2D_NOT_SUPPORTED            | 请求不被支持                                 |
| 8                            | N2D_ERROR_HEAP_CORRUPTED     | MMU 表损坏                  |
| 9                            | N2D_NOT_ALIGNED              | 未对齐                      |
| 10                           | N2D_NOT_FOUND                | 未找到                     |
| 11                           | N2D_INTERRUPTED              | 被中断                      |
| 12                           | N2D_MEMORY_LEAK              | 内存泄漏                    |

#### n2d_blend_t

- 说明
    - 此枚举定义了 HAL 支持的混合模式。`S` 和 `D` 代表源和目标颜色通道，`Sa` 和 `Da` 代表源和目标的 alpha 通道。


| n2d_blend_t value           | String Values              | Description                          |
|-----------------------------|----------------------------|--------------------------------------|
| 0                            | N2D_BLEND_NONE             | `S`，无混合                          |
| 1                            | N2D_BLEND_SRC_OVER         | `S + (1 - Sa) * D`                   |
| 2                            | N2D_BLEND_DST_OVER         | `(1 – Da) * S + D`                   |
| 3                            | N2D_BLEND_SRC_IN           | `Da * S`                             |
| 4                            | N2D_BLEND_DST_IN           | `Sa * D`                             |
| 5                            | N2D_BLEND_ADDITIVE         | `S + D`                              |
| 6                            | N2D_BLEND_SUBTRACT         | `D * (1 – S)`                        |



#### n2d_buffer_format_t

- 说明
    - 指定用于缓冲区的颜色格式像素类型。


| n2d_buffer_format_t value  | String Values              | Description                                                                           |
|----------------------------|----------------------------|---------------------------------------------------------------------------------------|
| 0x100                      | N2D_RGBA8888               | 32-bit RGBA 格式，每个颜色通道 8 位。红色在 7:0 位，绿色在 15:8 位，蓝色在 23:16 位， alpha 通道在 31:24 位。 |
| 0x101                      | N2D_RGBX8888               | 32-bit RGBX 格式，每个颜色通道 8 位。红色在 7:0 位，绿色在 15:8 位，蓝色在 23:16 位， X 通道在 31:24 位。     |
| 0x200                      | N2D_R1010B10A2             | 32-bit RGBA 格式，每个颜色通道 10 位， alpha 通道 2 位。红色在 9:0 位，绿色在 19:10 位，蓝色在 29:20 位， alpha 通道在 31:30 位。 |
| 0x300                      | N2D_R5G5B5A1               | 16-bit RGBA 格式，每个颜色通道 5 位， alpha 通道 1 位。红色在 4:0 位，绿色在 9:5 位，蓝色在 14:10 位， alpha 通道在 15:15 位。     |
| 0x301                      | N2D_R5G5B5X1               | 16-bit RGBX 格式，每个颜色通道 5 位， X 通道 1 位。红色在 4:0 位，绿色在 9:5 位，蓝色在 14:10 位， X 通道在 15:15 位。             |
| 0x400                      | N2D_RGBA4444               | 16-bit RGBA 格式，每个颜色通道 4 位。红色在 3:0 位，绿色在 7:4 位，蓝色在 11:8 位， alpha 通道在 15:12 位。                   |
| 0x401                      | N2D_RGBX4444               | 16-bit RGBX 格式，每个颜色通道 4 位。红色在 3:0 位，绿色在 7:4 位，蓝色在 11:8 位， X 通道在 15:12 位。                     |
| 0x402                      | N2D_RGB565                 | 16-bit RGB 格式，每个颜色通道 5 位，绿色为 6 位。红色在 4:0 位，绿色在 10:5 位，蓝色在 15:11 位。                         |
| 0x403                      | N2D_RGB888                 | 24-bit RGB 格式，每个颜色通道 8 位。红色在 7:0 位，绿色在 15:8 位，蓝色在 23:16 位。                                    |
| 0x404                      | N2D_RGB888I                | 24-bit RGB 格式，每个颜色通道 8 位。红色在 7:0 位，绿色在 15:8 位，蓝色在 23:16 位。                                    |
| 0x405                      | N2D_RGB161616I             | 48-bit RGB 格式，每个颜色通道 16 位。红色在 15:0 位，绿色在 31:16 位，蓝色在 47:32 位。                                   |
| 0x406                      | N2D_BGRA8888               | 32-bit RGBA 格式，每个颜色通道 8 位。红色在 23:16 位，绿色在 15:8 位，蓝色在 7:0 位， alpha 通道在 31:24 位。                 |
| 0x407                      | N2D_BGRX8888               | 32-bit RGBX 格式，每个颜色通道 8 位。红色在 23:16 位，绿色在 15:8 位，蓝色在 7:0 位， X 通道在 31:24 位。                     |
| 0x408                      | N2D_B10G10R10A2            | 32-bit RGBA 格式，每个颜色通道 10 位， alpha 通道 2 位。红色在 29:20 位，绿色在 19:10 位，蓝色在 9:0 位， alpha 通道在 31:30 位。   |
| 0x409                      | N2D_BGR565                 | 16-bit RGB 格式，每个颜色通道 5 位，绿色为 6 位。红色在 15:11 位，绿色在 10:5 位，蓝色在 4:0 位。                           |
| 0x40A                      | N2D_B5G5R5A1               | 16-bit RGBA 格式，每个颜色通道 5 位， alpha 通道 1 位。红色在 14:10 位，绿色在 9:5 位，蓝色在 4:0 位， alpha 通道在 15:15 位。    |
| 0x40B                      | N2D_B5G5R5X1               | 16-bit RGBX 格式，每个颜色通道 5 位， X 通道 1 位。红色在 14:10 位，绿色在 9:5 位，蓝色在 4:0 位， X 通道在 15:15 位。           |
| 0x40C                      | N2D_BGRA4444               | 16-bit RGBA 格式，每个颜色通道 4 位。红色在 11:8 位，绿色在 7:4 位，蓝色在 3:0 位， alpha 通道在 15:12 位。                 |
| 0x40D                      | N2D_BGRX4444               | 16-bit RGBX 格式，每个颜色通道 4 位。红色在 11:8 位，绿色在 7:4 位，蓝色在 3:0 位， X 通道在 15:12 位。                     |
| 0x40E                      | N2D_ABGR8888               | 32-bit RGBA 格式，每个颜色通道 8 位。红色在 31:24 位，绿色在 23:16 位，蓝色在 15:8 位， alpha 通道在 7:0 位。               |
| 0x40F                      | N2D_XBGR8888               | 32-bit RGBX 格式，每个颜色通道 8 位。红色在 31:24 位，绿色在 23:16 位，蓝色在 15:8 位， X 通道在 7:0 位。                   |
| 0x410                      | N2D_A2B10G10R10            | 32-bit RGBA 格式，每个颜色通道 10 位， alpha 通道 2 位。红色在 31:22 位，绿色在 21:12 位，蓝色在 11:2 位， alpha 通道在 1:0 位。 |
| 0x411                      | N2D_A1B5G5R5               | 16-bit RGBA 格式，每个颜色通道 5 位， alpha 通道 1 位。红色在 15:11 位，绿色在 10:6 位，蓝色在 5:1 位， alpha 通道在 0:0 位。    |
| 0x412                      | N2D_X1B5G5R5               | 16-bit RGBX 格式，每个颜色通道 5 位， X 通道 1 位。红色在 15:11 位，绿色在 10:6 位，蓝色在 5:1 位， X 通道在 0:0 位。           |
| 0x413                      | N2D_ABGR4444               | 16-bit RGBA 格式，每个颜色通道 4 位。红色在 15:12 位，绿色在 11:8 位，蓝色在 7:4 位， alpha 通道在 3:0 位。                 |
| 0x414                      | N2D_XBGR4444               | 16-bit RGBX 格式，每个颜色通道 4 位。红色在 15:12 位，绿色在 11:8 位，蓝色在 7:4 位， X 通道在 3:0 位。                     |
| 0x415                      | N2D_ARGB8888               | 32-bit RGBA 格式，每个颜色通道 8 位。红色在 15:8 位，绿色在 23:16 位，蓝色在 31:24 位， alpha 通道在 7:0 位。               |
| 0x416                      | N2D_XRGB8888               | 32-bit RGBX 格式，每个颜色通道 8 位。红色在 15:8 位，绿色在 23:16 位，蓝色在 31:24 位， X 通道在 7:0 位。                   |
| 0x417                      | N2D_A2R10G10B10            | 32-bit RGBA 格式，每个颜色通道 10 位， alpha 通道 2 位。红色在 11:2 位，绿色在 21:12 位，蓝色在 31:22 位， alpha 通道在 1:0 位。 |
| 0x418                      | N2D_A1R5G5B5               | 16-bit RGBA 格式，每个颜色通道 5 位， alpha 通道 1 位。红色在 5:1 位，绿色在 10:6 位，蓝色在 15:11 位， alpha 通道在 0:0 位。    |
| 0x419                      | N2D_X1R5G5B5               | 16-bit RGBX 格式，每个颜色通道 5 位， X 通道 1 位。红色在 5:1 位，绿色在 10:6 位，蓝色在 15:11 位， X 通道在 0:0 位。           |
| 0x41A                      | N2D_ARGB4444               | 16-bit RGBA 格式，每个颜色通道 4 位。红色在 7:4 位，绿色在 11:8 位，蓝色在 15:12 位， alpha 通道在 3:0 位。                 |
| 0x41B                      | N2D_XRGB4444               | 16-bit RGBX 格式，每个颜色通道 4 位。红色在 7:4 位，绿色在 11:8 位，蓝色在 15:12 位， X 通道在 3:0 位。                     |
| 0x500                      | N2D_RGB888_PLANAR          | planar RGB 格式，每个颜色通道 8 位。红 / 绿 / 蓝 0 在 7:0 位，红 / 绿 / 蓝 1 在 15:8 位，红 / 绿 / 蓝 2 在 23:16 位，红 / 绿 / 蓝 3 在 31:24 位。 |
| 0x501                      | N2D_RGB888I_PLANAR         | planar RGB 格式，每个颜色通道 8 位。红 / 绿 / 蓝 0 在 7:0 位，红 / 绿 / 蓝 1 在 15:8 位，红 / 绿 / 蓝 2 在 23:16 位，红 / 绿 / 蓝 3 在 31:24 位。 |
| 0x502                      | N2D_RGB161616I_PLANAR      | planar RGB 格式，每个颜色通道 16 位。红 / 绿 / 蓝 0 在 15:0 位，红 / 绿 / 蓝 1 在 31:16 位，红 / 绿 / 蓝 2 在 47:32 位，红 / 绿 / 蓝 3 在 63:48 位。 |
| 0x600                      | N2D_A8                     | 8-bit alpha 格式。没有 RGB 值。                                                         |
| 0x700                      | N2D_YUYV                   | 32-bit packed YUV 格式，每 2 个像素 32 位。 Y0 在 7:0 位， V 在 31:24 位。                          |
| 0x701                      | N2D_UYVY                   | 32-bit packed YUV 格式，每 2 个像素 32 位。 U 在 7:0 位， Y1 在 31:24 位。                          |
| 0x702                      | N2D_AYUV                   | 3 planar YUV 格式，无 alpha。 Y/U/V0 在 7:0 位， Y/U/V1 在 15:8 位， Y/U/V2 在 23:16 位， Y/U/V3 在 31:24 位。 |
| 0x703                      | N2D_YV12                   | 12 bpp planar YUV4:2:0 格式，每个分量 8 位。                                               |
| 0x704                      | N2D_I420                   | planar YUV 格式， 8 位 Y planar ，随后是 8 位 2x2 的 U 和 V planar。                               |
| 0x705                      | N2D_NV12                   | 12 bpp planar YUV 4:2:0 格式，每个分量 8 位。 16 个 Y 像素 =16 字节， 16 个 UV 像素 =16 字节。        |
| 0x706                      | N2D_NV21                   | 12 bpp planar YUV 4:2:0 格式，与 NV12 相同，但 U 和 V 在层反转。                      |
| 0x707                      | N2D_NV16                   | 16 bpp planar YUV 4:2:2 格式，每个分量 8 位。                                              |
| 0x708                      | N2D_NV61                   | 16 bpp planar YUV 4:2:2 格式，与 NV16 相同，但 U 和 V 层交换。                              |
| 0x709                      | N2D_NV12_10BIT             | 10-bit YUV 格式，每个分量 10 位。                                                       |
| 0x70A                      | N2D_NV21_10BIT             | 10-bit YUV 格式，每个分量 10 位。                                                       |
| 0x70B                      | N2D_NV16_10BIT             | 10-bit YUV 格式，每个分量 10 位。                                                       |
| 0x70C                      | N2D_NV61_10BIT             | 10-bit YUV 格式，每个分量 10 位。                                                       |
| 0x70D                      | N2D_P010_MSB               | P010 （ YUV 4:2:0 2planar ，每个分量 10 位） |

#### n2d_cache_mode_t

- 说明
    - 指定缓存模式。
    - 使用的结构体：`n2d_buffer_t`
    - 常量定义：`#define N2D_CACHEMODE_DEFAULT N2D_CACHE_256`


| n2d_cache_mode_t value  | String Values              | Description |
|-------------------------|----------------------------|-------------|
| 0                       | N2D_CACHE_AUTO             |             |
| 0x1                     | N2D_CACHE_128              |             |
| 0x2                     | N2D_CACHE_256              |             |
| 0x3                     | N2D_CACHE_ALL              | N2D_CACHE_128 或 N2D_CACHE_256 |





#### n2d_core_id_t

- 说明
    - 指定多处理器设计中的核心 ID。
    - 使用的函数：`n2d_switch_core`


| n2d_core_id_t value      | String Values    | Description |
|--------------------------|------------------|-------------|
| 0                        | N2D_CORE_0       |             |
| 1                        | N2D_CORE_1       |             |
| 2                        | N2D_CORE_2       |             |
| 3                        | N2D_CORE_3       |             |

#### n2d_csc_mode_t

- 说明
    - 指定颜色空间转换模式。
    - 使用的结构体：`n2d_csc_config_t`


| n2d_csc_mode_t value               | String Values                     | Description |
|------------------------------------|-----------------------------------|-------------|
| 0                                  | N2D_CSC_BT709                     |             |
| 0x1                                | N2D_CSC_BT601                     |             |
| 0x2                                | N2D_CSC_BT2020                    |             |
| 0x4                                | N2D_CSC_USER_DEFINED              |             |
| 0x5                                | N2D_CSC_USER_DEFINED_CLAMP        |             |
| 0x40000000                         | N2D_CSC_SET_FULL_RANGE            |             |
| 0x80000000                         | N2D_CSC_DST                       |             |


**注意**：在执行格式转换的时候，如果没有显式设定，默认使用的色彩空间是 BT709 ， limited range。

如果期望改变色彩空间和灰阶范围，可以在执行格式转换之前执行下面语句：
```C
    /*CSC SETTING*/
    n2d_state_config_t csc_com = {0};
    csc_com.state = N2D_SET_CSC;
    csc_com.config.csc.cscMode = N2D_CSC_SET_FULL_RANGE | N2D_CSC_BT709; // 设置为 BT709 ，灰阶范围为 full range
    csc_com.config.csc.userCSCMode = N2D_CSC_YUV_TO_RGB;
    n2d_set(&csc_com);
    csc_com.config.csc.userCSCMode = N2D_CSC_RGB_TO_YUV;
    n2d_set(&csc_com);
    /*END*/
```

这个对于 YUV 转 YUV（比如 NV12 转 YUYV）也同样生效，因为硬件针对 YUV 相互转换是按照 YUV->RGB->YUV pipeline 进行。


#### n2d_feature_t

- 说明
    - 指定可能在硬件中可用和支持的功能。
    - 使用的函数：`n2d_is_feature_support`


| n2d_feature_t value                       | String Values                        | Description                                                           |
|-------------------------------------------|--------------------------------------|-----------------------------------------------------------------------|
| 0                                         | N2D_FEATURE_YUV420_OUTPUT            | 支持 YUV420 输出                                                        |
| 1                                         | N2D_FEATURE_2D_10BIT_OUTPUT_LINEAR   | 支持 10 位线性输出                                                       |
| 2                                         | N2D_FEATURE_MAJOR_SUPER_TILE         |                                               |
| 3                                         | N2D_FEATURE_DEC400_COMPRESSION       | 支持 DEC400 压缩                                                   |
| 4                                         | N2D_FEATURE_ANDROID_ONLY             |                                                 |
| 5                                         | N2D_FEATURE_2D_TILING                | 支持 TILING                                                            |
| 6                                         | N2D_FEATURE_2D_MINOR_TILING          |                                                        |
| 7                                         | N2D_FEATURE_DEC_COMPRESSION          | 支持 DEC 压缩                                                           |
| 8                                         | N2D_FEATURE_2D_MULTI_SOURCE_BLT      | 支持多源传输                                                       |
| 9                                         | N2D_FEATURE_BGR_PLANAR               | 支持 BGR8888 和 AYUV 格式                                                  |
| 10                                        | N2D_FEATURE_SCALER                   | 支持拉伸                                                         |
| 11                                        | N2D_FEATURE_2D_ONE_PASS_FILTER       | 支持单次通过滤波                                                       |
| 12                                        | N2D_FEATURE_2D_OPF_YUV_OUTPUT        | 单次通过滤波支持 YUV 输出                                                |
| 13                                        | N2D_FEATURE_SEPARATE_SRC_DST         | 支持分离的源和目标                                                     |
| 14                                        | N2D_FEATURE_2D_ALL_QUAD              |                                                                       |
| 15                                        | N2D_FEATURE_2D_POST_FLIP             |                                                                       |
| 16                                        | N2D_FEATURE_AXI_FE                   |                          |
| 17                                        | N2D_FEATURE_CSC_PROGRAMMABLE         | 支持色彩空间转换                                                 |
| 18                                        | N2D_FEATURE_DEC400_FC                |                                                      |
| 19                                        | N2D_FEATURE_TRANSPARENCY_MASK        | 支持掩码位块传输                                                       |
| 20                                        | N2D_FEATURE_TRANSPARENCY_COLOR_KEY   |                                                            |
| 21                                        | N2D_FEATURE_NORMALIZATION            |                                                             |
| 22                                        | N2D_FEATURE_NORMALIZATION_QUALTIZATION |                                                     |
| 23                                        | N2D_FEATURE_HISTOGRAM                | 支持直方图功能                                                        |
| 24                                        | N2D_FEATURE_BRIGHTNESS_SATURATION    | 支持亮度和饱和度                                                      |
| 25                                        | N2D_FEATURE_64BIT_ADDRESS            | 支持 64 位地址                                                          |
| 26                                        | N2D_FEATURE_FEATURE_CONTEXT_ID       | 支持功能上下文 ID                                                      |
| 27                                        | N2D_FEATURE_FEATURE_SECURE_BUFFER    | 支持安全内存缓冲区                                                    |
| 28                                        | N2D_FEATURE_MMU_PAGE_DESCRIPTOR      | 支持内核的 MMU 页面描述符                                               |
| 29                                        | N2D_FEATURE_SECURITY_AHB             |                                                         |
| 30                                        | N2D_FEATURE_FRAME_DONE_INTERRUPT     | 支持帧中断                                                        |

#### n2d_orientation_t

- 说明
    - 指定 `n2d_buffer_t` 结构体的方向。
    - 使用的结构体：`n2d_buffer_t`


| n2d_orientation_t value  | String Values  | Description                       |
|--------------------------|----------------|-----------------------------------|
| 0                        | N2D_0          | Buffer is 0 degrees rotated.      |
| 1                        | N2D_90         | Buffer is 90 degrees rotated.     |
| 2                        | N2D_180        | Buffer is 180 degrees rotated.    |
| 3                        | N2D_270        | Buffer is 270 degrees rotated.    |
| 4                        | N2D_FLIP_X     | Flip in horizontal direction.     |
| 5                        | N2D_FLIP_Y     | Flip in vertical direction.       |


#### n2d_tiling_t

- 说明
    - 指定 `n2d_buffer_t` 结构体的 tile 方式。
    - 使用的结构体：`n2d_buffer_t`


| n2d_tiling_t value         | String Values                 | Description                                     |
|----------------------------|-------------------------------|-------------------------------------------------|
| 0                          | N2D_INVALID_TILED             | Invalid tiling                                  |
| 1                          | N2D_LINEAR                    | No tiling                                       |
| 2                          | N2D_TILED                     | 4x4 tiling                                      |
| 3                          | N2D_SUPER_TILED               | 64x64 tiling                                    |
| 4                          | N2D_MINOR_TILED               | 2x2 tiling                                      |
| 5                          | N2D_TILING_SPLIT_BUFFER       | 2x2 tiling                                      |
| 6                          | N2D_TILING_X_MAJOR            | X Major (Z-ordered) tiling                      |
| 7                          | N2D_TILING_Y_MAJOR            | Y Major tiling                                  |
| 8                          | N2D_TILING_SWAP               |                                                 |
| 9                          | N2D_MULTI_TILED               | N2D_TILED \| N2D_TILING_SPLIT_BUFFER            |
| 10                         | N2D_MULTI_SUPER_TILED         | N2D_SUPER_TILED \| N2D_TILING_SPLIT_BUFFER      |
| 11                         | N2D_YMAJOR


#### n2d_tile_status_config_t

- 说明
    - 指定 `n2d_buffer_t` 结构体的 tile 状态模式。
    - 使用的结构体：`n2d_buffer_t`


| n2d_tile_status_config_t value | String Values            | Description            |
|--------------------------------|--------------------------|------------------------|
| 0                              | N2D_TSC_DISABLE          | No compression         |
| 0x00000001                     | N2D_TSC_DEC_COMPRESSED   | DEC400 compression     |


#### n2d_pixel_color_multiply_mode_t

- 说明
    - 使用的函数：`n2d_set_pixel_multiply_mode`


| n2d_pixel_color_multiply_mode_t value | String Values               | Description |
|---------------------------------------|-----------------------------|-------------|
| 0                                     | N2D_COLOR_MULTIPLY_DISABLE  |             |
| 1                                     | N2D_COLOR_MULTIPLY_ENABLE   |             |

#### n2d_global_color_multiply_mode_t

- 说明
    - 指定用于 alpha 融合的全局模式。
    - 使用的函数：`n2d_set_pixel_multiply_mode`


| n2d_global_color_multiply_mode_t value | String Values                      | Description |
|----------------------------------------|------------------------------------|-------------|
| 0                                      | N2D_GLOBAL_COLOR_MULTIPLY_DISABLE  |             |
| 1                                      | N2D_GLOBAL_COLOR_MULTIPLY_ALPHA    |             |
| 2                                      | N2D_GLOBAL_COLOR_MULTIPLY_COLOR    |             |

#### n2d_filter_type_t

- 说明
    - 指定滤波器类型。
    - 使用的结构体：`n2d_state_config_t`


| n2d_filter_type_t value  | String Values     | Description              |
|--------------------------|-------------------|--------------------------|
| 0                        | N2D_FILTER_SYNC   |                          |
| 1                        | N2D_FILTER_BLUR   | Blur filter              |
| 2                        | N2D_FILTER_USER   | User specified filter    |
| 3                        | N2D_FILTER_BILINEAR | Bilinear                |
| 4                        | N2D_FILTER_BICUBIC | Bicubic                 |

#### n2d_state_value_t

- 说明
    - 用于区分特定的配置行为。
    - 使用的结构体：`n2d_csc_config_t`


| n2d_state_value_t value  | String Values     | Description              |
|--------------------------|-------------------|--------------------------|
| 0x1                      | N2D_CSC_YUV_TO_RGB|                          |
| 0x2                      | N2D_CSC_RGB_TO_YUV|                          |


#### n2d_state_type_t

- 说明
    - 指定配置状态的设置。
    - 使用的结构体：`n2d_state_config_t`


| n2d_state_type_t value         | String Values                   | Description                                                                      |
|--------------------------------|---------------------------------|----------------------------------------------------------------------------------|
| 0                              | N2D_SET_ALPHABLEND_MODE         |                                                  |
| 1                              | N2D_SET_BRIGHTNESS              | 不支持                                          |
| 2                              | N2D_SET_CLIP_RECTANGLE          |                                                   |
| 3                              | N2D_SET_CONTEXT_ID              | 不支持                                         |
| 4                              | N2D_SET_CSC                     |                                                                                  |
| 5                              | N2D_SET_DITHER                  |                                                                                  |
| 6                              | N2D_SET_DST_COLORKEY            |                                   |
| 7                              | N2D_SET_FAST_CLEAR              | 不支持                                             |
| 8                              | N2D_SET_FILTER_TYPE             |                                            |
| 9                              | N2D_SET_GLOBAL_ALPHA            |                                           |
| 10                             | N2D_SET_HISTOGRAM_CALC          | 不支持                                          |
| 11                             | N2D_SET_HISTOGRAM_EQUAL         | 不支持                                          |
| 12                             | N2D_SET_KERNEL_SIZE             |                                            |
| 13                             | N2D_SET_MASKPACK                | 不支持                                                                             |
| 14                             | N2D_SET_MULTISOURCE_INDEX       |                                           |
| 15                             | N2D_SET_MULTISRC_DST_RECTANGLE  |                                                 |
| 16                             | N2D_SET_NORMALIZATION           | 不支持                                      |
| 17                             | N2D_SET_PIXEL_MULTIPLY_MODE     |                                    |
| 18                             | N2D_SET_ROP                     |                                                   |
| 19                             | N2D_SET_SRC_COLORKEY            |                                        |
| 20                             | N2D_SET_TRANSPARENCY            | 不支持                                          |


#### n2d_source_type_t

- 说明
    - 指定源类型。


| n2d_source_type_t value | String Values              | Description |
|-------------------------|----------------------------|-------------|
| 0                       | N2D_SOURCE_DEFAULT         |             |
|                         | N2D_SOURCE_MASKED          |             |
|                         | N2D_SOURCE_MASKED_MONO     |             |


### 结构体

#### n2d_point_t

- 说明
    - 此结构描述了 Nano2D 的点数据。点定义了屏幕上的一个像素。
    - 使用的函数：`n2d_line`, `n2d_maskpack_config_t`

- 属性表

| 成员 | 类型         | 描述         |
|------|--------------|--------------|
| x    | n2d_int32_t  | 点的 X 坐标    |
| y    | n2d_int32_t  | 点的 Y 坐标    |

#### n2d_rectangle_t

- 说明
    - 此结构定义了 Nano2D 数据矩形的组织方式。
    - 使用的函数：`n2d_blit`, `n2d_fill`, `n2d_line`, `n2d_set_filter_type`, `n2d_set_source`, `n2d_set_clip`

- 属性表

| 成员    | 类型         | 描述                        |
|---------|--------------|-----------------------------|
| x       | n2d_int32_t  | 矩形的 X 坐标，左上角         |
| y       | n2d_int32_t  | 矩形的 Y 坐标，顶部           |
| width   | n2d_int32_t  | 矩形的宽度                  |
| height  | n2d_int32_t  | 矩形的高度                  |

#### n2d_csc_config_t

- 说明
    - 此结构体指定颜色空间转换（ CSC）模式。
    - 使用的结构体：`n2d_state_config_t`
    - 常量定义：`#define N2D_CSC_PROGRAMMABLE_SIZE 12`

- 属性表

| 成员                    | 类型               | 描述                                                                                                    |
|-------------------------|--------------------|---------------------------------------------------------------------------------------------------------|
| cscMode                 | n2d_csc_mode_t     | 颜色空间转换模式，具体参见枚举类型 `n2d_csc_mode_t`                                                     |
| userCSCMode             | n2d_state_value_t  | 用户定义的颜色空间转换方向。支持的值：`N2D_CSC_YUV_TO_RGB` 或 `N2D_CSC_RGB_TO_YUV`，仅在 `cscMode` 为 `N2D_CSC_USER_DEFINED` 或 `N2D_CSC_USER_DEFINED_CLAMP` 时使用 |
| cscTable[N2D_CSC_PROGRAMMABLE_SIZE] | n2d_int32_t         | 颜色转换表                                                                                              |

#### n2d_dither_info_t

- 说明
    - 此结构体指定是否启用抖动功能。
    - 使用的结构体：`n2d_state_config_t`

- 属性表

| 成员  | 类型         | 描述                    |
|-------|--------------|-------------------------|
| enable| n2d_bool_t   | 1= 启用抖动功能          |

#### n2d_multisrc_dst_rect_config_t

- 说明
    - 此结构体描述了多源目标矩形的配置。
    - 使用的结构体：`n2d_state_config_t`

- 属性表

| 成员    | 类型            | 描述                             |
|---------|-----------------|----------------------------------|
| *source | n2d_buffer_t    | 指向包含源缓冲区的结构体的指针    |
| srcRect | n2d_rectangle_t | 源矩形的结构体                   |
| dstRect | n2d_rectangle_t | 目标矩形的结构体                 |


#### n2d_rop_config_t

- 说明
    - 此结构体定义了 Nano2D 数据的 ROP 配置。
    - 使用的结构体：`n2d_state_config_t`

- 属性表

| 成员    | 类型          | 描述             |
|---------|---------------|------------------|
| fg_rop  | n2d_uint32_t  | 前景 ROP         |
| bg_rop  | n2d_uint32_t  | 背景 ROP         |


#### n2d_multiply_mode_config_t

- 说明
    - 此结构体描述了用于 Alpha 融合的预乘 / 预除模式。
    - 使用的结构体：`n2d_state_config_t`

- 属性表

| 成员         | 类型                         | 描述                           |
|--------------|------------------------------|--------------------------------|
| srcPremult   | n2d_pixel_color_multiply_mode_t  | 源预乘的枚举类型                |
| dstPremult   | n2d_pixel_color_multiply_mode_t  | 目标预乘的枚举类型              |
| srcGlobal    | n2d_global_color_multiply_mode_t | 源全局乘法的枚举类型            |
| dstDemult    | n2d_pixel_color_multiply_mode_t  | 目标预除的枚举类型              |



#### n2d_kernel_size_config_t

- 说明
    - 此结构体提供水平和垂直内核大小。
    - 使用的结构体：`n2d_state_config_t`

- 属性表

| 成员    | 类型         | 描述             |
|---------|--------------|------------------|
| horSize | n2d_uint8_t  | 水平内核尺寸     |
| verSize | n2d_uint8_t  | 垂直内核尺寸     |


#### n2d_state_config_t

- 说明
    - 此结构提供状态配置数据。
    - 使用的函数：`n2d_set`

- 属性表

| 成员               | 类型                            | 描述                                                                                                   |
|--------------------|---------------------------------|--------------------------------------------------------------------------------------------------------|
| state              | n2d_state_type_t                | 状态数据的枚举类型                                                                                      |
| config             | union                           | 包含不同配置结构的联合体                                                                                 |

- `config` 联合体成员

| 成员               | 类型                            | 描述                                                                                                   |
|--------------------|---------------------------------|--------------------------------------------------------------------------------------------------------|
|csc              | n2d_csc_config_t                | 颜色空间转换配置的结构体                                                                                 |                                                                                 |
|ditherInfo       | n2d_dither_info_t               | 包含抖动信息的结构体                                                                                     |                                                                                |
|multisourceIndex | n2d_multisource_index_config_t  | 源索引，类型定义为 `n2d_uint32_t`                                                                        |
|clipRect         | n2d_rectangle_t                 | 裁剪矩形的结构体                                                                                        |
|globalAlpha      | n2d_global_alpha_config_t       | 全局 alpha 值的结构体                                                                                      |
|alphablendMode   | n2d_blend_t                     | alpha 混合模式的枚举类型                                                                                   |
|multisrcAndDstRect | n2d_multisrc_dst_rect_config_t | 多源目标矩形的结构体                                                                                      |
|rop              | n2d_rop_config_t                | 前景和背景 ROP 的结构体                                                                                     |                                                                                     |
|pixelMultiplyMode| n2d_multiply_mode_config_t      | 预乘 / 预除模式的结构体                                                                             |
|kernelSize       | n2d_kernel_size_config_t        | 内核尺寸的结构体                                                                                         |
|filterType       | n2d_filter_type_t               | 滤波器类型的枚举类型                                                                                     |

#### n2d_buffer_t

- 说明
    - 此结构定义了 Nano2D buffer 的信息

- 属性表

| 成员               | 类型                        | 描述                                                                                 |
|--------------------|-----------------------------|--------------------------------------------------------------------------------------|
| width              | n2d_int32_t                 | 缓冲区的宽度（以像素为单位）                                                         |
| height             | n2d_int32_t                 | 缓冲区的高度（以像素为单位）                                                         |
| alignedw           | n2d_int32_t                 | 缓冲区对齐后的宽度（以像素为单位）                                  |
| alignedh           | n2d_int32_t                 | 缓冲区对齐后的高度（以像素为单位）                                  |
| stride             | n2d_int32_t                 | 缓冲区的 stride                                                         |
| srcType            | n2d_source_type_t           | 源类型                                                            |
| format             | n2d_buffer_format_t         | 缓冲区的像素格式                                                                     |
| orientation        | n2d_orientation_t           | 缓冲区的方向                                                                         |
| tiling             | n2d_tiling_t                | tiling 模式                                                             |
| cacheMode          | n2d_cache_mode_t            | 缓冲区的缓存模式。                                                   |
| handle             | n2d_uintptr_t               | 缓冲区句柄                                                     |
| memory             | n2d_pointer                 | CPU 侧的地址指针                                             |
| gpu                | n2d_uint32_t                | GPU 侧的地址指针                                                   |
| uvstride[MAX_UV_PLANE] | n2d_int32_t             | UV 层的 stride [ 仅对 YUV 格式有效 ]                                                    |
| uv_handle[MAX_UV_PLANE] | n2d_pointer            | UV 层的句柄 [ 仅对 YUV 格式有效 ]                                                    |
| uv_memory[MAX_UV_PLANE] | n2d_pointer            | UV 层的 CPU 侧的地址 [ 仅对 YUV 格式有效 ]                                                    |
| uv_gpu[MAX_UV_PLANE]    | n2d_uint32_t           | GPU 侧 UV 层的地址 [ 仅对 YUV 格式有效 ]                              |
| tile_status_config | n2d_tile_status_config_t    | tiling 状态配置                                                         |
| tile_status_buffer | n2d_tile_status_buffer_t    | tiling 状态                                                 |




<span id="return_val"/> </span>

## 返回值说明

### n2d_error_t

- 说明
    - Nano2D API 函数通过 `n2d_error_` 返回状态码，如果成功，将返回 `N2D_SUCCESS`。`N2D_SUCCESS` 设置为零，因此如果任何函数返回非零值，则表示发生了错误。可能的错误值包括下表中的值。


| n2d_error_t value           | String Values                | Description                                  |
|-----------------------------|------------------------------|----------------------------------------------|
| 0                            | N2D_SUCCESS                  | 成功，无错误                                 |
| 1                            | N2D_INVALID_ARGUMENT         | 指定的参数无效                               |
| 2                            | N2D_OUT_OF_MEMORY            | 内存不足                                     |
| 3                            | N2D_NO_CONTEXT               | 没有打开的上下文                             |
| 4                            | N2D_TIMEOUT                  | 等待期间发生超时                             |
| 5                            | N2D_OUT_OF_RESOURCES         | 系统资源不足                                 |
| 6                            | N2D_GENERIC_IO               | 无法与内核驱动程序通信                       |
| 7                            | N2D_NOT_SUPPORTED            | 请求不被支持                                 |
| 8                            | N2D_ERROR_HEAP_CORRUPTED     | MMU 表损坏                  |
| 9                            | N2D_NOT_ALIGNED              | 未对齐                      |
| 10                           | N2D_NOT_FOUND                | 未找到                     |
| 11                           | N2D_INTERRUPTED              | 被中断                      |
| 12                           | N2D_MEMORY_LEAK              | 内存泄漏                    |