SEGGER emWin RA Port (rm_emwin_port)

SEGGER emWin port for RA MCUs.

Overview

The SEGGER emWin RA Port module provides the configuration and hardware acceleration support necessary for use of emWin on RA products. The port provides full integration with the graphics peripherals as well as FreeRTOS.

SEGGER emWin FSP Port Block Diagram (using RA6M3 as example)

Note

This port layer primarily enables hardware acceleration and background handling of many display operations and does not contain code intended to be directly called by the user. Please consult the SEGGER emWin User Guide (UM03001) for details on how to use emWin in your project.

Hardware Acceleration

The following functions are currently performed with hardware acceleration:

• DRW Engine (r_drw)
  • Drawing bitmaps (ARGB8888 and RGB565)
  • 4bpp font rendering
  • Rectangle fill
  • Line and shape drawing
  • Anti-aliased operations
    • Circle stroke and fill
    • Polygon stroke and fill
    • Lines and arcs
• JPEG Codec (r_jpeg)
  • JPEG decoding
• Graphics LCD Controller (r_glcdc)
  • Brightness, contrast and gamma correction
  • Pixel format conversion (framebuffer to LCD)

---

Configuration

Build Time Configurations for rm_emwin_port

The following build time configurations are defined in fsp_cfg/rm_emwin_port_cfg.h:

Configuration	Options	Default	Description
Memory Allocation
GUI Heap Size	Value must be a non-negative integer	32768	Set the size of the heap to be allocated for use exclusively by emWin.
Section for GUI Heap	Manual Entry	.noinit	Specify the section in which to allocate the GUI heap. When Arm Compiler 6 is used to place this memory in on-chip SRAM, the section name must be .bss or start with .bss. to avoid consuming unnecessary ROM space.
Maximum Layers	Value must be a non-negative integer	16	Set the maximum number of available display layers in emWin. This setting is not related to GLCDC Layer 1 or 2.
AA Font Conversion Buffer Size	Value must be a non-negative integer	400	Set the size of the conversion buffer for anti-aliased font glyphs. This should be set to the size (in bytes) of the largest AA character to be rendered.
LCD Settings
Wait for Vertical Sync	Enabled Disabled	Enabled	When enabled emWin will wait for a vertical sync event each time the display is updated. If an RTOS is used the thread will yield; otherwise each frame will block until Vsync. WARNING: Disabling vertical sync will result in tearing. It is recommended to always leave this setting Enabled if an RTOS is used.
JPEG Decoding
JPEG Decoding > General
Input Alignment	8-byte aligned (faster) Unaligned (slower)	8-byte aligned (faster)	Setting this option to 8-bit alignment can allow the hardware JPEG Codec to directly read JPEG data. This speeds up JPEG decoding operations and reduces RAM overhead, but all JPEG images must reside on an 8-byte boundary. When this option is enabled the input buffer is not allocated.
Double-Buffer Output	Enabled Disabled	Disabled	Enable this option to configure JPEG decoding operations to use a double-buffered output pipeline. This allows the JPEG to be rendered to the display at the same time as decoding at the cost of additional RAM usage. Enabling this option automatically allocates double the output buffer size.
Error Timeout	Value must be a non-negative integer	50	Set the timeout for JPEG decoding operations (in RTOS ticks) in the event of a decode error.
JPEG Decoding > Buffers
Input Buffer Size	Value must be a non-negative integer	0x1000	Set the size of the JPEG decode input buffer (in bytes). This buffer is used to ensure 8-byte alignment of input data. Specifying a size smaller than the size of the JPEG to decode will use additional interrupts to stream data in during the decoding process.
Output Buffer Size	Value must be a non-negative integer	0x3C00	Set the size of the JPEG decode output buffer (in bytes). An output buffer smaller than the size of a decoded image will use additional interrupts to stream the data into a framebuffer. Unless you are sure of the subsampling used in and the size of the input JPEG images it is recommended to allocate at least 16 framebuffer lines of memory.
Section for Buffers	Manual Entry	.noinit	Specify the section in which to allocate the JPEG work buffers. When Arm Compiler 6 is used to place this memory in on-chip SRAM, the section name must be .bss or start with .bss. to avoid consuming unnecessary ROM space.

Hardware Configuration

No clocks or pins are directly required by this module. Please consult the submodules' documentation for their requirements.

Library Configuration

emWin is provided as a pre-compiled library. To maximize compatibility the build-time options are configured as follows:

#define GUI_OS                (1) // Context switch support enabled
#define GUI_MAXTASK           (1) // One task supported by default (can be increased at runtime via GUITASK_SetMaxTask())
#define GUI_NUM_LAYERS        (3) // Up to three displays supported
#define GUI_SUPPORT_TOUCH     (1) // Support touch screens
#define GUI_SUPPORT_MOUSE     (1) // Support a mouse
#define GUI_SUPPORT_MEMDEV    (1) // Memory devices available
#define GUI_WINSUPPORT        (1) // Window manager available
#define GUI_SUPPORT_BIDI      (1) // Bidirectional text enabled
#define GUI_DEBUG_LEVEL       (2) // Parameter and consistency checks enabled (no logging)

