diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-10 14:48:26 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-10 15:14:31 -0300 |
| commit | 7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb (patch) | |
| tree | a6add92cd4dcbbf4c31cd1ce989d99b190258353 /anim/src/hexdump.zig | |
| parent | ed46c51fe127377eb1fde8dee83da984e0f61860 (diff) | |
| download | computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.tar.gz computeranim-7e9bf9e6e85c6c6e7a400d4fa0b43b77133ed3cb.zip | |
canim: animations of recordings, as a debugger's whole context with a lens beside it
A package of its own (anim/), on sketchbook's anim module and pardes's
syntax. A scene opens a recording, takes a cursor into it, and declares
blocks that read the moment the cursor is at: the state column (registers
each followed as a pointer and inked by where it points, the stack
telescope, the backtrace), the program column (the whole source, the
disassembly in address order, and the scene's lens: a node-link list over
a hexdump of its heap, array cells, a call tree, a syscall crossing), and
ties between them. Motion is a step told as a sentence (the line fires,
its effects cascade a level at a time, the mark moves on last), timed by
what the step contains; walk, hurry and sprint pace a loop. Five scenes
from real recordings of fib, a linked list, a sort and syscalls.
First drafts, by the agent's own handover: the frame of the design's
second revision, the hexdump lens and the ties; no disassembly
annotations, no gallery, scenes not yet reviewed against the mocks.
Diffstat (limited to 'anim/src/hexdump.zig')
| -rw-r--r-- | anim/src/hexdump.zig | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/anim/src/hexdump.zig b/anim/src/hexdump.zig new file mode 100644 index 0000000..e4b0908 --- /dev/null +++ b/anim/src/hexdump.zig @@ -0,0 +1,114 @@ +//! Memory as a hexdump, for a lens that shows what its idea is made of: an +//! address gutter, sixteen bytes a row, the same bytes as text; and every +//! run of bytes marked as what it is, from the types of what the program's +//! pointers reach: a struct's number plain, its pointer in the ink of +//! where it points, the allocator's own bytes between allocations faint, +//! bytes never observed two dots. A line under a run says which field it +//! is (the legend is in the tag). Bytes a step wrote are struck here a +//! beat before the idea drawn from them changes: the words are the cause. +//! Reads `Moment.read` (with what is known), `Moment.allocation`, and the +//! recording's types. +const std = @import("std"); +const sk = @import("sketch"); +const anim = @import("anim"); +const ui = @import("ui.zig"); +const cursors = @import("cursor.zig"); +const contexts = @import("context.zig"); +const Recording = @import("Recording.zig"); +const objects = @import("objects.zig"); +const theme = ui.theme; +const Rect = ui.Rect; +const t = theme.color.text; +const m = theme.metric.context; +const size = theme.size.mono.context; +const adv = size * 3 / 5; +/// A byte's two digits, and the gap to the next; a wider one in the middle of a row. +const pitch = 28; +const middle = 12; + +pub const Hexdump = struct { + cursor: cursors.Cursor, + box: Rect, + title: []const u8 = "heap", + /// The first row's address; rounded down to sixteen. + base: u64, + focus: bool = false, + + const Kind = enum { number, pointer, allocated, allocator, unknown }; + + pub fn draw(g: *const Hexdump, f: *sk.Frame, at: anim.Placed) void { + const u: ui.Ui = .{ .f = f, .at = at }; + const now = g.cursor.now(at); + const rec = g.cursor.rec; + const body = u.panel(g.box.w, g.box.h, g.title, .{ .focus = g.focus, .note = "sixteen bytes a row \u{00b7} underlined: a field of a node; faint: the allocator's own" }); + const things = objects.reach(f.scratch, rec, now.moment(), null); + const rows: usize = @intFromFloat(@floor((body.h - 2 * m.pad) / m.row)); + const bytes_x = m.side + 14 * adv + 8; + const text_x = bytes_x + 16 * pitch + middle + 12; + for (0..rows) |row| { + const addr = (g.base & ~@as(u64, 15)) + row * 16; + const y = body.y + m.pad + @as(f32, @floatFromInt(row)) * m.row; + const base = theme.baseline(y, m.row, size); + _ = u.value(m.side, base, addr, true, .{ .ink = ui.rgb(contexts.ink(contexts.regionOf(now.moment(), addr))) }); + var is: [16]u8 = undefined; + var known: [16]bool = undefined; + now.moment().read(addr, &is, &known) catch return; + var was: [16]u8 = undefined; + var was_known: [16]bool = undefined; + now.before().read(addr, &was, &was_known) catch return; + // A word at a time: a mark, and a field's line, go under a run of bytes, not under each. + for (0..2) |half| { + const word = addr + half * 8; + const x = bytes_x + @as(f32, @floatFromInt(half)) * (8 * pitch + middle); + const span: Rect = .{ .x = x - 3, .y = y + 2, .w = 8 * pitch - 4 + 2, .h = m.row - 4 }; + @import("ties.zig").anchor(u, .{ .word = word }, span); + const landed = now.landed(.memory, 0); + const mark = u.struck(span, now.written(word, 8, .memory, 0)); + if (now.wasRead(word, 8) and now.writeAge(word, 8) != 0) u.readFrame(span, now.reading(.memory, 0)); + const kind = g.kindOf(things, now.moment(), word); + // What the eight bytes are, if they are an address: its ink. + const held = Recording.word(if (landed) now.moment() else now.before(), word, 8) catch null; + const region = if (held) |value| contexts.regionOf(now.moment(), value) else .none; + const color: ui.Color = if (mark) |struck| struck.ink else switch (kind) { + .pointer => if (region != .none) ui.rgb(contexts.ink(region)) else ui.rgb(t.dim), + .number => ui.rgb(t.primary), + .allocated => ui.rgb(t.dim), + .allocator, .unknown => ui.rgb(t.faint), + }; + for (0..8) |i| { + const n = half * 8 + i; + const bx = x + @as(f32, @floatFromInt(i)) * pitch; + if (!(if (landed) known[n] else was_known[n])) { + u.unknown(.{ .x = bx, .y = y, .w = 2 * adv, .h = m.row }); + continue; + } + const byte = if (landed) is[n] else was[n]; + u.text(if (mark != null) .mono_bold else .mono, size, bx, base, u.print("{x:0>2}", .{byte}), color); + // The same byte as text. + const tx = text_x + @as(f32, @floatFromInt(n)) * adv; + if (std.ascii.isPrint(byte) and byte != ' ') u.text(.mono, size, tx, base, &.{byte}, t.dim) else u.fill(.{ .x = tx + 4, .y = y + m.row / 2 - 2, .w = 4, .h = 4 }, t.faint); + } + // Which field: a line under the run, in the field's ink. + if (kind == .number or kind == .pointer) u.fill(.{ .x = x, .y = y + m.row - 3, .w = 8 * pitch - 4, .h = theme.stroke.rule }, if (kind == .pointer) theme.color.region.heap else t.primary); + } + } + u.veil(.{ .x = theme.stroke.rule, .y = body.y, .w = body.w - 2 * theme.stroke.rule, .h = body.h - theme.stroke.rule }, now.veil); + } + + /// What the word at `addr` is: a field of a struct the program's + /// pointers reach (by its type), other allocated bytes, the + /// allocator's own between allocations, or never observed. + fn kindOf(g: *const Hexdump, things: []const objects.Object, moment: Recording.Moment, addr: u64) Kind { + _ = g; + for (things) |o| { + if (!o.holds(addr)) continue; + for (o.type.record.fields) |field| if (o.addr + field.offset == addr) return if (field.type == .pointer) .pointer else .number; + return .allocated; + } + var bytes: [8]u8 = undefined; + var known: [8]bool = undefined; + moment.read(addr, &bytes, &known) catch return .unknown; + if (std.mem.indexOfScalar(bool, &known, true) == null) return .unknown; + return if ((moment.allocation(addr) catch null) != null) .allocated else .allocator; + } +}; |
