MI GFX API

1. 概述¶

1.1. 模块说明¶

GFX（Graphic Engine）硬件为画UI提供快速的图形绘制功能，主要有矩形色彩填充、位图搬移（支持缩放、旋转、镜像翻转、格式转换、alpha混合叠加、ColorKey等操作）。目前仅Taiyaki、Takoyaki、Tiramisu、Ikayaki系列芯片支持GFX。

Rotate：HW支持90/180/270度旋转

图1-1

Alpha混合叠加：支持正常的2D alpha操作

图1-2

镜像：支持H镜像，V镜像，HV同时镜像

图1-3

缩放：支持在bitblit的时候缩放

图1-4

在利用双线性插值进行缩放，会涉及到图像的几何中心偏移的概念。以下图为例，当需要将5x5的图像（如图(1)）缩小到3x3的图像（如图(2)）。当不设置偏移的情况下，缩放后图像和原图像的像素对应关系如图(3)会出现整体偏左，图(4)为有设置图像几何中心偏移的对应关系。

图像几何中心：

$SrcX = (dstX + coeff)\times (srcWidth/dstWidth) - coeff$

$SrcY = (dstY + coeff) \times (srcHeight/dstHeight)- coeff$

其他操作就不一一罗列，和标准的2D加速基本一致。

1.2. 调用流程框图¶

图1-5

如果想用GE来处理视频或者UI数据都可以如下流程使用即可

图1-6

1.3. 关键字说明¶

Fence

对应一个GFX的操作需要等待的状态，会阻塞等待，但是内部也会有超时机制用来防呆。
Colorkey

关键色，比如在做搬移的时候可以去掉位图中的某一个颜色，这就可以把这个颜色设置为关键色。
Pitch

每行像素占的字节数，(像素位数/8) * Width，也对应常用的Stride、LineLength。

2. API参考¶

该功能模块提供以下 API：

API名	功能
MI_GFX_Open	打开 GFX 设备
MI_GFX_Close	关闭 GFX 设备
MI_GFX_WaitAllDone	等待 GFX 的所有任务完成
MI_GFX_QuickFill	向任务中添加快速填充操作
MI_GFX_GetARGB8888To1555AlphaThreshold	获取ARGB8888转ARGB1555的alpha判决阈值
MI_GFX_SetARGB8888To1555AlphaThreshold	设置ARGB8888转ARGB1555的alpha判决阈值
MI_GFX_Bitblit	向任务中添加对光栅位图进行有附加功能的搬移操作
MI_GFX_SetPalette	设置索引颜色格式的调色板
MI_GFX_CreateDev	初始化GFX设备
MI_GFX_DestroyDev	反初始化GFX设备
MI_GFX_GetARGB1555To8888AlphaValue	获取ARGB1555转ARGB8888的alpha转换值
MI_GFX_SetARGB1555To8888AlphaValue	设置ARGB1555转ARGB8888的alpha转换值
MI_GFX_GetInitialScalingCoeff	获取初始缩放系数
MI_GFX_SetInitialScalingCoeff	设置初始缩放系数

2.1. MI_GFX_Open¶

功能

调用此接口打开GFX 设备并初始化硬件设备。

语法

MI_ S32 MI_GFX_Open(MI_GFX_DEV GfxDevId);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入
返回值
- MI_SUCCESS 打开设备成功。
- 初始化失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意
1. 在进行 GFX相关操作前应该首先调用此接口，保证 GFX 设备处于打开状态。
2. GFX设备初始化一次后，再次调用将返回已初始化，可重复调用。

举例

1.  MI_S32 s32Ret = 0;    
2.  #define DEFAULT_GFX_DEV_ID (0)  
3.  #define DEFAULT_SOC_ID (0)  
4.    
5.  MI_SYS_Init(DEFAULT_SOC_ID);  
6.  /* open GFX device*/    
7.  s32Ret = MI_GFX_Open(DEFAULT_GFX_DEV_ID);     
8.  if (MI_SUCCESS != s32Ret)    
9.  {    
10.     return -1;    
11. }    
12. /* close GFX device*/     
13. MI_GFX_Close(DEFAULT_GFX_DEV_ID);    
14. MI_SYS_Exit(DEFAULT_SOC_ID);

2.2. MI_GFX_Close¶

功能

调用此接口关闭 GFX设备。

语法

MI_ S32 MI_GFX_Close(MI_GFX_DEV GfxDevId);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入
返回值
- MI_SUCCESS 成功销毁GFX模块。
- 销毁GFX模块失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意

调用 MI_GFX_Open 与 MI_GFX_Close 的次数需要对应，可以重复调用，Open的次数和Close的次数一致时，GFX的api将不再能调用。

2.3. MI_GFX_WaitAllDone¶

功能

调用此接口等待 GFX 的所有任务完成或者等待指定的任务完成。

语法

MI_S32 MI_GFX_WaitAllDone(MI_GFX_DEV GfxDevId, MI_BOOL bWaitAllDone, MI_U16 u16TargetFence);

形参

参数名称	描述	输入/输出
GfxDevId	GFX设备号	输入
bWaitAllDone	是否等待所有GFX任务完成	输入
u16TargetFence	等待指定的fence完成，在bWaitAllDone为FALSE时才有效	输入

