跳到主要内容
版本:2.8.1

图形处理 (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
1628不支持
ZH_FMT_YUV420p1628不支持
ZH_FMT_YUV422SP1628不支持
ZH_FMT_YUV422_YUYV1628不支持
ZH_FMT_YUV400SP1628不支持
ZH_FMT_YUV420SP_10BIT
ZH_FMT_YUV422SP_10BIT
64210不支持
ZH_FMT_RGB5658116不支持
ZH_FMT_BGR5658116不支持
ZH_FMT_RGB88816124不支持
ZH_FMT_BGR88816124不支持
ZH_FMT_RGBA88884132不支持
ZH_FMT_BGRA88884132不支持
ZH_FMT_RGBA5551
ZH_FMT_BGRA5551
32116不支持

注意:

  • TDE 操作区域的对齐格式都有关系,如果是 rgb 格式的宽高和偏移不需要对齐,yuv 格式宽高和偏移均需 2 像素对齐。
  • 调用 TDE 操作时,请确保 ZH_TDE_Open() 被成功调用,否则硬件无法被使用。
  • 除了快速接口的操作外,TDE 暂不支持输入输出压缩格式,请保证图像输入为非压缩(非 AFBC 等任意压缩格式)。
  • TDE 支持图像大小在 64x64 到 8192x8192 范围内的缩放。

API 参考

该功能模块为用户提供以下API:


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

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
bSyncZH_BOOL暂时不使用。输入
bBlockZH_BOOL阻塞标志。
ZH_TRUE: 阻塞。
ZH_FALS: 非阻塞。
输入
u32TimeOutZH_U32超时时间,单位: ms。输入

返回值

返回值描述
0成功。
非 0失败,其值为TDE 错误码

注意事项

  • ZH_TDE_Open 需要被成功调用。
  • 在调用此接口前应保证调用 ZH_TDE_BeginJob 获得了有效的任务句柄。
  • 此接口若为阻塞接口,到达超时时间调用函数会返回,但是操作依然会继续完成。

ZH_TDE_CancelJob

描述

取消 TDE 任务。

语法

ZH_S32 ZH_TDE_CancelJob(TDE_HANDLE s32Handle);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入

返回值

返回值描述
0成功。
非 0失败,其值为 TDE 错误码

注意事项

  • ZH_TDE_Open 需要被成功调用。
  • 保证调用 ZH_TDE_BeginJob 获得了有效的任务句柄,否则返回值无效。
  • 已经提交的任务不能够再取消。
  • 取消后的任务不再有效,故不能再向其添加操作,也不能提交该任务。

ZH_TDE_WaitForDone

描述

等待指定的任务完成。

语法

ZH_S32 ZH_TDE_WaitForDone(TDE_HANDLE s32Handle);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入

返回值

返回值描述
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);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
pstSrcconst TDE_SURFACE_S*源位图。输入
pstSrcRectconst TDE_RECT_S*源位图操作区域。输入
pstDstconst TDE_SURFACE_S*目标位图。输入
pstDstRectconst 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);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
pstSrcconst TDE_SURFACE_S*源位图。输入
pstSrcRectconst TDE_RECT_S*源位图操作区域。输入
pstDstconst TDE_SURFACE_S*目标位图。输入
pstDstRectconst 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);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
pstBackGroundconst TDE_SURFACE_S*背景位图。输入
pstBackGroundRectconst TDE_RECT_S*背景位图操作区域。输入
pstForeGroundconst TDE_SURFACE_S*前景位图。输入
pstForeGroundRectconst TDE_RECT_S*前景位图操作区域。输入
pstDstconst TDE_SURFACE_S*目标位图。输入
pstDstRectconst TDE_RECT_S*目标位图操作区域。输入
pstOptconst TDE_OPT_S*运算参数设置结构。输入

返回值

返回值描述
0成功。
非 0失败,其值为 TDE 错误码

注意事项

  • ZH_TDE_Open 需要被成功调用。
  • 将前景位图(pstForeGround)与背景位图(pstBackGround)的指定区域(pstForeGroundRect、pstBackGroundRect)进行运算,将运算后的位图拷贝到目标位图(pstDst)的指定区域(pstDstRect)中。
    其中背景位图(pstBackGround)的指定区域(pstBackGroundRect)和目标目标位图(pstDst)的指定区域(pstDstRect)必须一致。
  • 支持指定区域旋转、裁剪、缩放和叠加操作。暂时不支持 ROP 操作。
  • Alpha 混合操作有两种方式:
    • 一种是将前景位图和背景位图根据配置的混合模型进行 Alpha 叠加计算,然后输出到背景位图上面。
    • 一种是将背景位图和前景位图进行 Alpha 叠加后输出到目标位图。

ZH_TDE_QuickFill

描述

向任务中添加快速填充操作。

语法

