diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 1115 |
1 files changed, 970 insertions, 145 deletions
@@ -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`. |
