shader-dev

shader-dev

Shader Craft

A unified skill covering 36 GLSL shader techniques (ShaderToy-compatible) for real-time visual effects.

Invocation

/shader-dev <request>

$ARGUMENTS contains the user's request (e.g. "create a raymarched SDF scene with soft shadows").

Skill Structure

shader-dev/
├── SKILL.md                      # Core skill (this file)
├── techniques/                   # Implementation guides (read per routing table)
│   ├── ray-marching.md           # Sphere tracing with SDF
│   ├── sdf-3d.md                 # 3D signed distance functions
│   ├── lighting-model.md         # PBR, Phong, toon shading
│   ├── procedural-noise.md       # Perlin, Simplex, FBM
│   └── ...                       # 34 more technique files
└── reference/                    # Detailed guides (read as needed)
    ├── ray-marching.md           # Math derivations & advanced patterns
    ├── sdf-3d.md                 # Extended SDF theory
    ├── lighting-model.md         # Lighting math deep-dive
    ├── procedural-noise.md       # Noise function theory
    └── ...                       # 34 more reference files

How to Use

• Read the Technique Routing Table below to identify which technique(s) match the user's request

• Read the relevant file(s) from techniques/ — each file contains core principles, implementation steps, and complete code templates

• If you need deeper understanding (math derivations, advanced patterns), follow the reference link at the bottom of each technique file to reference/

• Apply the WebGL2 Adaptation Rules below when generating standalone HTML pages

Technique Routing Table

User wants to create... Primary technique Combine with

3D objects / scenes from math ray-marching + sdf-3d lighting-model, shadow-techniques

Complex 3D shapes (booleans, blends) csg-boolean-operations sdf-3d, ray-marching

Infinite repeating patterns in 3D domain-repetition sdf-3d, ray-marching

Organic / warped shapes domain-warping procedural-noise

Fluid / smoke / ink effects fluid-simulation multipass-buffer

Particle effects (fire, sparks, snow) particle-system procedural-noise, color-palette

Physically-based simulations simulation-physics multipass-buffer

Game of Life / reaction-diffusion cellular-automata multipass-buffer, color-palette

Ocean / water surface water-ocean atmospheric-scattering, lighting-model

Terrain / landscape terrain-rendering atmospheric-scattering, procedural-noise

Clouds / fog / volumetric fire volumetric-rendering procedural-noise, atmospheric-scattering

Sky / sunset / atmosphere atmospheric-scattering volumetric-rendering

Realistic lighting (PBR, Phong) lighting-model shadow-techniques, ambient-occlusion

Shadows (soft / hard) shadow-techniques lighting-model

Ambient occlusion ambient-occlusion lighting-model, normal-estimation

Path tracing / global illumination path-tracing-gi analytic-ray-tracing, multipass-buffer

Precise ray-geometry intersections analytic-ray-tracing lighting-model

Voxel worlds (Minecraft-style) voxel-rendering lighting-model, shadow-techniques

Noise / FBM textures procedural-noise domain-warping

Tiled 2D patterns procedural-2d-pattern polar-uv-manipulation

Voronoi / cell patterns voronoi-cellular-noise color-palette

Fractals (Mandelbrot, Julia, 3D) fractal-rendering color-palette, polar-uv-manipulation

Color grading / palettes color-palette —

Bloom / tone mapping / glitch post-processing multipass-buffer

Multi-pass ping-pong buffers multipass-buffer —

Texture / sampling techniques texture-sampling —

Camera / matrix transforms matrix-transform —

Surface normals normal-estimation —

Polar coords / kaleidoscope polar-uv-manipulation procedural-2d-pattern

2D shapes / UI from SDF sdf-2d color-palette

Procedural audio / music sound-synthesis —

SDF tricks / optimization sdf-tricks sdf-3d, ray-marching

Anti-aliased rendering anti-aliasing sdf-2d, post-processing

Depth of field / motion blur / lens effects camera-effects post-processing, multipass-buffer

Advanced texture mapping / no-tile textures texture-mapping-advanced terrain-rendering, texture-sampling

WebGL2 shader errors / debugging webgl-pitfalls —

Technique Index

Geometry & SDF

• sdf-2d — 2D signed distance functions for shapes, UI, anti-aliased rendering

• sdf-3d — 3D signed distance functions for real-time implicit surface modeling

• csg-boolean-operations — Constructive solid geometry: union, subtraction, intersection with smooth blending

• domain-repetition — Infinite space repetition, folding, and limited tiling

• domain-warping — Distort domains with noise for organic, flowing shapes

• sdf-tricks — SDF optimization, bounding volumes, binary search refinement, hollowing, layered edges, debug visualization

Ray Casting & Lighting

• ray-marching — Sphere tracing with SDF for 3D scene rendering

• analytic-ray-tracing — Closed-form ray-primitive intersections (sphere, plane, box, torus)

• path-tracing-gi — Monte Carlo path tracing for photorealistic global illumination

• lighting-model — Phong, Blinn-Phong, PBR (Cook-Torrance), and toon shading

• shadow-techniques — Hard shadows, soft shadows (penumbra estimation), cascade shadows

• ambient-occlusion — SDF-based AO, screen-space AO approximation

• normal-estimation — Finite-difference normals, tetrahedron technique

Simulation & Physics

• fluid-simulation — Navier-Stokes fluid solver with advection, diffusion, pressure projection

• simulation-physics — GPU-based physics: springs, cloth, N-body gravity, collision

• particle-system — Stateless and stateful particle systems (fire, rain, sparks, galaxies)

