//! The developer console: a line editor, a short log, and the host commands //! (marks, clips, replay, sessions, field inspection). Lines the host does //! not know go to the sketch's `command`. const Console = @This(); const std = @import("std"); const abi = @import("abi"); const Host = @import("Host.zig"); const fields = @import("fields.zig"); const memory = @import("memory.zig"); const Sessions = @import("Sessions.zig"); pub const panel_height = 144; pub const Key = enum { left, right, home, end, backspace, delete, clear, tab, submit }; const Line = struct { bytes: [118]u8 = @splat(0), len: usize = 0 }; const host_commands = [_][]const u8{ "help", "overlay memory", "overlay sound", "get", "set", "reset", "save", "load", "snapshot", "recording", "marks", "clips", "play session", "record", "stop", "play", "pause", "step", "seek start", "seek end", "diff", "quit", "exit", "overlay timing", "sessions", "timing on", "timing off", "timing frame", "timing work", "timing reset", "timing stats", "export-session", "import", }; visible: bool = false, buffer: [96]u8 = @splat(0), len: usize = 0, cursor: usize = 0, lines: [5]Line = @splat(.{}), /// The mark `save`, `load`, `diff` and `record` use when given none. snapshot: Name = .of("1"), /// The clip `record`, `play`, `seek` and `step` use when given none. recording: Name = .of("0"), overlay_memory: bool = false, overlay_sound: bool = false, pub const Name = struct { bytes: [Sessions.max_name]u8 = undefined, len: usize = 0, pub fn of(text_: []const u8) Name { var n: Name = .{ .len = text_.len }; @memcpy(n.bytes[0..text_.len], text_); return n; } pub fn get(n: *const Name) []const u8 { return n.bytes[0..n.len]; } }; /// A mark or clip name: a word of at most `Sessions.max_name` bytes. fn nameOr(arg: ?[]const u8, default: *const Name) ![]const u8 { const n = arg orelse return default.get(); if (n.len > Sessions.max_name) return error.NameTooLong; return n; } pub fn text(self: *const Console) []const u8 { return self.buffer[0..self.len]; } pub fn insert(self: *Console, typed: []const u8) void { for (typed) |byte| { // Commands and the built-in font only need printable ASCII. if (byte < 32 or byte > 126 or byte == '`' or self.len == self.buffer.len) continue; std.mem.copyBackwards(u8, self.buffer[self.cursor + 1 .. self.len + 1], self.buffer[self.cursor..self.len]); self.buffer[self.cursor] = byte; self.cursor += 1; self.len += 1; } } /// Edits the line; `submit` returns it (valid until the next edit). pub fn edit(self: *Console, key: Key, extra: []const []const u8) ?[]const u8 { switch (key) { .left => self.cursor -|= 1, .right => self.cursor = @min(self.len, self.cursor + 1), .home => self.cursor = 0, .end => self.cursor = self.len, .clear => { self.len = 0; self.cursor = 0; }, .backspace => if (self.cursor > 0) { self.cursor -= 1; self.erase(); }, .delete => self.erase(), .tab => self.complete(extra), .submit => { const line = self.text(); // The bytes stay put until the next edit; only the length resets. self.len = 0; self.cursor = 0; if (std.mem.trim(u8, line, " ").len == 0) return null; self.print("> {s}", .{line}); return line; }, } return null; } fn erase(self: *Console) void { if (self.cursor == self.len) return; std.mem.copyForwards(u8, self.buffer[self.cursor .. self.len - 1], self.buffer[self.cursor + 1 .. self.len]); self.len -= 1; } fn complete(self: *Console, extra: []const []const u8) void { var first: ?[]const u8 = null; var common: usize = 0; var matches: [256]u8 = undefined; var used: usize = 0; var count: usize = 0; for ([_][]const []const u8{ &host_commands, extra }) |list| for (list) |candidate| { if (!std.mem.startsWith(u8, candidate, self.text())) continue; if (first) |previous| { var i: usize = 0; while (i < common and i < candidate.len and previous[i] == candidate[i]) : (i += 1) {} common = i; } else { first = candidate; common = candidate.len; } const match = std.mem.print(matches[used..], "{s} ", .{candidate}) catch continue; used += match.len; count += 1; }; if (first) |candidate| { self.cursor = self.len; self.insert(candidate[self.len..common]); if (count > 1) self.log(matches[0..used]); } else self.log("No completion. Type help for commands."); } pub fn log(self: *Console, message: []const u8) void { var rest = message; while (true) { std.mem.copyForwards(Line, self.lines[0..4], self.lines[1..5]); const line = &self.lines[4]; line.len = @min(rest.len, line.bytes.len); @memcpy(line.bytes[0..line.len], rest[0..line.len]); rest = rest[line.len..]; if (rest.len == 0) break; } } pub fn print(self: *Console, comptime fmt: []const u8, args: anytype) void { var buf: [512]u8 = undefined; self.log(std.mem.print(&buf, fmt, args) catch "(message too long)"); } /// Runs one line. Host commands first; anything else goes to the sketch. /// Returns events to replay after a seek, already restored to the snapshot. pub fn execute(self: *Console, host: *Host, line: []const u8, now: u64) ![]const abi.Event { const h = &host.timeline; var words = std.mem.tokenizeAny(u8, line, " \t"); const command = words.next() orelse return &.{}; const arg = words.next(); const rest = words.rest(); if (eq(command, "help")) { self.log("save|load|diff [MARK] snapshot MARK marks | record|play [CLIP] recording CLIP clips | stop | pause"); self.log("step N (frames) | seek start|end| | sessions | play session S [at SECS] | export-session [S] FILE | import FILE"); self.log("reset | get|set [] | overlay memory|sound | quit"); self.log("timing [on|off|frame|work|reset|stats] | overlay timing"); if (host.forward(self, line, now) == .unknown) self.log("Backtick hides the console. Tab completes."); return &.{}; } if (eq(command, "overlay")) { const name = arg orelse return error.ExpectedOverlay; if (rest.len != 0) return error.UnexpectedArgument; const flag = if (eq(name, "memory")) &self.overlay_memory else if (eq(name, "sound")) &self.overlay_sound else if (eq(name, "timing")) &host.timing.visible else return error.UnknownOverlay; flag.* = !flag.*; host.timing.dirty = true; self.print("{s} overlay: {s}", .{ name, if (flag.*) "on" else "off" }); } else if (eq(command, "timing")) { if (rest.len != 0) return error.UnexpectedArgument; if (eq(arg orelse "", "stats")) { self.print("Timing: last {d}/240 frames; frame includes present, work excludes present (wall clock).", .{host.timing.count}); inline for (.{ .frame, .work }) |metric| { const s = host.timing.stats(metric); self.print("{s}: avg {d:.3} ms | p90 {d:.3} ms | p99 {d:.3} ms | max {d:.3} ms", .{ @tagName(metric), s.mean, s.p90, s.p99, s.max }); } } else { try host.timing.command(arg); self.print("Timing overlay: {s}, graph: {t}, samples: {d}", .{ if (host.timing.visible) "on" else "off", host.timing.metric, host.timing.count }); } } else if (eq(command, "get")) { const path = arg orelse return error.ExpectedField; var buf: [160]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); fields.formatPath(host.state.layout, host.live(), path, &w) catch |err| switch (err) { error.UnknownField => return error.UnknownField, error.WriteFailed => {}, // shown cut off }; self.print("{s} = {s}", .{ path, w.buffered() }); } else if (eq(command, "set")) { const path = arg orelse return error.ExpectedField; const leaf = host.state.layout.find(path) orelse return error.UnknownField; if (rest.len == 0) return error.ExpectedValue; try stop(host); try fields.set(leaf, host.live(), std.mem.trim(u8, rest, " ")); self.print("{s} = {s}", .{ path, std.mem.trim(u8, rest, " ") }); } else if (eq(command, "quit") or eq(command, "exit")) { try stop(host); host.quit = true; } else if (eq(command, "reset")) { try stop(host); host.resetState(); self.log("Live state reset. Snapshots are kept."); } else if (eq(command, "snapshot") or eq(command, "recording")) { const n = try nameOr(arg orelse return error.ExpectedName, &self.snapshot); (if (eq(command, "snapshot")) &self.snapshot else &self.recording).* = .of(n); } else if (eq(command, "save")) { const n = try nameOr(arg, &self.snapshot); try stop(host); _ = try host.sessions.mark(n, .mark, host.live()); self.print("Saved snapshot {s}.", .{n}); } else if (eq(command, "load")) { const n = try nameOr(arg, &self.snapshot); const key = try loadMark(host, n); defer key.free(host.gpa); try stop(host); try h.restore(key); self.print("Loaded snapshot {s}.", .{n}); } else if (eq(command, "record")) { const n = try nameOr(arg, &self.recording); const from = self.snapshot.get(); try stop(host); // An unused mark captures the current state; an existing one is // restored, so several clips can branch from exactly those bytes. const k = if (try host.sessions.findMark(from) == null) try host.sessions.mark(from, .mark, host.live()) else blk: { const key = try loadMark(host, from); defer key.free(host.gpa); try h.restore(key); break :blk try host.sessions.keyframe(.jump, host.live()); }; // The input held now is restored first in the clip (Host.restoredInput). h.restored = true; try host.sessions.startClip(n, k); h.startRecording(); self.recording = .of(n); self.print("Started recording {s} from snapshot {s}.", .{ n, from }); } else if (eq(command, "play") and arg != null and eq(arg.?, "session")) { var more = std.mem.tokenizeAny(u8, rest, " \t"); const index = std.fmt.parseInt(u64, more.next() orelse return error.ExpectedSession, 10) catch return error.InvalidSession; var at: ?u64 = null; if (more.next()) |word| { if (!eq(word, "at")) return error.UnexpectedArgument; const seconds = std.fmt.parseFloat(f64, more.next() orelse return error.ExpectedPosition) catch return error.InvalidPosition; at = @intFromFloat(@max(0, seconds) * std.time.ns_per_s); } try stop(host); return self.playSession(host, index, at, now); } else if (eq(command, "play")) { const n = try nameOr(arg, &self.recording); try stop(host); try loadClip(host, n); try h.play(now); self.recording = .of(n); self.print("Playing recording {s}.", .{n}); self.warnBuild(host); } else if (eq(command, "stop")) { try stop(host); } else if (eq(command, "pause")) { if (h.mode != .playing and h.mode != .paused) return error.NotReplaying; h.pause(now); } else if (eq(command, "step") or eq(command, "seek")) { const value = arg orelse return error.ExpectedPosition; if (h.mode == .live or h.mode == .recording) { try stop(host); try loadClip(host, self.recording.get()); try h.play(now); self.warnBuild(host); } if (eq(command, "step")) return h.step(std.fmt.parseInt(i64, value, 10) catch return error.InvalidPosition); if (eq(value, "start")) return h.seekCount(0); if (eq(value, "end")) return h.seekCount(h.events.items.len); const ms = std.fmt.parseInt(u64, value, 10) catch return error.InvalidPosition; return h.seekTime(ms *| std.time.ns_per_ms); } else if (eq(command, "diff")) { const n = try nameOr(arg, &self.snapshot); var arena: std.heap.ArenaAllocator = .init(host.gpa); defer arena.deinit(); const saved = try markState(host, arena.allocator(), n); const diff = memory.compareKept(saved.layout, host.state.layout, host.live(), saved.bytes); if (diff.first) |first| { var buf: [96]u8 = undefined; var w: std.Io.Writer = .fixed(&buf); first.leaf.name(first.offset, &w) catch {}; self.print("Live vs snapshot {s}: {d} differing values, first {s}", .{ n, diff.count, w.buffered() }); } else self.print("Live vs snapshot {s}: same", .{n}); } else if (eq(command, "sessions")) { if (arg != null) return error.UnexpectedArgument; try self.listSessions(host); } else if (eq(command, "export-session")) { const s = &host.sessions; const first = arg orelse return error.ExpectedFile; const index = if (rest.len == 0) s.session else std.fmt.parseInt(u64, first, 10) catch return error.InvalidSession; const path = if (rest.len == 0) first else std.mem.trim(u8, rest, " \t"); try s.exportSession(index, path); self.print("Exported session {d} to {s}.", .{ index, path }); } else if (eq(command, "import")) { const path = arg orelse return error.ExpectedFile; if (rest.len != 0) return error.UnexpectedArgument; const s = &host.sessions; const first = try s.import(path); const n = try s.count(.sessions); self.print("Imported {s} as session {d}..{d}; marks and clips are NAME@{s}.", .{ path, first, n - 1, std.fs.path.basename(path) }); } else if (eq(command, "marks") or eq(command, "clips")) { if (arg != null) return error.UnexpectedArgument; try self.listNamed(host, eq(command, "marks")); } else { // Sketch commands edit state outside the recorded input. try stop(host); switch (host.forward(self, line, now)) { .unknown => return error.UnknownCommand, .failed => return error.CommandFailed, .done => {}, } } return &.{}; } pub fn draw(self: *const Console, host: *Host, out: *std.ArrayList(abi.Command), arena: std.mem.Allocator) !void { const ink: abi.Color = .{ .r = 230, .g = 255, .b = 230 }; const hint: abi.Color = .{ .r = 145, .g = 220, .b = 150 }; const top = @as(f32, @floatFromInt(host.canvas[1])) - panel_height; const width: f32 = @floatFromInt(host.canvas[0]); const h = &host.timeline; try out.append(arena, .{ .rect = .{ .dst = .{ .x = 0, .y = top, .w = width, .h = panel_height }, .color = .{ .r = 24, .g = 28, .b = 28 } } }); const s = &host.sessions; const playing = h.mode == .playing or h.mode == .paused; const frame = if (playing) (if (h.key) |k| k.frame else 0) + h.fed else s.frames; const at = (if (playing) h.position else s.last_time -| s.first_time) / std.time.ns_per_s; const status = try std.fmt.allocPrint(arena, "{s} | {t} | session {d} frame {d} ({d}:{d:0>2}) | mark {s} | clip {s} | rec {t}", .{ host.name, h.mode, if (playing) h.session orelse s.session else s.session, frame, at / 60, at % 60, self.snapshot.get(), self.recording.get(), s.mode(), }); try out.append(arena, .{ .text = .{ .x = 12, .y = top + 8, .scale = 1, .color = hint, .bytes = status } }); for (&self.lines, 0..) |*line, i| { try out.append(arena, .{ .text = .{ .x = 12, .y = top + 28 + @as(f32, @floatFromInt(i)) * 18, .scale = 1, .color = ink, .bytes = line.bytes[0..line.len] } }); } try out.append(arena, .{ .text = .{ .x = 12, .y = top + 122, .scale = 1, .color = ink, .bytes = try std.fmt.allocPrint(arena, "> {s}", .{self.text()}) } }); try out.append(arena, .{ .rect = .{ .dst = .{ .x = @floatFromInt(28 + self.cursor * 8), .y = top + 120, .w = 1, .h = 12 }, .color = hint } }); } /// Where this run records, then the last sessions: index, start, frames, /// stretches (loads), and how it ended. fn listSessions(self: *Console, host: *Host) !void { const s = &host.sessions; switch (s.mode()) { .file => self.print("recording to {s}", .{s.path}), .memory => self.log("recording in memory (scripted run)"), .off => return self.log("not recording (release build: .record = true collects)"), } const n = try s.count(.sessions); var i = n -| 4; while (i < n) : (i += 1) { const m = try s.summary(i); const secs = std.time.epoch.EpochSeconds{ .secs = m.started / std.time.ns_per_s }; const day = secs.getEpochDay().calculateYearDay(); const md = day.calculateMonthDay(); const ds = secs.getDaySeconds(); var end_buf: [32]u8 = undefined; const end = if (i == s.session) "(this run)" else if (m.ended == 0) "(crashed)" else blk: { const d = (m.ended -| m.started) / std.time.ns_per_s; break :blk std.fmt.bufPrint(&end_buf, "{d}:{d:0>2}", .{ d / 60, d % 60 }) catch ""; }; self.print("{d}: {d:0>4}-{d:0>2}-{d:0>2} {d:0>2}:{d:0>2} builds {d} frames {d} {s} {s}", .{ i, day.year, md.month.numeric(), md.day_index + 1, ds.getHoursIntoDay(), ds.getMinutesIntoHour(), m.stretches, m.frames, end, m.from() }); } } /// Ends a clip being recorded or played: live from here. fn stop(host: *Host) !void { if (host.timeline.mode == .recording) try host.sessions.stopClip(); host.timeline.stop(); } /// The keyframe of the newest mark `n`, or of mark number K for "#K". pub fn loadMark(host: *Host, n: []const u8) !Sessions.Loaded { const s = &host.sessions; const found = if (n.len > 1 and n[0] == '#') try s.markAt(std.fmt.parseInt(u64, n[1..], 10) catch return error.InvalidName) else try s.findMark(n) orelse return error.EmptySnapshot; return s.load(found.session, found.key); } /// Mark `n`'s State in today's layout (`arena`'s), and the layout it was /// taken in: compare them over the leaves migration kept (`memory.compareKept`). pub fn markState(host: *Host, arena: std.mem.Allocator, n: []const u8) !struct { bytes: []u8, layout: memory.Layout } { const key = try loadMark(host, n); defer key.free(host.gpa); const bytes = try arena.alignedAlloc(u8, .fromByteUnits(memory.page), host.state.layout.size); const layout = try memory.restore(arena, key.layout, key.state, host.state.layout, bytes, host.timeline.defaults); return .{ .bytes = bytes, .layout = layout }; } /// Makes clip `n` the one the timeline plays: its keyframe and frames. fn loadClip(host: *Host, n: []const u8) !void { const s = &host.sessions; const clip = try s.findClip(n) orelse return error.EmptyRecording; const key = try s.load(clip.session, clip.key); errdefer key.free(host.gpa); var events: std.ArrayList(abi.Event) = .empty; errdefer events.deinit(host.gpa); // A clip a crash left open ends where its session does. const end = if (clip.end != 0) clip.end else (try s.summary(clip.session)).frames; try s.events(clip.session, key.batch, clip.start, end, &events); host.timeline.load(key, events); } /// Plays session `index` from its start, or paused `at` nanoseconds into /// it: from the newest keyframe before then, replayed up to it. fn playSession(self: *Console, host: *Host, index: u64, at: ?u64, now: u64) ![]const abi.Event { const s = &host.sessions; const h = &host.timeline; if (index == s.session) try s.commit(.none); const sum = try s.summary(index); if (sum.keys == 0) return error.EmptyRecording; const t0 = (try s.keyAt(index, 0)).time; const k = if (at) |t| try s.keyBefore(index, .time, t0 + t) orelse 0 else 0; const key = try s.load(index, k); errdefer key.free(host.gpa); var events: std.ArrayList(abi.Event) = .empty; errdefer events.deinit(host.gpa); try s.events(index, key.batch, key.frame, sum.frames, &events); var checks: @TypeOf(h.checks) = .empty; errdefer checks.deinit(host.gpa); for (k + 1..sum.keys) |j| { const later = try s.keyAt(index, j); try checks.append(host.gpa, .{ .frame = later.frame, .key = j, .observed = switch (later.why) { .periodic, .mark, .before_reload, .exit => true, else => false, } }); } h.load(key, events); h.session = index; h.checks = checks; try h.play(now); self.print("Playing session {d} from frame {d}.", .{ index, key.frame }); if (key.build != host.build or !eq(key.source, host.source)) self.print("session {d} frame {d} was built from {s}; replaying with {s}", .{ index, key.frame, key.source, host.source }); if (at) |t| return h.seekTime((t0 + t) -| h.base); return &.{}; } /// A replay of a clip made by other code may diverge: say so. fn warnBuild(self: *Console, host: *const Host) void { const key = host.timeline.key orelse return; if (key.build != 0 and host.build != 0 and key.build != host.build) self.log("Warning: recorded by another build of the sketch; the replay may differ."); } /// The last marks or clips: index, name, session and frame. fn listNamed(self: *Console, host: *Host, marks: bool) !void { const s = &host.sessions; const n = try s.count(if (marks) .marks else .clips); if (n == 0) return self.log(if (marks) "No marks: save NAME makes one." else "No clips: record NAME makes one."); var i = n -| 5; while (i < n) : (i += 1) { const e = if (marks) try s.markAt(i) else try s.clipAt(i); const key = try s.load(e.session, e.key); defer key.free(host.gpa); const label = e.name(); if (marks) { self.print("#{d} {s}: session {d} frame {d}", .{ i, label, e.session, key.frame }); } else self.print("#{d} {s}: session {d} frames {d}..{d}", .{ i, label, e.session, e.start, e.end }); } } fn eq(a: []const u8, b: []const u8) bool { return std.mem.eql(u8, a, b); } test "line editing, completion and submission" { var c: Console = .{}; c.insert("scen"); _ = c.edit(.tab, &.{ "scene room", "scene gallery" }); try std.testing.expectEqualStrings("scene ", c.text()); c.insert("`room"); try std.testing.expectEqualStrings("scene room", c.text()); _ = c.edit(.home, &.{}); _ = c.edit(.delete, &.{}); try std.testing.expectEqualStrings("cene room", c.text()); const line = c.edit(.submit, &.{}).?; try std.testing.expectEqualStrings("cene room", line); try std.testing.expectEqualStrings("", c.text()); try std.testing.expect(c.edit(.submit, &.{}) == null); } test "timing console controls and validation" { var host: Host = undefined; host.timing = .{}; var console: Console = .{}; _ = try console.execute(&host, "timing work", 0); try std.testing.expect(host.timing.visible and host.timing.metric == .work); _ = try console.execute(&host, "overlay timing", 0); try std.testing.expect(!host.timing.visible); host.timing.add(.{ .frame = 17000000, .work = 500000 }); _ = try console.execute(&host, "timing stats", 0); const last = console.lines[console.lines.len - 1]; try std.testing.expect(std.mem.indexOf(u8, last.bytes[0..last.len], "p99 0.500 ms") != null); try std.testing.expectError(error.UnexpectedArgument, console.execute(&host, "timing on extra", 0)); try std.testing.expect(!host.timing.visible); try std.testing.expectError(error.ExpectedTimingOnOffFrameWorkResetStats, console.execute(&host, "timing bogus", 0)); _ = try console.execute(&host, "timing reset", 0); try std.testing.expectEqual(@as(usize, 0), host.timing.count); }