返回值
- MI_SUCCESS 等待的GFX任务都已经完成。
- 等待GFX任务完成失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意
- 此接口为阻塞接口，会阻塞等待所有的 GFX 任务完成。

2.4. MI_GFX_QuickFill¶

功能

将数据值u32ColorVal填充到以pstDst 为目的地址、pstDstRect 为输出区域的内存中，可实现颜色填充的功能。

语法

MI_S32 MI_GFX_QuickFill(MI_GFX_DEV GfxDevId, MI_GFX_Surface_t *pstDst, MI_GFX_Rect_t *pstDstRect, MI_U32 u32ColorVal, MI_U16    *pu16Fence);

形参

参数名称	描述	输入/输出
GfxDevId	GFX设备号	输入
pstDst	目标位图	输入
pstDstRect	目标位图操作区域	输入
u32ColorVal	填充颜色值	输入
pu16Fence	返回的Fence指针	输出

返回值
- MI_SUCCESS 成功添加QuickFill行为的任务到HW队列。
- 填充色块失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意
- 由于该操作直接将u32ColorVal填充在位图的指定区域内，调用者欲填充蓝色到指定位图，应按照位图格式指定相应的蓝色填充值。
- 如位图格式为 ARGB1555，欲填充为蓝色，则应指定 u32ColorVal为 0x801F（其中alpha 位为 1）。
- u32ColorVal从高位到低位，依次是A8：R8：G8：B8，如果Dst的格式为YUV，则A8则无效，R对应Y，G对应U，B对应V。

举例

#define DEFAULT_GFX_DEV_ID (0)
ExecFunc(MI_SYS_Init(), MI_SUCCESS);  
FILE *fp = NULL;  
fp = fopen(SRC_FILE_NAME, "wb");  
ExecFunc(MI_SYS_MMA_Alloc("mma_heap_name0", SRC_WIDTH*SRC_HEIGHT*2, &phyAddr), MI_SUCCESS);

//MI_U32 phySrcAddr, phyDstAddr;  
ExecFunc(MI_GFX_Open(DEFAULT_GFX_DEV_ID), MI_SUCCESS);  
ExecFunc(MI_SYS_Mmap(phyAddr, SRC_WIDTH*SRC_HEIGHT*2, &u64VirAddr , FALSE), MI_SUCCESS);  
memset(u64VirAddr, 0x22, SRC_WIDTH*SRC_HEIGHT*2);

//fillrect  
stSrc.eColorFmt = E_MI_GFX_FMT_ARGB1555;  
stSrc.u32Width = SRC_WIDTH;  
stSrc.u32Height = SRC_HEIGHT;  
stSrc.u32Stride = SRC_WIDTH * 2;  
stSrc.phyAddr = phyAddr;

stSrcRect.s32Xpos = 100;  
stSrcRect.s32Ypos = 100;  
stSrcRect.u32Width = 100;  
stSrcRect.u32Height = 100;  
ExecFunc(MI_GFX_QuickFill(DEFAULT_GFX_DEV_ID, &stSrc, &stSrcRect, u32ColorVal, &u16TargetFence), MI_SUCCESS);  
ExecFunc(MI_GFX_WaitAllDone(DEFAULT_GFX_DEV_ID, FALSE, u16TargetFence), MI_SUCCESS);  
if (NULL != fp)  
{  
    fwrite(u64VirAddr, 1, SRC_WIDTH*SRC_HEIGHT*2, fp);  
    fclose(fp);  
    fp = NULL;  
}  
ExecFunc(MI_SYS_Munmap(u64VirAddr, SRC_WIDTH*SRC_HEIGHT*2), MI_SUCCESS);  
ExecFunc(MI_SYS_MMA_Free(phyAddr), MI_SUCCESS);

ExecFunc(MI_GFX_Close(DEFAULT_GFX_DEV_ID), MI_SUCCESS);  
ExecFunc(MI_SYS_Exit(), MI_SUCCESS);

2.5. MI_GFX_GetARGB8888To1555AlphaThreshold¶

功能

获取 alpha 判决阈值。用于结果图片像素格式为 ARGB1555 的情况。若前景位图和背景位图的 alpha 运算结果小于此阈值，结果像素的 alpha 位取 0；大于或等于此阈值，像素的 alpha 位取 1。

语法

MI_S32 MI_GFX_GetARGB8888To1555AlphaThreshold(MI_GFX_DEV GfxDevId, MI_U8 *pu8ThresholdValue);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

pu8ThresholdValue 指向 alpha 判决阈值的指针输出
返回值
- MI_SUCCESS 成功获取到alpha阈值。
- 获取alpha阈值失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意

暂不支持。

2.6. MI_GFX_SetARGB8888To1555AlphaThreshold¶

功能

设置 alpha 判决阈值。当前景和背景做 bitblit 操作时，不管前景位图和背景位图的格式为什么，硬件都会生成 ARGB8888 的中间位图格式，若目标图片像素格式为 ARGB1555 的情况，则若前景位图和背景位图的 alpha 运算结果小于此阈值，结果象素的 alpha 位取0；大于或等于此阈值，像素的 alpha 位取 1。

语法

MI_S32 MI_GFX_SetARGB8888To1555AlphaThreshold(MI_GFX_DEV GfxDevId, MI_U8 u8ThresholdValue);

形参

