summaryrefslogtreecommitdiff
path: root/anim/src/cursor.zig
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-10 14:48:26 -0300
committerGabriel Schneider <[email protected]>2026-11-10 15:14:31 -0300
commit7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch)
treea6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/src/cursor.zig
parented46c51fe127377eb1fde8dee83da984e0f61860 (diff)
downloadcomputeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz
computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip
canim: animations of recordings, as a debugger's whole context with a lens beside it
A package of its own (anim/), on sketchbook's anim module and pardes's syntax. A scene opens a recording, takes a cursor into it, and declares blocks that read the moment the cursor is at: the state column (registers each followed as a pointer and inked by where it points, the stack telescope, the backtrace), the program column (the whole source, the disassembly in address order, and the scene's lens: a node-link list over a hexdump of its heap, array cells, a call tree, a syscall crossing), and ties between them. Motion is a step told as a sentence (the line fires, its effects cascade a level at a time, the mark moves on last), timed by what the step contains; walk, hurry and sprint pace a loop. Five scenes from real recordings of fib, a linked list, a sort and syscalls. First drafts, by the agent's own handover: the frame of the design's second revision, the hexdump lens and the ties; no disassembly annotations, no gallery, scenes not yet reviewed against the mocks.
Diffstat (limited to 'anim/src/cursor.zig')
-rw-r--r--anim/src/cursor.zig638
1 files changed, 638 insertions, 0 deletions
diff --git a/anim/src/cursor.zig b/anim/src/cursor.zig
new file mode 100644
index 0000000..2ca8a97
--- /dev/null
+++ b/anim/src/cursor.zig
@@ -0,0 +1,638 @@
+//! The cursor: where in the recording the picture is, as numbers on the
+//! scene's timeline. It moves in steps, each from one moment straight to a
+//! later one (the next instruction, the next source line, the line after a
+//! call returns, the next syscall: `Recording.Stop`), and remembers the
+//! last few places it stopped.
+//!
+//! A step is a sentence (design/motion.md): the line about to run fires;
+//! what it did lands a level at a time, the CPU, then memory, then the idea
+//! drawn from them, each armed and then struck; it is held to be read; and
+//! last the current mark moves on. The cursor writes that timetable (a
+//! `Plan`) for each step from what the step changed, so a walk has the
+//! program's rhythm and not a clock's, and every component reads it
+//! (`Cursor.now`) with no state of its own.
+const std = @import("std");
+const anim = @import("anim");
+const zt = @import("ztrace");
+const Recording = @import("Recording.zig");
+const ui = @import("ui.zig");
+const theme = ui.theme;
+const time = theme.time;
+
+/// A mark lasts this many steps, then one more to leave in.
+const history = time.strike.ember_steps + 2;
+
+/// Slow in and slow out, for things with weight: a value in flight, a
+/// layout, a colour cooling. Quickest at the middle.
+pub fn glide(t: f32) f32 {
+ return theme.ease(.glide, t);
+}
+
+/// For things that answer the program (the mark, cards, tags, an arrow
+/// growing): off promptly, a long settle.
+pub fn standard(t: f32) f32 {
+ return theme.ease(.standard, t);
+}
+
+/// The levels a step's effects land on, in the order they are caused.
+pub const Level = enum(u2) { cpu, memory, idea };
+
+/// What is on screen for the cursor to time a step by. A level the scene
+/// does not show gives up its place in the cascade.
+pub const Levels = struct {
+ cpu: bool = true,
+ memory: bool = true,
+ /// The idea drawn from them, when one is shown: the calls (cards, a
+ /// tree), or the data (nodes, an array's cells).
+ idea: enum { none, calls, data } = .none,
+ /// Follow-through: seconds the data's view goes on moving after its
+ /// strike (an arrow redrawn, a tag sliding), before the hold begins.
+ follow: f32 = 0,
+ /// Where a step fires: on the source line, or (a scene that steps by
+ /// instruction) on the pc's row of the disassembly. One place: two
+ /// views of the same thing start together, and only one of them pulses.
+ fire: enum { source, disasm } = .source,
+ /// How many lines the source panel shows (the split's): a step that
+ /// takes the program out of its window has the window's glide to wait for.
+ source_rows: u32 = 12,
+};
+
+/// How a step is drawn. Walk: everything, as a sentence. Run: the mark and
+/// structures eased, values as embers. Sprint: structures grow, embers.
+pub const Gait = enum(u2) { walk, run, sprint };
+
+/// A step's timetable, in seconds from its first frame.
+pub const Plan = struct {
+ gait: Gait = .walk,
+ /// When each level strikes (`Level` is the index).
+ at: [3]f32 = @splat(time.cascade),
+ /// When the mark sets off for the next line, and how long it takes.
+ advance: f32 = time.fire,
+ travel: f32 = time.step,
+ /// The whole step: the advance, then a rest in which the next line is read.
+ total: f32 = time.fire + time.step + time.rest,
+
+ /// Once the pattern is known: the levels a stagger apart from the
+ /// first frame, the mark after them, in `seconds`.
+ pub fn running(seconds: f32) Plan {
+ return .{ .gait = .run, .at = .{ 0, time.stagger, 2 * time.stagger }, .advance = time.run_ease, .travel = time.run_ease, .total = seconds };
+ }
+
+ pub fn sprinting(seconds: f32) Plan {
+ return .{ .gait = .sprint, .at = @splat(0), .advance = 0, .travel = 0, .total = seconds };
+ }
+};
+
+/// Registers whose change is no value to read: where execution is, and the flags.
+const quiet: u32 = blk: {
+ var mask: u32 = 0;
+ for (zt.Regs.names, 0..) |name, i| {
+ if (std.mem.eql(u8, name, "rip") or std.mem.eql(u8, name, "eflags")) mask |= 1 << i;
+ }
+ break :blk mask;
+};
+
+pub const Cursor = struct {
+ rec: *Recording,
+ /// Where it is (or is arriving), where it came from, and before that.
+ stops: [history]anim.Value,
+ /// 0 to 1 through the step it is taking; 1 at rest.
+ phase: anim.Value,
+ /// The step's `Plan`, a value a field.
+ plan: [7]anim.Value,
+ /// The moment the current mark was on, and the one it is on (or going to).
+ marks: [2]anim.Value,
+ /// 1 while steps are hurried (the head counts them), and while what
+ /// cannot be read at that pace is veiled.
+ hurried: anim.Value,
+ veil: anim.Value,
+ /// Steps taken.
+ count: anim.Value,
+ /// The levels the scene shows: set before the first step.
+ levels: Levels = .{},
+ /// The scene's whole way, for the head's progress line and counter (`journey`).
+ first: u64,
+ last: u64,
+ of: u32 = 0,
+
+ /// A cursor at rest at moment `start`.
+ pub fn init(s: *anim.Frame, rec: *Recording, start: u64) Cursor {
+ const here: f32 = @floatFromInt(start);
+ const plan: Plan = .{};
+ var c: Cursor = .{
+ .rec = rec,
+ .stops = undefined,
+ .phase = s.value(1),
+ .plan = .{ s.value(0), s.value(plan.at[0]), s.value(plan.at[1]), s.value(plan.at[2]), s.value(plan.advance), s.value(plan.travel), s.value(plan.total) },
+ .marks = .{ s.value(here), s.value(here) },
+ .hurried = s.value(0),
+ .veil = s.value(0),
+ .count = s.value(0),
+ .first = start,
+ .last = start,
+ };
+ // shortcut: an f32 holds whole moments up to 16 million; a longer recording needs two values a stop.
+ for (&c.stops) |*stop| stop.* = s.value(here);
+ return c;
+ }
+
+ /// Where the timeline has taken the cursor so far: for scene code that
+ /// finds the next place from the last.
+ pub fn moment(c: Cursor, s: *const anim.Frame) u64 {
+ return @intFromFloat(settled(s, c.stops[0]));
+ }
+
+ /// Tells the cursor how far the scene will take it, in steps of `by`:
+ /// what the head's progress line and step counter are measured against.
+ pub fn journey(c: *Cursor, by: Recording.Stop, until: u64) void {
+ c.last = until;
+ c.of = c.steps(by, c.first, until);
+ }
+
+ /// How many steps of `by` from `from` to `until`.
+ pub fn steps(c: Cursor, by: Recording.Stop, from: u64, until: u64) u32 {
+ var n: u32 = 0;
+ var here = from;
+ while (here < until) : (n += 1) here = @min(c.rec.next(by, here), until);
+ return n;
+ }
+
+ /// One step, straight to moment `to`, drawn as `plan` says and played
+ /// in `seconds` (a plan played in less than its `total` is the same
+ /// sentence said faster).
+ pub fn step(c: Cursor, s: *anim.Frame, to: u64, plan: Plan, seconds: f32) void {
+ const from = c.moment(s);
+ var set: [history + 11]anim.Animation = undefined;
+ for (1..history) |i| set[i] = c.stops[i].to(settled(s, c.stops[i - 1]));
+ set[0] = c.stops[0].to(@floatFromInt(to));
+ for (c.plan, [_]f32{ @floatFromInt(@intFromEnum(plan.gait)), plan.at[0], plan.at[1], plan.at[2], plan.advance, plan.travel, plan.total }, history..) |value, is, n| set[n] = value.to(is);
+ // At a sprint the mark is seen only where a phrase ends.
+ const was = settled(s, c.marks[1]);
+ set[history + 7] = c.marks[0].to(was);
+ set[history + 8] = c.marks[1].to(if (plan.gait == .sprint and !c.phraseEnds(from, to)) was else @floatFromInt(to));
+ set[history + 9] = c.phase.to(0);
+ set[history + 10] = c.count.to(settled(s, c.count) + 1);
+ s.play(set, .{ .seconds = 0 });
+ s.play(.{c.phase.to(1)}, .{ .seconds = seconds, .ease = anim.ease.linear });
+ }
+
+ /// Steps of `by` up to moment `until`, each shown in full and as long
+ /// as what it changed takes to read (`reading`), with a beat's rest
+ /// where a phrase ends. For the first time anything happens, and
+ /// whatever the narration names.
+ pub fn walk(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64) void {
+ var here = c.moment(s);
+ while (here < until) {
+ const next = @min(c.rec.next(by, here), until);
+ const plan = c.reading(here, next);
+ c.step(s, next, plan, plan.total);
+ if (c.phraseEnds(here, next)) s.wait(time.phrase_rest);
+ here = next;
+ }
+ }
+
+ /// Timing: the timetable a walked step from `from` to `to` deserves.
+ /// Fire; a slot of the cascade for each level it touched; the idea's
+ /// follow-through; a hold as long as the values take to read; the
+ /// advance; a rest. A line and no more comes to 0.8 s, one value to
+ /// 1.5, a register and memory to 2.0, a call through three levels 2.5.
+ pub fn reading(c: Cursor, from: u64, to: u64) Plan {
+ const rec = c.rec;
+ const regs: f32 = @floatFromInt(@popCount(rec.registersChanged(from, to) & ~quiet));
+ const wrote: f32 = @floatFromInt(rec.written(from, to).len);
+ const touched = wrote > 0 or rec.read(from, to).len > 0;
+ const deeper = rec.depths[to] > rec.depths[from];
+ const back = rec.depths[to] < rec.depths[from];
+ const levels = [3]bool{
+ c.levels.cpu and regs > 0,
+ c.levels.memory and touched,
+ switch (c.levels.idea) {
+ .none => false,
+ .calls => deeper or back,
+ .data => touched,
+ },
+ };
+ var plan: Plan = .{ .travel = c.travel(from, to) };
+ var slot: f32 = 0;
+ for (levels, &plan.at) |is, *strikes| {
+ if (is) slot += time.cascade;
+ strikes.* = @max(slot, time.cascade);
+ }
+ if (slot > 0) {
+ // What there is to read: a level's worth each. (In the whole
+ // context a line changes more registers than anyone reads;
+ // the hold is for the one the scene is about.)
+ var values: f32 = 0;
+ for (levels) |is| values += @floatFromInt(@intFromBool(is));
+ // A card leaves after its result is read; an arrow lands after its word strikes.
+ const follow: f32 = if (!levels[2]) 0 else switch (c.levels.idea) {
+ .none => 0,
+ .calls => if (back) time.returning else time.snap,
+ .data => c.levels.follow,
+ };
+ plan.advance = slot + follow + @min(time.read_value + time.read_more * (values - 1), time.read_most);
+ }
+ plan.total = plan.advance + plan.travel + time.rest;
+ return plan;
+ }
+
+ /// How long the mark takes to the next line: a slide by how far, or a
+ /// jump (out, then in) into or out of a call, or further than a few rows.
+ fn travel(c: Cursor, from: u64, to: u64) f32 {
+ const rec = c.rec;
+ // The source's window moves with it: by whole lines, and never a cut.
+ if (rec.viewFirst(c.levels.source_rows, rec.own[from]) != rec.viewFirst(c.levels.source_rows, rec.own[to])) return time.move;
+ if (jumps(rec, from, to)) return 2 * time.current_jump;
+ const rows: f32 = @floatFromInt(@max(rec.own[from], rec.own[to]) - @min(rec.own[from], rec.own[to]));
+ return @min(time.step + time.step_per_row * @max(rows - 1, 0), time.step_max);
+ }
+
+ /// A phrase ends where a call returns, or a loop comes round again.
+ pub fn phraseEnds(c: Cursor, from: u64, to: u64) bool {
+ const rec = c.rec;
+ return rec.depths[to] < rec.depths[from] or (rec.depths[to] == rec.depths[from] and rec.own[to] < rec.own[from]);
+ }
+
+ pub const Hurry = struct {
+ /// Seconds a step, once up to speed: `time.run`, or `time.sprint`.
+ pace: f32 = time.run,
+ /// What the pace was before, and is to be after.
+ from: f32 = time.walk,
+ to: f32 = time.walk,
+ /// Veil what cannot be read at that pace (null: at a sprint).
+ veil: ?bool = null,
+ /// Lift the veil and rest a beat afterwards: not when another
+ /// stretch at another pace follows at once.
+ settle: bool = true,
+ };
+
+ /// Pacing: steps of `by` up to `until`, hurried, for a pattern already
+ /// seen in full. A change of pace is never a switch: each step is
+ /// `time.ramp` of the one before on the way down from `from`, and on
+ /// the way back up to `to`, and then the picture is still for a beat.
+ /// A step with time enough is still a whole sentence, said faster;
+ /// shorter, it is a run (the mark and structures eased, values as
+ /// embers), with a short rest where a phrase ends; shorter still, a
+ /// sprint. The head counts the steps while it lasts.
+ pub fn hurry(c: Cursor, s: *anim.Frame, by: Recording.Stop, until: u64, options: Hurry) void {
+ var here = c.moment(s);
+ const n: f32 = @floatFromInt(c.steps(by, here, until));
+ if (n == 0) return;
+ // Anticipation: the veil and the counter come with the first shortened step.
+ const veiled = options.veil orelse (options.pace < time.run);
+ const start = s.cursor;
+ s.play(.{ c.hurried.to(1), c.veil.to(if (veiled) 1 else 0) }, .{ .seconds = time.veil, .ease = anim.ease.linear });
+ s.cursor = start;
+ var k: f32 = 0;
+ while (here < until) : (k += 1) {
+ const next = @min(c.rec.next(by, here), until);
+ const natural = c.reading(here, next);
+ const down = options.from * std.math.pow(f32, time.ramp, k + 1);
+ const up = options.to * std.math.pow(f32, time.ramp, n - k);
+ // Whole frames, at 30 a second as at 60.
+ const seconds = @round(@min(natural.total, @max(options.pace, @min(down, up))) * 30) / 30;
+ const plan: Plan = if (seconds >= time.walk_least) natural else if (seconds > 1.5 * time.sprint) .running(seconds) else .sprinting(seconds);
+ c.step(s, next, plan, seconds);
+ if (plan.gait != .sprint and c.phraseEnds(here, next)) s.wait(time.phrase_rest_running);
+ here = next;
+ }
+ if (!options.settle) return;
+ s.play(.{ c.hurried.to(0), c.veil.to(0) }, .{ .seconds = time.veil, .ease = anim.ease.linear });
+ s.wait(time.beat);
+ }
+
+ /// There at once, with nothing struck: a cut.
+ pub fn jump(c: Cursor, s: *anim.Frame, to: u64) void {
+ var all: [history + 3]anim.Animation = undefined;
+ for (c.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(to));
+ all[history] = c.phase.to(1);
+ all[history + 1] = c.marks[0].to(@floatFromInt(to));
+ all[history + 2] = c.marks[1].to(@floatFromInt(to));
+ s.play(all, .{ .seconds = 0 });
+ }
+
+ /// For a component, while it draws.
+ pub fn now(c: Cursor, placed: anim.Placed) Now {
+ const rec = c.rec;
+ var n: Now = .{
+ .rec = rec,
+ .stops = undefined,
+ .time = std.math.inf(f32),
+ .plan = .{
+ .gait = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(c.plan[0])), 0, 2)))),
+ .at = .{ placed.value(c.plan[1]), placed.value(c.plan[2]), placed.value(c.plan[3]) },
+ .advance = placed.value(c.plan[4]),
+ .travel = placed.value(c.plan[5]),
+ .total = placed.value(c.plan[6]),
+ },
+ .marks = .{ whole(rec, placed.value(c.marks[0])), whole(rec, placed.value(c.marks[1])) },
+ .hurried = placed.value(c.hurried),
+ .veil = placed.value(c.veil),
+ .count = @intFromFloat(@max(placed.value(c.count), 0)),
+ .of = c.of,
+ .place = 0,
+ .fired = c.levels.fire,
+ .way = .{ c.first, c.last },
+ };
+ for (&n.stops, c.stops) |*stop_at, v| stop_at.* = whole(rec, placed.value(v));
+ const phase = placed.value(c.phase);
+ if (phase < 1) n.time = phase * n.plan.total;
+ if (c.last > c.first) {
+ // Linear: time itself.
+ const here = std.math.lerp(@as(f32, @floatFromInt(n.stops[1])), @as(f32, @floatFromInt(n.stops[0])), std.math.clamp(phase, 0, 1));
+ n.place = std.math.clamp((here - @as(f32, @floatFromInt(c.first))) / @as(f32, @floatFromInt(c.last - c.first)), 0, 1);
+ }
+ return n;
+ }
+};
+
+fn whole(rec: *const Recording, value: f32) u64 {
+ return @min(@as(u64, @intFromFloat(@max(value, 0))), rec.end());
+}
+
+fn settled(s: *const anim.Frame, v: anim.Value) f32 {
+ return s.values.items[@backingInt(v)].settled;
+}
+
+/// Whether the mark jumps from the line of moment `from` to that of `to`
+/// (fades out there and in here) and does not slide: a call is not a
+/// journey across the lines between.
+pub fn jumps(rec: *const Recording, from: u64, to: u64) bool {
+ const rows = @max(rec.own[from], rec.own[to]) - @min(rec.own[from], rec.own[to]);
+ return rec.depths[from] != rec.depths[to] or rows > time.current_jump_rows;
+}
+
+/// The cursor at one instant.
+pub const Now = struct {
+ rec: *const Recording,
+ /// `stops[0]` is the moment shown, `stops[1]` where the step came
+ /// from: the step is every moment after it up to the one shown.
+ stops: [history]u64,
+ /// Seconds into the step's plan; infinite at rest.
+ time: f32,
+ plan: Plan,
+ /// The moment whose line the current mark is leaving, and the one it goes to.
+ marks: [2]u64,
+ /// 0 to 1: steps are hurried; what cannot be read is veiled.
+ hurried: f32,
+ veil: f32,
+ /// Steps taken, of how many in the scene (0: not told).
+ count: u32,
+ of: u32,
+ /// 0 to 1 along the scene's way through the recording.
+ place: f32,
+ /// Where the scene's steps fire (`Levels.fire`).
+ fired: @FieldType(Levels, "fire") = .source,
+ /// The scene's way through the recording: its first moment and its last.
+ way: [2]u64 = .{ 0, 0 },
+
+ /// The program's state as shown.
+ pub fn moment(n: Now) Recording.Moment {
+ return n.rec.moment(n.stops[0]);
+ }
+
+ /// Its state before this step.
+ pub fn before(n: Now) Recording.Moment {
+ return n.rec.moment(n.stops[1]);
+ }
+
+ pub fn resting(n: Now) bool {
+ return std.math.isInf(n.time);
+ }
+
+ /// A step shown in full: fire, arm, strike, hold.
+ pub fn walking(n: Now) bool {
+ return n.plan.gait == .walk and !n.resting();
+ }
+
+ /// Seconds since `level` struck, for the one of several that strikes
+ /// `delay` after the first: negative before, infinite at rest.
+ pub fn since(n: Now, level: Level, delay: f32) f32 {
+ return n.time - n.plan.at[@intFromEnum(level)] - delay;
+ }
+
+ /// Whether `level`'s changes show yet: until then a component draws
+ /// the state before the step. The digits change as the fill comes in.
+ pub fn landed(n: Now, level: Level, delay: f32) bool {
+ return n.since(level, delay) >= time.strike.in / 2.0;
+ }
+
+ /// The state to draw for `level`.
+ pub fn shown(n: Now, level: Level) Recording.Moment {
+ return if (n.landed(level, 0)) n.moment() else n.before();
+ }
+
+ /// The moment to ask the recording's index about, for `level`.
+ pub fn stop(n: Now, level: Level) u64 {
+ return if (n.landed(level, 0)) n.stops[0] else n.stops[1];
+ }
+
+ /// How far (0 to 1, to be eased) a thing has got that moves as `level`
+ /// strikes: it sets off `lead` seconds before the strike and takes
+ /// `seconds`. At a run it sets off with its level and takes
+ /// `time.run_ease`; at a sprint, and at rest, it is there.
+ pub fn moving(n: Now, level: Level, lead: f32, seconds: f32) f32 {
+ return switch (n.plan.gait) {
+ .walk => std.math.clamp((n.since(level, 0) + lead) / seconds, 0, 1),
+ .run => std.math.clamp(n.since(level, 0) / time.run_ease, 0, 1),
+ .sprint => 1,
+ };
+ }
+
+ /// The fire: how far out (in units) the edges of the mark's plaque
+ /// are, on the line about to run. The step's first beat, alone.
+ pub fn fire(n: Now) f32 {
+ return if (n.walking() and n.time < time.fire) theme.pulse(n.time / time.fire) else 0;
+ }
+
+ /// The same for the view the scene fires in, 0 for the other.
+ pub fn fires(n: Now, in: @FieldType(Levels, "fire")) f32 {
+ return if (n.fired == in) n.fire() else 0;
+ }
+
+ /// 0 to 1 (to be eased) through the mark's move to the next line: the
+ /// step's follow-through, and the next step's anticipation.
+ pub fn advancing(n: Now) f32 {
+ return n.advancingAfter(0);
+ }
+
+ /// The same for another view of where execution is (the pc's row, the
+ /// value of rip), which follows the source's mark `delay` seconds
+ /// behind: three panels do not start on one frame.
+ pub fn advancingAfter(n: Now, delay: f32) f32 {
+ if (n.resting() or n.plan.travel <= 0) return 1;
+ return std.math.clamp((n.time - n.plan.advance - delay) / @max(n.plan.travel - delay, 1.0 / 60.0), 0, 1);
+ }
+
+ /// The moment the current mark stands for: the step's own line until
+ /// the mark has left it.
+ pub fn marked(n: Now) u64 {
+ return if (n.advancing() >= 0.5) n.marks[1] else n.marks[0];
+ }
+
+ /// How many steps ago (0: in this one) the bytes `addr .. addr + size`
+ /// last changed; null when longer ago than a mark lasts.
+ pub fn writeAge(n: Now, addr: u64, size: u64) ?u64 {
+ return n.writeAgeFrom(addr, size, 0);
+ }
+
+ /// The same, not counting the `skip` newest steps.
+ fn writeAgeFrom(n: Now, addr: u64, size: u64, skip: usize) ?u64 {
+ for (skip..history - 1) |age| {
+ if (Recording.touches(n.rec.written(n.stops[age + 1], n.stops[age]), addr, size)) return age;
+ }
+ return null;
+ }
+
+ /// The same for a register, by its place in `Regs.names`.
+ pub fn registerAge(n: Now, reg: usize) ?u64 {
+ return n.registerAgeFrom(reg, 0);
+ }
+
+ fn registerAgeFrom(n: Now, reg: usize, skip: usize) ?u64 {
+ for (skip..history - 1) |age| {
+ if (n.rec.registersChanged(n.stops[age + 1], n.stops[age]) >> @intCast(reg) & 1 != 0) return age;
+ }
+ return null;
+ }
+
+ /// Whether this step read any of `addr .. addr + size`.
+ pub fn wasRead(n: Now, addr: u64, size: u64) bool {
+ return Recording.touches(n.rec.read(n.stops[1], n.stops[0]), addr, size);
+ }
+
+ /// How far into the run of bytes this step wrote `addr` is: bytes of
+ /// one write strike a frame apart, low address first.
+ pub fn writeOffset(n: Now, addr: u64) u64 {
+ for (n.rec.written(n.stops[1], n.stops[0])) |span| {
+ if (addr >= span.addr and addr < span.addr + span.len) return addr - span.addr;
+ }
+ return 0;
+ }
+
+ /// What a step `age` steps ago left on a thing it wrote: an ember for
+ /// three steps, leaving in the one after.
+ fn left(n: Now, age: ?u64) ui.Heat {
+ const s = time.strike;
+ const a = age orelse return .none;
+ if (a == 0 or a > s.ember_steps) return .none;
+ if (a < s.ember_steps) return .ember;
+ // Linear: a fade. Gone by the time this step is over.
+ return .{ .level = 1 - std.math.clamp(n.time / s.out, 0, 1) };
+ }
+
+ /// The mark of a thing last changed `age` steps ago (`older`: not
+ /// counting this step), whose strike came `since_strike` seconds ago.
+ /// Anticipation: armed first, a frame round the old value. Then the
+ /// strike: the fill comes in (never in one frame) with a pulse of its
+ /// edges, the one exaggeration there is. Held solid while the line
+ /// that did it is still gold; cooled as the mark leaves.
+ pub fn heat(n: Now, age: ?u64, older: ?u64, since_strike: f32) ui.Heat {
+ const s = time.strike;
+ if (age != 0) return n.left(age);
+ const was = n.left(older);
+ switch (n.plan.gait) {
+ // Faster than a strike can be seen: embers only.
+ .sprint => return .ember,
+ .run => return if (was.level >= 1 or n.resting()) .ember else .{ .level = std.math.clamp(since_strike / time.snap, 0, 1) },
+ .walk => {},
+ }
+ if (n.resting()) return .ember;
+ if (since_strike < 0) {
+ var armed = was;
+ if (since_strike >= -s.arm) armed.arm = std.math.clamp((since_strike + s.arm) / time.stagger, 0, 1);
+ return armed;
+ }
+ return .{
+ .level = 1,
+ .solid = 1 - glide(std.math.clamp((n.time - n.plan.advance) / s.cool, 0, 1)),
+ .in = std.math.clamp(since_strike / s.in, 0, 1),
+ .from = if (was.level >= 1) .ember else .nothing,
+ .out = if (since_strike < s.pulse) theme.pulse(since_strike / s.pulse) else 0,
+ };
+ }
+
+ /// The mark of the bytes `addr .. addr + size`, which strike with
+ /// `level`, `delay` seconds after its first.
+ pub fn written(n: Now, addr: u64, size: u64, level: Level, delay: f32) ui.Heat {
+ return n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), n.since(level, delay));
+ }
+
+ /// The mark of a register: the CPU's level.
+ pub fn register(n: Now, reg: usize, delay: f32) ui.Heat {
+ return n.heat(n.registerAge(reg), n.registerAgeFrom(reg, 1), n.since(.cpu, delay));
+ }
+
+ /// How much (0 to 1) the frame round a thing this step read shows: in
+ /// with its level, never armed or pulsed, held while the line is
+ /// gold, and out as the mark leaves, gone before the next line fires.
+ pub fn reading(n: Now, level: Level, delay: f32) f32 {
+ return switch (n.plan.gait) {
+ .walk => n.held(n.plan.at[@intFromEnum(level)] + delay),
+ .run => if (n.resting()) 0 else @min(std.math.clamp(n.since(level, 0) / time.stagger, 0, 1), std.math.clamp((n.plan.total - n.time) / time.snap, 0, 1)),
+ .sprint => 0,
+ };
+ }
+
+ /// The same for a frame that comes in `from` seconds into a walked step.
+ pub fn held(n: Now, from: f32) f32 {
+ const r = time.read;
+ if (!n.walking()) return 0;
+ return @min(std.math.clamp((n.time - from) / r.in, 0, 1), 1 - std.math.clamp((n.time - n.plan.advance) / r.out, 0, 1));
+ }
+};
+
+fn instant(seconds: f32, plan: Plan) Now {
+ return .{ .rec = undefined, .stops = undefined, .time = seconds, .plan = plan, .marks = undefined, .hurried = 0, .veil = 0, .count = 0, .of = 0, .place = 0 };
+}
+
+test "a write is armed, strikes, holds, cools with the advance, and leaves after three steps" {
+ const s = time.strike;
+ const expect = std.testing.expect;
+ const expectEqual = std.testing.expectEqual;
+ // One register written: struck at 0.30, the mark leaves at 0.90.
+ const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 };
+ // Armed: a frame, and no fill yet.
+ var h = instant(0.20, plan).heat(0, null, 0.20 - 0.30);
+ try expect(h.arm == 1 and h.level == 0);
+ // Not before its arm.
+ try expectEqual(ui.Heat.none, instant(0.05, plan).heat(0, null, 0.05 - 0.30));
+ // Struck: the fill half in, the edges out.
+ h = instant(0.35, plan).heat(0, null, 0.05);
+ try expect(h.level == 1 and h.solid == 1 and @abs(h.in - 0.5) < 1e-3 and h.out > 2 and h.arm == 0);
+ // Held solid until the mark leaves, then cooled, halfway at the middle.
+ h = instant(0.89, plan).heat(0, null, 0.59);
+ try expect(h.solid == 1 and h.in == 1 and h.out == 0);
+ h = instant(0.90 + s.cool / 2.0, plan).heat(0, null, 0.8);
+ try std.testing.expectApproxEqAbs(@as(f32, 0.5), h.solid, 1e-3);
+ // At rest, and for the steps after: the ember; then it goes.
+ const rest = instant(std.math.inf(f32), plan);
+ try expectEqual(ui.Heat.ember, rest.heat(0, null, std.math.inf(f32)));
+ try expectEqual(ui.Heat.ember, rest.heat(2, 2, 0));
+ try expectEqual(ui.Heat.none, rest.heat(4, 4, 0));
+ try expectEqual(ui.Heat.none, rest.heat(null, null, 0));
+ try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(s.out / 2.0, plan).heat(s.ember_steps, s.ember_steps, 0).level, 1e-3);
+ // Struck again over its ember: armed with the ember still under it.
+ h = instant(0.20, plan).heat(0, 1, -0.10);
+ try expect(h.level == 1 and h.arm == 1 and h.solid == 0);
+ // Running: an ember and no more. Sprinting: the same, at once.
+ try expect(instant(0.2, Plan.running(0.3)).heat(0, null, 0.2).solid == 0);
+ try expectEqual(ui.Heat.ember, instant(0.01, Plan.sprinting(0.05)).heat(0, null, 0.01));
+}
+
+test "what a step read is framed while its line is gold" {
+ const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .total = 1.50 };
+ try std.testing.expectEqual(@as(f32, 0), instant(0.2, plan).reading(.memory, 0));
+ try std.testing.expectEqual(@as(f32, 1), instant(0.6, plan).reading(.memory, 0));
+ try std.testing.expectEqual(@as(f32, 0), instant(0.9 + time.read.out, plan).reading(.memory, 0));
+ try std.testing.expectEqual(@as(f32, 0), instant(std.math.inf(f32), plan).reading(.memory, 0));
+}
+
+test "the mark fires first and moves last" {
+ const plan: Plan = .{ .at = @splat(0.30), .advance = 0.90, .travel = 0.20, .total = 1.50 };
+ try std.testing.expect(instant(0.10, plan).fire() > 3.9);
+ try std.testing.expectEqual(@as(f32, 0), instant(0.30, plan).fire());
+ try std.testing.expectEqual(@as(f32, 0), instant(0.89, plan).advancing());
+ try std.testing.expectEqual(@as(f32, 1), instant(1.10, plan).advancing());
+ try std.testing.expectEqual(@as(f32, 1), instant(std.math.inf(f32), plan).advancing());
+}