MI RGN API

---

REVISION HISTORY

Revision No.	Description	Date
3.0	Initial release	12/04/2020
	Added PROCFS introduction	08/25/2021
	Added chip information of Mochi	02/16/2022
	Added chip information of Maruko	03/21/2022
	Added chip information of Souffle	02/13/2023
	Refined procfs & Added error code description	11/10/2023
	Added chip information of Iford	11/13/2023
	Added chip information of Pcupid	04/17/2024
	Optimized the chapter structure	04/24/2025

---

1. OVERVIEW

1.1. Module Description

The region module is a part of an internal stream processing in some Pipeline modules. It is supported by hardware module named GOP (graphic output path) and MFF (Mosaic and Face Frame). And it is a set of software interface abstracted by hardware characteristics. OSD (on screen display), COVER and so on attaches to each channel in the way of using time sharing multiplexing.

The region module mainly provides the control and management functions of region resources. It includes the creation, destruction, acquisition and the setting of region attributes, acquisition and the setting of channel display attributes of the region, etc.

There are three kind of region attributions:

1. cover

   • cover has two modes.

     1. color mode, make a solid color occlusion of an area according to the settings, driver only needs to show the position, size, and color.
     2. Mosaic mode, mosaic an area according to the setting, driver only needs to show the position, size, and block size.

   • Cover can be divided into rectangles cover and polygons cover(Minimum 3 edges, maximum 6 edges, only convex polygons are supported) according to the area type, where the rectangle does not consume additional memory.

2. osd, also called ‘overlay’, which is same to 'cover'. It can be attached to the display video area worked by display buffer, so this kind of region can do a drew operation in point to point way, and the color format of ‘osd’ can support argb and bitmap. User can choose the color format according to the practical application scenarios.

3. frame, draw a rectangular frame on the specified area of the video as set. The underlying driver only needs to go down to the position, size, color, and width of the line of the rectangular box, without additional memory consumption.

Currently osd format supports ‘argb8888’, ‘argb1555’, ‘argb4444’, ‘rgb565’, ‘i2’, ‘i4’, ‘i8’. The format supporting conditions of each chip will be different. The following will be explained in detail. YUV format is not supported. I2, I4 and I8 are in bitmap format, and the memory data of a pixel is used as an index. Through the index, the color data in the color palette can be found, which the pixel displays is.

Through experiments, when region display has been set, dump the output of ‘scl’ module into a file, and you can see the content of region through the tool.

‘OSD’ can display a picture, ‘cover’ can only set different color, and ‘Osd’ always display above ‘cover’ when they are attached the same path.

note: Current chip(Pcupid) RGN only support attach rect cover to SCL.

Figure 1‑1: cover blending rendering

1.1.1 Keyword

• I2

  4 colors bitmap, 2 bits refer to an index, so that there are 4 colors. It can find the color by the index in palette.

• I4

  16 colors bitmap, 4 bits refer to an index and find the color by the index in palette.

• I8

  256 colors bitmap, 8 bits refer to an index and find the color by the index in palette.

• Palette

  The palette of bitmap, one color is represented by four 8bit variables: alpha, red, green and blue, there are totally 256 colors in palette with index range from 0 to 255.

• OSD

  Abbreviation of on-screen display, It is used to display some text, pictures, UI menus and other contents.

• GOP

  Abbreviation of graphic output path, it is a graphic layer above video.

• MFF

  Cover and Frame uniform name.

1.2. Basic Structure

Figure 1‑2: basic structure

1.3. Module Function

1. Support region management: Manage different region types such as OSD, COVER and FRAME.

2. Support multiple formats: OSD supports True Color and Indexed formats, COVER and FRAME support YUV format.

3. Support multi-channel processing: Can process of channels across different modules.

4. Support multiple graphic overlays: OSD, COVER and FRAME can be overlaid for display.

1.4. Application Scenario

Applications can be developed based on the API interface provided by MI_RGN on LINUX, RTOS and DUALOS.

1.4.1. OSD scenario and memory usage instructions

In order to ensure that the OSD can be output to the video stably, RGN allocates one or more buffers to each OSD according to the hardware/user usage to prevent writing to the buffer being used for hardware display, causing OSD flickering or tearing.

The following will increase the memory usage of RGN:

1. The update speed of the upper layer OSD(call MI_RGN_SetBitMap/MI_RGN_GetCanvasInfo/MI_RGN_UpdateCanvas) is accelerated;
2. The number of channels superimposed on an OSD has increased;
3. The number of OSDs superimposed on a channel at the same time exceeds the maximum hardware layers. For the maximum number of hardware layers supported by each chip, please see 'Table 1-4: Chip information of Tiramisu', 'Table 1-5: Chip information of Muffin', 'Table 1-6: Chip information of Mochi', 'Table 1-7: Chip information of Maruko', 'Table 1-8: Chip information of Opera', 'Table 1-9: Chip information of Souffle', 'Table 1-11: Chip information of Iford', 'Table 1-12: Chip information of Pcupid'.

The following table lists the buffer usage in common scenarios:

Table 1-1：OSD buffer use

Scenario Description	OSD	OSD refresh rate t/each time	Channel	buffer
1 OSD attached to 1 channel, only attached once without refreshing	1	NA	1	1
1 OSD attached to 1 channel, slow refresh	1	1s	1	2
1 OSD attached to 1 channel, fast refresh	1	30ms	1	3
1 OSD attached n channels, only attached once without refreshing	1	NA	n	1
1 OSD attached n channels, slow refresh	1	1s	n	2
1 OSD attached n channels, fast refresh	1	30ms	n	[3, 2n+1]
m OSDs attached to 1 channel, only attached once without refreshing	m <= L	NA	1	m
m OSDs attached to 1 channel, slow refresh	m <= L	1s	1	2m
m OSDs attached to 1 channel, fast refresh	m <= L	30ms	1	3m
m OSDs attached to n channels, only attached once without refreshing	m <= L	NA	n	m
m OSDs attached to n channels, slow refresh	m <= L	1s	n	2m
m OSDs attached to n channels, fast refresh	m <= L	30ms	n	[3m, m(2n+1)]
m OSDs attached to n channels, only attached once without refreshing	m > L	NA	n	L + n(m - L)
m OSDs attached to n channels, slow refresh	m > L	1s	n	2L + 2n(m - L)
m OSDs attached to n channels, fast refresh	m > L	30ms	n	[3L, L(2n+1)] + 3n(m–L)

Note:

• L represents the maximum number of hardware layers;
• For example, [3, 2n+1] represents a closed interval, and the number of buffers is a certain value in this interval (affected by system scheduling, it usually does not reach the maximum value).
• The above buffer usage only applies when the user does not limit the number of osd buffers, if the maximum number of OSD buffers is specified by MI_RGN_Create, the maximum number of OSD buffers is subject to the setting.

1.4.2. Cover scenario and memory usage instructions

COVER is divided into rectangular COVER and polygonal COVER according to the area type. The polygonal COVER in the current channel requires at least 1 buffer. Buffer length = (Screen width/8) (aligned 16 upwards) * Screen height, in bytes. Note: The screen width and height here is the resolution of the current channel.

The following table lists the buffer usage in common scenarios:

Table 1-2：COVER buffer use

Scenario Description	Channel	Minimum Buffer	Maximum Buffer
1 or multiple polygonal COVER attached to 1 channel, no refresh	1	1	1
1 or multiple polygonal COVER attached to 1 channel, slow refresh	1	2	2
1 or multiple polygonal COVER attached to 1 channel, fast refresh	1	2	3
1 or multiple polygonal COVER attached to n channels, no refresh	n	n	n
1 or multiple polygonal COVER attached to n channels, slow refresh	n	2n	2n
1 or multiple polygonal COVER attached to n channels, fast refresh	n	2n	3n

