MI RGN API¶

REVISION HISTORY¶

Revision No.	Description	Date
3.0	Initial release	12/04/2020
	新增PROCFS介绍	08/25/2021
	新增Mochi芯片差异部分	02/16/2022
	新增Maruko芯片差异部分	03/21/2022
	新增Souffle芯片差异部分	02/13/2023
	更新PROCFS介绍 & 新增错误码介绍	11/10/2023
	新增Iford芯片差异部分	11/13/2023
	新增Ifado芯片差异部分	03/18/2024
	新增Pcupid芯片差异部分	04/17/2024
3.1	添加区域属性"LINE"的说明	05/30/2024
	新增Ifackel芯片差异部分 & 新增modparam介绍	08/20/2024
	新增Ibopper芯片差异部分	08/26/2024
	添加echo命令用于开关通道上某种类型的RGN	08/28/2024
	新增Jaguar1芯片差异部分	12/27/2024
	优化章节结构	04/24/2025
	新增Ifliegen芯片差异部分	05/14/2025
	新增Ihalo芯片差异部分	08/25/2025
	新增Mhera芯片差异部分	11/07/2025

1. 概述¶

1.1. 模块说明¶

区域管理模块参与Pipeline上某些模块的内部流处理的一个环节。底层硬件模块支持有GOP（Graphic output path）、MFF（Mosaic and Face Frame）。

区域管理模块是利用硬件的特性抽象出来的一套软件接口，利用分时复用的原理使OSD(On-screen display)、COVER等区域贴到各个通道上。

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

区域属性分为四种:

COVER
- COVER有两种模式
  1. 颜色模式，按照设定给一块区域做纯色遮挡，底层驱动只要知道显示的位置、大小和颜色即可，部分芯片只支持该模式；
  2. 马赛克模式，按照设定给一块区域打马赛克，底层驱动只要知道显示的位置、大小和马赛克块大小即可；
- COVER根据区域类型可以分为矩形COVER和多边形COVER（最少3边形，最多6边形，只支持凸多边形），其中矩形COVER不额外消耗内存，有多边形COVER的通道需要COVER bitmap。
OSD，有些地方亦称为overlay，它同样可以贴在video显示的区域，这块区域用内存来描述显示的内容，所以这块内容可以做点对点画图操作，显示内存支持argb（真彩）、位图两种格式，使用者可以根据实际的场景来选择所需要的格式。
FRAME，按照设定在video的指定区域画上矩形框，底层驱动只要知道矩形框的位置大小、颜色以及线宽即可，不额外消耗内存。
LINE，通过两对坐标确定一条线段，线的宽度可以指定，支持实心和空心两种线，空心线需要指定线边框的宽度。不额外消耗内存。

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

在同一通道上OSD的内容永远在最上层；COVER、FRAME和LINE之间根据不同芯片硬件设计的不同，层级关系也不同。

不同芯片和模块上支持的区域类型和特性各有不同，在使用RGN模块前请先仔细查阅芯片差异说明！！

图1‑1 不同区域属性叠加效果图

1.1.1 关键字说明¶

I2

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

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

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

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

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

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

COVER + FRAME + LINE 的统称

1.2. 基本结构¶

图1‑2 基本结构框架

1.3. 功能介绍¶

支持区域管理：可对OSD、COVER、FRAME以及LINE等不同区域类型进行管理。
支持多种格式：OSD支持真彩和Index格式，COVER、FRAME和LINE支持YUV格式。
支持多通道处理：对不同模块的通道进行处理。
支持多种绘图叠加显示：OSD、COVER、FRAME和LINE可以叠加显示。

1.4. 应用场景¶

应用程序可以基于MI_RGN提供的API接口在LINUX、RTOS及DUALOS进行开发。

1.4.1. OSD应用场景及内存使用说明¶

为确保OSD能稳定输出在video上，RGN根据硬件/用户的使用情况为每个OSD分配一到多张buffer，中心思想为防止对正在用于硬件显示的buffer做写操作，从而造成OSD闪烁或撕裂的现象。

可能会增加RGN内存占用的情况主要有以下3种：

上层刷新OSD（调用MI_RGN_SetBitMap/MI_RGN_GetCanvasInfo/MI_RGN_UpdateCanvas）的速度变快；
一个OSD被同时叠加到的通道数增多；
一个通道同时叠加的OSD数超过硬件最大layer（每个芯片支持的硬件最大layer数见表1-5：Tiramisu芯片信息、表1-6：Muffin芯片信息、表1-7：Mochi芯片信息、表1-8：Maruko芯片信息、表1-9：Opera芯片信息、表1-10：Souffle芯片信息）、表1-12：Iford芯片信息）、表1-13：Ifado芯片信息）、表1-14：Pcupid芯片信息）、表1-15：Ifackel芯片信息、表1-20：Ibopper芯片信息、表1-21：Jaguar1芯片信息、表1-26：Ifliegen芯片信息、表1-29：Ihalo芯片信息）。

下表列出了几种常见的场景下buffer使用情况：

表1-1：OSD buffer使用

场景描述	OSD个数	OSD刷新速度 t/次	通道个数	buffer使用
1个OSD贴到1个通道，只贴一次不刷新	1	NA	1	1
1个OSD贴到1个通道，慢速刷新	1	1s	1	2
1个OSD贴到1个通道，快速刷新	1	30ms	1	3
1个OSD贴到n个通道，只贴一次不刷新	1	NA	n	1
1个OSD贴到n个通道，慢速刷新	1	1s	n	2
1个OSD贴到n个通道，快速刷新	1	30ms	n	[3, 2n+1]
m个OSD贴到1个通道，只贴一次不刷新	m <= L	NA	1	m
m个OSD贴到1个通道，慢速刷新	m <= L	1s	1	2m
m个OSD贴到1个通道，快速刷新	m <= L	30ms	1	3m
m个OSD贴到n个通道，只贴一次不刷新	m <= L	NA	n	m
m个OSD贴到n个通道，慢速刷新	m <= L	1s	n	2m
m个OSD贴到n个通道，快速刷新	m <= L	30ms	n	[3m, m(2n+1)]
m个OSD贴到n个通道，只贴一次不刷新	m > L	NA	n	L + n(m - L)
m个OSD贴到n个通道，慢速刷新	m > L	1s	n	2L + 2n(m - L)
m个OSD贴到n个通道，快速刷新	m > L	30ms	n	[3L, L(2n+1)] + 3n(m–L)

注：

L 表示硬件最大 layer 数；
形如[3, 2n+1]表示闭区间，buffer个数为此区间内的某个值（受系统调度影响，通常不会到达最大值）。
以上buffer使用情况仅适用于用户不限定OSD buffer数量的情形，若通过MI_RGN_Create设定最大OSD buffer数量，则最大OSD buffer数量以用户设定为准。

1.4.2. COVER应用场景及内存使用说明¶

COVER按照区域类型，分为矩形COVER和多边形COVER。当通道中贴有多边形COVER时，最少需要1张buffer，buffer长度 = （屏幕宽/8）（需向上16byte对齐）* 屏幕高，单位是（byte）。

注：此处的屏幕宽高为当前所贴通道的分辨率

下表列出了几种常见的场景下buffer使用情况：

表1-2：COVER buffer使用

场景描述	通道个数	最少buffer张数	最多buffer张数
1个通道贴1个或多个多边形COVER，不刷新	1	1	1
1个通道贴1个或多个多边形COVER，慢速刷新	1	2	2
1个通道贴1个或多个多边形COVER，快速刷新	1	2	3
n个通道分别贴1个或多个多边形COVER，不刷新	n	n	n
n个通道分别贴1个或多个多边形COVER，慢速刷新	n	2n	2n
n个通道分别贴1个或多个多边形COVER，快速刷新	n	2n	3n

1.4.3. 反色应用场景及内存使用说明¶

反色AUTO模式下每个通道最少需要1张buffer，MANUAL模式下每个通道最少需要2张buffer，buffer长度 =（屏幕宽/反色横向block长度）（需向上16byte对齐）*（屏幕高/反色纵向block长度），单位是（byte）。

注：此处的屏幕宽高为当前所贴通道的分辨率

下表列出了几种常见的场景下buffer使用情况：

表1-3：反色 buffer使用

场景描述	反色模式	最少buffer张数	最多buffer张数
1个通道，反色多帧	AUTO	1	1
1个通道，反色多帧	MANUAL	3	5
m个通道，反色多帧	AUTO	m	m
m个通道，反色多帧	MANUAL	3m	5m

1.5. 芯片差异¶

1.5.1 通用说明¶

各个芯片之间的差异主要体现在以下几个方面：通道类型、OSD硬件Layer数、OSD反色、Frame数、Cover数、Mosaic模式、多边形Cover以及支持的颜色格式。

通道类型：该芯片所支持的通道类型。
OSD硬件Layer数：通道中每个GOP支持的OSD个数。
OSD反色：通道是否支持OSD反色处理。
Frame数：通道支持贴Frame的个数。
Cover数：通道支持贴Cover的个数。
Mosaic模式：通道是否支持马赛克模式。
多边形Cover：通道是否支持贴多边形Cover。

注：在阅读芯片差异前，请先查看下面的图例。

Common

图1‑3 图例

部分芯片中的硬件可以选择被MI_RGN或者MI_FB使用，同一个硬件不能同时被两个模块使用。
对于引用了相同RGN硬件（GOP or MFF）的通道之间有一定使用限制，即可能会同时工作的通道不能同时引用同一个RGN硬件。

表1-4：RGN硬件复用规则

通道的关系（未提及的关系可为任意值）	能否同时叠加RGN	举例	说明
模块不同	No	SCL某个通道和DISP某个通道	不同模块的硬件独立，会同时工作
模块相同，Dev不同	No	SCL Dev0和SCL Dev1	相同模块不同Dev的硬件独立，会同时工作
模块相同，Dev相同，Chn不同	Yes	SCL Dev0 Chn0和SCL Dev0 Chn1	相同模块相同Dev不同Chn是同一个硬件的分时复用，不会同时工作
模块相同，Dev相同，Chn相同，Port类型相同，PortId不同	No	SCL Dev0 Chn0 OutputPort0和SCL Dev0 Chn0 OutputPort1	相同模块相同Dev相同Chn，硬件会同时工作
模块相同，Dev相同，Chn相同，Port类型不同	No	SCL Dev0 Chn0 InputPort0和SCL Dev0 Chn0 OutputPort0	相同模块相同Dev相同Chn，硬件会同时工作

1.5.2 Tiramisu¶

Tiramisu

图1‑4 Tiramisu芯片相关模块结构图

该芯片RGN只能在SCL上贴OSD和COVER。

SCL每个device支持6路output port(id:0-5)，每个output port占用一个SCL_GOP硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

表1-5：Tiramisu芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	NA

1.5.3 Muffin¶

Muffin

图1‑5 Muffin芯片相关模块结构图

该芯片DISP的每个device中有GOP_CUR0，GOP_CUR1，GOP_UI三种硬件，其中GOP_CUR0用于给RGN显示OSD，其它用于给MI_FB模块显示UI和鼠标。

SCL每个device支持9路output port(id:0-8)，其中output port(0-3)共用SCL_GOP0硬件，output port(4-8)共用SCL_GOP1硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件，device1占用VENC_GOP1硬件，device8占用JPE_GOP0硬件，device9占用JPE_GOP1硬件。

SCL GOP会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-6：Muffin芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	NA
VENC	8	NA	NA	NA	NA	NA	Y	NA
JPE	8	NA	NA	NA	NA	NA	Y	NA
DISP	1	NA	NA	NA	NA	NA	Y	NA

1.5.4 Mochi¶

Mochi

图1‑6 Mochi芯片相关模块结构图

该芯片DISP的每个device中有GOP_CUR0，GOP_CUR1，GOP_UI三种硬件，其中GOP_CUR0用于给RGN显示OSD，其它用于给MI_FB模块显示UI和鼠标。

SCL每个device支持7路output port(id:0-6)，共用SCL_GOP硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件，device8占用JPE_GOP0硬件，device9占用JPE_GOP1硬件。

表1-7：Mochi芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	NA
VENC	8	NA	NA	NA	NA	NA	Y	NA
JPE	8	NA	NA	NA	NA	NA	Y	NA
DISP	1	NA	NA	NA	NA	NA	Y	NA

1.5.5 Maruko¶

Maruko

图1‑7 Maruko芯片相关模块结构图

该芯片SCL每个device支持4路output port(id:0-3)，SCL与DISP共用GOP硬件（同一时刻仅有一方可占用）。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件，device8占用JPE_GOP0硬件。

SCL GOP会被多个SCL硬件或者DISP硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-8：Maruko芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	Y
VENC	8	NA	NA	NA	NA	NA	Y	NA
JPE	8	NA	NA	NA	NA	NA	Y	NA
DISP	8	NA	NA	NA	NA	NA	Y	Y

1.5.6 Opera¶

Opera

图1‑8 Opera芯片相关模块结构图

该芯片SCL每个device支持4路output port(id:0-3)，其中output port(0-1) 占用SCL_GOP0硬件，output port(2-3) 占用 SCL_GOP1硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件，device8占用JPE_GOP0硬件。

SCL GOP会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-9：Opera芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	Y
VENC	8	NA	NA	NA	NA	NA	Y	NA
JPE	8	NA	NA	NA	NA	NA	Y	NA

1.5.7 Souffle¶

Souffle

图1‑9 Souffle芯片相关模块结构图

该芯片SCL每个device支持7路output port(id:0-6)，每个device支持1路input port。SCL与DISP共用GOP硬件（同一时刻仅有一方可占用），SCL独占COVER/FRMAE硬件。

SCL相同id的input port和output port共用同一个COVER硬件，不同id对应不同的COVER硬件，且硬件之间相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件和 VENC_COVER/FRAME硬件，device8占用JPE_GOP0硬件和JPE_COVER/FRAME硬件。

同一个通道上不同类型区域的层级从上到下分别为OSD、FRAME、COVER（包含颜色模式COVER和马赛克模式COVER）；

同一个通道颜色模式COVER和FRAME的颜色最多只能各有16种，同一种颜色可以重复使用；

SCL GOP会被多个SCL硬件或者DISP硬件复用，具体请参考表1-4：RGN硬件复用规则；

SCL COVER和FRAME硬件会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

矩形COVER的Layer属性和多边形COVER的Layer属性分别计算，矩形COVER在多边形COVER之上；

同一个通道的所有多边形COVER都必须是同一种类型，颜色模式COVER的颜色一致，马赛克模式COVER的block size一致。

该平台支持在同一个通道上同时叠加多个不同像素格式的OSD。

