图形处理 (TDE)
概述
本文档主要介绍 TDE 的 API 和数据类型。
基本概念
TDE(Two Dimensional Engine)利用硬件 RGA 提供快速的图形处理功能,主要有快速位图搬移、快速色彩填充、快速位图旋转、快速位图缩放、位图格式转换、位图 alpha 叠加操作。
示例代码
ZH_S32 s32Ret = ZH_SUCCESS;
FILE *file = ZH_NULL;
ZH_S32 u32JobTestTime = 1;
ZH_S32 u32TaskTestTime = 2;
void *pSrcData = ZH_NULL;
ZH_U32 u32taskCount = 0;
MB_BLK srcBlk = ZH_NULL;
ZH_U32 u32ImgSize = COLOR_WIDTH * COLOR_HEIGHT * 3 / 2;
TDE_HANDLE hHandle = 0;
TDE_SURFACE_S pstDst[TDE_MAX_TASK_NUM];
TDE_RECT_S pstDstRect[TDE_MAX_TASK_NUM];
ZH_TDE_Open();
hHandle = ZH_TDE_BeginJob();
if (ZH_ERR_TDE_INVALID_HANDLE == hHandle) {
ZH_LOGE("start job fail");
return ZH_FAILURE;
}
TDE_SURFACE_S pstSrc;
TDE_RECT_S pstSrcRect;
test_tde_quick_resize_task(&pstSrc,
&pstSrcRect,
&pstDst[u32TaskIndex],
&pstDstRect[u32TaskIndex],
srcBlk, file, u32ImgSize);
s32Ret = ZH_TDE_QuickResize(hHandle, &pstSrc, &pstSrcRect,
&pstDst[u32TaskIndex], &pstDstRect[u32TaskIndex]);
if (s32Ret != ZH_SUCCESS) {
ZH_TDE_CancelJob(hHandle);
return ZH_FAILURE;
}
s32Ret = ZH_TDE_EndJob(hHandle, ZH_FALSE, ZH_TRUE, 10);
if (s32Ret != ZH_SUCCESS) {
ZH_TDE_CancelJob(hHandle);
return ZH_FAILURE;
}
ZH_TDE_WaitForDone(hHandle);
ZH_TDE_CancelJob(hHandle);
ZH_TDE_Close();
ZH_MPI_SYS_Free(srcBlk);
TDE 硬件规格
| 数据格式 | 宽度对齐像素 | 高度对齐像素 | 单像素比特数 | 压缩格式 |
|---|---|---|---|---|
| ZH_FMT_YUV420SP ZH_FMT_YUV420SP_VU | 16 | 2 | 8 | 不支持 |
| ZH_FMT_YUV420p | 16 | 2 | 8 | 不支持 |
| ZH_FMT_YUV422SP | 16 | 2 | 8 | 不支持 |
| ZH_FMT_YUV422_YUYV | 16 | 2 | 8 | 不支持 |
| ZH_FMT_YUV400SP | 16 | 2 | 8 | 不支持 |
| ZH_FMT_YUV420SP_10BIT ZH_FMT_YUV422SP_10BIT | 64 | 2 | 10 | 不支持 |
| ZH_FMT_RGB565 | 8 | 1 | 16 | 不支持 |
| ZH_FMT_BGR565 | 8 | 1 | 16 | 不支持 |
| ZH_FMT_RGB888 | 16 | 1 | 24 | 不支持 |
| ZH_FMT_BGR888 | 16 | 1 | 24 | 不支持 |
| ZH_FMT_RGBA8888 | 4 | 1 | 32 | 不支持 |
| ZH_FMT_BGRA8888 | 4 | 1 | 32 | 不支持 |
| ZH_FMT_RGBA5551 ZH_FMT_BGRA5551 | 32 | 1 | 16 | 不支持 |
注意:
- TDE 操作区域的对齐格式都有关系,如果是 rgb 格式的宽高和偏移不需要对齐,yuv 格式宽高和偏移均需 2 像素对齐。
- 调用 TDE 操作时,请确保 ZH_TDE_Open() 被成功调用,否则硬件无法被使用。
- 除了快速接口的操作外,TDE 暂不支持输入输出压缩格式,请保证图像 输入为非压缩(非 AFBC 等任意压缩格式)。
- TDE 支持图像大小在 64x64 到 8192x8192 范围内的缩放。
API 参考
该功能模块为用户提供以下API:
- ZH_TDE_Open : 打开 TDE 设备。
- ZH_TDE_Close : 关闭 TDE 设备。
- ZH_TDE_BeginJob : 创建 1 个 TDE 任务。
- ZH_TDE_EndJob : 提交已创建的 TDE 任务。
- ZH_TDE_CancelJob : 取消 TDE 任务。
- ZH_TDE_WaitForDone : 等指定的任务完成。
- ZH_TDE_WaitAllDone : 等待 TDE 的所有任务完成。
- ZH_TDE_QuickCopy : 向指定任务中添加快速拷贝操作。
- ZH_TDE_QuickResize: 向任务中添加光栅位图缩放操作。
- ZH_TDE_Bitblit: 向任务中添加对光栅位图进行有附加功能的搬移操作。
- ZH_TDE_QuickFill: 向任务中添加快速填充操作。
- ZH_TDE_Rotate: 向任务中添加光栅位图旋转操作。
ZH_TDE_Open
描述
打开 TDE 设备。
语法
ZH_S32 ZH_TDE_Open(ZH_VOID);
参数
无。
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败,其值为 TDE 错误码。 |
注意事项
- 使用 TDE 设备前需要调用 Open 接口完成 TDE 设备初始化。
- 不支持重复调用,重复调用返回失败。
ZH_TDE_Close
描述
关闭 TDE 设备。
语法
ZH_VOID ZH_TDE_Close(ZH_VOID);
参数
无。
返回值
无。
注意事项
ZH_TDE_Open需要被成功调用。
ZH_TDE_BeginJob
描述
创建 1 个 TDE 任务。
语法
TDE_HANDLE ZH_TDE_BeginJob(ZH_VOID);
参数
无。
返回值
| 返回值 | 描述 |
|---|---|
| 句柄 | 成功。 |
| 非 0 | 失败,其值为 TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- 应该判断返回值,确保获得 1 个正确的任务句柄。
- TDE 最多支持 128 个任务。
ZH_TDE_EndJob
描述
提交已创建的 TDE 任务。可以指定为阻塞还是非阻塞,阻塞的可以设置超时时间。
-
阻塞
函数调用不会立即返回,只有在 TDE Job 中的任务都执行完成或者超时时间到达的情况下才会返回。
-
非阻塞
函数调用会立即返回,不关心TDE中的job是不是执行完成。
语法
ZH_S32 ZH_TDE_EndJob(TDE_HANDLE s32Handle, ZH_BOOL bSync, ZH_BOOL bBlock, ZH_U32 u32TimeOut);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
| bSync | ZH_BOOL | 暂时不使用。 | 输入 |
| bBlock | ZH_BOOL | 阻塞标志。 ZH_TRUE: 阻塞。 ZH_FALS: 非阻塞。 | 输入 |
| u32TimeOut | ZH_U32 | 超时时间,单位: ms。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败,其值为TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- 在调用此接口前应保证调用 ZH_TDE_BeginJob 获得了有效的任务句柄。
- 此接口若为阻塞接口,到达超时时间调用函数会返回,但是操作依然会继续完成。
ZH_TDE_CancelJob
描述
取消 TDE 任务。
语法
ZH_S32 ZH_TDE_CancelJob(TDE_HANDLE s32Handle);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败,其值为 TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- 保证调用 ZH_TDE_BeginJob 获得了有效的任务句柄,否则返回值无效。
- 已经提交的任务不能够再取消。
- 取消后的任务不再有效,故不能再向其添加操作,也不能提交该任务。
ZH_TDE_WaitForDone
描述
等待指定的任务完成。
语法
ZH_S32 ZH_TDE_WaitForDone(TDE_HANDLE s32Handle);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非0 | 失败,其值为 TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- ZH_TDE_END_JOB 接口采用非阻塞方式或者有超时时间的,都需要调用这个接口等待任务完成。此接口为阻塞接口,会阻塞等待指定的任务完成。
ZH_TDE_WaitAllDone
描述
等待 TDE 的所有任务完成。
语法
ZH_S32 ZH_TDE_WaitAllDone(ZH_VOID);
参数
无。
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非0 | 失败,其值为 TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- 此接口为阻塞接口,会阻塞等待所有的 TDE 任务完成。
ZH_TDE_QuickCopy
描述
向指定任务中添加快速拷贝操作。
语法
ZH_S32 ZH_TDE_QuickCopy(TDE_HANDLE s32Handle,
const TDE_SURFACE_S *pstSrc,
const TDE_RECT_S *pstSrcRect,
const TDE_SURFACE_S *pstDst,
const TDE_RECT_S *pstDstRect);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
| pstSrc | const TDE_SURFACE_S* | 源位图。 | 输入 |
| pstSrcRect | const TDE_RECT_S* | 源位图操作区域。 | 输入 |
| pstDst | const TDE_SURFACE_S* | 目标位图。 | 输入 |
| pstDstRect | const TDE_RECT_S* | 目标位图操作区域。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败,其值为 TDE 错误码。 |
注意事项
- ZH_TDE_Open 需要被成功调用。
- 将基地址为 pstSrc 的位图的指定区域 pstSrcRect 拷贝到以 pstDst 为目的地址、pstDstRect 为输出区域的内存中。
- 位图信息由 TDE_SURFACE_S 表示,它描述位图的基本信息,包括:位图的像素深度、像素高度、颜色格式等。
- 操作区域由 TDE_RECT_S 表示,它描述位图中参与本次操作的矩形范围,包括:起始位置和尺寸信息。
- 输入和输出的图像宽高需要按照不同格式的对齐要求进行对齐。
ZH_TDE_QuickResize
描述
向任务中添加光栅位图缩放操作。
语法
ZH_S32 ZH_TDE_QuickResize(TDE_HANDLE s32Handle,
const TDE_SURFACE_S *pstSrc,
const TDE_RECT_S *pstSrcRect,
const TDE_SURFACE_S *pstDst,
const TDE_RECT_S *pstDstRect);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
| pstSrc | const TDE_SURFACE_S* | 源位图。 | 输入 |
| pstSrcRect | const TDE_RECT_S* | 源位图操作区域。 | 输入 |
| pstDst | const TDE_SURFACE_S* | 目标位图。 | 输入 |
| pstDstRect | const TDE_RECT_S* | 目标位图操作区域。 | 输入 |
返回值
| 返回值 | 描述 |
|---|---|
| 0 | 成功。 |
| 非 0 | 失败,其值为 TDE 错误码。 |
注意事项
ZH_TDE_Open需要被成功调用。
ZH_TDE_Bitblit
描述
向任务中添加对光栅位图进行有附加功能的搬移操作。
语法
ZH_S32 ZH_TDE_Bitblit(TDE_HANDLE s32Handle,
const TDE_SURFACE_S *pstBackGround,
const TDE_RECT_S *pstBackGroundRect,
const TDE_SURFACE_S *pstForeGround,
const TDE_RECT_S *pstForeGroundRect,
const TDE_SURFACE_S *pstDst,
const TDE_RECT_S *pstDstRect,
const TDE_OPT_S *pstOpt);
参数
| 参数名 | 数据类型 | 描述 | 输入/输出 |
|---|---|---|---|
| s32Handle | TDE_HANDLE | TDE 任务句柄。 | 输入 |
| pstBackGround | const TDE_SURFACE_S* | 背景位图。 | 输入 |
| pstBackGroundRect | const TDE_RECT_S* | 背景位图操作区域。 |