1.4.3. Color invert scenario and memory usage instructions

Color invert running in AUTO mode requires at least 1 buffer per channel. MANUAL mode requires at least 2 buffer per channel. Buffer size = (Screen width/Horizontal block size of color invert) (aligned 16 upwards) * (Screen height/Vertical block size of color invert), in bytes. Note: The screen width and height here is the resolution of the current channel.

The following table lists the buffer usage in common scenarios:

Table 1-3：Color invert buffer use

Scenario Description	Color Invert Mode	Minimum Buffer	Maximum Buffer
Color invert multiple frames in a channel	AUTO	1	1
Color invert multiple frames in a channel	MANUAL	3	5
Color invert multiple frames in m channels	AUTO	m	m
Color invert multiple frames in m channels	MANUAL	3m	5m

1.5. Chip Difference

The path in the table as below represent the SOC chip whether has GOP hardware module, which do not indicate the device id/ channel id/ port id. The user should find the actual path setting based on the actual situation of each module, and set driver by filling ‘MI_RGN_ChnPort_t* pstChnPort’.

• SCL corresponds to MI_SCL module, it usually bind hardware of SCL and software of device id / port id when initializing. For more information, please refer to MI SCL API document.
• DISP corresponds to MI_DISP module. The DISPx in the table is bound to the device id of the MI_DISP module, and only the device id can be set. Channel id and Port id need to be filled with 0(bInputPort invalid).

The differences among chips mainly lie in the following aspects: (1)Channel type, (2)Hardware layer count of OSD, (3)OSD color invert, (4)Frame count, (5)Cover countt, (6)Mosaic mode, (7)Polygonal Cover, (8)Color formats.

• Channel type: types of channels supported by the chip.

• Hardware layer count of OSD: the count of OSD supported by the channel.

• OSD color invert: whether the channel supports OSD color invert.

• Frame count: the count of Frame supported by the channel.

• Cover count: the count of Cover supported by the channel.

• Mosaic mode: whether the channel supports Mosaic mode.

• Polygonal Cover: whether the channel supports Polygonal Cover.

• Color formats: whether the channel supports the color format.

Note: Before reading the chip difference, please refer to the legend below.

Figure 1‑3: figure legend

1.5.1 Tiramisu

Figure 1‑4: Tiramisu chip related module structure diagram

• This chip RGN can only attach the OSD on SCL.
• Each device on the SCL has 6 output port(which id from 0 to 5), and each output port can exclusively occupy a SCL_GOP hardware.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.

Table 1-4: Chip information of Tiramisu

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	NA	NA	4	NA	NA	Y	NA

1.5.2 Muffin

Figure 1‑5: Muffin chip related module structure diagram

• The GOP_CUR0 of the chip is used to display the OSD for RGN, and the other is used to display the UI and cursor for the MI_FB module.
• Each device on the SCL has 9 output port(which id from 0 to 8), the output port(0-3) need to share the SCL_GOP0 hardware, the output port(4-8) need to share the SCL_GOP1 hardware.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 hardware, the device1 exclusively occupy the VENC_GOP1 hardware, the device8 exclusively occupy the JPE_GOP0 hardware, the device9 exclusively occupy the JPE_GOP1 hardware.

Table 1-5: Chip information of Muffin

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal 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.3 Mochi

Figure 1‑6: Mochi chip related module structure diagram

• The GOP_CUR0 of the chip is used to display the OSD for RGN, and the other is used to display the UI and cursor for the MI_FB module.
• Each device on the SCL has 7 output port(which id from 0 to 6), all the output port need to share the SCL_GOP hardware.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 hardware, the device8 exclusively occupy the JPE_GOP0 hardware, the device9 exclusively occupy the JPE_GOP1 hardware.

Table 1-6: Chip information of Mochi

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal 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 Maruko

Figure 1‑7: Maruko chip related module structure diagram

• Each device on the SCL has 4 output port(which id from 0 to 3), and all the output port need to share the GOP hardware with DISP (which means at the same time only SCL or DISP can use the hardware).
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 hardware, the device8 exclusively occupy the JPE_GOP0 hardware.

Table 1-7: Chip information of Maruko

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal 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.5 Opera

Figure 1‑8: Opera chip related module structure diagram

• Each device on the SCL has 4 output port(which id from 0 to 3), the output port(0-1) need to share SCL_GOP0 hardware, the output port(2-3) need to share the SCL_GOP1 hardware.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 hardware, the device8 exclusively occupy the JPE_GOP0 hardware.

Table 1-8: Chip information of Opera

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	8	Y	NA	4	NA	NA	Y	Y
VENC	8	Y	NA	NA	NA	NA	Y	NA
JPE	8	Y	NA	NA	NA	NA	Y	NA
DISP	1	NA	NA	NA	NA	NA	Y	NA

1.5.6 Souffle

Figure 1‑9: Souffle chip related module structure diagram

• Each device on the SCL has 7 output port(which id from 0 to 6) and 1 input port. SCL needs to share the GOP hardware with DISP (which means at the same time only SCL or DISP can use the hardware). SCL exclusively occupy the COVER/FRAME hardware.
• SCL input port and output port with the same id need to share access to a COVER hardware. Different id corresponds to different COVER hardware, COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 and the VENC_COVER/FRAME hardware, the device8 exclusively occupy the JPE_GOP0 and the JPE_COVER/FRAME hardware.
• The layer of different types of regions on the same channel are OSD, FRAME, and COVER(Contains color mode COVER and mosaic modeCOVER) from top to bottom.
• There can only be up to 16 colors each for COVER and FRAME in the same channel color mode, and the same color can be reused.
• SCL COVER and FRAME can only be attached to the same SCL at the same time.
• The rectangles COVER and the polygons COVER' Layer are calculated separately, rectangles COVER is above of polygons COVER.
• All polygonal COVER of the same channel must be the same mode, color mode COVER should be same color, mosaic mode Mosaic shouldbe same block size.

Table 1-9: Chip information of Souffle

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal 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

Table 1-10: The support situation of mosaic mode block size

Channel type	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.7 Iford

Figure 1‑10: Iford chip related module structure diagram

• The device0 on the DISP exclusively occupy the DISP_GOP0 hardware.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.
• The device0 on the VENC exclusively occupy the VENC_GOP0 and the VENC_FRAME hardware, the device8 exclusively occupy the JPE_GOP0 and the JPE_FRAME hardware.
• The layer of different types of regions on the VENC or JPE channel are OSD, FRAME from top to bottom.
• There can only be up to 16 colors each for COVER and FRAME in the same channel color mode, and the same color can be reused.
• The GOP hardware for implementing OSD in DISP and the hardware for displaying UI in MI_FB in this chip are the same, and onlyone of them can be used at the same time.

Table 1-11: Chip information of Iford

Channel type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	Polygonal 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.8. Pcupid

• This chip RGN can only attach the COVER on SCL.
• Each SCL output port corresponds to a COVER hardware. Different COVER hardware is independent of each other and can be used at the same time.

Table 1-12: Chip information of Pcupid

Path type	Hardware layer count of OSD	OSD color invert	Frame count	Cover count	Mosaic mode	poly Cover	ARGB1555/ARGB4444/I2/I4/I8	ARGB8888/RGB565
SCL_OUTPUT_PORT	NA	NA	NA	4	NA	NA	NA	NA

1.6. Principle

Different types of regions correspond to distinct hardware for management. MI_RGN use GOP to manage osd, use MFF to manage cover and frame.

1.7. Development Process

1. Enter alkaid project root directory, make menuconfig

   

2. Press Enter to enter the Sdk Config sub-option

   

3. Press Enter to enter the Interface Compile Config sub-option

   