表1-10：Souffle芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_INPUT_PORT	NA	NA	32	32	Y	Y	NA	NA
SCL_OUTPUT_PORT	8	Y	32	32	Y	Y	Y	Y
VENC	8	Y	32	64	Y	NA	Y	NA
JPE	8	Y	32	64	Y	NA	Y	NA
DISP	8	NA	NA	NA	NA	NA	Y	Y

表1-11：Mosaic 模式 block size 支持情况

通道类型	block size 4	block size 8	block size 16	block size 32	block size 64	block size 128	block size256
SCL_INPUT_PORT	N	Y	Y	Y	Y	Y	Y
SCL_OUTPUT_PORT	N	Y	Y	Y	Y	Y	Y
VENC	Y	Y	Y	Y	N	N	N
JPE	Y	Y	Y	Y	N	N	N

1.5.8 Iford¶

Iford

图1‑10 Iford芯片相关模块结构图

该芯片DISP device0 占用DISP_GOP0硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

VENC device0占用VENC_GOP0硬件和VENC_FREAME硬件，device8占用JPE_GOP0硬件和JPE_FRAME硬件。

VENC和JPE通道上不同类型区域的层级从上到下分别为OSD、FRAME。

同一个通道颜色模式COVER和FRAME的颜色最多只能各有16种，同一种颜色可以重复使用；

该芯片中DISP 实现OSD的GOP硬件和MI_FB中显示UI的硬件是同一个，同时只能使用其中一个。

该平台支持在同一个通道上同时叠加多个不同像素格式的OSD。

表1-12：Iford芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	NA	NA	NA	4	NA	NA	NA	NA
VENC	4	NA	32	NA	NA	NA	Y	NA
JPE	4	NA	32	NA	NA	NA	Y	NA
DISP	4	NA	NA	NA	NA	NA	Y	Y

1.5.9 Ifado¶

Ifado

图1‑11 Ifado芯片相关模块结构图

该芯片SCL每个device支持3路output port(id:0-2)，output port(0-2)共同占用SCL_GOP0硬件。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

SCL通道上不同类型区域的层级从上到下分别为OSD、COVER；

VENC device0 独占VENC_GOP0硬件和VENC_COVER/FRAME硬件。

VENC通道上不同类型区域的层级从上到下分别为OSD、MFF（包含FRAME,颜色模式COVER和LINE）；

VENC的COVER、FRAME和LINE通过同一个硬件实现，同一个通道上的这三种RGN统一计数，即该通道同时可以贴总共16个这三种类型的区域；

VENC的COVER、FRAME和LINE的层级一起由u32Layer参数决定，值更大的区域层级一定在值更小的区域之上；

同一个通道颜色模式COVER、FRAME和LINE同时使用的颜色最多只能有16种，同一种颜色可以重复使用；

SCL GOP会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

该平台支持在同一个通道上同时叠加多个不同像素格式的OSD。

表1-13：Ifado芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	多边形Cover	LINE数	实心LINE	空心LINE	ARGB1555/I2I4	ARGB4444/RGB565/I8
SCL_OUTPUT_PORT	4	NA	NA	4	NA	NA	NA	NA	Y	Y
VENC	4	NA	16	16	NA	16	Y	Y	Y	NA

1.5.10 Pcupid¶

该芯片RGN只能在SCL上贴COVER，不支持OSD、FRAME和LINE。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

表1-14：Pcupid芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	NA	NA	NA	4	NA	NA	NA	NA

1.5.11 Ifackel¶

Ifackel

图1‑12 Ifackel芯片相关模块结构图

该芯片SCL 每个device支持5路output port(id:0-4) 和 1路input port。SCL与DISP共用GOP硬件（同一时刻仅有一方可占用），SCL独占COVER/FRMAE硬件。

VENC device0独占VENC_GOP0硬件和VENC_COVER/FRAME硬件，device8独占JPE_GOP0和JPE_COVER/FRAME硬件。

SCL GOP会被多个SCL硬件或者DISP硬件复用，具体请参考表1-4：RGN硬件复用规则；

该平台支持在同一个通道上同时叠加多个不同像素格式的OSD。

表1-15：Ifackel芯片信息

通道类型	OSD硬件Layer数	OSD反色	ARGB1555/ARGB4444/I2/I4/I8	RGB565	ARGB8888
SCL_INPUT_PORT	NA	NA	NA	NA	NA
SCL_OUTPUT_PORT	8	NA	Y	Y	NA
VENC	8	NA	Y	NA	NA
JPE	8	NA	Y	NA	NA
DISP	8	NA	Y	Y	Y

表1-16：SCL MFF支持信息

通道类型	Frame数	颜色模式Cover+Mosaic数	Line数	多边形Cover
SCL_INPUT_PORT	32	32	NA	NA
SCL_OUTPUT_PORT	32	32	NA	NA

SCL通道上不同类型区域的层级从上到下分别为OSD、FRMAE、COVER（包含颜色模式COVER和马赛克模式COVER）；

SCL 颜色模式COVER和MOSAIC通过同一个硬件实现，同一个通道上的这两种RGN统一计数，即该通道同时可以贴总共32个这2种类型的区域；

SCL同一个通道上，颜色模式COVER和FRAME的颜色最多只能各有16种，同一种颜色可以重复使用；

SCL COVER和FRAME硬件会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-17：VENC MFF支持信息

通道类型	Frame+颜色模式Cover+Line数	Mosaic数	多边形Cover
VENC	32	32	NA

VENC通道上不同类型区域的层级从上到下分别为OSD、MFF（包含FRAME、颜色模式COVER和LINE）、马赛克模式COVER；

VENC的颜色模式COVER、FRAME和LINE通过同一个硬件实现，同一个通道上，这三种RGN统一计数，即该通道同时可以贴总共32个这3种类型的区域；

VENC同一个通道上，颜色模式COVER、FRAME和LINE的颜色最多只能有16种，同一种颜色可以重复使用；

VENC的颜色模式COVER、FRAME和LINE的层级一起由u32Layer参数决定，值更大的区域层级一定在值更小的区域之上；

表1-18：JPE MFF支持信息

通道类型	Frame数	颜色模式Cover+Mosaic数	Line数	多边形Cover
JPE	32	64	NA	NA

JPE通道上不同类型区域的层级从上到下分别为OSD、FRMAE、COVER（包含颜色模式COVER和马赛克模式COVER）；

JPE 颜色模式COVER和MOSAIC通过同一个硬件实现，同一个通道上，这两种RGN统一计数，即该通道同时可以贴总共64个这2种类型的区域;

JPE同一个通道上，颜色模式COVER和FRAME的颜色最多只能各有16种，同一种颜色可以重复使用；

表1-19：Mosaic 模式 block size 支持情况

| 通道类型 | block size 4 | block size 8 | block size 16 | block size 32 | block size 64 | block size 128 | blocksize 256 | |:---------------:|:------------:|:------------:|:-------------:|:-------------:|:-------------:|:--------------::--------------:| | SCL_INPUT_PORT | N | Y | Y | Y | Y | Y |Y | | SCL_OUTPUT_PORT | N | Y | Y | Y | Y | Y |Y | | VENC | Y | Y | Y | Y | N | N |N | | JPE | Y | Y | Y | Y | N | N |N |

1.5.12 Ibopper¶

该芯片RGN只能在SCL上贴COVER，不支持OSD、FRAME和LINE。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

表1-20：Ibopper芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	NA	NA	NA	4	NA	NA	NA	NA

1.5.13 Jaguar1¶

Jaguar1

图1‑13 Jaguar1芯片相关模块结构图

该芯片VENC device0占用VENC_GOP0硬件和VENC0_COVER/FRAME硬件，device1占用VENC_GOP1硬件和VENC1_COVER/FRAME硬件，device8占用JPE_GOP0硬件和JPE_COVER/FRAME硬件。

表1-21：OSD支持信息

通道类型	OSD硬件Layer数	OSD反色	ARGB1555/ARGB4444/I2/I4/I8	RGB565	ARGB8888
VENC0	8	NA	Y	NA	NA
VENC1	8	NA	Y	NA	NA
JPE	8	NA	Y	NA	NA

表1-22：SCL MFF支持信息

通道类型	Frame数	颜色模式Cover数	Mosaic数	Line数	多边形Cover
SCL	NA	4	NA	NA	NA

该芯片的SCL上只能贴COVER，不支持FRAME和LINE；

表1-23：VENC MFF支持信息

通道类型	Frame+颜色模式Cover+Line数	Mosaic数	多边形Cover
VENC0	32	32	NA
VENC1	32	32	NA

VENC通道上不同类型区域的层级从上到下分别为OSD、MFF（包含FRAME、颜色模式COVER和LINE）、马赛克模式COVER；

VENC的颜色模式COVER、FRAME和LINE通过同一个硬件实现，同一个通道上，这三种RGN统一计数，即该通道同时可以贴总共32个这3种类型的区域；

VENC同一个通道上，颜色模式COVER、FRAME和LINE的颜色最多只能有16种，同一种颜色可以重复使用；

VENC的颜色模式COVER、FRAME和LINE的层级一起由u32Layer参数决定，值更大的区域层级一定在值更小的区域之上；

表1-24：JPE MFF支持信息

通道类型	Frame数	颜色模式Cover+Mosaic数	Line数	多边形Cover
JPE	32	64	NA	NA

JPE通道上不同类型区域的层级从上到下分别为OSD、FRMAE、COVER（包含颜色模式COVER和马赛克模式COVER）；

JPE 颜色模式COVER和MOSAIC通过同一个硬件实现，同一个通道上，这两种RGN统一计数，即该通道同时可以贴总共64个这2种类型的区域;

JPE同一个通道上，颜色模式COVER和FRAME的颜色最多只能各有16种，同一种颜色可以重复使用；

表1-25：Mosaic 模式 block size 支持情况

通道类型	block size 4	block size 8	block size 16	block size 32	block size 64	block size 128	blocksize 256
VENC0	Y	Y	Y	Y	N	N	N
VENC1	Y	Y	Y	Y	N	N	N
JPE	Y	Y	Y	Y	N	N	N

1.5.14 Ifliegen¶

Ifliegen

图1‑14 Ifliegen芯片相关模块结构图

表1-26：OSD支持信息

通道类型	OSD硬件Layer数	OSD反色	ARGB1555/ARGB4444/I2/I4	I8	RGB565	ARGB8888
SCL_OUTPUT_PORT	1	NA	Y	Y	Y	Y
VENC0	4	NA	Y	NA	NA	NA
JPE	4	NA	Y	Y	NA	NA

SCL GOP会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-27：SCL MFF支持信息

通道类型	Frame数	颜色模式Cover数	Mosaic数	Line数	多边形Cover
SCL_OUTPUT_PORT	NA	4	NA	NA	NA

表1-28：VENC&JPE MFF支持信息

通道类型	Frame+颜色模式Cover+Line数	Mosaic数	多边形Cover
VENC0	16	NA	NA
JPE	NA	NA	NA

VENC通道上不同类型区域的层级从上到下分别为OSD、MFF（包含FRAME、颜色模式COVER和LINE）；

VENC的颜色模式COVER、FRAME和LINE通过同一个硬件实现，同一个通道上，这三种RGN统一计数，即该通道同时可以贴总共16个这3种类型的区域；

VENC同一个通道上，颜色模式COVER、FRAME和LINE的颜色最多只能有16种，同一种颜色可以重复使用；

VENC的颜色模式COVER、FRAME和LINE的层级一起由u32Layer参数决定，值更大的区域层级一定在值更小的区域之上；

JPE通道不支持叠加任何MFF区域；

1.5.15 Ihalo¶

Ihalo

图1‑15 Ihalo芯片相关模块结构图

表1-29：OSD支持信息

通道类型	OSD硬件Layer数	OSD反色	ARGB1555/ARGB4444/I2/I4	I8	RGB565	ARGB8888
SCL_OUTPUT_PORT	1	NA	Y	Y	Y	Y
VENC0	4	NA	Y	NA	NA	NA
JPE	4	NA	Y	Y	NA	NA

SCL GOP会被多个SCL硬件复用，具体请参考表1-4：RGN硬件复用规则；

表1-30：SCL MFF支持信息

通道类型	Frame数	颜色模式Cover数	Mosaic数	Line数	多边形Cover
SCL_OUTPUT_PORT	NA	4	NA	NA	NA

表1-31：VENC&JPE MFF支持信息

通道类型	Frame+颜色模式Cover+Line数	Mosaic数	多边形Cover
VENC0	16	32	NA
JPE	NA	NA	NA

VENC通道上不同类型区域的层级从上到下分别为OSD、MFF（包含FRAME、颜色模式COVER、马赛克COVER和LINE）；

VENC的颜色模式COVER、FRAME和LINE通过同一个硬件实现，同一个通道上，这三种RGN统一计数，即该通道同时可以贴总共16个这3种类型的区域；

VENC同一个通道上，颜色模式COVER、FRAME和LINE的颜色最多只能有16种，同一种颜色可以重复使用；

VENC的颜色模式COVER、FRAME和LINE的层级一起由u32Layer参数决定，值更大的区域层级一定在值更小的区域之上；

JPE通道不支持叠加任何MFF区域；

表1-32：Mosaic 模式 block size 支持情况

通道类型	block size 4	block size 8	block size 16	block size 32	block size 64	block size 128	blocksize 256
VENC	Y	Y	Y	Y	N	N	N

1.5.16 Mhera¶

该芯片RGN只能在SCL上贴COVER，不支持OSD、FRAME和LINE。

SCL每个output port都对应一个COVER硬件，不同COVER硬件相互独立，可以同时使用。

表1-33：Mhera芯片信息

通道类型	OSD硬件Layer数	OSD反色	Frame数	Cover数	Mosaic模式	多边形Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	NA	NA	NA	4	NA	NA	NA	NA

1.6. 工作原理¶

MI_RGN 不同区域类型对应有不同的硬件去管理。OSD使用GOP硬件去进行管理，COVER、FRAME和LINE使用MFF硬件进行管理，部分芯片SCL_OUTPUT_PORT叠加COVER使用BWIN硬件进行管理。

1.7. 开发流程¶

进入alkaid project根目录，make menuconfig
回车键进入Generic Options子选项
回车键进入Interface Compile Config子选项
空格键选中rgn模块
回车进入rgn模块，根据芯片支持情况选择rgn子模块，并重新编译project

编译完成将在sdk/interface/src/rgn下生成 mi_rgn.ko，同时将mi_rgn.h和mi_rgn_datatype.h release到 project/release 目录，在pure linux环境下会默认打包进入images。

1.8. 实例介绍¶