数名称描述输入/输出

GfxDevId GFX设备号输入

u8ThresholdValue alpha 判决阈值输入
返回值
- MI_SUCCESS 成功设置alpha阈值。
- 设置alpha阈值失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意

暂不支持。

2.7. MI_GFX_BitBlit¶

功能
- 将前景位图（pstSrc）与目标位图（pstDst）的指定区域（pstSrcRect、pstDstRect）进行运算，将运算后的位图拷贝到目标位图（pstDst）的指定区域（pstDstRect）中。
- MI_GFX_Opt_t 结构中存放有 GFX 运算功能的配置信息，如：是否作色键（colorkey）及 colorkey 的配置值；是否作区域裁减（clip 操作）及指定 clip 区域；是否镜像、是否进行 alpha 混合等信息。上述的操作可以同时使能。

语法

MI_S32 MI_GFX_BitBlit(MI_GFX_DEV GfxDevId, MI_GFX_Surface_t *pstSrc, MI_GFX_Rect_t *pstSrcRect,  MI_GFX_Surface_t *pstDst,  MI_GFX_Rect_t *pstDstRect, MI_GFX_Opt_t *pstOpt, MI_U16 *pu16Fence);

形参

参数名称	描述	输入/输出
GfxDevId	GFX设备号	输入
pstSrc	源位图。	输入
pstSrcRect	源位图操作区域。	输入
pstDst	目标位图。	输入
pstDstRect	目标位图操作区域。	输入
pstOpt	运算参数设置结构。	输入
pu16Fence	返回的Fence指针	输出

返回值
- MI_SUCCESS 初始化成功。
- 返回失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意
- 在调用此接口前应保证调用 MI_GFX_Open 打开 GFX 设备。
- 当源位图操作区域与目标位图操作区域尺寸不一致时，源区域按照目标区域比例进行缩放后，再与目标区域做运算。
- clip 操作时若为区域内 clip，则裁减区域必须与操作区域有公共交集，否则会返回错误。
- MI_GFX_Opt_t 结构中存放有 GFX 运算功能的配置信息，如：是否作色键（colorkey）及 colorkey 的配置值；是否作区域裁减（clip 操作）及指定 clip 区域；是否镜像、是否进行 alpha 混合等信息。上述的操作可以同时使能。

举例

#define DEFAULT_GFX_DEV_ID (0)
ExecFunc(MI_SYS_Init(), MI_SUCCESS);  
FILE *fp = NULL;  
FILE *dstfp = NULL;  
fp = fopen(SRC_FILE_NAME, "wb");  
dstfp = fopen(DST_FILE_NAME, "wb");  
ExecFunc(MI_SYS_MMA_Alloc("mma_heap_name0", SRC_WIDTH*SRC_HEIGHT*2, &phyAddr), MI_SUCCESS);  
ExecFunc(MI_SYS_MMA_Alloc("mma_heap_name0", DST_WIDTH*360*2, &phyAddr2), MI_SUCCESS);

//MI_U32 phySrcAddr, phyDstAddr;  
ExecFunc(MI_GFX_Open(DEFAULT_GFX_DEV_ID), MI_SUCCESS);  
ExecFunc(MI_SYS_Mmap(phyAddr, SRC_WIDTH*SRC_HEIGHT*2, &u64VirAddr , FALSE), MI_SUCCESS);  
memset(u64VirAddr, 0x22, SRC_WIDTH*SRC_HEIGHT*2);

ExecFunc(MI_SYS_Mmap(phyAddr2, DST_WIDTH*DST_HEIGHT*2, &u64VirAddr2 , FALSE), MI_SUCCESS);  
memset(u64VirAddr2, 0x0F, DST_WIDTH*DST_HEIGHT*2);

//bitblit  
stSrc.eColorFmt = E_MI_GFX_FMT_ARGB1555;  
stSrc.u32Width = SRC_WIDTH;  
stSrc.u32Height = SRC_HEIGHT;  
stSrc.u32Stride = SRC_WIDTH * 2;  
stSrc.phyAddr = phyAddr;

stSrcRect.s32Xpos = 100;  
stSrcRect.s32Ypos = 100;  
stSrcRect.u32Width = 300;  
stSrcRect.u32Height = 300;

stDst.eColorFmt = E_MI_GFX_FMT_ARGB1555;  
stDst.u32Width = DST_WIDTH;  
stDst.u32Height = DST_HEIGHT;  
stDst.u32Stride = DST_WIDTH * 2;  
stDst.phyAddr = phyAddr2;

stDstRect.s32Xpos = 200;  
stDstRect.s32Ypos = 100;  
stDstRect.u32Width = 200;  
stDstRect.u32Height = 100;  
ExecFunc(MI_GFX_BitBlit(DEFAULT_GFX_DEV_ID, &stSrc, &stSrcRect, &stDst, &stDstRect, NULL, &u16TargetFence), MI_SUCCESS);  
ExecFunc(MI_GFX_WaitAllDone(DEFAULT_GFX_DEV_ID, FALSE, u16TargetFence), MI_SUCCESS);  
if (NULL != dstfp)  
{  
    fwrite(u64VirAddr2, 1, DST_WIDTH*DST_HEIGHT*2, dstfp);  
    fclose(dstfp);  
    dstfp = NULL;  
}

