Provide brief documentation of each shader

shaders/gles2/common.inc.glsl

@@ -355,6 +355,7 @@ bool splitCurveAndComputeECAAWinding(out float outWinding,
     return true;
 }
 
+/// Returns true if the slope of the line along the given vector is negative.
 bool slopeIsNegative(vec2 dp) {
     return dp.y < 0.0;
 }
@@ -451,11 +452,11 @@ bool isPartiallyCovered(vec2 p0X, vec2 dPX, float pixelCenterY) {
     return !isNearZero(dP.x) || !isNearZero(dP.y);
 }
 
-// Solve the equation:
-//
-//    x = p0x + t^2 * (p0x - 2*p1x + p2x) + t*(2*p1x - 2*p0x)
-//
-// We use the Citardauq Formula to avoid floating point precision issues.
+/// Solves the equation:
+///
+///    x = p0x + t^2 * (p0x - 2*p1x + p2x) + t*(2*p1x - 2*p0x)
+///
+/// We use the Citardauq Formula to avoid floating point precision issues.
 vec2 solveCurveT(float p0x, float p1x, float p2x, vec2 x) {
     float a = p0x - 2.0 * p1x + p2x;
     float b = 2.0 * p1x - 2.0 * p0x;
@@ -463,14 +464,11 @@ vec2 solveCurveT(float p0x, float p1x, float p2x, vec2 x) {
     return 2.0 * c / (-b - sqrt(b * b - 4.0 * a * c));
 }
 
-vec2 solveCurveT1(float p0x, float p1x, float p2x, vec2 x) {
-    float a = p0x - 2.0 * p1x + p2x;
-    float b = 2.0 * p1x - 2.0 * p0x;
-    vec2 c = p0x - x;
-    return (-b + sqrt(b * b - 4.0 * a * c)) / (2.0 * a);
-}
-
-// https://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html
+/// Applies a slight horizontal blur to reduce color fringing on LCD screens
+/// when performing subpixel AA.
+///
+/// The algorithm should be identical to that of FreeType:
+/// https://www.freetype.org/freetype2/docs/reference/ft2-lcd_filtering.html
 float lcdFilter(float shadeL2, float shadeL1, float shade0, float shadeR1, float shadeR2) {
     return LCD_FILTER_FACTOR_2 * shadeL2 +
         LCD_FILTER_FACTOR_1 * shadeL1 +
@@ -517,11 +515,3 @@ vec4 fetchPathAffineTransform(out vec2 outPathTransformExt,
                                           pathTransformExtDimensions);
     return fetchFloat4Data(pathTransformSTTexture, pathID, pathTransformSTDimensions);
 }
-
-vec2 packPathID(int pathID) {
-    return vec2(imod(pathID, 256), pathID / 256) / 255.0;
-}
-
-int unpackPathID(vec2 packedPathID) {
-    return unpackUInt16(packedPathID);
-}

shaders/gles2/demo-3d-distant-glyph.fs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders cached textures of distant glyphs in the 3D demo.
+
 precision highp float;
 
 uniform vec4 uColor;

shaders/gles2/demo-3d-distant-glyph.vs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders cached textures of distant glyphs in the 3D demo.
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/demo-3d-monument.fs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders the monument surface in the 3D demo.
+
 precision mediump float;
 
 uniform vec3 uLightPosition;

shaders/gles2/demo-3d-monument.vs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders the monument surface in the 3D demo.
+
 precision mediump float;
 
 uniform mat4 uProjection;

shaders/gles2/direct-3d-curve.vs.glsl

@@ -8,6 +8,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! A version of `direct-curve` that takes each vertex's Z value from the
+//! transform instead of the path ID.
+//!
+//! FIXME(pcwalton): For CSS 3D transforms, I think `direct-curve` will need
+//! to do what this shader does. Perhaps these two shaders should be unified…
+
 precision highp float;
 
 uniform mat4 uTransform;
@@ -26,7 +32,6 @@ attribute float aSign;
 attribute float aNormalAngle;
 
 varying vec4 vColor;
-varying vec2 vPathID;
 varying vec2 vTexCoord;
 varying float vSign;
 
@@ -47,7 +52,6 @@ void main() {
     gl_Position = uTransform * vec4(position, 0.0, 1.0);
 
     vColor = fetchFloat4Data(uPathColors, pathID, uPathColorsDimensions);
-    vPathID = packPathID(pathID);
     vTexCoord = vec2(aTexCoord) / 2.0;
     vSign = aSign;
 }

shaders/gles2/direct-3d-interior.vs.glsl

@@ -8,6 +8,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! A version of `direct-interior` that takes each vertex's Z value from the
+//! transform instead of the path ID.
+//!
+//! FIXME(pcwalton): For CSS 3D transforms, I think `direct-interior` will need
+//! to do what this shader does. Perhaps these two shaders should be unified…
+
 precision highp float;
 
 uniform mat4 uTransform;
@@ -24,7 +30,6 @@ attribute float aPathID;
 attribute float aNormalAngle;
 
 varying vec4 vColor;
-varying vec2 vPathID;
 
 void main() {
     int pathID = int(aPathID);
@@ -43,5 +48,4 @@ void main() {
     gl_Position = uTransform * vec4(position, 0.0, 1.0);
 
     vColor = fetchFloat4Data(uPathColors, pathID, uPathColorsDimensions);
-    vPathID = packPathID(pathID);
 }

shaders/gles2/direct-curve.fs.glsl

@@ -8,7 +8,16 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-// This shader implements the quadratic Loop-Blinn formulation.
+//! Implements the quadratic Loop-Blinn formulation to render curved parts of
+//! the mesh.
+//!
+//! This shader performs no antialiasing; if you want antialiased output from
+//! this shader, use MSAA with sample-level shading (GL 4.x) or else perform
+//! SSAA by rendering to a higher-resolution framebuffer and downsampling (GL
+//! 3.x and below).
+//!
+//! If you know your mesh has no curves (i.e. it consists solely of polygons),
+//! then you don't need to run this shader.
 
 precision highp float;
 

shaders/gles2/direct-curve.vs.glsl

@@ -8,6 +8,17 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Implements the quadratic Loop-Blinn formulation to render curved parts of
+//! the mesh.
+//!
+//! This shader performs no antialiasing; if you want antialiased output from
+//! this shader, use MSAA with sample-level shading (GL 4.x) or else perform
+//! SSAA by rendering to a higher-resolution framebuffer and downsampling (GL
+//! 3.x and below).
+//!
+//! If you know your mesh has no curves (i.e. it consists solely of polygons),
+//! then you don't need to run this shader.
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/direct-interior.fs.glsl

@@ -8,6 +8,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders polygonal portions of a mesh.
+//!
+//! Typically, you will run this shader before running `direct-curve`.
+//! Remember to enable the depth test with a `GREATER` depth function for optimal
+//! performance.
+
 precision highp float;
 
 varying vec4 vColor;

shaders/gles2/direct-interior.vs.glsl

@@ -8,6 +8,12 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders polygonal portions of a mesh.
+//!
+//! Typically, you will run this shader before running `direct-curve`.
+//! Remember to enable the depth test with a `GREATER` depth function for optimal
+//! performance.
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/ecaa-curve.vs.glsl

@@ -8,6 +8,22 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Implements *edge coverage antialiasing* (ECAA) for curved path segments.
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! Use this shader only when *all* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. The paths are relatively small, so overdraw is not a concern.
+//!    (Otherwise, consider the MCAA shaders.)
+//!
+//! 3. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider `ecaa-transformed-curve`.)
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/ecaa-line.vs.glsl

@@ -8,6 +8,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Implements *edge coverage antialiasing* (ECAA) for straight-line path
+//! segments.
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. The paths are relatively small, so overdraw is not a concern.
+//!    (Otherwise, consider the MCAA shaders.)
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/ecaa-transformed-curve.vs.glsl

@@ -8,6 +8,26 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Implements *edge coverage antialiasing* (ECAA) for curved path segments,
+//! performing splitting as necessary.
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! This is a two-pass shader. It must be run twice, first with `uPassIndex`
+//! equal to 0, and then with `uPassIndex` equal to 1.
+//!
+//! Use this shader only when *all* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. The paths are relatively small, so overdraw is not a concern.
+//!    (Otherwise, consider the MCAA shaders.)
+//!
+//! 3. Your transform contains perspective, rotation, or skew. (Otherwise,
+//!    consider `ecaa-curve`, which is faster and saves a pass.)
+
 precision highp float;
 
 uniform mat4 uTransform;

shaders/gles2/mcaa-cover.fs.glsl

@@ -8,6 +8,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs the conservative coverage step for *mesh coverage antialiasing*
+//! (MCAA).
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider the ECAA shaders.)
+
 precision highp float;
 
 varying vec2 vHorizontalExtents;

shaders/gles2/mcaa-cover.vs.glsl

@@ -8,6 +8,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs the conservative coverage step for *mesh coverage antialiasing*
+//! (MCAA).
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider the ECAA shaders.)
+
 precision highp float;
 
 uniform vec4 uTransformST;

