summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:19:28 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commite2daafff2ed8cc20438d05722575db69fa9ba823 (patch)
tree6f1052394d447ef2a473f3cae6a3e74e407cfb62
parent13a6f2f920c3b6d69362720318a404900f27cdf6 (diff)
downloadsketchbook-e2daafff2ed8cc20438d05722575db69fa9ba823.tar.gz
sketchbook-e2daafff2ed8cc20438d05722575db69fa9ba823.zip
anim: play's .lag staggers its animations, manim's lag ratio, 0 by default
The option was read into every key (default 0.08) and never used. Now animation i of a play of n starts i * lag * each after the play does, each = seconds / (1 + lag * (n - 1)), so the last still ends with the play and the play keeps its length: manim's AnimationGroup run to a run_time. A lag of 1 is one after another. An object two animations of one play change moves with the first (Change.at); the camera with the first camera animation. Compiled and live scenes agree: a live play shows an animation from its own key's start, as the compiled lookup does. Default 0, so every key of a scene without .lag is the bits it was (start + 0, seconds / 1). What changes: examples/manual.zig, slide 1: 83, C0, 01 and add eax, 1 were written all at once over 1.5 s, now one after another (0.79 s each, 0.24 s apart); the six labels and three bytes of the flight played together, now in order, 0.12 s apart, 0.58 s each (exported frames 22.0- 23.4 s and 25.1-26.4 s). vecanim's intro passes .lag to a play of one write: unchanged. Tests: anim: a lagged play (four at 0.5, then two at 1) live against compiled at 16 instants, and its times. test-anim, test-talk, test-manual pass; the compiled scene's export (92 frames), the talk's two (364) and every scene screenshot are byte-identical to before, but for the player bar's wall-clock record time; manual's exports differ in those 29 frames only, its screenshots not at all. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md9
-rw-r--r--src/anim/root.zig133
2 files changed, 102 insertions, 40 deletions
diff --git a/README.md b/README.md
index 042a261..7d8b1a9 100644
--- a/README.md
+++ b/README.md
@@ -559,8 +559,13 @@ were added; each call returns a handle. Animations are methods of the handle: `w
`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; in a live scene, `pause()` makes what
+options are `.seconds`, `.ease` (any `fn (f32) f32`) and `.lag`, manim's
+lag ratio (0 by default, all at once): each animation starts `lag` of its
+own length after the one before, in the order given, and the play still
+lasts `.seconds`, the last ending with it, so each of n lasts
+`seconds / (1 + lag * (n - 1))`; a lag of 1 plays them one after
+another. An object two animations of one play change is timed by the
+first. `wait` moves time on; in a live scene, `pause()` makes what
follows wait for a click (see Talks). Positions are scene units: 1280x720 of them show at
camera zoom 1, the origin in the middle, y down. The page behind them is
the scene file's `pub const background = 0xRRGGBB` (manim's grey without
diff --git a/src/anim/root.zig b/src/anim/root.zig
index 560d71b..03abf11 100644
--- a/src/anim/root.zig
+++ b/src/anim/root.zig
@@ -54,7 +54,8 @@
//! `fadeIn`, `fadeOut`, `transformInto` (morph), `move`, `scaleTo`,
//! `rotate`, `indicate`; and `camera`, `Value.to`. `play` runs a tuple of
//! them together, with options `.seconds`, `.ease` (any `fn (f32) f32`,
-//! `ease.smooth` by default) and `.lag`. `wait` moves time on; `pause`
+//! `ease.smooth` by default) and `.lag` (manim's lag ratio, 0 by
+//! default). `wait` moves time on; `pause`
//! makes what follows wait for a click, like a slide step. Typst is
//! compiled at build time (`sb.addScene`), from the scene's
//! `typst_sources`.
@@ -118,7 +119,6 @@ pub fn Key(comptime P: type) type {
start: f32,
end: f32,
ease: Ease,
- lag: f32 = 0,
from: P,
to: P,
@@ -387,7 +387,7 @@ const Play = struct {
animations: []const Animation,
/// `play`'s options: `.seconds` (1, or 2 with a write in it), `.ease`
- /// (`ease.smooth`) and `.lag` (0.08).
+ /// (`ease.smooth`) and `.lag` (0: all start together).
fn of(start: f32, animations: []const Animation, options: anytype) Play {
const O = @TypeOf(options);
var seconds: f32 = 1;
@@ -399,13 +399,18 @@ const Play = struct {
.start = start,
.seconds = seconds,
.ease = if (@hasField(O, "ease")) options.ease else ease.smooth,
- .lag = if (@hasField(O, "lag")) options.lag else 0.08,
+ .lag = if (@hasField(O, "lag")) options.lag else 0,
.animations = animations,
};
}
- fn key(p: Play, comptime P: type, from: P, to: P, with: ?Ease) Key(P) {
- return .{ .start = p.start, .end = p.start + p.seconds, .ease = with orelse p.ease, .lag = p.lag, .from = from, .to = to };
+ /// Animation `i`'s key. With a lag, manim's lag ratio: each animation
+ /// starts `lag` of its length after the one before, and all are as long
+ /// as lets the last end with the play.
+ fn key(p: Play, comptime P: type, i: usize, from: P, to: P, with: ?Ease) Key(P) {
+ const each = p.seconds / (1 + p.lag * @as(f32, @floatFromInt(@max(p.animations.len, 1) - 1)));
+ const start = p.start + @as(f32, @floatFromInt(i)) * p.lag * each;
+ return .{ .start = start, .end = start + each, .ease = with orelse p.ease, .from = from, .to = to };
}
};
@@ -423,16 +428,17 @@ fn count(comptime T: type) usize {
};
}
-/// What a play does to one object: the pose it starts from and ends on.
-const Change = struct { obj: u16, from: Pose, to: Pose, ease: ?Ease = null };
+/// What a play does to one object: the pose it starts from and ends on,
+/// timed as its first animation in the play (`at`).
+const Change = struct { obj: u16, at: usize, from: Pose, to: Pose, ease: ?Ease = null };
/// The changes `animations`, played together, make to objects standing in
/// their `settled` poses. `buf` needs two per animation.
fn changes(buf: []Change, settled: []const Pose, animations: []const Animation) []Change {
var n: usize = 0;
- for (animations) |a| switch (a) {
+ for (animations, 0..) |a, at| switch (a) {
.write, .create => |o| {
- const c = touch(buf, &n, settled, o);
+ const c = touch(buf, &n, at, settled, o);
c.from.visible = true;
c.from.drawn = 0;
if (c.from.opacity <= 0) c.from.opacity = 1;
@@ -441,7 +447,7 @@ fn changes(buf: []Change, settled: []const Pose, animations: []const Animation)
c.to.drawn = 1;
},
.fade_in => |o| {
- const c = touch(buf, &n, settled, o);
+ const c = touch(buf, &n, at, settled, o);
c.from.visible = true;
c.from.drawn = 1;
c.from.opacity = 0;
@@ -449,28 +455,28 @@ fn changes(buf: []Change, settled: []const Pose, animations: []const Animation)
c.to.opacity = 1;
},
.fade_out => |o| {
- const c = touch(buf, &n, settled, o);
+ const c = touch(buf, &n, at, settled, o);
c.to.opacity = 0;
c.to.visible = false;
},
.transform => |t| {
- const c = touch(buf, &n, settled, t.from);
+ const c = touch(buf, &n, at, settled, t.from);
c.from.into = @backingInt(t.to);
c.from.morph = 0;
c.to = c.from;
c.to.morph = 1;
c.to.visible = false;
- const d = touch(buf, &n, settled, t.to);
+ const d = touch(buf, &n, at, settled, t.to);
d.from.visible = false;
d.to = d.from;
d.to.visible = true;
d.to.drawn = 1;
d.to.opacity = 1;
},
- .move => |m| m.to.apply(&touch(buf, &n, settled, m.obj).to),
- .rotate => |r| touch(buf, &n, settled, r.obj).to.rotation += r.by,
+ .move => |m| m.to.apply(&touch(buf, &n, at, settled, m.obj).to),
+ .rotate => |r| touch(buf, &n, at, settled, r.obj).to.rotation += r.by,
.indicate => |o| {
- const c = touch(buf, &n, settled, o);
+ const c = touch(buf, &n, at, settled, o);
c.to.scale *= 1.2;
c.to.highlight = 1;
c.ease = ease.thereAndBack;
@@ -480,25 +486,28 @@ fn changes(buf: []Change, settled: []const Pose, animations: []const Animation)
return buf[0..n];
}
-fn touch(buf: []Change, n: *usize, settled: []const Pose, o: Obj) *Change {
+fn touch(buf: []Change, n: *usize, at: usize, settled: []const Pose, o: Obj) *Change {
const i = @backingInt(o);
for (buf[0..n.*]) |*c| if (c.obj == i) return c;
- buf[n.*] = .{ .obj = i, .from = settled[i], .to = settled[i] };
+ buf[n.*] = .{ .obj = i, .at = at, .from = settled[i], .to = settled[i] };
n.* += 1;
return &buf[n.* - 1];
}
-/// Where `animations` leave a camera standing at `view`, if they move it.
-fn aim(view: Camera, animations: []const Animation) ?Camera {
+/// Where `animations` leave a camera standing at `view`, if they move it,
+/// and the first of them that does (`Change.at`).
+fn aim(view: Camera, animations: []const Animation) ?struct { to: Camera, at: usize } {
var out: ?Camera = null;
- for (animations) |a| if (a == .camera) {
+ var first: usize = 0;
+ for (animations, 0..) |a, i| if (a == .camera) {
+ if (out == null) first = i;
var c = out orelse view;
inline for (@typeInfo(CameraTarget).@"struct".field_names) |name| if (@field(a.camera, name)) |v| {
@field(c, name) = v;
};
out = c;
};
- return out;
+ return .{ .to = out orelse return null, .at = first };
}
/// Adding objects, the same for both kinds of scene (anything with `add`).
@@ -685,7 +694,7 @@ pub fn Scene(comptime construct: fn (*Builder) void) type {
var buf: [2 * play.animations.len]Change = undefined;
var touched: [n]bool = @splat(false);
for (changes(&buf, &poses, play.animations)) |c| {
- const k = play.key(Pose, c.from, c.to, c.ease);
+ const k = play.key(Pose, c.at, c.from, c.to, c.ease);
keys[c.obj] = keys[c.obj] ++ .{k};
poses[c.obj] = k.at(k.end);
touched[c.obj] = true;
@@ -698,14 +707,14 @@ pub fn Scene(comptime construct: fn (*Builder) void) type {
poses[f.obj] = k.at(k.end);
touched[f.obj] = true;
};
- for (play.animations) |a| if (a == .value) {
+ for (play.animations, 0..) |a, at| if (a == .value) {
const i = @backingInt(a.value.value);
- value_keys[i] = value_keys[i] ++ .{play.key(f32, values[i], a.value.to, null)};
+ value_keys[i] = value_keys[i] ++ .{play.key(f32, at, values[i], a.value.to, null)};
values[i] = a.value.to;
};
if (aim(view, play.animations)) |to| {
- camera_keys = camera_keys ++ .{play.key(Camera, view, to, null)};
- view = to;
+ camera_keys = camera_keys ++ .{play.key(Camera, to.at, view, to.to, null)};
+ view = to.to;
}
marks = marks ++ .{play.start};
}
@@ -1066,27 +1075,26 @@ pub const Frame = struct {
/// `play`, of animations known at runtime; `buf` holds two changes each.
fn playAll(s: *Frame, all: []const Animation, buf: []Change, p: Play) void {
- const started = s.t >= p.start;
const touched = changes(buf, s.settled.items, all);
for (touched) |c| {
- const k = p.key(Pose, c.from, c.to, c.ease);
+ const k = p.key(Pose, c.at, c.from, c.to, c.ease);
s.settled.items[c.obj] = k.at(k.end);
- if (started) s.shown.items[c.obj] = k.at(s.t);
+ if (s.t >= k.start) s.shown.items[c.obj] = k.at(s.t);
}
// A morph ends where its target settles.
- if (started) for (touched) |c| if (c.from.into != Pose.none) {
+ for (touched) |c| if (c.from.into != Pose.none and s.t >= p.key(Pose, c.at, c.from, c.to, c.ease).start) {
s.morphs.items[c.obj] = .{ .from = c.from, .to = s.settled.items[c.from.into] };
};
- for (all) |a| if (a == .value) {
+ for (all, 0..) |a, at| if (a == .value) {
const v = &s.values.items[@backingInt(a.value.value)];
- const k = p.key(f32, v.settled, a.value.to, null);
+ const k = p.key(f32, at, v.settled, a.value.to, null);
v.settled = a.value.to;
- if (started) v.shown = k.at(s.t);
+ if (s.t >= k.start) v.shown = k.at(s.t);
};
if (aim(s.settled_view, all)) |to| {
- const k = p.key(Camera, s.settled_view, to, null);
- s.settled_view = to;
- if (started) s.view = k.at(s.t);
+ const k = p.key(Camera, to.at, s.settled_view, to.to, null);
+ s.settled_view = to.to;
+ if (s.t >= k.start) s.view = k.at(s.t);
}
s.push(&s.marks, p.start);
s.cursor += p.seconds;
@@ -1976,3 +1984,52 @@ test "a part takes its shapes from its object, stands where they stood and follo
try std.testing.expectEqual(vector.geom.Rect{ .x = -50, .y = -50, .w = 100, .h = 100 }, taken.bounds().rect());
try std.testing.expectEqual(vector.geom.Rect{ .x = -150, .y = -50, .w = 200, .h = 100 }, rest.bounds().rect());
}
+
+/// Four animations a lag of 0.5 apart, then two a whole one apart.
+fn lagScene(s: anytype) void {
+ const a = s.circle(.{ .r = 10 });
+ const b = s.circle(.{ .r = 10, .x = 50 });
+ const c = s.rect(.{ .w = 20, .h = 20, .x = 100 });
+ const k = s.value(0);
+ s.play(.{ a.fadeIn(), b.fadeIn(), camera(.{ .zoom = 2 }), k.to(1) }, .{ .seconds = 2.5, .lag = 0.5 });
+ s.play(.{ b.move(.{ .x = 0 }), a.transformInto(c) }, .{ .lag = 1 });
+}
+
+test "a play's lag starts each animation a fraction of its length after the one before, and the last ends with the play" {
+ var arena: std.heap.ArenaAllocator = .init(std.testing.allocator);
+ defer arena.deinit();
+ const compiled = Scene(struct {
+ fn construct(s: *Builder) void {
+ lagScene(s);
+ }
+ }.construct);
+ const live = Live(struct {
+ fn frame(s: *Frame) void {
+ lagScene(s);
+ }
+ }.frame, struct {});
+ for (0..16) |i| {
+ const t = @as(f32, @floatFromInt(i)) / 4;
+ const x = try compiled.shot(arena.allocator(), .{ .t = t });
+ const y = try live.shot(arena.allocator(), .{ .t = t });
+ try std.testing.expectEqualSlices(Pose, x.poses, y.poses);
+ try std.testing.expectEqualSlices(f32, x.values, y.values);
+ try std.testing.expectEqual(x.camera, y.camera);
+ try std.testing.expectEqual(x.duration, y.duration);
+ try std.testing.expectEqualSlices(f32, x.marks, y.marks);
+ if (x.poses[0].into != Pose.none) try std.testing.expectEqual(x.morphs[0], y.morphs[0]);
+ }
+ // 2.5 s for four, each 1 s long (2.5 / (1 + 3 * 0.5)), 0.5 s apart.
+ try std.testing.expectEqual(@as(f32, 3.5), compiled.duration);
+ try std.testing.expectApproxEqAbs(@as(f32, 0.5), compiled.pose(0, 0.5).opacity, 1e-6);
+ try std.testing.expectEqual(@as(f32, 0), compiled.pose(1, 0.5).opacity);
+ try std.testing.expectApproxEqAbs(@as(f32, 0.5), compiled.pose(1, 1).opacity, 1e-6);
+ try std.testing.expectEqual(@as(f32, 1), compiled.view(1).zoom);
+ try std.testing.expectEqual(@as(f32, 2), compiled.view(2).zoom);
+ try std.testing.expectEqual(@as(f32, 0), compiled.values(1.5)[0]);
+ try std.testing.expectEqual(@as(f32, 1), compiled.values(2.5)[0]);
+ // A lag of 1: one after the other, half the play each.
+ try std.testing.expectApproxEqAbs(@as(f32, 25), compiled.pose(1, 2.75).x, 1e-4);
+ try std.testing.expectEqual(@as(f32, 0), compiled.pose(0, 3).morph);
+ try std.testing.expectApproxEqAbs(@as(f32, 0.5), compiled.pose(0, 3.25).morph, 1e-6);
+}