ExecFunc(MI_SYS_Munmap(u64VirAddr, SRC_WIDTH*SRC_HEIGHT*2), MI_SUCCESS);  
ExecFunc(MI_SYS_MMA_Free(phyAddr), MI_SUCCESS);

ExecFunc(MI_SYS_Munmap(u64VirAddr2, DST_WIDTH*DST_HEIGHT*2), MI_SUCCESS);  
ExecFunc(MI_SYS_MMA_Free(phyAddr2), MI_SUCCESS);

ExecFunc(MI_GFX_Close(DEFAULT_GFX_DEV_ID), MI_SUCCESS);

2.8. MI_GFX_SetPalette¶

功能

为索引颜色格式(I2/I4/I8)设置调色板

语法

MI_S32 MI_GFX_SetPalette(MI_GFX_DEV GfxDevId, MI_GFX_ColorFmt_e eColorFmt, MI_GFX_Palette_t* pstPalette);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

eColorFmt 调色板对应的颜色格式: MI_GFX_ColorFmt_e 输入

pstPalette 调色板数据输入
返回值
- MI_SUCCESS 初始化成功。
- 返回失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意

pstPalette 是一个容量为256的MI_GFX_PaletteEntry_t 数组,每一个MI_GFX_PaletteEntry_t代表一种颜色,对应在数组中的下标代表了颜色的索引。

举例

#define DEFAULT_GFX_DEV_ID (0)
MI_GFX_Palette_t myPal;  
MI_GFX_PaletteEntry_t index_0; 
MI_GFX_PaletteEntry_t index_1;
index_0.RGB.u8A = 0x40;
index_0.RGB.u8R = 0xFF;  
index_0.RGB.u8G = 0; 
index_0.RGB.u8B = 0;
index_1.RGB.u8A = 0x40;
index_1.RGB.u8R = 0; 
index_1.RGB.u8G = 0xFF;
index_1.RGB.u8B = 0;

myPal.aunPalette[0] = index_0; 
myPal.aunPalette[1] = index_1; 
myPal.u16PalStart = 0
myPal.u16PalEnd = 1;
MI_GFX_SetPalette(DEFAULT_GFX_DEV_ID, E_MI_GFX_FMT_I8,&myPal);

2.9. MI_GFX_CreateDev¶

功能

初始化gfx设备。

语法

MI_S32 MI_GFX_CreateDev(MI_GFX_DEV GfxDevId, MI_GFX_DevAttr_t *pstDevAttr);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

pstDevAttr 设备初始化参数。输入
返回值
- MI_SUCCESS 成功。
- 失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so

2.10. MI_GFX_DestroyDev¶

功能

反初始gfx设备。

语法

MI_S32 MI_GFX_DestroyDev(MI_GFX_DEV GfxDevId);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入
返回值
- MI_SUCCESS 成功。
- 失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so
注意
- 此函数必须在初始化设备后调用，否则返回失败。
- 如果本接口在app退出前没有调用，内部会自动反初始化设备。

2.11. MI_GFX_GetARGB1555To8888AlphaValue¶

功能

获取 alpha 转换值。用于发生ARGB1555到ARGB8888颜色空间转换的情况。若ARGB1555的 alpha 位为0，则转换后ARGB8888的 alpha 为 0；若ARGB1555的 alpha 位为1，则转换后ARGB8888的 alpha 为 alpha 转换值。

语法

MI_S32 MI_GFX_GetARGB1555To8888AlphaValue(MI_GFX_DEV GfxDevId, MI_U8 *pu8AlphaValue);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

pu8AlphaValue alpha 转换值输出
返回值
- MI_SUCCESS 成功。
- 获取alpha转换值失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so

2.12. MI_GFX_SetARGB1555To8888AlphaValue¶

功能

设置 alpha 转换值。当前景和背景做 bitblit 操作时，不管前景位图和背景位图的格式为什么，硬件都会生成 ARGB8888 的中间位图格式，若前景/背景图片象素格式为 ARGB1555 的情况，则若前景位图和背景位图的 alpha 位为0，转换后的ARGB8888 alpha 取0；若前景位图和背景位图的 alpha 位为1，转换后的ARGB8888 alpha 为 alpha转换值。

语法

MI_S32 MI_GFX_SetARGB1555To8888AlphaValue(MI_GFX_DEV GfxDevId, MI_U8 u8AlphaValue);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

u8AlphaValue alpha 转换值输入
返回值
- MI_SUCCESS 成功。
- 获取alpha转换值失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so

2.13. MI_GFX_GetInitialScalingCoeff¶

功能

获取缩放系数。当 bitblit 操作需要缩放时，双线性插值的图像几何中心偏移=缩放系数/1000。

语法

MI_S32 MI_GFX_GetInitialScalingCoeff(MI_GFX_DEV GfxDevId, MI_U16 *pu16ScalingCoefficient);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

pu16ScalingCoefficient 缩放系数输出
返回值
- MI_SUCCESS 成功。
- 获取缩放系数失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so

2.14. MI_GFX_SetInitialScalingCoeff¶

功能

设置缩放系数。当 bitblit 操作需要缩放时，双线性插值的图像几何中心偏移=缩放系数/1000。默认值为500。

语法

MI_S32 MI_GFX_SetInitialScalingCoeff(MI_GFX_DEV GfxDevId, MI_U16 u16ScalingCoefficient);

