Azure RTOS GUIX Port (rm_guix_port)

Functions
UINT	rm_guix_port_hw_initialize (GX_DISPLAY *p_display)

Detailed Description

Overview

The Azure RTOS GUIX Port module provides the configuration and hardware acceleration support necessary for use of GUIX on RA products. The port provides full integration with the graphics peripherals (GLCDC, DRW and JPEG).

Azure RTOS GUIX Port Block Diagram

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. For information about how to use GUIX and GUIX Studio (including example code) please consult the Azure RTOS GUIX documentation.

Hardware Acceleration

The following functions are currently performed with hardware acceleration:

• DRW Engine (D/AVE 2D Port Interface (r_drw))
  • Drawing bitmaps
  • 8, 4 and 1bpp uncompressed and compressed (RLE) font rendering
  • 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 (r_glcdc)
  • Brightness, contrast and gamma correction
  • Pixel format conversion (framebuffer to LCD)

---

Configuration

Build Time Configurations for gx

The following build time configurations are defined in fsp_cfg/azure/gx/gx_user.h:

Configuration	Options	Default	Description
Hardware Acceleration
JPEG Codec Support	MCU Specific Options		Select whether or not to use the JPEG Codec for hardware acceleration.
DRW Engine Support	Enabled Disabled	Enabled	Select whether or not to use the DRW Engine for hardware acceleration.
Max DRW Operations	Value must be a positive integer	30	Specifies the maximum number of DRW operations before flushing the display list. Reducing this value may reduce the peak heap used by the application but may reduce performance.
Internal Thread
Stack Size	Value must be greater than zero	4096	GUIX internal thread stack size in bytes. Must be greater than zero.
Priority	Value must be between 0 to 31	30	Priority of the GUIX Internal Thread. The value must be between 0 to 31.
Time Slice	Value must be in range 0 to 0xFFFFFFFF	10	Time Slice value of the GUIX Internal Thread. The value must be between 0 (TX_NO_TIME_SLICE) to 0xFFFFFFFF.
System Timer (ms)	Value must be greater than or equal to 10	20	GUIX system timer period (GX_SYSTEM_TIMER_MS). This value will be internally converted to RTOS ticks and will be rounded down to the next smallest multiple of the RTOS tick period (1000 / TX_TIMER_TICKS_PER_SECOND).
Multithread Support	Disabled Enabled	Enabled	Must be enabled if GUIX functions are called from multiple threads. Set to Disabled when calling GUIX from only one thread to reduce system overhead.
UTF8 Support	Disabled Enabled	Enabled	Select whether to enable or disable support for UTF8 characters.
Event Queue Size	Value must be greater than zero	48	Maximum number of events in the GUIX event queue.
Enable GX_WIDGET User Data	Enabled Disabled	Disabled	Set to Enabled to to use the gx_widget_user_data member in the GX_WIDGET structure.

Build Time Configurations for rm_guix_port

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

Configuration	Options	Default	Description
DRW Buffer Cache	Enabled Disabled	Enabled	Enabling this option significantly improves DRW Engine performance. Set to Disabled only if Display underflow events are triggered under high graphics load.

Configurations for Graphics > Azure RTOS GUIX Port (rm_guix_port)

Configuration	Options	Default	Description
Display Rotation
Screen Orientation	None CW (90 degrees) FLIP (180 degrees) CCW (270 degrees)	None	Select the display orientation specified in the GUIX Studio project. The Canvas Buffer must be enabled when rotating 180 degrees (FLIP).
Use Canvas Buffer	Enabled Disabled	Disabled	When screen rotation is set to 180 degrees (FLIP), a canvas buffer must be used. The canvas buffer size will be the same as a frame buffer for the display module.
Canvas Buffer Memory Section	This property must be a valid section name	bss	Specify the memory section where the GUIX Canvas Buffer will be allocated.
JPEG Decoding
Work Buffer Size	Must be a positive integer greater than 0	0xC800	Specify the JPEG work buffer size in bytes. A larger buffer can reduce JPEG decode/draw times. The buffer will not be allocated if JPEG Codec support is disabled. 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.
Buffer Memory Section	This property must be a valid section name	bss	Specify the memory section where the JPEG Work Buffer will be allocated.
Name	Name must be a valid C symbol	g_rm_guix_port0	Module name.
Target Display Layer	Graphics Layer 1 Graphics Layer 2	Graphics Layer 1	Specify which graphics screen to inherit the buffer and display dimensions from.
Callback Function	Must be a valid C symbol	NULL	If a callback function is provided it will be called when Display events occur.

Hardware Configuration

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

---

Usage Notes

Getting Started

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

