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.
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. Designers new to graphics tend to overuse 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, one pixel wide (default) | |
| GFX_LINE_STYLE_THIN_DOTTED | dotted line, one pixel wide | |
| GFX_LINE_STYLE_THIN_DASHED | dashed line, one pixel wide | |
| GFX_LINE_STYLE_THICK_SOLID | solid line, three pixels wide (default) | |
| GFX_LINE_STYLE_THICK_DOTTED | dotted line, three pixels wide | |
| GFX_LINE_STYLE_THICK_DASHED | dashed line, three pixels wide |
Drawing Functions:
GFX_LineDraw(unit16 x1, unit16 y1, unit16 x2, and 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, and unit16_t Bottom) draws a rectangle using the current line type, and coordinates for top, left, right, and bottom.
GFX_RectangleRoundDraw(top, left, bottom, right, and 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 x1 = 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, and 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, and radius) draws a circle with the given radius and center point using the current line type.
GFX_CircleFillDraw(x, y, and radius) draws a circle filled with the current color.
RectangleFillDraw(left, top, right, and bottom) draws a solid rectangle using the current color within the coordinates.
help_mlagfx.jar located in …microchip/mla/vYYYY_MM_DD/doc….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.
Fonts
- 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
Importing Fonts
Step-by-Step Instructions:
Importing fonts to an MLA Graphics Project
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 Apple OS X® 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 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 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 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.
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.
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."
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.
Graphic Images
- Bitmap Images
- Bitmap images are binary files that 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. 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 (GRC) utility 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: …microchip/mla/vYYYY_MM_DD/framework/gfx/utilities/grc
Linux and Apple OS X® 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.
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.
help_mlagfx.jar located in ..microchip/mla/vYYYY_MM_DD/doc…