形参

参数名称描述输入/输出

GfxDevId GFX设备号输入

u16ScalingCoefficient 缩放系数输入
返回值

MI_SUCCESS 成功。

设置缩放系数失败，详情参照错误码。
依赖
- 头文件：mi_gfx.h, mi_gfx_datatype.h
- 库文件：libmi_gfx.a / libmi_gfx.so

3. GFX 数据类型¶

3.1. GFX数据类型说明¶

数据类型	说明
MI_GFX_ColorFmt_e	GFX对应surface color format
MI_GFX_Rect_t	操作区域属性
MI_GFX_ColorKeyOp_e	Colorkey 模式
MI_GFX_Rotate_e	支持旋转角度操作
MI_GFX_ColorKeyValue_t	Colorkey关键色属性
MI_GFX_ColorKeyInfo_t	对应设置的colorkey的颜色值
MI_GFX_DfbBldOp_e	用户自定义 alpha 混合模式
MI_GFX_Mirror_e	图像镜像属性
MI_GFX_Surface_t	位图 surface 结构体
MI_Gfx_DfbBlendFlags_e	GFX blending操作属性结构体
MI_GFX_Opt_t	GFX 操作附加属性结构体
MI_GFX_PaletteEntry_t	索引颜色格式对应的RGB颜色定义
MI_GFX_Palette_t	调色板定义结构体
MI_GFX_DevAttr_t	GFX设备初始化参数
MI_GFX_DEV	GFX的设备号

3.2. MI_GFX_ColorFmt_e¶

说明

GFX支持的颜色格式

定义

typedef enum

{

    E_MI_GFX_FMT_I1 = 0, /* ColorFormat */

    E_MI_GFX_FMT_I2,

    E_MI_GFX_FMT_I4,

    E_MI_GFX_FMT_I8,

    E_MI_GFX_FMT_FABAFGBG2266,

    E_MI_GFX_FMT_1ABFGBG12355,

    E_MI_GFX_FMT_RGB565,

    E_MI_GFX_FMT_ARGB1555,

    E_MI_GFX_FMT_ARGB4444,

    E_MI_GFX_FMT_ARGB1555_DST,

    E_MI_GFX_FMT_YUV422,

    E_MI_GFX_FMT_ARGB8888,

    E_MI_GFX_FMT_RGBA5551,

    E_MI_GFX_FMT_RGBA4444,

    E_MI_GFX_FMT_ABGR8888,

    E_MI_GFX_FMT_BGRA5551,

    E_MI_GFX_FMT_ABGR1555,

    E_MI_GFX_FMT_ABGR4444,

    E_MI_GFX_FMT_BGRA4444,

    E_MI_GFX_FMT_BGR565,

    E_MI_GFX_FMT_RGBA8888,

    E_MI_GFX_FMT_BGRA8888,

    E_MI_GFX_FMT_MAX

} MI_GFX_ColorFmt_e;

注意

对应的surface支持的color format，在bitblt操作时，对应的SrcSurface、DstSurface的颜色格式。

3.3. MI_GFX_Rect_t¶

说明

GFX 操作区域属性。

定义

typedef struct MI_GFX_Rect_s

{

    MI_S32 s32Xpos;

    MI_S32 s32Ypos;

    MI_U32 u32Width;

    MI_U32 u32Height;

} MI_GFX_Rect_t;

成员