1. In e² studio, open the RA Configuration editor for your GUIX project
2. Select or create a thread
3. Add GUIX to your project in the Stacks view by clicking New Stack -> Azure RTOS -> GUIX
4. Ensure the configuration options for GUIX and the port layer are set as necessary for your application
5. Set the proporties for the GLCDC module to match the timing and memory requirements of your display panel
6. Set the input color format in the GLCDC module (Input -> Graphics Layer * -> General -> Color format) and the output color format in the JPEG Codec module if applicable (Decode -> Output color format) per your project specification
7. Click the BSP tab in the configuration editor and confirm the heap size in the Properties pane is sufficient (see Note below)
8. Click Generate Project Content to save and commit configuration changes
9. Drop the Quick Setup entry in Developer Assistance into the desired thread entry C file and update the items marked with TODO as necessary
10. Call the Quick Setup function from the thread entry function (or where desired)

At this point the project is now ready to build and run your GUIX Studio project. Please refer to the documentation for Azure RTOS GUIX and GUIX Studio for details on how to create and edit a GUI application.

Note

It is recommended to start with 8K-32K of heap to begin development. Actual heap use is typically far lower than this but must be characterized by the developer.

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:

• Avoid transparent pixelmaps in 8-bit display mode as they are rendered in software. In particular, ensure PNGs to be used in 8bpp GUIX Studio projects are saved without transparency data if no transparency is needed.
• The following items may require a large heap to draw successfully:
  • Polygons (more sides = more heap)
  • Filled arcs and ellipses (more framebuffer lines occupied = more heap)
  • gx_canvas_pixelmap_tile (more tiles = more heap)
• When using hardware acceleration, images used for tile fill of shapes must have dimensions that are a power of 2. This limitation does not apply to gx_canvas_pixelmap_tile as well as certain arc/ellipse fill functions as GUIX manually draws pixelmaps to fill these shapes (at the expense of heap space).

  ---

Examples

Basic Example

This is a basic example demonstrating how to get GUIX up and running given an existing GUIX Studio project. A template for this code is available in Developer Assistance for the GUIX Port module.

Note

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

GX_WINDOW_ROOT * p_window_root;

void guix_user_start (void)
{
    /* Initialize GUIX */
    gx_system_initialize();


    /* Configure GUIX Studio project main display and get a pointer to the root window */
    gx_studio_display_configure(MAIN_DISPLAY,
                                rm_guix_port_hw_initialize,
                                MAIN_DISPLAY_LANGUAGE_ENGLISH,
                                MAIN_DISPLAY_THEME,
                                &p_window_root);


    /* Set pointer to the first buffer generated by the configuration (rm_guix_port_canvas) */
    gx_canvas_memory_define(p_window_root->gx_window_root_canvas,
                            rm_guix_port_canvas,
                            p_window_root->gx_window_root_canvas->gx_canvas_memory_size);

    /* Create and show the root window in the GUIX Studio project */
    gx_studio_named_widget_create("root_widget_name", (GX_WIDGET *) p_window_root, GX_NULL);
    gx_widget_show(p_window_root);

    /* Start GUIX */
    gx_system_start();

    /* GUIX will continue to run in its own thread */
}

Data Structures
struct	rm_guix_port_callback_args_t

Enumerations
enum	rm_guix_port_device_t
enum	rm_guix_port_event_t

---

Data Structure Documentation

rm_guix_port_callback_args_t

struct rm_guix_port_callback_args_t

Callback arguments for the FSP GUIX Port

Data Fields
rm_guix_port_device_t	device	Device code.
rm_guix_port_event_t	event	Event code of the low level hardware.
uint32_t	error	Error code if RM_GUIX_PORT_EVENT_ERROR.

Enumeration Type Documentation

rm_guix_port_device_t

enum rm_guix_port_device_t

Low level device code for the GUIX

Enumerator
RM_GUIX_PORT_DEVICE_NONE	Non hardware.
RM_GUIX_PORT_DEVICE_DISPLAY	Display device.
RM_GUIX_PORT_DEVICE_DRW	2D Graphics Engine
RM_GUIX_PORT_DEVICE_JPEG	JPEG Codec.

rm_guix_port_event_t

enum rm_guix_port_event_t

Display event codes

Enumerator
RM_GUIX_PORT_EVENT_ERROR	Low level driver error occurs.
RM_GUIX_PORT_EVENT_DISPLAY_VSYNC	Display interface VSYNC.
RM_GUIX_PORT_EVENT_UNDERFLOW	Display interface underflow.

Function Documentation

rm_guix_port_hw_initialize()

UINT rm_guix_port_hw_initialize

(

GX_DISPLAY *

p_display

)

Callback function to be passed to gx_studio_display_configure in order to start hardware modules.

Example:

    /* Configure GUIX Studio project main display and get a pointer to the root window */
    gx_studio_display_configure(MAIN_DISPLAY,
                                rm_guix_port_hw_initialize,
                                MAIN_DISPLAY_LANGUAGE_ENGLISH,
                                MAIN_DISPLAY_THEME,
                                &p_window_root);

Note

This function should only be called by GUIX.

Return values

GX_SUCCESS	Device driver setup is successfully done.
GX_FAILURE	Device driver setup failed.