summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md1115
1 files changed, 970 insertions, 145 deletions
diff --git a/README.md b/README.md
index e2d8ab6..f54ab82 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,23 @@ pub fn draw(s: *const State, f: *sk.Frame) void {
}
```
+## Examples
+
+The standalone example packages live in [`examples/`](examples/):
+
+- [`noc`](examples/noc/): 21 Nature of Code sketches. Select one with `-Dsketch=flocking`.
+- [`shaders`](examples/shaders/): five shader examples in both Zig and GLSL.
+- [`vecanim`](examples/vecanim/): vector animation scenes. Select one with `-Dscene=scenes/live.zig`.
+- [`micscope`](examples/micscope/): records the microphone or opens sound files, plays them either way, and shows waveform, spectrogram and spectrum; a tuner.
+- [`spheres`](examples/spheres/): the three-body problem on the GPU, each body a voice synthesised by a compute shader.
+- [`live`](examples/live/): a tiny language for sound and picture, typed over its own picture: every line that parses is compiled to a tape one GPU interpreter runs per pixel and per sample.
+- [`talk.zig`](examples/talk.zig): a talk with a slider in it, a sketch that runs its own `anim.Deck` (`zig build test-talk` plays it).
+- [`manual.zig`](examples/manual.zig): Figure 2-1 of the Intel SDM comes alive, then ADD's opcode table is written row by row and its `80 /0 ib` turns into SUB's `80 /5 ib`: PDF pages as vector shapes and parts of them (`zig build manual -Dmanual=PDF`; see Animation, PDF pages and parts).
+
+Run `zig build run` inside a package, with `zig build lib --watch` in a second
+terminal for hot reload. `zig build test` runs its headless checks;
+`zig build web` builds the selected example for the browser.
+
## An app
An app is an ordinary module. Every declaration is optional:
@@ -29,35 +46,49 @@ An app is an ordinary module. Every declaration is optional:
| Declaration | Meaning |
| --- | --- |
| `name`, `width`, `height` | Window title and initial canvas |
-| `State` | Saved to a file, snapshotted, replayed: what `update` changes. No pointers and no host handles (compile errors). |
+| `audio_pull` | Samples the sound device takes at once (see sound) |
+| `State` | The one thing a sketch keeps: what `update` changes, saved in one file with its history, replayed. No pointers, no host handles, and at most 32 MiB, half of a save (compile errors). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
-| `Store` | On disk, at the same address in every run: survives reloads and restarts. Big data that is not replayed (a recording, a document). May point into itself; no host handles. |
-| `init(state, host)` | Setup for brand-new state, after the declared defaults |
+| `init(state, host)` | Seed brand-new state, after the declared defaults |
+| `setup(session, init) !void` | Initialize resources once per fresh Session, including startup with restored State |
| `update(state, input)` | **Deterministic**: the host replays recorded input through it |
-| `draw(state, session, store, frame)` | Pictures and sound, as commands; may change Session and Store |
-| `command(state, session, store, console, line) !bool` | Console lines the host does not know |
+| `draw(state, session, frame)` | Pictures and sound, as commands; may change Session |
+| `command(state, session, console, line) !bool` | Console lines the host does not know |
| `commands` | Console completions |
Functions take the parameters they name, matched by type and in any order:
-`draw(s: *const State, f: *sk.Frame)` and `draw(s: *const State, store:
-*Store, ss: *Session, f: *sk.Frame)` both work. `update` can only ask for
+`draw(s: *const State, f: *sk.Frame)` and `draw(f: *sk.Frame, ss: *Session,
+s: *const State)` both work. `update` can only ask for
`State` and `Input`; asking for more is a compile error, since a replay could
not reproduce it.
+`setup` receives `*sk.Init` with `host` and the `session` allocator; it may
+also request Session or Host directly. It gets no State, Input,
+or Frame. Load assets and create/upload GPU buffers there, then use those
+resources in `draw`. `try init.host.writeBuffer(buffer, offset, bytes)` submits
+a copy immediately; the source bytes may be released when it returns. WebGPU
+uploads require four-byte-aligned offsets and sizes.
+
+Resource setup runs after Session defaults, once on startup even when State was
+restored from disk, and again if a reload changes Session's layout. Compatible
+reloads and ordinary state resets preserve the Session and do not rerun setup.
+The browser invokes it during its initial setup too. A hook may return `void` or
+`!void`; uncaught errors are logged and disable app callbacks, while the native
+host console and 9P controls remain available. Restart after fixing a failed setup.
+Use a Session error field and handle the error inside setup when the app needs
+to display an initialization failure. `zig build test-setup` checks this lifecycle.
+
Memory comes by lifetime, one allocator each:
| Allocator | Lifetime | Released |
| --- | --- | --- |
| `f.scratch` | this frame | all at once, after the frame is drawn |
| `f.session` | this process | one allocation at a time; the rest when Session's layout changes, along with the images and buffers the session made |
-| `f.store` | on disk, `<state>.store` | one allocation at a time; `--fresh` empties it |
-A Store layout change migrates field by field like State: unchanged fields,
-pointers included, keep their values, since the store never moves.
-`command` gets the session and store allocators on its `Console`.
+`command` gets the session allocator on its `Console`.
-`update` sees only State, so when a key should do something to Session or
-Store, State carries a request: `seek: sk.Request(f32)`, sent with
+`update` sees only State, so when a key should do something to Session,
+State carries a request: `seek: sk.Request(f32)`, sent with
`s.seek.send(0.5)`. Session keeps an `sk.Handled`, and `draw` runs
`if (ss.seek.take(s.seek)) |to| ...` once per request. A fresh Session
counts earlier requests as handled, so nothing re-fires after a restart.
@@ -76,7 +107,10 @@ trackpad's or a touch screen's pinch arrives as ctrl+wheel with no key
events at all. `update` is called once per frame, with that frame's events
ending in its tick, live and replayed alike; in `update`, `input.now` and
`input.dt` come from that tick (`dt` read back from the tick's f32
-seconds, so a replay sees the same bits). `input.mouse_x`/`buttons`/`held`
+seconds, so a replay sees the same bits). Interactive Wayland frames use the
+display-paced clock for update and draw automatically; unsupported backends use
+wall time, and the browser uses its animation-frame timestamp.
+`input.mouse_x`/`buttons`/`held`
follow the events fed so far. So time-driven and pointer-driven sketches
replay exactly. Fields no event carries (`width`, `window_width`,
`console`, `frame`) are not replayed: a sketch that reads them in `update`
@@ -84,62 +118,45 @@ can replay differently. `input.started` is true on the first update after
the program starts, never after a reload: state is saved, so this is where
to stop what should not resume on its own. In `draw`, `input.jumped` says
State got where it is other than by `update` from what the last `draw`
-saw: the first frame, a seek, step, snapshot load, `set`, `reset`, play or
+saw: the first frame, a seek, step, a mark's `load`, `set`, `reset`, play or
record start, a sketch command, a reload. Anything `draw` piles up in
Session (a trail in an offscreen image) is stale then; repaint it from
State.
`draw` gets a `Frame`: `clear`, `fill`, `shape`, `shapeColors`, `image`,
-`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `audio`, `microphone`, `pixels`, `gpu`,
+`imageAt`, `target`, `blend`, `text`, `textIn`, `textScaled`, `print`, `paragraph`, `clip`, `canvas`, `cursor`, `voice`, `gain`, `audio`, `audioBuffer`, `microphone`, `pixels`, `gpu`,
`compute`, `upload`, `download`, `openFile`, `run`, `quit`, plus the three allocators and
`f.host` (`loadImage`, `decodeImage`, `newImage`, `newBuffer`, `loadSound`,
-`decodeSound`, `samples`, `readFile`, `env`, `log`, `textSize`). Commands may be built
+`decodeSound`, `newSound`, `samples`, `readFile`, `appendFile`, `writeFile`, `env`, `log`, `textSize`). Commands may be built
from locals: the methods copy what they keep (text, GPU descriptions,
uniforms) into scratch. Bulk data (vertices, samples, pixels, uploads) is
-not copied and must outlive the frame: scratch, session or store memory.
-
-`f.text(x, y, scale, bytes, color)` draws one line from its top left
-corner; scale 1 is a 13 px monospace face (8 px a character on a 16 px
-line), and any scale works, 1.5 or 7.25. `f.host.textSize(scale, bytes)`
-is the width and line height it covers, for laying out tables and code.
-Natively the text is shaped by Pango and drawn at the canvas's own pixels,
-with advances rounded to whole pixels at that size: sharp at any size, but
-a width is not a multiple of the scale (ten digits are 80 px at scale 1,
-230 at scale 3), so measure at the scale drawn. The font is Go Mono, built
-in; `SKETCHBOOK_FONT="JetBrains Mono"` in the environment puts an
-installed family before it. On the web it is the page's `monospace`, 8 px a
-character.
-
-`f.textIn(face, x, y, scale, bytes, color)` is the same line in another
-face of the Go family, all six bundled in the binary (`sk.Face`): `.mono`,
-`.mono_bold`, `.mono_italic` for data and code, `.sans`, `.sans_medium`,
-`.sans_bold` for what is said about it; and `.code`, `.code_bold`,
-`.code_italic`, `.code_medium` are JetBrains Mono NL (no ligatures),
-bundled too, for programs. `f.host.textSizeIn(face, scale, bytes)`
-measures a line. The seven monospaced faces advance alike (0.6 em: whole pixels at 20, 25, 30, 35, 45
-and 60 px and at their doubles), so columns of text need no measuring;
-JetBrains Mono's line box is taller (ascent 1.02 em, where Go's is 0.945).
-The web host draws every face as its one.
+not copied and must outlive the frame: scratch or session memory.
-Text is shaped for the size it is drawn at, so under a camera that zooms
-its letters would shift against each other from frame to frame.
-`f.textScaled(face, x, y, scale, raster, bytes, color)` lays the line out
-and rasterizes it at `raster` and draws that at `scale`, unsnapped: give it
-the scale the move ends on (the larger of its ends) while the camera
-moves, and `textIn` again once it rests. One texture serves the whole
-move. The web host ignores `raster`.
+`f.text(x, y, scale, bytes, color)` draws text from its top left corner,
+scale 1 a 13 px face; measuring, paragraphs and faces are in Text, below.
`f.openFile("open", .{ .pattern = "wav;flac" })` shows the system's file
dialog; the answer comes back as the console line `open <path>`, so it
reaches the sketch's `command` like anything typed there. `f.run(line)`
does the same with any line, after the frame: `draw` cannot write State,
-so this is how it tells State something only it learns (how many takes a
-Store holds, say).
+so this is how it tells State something only it learns (which of its
+files are already written, say).
+
+`f.host.appendFile(name, bytes)` appends to a file of the sketch's own,
+`<stem>.<name>` beside its save `<stem>.xitdb` (in `.sketchbook/` under
+`zig build run`), creating it, and returns its path for `readFile` ("" when nothing
+was written, and always on the web). Only `draw` and `command` can call it,
+and a write is not replayed, like sound. `readFile` maps a file once, so
+what is appended afterwards is not in what it returned.
+`f.host.writeFile(name, bytes)` does the same to a new, empty file of that
+name. micscope starts each take's `take-<id>.f32` so, and appends to it as
+it records.
`f.download(buffer, .{ .size = n, .key = k })` reads a GPU buffer back
without stalling: the bytes arrive in a later frame's `in.downloads`, a
frame or two behind. For measurements a shader made (a pitch, a level),
-not for pixels.
+not for pixels; sound a shader made goes to the speakers with
+`f.audioBuffer` (see sound, below), which does not wait a frame.
Geometry and colors are duck-typed. Anything with `x`/`y` is a point, anything
that also has `w`/`h` (or `width`/`height`) is a rect, in any number type, and
@@ -156,6 +173,111 @@ own type:
The drawing layer below is the exception: new, and typed (`sk.math.Vec`,
`sk.Color`), so decl literals and completion work.
+## Text
+
+`f.text(x, y, scale, bytes, color)` draws text from its top left corner;
+scale 1 is a 13 px face (Go Mono: 8 px a character, a 16 px line), any
+scale works, 1.5 or 7.25, and a `\n` starts a line. `f.textIn(face, ...)`
+is the same in another face (`sk.Face`): `.mono`, `.mono_bold`,
+`.mono_italic` for data and code, `.sans`, `.sans_medium`, `.sans_bold`
+for what is said about it (the Go family), and `.code`, `.code_bold`,
+`.code_italic`, `.code_medium`, JetBrains Mono NL (no ligatures: `->` stays
+two characters), for programs. All ten are built into the host. The
+monospaced faces advance alike (0.6 em: whole pixels at 20, 25, 30, 35, 45
+and 60 px and their doubles), so columns need no measuring; JetBrains
+Mono's line box is taller (ascent 1.02 em, where Go's is 0.945). `f.print`
+formats into `f.text`.
+
+Measuring is a pure function of the font, the size and the bytes, so it
+works anywhere, `update` and tests included, and gives the same numbers on
+every native platform:
+
+```zig
+const size = sk.text.size(.mono, 1, "0123456789"); // .{ 80, 16 }: width, height
+const l = sk.text.layout(s.line, .{ .width = 300, .@"align" = .center }); // l.w, l.h, l.lines
+```
+
+`sk.text.layout(bytes, paragraph)` lays a paragraph out without drawing
+it; `f.paragraph(x, y, bytes, paragraph)` draws it and returns the same
+`Layout`, its positions from `x`, `y`. A `sk.text.Paragraph` has `face`,
+`scale`, `color`; `width` (wrap at spaces to it; 0: lines end only at
+`\n`; a word wider than it stays whole); `align` (`.left`, `.center`,
+`.right`, within `width`, or the widest line when it is 0); `spans` (each
+from its `start` byte to the next: a `color`, a `face`, a `scale`, null for
+the paragraph's own); `reveal` (only the first N glyphs drawn, the layout
+still the whole text's: typewriter text costs nothing extra); and `caret`
+(a byte index). The `Layout` is `w`, `h`, `lines`, `glyphs` (a glyph is a
+codepoint) and `caret`: the left of the caret's glyph, the top of its line
+and the line's height. `sk.text.places(bytes, paragraph, out)` is the
+same layout with every byte's place in `out` (a `Caret` a byte and one for
+the end, each where a caret before that byte sits): what an editor draws
+ranges with and finds the byte under the pointer by, in one layout.
+`f.host.textSize(scale, bytes)` and `textSizeIn(face, scale, bytes)` still
+measure one line.
+
+Advances are whole pixels at the size drawn (HarfBuzz's, each rounded), so
+a width is not a multiple of the scale (ten digits are 80 px at scale 1,
+230 at scale 3): measure at the scale drawn. The line box is FreeType's at
+that size. Measuring never depends on the display: a paragraph wraps the
+same at any window size or density.
+
+`sk.text.font(bytes)` is a face for a sketch's own TTF or OTF bytes
+(copied; the same bytes give the same face), null if they are not a font;
+call it where the bytes are, `setup` say, and keep the face. A glyph a face
+lacks comes from one fallback, JetBrains Mono NL (Go Mono for JetBrains
+Mono's faces); else it is the face's missing-glyph box. There is no bidi
+(text runs left to right), no colour emoji, and no system font: neither
+family has CJK, Arabic or Hebrew.
+
+Natively the text is shaped by HarfBuzz and rasterized by pardes's
+`vendor/font.c` (FreeType, light hinting, 8-bit coverage, no gamma) at the
+device size it is drawn, each glyph on a whole device pixel, sampled
+nearest, from one glyph atlas: changing text rasterizes only glyphs not
+seen before, and a frame's text is one draw. `docs/text.md` is the design.
+
+Text is shaped for the size it is drawn at, so under a camera that zooms
+its letters would shift against each other from frame to frame.
+`f.textScaled(face, x, y, scale, raster, bytes, color)` lays the line out
+at `raster` and draws it at `scale`: each glyph rastered at the size drawn,
+at the `raster` layout's place scaled, not snapped to a pixel and sampled
+smoothly, so the letters glide and keep their places. Give it the scale
+the move ends on while the camera moves, and `textIn` again once it rests.
+The web host ignores `raster`.
+
+On the web, text is the canvas's, in the page's `monospace` and
+`sans-serif` in each face's weight and style (a sketch's font a
+`FontFace` from its bytes, drawn in a fallback until the browser has
+loaded it), measured with `measureText`, so what is drawn is what is
+measured there too; but the page's fonts are not the bundled ones, so web
+widths and line heights differ from native ones and are fractional.
+
+Recipes, for a game and an editor:
+
+```zig
+// A centred label in a rect: measure, then centre the block vertically.
+const p: sk.text.Paragraph = .{ .width = r.w, .@"align" = .center, .scale = 2 };
+const l = sk.text.layout("Unlock", p);
+_ = f.paragraph(r.x, r.y + @round((r.h - l.h) / 2), "Unlock", p);
+
+// Dialogue wrapped in a box and typed out: State counts glyphs in update
+// (`s.shown += 1` a tick), draw reveals them; one layout, no new rasters.
+_ = f.paragraph(box.x, box.y, line, .{ .width = box.w, .face = .sans, .reveal = s.shown });
+const done = s.shown >= sk.text.layout(line, .{ .width = box.w, .face = .sans }).glyphs; // in update too
+
+// A caret and per-token colours and sizes in source text.
+const src: sk.text.Paragraph = .{ .face = .code, .spans = tokens, .caret = cursor };
+const drawn = f.paragraph(x, y, source, src);
+f.fill(sk.Rect{ .x = drawn.caret.x, .y = drawn.caret.y, .w = 1, .h = drawn.caret.h }, 0xffcc00);
+
+// The byte under the pointer (in update too; px, py from the paragraph's
+// x, y): the last whose line holds py and whose x is at or left of px.
+_ = sk.text.places(source, src, places); // a Caret a byte and one more
+var hit: ?usize = null;
+for (places[0..source.len], 0..) |c, i| {
+ if (py >= c.y and py < c.y + c.h and px >= c.x) hit = i;
+}
+```
+
## Drawing shapes
Circles, lines and polygons are one host command, `Command.shape`: a
@@ -331,10 +453,9 @@ display's rate it steps once a frame, jitter and all: a 60 Hz frame is
after a reload that shrinks it. The default buffer is the element's own
defaults, never `std.mem.zeroes` (an enum may have no 0).
-**Data that grows.** State is snapshotted, replayed and migrated, so it
-holds what `update` changes, at a size fixed in its type. Store is not
-snapshotted or replayed, so what is in it does not follow a seek. Three
-cases, by who needs the data:
+**Data that grows.** State is kept in keyframes, replayed and migrated, so
+it holds what `update` changes, at a size fixed in its type, 32 MiB at most.
+Three cases, by who needs the data:
- `update` needs it: a `List` in State, sized for the worst case (the
quadtree's 4096 points, 32 KiB; flocking's 2048 boids).
@@ -348,18 +469,28 @@ cases, by who needs the data:
may derive it differently. A cheap derivation needs no cache at all:
the quadtree builds its tree in `f.scratch` every frame.
- It is the user's work, not a function of State (a recording, a
- document): Store.
+ document): a `List` in State, or, bigger than a save, files of the
+ sketch's own (`appendFile`), named from State, as micscope's takes are.
The timeline then needs nothing more: a seek changes the key like an
-update does (`sketches/noc`: `koch`, `lsystem`, `quadtree`).
+update does (`examples/noc`: `koch`, `lsystem`, `quadtree`).
**Sound scopes**, in the `scope` module (import `sb.modules.scope`): a
`scope.Scope` kept in Session takes samples with `push` and, once a frame,
`draw`s the views given rects for: the last seconds as a scrolling waveform
and spectrogram, the smoothed spectrum of the newest samples, and an
oscilloscope. All analysed and drawn on the GPU, new columns only; its
-shaders swap to WGSL for the web like any others. Lifted from micscope's
-live view; spheres uses it.
+shaders swap to WGSL for the web like any others. Given `.camera`, the
+rects are world rects: the views are made at their size there and drawn
+through the camera, so panning or zooming recomputes nothing. A sketch
+that analyses buffers of its own runs the same shaders:
+`scope.kernels.{waveform, spectrogram, spectrum}` over any read-only
+buffer of samples, `scope.pipelines.{wave, spectrogram, spectrum}` to
+draw them, with the parameter and view blocks in `scope.layouts`
+(`Scope.gpu.tape` is a Scope's own history on the GPU, for a kernel of
+the sketch's). `scope.midi(hz, a4)`, `scope.hz(note, a4)` and
+`scope.note_names` name pitches. Lifted from micscope's live view;
+spheres uses it.
**Vector graphics**, in the `vector` module (import `sb.modules.vector`):
SVG parsing (the static subset Typst emits, and more) into cubic Bézier
@@ -379,7 +510,9 @@ just a new pipeline after a reload. No sketch touches a graphics API. The
shaders are GLSL; the build turns them into SPIR-V for native and WGSL for
the web, and each build imports the form its host reads (see Build API). `abi.gpu.pipeline(Vertex, ...)` derives the
vertex layout from a struct, and `abi.gpu.uniform` checks std140 at
-compile time. A pipeline without attributes makes its own vertices from
+compile time, and the size: a uniform block is 4096 bytes at most, all
+SDL_GPU's Vulkan backend binds of one (a larger one was cut off without a
+word), so more goes in a storage buffer. A pipeline without attributes makes its own vertices from
`gl_VertexIndex` (a full-screen triangle, for shader-toy style views).
Compute is data too. `host.newBuffer(size)` makes a GPU storage buffer,
@@ -390,16 +523,87 @@ stay on the GPU: a compute shader's output is a later draw's input, with no
readback. Each dispatch is its own compute pass, so it sees everything the
commands before it wrote.
-Sound is declarative. `f.voice(.{ .key, .audio, .serial, .loop, .volume })`
-declares a voice that should be sounding. A new key or serial starts it, and
-an undeclared key stops it. A finished one-shot stays finished while it is
-still declared, so replays and seeks never re-fire sounds. `f.audio(key,
-samples, .{})` streams PCM, and `input.stream(key)` reports what the host has
-queued and played. `f.microphone()` keeps the default recording device open
+Sound is declarative. `f.voice(.{ .key, .audio, .serial, .loop, .volume,
+.fade, .rate, .group })` declares a voice that should be sounding. A new
+key or serial starts it, and an undeclared key stops it. A finished
+one-shot stays finished while it is still declared, so replays and seeks
+never re-fire sounds. `.rate` is its speed and so its pitch (2 is an
+octave up and half as long; resampled by linear interpolation, cheap and
+a little dull far from 1); changing it does not restart the voice.
+`.group` (0-7) puts it under a gain the sketch declares each frame,
+`f.gain(group, value)`, 1 when not declared: music ducks under speech by
+the sketch lowering one number, and the host glides to a new gain over
+10 ms so a step does not click. The host mixes the voices once a frame,
+topping its queue up to 2048 samples (about 43 ms) ahead of the device,
+so what `draw` declares is heard up to that much later.
+
+`f.audio(key, samples, .{})` streams PCM, and `input.stream(key)` reports
+what the host has queued and played, and its `underruns` (pushes that found
+it empty though the frame before had pushed to it: each a gap). The sketch
+chooses how far ahead it keeps a stream; `input.lead` is how far the host
+would: the slowest of the last 64 frames' worth of samples (a stream is fed
+once a frame), plus the device's pull (what it takes from a stream at once,
+1024 samples by SDL's default), plus half a pull for each recent underrun.
+A sketch that makes its sound as it goes pushes `in.lead -|
+in.stream(key).queued` a frame, and a change it makes is heard after what
+is queued ahead of it, about a pull: 19 to 27 ms after `draw` on this
+machine at 60 Hz.
+
+A sketch that must answer faster asks for a smaller pull:
+`pub const audio_pull = 256;` beside its `name` has the host ask SDL for
+256-sample pulls (5.3 ms) when it opens the device, and a change then
+leaves in about 6.5 ms. The price is paid by the whole machine: the audio
+server then runs every program's sound at that size, four times as many
+wake-ups, and under load it misses one now and then, a dropout (a click)
+in everything playing, not only the sketch. Without it SDL picks (1024 at
+48 kHz). `SDL_AUDIO_DEVICE_SAMPLE_FRAMES` in the environment wins over
+both, the web ignores it, it is read once, when the host starts, and the
+sound overlay (`overlay sound`) shows what the device took (`pull 256`).
+
+`f.audioBuffer(key, buffer, .{ .count
+= n })` streams `n` samples a compute shader wrote (f32 from `.offset`
+bytes): the host reads them back within the frame, waiting for the GPU's
+work so far (about 0.2 ms), and queues them. A GPU synth is then:
+
+```zig
+const n: u32 = @min(f.in.lead -| f.in.stream(1).queued, max_block);
+if (n > 0) {
+ f.compute(.{ .kernel = synth, .readwrite = &.{ss.block}, .uniforms = ..., .groups = .{ (n + 63) / 64, 1, 1 } });
+ f.audioBuffer(1, ss.block, .{ .count = n });
+}
+```
+
+(`examples/spheres` is one.) `f.microphone()` keeps the default recording device open
while declared, and the next frame's `input.microphone` holds what it heard
(to `draw` only: it is a device, not an event, so it does not replay).
`host.samples(audio)` gives a loaded sound's samples, mono at
-`input.sample_rate`.
+`input.sample_rate`. `--export` writes frames only, no sound.
+
+The host sums the voices and limits the sum, sample by sample: below
+0.75 (-2.5 dBFS) it plays at true volume, to the bit; above, it bends
+smoothly (same value and slope at 0.75) toward 1 and never past it, so a
+full-scale peak plays at 0.875 and any number of loud voices stays
+bounded. Streams are not limited: SDL adds each, as pushed, to the voice
+mix and clips the total at ±1.
+
+A sketch can make its own sounds: `host.newSound(samples)` copies mono
+samples at `input.sample_rate` into the host and returns an `Audio` that
+voices play like a loaded one, so a synthesised one-shot is replay-safe
+too. Like every sound it lives as long as the host: make each once and
+keep the handle in Session. `sk.sfxr` is sfxr, the classic generator of
+game blips, coins, lasers and explosions (`sfxr.Params`, its usual knobs,
+rendered at any rate; at 44.1 kHz to the bit as the original):
+
+```zig
+if (ss.blip == .none) {
+ var buf: [4096]f32 = undefined;
+ const n = sk.sfxr.render(.{ .freq = 0.5, .sustain = 0.05, .decay = 0.1 }, f.in.sample_rate, &buf);
+ ss.blip = f.host.newSound(buf[0..n]);
+}
+if (s.coins != 0) f.voice(.{ .key = 1, .audio = ss.blip, .serial = s.coins });
+```
+
+(`test/voices.zig` is this sketch.)
Sounds decode with single-file C libraries in `vendor/` (dr_wav, dr_flac,
stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
@@ -407,8 +611,8 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
## Animation
The `anim` module (`sb.modules.anim`) is manim-style animation written as
-code: Typst for text and math, shapes, cameras, morphs, slide-style
-pauses, and objects the scene draws itself. A scene is one file, and
+code: Typst for text and math, shapes, cameras, morphs, talks that wait
+for clicks, and objects the scene draws itself. A scene is one file, and
`sb.addScene` builds the player around it:
```zig
@@ -442,14 +646,19 @@ fn wobble(now: anim.Now, swing: anim.Value) anim.Pose {
```
Objects are added (`typst`, `svg`, `rect`, `circle`, `line`, `arrow`,
-`polygon`, `custom`) and show in the order they were added; each call
-returns a handle. Animations are methods of the handle: `write`, `create`,
+`polygon`, `custom`, and `part` of another) and show in the order they
+were added; each call returns a handle. Animations are methods of the handle: `write`, `create`,
`fadeIn`, `fadeOut`, `transformInto`, `move(.{ .x, .y, .scale, .rotation,
.opacity })`, `scaleTo`, `rotate`, `indicate`; plus `anim.camera(...)` and
`value.to(x)`. `play` runs a tuple (or array) of them together; its
-options are `.seconds`, `.ease` (any `fn (f32) f32`) and `.lag` (manim's
-lag ratio). `wait` moves time on, `pause()` holds the player there until a
-click, like a slide. Positions are scene units: 1280x720 of them show at
+options are `.seconds`, `.ease` (any `fn (f32) f32`) and `.lag`, manim's
+lag ratio (0 by default, all at once): each animation starts `lag` of its
+own length after the one before, in the order given, and the play still
+lasts `.seconds`, the last ending with it, so each of n lasts
+`seconds / (1 + lag * (n - 1))`; a lag of 1 plays them one after
+another. An object two animations of one play change is timed by the
+first. `wait` moves time on; in a live scene, `pause()` makes what
+follows wait for a click (see Talks). Positions are scene units: 1280x720 of them show at
camera zoom 1, the origin in the middle, y down. The page behind them is
the scene file's `pub const background = 0xRRGGBB` (manim's grey without
one).
@@ -467,13 +676,15 @@ A scene is one of two kinds, which share every call:
frame, at runtime. Each `play` takes effect at once against `s.t`, so the
code after it reads and changes what shows, with no callbacks:
`s.pose(obj).y = ...`, `s.get(value)`, `s.camera()`, the mouse
- (`s.pointer`), the wall clock (`s.clock`, which runs on through pauses)
- or any runtime data. Its Typst sources are the declarations of the
- namespace it is given, since the build cannot run it to find them.
+ (`s.pointer`), the time (`s.t`, which runs on while a pause waits) or
+ any runtime data. Its Typst sources are the declarations of the
+ namespace it is given (or a tuple of namespaces), since the build cannot
+ run it to find them.
Both answer the player the same way (`shot`: objects, poses, values,
-camera, plays and pauses at an instant), so the only state is `t`, and
-scrubbing, seeking and hot reload are free. A test checks that a live
+camera, plays and gates at an instant), so the only state is the time and
+the pauses clicked through, and scrubbing, seeking and hot reload are
+free. A test checks that a live
scene and a compiled one with the same timeline show the same poses at
every instant.
@@ -484,6 +695,63 @@ file, reads `scene.typst_sources`, compiles each with `typst compile`
(cached by content in `.zig-cache/typst`) and embeds the SVGs. Nothing
scans files, and a scene without Typst needs no `typst`.
+**PDF pages and parts.** Typst imports a page of a PDF as vector paths,
+so a page is a Typst object like any other:
+`s.typst("#image(\"/home/me/sdm.pdf\", page: 31)", .{})`. Typst runs with
+`/` as its root, so an absolute path names the file where it lies; the
+file is not part of the cache key, so one changed in place needs its entry
+in `.zig-cache/typst` gone. Text is outlines: every glyph is a filled
+shape (nothing to search or select), drawn crisp at any camera zoom, and
+`write` reveals the shapes in the order the PDF draws them (in the Intel
+SDM: header and footer, the text from the top, then the figures; a
+table's text row by row, left to right, and its rules after all of it). A page
+costs what its shapes do: Figure 2-1's page of the SDM is 2.1 MB of SVG
+and 1954 shapes, parsed once, 6-12 ms, the first frame it shows; then, at
+1280x720 in a release build, 0.9-1.7 ms a frame to record for the GPU
+(0.4 ms on the GPU itself) or 2-5 ms on the CPU renderer. A table of
+contents, dot leaders and all, is five times that: show a part of it.
+`zig build bench` times the page beside the simple objects, with a budget
+of its own. An SVG a Typst object includes (`image("x.svg")`) is kept the
+same way.
+
+`s.part(page, .{ .x, .y, .w, .h })` takes the shapes whose bounds' centre
+lies in a rectangle out of an object, as an object of its own, so a field
+of a figure or a row of a table can glow, be written, fly off or morph
+while the page around it stays. The rectangle is in the object's units,
+its centre and size: the literal `s.rect` takes to cover the same place
+when the object stands at the origin at scale 1. Pick it with the guides
+(G: lay the page at the origin, at scale 1, and read the pointer), or
+from `pdftotext -bbox -f N -l N file.pdf -`, whose points from the
+top-left of a W x H pt page are `(x - W/2) * 4/3` across and
+`(y - H/2) * 4/3` down. The part stands where its shapes stood, around
+the rectangle's centre (so `indicate`, `scaleTo` and `rotate` turn it in
+place), and shows as the object does after the plays laid so far: taken
+from a page that has faded in, it is there. The object draws the rest
+from then on, at every instant. A shape goes to the first part that
+takes it, so a rule that crosses several fields (a box's outline) stays
+with whichever holds its centre: keep areas inside the rules. A table's
+column rules run its whole height, so their centres all lie in one row:
+take them first, with a band a point high through that centre. Parts of
+parts, and of any vector object, work the same way, and share the
+object's geometry (a page is parsed once however many parts it gives).
+`transformInto` morphs into the whole of its target, so a morph's result
+can be split by parts taken after it: `c0.transformInto(bits)`, then
+`s.part(bits, ...)` for each run of bits.
+
+`examples/manual.zig` is a talk in two slides on the SDM (Vol. 2). On
+Figure 2-1 (page 31), the fields of the instruction format glow in turn,
+`83 C0 01` is written below, each byte flies into its field and `C0`
+splits into `11 000 000` over Mod, Reg and R/M. Then ADD's opcode table
+(page 132) is written row by row; its row `80 /0 ib ADD r/m8, imm8`,
+cut in pieces, becomes SUB's from page 1400, laid so that the rows
+coincide: first the digit after the slash alone, then the rest, a morph
+per piece, so the glyphs that stay hold still; the two rows end one over
+the other. `zig build manual` plays it in a
+window; the PDF is `-Dmanual=PATH` (`~/01-resources/intel-devref-ii.pdf`
+by default), never part of the repository: without it the example builds
+a scene that says so, and its script (`test/manual.script`, in `zig build
+test` when the file is there) is skipped.
+
**Custom objects** are drawn by the scene's own code with 2D commands
(`sk.draw`, `f.fill`, `f.text`): what is runtime data, a register table, a
memory grid, a code panel. `s.custom(&data, pose)` adds one, where `data`
@@ -534,11 +802,16 @@ a custom object's commands keep their own order.
**The player** (`src/anim/player.zig`) fits the scene's frame into the
canvas, and its canvas is the room it has: the window, or an export's
-`--size`. Keys: space pause, click to continue after a `pause`, left/right
-previous/next play, `,`/`.` step a frame, home/end, up/down speed, B GPU or
-CPU renderer, L loop, G guides (boxes, origins and the scene's axes, in
-scene units); drag and wheel to look around, R to reset the view. Exported,
-it plays through once, without pauses or controls, and quits at the end:
+`--size`. Its State is an `anim.Deck` (`deck.t`, `deck.playing`, ...)
+and the viewer's settings. Keys: click, space or page down for the next
+step of a talk (space plays and pauses a scene with no pause), page up or
+backspace back a step, `]`/`[` the next/previous slide, P play/pause,
+left/right previous/next play, `,`/`.` step a frame, home/end, up/down
+speed, B GPU or CPU renderer, L loop (a talk holds its end instead), G
+guides (boxes, origins and the scene's axes, in scene units); drag and
+wheel to look around, R to reset the view. Exported, it plays through once without controls, each pause
+held for the scene file's `pub const hold` seconds (1 without one), and
+quits at the end:
```sh
zig build export -- frames --size 3840x2160
@@ -561,41 +834,251 @@ the scene file besides `anim` and `sketch`. `test/scene_live.zig` and
`test/scene_compiled.zig` are small scenes of each kind, with a custom
object.
+### Talks
+
+A talk is a live scene that waits: run from the top every frame, it is a
+function of its time and of the gates opened so far. Time never stops at
+a gate. What was laid before it (plays still running, a `loop`, code
+reading `s.t`) carries on, and what comes after waits in the future until
+the gate opens. So a talk seeks, steps back and hot-reloads like any live
+scene.
+
+- `s.pause()` waits for the presenter's next step (a click, space, page
+ down). A click while a step plays finishes it, like Keynote: the
+ picture jumps to where the next pause is laid; the next click opens it.
+ Back cuts to the picture held before the last click.
+- `s.gate(open)` waits for anything: it opens on the first frame at or
+ after it is reached on which `open` is not null, and returns that value
+ from then on (null before), a choice to branch on:
+ `const pick = s.gate(app.answer) orelse return;`. Code after a closed
+ gate would show nothing, so `orelse return` is the usual end. A gate
+ opens only in `update`, from what `update` sees (events and State), so
+ a recording replays to the same talk. One click opens one gate.
+- `s.beside(f, args)` runs `f(s, args...)`, plays and all, from the
+ cursor, and leaves the cursor where it was: what follows runs alongside
+ (`s.beside(anim.Frame.clear, .{.{}})` fades a slide out while the next
+ one writes). `s.loop(f, args)` plays `f` again and again from the
+ cursor until the gate laid right after it opens; the cycle running then
+ completes. `f` only plays, and ends where it began. `s.clear(options)`
+ fades out everything that shows.
+- `s.slide()` begins a slide. Next/previous slide goes to a slide's
+ resting picture: held at its first gate (the end of the slide if it has
+ none), every gate before it opened at once (a choice with 0) or undone.
+
+The playhead is `anim.Deck`, plain data (`t`, `playing`, `speed`, `hold`,
+and `log`, each gate opened: how long after it was reached, and its
+value), so hot reload, snapshots, replay, scripts and the console see it
+like any field; `deck.waiting`, `deck.slide`, `deck.gates` and
+`deck.duration` say where the talk stands. The stock player keeps one, and
+any sketch can keep its own beside its data: its `update` decides which
+events ask for what (`anim.Ask`: `next`, `back`, `next_slide`,
+`back_slide`, `to`, `end`), so the deck never owns the keyboard. The talk
+takes the sketch's data after the frame: in `update` as `*App`, so the
+talk may change it, and when drawn as `*const App`, so drawing cannot.
+`anim.mutable(app)` is the app to write to, null when drawn; `s.events`
+are this update's events in scene units (none when drawn); a widget laid
+out before the pause it waits at takes a click by setting `s.next =
+false`. `anim.Painter` draws a shot as the player does:
+
+```zig
+pub const typst = struct { pub const law = "$ x'' + 2 zeta x' + x = 0 $"; };
+pub const scene = struct { pub const typst_sources = anim.sources(.{typst}); }; // for sb.addTypst
+pub const State = struct { deck: anim.Deck = .{}, app: App = .{} };
+pub const Session = struct { painter: anim.Painter = .{} };
+const App = struct { presses: u32 = 0 };
+const button: sk.Rect = .{ .x = -30, .y = 150, .w = 60, .h = 60 }; // scene units
+
+pub fn update(s: *State, in: *const sk.Input) void {
+ s.deck.update(in, .{ .next = in.mouseReleased(.left) != null, .back = in.pressed(sk.Key.left) }, talk, .{&s.app});
+}
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ const shot = s.deck.shot(f.scratch, f.in, .{ 0, 0 }, talk, .{&s.app}) catch return;
+ ss.painter.paint(f, shot, @import("typst"), .{}) catch {};
+}
+
+fn talk(s: *anim.Frame, app: anytype) void {
+ const law = s.typst(typst.law, .{});
+ s.play(.{law.write()}, .{});
+ s.loop(pulse, .{law}); // runs on while the deck waits
+ s.pause();
+ const knob = s.circle(.{ .r = 30, .y = 180, .fill = anim.blue });
+ s.play(.{knob.fadeIn()}, .{});
+ if (anim.mutable(app)) |a| for (s.events) |e| if (e.kind == .mouse_up and button.contains(e.x, e.y)) {
+ a.presses += 1; // the knob's click, not the presenter's next
+ s.next = false;
+ };
+ const many = s.gate(if (s.next) @intFromBool(app.presses > 2) else null) orelse return; // a choice
+ s.play(.{if (many == 1) knob.scaleTo(2) else knob.fadeOut()}, .{});
+}
+
+fn pulse(s: *anim.Frame, o: anim.Obj) void {
+ s.play(.{o.indicate()}, .{ .seconds = 1.5 });
+}
+```
+
+`sb.addTypst(module)` compiles the Typst of a module that declares
+`scene.typst_sources` (a module of the sketch's file without the `typst`
+import, see `build.zig`'s talk). Gates are known by the order they are
+reached: insert a pause above where a talk stands and it lands a step
+earlier. An edit that moves the last opened gate (a step above retimed)
+moves `t` with it on reload, so the presenter stays on the same step, as
+far into it. Exported (`in.exporting`), every gate opens `deck.hold`
+seconds after it is reached, in the first frame's run, so the video shows
+each wait for that long, loops running, and the frames are the same every
+run; a sketch quits at `deck.t >= shot.duration`. `examples/talk.zig` is
+a talk with a slider, a loop, a choice, two slides and `beside`.
+
## The host
- **Hot reload.** It watches the library file and loads each new build through
- a private copy.
-- **State file.** `<name>.state` holds the live state plus 7 snapshot slots,
- shared via `MAP_SHARED`. Its header carries the reflected layout, so a
- layout change migrates every slot field by field, with enums matched by tag
- name, and `sketchbook-probe` can print any sketch's state. Arrays and
+ a symlink with a fresh name (a build must replace the file, as `zig build`
+ does, not rewrite it in place). `zig build lib --watch -fincremental
+ --debounce 0` makes a reload take tens of milliseconds instead of a second:
+ Zig recompiles only what the edit changed, and starts as soon as a file is
+ saved instead of 50 ms later. Its limits, with Zig 0.17.1: the incremental
+ linker is new, and a library of it that does not link libc loads only
+ through a host workaround that Zig 0.18 makes unnecessary; if a reload ever runs code other than what you
+ wrote, stop the watch and rebuild without `-fincremental`. The library is
+ larger (27 MB instead of 10 for a small sketch), the watching compilers
+ stay in memory (about 300 MB for a small sketch, 1.3 GB for a game with C
+ and shaders), and a save that touches several files may build more than
+ once. The cache grows with each start of the watch (65 MB for a game),
+ not with edits.
+- **The save.** A sketch keeps one thing, State, in one file, its save:
+ `<name>.xitdb`, an xitdb database. Live State is process memory; the save
+ holds the present, its newest keyframe and the frames logged after it,
+ which a run restores and replays through `update` (played by another
+ build, the keyframe alone, and the run says how many frames it left),
+ so a run starts where the last stopped; and the history before it
+ (Sessions, below). `--fresh` starts from defaults and leaves the save as
+ it is. A keyframe is State in 4 KiB pages and writes only the pages that
+ changed since the keyframe before it, an all-zero page nothing: about 5
+ KB a keyframe for drat-meout's 20 KiB State, 10 KB for a 4 MiB State
+ edited once a minute. Each stretch carries the reflected layout, so a
+ keyframe from an older layout migrates field by field, with enums
+ matched by tag name, and so does live State at a reload. Arrays and
vectors migrate element by element: the elements both layouts have, each
field by field, so an element type can gain a field and a capacity can
grow (new elements take their defaults) or shrink (the rest is dropped; a
count field such as `sk.List`'s `len` is kept, and `List` clamps it where
- it is read). An array whose type is unchanged is copied whole. Files from
- before element leaves (`SKETCH01`) are read and rewritten; a file that
- is not a state file is refused, never truncated.
-- **Store file.** `<name>.state.store` is a heap mapped at a fixed address
- (`0x2000_0000_0000`, 64 GiB reserved), grown in place, locked to one
- process. Power-of-two size classes with free lists in the file. Snapshots
- and replays do not cover it (only `draw` and `command` change it).
-- **Time travel.** Recordings, replay, seek and step work on any sketch,
- because they only need state bytes and events. A recording is whole
- frames; playback, `seek` and `step N` (frames) stop only between them.
- Restoring a snapshot (play, seek, step, `load`) clears the pointer,
- button and key state, and a recording begins with events that bring back
- what was held when it started (a pointer move, a button or key down), so
- a replay starts from the same input whatever the live pointer did since.
- A recording carries a hash of the build that made it; `play` warns when
- the running build differs (edited `update`, a new compiler), since the
- replay may then diverge.
-- **Console and overlays.** `get`/`set <field path>` (`get` of a vector,
- array or struct shows its values, in memory order), snapshots, recordings and
- the memory and scope overlays come from the host; unknown lines go to the
- sketch. Paths index arrays and vector lanes: `get pos[0]`,
- `set boids.buffer[3].pos[1] 20`. `diff N` compares live state with
- snapshot N leaf by leaf, so padding (a Debug `@Vector`'s spare lane)
+ it is read). An array whose type is unchanged is copied whole. A state
+ file from before (`<name>.state` beside the save, any of its formats) is
+ imported into a new save once: its State the present, its snapshot slots
+ marks `1` to `7`; the file is left as it was and not read again, and one
+ that is not a state file is said and left.
+- **Where files go.** `zig build run` and `export` keep a sketch's files in
+ `.sketchbook/`: `<name>.xitdb` and the `<name>.<file>` it appends to. The
+ host makes the directory with a `.gitignore` of `*`, so neither git nor
+ jj takes in a save that grows (the jj snapshot a build makes would commit
+ one while it is under a megabyte), and moves in, once, the `<name>.state`
+ an older build kept in the project's root; when both exist, nothing moves
+ and the host says which is used. Without `--state`, a run keeps them in
+ `$XDG_DATA_HOME/<name>/` (`~/.local/share/<name>/` without it), which is
+ where a shipped game's go; a script or an export uses `sketch.xitdb` in
+ the working directory. `--state x.xitdb` and `--state x.state` both name
+ the save `x.xitdb`.
+- **Sessions.** Every run is a session in the save: an append-only log of the events live `update` was fed, in whole frames, and
+ keyframes, the State at the start, every minute while it changes, at
+ every jump (`load`, `set`, `reset`, a seek, a sketch command), before and
+ after a reload, at every mark and at exit. Each stretch of a session
+ between reloads keeps its build's identity, its layout and the source it
+ was built from: the repository's revision (`jj:<commit> <change>`, else
+ `git:<sha>`, `+dirty` with uncommitted changes, read once per `zig
+ build`), Zig's version, the backend and the mode. Nothing in it is ever
+ overwritten, only dropped, oldest first, at the cap (below); marks and
+ clips are names pointing into it.
+
+ `App.Options.record` decides how much of it the save keeps, at build
+ time: null, the default, means Debug builds keep all of it, up to the
+ cap below. A build that does not record keeps the present and the marks
+ (and clips) only: at every keyframe it drops the frames and keyframes
+ before it, and at exit it compacts the file, so while it runs the disk
+ holds at most the last minute of input, and after, none. A playtest
+ build of a release opts in with one line, `.record = b.option(bool,
+ "record", "collect sessions in a release build")`. A script from
+ `--fresh` state records in memory (time travel works, nothing touches
+ the disk; it stops at 256 MiB, ten hours or more of play, keeping what
+ it has), a script without `--fresh` to the file, an export nothing, and
+ an export has no marks or clips, as the console says. The console's
+ status line ends with `rec file`, `rec memory` or `rec off`, and
+ `sessions` says where.
+
+ A commit is a second of play (of event time, so a script commits on the
+ same frames every run), and is made at once for a reload, a mark, a
+ clip's start or end, an export and exit; only a mark and exit are synced
+ to disk. A crash (a panic, `kill -9`) loses the frames not yet committed,
+ under a second (15 of 255 in the kill test): the next run starts from the
+ last committed frame's State, the session lists as `(crashed)`, and a
+ clip it left open ends where the session does. A power loss loses what the kernel had
+ not written back (30 s past the last sync, by default); the torn end is
+ mended at the next start, the file opened at its last whole commit, and
+ a file still unreadable is renamed to `<path>.broken.<seconds>`, never
+ deleted, and a new one begun.
+
+ A minute of drat-meout's play was 268 KB with the pointer moving every
+ frame (16 MB an hour), 164 KB idle (86 KB of ticks, the rest keyframes,
+ then whole States; a keyframe is about 5 KB now).
+
+ **The cap.** A save is at most 64 MiB, and State half of that, so
+ history has room. A commit that leaves the file past it drops history
+ oldest first, keyframes' pages and the frames logged with them, and
+ compacts the file to three quarters of the cap: a hitch of about 170 ms
+ for a 48 MiB file in a Debug build, once every 16 MiB of history. The
+ present is never dropped, nor the keyframe of the newest mark of each
+ name, nor the newest clip of each name and its frames. What was dropped
+ says so when it is asked for (`load #K`, `play session N`). A mark of a
+ new name needs room for a whole State: when marks fill the save it is
+ refused, saying how to make room, by saving over a mark's name (the
+ older one then goes with history) or starting another save (`--state`).
+ Every commit leaves the nodes it copied behind, about a kilobyte, which
+ the compaction removes too.
+
+ Playtests: `export-session [S] FILE` writes session S (this run's when
+ none is given) with its marks and clips to a database of its own, for a
+ player to send; `import FILE` adds the sessions in such a file to this
+ sketch's (`sessions` lists them as `import <file>`), its marks and clips
+ named `NAME@<file>`; `play session N` replays one, and its stretch names
+ the commit to build to replay it without divergence. What such a file holds
+ of the player: every input event (pointer positions, keys, the text typed
+ into the sketch), the console lines that changed State (an `f.openFile`
+ answer is a local path), and the date the session started; nothing about
+ the machine or the user.
+- **Time travel.** Marks, clips, replay, seek and step work on any sketch,
+ because they only need state bytes and events. `save NAME` marks the
+ State now: a keyframe with a name, the newest of a name winning. `load
+ NAME` (or `load #K`, the K-th in `marks`) brings it back through the
+ layout it was taken in, migrated to today's, and `diff NAME` compares it
+ with live leaf by leaf over the fields both layouts have. `record NAME`
+ starts a clip from the mark `snapshot NAME` chose (saved first if it is
+ new, restored if it exists, so several clips branch from the same bytes)
+ and `stop` ends it; `play NAME` restores its keyframe and replays its
+ frames; `pause`, `seek start|end|MS` and `step N` (frames) move within
+ it, stopping only between frames. `play session S [at SECONDS]` replays a
+ past session from its start, or from the keyframe before that time,
+ paused there. At each later keyframe `update` produced, the replay is
+ compared with what was recorded: a difference is said once, `diverged
+ before frame F: N values, first <field>`, and the replay goes on from the
+ recorded State, which also carries it over the jumps the log does not
+ hold. A clip or session made by another build says so, since the replay
+ may then differ. Going back and playing on is `play` or `seek`, then
+ `stop`: live goes on from there in the same session, nothing
+ overwritten. Names are words of up to 32 bytes, and numbers are names, so
+ `save 3` and `play 0` work as they always have. Restoring State (play,
+ seek, step, `load`) clears the pointer, button and key state, and a clip
+ begins with events that bring back what was held when it started (a
+ pointer move, a button or key down), so a replay starts from the same
+ input whatever the live pointer did since. Event times are the session's:
+ `in.now` does not restart at 0 in a clip.
+- **Console and overlays.** `help` lists the console's verbs and `help
+ VERB` says what one does. `get`/`set <field path>` (`get` of a vector,
+ array or struct shows its values, in memory order; `set` of an array of
+ numbers takes all its values), marks, clips,
+ sessions (`marks`, `clips` and `sessions` list the last few) and the
+ memory, scope and frame timing overlays come from the host; unknown lines
+ go to the sketch. Paths index arrays and vector lanes: `get pos[0]`,
+ `set boids.buffer[3].pos[1] 20`. `diff NAME` compares live state with
+ mark NAME leaf by leaf, so padding (a Debug `@Vector`'s spare lane)
never counts.
- **Scripts** (`--headless --fresh --script file`) drive the same routing and
frames as a player: `click`, `key`, `hold`/`release` (a key down until
@@ -605,18 +1088,22 @@ object.
(`expect pos[0] 250 ~0.5` within a tolerance; a failure prints what it
found),
`await field value [~tol]` (frames until it holds, a minute at most),
- `expect-snapshot N` (live state equals snapshot N, leaf by leaf, printing
- the first differences), `expect-log`/`expect-no-log text` (the console's
+ `expect-snapshot NAME` (live state equals mark NAME, leaf by leaf,
+ printing the first differences), `expect-key WHY field value` (the
+ newest keyframe of this session taken for WHY, `before_reload`, `mark`,
+ `exit`..., holds the value, read in its own layout),
+ `expect-log`/`expect-no-log text` (the console's
recent lines), `expect-audio`, `screenshot`,
`expect-same-screenshot a b [max [x y w h]]`,
`expect-different-screenshot a b [x y w h]`, `expect-pixel file x y r g b
- a [tol]`, `load`, `reload`, `await-reload`. A failed
+ a [tol]`, `load`, `reload`, `await-reload`, `kill` (death by SIGKILL,
+ for tests of what a crash keeps). A failed
`expect`, or a console line that errors (a sketch command returning an
error included), fails the script. Headless always means offscreen, even
with `SDL_VIDEO_DRIVER` set, and GPU work still runs, into a texture. A
- scripted `--fresh` run works on files of its own (`<state>.<pid>`),
- renamed to the given `--state` at exit, so two builds running the same
- script at once do not share them.
+ scripted `--fresh` run saves nothing: its sessions are in memory, and the
+ files it appends to are `<stem>.<pid>.<name>`, removed at exit, so two
+ builds running the same script at once do not share them.
- **Export.** `--export DIR` plays the sketch headless, from fresh state,
and saves every frame as `DIR/000000.png`, `000001.png`, ...;
`--export -` writes them to stdout instead, as raw RGBA:
@@ -636,8 +1123,8 @@ object.
hides its controls, plays through and quits. `--size WxH` is the room
for the canvas (`in.window_width`/`height`, and the first canvas): a
sketch that sets its canvas to the room exports at any size. An export
- keeps state files of its own and removes them, so it can run beside a
- player. `--export` plays no script. In a release build on an RTX 3050,
+ saves nothing, and the files it appends to are its own, removed at exit,
+ so it can run beside a player. `--export` plays no script. In a release build on an RTX 3050,
an `anim` scene takes 6 ms a frame as raw RGBA and 21 as PNG at
1920x1080, 19 and 73 at 3840x2160; with ffmpeg encoding x264 from the
pipe, 11 and 41. The PNG encoder is the slow part: pipe, when the frames
@@ -700,7 +1187,7 @@ pub fn build(b: *std.Build) void {
}
```
-`addSteps` installs the executable and adds `run`, `lib`, `probe`,
+`addSteps` installs the executable and adds `run`, `lib`,
`export` (`zig build export -- frames --size 1920x1080`: what follows `--`
is `--export`'s directory, or `-`, then its options), `e2e` and
`test`, and with `.web = .{}` also `web` (the page into `zig-out/web`) and
@@ -716,11 +1203,10 @@ and returns plain `std.Build` objects:
| `app.addScriptExecutable()` | the same, built in `script_optimize` mode, as `e2e` plays scripts with |
| `app.addWeb(.{ .assets = ... })` | the wasm module and a ready-to-serve directory, built from the app's modules with every shader module swapped for its WGSL twin; tests can read its state by path (indices too: `list[2].x`) with `sk_field` (numbers) and `sk_tag` (enum tag names) |
| `app.addServe(install)` | `miniserve` serving an installed web directory over https, on every interface, with a self-signed certificate made once by `openssl`: https makes the page a secure context on any device, which WebGPU and the microphone need. Its defaults are environment variables, so miniserve options after `--` replace them |
-| `app.addRun(lib, .{})` | the generic host running the installed library |
+| `app.addRun(lib, .{})` | the generic host running the installed library, its files in `.sketchbook/` |
| `app.addScript(exe_or_lib, file, .{})` | a headless, fresh-state scripted run, of the executable or of the library through the host (so the script can `reload` it) |
| `app.addExport(exe, .{ .fps, .frames, .size })` | a headless export of the executable's frames, as PNGs in `.frames`, a directory of the cache |
-| `app.addProbe(state)` | the probe on a state file |
-| `app.addTest(.{})` | tests with the app importable as `app` |
+| `app.addTest(.{})` | tests with the app importable as `app`, linked with `sb.text` (FreeType, HarfBuzz and `vendor/text.c`), so they measure text as the host does |
| `app.addReloadCheck(.{ .script, .edits })` | a check that the app hot-reloads with State kept (below) |
`sketchbook.init(b, .{ ..., .script_optimize = .ReleaseSafe })` builds
@@ -729,6 +1215,9 @@ for sketches whose per-pixel loops crawl in Debug; null (the default) is
`optimize`. Only Zig code changes mode (the host's and the app's), so it
costs one more compile, not SDL's. A `b.option` makes it a `-D` flag.
+`sb.app(.{ ..., .record = true })` keeps history in every mode (see
+The host); null, the default, in Debug builds only.
+
**Hot reload, checked.** `addReloadCheck` builds the app's library as
written, and again from a copy of its sources with textual edits applied,
then plays a script on the first through the generic host with `{v2}`
@@ -751,8 +1240,8 @@ and Zig shaders all reach the second library. The script plays, checks
State, runs `load {v2}`, checks the same State, and compares screenshots
(`expect-different-screenshot a.png b.png [x y w h]`). Pausing a replay
first (`record`, `play`, `pause`) keeps the State still, so the two
-screenshots differ only by the edit. `sketches/shaders` and
-`sketches/noc` (bouncing_ball) have one each.
+screenshots differ only by the edit. `examples/shaders` and
+`examples/noc` (bouncing_ball) have one each.
Shaders:
@@ -792,7 +1281,7 @@ and naga's reader does not; and naga translates the result for the web as
for GLSL. Shader code cannot use table-driven `std.math` (`atan2`: call
GLSL.std.450 through inline assembly), and a uniform struct shared with
the CPU needs a vec2 that is `@Vector(2, f32)` only on SPIR-V and `[2]f32`
-elsewhere. `sketches/shaders` has five Book of Shaders examples in both
+elsewhere. `examples/shaders` has five Book of Shaders examples in both
languages.
Tools: `glslc` (shaderc, or the Vulkan SDK's) for shaders, for web builds
@@ -803,8 +1292,12 @@ directory), `typst` for scenes with Typst in them, and for `serve`,
and Pillow (the renderers against resvg), `ffmpeg` if there is one, and,
for `zig build test-web`, Chrome.
-`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`),
-`sb.host_exe` and `sb.probe_exe` are exposed for anything else.
+`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`, and
+`cloud9`, the 9P library, whose `Fsys` lets an app's tests dial its own
+executable as `fs` does), `sb.host_exe` is exposed for anything else. `sb.text` is the static
+library the host measures and draws text with (FreeType and HarfBuzz, the
+packages pardes pins, built from source: no system font library is
+needed), which `app.addTest` links.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## Known limits
@@ -813,20 +1306,29 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
`f.openFile` answers with a line of any length.
- Every upload, compute dispatch and GPU pass is its own command buffer and
submit. Fine at a handful per frame; batch them per frame if that grows.
-- The store is not crash-safe: a crash in the middle of an allocation can
- leave it inconsistent, and `--fresh` starts it over.
-- Handles inside Store containers (`std.ArrayList(sk.Image)`) are not caught
- at compile time: the check does not follow pointers.
- Native antialiasing resolves coverage per sample within a run of
shapes, the canvas per shape, so where two shapes' edges meet the web
can show a faint seam native does not. `fill` rects and images are
antialiased natively only inside a target. Without a GPU renderer,
native draws aliased. A stroke that overlaps itself blends twice
natively where it overlaps, once on the web.
-- On the web: nothing persists (Store lasts as long as the page),
- synthesised voices are silent, `loadSound` knows only sounds the page
- decoded, multisampling is 4× at most, and mixing runs on the main thread
- (a ScriptProcessor), so a busy page can crackle.
+- A keyframe hashes all of State to find the pages that changed: about 70
+ ms for 32 MiB in a Debug build, 3 ms in ReleaseFast, once a minute while
+ State changes and at every jump.
+- On the web: nothing persists and no
+ sessions are recorded, and multisampling is 4× at most. Every voice is
+ silent there, whatever its sound (loaded, decoded or made with
+ `newSound`), and so are groups' gains; `decodeSound` gives `.none`, and
+ `loadSound` knows only sounds the page decoded (opened or dropped
+ files). What does sound: streams (`f.audio`, `f.audioBuffer`) and the
+ microphone, mixed on the main thread (a ScriptProcessor), so a busy page
+ can crackle. A GPU buffer streamed there arrives a frame or two later
+ (WebGPU reads back only asynchronously), counted as queued meanwhile, and
+ `in.lead` is a fixed 100 ms.
+
+The reusable GPU executor and the pardes integration are described in
+[docs/pardes-rendering.md](docs/pardes-rendering.md), including the remaining
+renderer migration work and the optional addon boundary.
## Designs
@@ -837,16 +1339,23 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## The boundary
Host and sketch are built by the same `zig build`, so ordinary Zig types cross
-it (slices, tagged unions, `std.mem.Allocator`). `abi.hash`, a comptime hash
-of every shared type's layout, guards against the one real hazard: a host
-refuses a library built against different definitions. Everything that outlives
-a call lives in host memory, since host code is never unloaded. Only the
-recorded `Event` and the reflected `Layout` are `extern`, because they are
-written to disk.
+it (slices, tagged unions, `std.mem.Allocator`). `abi.hash`, a hash of
+every shared type's layout and of the zig version, backend and optimize
+mode, guards against the real hazards: a host refuses a library built
+against different definitions, or by another compiler or mode (`zig build
+run` beside `zig build lib --watch -Doptimize=fast`: Zig's own calling
+convention differs between them), and says what differs. The layout half
+costs half a second of comptime, so a small program (`src/abi_hash.zig`)
+computes it once per change of the abi sources, at build time, and host and
+sketches import the number; it is computed for the build machine in Debug,
+so a layout change seen only by another target or mode is not caught.
+Everything that outlives a call lives in host memory, since host code is
+never unloaded. Only the recorded `Event` and the reflected `Layout` are
+`extern`, because they are written to disk.
`zig build test` in this directory runs the unit tests, a headless reload
through `dlopen`, where a counter sketch changes its layout mid-run and keeps
-its values, and a replay test (`test/replay.script`): a recording played,
+its values, and a replay test (`test/replay.script`): a clip played,
sought, stepped and replayed after a live pointer move, each ending on the
state it was stopped at.
@@ -862,7 +1371,9 @@ them with the native screenshots (`tools/chrome.mjs`), and times 5000
circles a frame (software Canvas2D here: about 12 ms as 5000 shapes, 8 ms
batched).
-And the rest: `test/text.zig` (a box of `textSize` under each line),
+And the rest: `test/text.zig` (a box of `textSize` under each line, and a
+wrapped, centred paragraph with spans and a caret; `zig build test-text`
+with `sk.text`'s tests and the atlas's rasters against pardes's),
`test/export.zig` (two builds export the same frames, frame k at k/fps;
the raw stream's length; a video from ffmpeg with as many frames), and the
`anim` player on its two test scenes: the live one checks, pixel by
@@ -889,3 +1400,317 @@ canvas, in release mode, and fails if a simple one (30 shapes) takes 1 ms
to parse and draw: an equation of 8 shapes parses in 0.02 ms, draws on the
CPU in 0.25 ms, and is recorded as a GPU pass in 0.02 ms (the GPU's own
time is not measured).
+
+### Optional native profiling
+
+Build the host with `zig build -Doptimize=ReleaseFast -Dtracy=/absolute/path/to/tracy`.
+The checkout supplies `public/TracyClient.cpp`; no profiler is downloaded or
+linked by default. Linked native apps pass their `-Dtracy` option to `sketchbook.init` as
+`.tracy = path` and can import `sb.modules.tracy` for their own zones:
+`const zone = tracy.zone(@src(), "work"); defer zone.end();`.
+The host marks frames, input polling, drawing, command painting and presentation.
+These are CPU wall times (presentation includes waits), not GPU timestamps.
+Use a matching `tracy-capture` or the Tracy UI. Disabled builds compile the
+calls out; tests disable their zones too. The wrapper follows Pardes's small
+Zig Tracy binding. Forward the same option through dependencies that also
+initialize Sketchbook so the build shares one host/client module.
+
+Text rasterizes each glyph once into one atlas, whatever its ink. The pinned SDL Vulkan
+patch keeps memory relocation disabled and lets small transfer buffers share
+allocations, avoiding hundreds of dedicated allocation frees during presentation.
+
+## glTF / GLB assets
+
+The optional `gltf` module wraps the vendored C99 `cgltf` loader. It loads scene
+hierarchies, mesh accessors, materials, cameras, animation tracks and arbitrary
+`extras` metadata without depending on the window or renderer. Import it into a
+native executable or sketch with `.imports = &.{.{ .name = "gltf", .module = sb.modules.gltf }}`.
+It currently requires libc; it is not wired into the freestanding browser host.
+
+```zig
+const gltf = @import("gltf");
+const document = try gltf.Document.parse(bytes);
+defer document.deinit();
+try document.loadBuffers(null); // embedded GLB / data-URI buffers, no file reads
+const node = document.findNode("CAM_StreetTour") orelse return error.MissingCamera;
+const json = gltf.extrasJson(&node.extras) orelse return error.MissingMetadata;
+// Parse json with std.json using the application's own metadata schema.
+```
+
+Keep `bytes` alive until `deinit`: GLB buffers may borrow it. Parsing validates
+structure and uses cgltf's C allocator, released by `deinit`. `loadBuffers`
+validates again with loaded data. Only passing a non-null, zero-terminated glTF
+source path enables relative external buffer-file reads; use that for trusted
+assets. Images and compressed geometry still need their own decoders.
+
+`document.data` and `gltf.c` expose cgltf directly; `gltf.readFloats(accessor,
+index, out)` adds bounds/component checks and supports strided, normalized and
+sparse accessors. The raw animation channels remain available to the caller;
+this module does not create GPU resources or implement an animation player.
+Run `zig build test-gltf` for focused loader tests; they are also part of
+`zig build test`.
+
+### Generated scene bindings
+
+`sb.addGltf` runs a native host executable in a separate build step, then supplies
+its generated `.zig` file as a module. The glTF file is a tracked build input;
+changing it regenerates the bindings before compiling their consumers.
+
+```zig
+// build.zig: add this import to the consuming module's .imports.
+.{ .name = "street_scene", .module = sb.addGltf(b.path("street.glb")) }
+```
+
+```zig
+const scene = @import("street_scene");
+const camera = scene.nodes.CAM_StreetTour;
+comptime {
+ if (!@import("std").mem.eql(u8, camera.extras.drat_role, "camera"))
+ @compileError("expected a camera role");
+}
+// camera.index locates the node; @TypeOf(camera.extras) exposes metadata fields.
+```
+
+The generated `nodes`, `animations`, `cameras`, `meshes`, and `materials`
+namespaces expose named entries with indices and typed `extras`; nodes also
+include optional camera and mesh indices. Labels with spaces use Zig's quoted
+identifier syntax, e.g. `scene.nodes.@"Camera - At the corner"`. Unnamed entries
+are omitted; duplicate labels within one namespace fail generation. JSON objects
+become struct values, arrays become tuples, and strings/numbers retain explicit
+Zig types. Comptime can reflect on these types or assert expected values; it never
+parses the asset. Missing referenced labels/fields and incompatible types fail
+compilation; application assertions define which metadata values must match.
+
+The module contains no libc dependency. `source_path` is the build input filename;
+`source_sha256` lets runtime consumers
+reject a replaced asset before using generated indices. Code generation reads
+metadata, not external buffers; geometry and animation sample checks still use
+the runtime loader. The game repo's `scripts/check_scene.zig` demonstrates both.
+
+### Local 9P controls
+
+A running sketch is a small file tree, served over 9P by cloud9: its
+State as files, a `ctl` that takes the console's words and a script's
+input, its screen as a PNG. The tree describes itself: `README` has a
+line for every file, every verb under `ctl` and every State file under
+`state/`, made from the same tables the console, scripts and `--help`
+read; `commands` lists the verbs alone, the sketch's own last.
+
+A run a person watches posts its tree as `sketchbook/<name>` (the
+socket `$XDG_RUNTIME_DIR/9p/sketchbook/<name>`, owner-only, removed at
+a clean exit); `--9p NAME` posts it under another name, also headless,
+and `--9p /path.sock` listens at a path instead. Every executable built
+with sketchbook, and the generic host after its LIBRARY, takes `fs VERB
+PATH`: cloud9's verbs (`ls read write ask follow stat help complete`)
+on that tree, the server's refusals printed in its words, exit status 1.
+With the sketch closed, `fs` serves the same tree itself, with no
+window, from the save's newest State (the default save, or `--state`'s),
+else from State's declared defaults: `README`, `commands` and `state/`
+answer, and the rest say the sketch is not running. A `read` answered
+that way says so on stderr (`drat-meout is not running: this is its
+save's newest State, frame 61 of ...`), so a script that reads before the
+sketch is up does not take the save for it.
+
+```
+ctl write a verb a line: ctl's own (screenshot, profile-reset),
+ a script's input verbs (click, key, type...: routed live,
+ no frame of their own), the console's (set, load, pause,
+ step...); any other line goes to the sketch
+status, log name, canvas, mode, GPU, screenshot state; the console's
+ last five lines
+screen.png the next frame: an open waits for it to be drawn
+README the tree, a line a file; commands: the verbs
+state/ the State: a directory per struct and per array, a file
+ per value (state/tracker/songs/3/bpm); a read is the
+ value as `get` shows it, a write is `set` (a jump)
+sketch/ reserved for the sketch's own files, empty
+```
+
+An array of numbers is one file of its values, blank-separated
+(`state/talk/text`, a vector's lanes), written the same way; an array
+of arrays is a directory of such rows; an array of structs a directory
+of indices, so drat-meout's 8x16x16x4 tracker notes are
+`state/tracker/songs/<n>/patterns/<n>/<n>/<n>/pitch`. Optionals and
+unions read as `<N bytes>` and refuse writes. A value is read as it was
+at the open.
+
+Driving a sketch from an agent, here drat-meout:
+
+```sh
+drat-meout --headless --9p drat-meout & # or just run it: it posts itself
+drat-meout fs help ctl # the verbs, with their arguments
+drat-meout fs write ctl 'scene street' # a console line, or the sketch's
+drat-meout fs read state/scene # .street
+until [ "$(drat-meout fs read state/street/time | cut -d. -f1)" -ge 3 ]; do :; done
+drat-meout fs write ctl 'click 480 300' # input, live
+drat-meout fs read screen.png > street.png # one read: answered when the frame lands
+drat-meout fs write state/street/camera fast # fs: state/street/camera: InvalidValue
+drat-meout fs help state/street/camera # state/street/camera .placeholder .scene
+drat-meout fs write ctl quit
+drat-meout fs read state/scene # closed: from the save
+```
+
+Scripts stay what tests use (a fixed clock, fresh state, `expect`); the
+tree is live, between real frames, and an agent asserts by reading.
+Anything that speaks 9P works too: `9p -a
+unix!$XDG_RUNTIME_DIR/9p/sketchbook/drat-meout read state/scene`.
+Four clients can connect; requests run between frames on the host
+thread. `zig build test-fs` drives a sketch this way.
+
+The native host's `timing` command toggles a scrolling graph with average, p90
+and p99 in milliseconds. `timing on|off` sets visibility;
+`timing frame|work` selects the graph and shows it; `overlay timing` also toggles.
+`timing stats` prints current average/p90/p99/maximum; `timing reset` clears history
+without changing visibility or metric. Collection continues while hidden.
+Readouts refresh about four times a second from fixed text buffers. All glyphs
+reuse one immutable atlas texture, so changing values neither rasterizes text
+nor switches textures per digit. Fixed vertex/index arrays batch the entire
+panel, graph and text into one geometry draw, without per-frame overlay allocation.
+Percentiles use nearest rank over the last 240 individual frames. A separate
+fixed graph ring holds 240 peaks, each over eight frames: eight times slower
+scrolling, with single-frame spikes preserved across 1920 frames. Its scale
+label updates when the peak range changes. Frame measures wall-clock cadence
+between completed host frames, including pacing, event/9P polling and present.
+Work measures update/draw through the deferred 2D command flush, before present.
+Both include visible overlays and screenshot capture and use real time even
+during replay/export. These are not GPU hardware timestamps, and frame can
+include vsync waits. No GPU synchronization is added. Test with
+`zig build test-timing`.
+
+The read-only 9P file `timing-trace` exports paired raw samples as CSV:
+`index,frame_ns,work_ns,outside_work_ns`. Indices start at zero within the captured
+history, oldest first. `outside_work_ns` is saturating `frame_ns - work_ns`, including
+pacing, polling, presentation and cleanup; it is not a hardware GPU duration. Each
+open pins the bounded timing history, so subsequent frames or `timing reset`
+cannot change a partially read trace. It works without `--profile-gpu`:
+`drat-meout fs read timing-trace > timing.csv`.
+
+For compositor/video measurements, launch with `--timing-marker`. This opt-in
+marker is drawn last, independently of the timing overlay: 80 black/white cells,
+each 4×8 canvas pixels, at the bottom-left (320×8 total). Cells encode, LSB-first,
+16-bit magic `0xD3A7`, the low 32 bits of `Input.frame`, then the low 32 bits of
+`Input.now` in whole milliseconds. It identifies submitted frames and draw
+sample times in captured video; repeated decoded IDs reveal repeated presented
+frames. Decode at canvas scale, accounting for any window/compositor scaling.
+The marker is omitted when the canvas is smaller than 320×8 and is disabled by
+default. `zig build test-timing` checks its encoding, placement and counter wrap.
+
+On Wayland, `presentation-trace` provides immutable CSV snapshots of
+`wp_presentation` feedback: frame ID, sample time, request time, presented/discarded
+result, presentation timestamp, refresh period, sequence and flags. Status and
+clock metadata make unsupported backends explicit. `commit_ns` is the feedback
+request time before present, not an intercepted surface commit. Only subtract
+timestamps in the same clock domain; sample time uses SDL's elapsed clock.
+Feedback attaches to the next surface commit, which the binary marker lets a
+compositor capture independently verify.
+
+Interactive Wayland windows use this feedback to pace submissions and sample
+one shared frame clock before update and draw. Ordinary `Input.now`, tick events
+and `Input.dt` therefore follow display refresh automatically; sketches need no
+separate rendering clock or animation correction. A tick never precedes the
+previous frame or its queued input, so newly arrived input can move it slightly
+past the scheduled instant. Recording stores these exact ticks; replay, scripts
+and export retain their existing clocks. The browser already uses the
+`requestAnimationFrame` timestamp for its shared update/draw clock.
+Without usable feedback, rendering falls back to SDL's normal presentation and
+wall-clock ticks. Hidden/minimized windows keep servicing controls but skip
+animation and drawing until visible again.
+The implementation is `src/host/Presentation.zig`, including the Wayland callbacks
+and trace writer. `zig build test-presentation` checks its clock and feedback
+behavior. Linux builds require `wayland-scanner` plus the `wayland-client`
+development package and pkg-config metadata. The build generates the protocol
+header/tables from the vendored XML and translates the header into Zig bindings;
+only the generated protocol tables are compiled as C.
+
+
+`ctl` takes up to 4096 bytes a write; an error returns as the 9P error,
+the error's name (`UnknownField`, `InvalidValue`). Each open of
+`screen.png` (and of the traces, `README` and a State file) pins its own
+copy, so a later frame cannot change a partially read one; screenshots
+include visible overlays. `zig build test-control` checks the control
+boundary and snapshot lifetime; the same tests belong to the full host
+suite.
+
+With `--profile-gpu`, `profile` reports tab-separated `label`, `count`, `mean_ms`,
+and `worst_ms`, plus a `# frames N` line. `profile-reset` written to `ctl` resets
+counters and the frame denominator without discarding label allocations. Warm up
+first, reset, then wait for the desired number of frames before reading. These
+measure CPU wall time from GPU command recording through submission and fence
+wait, including synchronization overhead; they are not hardware GPU timestamps.
+Both operations return `ProfilingDisabled` when profiling is off.
+
+### Imperative glTF drawing
+
+Add an import with `.module = sb.addGltfRenderer()` (e.g. named `gltf_render`).
+Its `Model` copies a GLB's meshes and animation tracks into the caller's session
+arena. The cgltf document is released after loading; geometry uploads once to
+host-owned GPU buffers. Opaque primitives in each mesh are batched into one draw
+with per-vertex material colors. Only transforms and draw commands change each frame.
+
+```zig
+const render = @import("gltf_render");
+const street_scene = @import("street_scene");
+pub const Session = struct { model: render.Model = undefined, image: sk.Image = .none };
+
+pub fn setup(ss: *Session, init: *sk.Init) !void {
+ // Filename + hash come from the generated bindings. Parses and uploads once.
+ ss.model = try render.Model.load(init, street_scene);
+ ss.image = init.host.newImage(960, 600);
+}
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ renderFrame(s, ss, f) catch |err| f.host.print("scene: {t}", .{err});
+}
+fn renderFrame(s: *const State, ss: *Session, f: *sk.Frame) !void {
+ try ss.model.scene.sample(street_scene.animations.CAM_StreetTour.index, s.time);
+ const camera = try render.sceneCamera(&ss.model.scene, street_scene.nodes.CAM_StreetTour.index);
+ var view = render.View.init(f, ss.image, 960, 600, camera);
+ try view.scene(&ss.model);
+ // Or: try view.mesh(&ss.model, street_scene.meshes.MyMesh.index, transform);
+ // Or: try view.triangles(&geometry, transform, color); // upload in setup first
+ view.end();
+ f.image(ss.image, .{ .x = 0, .y = 0, .w = 960, .h = 600 }, .{});
+}
+```
+
+`model.scene.nodes[index].world` is a column-major transform; `meshes[index]`
+exposes indexed vertices, normals and material colors. Animation sampling is
+allocation-free, supports STEP, LINEAR (slerp for rotations), and CUBICSPLINE TRS,
+and clamps to the clip range; the application decides how to loop. The separate
+CPU API is `gltf.Scene.init(allocator, document)`, `sample`, `reset`, and `deinit`.
+It copies loaded data, so the document can be destroyed after initialization.
+
+`render.sceneCamera(scene, node_index)` derives perspective or orthographic
+projection and view from the sampled camera node. Alternatively pass a plain
+`render.Camera` with your own eye/target to `View.init`. `Model.init` remains
+available for CPU loading, and `Geometry.upload(host)` uploads custom triangles
+explicitly during setup. No resource loading happens inside `View.scene/mesh`.
+
+This initial renderer uses opaque material base colors, directional light and a
+depth buffer. It has no texture sampling, alpha blending, shadows, skinning or
+morph animation. Unsupported mesh/animation features fail loading explicitly;
+material textures are ignored. The renderer currently supports native hosts;
+`render.supported` is false in the browser replacement module. GPU handles are
+released by the host on session reset; call `model.release(host)` to release them
+earlier. Vertex storage layout and shader uniform layout are checked at comptime;
+GLSL uniform declarations are generated from the Zig types.
+
+A separate fullscreen pass can sample a completed render with
+`f.postProcess(source, target, .{ .vertex = vertex_shader, .fragment = fragment_shader,
+.sample_depth = true, .fragment_uniforms = uniforms })`. Allocate distinct source
+and target images in setup, then draw the target image after this command.
+Native fragment bindings are color at 0 and depth at 1 (set 2). Web GLSL uses
+separate texture/sampler pairs at 0/1 and 2/3 (set 2). Fragment uniforms use set 3,
+binding 0. Depth sampling requires the source's latest pass to have `.depth = true`
+and `.samples = 1`; missing depth, multisampled depth and feedback loops are
+rejected. Omit `sample_depth` for a color-only pass. Native profiling reports this
+work separately as `postprocess`.
+
+`profile` also includes `p95_ms` and `p99_ms`: nearest-rank percentiles of the
+latest 2048 measured commands per label. Mean and worst cover every command since
+reset. `profile-trace` exposes those retained samples as CSV (`label,sample,ns`),
+ordered oldest to newest within each label; sample numbers start at 1 after
+reset. Each open pins the trace even if profiling continues or counters reset.
+The render path writes a fixed ring; sorting and CSV generation happen only on
+inspection. A trace snapshot is limited to 256 KiB and fails if it exceeds that
+limit. Capture it with `drat-meout fs read profile-trace > trace.csv`.