summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md73
1 files changed, 71 insertions, 2 deletions
diff --git a/README.md b/README.md
index eb82bda..298dde4 100644
--- a/README.md
+++ b/README.md
@@ -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;