Pixel Processing Engine (PPE)

Supported ICs[ RTL8721Dx ][ RTL8721F ]

Overview

PPE (Pixel Processing Engine) is a lightweight 2D image processing engine that provides basic image processing capabilities. It is specifically designed for scenarios with strict resource and cost requirements, such as embedded systems.

PPE supports common pixel-level operations, including color conversion, scaling, alpha blending, and color keying. It can efficiently complete common 2D image processing tasks but does not possess complex 3D rendering capabilities.

Features

RTL8721Dx:

PPE has 3 input layers and 1 output layer. It offers the following features:

  • Alpha blending

  • Scaling

  • Window configuration

  • Color keying

  • Pixel conversion

  • Multiple input and output sources

Note

  • Alpha blending and scaling functions are parallel features and cannot be used simultaneously.

  • When using alpha blending or scaling, other feature characteristics can be used concurrently.

Alpha Blending

PPE supports up to 3-layer alpha blending.

../../_images/ppe_alpha_blending_dplus.jpg

The alpha blending calculation formula is as follows:

../../_images/ppe_alpha_blending_formula_dplus.png

Scaling

PPE uses a bilinear interpolation algorithm to achieve good scaling effects, with up to 16x magnification or reduction.

Note

  • When using scaling, variable pixel start positions are not supported.

  • Only the first layer supports scaling.

Window Configuration

PPE’s window configuration feature has the following characteristics:

  • Variable pixel start position: Control the position of the input window in the output window.

  • Variable window size: Configure the size of input and output windows.

  • Variable line width: Implement cropping for the input window and picture-in-picture functionality for the output window.

../../_images/ppe_window.jpg

Color Keying

When a pixel in the output window matches the set value, that pixel will output a value of 0.

Pixel Conversion

Input and output support multiple pixel formats, including ARGB8888, RGB888, RGB565, and various other common formats.

For all supported formats, refer to the PPE_PIXEL_FORMAT in the ameba_ppe.h file. In some formats like XRGB8888, X represents the inverted alpha value, meaning the X value will be inverted during actual calculations.

Multiple Input and Output Sources

The input address can be either internal pixel values set by PPE or memory.

The output address can be memory or QSPI. Through QSPI, the output can be directly displayed on an external screen.

Application Examples

RTL8721Dx:

The SDK provides functional examples to help developers understand and use PPE:

Raw Examples

  • Path: {SDK}\example\peripheral\raw\Display\PPE\{demo}

Here’s a brief description of the raw example functionalities:

Raw API

PPE Exported Types

enum PPE_PIXEL_SOURCE

PPE Pixel Source Definition.

Values:

/* Pixel data from constant color register. */
PPE_LAYER_SRC_CONST

/* Pixel data read from memory via DMA. */
PPE_LAYER_SRC_FROM_DMA
RTL8721Dx:
enum PPE_GLOBAL_STATE

PPE Global State Definition.

Values:

/* PPE is disabled. */
PPE_STATE_DISABLE = 0

/* PPE is running. */
PPE_STATE_RUNNING = 1
struct PPE_InputLayer_InitTypeDef

PPE Input layer Init Structure Definition.

Public Members

u32 src_addr

Source address of the layer pixel data.

u32 start_x

X coordinate of the top-left pixel in the result window.

u32 start_y

Y coordinate of the top-left pixel in the result window.

u32 width

Width of the input layer in pixels.

u32 height

Height of the input layer in pixels.

u32 const_ABGR8888_value

Constant pixel color in ABGR8888 format, used when src is PPE_LAYER_SRC_CONST.

u32 key_color_value

Transparent (chroma-key) color value.

u32 line_len

Number of bytes between two vertically adjacent pixels in memory (line stride).

PPE_PIXEL_FORMAT format

Pixel format of the input layer; see PPE_PIXEL_FORMAT.

PPE_PIXEL_SOURCE src

Pixel data source; see PPE_PIXEL_SOURCE.

int color_key_en

Color keying enable: 1 to enable, 0 to disable.

struct PPE_LLI_GLB

PPE Global register Format Definition.

Public Members

u32 LL_CFG

Linked list configuration register value.

u32 LLP

Linked list pointer register value.

u32 SCA_RATIO_X

Horizontal scale ratio register value.

u32 SCA_RATIO_Y

Vertical scale ratio register value.

enum PPE_PIXEL_FORMAT

PPE Pixel Format Definition.

Values:

/* 32bpp ABGR 8-8-8-8 format. */
PPE_ABGR8888 = 0x0

