pdf-scroll-bench takes --cell WxH, --slow-frames N and one tall page, and reports the rasters' peak bytes

A single tall page is four screenfuls of strip as much as four pages
are, so the gate asks for the strip, not the page count. --cell 16x32
is the same window on a 2x display, and peak_kib is the most the
pane's rasters, clean copies and spares held after any frame.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 74 insertions, 32 deletions

diff --git a/test/pdf_scroll_bench.zig b/test/pdf_scroll_bench.zig
index a4511dbe..166fa809 100644
--- a/test/pdf_scroll_bench.zig
+++ b/test/pdf_scroll_bench.zig
@@ -4,6 +4,7 @@
 //!   zig build pdf-scroll-bench -Doptimize=ReleaseFast -- --json
 //!   zig build pdf-scroll-bench -Doptimize=ReleaseFast -- --warmup 1 --reps 15
 //!   zig build pdf-scroll-bench -Doptimize=ReleaseFast -- --path other.pdf
+//!   zig build pdf-scroll-bench -Doptimize=ReleaseFast -- --cell 16x32  a 2x display
 //!   zig build pdf-scroll-bench -Doptimize=Debug -- --reps 1      the diagnosis
 //!   zig build pdf-scroll-bench -Dtracy=~/05-genizah/tracy        the zones
 //!
@@ -62,7 +63,7 @@ const gpa = std.heap.smp_allocator;
 // is what the tty shell actually ships.
 const bench_cols: u16 = 120;
 const bench_rows: u16 = 40;
-const bench_cell_pixels: pardes.CellPixels = .{ .w = 8, .h = 16 };
+const default_cell_pixels: pardes.CellPixels = .{ .w = 8, .h = 16 };
 
 /// config.wheel_rows is one cell per notch, so a notch is `cell_pixels.h`
 /// display pixels. 192 notches is ~3072px — between two and three fit-width
@@ -74,7 +75,7 @@ const slow_ticks_per_frame: usize = 1;
 /// The control row is a fixed wall of frames rather than a whole-document
 /// traversal: one notch per frame over a real document is tens of thousands of
 /// frames, and 240 already crosses several page boundaries at reading speed.
-const slow_frames: usize = 240;
+const default_slow_frames: usize = 240;
 /// Guard against a pathological document turning one row into a multi-minute
 /// run. Deterministic either way: the frame count is derived from layout.
 const max_frames: usize = 2048;
@@ -91,6 +92,10 @@ const Config = struct {
     /// Override `max_frames` for one run: a 5000-page manual is 2000 frames of
     /// travel per round, which is a fine scoreboard and a poor edit-run loop.
     frames: ?usize = null,
+    /// One cell in display pixels: 16x32 is the same window on a 2x display.
+    cell: pardes.CellPixels = default_cell_pixels,
+    /// Frames of the one-notch control row.
+    slow_frames: usize = default_slow_frames,
 };
 
 /// The bit-exact description of one scrolling run. `visual` is the invariant;
@@ -120,6 +125,9 @@ const Result = struct {
     total_ns: u64,
     rasterizations: u64,
     rasters_retained: u64,
+    /// Most bytes the pane's rasters held after any frame: every slot's
+    /// pixels, its clean copy, and the spare buffers kept for reuse.
+    peak_raster_bytes: u64,
     identity: Identity,
 };
 