shaders/gles2/mcaa-curve.vs.glsl

@@ -8,6 +8,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders the curved edges of paths when performing *mesh coverage
+//! antialiasing* (MCAA).
+//!
+//! This shader expects to render to the red channel of a floating point color
+//! buffer. Half precision floating point should be sufficient.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider the ECAA shaders.)
+
 precision highp float;
 
 uniform vec4 uTransformST;

shaders/gles2/mcaa-line.vs.glsl

@@ -8,6 +8,17 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders the straight line segments of paths when performing *mesh coverage
+//! antialiasing* (MCAA).
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are only rendering monochrome paths such as text. (Otherwise,
+//!    consider `mcaa-multi`.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider the ECAA shaders.)
+
 precision highp float;
 
 uniform vec4 uTransformST;

shaders/gles2/mcaa-multi.fs.glsl

@@ -8,6 +8,21 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders paths when performing multicolor *mesh coverage antialiasing*
+//! (MCAA). This one shader handles both lines and curves.
+//!
+//! This shader expects to render to a standard RGB color buffer.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are rendering multiple multicolor paths. (Otherwise, consider the
+//!    other MCAA shaders, which render with higher quality.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider repartitioning the path to
+//!    generate a new mesh, or, alternatively, use the direct Loop-Blinn
+//!    shaders.)
+
 precision highp float;
 
 varying vec4 vUpperEndpoints;

shaders/gles2/mcaa-multi.vs.glsl

@@ -8,6 +8,21 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders paths when performing multicolor *mesh coverage antialiasing*
+//! (MCAA). This one shader handles both lines and curves.
+//!
+//! This shader expects to render to a standard RGB color buffer.
+//!
+//! Use this shader only when *both* of the following are true:
+//!
+//! 1. You are rendering multiple multicolor paths. (Otherwise, consider the
+//!    other MCAA shaders, which render with higher quality.)
+//!
+//! 2. Your transform is only a scale and/or translation, not a perspective,
+//!    rotation, or skew. (Otherwise, consider repartitioning the path to
+//!    generate a new mesh, or, alternatively, use the direct Loop-Blinn
+//!    shaders.)
+
 #define MAX_SLOPE   10.0
 
 precision highp float;

shaders/gles2/ssaa-subpixel-resolve.fs.glsl

@@ -8,6 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs subpixel antialiasing for LCD screens by converting a
+//! 3x-oversampled RGBA color buffer to an RGB framebuffer, applying the
+//! FreeType color defringing filter as necessary.
+
 precision mediump float;
 
 uniform sampler2D uSource;

shaders/gles2/xcaa-curve.fs.glsl

@@ -8,6 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs analytic *coverage antialiasing* (XCAA) in order to render curves.
+//!
+//! Given endpoints P0 and P2 and control point P1, this shader expects that
+//! P0.x <= P1.x <= P2.x.
+
 precision highp float;
 
 varying vec4 vEndpoints;

shaders/gles2/xcaa-line.fs.glsl

@@ -8,6 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs analytic *coverage antialiasing* (XCAA) in order to render lines.
+//!
+//! This shader expects that P1 is to the right of P0.
+
 precision highp float;
 
 varying vec4 vEndpoints;

shaders/gles2/xcaa-mono-resolve.fs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders a single-channel alpha coverage buffer to an RGB framebuffer.
+
 precision mediump float;
 
 uniform vec4 uBGColor;

shaders/gles2/xcaa-mono-resolve.vs.glsl

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Renders a single-channel alpha coverage buffer to an RGB framebuffer.
+
 precision highp float;
 
 uniform vec4 uTransformST;

shaders/gles2/xcaa-mono-subpixel-resolve.fs.glsl

@@ -8,6 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs subpixel antialiasing for LCD screens by converting a
+//! 3x-oversampled single-channel color buffer to an RGB framebuffer, applying
+//! the FreeType color defringing filter as necessary.
+
 precision mediump float;
 
 uniform vec4 uBGColor;

shaders/gles2/xcaa-mono-subpixel-resolve.vs.glsl

@@ -8,6 +8,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Performs subpixel antialiasing for LCD screens by converting a
+//! 3x-oversampled single-channel color buffer to an RGB framebuffer, applying
+//! the FreeType color defringing filter as necessary.
+
 precision highp float;
 
 uniform vec4 uTransformST;