//! 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 syscalls = @import("syscalls.zig"); const theme = ui.theme; const time = theme.time; /// The writes of one step strike this far apart, in the order they happened. pub const write_apart = 6.0 / 60.0; /// 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, /// A step that makes one syscall is drawn as its crossing (the context /// sets it, `Context.Options.syscalls`): what the step changed in the /// registers strikes once the call is back. crossings: bool = false, }; /// 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, /// A `continue`: the registers strike in a wave, no arm and no pulse. wave: bool = false, /// The line fires (not on a step that goes on from the last one's /// mark: a crossing stepped over, from its call row). fires: bool = true, /// 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. pub 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, /// The pace each of those steps was taken at (`Gait`): what a run /// changed is not marked, then or after. gaits: [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: [9]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, /// The veil over what a sprint also cannot show: the source and the band's view. sprint_veil: anim.Value, /// Steps taken. count: anim.Value, /// The same values a little behind (`time.minimap_lag`, then a frame /// later each, `time.minimap_fade` of them): what the minimap draws /// from, secondary action that never starts on a primary onset's frame /// and fades over those frames. lags: [time.minimap_fade]Lagged, /// 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, .gaits = 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), s.value(0), s.value(1) }, .marks = .{ s.value(here), s.value(here) }, .hurried = s.value(0), .veil = s.value(0), .sprint_veil = s.value(0), .count = s.value(0), .lags = undefined, .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); for (&c.gaits) |*gait| gait.* = s.value(0); for (&c.lags) |*lag| inline for (@typeInfo(Lagged).@"struct".field_names) |name| { const from = @field(c, name); if (@TypeOf(from) == anim.Value) { @field(lag, name) = s.value(s.get(from)); } else for (&@field(lag, name), from) |*to, one| { to.* = s.value(s.get(one)); } }; return c; } /// The cursor's animated values, mirrored for the minimap. pub const Lagged = struct { stops: [history]anim.Value, gaits: [history]anim.Value, phase: anim.Value, plan: [9]anim.Value, marks: [2]anim.Value, hurried: anim.Value, veil: anim.Value, sprint_veil: anim.Value, count: anim.Value, }; /// Plays `plays(values)` on the cursor's values from here, and on their /// lagging mirrors `time.minimap_lag` later and a frame apart; the cursor ends where the first left it. fn both(c: Cursor, s: *anim.Frame, plays: anytype) void { const start = s.cursor; for (0..c.lags.len) |k| { s.cursor = start + time.minimap_lag + @as(f32, @floatFromInt(k)) / 60.0; plays.run(s, lagged(c, k)); } s.cursor = start; plays.run(s, c); } /// `c` with its `k`th lagging values in place of its own. fn lagged(c: Cursor, k: usize) Cursor { var out = c; inline for (@typeInfo(Lagged).@"struct".field_names) |name| @field(out, name) = @field(c.lags[k], name); return out; } /// `values` (a frame's every value, a copy) with the cursor's own as its /// `k`th lagging mirror has them: what the minimap's `k`th drawing reads. /// Returns whether they differ from the mirror before's (a drawing to make, not one to reuse). pub fn lagInto(c: Cursor, values: []f32, k: usize) bool { var differs = k == 0; inline for (@typeInfo(Lagged).@"struct".field_names) |name| { const own = @field(c, name); const mirror = @field(c.lags[k], name); const before = @field(c.lags[k -| 1], name); if (@TypeOf(own) == anim.Value) { values[@backingInt(own)] = values[@backingInt(mirror)]; differs = differs or values[@backingInt(mirror)] != values[@backingInt(before)]; } else for (own, mirror, before) |o, mv, b| { values[@backingInt(o)] = values[@backingInt(mv)]; differs = differs or values[@backingInt(mv)] != values[@backingInt(b)]; } } return differs; } /// 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); // Where each value goes, from the cursor's own (the mirror goes the same way, later). const Step = struct { stops: [history]f32, gaits: [history]f32, plan: [9]f32, marks: [2]f32, count: f32, seconds: f32, fn run(st: @This(), sf: *anim.Frame, v: Cursor) void { var set: [2 * history + 13]anim.Animation = undefined; for (v.stops, st.stops, 0..) |value, is, i| set[i] = value.to(is); for (v.gaits, st.gaits, 0..) |value, is, i| set[history + 13 + i] = value.to(is); for (v.plan, st.plan, history..) |value, is, n| set[n] = value.to(is); set[history + 9] = v.marks[0].to(st.marks[0]); set[history + 10] = v.marks[1].to(st.marks[1]); set[history + 11] = v.phase.to(0); set[history + 12] = v.count.to(st.count); sf.play(set, .{ .seconds = 0 }); sf.play(.{v.phase.to(1)}, .{ .seconds = st.seconds, .ease = anim.ease.linear }); } }; var st: Step = .{ .stops = undefined, .gaits = undefined, .plan = .{ @floatFromInt(@intFromEnum(plan.gait)), plan.at[0], plan.at[1], plan.at[2], plan.advance, plan.travel, plan.total, @floatFromInt(@intFromBool(plan.wave)), @floatFromInt(@intFromBool(plan.fires)) }, .marks = undefined, .count = settled(s, c.count) + 1, .seconds = seconds }; st.stops[0] = @floatFromInt(to); for (1..history) |i| st.stops[i] = settled(s, c.stops[i - 1]); st.gaits[0] = @floatFromInt(@intFromEnum(plan.gait)); for (1..history) |i| st.gaits[i] = settled(s, c.gaits[i - 1]); // At a sprint the mark is seen only where a phrase ends. const was = settled(s, c.marks[1]); st.marks = .{ was, if (plan.gait == .sprint and !c.phraseEnds(from, to)) was else @floatFromInt(to) }; c.both(s, st); } /// 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 { return c.timetable(from, to, false); } /// The timetable a step from `from` to `to` gets walked (`wave`: as a `continue`), for a scene that adds a beat to it. pub fn planned(c: Cursor, from: u64, to: u64, wave: bool) Plan { return c.timetable(from, to, wave); } /// `continue`: straight to a stop far from this one (a breakpoint, not /// a step). The line it leaves fires; the registers it changed strike /// in a wave, 2 f apart in pwndbg's order, the fill in over 6 f, no arm /// and no pulse (a dozen arms at once are a crowd, a dozen pulses a /// flash); memory 18 f after the last of them (the stack's window /// scrolls or fades to its place, the backtrace's frames leave, slide /// and arrive), then the idea; a hold of 36 f after the last strike; /// the advance, the mark out and in (6 f each), the source fading /// through first if it goes farther than its window; a rest. pub fn @"continue"(c: Cursor, s: *anim.Frame, to: u64) void { const plan = c.timetable(c.moment(s), to, true); c.step(s, to, plan, plan.total); } fn timetable(c: Cursor, from: u64, to: u64, wave: bool) Plan { const rec = c.rec; const regs: f32 = @floatFromInt(@popCount(rec.registersChanged(from, to) & ~quiet)); // Memory gives up its slot when nothing it touched is drawn. var wrote_n: usize = 0; for (rec.written(from, to)) |span| wrote_n += @intFromBool(rec.drawn(span, from, to)); var read_n: usize = 0; for (rec.read(from, to)) |span| read_n += @intFromBool(rec.drawn(span, from, to)); const wrote: f32 = @floatFromInt(wrote_n); const touched = wrote_n > 0 or read_n > 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, wave), .wave = wave }; var slot: f32 = 0; for (levels, &plan.at, 0..) |is, *strikes, level| { // A drawing made of the bytes reacts when the projection from // them arrives: its bracket and its line after their strike, and // for a write its own arm. const projected = level == 2 and is and levels[1] and (c.levels.idea == .data or deeper); if (projected) slot += time.project.bracket + @as(f32, if (c.levels.idea == .data) time.project.draw else time.project.far) + @as(f32, if (wrote > 0 and c.levels.idea == .data) time.strike.arm else 0) else if (is) slot += time.cascade; strikes.* = @max(slot, time.cascade); // A wave's last register strikes 2 f a register after its first, // a cascade's 6 f (the fourth and on with the third): the next level is 18 f after that. if (level == 0 and is) slot += if (wave) (regs - 1) * time.continue_wave else @min(regs - 1, 3) * write_apart; } // The writes of one step strike 6 f apart: the last is later. if (levels[1]) slot += @min(@max(wrote - 1, 0), 3) * write_apart; 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, }; // A continue's hold is 36 f: what it changed is too much to read value by value. plan.advance = slot + follow + if (wave) time.read_value else @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, further than a few rows, /// or at the end of a continue (`wave`). fn travel(c: Cursor, from: u64, to: u64, wave: bool) 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 (wave or 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. // What changes faster than it can be read is veiled at a run too. const veiled = options.veil orelse true; const start = s.cursor; c.both(s, Veils{ .to = .{ 1, if (veiled) 1 else 0, if (options.pace < time.run) 1 else 0 } }); 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; c.both(s, Veils{ .to = .{ 0, 0, 0 } }); s.wait(time.beat); } /// The hurry's veils going to `to` (hurried, veil, sprint_veil). const Veils = struct { to: [3]f32, fn run(v: Veils, s: *anim.Frame, c: Cursor) void { s.play(.{ c.hurried.to(v.to[0]), c.veil.to(v.to[1]), c.sprint_veil.to(v.to[2]) }, .{ .seconds = time.veil, .ease = anim.ease.linear }); } }; /// There at once, with nothing struck: a cut. pub fn jump(c: Cursor, s: *anim.Frame, to: u64) void { const Jump = struct { to: u64, fn run(j: @This(), sf: *anim.Frame, v: Cursor) void { var all: [history + 3]anim.Animation = undefined; for (v.stops, 0..) |stop_value, i| all[i] = stop_value.to(@floatFromInt(j.to)); all[history] = v.phase.to(1); all[history + 1] = v.marks[0].to(@floatFromInt(j.to)); all[history + 2] = v.marks[1].to(@floatFromInt(j.to)); sf.play(all, .{ .seconds = 0 }); } }; c.both(s, Jump{ .to = to }); } /// For a component, while it draws (on the minimap the values are a lagging mirror's: `lagInto`). 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]), .wave = placed.value(c.plan[7]) >= 0.5, .fires = placed.value(c.plan[8]) >= 0.5, }, .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), .sprint_veil = placed.value(c.sprint_veil), .count = @intFromFloat(@max(placed.value(c.count), 0)), .of = c.of, .place = 0, .fired = c.levels.fire, .crossings = c.levels.crossings, .way = .{ c.first, c.last }, }; for (&n.stops, c.stops) |*stop_at, v| stop_at.* = whole(rec, placed.value(v)); for (&n.gaits, c.gaits) |*gait, v| gait.* = @enumFromInt(@as(u2, @intFromFloat(std.math.clamp(@round(placed.value(v)), 0, 2)))); 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, /// The pace each step to them was taken at: `gaits[0]` this one's. gaits: [history]Gait = @splat(.walk), /// 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, sprint_veil: f32 = 0, /// 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, /// Steps that make a syscall cross into the kernel (`Levels.crossings`). crossings: bool = false, /// 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 it takes the step (4 f: never one /// frame); 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 => if (n.resting()) 1 else std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 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.plan.fires 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 over the 12 f before the advance (from the step's start where /// that is sooner, over the step at a sprint): how far a label that /// changes in place with the step (a frame's name, a tag's note) has /// crossfaded to the new one. Never in a frame. pub fn renaming(n: Now) f32 { if (n.resting()) return 1; const span = @min(time.quick, n.plan.advance); if (span <= 0) return std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 1); return std.math.clamp((n.time - (n.plan.advance - span)) / span, 0, 1); } /// 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); } /// Of the bytes `addr .. addr + len` (16 at most), the first and the last /// (from `addr`) whose value the step that last wrote them changed: what /// its strike covers. Null where that is not known. pub fn changedBytes(n: Now, addr: u64, len: u64) ?[2]u8 { const age = n.writeAge(addr, len) orelse return null; const l: usize = @intCast(@min(len, 16)); var was: [16]u8 = undefined; var is: [16]u8 = undefined; var known_was: [16]bool = undefined; var known_is: [16]bool = undefined; n.rec.moment(n.stops[age + 1]).read(addr, was[0..l], known_was[0..l]) catch return null; n.rec.moment(n.stops[age]).read(addr, is[0..l], known_is[0..l]) catch return null; var out: ?[2]u8 = null; for (0..l) |i| if (known_was[i] and known_is[i] and was[i] != is[i]) { out = .{ if (out) |o| o[0] else @intCast(i), @intCast(i) }; }; return out; } /// 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); } pub 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; // A run changes values unmarked: it shows them settled. if (n.gaits[a] == .run) return .none; if (a < s.ember_steps) return .ember; // Linear: a fade, as the mark leaves: secondary action does not // start on the fire's frame, where the step's primary one does. // Within the step: a short one (a run's) is not cut off mid-fade by the next. return .{ .level = 1 - std.math.clamp((n.time - n.plan.advance) / @max(@min(s.out, n.plan.total - n.plan.advance), 1.0 / 60.0), 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, coming in over the step. .sprint => return .{ .level = if (n.resting()) 1 else std.math.clamp(n.time / @max(n.plan.total, 1.0 / 60.0), 0, 1) }, // A run strikes nothing: its values change in place, and what // marked them before goes with the run's ease, not in a frame. .run => { var gone = was; gone.level *= 1 - (if (n.resting()) 1 else std.math.clamp(n.time / time.run_ease, 0, 1)); return gone; }, .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; } const cooled = (n.time - n.plan.advance) / s.cool; const in = std.math.clamp(since_strike / s.in, 0, 1); return .{ .level = 1, .solid = 1 - glide(std.math.clamp(cooled, 0, 1)), .in = in, .from = if (was.level >= 1) .ember else .nothing, .out = if (since_strike < s.pulse) theme.pulse(since_strike / s.pulse) else 0, // The turned corner: the old one goes as the paper comes in over // it; the new one comes in over the cool's last 6 f. .corner = @max(std.math.clamp((cooled - 1) * s.cool / s.corner + 1, 0, 1), if (was.level >= 1) 1 - in else 0), }; } /// The mark of the bytes `addr .. addr + size`, which strike with /// `level`, `delay` seconds after its first, and 6 f after the write of /// this step before theirs. pub fn written(n: Now, addr: u64, size: u64, level: Level, delay: f32) ui.Heat { // What the kernel fills in a crossing lands as its work does it, unpulsed. if (level == .memory) if (syscalls.filledAt(n, addr)) |at| { var h = n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), n.time - at); h.out = 0; return h; }; return n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), n.since(level, delay + n.writeDelay(addr, size))); } /// `written`, struck `since` seconds ago (a loupe's own times: it strikes once it has opened). pub fn writtenAt(n: Now, addr: u64, size: u64, struck: f32) ui.Heat { return n.heat(n.writeAge(addr, size), n.writeAgeFrom(addr, size, 1), struck); } /// The state to draw the memory at `addr` from: `shown(.memory)`, but /// what the kernel fills in a crossing from when its byte lands. pub fn shownAt(n: Now, addr: u64) Recording.Moment { if (syscalls.filledAt(n, addr)) |at| return if (n.time - at >= time.strike.in / 2.0) n.moment() else n.before(); return n.shown(.memory); } /// `written`, on a thing the viewer has watched only through the steps /// `lo` to `hi` ago (a window that faded to its place, a view that came /// in after its step): what changed in any other step is plain. pub fn writtenWatched(n: Now, addr: u64, size: u64, level: Level, delay: f32, lo: usize, hi: usize) ui.Heat { const age = n.writeAge(addr, size) orelse return .none; return if (age >= lo and age < hi) n.written(addr, size, level, delay) else .none; } /// How far after this step's first write the one of `addr .. addr + size` is. pub fn writeDelay(n: Now, addr: u64, size: u64) f32 { var order: f32 = 0; var last: ?u64 = null; for (n.rec.written(n.stops[1], n.stops[0])) |span| { if (span.addr < addr + size and span.addr + span.len > addr) return @min(order, 3) * write_apart; // The kernel's own writes have their own times (`filledAt`). if (syscalls.filledAt(n, span.addr) != null) continue; // Bytes of one write (one store, in pieces) are one strike. if (last == null or span.addr != last.?) order += 1; last = span.addr + span.len; } return 0; } /// The mark of a register: the CPU's level. In a continue's wave, no arm and no pulse. pub fn register(n: Now, reg: usize, delay: f32) ui.Heat { var h = n.heat(n.registerAge(reg), n.registerAgeFrom(reg, 1), n.since(.cpu, delay)); if (n.plan.wave) { h.arm = 0; h.out = 0; } return h; } /// 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); try expect(h.corner == 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); // The turned corner: none until the cool's last 6 f, then in. try expect(h.corner == 0); try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(0.90 + s.cool - s.corner / 2.0, plan).heat(0, null, 1).corner, 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(0.90 + 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: nothing struck, and the ember before goes over the run's ease. Sprinting: an ember, coming in over the step. try expectEqual(ui.Heat.none, instant(0.2, Plan.running(0.3)).heat(0, null, 0.2)); try std.testing.expectApproxEqAbs(@as(f32, 0.5), instant(time.run_ease / 2.0, Plan.running(0.3)).heat(0, 1, 0).level, 1e-4); try std.testing.expectApproxEqAbs(@as(f32, 0.2), instant(0.01, Plan.sprinting(0.05)).heat(0, null, 0.01).level, 1e-4); } 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()); }