diff options
Diffstat (limited to 'examples/shaders/README.md')
| -rw-r--r-- | examples/shaders/README.md | 81 |
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. |
