GFX library

The GFX library provides support for drawing graphic objects, as well as printing text.

Main features:

• Support for drawing lines, rectangles, and circles.
• Support for printing text on the screen.
• Support for drawing bitmaps in RGB565 color format.
• Hardware independent.
• Any number of instances.

The library uses Bresenham's algorithms for drawing objects. These are simple and efficient algorithms for drawing straight lines and circles on a grid of pixels.

For full API documentation of the library, see GFX Library.

LCD abstraction

In order to make the GFX library more generic, all of the GFX functions use pointers to an abstract LCD structure - nrf_lcd_t. This structure contains pointers to the LCD generic function and a control block to keep the state of the LCD. Functions nrf_lcd_t::lcd_pixel_draw and nrf_lcd_t::lcd_rect_draw must be implemented to use all functions for drawing objects. Other functions are optional - for example, if you do not need any initialization for your LCD, you do not need to implement the lcd_init function. However, you must provide a pointer to every function, even if it is a pointer to an empty function.

Note

nrf_lcd_t::p_lcd_cb keeps information about the state of the LCD so even if you do not need any initialization, you must still call nrf_gfx_init to set LCD in proper state. This function will also check if pointers to functions are not NULL.

This generic API guarantees that you can pick almost any LCD controller and adapt it to use the GFX library. The drawback is that some optimizations specific for your controller may be incompatible with this library.

Initialization and starting

The module itself does not require any initializing but in order to start working with your LCD, you must call nrf_gfx_init. This function calls the LCD initializing function and sets the proper state of your LCD control block. The most important part is to fill the LCD generic structure - nrf_lcd_t with proper function pointers and proper information about the LCD.

The following is an example of initialization of the GFX library using a driver for the ILI9341 controller (available in this SDK in the drivers_ext folder).

extern nrf_lcd_t nrf_lcd_ili9341; // This is defined in ili9341.c

nrf_lcd_t * p_lcd = &nrf_lcd_ili9341;

APP_ERROR_CHECK(nrf_gfx_init(p_lcd));

Drawing objects

To draw an object using GFX, you must call the proper function with parameters of this object, which are typically start point, end point, radius width, color etc. To facilitate the usage of this library, a set of macros is provided which will help you define your object. For example, to draw a line, execute the following code example (assuming you already initialized your LCD with nrf_gfx_init):

#define RED 0xF800

nrf_gfx_line_t my_line = NRF_GFX_LINE(nrf_gfx_width_get(p_lcd),
nrf_gfx_height_get(p_lcd), 
0, 
nrf_gfx_height_get(p_lcd), 
1);
nrf_gfx_line_draw(p_lcd, &my_line, RED);

To draw any other object, the steps are very similar, you only need to use the proper function.

Note

Color type is uint32_t but you can cast it inside your drawing function to any type you want. In this way, you can use this library with an RGB888 LCD, as well as with a monochromatic one.

LCD frame buffer

In some cases, LCD drivers may not support the drawing of a single pixel or you may want to use a frame buffer to accelerate the drawing operations. Another solution is to implement nrf_lcd_t::lcd_pixel_draw and nrf_lcd_t::lcd_rect_draw to write to your internal frame buffer. Then, you can implement the nrf_lcd_t::lcd_display function to write the whole buffer to the screen. It gives you control over hardware communication with your controller and allows to refresh the screen only when needed.

GFX fonts

The library comes with two different fonts but you can generate any kind of font yourself. To generate fonts, you can use The Dot Factory free font generator. The GFX library is designed to be compatible with fonts generated by The Dot Factory tool. Once you generate your font, you only need to pass the font descriptor to nrf_gfx_print :

static const char * test_text = "This is nRF52";

extern const FONT_INFO microsoftSansSerif_16ptFontInfo;

static const FONT_INFO * p_font = &microsoftSansSerif_16ptFontInfo;

static void text_print(void)
{
 nrf_gfx_point_t text_start = NRF_GFX_POINT(10, 10);
 APP_ERROR_CHECK(nrf_gfx_print(p_lcd, &text_start, 0, test_text, p_font, true));
}

Note

After generating a font, you must change FONT_INFO::height to be described in bits (pixels), not pages.

Usage example

For a usage example of this library, see GFX Library Example.