Drawing Graphic Primitives

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

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

Back to top.

Primitive Elements

Primitive Elements

Back to top.

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_SOLIDsolid line, one pixel wide (default)
 GFX_LINE_STYLE_THIN_DOTTEDdotted line, one pixel wide
 GFX_LINE_STYLE_THIN_DASHEDdashed line, one pixel wide
 GFX_LINE_STYLE_THICK_SOLIDsolid line, three pixels wide (default)
 GFX_LINE_STYLE_THICK_DOTTEDdotted line, three pixels wide
 GFX_LINE_STYLE_THICK_DASHEDdashed line, three pixels wide

Back to top.

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.

Drawing Lines

Line Image

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.

Code to Draw a Rectangle

Rectangle added to image

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.

Bevelled Corners Image

Bevelling Code

Bevel Picure

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.

Code for Filled Bevel

Filled Bevel Picture

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.

Code to Draw a Circle

Circle Picture

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

Fill a Rectangle Code

Rectangle Fill Picture

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

Back to top.

Learn More

Back to top.