GLSL and WGSL Shaders skill for Codex

Done well means: the shader compiles on the weakest target (mobile WebGL2, the oldest supported GPU), math happens in linear color space with one conversion at output, every uniform has a clear unit and range, cost per pixel is known, and the effect was validated offline before it went into the engine.

Identify the dialect first

Target	Language	Notes
WebGL2, raw	GLSL ES 3.00 (#version 300 es)	in/out, explicit out vec4 fragColor;
Three.js ShaderMaterial	GLSL ES 3.00 with Three’s prefix	Three injects projectionMatrix, modelViewMatrix, position, uv, normal; RawShaderMaterial injects nothing
Three.js WebGPU renderer	TSL (node materials)	GLSL ShaderMaterial is not supported there
Godot 4	Godot shading language (GLSL-like)	shader_type canvas_item;/spatial;, built-ins UV, COLOR, TIME, ALBEDO
WebGPU, wgpu, Bevy	WGSL	Explicit types, bind groups, strict uniformity rules
Unity	HLSL / Shader Graph	Out of scope here except for porting math
Shadertoy	GLSL with mainImage(out vec4, in vec2) and iTime, iResolution	Needs a wrapper to run anywhere else

Read AGENTS.md, then find how shaders are loaded (inline strings, .glsl imports via a Vite plugin, .gdshader, .wgsl files) and follow it.

Fragment shader skeleton (WebGL2 / Three.js)

// Three.js ShaderMaterial fragment shader: dissolve with an edge glow
uniform sampler2D uMap;
uniform sampler2D uNoise;
uniform float uProgress;      // 0 = intact, 1 = fully dissolved
uniform vec3 uEdgeColor;      // linear RGB
uniform float uEdgeWidth;     // in noise units, e.g. 0.05

varying vec2 vUv;

void main() {
  vec4 base = texture2D(uMap, vUv);
  float n = texture2D(uNoise, vUv).r;
  float cut = n - uProgress;
  if (cut < 0.0) discard;
  float edge = 1.0 - smoothstep(0.0, uEdgeWidth, cut);
  vec3 color = mix(base.rgb, uEdgeColor * 4.0, edge);   // >1.0 feeds bloom in HDR pipelines
  gl_FragColor = vec4(color, base.a);
  #include <colorspace_fragment>                         // Three: linear -> output color space
}

Three.js maps texture2D, varying and gl_FragColor to GLSL3 equivalents. In raw GLSL ES 3.00 write texture, in/out and declare out vec4 fragColor;.

WGSL equivalent structure

struct Params {
  time: f32,
  progress: f32,
  resolution: vec2f,          // offset 8: vec2f aligns to 8 bytes
};
@group(0) @binding(0) var<uniform> params: Params;
@group(0) @binding(1) var colorTex: texture_2d<f32>;
@group(0) @binding(2) var colorSampler: sampler;

struct VsOut { @builtin(position) pos: vec4f, @location(0) uv: vec2f };

@vertex
fn vs_main(@builtin(vertex_index) i: u32) -> VsOut {
  // Fullscreen triangle; WebGPU texture space has v = 0 at the top, so flip y.
  var p = array<vec2f, 3>(vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0));
  var out: VsOut;
  out.pos = vec4f(p[i], 0.0, 1.0);
  out.uv = vec2f(p[i].x * 0.5 + 0.5, 0.5 - p[i].y * 0.5);
  return out;
}

@fragment
fn fs_main(in: VsOut) -> @location(0) vec4f {
  let c = textureSample(colorTex, colorSampler, in.uv);   // must be in uniform control flow
  let vignette = smoothstep(0.9, 0.3, distance(in.uv, vec2f(0.5)));
  return vec4f(c.rgb * vignette, c.a);
}

For a GLSL to WGSL and GLSL to Godot translation table (types, built-ins, texture calls, coordinate conventions), read references/glsl-wgsl-mapping.md when porting a shader between dialects.

Rules that prevent most bugs

