summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:13:20 -0300
committerGabriel Schneider <[email protected]>2026-11-12 13:22:02 -0300
commit86ffca0024326110962f0880727f4eb84e6a48d1 (patch)
tree055f489341053c1db258606bb63b282bc7345a89 /README.md
parenta62a6aa896adda901d335ef38814a13b8839545c (diff)
downloadsketchbook-86ffca0024326110962f0880727f4eb84e6a48d1.tar.gz
sketchbook-86ffca0024326110962f0880727f4eb84e6a48d1.zip
sketchbook: frames for ffmpeg (--export, on a clock of its own), text sizes, a font from the environment
Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'README.md')
-rw-r--r--README.md40
1 files changed, 38 insertions, 2 deletions
diff --git a/README.md b/README.md
index e364c30..181493b 100644
--- a/README.md
+++ b/README.md
@@ -93,11 +93,23 @@ State.
`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `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
+`decodeSound`, `samples`, `readFile`, `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.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)`
@@ -425,6 +437,27 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
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.
+- **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:
+
+ ```sh
+ demo --export frames --size 1920x1080 --frames 600
+ demo --export - --size 3840x2160 --fps 60 --frames 600 |
+ ffmpeg -f rawvideo -pix_fmt rgba -s 3840x2160 -r 60 -i - -pix_fmt yuv420p out.mp4
+ ```
+
+ The frames run on a clock of their own: frame k is k/fps seconds in
+ (`--fps N`, 60 unless given) and its tick is exactly 1/N s (frame 0's
+ is 0, as any run's first), however long a frame takes to draw. A sketch
+ that takes its time from the ticks exports the same frames every time.
+ It ends after `--frames N`, or when the sketch calls `f.quit()`;
+ `in.exporting` tells a sketch that nobody is watching, so a player
+ 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.
- **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
@@ -478,7 +511,9 @@ pub fn build(b: *std.Build) void {
}
```
-`addSteps` installs the executable and adds `run`, `lib`, `probe`, `e2e` and
+`addSteps` installs the executable and adds `run`, `lib`, `probe`,
+`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
`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
@@ -493,6 +528,7 @@ and returns plain `std.Build` objects:
| `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.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) |