MI RGN API

1. 概 述¶

1.1. 模块说明¶

区域管理模块参与VPE、DIVP、LDC模块的内部流处理的一个环节。底层硬件模块支持是GOP（Graphic output path），区域管理模块利用GOP的特性抽象出来的一套软件接口，利用分时复用的原理使OSD(On-screen display)或者Cover贴到各个通道上。

区域管理模块提供区域资源的控制管理功能，包括区域的创建、销毁、获取与设置区域属性、获取与设置区域的通道属性等。

区域属性分为两种，一种是cover，Cover只是按照设定，给一块区域做遮挡，底层驱动只要知道显示的位置大小和颜色即可，因此创建Cover时，不会给cover分配内存做显示。

另外一种区域属性称为osd,有些地方亦称为overlay，它同样可以贴在video显示的区域，这块区域用内存来描述显示的内容，所以这块内容可以做点对点画图操作，显示内存支持argb、位图两种格式，使用者可以根据实际的场景来选择所需要的格式。

目前OSD可以支持的格式有ARGB1555、ARGB4444、ARGB8888、RGB565、I2、I4、I8，每个芯片支持的情况会有差异，下文会详细说明。暂不支持YUV格式。I2、I4、I8格式为位图格式，一个pixel的内存数据当作一个索引，通过索引能找到调色盘中的颜色数据，当前pixel显示的就是此颜色。

无论是Cover还是Osd其显示的内容均是叠加到VPE/DIVP/LDC模块的输出上，通过实验，当设定了region显示之后，把VPE/DIVP/LDC模块的输出dump成文件,通过工具就可以看到region的内容.

OSD可以显示一张图片，COVER仅仅可以设定颜色，在同一通道上OSD的内容永远在COVER之上，下图在同一个通道上显示了四个cover区域以及三张osd。

图1-1

1.2. 流程框图¶

图1-2

1.3. 关键字说明¶

• I2

  4色位图格式，用2个bit表示一个索引，因而有4种颜色，在调色盘中通过索引找到对应的颜色。

• I4

  16色位图格式，与I2格式类似，不同的是用4个bit表示一个索引，因而有16种颜色。

• I8

  256色位图格式，不同的是用8个bit表示一个索引，因而有256种颜色。

• Palette

  位图的调色盘，由Alpha、Red、Green、Blue四个8bit变量表示一个pixel的颜色，一共有256个颜色，对应0-255的索引序号。

• OSD

  On-screen display的简称，用来显示一些文字、图片、以及人机交互的菜单等内容。

• GOP

  Graphic output path的简称，可以理解为在video层之上的一个图形层。

2. API 参考¶

2.1. 功能模块API¶

2.2. MI_RGN_Init¶

• 功能

  初始化。

• 语法

  MI_S32 MI_RGN_Init(MI_RGN_PaletteTable_t *pstPaletteTable);
  

• 形参

  参数名称	参数含义	输入/输出
  pstPaletteTable	调色板指针。	输入

• 返回值

  • MI_RGN_OK 成功。

  • MI_ERR_RGN_BUSY 已初始化。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件

• 注意

  • I2/I4/I8的图像格式是共用一份palette table，palette table只能在初始化时做一次，不可再次设置。

  • RGB格式不会参考palette。

  • Palette的第0号成员为透明色，上层无法指定。

  • MI_RGN_Init需要在其他使用到RGN的模块Init之前进行（如VPE/DIVP）。

• 举例

  MI_S32 s32Result = 0;
  MI_RGN_PaletteTable_t stPaletteTable；
  memset(&stPaletteTable, 0, sizeof(MI_RGN_PaletteTable_t));
  stPaletteTable.astElement[1].u8Alpha = 255;
  stPaletteTable.astElement[1].u8Red = 255;
  stPaletteTable.astElement[1].u8Green = 0;
  stPaletteTable.astElement[1].u8Blue = 0;
  stPaletteTable.astElement[2].u8Alpha = 255;
  stPaletteTable.astElement[2].u8Red = 0;
  stPaletteTable.astElement[2].u8Green = 255;
  stPaletteTable.astElement[2].u8Blue = 0;
  stPaletteTable.astElement[3].u8Alpha = 255;
  stPaletteTable.astElement[3].u8Red = 0;
  stPaletteTable.astElement[3].u8Green = 0;
  stPaletteTable.astElement[3].u8Blue = 255;
  s32Result = MI_RGN_Init(&stPaletteTable);
  s32Result = MI_RGN_DeInit();
  

• 相关主题

  MI_RGN_DeInit

2.3. MI_RGN_DeInit¶

• 功能

  反初始化。

• 语法s

  MI_S32 MI_RGN_DeInit();
  

• 返回值

  • MI_RGN_OK 成功。

  • MI_ERR_RGN_BUSY 未初始化。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件

• 注意

  MI_RGN_DeInit需要在其他使用到RGN的模块Deinit之后进行（如VPE/DIVP）。

• 举例

  参见MI_RGN_Init 举例。

• 相关主题

  MI_RGN_Init

2.4. MI_RGN_Create¶

• 功能

  创建区域。

• 语法

  MI_S32 MI_RGN_Create(MI_RGN_HANDLE hHandle,
  MI_RGN_Attr_t *pstRegion);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 必须是未使用的hHandle号 取值范围：[0, MI_RGN_MAX_HANDLE]。	输入
  pstRegion	区域属性指针。	输入

