summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-10-28 21:07:13 -0300
committerGabriel Schneider <[email protected]>2026-11-12 13:22:02 -0300
commit590ba7b9b579b97e34b51ab7e3460ebc85713343 (patch)
tree6a73a7570ff4f79f41deff078455877b9bc6571b /README.md
parentbc8e6eb1bfef0c5e9b3c40fc1e4fd5a1659e2b03 (diff)
downloadsketchbook-590ba7b9b579b97e34b51ab7e3460ebc85713343.tar.gz
sketchbook-590ba7b9b579b97e34b51ab7e3460ebc85713343.zip
sketchbook: Zig 0.17, a Store on disk, requests, a scope (waveform, spectrum, spectrogram), audio codecs and fonts, web host
Diffstat (limited to 'README.md')
-rw-r--r--README.md212
1 files changed, 180 insertions, 32 deletions
diff --git a/README.md b/README.md
index 78aee58..ff9e538 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# sketchbook
-A small Zig 0.16 platform for sketching games and toys, in the spirit of
+A small Zig 0.17 platform for sketching games and toys, in the spirit of
Processing and pygame: write plain data and two functions, save, and the
running program picks up the new code with its state intact.
@@ -29,25 +29,75 @@ An app is an ordinary module. Every declaration is optional:
| Declaration | Meaning |
| --- | --- |
| `name`, `width`, `height` | Window title and initial canvas |
-| `State` | Persistent state: saved to a file, snapshotted, replayed. No pointers (compile error). |
-| `Session` | Survives reloads, never saved: caches, loaded handles, audio buffers. May point into host memory. |
+| `State` | Saved to a file, snapshotted, replayed: what `update` changes. No pointers and no host handles (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 |
| `update(state, input)` | **Deterministic**: the host replays recorded input through it |
-| `draw(state, session, frame)` | Pictures and sound, as commands; may change only `Session` |
-| `command(state, session, console, line) !bool` | Console lines the host does not know |
+| `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 |
| `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
+`State` and `Input`; asking for more is a compile error, since a replay could
+not reproduce it.
+
+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`.
+
+`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
+`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.
+
+`input.width`/`height` are the canvas, which a sketch sets with
+`f.canvas(w, h)` and the host scales to fit its window.
+`input.window_width`/`window_height` are the room it has (the window, in CSS
+pixels on the web): a sketch that sets its canvas to them, and lays out by
+the canvas, is responsive, at its own scale on a phone as on a desktop.
+
`update` sees `input.events`: pointer, wheel, key, text, `cancel` (focus loss,
-console) and one `tick` per frame carrying `dt`. Recorded ticks make
+console) and one `tick` per frame carrying `dt`. Pointer and wheel events
+carry the modifier keys held as they happened (`e.modifiers()`, `Key.Mod`
+bits): read those, not `input.held`, for ctrl+wheel and the like, since a
+trackpad's or a touch screen's pinch arrives as ctrl+wheel with no key
+events at all. Recorded ticks make
time-driven sketches replay exactly. `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.
`draw` gets a `Frame`: `clear`, `fill`, `image`, `text`, `print`, `clip`,
-`canvas`, `cursor`, `voice`, `audio`, `pixels`, `quit`, plus `f.arena` (frame
-lifetime), `f.gpa` (session lifetime) and `f.host` (`loadImage`,
-`decodeImage`, `newImage`, `loadSound`, `decodeSound`, `readFile`, `env`,
-`log`).
+`canvas`, `cursor`, `voice`, `audio`, `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`). 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.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).
+
+`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.
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
@@ -58,6 +108,14 @@ helpers return the caller's own type:
- `sk.Camera`: `toScreen`, `toWorld`, `pan`, `zoomAt`
- `sk.tween`: `lerp` over any plain data, `lerpFields(a, b, t, .{ .x, .zoom })`, `toward(a, .{ .x = 100 }, t)`, and `ease`
+**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.
+
**Vector graphics**, in the `vector` module (import `sb.modules.vector`):
SVG parsing (the static subset Typst emits, and more) into cubic Bézier
data; flattening, stroking, dashing, trimming, clipping and morphing as
@@ -66,21 +124,38 @@ backend computes exact coverage and runs anywhere, wasm included. The GPU
backend describes stencil-then-cover passes (8× MSAA, gradients in a
shader). Both are tested against resvg (see `sketches/vecanim` in the game repository).
-**GPU work is data.** A sketch describes pipelines (SPIR-V, vertex layout,
-blend, stencil) and passes (`f.gpu(.{ .image, .pipelines, .draws, ... })`);
-the host runs them with SDL_GPU. It caches shaders and pipelines by content
-hash, so an edited shader is just a new pipeline after a reload. No sketch
-touches a graphics API, and another host (Vulkan, WebGPU) would be another
-translation of the same data. `abi.gpu.pipeline(Vertex, ...)` derives the
+**GPU work is data.** A sketch describes pipelines (shader code, vertex
+layout, blend, stencil) and passes (`f.gpu(.{ .image, .pipelines, .draws,
+... })`); the native host runs them with SDL_GPU, the web host with WebGPU.
+Both cache shaders and pipelines by content hash, so an edited shader is
+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.
+compile time. 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,
+`f.upload(buffer, offset, bytes)` fills it, `f.compute(.{ .kernel, .readonly,
+.readwrite, .uniforms, .groups })` runs a compute shader over buffers, and a
+draw reads buffers through `.vertex_storage` / `.fragment_storage`. Results
+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.
+queued and played. `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`.
+
+Sounds decode with single-file C libraries in `vendor/` (dr_wav, dr_flac,
+stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
## The host
@@ -90,13 +165,18 @@ queued and played.
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.
+- **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.
- **Console and overlays.** `get`/`set <field path>`, snapshots, recordings and
the memory and scope overlays come from the host; unknown lines go to the
sketch.
- **Scripts** (`--headless --fresh --script file`) drive the same routing and
- frames as a player: `click`, `key`, `type`, `console`, `expect field value`,
+ frames as a player: `click`, `key`, `hold`/`release` (a key down until
+ released, for modifiers), `wheel`, `type`, `console`, `expect field value`,
`await field value` (frames until it holds, a minute at most),
`expect-audio`, `screenshot`, `load`, `reload`, `await-reload`. A failed
`expect`, or a console line that errors (a sketch command returning an
@@ -104,9 +184,43 @@ queued and played.
with `SDL_VIDEO_DRIVER` set, and GPU work still runs, into a texture.
- **GPU.** The host's 2D renderer runs on an SDL GPU device, which also
runs sketches' GPU passes. Without a GPU it falls back to any renderer.
+ `--profile-gpu` times every upload, dispatch and pass alone on an idle
+ GPU (SDL_GPU has no timestamp queries) and prints count, mean, worst and
+ per-frame time by `label` at exit.
- **Memory.** SDL allocations go through a leak-checking allocator; a leak
fails the exit.
+## The web host
+
+`web/host.js` runs the same sketch, compiled to wasm32-freestanding, in a
+page. Draw commands go to a 2D canvas; GPU passes, dispatches, uploads and
+downloads to WebGPU, whose renders are shown through the canvas; streams and
+the microphone to Web Audio (at 48 kHz where the browser agrees, sound
+starting at the first click or key, as browsers require); `f.openFile` to a
+file picker, whose sound the browser decodes and hands over by name before
+the console line arrives. `f.run` and the sketch's `command` work as on
+native.
+
+Touch: one finger is the mouse's left button. Two fingers pan, as the wheel
+(60 px a notch), and pinch, as ctrl+wheel (a notch per 20 % of spread), both
+around the point between them: what a trackpad sends, so a sketch that
+handles a trackpad handles a touch screen. Keys have no touch equivalent;
+draw buttons for what matters.
+
+Without WebGPU, the page says why the first time the sketch asks for it:
+not a secure context (WebGPU and the microphone need https, or localhost),
+WebGPU turned off (Firefox on Linux: `dom.webgpu.enabled`), or no usable
+adapter.
+
+`.web = .{ .pwa = .{ .icons = ..., .theme = ... } }` makes the page an
+installable app that opens offline: a manifest, icons, and `web/sw.js`, a
+service worker that keeps a copy of everything the page fetches, network
+first, so each new build shows as soon as there is a network. Service
+workers need a secure context, like WebGPU.
+
+For tests, `window.sketch` reads state (`field(path)`), runs console lines
+(`command(line)`) and hands over decoded sound (`sound(name, samples)`).
+
## Build API
```zig
@@ -119,38 +233,72 @@ pub fn build(b: *std.Build) void {
}
```
-`addSteps` installs the executable and adds `run`, `lib`, `web`, `probe`,
-`e2e` and `test`. Every piece is also available on its own and returns plain
-`std.Build` objects:
+`addSteps` installs the executable and adds `run`, `lib`, `probe`, `e2e` and
+`test`, and with `.web = .{}` also `web` (the page into `zig-out/web`) and
+`serve` (it, over https on port 8042, to the local network too; `zig build
+web --watch` alongside rebuilds it for the next reload). Every piece is also available on its own
+and returns plain `std.Build` objects:
| Call | Returns |
| --- | --- |
| `app.addLibrary()` | the hot-reloadable shared library |
| `app.addExecutable()` | host and sketch linked into one binary |
-| `app.addWeb(.{ .assets = ... })` | the wasm module and a ready-to-serve directory; tests can read its state by path with `sk_field` (numbers) and `sk_tag` (enum tag names) |
+| `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 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.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.addProbe(state)` | the probe on a state file |
| `app.addTest(.{})` | tests with the app importable as `app` |
-Shaders, in the same style:
+Shaders:
```zig
-const layouts = sb.addGlslLayouts(.{ .module = my_layouts, .types = &.{ "Vertex", "Paint" } });
-const shaders = sb.addSpirvModule(&.{
- .{ .name = "fill_vert", .spirv = sb.addGlslc(.{ .source = b.path("fill.vert"), .include_dirs = &.{layouts.dir} }).spirv },
+const shaders = sb.addShaders(.{
+ .layouts = .{ .module = my_layouts, .types = &.{ "Vertex", "Paint" } },
+ .sources = &.{ b.path("shaders/fill.vert"), b.path("shaders/fill.frag") },
});
+const app = sb.app(.{ ..., .imports = &.{.{ .name = "shaders", .module = shaders.module }} });
+// in the sketch: .{ .code = shaders.fill_vert }
```
-`addGlslLayouts` writes `<Name>.glsl` declarations generated from Zig
-structs (tagged with `pub const glsl = .vertex` or
-`.{ .uniform = .{ .set, .instance } }`), so the Zig struct is the one
-definition. `addGlslc` compiles one file. `addSpirvModule` embeds the
-results, aligned for Vulkan.
+The layouts are Zig structs (tagged with `pub const glsl = .vertex` or
+`.{ .uniform = .{ .set, .instance } }`) written out as `<Name>.glsl` for the
+sources to `#include`, so the Zig struct is the one definition. Each source
+is compiled by `glslc` into `shaders.module`, as SPIR-V under its file name
+(`fill.vert` is `fill_vert`). For the web it is compiled again with
+`SKETCHBOOK_WEB` defined and translated by `naga` into `shaders.web`, the
+same names in WGSL; `addWeb` puts that twin in place of the SPIR-V module
+wherever the app's imports reach it, however deep (the `vector` module's
+shaders included). Only the web build runs `naga`, and a missing tool
+fails only the steps that need it, listing where it looked. WGSL has no
+write-only storage buffers and no `coherent`: write them plain, or under
+`#ifndef SKETCHBOOK_WEB`. Sources may `#include` files beside them;
+`glslc`'s depfiles tell the build, so editing an included file recompiles
+what includes it. `addGlslLayouts` and `addGlslc` are the pieces, for
+anything else.
+
+Tools: `glslc` (shaderc, or the Vulkan SDK's) for shaders, for web builds
+with shaders `naga` (`cargo install naga-cli`; found on PATH or in cargo's
+directory), and for `serve`, `miniserve` and `openssl`.
`sb.modules`, `sb.host_exe` and `sb.probe_exe` are exposed for anything else.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
+## Known limits
+
+- The console line holds 96 characters, so long paths cannot be typed;
+ `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.
+- 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.
+
## Designs
- [Regions in source](docs/regions-in-source.md): editing layout from the