4. Press Space bar to select the rgn module

   

5. Press Enter to enter the fb module, select the sub-option supported by the chip and recompile the project

   

   After compilation, mi_rgn.ko will generated in project/release, and release mi_rgn.h and mi_rgn_datatype.h to this directory at the same time. It will be packaged into images by default in pure Linux.

1.8. Example

RGN only support attach rect cover to SCL on the current chip(Pcupid).

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

int main()
{
    MI_SYS_Init(0);
    MI_S32 s32Result = 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;
    s32Result = MI_RGN_Init(0, &stPaletteTable);

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

    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.stColorAttr.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;
    }

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

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

    MI_SYS_Exit(0);
    return 0;
}

2. API LIST

API	Function
MI_RGN_Init	Initialization
MI_RGN_DeInit	De-initialization
MI_RGN_Create	Create region
MI_RGN_Destroy	Destroy region
MI_RGN_GetAttr	Get region attributes
MI_RGN_SetBitMap	Set bitmap region
MI_RGN_AttachToChn	Attach region to channel
MI_RGN_DetachFromChn	Detach region from channel
MI_RGN_SetDisplayAttr	Set display attributes of region
MI_RGN_GetDisplayAttr	Get display attributes of region
MI_RGN_GetCanvasInfo	Get canvas information of region
MI_RGN_UpdateCanvas	Update canvas information of region
MI_RGN_SetColorInvertAttr	Set color invert attributes of channel
MI_RGN_GetColorInvertAttr	Get color invert attributes of channel
MI_RGN_GetLuma	Get luminance information of channel
MI_RGN_InitDev	Initialize RGN device
MI_RGN_DeInitDev	De-initialize RGN device

2.1. MI_RGN_Init

• Function

  Initialization.

• Syntax

  MI_S32 MI_RGN_Init(MI_U16 u16SocId, MI_RGN_PaletteTable_t *pstPaletteTable);
  

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  pstPaletteTable	Pointer to the palette table	Input

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_BUSY: Failed. Device is initializad already. The reason for this error is that the parameters of multiple API calls are inconsistent in the branch that supports multiple processes.

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file

• Note

  • The palette table can only be done once during initialization and cannot be set again.

  • It is not used for RGB color format.

  • The index of ‘0’ in palette array is used for colorkey, which will not display anything.

  • MI_RGN_Init needs to be done before Init of any other modules that use RGN (such as SCL).

• Example

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

• Related APIs

  MI_RGN_DeInit

2.2. MI_RGN_DeInit

• Function

  De-initialization

• Syntax

  MI_S32 MI_RGN_DeInit(MI_U16 u16SocId);
  

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_BUSY: Failed

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file

• Note

  MI_RGN_Deinit needs to be done after Deinit of any other modules that use RGN (such as SCL).

• Example

  Refer to MI_RGN_Init

• Related APIs

  MI_RGN_Init

2.3. MI_RGN_Create

• Function

  Create region

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Must be an unused hHandle Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstRegion	Pointer to the attribute of region	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file

• Note

  • This handle is specified by the user and has the same meaning as the ID.
  • Repeated creation is not supported.
  • The attribute of region must be legal. Refer to MI_RGN_Attr_t
  • The pointer to attribute of region cannot be null.
  • When creating a Cover or Frame, it only needs to assign the region type. Other attributes, such as location, hierarchy, etc., are assigned when theMI_RGN_AttachToChn interface is called.
  • When creating a region, this only checks the basic parameters such as minimum width and height, maximum width and height. When this region is attached to the channel, more targeted parameters can be checked based on constraints of the supported type of channel module. Such as supported pixel formats, etc.
  • This interface allows you to set the maximum number of buffers used by each osd node and assign u16MaxCanvasNum in the structure MI_RGN_Attr_t.
  • If u16MaxCanvasNum is set to 1, it indicates that screen tearing is allowed and accepted, and no error messages will be printed.

• Example

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

• Related APIs

  MI_RGN_Destroy

  MI_RGN_GetAttr

2.4. MI_RGN_Destroy

• Function

  Destroy region

• Syntax

  MI_S32 MI_REG_Destroy (MI_U16 u16SocId, MI_RGN_HANDLE hHandle);
  

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  Region must have been created.

• Example

  Refer to MI_RGN_Create

• Related APIs

  MI_RGN_Create

2.5. MI_RGN_GetAttr

• Function

  Get the attribute of region.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstRegion	Pointer to the attribute of region.	Output

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • The pointer to the attribute of region cannot be null.

• Example

  Refer to MI_RGN_Create.

2.6. MI_RGN_SetBitMap

• Function

  Set the region bitmap, that is, fill the region with bitmap.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstBitmap	The pointer to the attribute of bitmap	Input

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_BUSY: Failed. The number of OSD buffer has reached the maximum value and all buffer were busy. Please call this API repeatedly until a buffer is free.
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • The size of the supported bitmap is inconsistent with the size of the region.
  • The bitmap is loaded from (0,0) of the region. When the bitmap is larger than the region, the image will be automatically cropped into region.
  • The pixel format of the bitmap must be the same as the pixel format of the region.
  • The pointer to the attribute of bitmap cannot be null.
  • Support multiple calls.
  • This interface is only valid for overlay.
  • After calling MI_RGN_GetCanvasInfo, calling this interface is invalid unless MI_RGN_UpdateCanvas is in effect.

• Example

  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

• Function

  Attach region to channel

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstChnPort	Pointer to channel port When region type is Cover and the output port is VPE, only port 0 and port 3 are valid.	Input
  pstChnAttr	Pointer to the attribute of channel port.	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • Pointer to channel port cannot be null.
  • Pointer to the attribute of channel port cannot be null.
  • If two or more OSD regions are attached to the same channel, the format of these OSD regions must be the same.
  • Not all channels have the ability to overlay regions.
  • ‘COVER’ can be worked by hardware layer. 'OSD' can be worked by software layer, which is implemented by software jigsaw.
  • The channel id does not have any limitation about 'OSD', 'FRAME' and 'COVER' attached on the channel.
  • The OSD and COVER is not supported when SCL used rotate function.
  • If the OSD attached on the channel is less than or equal to the number of hardware layers, all the hardware layers will be used, otherwise, the software jigsaw will be used.

• Example

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

• Related APIs

  MI_RGN_DetachFromChn

2.8. MI_RGN_DetachFromChn

• Function

  Detach region from channel

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstChnPort	The pointer to channel port	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • The pointer to channel port cannot be null.
  • Before the overlaid channel or modules (such as SCL) is destroyed, it needs to call this interface to detach from region channel or module.

• Example

  Refer to MI_RGN_AttachToChn.

• Related APIs

  MI_RGN_AttachToChn

2.9. MI_RGN_SetDisplayAttr

• Function

  Set the display attribute of region.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstChnPort	The pointer to channel port	Input
  pstChnPortAttr	The pointer to the parameter of channel port	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • It is recommended to obtain the attributes first and then set them.
  • The pointer to channel port cannot be null.
  • The pointer to the parameter of channel port cannot be null.
  • The region must overlay with channel first.
  • Static properties cannot be modified, dynamic properties can be modified. Refer to MI_RGN_ChnPortParam_t

• Example

  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.u32Color = 0xffff00;
  
  s32Result = MI_RGN_SetDisplayAttr(0, hHandle, &stChnPort, &stChnAttr);
  if (s32Result != MI_RGN_OK)
  {
      return s32Result;
  }
  

• Related APIs

  MI_RGN_GetDisplayAttr

2.10. MI_RGN_GetDisplayAttr

• Function

  Get the display attribute of region.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstChnPort	The pointer to channel port	Input
  pstChnPortAttr	The pointer to the parameter of channel port	Output

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • The pointer to channel port cannot be null.
  • The pointer to the parameter of channel port cannot be null.

