Using Fonts in a Graphics Application

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

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

Fonts

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 non-volatile memory.

Fonts are created with font editors and may be considered works of art. Pre-created fonts are available from many sources but may have a license; 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

Back to top.

Importing Fonts

Step-by-Step Instructions:

The Graphics Resource Converter (GRC) utility 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:
…microchip/mla/vYYYY_MM_DD/framework/gfx/utilities/grc.

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

Back to top.

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 the user's program in the project to access the font.

Inside the header (.h) and the C (.c) file are the definitions of the structure 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.

Structure containing the font

MPLAB X IDE project tree

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

Back to top.

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

Used to Draw a Horizontal "Microchip"

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

Picture showing the "Microchip" text

Back to top.

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.

Functions Used to Manipulate Text

Example of Using GFx_TextStringHeightGet, GFX_TextCursorPositionSet, and GFX_TextCharDraw to Vertically Output Graphics

Picture of vertical "Graphics" text

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

Back to top.