@@ -174,13 +182,13 @@ pub fn main(init: std.process.Init) !void {
     // One untimed probe boot supplies the strip height every plan is sized
     // from, so the frame counts below are a property of the document and the
     // viewport rather than of the machine.
-    const travel = probeTravel(config.path);
+    const travel = probeTravel(config);
 
     const cap = config.frames orelse max_frames;
     const results = [_]Result{
-        try measure(config, planFor(.fling_down, travel, cap)),
-        try measure(config, planFor(.fling_reverse, travel, cap)),
-        try measure(config, planFor(.slow_scroll, travel, cap)),
+        try measure(config, planFor(.fling_down, travel, cap, config.slow_frames)),
+        try measure(config, planFor(.fling_reverse, travel, cap, config.slow_frames)),
+        try measure(config, planFor(.slow_scroll, travel, cap, config.slow_frames)),
     };
 
     if (config.json)
@@ -207,9 +215,19 @@ fn parseArgs(args: []const []const u8) Config {
         } else if (std.mem.eql(u8, args[i], "--frames") and i + 1 < args.len) {
             i += 1;
             config.frames = parseCount("--frames", args[i]);
+        } else if (std.mem.eql(u8, args[i], "--slow-frames") and i + 1 < args.len) {
+            i += 1;
+            config.slow_frames = parseCount("--slow-frames", args[i]);
+        } else if (std.mem.eql(u8, args[i], "--cell") and i + 1 < args.len) {
+            i += 1;
+            var it = std.mem.splitScalar(u8, args[i], 'x');
+            const w = parseCount("--cell", it.next() orelse "");
+            const h = parseCount("--cell", it.next() orelse "");
+            if (w > std.math.maxInt(u16) or h > std.math.maxInt(u16)) fatal("--cell {s} is too large", .{args[i]});
+            config.cell = .{ .w = @intCast(w), .h = @intCast(h) };
         } else fatal(
             "usage: pardes-pdf-scroll-bench [--json] [--warmup N] [--reps N]" ++
-                " [--path FILE] [--frames N]",
+                " [--path FILE] [--frames N] [--slow-frames N] [--cell WxH]",
             .{},
         );
     }
@@ -226,28 +244,35 @@ const Travel = struct {
     /// same benchmark and the report must not pretend otherwise.
     pages: usize,
     strip_px: u64,
+    /// The first frame of a fresh pane: opening the document and rasterizing
+    /// what it shows first. One sample, from the probe boot.
+    first_frame_ns: u64,
 };
 
