Structure of an MLA Graphics Project

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. bsp - "board support package" 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 locate in the folder: <your project>/firmware/src/system_config.


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


system-config.h 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.

Graphics Controller Device Drivers

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


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 into a project based upon the configuration selected.


In order to port an application to a platform which 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.

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's which 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.
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. 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


Coding Examples of Blocking and Non-Blocking Mode


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

© 2017 Microchip Technology, Inc.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.