vystem/docs/boottools/fontgen.md

Fontgen docs

Introduction

The fontgen utility is responsible for generating the font used by Blastproof. It can only generate FBM font.

Detailled informations

Folder: Blastproof/fontgen Source code file: fontgen.cpp

For building fontgen, use the following command:

g++ fontgen.cpp -o fontgen

External library:

• stb_image, made by Sean Barrett, sourced from nothings/stb, provided in the public domain

Usage

The fontgen utility can be used like this:

fontgen <text color> <background color> [ascii/utf8/utf16] <path to folder containing images files for characters>

The text and background color arguments must be given under a hexadecimal RGB color code, starting with #. They serve as boundary for generating the shading scale. The encoding argument can be ascii, utf8 or utf16, however in Vystem build script, only the ascii encoding is used. Others supported encoding modes haven't been tested. The final argument is the path to the folder that contain all images files for the font characters. Each character is encoded with the following format:

• they must named with this format 0xXXXXXXXX where X is an hexadecimal character. All X aren't mandatory, and the utility interprete them as characters codepoint. For example, file name 0x00 will be interpreted as a codepoint of value 0x00000000, resulting in the \0 character for ASCII
• each file inside the provided folder must be a PNG file
• each file must only contain pixel with colors inside the generated shading scale. For instance, the bitra font only use color from the two extremities of the shading scale. Transparency isn't checked as the shading scale is in RGB and all images files are opened in 3 channels mode.
• all files must have the same height and width, that will indicate the dimensions of the bitmap grid for each pixel

Any failure to meet the above points will result in font compilation error.

Command example:

fontgen "#FFFFFF" "#000000" ascii ./chars

Detailled generation process

1. Generate the shading scale by associating colors from the linear interpolation of the two provided colors to values ranging from 0 to 15. The text color will be occupy the value 15 and the background color the value 0.
2. For each image file in the provided folders: extract the character codepoint from the file name, endode it to FBM codepoint format, extract the raw pixel data
3. For each valid character: extract the codepoint bits that will be inserted into pixel bytes, iterate for each pixel of the character: identify which value in the shading scale the pixel color is, encode it into a byte with codepoint bits and on/off value (off if the shading value is 0, on otherwise)
4. Write the header and all the encoded characters into the final file that will be named font.fbm

Any failure to meet the above criteria (except some of the second step that will only trigger a warning) will result in font compilation error.

For a detailled overview of how a .fbm file is structured, please see FBM docs.