test/test-shader-limits/README.md

1# test-shader-limits

3The measured proof for the v0.11.3 shader additions, on native and on the

4`web` config: a Game of Life stepped entirely on the GPU (a step shader bound

5with `with-shader` inside `with-render-target`, ping-pong between two render

6targets), colours drawn from `vec4 palette[8]` and `float levels[4]` uniform

7arrays, and a 4x4 texture made from pixels and refilled with `update-texture`.

8`verify.mjs` reads the presented frame on each target and compares every cell

9against a CPU Life run of the same seed, every strip against the array entries,

10and every texel against the post-update pattern.

12## Native arm

14Builds against the sigil-graphics checkout two directories up (`dev-redirects.sgl`).

15The app needs an X display; use a worker-owned Xvfb, never a real session.

17```sh

18guix shell xorg-server -- Xvfb :91 -screen 0 1400x900x24 +extension GLX -nolisten tcp &

guix shell -m ../../manifest.scm -- sh -c 'CPATH=$GUIX_ENVIRONMENT/include LIBRARY_PATH=$GUIX_ENVIRONMENT/lib sigil deps install --redirects dev-redirects.sgl && sigil build --redirects dev-redirects.sgl'

DISPLAY=:91 guix shell -m ../../manifest.scm imagemagick xdotool -- sh -c 'LD_LIBRARY_PATH=$GUIX_ENVIRONMENT/lib node verify.mjs --native'

21```

23The verifier runs `build/dev/bin/test-shader-limits`, waits for its

24`shader-limits: ready` line, captures the window with `import -window`, and

25prints one `PASS`/`FAIL` line per sub-arm, then `GREEN`/`RED`; exit 1 on any

26FAIL, 2 when a wait ran out or the setup was wrong (`TIMED-OUT`, `SETUP-FAILED`).

27The capture lands at `/tmp/test-shader-limits-native.png`.

29## Web arm

31Needs `binaryen` (wasm-opt) for the build and `google-chrome` plus Node 22 for

32the verifier (headless Chrome with SwiftShader, driven over the DevTools

33Protocol, no puppeteer).

35```sh

36guix shell binaryen -- sigil build --redirects dev-redirects.sgl --config web

37node verify.mjs --web

38```

40Adds two sub-arms: `imports` (the wasm imports only `gl`, `sigil_wasm_gles3` and

41wasi) and `console` (no error entries). The page screenshot lands at

42`/tmp/test-shader-limits-web.png`.

44## Options

46- `--grid N`, `--steps N`: the field size (64) and the generations to run (8).

47- `--expect-steps N`: what the verifier models; different from `--steps` it must

48 go RED (the assertion-layer control).

49- `--rule reaction --steps 4000 --substeps 8 [--grid 128]`: the Gray-Scott bonus:

50 u and v packed into 16 bits each across the RGBA8 target (8 bits per quantity

51 freezes the field), the step shader loaded with `'none` blending. The field

52 sub-arm then checks that a pattern grew from the three seed squares rather than

53 comparing cells (there is no closed form), and the screenshot shows it.

54- `--bench [--grid 512]`: run the app in bench mode and print its

55 `frame-ms MEAN MAX tick-ms MEAN MAX` lines (wall time between frames, and the

56 tick's own step+present CPU time), no verdict.

57- `--verbose` (web): dump the page console, including sokol's log lines.

59Running the app by hand: `test-shader-limits [--grid N] [--steps N] [--rule life|reaction]

60[--substeps N] [--bench]

61[--hold SECONDS]` natively; `index.html?grid=N&steps=N&rule=NAME&substeps=N&bench` on the web.

63## What it proves, and what it does not

65Every cell of the field is compared, so a wrong neighbour offset, a wrong wrap

66(the glider crosses both torus edges), a wrong `u_resolution` inside the pass,

67a filtered read, or a pass that silently draws nothing all read as a FAIL; the

68sabotage legs that showed each of those going red are in the task note

69`tasks/sigil-graphics-shader-limits`. Frame timing under Xvfb (llvmpipe) and

70SwiftShader is software rendering on both arms: it bounds the CPU-side cost of a

71step, not what a phone's GPU will do.

73## Wayland arm

75`verify-wl.mjs` is the native arm for a Wayland compositor the caller owns

76(a headless sway); it captures the window through `swaymsg` and `grim`

77instead of `xdotool` and `import`, and pins the window to the child's pid.

79```sh

80WAYLAND_DISPLAY=/run/user/$UID/<private>/wayland-1 SWAYSOCK=<its ipc socket> \

81 guix shell -m ../../manifest.scm imagemagick grim jq -- \

82 sh -c 'LD_LIBRARY_PATH=$GUIX_ENVIRONMENT/lib node verify-wl.mjs --native'

83```

85With sigil-desktop 0.10 the binary's NEEDED list is libm and libc only, so

86`guix shell --pure -m <sigil-desktop>/guix/run-wayland.scm -- build/dev/bin/test-shader-limits`

87runs it with no LD_LIBRARY_PATH at all (the runtime libraries resolve

88through sigil-desktop's dlopen fallback).