summaryrefslogtreecommitdiff
path: root/examples/shaders/README.md
blob: 98b5bc071e6f54c8ae4a5ffa04ce22dca7e42000 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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.