• Color space. Do lighting and blending in linear space. Textures holding color (albedo, UI) are sRGB and must be decoded (engine texture settings or SRGB formats); data textures (normals, noise, masks) must not be. Convert to sRGB once at output. Washed-out or too-dark results almost always mean a double or missing conversion.
• Precision. In GLSL ES fragment shaders, declare precision highp float; when computing positions, UV over large textures or time; mediump (often 16-bit on mobile) breaks UV scrolling after minutes of uTime. Wrap time: mod(uTime, 1000.0) or pass fract values.
• Uniform layout. In std140 (GLSL UBOs) and WGSL uniform buffers, vec3 aligns to 16 bytes. Pack as vec4 or put a float right after a vec3 deliberately. Mismatched CPU-side layout gives garbage values with no error.
• Undefined math. pow(x, y) with negative x, normalize(vec3(0)), sqrt of negative, division by zero, and atan(0, 0) produce NaN or implementation-defined values that differ per GPU. Clamp inputs (max(x, 0.0), max(len, 1e-5)).
• Derivatives and texture sampling in branches. texture(), dFdx, fwidth inside non-uniform branches give undefined mip selection in GLSL and are a compile error in WGSL (textureSample requires uniform control flow). Sample before branching, or use textureSampleLevel / textureLod with an explicit level.
• Premultiplied alpha. Know whether the pipeline expects premultiplied output. Dark fringes around sprites mean straight alpha blended as premultiplied (or the reverse).
• Coordinate conventions. GL texture v=0 is the bottom; WebGPU/D3D/Metal v=0 is the top. Render-target sampling in one API is flipped in the other.

Performance

Cost driver	Guidance
Overdraw (full-screen passes, layered transparency)	Count passes; each 1080p full-screen pass is ~2M fragment invocations
Texture fetches	Fewer, smaller, mipmapped textures; pack masks into RGBA channels
Dependent reads (UV computed from another texture)	Fine on desktop, costly on old mobile; keep chains short
Branching	Uniform branches (same for all pixels) are cheap; divergent ones run both sides
Loops	Constant bounds; avoid large loops per pixel (blur: separable two-pass, not N x N)
discard	Disables early depth test on many GPUs; use alpha blending or alpha-to-coverage where possible

Move work up the pipeline: per-frame constants on the CPU, per-vertex values in the vertex shader (interpolated), per-pixel only what must be.

Debugging

• Output intermediate values as color: fragColor = vec4(vec3(n), 1.0); to see a noise value, vec4(normal * 0.5 + 0.5, 1.0) for normals, bright magenta for NaN checks (if (isnan(v)) fragColor = vec4(1,0,1,1); in GLSL ES 3.00).
• Frame captures: Spector.js (WebGL), browser WebGPU devtools, RenderDoc (desktop, Vulkan/D3D/GL).
• Change one thing per reload; shader errors in engines often report the line of the generated code, not your file. Print the final source the engine compiled when lines do not match.

Offline validation

Both tools are offline once installed (installing needs network and may need approval):

glslangValidator shader.frag            # GLSL; needs a #version line; -S frag for unknown extensions
naga shader.wgsl                        # WGSL validation (cargo install naga-cli)
naga shader.frag shader.wgsl            # naga can also translate GLSL -> WGSL as a starting point

For Three.js or Godot shaders that rely on injected prefixes, validate in the engine: load the material in a test scene and check the console or Godot output for compile errors.

Verification checklist

• Compiles in the target engine with zero warnings, on WebGL2 and on one mobile device
• Looks correct in both linear and sRGB output paths the project uses
• Uniforms at their extremes (0, 1, large time) produce no NaN, banding or popping
• Measured: GPU frame time with and without the effect at target resolution
• CPU-side uniform buffer layout matches the shader struct byte for byte (WGSL/std140)

Hand-off summary

**Shader:** dissolve.frag (Three.js ShaderMaterial, GLSL3) + dissolve.wgsl port for the WebGPU path
**Uniforms:** uProgress 0..1, uEdgeWidth 0.05, uEdgeColor linear RGB (HDR x4 for bloom)
**Checks:** glslangValidator and naga clean; Pixel 6 + desktop Chrome; no NaN at progress 0 and 1
**Cost:** +0.3 ms GPU at 1080p (1 extra texture fetch, discard on dissolved pixels)