# shaders Five Book of Shaders examples, each written twice, in Zig (`shaders/zig`) and in GLSL (`shaders/glsl`), drawn by one sketch: left/right or a click change example, `l` the language. `zig build e2e` screenshots every pair into `.zig-cache/e2e/`, and checks a hot reload (`test/reload.script`, `addReloadCheck` in `build.zig`): one edit to a Zig shader, one to a GLSL shader and one to the sketch's Zig code, State kept, each edit visible. `zig build run` with `zig build lib --watch` beside it is the live loop. | example | Book of Shaders | Zig vs GLSL pixels | | --- | --- | --- | | expo | 05/expo.frag | equal (±1/255) | | hsb_wheel | 06/hsb-colorwheel.frag | equal (±1/255) | | polar | 07/polar.frag | equal (±1/255) | | truchet | 10/2d-random-truchet.frag | identical | | clouds | 13/clouds.frag | animated; differs only by the time between shots | ## Zig shaders in 0.17: viable, with four sharp edges Zig compiles a fragment or vertex shader to Vulkan SPIR-V with its own backend: `export fn main() callconv(.{ .spirv_fragment = .{} })`, stage I/O and resources as `@extern` pointers in the `.input`, `.output`, `.uniform`, `.storage_buffer` and `.push_constant` address spaces, with `.decoration = .{ .location }` or `.{ .descriptor = .{ .set, .binding } }`, and builtins in `std.spirv` (`frag_coord`, `vertex_index`, `position_out`, barriers, image sampling). `@sin`, `@floor`, `@sqrt`, `@exp2`, `@mod` and the like become GLSL.std.450 instructions. The output passes `spirv-val`, runs on SDL_GPU, matches glslc's pixels, compiles as fast as glslc does, and, after one fix-up, translates to WGSL through naga like the GLSL shaders. `sb.addZigShaders` (sketchbook's build.zig, prototyped here) returns the same `Shaders` (SPIR-V module and WGSL twin) as `addShaders`, so a sketch cannot tell which language a shader came from. The edges, and what this project does about each: 1. **Target `spirv32-vulkan`, self-hosted backend.** `spirv64` declares `PhysicalStorageBufferAddresses`, which naga refuses. Without `use_llvm = false`, `-O ReleaseFast` goes through LLVM and writes an empty file with no error. 2. **Zig puts `Aligned N` on every `OpLoad`/`OpStore`.** Vulkan accepts it; naga's SPIR-V reader fails with "invalid operand count 6 for Load", and `spirv-opt` keeps the operands. sketchbook's `tools/spirv_strip.zig` (~30 lines) drops them before anything else reads the module. 3. **Not all of `std.math` is shader code.** `std.math.atan2` indexes const tables through generic pointers, which logical addressing forbids (compile error). `gl.zig` calls GLSL.std.450 `Atan2` through inline SPIR-V assembly instead: four lines. Expect the same for anything table-driven. 4. **Shared uniform structs need a vec2 that changes with the target.** Native `extern struct`s cannot hold `@Vector`s, and in a uniform block a `[2]f32` gets array stride 4, which naga and WebGPU reject (std140 wants 16). Native Vulkan happened to render it. `uniforms.zig` uses `pub const vec2 = if (builtin.cpu.arch.isSpirV()) @Vector(2, f32) else [2]f32;` so one struct serves the sketch, the Zig shaders and the generated GLSL, and `abi.gpu.uniform` still checks std140 on the CPU side. Ergonomics: Zig does not broadcast scalars (`v * 2.0` is a compile error, `@splat` needs a result type), so GLSL's `vec3(y)` and `3.0 - 2.0 * f` become `gl.v3(y)` and `gl.v2(3) - gl.v2(2) * f`. Swizzles become indexing (`st[1]`, `.{ fc[0], fc[1] }`). The Zig ports are the same length as the GLSL ones (9/13/7/17/41 lines vs 11/14/8/18/37) but noisier. In exchange you get real functions and types, `comptime`, `for (0..5)`, modules shared with the CPU side (the same `Uniforms`, the same noise function could run on both), and one toolchain: no glslc, and no `#include` or `#define` preamble. The SPIR-V is 2–4× larger than glslc's (names and debug strings), which costs nothing at this scale. ## Not verified - The web build: `zig build web` produces the page, and naga validates every WGSL twin, but headless Chrome here only offers SwiftShader, which loses its device before the first frame. Open `zig build serve` in a real browser to check. - Compute shaders and storage buffers in Zig (`@SpirvType(.{ .runtime_array = T })` exists; not tried here), and textures and samplers. Reloading a Zig shader edit is checked (`test/reload.script`, through `load`); the file watcher path (`zig build lib --watch`) only by hand.