diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-17 01:32:18 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-17 12:15:01 -0300 |
| commit | 62ab82af9da007a8ff04677943809cf541b1e420 (patch) | |
| tree | 9e0da7051fcf606860ada1d2202f14a768d21182 | |
| parent | 8bf10e316178755b8710e27c807dbf9b6a1d37a8 (diff) | |
| download | sketchbook-62ab82af9da007a8ff04677943809cf541b1e420.tar.gz sketchbook-62ab82af9da007a8ff04677943809cf541b1e420.zip | |
README: one thing a sketch keeps, in one file; what a crash loses; the cap
The manual described a mapped state file, a sessions database beside
it, a probe, private files for scripted runs and exits that compact
past 64 MiB. Now, in The host: "The save" replaces "State file" (one
thing, State, in one file, `<name>.xitdb`; the present restored and
replayed at start; keyframes as pages and what they cost, measured;
layout migration as before; an old `<name>.state` imported once and
left as it was); "Where files go" lists `<name>.xitdb` and the files a
sketch appends to, `--state x.state` and `x.xitdb` naming one save;
"Sessions" says every run is one, `record` decides how much history is
kept (a build that does not record keeps the present and the marks,
the last minute of input at most while it runs, none after), a crash
loses under a second and the next run starts from the last committed
frame; a new paragraph, "The cap": 64 MiB, State half, history dropped
oldest first and the file compacted to three quarters (about 170 ms in
Debug), the present, marks and clips never dropped, a new mark refused
with how to make room. The State row and "Data that grows" say 32 MiB;
the appendFile paragraph names `<stem>.<name>` beside the save; scripts
and exports save nothing; the Build API loses `probe`, `addProbe` and
`probe_exe`; Known limits gains the hash pass's cost. layout.zig's note
on what State may hold says where it is saved; micscope's README names
its takes `micscope.take-<id>.f32`.
Tests: zig build test, 168/168 steps.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
| -rw-r--r-- | README.md | 146 | ||||
| -rw-r--r-- | examples/micscope/README.md | 2 | ||||
| -rw-r--r-- | src/layout.zig | 7 |
3 files changed, 92 insertions, 63 deletions
@@ -44,7 +44,7 @@ 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, kept in every session's keyframes and marks, replayed: what `update` changes. No pointers, no host handles, and at most 64 MiB (compile errors). | +| `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. | | `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 | @@ -168,8 +168,8 @@ 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, -`<state>.<name>` beside its state file (in `.sketchbook/` under `zig build -run`), creating it, and returns its path for `readFile` ("" when nothing +`<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. @@ -373,7 +373,7 @@ 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 kept in keyframes, replayed and migrated, so -it holds what `update` changes, at a size fixed in its type, 64 MiB at most. +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 @@ -766,32 +766,40 @@ a talk with a slider, a loop, a choice, two slides and `beside`. 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. -- **State file.** `<name>.state` holds the live State, shared via - `MAP_SHARED`, so the file is up to date as it changes. Its header carries - the reflected layout, so a layout change migrates it field by field, with - enums matched by tag name, and `sketchbook-probe` can print any sketch's - state. 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, and the snapshot slots of files from before sessions become - marks `1` to `7` in a run that records; a file that is not a state file - is refused, never truncated. -- **Where files go.** `zig build run`, `probe` and `export` keep a sketch's - files in `.sketchbook/`: `<name>.state`, `<name>.xitdb` and the - `<name>.state.<file>` it appends to. The host makes the directory with a `.gitignore` of `*`, - so neither git nor jj takes in a database that grows (the jj snapshot a - build makes would commit one while it is under a megabyte), and moves in, - once, the 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.state` in the working directory. -- **Sessions.** Every run of a build that records is a session in - `<name>.xitdb`, one xitdb database per sketch beside its state file: an - append-only log of the events live `update` was fed, in whole frames, and +- **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. 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 @@ -799,34 +807,53 @@ a talk with a slider, a loop, a choice, two slides and `beside`. 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; marks and clips are names pointing into it. + overwritten, only dropped, oldest first, at the cap (below); marks and + clips are names pointing into it. - `App.Options.record` decides who records, at build time: null, the - default, means Debug builds. 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. A build that does not record has no marks or - clips, and the console says so. The console's status line ends with - `rec file`, `rec memory` or `rec off`, and `sessions` says where. + `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: the session lists as `(crashed)`, and a clip it left - open ends where the session does. A power loss loses what the kernel had + 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. Live State is in the state file either way. + deleted, and a new one begun. - A minute of drat-meout's play is 268 KB with the pointer moving every - frame (16 MB an hour), 164 KB idle (86 KB of ticks, the rest keyframes). - Every commit leaves the nodes it copied behind, about a kilobyte; a clean - exit compacts the file once it is past twice what its sessions hold plus - 64 MiB. Nothing is compressed or forgotten yet. + 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 @@ -893,10 +920,9 @@ a talk with a slider, a loop, a choice, two slides and `beside`. `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>`, and - `<state>.<pid>.<name>` for those it appends to), renamed to the given - `--state` at exit, so two builds running the same script at once do not - share them; its sessions are in memory. + 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: @@ -916,8 +942,8 @@ a talk with a slider, a loop, a choice, two slides and `beside`. 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 @@ -980,7 +1006,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 @@ -999,7 +1025,6 @@ and returns plain `std.Build` objects: | `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.addReloadCheck(.{ .script, .edits })` | a check that the app hot-reloads with State kept (below) | @@ -1009,8 +1034,8 @@ 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 })` records sessions in every mode (see -The host); null, the default, records in Debug builds only. +`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, @@ -1087,7 +1112,7 @@ 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.host_exe` is exposed for anything else. Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`. ## Known limits @@ -1102,6 +1127,9 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`. 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. +- 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 diff --git a/examples/micscope/README.md b/examples/micscope/README.md index e917bf0..875ebdf 100644 --- a/examples/micscope/README.md +++ b/examples/micscope/README.md @@ -149,7 +149,7 @@ browser has accepted its self-signed certificate (miniserve prints the addresses as QR codes, for phones). Each take is a file of its samples (mono 32-bit floats at the host's -rate), `micscope.state.take-<id>.f32` beside the state (in `.sketchbook/` +rate), `micscope.take-<id>.f32` beside the save (in `.sketchbook/` under `zig build run`), written as it records (`Host.appendFile`). State lists the takes, so they are still there after a restart. A take starts its file empty (`Host.writeFile`). A deleted take's file stays: a seek diff --git a/src/layout.zig b/src/layout.zig index b3c6520..c585d71 100644 --- a/src/layout.zig +++ b/src/layout.zig @@ -13,9 +13,10 @@ //! against a leaf's pattern at lookup time. //! //! What each kind of sketch memory may hold: -//! - State is saved to disk and snapshotted: no pointers, and no host -//! handles (images, sounds, buffers), which only mean something in the -//! process that made them. +//! - State is saved, the one thing a sketch keeps, in keyframes of its +//! save: no pointers, and no host handles (images, sounds, buffers), +//! which only mean something in the process that made them; at most +//! `max_state` bytes. //! - Session lives in this process: anything, as long as pointers go into //! memory the host owns (its heaps, mapped files), never into the sketch //! library, which a reload unmaps. |
