Chapter 811: Debugging GLSL (Manual)

Core Idea

Practical tricks for isolating GLSL shader bugs by forcing solid output colors and visualizing intermediate values (normals, UVs, matrices) as colors or in a debugger to narrow down whether a problem is in the vertex or fragment stage.

Key Concepts

• Force a solid gl_FragColor: set the fragment shader to output a flat color first — if the shape appears, the bug is in the fragment logic (textures, uniforms), not geometry/vertex setup.
• Visualize normals/UVs as color: remap a -1..1 normal or 0..1 UV into color range (value * 0.5 + 0.5) and output it, to sanity-check it visually against known-good values.
• fract() for repeated UVs: wrap texture coordinates back into 0..1 before visualizing, useful when texture.repeat is greater than 1.
• Matrix sanity checks: break after renderer.render() and inspect camera/object world and projection matrices in the debugger for NaNs or wildly out-of-scale values.
• Varyings to expose vertex-shader values: pass a suspect vertex-shader value to the fragment shader via a varying so it can be visualized the same way.
• Simplify first: fall back to MeshBasicMaterial or a minimal vertex shader to confirm the geometry itself is correct before debugging custom shader logic.

Code Examples

void main() {
  // ...
  gl_FragColor = vec4(1, 0, 0, 1); // force solid red
}

• What it demonstrates: the first diagnostic step — force a solid fragment color to check whether anything renders at all.

Key Takeaways

1. Force gl_FragColor to a solid color first to check whether the fragment shader is even the source of the problem.
2. Remap suspect values (normals, UVs) into the 0–1 range and output them as color to visually verify them against expectations.
3. If nothing draws even with a solid fragment color, suspect the vertex stage — check camera/object matrices for NaNs in a debugger.
4. Fall back to MeshBasicMaterial or a minimal vertex shader to isolate whether a bug is in your custom vertex logic or elsewhere.

Connects To

• CanvasTexture / DataTexture: useful as known-good textures when isolating texture-related shader bugs.
• MeshBasicMaterial: the simplification target when isolating vertex-stage issues.