Home

Awesome

Project logo

mcu-renderer

mcu-renderer is a C-language graphics library for MCUs, focused on rendering non-flickering, anti-aliased text with low resource use on both monochrome and color LCD displays.

Features

Supported devices

Setup

To start using mcu-renderer, include the appropriate header file.

In order to initialize the library, call the corresponding mr_xxx_init() function. The display is initially turned off, allowing you to draw before the first screen update. To turn the display on, call mr_xxx_set_display(). On color LCD screens, you also need to disable sleep mode with mr_xxx_set_sleep().

Next, set up the fonts. You may use the fonts available in the fonts folder, or prepare your own, as the Preparing fonts section explains.

After that, set up a screen layout consisting of non-overlapping rectangles. This will avoid any flickering when updating the screen.

To draw a filled rectangle, call mr_set_fill_color() to set the fill color and mr_draw_rectangle() for the actual drawing. You can convert web colors (e.g. #ff2020) to mcu-renderer colors with the mr_get_color macro.

To draw a bitmap in a user-provided uint8_t framebuffer, call mr_set_stroke_color() to set the foreground color, mr_set_fill_color() to set the background color and mr_draw_bitmap() to draw the bitmap.

To draw an image in a user-provided RGB565 framebuffer, call mr_draw_image().

To draw a text rectangle, call mr_set_font() to set the font, mr_set_fill_color() to set the background color, mr_set_stroke_color() to set the text color, and mr_draw_text(), mr_draw_text_utf8() and mr_draw_text_utf16() to render C-strings, UTF-8 strings and UTF-16 strings, respectively. The offset parameter specifies the upper left corner of the text within the drawing rectangle: to center text horizontally, use the mr_get_text_width(), mr_get_text_utf8_width() and mr_get_text_utf16_width() functions; to center text vertically, get the current font's metrics with mr_get_cap_height() (height of uppercase A), mr_get_ascent() (top of line to baseline), mr_get_descent() (baseline to bottom of line) and mr_get_line_height() (height of line). Make sure you set the font before retrieving any metrics.

Rectangle bounds may not exceed the display size. The offset parameter of the text drawing functions is not limited.

Monochrome displays and SDL require a screen refresh. For refreshing the screen, call mr_xxx_refresh_screen() after you finished drawing.

Examples

See the examples folder.

Font compression ratio comparison

(ASCII characters 0x20-0x7e)
(sizes in bytes)

FontRoboto 12 pxRoboto 24 pxRoboto 48 pxRoboto 72 px
Adafruit_GFX/TFT_eSPI (1 bpp)38321458956677129389
u8g2 (1 bpp)150830396632N/A
mcu-renderer 1 bpp1473289159029511
mcu-renderer 2 bpp20524162874313969
mcu-renderer 3 bpp269556771212818701
mcu-renderer 4 bpp332873291553323676
MCUFont (4 bpp)312562961296920045
TFT_eSPI (vlw)76421938765833143333

Preparing fonts

In order to convert your fonts to the mcu-renderer format, use the fontconv tool (available in binary form under releases), which lets you convert both .bdf and .pcf bitmap fonts as well as .ttf, .ttc, .otf, .otc and .woff vector fonts.

In digital typography, 72 points is usually defined as 96 pixels. For rasterizing a vector font to a given pixel size, convert the pixel size to a point size by multiplying by the factor 4/3. Not all fonts follow this rule, so you might need to tweak this factor.

fontconv calculates the cap height (the height of the uppercase letter A) as the difference between the ascent height (top of line to baseline) and the descent height (baseline to bottom of line). On some fonts this calculation is inaccurate, so you can override the cap height to achieve the correct result. You can also override the ascent height and the descent height.

Additional resources