From e4b531f3a06e73118fbb02e2339902902af53bd9 Mon Sep 17 00:00:00 2001
From: Patrick Walton <pcwalton@mimiga.net>
Date: Thu, 26 Oct 2017 20:30:47 -0700
Subject: [PATCH] Do some work on shader documentation

---
 shaders/gles2/blit.fs.glsl    |  2 ++
 shaders/gles2/blit.vs.glsl    |  7 ++++++
 shaders/gles2/common.inc.glsl | 46 ++++++++++++++++++++++++++++-------
 3 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/shaders/gles2/blit.fs.glsl b/shaders/gles2/blit.fs.glsl
index c73862fe..03667e4d 100644
--- a/shaders/gles2/blit.fs.glsl
+++ b/shaders/gles2/blit.fs.glsl
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/// A trivial shader that does nothing more than blit a texture.
+
 precision mediump float;
 
 uniform sampler2D uSource;
diff --git a/shaders/gles2/blit.vs.glsl b/shaders/gles2/blit.vs.glsl
index 9f952bc9..55b5d8f0 100644
--- a/shaders/gles2/blit.vs.glsl
+++ b/shaders/gles2/blit.vs.glsl
@@ -8,14 +8,21 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+/// A trivial shader that does nothing more than blit a texture.
+
 precision mediump float;
 
+/// A 3D transform to apply to the scene.
 uniform mat4 uTransform;
+/// A fixed scaling to be applied to the texture coordinates.
 uniform vec2 uTexScale;
 
+/// The 2D vertex position.
 attribute vec2 aPosition;
+/// The texture coordinate.
 attribute vec2 aTexCoord;
 
+/// The scaled texture coordinate.
 varying vec2 vTexCoord;
 
 void main() {
diff --git a/shaders/gles2/common.inc.glsl b/shaders/gles2/common.inc.glsl
index 9783e79a..d58fc8e3 100644
--- a/shaders/gles2/common.inc.glsl
+++ b/shaders/gles2/common.inc.glsl
@@ -22,33 +22,51 @@
 
 precision highp float;
 
-// https://stackoverflow.com/a/36078859
+/// Computes `ia % ib`.
+///
+/// This function is not in OpenGL ES 2 but can be polyfilled.
+/// See: https://stackoverflow.com/a/36078859
 int imod(int ia, int ib) {
     float a = float(ia), b = float(ib);
     float m = a - floor((a + 0.5) / b) * b;
     return int(floor(m + 0.5));
 }
 
-bool xor(bool a, bool b) {
-    return (a && !b) || (!a && b);
-}
-
+/// Returns the determinant of the 2D matrix [a, b].
+/// This is equivalent to: cross(vec3(a, 0.0), vec3(b, 0.0)).z
 float det2(vec2 a, vec2 b) {
     return a.x * b.y - b.x * a.y;
 }
 
+/// Returns the *2D* result of transforming the given 2D point with the given 4D transformation
+/// matrix.
+///
+/// The z and w coordinates are treated as 0.0 and 1.0, respectively.
 vec2 transformVertexPosition(vec2 position, mat4 transform) {
     return (transform * vec4(position, 0.0, 1.0)).xy;
 }
 
+/// Returns the 2D result of transforming the given 2D position by the given ST-transform.
+///
+/// An ST-transform is a combined 2D scale and translation, where the (x, y) coordinates specify
+/// the scale and and the (z, w) coordinates specify the translation.
 vec2 transformVertexPositionST(vec2 position, vec4 stTransform) {
     return position * stTransform.xy + stTransform.zw;
 }
 
-/// pathHints.x: xHeight
-/// pathHints.y: hintedXHeight
-/// pathHints.z: stemHeight
-/// pathHints.w: hintedStemHeight
+/// Interpolates the given 2D position in the vertical direction using the given ultra-slight
+/// hints.
+///
+/// Similar in spirit to the `IUP[y]` TrueType command, but minimal.
+///
+///     pathHints.x: xHeight
+///     pathHints.y: hintedXHeight
+///     pathHints.z: stemHeight
+///     pathHints.w: hintedStemHeight
+///
+/// TODO(pcwalton): Do something smarter with overshoots and the blue zone.
+/// TODO(pcwalton): Support interpolating relative to arbitrary horizontal stems, not just the
+/// baseline, x-height, and stem height.
 vec2 hintPosition(vec2 position, vec4 pathHints) {
     float y;
     if (position.y >= pathHints.z) {
@@ -65,18 +83,28 @@ vec2 hintPosition(vec2 position, vec4 pathHints) {
     return vec2(position.x, y);
 }
 
+/// Converts the given 2D position in clip space to device pixel space (with origin in the lower
+/// left).
 vec2 convertClipToScreenSpace(vec2 position, ivec2 framebufferSize) {
     return (position + 1.0) * 0.5 * vec2(framebufferSize);
 }
 
+/// Converts the given 2D position in device pixel space (with origin in the lower left) to clip
+/// space.
 vec2 convertScreenToClipSpace(vec2 position, ivec2 framebufferSize) {
     return position / vec2(framebufferSize) * 2.0 - 1.0;
 }
 
+/// Packs the given path ID into a floating point value suitable for storage in the depth buffer.
+/// This function returns values in clip space (i.e. what `gl_Position` is in).
 float convertPathIndexToViewportDepthValue(int pathIndex) {
     return float(pathIndex) / float(MAX_PATHS) * 2.0 - 1.0;
 }
 
+/// Packs the given path ID into a floating point value suitable for storage in the depth buffer.
+///
+/// This function returns values in window space (i.e. what `gl_FragDepth`/`gl_FragDepthEXT` is
+/// in).
 float convertPathIndexToWindowDepthValue(int pathIndex) {
     return float(pathIndex) / float(MAX_PATHS);
 }