Compiling WGSL
scripts/forge is a pure-Python WGSL toolchain (numpy is the only dependency): a parser
that follows the spec's template-list rules, a minifier, a shape compiler, and a GLSL
front end that rewrites WebGL and Shadertoy GLSL for naga (and glslang) to translate. It came
from oaustegard/experiments/wgsl-forge, whose RESULTS.md holds the measurements quoted
here. Set SKILL=/mnt/skills/user/compiling-wgsl (or this directory) and run every
command with PYTHONPATH=$SKILL/scripts.
When NOT to use this skill
| Situation |
Use instead |
| A raster image (photo, PNG) should become vector shapes |
image-to-svg, then this skill on its SVG |
| The output is a PNG, PDF or SVG file rather than a shader |
drawing-with-pycairo |
| Charts or dashboards |
charting, charting-vega-lite |
| HLSL or Metal |
not covered; naga reads SPIR-V (naga in.spv out.wgsl), so HLSL can go through DXC to SPIR-V first |
GLSL for desktop OpenGL with #version 330 or older, or code using iChannel buffers (multi-pass Shadertoy) |
converts, but the multi-pass plumbing (render targets, feedback) is host code you write |
| A shader whose host reads names back by reflection (a binding library that matches struct member or function names) |
run with --keep name1,name2, or do not rename |
Setup
export SKILL=/mnt/skills/user/compiling-wgsl
pip install --break-system-packages numpy pillow # pillow only for --png
command -v naga || cargo install naga-cli # validator; required for GLSL, ~3 min
command -v glslangValidator || apt-get install -y glslang-tools # GLSL fallback route
node -e "require('playwright')" && echo playwright-ok # GPU checks need it
python3 $SKILL/scripts/selftest.py # ~20 s: every route on bundled fixtures
selftest.py prints missing tools: first if naga, glslang or node is absent. Every
other line must read ok.
The GPU checks run headless Chromium on SwiftShader. On claude.ai and Claude Code on
the web, Playwright's Chromium is already installed. Elsewhere, point CHROME_PATH at a
Chromium binary.
Minify a shader
PYTHONPATH=$SKILL/scripts python3 -m forge minify in.wgsl -o out.wgsl # prints bytes before -> after
python3 $SKILL/scripts/verify.py minify in.wgsl # always run this
verify.py minify validates the output with naga and compiles both versions in Tint.
It then runs every compute entry point that binds only buffers on random typed inputs:
the original twice and the minified once. It exits 1 on any failure.
Read the result lines:
ok compute main bit-identical: the minified kernel computes the same bytes.
skip ... original disagrees with itself: the original has a race for this dispatch
shape. Pass the real shape with --dispatch 64,1,1.
skip ... textures or samplers bound: that shader was compiled, not executed. To prove
a render shader unchanged, render it in its real host before and after and compare
pixels.
Options:
--no-aliases skips the alias a=vec4f; pass. Use it for shaders served gzipped: on
the 86-shader corpus that pass saves 1.7% raw bytes but adds 0.9% gzip bytes.
--keep a,b protects extra names from renaming and removal.
Entry-point names, override names, binding numbers and attributes are never changed.
Struct members spelled like swizzles (x, rgb) or like builtin result fields (fract,
exp, whole) are never renamed either.
Expect 30–35% of the original bytes on typical shaders (34% on the corpus, against 56%
for LucentFlux wgsl-minifier on the files both handle). Shaders that are already terse
land nearer 50%: Tilt Rally's nine came out at 51%.
python3 -m forge fmt out.wgsl pretty-prints minified code for reading.
Convert GLSL to WGSL
PYTHONPATH=$SKILL/scripts python3 -m forge glsl shader.frag -o shader.wgsl [--minify]
python3 $SKILL/scripts/verify.py glsl shader.frag --png /tmp/port.png # always run this
PYTHONPATH=$SKILL/scripts python3 -m forge html toy.glsl -o preview.html # Shadertoy only
The input kind is detected automatically:
| input |
detected by |
output |
| Shadertoy |
mainImage and no main |
the same interface as compiled scenes: uniform {r, t} at binding 0, vs and fs entries; y flipped to Shadertoy's bottom-left origin, alpha forced to 1 |
WebGL 2 (#version 300 es) or WebGL 1 (no version) |
version line |
one WGSL entry point main; loose uniforms gathered into one std140 block at binding 0, each sampler2D split into a texture and a sampler from binding 1 |
| Vulkan GLSL 450 |
#version 450 |
passed through as written |
The stage comes from the extension (.vert, .frag, .comp) or from the content
(gl_Position, local_size_x). --stage overrides it.
forge glsl prints the binding lines the host must now supply, with byte offsets. A
WebGL program set uniforms by name; WebGPU writes one buffer at those offsets, and
std140 puts a vec3 or mat3 column on a 16-byte boundary. note: lines report every
rewrite the converter made.
Translation goes through naga's GLSL reader. When naga refuses the source, it is
compiled to SPIR-V with glslang and naga translates that instead (--backend forces
either). The glslang route accepts more GLSL but mangles function names; minifying
renames them anyway.
verify.py glsl validates and compiles both the WGSL and its minified form.
- Shadertoy code is also rendered by Chrome's WebGL2 as the reference and by the
WGSL on WebGPU, at t=0 and t=1.7. It must reach 30 dB PSNR, and the minified version
must draw identically.
- Other GLSL has no reference renderer, so it is compiled only. To check a compute
port, run the WGSL with
scripts/forge/gpu.py run_jobs (kind compute) and compare
the result with a numpy version of the algorithm.
Compile an SVG to a shader
PYTHONPATH=$SKILL/scripts python3 -m forge svg icon.svg --minify -o icon.wgsl
python3 $SKILL/scripts/verify.py svg icon.svg --size 512 --png /tmp/check.png
PYTHONPATH=$SKILL/scripts python3 -m forge html icon.svg --minify -o preview.html # live page with host code
Read every warning: line. Skipped elements (text, image, clipPath, mask,
filter, pattern, marker) are missing from the shader. verify.py svg reports
mean error, PSNR and an ink ratio against Chromium's own SVG rendering. When anything
was dropped, it also scores against Chromium rendering the SVG with those parts removed
(text, masks, clips, filters, animations), and the pass/fail uses that second score. The
first score tells you how much the dropped parts mattered; the second tells you whether
what was compiled is right. Then Read the PNG: reference | shader | difference ×4.
The shader's interface is fixed:
@group(0) @binding(0) var<uniform> u: U with struct U { r: vec2f, t: f32 }, which
holds the canvas size in pixels and the time in seconds (16-byte buffer:
[w, h, t, 0]).
- Vertex entry
vs; draw 3 vertices, no vertex buffers.
- Fragment entry
fs, which returns premultiplied RGBA (alphaMode: "premultiplied").
forge html writes a working host page to copy from.
Self-painting. --paint-in 4 (Scene(paint_in=4)) makes the shapes appear one by one
in paint order over 4 seconds of the time uniform, each fading in over its own slot.
--loop holds the finished picture, then starts again, and forge html shows it live.
Table rows stop the loop at the first unrevealed row, so early frames are also cheaper to
draw. The reveal follows SVG order (back to front), because reordering overlapping shapes
would change the picture. verify.py svg X.svg --paint-in 4 checks the contract:
- t=0: only the background shows.
- While painting: no pixel's coverage ever decreases. Ink can legitimately fall when
light shapes paint over dark ones, so coverage is the measure.
- Finished frame: bit-identical to the static shader, minified or not.
Size against accuracy. --grid N (Scene(grid=N)) sets the path coordinate step,
1/N of a nominal pixel. The default of 64 sits at the knee. On Twemoji's lion at 512 px,
grid 16 saves 10% of gzip bytes and costs 4.6 dB, and grid 128 adds 4% for 0.6 dB.
Rounding float literals to fewer digits was measured and rejected. Literals are already
short, so rounding to 5 digits saved 0.3% of a scene shader's bytes and 0.05% of a
hand-written one's, and it changed pixels.
Large scenes (matplotlib output, traced images, icon sets).
- Shape table: four or more consecutive plain shapes become rows in a table that
one loop draws. A plain shape is a static path or primitive with a solid fill or
stroke.
- Storage buffer: path data over 8,192 ints moves out of the shader into a storage
buffer at
@group(0) @binding(1) (var<storage, read> D: array<i32>).
forge svg -o x.wgsl then also writes x.bin, which the host uploads.
scene.data_buffer holds the same bytes in Python, and forge html embeds them.
- Segment warning: a scene with more than 20,000 path segments is flagged, because a
pixel walks every segment of every shape whose bounding box covers it.
Build a scene in Python
Use this when the shapes come from code, need animation, or need operations SVG lacks.
references/scene-api.md lists the whole API; references/example_scene.py is a
complete animated scene.
from forge.scene import Scene, T, sin, radial, smooth_union, Circle
s = Scene(320, 200, background="#101418")
s.circle(160, 100, 40 + 4 * sin(T * 2), fill=radial(160, 100, 50, ["#fff7d6", "#ff8a3d"]))
with s.group(translate=(160, 100), rotate=T * 30):
s.rect(-2, -80, 4, 20, rx=2, fill="#ffd36e")
s.add(smooth_union(Circle(60, 150, 25), Circle(90, 150, 20), k=12), fill="hotpink")
open("scene.wgsl", "w").write(s.compile(minify=True))
open("frame.svg", "w").write(s.to_svg(t=1.3)) # reference frame for checking
Any number can be an expression in T. Check an animated scene at a time where its
animated terms are large, not just at t=0: render the shader with time set and compare it
with Chromium rendering to_svg(t). scripts/forge/gpu.py's run_jobs takes render
and svg jobs with a time field. SDF-only features (smooth_union, subtract,
intersect, rounded, onion, soft) make to_svg raise, because SVG cannot express
them. Check those by rendering and reading the image.
When to abandon it
- The SVG relies on unsupported features. If warnings list
text, clipPath,
mask or filter and those carry the design, the shader will be wrong. Rasterise
instead, or convert text to paths first.
- The shader is too slow. Every pixel loops over every path segment. A scene with
thousands of segments (a detailed illustration, a map) is too heavy as one shader:
draw it as triangles, or bake it to a texture.
- A shader under 1 KB. Expect only small gains, so minify only if bytes really matter.
Failure modes
naga could not translate the GLSL and glslang also fails → read glslang's message.
It is usually real GLSL that Vulkan forbids, such as a sampler passed as a function
argument (a note: names it). Rewrite that part by hand: pass the texture and sampler
separately.
Tint compiles WGSL FAILs with unresolved call target 'subgroupBarrier' → the
WGSL came from an older copy of this converter. Since 0.2.0 it strips the subgroup and
texture barriers that naga adds for GLSL barrier(), keeping workgroupBarrier().
A WebGL port renders but the colours or positions are wrong → check the uniform
buffer against the binding offsets that forge glsl printed. The usual mistake is a
vec3 written tightly packed instead of on its 16-byte boundary.
A Shadertoy port renders upside down in your own host → you dropped the
fragCoord flip. The shader expects the uniform r to hold the canvas size in pixels.
Integer % or division differs from WebGL for negative operands → GLSL leaves
these undefined, and the WGSL takes one definite answer. Rewrite the GLSL to stay
non-negative.
naga says expected array<i32, 2>, but got array<i32, 2> → this is naga 30's
quirk with an alias inside a template argument. The alias pass already avoids it; if
it appears, rerun with --no-aliases and report the input.
Tint compiles the minified shader but not the original → expected when dead-code
removal drops unused code that Tint rejects; the reachable code is unchanged. Two naga
test files do this.
compute ... bit-identical FAILs with a 2-D or 3-D --dispatch → probably a race
in the original: invocations that share id.x write the same element, and two original
runs happened to agree. Rerun with the host's real dispatch shape before believing it.
Diagnosed 2026-11-02 on Tilt Rally's SMOKE_SIM: 4×4 failed, while 4×1 was identical
on three seeds.
The harness prints harness failed or every GPU job errors → Chromium or WebGPU is
unavailable. Check node -e "require('playwright')", set CHROME_PATH, and keep the
--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader flags that
scripts/harness/gpu.mjs passes.
Small text or hairlines look bolder than in the browser (ink ratio 1.03 to 1.07 on
text-heavy charts) → antialiasing works from one distance per shape, so a feature
thinner than a pixel gets about half a pixel of coverage too much. The geometry is right.
Render larger, or accept it. Measured on a matplotlib chart whose labels are glyph
outlines: ink ratio 1.067 at 512 px.
warning: N path segments, and a frame takes seconds → per-pixel cost is the
number of segments under the pixel. Simplify the paths (fewer points) or bake the image
to a texture; this compiler has no tile binning.
colour 'var(...)' unsupported → a custom property the reader could not resolve.
Plain var(--x) from CSS rules, inline styles and @property initial values is
supported. A malformed name stays unresolved and paints black, which is what the
browser does with the invalid declaration too.
The ink ratio is below 0.97 or above 1.03 at large sizes → a geometry error, not
antialiasing: antialiasing error shrinks as size grows, and geometry error does not.
Compare verify.py svg --size 128 with --size 768.
Curves look faceted at extreme zoom → curves are fitted to 0.02 of the SVG's own
pixel, which holds to about 50× magnification. Lower it with --tolerance 0.02; the
default is 0.2, of which a tenth goes to the curve fit.
Verification
- Minifier:
verify.py minify must print no FAIL. A good result passes naga, compiles
in Tint and gives bit-identical compute buffers. A bad success compiles but computes
something else: a renamed name the host looks up, or a shader with textures that was
only compiled. For the second case, render it in its host before and after and compare
pixels.
- GLSL:
verify.py glsl must print no FAIL, and for Shadertoy code the PNG rows
(WebGL | WGSL | difference ×8) must show the same picture. A bad success is two blank
images that match: check that the picture has content. Another is a non-Shadertoy port
that compiles but was never run against anything.
- SVG:
verify.py svg must print no FAIL, and the PNG must look right. A bad
success is a high PSNR on an SVG whose warning: lines show that elements were
dropped. A missing element still scores well when it is small.
Diagnosed failures (fixed, kept as signals)
2026-11-02, paint-in check: the first version required ink to rise from frame to
frame. It failed on Twemoji's lion, where the dark mane paints first and the light face
covers it, so ink fell from 131% to 100% of the final value. That is correct painter's
order. The invariant is coverage per pixel, which is what the check now measures.
2026-11-02, real Python-made SVGs from the experiments repo:
- matplotlib Pareto chart: 235 KB of unrolled WGSL killed SwiftShader's pipeline
compiler ("A valid external Instance reference no longer exists"). The shape table
fixed it: 6.7 KB of WGSL, 29.0 dB.
- Palette-cycling cat: 880 shapes broke Tint's array-constructor limit ("excessive
number of elements (>32767)"). The storage buffer fixed it: 34.2 dB, ink ratio 1.000.
- Traced dog: same limit. With the buffer and masks excluded it scored 41.0 dB, but
took 215 s per frame on SwiftShader, which led to the segment warning.
- Also found: a missing
f prefix in svg-palette-cycle/build.py writes the
literal var(--b{len(BANDS) - 1}) into its SVG.
2026-11-02, a switch case that returns: naga's GLSL reader rejected
switch (i) { case 0: return a; ... } ("fall-through switch case block"), even with a
break; after the return. The auto backend now falls back to glslang.
2026-11-02, subgroupBarrier: GLSL barrier() came out of naga as four barriers,
subgroupBarrier() among them, and Tint rejects that call. naga validated the output,
so only the Tint compile in verify.py caught it.
2026-11-02, html preview: forge html had never worked in 0.1.0. A % in its CSS
broke the %-formatting of the page template, and nothing ran the command until the
GLSL work. selftest.py now covers every route.
2026-11-02, zero error that looked suspicious: every Shadertoy fixture matched WebGL
at 0 error. The images were checked and are real: WebGL and WebGPU both run on
SwiftShader in the container. Expect small floating-point differences on real GPUs,
hence the 30 dB bar rather than exact equality.
2026-11-01, line segments: flattening curves to line segments at the SVG's size left
icons 1.8% too light at 512 px (ink ratio 0.982), and the error never shrank with size.
The fix was to keep curves as quadratic Béziers with exact distance. The signal was the
ink ratio at two sizes.
2026-11-01, missing parentheses: an animated radius compiled without parentheses,
- 44+3*sin(..). Frames at t=0 and t=4.7 still matched closely, because the animated
term was near zero there, and t=1.3 diverged visibly. The lesson: test animation at
large values of its animated terms.
2026-11-01, packed arc flags: 0 014.907 was misread, and two Simple Icons logos
failed to parse. No hand-written test packed flags that way.
1---2name: compiling-wgsl3description: "Produces and shrinks WGSL shaders. Converts GLSL (WebGL 1 and 2, Shadertoy mainImage code, Vulkan GLSL 450, compute shaders) to WGSL and checks the port pixel by pixel against WebGL; minifies a WebGPU shader (renaming, dead code, literal and type shortening) and proves the result unchanged with naga, Chrome's Tint and bit-identical compute runs; compiles an SVG file or a Python-built scene of circles, rects, paths, gradients and animated transforms into one resolution-independent WGSL fragment shader. Use for convert GLSL to WGSL, port this Shadertoy to WebGPU, WebGL shader to WebGPU, minify this WGSL, shrink my shader, make the shader smaller, WGSL optimizer, turn this SVG into a shader, draw this icon in WebGPU, SDF shapes in WGSL, smooth union shapes, animated vector graphics on the GPU, pretty-print WGSL."4metadata:5 source: https://skillmd.com/skills/oaustegard/compiling-wgsl6 version: 0.5.07---89# Compiling WGSL1011`scripts/forge` is a pure-Python WGSL toolchain (numpy is the only dependency): a parser12that follows the spec's template-list rules, a minifier, a shape compiler, and a GLSL13front end that rewrites WebGL and Shadertoy GLSL for naga (and glslang) to translate. It came14from `oaustegard/experiments/wgsl-forge`, whose RESULTS.md holds the measurements quoted15here. Set `SKILL=/mnt/skills/user/compiling-wgsl` (or this directory) and run every16command with `PYTHONPATH=$SKILL/scripts`.1718## When NOT to use this skill1920| Situation | Use instead |21|---|---|22| A raster image (photo, PNG) should become vector shapes | `image-to-svg`, then this skill on its SVG |23| The output is a PNG, PDF or SVG file rather than a shader | `drawing-with-pycairo` |24| Charts or dashboards | `charting`, `charting-vega-lite` |25| HLSL or Metal | not covered; naga reads SPIR-V (`naga in.spv out.wgsl`), so HLSL can go through DXC to SPIR-V first |26| GLSL for desktop OpenGL with `#version 330` or older, or code using `iChannel` buffers (multi-pass Shadertoy) | converts, but the multi-pass plumbing (render targets, feedback) is host code you write |27| A shader whose host reads names back by reflection (a binding library that matches struct member or function names) | run with `--keep name1,name2`, or do not rename |2829## Setup3031```bash32export SKILL=/mnt/skills/user/compiling-wgsl33pip install --break-system-packages numpy pillow # pillow only for --png34command -v naga || cargo install naga-cli # validator; required for GLSL, ~3 min35command -v glslangValidator || apt-get install -y glslang-tools # GLSL fallback route36node -e "require('playwright')" && echo playwright-ok # GPU checks need it37python3 $SKILL/scripts/selftest.py # ~20 s: every route on bundled fixtures38```3940`selftest.py` prints `missing tools:` first if naga, glslang or node is absent. Every41other line must read `ok`.4243The GPU checks run headless Chromium on SwiftShader. On claude.ai and Claude Code on44the web, Playwright's Chromium is already installed. Elsewhere, point `CHROME_PATH` at a45Chromium binary.4647## Minify a shader4849```bash50PYTHONPATH=$SKILL/scripts python3 -m forge minify in.wgsl -o out.wgsl # prints bytes before -> after51python3 $SKILL/scripts/verify.py minify in.wgsl # always run this52```5354`verify.py minify` validates the output with naga and compiles both versions in Tint.55It then runs every compute entry point that binds only buffers on random typed inputs:56the original twice and the minified once. It exits 1 on any failure.5758Read the result lines:59- `ok compute main bit-identical`: the minified kernel computes the same bytes.60- `skip ... original disagrees with itself`: the original has a race for this dispatch61 shape. Pass the real shape with `--dispatch 64,1,1`.62- `skip ... textures or samplers bound`: that shader was compiled, not executed. To prove63 a render shader unchanged, render it in its real host before and after and compare64 pixels.6566Options:67- `--no-aliases` skips the `alias a=vec4f;` pass. Use it for shaders served gzipped: on68 the 86-shader corpus that pass saves 1.7% raw bytes but adds 0.9% gzip bytes.69- `--keep a,b` protects extra names from renaming and removal.7071Entry-point names, `override` names, binding numbers and attributes are never changed.72Struct members spelled like swizzles (`x`, `rgb`) or like builtin result fields (`fract`,73`exp`, `whole`) are never renamed either.7475Expect 30–35% of the original bytes on typical shaders (34% on the corpus, against 56%76for LucentFlux wgsl-minifier on the files both handle). Shaders that are already terse77land nearer 50%: Tilt Rally's nine came out at 51%.7879`python3 -m forge fmt out.wgsl` pretty-prints minified code for reading.8081## Convert GLSL to WGSL8283```bash84PYTHONPATH=$SKILL/scripts python3 -m forge glsl shader.frag -o shader.wgsl [--minify]85python3 $SKILL/scripts/verify.py glsl shader.frag --png /tmp/port.png # always run this86PYTHONPATH=$SKILL/scripts python3 -m forge html toy.glsl -o preview.html # Shadertoy only87```8889The input kind is detected automatically:9091| input | detected by | output |92|---|---|---|93| Shadertoy | `mainImage` and no `main` | the same interface as compiled scenes: uniform `{r, t}` at binding 0, `vs` and `fs` entries; y flipped to Shadertoy's bottom-left origin, alpha forced to 1 |94| WebGL 2 (`#version 300 es`) or WebGL 1 (no version) | version line | one WGSL entry point `main`; loose uniforms gathered into one std140 block at binding 0, each `sampler2D` split into a texture and a sampler from binding 1 |95| Vulkan GLSL 450 | `#version 450` | passed through as written |9697The stage comes from the extension (`.vert`, `.frag`, `.comp`) or from the content98(`gl_Position`, `local_size_x`). `--stage` overrides it.99100`forge glsl` prints the `binding` lines the host must now supply, with byte offsets. A101WebGL program set uniforms by name; WebGPU writes one buffer at those offsets, and102std140 puts a `vec3` or `mat3` column on a 16-byte boundary. `note:` lines report every103rewrite the converter made.104105Translation goes through naga's GLSL reader. When naga refuses the source, it is106compiled to SPIR-V with glslang and naga translates that instead (`--backend` forces107either). The glslang route accepts more GLSL but mangles function names; minifying108renames them anyway.109110`verify.py glsl` validates and compiles both the WGSL and its minified form.111- **Shadertoy code** is also rendered by Chrome's WebGL2 as the reference and by the112 WGSL on WebGPU, at t=0 and t=1.7. It must reach 30 dB PSNR, and the minified version113 must draw identically.114- **Other GLSL** has no reference renderer, so it is compiled only. To check a compute115 port, run the WGSL with `scripts/forge/gpu.py` `run_jobs` (kind `compute`) and compare116 the result with a numpy version of the algorithm.117118## Compile an SVG to a shader119120```bash121PYTHONPATH=$SKILL/scripts python3 -m forge svg icon.svg --minify -o icon.wgsl122python3 $SKILL/scripts/verify.py svg icon.svg --size 512 --png /tmp/check.png123PYTHONPATH=$SKILL/scripts python3 -m forge html icon.svg --minify -o preview.html # live page with host code124```125126Read every `warning:` line. Skipped elements (`text`, `image`, `clipPath`, `mask`,127`filter`, `pattern`, `marker`) are missing from the shader. `verify.py svg` reports128mean error, PSNR and an ink ratio against Chromium's own SVG rendering. When anything129was dropped, it also scores against Chromium rendering the SVG with those parts removed130(text, masks, clips, filters, animations), and the pass/fail uses that second score. The131first score tells you how much the dropped parts mattered; the second tells you whether132what was compiled is right. Then `Read` the PNG: reference | shader | difference ×4.133134The shader's interface is fixed:135- `@group(0) @binding(0) var<uniform> u: U` with `struct U { r: vec2f, t: f32 }`, which136 holds the canvas size in pixels and the time in seconds (16-byte buffer:137 `[w, h, t, 0]`).138- Vertex entry `vs`; draw 3 vertices, no vertex buffers.139- Fragment entry `fs`, which returns premultiplied RGBA (`alphaMode: "premultiplied"`).140141`forge html` writes a working host page to copy from.142143**Self-painting.** `--paint-in 4` (`Scene(paint_in=4)`) makes the shapes appear one by one144in paint order over 4 seconds of the time uniform, each fading in over its own slot.145`--loop` holds the finished picture, then starts again, and `forge html` shows it live.146Table rows stop the loop at the first unrevealed row, so early frames are also cheaper to147draw. The reveal follows SVG order (back to front), because reordering overlapping shapes148would change the picture. `verify.py svg X.svg --paint-in 4` checks the contract:149- **t=0:** only the background shows.150- **While painting:** no pixel's coverage ever decreases. Ink can legitimately fall when151 light shapes paint over dark ones, so coverage is the measure.152- **Finished frame:** bit-identical to the static shader, minified or not.153154**Size against accuracy.** `--grid N` (`Scene(grid=N)`) sets the path coordinate step,1551/N of a nominal pixel. The default of 64 sits at the knee. On Twemoji's lion at 512 px,156grid 16 saves 10% of gzip bytes and costs 4.6 dB, and grid 128 adds 4% for 0.6 dB.157Rounding float literals to fewer digits was measured and rejected. Literals are already158short, so rounding to 5 digits saved 0.3% of a scene shader's bytes and 0.05% of a159hand-written one's, and it changed pixels.160161**Large scenes (matplotlib output, traced images, icon sets).**162- **Shape table:** four or more consecutive plain shapes become rows in a table that163 one loop draws. A plain shape is a static path or primitive with a solid fill or164 stroke.165- **Storage buffer:** path data over 8,192 ints moves out of the shader into a storage166 buffer at `@group(0) @binding(1)` (`var<storage, read> D: array<i32>`).167 `forge svg -o x.wgsl` then also writes `x.bin`, which the host uploads.168 `scene.data_buffer` holds the same bytes in Python, and `forge html` embeds them.169- **Segment warning:** a scene with more than 20,000 path segments is flagged, because a170 pixel walks every segment of every shape whose bounding box covers it.171172## Build a scene in Python173174Use this when the shapes come from code, need animation, or need operations SVG lacks.175`references/scene-api.md` lists the whole API; `references/example_scene.py` is a176complete animated scene.177178```python179from forge.scene import Scene, T, sin, radial, smooth_union, Circle180s = Scene(320, 200, background="#101418")181s.circle(160, 100, 40 + 4 * sin(T * 2), fill=radial(160, 100, 50, ["#fff7d6", "#ff8a3d"]))182with s.group(translate=(160, 100), rotate=T * 30):183 s.rect(-2, -80, 4, 20, rx=2, fill="#ffd36e")184s.add(smooth_union(Circle(60, 150, 25), Circle(90, 150, 20), k=12), fill="hotpink")185open("scene.wgsl", "w").write(s.compile(minify=True))186open("frame.svg", "w").write(s.to_svg(t=1.3)) # reference frame for checking187```188189Any number can be an expression in `T`. Check an animated scene at a time where its190animated terms are large, not just at t=0: render the shader with `time` set and compare it191with Chromium rendering `to_svg(t)`. `scripts/forge/gpu.py`'s `run_jobs` takes `render`192and `svg` jobs with a `time` field. SDF-only features (`smooth_union`, `subtract`,193`intersect`, `rounded`, `onion`, `soft`) make `to_svg` raise, because SVG cannot express194them. Check those by rendering and reading the image.195196## When to abandon it197198- **The SVG relies on unsupported features.** If warnings list `text`, `clipPath`,199 `mask` or `filter` and those carry the design, the shader will be wrong. Rasterise200 instead, or convert text to paths first.201- **The shader is too slow.** Every pixel loops over every path segment. A scene with202 thousands of segments (a detailed illustration, a map) is too heavy as one shader:203 draw it as triangles, or bake it to a texture.204- **A shader under 1 KB.** Expect only small gains, so minify only if bytes really matter.205206## Failure modes207208- **`naga could not translate the GLSL` and glslang also fails** → read glslang's message.209 It is usually real GLSL that Vulkan forbids, such as a sampler passed as a function210 argument (a `note:` names it). Rewrite that part by hand: pass the texture and sampler211 separately.212- **`Tint compiles WGSL` FAILs with `unresolved call target 'subgroupBarrier'`** → the213 WGSL came from an older copy of this converter. Since 0.2.0 it strips the subgroup and214 texture barriers that naga adds for GLSL `barrier()`, keeping `workgroupBarrier()`.215- **A WebGL port renders but the colours or positions are wrong** → check the uniform216 buffer against the `binding` offsets that `forge glsl` printed. The usual mistake is a217 `vec3` written tightly packed instead of on its 16-byte boundary.218- **A Shadertoy port renders upside down in your own host** → you dropped the219 `fragCoord` flip. The shader expects the uniform `r` to hold the canvas size in pixels.220- **Integer `%` or division differs from WebGL for negative operands** → GLSL leaves221 these undefined, and the WGSL takes one definite answer. Rewrite the GLSL to stay222 non-negative.223224- **`naga` says `expected array<i32, 2>, but got array<i32, 2>`** → this is naga 30's225 quirk with an alias inside a template argument. The alias pass already avoids it; if226 it appears, rerun with `--no-aliases` and report the input.227- **Tint compiles the minified shader but not the original** → expected when dead-code228 removal drops unused code that Tint rejects; the reachable code is unchanged. Two naga229 test files do this.230- **`compute ... bit-identical` FAILs with a 2-D or 3-D `--dispatch`** → probably a race231 in the original: invocations that share `id.x` write the same element, and two original232 runs happened to agree. Rerun with the host's real dispatch shape before believing it.233 Diagnosed 2026-11-02 on Tilt Rally's `SMOKE_SIM`: 4×4 failed, while 4×1 was identical234 on three seeds.235- **The harness prints `harness failed` or every GPU job errors** → Chromium or WebGPU is236 unavailable. Check `node -e "require('playwright')"`, set `CHROME_PATH`, and keep the237 `--enable-unsafe-webgpu --use-webgpu-adapter=swiftshader` flags that238 `scripts/harness/gpu.mjs` passes.239- **Small text or hairlines look bolder than in the browser (ink ratio 1.03 to 1.07 on240 text-heavy charts)** → antialiasing works from one distance per shape, so a feature241 thinner than a pixel gets about half a pixel of coverage too much. The geometry is right.242 Render larger, or accept it. Measured on a matplotlib chart whose labels are glyph243 outlines: ink ratio 1.067 at 512 px.244- **`warning: N path segments`, and a frame takes seconds** → per-pixel cost is the245 number of segments under the pixel. Simplify the paths (fewer points) or bake the image246 to a texture; this compiler has no tile binning.247- **`colour 'var(...)' unsupported`** → a custom property the reader could not resolve.248 Plain `var(--x)` from CSS rules, inline styles and `@property` initial values is249 supported. A malformed name stays unresolved and paints black, which is what the250 browser does with the invalid declaration too.251- **The ink ratio is below 0.97 or above 1.03 at large sizes** → a geometry error, not252 antialiasing: antialiasing error shrinks as size grows, and geometry error does not.253 Compare `verify.py svg --size 128` with `--size 768`.254- **Curves look faceted at extreme zoom** → curves are fitted to 0.02 of the SVG's own255 pixel, which holds to about 50× magnification. Lower it with `--tolerance 0.02`; the256 default is 0.2, of which a tenth goes to the curve fit.257258## Verification259260- **Minifier:** `verify.py minify` must print no FAIL. A good result passes naga, compiles261 in Tint and gives bit-identical compute buffers. A *bad success* compiles but computes262 something else: a renamed name the host looks up, or a shader with textures that was263 only compiled. For the second case, render it in its host before and after and compare264 pixels.265- **GLSL:** `verify.py glsl` must print no FAIL, and for Shadertoy code the PNG rows266 (WebGL | WGSL | difference ×8) must show the same picture. A *bad success* is two blank267 images that match: check that the picture has content. Another is a non-Shadertoy port268 that compiles but was never run against anything.269- **SVG:** `verify.py svg` must print no FAIL, and the PNG must look right. A *bad270 success* is a high PSNR on an SVG whose `warning:` lines show that elements were271 dropped. A missing element still scores well when it is small.272273## Diagnosed failures (fixed, kept as signals)274275- 2026-11-02, **paint-in check**: the first version required ink to rise from frame to276 frame. It failed on Twemoji's lion, where the dark mane paints first and the light face277 covers it, so ink fell from 131% to 100% of the final value. That is correct painter's278 order. The invariant is coverage per pixel, which is what the check now measures.279280- 2026-11-02, **real Python-made SVGs from the experiments repo**:281 - **matplotlib Pareto chart:** 235 KB of unrolled WGSL killed SwiftShader's pipeline282 compiler ("A valid external Instance reference no longer exists"). The shape table283 fixed it: 6.7 KB of WGSL, 29.0 dB.284 - **Palette-cycling cat:** 880 shapes broke Tint's array-constructor limit ("excessive285 number of elements (>32767)"). The storage buffer fixed it: 34.2 dB, ink ratio 1.000.286 - **Traced dog:** same limit. With the buffer and masks excluded it scored 41.0 dB, but287 took 215 s per frame on SwiftShader, which led to the segment warning.288 - **Also found:** a missing `f` prefix in `svg-palette-cycle/build.py` writes the289 literal `var(--b{len(BANDS) - 1})` into its SVG.290- 2026-11-02, **a switch case that returns**: naga's GLSL reader rejected291 `switch (i) { case 0: return a; ... }` ("fall-through switch case block"), even with a292 `break;` after the `return`. The auto backend now falls back to glslang.293- 2026-11-02, **subgroupBarrier**: GLSL `barrier()` came out of naga as four barriers,294 `subgroupBarrier()` among them, and Tint rejects that call. naga validated the output,295 so only the Tint compile in `verify.py` caught it.296- 2026-11-02, **html preview**: `forge html` had never worked in 0.1.0. A `%` in its CSS297 broke the `%`-formatting of the page template, and nothing ran the command until the298 GLSL work. `selftest.py` now covers every route.299- 2026-11-02, **zero error that looked suspicious**: every Shadertoy fixture matched WebGL300 at 0 error. The images were checked and are real: WebGL and WebGPU both run on301 SwiftShader in the container. Expect small floating-point differences on real GPUs,302 hence the 30 dB bar rather than exact equality.303304- 2026-11-01, **line segments**: flattening curves to line segments at the SVG's size left305 icons 1.8% too light at 512 px (ink ratio 0.982), and the error never shrank with size.306 The fix was to keep curves as quadratic Béziers with exact distance. The signal was the307 ink ratio at two sizes.308- 2026-11-01, **missing parentheses**: an animated radius compiled without parentheses,309 `- 44+3*sin(..)`. Frames at t=0 and t=4.7 still matched closely, because the animated310 term was near zero there, and t=1.3 diverged visibly. The lesson: test animation at311 large values of its animated terms.312- 2026-11-01, **packed arc flags**: `0 014.907` was misread, and two Simple Icons logos313 failed to parse. No hand-written test packed flags that way.