# Bootanim docs

## Introduction

The `bootanim` utility is responsible for generating the boot animation. It is used even if the bootloader configuration specify to not play the boot animation, as it contain the Vystem logo blueprint.

## Detailled informations

Folder: `Blastproof/bootanim`
Source code file: `bootanim.cpp`

For building `bootanim`, use the following command:
``` bash
g++ bootanim.cpp -o bootanim -Ofast -march=native
```
The `-Ofast -march=native` is recommended for better performances, as the boot animation generation is a bit heavy on computation.

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

## Usage

Prerequisites: having `ffmpeg` accessible in path for the use of folder mode, for generating the video.

The `bootanim` can be used like this:
``` bash
bootanim <png logo file> [file/folder] <width> <height>
```
 
You can use `bootanim` in two differents mode:
- file mode: will export the boot animation as `bootanim.bin`, into a format readable by the bootloader
- folder mode: will export the boot animation as a folder named `frames` that will contain all the generated frames under the name format `frameXXXX.ppm`, as well as a video named `out.mp4`

Command example:
``` bash
bootanim logo.png file 1280 720
bootanim logo.png folder 2160 1440
```

## Boot animation generation

The first thing to know about Blastproof boot animation is that, due to poor FAT32 read performance, we decided to find a compromise between the amount of data being stored into the generated file and the amount of data computed at each boot. In order to maintain a fluid, 60 fps animation at each boot on most hardware, we landed on this compromise:
- We only store 16 frames per second, under the form of points coordinates
- The 48 others frames per second are computed using linear interpolation at each boot
This result in the `bootanim.bin` file being only 14 megabytes in size, instead of 56 megabytes, for the actual Vystem logo and a resolution of 1920x1080.

The detailled generation procedure is as follow:
1) Locate and open the logo file in monochrom mode (with only one color channel, conversion is made by stb_image). The utility will reject any non-square logo.
2) Center the logo on a black canva the size provided by `width` and `height` arguments.
3) Scan the canva to detect all points that have their value over 127. Save these points with their coordinates. In the Vystem logo, there is over 45k points.
4) For each of these points, generate a random position in the canva, the seed doesn't have any cryptographic implication and is randomised for every new build.
5) Apply two quadratic bezier curves: one for the "explosion" (all points starting from the exact center of the screen and being scattered around the screen to their random position) and one for the logo appearence (each point is assigned a random coordinates in the logo points and will be attrected to this position from their random position).
6) Generate the selected output media and write it into the files.

It is recommanded that the image file provided is already monochrom.

## Output file structure

The outputted file named `bootanim.bin` is the format that is usable by the bootloader. The file header is structured like this (all uint64_t are in little endian):
- Signature: an array of 8 bytes containing `BootAnim` in ASCII
- The width of canva used for generating the boot animation, stored as an uint64_t
- The height of canva used for generating the boot animation, stored as an uint64_t
- Number of frame inside the boot animation, stored as an uint64_t
- Number of points inside each frame, stored as an uint64_t

Then, each frame is written inside the file. Each frame is made of <number of points per frame> points. Each points is made of two uint16_t, one for the x position and one for the y position.