Font Generator
Principle
The Font Generator module is an off-board tool that generates fonts ready to be displayed without the need for additional runtime memory. It outputs a raw file for each converted font.
Functional Description
Process overview:
The user defines, in a text file, the fonts to load.
The Font Generator outputs a raw file for each font to convert.
The raw files are embedded as (hidden) resources within the MicroEJ Application. The raw file’s data is linked into the FLASH memory.
When the application draws text on the display (or on an image), the font data comes directly from the FLASH memory (the font data is not copied to the RAM memory first).
Pixel Transparency
As mentioned above, each pixel of each character in an .ejf
file has one of 256 different gray-scale values.
However RAW files can have 1, 2, 4 or 8 bits-per-pixel (respectively 2, 4, 16 or 256 gray-scale values).
The required pixel depth is defined in the configuration file (see next chapter).
The Font Generator compresses the input pixels to the required depth.
The following tables illustrates the conversion “grayscale to transparency level”. The grayscale value ‘0x00’ is black whereas value ‘0xff’ is white. The transparency level ‘0x0’ is fully transparent whereas level ‘0x1’ (bpp == 1), ‘0x3’ (bpp == 2) or ‘0xf’ (bpp == 4) is fully opaque.
Grayscale Ranges |
Transparency Levels |
---|---|
0x00 to 0x7f |
0x1 |
0x80 to 0xff |
0x0 |
Grayscale Ranges |
Transparency Levels |
---|---|
0x00 to 0x1f |
0x3 |
0x20 to 0x7f |
0x2 |
0x80 to 0xdf |
0x1 |
0xe0 to 0xff |
0x0 |
Grayscale Ranges |
Transparency Levels |
---|---|
0x00 to 0x07 |
0xf |
0x08 to 0x18 |
0xe |
0x19 to 0x29 |
0xd |
0x2a to 0x3a |
0xc |
0x3b to 0x4b |
0xb |
0x4c to 0x5c |
0xa |
0x5d to 0x6d |
0x9 |
0x6e to 0x7e |
0x8 |
0x7f to 0x8f |
0x7 |
0x90 to 0xa0 |
0x6 |
0xa1 to 0xb1 |
0x5 |
0xb2 to 0xc2 |
0x4 |
0xc3 to 0xd3 |
0x3 |
0xd4 to 0xe4 |
0x2 |
0xe5 to 0xf5 |
0x1 |
0xf6 to 0xff |
0x0 |
For 8-BPP RAW font, a transparency level is equal to
255 - grayscale value
.
Configuration File
The Font Generator uses a configuration file (called the “list file”) for describing fonts that must be processed. The list file is a basic text file where each line describes a font to convert. The font file is described as a resource path, and should be available from the application classpath.
Note
The list file must be specified in the application launcher (see Standalone Application Options).
However, all files in application classpath with suffix .fonts.list
are automatically parsed by the Font Generator tool.
Each line can have optional parameters (separated by a ‘:’) which define some ranges of characters to embed in the final raw file, and the required pixel depth. By default, all characters available in the input font file are embedded, and the pixel depth is 1 (i.e 1 bit-per-pixel).
Note
See Configuration File to understand the list file grammar.
Selecting only a specific set of characters to embed reduces the memory footprint. There are two ways to specify a character range: the custom range and the known range. Several ranges can be specified, separated by “;”.
Below is an example of a list file for the Font Generator:
myfont
myfont1:latin
myfont2:latin:8
myfont3::4
External Resources
The Font Generator manages two configuration files when the External Resources Loader is enabled. The first configuration file lists the fonts which will be stored as internal resources with the MicroEJ Application. The second file lists the fonts the Font Generator must convert and store in the External Resource Loader output directory. It is the BSP’s responsibility to load the converted fonts into an external memory.
Refer to the chapter Fonts to have more details how to use this kind of resources.
Refer to the chapter External Resources to have more details how the Font Engine manages this kind of resources.
Installation
The Font Generator module is an additional tool for MicroUI library. When the MicroUI module is installed, install this module in order to be able to embed some additional fonts with the application.
If the module is not installed, the platform user will not be able to embed a new font with his/her application. He/she will be only able to use the system fonts specified during the MicroUI initialization step (see Static Initialization).
In the VEE Port configuration file, check UI > Font Generator to install the Font Generator module.
Use
In order to be able to embed ready-to-be-displayed fonts, you must activate the fonts conversion feature and specify the fonts configuration file.
Refer to the chapter Standalone Application Options (Libraries > MicroUI > Font) for more information about specifying the fonts configuration file.