diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 73 |
1 files changed, 71 insertions, 2 deletions
@@ -93,7 +93,10 @@ trackpad's or a touch screen's pinch arrives as ctrl+wheel with no key events at all. `update` is called once per frame, with that frame's events ending in its tick, live and replayed alike; in `update`, `input.now` and `input.dt` come from that tick (`dt` read back from the tick's f32 -seconds, so a replay sees the same bits). `input.mouse_x`/`buttons`/`held` +seconds, so a replay sees the same bits). Interactive Wayland frames use the +display-paced clock for update and draw automatically; unsupported backends use +wall time, and the browser uses its animation-frame timestamp. +`input.mouse_x`/`buttons`/`held` follow the events fed so far. So time-driven and pointer-driven sketches replay exactly. Fields no event carries (`width`, `window_width`, `console`, `frame`) are not replayed: a sketch that reads them in `update` @@ -609,7 +612,7 @@ object. replay may then diverge. - **Console and overlays.** `get`/`set <field path>` (`get` of a vector, array or struct shows its values, in memory order), snapshots, recordings and - the memory and scope overlays come from the host; unknown lines go to the + the memory, scope and frame timing overlays come from the host; unknown lines go to the sketch. Paths index arrays and vector lanes: `get pos[0]`, `set boids.buffer[3].pos[1] 20`. `diff N` compares live state with snapshot N leaf by leaf, so padding (a Debug `@Vector`'s spare lane) @@ -1015,6 +1018,72 @@ printf 'screenshot\n' | 9p -a unix!/tmp/drat.sock write ctl printf 'quit\n' | 9p -a unix!/tmp/drat.sock write ctl ``` +The native host's `timing` command toggles a scrolling graph with average, p90 +and p99 in milliseconds. `timing on|off` sets visibility; +`timing frame|work` selects the graph and shows it; `overlay timing` also toggles. +`timing stats` prints current average/p90/p99/maximum; `timing reset` clears history +without changing visibility or metric. Collection continues while hidden. +Readouts refresh about four times a second from fixed text buffers. All glyphs +reuse one immutable atlas texture, so changing values neither rasterizes text +nor switches textures per digit. Fixed vertex/index arrays batch the entire +panel, graph and text into one geometry draw, without per-frame overlay allocation. +Percentiles use nearest rank over the last 240 individual frames. A separate +fixed graph ring holds 240 peaks, each over eight frames: eight times slower +scrolling, with single-frame spikes preserved across 1920 frames. Its scale +label updates when the peak range changes. Frame measures wall-clock cadence +between completed host frames, including pacing, event/9P polling and present. +Work measures update/draw through the deferred 2D command flush, before present. +Both include visible overlays and screenshot capture and use real time even +during replay/export. These are not GPU hardware timestamps, and frame can +include vsync waits. No GPU synchronization is added. Test with +`zig build test-timing`. + +The read-only 9P file `timing-trace` exports paired raw samples as CSV: +`index,frame_ns,work_ns,outside_work_ns`. Indices start at zero within the captured +history, oldest first. `outside_work_ns` is saturating `frame_ns - work_ns`, including +pacing, polling, presentation and cleanup; it is not a hardware GPU duration. Each +open pins the bounded timing history, so subsequent frames or `timing reset` +cannot change a partially read trace. It works without `--profile-gpu`: +`9p -a unix!/tmp/drat.sock read timing-trace > timing.csv`. + +For compositor/video measurements, launch with `--timing-marker`. This opt-in +marker is drawn last, independently of the timing overlay: 80 black/white cells, +each 4×8 canvas pixels, at the bottom-left (320×8 total). Cells encode, LSB-first, +16-bit magic `0xD3A7`, the low 32 bits of `Input.frame`, then the low 32 bits of +`Input.now` in whole milliseconds. It identifies submitted frames and draw +sample times in captured video; repeated decoded IDs reveal repeated presented +frames. Decode at canvas scale, accounting for any window/compositor scaling. +The marker is omitted when the canvas is smaller than 320×8 and is disabled by +default. `zig build test-timing` checks its encoding, placement and counter wrap. + +On Wayland, `presentation-trace` provides immutable CSV snapshots of +`wp_presentation` feedback: frame ID, sample time, request time, presented/discarded +result, presentation timestamp, refresh period, sequence and flags. Status and +clock metadata make unsupported backends explicit. `commit_ns` is the feedback +request time before present, not an intercepted surface commit. Only subtract +timestamps in the same clock domain; sample time uses SDL's elapsed clock. +Feedback attaches to the next surface commit, which the binary marker lets a +compositor capture independently verify. + +Interactive Wayland windows use this feedback to pace submissions and sample +one shared frame clock before update and draw. Ordinary `Input.now`, tick events +and `Input.dt` therefore follow display refresh automatically; sketches need no +separate rendering clock or animation correction. A tick never precedes the +previous frame or its queued input, so newly arrived input can move it slightly +past the scheduled instant. Recording stores these exact ticks; replay, scripts +and export retain their existing clocks. The browser already uses the +`requestAnimationFrame` timestamp for its shared update/draw clock. +Without usable feedback, rendering falls back to SDL's normal presentation and +wall-clock ticks. Hidden/minimized windows keep servicing controls but skip +animation and drawing until visible again. +The implementation is `src/host/Presentation.zig`, including the Wayland callbacks +and trace writer. `zig build test-presentation` checks its clock and feedback +behavior. Linux builds require `wayland-scanner` plus the `wayland-client` +development package and pkg-config metadata. The build generates the protocol +header/tables from the vendored XML and translates the header into Zig bindings; +only the generated protocol tables are compiled as C. + + `ctl` accepts complete console command lines (up to 4096 bytes per write), including game commands and host `set`, `get`, `pause`, `step`, `seek`, and `quit`. Errors return as 9P errors. `log` exposes the console's latest five lines; |
