From 9656105cb4c902213f281e658dd88286cc2df8ed Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Fri, 13 Nov 2026 15:10:16 -0300 Subject: debugger: link register hints and profile smooth native rendering --- gui/README.md | 28 ++++++++++++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) (limited to 'gui/README.md') diff --git a/gui/README.md b/gui/README.md index 36e4a1c..b77a546 100644 --- a/gui/README.md +++ b/gui/README.md @@ -14,7 +14,7 @@ zig build run -Doptimize=ReleaseFast -- --fresh ``` Use the repository's Zig toolchain and existing sibling `sketchbook` and `pardes` -checkouts (Sketchbook `409c1ac` or newer for native backdrop filtering). Keep the +checkouts (Sketchbook `d307463` or newer for native profiling and upload fixes). Keep the installed `ztrace` beside `ztrace-gui`. ## Controls @@ -69,7 +69,8 @@ Wide windows keep code beside registers and memory beside stack. Smaller windows stack these panes; wheel over a header/gutter or use PageUp/PageDown to reach them. Font scaling changes drawing scale, geometry, visible rows and pointer hit regions; it never changes the native window dimensions or backing size. Every new -execution stop reveals PC and its source group. Manual scrolling lasts until the +execution stop reveals PC and its source group. Nearby scrolling settles in +200 ms using elapsed time, including when the frame rate changes. Manual scrolling lasts until the next stop; an explicit address jump stays pinned until Follow is enabled. Stack, memory and disassembly navigation span the **entire selected mapping**. @@ -97,6 +98,8 @@ including `lea`, using the selected stop's registers only at its PC. RIP-relativ and absolute addresses work on other rows too. Future/past register values, segment overrides and 32-bit addressing are not inferred. Truncated brackets have no hidden hit target. These links work in executable lenses too. +Address values in the right-hand register hints use the same hover and mouse +actions, at the displayed register width. Ordinary scalar hints stay inactive. Memory's two header controls choose 8/16/32/64-bit groups and hexadecimal, unsigned, signed or floating-point values (little endian). `memory-format SIZE @@ -198,3 +201,24 @@ python3 gui/test/restart.py --native This checks the actual SDL window dimensions across zoom levels, in addition to the headless checks included in `zig build test`. + +## Frame profiling + +Tracy is optional and shared with Sketchbook. A normal build has no Tracy client. +To measure native scrolling, lenses and live stepping: + +```sh +cd gui +zig build -Doptimize=ReleaseFast -Dtracy=/absolute/path/to/tracy +cd .. +python3 gui/bench/frames.py --tracy /absolute/path/to/tracy --out /tmp/ztrace-frames +# Repeat with --size 1440x900 or --size 800x700 --zoom 200. +``` + +The checkout needs `build-capture/tracy-capture` and +`build-csvexport/tracy-csvexport`. The harness writes a reproducible input script, +`.tracy` capture, event CSV and percentile summary. It excludes the first two +seconds from warm interaction statistics. Host frame/presentation times include +VSync and driver waits; GUI `draw` measures construction of drawing commands. +Source loading and debugger transition capture have separate measurements in +[the benchmark results](bench/RESULTS.md). Rebuild without `-Dtracy` for ordinary use. -- cgit v1.3