summaryrefslogtreecommitdiff
path: root/examples/shaders/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/shaders/README.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz
sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/shaders/README.md')
-rw-r--r--examples/shaders/README.md81
1 files changed, 81 insertions, 0 deletions
diff --git a/examples/shaders/README.md b/examples/shaders/README.md
new file mode 100644
index 0000000..98b5bc0
--- /dev/null
+++ b/examples/shaders/README.md
@@ -0,0 +1,81 @@
+# 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.