summaryrefslogtreecommitdiff
path: root/docs/typ/reference.typ
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-12 10:56:42 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commitf2b02c455f2bcdfb905a015eefbb630a28b4b12e (patch)
treec344c7ad42ec288dd5e1ebd0eb6d25f5aa2fbccc /docs/typ/reference.typ
parentfc38c73c59f7855a4caad8aa4d3bb8e023309c13 (diff)
downloadpardes-f2b02c455f2bcdfb905a015eefbb630a28b4b12e.tar.gz
pardes-f2b02c455f2bcdfb905a015eefbb630a28b4b12e.zip
addons: an addon can hand the frontend a GPU scene (ABI 3.1), and a snake drawn by shaders does; a commit's patch keeps its own +Diff pane; a real ZLS checked through the window build
ABI 3.1 appends an optional `gpu` callback and its context to pa_paint: one self-contained sketchbook SGPU v1 scene for the pane, at most 4 MiB, copied during the call, the last successful call winning. The SDL frontend runs it on its own GPU through sketchbook's executor and composites its target texture into the pane; replicas carry the scene beside the authoritative pane frame; cells and rasters stay the fallback for terminals, older hosts and frontends without an executor. addons/snake_shader is such an addon (`zig build snake-shader`, the SnakeShader word: a board that follows its pane, buffered turns, a CRT look), with test/gpu_snake.py, test/gpu_snake_interaction.py and test/gpu_upgrade.py. Commit patches open as `+Diff-<short-hash>` and reuse only their own commit's pane, so another paged patch no longer replaces one already open. The language-server client looks in the standard per-user bin directory, which desktop launchers often leave out of PATH, and takes an empty answer that beats the startup progress notification onto the wire; test/real_zls.py checks imports, hover, references, rename previews, diagnostics and completion against a real ZLS from a private home. The dump's schema reader skips two fields older builds persisted, and a replica's shadow of a kind ticks when the authority's does. The reference, the guide, the building and setup notes and the changelog say so. The working copy as it stood on 2026-11-12; message written by Claude from the diff, at the author's request.
Diffstat (limited to 'docs/typ/reference.typ')
-rw-r--r--docs/typ/reference.typ27
1 files changed, 27 insertions, 0 deletions
diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ
index 030b7c6a..7360179f 100644
--- a/docs/typ/reference.typ
+++ b/docs/typ/reference.typ
@@ -1375,3 +1375,30 @@ with Client(sys.argv[1]) as c: # a socket path, or (ip, port)
[`pty/run` output], [64 KiB],
[file name component], [255 bytes],
)
+
+== Optional GPU scenes
+
+ABI 3.1 appends an optional `gpu` callback and its context to `pa_paint`.
+An addon checks `api->abi >= 0x30001` before reading it; a null callback
+means unsupported. `addon.Paint.gpu(bytes)` does both checks. The callback
+copies at most 4 MiB during the call, so a stack buffer is valid. It takes
+one self-contained sketchbook SGPU v1 scene, not device pointers. Paint
+cells or a raster too: terminals, older hosts and frontends without a GPU
+scene executor keep that fallback. Acceptance means the host can carry
+the scene, not that every view can render it.
+
+The SDL frontend runs scenes on its own GPU and composites their target
+textures; replicas carry the scene alongside the authoritative pane frame.
+The scene codec and executor live in sketchbook (`src/gpu/scene.zig` and
+`src/gpu/Executor.zig`). GPU support adds no required addon operation.
+
+`zig build snake-shader` builds `zig-out/lib/libsnake_shader.so` (with
+`glslc`). Load it with `Addon load /absolute/path/libsnake_shader.so`, then
+run `SnakeShader`: a GPU board with square cells that expands and shrinks
+with its pane. `h j k l` or arrows steer, and `r` restarts. Two turns can
+be buffered; a late turn gets 60 ms of grace. Losing focus pauses movement.
+Hover highlights a cell; bloom, colour mapping, RGB phosphors and scanlines
+give it a CRT appearance, with a subtle food pulse and phosphor shimmer
+while paused. A severe shrink can shorten the tail, keeping the score.
+The text fallback remains available. A running older host must be upgraded
+to display the GPU version.