summaryrefslogtreecommitdiff
path: root/vendor/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 20:31:59 -0300
committerGabriel Schneider <[email protected]>2026-11-16 20:31:59 -0300
commit82fca5c9f29124f37f6dcd08e73e6999ce44a69d (patch)
treeb3d5487659aa933d47699e5e420fa6140b0b75f3 /vendor/README.md
parente77b01d4b5504cea08a3f88cf8502897d868a1d3 (diff)
downloadsketchbook-82fca5c9f29124f37f6dcd08e73e6999ce44a69d.tar.gz
sketchbook-82fca5c9f29124f37f6dcd08e73e6999ce44a69d.zip
Add display-paced frame timing and presentation feedback in Zig
Diffstat (limited to 'vendor/README.md')
-rw-r--r--vendor/README.md21
1 files changed, 21 insertions, 0 deletions
diff --git a/vendor/README.md b/vendor/README.md
index 2d01105..c23a785 100644
--- a/vendor/README.md
+++ b/vendor/README.md
@@ -8,3 +8,24 @@ Single-file codecs, vendored unchanged; `codecs.c` compiles them for the host.
| `cgltf.h` | https://github.com/jkuhlmann/cgltf | 1.15, commit `85cd62382dfea638278962690cf515023f33ed00` (MIT, license in header) |
`cgltf.c` compiles the unchanged cgltf header for the optional `gltf` module.
+
+`presentation-time/presentation-time.xml` is the Wayland presentation-time v3
+protocol description (the client binds v1; its license is included in the XML).
+On Linux, `build.zig` runs `wayland-scanner` to generate a client header and C
+protocol tables in the build cache, then translates that header into the existing
+Zig `c` module alongside SDL. No generated C/header files are checked in.
+
+All handwritten callbacks, resource ownership, clock conversion, pacing and trace
+formatting live in `src/host/Presentation.zig`. Run `zig build test-presentation`
+(or `zig build test-timing`) from the project root to test them. Linux builds need
+`wayland-scanner` and the `wayland-client` development package.
+
+The trace uses a private event queue dispatched on the SDL thread. Per-frame
+feedback objects are owned by libwayland; our pending slots and completed-record
+ring are fixed capacity. CSV `commit_ns` timestamps the feedback request before
+`SDL_RenderPresent`, rather than intercepting `wl_surface.commit`; the protocol
+associates feedback with the next commit of the SDL surface. Presented times,
+refresh periods, sequence numbers and flags are supplied by the compositor.
+`sample_ms` is the draw sample clock in SDL's epoch; `commit_ns` and `presented_ns` use the
+advertised protocol clock. Discarded rows have no presentation timestamp. A
+trace snapshot reports pending requests, exhausted slots and its retention limit.