Overview of a Typical Graphics Application's Software

Last modified by Microchip on 2023/11/09 09:10

This page contains information for the Graphics Library found in Microchip Libraries for Applications (MLA). It is not relevant for the MPLAB® Harmony Graphics Library.

Introduction

Typical Graphics Application

The code on the screen represents a typical PIC® MCU graphics application. Understanding the program flow is essential to developing graphics applications.

Navigation

The next few screens contain an explanation for each of these lines of code. After reviewing the program overview you will be able to explore the individual graphics topics and begin developing applications. 

Typical PIC® MCU graphics application

Back to top.

User's Application Code

These functions represent the non-graphics portion of the application program.

SYSTEM_InitializeBoard(); represents the user-written function that performs the one-time start-up initialization needed for the application to run.

APP_Tasks(); represents the function (or functions) that run infinitely to execute the non-graphics portion of the user application.

Users Application Code

Back to top.

Initializing the Graphics Library

Before any graphics items can be output to the display DRVgfx_Initialize must be run to initialize the hardware drivers.

GFX_Primitive_ Initialize sets up the library to output Graphics Primitive elements.

Initializing Library

The GFX_Initialize function makes these two necessary calls...
void GFX_Initialize(void)
{
DRV_GFX_Initialize();
GFX_Primitive_Initialize();
}

Back to top.

Setting up the Callback Functions

Microchip Graphics Applications utilize two callback functions: GFX_GOL_MessageCallback and GFX_GOL_DrawCallback. The user is responsible for writing the functions to perform these tasks and then setting these user-written functions as the callback routines.

This example shows the user-written APP_ObjectMessageCallback being set as the message callback function and APP_ObjectDrawCallback being set as the drawing callback function.

Callback Functions

Back to top.

Creating Screens

APP_CreateScreens() represents a user-written function that creates screens to display. A screen, or display list, is a list of interactive Graphics Objects linked together and kept in the MCU's heap memory. The application generates the display list at run time by making a series of object-creating function calls.

In order to successfully create a screen you will need to understand the object-creating functions, the object state bits, and style schemes.

Create Screens

Back to top.

Drawing Graphics Objects

GFX_GOL_ObjectListDraw() parses the linked list of objects and updates the frame buffer based on the state bits of the objects in the list.

When GFX_GOL_ObjectListDraw completes parsing the list a 'true' condition is returned

It may take more than one call to GFX_GOL_ObjectListDraw to complete processing the current linked list

ObjectListDraw is compared to GFX_STATUS_SUCCESS

Back to top.

The "Safe" Zone

Altering the state-bits of the display list while the list is being processed by GFX_GOL_ObjectListDraw can result in anomalies in the image being displayed.

To avoid problems with the display the only safe place to update the list of objects is after the drawing function returns a true condition

Safe Zone

Back to top.

Getting Touch Input

TouchGetMsg is a function supplied by Microchip to detect if (and where) there is a touch, release, or movement on a resistive-touch graphics display. This function populates the structure called msg with information on the touch event.

Touch Get Msg function

Back to top.

Processing Input

GFX_GOL_ObjectMessage() analyzes msg to determine if the touch event impacts an existing graphics object.

If an object has been touched, the callback function GFX_GOL_MessageCallback is executed to process the event.

GFX GOL Object Message function

Back to top.

Message Callback Function

  • Written by the user and called by: GFX_GOL_ObjectMessage
  • Performs MCU actions based on input to an object. These actions may include starting a motor, turning on an LED, or any MCU controlled task
  • Changes the appearance of an object (or objects) in the display list and updates their status bit so they will be redrawn to the frame buffer by: GFX_GOL_ObjectListDraw.
  • Returns CPU control to: GFX_GOL_ObjectMessage

GFX GOL Object Message function

Back to top.

Draw Callback Function

  • Written by the user and called by: GFX_GOL_ObjectListDraw
  • Executes on each iteration of the main loop regardless of whether or not a touch event has occurred
  • Can be used in conjunction with the message callback function to determine how long a touch event has occurred. Timing a touch event facilitates taking an action based on how long a touch event has occurred (e.g. dimmer switches or volume control)
  • Returns control to: GFX_GOL_ObjectListDraw

ObjectListDraw Function

Back to top.