• Example

  Refer to MI_RGN_SetDisplayAttr.

• Related APIs

  MI_RGN_SetDisplayAttr

2.11. MI_RGN_GetCanvasInfo

• Function

  Get the canvas information of region.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input
  pstCanvasInfo	Pointer to the canvas information of region	Output

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_BUSY: Failed. The maximum number of canvas buffers set in the MI_RGN_Create interface is small, and all canvas buffers are occupied by hardware. In order to avoid screen tearing, you can select to call this interface repeatedly and wait for hardware to abandon buffer. Or set u16MaxCanvasNum to a higher value when calling MI_RGN_Create.
  • MI_ERR_RGN_EXIST: Failed. OSD combined in this channel and other OSD have got canvas already.
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.

  • This interface is similar to MI_RGN_SetBitMap and is mainly used for overlay types to import bitmap data. This interface is relative to MI_RGN_SetBitMap, users can update directly to display the internal data of canvas, which can save one memory copy and one memory’s allocation.

  • This interface is used to obtain canvas information corresponding to a region. After getting the canvas address, the user can directly operate the canvas. For example: Fill bmp data directly into the canvas, then update the display canvas data by calling MI_RGN_UpdateCanvas.
  • This interface is mutually exclusive with MI_RGN_SetBitMap. If this interface is already in use, calling MI_RGN_SetBitMap does not take effect until MI_RGN_UpdateCanvas is called.
  • If the channel has OSD combined, MI_RGN only allows one OSD to get canvas until this OSD call MI_RGN_UpdateCanvas. Other OSD call MI_RGN_SetBitMap and MI_RGN_GetCanvas will return failed.

• Example

  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;
  }
  if (MI_RGN_GetCanvas(0, 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(0, hHandle) != MI_RGN_OK)
  {
      return s32Result;
  }
  

• Related APIs

  MI_RGN_UpdateCanvas

2.12. MI_RGN_UpdateCanvas

• Function

  Update canvas. If the canvas is attached to the path, it will display on video, otherwise it will display after attach.

• Syntax

  MI_S32 MI_RGN_UpdateCanvas(MI_U16 u16SocId, MI_RGN_HANDLE hHandle);
  

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  hHandle	Handle of region. Range: [0, MI_RGN_MAX_HANDLE).	Input

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_NOT_PERM: Failed, you must call this API after MI_RGN_GetCanvasInfo.
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Region must have been created.
  • This interface is used with MI_RGN_GetCanvasInfo. It is mainly used for canvas switching display after the canvas memory data is updated.
  • This interface must be called by pair with MI_RGN_GetCanvasInfo. It is used after user calls MI_RGN_GetCanvasInfo to get the pointer of canvas and the draw operation has done.
  • If the channel has OSD combined, only one OSD can be allowed to get the canvas at the same time. When two or more handle have attached to the same path, and all the handles use MI_RGN_GetCanvasInfo and this interface to draw, draw operation can work normally on the same thread; If it work on different thread, it must use ‘mutex’ lock to protect, or it may cause ‘osd’ disappearance.

  • The detail note of multithreading’s ‘mutex’ lock usage is as below:

    Suppose ‘handle0’ and ‘handle1’, which run on two threads, attach to the same path.

      handle0:
          T0_0 = getcanvas
          T0_1 = update
      handle1:
          T1_0 = getcanvas
          T1_1 = update
    

    The wrong situation below is running in order of time, which is showing error log ‘‘Front buf state error!!!’’.

    T0_0 -\> T1_0 -\> T0_1 -\> T1_1

    After using ‘mutex’, it will work fine:

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

• Example

  Refer to MI_RGN_GetCanvasInfo.

• Related APIs

  MI_RGN_GetCanvasInfo

2.13. MI_RGN_SetColorInvertAttr

• Function

  Set color invert attributes of channel.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  pstChnPort	The pointer to channel port	Input
  pstColorInvertAttr	The pointer to the attribute of color invert	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • The area of color invert is the entire channel, and the entire screen is divided into blocks based on a rectangle with a width of eBlkSizeHori and a height of eBlkSizeVert. Pixels that are less than the width or height of the color invert's blocks on the right and lower sides of the screen don't participate in color invert.
  • The area of color invert includes only the area of OSD.
  • Color invert has two work mode:
    • "AUTO" mode, the hardware determines whether the color needs to be inverted by comparing the luminance information calculated by block with the threshold set by user.
    • "MANUAL" mode, the user modifies the value of the block in buffer got through API MI_RGN_GetLuma and manually selects the block that need to be inverted.
  • User can control sensitivity in "AUTO" mode:
    • The block need color invert if the brightness of the current frame larger than (u8ThresholdHigh / 2).
    • The block don't need color invert if the brightness of the current frame less than (u8ThresholdLow / 2).
    • Otherwise, the color invert of the last frame is the same as the current frame.

  • In "MANUAL" mode, each byte represents a block in the luminance information of buffer:

    • bit [6:0] is obtained by shifting the average brightness of all pixels in the block to the left by one bit. bit [7] is the color invert result of this block, 1 means color invert, and 0 means no color invert.
    • Users can modify the value of the byte corresponding to the specified block after getting the luminance information of buffer. 0xff means color invert.

  • Souffle

    

    Figure 2-1: Souffle color invert related module structure diagram

    Path type	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

• Example

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

• Related APIs

  MI_RGN_GetColorInvertAttr

2.14. MI_RGN_GetColorInvertAttr

• Function

  Get color invert attributes of channel.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  pstChnPort	The pointer to channel port	Input
  pstColorInvertAttr	The pointer to the attribute of color invert	Output

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • The pointer to channel port can't be null.
  • The pointer to the attribute of color invert can't be null.

• Example

  Refer to MI_RGN_SetColorInvertAttr.

• Related APIs

  MI_RGN_SetColorInvertAttr

2.15. MI_RGN_GetLuma

• Function

  Get luminance information of channel.

• Syntax

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

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  pstChnPort	The pointer to channel port	Input
  pstLuma	Luminance information of the channel	Output

• Return Value

  • MI_RGN_OK: Successful
  • MI_ERR_RGN_NOBUF: Failed, this channel do not have luma buffer.
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file:

• Note

  • Color invert must be enable and work mode must be "MANUAL" mode. This API can be called repeatedly, and each call can get the latest luminance information of the current channel.
  • The pointer to channel port can't be null.
  • The luminance information of the channel can't be null.

• Example

  // 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;
  }
  

• Related APIs

  MI_RGN_SetColorInvertAttr

2.16. MI_RGN_InitDev

• Function

  Initialize RGN device

• Syntax

  MI_S32 MI_RGN_InitDev(MI_U16 u16SocId, MI_RGN_InitParam_t *pstInitParam);
  

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input
  pstInitParam	Initialization Parameter	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file

• Note

  Using this interface to replace the original MI_RGN_Init interface.

2.17. MI_RGN_DeInitDev

• Function

  De-initialize RGN device

• Syntax

  MI_S32 MI_RGN_DeInitDev(MI_U16 u16SocId);
  

• Parameters

  Parameter	Description	Input / Output
  s32SocId	Chip ID for multiple chips	Input

• Return Value

  • MI_RGN_OK: Successful
  • Not MI_RGN_OK: Failed. Please refer to Return Value

• Requirement

  • Header file: mi_sys.h, mi_rgn.h.
  • Library file

• Note

  Using this interface to replace the original MI_RGN_DeInit interface.

3. RGN DATA TYPE

The data types of video pre-processing and their data structures are defined as follows:

Data type	Definition
MI_RGN_MAX_HANDLE	The maximum number of handle of region.
MI_RGN_MAX_PALETTE_TABLE_NUM	The maximum number of palette table
MI_RGN_I2_PALETTE_INDEX_MAX	The maximum number of palette index when the pixel format is I2
MI_RGN_I4_PALETTE_INDEX_MAX	The maximum number of palette index when the pixel format is I4
MI_RGN_POLY_VERTEX_MIN	The minimum number of polygon vertex
MI_RGN_POLY_VERTEX_MAX	The maximum number of polygon vertex
MI_RGN_HANDLE	The definition for the handle of region
MI_RGN_Type_e	The enumeration of region type
MI_RGN_PixelFormat_e	The enumeration of Pixel format
MI_RGN_AlphaMode_e	The way to display with alpha mode
MI_RGN_BlockSize_e	Mosaic or color invert block size
MI_RGN_CoverMode_e	Cover mode
MI_RGN_AreaType_e	Area type
MI_RGN_ColorInvertWorkMode_e	The work mode of color invert
MI_RGN_Size_t	The structure of the region size
MI_RGN_OsdAlphaAttr_t	The structure of the attribute of OSD ‘alpha’.
MI_RGN_OsdInitParam_t	The structure of the attribute of OSD region
MI_RGN_PaletteElement_t	The structure of Palette element
MI_RGN_PaletteTable_t	The structure of Palette table
MI_RGN_Attr_t	The structure of region attribute
MI_RGN_Bitmap_t	The attribute of bitmap attribute
MI_RGN_ChnPort_t	The structure of channel port
MI_RGN_Point_t	The structure of coordinates
MI_RGN_Rect_t	The structure of rectangle
MI_RGN_Poly_t	The structure of polygon
MI_RGN_CoverColorAttr_t	The COVER attribute of the color mode
MI_RGN_CoverMosaicAttr_t	The COVER attribute of the mosaic mode
MI_RGN_CoverChnPortParam_t	The structure of the covered channel port
MI_RGN_FrameChnPortParam_t	The structure of the frame channel port
MI_RGN_OsdChnPortParam_t	The structure of the OSD channel port
MI_RGN_OsdArgb1555Alpha_t	Foreground and background Alpha settings of Argb1555 format
MI_RGN_AlphaModePara_u	The union of osd alpha mode parameters
MI_RGN_ChnPortParam_t	The structure of the attribute of channel port
MI_RGN_CanvasInfo_t	The structure of canvas information
MI_RGN_InitParam_t	Define the initialized parameter of RGN device
MI_RGN_ColorInvertAttr_t	The attribute of color invert
MI_RGN_LumaInfo_t	Luminance information

3.1. MI_RGN_MAX_HANDLE

• Description

  The definition for the maximum handle of region.

• Definition

  #define MI_RGN_MAX_HANDLE 1024
  

3.2. MI_RGN_MAX_PALETTE_TABLE_NUM

• Description

  The maximum number of palette table.

• Definition

  #define MI_RGN_MAX_PALETTE_TABLE_NUM 256
  

3.3. MI_RGN_I2_PALETTE_INDEX_MAX

• Description

  The maximum number of palette index when the pixel format is I2.

• Definition

  #define MI_RGN_I2_PALETTE_INDEX_MAX  63
  

3.4. MI_RGN_I4_PALETTE_INDEX_MAX

• Description

  The maximum number of palette index when the pixel format is I4.

• Definition

  #define MI_RGN_I4_PALETTE_INDEX_MAX  15
  

3.5. MI_RGN_POLY_VERTEX_MIN

• Description

  The minimum number of polygon vertex.

• Definition

  #define MI_RGN_POLY_VERTEX_MIN 3
  

3.6. MI_RGN_POLY_VERTEX_MAX

• Description

  The maximum number of polygon vertex.

• Definition

  #define MI_RGN_POLY_VERTEX_MAX 6
  

3.7. MI_RGN_HANDLE

• Description

  The definition for the handle of region.

• Definition

  typedef MI_U32 MI_RGN_HANDLE;
  

• Members

  Member	Description
  MI_RGN_HANDLE	The handle of region.

3.8. MI_RGN_Type_e

• Description

  The enumeration of region type

• Definition

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

• Members

  Member	Description
  E_MI_ REG_OSD	Video overlaid region
  E_MI_REG_COVER	Video covered region
  E_MI_RGN_FRAME	Video frame region

3.9. MI_RGN_PixelFormat_e

• Description

  The enumeration of Pixel format.

• Definition

  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;
  

• Members

  Member	Description
  E_MI_RGN_PIXEL_FORMAT_ARGB1555	ARGB1555 format
  E_MI_RGN_PIXEL_FORMAT_ARGB4444	ARGB4444 format
  E_MI_RGN_PIXEL_FORMAT_RGBI2	2 bit representation. Can support 4 colors. Check color by the palette table.
  E_MI_RGN_PIXEL_FORMAT_RGBI4	4 bit representation. Can support 16 colors. Check color by the palette table.
  E_MI_RGN_PIXEL_FORMAT_I8	8 bit representation. Can support 256 colors. Check color by the palette table.
  E_MI_RGN_PIXEL_FORMAT_RGB565	RGB565
  E_MI_RGN_PIXEL_FORMAT_ARGB8888	ARGB8888 format

• Note

  The image format supported by each chip is different. The APIs list all image formats, but some formats may not be supported by the API. If users need chip support, please refer to region procfs.

  Command: echo getmodcap [modeid] > /proc/mi_modules/mi_rgn/mi_rgn0

  Users cannot set the index 0 of the color palette. The index 0 of these formats is used as the color key by the underlying driver. That means this color is not recognized by hardware, so when all 0 data is covered on the channel, no color is displayed.

  The value of the Color key can be viewed in the getcap of procfs. The value of color key is a 16bit integer. Its high 8 bits and low 8 bits are the same value. When using the color format of the Index type, memset 0 on the memory data can make the hardware not recognized. When using the RGB or ARGB format, no matter what arrangement is used, the memset (color key & 0xFF) value can be used for the memory data.

3.10. MI_RGN_AlphaMode_e

• Description

  The way to display with alpha mode.

• Definition

  typedef enum
  {
      E_MI_RGN_PIXEL_ALPHA = 0,
      E_MI_RGN_CONSTANT_ALPHA,
  } MI_RGN_AlphaMode_e;
  

• Members

  Member	Description
  E_MI_RGN_PIXEL_ALPHA	OSD display every pixel with alpha value, which can support by these color formats ‘argb1555/argb4444/arbg8888/i2/i4/i8’. Rgb565 without alpha value does not make sense.
  E_MI_RGN_CONSTANT_ALPHA	The hardware ignores the alpha value (if exist) from the pixel format, In fact it use the specified alpha value to take the place of the original alpha value of each pixel.

3.11. MI_RGN_BlockSize_e

• Description

  Mosaic or color invert block size.

• Definition

  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;
  

• Members

  Member	Description
  E_MI_RGN_BLOCK_SIZE_4	Mosaic block size is 4x4 or color invert block size is 4.
  E_MI_RGN_BLOCK_SIZE_8	Mosaic block size is 8x8 or color invert block size is 8.
  E_MI_RGN_BLOCK_SIZE_16	Mosaic block size is 16x16 or color invert block size is 16.
  E_MI_RGN_BLOCK_SIZE_32	Mosaic block size is 32x32 or color invert block size is 32.
  E_MI_RGN_BLOCK_SIZE_64	Mosaic block size is 64x64 or color invert block size is 64.
  E_MI_RGN_BLOCK_SIZE_128	Mosaic block size is 128x128 or color invert block size is 128.
  E_MI_RGN_BLOCK_SIZE_256	Mosaic block size is 256x256 or color invert block size is 256.