1.8.1 RGN贴OSD到SCL¶

#include <string.h>
#include <stdio.h>
#include "mi_sys.h"
#include "mi_rgn.h"
#include "mi_rgn_datatype.h"

#define OSD_WIDTH (100)
#define OSD_HEIGHT (100)
#define MAX_CANVAS_NUM (3)
#define FILE_PATH "/mnt/demo_100x100.argb1555.yuv"
#define YUV_STRIDE (200)

int main()
{
    MI_SYS_Init(0);
    MI_S32 s32Ret = 0;
    MI_RGN_PaletteTable_t stPaletteTable;
    MI_RGN_HANDLE hHandle = 0;
    MI_RGN_Attr_t stRegion;
    MI_RGN_ChnPort_t stChnPort;
    MI_RGN_ChnPortParam_t stChnAttr;
    MI_RGN_CanvasInfo_t stCanvasInfo;
    MI_S32 s32ReadCnt = 0;
    FILE *file = NULL;

    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[255].u8Alpha = 255;
    stPaletteTable.astElement[255].u8Red = 128;
    stPaletteTable.astElement[255].u8Green = 128;
    stPaletteTable.astElement[255].u8Blue = 128;
    s32Ret = MI_RGN_Init(0, &stPaletteTable);

    memset(&stRegion, 0, sizeof(MI_RGN_Attr_t));
    stRegion.eType = E_MI_RGN_TYPE_OSD;
    stRegion.stOsdInitParam.ePixelFmt = E_MI_RGN_PIXEL_FORMAT_ARGB1555;
    stRegion.stOsdInitParam.stSize.u32Width = OSD_WIDTH;
    stRegion.stOsdInitParam.stSize.u32Height = OSD_WIDTH;
    stRegion.stOsdInitParam.u16MaxCanvasNum = MAX_CANVAS_NUM;
    s32Ret = MI_RGN_Create(0, hHandle, &stRegion);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
    memset(&stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
    stChnPort.eModId = E_MI_MODULE_ID_SCL;
    stChnPort.s32DevId = 0;
    stChnPort.s32ChnId = 0;
    stChnPort.s32PortId = 0;
    stChnPort.bInputPort = FALSE;
    stChnAttr.bShow = TRUE;
    stChnAttr.u32Layer = 0;
    stChnAttr.stOsdChnPort.stPoint.s32X = 100;
    stChnAttr.stOsdChnPort.stPoint.s32Y = 100;
    stChnAttr.stOsdChnPort.stOsdAlphaAttr.eAlphaMode = E_MI_RGN_PIXEL_ALPHA;
    stChnAttr.stOsdChnPort.stOsdAlphaAttr.stAlphaPara.stArgb1555Alpha.u8BgAlpha = 0;
    stChnAttr.stOsdChnPort.stOsdAlphaAttr.stAlphaPara.stArgb1555Alpha.u8FgAlpha = 0xff;
    s32Ret = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    // 获取画布
    memset(&stCanvasInfo,0,sizeof(MI_RGN_CanvasInfo_t));
    s32Ret = MI_RGN_GetCanvasInfo(0, hHandle, &stCanvasInfo);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    // 读取 yuv 图像
    // 请先修改宏 FILE_PATH 和 YUV_STRIDE
    file = fopen(FILE_PATH,"rb");
    for (int i = 0; i < stCanvasInfo.stSize.u32Height ; i++)
    {
       fseek(file, YUV_STRIDE, SEEK_SET);
       s32ReadCnt += fread((MI_U8*)stCanvasInfo.virtAddr + i * stCanvasInfo.u32Stride, 1, YUV_STRIDE, file);
    }
    fclose(file);

    // 更新画布
    s32Ret = MI_RGN_UpdateCanvas(0, hHandle);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DetachFromChn(0, hHandle, &stChnPort);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_Destroy(0, hHandle);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DeInit(0);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    MI_SYS_Exit(0);
    return 0;
}

1.8.2 RGN贴COVER到SCL¶

#include <string.h>
#include "mi_sys.h"
#include "mi_rgn.h"
#include "mi_rgn_datatype.h"

int main()
{
    MI_SYS_Init(0);
    MI_S32 s32Ret = 0;
    MI_RGN_PaletteTable_t stPaletteTable;
    MI_RGN_HANDLE hHandle = 0;
    MI_RGN_Attr_t stRegion;
    MI_RGN_ChnPort_t stChnPort;
    MI_RGN_ChnPortParam_t stChnAttr;

    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[255].u8Alpha = 255;
    stPaletteTable.astElement[255].u8Red = 128;
    stPaletteTable.astElement[255].u8Green = 128;
    stPaletteTable.astElement[255].u8Blue = 128;
    s32Ret = MI_RGN_Init(0, &stPaletteTable);

    memset(&stRegion, 0, sizeof(MI_RGN_Attr_t));
    stRegion.eType = E_MI_RGN_TYPE_COVER;
    s32Ret = MI_RGN_Create(0, hHandle, &stRegion);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
    memset(&stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
    stChnPort.eModId = E_MI_MODULE_ID_SCL;
    stChnPort.s32DevId = 0;
    stChnPort.s32ChnId = 0;
    stChnPort.s32PortId = 0;
    stChnPort.bInputPort = FALSE;
    stChnAttr.bShow = TRUE;
    stChnAttr.u32Layer = 0;

    // rect cover
    stChnAttr.stCoverChnPort.eAreaType = E_MI_RGN_AREA_TYPE_RECT;
    stChnAttr.stCoverChnPort.stRect.s32X = 0;
    stChnAttr.stCoverChnPort.stRect.s32Y = 0;
    stChnAttr.stCoverChnPort.stRect.u32Width = 1024;
    stChnAttr.stCoverChnPort.stRect.u32Height = 1024;
    // color mode
    stChnAttr.stCoverChnPort.eMode = E_MI_RGN_COVER_MODE_COLOR;
    stChnAttr.stCoverChnPort.stColorAttr.u32Color = 0xff0000;
    /* mosaic mode
    stChnAttr.stCoverChnPort.eMode = E_MI_RGN_COVER_MODE_MOSAIC;
    stChnAttr.stCoverChnPort.stMosaicAttr.eBlkSize = E_MI_RGN_BLOCK_SIZE_64;
    */
    s32Ret = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    /* poly cover
    memset(&stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
    stChnAttr.stCoverChnPort.eAreaType = E_MI_RGN_AREA_TYPE_POLY;
    stChnAttr.stCoverChnPort.stPoly.u8VertexNum = 6;
    stChnAttr.stCoverChnPort.stPoly.astCoord[0].s32X = 1024;
    stChnAttr.stCoverChnPort.stPoly.astCoord[0].s32Y = 0;
    stChnAttr.stCoverChnPort.stPoly.astCoord[1].s32X = 2048;
    stChnAttr.stCoverChnPort.stPoly.astCoord[1].s32Y = 0;
    stChnAttr.stCoverChnPort.stPoly.astCoord[2].s32X = 3072;
    stChnAttr.stCoverChnPort.stPoly.astCoord[2].s32Y = 1024;
    stChnAttr.stCoverChnPort.stPoly.astCoord[3].s32X = 2048;
    stChnAttr.stCoverChnPort.stPoly.astCoord[3].s32Y = 2048;
    stChnAttr.stCoverChnPort.stPoly.astCoord[4].s32X = 1024;
    stChnAttr.stCoverChnPort.stPoly.astCoord[4].s32Y = 2048;
    stChnAttr.stCoverChnPort.stPoly.astCoord[5].s32X = 0;
    stChnAttr.stCoverChnPort.stPoly.astCoord[5].s32Y = 1024;
    s32Ret = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }
    */

    s32Ret = MI_RGN_DetachFromChn(0, hHandle, &stChnPort);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_Destroy(0, hHandle);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DeInit(0);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    MI_SYS_Exit(0);
    return 0;
}

1.8.3 RGN贴FRAME到SCL¶

#include <string.h>
#include "mi_sys.h"
#include "mi_rgn.h"
#include "mi_rgn_datatype.h"

int main()
{
    MI_SYS_Init(0);
    MI_S32 s32Ret = 0;
    MI_RGN_PaletteTable_t stPaletteTable;
    MI_RGN_HANDLE hHandle = 0;
    MI_RGN_Attr_t stRegion;
    MI_RGN_ChnPort_t stChnPort;
    MI_RGN_ChnPortParam_t stChnAttr;

    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[255].u8Alpha = 255;
    stPaletteTable.astElement[255].u8Red = 128;
    stPaletteTable.astElement[255].u8Green = 128;
    stPaletteTable.astElement[255].u8Blue = 128;
    s32Ret = MI_RGN_Init(0, &stPaletteTable);

    memset(&stRegion, 0, sizeof(MI_RGN_Attr_t));
    stRegion.eType = E_MI_RGN_TYPE_COVER;
    s32Ret = MI_RGN_Create(0, hHandle, &stRegion);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
    memset(&stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
    stChnPort.eModId = E_MI_MODULE_ID_SCL;
    stChnPort.s32DevId = 0;
    stChnPort.s32ChnId = 0;
    stChnPort.s32PortId = 0;
    stChnPort.bInputPort = FALSE;
    stChnAttr.bShow = TRUE;
    stChnAttr.u32Layer = 0;
    stChnAttr.stLineChnPort.stPointFrom.s32X = 100;
    stChnAttr.stLineChnPort.stPointFrom.s32Y = 100;
    stChnAttr.stLineChnPort.stPointTo.s32X = 200;
    stChnAttr.stLineChnPort.stPointTo.s32Y = 200;
    stChnAttr.stLineChnPort.u32LineWidth = 5;
    stChnAttr.stLineChnPort.u32Color = 0xff0000;
    stChnAttr.stLineChnPort.bHollow = FALSE;
    stChnAttr.stLineChnPort.u8BorderThickness = 2;
    s32Ret = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DetachFromChn(0, hHandle, &stChnPort);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_Destroy(0, hHandle);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DeInit(0);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    MI_SYS_Exit(0);
    return 0;
}

1.8.3 RGN贴LINE到SCL¶

#include <string.h>
#include "mi_sys.h"
#include "mi_rgn.h"
#include "mi_rgn_datatype.h"

int main()
{
    MI_SYS_Init(0);
    MI_S32 s32Ret = 0;
    MI_RGN_PaletteTable_t stPaletteTable;
    MI_RGN_HANDLE hHandle = 0;
    MI_RGN_Attr_t stRegion;
    MI_RGN_ChnPort_t stChnPort;
    MI_RGN_ChnPortParam_t stChnAttr;

    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[255].u8Alpha = 255;
    stPaletteTable.astElement[255].u8Red = 128;
    stPaletteTable.astElement[255].u8Green = 128;
    stPaletteTable.astElement[255].u8Blue = 128;
    s32Ret = MI_RGN_Init(0, &stPaletteTable);

    memset(&stRegion, 0, sizeof(MI_RGN_Attr_t));
    stRegion.eType = E_MI_RGN_TYPE_COVER;
    s32Ret = MI_RGN_Create(0, hHandle, &stRegion);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
    memset(&stChnAttr, 0, sizeof(MI_RGN_ChnPortParam_t));
    stChnPort.eModId = E_MI_MODULE_ID_SCL;
    stChnPort.s32DevId = 0;
    stChnPort.s32ChnId = 0;
    stChnPort.s32PortId = 0;
    stChnPort.bInputPort = FALSE;
    stChnAttr.bShow = TRUE;
    stChnAttr.u32Layer = 0;
    stChnAttr.stFrameChnPort.u32Color = 0xff0000;
    stChnAttr.stFrameChnPort.stRect.s32X = 100;
    stChnAttr.stFrameChnPort.stRect.s32Y = 100;
    stChnAttr.stFrameChnPort.stRect.u32Width = 100;
    stChnAttr.stFrameChnPort.stRect.u32Height = 100;
    stChnAttr.stFrameChnPort.u8Thickness = 5;

    s32Ret = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DetachFromChn(0, hHandle, &stChnPort);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_Destroy(0, hHandle);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    s32Ret = MI_RGN_DeInit(0);
    if (s32Ret != MI_RGN_OK)
    {
        return s32Ret;
    }

    MI_SYS_Exit(0);
    return 0;
}

2. API 参考¶

API名	功能
MI_RGN_Init	初始化
MI_RGN_DeInit	反初始化
MI_RGN_Create	创建区域
MI_RGN_Destroy	销毁区域
MI_RGN_GetAttr	获取区域属性
MI_RGN_SetBitMap	设置区域位图
MI_RGN_AttachToChn	将区域叠加到通道上
MI_RGN_DetachFromChn	将区域从通道中撤出
MI_RGN_SetDisplayAttr	设置区域的通道显示属性
MI_RGN_GetDisplayAttr	获取区域的通道显示属性
MI_RGN_GetCanvasInfo	获取区域画布信息
MI_RGN_UpdateCanvas	更新区域画布信息
MI_RGN_SetColorInvertAttr	设置通道反色属性
MI_RGN_GetColorInvertAttr	获取通道反色属性
MI_RGN_GetLuma	获取通道亮度信息

2.1. MI_RGN_Init¶

功能

初始化。

语法

MI_S32 MI_RGN_Init(MI_U16 u16SocId, MI_RGN_PaletteTable_t *pstPaletteTable);

形参

参数名称 参数含义 输入/输出

s32SocId 芯片ID，用于级联场景。输入

pstPaletteTable 调色板指针。输入
返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_BUSY 已初始化。在支持多进程的分支中，该错误原因是多次调用API的参数不一致。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件
注意
- I2 / I4 / I8 的图像格式是共用一份palette table，palette table只能在初始化时做一次，不可再次设置。
- RGB 格式不会参考 palette。
- Palette 的第 0 号成员为透明色，上层无法指定。

举例

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;
... ...
stPaletteTable.astElement[255].u8Alpha = 255;
stPaletteTable.astElement[255].u8Red = 128;
stPaletteTable.astElement[255].u8Green = 128;
stPaletteTable.astElement[255].u8Blue = 128;
s32Result = MI_RGN_Init(0, &stPaletteTable);
s32Result = MI_RGN_DeInit(0);

相关主题

MI_RGN_DeInit

2.2. MI_RGN_DeInit¶

功能

反初始化。
语法
```
MI_S32 MI_RGN_DeInit(MI_U16 u16SocId);
```
返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_BUSY 未初始化。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：libmi_rgn.so
举例

参见MI_RGN_Init 举例。
相关主题

MI_RGN_Init

2.3. MI_RGN_Create¶

功能

创建区域。

语法

MI_S32 MI_RGN_Create(MI_U16 u16SocId, MI_RGN_HANDLE hHandle, MI_RGN_Attr_t *pstRegion);

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
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中指定OSD、COVER、FRAME还是LINE
- 区域属性指针不能为空。
- 创建 COVER、FRAME或LINE时，只需指定区域类型即可。其它的属性，如区域位置，层次等信息在调用MI_RGN_AttachToChn 接口时指定。
- 创建区域时，本接口只进行基本的参数的检查，例如：最小宽高，最大宽高等；当区域 attach 到通道上时，根据各通道模块支持类型的约束条件进行更加有针对性的参数检查，譬如支持的像素格式等；
- 本接口可以设置每个OSD占用的buffer最大数量，在结构体MI_RGN_Attr_t中对 u16MaxCanvasNum 进行赋值操作。
- 若 u16MaxCanvasNum 设置为 1, 表明允许并接受画面有撕裂风险, 并且不会打印任何错误信息。

举例

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_ARGB1555;
stRegion.stOsdInitParam.stSize.u32Width = 40;
stRegion.stOsdInitParam.stSize.u32Height = 40;
stRegion.stOsdInitParam.u16MaxCanvasNum = 3;

s32Result = MI_RGN_Create(0, hHandle, &stRegion);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

s32Result = MI_RGN_GetAttr(0, hHandle, &stRegion);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

s32Result = MI_RGN_Destroy(0, hHandle);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

相关主题

MI_RGN_Destroy

MI_RGN_GetAttr

2.4. MI_RGN_Destroy¶

功能

销毁区域。

语法

MI_S32 MI_REG_Destroy (MI_U16 u16SocId, MI_RGN_HANDLE hHandle);

形参

参数名称 参数含义 输入/输出

s32SocId 芯片ID，用于级联场景。输入

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.5. MI_RGN_GetAttr¶

功能

获取区域属性。

语法

MI_S32 MI_RGN_GetAttr(MI_U16 u16SocId, MI_RGN_HANDLE hHandle, MI_RGN_Attr_t *pstRegion);

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
hHandle	区域句柄号。取值范围：[0, MI_RGN_MAX_HANDLE)	输入
pstRegion	区域属性指针。	输出

返回值
- MI_RGN_OK成功。
- 非 MI_RGN_OK失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：
注意
- 区域必须已创建。
- 区域属性指针不能为空。
举例

参见 MI_RGN_Create举例。

2.6. MI_RGN_SetBitMap¶

功能

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

语法

MI_S32 MI_RGN_SetBitMap(MI_U16 u16SocId, MI_RGN_HANDLE hHandle, MI_RGN_Bitmap_t *pstBitmap);

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
hHandle	区域句柄号。取值范围：[0, MI_RGN_MAX_HANDLE)	输入
pstBitmap	位图属性指针。	输入

返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_BUSY 失败，OSD的buffer已达最大值且当前所有buffer都正繁忙，请重复调用此API直到有buffer空闲。
- 非 MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：
注意
- 区域必须已创建。
- 支持位图的大小和区域的大小可以不一致。
- 位图从区域的(0,0)点开始加载。当位图比区域大时，将会自动将图像剪裁成区域大小。
- 位图的像素格式必须和区域的像素格式一致。
- 位图属性指针不能为空。
- 支持多次调用。
- 此接口只对 OSD有效。
- 调用了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_ARGB1555;
stBitmap.pData = pu8FileBuffer;
s32Result = MI_RGN_SetBitMap(0, hHandle, &stBitmap);
free(pu8FileBuffer);

2.7. MI_RGN_AttachToChn¶

功能

将区域叠加到通道上。

语法

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

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
hHandle	区域句柄号。取值范围：[0,MI_RGN_MAX_HANDLE)	输入
pstChnPort	通道端口结构体指针。	输入
pstChnAttr	区域通道显示属性指针。	输入

返回值
- MI_RGN_OK 成功。
- 非MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：
注意
- 区域必须已创建。
- 通道结构体指针不能为空。
- 区域通道显示属性指针不能为空。
- 不同的RGN类型使用不同的通道参数来设置通道属性:
  - OSD : MI_RGN_OsdChnPortParam_t
  - COVER: MI_RGN_CoverChnPortParam_t
  - FRAME: MI_RGN_FrameChnPortParam_t
  - LINE : MI_RGN_LineChnPortParam_t
- 并不是所有的通道上都有叠加区域的能力。
- COVER、FRAME和LINE只有硬件layer. OSD支持软件layer，底层会用软件拼图实现，拼到一起的OSD必须为同一种格式。
- OSD、FRAME、COVER和LINE叠加到通道上对channel id不会有要求。
- SCL进行rotate时不支持叠加RGN。
- 叠加到通道上的OSD小于或等于硬件layer个数，则全部使用硬件layer，反之则会用软件拼图。
- SCL对应MI_SCL模块，通常在初始化时绑定硬件SCL和软件的设备Id和output port id，具体要参考MI SCL API文档。
- DISP对应MI_DISP模块，表格中的DISPx与MI_DISP模块的设备id绑定，只能指定设备Id，通道Id和port id需填0(bInputPort无效)。
- JPE和VENC对应MI_VENC模块的不同Device（具mi_scl.z体需参考MI VENC API文档），通道Id根据实际情况填写，port id需填0（bInputPort无效）。

举例

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_MODULE_ID_SCL;
stChnPort.s32DevId = 0;
stChnPort.s32ChnId = 0;
stChnPort.s32PortId = 0;
stChnPort.bInputPort = FALSE;
stChnAttr.bShow = TRUE;
stChnAttr.u32Layer = 0;
stChnAttr.stCoverChnPort.eAreaType = E_MI_RGN_AREA_TYPE_RECT;
stChnAttr.stCoverChnPort.stRect.s32X = 0;
stChnAttr.stCoverChnPort.stRect.s32Y = 0;
stChnAttr.stCoverChnPort.stRect.u32Width = 1024;
stChnAttr.stCoverChnPort.stRect.u32Height = 1024;
stChnAttr.stCoverChnPort.eMode = E_MI_RGN_COVER_MODE_COLOR;
stChnAttr.stCoverChnPort.u32Color = 0xffff00;

s32Result = MI_RGN_AttachToChn(0, hHandle, &stChnPort, &stChnAttr);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

s32Result = MI_RGN_DetachFromChn(0, hHandle, &stChnPort);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

相关主题

MI_RGN_DetachFromChn

2.8. MI_RGN_DetachFromChn¶

功能

将区域从通道中撤出。

语法

MI_S32 MI_RGN_DetachFromChn(MI_U16 u16SocId, MI_RGN_HANDLE hHandle, MI_RGN_ChnPort_t *pstChnPort);

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
hHandle	区域句柄号。取值范围：[0, MI_RGN_MAX_HANDLE)	输入
pstChnPort	通道端口结构体指针。	输入

返回值
- MI_RGN_OK成功。
- 非MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：
注意
- 区域必须已创建。
- 通道结构体指针不能为空。
- 区域必须先叠加到通道上。
举例

参见 MI_RGN_AttachToChn举例。
相关主题

MI_RGN_AttachToChn

2.9. MI_RGN_SetDisplayAttr¶

功能

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

语法

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

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
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_MODULE_ID_SCL;
stChnPort.s32DevId = 0;
stChnPort.s32ChnId = 0;
stChnPort.s32PortId = 0;
stChnPort.bInputPort = FALSE;
s32Result = MI_RGN_GetDisplayAttr(0, hHandle, &stChnPort, &stChnAttr);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

stChnAttr.bShow = TRUE;
stChnAttr.stCoverPara.u32Layer = 0;
stChnAttr.stCoverChnPort.eAreaType = E_MI_RGN_AREA_TYPE_RECT;
stChnAttr.stCoverChnPort.stRect.s32X = 0;
stChnAttr.stCoverChnPort.stRect.s32Y = 0;
stChnAttr.stCoverChnPort.stRect.u32Width = 1024;
stChnAttr.stCoverChnPort.stRect.u32Height = 1024;
stChnAttr.stCoverChnPort.eMode = E_MI_RGN_COVER_MODE_COLOR;
stChnAttr.stCoverChnPort.stColorAttr.u32Color = 0xffff00;

s32Result = MI_RGN_SetDisplayAttr(0, hHandle, &stChnPort, &stChnAttr);
if (s32Result != MI_RGN_OK)
{
    return s32Result;
}

相关主题

MI_RGN_GetDisplayAttr

2.10. MI_RGN_GetDisplayAttr¶

功能

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

语法

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

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
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.11. MI_RGN_GetCanvasInfo¶

功能

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

语法

MI_S32 MI_RGN_GetCanvasInfo(MI_U16 u16SocId, MI_RGN_HANDLE hHandle,
                            MI_RGN_CanvasInfo_t* pstCanvasInfo);

形参

参数名称	参数含义	输入/输出
s32SocId	芯片ID，用于级联场景。	输入
hHandle	区域句柄号。取值范围：[0, MI_RGN_MAX_HANDLE)	输入
pstCanvasInfo	区域显示画布信息。	输出

返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_BUSY 失败，说明在MI_RGN_Create接口中设置 canvas 最大 buffer 数量较小，此时所有 canvas buffer 都已经被硬件占用，为防止画面 tearing，MI_RGN不允许此时更新OSD buffer直到有buffer空闲，可以选择重复调用此接口，直到硬件放弃占用 buffer；或者在调用MI_RGN_Create接口处将设定参数 u16MaxCanvasNum 调大一些。
- MI_ERR_RGN_EXIST 失败，说明此OSD贴的通道中存在OSD拼图情况且其它OSD已经获取了画布。
- 非 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不生效。
- 在同一个通道上，如果存在OSD拼图的情况，同时只允许有一个OSD拿到画布，直到该OSD调用MI_RGN_UpdateCanvas，其它OSD调用MI_RGN_SetBitMap和MI_RGN_GetCanvasInfo都会失败。不拼图时不存在该限制。

举例

MI_S32        s32Result = MI_RGN_OK;
MI_RGN_HANDLE hHandle;
MI_RGN_Attr_t stRegion;
MI_RGN_CanvasInfo_t stCanvasInfo;

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;
stRegion.stOsdInitParam.u16MaxCanvasNum = 3;
if (MI_RGN_OK != MI_RGN_Create(0, 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(0, hHandle);
    return -1;
}
retry_get_canvas:
s32Result = MI_RGN_GetCanvas(0, hHandle, &stCanvasInfo);
if (s32Result != MI_RGN_OK)
{
    if (s32Result == MI_ERR_RGN_BUSY) // every canvas has busy now
    {
        usleep(1000); // wait 1ms
        goto retry_get_canvas; // rery get canvas until return success
    }
    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(0, hHandle) != MI_RGN_OK)
{
    return s32Result;
}

相关主题

MI_RGN_UpdateCanvas

2.12. MI_RGN_UpdateCanvas¶

功能

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

语法

MI_S32 MI_RGN_UpdateCanvas(MI_U16 u16SocId, MI_RGN_HANDLE hHandle);

形参

参数名称 参数含义 输入/输出

s32SocId 芯片ID，用于级联场景。输入

hHandle 区域句柄号。取值范围：[0, MI_RGN_MAX_HANDLE) 输入
返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_NOT_PERM 失败，使用该handle调用该接口之前没有调用MI_RGN_GetCanvasInfo。
- 非 MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h。
- 库文件：
注意
- 区域必须已创建。
- 本接口配合MI_RGN_GetCanvasInfo使用。主要用于画布内存数据更新之后，进行画布切换显示。
- 本接口必须与MI_RGN_GetCanvasInfo成对调用，同一个handle先执行MI_RGN_GetCanvasInfo获取画布的内存指针，待绘图操作完成后执行本接口。
- 如果通道上存在OSD拼图，那么同时只能允许一个OSD获取画布。当多个handle叠加到同一个通道上显示，并且都会使用MI_RGN_GetCanvasInfo及本接口进行绘图操作，在这个通道上的所有绘图操作可以在同一个线程上执行；若在不同线程上，必须使用锁保护起来，否则有可能出现osd不刷新的问题。
- 以上多线程的情况下锁的使用详细说明如下：
  
  rgn 的 handle 假设有 handle0 和 handle1 都贴到同一个通道上
  
  分别两个线程
  
  handle0 T0_0 = getcanvas T0_1 = update handle1 T1_0 = getcanvas T1_1 = update
  
  按照时间T的顺序执行
  
  有问题的情况：T0_0 -> T1_0 -> T0_1 -> T1_1，会在T1_0调用MI_RGN_GetCanvasInfo时报erro并打印："This path has a OSD getcanvas already. One path only one OSD getcanvas if OSD count more than GWIN count.”。
  
  加mutex后，能够正常。调整后的时序：lock-> T0_0 -> T0_1 -> unlock -> lock -> T1_0 -> T1_1 -> unlock
举例

请参见MI_RGN_GetCanvasInfo的举例。
相关主题

MI_RGN_GetCanvasInfo

2.13. MI_RGN_SetColorInvertAttr¶

功能

设置区域的通道反色属性。

语法

MI_S32 MI_RGN_SetColorInvertAttr(MI_U16 u16SocId, MI_RGN_ChnPort_t *pstChnPort, MI_RGN_ColorInvertAttr_t *pstColorInvertAttr);

形参

参数名称参数含义输入/输出

s32SocId 芯片ID，用于级联场景。输入

pstChnPort 通道端口结构体指针。输入

pstColorInvertAttr 通道反色属性输入
返回值
- MI_RGN_OK 成功。
- 非MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h
- 库文件
注意
- 反色作用区域是整个通道，整个屏幕按照宽为eBlkSizeHori、高为eBlkSizeVert的矩形为单位分成块，屏幕右侧和下侧不足块宽和高的像素不参与反色，同一个块内反色属性一致；
- 反色作用的区域仅包括OSD的区域。
- 反色有两种工作模式：
  - “AUTO”模式，硬件直接通过块算出的亮度信息和用户设置的阈值对比决定是否反色。
  - “MANUAL”模式，用户修改通过API MI_RGN_GetLuma获取的buffer对应块的值，手动选择需要反色的块。
- 在“AUTO”模式下，用户可以通过阈值参数来控制反色的灵敏度：
  - 当前帧屏幕亮度大于(u8ThresholdHigh / 2)时，该块反色；
  - 当前帧屏幕亮度小于(u8ThresholdLow / 2)时，该块不反色；
  - 否则，上一帧该块反色则当前帧也反色，上一帧该块不反色则当前帧也不反色。
- 在“MANUAL”模式下，亮度信息buffer中每一个byte代表一个块。
  - 其中bit[6:0]是该block中所有的像素亮度的平均值左移一位得到的；bit[7]是这个块的反色结果，1代表有反色，0代表没有反色。
  - 获取亮度信息buffer后，用户可以选择修改指定块对应byte的值。byte值等于0xff时代表需要反色，否则代表不需要反色。
- Souffle
  
  图2‑1 Souffle芯片反色相关模块结构图
  
  通道类型 block size 4 block size 8 block size16 block size 32 block size 64 block size 128 block size 256
  
  SCL_OUTPORT NA NA NA Y Y Y Y
  
  VENC NA NA NA Y Y Y Y
  
  JPE NA NA NA Y Y Y Y

举例

MI_S32 s32Result = MI_RGN_OK;
MI_RGN_ChnPort_t stChnPort;
MI_RGN_ColorInvertAttr_t stColorInvertAttr;
memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
memset(&stColorInvertAttr, 0, sizeof(MI_RGN_ColorInvertAttr_t));
stChnPort.eModId = E_MI_MODULE_ID_SCL;
stChnPort.s32DevId = 1;
stChnPort.s32ChnId = 0;
stChnPort.s32PortId = 0;
stChnPort.bInputPort = FALSE;
stColorInvertAttr.bEnable = TRUE;
stColorInvertAttr.eWorkMode = E_MI_RGN_COLOR_INVERT_WORK_MODE_AUTO;
stColorInvertAttr.eBlkSizeHori = E_MI_RGN_BLOCK_SIZE_32;
stColorInvertAttr.eBlkSizeVert = E_MI_RGN_BLOCK_SIZE_32;
stColorInvertAttr.u8ThresholdHigh = 0x0;
stColorInvertAttr.u8ThresholdLow = 0x0;
s32Result = MI_RGN_SetColorInvertAttr(0, &stChnPort, &stColorInvertAttr);
if (MI_RGN_OK != s32Result)
{
    return s32Result;
}
s32Result = MI_RGN_GetColorInvertAttr(0, &stChnPort, &stColorInvertAttr);
if (MI_RGN_OK != s32Result)
{
    return s32Result;
}

相关主题

MI_RGN_GetColorInvertAttr

2.14. MI_RGN_GetColorInvertAttr¶

功能

获取区域的通道反色属性。

语法

MI_S32 MI_RGN_GetColorInvertAttr(MI_U16 u16SocId, MI_RGN_ChnPort_t *pstChnPort, MI_RGN_ColorInvertAttr_t *pstColorInvertAttr);

形参

参数名称参数含义输入/输出

s32SocId 芯片ID，用于级联场景。输入

pstChnPort 通道端口结构体指针。输入

pstColorInvertAttr 通道反色属性输出
返回值
- MI_RGN_OK 成功。
- 非MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h
- 库文件
注意
- 通道结构体指针不能为空。
- 区域通道反色属性指针不能为空。
举例

请参见MI_RGN_SetColorInvertAttr 的举例。
相关主题

MI_RGN_SetColorInvertAttr

2.15. MI_RGN_GetLuma¶

功能

获取区域的通道的屏幕亮度信息。

语法

MI_S32 MI_RGN_GetLuma(MI_U16 u16SocId, MI_RGN_ChnPort_t *pstChnPort, MI_RGN_LumaInfo_t *pstLuma);

形参

参数名称参数含义输入/输出

s32SocId 芯片ID，用于级联场景。输入

pstChnPort 通道端口结构体指针。输入

pstLuma 通道屏幕亮度信息输出
返回值
- MI_RGN_OK 成功。
- MI_ERR_RGN_NOBUF 失败，当前通道无有效的亮度信息。
- 非MI_RGN_OK 失败，参照返回值。
依赖
- 头文件：mi_sys.h、mi_rgn.h
- 库文件
注意
- 反色功能必须已经打开而且工作模式必须是“MANUAL”模式。可以重复调用，每次调用能够获取当前屏幕最新的亮度信息。
- 通道结构体指针不能为空。
- 区域通道屏幕亮度信息不能为空。

举例

// 该通道反色属性为Manual mode
MI_S32 s32Result = MI_RGN_OK;
MI_RGN_ChnPort_t stChnPort;
MI_RGN_LumaInfo_t stLuma;
MI_RGN_ColorInvertAttr_t stColorInvertAttr;
memset(&stChnPort, 0, sizeof(MI_RGN_ChnPort_t));
memset(&stColorInvertAttr, 0, sizeof(MI_RGN_ColorInvertAttr_t));
stChnPort.eModId = E_MI_MODULE_ID_SCL;
stChnPort.s32DevId = 1;
stChnPort.s32ChnId = 0;
stChnPort.s32PortId = 0;
stChnPort.bInputPort = FALSE;
s32Result = MI_RGN_GetLuma(0, &stChnPort, &stLuma);
if (MI_RGN_OK != s32Result)
{
    return s32Result;
}
char *pAddr = stLuma.virtAddr;
for (int y = 0; y < stLuma.stSize.u32Height; y++)
{
    for (int x = 0; x < stLuma.stSize.u32Width; x++)
    {
        if (pAddr[y * stLuma.u32Stride + x] > 0x128)
        {
            pAddr[y * stLuma.u32Stride + x] = 0xff;
        }
    }
}
s32Result = MI_RGN_GetColorInvertAttr(0, &stChnPort, &stColorInvertAttr);
if (MI_RGN_OK != s32Result)
{
    return s32Result;
}
stColorInvertAttr.bApplyMap = TRUE;
s32Result = MI_RGN_SetColorInvertAttr(0, &stChnPort, &stColorInvertAttr);
if (MI_RGN_OK != s32Result)
{
    return s32Result;
}

相关主题

MI_RGN_SetColorInvertAttr

3. RGN 数据类型¶

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

数据类型	定义
MI_RGN_MAX_HANDLE	定义区域的最大句柄数
MI_RGN_MAX_PALETTE_TABLE_NUM	颜色表最大元素个数
MI_RGN_MAX_PALETTE_TABLE_NUM	颜色表最大元素个数
MI_RGN_I2_PALETTE_INDEX_MAX	定义像素格式为I2时palette index的最大值
MI_RGN_I4_PALETTE_INDEX_MAX	定义像素格式为I4时palette index的最大值
MI_RGN_POLY_VERTEX_MIN	定义多边形顶点最小值
MI_RGN_POLY_VERTEX_MAX	定义多边形顶点最大值
MI_RGN_HANDLE	定义区域句柄
MI_RGN_Type_e	定义区域类型
MI_RGN_PixelFormat_e	RGB or Index格式
MI_RGN_AlphaMode_e	设定OSD Alpha显示模式
MI_RGN_BlockSize_e	定义Mosaic或者反色的块大小
MI_RGN_CoverMode_e	定义COVER的模式
MI_RGN_AreaType_e	定义区域的类型
MI_RGN_ColorInvertWorkMode_e	定义反色的工作模式
MI_RGN_Size_t	大小信息
MI_RGN_OsdAlphaAttr_t	定义OSD Alpha属性的结构体
MI_RGN_OsdInitParam_t	定义OSD区域属性结构体
MI_RGN_PaletteElememt_t	定义颜色元素
MI_RGN_PaletteTable_t	定义颜色表
MI_RGN_Attr_t	定义区域类型结构体
MI_RGN_Bitmap_t	定义位图图像信息结构
MI_RGN_ChnPort_t	定义模块设备通道结构体
MI_RGN_Point_t	定义坐标信息结构体
MI_RGN_Rect_t	定义矩形区域结构体
MI_RGN_Poly_t	定义多边形区域结构体
MI_RGN_CoverColorAttr_t	定义颜色模式COVER的属性
MI_RGN_CoverMosaicAttr_t	定义马赛克模式COVER的属性
MI_RGN_CoverChnPortParam_t	定义遮挡区域的通道显示属性
MI_RGN_FrameChnPortParam_t	定义矩形框区域的通道显示属性
MI_RGN_OsdChnPortParam_t	定义OSD区域的通道显示属性
MI_RGN_OsdArgb1555Alpha_t	Argb1555格式的前景、背景Alpha设定
MI_RGN_AlphaModePara_u	定义OSD Alpha Mode参数联合体
MI_RGN_ChnPortParam_t	定义区域通道显示属性结构体
MI_RGN_CanvasInfo_t	定义画布信息结构体
MI_RGN_ColorInvertAttr_t	定义RGN反色属性参数
MI_RGN_LumaInfo_t	定义获取的亮度信息
MI_RGN_LineChnPortParam_t	定义线段区域的通道显示属性

3.1. MI_RGN_MAX_HANDLE¶

说明

定义区域的最大句柄。
定义
```
#define MI_RGN_MAX_HANDLE 1024
```

3.2. MI_RGN_MAX_PALETTE_TABLE_NUM¶

说明

颜色表最大元素个数。

定义

#define MI_RGN_MAX_PALETTE_TABLE_NUM 256

3.3. MI_RGN_I2_PALETTE_INDEX_MAX¶

说明

定义像素格式为I2时palette index的最大值。

定义

#define MI_RGN_I2_PALETTE_INDEX_MAX  63

3.4. MI_RGN_I4_PALETTE_INDEX_MAX¶

说明

定义像素格式为I4时palette index的最大值。

定义

#define MI_RGN_I4_PALETTE_INDEX_MAX  15

3.5. MI_RGN_POLY_VERTEX_MIN¶

说明

定义多边形顶点最小值。
定义
```
#define MI_RGN_POLY_VERTEX_MIN 3
```

3.6. MI_RGN_POLY_VERTEX_MAX¶

说明

定义多边形顶点最大值。
定义
```
#define MI_RGN_POLY_VERTEX_MAX 6
```

3.7. MI_RGN_HANDLE¶

说明

定义区域句柄。
定义
```
typedef MI_U32 MI_RGN_HANDLE;
```
成员

成员名称 描述

MI_RGN_HANDLE 区域句柄。

3.8. MI_RGN_Type_e¶

说明

定义区域类型。

定义

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

成员

成员名称 描述

E_MI_RGN_OSD 视频叠加区域。

E_MI_RGN_COVER 视频遮挡区域。

E_MI_RGN_FRAME 视频矩形框区域。

E_MI_RGN_LINE 视频线段区域。

3.9. 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 getmodcap [modid] > /proc/mi_modules/mi_rgn/mi_rgn0。
- 使用者无法设定index 0的调色盘，I2/I4/I8这些格式的index0被底层driver用作color key，表示这种颜色不被硬件识别，所以当全0的数据叠加到通道上时，是不显示任何颜色的。
- Colorkey的数值可以在procfs的getcap中查看，colorkey的数值是一个16bit整型，它的高8位和低8位是一样的值，当使用Index类型的colorformat时，对内存数据进行memset 0即可让硬件不识别，当使用RGB或者ARGB格式时无论使用的是何种排列，对内存数据进行memset(colorkey & 0xFF)数值即可。

3.10. 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.11. MI_RGN_BlockSize_e¶

说明

定义Mosaic或者反色的块大小。

定义

typedef enum
{
    E_MI_RGN_BLOCK_SIZE_4 = 0,
    E_MI_RGN_BLOCK_SIZE_8,
    E_MI_RGN_BLOCK_SIZE_16,
    E_MI_RGN_BLOCK_SIZE_32,
    E_MI_RGN_BLOCK_SIZE_64,
    E_MI_RGN_BLOCK_SIZE_128,
    E_MI_RGN_BLOCK_SIZE_256,
    E_MI_RGN_BLOCK_SIZE_MAX
} MI_RGN_BlockSize_e;

成员

成员名称	描述
E_MI_RGN_BLOCK_SIZE_4	Mosaic block size为4x4或者反色block size为4。
E_MI_RGN_BLOCK_SIZE_8	Mosaic block size为8x8或者反色block size为8。
E_MI_RGN_BLOCK_SIZE_16	Mosaic block size为16x16或者反色block size为16。
E_MI_RGN_BLOCK_SIZE_32	Mosaic block size为32x32或者反色block size为32。
E_MI_RGN_BLOCK_SIZE_64	Mosaic block size为64x64或者反色block size为64。
E_MI_RGN_BLOCK_SIZE_128	Mosaic block size为128x128或者反色block size为128。
E_MI_RGN_BLOCK_SIZE_256	Mosaic block size为256x256或者反色block size为256。

3.12. MI_RGN_CoverMode_e¶

说明

定义COVER的模式。

定义

typedef enum
{
    E_MI_RGN_COVER_MODE_COLOR = 0,
    E_MI_RGN_COVER_MODE_MOSAIC,
    E_MI_RGN_COVER_MODE_MAX
} MI_RGN_CoverMode_e;

成员

成员名称	描述
E_MI_RGN_COVER_MODE_COLOR	COVER 模式为颜色模式，表示COVER区域填充纯色块。
E_MI_RGN_COVER_MODE_MOSAIC	COVER 模式为马赛克模式，表示COVER区域填充马赛克。

3.13. MI_RGN_AreaType_e¶

说明

定义区域的类型。

定义

typedef enum
{
    E_MI_RGN_AREA_TYPE_RECT = 0,
    E_MI_RGN_AREA_TYPE_POLY,
    E_MI_RGN_AREA_TYPE_MAX
} MI_RGN_AreaType_e;

成员

成员名称	描述
E_MI_RGN_AREA_TYPE_RECT	区域类型为矩形，描述一个矩形的位置及大小。
E_MI_RGN_AREA_TYPE_POLY	区域类型为多边形，描述一个多边形的顶点坐标。

3.14. MI_RGN_ColorInvertWorkMode_e¶

说明

定义反色的工作模式。

定义

typedef enum
{
    E_MI_RGN_COLOR_INVERT_WORK_MODE_AUTO = 0,
    E_MI_RGN_COLOR_INVERT_WORK_MODE_MANUAL,
    E_MI_RGN_COLOR_INVERT_WORK_MODE_MAX
} MI_RGN_ColorInvertWorkMode_e;

成员

成员名称	描述
E_MI_RGN_COLOR_INVERT_WORK_MODE_AUTO	反色工作模式为AUTO模式，根据用户设置的亮度阈值，自动对亮度满足条件的block的OSD做反色处理。
E_MI_RGN_COLOR_INVERT_WORK_MODE_MANUAL	反色工作模式为MANUAL模式，用户可以手动获取屏幕每个block的亮度信息，手动更改反色map或者更新OSD canvas。

3.15. MI_RGN_Size_t¶

说明

定义大小信息结构体。

定义

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

成员

成员名称 描述

u32Width 宽度

u32Height 高度

3.16. 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.17. MI_RGN_OsdInitParam_t¶

说明

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

定义

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

成员

成员名称	描述
ePixelFmt	像素格式。
stSize	区域的宽高。宽最大不超过3840 高最大不超过2160。
u16MaxCanvasNum	OSD画布的最大数量，为0时代表不做限制。

注意
- 某些像素格式OSD的尺寸有对齐要求：
  
  pixel format 宽对齐要求高对齐要求
  
  I2 4 1
  
  I4 2 1
  
  其它 1 1

3.18. 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.19. 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.20. 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.21. MI_RGN_Bitmap_t¶

说明

定义位图图像信息结构。

定义

typedef struct MI_RGN_Bitmap_s
{
    MI_RGN_PixelFormat_e ePixelFormat;
    MI_RGN_Size_t stSize;
    union
    {
        MI_PTR   pData;
        MI_PTR64 _Reserved;
    };
} MI_RGN_Bitmap_t;

成员

成员名称	描述
ePixelFormat	位图像素格式
stSize	位图宽度，高度，stride
pData	位图数据
_Reserved	为兼容 32 位与 64 位环境增加的保留数据，用户可忽略此字段。

3.22. MI_RGN_ChnPort_t¶

说明

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

定义

typedef struct MI_RGN_ChnPort_s
{
    MI_ModuleId_e  eModId;
    MI_S32 s32DevId;
    MI_S32 s32ChnId;
    MI_S32 s32PortId;
    MI_S32 bInputPort;
}MI_RGN_ChnPort_t;

成员

成员名称 描述

eModId 模块号

s32DevId 设备号

s32ChnId 通道号

s32PortId 输出端口id

bInputPort 端口id是否为输入端口
注意事项
- s32PortId和bInputPort参数仅在eModId为E_MI_MODULE_ID_SCL时有效。

3.23. MI_RGN_Point_t¶

说明

定义坐标信息结构体。

定义

typedef struct MI_RGN_Point_s
{
    MI_U32 s32X;
    MI_U32 s32Y;
}MI_RGN_Point_t;

成员

成员名称 描述

s32X 横坐标

s32Y 纵坐标

3.24. MI_RGN_Rect_t¶

说明

定义矩形区域结构体。

定义

typedef struct MI_RGN_Rect_s
{
    MI_S32         s32X;
    MI_S32         s32Y;
    MI_U32         u32Width;
    MI_U32         u32Height;
} MI_RGN_Rect_t;

成员

成员名称 描述

s32X X坐标

s32Y Y坐标

u32Width 矩形宽

u32Height 矩形高

3.25. MI_RGN_Poly_t¶

说明

定义多边形区域结构体。

定义

typedef struct MI_RGN_Poly_s
{
    MI_U8          u8VertexNum;
    MI_RGN_Point_t astCoord[MI_RGN_POLY_VERTEX_MAX];
} MI_RGN_Poly_t;

成员

成员名称 描述

u8VertexNum 多边形顶点数

astCoord 多边形顶点坐标数组
注意事项
- 顶点坐标数组有效的下标范围是[0 : u8VertexNum - 1]。
- 顶点坐标必须按照被描述多边形的顺时针顺序排列。
- 多边形必须是凸多边形。

3.26. MI_RGN_CoverColorAttr_t¶

说明

定义颜色模式COVER的属性。

定义

typedef struct MI_RGN_CoverColorAttr_s
{
    MI_U32 u32Color;
} MI_RGN_CoverColorAttr_t;

成员

成员名称 描述

u32Color COVER颜色值
注意事项
- u32Color代表COVER的显示颜色，其中bit[23:16]代表V分量，bit[15:8]代表Y分量，bit[7:0]代表U分量。

3.27. MI_RGN_CoverMosaicAttr_t¶

说明

定义马赛克模式Cover的属性。

定义

typedef struct MI_RGN_CoverMosaicAttr_s
{
    MI_RGN_BlockSize_e eBlkSize;
} MI_RGN_CoverMosaicAttr_t;

成员

成员名称 描述

eBlkSize 马赛克块大小

3.28. MI_RGN_CoverChnPortParam_t¶

说明

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

定义

typedef struct MI_RGN_CoverChnPortParam_s
{
    MI_RGN_AreaType_e eAreaType;
    union
    {
        MI_RGN_Rect_t stRect;
        MI_RGN_Poly_t stPoly;
    };
    MI_RGN_CoverMode_e eMode;
    union
    {
        MI_RGN_CoverColorAttr_t  stColorAttr;
        MI_RGN_CoverMosaicAttr_t stMosaicAttr;
    };
} MI_RGN_CoverChnPortParam_t;

成员

成员名称	描述
eAreaTyp	区域类型
stRect	矩形COVER位置及宽高信息，区域类型为E_MI_RGN_AREA_TYPE_RECT时有效
stPoly	多边形COVER顶点数和顶点坐标信息，区域类型为E_MI_RGN_AREA_TYPE_POLY时有效
eMode	COVER模式
stColorAttr	颜色模式COVER属性，COVER模式为E_MI_RGN_COVER_MODE_COLOR时有效
stMosaicAttr	马赛克模式COVER属性，COVER模式为E_MI_RGN_COVER_MODE_MOSAIC时有效

注意事项
- COVER的坐标类型是相对坐标，取值范围是[0~8191]；COVER的宽高是相对值，取值范围是[1:8192]。目的是为了让COVER能够在不同的分辨率下，实际显示的相对位置不变。
  
  如：COVER需要在从屏幕宽高¼处开始显示，宽高均为屏幕的½，那么COVER的stRect应该要设定成(2047, 2047, 4096, 4096)。

3.29. MI_RGN_FrameChnPortParam_t¶

说明

定义矩形框区域的通道显示属性。

定义

typedef struct MI_RGN_FrameChnPortParam_s
{
    MI_U32        u32Color;
    MI_U8         u8Thickness;
    MI_RGN_Rect_t stRect;
} MI_RGN_FrameChnPortParam_t;

成员

成员名称 描述

u32Color 颜色，数据格式为VYU444

u8Thickness 框线宽度

stRect 矩形FRAME位置及宽高信息
注意事项
- FRAME的坐标类型是相对坐标，取值范围是[0~8191]；FRAME的宽高是相对值，取值范围是[1:8192]。目的是为了让FRAME能够在不同的分辨率下，实际显示的相对位置不变。
  
  如：FRAME需要在从屏幕宽高¼处开始显示，宽高均为屏幕的½，那么FRAME的stRect应该要设定成(2047, 2047, 4096, 4096)。
- u32Color代表FRAME的显示颜色，其中bit[23:16]位代表V分量，bit[15:8]位代表Y分量，bit[7:0]代表U分量。
- 框线宽度是绝对值，指线宽占的像素数。

3.30. MI_RGN_OsdChnPortParam_t¶

说明

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

定义

typedef struct MI_RGN_OsdChnPortParam_s
{
    MI_RGN_Point_t stPoint;
    MI_RGN_OsdAlphaAttr_t stOsdAlphaAttr;
    MI_U8 u8PaletteIdx;
}MI_RGN_OsdChnPortParam_t;

成员

成员名称 描述

stPoint OSD 在该通道上的起始坐标

stOsdAlphaAttr OSD Alpha 属性

u8PaletteIdx 定义Index格式OSD像素值在调色板上的偏移

注意事项

某些像素格式OSD的起始坐标有对齐要求：

pixel format 水平方向对齐要求垂直方向对齐要求

I2 4 1

I4 2 1

其它 1 1

实际索引值计算方式：

pixel format	计算方式	取值范围
I2	实际索引值 = 像素值 + u8PaletteIdx * 4(I2格式颜色总数)	0~63
I4	实际索引值 = 像素值 + u8PaletteIdx * 16(I4格式颜色总数)	0~15
其它	不支持	NA

参与软件拼图的OSD u8PaletteIdx设定无效，使用默认值0。

3.31. 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.32. 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.33. MI_RGN_ChnPortParam_t¶

说明

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

定义

typedef struct MI_RGN_ChnPortParam_s
{
    MI_BOOL bShow;
    MI_U32 u32Layer;
    union
    {
        MI_RGN_CoverChnPortParam_t stCoverChnPort;
        MI_RGN_OsdChnPortParam_t   stOsdChnPort;
        MI_RGN_FrameChnPortParam_t stFrameChnPort;
        MI_RGN_LineChnPortParam_t  stLineChnPort;
    };
} MI_RGN_ChnPortParam_t;

成员

成员名称	描述
bShow	区域是否显示。取值范围：MI_TRUE 或者 MI_FALSE。动态属性。
u32Layer	区域层级
stCoverChnPort	COVER通道显示属性。
stOsdChnPort	OSD通道显示属性。
stFrameChnPort	FRAME通道显示属性。
stLineChnPort	LINE通道显示属性。

3.34. MI_RGN_CanvasInfo_t¶

说明

定义画布信息结构体。

定义

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

成员

成员名称	描述
phyAddr	画布物理地址。
virtAddr	画布虚拟地址
_Reserved	为兼容 32 位与 64 位环境增加的保留数据，用户可忽略此字段。
stSize	画布尺寸
u32Stride	画布的 stride，目前所有平台均为16字节对齐
ePixelFmt	画布的像素格式

3.35. MI_RGN_ColorInvertAttr_t¶

说明

定义RGN反色属性参数。

定义

typedef struct MI_RGN_ColorInvertAttr_s
{
    MI_BOOL bEnable;
    MI_BOOL bApplyMap;
    MI_RGN_ColorInvertWorkMode_e eWorkMode;
    MI_U8 u8ThresholdLow;
    MI_U8 u8ThresholdHigh;
    MI_RGN_BlockSize_e eBlkSizeHori;
    MI_RGN_BlockSize_e eBlkSizeVert;
} MI_RGN_ColorInvertAttr_t;

成员

成员名称	描述
bEnable	使能反色功能
bApplyMap	标志位，为TRUE时代表会更新用户的map
eWorkMode	工作模式
u8ThresholdLow	阈值低
u8ThresholdHigh	阈值高（必须大于等于u8ThresholdLow）
eBlkSizeHori	反色横向block size
eBlkSizeVert	反色纵向block size

注意事项
- 反色作用的范围是目标通道的整个屏幕，从左上角开始屏幕被反色横向和纵向block size分割成若干个矩形区域，反色的最小处理单位就是这些矩形区域；
- 屏幕右侧水平方向像素不满足反色横向block size的区域，反色同左侧完整block的反色状态；
- 屏幕下侧垂直方向像素不满足反色纵向block size的区域，反色同上侧完整block的反色状态；

3.36. MI_RGN_LumaInfo_t¶

说明

定义亮度信息的buffer。

定义

typedef struct MI_RGN_LumaInfo_s
{
    MI_PHY        phyAddr;
    MI_VIRT       virtAddr;
    MI_RGN_Size_t stSize;
    MI_U32        u32Stride;
} MI_RGN_LumaInfo_t;

成员

成员名称	描述
phyAddr	亮度信息buffer物理地址
virtAddr	亮度信息buffer虚拟地址
stSize	描述亮度信息的尺寸，与目标通道的分辨率和反色的block设定有关。
u32Stride	亮度信息buffer的stride，目前所有平台均为16字节对齐

3.37. MI_RGN_LineChnPortParam_t¶

说明

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

定义

typedef struct MI_RGN_LineChnPortParam_s
{
    MI_RGN_Point_t stPointFrom;
    MI_RGN_Point_t stPointTo;
    MI_U32         u32LineWidth;
    MI_U32         u32Color;
    MI_BOOL        bHollow;
    MI_U8          u8BorderThickness;
} MI_RGN_LineChnPortParam_t;

成员

成员名称	描述
stPointFrom	线段起始坐标，坐标类型为绝对坐标。
stPointTo	线段结束坐标，坐标类型为绝对坐标。
u32LineWidth	线段宽度，单位为像素数。
u32Color	线段颜色
bHollow	是否为空心线段
u8BorderThickness	边框宽度，只有空心线段时有效

注意事项
- LINE填充颜色的最小单位是2x2像素；
- u32Color代表COVER的显示颜色，其中bit[23:16]代表V分量，bit[15:8]代表Y分量，bit[7:0]代表U分量。
- 线段宽度代表的线段向两边延伸的像素数量，两边各延伸线段宽度的½。

4. 返回值¶

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

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

错误码	宏定义	描述
0	MI_RGN_OK	成功
0xA0030000	MI_NOTICE_RGN_BUFFER_CHANGE	Buffer发生改变。当设置属性时会发生，需要重新remap.
0xA0032001	MI_ERR_RGN_INVALID_HANDLE	非法的句柄
0xA0032001	MI_ERR_RGN_INVALID_DEVID	设备ID超出合法范围
0xA0032002	MI_ERR_RGN_INVALID_CHNID	通道组号错误或无效区域句柄
0xA0032003	MI_ERR_RGN_ILLEGAL_PARAM	参数超出合法范围
0xA0032004	MI_ERR_RGN_EXIST	重复创建已存在的设备、通道或资源
0xA0032005	MI_ERR_RGN_UNEXIST	试图使用或者销毁不存在的设备、通道或者资源
0xA0032006	MI_ERR_RGN_NULL_PTR	函数参数中有空指针
0xA0032007	MI_ERR_RGN_NOT_CONFIG	模块没有配置
0xA0032008	MI_ERR_RGN_NOT_SUPPORT	不支持的参数或者功能
0xA0032009	MI_ERR_RGN_NOT_PERM	该操作不允许，如试图修改静态配置参数
0xA003200C	MI_ERR_RGN_NOMEM	分配内存失败，如系统内存不足
0xA003200D	MI_ERR_RGN_NOBUF	分配缓存失败，如申请的数据缓冲区太大
0xA003200E	MI_ERR_RGN_BUF_EMPTY	缓冲区中无数据
0xA003200F	MI_ERR_RGN_BUF_FULL	缓冲区中数据满
0xA0032010	MI_ERR_RGN_NOTREADY	系统没有初始化或没有加载相应模块
0xA0032011	MI_ERR_RGN_BADADDR	地址非法
0xA0032012	MI_ERR_RGN_BUSY	系统忙

5. PROCFS介绍¶

由于 RGN 通常会 attach 到其他模块，因此下文中的 ModId是指被RGN attach的其他模块，比如SCL/VENC等。

5.1. cat¶

5.1.1 RGN 模块信息¶

调试信息

/ # cat /proc/mi_modules/mi_rgn/mi_rgn0
-----------------------------------------------------Start dump region capability info-----------------------------------------------------
Module name : REGION

Limitation :
Region handle : 1024 (0 ~ 1023)
channel       :   64 (0 ~   63)
Osd attach    :  128 (each channel port)

Osd support :
  Width   : 1 ~ 16384
  Height  : 1 ~ 8192
  Color key value : 0x23232323
  Overlap : Support

Mff support :
Size :
  Width   : 1 ~ 8192
  Height  : 1 ~ 8192

Line support :
Size :
  Pos     : -16383 ~  16383
  Width   :      1 ~  16383

------------------------------------------------------End dump region capability info------------------------------------------------------

----------------------------------------------------------Start dump region attr----------------------------------------------------------
  Handle    Type    User  CvsCnt  MaxCvs  RefCnt
       0     OSD       N       2       3       1
           Width  Height  Stride  Format      PhyAddr      VirAddr     UsingCnt
             240     135     480       0      44b3000            0            1
             240     135     480       0      44d2a80            0            0
       1     OSD       N       2       3       1
           Width  Height  Stride  Format      PhyAddr      VirAddr     UsingCnt
             240     135     480       0      44c2d40            0            1
             240     135     480       0      44e27c0            0            0
       5   COVER
       6   COVER
       9   FRAME
      10   FRAME

-----------------------------------------------------------End dump region attr-----------------------------------------------------------

-------------------------------------------------------Start dump Operate count info-------------------------------------------------------
  Handle         Type    AttachCnt    DetachCnt   SetAttrCnt    SetBitMap GetCanvasCnt UpdateCanvasCnt
       0          OSD            1            0          149            1          149          149
       1          OSD            1            0          149            1          149          149
       5        COVER            1            0          149
       6        COVER            1            0          149
       9        FRAME            1            0          149
      10        FRAME            1            0          149

--------------------------------------------------------End dump Operate count info--------------------------------------------------------

-------------------------------------------------------Start dump Operate time info-------------------------------------------------------
  Handle         Type    UpdateCvsCost(us)  UpdateCvsInterval(ms)      SetAttrCost(us)  SetAttrInterval(ms)
       0          OSD                  740                    101                    7                  102 (avg)
                                       878                    102                    8                  103 (max)
                                       716                    101                    7                  102 (min)
       1          OSD                  722                    101                    6                  102 (avg)
                                       769                    102                    7                  103 (max)
                                       690                    101                    5                  102 (min)
       5        COVER                                                               10                  102 (avg)
                                                                                    12                  103 (max)
                                                                                     9                  102 (min)
       6        COVER                                                                4                  102 (avg)
                                                                                     5                  103 (max)
                                                                                     4                  102 (min)
       9        FRAME                                                                4                  102 (avg)
                                                                                     5                  103 (max)
                                                                                     4                  102 (min)
      10        FRAME                                                                3                  102 (avg)
                                                                                     4                  103 (max)
                                                                                     3                  102 (min)

--------------------------------------------------------End dump Operate time info--------------------------------------------------------

--------------------------------------------Start dump Mod 2 device 0 Channel 0 outport 0 info--------------------------------------------

---------------------------------------------------------------ChnPort Info---------------------------------------------------------------
      ScreenWidth     ScreenHeight     RealtimeFlip       EnqueueCnt       DequeueCnt     OsdRewindCnt     MapRewindCnt
             1920             1080          Disable              386              386                0                0

--------------------------------------------------------------Disp OnOff Info--------------------------------------------------------------
      OSD            COVER            FRAME             LINE
       On               On               On               On

-------------------------------------------------------------ChnPort Time Info-------------------------------------------------------------
     EnqueueCost(us) EnqueueInterval(ms)     DequeueCost(us) DequeueInterval(ms)
                 120                  39                   9                  39 (avg)
                 139                  42                  10                  41 (max)
                  96                  39                   9                  39 (min)

-------------------------------------------------------------ColorInvert Info-------------------------------------------------------------
      Enable    WorkMode   BlkSzHori   BlkSzVert  ThreshHigh   ThreshLow  ReadPhyAddr WritePhyAddr StorageMode     CalMode
           0           0           0           0           0           0            0            0           0           0

--------------------------------------------------------------frontbuff Info--------------------------------------------------------------
 Index bShow  OffsetX  OffsetY Width  Height   Stride   Format   PhyAddr AlphaMode AlphaVal BgAlpha FgAlpha paletteIdx BufCnt OsdCnt

----------------------------------------------------------------region Info----------------------------------------------------------------
Handle   Type bShow Layer areaType  PosX  PosY Width Height    Color BlkSize thickness Format AlphaMode AlphaVal BgAlpha FgAlpha paletteIdx
     0    OSD     1   447           1157   343   240    135                                 0     Pixel               26      96          0
     1    OSD     0   435            197   111   240    135                                 0     Pixel               40       3          0
     5  COVER     1    55        0  7974   867  1024   1024     7fc8
     6  COVER     1   459        0  3499  3720  1024   1024       ff
     9  FRAME     1   240           1164  1640  7286   7048     7fc8                 6
    10  FRAME     1   851           6481  2037  8163   4881   7fdc00                16
Handle   Type bShow Layer FromX FromY   ToX   ToY  Width    Color  Hollow thickness
    13   LINE     0   450  1259   107  1087   421    400   418041   solid        16
    14   LINE     0   768   609   940   740   814    504   a0a0a0   solid        14

---------------------------------------------End dump Mod 2 device 0 Channel 0 outport 0 info---------------------------------------------

----------------------------------------------------Start dump info of buffers in used----------------------------------------------------
Memory used:
kmalloc    : 8384 bytes
mma malloc : 259200 bytes

-----------------------------------------------------End dump info of buffers in used-----------------------------------------------------

调试信息分析

记录当前RGN的使用状况以及device属性可以动态地获取到这些信息，方便调试和测试。
参数说明
- Region capability
  - Region handle: 创建region的最大数量为1024个，句柄取值为[0~1023]
  - channel: 最大通道数量为64个，通道取值为[0~63]
  - Osd attach: 每个输出端口每个通道能绑定的Osd数量上限为128个
  - Osd Support:
    - Width: OSD宽取值范围为1 ~ 16384
    - Height: OSD高取值范围为1~ 8192
    - Color key value: 系统默认的colorkey的值，除了index的格式，不管OSD的format是多少，只要内存中的值是此就表示colorkey
  - Mff(Cover/Mosaic/Frame) support:
    - Width: Mff宽取值范围为1 ~ 8192
    - Height: Mff高取值范围为1 ~ 8192
    - Overlap: Mff是否支持重叠
  - Line support:
    - Size:
      - Pos: Line端点坐标取值范围为-16383 ~ 16383
      - Width: Line宽取值范围为1 ~ 16383
- Region attr:
  - Handle: 句柄
  - Type: 类型，OSD、COVER、FRAME或者LINE
  - User: OSD专属参数，是否已经获取Canvas
  - CvsCnt: OSD专属参数，当前Canvas使用的buffer数量
  - MaxCnt: OSD专属参数，Canvas允许申请的buffer最大数量
  - RefCnt: OSD专属参数，Canvas直接用于HW显示的数量（OSD参与拼图时不直接通过HW显示）
  - Width: OSD专属参数，宽
  - Height: OSD专属参数，高
  - Stride: OSD专属参数，宽补齐
  - Format: OSD专属参数，颜色格式[0-6]：ARGB1555，ARGB4444，I2，I4，I8，RGB565，ARGB8888
  - PhyAddr: OSD专属参数，Canvas的物理地址
  - VirAddr: OSD专属参数，Canvas的虚拟地址
  - UsingCnt: OSD专属参数，使用当前Canvas的HW数量
- Operate count:
  - Handle: 句柄
  - Type: 类型，OSD、COVER、FRAME或者LINE
  - AttachCnt: 该Handle 调用API MI_RGN_AttachToChn的次数。
  - DetachCnt: 该Handle 调用API MI_RGN_DetachFromChn的次数。
  - SetAttrCnt: 该Handle 调用API MI_RGN_SetDisplayAttr的次数。
  - SetBitMap: 该Handle 调用API MI_RGN_SetBitMap的次数。
  - GetCanvasCnt: 该Handle 调用API MI_RGN_GetCanvasInfo的次数。
  - UpdateCanvasCnt: 该Handle 调用API MI_RGN_UpdateCanvas的次数。
- Operate time:
  - Handle: 句柄
  - Type: 类型，OSD、COVER、FRAME或者LINE
  - UpdateCvsCost(us): 该Handle同一次调用MI_RGN_GetCanvasInfo和MI_RGN_UpdateCanvas之间的耗时，分别为avg(平均值)、miax(最大值)和min(最小值)，单位为us。
  - UpdateCvsInterval(ms): 该Handle连续两次调用MI_RGN_UpdateCanvas之间的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为ms。
  - SetAttrCost(us): 该Handle调用MI_RGN_SetDisplayAttr接口的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为us。
  - SetAttrInterval(ms): 该Handle连续两次调用MI_RGN_SetDisplayAttr的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为ms。
- Channel Port Info:
  - ChnPort Info
    - ScreenWidth: 该通道的分辨率宽
    - ScreenHeight: 该通道的分辨率高
    - RealtimeFlip: OSD realtime更新模式使能状态
    - EnqueueCnt: 该通道enqueue次数
    - DequeueCnt: 该通道dequeue次数
    - OsdRewindCnt: 该通道OSD软件拼图buffer回放次数
    - MapRewindCnt: 该通道Cover map buffer回放次数
  - Disp OnOff Info
    - OSD: 该通道OSD功能开关状态
    - COVER: 该通道COVER功能开关状态
    - LINE: 该通道LINE功能开关状态
    - FRAME: 该通道FRAME功能开关状态
  - ChnPort Time Info
    - EnqueueCost(us): Rgn enqueue的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为us。
    - EnqueueInterval(ms): Rgn连续两次enqueue的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为ms。
    - DequeueCost(us): Rgn dequeue的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为us。
    - DequeueInterval(ms): Rgn连续两次dequeue的耗时，分别为avg(平均值)、max(最大值)和min(最小值)，单位为ms。
  - ColorInvert Info:
    - Enable: 反色使能
    - WorkMode: 反色工作模式
    - BlkSzHori: 反色块水平方向占像素数
    - BlkSzVert: 反色块垂直方向占像素数
    - ThreshHigh: 反色亮度高阈值
    - ThreshLow: 反色亮度低阈值
    - ReadPhyAddr: 反色最新读buffer物理地址
    - WritePhyAddr: 反色最新写buffer物理地址
    - StorageMode: 反色存储模式（默认值即可）
    - eCalMode: 反色亮度计算模式（默认值即可）
  - Frontbuffer info:
    - Index: Frontbuffer索引
    - bShow: 是否显示
    - OffsetX: X偏移
    - OffsetY: Y偏移
    - Width: 宽
    - Height: 高
    - Stride: 宽补齐
    - Format: 颜色格式
    - PhyAddr: 物理地址
    - AlphaMode: Alpha模式，指pixel alpha还是constant alpha
    - AlphaVal: 如果是constant alpha，alpha的值
    - BgAlpha: 如果是pixel alpha，argb1555的背景alpha值
    - FgAlpha: 如果是pixel alpha，argb1555的前景alpha值
    - paletteIdx: 调色板索引值
    - BufCnt: 通道上front buffer的个数
    - OsdCnt: 通道上一个front buffer由多少个back buffer拼接而成
  - Region info:
    - Handle: 绑定Region句柄
    - Type: 绑定Region类型
    - bShow: 是否显示
    - Layer: 绑定Region的层级
    - areaType: 区域类型
    - PosX: X偏移
    - PosY: Y偏移
    - Width: 宽
    - Height: 高
    - Color: 绑定COVER或者FRAME的颜色值
    - BlkSize: 绑定Mosaic的块尺寸
    - thickness: 绑定Frame的线宽（pixel）
    - Format: 绑定OSD的颜色格式
    - AlphaMode: Alpha模式，指pixel alpha还是constant alpha
    - AlphaVal: 如果是constant alpha，alpha的值
    - BgAlpha: 如果是pixel alpha，argb1555的背景alpha值
    - FgAlpha: 如果是pixel alpha，argb1555的前景alpha值
    - paletteIdx: 调色板索引值
    - Line Info
      - FromX: Line区域起始端点水平方向的坐标值
      - FromY: Line区域起始端点垂直方向的坐标值
      - ToX: Line区域结束端点水平方向的坐标值
      - ToY: Line区域结束端点垂直方向的坐标值
      - Width: 线的宽度
      - Color: 颜色
      - Hollow: 线的种类，实心或者空心
      - thickness: 空心线的边框宽度
- Buffer info:
  - kmalloc: Region模块内部申请内存字节数。
  - mma malloc: Region模块通过Sys模块申请内存字节数。

5.1.2 RGN 内存使用信息¶

调试信息

/ # cat /proc/mi_modules/mi_sys_mma/mma_heap_name0 heap_info: heap_name pa_start length avail mma_heap_name0 2f600000 10000000 ff00000 heap_param: mmuEnable freeEntryNum 1 800

main_chunk_mgr: vpa_start length avail used HighPeak LowPeak 40000000 20000000 1ff00000 100000 9b62c00 100000

    ------------------------------------------------------------------------------------------------------------------
        offset              length           used_flag           task_name                 pid               Module
            0               100000                   1              CMDMEM                  -1               mi_sys
        100000            1ff00000                   0                  NA                  -1               mi_sys
             x                   x                   1           rgn_cvs_n                   x               mi_rgn
             x                   x                   1             ciXXXXX                   x               mi_rgn
             x                   x                   1            mapXXXXX                   x               mi_rgn
             x                   x                   1            mffXXXXX                   x               mi_rgn
             x                   x                   1           fbXXXXX_n                   x               mi_rgn

(CMDMEM)sub_chunk_mgr: vpa_start length avail 0 100000 100000

调试信息分析

记录当前RGN使用内存的信息，便于分析RGN内存使用情况。
参数说明

该小节仅介绍RGN相关字段，其他参数说明请参考MI SYS API文档。

在main_chunk_mgr中的Module一列可以找到mi_rgn的内存使用记录，针对不同场景，RGN使用的内存对应task_name会有所不同。
- x: 占位符，请以实际值为准。
- rgn_cvs_n: OSD使用内存记录，n表示handle值。
- ciXXXXX: CI使用内存记录，其后数字“XXXXX”依次表示 [ModId] [DevId] [ChnID] [PortID] [bInputPort]。
- mapXXXXX: CoverMap使用内存记录，其后数字“XXXXX”依次表示 [ModId] [DevId] [ChnID] [PortID] [bInputPort]。
- mffXXXXX: MFF使用内存记录，其后数字“XXXXX”依次表示 [ModId] [DevId] [ChnID] [PortID] [bInputPort]。
- fbXXXXX_n: FrontBuffer使用内存记录，其后数字“XXXXX”依次表示 [ModId] [DevId] [ChnID] [PortID] [bInputPort]，最后的n表示第n个FrontBuffer。
  - [ModId]: 模块号，参考mi_common_datatype.h中的模块定义枚举值。
  - [DevId]: 模块的设备号。
  - [ChnID]: 通道号 [0 ~ 63]。
  - [PortID]: 端口号 [0 ~ 3]。
  - [bInputPort]: 端口类型是否为输入端口 [0 / 1]。

5.2. dumpRgnBuf¶

功能

Dump 指定 Region 的 buffer

命令

echo dumpRgnBuf [Handle] [Path]  > /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [Handle]: region 句柄
- [Path]: 保存 dump 数据的路径。保存内容为 region 的 canvas 内容。
举例
```
echo dumpRgnBuf 0 /mnt >  /proc/mi_modules/mi_rgn/mi_rgn0
```
在 /mnt 下产生文件 Rgn0_canvasInfo_fmt0_64X48，表示 dump 句柄为 0，颜色格式为 ARGB1555，Stride 为 64，高为 48 的 region 的 canvas 数据。

文件格式为：Rgn[Handle]_canvasInfo_fmt[Format]_[Stride]X[Height]
- [Handle] region句柄。
- [Format] 颜色格式：ARGB1555为0，ARGB4444为1，I2为2，I4为3，I8为4。
- [Stride] 宽补齐。
- [Height] 高。

5.3. dumpFrontBuf¶

功能

Dump 指定 channel 和 port 的 frontbuffer

命令

echo dumpFrontBuf [ModId] [DevId] [ChnID] [PortID] [bInputPort] [Path] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId]: 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId]: 模块的设备号。
- [ChnID]: 通道号 [0 ~ 63]。
- [PortID]: 端口号 [0 ~ 3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [Path]: 保存dump数据的路径。会根据当前实际使用的frontbuffer数量生成0 ~ 8个文件。
举例
```
echo dumpFrontBuf 34 1 0 0 0 /mnt > /proc/mi_modules/mi_rgn/mi_rgn0
```
在 /mnt 下产生 Mod34_Dev1_Chn0_InPort0_frontbuf0_fmt0_64X48，表示 dump 模块号为 34，设备号为 1，通道为 0，端口为 0 号输入端口，索引为 0 的 frontbuffer 的数据。颜色格式为 ARGB1555，Stride 为 64，高为 48。

文件格式为：`Mod[ModId]Dev[DevId]_Chn[Channel][In/Out]Port[Port]frontbuf[Index]_fmt[Format][Stride]X[Height]
- [ModId]: 输出模块号。
- [DevId]: 输出模块的设备号。
- [Channel]: 通道号。
- [In/Out]: 端口类型。
- [Port]: 端口号。
- [Index]: frontbuffer索引号。
- [Format]: 颜色格式：ARGB1555为0，ARGB4444为1，I2为2，I4为3, I8为4。
- [Stride]: 宽补齐。
- [Height]: 高。

5.4. getcap¶

功能

获取 region 能力集信息

命令

echo getcap > /proc/mi_modules/mi_rgn/mi_rgn0

5.5. dumprgn¶

功能

获取已创建 region 信息

命令

echo dumprgn > /proc/mi_modules/mi_rgn/mi_rgn0

5.6. dumpchport¶

功能

获取已创建 channel 和 port 的信息

命令

echo dumpchport > /proc/mi_modules/mi_rgn/mi_rgn0

5.7. bufcnt¶

功能

获取内存使用信息

命令

echo bufcnt > /proc/mi_modules/mi_rgn/mi_rgn0

5.8. dumpPalette¶

功能

获取 Palette 信息

命令

echo dumpPalette > /proc/mi_modules/mi_rgn/mi_rgn0

5.9. setDispOnOff¶

功能

开关某个gwin.

命令

echo setDispOnOff [ModId] [DevId] [ChnID] [PortID] [bInputPort] [Idx] [OnOff] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId]: 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId]: 模块的设备号。
- [ChnID]: 通道号 [0 ~ 63]。
- [PortID]: 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [Idx]: 当前通道上OSD显示gwin的序号。
- [OnOff]: 是否开关，0表示关、1表示开。

举例

echo setDispOnOff 34 1 0 0 0 0 0 > /proc/mi_modules/mi_rgn/mi_rgn0

5.10. forceUpdate¶

功能

强制更新OSD的back buffer.

命令

echo forceUpdate [handle] > /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [handle]: OSD handle

举例

echo forceUpdate 0 > /proc/mi_modules/mi_rgn/mi_rgn0

5.11. setRealtimeFlip¶

功能

使能OSD实时显示模式，确保在用户操作后的下一帧视频画面即可显示OSD

命令

echo setRealtimeFlip [ModId] [DevId] [ChnID] [PortID] [bInputPort] [OnOff] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId]: 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId]: 模块的设备号。
- [ChnID]: 通道号 [0 ~ 63]。
- [PortID]: 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [OnOff]: RealtimeFlip使能状态。

举例

echo setRealtimeFlip 34 1 0 0 0 1  >/proc/mi_modules/mi_rgn/mi_rgn0

5.12. setMaxCanvasForPath¶

功能

限制指定channel和port的最大使用buffer数。

命令

echo setMaxCanvasForPath [ModId] [DevId] [ChnID] [PortID] [bInputPort] [LimitNum] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId] 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId] 模块的设备号。
- [ChnID] 通道号 [0 ~ 63]。
- [PortID] 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [LimitNum] 设定的最大buffer数。

举例

echo setMaxCanvasForPath 34 1 0 0 0 2  > /proc/mi_modules/mi_rgn/mi_rgn0

5.13. getmodcap¶

功能

获取其他modules 对于RGN的支持能力。

命令

echo getmodcap [ModId] [DevId] [ChnID] [PortID] [bInputPort] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId]：模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId] 模块的设备号。
- [ChnID] 通道号 [0 ~ 63]。
- [PortID] 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。

举例

echo getmodcap 2 0 0 0 0 >  /proc/mi_modules/mi_rgn/mi_rgn0

5.14. dumpOperateCnt¶

功能

获取 handle 操作的引用计数信息

命令

echo dumpOperateCnt >  /proc/mi_modules/mi_rgn/mi_rgn0

5.15. setcolorkeymask¶

功能

设置 colorkey 的 mask 掩码

命令

echo setcolorkeymask [Mask] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [Mask]：colorkeymask值，16进制数 rgb。

举例

echo setcolorkeymask 0xff0000 >  /proc/mi_modules/mi_rgn/mi_rgn0

5.16. debugRgnWin¶

功能

debug rgn 通道

命令

echo debugRgnWin [ModId] [DevId] [ChnID] [PortID] [bInputPort] [Mask] [bSetCnt] [Count] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId] 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId] 模块的设备号。
- [ChnID] 通道号 [0 ~ 63]。
- [PortID] 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [Mask]: Debug类型掩码。
- [bSetCnt]：是否计数[0 / 1]，为1时采用计数，打印[count]条log后停止打印；为0时不采用计数，log会一直打印。
- [Count]：计数。

举例

echo debugRgnWin 34 1 0 0 0 0xff 1 100 > /proc/mi_modules/mi_rgn/mi_rgn0

5.17. maskOperate¶

功能

屏蔽指定操作的功能

命令

echo maskOperate [Operate] [enable] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [Operate] 具体操作，可取"attach", "detach", "bitmap", "setattr", "getcanvas", "updatecanvas"。
- [enable] mask 使能，on/off。

举例

echo maskOperate attach on >  /proc/mi_modules/mi_rgn/mi_rgn0

5.19. setRgnOnOff¶

功能

开关某个通道上贴的所有某种类型区域(OSD/COVER/FRAME等)，可以从RGN procfs info中的《Disp OnOff Info》中确认当前的开关状态。

命令

echo setRgnOnOff [ModId] [DevId] [ChnID] [PortID] [bInputPort] [RgnType] [OnOff] >  /proc/mi_modules/mi_rgn/mi_rgn0

参数说明
- [ModId]: 模块号，参考mi_common_datatype.h中的模块定义枚举值。
- [DevId]: 模块的设备号。
- [ChnID]: 通道号 [0 ~ 63]。
- [PortID]: 端口号 [0~3]。
- [bInputPort]: 端口类型是否为输入端口 [0 / 1]。
- [RgnType]: RGN类型，参考枚举MI_RGN_Type_e中的定义。例如0代表OSD。
- [OnOff]: 是否开关，0表示关、1表示开。

举例

echo setRgnOnOff 34 1 0 0 0 0 0 > /proc/mi_modules/mi_rgn/mi_rgn0

6. MODPARAM.json介绍¶

6.1. json文件内容¶

"E_MI_MODULE_ID_RGN" :
{
    "b_support_osd_blending": false
}

modparam.json 文件在/config 目录下，该文件在sys 初始化阶段会加载进去。

6.2. RGN常用参数以及参数解析¶

参数名	默认值	支持平台	是否支持客户配置	作用
b_support_osd_blending	false	Maruko，Iford，Ifado，Ifackel	Y	控制 osd 重叠区alpha blending功能的开关

6.3. 参数用法举例¶

6.3.1. b_support_osd_blending¶

该参数是控制 osd 重叠区alpha blending功能的开关。"b_support_osd_blending":false, 表示关闭osd 重叠区alpha blending 的功能；"b_support_osd_blending":TRUE, 表示开启osd 重叠区alpha blending 的功能。

应用场景：当多个OSD重叠时，如果不打开osd 重叠区alpha blending功能，只会显示最上层OSD的内容，而此时如果最上层OSD为透明，则全部内容都将不显示。所以osd blending的优点是能将重叠OSD中非透明部分显示出来。缺点是该功能为软件功能，由CPU实现，开启后会导致CPU loading以及BW增加，且可能导致显示延迟。若在使用过程中，需要使用该功能且希望快速显示，可使用setRealtimeFlip使能OSD实时显示模式来加速显示。具体参考5.11节setRealtimeFlip。效果对比如下：

disable

图6‑1 关闭alpha blending功能
enable

图6‑1 开启alpha blending功能

成员名称	描述
E_MI_RGN_OSD	视频叠加区域。
E_MI_RGN_COVER	视频遮挡区域。
E_MI_RGN_FRAME	视频矩形框区域。
E_MI_RGN_LINE	视频线段区域。

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

成员名称	描述
eModId	模块号
s32DevId	设备号
s32ChnId	通道号
s32PortId	输出端口id
bInputPort	端口id是否为输入端口

成员名称	描述
u8VertexNum	多边形顶点数
astCoord	多边形顶点坐标数组

成员名称	描述
u32Color	颜色，数据格式为VYU444
u8Thickness	框线宽度
stRect	矩形FRAME位置及宽高信息

成员名称	描述
stPoint	OSD 在该通道上的起始坐标
stOsdAlphaAttr	OSD Alpha 属性
u8PaletteIdx	定义Index格式OSD像素值在调色板上的偏移

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

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

MI RGN API¶

REVISION HISTORY¶

1. 概 述¶

1.1. 模块说明¶

1.1.1 关键字说明¶

1.2. 基本结构¶

1.3. 功能介绍¶

1.4. 应用场景¶

1.4.1. OSD应用场景及内存使用说明¶

1.4.2. COVER应用场景及内存使用说明¶

1.4.3. 反色应用场景及内存使用说明¶

1.5. 芯片差异¶

1.5.1 通用说明¶

1.5.2 Tiramisu¶

1.5.3 Muffin¶

1.5.4 Mochi¶

1.5.5 Maruko¶

1.5.6 Opera¶

1.5.7 Souffle¶

1.5.8 Iford¶

1.5.9 Ifado¶

1.5.10 Pcupid¶

1.5.11 Ifackel¶

1.5.12 Ibopper¶

1.5.13 Jaguar1¶

1.5.14 Ifliegen¶

1.5.15 Ihalo¶

1.5.16 Mhera¶

1.6. 工作原理¶

1.7. 开发流程¶

1.8. 实例介绍¶

1.8.1 RGN贴OSD到SCL¶

1.8.2 RGN贴COVER到SCL¶

1.8.3 RGN贴FRAME到SCL¶

1.8.3 RGN贴LINE到SCL¶

2. API 参考¶

2.1. MI_RGN_Init¶

2.2. MI_RGN_DeInit¶

2.3. MI_RGN_Create¶

2.4. MI_RGN_Destroy¶

2.5. MI_RGN_GetAttr¶

2.6. MI_RGN_SetBitMap¶

2.7. MI_RGN_AttachToChn¶

2.8. MI_RGN_DetachFromChn¶

2.9. MI_RGN_SetDisplayAttr¶

2.10. MI_RGN_GetDisplayAttr¶

2.11. MI_RGN_GetCanvasInfo¶

2.12. MI_RGN_UpdateCanvas¶

2.13. MI_RGN_SetColorInvertAttr¶

2.14. MI_RGN_GetColorInvertAttr¶

2.15. MI_RGN_GetLuma¶

3. RGN 数据类型¶

3.1. MI_RGN_MAX_HANDLE¶

3.2. MI_RGN_MAX_PALETTE_TABLE_NUM¶

3.3. MI_RGN_I2_PALETTE_INDEX_MAX¶

3.4. MI_RGN_I4_PALETTE_INDEX_MAX¶

3.5. MI_RGN_POLY_VERTEX_MIN¶

3.6. MI_RGN_POLY_VERTEX_MAX¶

3.7. MI_RGN_HANDLE¶

3.8. MI_RGN_Type_e¶

3.9. MI_RGN_PixelFormat_e¶

3.10. MI_RGN_AlphaMode_e¶

3.11. MI_RGN_BlockSize_e¶

3.12. MI_RGN_CoverMode_e¶

3.13. MI_RGN_AreaType_e¶

3.14. MI_RGN_ColorInvertWorkMode_e¶

3.15. MI_RGN_Size_t¶

3.16. MI_RGN_OsdAlphaAttr_t¶

3.17. MI_RGN_OsdInitParam_t¶

3.18. MI_RGN_PaletteElement_t¶

3.19. MI_RGN_PaletteTable_t¶

3.20. MI_RGN_Attr_t¶

3.21. MI_RGN_Bitmap_t¶

3.22. MI_RGN_ChnPort_t¶

3.23. MI_RGN_Point_t¶

3.24. MI_RGN_Rect_t¶

3.25. MI_RGN_Poly_t¶

3.26. MI_RGN_CoverColorAttr_t¶

3.27. MI_RGN_CoverMosaicAttr_t¶

3.28. MI_RGN_CoverChnPortParam_t¶

1. 概述¶