shader-art-coding

Shader Art Coding

Treat shader work as visual engineering: start from the intended image, choose the smallest mathematical model that can produce it, build it in inspectable stages, and verify each stage with a debug view.

Workflow

1. Target. State the image: subject, camera and framing, dominant forms, materials, light, motion.
2. Route. Pick the rendering model and starting template from references/subject-routing.md:

2D distance fields (posters, icons, patterns), SDF raymarching (objects, characters), heightfield marching (landscapes), volume integration (clouds, smoke, fire).

1. Assemble from the library. Find building blocks with python3 scripts/glsl_tools.py search <words> or

references/library-index.md, and call them by name. Do not paste or re-derive library code; it is tested.

1. First image fast. Coordinates, background, one primitive, one light. Then add the debug views.
2. Refine in order: proportions, composition, material separation, lighting, atmosphere, color, antialiasing,

performance.

1. Bundle and check. python3 scripts/glsl_tools.py bundle shader.glsl -o out.glsl inlines exactly the

functions used. python3 scripts/glsl_tools.py check out.glsl lints it and compiles it with glslangValidator when installed. Fix every error, then deliver out.glsl.

Run the scripts from this skill's directory. They need only Python 3.

Conventions

• Coordinates: vec2 uv = (2.0 * fragCoord - iResolution.xy) / iResolution.y;, so one pixel is

2.0 / iResolution.y.

• Scene contract: vec2 map(vec3 p) returns vec2(distance, materialId). raymarch, calcNormal,

softShadow, calcAO and sdfThickness all use it.

• Debug: #define DEBUG_MODE 0 with 0 final, 1 distance field, 2 normals, 3 ids, 4 steps, 5 masks,

6 lighting terms.

• Color pipeline: light in linear and decode picked colors with srgbToLinear. Then exposure, then the

tonemap (tonemapAgX by default, per AA sample), then the average, then linearToSrgb once, then ditherTPDF.

• Distances: respect the @exact / @bound / @approx tags. If a deformation pushes Lipschitz above 1,

divide the distance or lower the stepScale of raymarch.

Hard rules (these break Shadertoy/WebGL)

• No #version line, no custom uniforms, no gl_FragColor / texture2D / iGlobalTime.
• No ?: on structs. Use vec2(distance, id) or if.
• Write float literals: 2.0 * PI, clamp(x, 0.0, 1.0).
• No fract(sin(...) * 43758.5453) hashes. Use hash12 / hash22 / hash33 (integer PCG). Replace them even

when porting with "keep the look": the sine hash's exact pattern already differs between GPUs, and a PCG hash on the same integer cell ids gives the noise the same look. check reports a sine hash as an error.

• Guard NaN sources: atan(0, 0), pow of negatives, sqrt of negatives, normalize(vec3(0)).
• Keep dFdx / fwidth out of non-uniform branches and loops, or use an explicit pixel size.

Reference routing

Read only what the task needs:

Templates in templates/ are complete, render-verified starting points (gallery in the repository README): raymarch-sdf.glsl, terrain.glsl, ocean.glsl, volumetric-clouds.glsl, sdf-2d-poster.glsl, pattern-swatches.glsl, noise-progression.glsl, noise-terrain-map.glsl, procedural-city.glsl, alpine-valley.glsl, coastal-water.glsl.

Output expectations

When writing a shader:

• Deliver the bundled, paste-ready Shadertoy code with mainImage(out vec4 fragColor, in vec2 fragCoord).
• Avoid textures unless the user provides them.
• Include DEBUG_MODE switches and name the art controls as constants at the top.
• End with a short tuning guide: which constants control scale, softness, color, light and motion.
• Say whether the shader was compile-checked, and how.
• For buildings/terrain/water, separate implemented features from engine-side upgrades. Do not call a heightfield

a cave generator, a material window a modeled recess, or a procedural foam/caustic mask a fluid/light simulation.

• For quality requests, state the target and budget, expose presets/debug views, and inspect rendered output.

Annotate important template presets with // @variant QUALITY=3 (or another defined integer macro) so CI compiles and renders them. Preserve horizon/shore contact and temporal filtering before adding detail.

When improving an existing shader:

• Identify its rendering model and bottlenecks.
• Preserve its intent and interface.
• Fix correctness first, then readability, visual quality and speed.
• Call out risky changes (coordinate scale, material ids, loop counts).