# 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:
``` bash
g++ fontgen.cpp -o fontgen
```

External library:
- stb_image, made by `Sean Barrett`, sourced from [nothings/stb](https://github.com/nothings/stb), provided in the public domain

## Usage

The `fontgen` utility can be used like this:
``` bash
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:
``` bash
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](../blastproof/fbm.md).