Graphic Primitives

What are Graphics Primitives

Graphics Primitives

Graphics Primitives are non-interactive rudimentary elements displayed on a screen. Several primitive elements can be combined together to create a complex image. Graphics primitive elements are used by both Microchip Harmony and MLA applications.

Graphics primitives include:

  • Lines, Circles, Arcs, Rectangles, etc.
  • Character Fonts
  • Imported Images

In order to include Graphics Primitives in a project both gfx_primitive.h and gfx_primitive.c files must be included in the project.

Care should be taken regarding the use of Graphics Primitives in an application. Graphics primitives are easy to understand and program. New-to-graphics designers tend to over use graphics primitives in displaying dynamic data. Primitives are primarily used in introduction or "splash" screens. Graphics Objects are best used to display dynamic data and retrieve user input from touch screens.

Primitive Elements


Setup Functions:

DRVgfx_Initialize() - Initializes the display driver. This function must be called before any graphics element can be displayed.

GFX_Primitive_Initialize() - Initializes the primitive layer software allowing the primitive's drawing functions to operate.

GFX_ColorSet(color) - Sets the drawing color. The value of the color is set by the RGB565 macro and can be found in GFXColor.h.

GFX_ScreenClear() - Clears screen with current color then places the cursor at (0,0).

GFX_LineStyleSet(key) - Establishes that any line to be drawn has the attribute set by the key. The options for keys are:

GFX_LINE_STYLE_THIN_SOLID solid line, 1 pixel wide (default)
GFX_LINE_STYLE_THIN_DOTTED dotted line, 1 pixel wide
GFX_LINE_STYLE_THIN_DASHED dashed line, 1 pixel wide
GFX_LINE_STYLE_THICK_SOLID solid line, 3 pixels wide (default)
GFX_LINE_STYLE_THICK_DOTTED dotted line, 3 pixels wide
GFX_LINE_STYLE_THICK_DASHED dashed line, 3 pixels wide

Drawing Functions:

GFX_LineDraw(unit16 x1, unit16 y1, unit16 x2, unit16 y2) draws a line from x1,y1 to x2,y2, and leaves the cursor at the end point of the line.


GFX_RectangleDraw(unit16_t Left, unit16_t Top, unit16_t Right, unit16_t Bottom) draws a rectangle using the current line type, and co-ordinates for top, left, right and bottom.


GFX_RectangleRoundDraw(top, left, bottom, right, radius) renders a rectangular shape with rounded corner using the given left, top, right, bottom and radius parameters to define the shape dimension. Radius defines the rounded corner shape. When = x2 and y1 = y2, a circular object is drawn. When x1 < x2 and y1 < y2 and rad (radius) = 0, a rectangular object is drawn.


GFX_RectangleRoundFillDraw(top, left, bottom, right, radius) draws a filled beveled figure on the screen. For a filled circular object use top = bottom, and left =right. For a filled rectangular object, use radius = 0.


GFX_CircleDraw(x,y,radius) draws a circle with the given radius and center point using the current line type.
GFX_CircleFillDraw(x,y,radius) draws a circle filled with the current color.


RectangleFillDraw(left,top,right,bottom) draws a solid rectangle using the current color within the coordinates.

To get a complete list of all Graphics Primitive functions, open GFX_help.png help_mlagfx.jar
located in..microchip/mla/vYYYY_MM_DD/doc…



Fonts are electronic data files containing a set of glyphs, characters, and symbols. A typical font image contains the characters (and sizes) used in a project. Fonts are imported into the project as source code and compiled during the project build. Imported fonts can be stored in program memory or placed into external nonvolatile memory.

Fonts are created with font editors and may be considered works of art. Pre-created fonts are available from many sources, but may be licensed. It is not uncommon for fonts to be copyrighted.

This tutorial shows how to import and work with fonts located in program memory. Most of the MLA graphics projects are built with an imported default font so there is no need to import a font to begin displaying messages. The code for the default font is located in the files:

  • internal_resoure.s,
  • internal_resource_reference.c
  • internal_resource_reference.h

Importing Fonts

Step-by-Step Instructions:
Importing fonts to an MLA Graphics project

The Graphics Resource Converter utility (GRC) is used to import fonts. The GRC can import a font already existing on the developer's computer or can import a font from one of several font format files.

The GRC is located in the MLA Installation directory:

Linux and Apple OSX users launch the resource converter by executing grc.jar, and Microsoft Windows users invoke it by executing launch_grc.bat

Using Fonts

Once the GRC has been used to import a font, the associated assembly (.s), C (.c), and header files (.h) are added to the open MLA project. Including the font files in the project will allow user's program in the project to access the font.

Inside the header (.h) and the C (.c) file are the definitions of the stucture containing the font. The assembly file (.s) contains the bitmaps of the characters. The name of the structure in the C (.c) file is taken from the font being imported. If you want to change the name of the font, you will need to edit both the header (.h) and C (.c) files. For this example we are using the font from the step-by-step instruction on importing fonts. The font name is Miriam_Fixed_Bold_18. The font has been saved to MyNewFont.s, MyNewFont_reference.c and MyNewFont.h.


Example of MPLAB®X IDE's project tree with the assembly (s.), header (.h), and C (.c) files added.

Basic Functions to use fonts and output text

GFX_FontSet(pFont) - Sets the font to be used in the application. The pointer must point to the font image in the imported font file.

GFX_TextStringDraw( x, y, pFont, length) Outputs the text string pointed to by pFont starting at the location specified by x and y. Outputs the number of characters specified by length. If length = 0 the string will be rendered until the null character is reached.


Example of GFX_SetFont and GFX_TextStringDraw used to draw a horizontal "Microchip"

Functions used to manipulate text

GFX_TextSringHeightGet( pFont) - Returns the height, in pixels, of the string pointed to by pFont. Requires the font to have been set with GFX_FontSet.

GFX_TextStrightWidthGet( textstring, pFont) - Returns the width, in pixels, of the string pointed to by "textstring" if drawn with the font designated by pFont.

GFX_TextCursoPositionSet(x, y) - Sets the drawing cursor to the location specified by X and Y.

GFX_TextCharDraw( ch) - Outputs the one character designated by ch at the current cursor position.


Example of using GFx_TextStringHeightGet, GFX_TextCursorPositionSet, and GFX_TextCharDraw to vertically output "Graphics"

To get a complete list of the functions available for working with fonts and text open GFX_help.png help_mlagfx.jar
located in..microchip/mla/vYYYY-MM-DD/doc…
Note that the two example programs demonstrating fonts can be reproduced by modifying the main() function in the MLA project "primitive_layer"

Graphic Images

Bitmap Images

Bitmap images are binary files which contain a pixel by pixel description of a graphical image.. The value of each pixel is stored in one or more bits of data as defined by the color depth, or bits per pixel (bpp).

The amount of memory required to store images can be quite large. Click Here to see a chart of how images size and color density can effect the memory requirements. To conserve the application's program memory it is possible to store images and fonts in external non-volatile memory.

Importing Bitmap images

Step-by-Step Instructions:
Importing Images to an MLA Graphics project

The Graphics Resource Converter utility (GRC) is used to import graphics images. (This is the same utility used to import fonts). The GRC can import images from bitmap files (.BMP) or JPEG files (.JPG or .JPEG).

The GRC is located in the MLA Installation directory:

Linux and Apple OSX users launch the resource converter by executing grc.jar, and Microsoft Windows users invoke it by executing launch_grc.bat

Using Bitmap Images

Once the image has been imported into the project and rebuilt you will be able to display the image on the screen. To reference an imported image you refer to the image by the name given in the header file. When an image file is converted you will be prompted to enter the name of the file to store the image. This example uses NewImage as the name of the image file.


Example of MPLAB® X IDE's project tree with the assembly (.s), header (.h), and C (.c) files added.

Function used to Output an Image

GFX_ImageDraw( left, top, &image) displays the image on the screen at the coordinates designated.


Helpful Functions to Position Images on the Screen

The following functions can be useful to position your images (and objects) on the screen

GFX_MaxXGet() returns the width (in pixels) of the display

GFX_MaxYGet() returns the height (in pixels) of the display

GFX_ImageWidthGet( GFX_RESOURCE_HDR * pImage) returns the width, in pixels, of the image.

GFX_ImageHeightGet(GFX_RESOURCE_HDR * |pImage) returns the height, in pixels, of the image.

To get a complete list of the functions available for working with bitmap images open GFX_help.png help_mlagfx.jar
located in..microchip/mla/vYYYY_MM_DD/doc…

© 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.