All other options are left at the default settings in GUI_ConfDefaults.h.

---

Usage Notes

Getting Started

To get started with emWin in an RA project the following must be performed:

1. Open the RA Configuration editor for your project
2. Add emWin to your project in the Stacks view by clicking New Stack -> SEGGER -> SEGGER emWin
3. Ensure the configuration options for emWin are set as necessary for your application
4. Set the proporties for the GLCDC module to match the timing and memory requirements of your display panel
5. Set the JPEG decode color depth to the desired value (if applicable)
6. Ensure interrupts on all modules are enabled:
   • GLCDC Vertical Position (Vpos) Interrupt
   • DRW Interrupt (if applicable)
   • JPEG Encode/Decode and Data Transfer Interrupts (if applicable)
7. Confirm stack and heap are configured as needed
   • When starting development a minimum stack of 0x1000 (4K) and heap of 0x4000 (16K) are recommended until actual usage can be characterized
8. Click Generate Project Content to save and commit configuration changes

At this point the project is now ready to build with emWin. Please refer to the SEGGER emWin User Guide (UM03001) as well as demo and sample code for details on how to create a GUI application.

Using Hardware Acceleration

In most cases there is no need to perform additional configuration to ensure the DRW Engine is used. However, there are some guidelines that should be followed depending on the item in question:

• Bitmaps:
  • ARGB8888, RGB888 and RGB565 bitmaps require no additional settings.
• Anti-aliased shapes:
  • Anti-aliased lines, circles, polygons, polygon outlines and arcs are rendered with the DRW Engine.
• Anti-aliased (4bpp) fonts:
  • Set the text mode to GUI_TM_TRANS or create the relevant widget with WM_CF_HASTRANS set.
  • Ensure the "AA Font Conversion Buffer Size" configuration option is set to a size equal to or greater than the size (in bytes) of the largest glyph.
• 8bpp palletized images:
  • When creating these images ensure transparency is not enabled as the SEGGER method for this is not compatible with the DRW Engine.
• RLE-encoded images:
  • Hardware acceleration is not available for SEGGER's RLE format.
• JPEG images:
  • Align any user-declared JPEG data to an 8-byte boundary. If 8-byte alignment cannot be guaranteed disable the JPEG Decoding -> General -> Input Alignment option in the RA Configuration.

Multi-thread Support

When the "Multi-thread Support" configuration is enabled, emWin can be called from multiple threads. This comes with advantages and disadvantages:

Advantages:

• High flexibility in development of applications
• Threads can pend and post on emWin events

Disadvantages:

• Slightly higher RAM/ROM use
• Large GUI projects can become difficult to debug

Note

Multi-thread support is independent of RTOS support. RTOS support is managed internally and cannot be manually configured.

Limitations

Developers should be aware of the following limitations when using SEGGER emWin with FSP:

• Hardware acceleration is not available when using color modes lower than 16 bits.
• Hardware acceleration is not available for SEGGER's RLE image format.
• Rotated screen modes are not supported.
• Because emWin is provided as a pre-compiled library the build-time options are fixed. See the Library Configuration section for the supplied configuration.

  ---

Examples

Basic Example

This is a basic example demonstrating a very simple emWin application. The screen is cleared to white and "Hello World!" is printed in the center.

Note

emWin manages the GLCDC, DRW and JPEG Codec submodules internally; they do not need to be opened directly.

#include "DIALOG.h"

#define COLOR_WHITE       0x00FFFFFFU
#define COLOR_BLACK       0x00000000U

#define GUI_DRAW_DELAY    100

static void _cbMain (WM_MESSAGE * pMsg)
{
    GUI_RECT Rect;

    switch (pMsg->MsgId)
    {
        case WM_CREATE:
        {
            break;
        }

        case WM_PAINT:
        {
            /* Clear background to white */
            GUI_SetBkColor(COLOR_WHITE);
            GUI_Clear();

            /* Draw "Hello World!" in black in the center */
            WM_GetClientRect(&Rect);
            GUI_SetColor(COLOR_BLACK);
            GUI_DispStringInRect("Hello World!", &Rect, GUI_TA_VCENTER | GUI_TA_HCENTER);
            break;
        }

        default:
        {
            WM_DefaultProc(pMsg);
            break;
        }
    }
}

void emWinTask (void)
{
    int32_t xSize;
    int32_t ySize;

    /* Initialize emWin */
    GUI_Init();

    /* Get screen dimensions */
    xSize = LCD_GetXSize();
    ySize = LCD_GetYSize();

    /* Create main window */
    WM_CreateWindowAsChild(0, 0, xSize, ySize, WM_HBKWIN, WM_CF_SHOW, _cbMain, 0);

    /* Enter main drawing loop */
    while (1)
    {
        GUI_Delay(GUI_DRAW_DELAY);
    }
}

Note

For further example code please consult SEGGER emWin documentation, which can be downloaded here, as well as the Quick Start Guide and example project(s) provided with your Evaluation Kit (if applicable).