MCUFont: Overview

MCUFont is a font compression, decompression and rendering library for use with microcontroller systems. Its main purpose is to allow high-quality anti-aliased text rendering, while having small enough footprint to fit in the typical flash memories.

Historically, there are many simple font rendering routines available. They are usually ad-hoc implementations inside various graphics libraries, and consequently they "take the easy way out". Usually this means monochrome only, no kerning, sometimes only monospace and very basic algorithms for word wrap. The goal of this library is to become a standard solution for this problem, so that also microcontroller based systems can enjoy high quality text. On the other hand, the purpose is not to compete with libfreetype and similar vector font rendering libraries, because they already exist.

Example

Overall structure

The library consists of the encoder program, written in C++, and the decoder library, written in ANSI C. The encoder runs on your PC and is used to import and compress font files. The decoder runs on the target microcontroller and decompresses and renders the characters.

Getting started

In order to get started, download the library and install the following dependencies:

• libfreetype
• cxxtest

Next, run make in the root folder. This will build the encoder, encode a few example fonts and build a render_bmp example program for testing the decoder and renderer.

The example fonts will be built in the fonts subfolder, and consist of two files each. For example, DejaVuSans12.c and DejaVuSans12.h are the DejaVu Sans font rendered at 12 pixels height. To render text using this font, you could do this:

#include "fonts.h"
#include <mcufont.h>

static void pixel_callback(int16_t x, int16_t y, uint8_t count, uint8_t alpha, void *state)
    {
    while (count--)
        {
            /* your code goes here, ex: drawPixel(x, y, alpha, color::black); */
            x++;
        }
    }

static uint8_t char_callback(int16_t x0, int16_t y0, mf_char character, void *state)
    {
        return mf_render_character(&mf_rlefont_DejaVuSans12.font, x0, y0, character, &pixel_callback, state);
    }

void main()
    {
        mf_render_aligned(
            &mf_rlefont_DejaVuSans12.font,
            0, 0,
            MF_ALIGN_LEFT,
            "Hello, World!", 13,
            &char_callback, NULL);
    }

What happens here is that mf_render_aligned takes each character of the string "Hello, world!" in turn, and calls mf_render_character for them. The character rendering function will then decompress the glyph data and call pixel_callback for each consecutive run of pixels. The callback function provided by you will then finally draw the pixels to the screen.

Features and limitations

Features

• Pure C runtime
• Support for importing .ttf and .bdf fonts
• Small code size of the decoder library (1-5 kB depending on used features)
• Abstract callback interface for writing to any kind of display
• 16-level antialiased fonts
• Uses libfreetype's high-quality hinting when importing .ttf fonts
• Advanced kerning, justification and word wrapping algorithms
• Fast decoding and high compression ratio

Limitations

• No support for runtime scaling of fonts
• No subpixel antialiasing (could be added in the future)

System requirements

The decoder side has minimal system requirements. The following header files are only required for the declaration of the standard types, and can be easily replaced if not available on the target platform:

• stdbool.h for declaration of bool datatype
• stdint.h for declaration of uint32_t etc. datatypes
• stddef.h for wchar_t if enabled (optional)

The encoder also should compile on many kinds of platforms.

Debugging and testing

The encoder includes basic unit tests which are run before building. The decoder side is tested using the render_bmp example applications. All tests are run automatically by executing make in the top directory.