summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
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).