FreeType support

Interface to FreeType to generate font bitmaps run time.

Add FreeType to your project

First, Download FreeType from here.

There are two ways to use FreeType:

For UNIX

For UNIX systems, it is recommended to use the way of compiling and installing libraries.

  • Enter the FreeType source code directory.

  • make

  • sudo make install

  • Add include path: /usr/include/freetype2 (for GCC: -I/usr/include/freetype2 -L/usr/local/lib)

  • Link library: freetype (for GCC: -L/usr/local/lib -lfreetype)

For Embedded Devices

For embedded devices, it is more recommended to use the FreeType configuration file provided by LVGL, which only includes the most commonly used functions, which is very meaningful for saving limited FLASH space.

  • Copy the FreeType source code to your project directory.

  • Refer to the following Makefile for configuration:

# FreeType custom configuration header file
CFLAGS += -DFT2_BUILD_LIBRARY
CFLAGS += -DFT_CONFIG_MODULES_H=<lvgl/src/libs/freetype/ftmodule.h>
CFLAGS += -DFT_CONFIG_OPTIONS_H=<lvgl/src/libs/freetype/ftoption.h>

# FreeType include path
CFLAGS += -Ifreetype/include

# FreeType C source file
FT_CSRCS += freetype/src/base/ftbase.c
FT_CSRCS += freetype/src/base/ftbitmap.c
FT_CSRCS += freetype/src/base/ftdebug.c
FT_CSRCS += freetype/src/base/ftglyph.c
FT_CSRCS += freetype/src/base/ftinit.c
FT_CSRCS += freetype/src/cache/ftcache.c
FT_CSRCS += freetype/src/gzip/ftgzip.c
FT_CSRCS += freetype/src/sfnt/sfnt.c
FT_CSRCS += freetype/src/smooth/smooth.c
FT_CSRCS += freetype/src/truetype/truetype.c
CSRCS += $(FT_CSRCS)

Usage

Enable LV_USE_FREETYPE in lv_conf.h.

Cache configuration:

  • LV_FREETYPE_CACHE_SIZE - Maximum memory(Bytes) used to cache font bitmap, outline, character maps, etc. Note: This value does not include the memory used by 'FT_Face' and 'FT_Size' objects

  • LV_FREETYPE_CACHE_FT_FACES - Maximum open number of FT_Face objects.

  • LV_FREETYPE_CACHE_FT_SIZES - Maximum open number of FT_Size objects.

When you are sure that all the used font sizes will not be greater than 256, you can enable LV_FREETYPE_SBIT_CACHE, which is much more memory efficient for small bitmaps.

By default, the FreeType extension doesn't use LVGL's file system. You can simply pass the path to the font as usual on your operating system or platform.

If you want FreeType to use lvgl's memory allocation and file system interface, you can enable LV_FREETYPE_USE_LVGL_PORT in lv_conf.h, convenient for unified management.

The font style supports Italic and Bold fonts processed by software, and can be set with reference to the following values:

  • LV_FREETYPE_FONT_STYLE_NORMAL - Default style.

  • LV_FREETYPE_FONT_STYLE_ITALIC - Italic style.

  • LV_FREETYPE_FONT_STYLE_BOLD - Bold style.

They can be combined.eg: LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC.

Use the lv_freetype_font_create() function to create a font. To delete a font, use lv_freetype_font_del(). For more detailed usage, please refer to example code.

Example

Open a front with FreeType

C code  

 GitHub
#include "../../lv_examples.h"
#if LV_BUILD_EXAMPLES
#if LV_USE_FREETYPE

#if LV_FREETYPE_USE_LVGL_PORT
    #define PATH_PREFIX "A:"
#else
    #define PATH_PREFIX "./"
#endif

/**
 * Load a font with FreeType
 */
void lv_example_freetype_1(void)
{
    /*Create a font*/
    lv_font_t * font = lv_freetype_font_create(PATH_PREFIX "lvgl/examples/libs/freetype/Lato-Regular.ttf",
                                               24,
                                               LV_FREETYPE_FONT_STYLE_NORMAL);

    if(!font) {
        LV_LOG_ERROR("freetype font create failed.");
        return;
    }

    /*Create style with the new font*/
    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_text_font(&style, font);
    lv_style_set_text_align(&style, LV_TEXT_ALIGN_CENTER);

    /*Create a label with the new style*/
    lv_obj_t * label = lv_label_create(lv_scr_act());
    lv_obj_add_style(label, &style, 0);
    lv_label_set_text(label, "Hello world\nI'm a font created with FreeType");
    lv_obj_center(label);
}
#else

void lv_example_freetype_1(void)
{
    /*TODO
     *fallback for online examples*/

    lv_obj_t * label = lv_label_create(lv_scr_act());
    lv_label_set_text(label, "FreeType is not installed");
    lv_obj_center(label);
}

#endif
#endif

MicroPython code  

 GitHub Simulator
#!/opt/bin/lv_micropython -i
import lvgl as lv
import display_driver
import fs_driver

font = lv.freetype_font_create("./Lato-Regular.ttf", 24, lv.FREETYPE_FONT_STYLE.NORMAL)

# Create style with the new font
style = lv.style_t()
style.init()
style.set_text_font(font)
style.set_text_align(lv.TEXT_ALIGN.CENTER)

# Create a label with the new style
label = lv.label(lv.scr_act())
label.add_style(style, 0)
label.set_text("Hello world\nI'm a font created with FreeType")
label.center()

Learn more

API

Enums

enum lv_freetype_font_style_t

Values:

enumerator LV_FREETYPE_FONT_STYLE_NORMAL
enumerator LV_FREETYPE_FONT_STYLE_ITALIC
enumerator LV_FREETYPE_FONT_STYLE_BOLD

Functions

lv_res_t lv_freetype_init(uint16_t max_faces, uint16_t max_sizes, uint32_t max_bytes)

Initialize the freetype library.

Parameters
  • max_faces -- Maximum number of opened FT_Face objects managed by this cache instance. Use 0 for defaults.

  • max_sizes -- Maximum number of opened FT_Size objects managed by this cache instance. Use 0 for defaults.

  • max_bytes -- Maximum number of bytes to use for cached data nodes. Use 0 for defaults. Note that this value does not account for managed FT_Face and FT_Size objects.

Returns

LV_RES_OK on success, otherwise LV_RES_INV.

void lv_freetype_uninit(void)

Uninitialize the freetype library

lv_font_t *lv_freetype_font_create(const char *pathname, uint16_t size, uint16_t style)

Create a freetype font.

Parameters
  • pathname -- font file path.

  • size -- font size.

  • style -- font style(see lv_freetype_font_style_t for details).

Returns

Created font, or NULL on failure.

void lv_freetype_font_del(lv_font_t *font)

Delete a freetype font.

Parameters

font -- freetype font to be deleted.