From 82fca5c9f29124f37f6dcd08e73e6999ce44a69d Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Mon, 16 Nov 2026 20:31:59 -0300 Subject: Add display-paced frame timing and presentation feedback in Zig --- src/host/Timing.zig | 169 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 src/host/Timing.zig (limited to 'src/host/Timing.zig') diff --git a/src/host/Timing.zig b/src/host/Timing.zig new file mode 100644 index 0000000..1e5d991 --- /dev/null +++ b/src/host/Timing.zig @@ -0,0 +1,169 @@ +//! Wall-clock frame history, independent of the sketch's replay clock. +const Timing = @This(); +const std = @import("std"); + +pub const capacity = 240; +pub const frames_per_column = 8; +pub const Metric = enum { frame, work }; +pub const Sample = struct { frame: u64 = 0, work: u64 = 0 }; +pub const Stats = struct { + mean: f64 = 0, + p90: f64 = 0, + p99: f64 = 0, + max: f64 = 0, +}; + +visible: bool = false, +metric: Metric = .frame, +samples: [capacity]Sample = @splat(.{}), +count: usize = 0, +next: usize = 0, +dirty: bool = true, +cached: [2]Stats = @splat(.{}), +labels: [4][96]u8 = undefined, +label_lengths: [4]usize = @splat(0), +label_elapsed: u64 = 0, +ceiling: f64 = 1.25, +graph: [capacity]Sample = @splat(.{}), +graph_count: usize = 0, +graph_next: usize = 0, +group_count: usize = 0, +group_peak: Sample = .{}, + +pub fn add(self: *Timing, sample: Sample) void { + self.samples[self.next] = sample; + self.next = (self.next + 1) % capacity; + self.count = @min(self.count + 1, capacity); + self.label_elapsed +|= sample.frame; + // Refresh text at most four times a second; collection never allocates or sorts. + if (self.label_elapsed >= 250 * std.time.ns_per_ms) { + self.dirty = true; + self.label_elapsed = 0; + } + self.group_peak.frame = @max(self.group_peak.frame, sample.frame); + self.group_peak.work = @max(self.group_peak.work, sample.work); + self.group_count += 1; + if (self.group_count == frames_per_column) { + self.graph[self.graph_next] = self.group_peak; + self.graph_next = (self.graph_next + 1) % capacity; + self.graph_count = @min(self.graph_count + 1, capacity); + self.group_count = 0; + self.group_peak = .{}; + } +} + +pub fn graphAt(self: *const Timing, index: usize) Sample { + std.debug.assert(index < self.graph_count); + return self.graph[(self.graph_next + capacity - self.graph_count + index) % capacity]; +} + +pub fn label(self: *const Timing, index: usize) []const u8 { + return self.labels[index][0..self.label_lengths[index]]; +} + +pub fn setLabel(self: *Timing, index: usize, comptime fmt: []const u8, args: anytype) void { + const text = std.mem.print(&self.labels[index], fmt, args) catch unreachable; + self.label_lengths[index] = text.len; +} + +pub fn sampleAt(self: *const Timing, index: usize) Sample { + std.debug.assert(index < self.count); + return self.samples[(self.next + capacity - self.count + index) % capacity]; +} + +pub fn value(sample: Sample, metric: Metric) u64 { + return switch (metric) { + .frame => sample.frame, + .work => sample.work, + }; +} + +pub fn ms(ns: u64) f64 { + return @as(f64, @floatFromInt(ns)) / std.time.ns_per_ms; +} + +pub fn stats(self: *const Timing, metric: Metric) Stats { + if (self.count == 0) return .{}; + var sorted: [capacity]u64 = undefined; + var total: f64 = 0; + for (sorted[0..self.count], 0..) |*v, i| { + v.* = value(self.sampleAt(i), metric); + total += ms(v.*); + } + const values = sorted[0..self.count]; + std.mem.sort(u64, values, {}, std.sort.asc(u64)); + return .{ + .mean = total / @as(f64, @floatFromInt(values.len)), + .p90 = ms(values[(values.len * 90 + 99) / 100 - 1]), + .p99 = ms(values[(values.len * 99 + 99) / 100 - 1]), + .max = ms(values[values.len - 1]), + }; +} + +pub fn command(self: *Timing, arg: ?[]const u8) !void { + if (arg) |name| { + if (std.mem.eql(u8, name, "on")) { + self.visible = true; + } else if (std.mem.eql(u8, name, "off")) { + self.visible = false; + } else if (std.mem.eql(u8, name, "reset")) { + self.* = .{ .visible = self.visible, .metric = self.metric }; + } else if (std.meta.stringToEnum(Metric, name)) |metric| { + self.metric = metric; + self.visible = true; + } else return error.ExpectedTimingOnOffFrameWorkResetStats; + } else self.visible = !self.visible; + self.dirty = true; +} + +test "timing history percentiles, wrap, reset and commands" { + var t: Timing = .{}; + try std.testing.expectEqual(@as(f64, 0), t.stats(.frame).p99); + t.add(.{ .frame = 1000000, .work = 500000 }); + try std.testing.expectEqual(@as(f64, 0.5), t.stats(.work).p90); + try t.command("reset"); + for (1..401) |i| t.add(.{ .frame = i * 1000000, .work = i * 1000 }); + try std.testing.expectEqual(capacity, t.count); + try std.testing.expectEqual(@as(u64, 161000000), t.sampleAt(0).frame); + const s = t.stats(.frame); + try std.testing.expectEqual(@as(f64, 280.5), s.mean); + try std.testing.expectEqual(@as(f64, 376), s.p90); + try std.testing.expectEqual(@as(f64, 398), s.p99); + try std.testing.expectEqual(@as(f64, 400), s.max); + try t.command("work"); + try t.command("reset"); + try std.testing.expect(t.visible and t.metric == .work and t.count == 0); + try t.command(null); + try std.testing.expect(!t.visible); + try t.command("on"); + try std.testing.expect(t.visible); + try t.command("off"); + try std.testing.expect(!t.visible); + try std.testing.expectError(error.ExpectedTimingOnOffFrameWorkResetStats, t.command("bogus")); +} + +test "timing graph keeps peaks while scrolling eight times slower" { + var t: Timing = .{}; + for (0..7) |_| t.add(.{ .frame = 10, .work = 1 }); + try std.testing.expectEqual(@as(usize, 0), t.graph_count); + t.add(.{ .frame = 100, .work = 5 }); + try std.testing.expectEqual(@as(usize, 1), t.graph_count); + try std.testing.expectEqual(Sample{ .frame = 100, .work = 5 }, t.graphAt(0)); + for (0..capacity * frames_per_column) |_| t.add(.{ .frame = 20, .work = 2 }); + try std.testing.expectEqual(capacity, t.graph_count); + try std.testing.expectEqual(Sample{ .frame = 20, .work = 2 }, t.graphAt(0)); + try t.command("reset"); + try std.testing.expectEqual(@as(usize, 0), t.graph_count); + try std.testing.expectEqual(@as(usize, 0), t.group_count); +} + +test "timing readouts refresh quarterly and use fixed text storage" { + var t: Timing = .{}; + t.dirty = false; + for (0..24) |_| t.add(.{ .frame = 10 * std.time.ns_per_ms }); + try std.testing.expect(!t.dirty); + t.add(.{ .frame = 10 * std.time.ns_per_ms }); + try std.testing.expect(t.dirty); + t.setLabel(0, "p99 {d:.3}", .{@as(f64, 0.123)}); + try std.testing.expectEqualStrings("p99 0.123", t.label(0)); +} -- cgit v1.3