diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-28 21:07:13 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-12 13:22:02 -0300 |
| commit | 590ba7b9b579b97e34b51ab7e3460ebc85713343 (patch) | |
| tree | 6a73a7570ff4f79f41deff078455877b9bc6571b /README.md | |
| parent | bc8e6eb1bfef0c5e9b3c40fc1e4fd5a1659e2b03 (diff) | |
| download | sketchbook-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.md | 212 |
1 files changed, 180 insertions, 32 deletions
@@ -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 |