ZH_S32 ZH_TDE_QuickFill(TDE_HANDLE s32Handle,
TDE_SURFACE_S *pstDst,
TDE_RECT_S *pstDstRect,
ZH_U32 u32FillData);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
pstDstTDE_SURFACE_S*目标位图。输入
pstDstRectTDE_RECT_S*目标位图操作区域。输入
u32FillDataZH_U32填充值。输入

返回值

返回值描述
0成功。
非 0失败,其值为 TDE 错误码

注意事项

  • ZH_TDE_Open 需要被成功调用。
  • 该操作直接将 u32FillData 填充在位图的指定区域内。
  • 目标位图为 ARGB1555 / BGRA5551 时,u32FillData 参数由高到低位分别是 A(1bit)、R(5bit)、G(5bit)、B(5bit)。例如,红色:u32FillData = 0x00007C00。
  • 其他位图格式,u32FillData 参数由高到低位分别是 A(8bit)、R(8bit)、G(8bit)、B(8bit)。例如,红色:u32FillData = 0x00ff0000。
  • 不支持处理输入的数据为压缩格式。

ZH_TDE_Rotate

描述

向任务中添加光栅位图旋转操作。

语法

ZH_S32 ZH_TDE_Rotate(TDE_HANDLE s32Handle,
TDE_SURFACE_S *pstSrc,
TDE_RECT_S *pstSrcRect,
TDE_SURFACE_S *pstDst,
TDE_RECT_S *pstDstRect,
ROTATION_E enRotateAngle);

参数

参数名数据类型描述输入/输出
s32HandleTDE_HANDLETDE 任务句柄。输入
pstSrcTDE_SURFACE_S*源位图。输入
pstSrcRectTDE_RECT_S*源位图操作区域。输入
pstDstTDE_SURFACE_S*目标位图。输入
pstDstRectTDE_RECT_S*目标位图操作区域。输入
enRotateAngleROTATION_E旋转的角度。输入

返回值

返回值描述
0成功。
非 0失败,其值为 TDE 错误码

注意事项

  • ZH_TDE_Open需要被成功调用。
  • 将基地址为 pstSrc 的位图以区域 pstSrcRect 指定的尺寸旋转至 pstDstRect 的尺寸,将结果拷贝到以 pstDst 为目的地址、pstDstRect 为输出区域的内存中,可以做 90 度,180 度和 270 度顺时针转。

数据类型

图形处理相关数据类型、数据结构定义如下:


TDE_MAX_JOB_NUM

说明

定义最大的 job 个数。

定义

#define TDE_MAX_JOB_NUM         128

TDE_MAX_TASK_NUM

说明

定义最大的 task 个数。

定义

#define TDE_MAX_TASK_NUM        200

TDE_HANDLE

说明

定义 job 的句柄。

定义

typedef ZH_S32 TDE_HANDLE;

TDE_SURFACE_S

说明

定义 job 的 surface。

定义

typedef struct zhTDE_SURFACE_S {
MB_BLK pMbBlk;
PIXEL_FORMAT_E enColorFmt;
ZH_U32 u32Height;
ZH_U32 u32Width;
COMPRESS_MODE_E enComprocessMode;
ZH_BOOL bAlphaExt1555;
ZH_U8 u8Alpha0;
ZH_U8 u8Alpha1;
} TDE_SURFACE_S;

成员

成员名称数据类型描述
pMbBlkMB_BLK缓存块句柄。
enColorFmtPIXEL_FORMAT_E图像格式类型。
u32HeightZH_U32图像高度。
u32WidthZH_U32图像宽度。
enComprocessModeCOMPRESS_MODE_E图像的压缩类型。
bAlphaExt1555ZH_BOOL不支持。
u8Alpha0ZH_U8不支持。
u8Alpha1ZH_U8不支持。

注意事项

TDE 输入输出图像均存储在 pMbBlk 中,输入输出均需要外部申请合理合法的缓存块。


TDE_RECT_S

说明

TDE 操作区域属性。

定义

typedef struct zhTDE_RECT_S {
ZH_S32 s32Xpos;
ZH_S32 s32Ypos;
ZH_U32 u32Width;
ZH_U32 u32Height;
} TDE_RECT_S;

成员

成员名称数据类型描述
s32XposZH_S32操作区域的起始横坐标,以像素数为单位。有效范围:[0, 位图宽度)。
s32YposZH_S32操作区域的起始纵坐标,以像素数为单位。有效范围:[0, 位图高度)。
u32WidthZH_U32操作区域的宽度,以像素数为单位。有效范围:(0, 8192]。
u32HeightZH_U32操作区域的高度,以像素数为单位。有效范围:(0, 8192]。

注意事项

  • TDE 输入输出图像均存储在 pMbBlk 中,输入输出均需要外部申请合理合法的缓存块。
  • 操作区域不可超出位图区域,若超出,则返回相应 TDE 错误码

TDE_BLENDCMD_E

说明

TDE blend 模式属性,Alpha 混合命令,用于计算进行 alpha 混合以后的像素值。

定义

