From 15de88cf82c187635c1989e91bfa639a10304066 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Wed, 11 Nov 2026 20:08:07 -0300 Subject: canim: a column of text as an experiment; the disassembly tied to the stack From the user. A scene may set its text in a column beside the panes a beat is about: col.beat names the panes and their rows, where the text is placed (beside, below, above, or on a drawing) and what it is level with; panes the beat leaves out fold to their title bars on a shelf, their changes struck there. Tried as two scenes beside the originals: the call followed down (column) and a bubble on sort's rings (column_sort). annotation = .tied names the word an instruction touched and draws a touch to its stack row; offsets count from the frame's base; rsp's pin travels with its amount before the stack follows; .whole keeps the full chain. carry = .arrow draws a value's way between memory and a register. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNCKgYCGiANnEwcEQxa --- anim/src/column.zig | 942 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 942 insertions(+) create mode 100644 anim/src/column.zig (limited to 'anim/src/column.zig') diff --git a/anim/src/column.zig b/anim/src/column.zig new file mode 100644 index 0000000..32b3d4d --- /dev/null +++ b/anim/src/column.zig @@ -0,0 +1,942 @@ +//! The column (design/README.md, "column (an experiment)"): a second way +//! to compose a scene, beside the working frame. Two columns of 880: the +//! panes a beat is about on the left (x 64, from y 84 to 1032, 12 apart, in +//! the frame's order), the narration on the right (x 976), each `bubble` +//! level with the row it speaks of; every pane the beat leaves out folded to +//! its tag on the `shelf` (y 48), a register struck on its tag as on its row. +//! +//! It is an author's instrument: the scene says, beat by beat, which panes +//! stand and with how many rows, where the text is placed (`beside`, +//! `below` the working frame as a caption, `above` or `on` a wide drawing), +//! what each bubble is level with and what its stem points at; what a beat +//! leaves out is defaulted, never against what it wrote: +//! +//! const col = canim.column(s, ctx, .{ .lens = log, .titles = .{ .band = "system calls", .view = "its bytes" } }); +//! col.beat(s, .{ +//! .panes = &.{ .{ .source, 3 }, .{ .disasm, 11 }, .{ .stack, canim.column_rest } }, +//! .say = "The call pushes where to come back to, `main+45`, and goes down to open's stub.", +//! .level = .{ .row = call }, // default: the pc's row at the beat +//! }); +//! +//! Between beats, in a rest (design/README.md, "Panes between beats"): the +//! last bubble dims; the panes that leave fade (12 f) and fold to the shelf +//! (24 f, `glide`); those that stay glide (24 f); those that come unfold +//! (24 f) and fade in (12 f); an older bubble in the way glides out of it +//! (24 f); the next arrives (18 f, rising 8), its stem drawing (12 f); the +//! lead; the stem draws back as the step fires. A bubble never travels +//! between placements: the last leaves (12 f), the frame changes (48 f), the +//! next arrives. +const std = @import("std"); +const sk = @import("sketch"); +const anim = @import("anim"); +const ui = @import("ui.zig"); +const ties = @import("ties.zig"); +const words = @import("words.zig"); +const cursors = @import("cursor.zig"); +const context = @import("context.zig"); +const Stage = @import("stage.zig").Stage; +const theme = ui.theme; +const time = theme.time; +const Rect = ui.Rect; +const Split = theme.layout.Split; +const t = theme.color.text; +const m = theme.metric.context; + +/// The panes, in the frame's order: the drawing, its view, the source, the +/// disassembly (or the descent), the registers, the stack, the backtrace. +pub const Part = enum { band, view, source, disasm, registers, stack, backtrace }; +const parts = std.enums.values(Part); +/// A pane's rows: what the column has left (to 1032, the floor's foot). +pub const rest: u32 = std.math.maxInt(u32); +/// A pane that stands in a beat, and its rows (or `rest`). +pub const Pane = struct { Part, u32 }; +pub const Placement = enum { beside, below, above, on }; +/// What a bubble is level with: the pc's row as the beat begins (the +/// default), a row of the disassembly by its instruction's address, the head +/// row over a function's window in a descent, the descent's floor (where the +/// kernel's window opens), a graph's block by its address, or a height. +pub const Level = union(enum) { pc, row: u64, head: []const u8, floor, block: u64, y: f32 }; +/// A bubble's stem: to what it is level with (the default), none (its level +/// is the tie), or to another place. +pub const Stem = union(enum) { level, none, to: Level }; +/// A folded pane's tag note, as the scene says it (`code` in backticks). +pub const Note = struct { Part, []const u8 }; + +pub const Beat = struct { + /// The panes that stand (`beside`); null: the beat's cause and effect, + /// the source (3 lines) and the disassembly (11 rows, a descent the rest) + /// and the pane the next step's effect lands in. + panes: ?[]const Pane = null, + say: []const u8, + /// Null: the column's (`Options.at`). + at: ?Placement = null, + level: Level = .pc, + stem: Stem = .level, + /// Folded panes' tag notes from this beat on (unless one is given: the + /// registers' is those the step changed, the source's its line, the + /// disassembly's the instruction at the pc). + notes: []const Note = &.{}, + /// `on`: the bubble's top left in the frame (design units), in the drawing's free space. + where: ?[2]f32 = null, +}; + +pub const Options = struct { + /// The lens (one object drawing the band and its view: `Crossing`, a + /// graph), with its panes' titles for the shelf. + lens: ?anim.Obj = null, + titles: struct { band: []const u8 = "", view: []const u8 = "" } = .{}, + /// The scene's placement where a beat names none. + at: Placement = .beside, +}; + +/// Frames, at 60 a second (design/README.md, "Panes between beats"). +const f = struct { + const dim = 18.0 / 60.0; + const rows = 12.0 / 60.0; + const fold = 24.0 / 60.0; + const glide = 24.0 / 60.0; + const relayout = theme.time.relayout; + const push = 24.0 / 60.0; + const arrive = 18.0 / 60.0; + const stem_after = 6.0 / 60.0; + const stem = 12.0 / 60.0; + const leave = 12.0 / 60.0; + const note = 12.0 / 60.0; +}; +/// The bubble: Go 40 on 54, code in mono 35, 16 of padding, 812 wide at +/// most, 40 characters a line; its first line's middle 40 under its top. +const bubble = struct { + const x = 984; + const pad = 16; + const max_w = 812; + const chars = 40; + const pitch = theme.size.sans.caption_leading; + const first = 40; + const gap = 12; + const top = theme.canvas.stage.y; + const bottom = theme.canvas.stage.y + theme.canvas.stage.h; +}; +/// A drawing's own size (the `blocks` lens's room, less its tag): `on` and `above` draw it larger. +const lens_w = 896; +const lens_h = 344; +/// The panes' column: from 84 to 1032 (the floor's foot), 12 apart; the shelf at 48. +const column_top = 84; +const column_foot = 1032; +const shelf_y = theme.canvas.stage.y; + +const Text = struct { + text: []const u8, + placement: Placement, + level: Level, + stem: ?Level, + where: ?[2]f32, + notes: [parts.len]?[]const u8, + /// 0 to 1: arriving (18 f), dimmed (18 f), leaving (12 f), its stem drawn, + /// the bubbles before it gliding out of its way (24 f), its notes in (12 f). + in: anim.Value, + dim: anim.Value, + out: anim.Value, + stem_v: anim.Value, + push: anim.Value, + notes_in: anim.Value, +}; + +pub const Column = struct { + cursor: cursors.Cursor, + stage: *Stage, + obj: anim.Obj = undefined, + objs: [parts.len]?anim.Obj, + titles: [parts.len][]const u8, + /// Whether each pane stands, as the scene's code has it so far. + standing: [parts.len]bool, + /// 1 on the shelf, 0 standing (the fold's travel between); 1 while the + /// column draws a pane's frame in its stead (folding, unfolding). + shelf: [parts.len]anim.Value, + ghost: [parts.len]anim.Value, + texts: [48]Text = undefined, + n: usize = 0, + placement: Placement = .below, + default: Placement, + /// The working frame's split, and the one the stage is going to. + working: Split, + split: Split, + /// The drawing across both columns (`on`, `above`): how much larger, and where its box goes. + zoom: f32 = 1, + read_by: f32 = 0, + said: bool = false, + + /// One beat: the panes change (in a rest, never under a step), the text + /// arrives where the beat places it, the lead, then the scene's step. + pub fn beat(col: *Column, s: *anim.Frame, b: Beat) void { + const at = b.at orelse col.default; + const here = col.cursor.moment(s); + const rec = col.cursor.rec; + const level: Level = if (b.level == .pc) .{ .row = rec.register(here, "rip") } else b.level; + var notes: [parts.len]?[]const u8 = @splat(null); + for (b.notes) |note| notes[@intFromEnum(note[0])] = note[1]; + // Which panes stand, and where. + var to: [parts.len]bool = @splat(false); + var split = col.split; + var zoom: f32 = 1; + switch (at) { + .below => { + for (parts) |p| to[@intFromEnum(p)] = col.objs[@intFromEnum(p)] != null; + split = col.working; + }, + .beside => { + const panes = b.panes orelse col.defaults(s); + for (panes) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null; + split = col.columnSplit(panes); + }, + .above, .on => { + to[@intFromEnum(Part.band)] = true; + for (b.panes orelse &.{}) |pane| to[@intFromEnum(pane[0])] = col.objs[@intFromEnum(pane[0])] != null; + // The drawing at its lens size across both columns, as large as the stage lets it. + const room: Rect = if (at == .on) .{ .x = 64, .y = column_top, .w = 1792, .h = 712 } else .{ .x = 64, .y = column_top + 132, .w = 1792, .h = bubble.bottom - column_top - 132 }; + zoom = @min(room.w / lens_w, (room.h - m.tag) / lens_h); + split.band = room; + }, + } + // Not before the text up has been read. + s.wait(@max(col.read_by - s.cursor, 0)); + const kind = frameOf(at) != frameOf(col.placement); + const moves = !std.meta.eql(to, col.standing) or !sameBoxes(col.split, split, to) or zoom != col.zoom or kind; + const newest = col.newestStanding(); + if (col.said) { + if (kind or at != .beside) { + // A text never travels between placements: what stands leaves (then a gap, as a caption's). + col.leaveAll(s); + if (!moves) s.wait(time.caption_gap); + } else if (moves) if (newest) |k| { + s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear }); + }; + } + if (moves) col.change(s, to, split, at, zoom, kind); + col.placement = at; + // A beat with nothing to say: the panes alone. + if (b.say.len == 0) return; + // The text. + const tx = col.add(s, b.say, at, level, switch (b.stem) { + .level => level, + .none => null, + .to => |l| l, + }, b.where, notes); + if (at == .beside) { + // Three stand at most: the oldest leaves first. + var standing: usize = 0; + var oldest: ?usize = null; + for (col.texts[0 .. col.n - 1], 0..) |x, k| if (x.placement == .beside and settled(s, x.out) < 1) { + standing += 1; + if (oldest == null) oldest = k; + }; + if (standing >= 3) { + s.play(.{col.texts[oldest.?].out.to(1)}, .{ .seconds = f.leave, .ease = easeExit }); + } + if (standing > 0) { + const start = s.cursor; + // A beat that keeps its panes: the last dims as the older ones make way. + if (!moves) if (newest) |k| { + s.play(.{col.texts[k].dim.to(1)}, .{ .seconds = f.dim, .ease = anim.ease.linear }); + s.cursor = start; + }; + s.play(.{tx.push.to(1)}, .{ .seconds = f.push, .ease = anim.ease.linear }); + } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 }); + } else s.play(.{tx.push.to(1)}, .{ .seconds = 0 }); + const arrives = s.cursor; + s.play(.{tx.notes_in.to(1)}, .{ .seconds = f.note, .ease = anim.ease.linear }); + s.cursor = arrives; + s.play(.{tx.in.to(1)}, .{ .seconds = f.arrive, .ease = easeEnter }); + if (tx.stem != null and at != .below and at != .above) { + const arrived = s.cursor; + s.cursor = arrives + f.stem_after; + s.play(.{tx.stem_v.to(1)}, .{ .seconds = f.stem, .ease = anim.ease.linear }); + s.cursor = @max(s.cursor, arrived); + } + col.read_by = s.cursor + time.caption(@intCast(std.unicode.utf8CountCodepoints(b.say) catch b.say.len)); + s.wait(if (col.said) time.caption_lead else time.caption_lead_first); + // The stem draws back as the step fires: the step's own ties have the gutter. + const fires = s.cursor; + s.play(.{tx.stem_v.to(2)}, .{ .seconds = f.stem, .ease = anim.ease.linear }); + s.cursor = fires; + col.said = true; + } + + /// The close: the last picture still, the last text read. + pub fn close(col: *Column, s: *anim.Frame) void { + s.wait(time.before_cut); + s.wait(@max(col.read_by - s.cursor, 0)); + } + + fn add(col: *Column, s: *anim.Frame, text: []const u8, at: Placement, level: Level, stem: ?Level, where: ?[2]f32, notes: [parts.len]?[]const u8) *Text { + const k = @min(col.n, col.texts.len - 1); + col.texts[k] = .{ .text = text, .placement = at, .level = level, .stem = stem, .where = where, .notes = notes, .in = s.value(0), .dim = s.value(0), .out = s.value(0), .stem_v = s.value(0), .push = s.value(0), .notes_in = s.value(0) }; + col.n = k + 1; + return &col.texts[k]; + } + + fn newestStanding(col: *const Column) ?usize { + if (col.n == 0 or col.texts[col.n - 1].placement != .beside) return null; + return col.n - 1; + } + + fn leaveAll(col: *Column, s: *anim.Frame) void { + var all: [48]anim.Animation = undefined; + var n: usize = 0; + for (col.texts[0..col.n]) |x| if (settled(s, x.out) < 1) { + all[n] = x.out.to(1); + n += 1; + }; + if (n > 0) together(s, all[0..n], f.leave, easeExit); + } + + /// The panes go from what stands to `to` at `split`: the leaving fade + /// and fold, the staying glide, the coming unfold and fade in; never a + /// fold and an unfold at once. + fn change(col: *Column, s: *anim.Frame, to: [parts.len]bool, split: Split, at: Placement, zoom: f32, kind: bool) void { + var leaving: [parts.len]bool = undefined; + var coming: [parts.len]bool = undefined; + // A pane that stays but changes its rows: its rows fade out and in round the + // glide (they are laid out for its height), its frame gliding as the column's. + var resized: [parts.len]bool = undefined; + var any_leaving = false; + var any_coming = false; + inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| { + leaving[i] = col.standing[i] and !to[i]; + coming[i] = !col.standing[i] and to[i]; + resized[i] = col.standing[i] and to[i] and i > 1 and @field(col.split, name).h != @field(split, name).h; + any_leaving = any_leaving or leaving[i] or resized[i]; + any_coming = any_coming or coming[i] or resized[i]; + } + const band = @intFromEnum(Part.band); + const view = @intFromEnum(Part.view); + if (any_leaving) { + var anims: [3 * parts.len]anim.Animation = undefined; + var n: usize = 0; + for (parts, 0..) |_, i| if (leaving[i] or resized[i]) { + anims[n] = col.ghost[i].to(1); + n += 1; + }; + for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| { + anims[n] = o.fadeOut(); + n += 1; + }; + for (parts, 0..) |_, i| if (leaving[i]) if (col.objs[i]) |o| { + // The lens is one object: it goes when neither of its panes stands (once). + const lens = i == band or i == view; + if (!lens or !(to[band] or to[view]) and !(i == view and leaving[band])) { + anims[n] = o.fadeOut(); + n += 1; + } + if (i == band) { + anims[n] = col.stage.drawing.to(0); + n += 1; + } + }; + if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear); + n = 0; + for (parts, 0..) |_, i| if (leaving[i]) { + anims[n] = col.shelf[i].to(1); + n += 1; + }; + if (n > 0) { + together(s, anims[0..n], f.fold, anim.ease.linear); + n = 0; + for (parts, 0..) |_, i| if (leaving[i]) { + anims[n] = col.ghost[i].to(0); + n += 1; + }; + together(s, anims[0..n], 0, anim.ease.linear); + } + } + // What stays glides (the frame changing between placements: 48 f); the + // folded keep their boxes, a folded band none, so that its view can stand alone. + var next = split; + inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (!to[i]) { + @field(next, name) = @field(col.split, name); + if (i == band) next.band.h = 0; + }; + const glides = !sameBoxes(col.split, next, col.standing) or zoom != col.zoom or kind; + const seconds: f32 = if (!glides) 0 else if (kind) f.relayout else f.glide; + const start = s.cursor; + // A pane going over to the other column goes down (or up) its own + // first, as the others make room, then across: never over another's rows. + var mid = next; + var crosses = false; + inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (to[i] and col.standing[i] and @field(next, name).x != @field(col.split, name).x) { + @field(mid, name).x = @field(col.split, name).x; + crosses = true; + }; + if (crosses) col.stage.glide(s, mid, seconds / 2); + col.stage.glide(s, next, if (crosses) seconds / 2 else seconds); + const end = s.cursor; + s.cursor = start; + s.play(.{col.stage.column.to(if (at == .beside) 1 else 0)}, .{ .seconds = seconds, .ease = anim.ease.linear }); + // The drawing grows with its box, across both columns, its tag as it was. + s.cursor = start; + s.play(.{col.stage.zoom.to(zoom)}, .{ .seconds = seconds, .ease = easeGlide }); + s.cursor = end; + col.split = next; + col.zoom = zoom; + if (any_coming) { + var anims: [3 * parts.len]anim.Animation = undefined; + var n: usize = 0; + for (parts, 0..) |_, i| if (coming[i]) { + anims[n] = col.ghost[i].to(1); + n += 1; + }; + together(s, anims[0..n], 0, anim.ease.linear); + n = 0; + for (parts, 0..) |_, i| if (coming[i]) { + anims[n] = col.shelf[i].to(0); + n += 1; + }; + if (n > 0) together(s, anims[0..n], f.fold, anim.ease.linear); + n = 0; + for (parts, 0..) |_, i| if (coming[i] or resized[i]) { + anims[n] = col.ghost[i].to(0); + n += 1; + }; + for (parts, 0..) |_, i| if (resized[i]) if (col.objs[i]) |o| { + anims[n] = o.fadeIn(); + n += 1; + }; + for (parts, 0..) |_, i| if (coming[i]) if (col.objs[i]) |o| { + const lens = i == band or i == view; + if (!lens or !(col.standing[band] or col.standing[view]) and !(i == view and coming[band])) { + anims[n] = o.fadeIn(); + n += 1; + } + if (i == band) { + anims[n] = col.stage.drawing.to(1); + n += 1; + } + }; + if (n > 0) together(s, anims[0..n], f.rows, anim.ease.linear); + } + col.standing = to; + } + + /// The beat's panes where the scene names none: its cause, the source + /// (three lines) over the disassembly; and where the next step's effect + /// lands, the registers or the stack. + fn defaults(col: *const Column, s: *anim.Frame) []const Pane { + const rec = col.cursor.rec; + const here = col.cursor.moment(s); + const next = rec.next(.moment, here); + const changed = rec.registersChanged(here, next) & ~cursors.quiet & ~(@as(u32, 1) << @intCast(context.index("rsp").?)); + const pushes = rec.register(next, "rsp") != rec.register(here, "rsp") or rec.written(here, next).len > 0; + const out = s.arena.alloc(Pane, 3) catch @panic("column: out of memory"); + out[0] = .{ .source, 3 }; + if (changed != 0) { + out[1] = .{ .disasm, 11 }; + out[2] = .{ .registers, if (col.stage.registers_rows > 0) @intFromFloat(col.stage.registers_rows) else @intCast(context.registerRows(context.every)) }; + return out; + } + if (pushes) { + out[1] = .{ .disasm, 11 }; + out[2] = .{ .stack, rest }; + return out; + } + out[1] = .{ .disasm, rest }; + return out[0..2]; + } + + /// The panes in one column, 12 apart from 84, in the frame's order. + fn columnSplit(col: *const Column, panes: []const Pane) Split { + var rows: [parts.len]?u32 = @splat(null); + for (panes) |p| rows[@intFromEnum(p[0])] = p[1]; + var fixed: f32 = 0; + var n: f32 = 0; + for (rows) |r| if (r) |count| { + if (count != rest) fixed += theme.layout.panelH(@floatFromInt(count)); + n += 1; + }; + const left = column_foot - column_top - fixed - (n - 1) * theme.canvas.row_gap; + var out = col.split; + var y: f32 = column_top; + inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| if (rows[i]) |count| { + const h = if (count == rest) theme.layout.panelH(@floatFromInt(theme.layout.rowsIn(left))) else theme.layout.panelH(@floatFromInt(count)); + @field(out, name) = .{ .x = theme.layout.program.x, .y = y, .w = theme.layout.program.w, .h = h }; + y += h + theme.canvas.row_gap; + }; + return out; + } + + pub fn draw(col: *const Column, fr: *sk.Frame, placed: anim.Placed) void { + const u: ui.Ui = .{ .f = fr, .at = placed }; + col.drawShelf(u, placed); + col.drawTexts(u, placed); + } + + fn box(col: *const Column, placed: anim.Placed, p: Part) Rect { + return col.stage.box(placed, switch (p) { + inline else => |tag| @field(@import("stage.zig").Part, @tagName(tag)), + }); + } + + /// The notes in force: the newest text's, crossfading from the one before. + fn notesNow(col: *const Column, placed: anim.Placed) struct { [parts.len]?[]const u8, [parts.len]?[]const u8, f32 } { + var k = col.n; + while (k > 0) { + k -= 1; + const p = placed.value(col.texts[k].notes_in); + if (p <= 0) continue; + const before: [parts.len]?[]const u8 = if (k > 0) col.texts[k - 1].notes else @splat(null); + return .{ before, col.texts[k].notes, p }; + } + return .{ @splat(null), @splat(null), 1 }; + } + + /// The shelf: each folded pane's tag, side by side from 64 in the frame's + /// order; a pane folding or unfolding drawn as its frame on its way + /// between its box and its place there. + fn drawShelf(col: *const Column, u: ui.Ui, placed: anim.Placed) void { + const before, const after, const p = col.notesNow(placed); + var x: f32 = theme.layout.program.x; + for (parts, 0..) |part, i| { + if (col.objs[i] == null) continue; + const on = theme.ease(.glide, placed.value(col.shelf[i])); + // Its frame drawn in the pane's stead: crossfading with the pane at its box, alone on its way. + const ghost = placed.value(col.ghost[i]); + if (on <= 0 and ghost <= 0) continue; + const notes = [2]?[]const u8{ before[i], after[i] }; + const w = std.math.lerp(tagWidth(col, u, placed, part, notes[0]), tagWidth(col, u, placed, part, notes[1]), p); + const slot: Rect = .{ .x = x, .y = shelf_y, .w = w, .h = m.tag }; + const name = col.title(placed, part); + const b = col.box(placed, part); + const r: Rect = if (ghost > 0) .{ .x = std.math.lerp(b.x, slot.x, on), .y = std.math.lerp(b.y, slot.y, on), .w = std.math.lerp(b.w, slot.w, on), .h = std.math.lerp(b.h, slot.h, on) } else slot; + const v = u.moved(r.x, r.y).faded(if (on > 0) 1 else ghost); + _ = v.panel(r.w, r.h, name, .{}); + // Its note comes as it lands on the shelf, and goes as it leaves. + const shows = std.math.clamp((on - 0.75) * 4, 0, 1); + if (shows > 0) { + const nx = 28 + v.width(.sans_medium, theme.size.sans.tag, name) + 12; + if (p < 1) _ = col.tagNote(v.faded(shows * (1 - p)), placed, part, nx, notes[0]); + _ = col.tagNote(v.faded(shows * p), placed, part, nx, notes[1]); + } + x += (w + theme.canvas.row_gap) * on; + } + } + + fn title(col: *const Column, placed: anim.Placed, p: Part) []const u8 { + if (p != .source) return col.titles[@intFromEnum(p)]; + const now = col.cursor.now(placed); + const rec = col.cursor.rec; + return rec.sources[rec.shown[now.marked()].src].name(); + } + + fn tagWidth(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, note: ?[]const u8) f32 { + const title_w = u.width(.sans_medium, theme.size.sans.tag, col.title(placed, p)); + const note_w = col.tagNote(u.faded(0), placed, p, 0, note); + return 28 + title_w + (if (note_w > 0) 12 + note_w else 0) + 12; + } + + /// A folded pane's note from `x`: the scene's, or for the registers the + /// ones the last steps changed (the first with its value, struck on the + /// tag as on its row). How wide it is. + fn tagNote(col: *const Column, u: ui.Ui, placed: anim.Placed, p: Part, x: f32, note: ?[]const u8) f32 { + const base = m.tag - 6; + if (note) |text| return words.runs(u, x, base, text, .sans, theme.size.sans.micro, theme.size.mono.context, t.faint) - x; + if (p == .source or p == .disasm) { + // Where the mark is: the line, or the instruction and its address; changing with the advance. + const now = col.cursor.now(placed); + const turn = now.renaming(); + const was = if (turn < 1) col.markNote(u.faded(1 - turn), now.marks[0], p, x) else 0; + const is = if (turn > 0) col.markNote(u.faded(turn), now.marks[1], p, x) else 0; + return std.math.lerp(was, is, turn); + } + if (p != .registers) return 0; + const now = col.cursor.now(placed); + // The step's registers come with their strike; the step before's go (6 f; at a run its 8 f). + const first = for (theme.metric.all_registers[0..16]) |name| { + const i = context.index(name).?; + if (now.registerAge(i) == 0) break ties.strikeDelay(now, i); + } else 0; + const turn: f32 = if (now.resting()) 1 else switch (now.plan.gait) { + .walk => std.math.clamp(now.since(.cpu, first) / time.strike.in, 0, 1), + .run => std.math.clamp(now.since(.cpu, 0) / time.run_ease, 0, 1), + .sprint => std.math.clamp(now.time / @max(now.plan.total, 1.0 / 60.0), 0, 1), + }; + const was = if (turn < 1) col.registersNote(u.faded(1 - turn), now, x, 1) else 0; + const is = if (turn > 0) col.registersNote(u.faded(turn), now, x, 0) else 0; + return std.math.lerp(was, is, turn); + } + + /// The source's line at `moment` (`line 12`), or the disassembly's instruction there (`jne 4011af`). + fn markNote(col: *const Column, u: ui.Ui, moment: u64, p: Part, x: f32) f32 { + const rec = col.cursor.rec; + const size = theme.size.mono.context; + const base = m.tag - 6; + var at = x; + if (p == .source) { + u.text(.mono, size, at, base, "line", t.dim); + at += u.width(.mono, size, "line") + ui.advance(size); + const n = u.print("{d}", .{rec.shown[moment].line}); + u.text(.mono, size, at, base, n, t.primary); + return at + u.width(.mono, size, n) - x; + } + var buf: [256]u8 = undefined; + const pc = rec.register(moment, "rip"); + const here = rec.instruction(moment, pc, &buf) orelse return 0; + const mn = (@import("disasm.zig").Insn{ .addr = pc, .len = here.len, .text = here.text }).mnemonic(); + const word = u.print("{s}", .{mn}); + u.text(.mono_bold, size, at, base, word, theme.color.code.keyword); + at += u.width(.mono, size, word) + ui.advance(size); + return u.address(at, base, pc, .{ .ink = ui.rgb(theme.color.region.code_) }) - x; + } + + /// The registers the step `age` steps ago changed (three at most, in + /// pwndbg's order), the first with its value: struck on the tag as on its row. + fn registersNote(col: *const Column, u: ui.Ui, now: cursors.Now, x: f32, age: u64) f32 { + const base = m.tag - 6; + const rec = col.cursor.rec; + const size = theme.size.mono.context; + var at = x; + var shown: usize = 0; + for (theme.metric.all_registers[0..16]) |name| { + const i = context.index(name).?; + if (now.registerAgeFrom(i, age) != age or shown == 3) continue; + if (shown > 0) at += ui.advance(size); + u.text(.mono, size, at, base, name, if (shown == 0) t.dim else t.primary); + at += u.width(.mono, size, name); + if (shown == 0) { + const v = rec.register(now.stops[age], name); + at += ui.advance(size); + const digits = if (v < 0x10000) u.print("{d}", .{v}) else u.print("{x}", .{v}); + const dw = u.width(.mono, size, digits); + const heat = if (age == 0) now.register(i, ties.strikeDelay(now, i)) else now.heat(1, null, 0); + const ink = u.written(.{ .x = at, .y = 0, .w = dw, .h = m.tag }, heat) orelse ui.Ink{}; + u.text(ink.face, size, at, base, digits, ink.ink); + at += dw; + } + shown += 1; + } + return at - x; + } + + fn drawTexts(col: *const Column, u: ui.Ui, placed: anim.Placed) void { + const inv = placed.xf.invert(); + const now = col.cursor.now(placed); + // The newest text arriving (or arrived), and the beside ones standing. + var newest: ?usize = null; + for (col.texts[0..col.n], 0..) |x, k| if (placed.value(x.push) > 0 or placed.value(x.in) > 0) { + newest = k; + }; + // While panes fold, unfold or are laid out anew, what has been said stays where it is, from then on. + for (col.ghost) |g| if (placed.value(g) > 0) { + for (col.texts[0..col.n], 0..) |_, k| if (last_level[k] != null) { + latched[k] = true; + }; + break; + }; + var with: [48]f32 = undefined; + var without: [48]f32 = undefined; + col.layout(placed, inv, newest, true, &with); + col.layout(placed, inv, newest, false, &without); + const push = if (newest) |k| theme.ease(.glide, placed.value(col.texts[k].push)) else 1; + for (col.texts[0..col.n], 0..) |x, k| { + const in = placed.value(x.in); + const out = placed.value(x.out); + if (in <= 0 or out >= 1) continue; + const rise = (1 - theme.ease(.enter, in)) * time.caption_rise; + var shows = in * (1 - out); + switch (x.placement) { + .below => { + const v = u.faded(shows).moved(0, rise); + var lines = std.mem.splitScalar(u8, x.text, '\n'); + const two = std.mem.indexOfScalar(u8, x.text, '\n') != null; + var n: usize = if (two) 1 else 0; + while (lines.next()) |line| : (n += 1) { + if (n > 2) break; + _ = words.runs(v, theme.canvas.margin_x, theme.canvas.caption_baseline[n], line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary); + } + }, + .above => { + const lines = wrap(u, x.text, 80); + const v = u.faded(shows).moved(0, rise); + for (lines, 0..) |line, n| _ = words.runs(v, theme.canvas.margin_x, column_top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, t.primary); + }, + .on => { + const where = x.where orelse .{ 104, 144 }; + col.paper(u.faded(shows).moved(0, rise), x, where[0], where[1], 0); + if (x.stem) |target| col.stemOn(u, inv, x, where, target, placed); + }, + .beside => { + // At a run only the newest stands. + if (newest != k) shows *= 1 - now.hurried; + const top = if (newest == k) with[k] else std.math.lerp(without[k], with[k], push); + col.paper(u.faded(shows).moved(0, rise), x, bubble.x, top, placed.value(x.dim)); + if (x.stem) |target| col.stemBeside(u, inv, x, top, target, placed); + }, + } + } + } + + /// A bubble's text from `x, top`: on `raised` paper and primary, the + /// paper going and the ink dimming as it becomes the account (`dim`). + fn paper(_: *const Column, u: ui.Ui, x: Text, left: f32, top: f32, dim: f32) void { + const lines = wrap(u, x.text, bubble.chars); + const h = bubble.first * 2 + @as(f32, @floatFromInt(lines.len - 1)) * bubble.pitch; + if (dim < 1) u.faded(1 - dim).fill(.{ .x = left, .y = top, .w = paperWidth(u, x), .h = h }, theme.color.raised); + const ink = ui.mix(t.primary, t.dim, dim); + for (lines, 0..) |line, n| _ = words.runs(u, left + bubble.pad, top + bubble.first + @as(f32, @floatFromInt(n)) * bubble.pitch + 14, line, .sans, theme.size.sans.caption, theme.size.mono.value, ink); + } + + /// Each beside text's top, the newest's or not: level with what it + /// speaks of where it can be; an older one in a newer one's way above it, + /// or under it where there is no room above. + fn layout(col: *const Column, placed: anim.Placed, inv: sk.math.Affine, newest: ?usize, with_newest: bool, out: *[48]f32) void { + var taken: [48][2]f32 = undefined; + var n_taken: usize = 0; + var k = col.n; + while (k > 0) { + k -= 1; + const x = col.texts[k]; + out[k] = 0; + if (x.placement != .beside) continue; + if (!with_newest and newest == k) continue; + if (placed.value(x.out) >= 1) continue; + // Only what has arrived. + if (newest == null or k > newest.?) continue; + const h = height(x); + var top = std.math.clamp(levelY(placed, inv, k, x.level) - bubble.first, bubble.top, bubble.bottom - h); + // Above what is in its way, while there is room; else under it. + var tries: usize = 0; + while (tries < n_taken + 1) : (tries += 1) { + const hit = for (taken[0..n_taken]) |r| { + if (top < r[1] + bubble.gap and top + h + bubble.gap > r[0]) break r; + } else null; + const r = hit orelse break; + top = r[0] - bubble.gap - h; + } + if (top < bubble.top) { + var lowest: f32 = bubble.top; + for (taken[0..n_taken]) |r| lowest = @max(lowest, r[1] + bubble.gap); + top = lowest; + } + out[k] = top; + taken[n_taken] = .{ top, top + h }; + n_taken += 1; + } + } + + /// The stem of a beside text: from its first line across the gutter onto + /// the pane's right rule level with the row, a head 7 by 8 on the rule. + fn stemBeside(_: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, top: f32, target: Level, placed: anim.Placed) void { + const v = placed.value(x.stem_v); + if (v <= 0 or v >= 2) return; + const r = find(inv, target) orelse return; + const y0 = top + bubble.first; + const y1 = (r[1] + r[3]) / 2; + const lane = theme.metric.tie.link_lane + 6; + var buf = [4]ui.Vec{ .{ bubble.x, y0 }, .{ lane, y0 }, .{ lane, y1 }, .{ r[2] + 1, y1 } }; + const points: []const ui.Vec = if (@abs(y0 - y1) < 1) &.{ .{ bubble.x, y1 }, .{ r[2] + 1, y1 } } else buf[0..]; + u.route(points, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 6 }); + } + + /// The stem of a text `on` a drawing: round the drawing's outside, along + /// its top lane (under its tag), down onto the part it speaks of. + fn stemOn(col: *const Column, u: ui.Ui, inv: sk.math.Affine, x: Text, where: [2]f32, target: Level, placed: anim.Placed) void { + const v = placed.value(x.stem_v); + if (v <= 0 or v >= 2) return; + const r = find(inv, target) orelse return; + const w = paperWidth(u, x); + const lane = column_top + m.tag + 10; + const from_x = where[0] + w - 32; + const to_x = r[2] - 24; + _ = col; + u.route(&.{ .{ from_x, where[1] }, .{ from_x, lane }, .{ to_x, lane }, .{ to_x, r[1] - 1 } }, t.dim, .{ .width = theme.stroke.rule, .head = .{ 7, 8 }, .progress = cursors.standard(@min(v, 1)), .from = cursors.standard(@max(v - 1, 0)), .radius = 8 }); + } +}; + +/// `all` played together from the cursor, which then moves past them. +fn together(s: *anim.Frame, all: []const anim.Animation, seconds: f32, ease: anim.Ease) void { + const start = s.cursor; + for (all) |a| { + s.cursor = start; + s.play(.{a}, .{ .seconds = seconds, .ease = ease }); + } + s.cursor = start + seconds; +} + +fn easeExit(x: f32) f32 { + return theme.ease(.exit, x); +} +fn easeEnter(x: f32) f32 { + return theme.ease(.enter, x); +} +fn easeGlide(x: f32) f32 { + return theme.ease(.glide, x); +} + +fn frameOf(p: Placement) enum { working, column, wide } { + return switch (p) { + .below => .working, + .beside => .column, + .above, .on => .wide, + }; +} + +/// Whether the panes that stand in both have the same boxes. +fn sameBoxes(a: Split, b: Split, standing: [parts.len]bool) bool { + inline for (.{ "band", "view", "source", "disasm", "registers", "stack", "backtrace" }, 0..) |name, i| { + if (standing[i] and !std.meta.eql(@field(a, name), @field(b, name))) return false; + } + return true; +} + +fn settled(s: *const anim.Frame, v: anim.Value) f32 { + return s.values.items[@backingInt(v)].settled; +} + +/// Where a level's place is this frame, in the frame's units: left, top, right, bottom. +fn find(inv: sk.math.Affine, level: Level) ?[4]f32 { + const place: ties.Place = switch (level) { + .pc => .pc, + .row => |a| .{ .row = a }, + .head => |name| .{ .row = @import("descent.zig").headKey(name) }, + .floor => .floor, + .block => |a| .{ .block = a }, + .y => |y| return .{ 0, y - m.row / 2, theme.layout.program.x + theme.layout.program.w, y + m.row / 2 }, + }; + const r = ties.find(place) orelse return null; + const a = inv.apply(.{ r[0], r[1] }); + const b = inv.apply(.{ r[2], r[3] }); + return .{ a[0], a[1], b[0], b[1] }; +} + +/// The middle of the row a text `k` is level with; where the row has gone +/// (a window closed round it), where it last was. +/// shortcut: remembered by the process as frames are drawn in order (an export, a player playing); after a seek a text whose row is gone sits at 400 until it is seen again. +var last_level: [48]?f32 = @splat(null); +/// Once its row has gone from a pane that is drawn, or the panes have changed, a text stays where it is (`latched`). +var latched: [48]bool = @splat(false); +fn levelY(_: anim.Placed, inv: sk.math.Affine, k: usize, level: Level) f32 { + if (!latched[k]) if (find(inv, level)) |r| { + const y = (r[1] + r[3]) / 2; + last_level[k] = y; + return y; + }; + // A row of the disassembly, gone while the pane is there (its pc drawn): the text stays. + if (last_level[k] != null and (level == .row or level == .head or level == .floor) and ties.find(.pc) != null) latched[k] = true; + return last_level[k] orelse 400; +} + +fn height(x: Text) f32 { + const n = lineCount(x.text, bubble.chars); + return bubble.first * 2 + @as(f32, @floatFromInt(n - 1)) * bubble.pitch; +} + +fn paperWidth(u: ui.Ui, x: Text) f32 { + var w: f32 = 0; + for (wrap(u, x.text, bubble.chars)) |line| w = @max(w, runsWidth(u, line)); + return @min(w + 2 * bubble.pad, bubble.max_w); +} + +/// How wide `words.runs` sets `text`. +fn runsWidth(u: ui.Ui, text: []const u8) f32 { + var w: f32 = 0; + var parts_ = std.mem.splitScalar(u8, text, '`'); + var code = false; + while (parts_.next()) |part| : (code = !code) w += if (code) u.width(.mono, theme.size.mono.value, part) else u.width(.sans, theme.size.sans.caption, part); + return w; +} + +/// `text` in lines of at most `chars` characters (a newline breaks one too), +/// broken at spaces; a code span broken across two lines is closed and opened again. +fn wrap(u: ui.Ui, text: []const u8, chars: usize) []const []const u8 { + var lines: std.ArrayList([]const u8) = .empty; + var paragraphs = std.mem.splitScalar(u8, text, '\n'); + while (paragraphs.next()) |para| { + var line: std.ArrayList(u8) = .empty; + var count: usize = 0; + var code = false; + var ws = std.mem.splitScalar(u8, para, ' '); + while (ws.next()) |word| { + const n = visible(word); + if (count > 0 and count + 1 + n > chars) { + if (code) line.append(u.f.scratch, '`') catch {}; + lines.append(u.f.scratch, line.items) catch {}; + line = .empty; + count = 0; + if (code) line.append(u.f.scratch, '`') catch {}; + } + if (count > 0) line.append(u.f.scratch, ' ') catch {}; + line.appendSlice(u.f.scratch, word) catch {}; + count += n + @intFromBool(count > 0); + for (word) |ch| if (ch == '`') { + code = !code; + }; + } + lines.append(u.f.scratch, line.items) catch {}; + } + return lines.items; +} + +/// How many lines `wrap` makes of `text`. +fn lineCount(text: []const u8, chars: usize) usize { + var n: usize = 0; + var paragraphs = std.mem.splitScalar(u8, text, '\n'); + while (paragraphs.next()) |para| { + var count: usize = 0; + n += 1; + var ws = std.mem.splitScalar(u8, para, ' '); + while (ws.next()) |word| { + const w = visible(word); + if (count > 0 and count + 1 + w > chars) { + n += 1; + count = 0; + } + count += w + @intFromBool(count > 0); + } + } + return n; +} + +/// Its characters as shown: backticks are not. +fn visible(word: []const u8) usize { + const n = std.unicode.utf8CountCodepoints(word) catch word.len; + return n - std.mem.count(u8, word, "`"); +} + +/// The column over context `ctx`: add it after the panes and the lens and +/// before the ties (`ctx.ties`); the scene opens in the working frame, its +/// first beat usually `below` (the opening establishes everything). +pub fn column(s: *anim.Frame, ctx: anytype, options: Options) *Column { + const st = ctx.stage; + const working = st.last(); + var objs: [parts.len]?anim.Obj = .{ options.lens, options.lens, ctx.source, ctx.disasm, ctx.registers, ctx.stack, ctx.backtrace }; + if (working.band.h <= 0) objs[0] = null; + if (working.view.h <= 0) objs[1] = null; + if (working.backtrace.h <= 0) objs[6] = null; + var shelf: [parts.len]anim.Value = undefined; + var ghost: [parts.len]anim.Value = undefined; + for (&shelf, &ghost) |*a, *b| { + a.* = s.value(0); + b.* = s.value(0); + } + var standing: [parts.len]bool = undefined; + for (objs, &standing) |o, *is| is.* = o != null; + const col = s.new(Column{ + .cursor = ctx.cursor, + .stage = st, + .objs = objs, + .titles = .{ options.titles.band, options.titles.view, "", "disassembly", "registers", "stack", "backtrace" }, + .standing = standing, + .shelf = shelf, + .ghost = ghost, + .default = options.at, + .working = working, + .split = working, + }); + col.obj = s.custom(col, .{ .x = -640, .y = -360, .scale = ui.scale }); + s.play(.{col.obj.fadeIn()}, .{ .seconds = 0 }); + return col; +} + +test "a bubble's lines: at most forty characters, a code span kept whole on each" { + const n = lineCount("main puts open's arguments where the convention says: \"note\" in rdi, 0 (O_RDONLY) in rsi.", 40); + try std.testing.expectEqual(@as(usize, 3), n); + try std.testing.expectEqual(@as(usize, 2), lineCount("`syscall` crosses down.\nThe kernel answers.", 40)); + try std.testing.expectEqual(@as(usize, 4), visible("`rdi`,")); +} -- cgit v1.3