• 返回值

  • MI_RGN_OK成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件

• 注意

  • 该句柄由用户指定，意义等同于 ID 号。

  • 不支持重复创建。

  • 区域属性必须合法，具体约束参见MI_RGN_Attr_t。

  • MI_RGN_Attr_t中指定Cover还是OSD

  • 区域属性指针不能为空。

  • 创建 Cover时，只需指定区域类型即可。其它的属性，如区域位置，层次等信息在调用 MI_RGN_AttachToChn 接口时指定。

  • 创建区域时，本接口只进行基本的参数的检查，例如：最小宽高，最大宽高等；当区域 attach 到通道上时，根据各通道模块支持类型的约束条件进行更加有针对性的参数检查，譬如支持的像素格式等；

• 举例

  MI_S32 s32Result = 0;
  MI_RGN_HANDLE hHandle = 0;
  MI_RGN_Attr_t stRegion;
  stRegion.eType = E_MI_RGN_TYPE_OSD;
  stRegion.stOsdInitParam.ePixelFmt = E_MI_RGN_PIXEL_FORMAT_RGB1555;
  stRegion.stOsdInitParam.stSize.u32Width = 40;
  stRegion.stOsdInitParam.stSize.u32Height = 40;
  
  s32Result = MI_RGN_Create(hHandle, &stRegion);
  if (s32Result != MI_RGN_OK)
  {
                      return s32Result;
  }
  
  s32Result = MI_RGN_GetAttr(hHandle, &stRegion);
  if (s32Result != MI_RGN_OK)
  {
                      return s32Result;
  }
  
  s32Result = MI_RGN_Destroy(hHandle);
  if (s32Result != MI_RGN_OK)
  {
                      return s32Result;
  }
  

• 相关主题

  MI_RGN_Destroy

  MI_RGN_GetAttr

2.5. MI_RGN_Destroy¶

• 功能

  销毁区域。

• 语法

  MI_S32 MI_REG_Destroy (MI_RGN_HANDLE hHandle);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE)。	输入

• 返回值

  • MI_RGN_OK成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

• 举例

  参见 MI_RGN_Create 举例。

• 相关主题

  MI_RGN_Create

2.6. MI_RGN_GetAttr¶

• 功能

  获取区域属性。

• 语法

  MI_S32 MI_RGN_GetAttr(MI_RGN_HANDLE hHandle,
  MI_RGN_Attr_t *pstRegion);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, )。	输入
  pstRegion	区域属性指针。	输出

• 返回值

  • MI_RGN_OK成功。

  • 非 MI_RGN_OK失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 区域属性指针不能为空。

• 举例

  参见 MI_RGN_Create举例。

2.7. MI_RGN_SetBitMap¶

• 功能

  设置区域位图，即对区域进行位图填充。

• 语法

  MI_S32 MI_RGN_SetBitMap(MI_RGN_HANDLE hHandle,
  
  MI_RGN_Bitmap_t *pstBitmap);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE )。	输入
  pstBitmap	位图属性指针。	输入

• 返回值

  • MI_RGN_OK 成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 支持位图的大小和区域的大小可以不一致。

  • 位图从区域的(0,0)点开始加载。当位图比区域大时，将会自动将图像剪裁成区域大小。

  • 位图的像素格式必须和区域的像素格式一致。

  • 位图属性指针不能为空。

  • 支持多次调用。

  • 此接口只对 Overlay有效。

  • 调用了MI_RGN_GetCanvasInfo之后调用本接口无效，除非MI_RGN_UpdateCanvas 更新画布生效后。

• 举例

  MI_S32 s32Result = 0;
  MI_HANDLE hHandle = 0;
  MI_RGN_Bitmap_t stBitmap;
  MI_U32 u32FileSize = 200 * 200 * 2;
  MI_U8 *pu8FileBuffer = NULL;
  FILE *pFile = fopen("200X200.argb1555", "rb");
  if (pFile == NULL)
  {
  printf("open file failed \n");
  return -1;
  }
  pu8FileBuffer = (MI_U8*)malloc(u32FileSize);
  if (pu8FileBuffer == NULL)
  {
  printf("malloc failed fileSize=%d\n", u32FileSize);
  fclose(pFile);
  return -1;
  }
  memset(pu8FileBuffer, 0, u32FileSize);
  fread(pu8FileBuffer, 1,  u32FileSize, pFile);
  fclose(pFile);
  stBitmap.stSize.u32Width = 200;
  stBitmap.stSize.u32Height = 200;
  stBitmap.ePixelFormat = E_MI_RGN_PIXEL_FORMAT_RGB1555;
  stBitmap.pData = pu8FileBuffer;
  free(pu8FileBuffer);
  s32Result = MI_RGN_SetBitMap(hHandle, &stBitmap);
  

2.8. MI_RGN_AttachToChn¶

• 功能

  将区域叠加到通道上。

• 语法

  MI_S32 MI_RGN_AttachToChn(MI_RGN_HANDLE hHandle, 
  MI_RGN_ChnPort_t* pstChnPort, 
  MI_RGN_ChnPortParam_t *pstChnAttr)
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0,MI_RGN_MAX_HANDLE)。	输入
  pstChnPort	通道端口结构体指针。	输入
  pstChnAttr	区域通道显示属性指针。	输入