/* 32bpp ARGB 8-8-8-8 format. */
PPE_ARGB8888

/* 32bpp XBGR 8-8-8-8 format. */
PPE_XBGR8888

/* 32bpp XRGB 8-8-8-8 format. */
PPE_XRGB8888

/* 32bpp BGRA 8-8-8-8 format. */
PPE_BGRA8888

/* 32bpp RGBA 8-8-8-8 format. */
PPE_RGBA8888

/* 32bpp BGRX 8-8-8-8 format. */
PPE_BGRX8888

/* 32bpp RGBX 8-8-8-8 format. */
PPE_RGBX8888

/* 16bpp ABGR 4-4-4-4 format. */
PPE_ABGR4444

/* 16bpp ARGB 4-4-4-4 format. */
PPE_ARGB4444

/* 16bpp XBGR 4-4-4-4 format. */
PPE_XBGR4444

/* 16bpp XRGB 4-4-4-4 format. */
PPE_XRGB4444

/* 16bpp BGRA 4-4-4-4 format. */
PPE_BGRA4444

/* 16bpp RGBA 4-4-4-4 format. */
PPE_RGBA4444

/* 16bpp BGRX 4-4-4-4 format. */
PPE_BGRX4444

/* 16bpp RGBX 4-4-4-4 format. */
PPE_RGBX4444

/* 8bpp ABGR 2-2-2-2 format. (= 0x10) */
PPE_ABGR2222

/* 8bpp ARGB 2-2-2-2 format. */
PPE_ARGB2222

/* 8bpp XBGR 2-2-2-2 format. */
PPE_XBGR2222

/* 8bpp XRGB 2-2-2-2 format. */
PPE_XRGB2222

/* 8bpp BGRA 2-2-2-2 format. */
PPE_BGRA2222

/* 8bpp RGBA 2-2-2-2 format. */
PPE_RGBA2222

/* 8bpp BGRX 2-2-2-2 format. */
PPE_BGRX2222

/* 8bpp RGBX 2-2-2-2 format. */
PPE_RGBX2222

/* 24bpp ABGR 8-5-6-5 format. */
PPE_ABGR8565

/* 24bpp ARGB 8-5-6-5 format. */
PPE_ARGB8565

/* 24bpp XBGR 8-5-6-5 format. */
PPE_XBGR8565

/* 24bpp XRGB 8-5-6-5 format. */
PPE_XRGB8565

/* 24bpp BGRA 5-6-5-8 format. */
PPE_BGRA5658

/* 24bpp RGBA 5-6-5-8 format. */
PPE_RGBA5658

/* 24bpp BGRX 5-6-5-8 format. */
PPE_BGRX5658

/* 24bpp RGBX 5-6-5-8 format. */
PPE_RGBX5658

/* 16bpp ABGR 1-5-5-5 format. (= 0x20) */
PPE_ABGR1555

/* 16bpp ARGB 1-5-5-5 format. */
PPE_ARGB1555

/* 16bpp XBGR 1-5-5-5 format. */
PPE_XBGR1555

/* 16bpp XRGB 1-5-5-5 format. */
PPE_XRGB1555

/* 16bpp BGRA 5-5-5-1 format. */
PPE_BGRA5551

/* 16bpp RGBA 5-5-5-1 format. */
PPE_RGBA5551

/* 16bpp BGRX 5-5-5-1 format. */
PPE_BGRX5551

/* 16bpp RGBX 5-5-5-1 format. */
PPE_RGBX5551

/* 24bpp BGR 8-8-8 format. */
PPE_BGR888

/* 24bpp RGB 8-8-8 format. */
PPE_RGB888

/* 16bpp BGR 5-6-5 format. */
PPE_BGR565

/* 16bpp RGB 5-6-5 format. */
PPE_RGB565

/* 8bpp alpha-only format. */
PPE_A8

/* 8bpp ignored-alpha format. */
PPE_X8

/* 32bpp ABGR 8-6-6-6 format. */
PPE_ABGR8666 = 0x32

/* 32bpp ARGB 8-6-6-6 format. */
PPE_ARGB8666

/* 32bpp XBGR 8-6-6-6 format. */
PPE_XBGR8666

/* 32bpp XRGB 8-6-6-6 format. */
PPE_XRGB8666

/* 32bpp BGRA 6-6-6-8 format. */
PPE_BGRA6668

/* 32bpp RGBA 6-6-6-8 format. */
PPE_RGBA6668

/* 32bpp BGRX 6-6-6-8 format. */
PPE_BGRX6668