• cellular-automata — Game of Life, reaction-diffusion (Turing patterns), sand simulation

Natural Phenomena

• water-ocean — Gerstner waves, FFT ocean, caustics, underwater fog

• terrain-rendering — Heightfield ray marching, FBM terrain, erosion

• atmospheric-scattering — Rayleigh/Mie scattering, god rays, SSS approximation

• volumetric-rendering — Volume ray marching for clouds, fog, fire, explosions

Procedural Generation

• procedural-noise — Value noise, Perlin, Simplex, Worley, FBM, ridged noise

• procedural-2d-pattern — Brick, hexagon, truchet, Islamic geometric patterns

• voronoi-cellular-noise — Voronoi diagrams, Worley noise, cracked earth, crystal

• fractal-rendering — Mandelbrot, Julia sets, 3D fractals (Mandelbox, Mandelbulb)

• color-palette — Cosine palettes, HSL/HSV/Oklab, dynamic color mapping

Post-Processing & Infrastructure

• post-processing — Bloom, tone mapping (ACES, Reinhard), vignette, chromatic aberration, glitch

• multipass-buffer — Ping-pong FBO setup, state persistence across frames

• texture-sampling — Bilinear, bicubic, mipmap, procedural texture lookup

• matrix-transform — Camera look-at, projection, rotation, orbit controls

• polar-uv-manipulation — Polar/log-polar coordinates, kaleidoscope, spiral mapping

• anti-aliasing — SSAA, SDF analytical AA, temporal anti-aliasing (TAA), FXAA post-process

• camera-effects — Depth of field (thin lens), motion blur, lens distortion, film grain, vignette

• texture-mapping-advanced — Biplanar mapping, texture repetition avoidance, ray differential filtering

Audio

• sound-synthesis — Procedural audio in GLSL: oscillators, envelopes, filters, FM synthesis

Debugging & Validation

• webgl-pitfalls — Common WebGL2/GLSL errors: fragCoord, main() wrapper, function order, macro limitations, uniform null

WebGL2 Adaptation Rules

All technique files use ShaderToy GLSL style. When generating standalone HTML pages, apply these adaptations:

Shader Version & Output

• Use canvas.getContext("webgl2")

• Shader first line: #version 300 es, fragment shader adds precision highp float;

• Fragment shader must declare: out vec4 fragColor;

• Vertex shader: attribute → in, varying → out

• Fragment shader: varying → in, gl_FragColor → fragColor, texture2D() → texture()

Fragment Coordinate

• Use gl_FragCoord.xy instead of fragCoord (WebGL2 does not have fragCoord built-in)

// WRONG
vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;
// CORRECT
vec2 uv = (2.0 * gl_FragCoord.xy - iResolution.xy) / iResolution.y;

main() Wrapper for ShaderToy Templates

• ShaderToy uses void mainImage(out vec4 fragColor, in vec2 fragCoord)

• WebGL2 requires standard void main() entry point — always wrap mainImage:

void mainImage(out vec4 fragColor, in vec2 fragCoord) {
    // shader code...
    fragColor = vec4(col, 1.0);
}

void main() {
    mainImage(fragColor, gl_FragCoord.xy);
}

Function Declaration Order

• GLSL requires functions to be declared before use — either declare before use or reorder:

// WRONG — getAtmosphere() calls getSunDirection() before it's defined
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Error!
vec3 getSunDirection() { return normalize(vec3(1.0)); }

// CORRECT — define callee first
vec3 getSunDirection() { return normalize(vec3(1.0)); }
vec3 getAtmosphere(vec3 dir) { return getSunDirection(); } // Works

Macro Limitations

• #define cannot use function calls — use const instead:

// WRONG
#define SUN_DIR normalize(vec3(0.8, 0.4, -0.6))

// CORRECT
const vec3 SUN_DIR = vec3(0.756, 0.378, -0.567); // Pre-computed normalized value

Script Tag Extraction

• When extracting shader source from <script> tags, ensure #version is the first character — use .trim():

const fs = document.getElementById('fs').text.trim();

Common Pitfalls

• Unused uniforms: Compiler may optimize away unused uniforms, causing gl.getUniformLocation() to return null — always use uniforms in a way the compiler cannot optimize out

• Loop indices: Use runtime constants in loops, not #define macros in some ES versions

• Terrain functions: Functions like terrainM(vec2) need XZ components — use terrainM(pos.xz + offset) not terrainM(pos + offset)

HTML Page Setup

When generating a standalone HTML page:

• Canvas fills the entire viewport, auto-resizes on window resize

• Page background black, no scrollbars: body { margin: 0; overflow: hidden; background: #000; }

• Implement ShaderToy-compatible uniforms: iTime, iResolution, iMouse, iFrame

• For multi-pass effects (Buffer A/B), use WebGL2 framebuffer + ping-pong (see multipass-buffer technique)

Common Pitfalls

JS Variable Declaration Order (TDZ — causes white screen crash)

let/const variables must be declared at the top of the <script> block, before any function that references them:

// 1. State variables FIRST
let frameCount = 0;
let startTime = Date.now();

// 2. Canvas/GL init, shader compile, FBO creation
const canvas = document.getElementById('canvas');
const gl = canvas.getContext('webgl2');
// ...

// 3. Functions and event bindings LAST
function resize() { /* can now safely reference frameCount */ }
function render() { /* ... */ }
window.addEventListener('resize', resize);

Reason: let/const have a Temporal Dead Zone — referencing them before declaration throws ReferenceError,

...