• 返回值

  • MI_RGN_OK 成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 通道结构体指针不能为空。

  • 区域通道显示属性指针不能为空。

  • 多个osd区域类叠加到同一个通道上，每个osd必须是同一个图像格式。

  • 并不是所有的通道上都有叠加region的能力，下表列出芯片差异。

  • COVER只有硬件layer. OSD支持软件layer，底层会用软件拼图实现。

  • OSD、COVER叠加到通道上对channel id不会有要求。

  • 叠加到通道上的OSD小于或等于硬件layer个数，则全部使用硬件layer，反之则会用软件拼图。

注：此系列芯片内部可用的GOP硬件个数为3个，可输出的OSD模块有VPE PORT0/PORT1/PORT2、DIVP，一共有4个，根据用户使用场景，可以同时在其中任意选择三个端口的组合作为当前可用的OSD输出。

注：此系列芯片内部可用的GOP硬件个数为3个，可输出的OSD模块有VPE PORT0/PORT1/PORT2、LDC、DIVP，一共有5个。 DIVP和LDC不可以同时贴OSD，除此之外可以同时在其中任意选择三个端口的组合作为当前可用的OSD输出。

注：此系列芯片内部可用的GOP硬件个数为6个，可输出的OSD模块有VPE PORT0/PORT1/PORT2/PORT5/PORT6、LDC、DIVP，一共有7个。 DIVP和LDC不可以同时贴OSD，因此最多同时可以有6个输出端口同时显示OSD。

• 举例

  MI_S32 s32Result = 0;
  MI_RGN_HANDLE hHandle = 0;
  MI_RGN_ChnPort_t stChnPort;
  MI_RGN_ChnPortParam_t stChnAttr;
  
  memset(stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
  memset(stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
  stChnPort.eModId = E_MI_RGN_MODID_VPE;
  stChnPort.s32DevId = 0;
  stChnPort.s32ChnId = 0;
  stChnPort.s32OutputPortId = 0;
  stChnAttr.bShow = TRUE;
  stChnAttr.stPoint.u32X = 0;
  stChnAttr.stPoint.u32Y = 0;
  stChnAttr.unPara. stCoverChnPort.u32Layer = 0;
  stChnAttr.unPara. stCoverChnPort.stSize.u32Width = 200;
  stChnAttr.unPara. stCoverChnPort.stSize.u32Height = 200;
  stChnAttr.unPara. stCoverChnPort.u32Color = 0;
  
  s32Result = MI_RGN_AttachToChn(hHandle, &stChnPort, &stChnAttr);
  if (s32Result != MI_RGN_OK)
  {
                  return s32Result;
  }
  
  s32Result = MI_RGN_DetachFromChn(hHandle, &stChnPort);
  if (s32Result != MI_RGN_OK)
  {
                  return s32Result;
  }
  

• 相关主题

  MI_RGN_DetachFromChn

2.9. MI_RGN_DetachFromChn¶

• 功能

  将区域从通道中撤出。

• 语法

  MI_S32 MI_RGN_DetachFromChn(MI_RGN_HANDLE hHandle,
  
  MI_RGN_ChnPort_t *pstChnPort);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE )。	输入
  pstChnPort	通道端口结构体指针。	输入

• 返回值

  • MI_RGN_OK成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 通道结构体指针不能为空。

  • 支持多次调用。

  • 被叠加区域的通道或组（如 VENC，VPE 等）销毁前，需要调用本接口将区域

  • 通道或组中撤出。

• 举例

  参见 MI_RGN_AttachToChn举例。

• 相关主题

  MI_RGN_AttachToChn

2.10. MI_RGN_SetDisplayAttr¶

• 功能

  设置区域的通道显示属性。

• 语法

  MI_S32 MI_RGN_SetDisplayAttr(MI_RGN_HANDLE hHandle,
  
  MI_RGN_ChnPort_t *pstChnPort,
  
  MI_RGN_ChnPortParam_t *pstChnPortAttr);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE )。	输入
  pstChnPort	通道端口结构体指针。	输入
  pstChnPortAttr	区域通道端口显示属性指针。	输入

• 返回值

  • MI_RGN_OK成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 建议先获取属性，再设置。

  • 通道结构体指针不能为空。

  • 区域通道显示属性指针不能为空。

  • 区域必须先叠加到通道上。

• 举例

  MI_S32 s32Result = 0;
  MI_RGN_HANDLE hHandle = 0;
  MI_RGN_ChnPort_t stChnPort;
  MI_RGN_ChnPortParam_t stChnAttr;
  
  stChnPort.eModId = E_MI_RGN_MODID_VPE;
  stChnPort.s32DevId = 0;
  stChnPort.s32ChnId = 0;
  stChnPort.s32OutputPortId = 0;
  s32Result = MI_RGN_GetDisplayAttr(hHandle, &stChnPort, &stChnAttr);
  if (s32Result != MI_RGN_OK)
  {
      return s32Result;
  }
  
  stChnAttr.bShow = TRUE;
  stChnAttr.stPoint.u32X = 0;
  stChnAttr.stPoint.u32Y = 0;
  stChnAttr.stCoverPara.u32Layer = 0;
  stChnAttr.stCoverPara.stSize.u32Width = 200;
  stChnAttr.stCoverPara.stSize.u32Height = 200;
  stChnAttr.stCoverPara.u32Color = 0;
  
  s32Result = MI_RGN_SetDisplayAttr(hHandle, &stChnPort, &stChnAttr);
  if (s32Result != MI_RGN_OK)
  {
  return s32Result;
  }
  