成员	描述
s32Xpos	操作区域的起始横坐标，以像素数为单位。有效范围[0, 位图宽度）
s32Ypos	操作区域的起始纵坐标，以像素数为单位。有效范围[0, 位图高度）
u32Width	操作区域的宽度，以像素数为单位。有效范围(0,0xFFF]
u32Height	操作区域的高度，以像素数为单位。有效范围(0,0xFFF]

注意事项
- 若操作区域与位图部分相交，则取相交部分为实际参与操作的区域；若操作区域与位图不相交，则返回相应错误码。
- 操作范围必须在SurFace范围内，否则将无任何操作。

3.4. MI_GFX_ColorKeyOp_e¶

说明

GFX colorkey 操作模式。

定义

typedef enum

{

    E_MI_GFX_RGB_OP_EQUAL = 0,

    E_MI_GFX_RGB_OP_NOT_EQUAL,

    E_MI_GFX_ALPHA_OP_EQUAL,

    E_MI_GFX_ALPHA_OP_NOT_EQUAL,

    E_MI_GFX_ARGB_OP_EQUAL,

    E_MI_GFX_ARGB_OP_NOT_EQUAL,

    E_MI_GFX_CKEY_OP_BUTT,

} MI_GFX_ColorKey_e;

成员

成员	描述
E_MI_GFX_RGB_OP_EQUAL	RGB相等做colorkey 操作
E_MI_GFX_RGB_OP_NOT_EQUAL	RGB不相等做colorkey 操作
E_MI_GFX_ ALPHA_OP_EQUAL	ALPHA相等做colorkey操作
E_MI_GFX_ ALPHA_OP_NOT_EQUAL	ALPHA不相等做colorkey操作
E_MI_GFX_ ARGB_OP_EQUAL	ARGB相等做colorkey 操作，详见注意事项
E_MI_GFX_ARGB_OP_NOT_EQUAL	RGB不相等做colorkey 操作，详见注意事项
E_MI_GFX_CKEY_OP_BUTT	无效的colorkey 操作

注意事项

对位图进行 colorkey 时，可选择前景、背景然后可以选择key值相等或者不等。

3.5. MI_GFX_Rotate_e¶

说明

支持旋转角度操作

定义

typedef enum

{

    E_MI_GFX_ROTATE_0 = 0，

    E_MI_GFX_ROTATE_90，

    E_MI_GFX_ROTATE_180，

    E_MI_GFX_ROTATE_270

} MI_GFX_Rotate_e;

3.6. MI_GFX_ColorKeyValue_t¶

说明

对应设置的colorkey的颜色值

定义

typedef struct MI_GFX_ColorKey_s

{

    MI_U32 u32ColorStart;

    MI_U32 u32ColorEnd;

} MI_GFX_ColorKeyValue_t;

成员

成员描述

u32ColorStart ColorKey颜色范围起始值

u32ColorEnd ColorKey颜色范围结束值
注意事项

当仅针对一个color值做colorkey操作时，将 u32ColorStart = u32ColorEnd = colorVal。

3.7. MI_GFX_ColorKeyInfo_t¶

说明

对应设置的colorkey的颜色值

定义

typedef struct MI_GFX_ColorKeyInfo_s

{

    MI_BOOL bEnColorKey;

    MI_GFX_ColorKeyOp_e eCKeyOp;

    MI_GFX_ColorFmt_e eCKeyFmt;

    MI_GFX_ColorKeyValue_t stCKeyVal;

} MI_GFX_ColorKeyInfo_t;

成员

成员描述

bEnColorKey 是否使能ColorKey操作

eCKeyOp ColorKey操作模式

stCKeyVal ColorKey颜色范围

eCKeyFmt ColorKey的颜色格式
注意事项
- Colorkey操作模式对Surface有效。

3.8. MI_GFX_DfbBldOp_e¶

说明

alpha 混合模式操作。

定义

typedef enum

{

    E_MI_GFX_DFB_BLD_ZERO = 0,

    E_MI_GFX_DFB_BLD_ONE,

    E_MI_GFX_DFB_BLD_SRCCOLOR,

    E_MI_GFX_DFB_BLD_INVSRCCOLOR,

    E_MI_GFX_DFB_BLD_SRCALPHA,

    E_MI_GFX_DFB_BLD_INVSRCALPHA,

    E_MI_GFX_DFB_BLD_DESTALPHA,

    E_MI_GFX_DFB_BLD_INVDESTALPHA,

    E_MI_GFX_DFB_BLD_DESTCOLOR,

    E_MI_GFX_DFB_BLD_INVDESTCOLOR,

    E_MI_GFX_DFB_BLD_SRCALPHASAT,

    E_MI_GFX_DFB_BLD_NONE,

    E_MI_GFX_DFB_BLD_MAX,

} MI_GFX_DfbBldOp_e;

成员

成员	描述
E_MI_GFX_DFB_BLD_OP_ZERO	0
E_MI_GFX_DFB_BLD_OP_ONE	1
E_MI_GFX_DFB_BLD_OP_SRCCOLOR	取 sc
E_MI_GFX_DFB_BLD_OP_INVSRCCOLOR	取 1-sc
E_MI_GFX_DFB_BLD_OP_SRCALPHA	sa
E_MI_GFX_DFB_BLD_OP_INVSRCALPHA	1-sa
E_MI_GFX_DFB_BLD_OP_DESTCOLOR	dc
E_MI_GFX_DFB_BLD_OP_INVDESTCOLOR	1-dc
E_MI_GFX_DFB_BLD_OP_DESTALPHA	da
E_MI_GFX_DFB_BLD_OP_INVDESTALPHA	1-da
E_MI_GFX_DFB_BLD_OP_SRCALPHASAT	min(1-da, sa)＋1
E_MI_GFX_DFB_BLD_NONE	不做 alpha 混合
E_MI_GFX_BLD_MAX	无效的 alpha 混合模式

注意事项

在前景位图和背景位图作叠加运算时，可以分别设置 Src1 通道和 Src2 通道的叠加模式。现在支持 11 种叠加模式。用MI_GFX_DfbBldOp_e设置模式。

3.9. MI_GFX_Mirror_e¶

说明

图像镜像属性。

定义

typedef enum

{

    E_MI_GFX_MIRROR_NONE = 0,

    E_MI_GFX_MIRROR_HORIZONTAL,

    E_MI_GFX_MIRROR_VERTICAL,

    E_MI_GFX_MIRROR_BOTH,

    E_MI_GFX_MIRROR_MAX

} MI_GFX_Mirror_e;

成员

成员	描述
E_MI_GFX_MIRROR_NONE	输出图像不进行镜像操作
E_MI_GFX_MIRROR_HORIZONTAL	输出图像水平镜像
E_MI_GFX_MIRROR_VERTICAL	输出图像垂直镜像
E_MI_GFX_MIRROR_BOTH	输出图像水平+垂直镜像
E_MI_GFX_MIRROR_MAX	无效的镜像类型

3.10. MI_GFX_Surface_t¶

说明

位图 surface 结构体。

定义

typedef struct MI_GFX_Surface_s

{

    MI_PHY phyAddr;

    MI_GFX_ColorFmt_e eColorFmt;

    MI_U32 u32Width;

    MI_U32 u32Height;

    MI_U32 u32Stride;

} MI_GFX_Surface_t;

成员

成员描述

u32PhyAddr 位图首地址

eColorFmt 位图格式

u32Height 位图高度

u32Width 位图宽度

u32Stride 位图跨度
注意事项
- 像素格式大于等于 Byte 的位图格式的位图首地址和 Stride 必须按照像素格式对齐，像素格式不足 Byte 的位图格式的位图首地址和 Stride 需要按照 Byte 对齐。
- 像素格式不足 Byte 的位图格式的水平起始位置和宽度必须按照像素对齐。
- YCbCr422 格式的位图的水平起始位置和宽度必须为偶数。

3.11. MI_Gfx_DfbBlendFlags_e¶

说明

GFX blending操作属性结构体。

定义

typedef enum

{

    E_MI_GFX_DFB_BLEND_NOFX = 0x00000000,

    E_MI_GFX_DFB_BLEND_COLORALPHA = 0x00000001,

    E_MI_GFX_DFB_BLEND_ALPHACHANNEL = 0x00000002,

    E_MI_GFX_DFB_BLEND_COLORIZE = 0x00000004,

    E_MI_GFX_DFB_BLEND_SRC_PREMULTIPLY = 0x00000008,

    E_MI_GFX_DFB_BLEND_SRC_PREMULTCOLOR = 0x00000010,

    E_MI_GFX_DFB_BLEND_DST_PREMULTIPLY = 0x00000020,

    E_MI_GFX_DFB_BLEND_XOR = 0x00000040,

    E_MI_GFX_DFB_BLEND_DEMULTIPLY = 0x00000080,

    E_MI_GFX_DFB_BLEND_SRC_COLORKEY = 0x00000100,

    E_MI_GFX_DFB_BLEND_DST_COLORKEY = 0x00000200,

    E_MI_GFX_DFB_BLEND_MAX = 0x3FF

} MI_Gfx_DfbBlendFlags_e;

成员

成员	描述
E_MI_GFX_DFB_BLEND_NOFX	没有任何BLD操作
E_MI_GFX_DFB_BLEND_COLORALPHA	src alpha会根据const color value运算 src.a = const color.a;
E_MI_GFX_DFB_BLEND_ALPHACHANNEL	src alpha会根据const color value运算 src.a = src.a * const color.a;
E_MI_GFX_DFB_BLEND_COLORIZE	将const color作为全局颜色，调整源颜色
E_MI_GFX_DFB_BLEND_SRC_PREMULTIPLY	使用源alpha预乘源颜色 src.r = src.r * src.a;等
E_MI_GFX_DFB_BLEND_SRC_PREMULTCOLOR	使用const alpha预乘源颜色 src.r = src.r * const.a;等
E_MI_GFX_DFB_BLEND_DST_PREMULTIPLY	使用目的alpha预乘目的颜色 dst.r = dst.r * dst.a;等
E_MI_GFX_DFB_BLEND_XOR	调节和预乘alpha src.a ^= dst.a;
E_MI_GFX_DFB_BLEND_DEMULTIPLY	预乘到非预乘的转换，最好不要使用这样的操作 x.r = ((int)x.r << 8) / ((int)x.a + 1);等
E_MI_GFX_DFB_BLEND_SRC_COLORKEY	如果src的颜色等于const color，则会被key掉
E_MI_GFX_DFB_BLEND_DST_COLORKEY	如果dst的颜色等于const color，则会被key掉
E_MI_GFX_DFB_BLEND_MAX	上面所有的action都会被使能

3.12. MI_GFX_Opt_t¶

说明

GFX 操作属性结构体。

定义

ty typedef struct MI_GFX_Opt_s

{

    MI_GFX_Rect_t stClipRect;

    MI_GFX_ColorKeyInfo_t stSrcColorKeyInfo;

    MI_GFX_ColorKeyInfo_t stDstColorKeyInfo;

    MI_GFX_DfbBldOp_e eSrcDfbBldOp;

    MI_GFX_DfbBldOp_e eDstDfbBldOp;

    MI_GFX_Mirror_e eMirror;

    MI_GFX_Rotate_e eRotate;

    MI_Gfx_DfbBlendFlags_e eDFBBlendFlag;

    MI_U32 u32GlobalSrcConstColor;

    MI_U32 u32GlobalDstConstColor;

} MI_GFX_Opt_t;

成员

成员	描述
stSrcColorKeyInfo	Src surface colorkey 操作
stDstColorKeyInfo	Dst surface colorkey操作
stClipRect	clip 区域定义
eMirror	镜像类型
eSrcDfbBldOp	Src Surface BLEND操作类型
eDstDfbBldOp	Dst Surface BLEND操作类型
eRotate	支持旋转角度，0、90、180、270度旋转
eDFBBlendFlag	Blending的相关操作，如XOR、AlphaBlending、Colorize等操作
u32GlobalSrcConstColor	针对eDFBBlendFlag 操作对应的const参数，eDFBBlendFlag 操作有对应的mutli等等
u32GlobalDstConstColor	针对eDFBBlendFlag 操作对应的const参数，eDFBBlendFlag 操作有对应的mutli等等

注意事项

目前仅有u32GlobalSrcConstColor有效。

3.13. MI_GFX_PaletteEntry_t¶

说明

索引颜色格式对应的RGB颜色定义

定义

typedef union

{

    /// ARGB8888 byte order

    struct

        {

            MI_U8 u8A;

            MI_U8 u8R;

            MI_U8 u8G;

            MI_U8 u8B;

        } RGB;

        // u8Data[0] = u8A

        // u8Data[1] = u8R

        // u8Data[2] = u8G

        // u8Data[3] = u8B

        MI_U8 u8Data[4];

} MI_GFX_PaletteEntry_t;

成员

成员描述

RGB 索引颜色对应的RGB颜色的分量结构体表示

u8Data 索引颜色对应的RGB颜色的字节序表示
注意事项

注意定义中注释对颜色定义的描述，以便正确填写调色板数据。

3.14. MI_GFX_Palette_t¶

说明

调色板定义结构体

定义

typedef struct MI_GFX_Palette_s

{

    MI_GFX_PaletteEntry_t aunPalette[256];

    MI_U16 u16PalStart;

    MI_U16 u16PalEnd;

}MI_GFX_Palette_t;

成员

成员描述

aunPalette 调色板索引对应的RGB颜色数组

u16PalStart 需要配置RGB颜色的索引集起始索引

u16PalEnd 需要配置RGB颜色的索引集结束索引
相关数据类型及结果

MI_GFX_PaletteEntry_t

3.15. MI_GFX_DevAttr_t¶

说明

GFX设备初始化参数

定义

typedef struct MI_GFX_DevAttr_s
{
    MI_U32 u32DevId;
    MI_U8 *u8Data;
} MI_GFX_DevAttr_t;

成员

成员名称描述

u32DevId 设备ID

u8Data 数据指针buffer
相关数据类型及接口

MI_GFX_CreateDev

3.16. MI_GFX_DEV¶

说明

GFX设备号
定义
```
typedef MI_S32 MI_GFX_DEV;
```
相关数据类型及接口

所有的接口。

4. 错误码¶

GFX API 错误码如下所示

错误代码	宏定义	描述
0xA00D2003	MI_ERR_GFX_INVALID_PARAM	非法参数
0xA00D2002	MI_ERR_GFX_DEV_BUSY	GFX设备忙
0xA00D2220	MI_ERR_GFX_NOT_INIT	设备未初始化
0xA00D2221	MI_ERR_GFX_DRV_NOT_SUPPORT	不支持的操作类型
0xA00D2222	MI_ERR_GFX_DRV_FAIL_FORMAT	不支持的格式类型
0xA00D2223	MI_ERR_GFX_NON_ALIGN_ADDRESS	地址未对齐
0xA00D2224	MI_ERR_GFX_NON_ALIGN_PITCH	Pitch对齐错误
0xA00D2225	MI_ERR_GFX_DRV_FAIL_OVERLAP	Option内存有叠加区域
0xA00D2226	MI_ERR_GFX_DRV_FAIL_STRETCH	缩放失败
0xA00D2228	MI_ERR_GFX_DRV_FAIL_LOCKED	设备被其他使用者锁住
0xA00D2229	MI_ERR_GFX_DRV_FAIL_BLTADDR	Bitblit起始地址错误

5. PROCFS介绍¶

5.1. cat¶

调试信息
```
# cat /proc/mi_modules/mi_gfx/mi_gfx0
```
调试信息分析

记录当前GFX的使用状况以及device属性可以动态地获取到这些信息，方便调试和测试。

参数说明

参数		描述
device info	module init count	设备被 Open 的次数，由于 GFX 会有多个模块进行调用，并且不能确定是哪一个 module 会先调用 GFX 的初始化，所以设备允许多次 Open，会记录 Open 次数来在 Close 的时候做对应的计数判断是否需要真的 Close Device。
	Device id	GFX的设备ID
	ARGB1555 alpha threshold	ARGB8888 转 ARGB1555 时，GFX 内部的 alpha 判定阈值，如大于 N 则 alpha 为 1，反之 alpha 为 0。
	ARGB1555 To ARGB8888 alpha value	ARGB1555 转 ARGB8888 时，GFX 将 ARGB1555 alpha bit 为 1的像素的 alpha 转为 ARGB1555 To ARGB8888 alpha value。
	Scaling coefficient	图像几何中心偏移

成员	描述
u32ColorStart	ColorKey颜色范围起始值
u32ColorEnd	ColorKey颜色范围结束值

成员	描述
bEnColorKey	是否使能ColorKey操作
eCKeyOp	ColorKey操作模式
stCKeyVal	ColorKey颜色范围
eCKeyFmt	ColorKey的颜色格式

成员	描述
u32PhyAddr	位图首地址
eColorFmt	位图格式
u32Height	位图高度
u32Width	位图宽度
u32Stride	位图跨度

成员	描述
RGB	索引颜色对应的RGB颜色的分量结构体表示
u8Data	索引颜色对应的RGB颜色的字节序表示

成员	描述
aunPalette	调色板索引对应的RGB颜色数组
u16PalStart	需要配置RGB颜色的索引集起始索引
u16PalEnd	需要配置RGB颜色的索引集结束索引

成员名称	描述
u32DevId	设备ID
u8Data	数据指针buffer