From a338a2f1b28ce0d2a5215effafec6ed299f8665e Mon Sep 17 00:00:00 2001
From: Simon Schneegans <code@simonschneegans.de>
Date: Wed, 22 Dec 2021 05:54:58 +0100
Subject: [PATCH] :memo: Add some comments

---
 src/extension/FireShader.js     | 13 ++++++++-----
 src/extension/shaderSnippets.js | 27 +++++++++++++++++++++++++--
 2 files changed, 33 insertions(+), 7 deletions(-)

diff --git a/src/extension/FireShader.js b/src/extension/FireShader.js
index ced910f..e1af97c 100644
--- a/src/extension/FireShader.js
+++ b/src/extension/FireShader.js
@@ -29,7 +29,7 @@ var FireShader = GObject.registerClass({Properties: {}, Signals: {}},
 
     // Load the gradient values from the settings. We directly inject the values in the
     // GLSL code below. The shader is compiled once for each window-closing anyways. In
-    // the future, we my want to prevent this frequent recompilations of shaders,
+    // the future, we may want to prevent this frequent recompilations of shaders,
     // though.
     const gradient = [];
     for (let i = 1; i <= 5; i++) {
@@ -40,6 +40,8 @@ var FireShader = GObject.registerClass({Properties: {}, Signals: {}},
 
 
     this.set_shader_source(`
+
+      // Inject some common shader snippets.
       ${shaderSnippets.standardUniforms()}
       ${shaderSnippets.noise()}
       ${shaderSnippets.effectMask()}
@@ -51,6 +53,7 @@ var FireShader = GObject.registerClass({Properties: {}, Signals: {}},
       const vec2  FIRE_SCALE = vec2(400, 600) * ${settings.get_double('flame-scale')};
       const float FIRE_SPEED = ${settings.get_double('flame-movement-speed')};
 
+      // This maps the input value from [0..1] to a color from the gradient.
       vec4 getFireColor(float v) {
         const float steps[5] = float[](0.0, 0.2, 0.35, 0.5, 0.8);
         const vec4 colors[5] = vec4[](
@@ -77,12 +80,12 @@ var FireShader = GObject.registerClass({Properties: {}, Signals: {}},
 
       void main(void) {
 
-        // Get a noise value.
+        // Get a noise value which moves vertically in time.
         vec2 uv = cogl_tex_coord_in[0].st * vec2(uSizeX, uSizeY) / FIRE_SCALE;
         uv.y += uTime * FIRE_SPEED;
         float noise = perlinNoise(uv, 10.0, 5, 0.5);
 
-        // Modulate noise by mask.
+        // Modulate noise by effect mask.
         vec2 effectMask = effectMask(HIDE_TIME, FADE_WIDTH, EDGE_FADE);
         noise *= effectMask.y;
 
@@ -90,10 +93,10 @@ var FireShader = GObject.registerClass({Properties: {}, Signals: {}},
         vec4 fire = getFireColor(noise);
         fire.rgb *= fire.a;
 
-        // Get window texture.
+        // Get the window texture and fade it according to the effect mask.
         cogl_color_out = texture2D(uTexture, cogl_tex_coord_in[0].st) * effectMask.x;
 
-        // Add fire.
+        // Add the fire to the window.
         cogl_color_out += fire;
       }
     `);
diff --git a/src/extension/shaderSnippets.js b/src/extension/shaderSnippets.js
index 2b0b48b..8e52391 100644
--- a/src/extension/shaderSnippets.js
+++ b/src/extension/shaderSnippets.js
@@ -13,6 +13,16 @@
 
 'use strict';
 
+//////////////////////////////////////////////////////////////////////////////////////////
+// These functions return strings which can be injected to GLSL shader code.            //
+//////////////////////////////////////////////////////////////////////////////////////////
+
+// These should be included in every shader.
+// uTexture:    Contains the texture of the window.
+// uProgress:   A value which transitions from 0 to 1 during the entire animation.
+// uTime:       A steadily increasing value in seconds.
+// uSizeX:      The horizontal size of uTexture in pixels.
+// uSizeY:      The vertical size of uTexture in pixels.
 function standardUniforms() {
   return `
   uniform sampler2D uTexture;
@@ -23,14 +33,17 @@ function standardUniforms() {
   `;
 }
 
-// The noise implementation is from https://www.shadertoy.com/view/3tcBzH
-// (CC-BY-NC-SA).
+// The noise implementation is from https://www.shadertoy.com/view/3tcBzH (CC-BY-NC-SA).
 function noise() {
   return `
   float rand(vec2 co) {
     return fract(sin(dot(co.xy ,vec2(12.9898,78.233))) * 43758.5453);
   }
 
+  vec2 rand2(vec2 co) {
+    return vec2(rand(co), rand(co + vec2(12.9898,78.233)));
+  }
+
   float hermite(float t) {
     return t * t * (3.0 - 2.0 * t);
   }
@@ -69,6 +82,16 @@ function noise() {
   `;
 }
 
+// This method requires the uniforms from standardUniforms() to be available.
+// It returns two values: The first is an alpha value which can be used for the window
+// texture. This gradually dissolves the window from top to bottom. The second can be used
+// to mask any effect, it will be most opaque where the window is currently fading and
+// gradually dissolve to zero over time.
+// hideTime:      A value in [0..1]. It determines the percentage of the animation which
+//                is spent for hiding the window. 1-hideTime will be spent thereafter for
+//                dissolving the effect mask.
+// fadeWidth:     The relative size of the window-hiding gradient in [0..1].
+// edgeFadeWidth: The pixel width of the effect fading range at the edges of the window.
 function effectMask() {
   return `
   vec2 effectMask(float hideTime, float fadeWidth, float edgeFadeWidth) {