summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 11:27:39 -0300
committerGabriel Schneider <[email protected]>2026-11-12 13:22:02 -0300
commit71e534631bf68f33f802d64794340870374b9f69 (patch)
tree2a45229ce238a4e2ce355683f0e75a7725d4851a /README.md
parent00605f7a109845a99f16621b267305a8b995dddc (diff)
downloadsketchbook-71e534631bf68f33f802d64794340870374b9f69.tar.gz
sketchbook-71e534631bf68f33f802d64794340870374b9f69.zip
sketchbook: anim, manim-style scenes as a module (from the game's vecanim), with objects a scene draws itself
The player takes its canvas from the room it has and fits the scene's frame into it, plays through and quits when exported, and draws vector objects in runs around custom ones. The renderers' resvg comparison and the timings come along as `zig build diff` and `zig build bench`; the comparison's reference is padded to whole blocks rather than squeezed, which had put Typst text over the limit. Co-Authored-By: Claude Fable 5.2 <[email protected]>
Diffstat (limited to 'README.md')
-rw-r--r--README.md204
1 files changed, 198 insertions, 6 deletions
diff --git a/README.md b/README.md
index 123b2bc..ba6598a 100644
--- a/README.md
+++ b/README.md
@@ -347,7 +347,8 @@ geometry; and `vector.Renderer(.gpu)` or `vector.Renderer(.cpu)`. The CPU
backend computes exact coverage and runs anywhere, wasm included. The GPU
backend describes one pass (8× MSAA, gradients in a shader): convex fills
drawn directly, the rest stencil-then-cover, all batched into layers of
-non-overlapping fills, a few draws per layer whatever the shape count. Both are tested against resvg (see `sketches/vecanim` in the game repository).
+non-overlapping fills, a few draws per layer whatever the shape count.
+Both are tested against resvg (`zig build diff`, below).
**GPU work is data.** A sketch describes pipelines (shader code, vertex
layout, blend, stencil) and passes (`f.gpu(.{ .image, .pipelines, .draws,
@@ -382,6 +383,161 @@ while declared, and the next frame's `input.microphone` holds what it heard
Sounds decode with single-file C libraries in `vendor/` (dr_wav, dr_flac,
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
+`sb.addScene` builds the player around it:
+
+```zig
+const std = @import("std");
+const anim = @import("anim");
+
+pub const typst_preamble = "#set text(fill: white)";
+pub const scene = anim.Scene(construct);
+
+fn construct(s: *anim.Builder) void {
+ const eq = s.typst("$ a^2 + b^2 = c^2 $", .{ .y = 220, .scale = 1.4 });
+ const eq2 = s.typst("$ c = sqrt(a^2 + b^2) $", .{ .y = 220, .scale = 1.4 });
+ const square = s.rect(.{ .w = 180, .h = 180, .x = -320, .stroke = anim.blue });
+ s.play(.{eq.write()}, .{});
+ s.play(.{ square.create(), square.rotate(std.math.pi / 4.0) }, .{ .seconds = 1.5 });
+ s.play(.{eq.transformInto(eq2)}, .{});
+ s.wait(1);
+
+ // Updaters run every frame, on top of the timeline. Their extra
+ // arguments are bound here, like a closure's captures.
+ const swing = s.value(0);
+ s.always(square, wobble, .{swing});
+ s.play(.{ swing.to(0.3), anim.camera(.{ .zoom = 1.4 }) }, .{ .ease = anim.ease.outBack });
+}
+
+fn wobble(now: anim.Now, swing: anim.Value) anim.Pose {
+ var p = now.pose;
+ p.rotation += now.value(swing) * @sin(now.t * 4);
+ return p;
+}
+```
+
+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`,
+`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
+camera zoom 1, the origin in the middle, y down.
+
+A scene is one of two kinds, which share every call:
+
+- **Compiled** (`anim.Scene(construct)`): `construct` runs at comptime,
+ and what it recorded is played once, still at comptime, into keyframes
+ per object: a `from` and a `to` pose (plain structs), a time span and an
+ easing. Drawing an instant is a lookup and a `tween.lerp`, then the
+ object's updaters. The whole timeline is data before the first frame, a
+ morph can look ahead to where its target ends, a broken scene is a
+ compile error, and Typst strings are written inline.
+- **Live** (`anim.Live(frame, typst)`): `frame(s: *anim.Frame)` runs every
+ 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.
+
+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
+scene and a compiled one with the same timeline show the same poses at
+every instant.
+
+**Typst.** `s.typst(source, pose)` takes Typst markup; the scene's
+`typst_preamble` goes in front of each (by default a transparent page
+that fits its content). The build runs a generator that imports the scene
+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`.
+
+**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`
+has `pub fn draw(self: *const T, f: *sk.Frame, at: anim.Placed) void`. It
+is an object like the others: the same camera, pose, `play`, `fadeIn`,
+`move` and place in the order.
+
+```zig
+const Bar = struct {
+ level: f32,
+
+ pub fn draw(b: *const Bar, f: *sk.Frame, at: anim.Placed) void {
+ // In the object's own units, around its origin.
+ sk.draw.rect(f, .{ .x = -100, .y = -20, .w = 200, .h = 40 }, at.pen(.{ .stroke = .white, .width = 2 }));
+ sk.draw.rect(f, .{ .x = -100, .y = -20, .w = 200 * b.level, .h = 40 }, at.pen(.{ .fill = .hex(0xf0ac5f) }));
+ at.text(f, -100, 26, 1.5, "rax", .white);
+ }
+};
+
+fn frame(s: *anim.Frame) void {
+ const bar = s.new(Bar{ .level = 0 }); // lives for this frame
+ const obj = s.custom(bar, .{ .x = -200 });
+ const level = s.value(0);
+ s.play(.{ obj.fadeIn(), level.to(1) }, .{});
+ s.play(.{obj.move(.{ .x = 200, .scale = 1.5 })}, .{});
+ bar.level = s.get(level); // after the plays: as it stands now
+}
+```
+
+`at` (`anim.Placed`) is where the object stands: `xf`, its units to
+canvas pixels (camera, then pose); `scale`, pixels per unit; `pose`
+(`opacity`; `drawn`, 0 to 1 while a `write` or `create` plays, to reveal
+by; `highlight`); `stage`, scene units to pixels; `t`; and `value(v)`,
+every `Value` now, which is how a compiled scene's custom object (its
+data a constant) moves. `at.pen(pen)` is a `sk.draw.Pen` in the object's
+units at its opacity, `at.text` and `at.textSize` are `f.text` and
+`host.textSize` likewise. Text scales and moves with the object but does
+not turn. A custom object has no outline to `transformInto`.
+
+Vector objects are drawn on the GPU into an image, then the image onto
+the canvas; a custom object draws onto the canvas directly. So the
+picture is built in runs: the vector objects up to a custom one, that
+object's 2D commands, the vector objects after it, and so on, each run
+its own image (8x multisampled, at the canvas's size: about 140 MiB of
+GPU memory at 1920x1080 and 560 at 3840x2160, so add custom objects next
+to each other in the order where it does not matter). Within its `draw`,
+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:
+
+```sh
+zig build export -- frames --size 3840x2160
+zig build export -- - --size 1920x1080 --fps 60 |
+ ffmpeg -f rawvideo -pix_fmt rgba -s 1920x1080 -r 60 -i - -pix_fmt yuv420p scene.mp4
+```
+
+A package of scenes is a few lines of `build.zig`:
+
+```zig
+const sb = sketchbook.init(b, .{ .target = target, .optimize = optimize });
+const scene = sb.addScene(.{ .root_source_file = b.path("scenes/intro.zig") });
+_ = scene.app.addSteps(.{ .scripts = &.{b.path("test/intro.script")} });
+```
+
+`scene.app` is an app like any other (`run` with hot reload: save the
+scene and the animation carries on from the same instant; `lib`, `web`,
+`export`, `e2e`), named after the scene file; `.imports` are modules for
+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.
+
## The host
- **Hot reload.** It watches the library file and loads each new build through
@@ -458,7 +614,11 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
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.
+ 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
+ are only on their way to a video.
- **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
@@ -527,6 +687,7 @@ and returns plain `std.Build` objects:
| Call | Returns |
| --- | --- |
+| `sb.addScene(.{ .root_source_file, .name, .imports })` | an `anim` scene file's player: `.app`, and `.module` and `.typst` (its Typst as SVG) |
| `app.addLibrary()` | the hot-reloadable shared library |
| `app.addExecutable()` | host and sketch linked into one binary |
| `app.addScriptExecutable()` | the same, built in `script_optimize` mode, as `e2e` plays scripts with |
@@ -613,11 +774,14 @@ languages.
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`. This repository's
-own tests also run `node` (noise on wasm32, under WASI) and, for `zig build
-test-web`, Chrome.
+directory), `typst` for scenes with Typst in them, and for `serve`,
+`miniserve` and `openssl`. This repository's own tests also run `node`
+(noise on wasm32, under WASI), `typst`, `resvg` and `python3` with numpy
+and Pillow (the renderers against resvg), `ffmpeg` if there is one, and,
+for `zig build test-web`, Chrome.
-`sb.modules`, `sb.host_exe` and `sb.probe_exe` are exposed for anything else.
+`sb.modules` (`abi`, `sketch`, `host`, `vector`, `scope`, `anim`),
+`sb.host_exe` and `sb.probe_exe` are exposed for anything else.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
## Known limits
@@ -674,3 +838,31 @@ test-web` draws the shape and render cases in headless Chrome, compares
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),
+`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
+pixel, that a custom object sits over the vector object added before it
+and under the one added after, moves, fades and zooms with the timeline
+and camera, on both renderers; the compiled one is also exported at half
+size.
+
+`zig build diff` (part of `test`) renders a corpus (`test/svg`: every
+path command, fill rules, joins, caps, dashes, transforms, opacity,
+gradients, symbols, and Typst documents) with resvg as the reference, and
+with both vector backends through the real host, headless
+(`test/svgview.zig`, `tools/svgdiff.py`). Every case is under 0.7 mean
+channel error, with no more than 0.01% of pixels off by more than 48;
+side-by-side images land in `.zig-cache/svgdiff`. Two details make the
+reference fair: resvg samples coverage on four sub-scanlines, so it
+renders at 4x and is box-filtered down (padded to whole blocks, not
+squeezed); and sizes in `pt` make it round to whole pixels before
+scaling, so the harness gives it unit-free sizes.
+
+`zig build bench` (part of `test`, after the rest) times each Typst
+object of the compiled test scene at 1280x720, the drawing filling the
+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).