3.12. MI_RGN_CoverMode_e

• Description

  Cover mode.

• Definition

  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;
  

• Members

  Member	Description
  E_MI_RGN_COVER_MODE_COLOR	Cover mode is color mode.
  E_MI_RGN_COVER_MODE_MOSAIC	Cover mode is mosaic mode.

3.13. MI_RGN_AreaType_e

• Description

  Area type.

• Definition

  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;
  

• Members

  Member	Description
  E_MI_RGN_AREA_TYPE_RECT	Area type is rectangle, which describes the location and size of the rectangle.
  E_MI_RGN_AREA_TYPE_POLY	Area type is polygon, which describes the vertex coordinates of the polygon.

3.14. MI_RGN_ColorInvertWorkMode_e

• Description

  The work mode of color invert.

• Definition

  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;
  

• Members

  Member	Description
  E_MI_RGN_COLOR_INVERT_WORK_MODE_AUTO	Color invert work mode is AUTO mode. According to the brightness threshold set by the user, the OSD of the block that meets the brightness condition is automatically processed.
  E_MI_RGN_COLOR_INVERT_WORK_MODE_MANUAL	Color invert work mode is MANUAL mode. Users can manually get luminance information of the screen, manually change the inverted color map, or update the OSD canvas.

3.15. MI_RGN_Size_t

• Description

  The structure of the region size

• Definition

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

• Members

  Member	Description
  u32Width	Width
  u32Height	Height

3.16. MI_RGN_OsdAlphaAttr_t

• Description

  The structure of the attribute of OSD ‘alpha’.

• Definition

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

• Members

  Member	Description
  eAlphaMode	The OSD alpha mode enum.
  stAlphaPara	The parameters of alpha mode.

3.17. MI_RGN_OsdInitParam_t

• Description

  The structure of the attribute of OSD region.

• Definition

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

• Members

  Member	Description
  ePixelFmt	Pixel format
  stSize	The width and height of region Range: Width: It is related to output port resolution(8pixel alignment).TBD Height: It is related to output port resolution (2pixel alignment).
  u16MaxCanvasNum	Maximum number of buffers used by each OSD node.

• Note

  • ePixelFmt, stSize are meaningful only after calling MI_RGN_AttachToChn.

  • ePixelFmt and stSize are static variables before calling MI_RGN_DetachFromChn

  • If the user does not assign a value to u16MaxCanvasNum when invoking the MI_RGN_Create interface, the value of u16MaxCanvasNum will be zero, indicating that the number of osd canvas is not limited by default. The actual value corresponds to the maximum value 0xffff.

3.18. MI_RGN_PaletteElement_t

• Description

  The structure of the palette element of region

• Definition

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

• Members

  Member	Description
  u8Alpha	Alpha
  u8Red	Red
  u8Green	Green
  u8Blue	Blue

3.19. MI_RGN_PaletteTable_t

• Description

  The structure of Palette table.

• Definition

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

• Members

  Member	Description
  astElement	Color element

3.20. MI_RGN_Attr_t

• Description

  The structure of region attribute.

• Definition

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

• Members

  Member	Description
  eType	Region type
  stOsdInitParam	Region attribute of OSD

3.21. MI_RGN_Bitmap_t

• Description

  The attribute of bitmap attribute.

• Definition

  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;
  

• Members

  Member	Description
  ePixelFormat	Pixel format
  stSize	Bitmap width, height and stride
  pData	The data of bitmap
  _Reserved	Reserved data added for compatibility with 32-bit and 64-bit environments, users can ignore this field

3.22. MI_RGN_ChnPort_t

• Description

  The structure of channel port

• Definition

  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;
  

• Members

  Member	Description
  eModId	Module ID
  s32DevId	Device ID
  s32ChnId	Channel ID
  s32PortId	Output port ID
  bInputPort	Whether the port ID is input port.

3.23. MI_RGN_Point_t

• Description

  The structure of coordinates.

• Definition

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

• Members

  Member	Description
  u32X	X-axis
  u32Y	Y-axis

3.24. MI_RGN_Rect_t

• Description

  The structure of rectangle.

• Definition

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

• Members

  Member	Description
  s32X	X-coordinate
  s32Y	Y-coordinate
  u32Width	width
  u32Height	height

3.25. MI_RGN_Poly_t

• Description

  The structure of polygon.

• Definition

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

• Members

  Member	Description
  u8VertexNum	The number of vertex
  astCoord	Vertex coordinates

3.26. MI_RGN_CoverColorAttr_t

• Description

  The COVER attribute of the color mode.

• Definition

  typedef struct MI_RGN_CoverColorAttr_s
  {
      MI_U32 u32Color;
  } MI_RGN_CoverColorAttr_t;
  

• Members

  Member	Description
  u32Color	Cover color value

• Note

  • u32Color means cover color value, bit[23:16] is V, bit[15:8] is Y, bit[7:0] is U.

3.27. MI_RGN_CoverMosaicAttr_t

• Description

  The COVER attribute of the mosaic mode.

• Definition

  typedef struct MI_RGN_CoverMosaicAttr_s
  {
      MI_RGN_BlockSize_e eBlkSize;
  } MI_RGN_CoverMosaicAttr_t;
  

• Members

  Member	Description
  eBlkSize	mosaic block size

3.28. MI_RGN_CoverChnPortParam_t

• Description

  The structure of the covered channel port.

• Definition

  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;
  

• Members

  Member	Description
  eAreaTyp	Area type
  stRect	The location and size of Rectangle cover, valid when area type is E_MI_RGN_AREA_TYPE_RECT
  stPoly	The vertex number and vertex coordinate of polygon cover, valid when area type is E_MI_RGN_AREA_TYPE_POLY
  eMode	Cover mode
  stColorAttr	Cover attribute of Color mode, valid when cover mode is E_MI_RGN_COVER_MODE_COLOR
  stMosaicAttr	Cover attribute of Mosaic mode, valid when cover mode is E_MI_RGN_COVER_MODE_MOSAIC

• Note

  • The size and coordinate of the cover are relative values based on the maximum value (8192).

    For example, if the size of target channel is 1920x1080, rectangle cover is required to set the location to [960x540], set the size to 960x540, and set the stRect to (1096, 4096, 4096, 4096).

3.29. MI_RGN_FrameChnPortParam_t

• Description

  The structure of the frame channel port.

• Definition

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

• Members

  Member	Description
  stRect	Location and size of Frame
  u32Color	Color, VYU444
  u8Thickness	Thickness of Frame

• Note

  • The size and coordinate of the frame are relative values based on the maximum value (8192).

    For example, if the size of target channel is 1920x1080, Frame is required to set the location to [960x540], set the size to 960x540,and set the stRect to (1096, 4096, 4096, 4096).

  • u32Color means color value of Cover, bit[23:16] is V, bit[15:8] is Y, bit[7:0] is U.

  • Thickness of Frame is absolute value in pixels.

3.30. MI_RGN_OsdChnPortParam_t

• Description

  The structure of the OSD channel port

• Definition

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

• Members

  Member	Description
  stPoint	The starting coordinate of the OSD channel port
  stOsdAlphaAttr	Osd Alpha attribute
  u8PaletteIdx	Palette index value, which defines the index of palette used by OSD relative to total palette set by rgn init