• 相关主题

  MI_RGN_GetDisplayAttr

2.11. MI_RGN_GetDisplayAttr¶

• 功能

  获取区域的通道显示属性。

• 语法

  MI_S32 MI_RGN_GetDisplayAttr(MI_RGN_HANDLE hHandle,
  
  MI_RGN_ChnPort_t *pstChnPort,
  
  MI_RGN_ChnPortParam_t *pstChnPortAttr);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE )。	输入
  pstChnPort	通道端口结构体指针。	输入
  pstChnPortAttr	区域通道端口显示属性指针。	输出

• 返回值

  • MI_RGN_OK成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 通道结构体指针不能为空。

  • 区域通道显示属性指针不能为空。

• 举例

  请参见MI_RGN_SetDisplayAttr 的举例。

• 相关主题

  MI_RGN_SetDisplayAttr

2.12. MI_RGN_GetCanvasInfo¶

• 功能

  获取区域的显示画布信息。

• 语法

  MI_S32 MI_RGN_GetCanvasInfo(MI_RGN_HANDLE hHandle, 
  MI_RGN_CanvasInfo_t* pstCanvasInfo);
  

• 形参

  参数名称	参数含义	输入/输出
  hHandle	区域句柄号。 取值范围：[0, MI_RGN_MAX_HANDLE)。	输入
  pstCanvasInfo	区域显示画布信息。	输出

• 返回值

  • MI_RGN_OK成功。

  • 非 MI_RGN_OK失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 本接口与MI_RGN_SetBitMap功能类似，主要用于 overlay类型

  • 导入位图数据。本接口相对于MI_RGN_SetBitMap 接口，用户可以直接更新

  • 显示内部画布数据，节省一次内存拷贝和一张画布内存。

  • 本接口用于获取区域对应的画布信息，在得到画布地址之后，用户可直接对画布进行操作，譬如：将 bmp 数据直接填写到该画布中。然后通过调用MI_RGN_UpdateCanvas 接口，更新显示画布数据。

  • 本接口与MI_RGN_SetBitMap 接口互斥。如果已经使用了本接口，那么在调用 MI_RGN_UpdateCanvas 前，调用 MI_RGN_SetBitMap不生效。

• 举例

  MI_RGN_HANDLE hHandle;
  MI_RGN_Attr_t stRegion;
  MI_RGN_PaletteTable_t stPaletteTable；
  MI_RGN_CanvasInfo_t stCanvasInfo;
  
  memset(&stPaletteTable, 0, sizeof(MI_RGN_PaletteTable_t));
  stPaletteTable.astElement[0].u8Alpha = 0;
  stPaletteTable.astElement[0].u8Red = 255;
  stPaletteTable.astElement[0].u8Green = 255;
  stPaletteTable.astElement[0].u8Blue = 255;
  if (MI_RGN_OK != MI_RGN_Init(&stPaletteTable))
  {
      printf("Init error!\n");
  
      return -1;
  }
  hHandle = 10;
  stRegion.eType = E_MI_RGN_TYPE_OSD;
  stRegion.stOsdInitParam.ePixelFmt = E_MI_RGN_PIXEL_FORMAT_ARGB1555;
  stRegion.stOsdInitParam.stSize.u32Width = 100;
  stRegion.stOsdInitParam.stSize.u32Height = 100;
  if (MI_RGN_OK != MI_RGN_Init(hHandle, &stRegion))
  {
      printf("Create handle error!\n");
  
      return -1;
  }
  if (MI_RGN_OK != MI_RGN_Create(hHandle, &stRegion))
  {
      printf("Create handle error!\n");
  
      return -1;
  }
  FILE *pFile = fopen("100X100.argb1555", "rb");
  if (pFile == NULL)
  {
      printf("open file failed \n");
      MI_RGN_Destroy(hHandle);
  
      return -1;
  }
  if (MI_RGN_GetCanvas(hHandle, &stCanvasInfo) != MI_RGN_OK)
  {
      return s32Result;
  }
  
  for (int i = 0; i < 100; i++)
  {
      fread((MI_U8*)stCanvasInfo.virtAddr + i * stCanvasInfo.u32Stride, 1, 100 * 2, pFile);
  }
  fclose(pFile);
  if (MI_RGN_UpdateCanvas(hHandle) != MI_RGN_OK)
  {
      return s32Result;
  }
  

• 相关主题

  MI_RGN_UpdateCanvas

2.13. MI_RGN_UpdateCanvas¶

• 功能

  更新显示画布，若画布有叠加到通道上则更新显示画布，若没有叠加到通道，则在执行叠加操作后才会在通道上显示出画布的内容。

• 语法

  MI_S32 MI_RGN_UpdateCanvas(MI_RGN_HANDLE hHandle);
  

