Using the Graphics Canvas

Introduction

The Graphics Canvas is a middleware in Microchip Graphics Suite (MGS) that enables users to easily leverage the HW features of the integrated display controllers in Microchip's graphics-enabled MCUs and MPUs. These features can be used to perform complex Graphical User Interface (GUI) effects without loading the CPU, including effects like sliding, fading, screen pre-rendering, and sprite animations.

The Graphics Canvas middleware provides abstracted, user-friendly APIs to utilize the display controller functions for these GUI effects.

Concept and Theory

This block diagram shows the various blocks in a GUI application that uses the MGS Graphics Canvas middleware.

The Graphics Canvas middleware includes the Graphics Canvas layer and the Graphics Canvas Task.

Graphics Canvas Layer

The Graphics Canvas layer sits between the display controller and the MGS library and application tasks. It contains the Canvas objects that are used to manage the frame buffers and how these frame buffers are displayed by the display controller. There can be as many Canvas objects as memory will allow.

A Canvas object is like a virtual display buffer that the MGS Graphics Library can use to render frames. The frame buffers in these Canvas objects can be used by the display controller as source for a displaying frames to an actual display.

Control and configuration of these Canvas objects are independent of the graphics library functions. The Graphics Canvas component also provides an application abstraction layer for the display controller functions. This allows the application to call a standard set of functions for configuring display controller functions like alpha blending, window position, window size, etc., regardless of the underlying display controller peripheral.

The availability of these functions depends on the features of the display controller. The Graphics Canvas APIs will be called by the application to configure how a Canvas object is displayed on the screen using the display controller functions. 

The Canvas Component also allows applications to read and write data to the frame buffers. This will allow applications to

1. Read graphics frame data over interfaces like USB, network, and UART, and display on a remote system. Useful for demonstration or debugging.
2. Write frame data from peripherals like USB, network, UART, and SD card to display frames from the camera, image sensors, video files, remote systems, etc.

Graphics Canvas Task and Effects

Other features that are provided by the Canvas component are effects such as fade in/out, window motion, sprite animation, etc. These effects will be used and depend on the display controller functions for hardware acceleration.

To support the Canvas effects, a Canvas task is needed to manage the execution of the effects using a timer.

The Graphics Canvas provides APIs that the application can call to start the effects. The application must register a callback function to be notified of the progress and completion of the effect.

Configuring an MCC Harmony Project with Graphics Canvas

This is what the MPLAB^® Code Configurator (MCC) Harmony project graph looks like for a typical MGS GUI application that uses the Graphics Canvas.

Compared to a typical MGS Graphics application, the Graphics Canvas is an additional MCC component that sits between the MGS Graphics Library and the Display Controller.

Configuring the Graphics Canvas Component

Adding and selecting the Graphics Canvas component in the MCC Harmony Project Graph will show the following options.

1. Canvas Setting - Configuration options for the canvas objects.
   • Enable Window Clipping - Uses the HW overlay to automatically clip regions of the frame buffer that is outside the screen.
   • Default Color Mode - The default color mode for the canvas objects, unless modified.
   • Default Number of Layers (read-only) - Shows the default number of layers.
   • Max Number of parameters (read-only) - Shows the maximum number of Canvas Objects.
   • Canvas Objects - Number of canvas objects.
     • Canvas Width - Width of the canvas, in pixels.
     • Canvas Height - Height of the canvas, in pixels.
     • Color Mode - Color mode of the canvas.
     • Frame Buffer Allocation - determines how the canvas frame buffer is allocated during initialization.
       • None - No allocations. The application can assign or allocate the buffer later.
       • Manual - Frame buffer is stored in a user-specified address.
       • Auto-Canvas will allocate the frame buffer as a statically declared array. Size is based on the canvas width, height, and color mode.
       • Dynamic - Canvas will dynamically allocate the frame buffer using malloc. Size is based on the canvas width, height, and color mode.
2. Effects Setting - Enables canvas effects
   • Effects Interval - Delay between effect updates. A short or long delay will make the effect run faster or slower, respectively.
   • Enable Fade Effects - Enables canvas fade in/out effects using the display controller HW overlay.
   • Enable Move Effects - Enables canvas move/sliding effects using the display controller HW overlay.
3. Display Driver Settings 
   • Display Driver (read-only) - Shows the name of the display controller driver.
4. Graphics Processor Driver Settings 
   • Use GPU to blit scratch buffer - Uses the GPU to copy scratch buffer to frame buffer memory. Enable only when a GPU is available on the target device.

Back to Top

Designing an MGS Harmony Composer project with Graphics Canvas

MGS Harmony Composer is used to design the frames that are rendered to each Graphics Canvas object.

An MGS Harmony Composer Layer is used to design the frame and the Layer index specifies to which Graphics Canvas object that frame will be rendered. So the UI design on Layer 0 is rendered to Canvas Object 0, Layer 1 to Canvas Object 1, and so on.

Back to Top

Use Cases and Example Projects

Graphics Canvas is an advanced feature that is best demonstrated through example projects. Check out the following example projects for more information on how a Canvas project is configured in MCC, how the MGS Harmony Composer design looks like, and how the various APIs are used.

Back to Top

Screen Sliding

The screen sliding project example shows how to horizontally slide a screen using Graphics Canvas effects. When run on a graphics-enabled MCU or MPU, this will utilize the display controller layers to perform the sliding without redrawing the frame.

Back to Top

Pre-rendered Layer-Screens

This example shows how to use multiple MGS Composer layers and canvas objects to create pre-rendered 'layer-screens'. GFX Canvas is used to transition between these layer-screens to simulate UI screen transitions. Since these layer-screens are completely rendered during initialization and are persistent throughout the lifecycle of the application, these screen transitions are very quick and requires very minimal processing.

Back to Top

APIs Documentation

This section contains the description of user-level APIs for MGS Graphics Canvas.

Back to Top