Screen Sliding Using Graphics Canvas

Last modified by Microchip on 2024/04/15 09:42


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

Microchip Graphics Suite (MGS) Example Project

Refer to the project in GitHub for the example.

MGS Harmony Web Simulator Output

Here's how the application runs:

  • The project boots, showing the left half of the frame with the Microchip and MGS Harmony logos.
  • Pressing the <<<< button will slide the frame to the left to show the right half of the screen, with the Quickstart button.
  • Pressing the >>>> button will slide the frame to the right to return to the original screen.

Try these here in the Canvas Sliding Example Simulator Output.

Canvas Sliding Example Simulator Output

Back to Top

MPLAB® Code Configurator (MCC) Harmony Configuration

Here's how the project is configured in MPLAB® Code Configurator (MCC) Harmony.

MCC Harmony Project Graph

Figure 1

The Graphics Canvas component is added to the project and connected between the MGS GFX library (Legato) and the MGS Harmony Web Simulator components.

Note that this project graph is for a simulator-based project. Projects that would run on actual HW would have the simulator replaced with the display driver and peripheral library components for the target device.

The Graphics Canvas component is configured as shown in Figure 2.

Graphics Canvas Component Configuration

Figure 2

  1. Default Color Mode is set to RGB565. This matches the color mode for the simulator and the MGS Harmony Composer project.
  2. Only one Canvas Object is used.
    • Width and Height are configured so that it is twice (960x272) as wide as the display or screen resolution (480x272). 
    • Color mode is set to RGB565.
    • Frame Buffer Allocation is set to Auto. This will statically allocate the frame buffer in RAM.

The rest of the settings are kept at their default values.

Back to Top

MGS Harmony Composer Design

The MGS Harmony Composer project was created with the display settings set to WQVGA, width and height are set to 480x272, and renderer color mode set to RGB565.

Display Size Settings

Figure 3

Renderer Color Mode settings

Figure 4

Figure 5 demonstrates what the UI design looks like in MGS Harmony Composer.

MGS Composer Design

Figure 5

  1. Only one layer is used in the Screen Tree. This matches the number of Canvas Objects (1) configured in the MCC Harmony Project Graph.
  2. The screen is designed so that Layer_0 and the Background Panel are twice as wide as the display.
  3. The On Show and On Update screen event callbacks are enabled. These will be used to initialize and manage the canvas objects at run-time.

To support the wide layer, the Layer_0 properties are configured so that the size is 960 pixels. Unchecking Locked To Screen allows a user-specified value for Size.

Layer_0 properties

Figure 6

Next, the assets were imported to the project and the widgets were added to Layer_0 and configured according to the UI design.

The button pressed event callback for the slide left (<<<<) and right (>>>>) button widgets were enabled so the user can press those buttons to slide the frame left or right.

Enable button pressed callbacks

Figure 7

The event callback functions are defined in app.c.

The screen state machine is managed inside the Screen0_OnUpdate() function.

On screen initialization, it waits for the library to be done rendering and then configures canvas object 0 to be shown on HW layer 0. This ensures that the screen is completely drawn before it is shown on the display.

Check the code comments to learn more about the Graphics Canvas Application Programming Interface (API) calls used to configure the canvas object.

//Check if renderer is done drawing the screen
if (leRenderer_IsIdle() == LE_TRUE)
    //assign canvas object 0 to HW layer 0
    gfxcSetLayer(0, 0);

    //Set window size to 2x the screen size 
    gfxcSetWindowSize(0, 960, 272);

     //Set window position to origin
     gfxcSetWindowPosition(0, 0, 0);

     //Set canvas 0 to be visible 

     //Update controller with canvas 0 settings

     //Register effects callback
     gfxcSetEffectsCallback(0, APP_Canvas_EffectsCallback, NULL)

     screenState = SCREEN_IDLE;

Note that gfxcCanvasUpdate must be called in order for the canvas object's properties to be applied to its associated HW layer. If multiple canvas objects that use the same HW layer are updated, the settings of the last updated canvas object will be applied.

It also registers a callback function for the Graphics Canvas effects. The callback function is used to determine whether an effect is currently running or not.

/* Canvas effects callback function */
static void APP_Canvas_EffectsCallback(unsigned int canvasID,
                                      GFXC_FX_TYPE effect,
                                      GFXC_FX_STATUS status,
                                      void * parm)
   switch (effect)
       case GFXC_FX_MOVE:
           if (status == GFXC_FX_START)
               //Set screen sliding flag when effect is about to start
               screenSliding = true
           else if (status == GFXC_FX_DONE)
               //Clear screen sliding flag when effect is done
               screenSliding = false;

After initialization, the screen state machine transitions between SCREEN_IDLE and SCREEN_SLIDING when a slide effect starts or completes.

The slide effect is started when the slide left or right buttons are pressed by calling the gfxcStartEffectMove() API.

//Slide left button pressed callback function
void event_Screen0_SlideLeftButton_OnPressed(leButtonWidget* btn)
   //Make sure that screen is idle, not sliding
   if (screenState == SCREEN_IDLE)
       //Start move effect to slide 480 pixels to left
       gfxcStartEffectMove(0, GFXC_FX_MOVE_DEC, 0, 0, -480, 0, 4);

//Slide left button pressed callback function
void event_Screen0_SlideRightButton_OnPressed(leButtonWidget* btn)
   //Make sure that screen is idle, not sliding
   if (screenState == SCREEN_IDLE)
       //Start move effect to slide 480 pixels to right, back to origin
       gfxcStartEffectMove(0, GFXC_FX_MOVE_DEC, -480, 0, 0, 0, 4);

Refer to the "Microchip Graphics Suite (MGS) Graphics Canvas API Documentation" page for more details about the APIs used in this example project.

Back to Top