From 082a85720bafe6825bc5bd386f37832c05e5c93b Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Wed, 8 Sep 2021 10:51:21 +0200
Subject: [PATCH] added file format description

---
 README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7c1b533..1deab6c 100644
--- a/README.md
+++ b/README.md
@@ -31,7 +31,61 @@ Resources are organized in a single folder called `ft_top`. It contains the foll
 The program accesses these resources at runtime.
 
 ## File Formats
-Todo
+This section describes the file formats external files are expected to follow.
+
+### GUI Images
+Gui Images, such as the button textures, are loaded using `stbi`. The exact calls can be found in `GuiHandler::load_image_to_texture_`. The important parts are
+```c++
+data = stbi_load(file.c_str(), &width, &height, &nrChannels, STBI_rgb_alpha);
+//...
+glTexImage2D(GL_TEXTURE_2D, 0, GL_RGB, width, height, 0, GL_RGBA, GL_UNSIGNED_BYTE, data);
+```
+Images are expected to be RGBA, i.e. to have an alpha channel. Not being very fluent in image formats, I believe this is the only limitation. 
+To be save, I'll state that images are expected to be loadable with the above calls.
+
+### Damping Textures
+Damping Textures, such as those used by `PatternHandler` and `WaveHandler`, are 2D textures and they are composed of two files: 
+- a `.conf` file that describes several properties of the texture,
+- a `.texture` file that contains the texture data.
+These two files are expected to be in the same directory. By convention, the name of the texture does never include any file extensions. 
+Thus a texture with name `my_damping_map` will consist of the two files `my_damping_map.conf` and `my_damping_map.texture`.
+
+A sample `.conf` file with comments is shown below. 
+Its screen dimensions are what the FocusTerra touchscreen supports natively. 
+Note that the comments are not allowed in real files.
+```c++
+3840 //screen width in pixels
+2160 //screen height in pixels
+4440 //texture width in texels
+3360 //texture height in texels
+0    //screen offset left in texels
+600  //screen offset right in texels
+600  //screen offset bottom in texels
+600  //screen offset top in texels
+```
+
+The meaning of the offsets is the following: In this application, we simulate a larger region than what's drawn on the screen. 
+Thus what's drawn on the screen is just a rectangular region within the texture. 
+To describe the placement of this region, we use the number of pixels between the screen region and the texture boundaries in all four directions.
+That's what these offsets describe.
+
+Note that only if all damping textures agree with the dimensions specified in the application, will the program run correctly. Anything else will give you UB.
+
+A `.texture` file contains `4 * texture_width * texture_height` floating point values. Each group of four is to be interpreted as the RGBA values of a single texel.
+Successive values are delimited with a single space. After each `4 * texture_width` values, a newline is expected.
+
+Be aware of different axis conventions here. 
+Images typically have the origin in the lower left corner with y-axis pointing upwards, while OpenGL has the origin in the top left corner with the y-axis pointing **downwards**. 
+This means that the first four floats in the file describe the top left texel, and the first `4 * texture_width` values describe the top most row of texels.
+This is only important when using images that are asymmetric with respect to the horizontal. 
+If it is a problem, consider either flipping the image, or look into calling `stbi_set_flip_vertically_on_load(true)`. This can also be taken care of shader side.
+
+### Colour Palettes
+A colour palette, like that loaded by `WaveHandler::load_palette_` and used to draw the waves in a custom colour scheme, is a 1D texture. 
+Most of the conventions for [Damping Textures](#damping-textures) also apply here. The differences are:
+- The `.conf` file only contains one integer, the number of texels in the texture
+- The `.texture` file still contains four space-denominated floats per texel (RGBA), but there is a newline after each texel
+As things stand now, the lowest wave point maps to the first texel, and the highest wave point maps to the last texel.
 
 # Building the Project
 ## Windows
-- 
GitLab