Skip to Content

Structure of an MLA Graphics Project

Last modified by Microchip on 2024/12/05 12:58
Contents

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.

Directory Structure

After installation, the contents of an MLA installation directory will look like the one below. Four of the subdirectories are used for graphics projects.

  1. apps: sample projects
  2. board support package (bsp): contains code to run common peripherals
  3. doc: help files for all applications
  4. framework: all the source code and header files for the MLA

Project Properties and Drivers

Display Properties

Graphics Projects supplied by Microchip contain a single system configuration subdirectory for each project configuration. Each of these subdirectories contains at least two files, system.h and system-config.h.

These system config directories are located in the folder:
<your project>/firmware/src/system_config.

Graphics Projects Subdirectory Structure

​

In Microchip supplied projects, these subdirectories are in the project tree, however, only the subdirectory for the current configuration is included in the project.

The system-config.h file location

The system-config.h file contains display-specific information needed by the driver. Among the information contained in this file are the screen resolution and control signals needed to drive the display.

​

When changing to a display not supported by the Microchip Graphics Library you will need to modify system-config.h to define the display properties.

Back to top

Graphics Controller Device Drivers

The compilable source code and s for the graphics controller drivers are located within the /framework/driver/gfx subdirectory.

Header file location

Microchip typically places all the driver source and header files in every project tree.

  • The driver source files a located in the project tree under Source Files/framework/driver/gfx.
  • The driver header files are located in the project tree under Header Files/framework/driver/gfx.

While all the files are present in the project tree, they are not all included in every project. The driver files for a particular graphics controller are included in a project based upon the configuration selected.

Source and Header files location and identification

​

In order to port an application to a platform that contains a graphics controller not supported by Microchip, the functions supplied in the device drivers will need to be replaced with drivers supplied by the developer. These functions include DRVgfx_Initialize, DRVgfx_ImageDraw, GFX_PixelPut GFX_PixelGet, GFX_PixelArrayPut, GFX_PixelArrayGet, GFX_RenderStatusGet. Consult the individual header and source files for a complete list of functions needed.

Back to top

Graphics Configuration File gfx-config.h

Graphics projects contain a project-specific configuration file called gfx-config.h. This file is #included into the project and is used during the compilation of the project. The file contains a series of #defines functions that instruct the compiler to enable or disable graphics-specific features in the compiled code.

Familiarity with this file is important as this file is quite often modified by the programmer. Among the features controlled by gfx-config.h are:

  • Alpha Blending
  • Color Gradient
  • Color Palette Settings
  • Using External Flash
  • Double Buffering
  • Blocking vs. Non-Blocking Code

Some embedded MCU applications implement multi-tasking programming techniques. In multi-tasking applications several autonomous tasks are present yet only one task is executing at any one time. In most multi-tasking systems an application task may not know when or if control was given to another task. Decisions over when to remove control from a task are controlled by resources outside of the program (i.e. operating system, real-time kernel, etc.)

To work with a multi-tasking environment, Microchip’s MLA graphics library functions which draw primitive graphic elements can be compiled with one of two attributes: Blocking or non-Blocking Mode.

Blocking Mode

When compiled as Blocking Mode, the drawing functions called by the MLA will presume to have completed their function when they return (i.e. the function is called, runs to completion, then returns). Blocking mode is the method in which most embedded programmers first learn to program.
In Non-Blocking Mode, the user must realize that the system may take control of the task before completion and there is a possibility that an MLA function was not completed.

Non-Blocking Mode

In Non-Blocking mode, primitive gaphic drawing functions will return a ‘1’ when they complete their function and a ‘0’ when they are unfinished. Users who program in Non-Blocking Mode should test the primitive graphics funcions to verify they have finished executing.

Setting the mode to either Blocking or Non-Blocking is done by a #define of the macro USE_NONBLOCKING_CONIFG in the file GraphicsConfig.h

Blocking and non-Blocking Mode

Coding Examples of Blocking and Non-Blocking Mode

Blocking and non-Blocking Config

​

Most coding examples used in this tutorial use the simpler Blocking Mode syntax and flow.

Learn More

Back to top