• 形参

  | **参数名称** | **参数含义**                   | **输入/输出** |
  |--------------|--------------------------------|---------------|
  | hHandle      | 区域句柄号。 取值范围：[0, [MI_RGN_MAX_HANDLE](#32-mi_rgn_max_handle))。 | 输入          |
  

• 返回值

  • MI_RGN_OK成功。

  • 非 MI_RGN_OK失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 本接口配合MI_RGN_GetCanvasInfo 使用。主要用于画布内存数据更新之后，进行画布切换显示。

  • 本接口必须与MI_RGN_GetCanvasInfo成对调用，同一个handler先执行MI_RGN_GetCanvasInfo获取画布的内存指针，待绘图操作完成后执行本接口，若没有先执行MI_RGN_GetCanvasInfo，则会返回MI_ERR_RGN_NOT_PERM。

  • 当多个handler叠加到同一个通道上显示，并且都会使用MI_RGN_GetCanvasInfo及本接口进行绘图操作，在这个通道上的所有绘图操作可以在同一个线程上执行，若在不同线程上，必须使用锁保护起来，否则有可能会出现OSD闪烁，或者osd不刷新的问题。

  • 以上多线程的情况下锁的使用详细说明如下：

    rgn的handle假设有handler0和handler1都贴到同一个通道上

    分别两个线程

    handler0 

    T0_0 = getcanvas

    T0_1 = update

    handler1

    T1_0 = getcanvas

    T1_1 = update

    按照时间T的顺序执行

    有问题的情况：

    T0_0 -> T1_0 -> T0_1 -> T1_1，并伴随底层error的打印：“Front buf state error!!!”。

    加mutex后，能够正常。调整后的时序：

    lock-> T0_0 -> T0_1 -> unlock -> lock -> T1_0 -> T1_1 -> unlock

• 举例

  请参见MI_RGN_GetCanvasInfo的举例。

• 相关主题

  MI_RGN_GetCanvasInfo

2.14. MI_RGN_ScaleRect¶

• 功能

  OSD区域放大。

• 语法

  MI_S32 MI_RGN_ScaleRect(MI_RGN_ChnPort_t *pstChnPort, MI_RGN_Size_t *pstCanvasSize, MI_RGN_Size_t *pstScreenSize);
  

• 型参

  参数名称	参数含义	输入/输出
  pstChnPort	通道端口结构体指针。	输入
  pstCanvasSize	放大前OSD所在图层宽高的结构体指针。 要求宽按16byte对齐，如I4格式，需按32pixel对齐。	输入
  pstScreenSize	放大后OSD所在屏幕宽高的结构体指针。	输入

• 返回值

  • MI_RGN_OK成功。

  • 非 MI_RGN_OK失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件：

• 注意

  • 区域必须已创建。

  • 放大后的屏幕宽高不能超过视频帧的宽高，视频帧的最大宽高不超过3840x2160。

  • 放大前的图层宽高不能超过放大后的屏幕宽高。

  • 放大前的宽需按16byte对齐。硬件上要求放大前宽按2pixel对齐，但当OSD区域出现在显示区域边缘时，放大处理后可能会与屏幕边缘存在间隔，所以要求放大前的宽也按Gwin对齐要求对齐。

  • 做OSD放大时，OSD反色功能失效。

  • OSD区域放大功能目前只有Pretzel能够支持，其他的芯片暂不支持。

• 举例

  MI_S32 s32Result = 0;
  MI_RGN_ChnPort_t stChnPort;
  MI_RGN_Size_t stCanvasSize;
  MI_RGN_Size_t stScreenSize;
  
  memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
  memset(&stCanvasSize, 0, sizeof(MI_RGN_Size_t));
  memset(&stScreenSize, 0, sizeof(MI_RGN_Size_t));
  
  stChnPort.eModId = E_MI_RGN_MODID_VPE; 
  stChnPort.s32DevId = 0; 
  stChnPort.s32ChnId = 0; 
  stChnPort.s32OutputPortId = 0; 
  stCanvasSize.u32Width = 1280; 
  stCanvasSize.u32Height = 720;
  stScreenSize.u32Width = 1920; 
  stScreenSize.u32Height = 1080;
  
  s32Result = MI_RGN_ScaleRect(&stChnPort, &stCanvasSize, &stScreenSize);
  if (s32Result != MI_RGN_OK)
  {
  return s32Result;
  }
  

2.15. MI_RGN_InitDev¶

• 功能

  初始化RGN设备。

• 语法

  MI_S32 MI_RGN_InitDev(MI_RGN_InitParam_t *pstInitParam);
  

• 形参

  参数名称	参数含义	输入/输出
  pstInitParam	设备初始化参数	输入

• 返回值

  • MI_RGN_OK 成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件

• 注意

  • 此接口在Version 2.08以上版本推荐使用，用于替换原有MI_RGN_Init接口。

2.16. MI_RGN_DeInitDev¶

• 功能

  反初始化RGN设备。

• 语法

  MI_S32 MI_RGN_DeInitDev();
  

• 返回值

  • MI_RGN_OK 成功。

  • 非MI_RGN_OK 失败，参照返回值。

• 依赖

  • 头文件：mi_sys.h、mi_rgn.h。

  • 库文件

• 注意

  • 此接口在Version 2.08以上版本推荐使用，用于替换原有MI_RGN_DeInit接口。

3. RGN 数据类型¶

3.1. 数据类型定义¶

视频前处理相关数据类型、数据结构定义如下：

3.2. MI_RGN_MAX_HANDLE¶

• 说明

  定义区域的最大句柄。

• 定义

  #define MI_RGN_MAX_HANDLE 1024
  

3.3. MI_RGN_MAX_PALETTE_TABLE_NUM¶

• 说明

  颜色表最大元素个数。

• 定义

  #define MI_RGN_MAX_PALETTE_TABLE_NUM 256
  

3.4. MI_RGN_HANDLE¶

• 说明

  定义区域句柄。

• 定义

  typedef MI_U32 MI_RGN_HANDLE;
  

• 成员

  成员名称	描述
  MI_RGN_HANDLE	区域句柄。

3.5. MI_RGN_Type_e¶

• 说明

  定义区域类型。

• 定义

  typedef enum
  
  {
  
      E_MI_RGN_TYPE_OSD = 0,
  
      E_MI_RGN_TYPE_COVER,
  
      E_MI_RGN_TYPE_MAX
  
  } MI_RGN_Type_e;
  

• 成员

  成员名称	描述
  E_MI_ REG_OSD	视频叠加区域。
  E_MI_REG_COVER	视频遮挡区域。

3.6. MI_RGN_PixelFormat_e¶

• 说明

  定义叠加区域属性结构体。

• 定义

  typedef enum
  
  {
  
      E_MI_RGN_PIXEL_FORMAT_ARGB1555 = 0,
  
      E_MI_RGN_PIXEL_FORMAT_ARGB4444,
  
      E_MI_RGN_PIXEL_FORMAT_I2,
  
      E_MI_RGN_PIXEL_FORMAT_I4,
  
      E_MI_RGN_PIXEL_FORMAT_I8,
  
      E_MI_RGN_PIXEL_FORMAT_RGB565,
  
      E_MI_RGN_PIXEL_FORMAT_ARGB8888,
  
      E_MI_RGN_PIXEL_FORMAT_MAX
  
  } MI_RGN_PixelFormat_e;
  

• 成员

  成员名称	描述
  E_MI_RGN_PIXEL_FORMAT_ARGB1555	ARGB1555格式
  E_MI_RGN_PIXEL_FORMAT_ARGB4444	ARGB4444格式
  E_MI_RGN_PIXEL_FORMAT_RGBI2	I2格式（两个bit表示，支援4种颜色，调色板查色）
  E_MI_RGN_PIXEL_FORMAT_RGBI4	I4格式（4个bit表示，支援16种颜色，调色板查色）
  E_MI_RGN_PIXEL_FORMAT_I8	I4格式（8个bit表示，支援256种颜色，调色板查色）
  E_MI_RGN_PIXEL_FORMAT_RGB565	RGB565
  E_MI_RGN_PIXEL_FORMAT_ARGB8888	ARGB8888格式

• 注意事项

  每个chip支持的图像格式不一样，API种极大化地罗列出了所有的图像格式，但是有些格式存在API不支援的情况，如果使用者需要chip支援的情况，请查看region procfs。

  使用命令： echo getcap > /proc/mi_modules/mi_rgn/mi_rgn0。

  使用者无法设定index 0的调色盘，I2/I4/I8这些格式的index 0被底层driver用作color key，表示这种颜色不被硬件识别，所以当全0的数据叠加到通道上时，是不显示任何颜色的。

  Color key的数值可以在procfs的getcap中查看，colorkey的数值是一个16bit整型，它的高8位和低8位是一样的值，当使用Index类型的colorformat时，对内存数据进行memset 0即可让硬件不识别，当使用RGB或者ARGB格式时无论使用的是何种排列，对内存数据进行memeset (colorkey & 0xFF)数值即可。

3.7. MI_RGN_InvertColorMode_e¶

• 说明

  定义反色区域的反色模式。

• 定义

  typedef enum
  
  {
  
      E_MI_RGN_ABOVE_LUMA_THRESHOLD = 0,
  
      E_MI_RGN_BELOW_LUMA_THRESHOLD,
  
      E_MI_RGN_LUMA_THRESHOLD_BUTT
  
  } MI_RGN_InvertColorMode_e;
  

• 成员

  成员名称	描述
  E_MI_RGN_ABOVE_LUMA_THRESHOLD	大于阈值做反色。
  E_MI_RGN_BELOW_LUMA_THRESHOLD	小于阈值做反色。

3.8. MI_RGN_AlphaMode_e¶

• 说明

  设定Osd Alpha显示模式。

• 定义

  typedef enum
  
  {
  
      E_MI_RGN_PIXEL_ALPHA = 0,
  
      E_MI_RGN_CONSTANT_ALPHA
  
  }MI_RGN_AlphaMode_e;
  

• 成员

  成员名称	描述
  E_MI_RGN_PIXEL_ALPHA	Osd显示每个pixel对应的alpha效果，例如argb1555/argb4444/arbg8888/i2/i4/i8这些格式都能支持pixel alpha，rgb565则不会生效。
  E_MI_RGN_CONSTANT_ALPHA	Osd硬件会忽略图像格式中的alpha位，使用统一的值设定alpha值。例如rgb565能设定其透明度 。

3.9. MI_RGN_Size_t¶

• 说明

  定义大小信息结构体。

• 定义

  typedef struct MI_RGN_Size_s
  
  {
  
      MI_U32 u32Width;
  
      MI_U32 u32Height;
  
  } MI_RGN_Size_t;
  

• 成员

  成员名称	描述
  u32Width	宽度
  u32Height	高度

3.10. MI_RGN_OsdInvertColorAttr_t¶

• 说明

  定义反色区域属性结构体。

• 定义

  typedef struct MI_RGN_OsdInvertColorAttr_s
  
  {
  
      MI_BOOL bEnableColorInv;
  
      MI_RGN_InvertColorMode_e eInvertColorMode;
  
      MI_U16 u16LumaThreshold;
  
      MI_U16 u16WDivNum;
  
      MI_U16 u16HDivNum;
  
  } MI_RGN_OsdInvertColorAttr_t;
  

• 成员

  成员名称	描述
  bEnableColorInv	反色使能。
  eInvertColorMode	反色模式。
  u16LumaThreshold	发色阈值。取值范围为0~255
  u16WDivNum	反色区域横向切割数。反色区域宽要求能被横向分割数整除。
  u16HDivNum	反色区域纵向切割数。反色区域高要求能被纵向分割数整除。

• 注意事项

  反色仅在region可显示，开启反色且设置参数合法的情况下才会起作用。

  反色区域的位置和大小与region相同，建议根据实际需要做反色的区域大小来创建region。

  反色区域可切块的数量为1~2048，每个切割块的最大范围为64pixel*64pixel。u16WdivNum与u16HDivNum的乘积不能超过2048。也不能设置过小，使切割块的范围超出最大限制。同时还需满足宽高能分别被横向切割数和纵向切割数整除，否则反色无效果。

  同一个ChnPort绑定多个region，当多个region开启反色时，各个region的反色模式和阈值须设为一致。若反色模式和阈值设置不一致时，实际反色模式与阈值与最上层显示且开启反色的region的设定相同。

  反色功能目前只有Pretzel能够支持，其他的芯片暂不支持。

3.11. MI_RGN_OsdAlphaAttr_t¶

• 说明

  定义Osd Alpha属性的结构体体。

• 定义

  typedef struct MI_RGN_OsdAlphaAttr_s
  
  {
  
      MI_RGN_AlphaMode_e eAlphaMode;
  
      MI_RGN_AlphaModePara_u stAlphaPara;
  
  }MI_RGN_OsdAlphaAttr_t;
  

• 成员

  成员名称	描述
  eAlphaMode	Osd Alpha的使用模式。
  stAlphaPara	模式对应的参数。

3.12. MI_RGN_OsdInitParam_t¶

• 说明

  定义叠加区域属性结构体。

• 定义

  typedef struct MI_RGN_OsdInitParam_s
  {
      MI_RGN_PixelFormat_e ePixelFmt;
      MI_RGN_Size_t stSize;
  }MI_RGN_OsdInitParam_t;
  

• 成员

  成员名称	描述
  ePixelFmt	像素格式。
  stSize	区域的宽高。 宽最大不超过3840 高最大不超过2160。

• 注意事项

  ePixelFmt、stSize 只在调用MI_RGN_AttachToChn 后，MI_RGN_DetachFromChn之前为静态变量。

3.13. MI_RGN_PaletteElement_t¶

• 说明

  定义颜色元素

• 定义

  typedef struct MI_RGN_PaletteElement_s
  
  {
  
      MI_U8 u8Alpha;
  
      MI_U8 u8Red;
  
      MI_U8 u8Green;
  
      MI_U8 u8Blue;
  
  }MI_RGN_PaletteElement_t;
  

• 成员

  成员名称	描述
  u8Alpha	透明度
  u8Red	红色
  u8Green	绿色
  u8Blue	蓝色

3.14. MI_RGN_PaletteTable_t¶

• 说明

  定义颜色元素

• 定义

  typedef struct MI_RGN_PaletteTable_s
  
  {
  
      MI_RGN_PaletteElement_t
      astElement[MI_RGN_MAX_PALETTE_TABLE_NUM];
  
  }MI_RGN_PaletteTable_t;
  

• 成员

  成员名称	描述
  astElement	颜色元素

3.15. MI_RGN_Attr_t¶

• 说明

  定义区域属性结构体。

• 定义

  typedef struct MI_RGN_Attr_s
  
  {
  
      MI_RGN_Type_e eType;
  
      MI_RGN_OsdInitParam_t stOsdInitParam;
  
  }MI_RGN_Attr_t;
  

• 成员

  成员名称	描述
  eType	区域类型。
  stOsdInitParam	osd区域属性。

3.16. MI_RGN_Bitmap_t¶

• 说明

  定义位图图像信息结构。

• 定义

  typedef struct MI_RGN_Bitmap_s
  
  {
  
      MI_RGN_PixelFormat_e ePixelFormat;
  
      MI_RGN_Size_t stSize;
  
      void *pData;
  
  } MI_RGN_Bitmap_t;
  

• 成员

  成员名称	描述
  ePixelFormat	位图像素格式
  stSize	位图宽度，高度，stride
  pData	位图数据

3.17. MI_RGN_ModId_e¶

• 说明

  定义模块ID枚举类型。

• 定义

  typedef enum
  
  {
  
      E_MI_RGN_MODID_VPE = 0,
  
      E_MI_RGN_MODID_DIVP,
  
      E_MI_RGN_MODID_LDC,
  
      E_MI_RGN_MODID_MAX
  
  }MI_RGN_ModId_e;
  

• 成员

  成员名称	描述
  E_MI_RGN_MODID_VPE	VPE模块ID
  E_MI_RGN_MODID_DIVP	DIVP模块ID
  E_MI_RGN_MODID_LDC	LDC 模块ID

3.18. MI_RGN_ChnPort_t¶

• 说明

  定义模块设备通道结构体。

• 定义

  typedef struct MI_RGN_ChnPort_s
  
  {
  
      MI_RGN_ModId_e eModId;
  
      MI_S32 s32DevId;
  
      MI_S32 s32ChnId;
  
      MI_S32 s32OutputPortId;
  
  }MI_RGN_ChnPort_t;
  

• 成员

  成员名称	描述
  eModId	模块号
  s32DevId	设备号
  s32ChnId	通道号
  s32OutputPortId	输出端口id

3.19. MI_RGN_Point_t¶

• 说明

  定义坐标信息结构体。

• 定义

  typedef struct MI_RGN_Point_s
  
  {
  
      MI_U32 u32X;
  
      MI_U32 u32Y;
  
  }MI_RGN_Point_t;
  

• 成员

  成员名称	描述
  u32X	横坐标
  u32Y	纵坐标

3.20. MI_RGN_CoverChnPortParam_t¶

• 说明

  定义遮挡区域的通道显示属性。

• 定义

  typedef struct MI_RGN_CoverChnPortParam_s
  
  {
  
      MI_U32 u32Layer;
  
      MI_RGN_Size_t stSize;
  
      MI_U32 u32Color;
  
  }MI_RGN_CoverChnPortParam_t;
  

• 成员

  成员名称	描述
  u32Layer	区域层次，数值低的在底层
  stSize	Cover宽，高，stride
  u32Color	颜色，VYU444

3.21. MI_RGN_OsdChnPortParam_t¶

• 说明

  定义OSD区域的通道显示属性。

• 定义

  typedef struct MI_RGN_OsdChnPortParam_s
  
  {
  
      MI_U32 u32Layer;
  
      MI_RGN_OsdAlphaAttr_t stOsdAlphaAttr;
  
      MI_RGN_OsdInvertColorAttr_t stColorInvertAttr;
  
  }MI_RGN_OsdChnPortParam_t;
  

• 成员

3.22. MI_RGN_OsdArgb1555Alpha_t¶

• 说明

  Argb1555格式的前景、背景Alpha设定。

• 定义

  typedef struct MI_RGN_OsdArgb1555Alpha_s
  
  {
  
      MI_U8 u8BgAlpha;
  
      MI_U8 u8FgAlpha;
  
  }MI_RGN_OsdArgb1555Alpha_t;
  

• 成员

  成员名称	描述
  u8BgAlpha	背景Alpha，Alpha bit为0时对应的Alpha值，取值范围0~0xFF。
  u8FgAlpha	前景Alpha， Alpha bit为1时对应的Alpha值，取值范围0~0xFF。

3.23. MI_RGN_ChnPortParamUnion_u¶

• 说明

  定义Region属性的联合体。

• 定义

  typedef union
  {
      MI_RGN_CoverChnPortParam_t stCoverChnPort;
      MI_RGN_OsdChnPortParam_t stOsdChnPort;
  } MI_RGN_ChnPortParamUnion_u;
  

• 成员

  成员名称	描述
  stCoverChnPort	遮挡区域在通道上的属性设置
  stOsdChnPort	Osd区域在通道上的属性设置

3.24. MI_RGN_AlphaModePara_u¶

• 说明

  定义Osd Alpha Mode参数联合体。

• 定义

  typedef union
  {
      MI_RGN_OsdArgb1555Alpha_t stArgb1555Alpha;
      MI_U8 u8ConstantAlpha;
  } MI_RGN_AlphaModePara_u;
  

• 成员

  成员名称	描述
  stArgb1555Alpha	Pixel alpha时Argb1555格式的前景Alpha及背景Alpha设定。
  u8ConstantAlpha	Constant Alpha时Alpha值设定，取值范围0~0xFF。

3.25. MI_RGN_ChnPortParam_t¶

• 说明

  定义区域通道显示属性结构体。

• 定义

  typedef struct MI_RGN_ChnPortParam_s
  {
      MI_BOOL bShow;
      MI_RGN_Point_t stPoint;
      MI_RGN_ChnPortParamUnion_u unPara;
  } MI_RGN_ChnPortParam_t;
  

• 成员

  成员名称	描述
  bShow	区域是否显示。 取值范围：MI_TRUE 或者 MI_FALSE。 动态属性。
  stPoint	区域起始点坐标。 当RGN类型为OSD时，要求X坐标按1byte对齐。
  unPara	Region通道显示属性。

3.26. MI_RGN_CanvasInfo_t¶

• 说明

  定义画布信息结构体。

• 定义

  typedef struct MI_RGN_CanvasInfo_s
  {
      MI_PHY phyAddr;
      MI_VIRT virtAddr;
      MI_RGN_Size_t stSize;
      MI_U32 u32Stride;
      MI_RGN_PixelFormat_e ePixelFmt;
  } MI_RGN_CanvasInfo_t;
  

• 成员

  成员名称	描述
  phyAddr	画布物理地址。
  virtAddr	画布虚拟地址
  stSize	画布尺寸
  u32Stride	画布的 stride
  ePixelFmt	画布的像素格式

4. 返回值¶

区域管理 API 返回值如表所示。

表4-1 区域管理 API返回值