//! 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`,")); }