From 013b208d2b30c112c69bd28c32bdd203b8ff1684 Mon Sep 17 00:00:00 2001
From: Pascal Engeler <engelerp@phys.ethz.ch>
Date: Tue, 7 Sep 2021 14:29:38 +0200
Subject: [PATCH] documented on

---
 README.md | 161 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 140 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 98b8b1e..a26d6d0 100644
--- a/README.md
+++ b/README.md
@@ -959,14 +959,16 @@ Represents a message to one of the components
 - Construct object using a message, e.g. `WAVEMESSAGE::RESET_DAMPING` or `PATTERNMESSAGE::PATTERN_SSH` (see `*MESSAGE` types in [enums](#enums-enumshpp))
 - Read messages using the pattern
 ```c++
-Message m = getSomeMessage();
+Message m (getSomeMessage());
 if(m.target == MESSAGETARGET::WAVE){
     WAVEMESSAGE message = std::get<WAVEMESSAGE>(m.message);
     switch(message){
         case WAVEMESSAGE::RESET_WAVE:
             //process RESET_WAVE here
+            break;
         case WAVEMESSAGE::RESET_DAMPING:
             //process RESET_DAMPING here
+            break;
         default:
             break;
     }
@@ -1011,7 +1013,8 @@ Handles the placement of predefined patterns.
 
 **Usage**
 
-Todo
+- Construct object
+- Call `update` once per frame
 
 **Constructors and Destructors**
 
@@ -1055,7 +1058,7 @@ Stores `SDL_Event`s in a more convenient way.
 
 **Usage**
 
-Todo
+- Use a [`PeventFactory`](#peventfactory-peventhpp-peventcpp) to construct objects of this type
 
 **Constructors and Destructors**
 
@@ -1093,7 +1096,8 @@ Constructs `Pevent` objects.
 
 **Usage**
 
-Todo
+- Construct object using non-trivial constructor
+- call `operator()` to construct a `Pevent` from an `SDL_Event`
 
 **Constructors and Destructors**
 
@@ -1134,7 +1138,12 @@ Represents a GLSL shader.
 
 **Usage**
 
-Todo
+- Construct object from vertex and fragment shader sources, e.g.
+```c++
+Shader stepshader((shader_path_ + "stepwave.vert").c_str(), (shader_path_ + "stepwave.frag").c_str());
+```
+- Make the shader current by calling `use()` (before setting uniforms and rendering)
+- Set uniforms using the `set*` functions
 
 **Constructors and Destructors**
 
@@ -1218,7 +1227,8 @@ The drawcalls are issued at the very end of the update-cycle, all in one.
 
 **Usage**
 
-Todo
+- Construct object from a `Toolbox`. Note that the toolbox must be fully initialized.
+- Once per frame, call `update`
 
 **Constructors and Destructors**
 
@@ -1297,7 +1307,8 @@ Keeps track of the time since the last user input, and resets the state of the a
 
 **Usage**
 
-Todo
+- Construct object with the desired timeout
+- After the `events` list of the toolbox has been filled, and before anyone else gets access to the toolbox, call `update`
 
 **Constructors and Destructors**
 
@@ -1337,7 +1348,9 @@ The Toolbox is passed from one component to the next, so each component has all
 
 **Usage**
 
-Todo
+- Construct object with all necessary parameters
+- Finish initialization by having a `WaveHandler` call `generate_and_transfer_textures` on this object
+- At the beginning of every frame, call `newFrame`
 
 **Constructors and Destructors**
 
@@ -1375,7 +1388,14 @@ Handles simulation and rendering of the wave.
 
 **Usage**
 
-Todo
+- Construct object
+- Call `initialize`
+- Initialize the toolbox using `generate_and_transfer_textures`
+- In each frame, after the GUI has been updated, call `update`
+- Once each module has processed the toolbox, step the wave
+  - Call `prepare_step`
+  - Then call `step` with the desired number of double steps
+- Just before the GUI is rendered, call `render`
 
 **Constructors and Destructors**
 
@@ -1500,23 +1520,33 @@ Only relevant members are listed
 This class predates the Toolbox and is not yet well integrated into the flow. All member functions assume the object is fully initialized.
 
 ## Enums ([enums.hpp](include/enums.hpp))
+
+### Global States
+
 **`MSTATE`** (Mouse State): `IMMEDIATE` (Spielen), `PLACE`, `DELETE`, `MOVE`, `DRAW` (Zeichnen), `Erase` (Radieren)
 
 **`SSTATE`** (Source State): `RUN`, `STOP`
 
 **`GSTATE`** (Game State): `RUN`, `FREEZE`, `EXIT`
 
-**`MESSAGETARGET`** (Possible targets for messages): `BLOCKCHAIN`, `DRAWER`, `GUI`, `WAVE`, `PATTERN`
+### Message Targets
+
+**`MESSAGETARGET`**: `BLOCKCHAIN`, `DRAWER`, `GUI`, `WAVE`, `PATTERN`
+
+### Message Types
+
+**`BLOCKCHAINMESSAGE`**: `CLEAR`, `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL`
+- Note: `PATTERN_*` messages don't do anything, they are no longer listened for by the `SlimBlockchainHandler`.
 
-**`BLOCKCHAINMESSAGE`** (Possible messages to `SlimBlockchainHandler`): `CLEAR`, `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL`
+**`PATTERNMESSAGE`**: `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL`
 
-**`PATTERNMESSAGE`** (Possible messages to `PatternHandler`): `PATTERN_SINGLESLIT`, `PATTERN_DOUBLESLIT`, `PATTER_LATTICE`, `PATTERN_WAVEGUIDE`, `PATTERN_SSH`, `PATTERN_FRESNEL`
+**`DRAWERMESSAGE`**: `CLEAR`
 
-**`DRAWERMESSAGE`** (Possible messages to `DrawingHandler`): `CLEAR`
+**`GUIMESSAGE`**: n/a
 
-**`GUIMESSAGE`** (Possible messages to `GuiHandler`): n/a
+**`WAVEMESSAGE`**: `RESET_WAVE`, `RESET_DAMPING`, `DIMENSION_2D`, `DIMENSION_3D`, `DEBUG_ON`, `DEBUG_OFF`
 
-**`WAVEMESSAGE`** (Possible messages to `WaveHandler`): `RESET_WAVE`, `RESET_DAMPING`, `DIMENSION_2D`, `DIMENSION_3D`, `DEBUG_ON`, `DEBUG_OFF`
+### Pevent Types
 
 **`PEVENTTYPE`** (Possible `Pevent` types): `DOWN`, `UP`, `MOVE`, `OTHER`
 
@@ -1536,17 +1566,106 @@ The ImGui library has been customized in the following way:
     - To run `ImGui` demos, one must revert the change to `ImGui_ImplSDL2_NewFrame` (see comments).
 
 ## GLSL Shaders
-**`combine_damping`**
+### **[`combine_damping.vert`](shaders/combine_damping.vert) [`combine_damping.frag`](shaders/combine_damping.frag)**
 
-**`copy_texture`**
+This shader takes two damping textures and renders the combination of the two. Combination is performed using `min`.
 
-**`draw`**
+Layout:
+```glsl
+layout (location = 0) in vec3 verCoords;
+layout (location = 1) in vec2 texCoords;
+```
+
+Uniforms:
+```glsl
+uniform sampler2D tex_damping_static; //static damping
+uniform sampler2D tex_damping_dynamic; //dynamic damping
+```
 
-**`draw_blocks`**
+### **[`copy_texture.vert`](shaders/copy_texture.vert) [`copy_texture.frag`](shaders/copy_texture.frag)**
 
-**`render2d`**
+This shader copies a `source_texture` to the output
 
-**`stepwave`**
+Layout:
+```glsl
+layout (location = 0) in vec2 verCoords;
+layout (location = 1) in vec2 texCoords;
+```
+
+Uniforms:
+```glsl
+uniform sampler2D source_texture;
+```
+
+### **[`draw.vert`](shaders/draw.vert) [`draw.frag`](shaders/draw.frag)**
+
+This shader is used to draw, in the sense of "Zeichnen" and "Radieren".
+
+Layout:
+```glsl
+layout (location = 0) in vec3 verCoords;
+```
+
+Uniforms:
+```glsl
+uniform sampler2D source_texture;
+```
+
+### **[`draw_blocks.vert`](shaders/draw_blocks.vert) [`draw_blocks.frag`](shaders/draw_blocks.frag)**
+
+This shader is used to draw blocks (see `SlimBlockchainHandler`).
+
+Layout:
+```glsl
+layout (location = 0) in vec2 verCoords;
+layout (location = 1) in vec2 texCoords;
+```
+
+Uniforms:
+```glsl
+uniform float color_multiplier;
+uniform sampler2D source_texture;
+```
+
+### **[`render2d.vert`](shaders/render2d.vert) [`render2d.frag`](shaders/render2d.frag)**
+
+This shader is used to render the current wave state with a custom colour palette, along with the current damping.
+
+Layout:
+```glsl
+layout (location = 0) in vec3 verCoords;
+layout (location = 1) in vec2 texCoords;
+```
+
+Uniforms:
+```glsl
+uniform sampler2D tex_wave; //wave
+uniform sampler2D tex_damp; //damping
+uniform sampler1D tex_palette; //colour palette
+```
+
+### **[`stepwave.vert`](shaders/stepwave.vert) [`stepwave.frag`](shaders/stepwave.frag)**
+
+This shader takes an input wave and damping texture, and renders the state of the wave one timestep in the future.
+
+Layout:
+```glsl
+layout (location = 0) in vec3 verCoords;
+layout (location = 1) in vec2 texCoords;
+```
+
+Uniforms:
+```glsl
+uniform float dx;
+uniform float dy;
+uniform float c1;
+uniform float c2;
+uniform float t;
+uniform float amplitude;
+uniform float frequency;
+uniform sampler2D tex_wave;
+uniform sampler2D tex_damp;
+```
 
 ## Workflow: Sample `main` function
 Todo
\ No newline at end of file
-- 
GitLab