-fn probeTravel(path: []const u8) Travel {
-    const core = bootCore(path) catch |err|
+fn probeTravel(config: Config) Travel {
+    const path = config.path;
+    const core = bootCore(config) catch |err|
         fatal("cannot boot a PDF pane on {s}: {t}", .{ path, err });
     defer core.deinit();
     var frame_arena = std.heap.ArenaAllocator.init(gpa);
     defer frame_arena.deinit();
+    const started = nowNs();
     _ = core.render(frame_arena.allocator()) catch |err|
         fatal("first render failed: {t}", .{err});
     drainEffects(core);
+    const first_frame_ns = nowNs() -| started;
     const pane = core.panes[0] orelse fatal("PDF pane disappeared", .{});
     if (pane.pdf == null) fatal("{s} did not open as a PDF", .{path});
     const pv = &pane.pdf.?;
-    if (pv.page_count < 4)
-        fatal("{s} has {d} pages; a fling benchmark needs at least 4", .{ path, pv.page_count });
     if (!pv.layout_valid or pv.document_height == 0)
         fatal("the pixel strip never laid out; is native_images/cell_pixels wired?", .{});
     // Exactly the clamp scrollPdfDocument enforces, so the last fling frame
     // lands on the document end instead of adding a no-op frame to the row.
-    const viewport_h: u64 = @as(u64, bench_rows -| pardes.BOX_H) * bench_cell_pixels.h;
-    const notch: f64 = @floatFromInt(bench_cell_pixels.h);
+    const viewport_h: u64 = @as(u64, bench_rows -| pardes.BOX_H) * config.cell.h;
+    // Four screenfuls of strip, in pages or in one tall page.
+    if (pv.document_height < 4 * viewport_h)
+        fatal("{s} is {d}px of strip; a fling benchmark needs at least four screenfuls", .{ path, pv.document_height });
+    const notch: f64 = @floatFromInt(config.cell.h);
     if (!std.math.isFinite(notch) or notch <= 0)
         fatal("a notch of {d} display pixels cannot size a fling", .{notch});
     const strip = @as(f64, @floatFromInt(pv.document_height -| viewport_h));
@@ -258,6 +283,7 @@ fn probeTravel(path: []const u8) Travel {
         .per_frame = notch * @as(f64, @floatFromInt(fling_ticks_per_frame)),
         .pages = pv.page_count,
         .strip_px = pv.document_height,
+        .first_frame_ns = first_frame_ns,
     };
 }
 
@@ -267,7 +293,7 @@ fn probeTravel(path: []const u8) Travel {
 /// The cap is applied before any arithmetic on the count, so a document the
 /// float division cannot describe still produces a runnable plan instead of an
 /// overflow.
-fn planFor(scenario: Scenario, travel: Travel, cap: usize) Plan {
+fn planFor(scenario: Scenario, travel: Travel, cap: usize, slow: usize) Plan {
     const wanted = travel.max_scroll / travel.per_frame;
     const whole: usize = if (std.math.isFinite(wanted) and wanted >= 1)
         @intFromFloat(@min(@as(f64, @floatFromInt(cap)), @ceil(wanted)))
@@ -282,15 +308,15 @@ fn planFor(scenario: Scenario, travel: Travel, cap: usize) Plan {
             .frames = @max(2, down),
             .down_frames = @max(1, down / 2),
         },
-        .slow_scroll => .{ .scenario = scenario, .frames = slow_frames, .down_frames = slow_frames },
+        .slow_scroll => .{ .scenario = scenario, .frames = slow, .down_frames = slow },
     };
 }
 
 /// A pane on a real multi-page document with the native pixel-strip path live
 /// and a genuine pixel viewport delivered the way a shell delivers one.
-fn bootCore(path: []const u8) !*pardes.Pardes {
+fn bootCore(config: Config) !*pardes.Pardes {
     const core = try pardes.Pardes.init(gpa, .{
-        .file = path,
+        .file = config.path,
         .cols = bench_cols,
         .rows = bench_rows,
     });
@@ -299,7 +325,7 @@ fn bootCore(path: []const u8) !*pardes.Pardes {
     core.update(.{ .resize = .{
         .cols = bench_cols,
         .rows = bench_rows,
-        .cell_pixels = bench_cell_pixels,
+        .cell_pixels = config.cell,
     } });
     drainEffects(core);
     return core;
@@ -318,9 +344,10 @@ fn measure(config: Config, plan: Plan) !Result {
     var expected: ?Identity = null;
     var rasterizations: u64 = 0;
     var rasters_retained: u64 = 0;
+    var peak_raster_bytes: u64 = 0;
 
     for (0..config.warmup + config.reps) |round| {
-        const core = try bootCore(config.path);
+        const core = try bootCore(config);
         defer core.deinit();
         var frame_arena = std.heap.ArenaAllocator.init(gpa);
         defer frame_arena.deinit();
@@ -355,6 +382,7 @@ fn measure(config: Config, plan: Plan) !Result {
             const elapsed = nowNs() -| started;
             total += elapsed;
             recorder.observe(frame, surface);
+            peak_raster_bytes = @max(peak_raster_bytes, rasterBytes(pv));
             // The same frame boundary src/tty/tty.zig marks, so a Tracy capture
             // of this benchmark reads like a capture of the real shell.
             pardes.frameMark();
@@ -388,10 +416,19 @@ fn measure(config: Config, plan: Plan) !Result {
         .total_ns = totals[totals.len / 2],
         .rasterizations = rasterizations,
         .rasters_retained = rasters_retained,
+        .peak_raster_bytes = peak_raster_bytes,
         .identity = expected.?,
     };
 }
 
+/// What the pane's rasters hold right now (untimed: outside the frame).
+fn rasterBytes(pv: anytype) u64 {
+    var total: u64 = 0;
+    for (pv.rasters[0..pv.rasters_len]) |raster| total += raster.rgba.len + raster.clean.len;
+    for (pv.spare[0..pv.spare_len]) |spare| total += spare.len;
+    return total;
+}
+
 /// Accumulates the two checksums across one run. Raster generations are
 /// rebased on the counter's value at run start so the trace describes the
 /// ORDER textures were produced in rather than absolute counter values, which
@@ -545,23 +582,24 @@ fn reportText(config: Config, travel: Travel, results: []const Result) void {
     std.debug.print(
         "{s}: {d} pages, {d}px strip at {d}x{d} cells of {d}x{d}px\n",
         .{
-            config.path, travel.pages,        travel.strip_px,     bench_cols,
-            bench_rows,  bench_cell_pixels.w, bench_cell_pixels.h,
+            config.path, travel.pages,  travel.strip_px, bench_cols,
+            bench_rows,  config.cell.w, config.cell.h,
         },
     );
+    std.debug.print("first frame of a fresh pane: {d}us\n", .{travel.first_frame_ns / 1000});
     std.debug.print(
         "warmup: {d}, sampled reps: {d}; every number is ONE FRAME (notch batch + render + drain)\n\n",
         .{ config.warmup, config.reps },
     );
-    std.debug.print("{s:<16} {s:>6} {s:>7} {s:>10} {s:>10} {s:>10} {s:>10} {s:>10} {s:>11} {s:>7} {s:>5}  {s:<16}  {s}\n", .{
-        "scenario",  "frames",  "notches", "min",
-        "median",    "p90",     "p99",     "max",
-        "total_us",  "rasters", "kept",    "visual",
-        "transport",
+    std.debug.print("{s:<16} {s:>6} {s:>7} {s:>10} {s:>10} {s:>10} {s:>10} {s:>10} {s:>11} {s:>7} {s:>5} {s:>9}  {s:<16}  {s}\n", .{
+        "scenario", "frames",    "notches", "min",
+        "median",   "p90",       "p99",     "max",
+        "total_us", "rasters",   "kept",    "peak_kib",
+        "visual",   "transport",
     });
     std.debug.print("{s}\n", .{"-" ** 160});
     for (results) |result| std.debug.print(
-        "{s:<16} {d:>6} {d:>7} {d:>10} {d:>10} {d:>10} {d:>10} {d:>10} {d:>11} {d:>7} {d:>5}  {x:0>16}  {x:0>16}\n",
+        "{s:<16} {d:>6} {d:>7} {d:>10} {d:>10} {d:>10} {d:>10} {d:>10} {d:>11} {d:>7} {d:>5} {d:>9}  {x:0>16}  {x:0>16}\n",
         .{
             result.name,
             result.frames,
@@ -574,12 +612,14 @@ fn reportText(config: Config, travel: Travel, results: []const Result) void {
             result.total_ns / 1000,
             result.rasterizations,
             result.rasters_retained,
+            result.peak_raster_bytes / 1024,
             result.identity.visual,
             result.identity.transport,
         },
     );
     std.debug.print(
-        "\n`rasters` counts MuPDF page rasterizations over one run; `kept` is the retained raster count at the end.\n" ++
+        "\n`rasters` counts MuPDF page rasterizations over one run; `kept` is the retained raster count at the end;\n" ++
+            "`peak_kib` is the most the pane's rasters, clean copies and spares held after any frame.\n" ++
             "`visual` pins presented pixels and placement and must never change; `transport` traces texture uploads.\n",
         .{},
     );
@@ -592,16 +632,17 @@ fn reportJson(io: std.Io, config: Config, travel: Travel, results: []const Resul
     var out: std.Io.Writer = .fixed(&storage);
     out.print(
         "{{\"benchmark\":\"pardes-pdf-scroll\",\"build\":\"{s}\",\"path\":\"{s}\"," ++
-            "\"pages\":{d},\"strip_px\":{d},\"warmup\":{d},\"reps\":{d},\"results\":[",
+            "\"pages\":{d},\"strip_px\":{d},\"first_frame_ns\":{d},\"warmup\":{d},\"reps\":{d},\"results\":[",
         .{
-            bench_config.core_optimize, config.path,   travel.pages,
-            travel.strip_px,            config.warmup, config.reps,
+            bench_config.core_optimize, config.path,           travel.pages,
+            travel.strip_px,            travel.first_frame_ns, config.warmup,
+            config.reps,
         },
     ) catch return;
     for (results, 0..) |result, i| out.print(
         "{s}{{\"scenario\":\"{s}\",\"frames\":{d},\"notches_per_frame\":{d}," ++
             "\"min_ns\":{d},\"median_ns\":{d},\"p90_ns\":{d},\"p99_ns\":{d},\"max_ns\":{d},\"total_ns\":{d}," ++
-            "\"rasterizations\":{d},\"rasters_retained\":{d},\"images\":{d}," ++
+            "\"rasterizations\":{d},\"rasters_retained\":{d},\"peak_raster_bytes\":{d},\"images\":{d}," ++
             "\"visual\":\"{x:0>16}\",\"transport\":\"{x:0>16}\"}}",
         .{
             if (i == 0) "" else ",",
@@ -616,6 +657,7 @@ fn reportJson(io: std.Io, config: Config, travel: Travel, results: []const Resul
             result.total_ns,
             result.rasterizations,
             result.rasters_retained,
+            result.peak_raster_bytes,
             result.identity.images,
             result.identity.visual,
             result.identity.transport,