typedef enum zhTDE_BLENDCMD_E {
TDE_BLENDCMD_NONE = 0x0,
TDE_BLENDCMD_CLEAR,
TDE_BLENDCMD_SRC,
TDE_BLENDCMD_SRCOVER,
TDE_BLENDCMD_DSTOVER,
TDE_BLENDCMD_SRCIN,
TDE_BLENDCMD_DSTIN,
TDE_BLENDCMD_SRCOUT,
TDE_BLENDCMD_DSTOUT,
TDE_BLENDCMD_SRCATOP,
TDE_BLENDCMD_DSTATOP,
TDE_BLENDCMD_ADD,
TDE_BLENDCMD_XOR,
TDE_BLENDCMD_DST,
TDE_BLENDCMD_CONFIG,
TDE_BLENDCMD_BUTT,
} TDE_BLENDCMD_E;

成员

计算公式:pixel = (foreground x fs + background x fd),其中:

  • fs: foreground blend coefficient;
  • fd: destination blend coefficient;
  • pixel: 运算以后的像素值;
  • foreground: 前景位图的像素值;
  • background: 背景位图的像素值;
  • sa: forground alpha;
  • da: background alpha。
成员名称描述
TDE_BLENDCMD_NONEfs 取 sa,fd 取 1.0 - sa。
TDE_BLENDCMD_CLEARfs 取 0.0,fd 取 0.0。
TDE_BLENDCMD_SRCfs 取 1.0,fd 取 0.0。
TDE_BLENDCMD_SRCOVERfs 取 1.0,fd 取 1.0 - sa。
TDE_BLENDCMD_DSTOVERfs 取 1.0 - da,fd 取 1.0。
TDE_BLENDCMD_SRCINfs 取 da,fd 取 0.0。
TDE_BLENDCMD_DSTINfs 取 0.0,fd 取 sa。
TDE_BLENDCMD_SRCOUTfs 取 1.0 - da,fd 取 0.0。
TDE_BLENDCMD_DSTOUTfs 取 0.0,fd 取 1.0 - sa。
TDE_BLENDCMD_SRCATOPfs 取 da,fd 取 1.0 - sa。
TDE_BLENDCMD_DSTATOPfs 取 1.0 - da,fd 取 sa。
TDE_BLENDCMD_ADDfs 取 1.0,fd 取 1.0。
TDE_BLENDCMD_XORfs 取 1.0 - da,fd 取 1.0 - sa。
TDE_BLENDCMD_DSTfs 取 0.0,fd 取 1.0。
TDE_BLENDCMD_CONFIG用户自己配置参数。
TDE_BLENDCMD_BUTT无效的 alpha 混合命令。

注意事项

alpha 混合目前只支持将前景位图和背景位图根据配置的混合模型进行 Alpha 叠加计算,然后输出到背景位图上面。


TDE_OPT_S

说明

TDE 操作属性结构体。

定义

typedef struct zhTDE_OPT_S {
TDE_COLORKEY_MODE_E enColorKeyMode;
ZH_U32 unColorKeyValue;
MIRROR_E enMirror;
TDE_RECT_S stClipRect;
ZH_U32 u32GlobalAlpha;
TDE_BLENDCMD_E eBlendCmd;
} TDE_OPT_S;

成员

成员名称数据类型描述
enColorKeyModeTDE_COLORKEY_MODE_E不支持。
unColorKeyValueZH_U32不支持。
enMirrorMIRROR_E镜像类型。
stClipRectTDE_RECT_Sclip 区域定义。
u32GlobalAlphaZH_U32全局 alpha 值。取值范围:[0, 255]。
eBlendCmdTDE_BLENDCMD_Eblend 方式。

TDE 错误码

TDE API 的 TDE 错误码如下所示。

错误代码宏定义描述
0xA00E8005ZH_ERR_TDE_DEV_NOT_OPENTDE 设备未打开,API 调用失败。
0xA00E8012ZH_ERR_TDE_DEV_OPEN_FAILED开启 TDE 设备失败。
0xA00E8006ZH_ERR_TDE_NULL_PTR参数中有空指针错误。
0xA00E800CZH_ERR_TDE_NO_MEM内存不足,无法添加操作。
0xA00E8001ZH_ERR_TDE_INVALID_HANDLE非法的 TDE 任务句柄。
0xA00E8003ZH_ERR_TDE_INVALID_PARA无效的参数设置。
0xA00E803EZH_ERR_TDE_NOT_ALIGNEDClut 表的起始地址没有按照 4byte 对齐。
0xA00E803FZH_ERR_TDE_MINIFICATION缩小倍数过大。
0xA00E8040ZH_ERR_TDE_CLIP_AREA操作区域与 clip 区域没有交集,显示不会有更新。
0xA00E8041ZH_ERR_TDE_JOB_TIMEOUT等待超时。
0xA00E8042ZH_ERR_TDE_UNSUPPORTED_OP_ERATION不支持的操作。
0xA00E8043ZH_ERR_TDE_QUERY_TIMEOUT指定的任务超时未完成。
0xA00E8044ZH_ERR_TDE_INTERRUPT等待任务完成被中断。