• Note

  • Function u8PaletteIdx is only valid at pixel format of I2 or I4. Currently only supported by Souffle.

  • How the actual index is calculated

    pixel format	formula
    I2	index = u8PaletteIdx * 4(I2's Total number of colors)
    I4	index = u8PaletteIdx * 16(I4's Total number of colors)
    other	Unsupport

  • MI_RGN defaults to using palette[0]'s color as display transparency, and when using the palette index function, the display of OSD transparency needs to rely on the user to change the color value corresponding to palette to the color of colorkey.

  • The palette index function of OSD participating puzzle is invalid.

3.31. MI_RGN_OsdArgb1555Alpha_t

• Description

  Argb1555 only has one bit to describe the alpha, which divide two settings, the foreground alpha with alpha bit equal ‘1’ and background alpha with alpha bit equal ‘0’.

• Definition

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

• Members

  Member	Description
  u8BgAlpha	The alpha value to display in background when alpha bit is 0. Value range: 0~0xFF.
  u8FgAlpha	The alpha value to display in foreground when alpha bit is 1. Value range: 0~0xFF.

3.32. MI_RGN_AlphaModePara_u

• Description

  The union of osd alpha mode parameters.

• Definition

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

• Members

  Member	Description
  stArgb1555Alpha	The setting of argb1555 format foreground and background alpha.
  u8ConstantAlpha	The setting in constant alpha case, and value range is from 0 to 0xFF.

3.33. MI_RGN_ChnPortParam_t

• Description

  The structure of the attribute of channel port.

• Definition

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

• Members

  Member	Description
  bShow	Whether the area is displayed. Range: MI_TRUE or MI_FALSE. Dynamic attribute.
  u32Layer	layer
  stCoverChnPort	The structure of the covered channel port
  stOsdChnPort	The structure of the OSD channel port
  stFrameChnPort	The structure of the frame channel port

3.34. MI_RGN_CanvasInfo_t

• Description

  The structure of canvas information

• Definition

  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;
  

• Members

  Member	Description
  phyAddr	The physical address of canvas
  virtAddr	The virtual address of canvas
  _Reserved	Reserved data added for compatibility with 32-bit and 64-bit environments, users can ignore this field
  stSize	The size of canvas
  u32Stride	The stride of canvas
  ePixelFmt	The pixel format of canvas

3.35. MI_RGN_InitParam_t

• Description

  RGN device initialization parameter.

• Definition

  typedef struct MI_RGN_InitParam_s
  {
      MI_RGN_PaletteTable_t *pstPaletteTable;
  } MI_RGN_InitParam_t;
  

• Members

  Member	Description
  pstPaletteTable	Color element pointer

• Relevant data types and interface

  MI_RGN_InitDev

3.36. MI_RGN_ColorInvertAttr_t

• Description

  The attribute of color invert.

• Definition

  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;
  

• Members

  Member	Description
  bEnable	Enale/disable color invert
  bApplyMap	Mask bit, user will to update color invert map if bApplyMap is TRUE.
  eWorkMode	Work mode
  u8ThresholdLow	Threshold low
  u8ThresholdHigh	Threshold high(Must greater than u8ThresholdLow)
  eBlkSizeHori	Horizontal block size
  eBlkSizeVert	Vertical block size

3.37. MI_RGN_LumaInfo_t

• Description

  Luminance information.

• Definition

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

• Members

  Member	Description
  phyAddr	The physical address
  virtAddr	The virtual address
  stSize	The size of luminance information
  u32Stride	buffer stride

4. RETURN VALUE

The return values of region module is shown in the following table.

Error Code	Marco definition	Description
0	MI_RGN_OK	Success.
0xA0030000	MI_NOTICE_RGN_BUFFER_CHANGE	Buffer changed. This happens when the attribute is set and needs to be remapped again
0xA0030001	MI_ERR_RGN_INVALID_HANDLE	Invalid handle.
0xA0030001	MI_ERR_RGN_INVALID_DEVID	Invalid Device ID.
0xA0030002	MI_ERR_RGN_INVALID_CHNID	Invalid channel ID or the handle
0xA0030003	MI_ERR_RGN_ILLEGAL_PARAM	Illegal parameters.
0xA0030004	MI_ERR_RGN_EXIST	Repeat creating the existing devices, channels, or resources.
0xA0030005	MI_ERR_RGN_UNEXIST	Trying to use or destroy a device, channel, or resource that does not exist.
0xA0030006	MI_ERR_RGN_NULL_PTR	Null pointer
0xA0030007	MI_ERR_RGN_NOT_CONFIG	Not configured
0xA0030008	MI_ERR_RGN_NOT_SUPPORT	Not supported
0xA0030009	MI_ERR_RGN_NOT_PERM	This operation is not allowed, such as trying to modify static configuration parameters.
0xA003000C	MI_ERR_RGN_NOMEM	Failed to allocate memory, such as insufficient system memory.
0xA003000D	MI_ERR_RGN_NOBUF	The allocation for cache failed, such as the requested data buffer is too large.
0xA003000E	MI_ERR_RGN_BUF_EMPTY	Buffer is empty.
0xA003000F	MI_ERR_RGN_BUF_FULL	Buffer is full.
0xA0030010	MI_ERR_RGN_NOTREADY	The system is not initialized or the corresponding module is not loaded.
0xA0030011	MI_ERR_RGN_BADADDR	Bad address
0xA0030012	MI_ERR_RGN_BUSY	System is busy.

5. PROCFS INTRODUCTION

Since RGN is usually attached to other modules, the following ModId refers to other modules attached by RGN, such as SCL.

5.1. cat

• Debug info

  cat  /proc/mi_modules/mi_rgn0
  

  

  

  

  

  

• Debug info analysis

  Record the current RGN usage status and device attributes, and can dynamically obtain information, which is convenient for debugging and testing.

• Parameter Description

  • Region capability

    • Region handle: The max regions to create are 1024, value range: [0~1023]
    • channel: The max channels are 64, value range: [0~63]
    • Osd attach: The max osds that can be bound to each channel of the output port are 128

    • Osd Support:

      • Width: Osd width value range: 1 ~ 4096
      • Height: Osd height value range: 1 ~ 4096
      • Color key value: Default colorkey value of the system, except for the index format

    • Mff(Cover/Mosaic/Frame) support:

      • Width: Mff width value range: 1 ~ 8192
      • Height: Mff height value range: 1 ~ 8192
      • Overlap: Mff supports overlap or not

  • Region attr:

    • Handle: Handle
    • Type: Osd, Cover or Frame
    • User: Osd only, canvas has been gotten or not
    • CvsCnt: Osd only, current buffer number of canvas
    • MaxCvs: Osd only, max buffer number of canvas
    • RefCnt: Osd only, canvas number for hardware direct display(OSD combined to the front buffer does not display directly through HW)
    • Width: Osd only, width
    • Height: Osd only, height
    • Stride: Osd only, line length
    • Format: Osd only, pixel format[0-6]: ARGB1555, ARGB4444, I2, I4, I8, RGB565, ARGB8888
    • PhyAddr: Osd only, canvas physical address
    • VirAddr: Osd only, canvas virtual address
    • UsingCnt: Osd only, the hardware number of the using canvas.

  • Operate count:

    • Handle: Handle
    • Type: Osd, Cover or Frame
    • AttachCnt: The count of calling API MI_RGN_AttachToChn
    • DetachCnt: The count of calling API MI_RGN_DetachFromChn
    • SetAttrCnt: The count of calling API MI_RGN_SetDisplayAttr
    • SetBitMap: The count of calling API MI_RGN_SetBitMap
    • GetCanvasCnt: The count of calling API MI_RGN_GetCanvasInfo
    • UpdateCanvasCnt: The count of calling API MI_RGN_UpdateCanvas

  • Channel Port Info:

    • ChnPort Info
      • ScreenWidth: The width of screen resolution
      • ScreenHeight: The height of screen resolution
      • EqOutRangeCnt: NA
      • RealtimeFlip: Osd realtime update mode flag
    • ColorInvert Info:
      • Enable: Color invert enable flag
      • WorkMode: Color invert work mode
      • BlkSzHori: The pixel number of color invert block in horizontal
      • BlkSzVert: The pixel number of color invert block in vertical
      • ThreshHigh: High threshold of color invert luminance
      • ThreshLow: Low threshold of color invert luminance
      • ReadPhyAddr: Read physical address of color invert
      • WritePhyAddr: Write physical address of color invert
      • StorageMode: Storage mode of color invert (By default)
      • eCalMode: Calculation mode of color invert luminance (By default)
    • Frontbuffer info:
      • Index: Frontbuffer index
      • bShow: Show flag
      • OffsetX: X position
      • OffsetY: Y position
      • Width: Width
      • Height: Height
      • Stride: Line length
      • Format: Pixel format
      • PhyAddr: Physical address
      • AlphaMode: Alpha mode, pixel alpha or constant alpha
      • AlphaVal: The alpha value when the alpha mode is constant alpha
      • BgAlpha: The background alpha value in ARGB1555 when the alpha mode is pixel alpha
      • FgAlpha: The front alpha value in ARGB1555 when the alpha mode is pixel alpha
      • paletteIdx: Palette index
      • BufCnt: The number of front buffer
      • OsdCnt: The number of OSD in front buffer
    • Region info:
      • Handle: handle
      • Type: Osd, Cover or Frame
      • bShow: Show flag
      • Layer: Layer
      • areaType: Area type, rectangle or polygon
      • PosX: X position
      • PosY: Y position
      • Width: Width
      • Height: Height
      • Color: The color RGB value of Cover or Frame
      • BlkSize: Mosaic block size
      • thickness: Frame border(Unit: pixel)
      • Format: Pixel format
      • AlphaMode: Alpha mode, pixel alpha or constant alpha
      • AlphaVal: The alpha value when the alpha mode is constant alpha
      • BgAlpha: The background alpha value in ARGB1555 when the alpha mode is pixel alpha
      • FgAlpha: The front alpha value in ARGB1555 when the alpha mode is pixel alpha
      • paletteIdx: Palette index
  • Buffer info:
    • kmalloc: Memory bytes allocated in the Region module
    • mma malloc: Memory bytes allocated in the Region module through sys module

---

5.2. dumpRgnBuf

• Function

  Dump buffer of specified region

• Command

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

• Parameter Description

  • [Handle]: region handle
  • [Path]: Path to save dump data. The saved content is the canvas of the region.

• Example

  echo dumpRgnBuf 0 /mnt >  /proc/mi_modules/mi_rgn/mi_rgn0
  

  Generate file Rgn0_canvasInfo_fmt0_64X48 in /mnt.

  It is the canvas data of the region that the dump handle is 0, the color format is ARGB1555, the stride is 64, and the height is 48.

  File format: Rgn[Handle]_canvasInfo_fmt[Format]_[Stride]X[Height]

  • [Handle]: region handle
  • [Format]: Color format, ARGB1555 is 0, ARGB4444 is 1, I2 is 2, I4 is 3.
  • [Stride]: Stride
  • [Height]: Height

---

5.3. dumpFrontBuf

• Function

  Dump frontbuffer of specified channel and port.

• Command

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

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.
  • [DevId]: Device id.
  • [ChnID]: Channel id [0~63].
  • [PortID]: Port id [0~3].
  • [bInputPort]: Whether the port type is an input port[0/1].
  • [Path]: Path to save dump data. 0~2 files will be generated according to the actual frontbuffers currently used.

• Example

  echo dumpFrontBuf 34 1 0 0 0 /mnt > /proc/mi_modules/mi_rgn/mi_rgn0
  

  Generate file Mod34_Dev1_Chn0_InPort0_frontbuf0_fmt0_64X48 in /mnt. It is the data of the frontbuffer that the dump module id is 34, the device id is 1, the channel id is 0, the port is input port 0 and the index is 0. The color format is ARGB1555, the stride is 64, and the height is 48.

  File format: Mod[ModId]_Dev[DevId]_Chn[Channel]_[In/Out]Port[Port]_frontbuf[Index]_fmt[Format]_[Stride]X[Height]

  • [ModId]: Output module id
  • [DevId]: Output device id
  • [Channel]: Channel id
  • [In/Out]: Port type
  • [Port]: Port id
  • [Index]: Frontbuffer index
  • [Format]: Color format, ARGB1555 is 0, ARGB4444 is 1, I2 is 2, I4 is 3.
  • [Stride]: Stride
  • [Height]: Height

---

5.4. getcap

• Function

  Get region capability info.

• Command

  echo getcap > /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.5. dumprgn

• Function

  Get created region info.

• Command

  echo dumprgn > /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.6. dumpchport

• Function

  Get channel and port info.

• Command

  echo dumpchport > /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.7. bufcnt

• Function

  Get memory usage info.

• Command

  echo bufcnt > /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.8. dumpPalette

• Function

  Get Palette info.

• Command

  echo dumpPalette > /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.9. setDispOnOff

• Function

  Turn on or off a gwin.

• Command

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

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.
  • [DevId]: Device id
  • [ChnID]: Channel id [0~63]
  • [PortID]: Port id [0~3]
  • [bInputPort]: Whether the port type is an input port[0/1].
  • [Idx]: The gwin number displayed by the osd on the current channel.
  • [OnOff]: 0: OFF, 1: ON

• Example

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

---

5.10. forceUpdate

• Function

  Force to update the back buffer of osd

• Command

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

• Parameter Description

  • [handle]: Osd handle

• Example

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

---

5.11. setRealtimeFlip

• Function

  Enable the real-time OSD display mode to ensure that the OSD is displayed in the next video frame.

• Command

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

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.
  • [DevId]: Device id
  • [ChnID]: Channel id [0~63]
  • [PortID]: Port id [0~3]
  • [bInputPort]: Whether the port type is an input port[0/1].
  • [OnOff]: RealtimeFlip enable state

• Example

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

---

5.13. setMaxCanvasForPath

• Function

  Limit the maximum buffer number of specified channel and port.

• Command

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

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.
  • [DevId]: Device id
  • [ChnID]: Channel id [0~63]
  • [PortID]: Port id [0~3]
  • [bInputPort]: Whether the port type is an input port[0/1].
  • [LimitNum]: The limited maximun buffer number

• Example

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

---

5.14. getmodcap

• Function

  Get other modules' ability to support RGN

• Command

  echo getmodcap [ModId] >  /proc/mi_modules/mi_rgn/mi_rgn0
  

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.

• Example

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

5.15. dumpOperateCnt

• Function

  Get the handle operation with count of references information

• Command

  echo dumpOperateCnt >  /proc/mi_modules/mi_rgn/mi_rgn0
  

---

5.16. setcolorkeymask

• Function

  Set the mask of the colorkey

• Command

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

• Parameter Description

  • [Mask]: colorkeymask value, Hexadecimal RGB

• Example

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

---

5.17. debugRgnWin

• Function

  Debug rgn channel port

• Command

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

• Parameter Description

  • [ModId]: Module ID, refer to the module in mi_common_datatype.h to define enumeration values.
  • [DevId]: Device id
  • [ChnID]: Channel id [0~63]
  • [PortID]: Port id [0~3]
  • [bInputPort]: Whether the port type is an input port[0/1].
  • [Mask]: Debug type mask
  • [bSetCnt]: Enable count or not [0 / 1]. 1: Enable count, the log printing will stop after printing [count] logs; 0: Disable count, the log will always be printed.
  • [Count]: Count.

• Example

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

---

5.18. maskOperate

• Function

  Set the operation of the mask

• Command

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

• Parameter Description

  • [Operate] rgn opertion, such as "attach", "detach", "bitmap", "setattr", "getcanvas", "updatecanvas"
  • [enable] mask enable, on/off

• Example

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