/* 32bpp RGBX 6-6-6-8 format. */
PPE_RGBX6668
struct PPE_ResultLayer_InitTypeDef

PPE Result layer Init Structure Definition.

Public Members

u32 src_addr

Destination address for the composited output.

u32 width

Width of the output image in pixels.

u32 height

Height of the output image in pixels.

u32 line_len

Number of bytes between two vertically adjacent pixels in memory (line stride).

PPE_PIXEL_FORMAT format

Pixel format of the output layer; see PPE_PIXEL_FORMAT.

PPE_ADDR_TYPE type

Address type of the output buffer; see PPE_ADDR_TYPE.

enum PPE_ADDR_TYPE

PPE Result Layer Address Type.

Values:

/* Address in internal memory. */
PPE_ADDR_MEM

/* Address in QSPI flash. */
PPE_ADDR_QSPI
enum PPE_ARBURST

PPE Arburst Definition.

Values:

/* AXI FIXED burst type. */
PPE_ARBURST_FIX

/* AXI INCR burst type. */
PPE_ARBURST_INCR
enum PPE_DMA_HANDSHAKE

PPE DMA Handshake Definition.

Values:

/* Hardware DMA handshake mode. */
PPE_DMA_HW_HANDSHAKE

/* Software DMA handshake mode. */
PPE_DMA_SW_HANDSHAKE
struct PPE_InitTypeDef

PPE Function Structure Definition.

Public Members

u32 function

PPE function mode selection; see PPE_FUNCTION_ALPHA_BLEND and PPE_FUNCTION_SCALE.

u32 blend_layer_num

Number of input layers used for alpha blending.

struct PPE_LLI_LAYER

PPE LLI Layer Format Definition.

Public Members

u32 LAYER_ADDR

Address of the first pixel.

u32 LAYER_POS

Position of the first pixel in the result window.

u32 LAYER_WINSIZE

Window size: height[31:16] and width[15:0] in pixels.

u32 LAYER_CONST_PIX

Constant pixel value in ABGR8888 format.

PPE Exported Constants

/* Check if PPE channel index is valid (0-16). */
#define IS_PPE_CHN_INDEX (((chn) < 17) && ((chn) >= 0))

/* Check if PPE alpha blend layer count is valid (< 16). */
#define IS_PPE_ALPHA_BLEND_LAYER_NUM ((layer_num) < 16)

/* Index of the PPE result (output) layer. */
#define PPE_RESULT_LAYER_INDEX 0

/* Index of PPE input layer 1. */
#define PPE_INPUT_LAYER1_INDEX 1

/* Index of PPE input layer 2. */
#define PPE_INPUT_LAYER2_INDEX 2

/* Index of PPE input layer 3. */
#define PPE_INPUT_LAYER3_INDEX 3

/* Bit mask for PPE result layer selection. */
#define PPE_RESULT_LAYER_BIT ((u32)0x1 << PPE_RESULT_LAYER_INDEX)

/* Bit mask for PPE input layer 1 selection. */
#define PPE_INPUT_LAYER1_BIT ((u32)0x1 << PPE_INPUT_LAYER1_INDEX)

/* Bit mask for PPE input layer 2 selection. */
#define PPE_INPUT_LAYER2_BIT ((u32)0x1 << PPE_INPUT_LAYER2_INDEX)

/* Bit mask for PPE input layer 3 selection. */
#define PPE_INPUT_LAYER3_BIT ((u32)0x1 << PPE_INPUT_LAYER3_INDEX)
RTL8721Dx: 
/* PPE function mode: alpha blending. */
#define PPE_FUNCTION_ALPHA_BLEND ((u32)0x0)

/* PPE function mode: scaling. */
#define PPE_FUNCTION_SCALE ((u32)0x1)

/* Check if PPE function selection is valid. */
#define IS_PPE_FUNCTION (((func) == PPE_FUNCTION_ALPHA_BLEND) || ((func) == PPE_FUNCTION_SCALE))

PPE Exported Functions

void PPE_AutoClearCmd(int NewState)

Enable or disable auto clear after loading.

Parameters:

  • NewState – The new state. This parameter can be: ENABLE or DISABLE.

void PPE_AutoReloadClrLayerAll(void)

Clear all auto reload layers.

void PPE_AutoReloadSetLayer(u32 layers)

Configure auto reload layers.

Parameters:

  • layers –

    Auto reload layers. This parameter can be one or combinations of the following values:

    • PPE_RESULT_LAYER_BIT: result layer.

    • PPE_INPUT_LAYER1_BIT: input layer1.

    • PPE_INPUT_LAYER2_BIT: input layer2.

    • PPE_INPUT_LAYER3_BIT: input layer3.

