Font Loader

Principle

The Font Loader is a module of the MicroUI runtime that loads font data (precomputed bitmaps of glyphs) ready to be displayed. The font data must be stored as a resource (in EJF raw format). Typically, these resources are generated by the Font Generator and embedded as internal resources or loaded from external memories (External Resources loader).

External Resources

Memory Management

The Font Renderer is able to load some fonts located outside the CPU addresses’ space range. It uses the External Resource Loader.

When a font is located in such memory, the Font Renderer copies a very short part of the resource (the font file) into a RAM memory (into CPU addresses space range): the font header. This header stays located in RAM until the application is using the font. As soon as the application uses another external font, new font replaces the old one. Then, on application demand, the Font Renderer loads some extra information from the font into the RAM memory (the font meta data, the font pixels, etc.). This extra information is automatically unloaded from RAM when the Font Renderer no longer needs them.

This extra information is stored into a RAM section called .bss.microui.display.externalFontsHeap. Its size is automatically calculated according to the external fonts used by the firmware. However it is possible to change this value by setting the application property ej.microui.memory.externalfontsheap.size. This option is very useful when building a kernel: the kernel may anticipate the section size required by the features.

Warning

When this size is smaller than the size required by an external font, some characters may be not drawn.

Configuration File

Like internal resources, the Font Generator uses a configuration file (also called the “list file”) for describing fonts that need to be processed. The list file must be specified in the application launcher (see Application Options). However, all the files in the application classpath with the suffix .fontsext.list are automatically parsed by the Font Generator tool.

Process

This chapter describes the steps to setup the loading of an external resource from the application:

  1. Add the font to the application project resources (typically in the source folder src/main/resources and in the package fonts).
  2. Create / open the configuration file (e.g. application.fontsext.list).
  3. Add the relative path of the font and, at least, its output format (e.g. /fonts/myFont.ejf::4, see Fonts).
  4. Build the application: the Font Generator converts the font in RAW format in the external resources folder ([application_output_folder]/externalResources).
  5. Deploy the external resources to the external memory (SDCard, flash, etc.) of the device.
  6. (optional) Configure the External Resources Loader to load from this source.
  7. Build the application and run it on the device.
  8. The application loads the external resource using Font.getFont(String).
  9. The font loader looks for the font and only reads the font header.
  10. (optional) The external resource is closed if the external resource is inside the CPU addresses’ space range.
  11. The application can use the font.
  12. The external resource is never closed: the font’s bytes are copied in RAM on demand (drawString, etc.).

Simulation

The Simulator automatically manages the external resources like internal resources. All images listed in *.fontsext.list files are copied in the external resources folder, and this folder is added to the Simulator’s classpath.

Backward Compatibility

As explained here, the notion of Dynamic styles and the style UNDERLINED are not supported anymore by MicroUI 3. However, an external font may have been generated with an older version of the Font Generator; consequently, the generated file can hold the Dynamic style. The Font Renderer can load these old versions of fonts. However, there are some runtime limitations:

  • The Dynamic styles are ignored. The font is drawn without any dynamic algorithm.
  • The font style (the style returned by Font.isBold() and Font.isItalic()) is the Dynamic style. For instance, when a font holds the style bold as dynamic style and the style italic as built-in style, the font is considered as bold + italic; even if the style bold is not rendered.

Installation

The Font Renderer is part of the MicroUI module and Display module. You must install them in order to be able to use some fonts.

Use

The MicroUI font APIs are available in the class ej.microui.display.Font.