int PPE_ChannelInactiveCheck(u8 chn_id)

Check if a layer is inactive.

Parameters:

  • chn_id – The layer number to be checked.

Returns:

Layer inactive status:

  • 0: the layer is active

  • 1: the layer is inactive

void PPE_ClearINTPendingBit(u32 PPE_INT)

Clear specific interrupt status.

Parameters:

  • PPE_INT – Specifies the PPE interrupt type. This parameter can be one or combinations of PPE_INTR_ST.

void PPE_Cmd(int state)

Enable or disable PPE.

Parameters:

  • state – The state of PPE. This parameter can be ENABLE or DISABLE.

Note

DISABLE may have no effect on some platforms.

u32 PPE_GetAllIntStatus(void)

Get all interrupt status.

Returns:

Current PPE interrupt status.

u32 PPE_GetGlobalState(void)

Get PPE global state.

Returns:

One of PPE_GLOBAL_STATE.

u32 PPE_GetValid(void)

Get the setting valid value for polling.

Returns:

Set valid bit status:

  • 0: User can call PPE_SetValid() to tell PPE the settings are valid

  • 1: Settings valid bit is set

void PPE_InitInputLayer(u8 id, PPE_InputLayer_InitTypeDef *layer_init_struct)

Initialize specific input layer.

Parameters:

  • id – Input layer number. Can be PPE_INPUT_LAYER1_INDEX or PPE_INPUT_LAYER2_INDEX or PPE_INPUT_LAYER3_INDEX.

  • layer_init_struct – Pointer to a PPE_InputLayer_InitTypeDef structure that contains the configuration information for the specified input layer.

void PPE_InitResultLayer(PPE_ResultLayer_InitTypeDef *layer_init_struct)

Initialize result layer.

Parameters:

  • layer_init_struct – Pointer to a PPE_ResultLayer_InitTypeDef structure that contains the configuration information for the result layer.

void PPE_InputLayer_StructInit(PPE_InputLayer_InitTypeDef *layer_init_struct)

Fill each layer_init_struct member with its default value.

Parameters:
void PPE_LLSetLayer(u32 layers)

Set layers used by the first linked list item.

Parameters:

  • layers –

    Linked list layers. This parameter can be one or combinations of the following values:

    • PPE_RESULT_LAYER_BIT: result layer.

    • PPE_INPUT_LAYER1_BIT: input layer1.

    • PPE_INPUT_LAYER2_BIT: input layer2.

    • PPE_INPUT_LAYER3_BIT: input layer3.

void PPE_MaskAllInt(void)

Mask all interrupt.

void PPE_MaskINTConfig(u32 PPE_INT_MSK, int NewState)

Enable or disable the specified interrupt.

Parameters:

  • PPE_INT_MSK – Specifies the PPE interrupt type. This parameter can be one or combinations of PPE_INTR_ST.

  • NewState – The new state. This parameter can be: ENABLE or DISABLE.

void PPE_ResultLayer_StructInit(PPE_ResultLayer_InitTypeDef *layer_init_struct)

Fill each layer_init_struct member with its default value.

Parameters:
void PPE_Resume(void)

Resume PPE from suspend state.

void PPE_SetLLP(u32 lli)

Set the LLP value to the pointer of the first linked list item.

Parameters:

  • lli – Pointer to the first linked list item. Must align to 4 bytes.

void PPE_SetLine(u32 line)

Set line index for line over interrupt.

Parameters:

  • line – The line index.

void PPE_SetValid(void)

Tell PPE the settings are valid for the auto reload function.

void PPE_Suspend(void)

Suspend PPE.

RTL8721Dx:
void PPE_Abort(void)

Abort PPE.

void PPE_Init(PPE_InitTypeDef *PPE_init_struct)

Initialize the PPE peripheral according to the specified parameters in the PPE_init_struct.

Parameters:

  • PPE_init_struct – Pointer to a PPE_InitTypeDef structure that contains the configuration information for the specified PPE peripheral.

void PPE_SetScaleRation(float scale_x, float scale_y)

Set the scale ratio.

Parameters:

  • scale_x – Scale ratio in the X direction. No smaller than 1/16.

  • scale_y – Scale ratio in the Y direction. No smaller than 1/16.

void PPE_StructInit(PPE_InitTypeDef *PPE_init_struct)

Fill each PPE_init_struct member with its default value.

Parameters:

  • PPE_init_struct – Pointer to a PPE_InitTypeDef structure which will be initialized.