A frame is timed at six different moments, and none of them is when it reaches the screen #1518

Open
opened 2026-11-18 01:53:47 +00:00 by mooki · 4 comments
Member

Type: measurement · Area: frame metrics, in the renderer and the host · Part of: #1493

TL;DR

Every tool that reports "frame time" reads a different moment of the frame, and not from the same clock: the FPS counter and the field data read the renderer's present entry, the frame trace reads the render thread, the frame log (and so the test farm's p99) reads the return of the present call, and the game's own time step reads the host. Only PresentMon and the driver's Reflex timings get near the screen. We propose one record per game frame, stamped from one clock, that every reader takes its number from, with the shown time added where the platform gives it.

Breakdown

  • Who it affects: everyone who compares frame numbers: pull requests that claim speed, the farm's gates, the field dashboard, players reading the counter, and the renderer rewrite's gates (#1493), which need numbers that mean the same thing in every arm.
  • What is wrong: there are six moments (table below) and none of the four we record ourselves is scan-out. Under frame generation the counter counts shown frames, the field summary counts game frames, and the frame log counts every present, made frames included, so the three disagree about one session. The Breakdown's parts belong to one thread and are scaled down when they add up to more than the frame.
  • What we propose: a ring with one record per game frame: an id, then stamps from one clock at each step the frame passes (simulation start, last submit handed over, present entry and return, render begin and end, GPU begin and end, swapchain acquire, queue present begin and end, shown time, number of made frames and when each was shown). The counter, the field summary, the frame log, the trace, the Breakdown and the Reflex markers are all computed from the ring.
  • What does not change: the host alone steps game time (the pacer issue covers that). The counter keeps showing the shown rate and "Base". Log and CSV columns stay readable by today's scripts, new ones go at the end. The first step changes no behaviour and no number a player sees.
  • How we would prove it: a game-free check that feeds one stream of made-up stamps to every reader and requires the same answers; then one windowed run on a Windows PC with PresentMon beside it, after a null pair (the same build in both arms), that publishes how far apart the moments are in each present mode.

Evidence

Read at forge main 310e7c9df (18 Nov 2026), not run. The research pass that found this read 347aa6e82. Four commits landed in between (#1235, #1486, #1487, #1209); the moments below did not change, only line numbers.

Moment Read at Used by
T0 the host's clock when the game's present call returns, on the game's thread host/nn_vi.c:583 the game's time step, the vi: lines (613-617), HOS_PRESENT_TRACE (547-574)
T1 entry of the renderer's present, on the presenting thread, before the frame gate's wait gpu/vk/vk_replay.cpp:7075 calls gpu/vk/vk_fps.cpp:86-159 the FPS counter's ring, the field summary (vk_fps.cpp:146)
T2 the render thread at the frame's present job gpu/vk/vk_replay.cpp:4842-4913, called at 5075 frames.csv (RX_VK_FRAME_TRACE), the vk: status: line
T3 after the present call returns (headless: after the offscreen copy is submitted) gpu/vk/vk_replay.cpp:4942-4953, called from 6095-6100 RX_VK_FRAME_LOG, so the farm's frame-time probe
T4 the screen outside the game PresentMon's DisplayedTime, Windows only
T5 the driver's own timings gpu/vk/vk_reflex.cpp RX_VK_REFLEX_LOG, averages over 300 frames
  • Three clock sources. T0 is the host's QueryPerformanceCounter (host/hos_thread.c:1123-1136). T1 reads a TSC calibrated against it on first use (gpu/vk/vk_internal.h:559-585). T2 and T3 read std::chrono::steady_clock (vk_replay.cpp:4855, 4947). The trace's at_ns column carries the host's clock (vk_replay.cpp:4904-4906), but the frame log's time column starts at its own first present (4948), so matching a log row to a trace row or a PresentMon row means guessing the offset.
  • The counter's first two levels read no clock per frame. Off and FPS return before any read; Frame time and up read T1 (vk_fps.cpp:103-107).
  • Frame generation counts three ways. The counter's big number is the shown rate. Base N and the field summary count game frames (vk_fps.cpp:146). The frame log writes a row for every present call: made frames are presented by present_commit (vk_replay.cpp:6019-6030, called from vk_framegen.cpp:819), which ends in present_finish and so in the log.
  • The project already says the log is not the screen (docs/design.md:324-329). Checked 16 Nov 2026 on an RTX 5090 with DLSS Frame Gen and PresentMon 2.3.0: the log had no late frame while PresentMon showed 32% (3x) and 45% (4x) of the frames on the screen under 2 ms.
  • Nothing asks the driver when a frame was shown. VK_EXT_present_timing is not referenced in gpu/vk. VK_KHR_present_wait is used only by the presenter thread under FIFO, for at most five 20 ms waits (vk_replay.cpp:6118-6200).
  • The Breakdown is one thread's accounting. Parts are scaled down when they sum past the frame, and "game" is what is left (gpu/vk/fps_stats.h:94-113). With the render thread on, a trace row's parts belong to the game's present before the row's (vk_replay.cpp:4887-4891).
  • Reflex markers are approximate by the file's own words (gpu/vk/vk_reflex.cpp:13-14).

Proposed change

  1. A plain header for the record, its ring and the readers as pure functions over the ring, with its checks beside it, in the style of fps_stats.h and tests/test_fps_stats.cpp.
  2. One clock for every stamp: the host's (the interface already hands the renderer host->now_ns). The TSC read stays only for the per-draw phase timers, where its cost matters.
  3. Move the readers onto the ring one pull request at a time, each showing exactly what it shows today: the FPS counter, the field summary, the frame log and trace, the Breakdown, the Reflex markers.
  4. Add the shown time. Use VK_EXT_present_timing where a driver has it (survey which of our rigs expose it, with present_id and present_wait first), present_wait under FIFO otherwise, and "not known" where neither exists. Made frames carry their own shown times.
  5. Keep PresentMon as the outside check and publish the gap between the moments for each present mode.

How we would test it

  • Game-free (new, not red today): one stream of made-up stamps (steady 16.67 ms, one 40 ms frame, a set of one game frame and three made frames) goes through every reader. The counter, the summary, the log and the trace must report the same intervals, and the Breakdown's parts must add up to the frame within 1 ms. Today no such check can exist, because each reader reads its own clock.
  • Game run: Windows, mailbox, immediate and FIFO, a 60 cap, one scripted turn, with HOS_PRESENT_TRACE, RX_VK_FRAME_TRACE, RX_VK_FRAME_LOG and PresentMon recorded together. Null pair first: the same build in both arms. Publish the median and p99 of the difference between each pair of moments. After the change the first four agree to the stamp.
  • Cost: no speed claim. The stamps' cost is measured as a pair (cap 1000, HOS_FPS_STEP=0, Per frame, windowless) after a null main-against-main pair on the same PC.
  • #1493, the renderer rewrite (Step 0, item 4: frame metrics that mean what they say).
  • #1362, #1442 and #1476: the PresentMon method and the shown-cadence numbers this would make routine.
  • #1235 (the vsync ticker's wait) and #1458 and #1462 (farm numbers that read T3).
  • #928, #998 and #1279: the counter's Breakdown, its overhaul, and the profile folder that writes presents.csv and frames.csv together.
  • #1372: per-second samples in the field summary, the other reader of T1.
  • Searched all 570 issues and 925 pull requests, open and closed, by title and body (frame record, frame clock, PresentMon, present timing, DisplayedTime, Reflex, FPS counter). None asks for one record or one clock.

New on this forge; not opened on GitHub.

**Type:** measurement · **Area:** frame metrics, in the renderer and the host · **Part of:** #1493 ## TL;DR Every tool that reports "frame time" reads a different moment of the frame, and not from the same clock: the FPS counter and the field data read the renderer's present entry, the frame trace reads the render thread, the frame log (and so the test farm's p99) reads the return of the present call, and the game's own time step reads the host. Only PresentMon and the driver's Reflex timings get near the screen. We propose one record per game frame, stamped from one clock, that every reader takes its number from, with the shown time added where the platform gives it. ## Breakdown - **Who it affects:** everyone who compares frame numbers: pull requests that claim speed, the farm's gates, the field dashboard, players reading the counter, and the renderer rewrite's gates (#1493), which need numbers that mean the same thing in every arm. - **What is wrong:** there are six moments (table below) and none of the four we record ourselves is scan-out. Under frame generation the counter counts shown frames, the field summary counts game frames, and the frame log counts every present, made frames included, so the three disagree about one session. The Breakdown's parts belong to one thread and are scaled down when they add up to more than the frame. - **What we propose:** a ring with one record per game frame: an id, then stamps from one clock at each step the frame passes (simulation start, last submit handed over, present entry and return, render begin and end, GPU begin and end, swapchain acquire, queue present begin and end, shown time, number of made frames and when each was shown). The counter, the field summary, the frame log, the trace, the Breakdown and the Reflex markers are all computed from the ring. - **What does not change:** the host alone steps game time (the pacer issue covers that). The counter keeps showing the shown rate and "Base". Log and CSV columns stay readable by today's scripts, new ones go at the end. The first step changes no behaviour and no number a player sees. - **How we would prove it:** a game-free check that feeds one stream of made-up stamps to every reader and requires the same answers; then one windowed run on a Windows PC with PresentMon beside it, after a null pair (the same build in both arms), that publishes how far apart the moments are in each present mode. ## Evidence Read at forge main 310e7c9df (18 Nov 2026), not run. The research pass that found this read 347aa6e82. Four commits landed in between (#1235, #1486, #1487, #1209); the moments below did not change, only line numbers. | | Moment | Read at | Used by | |---|---|---|---| | T0 | the host's clock when the game's present call returns, on the game's thread | host/nn_vi.c:583 | the game's time step, the `vi:` lines (613-617), HOS_PRESENT_TRACE (547-574) | | T1 | entry of the renderer's present, on the presenting thread, before the frame gate's wait | gpu/vk/vk_replay.cpp:7075 calls gpu/vk/vk_fps.cpp:86-159 | the FPS counter's ring, the field summary (vk_fps.cpp:146) | | T2 | the render thread at the frame's present job | gpu/vk/vk_replay.cpp:4842-4913, called at 5075 | frames.csv (RX_VK_FRAME_TRACE), the `vk: status:` line | | T3 | after the present call returns (headless: after the offscreen copy is submitted) | gpu/vk/vk_replay.cpp:4942-4953, called from 6095-6100 | RX_VK_FRAME_LOG, so the farm's frame-time probe | | T4 | the screen | outside the game | PresentMon's DisplayedTime, Windows only | | T5 | the driver's own timings | gpu/vk/vk_reflex.cpp | RX_VK_REFLEX_LOG, averages over 300 frames | - **Three clock sources.** T0 is the host's QueryPerformanceCounter (host/hos_thread.c:1123-1136). T1 reads a TSC calibrated against it on first use (gpu/vk/vk_internal.h:559-585). T2 and T3 read std::chrono::steady_clock (vk_replay.cpp:4855, 4947). The trace's `at_ns` column carries the host's clock (vk_replay.cpp:4904-4906), but the frame log's time column starts at its own first present (4948), so matching a log row to a trace row or a PresentMon row means guessing the offset. - **The counter's first two levels read no clock per frame.** Off and FPS return before any read; Frame time and up read T1 (vk_fps.cpp:103-107). - **Frame generation counts three ways.** The counter's big number is the shown rate. `Base N` and the field summary count game frames (vk_fps.cpp:146). The frame log writes a row for every present call: made frames are presented by present_commit (vk_replay.cpp:6019-6030, called from vk_framegen.cpp:819), which ends in present_finish and so in the log. - **The project already says the log is not the screen** (docs/design.md:324-329). Checked 16 Nov 2026 on an RTX 5090 with DLSS Frame Gen and PresentMon 2.3.0: the log had no late frame while PresentMon showed 32% (3x) and 45% (4x) of the frames on the screen under 2 ms. - **Nothing asks the driver when a frame was shown.** VK_EXT_present_timing is not referenced in gpu/vk. VK_KHR_present_wait is used only by the presenter thread under FIFO, for at most five 20 ms waits (vk_replay.cpp:6118-6200). - **The Breakdown is one thread's accounting.** Parts are scaled down when they sum past the frame, and "game" is what is left (gpu/vk/fps_stats.h:94-113). With the render thread on, a trace row's parts belong to the game's present before the row's (vk_replay.cpp:4887-4891). - **Reflex markers are approximate by the file's own words** (gpu/vk/vk_reflex.cpp:13-14). ## Proposed change 1. A plain header for the record, its ring and the readers as pure functions over the ring, with its checks beside it, in the style of fps_stats.h and tests/test_fps_stats.cpp. 2. One clock for every stamp: the host's (the interface already hands the renderer host->now_ns). The TSC read stays only for the per-draw phase timers, where its cost matters. 3. Move the readers onto the ring one pull request at a time, each showing exactly what it shows today: the FPS counter, the field summary, the frame log and trace, the Breakdown, the Reflex markers. 4. Add the shown time. Use VK_EXT_present_timing where a driver has it (survey which of our rigs expose it, with present_id and present_wait first), present_wait under FIFO otherwise, and "not known" where neither exists. Made frames carry their own shown times. 5. Keep PresentMon as the outside check and publish the gap between the moments for each present mode. ## How we would test it - **Game-free (new, not red today):** one stream of made-up stamps (steady 16.67 ms, one 40 ms frame, a set of one game frame and three made frames) goes through every reader. The counter, the summary, the log and the trace must report the same intervals, and the Breakdown's parts must add up to the frame within 1 ms. Today no such check can exist, because each reader reads its own clock. - **Game run:** Windows, mailbox, immediate and FIFO, a 60 cap, one scripted turn, with HOS_PRESENT_TRACE, RX_VK_FRAME_TRACE, RX_VK_FRAME_LOG and PresentMon recorded together. Null pair first: the same build in both arms. Publish the median and p99 of the difference between each pair of moments. After the change the first four agree to the stamp. - **Cost:** no speed claim. The stamps' cost is measured as a pair (cap 1000, HOS_FPS_STEP=0, Per frame, windowless) after a null main-against-main pair on the same PC. ## Related - #1493, the renderer rewrite (Step 0, item 4: frame metrics that mean what they say). - #1362, #1442 and #1476: the PresentMon method and the shown-cadence numbers this would make routine. - #1235 (the vsync ticker's wait) and #1458 and #1462 (farm numbers that read T3). - #928, #998 and #1279: the counter's Breakdown, its overhaul, and the profile folder that writes presents.csv and frames.csv together. - #1372: per-second samples in the field summary, the other reader of T1. - Searched all 570 issues and 925 pull requests, open and closed, by title and body (frame record, frame clock, PresentMon, present timing, DisplayedTime, Reflex, FPS counter). None asks for one record or one clock. New on this forge; not opened on GitHub.
Collaborator

Possibly related, for context:

  • issue #1493 Renderer rewrite — Renderer rewrite explicitly calls for honest frame metrics
  • PR #1362 fix(vk): frame generation's made frames at their own times with V-Sync Off — Related shown-frame timing for generated frames
  • PR #1235 perf(vi): the vsync ticker waits on a high-resolution timer instead of yielding — Related frame pacing measurements and timing interpretation
Possibly related, for context: - issue #1493 Renderer rewrite — Renderer rewrite explicitly calls for honest frame metrics - PR #1362 fix(vk): frame generation's made frames at their own times with V-Sync Off — Related shown-frame timing for generated frames - PR #1235 perf(vi): the vsync ticker waits on a high-resolution timer instead of yielding — Related frame pacing measurements and timing interpretation
Member

Picking up the compatible frame-record design and a synthetic timestamp fixture. I’ll align the simulation, render, queue-present, and optional display-confirmation events by game-frame ID, preserve current consumer semantics, and coordinate the producer boundary with the existing v2 telemetry PR.

Picking up the compatible frame-record design and a synthetic timestamp fixture. I’ll align the simulation, render, queue-present, and optional display-confirmation events by game-frame ID, preserve current consumer semantics, and coordinate the producer boundary with the existing v2 telemetry PR.
Member

The local frame-record contract and synthetic fixture are complete. All nine game-free cases passed. The contract uses one host monotonic clock and a game-frame ID to associate simulation, submit, replay and present events. Generated outputs retain their own identities under the parent frame. Display confirmation is optional and carries the matching ID, so a stale or unavailable confirmation cannot be mistaken for the current frame's display time.

The first runtime slice proposed is an opt-in renderer-entry-to-replay diagnostic, estimated at two clock reads and one bounded publication per captured game present, with roughly 32 KiB of event storage. We still need to measure overhead and validate synchronous and threaded token transfer, overflow, disabled-path behavior, and legacy output parity. I checked the boundary against Gab’s v2 telemetry PR. The existing producer, CSV and pacing semantics remain in use.

The local frame-record contract and synthetic fixture are complete. All nine game-free cases passed. The contract uses one host monotonic clock and a game-frame ID to associate simulation, submit, replay and present events. Generated outputs retain their own identities under the parent frame. Display confirmation is optional and carries the matching ID, so a stale or unavailable confirmation cannot be mistaken for the current frame's display time. The first runtime slice proposed is an opt-in renderer-entry-to-replay diagnostic, estimated at two clock reads and one bounded publication per captured game present, with roughly 32 KiB of event storage. We still need to measure overhead and validate synchronous and threaded token transfer, overflow, disabled-path behavior, and legacy output parity. I checked the boundary against [Gab’s v2 telemetry PR](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1530). The existing producer, CSV and pacing semantics remain in use.
Member

The opt-in Windows frame-state trace is in WIP PR #1625.

On the same build, capture off produced no sidecar and all three legacy CSV headers matched capture on. The trace separated gameplay from Pause, Items and Insert within Kokiri Forest and detected the decoded title movie. Insert's open and close crossings went to transition. Gameplay resumed after closing the menu and after loading Hyrule Field. The load window went to unknown where it lacked a qualifying player update.

The next checks are disabled and enabled overhead against current main, Linux runtime, and an in-game load that produces a positive loading hint. The trace labels host-present intervals. Linking those intervals to renderer replay and confirmed display times remains part of this issue.

The opt-in Windows frame-state trace is in [WIP PR #1625](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1625). On the same build, capture off produced no sidecar and all three legacy CSV headers matched capture on. The trace separated gameplay from Pause, Items and Insert within Kokiri Forest and detected the decoded title movie. Insert's open and close crossings went to `transition`. Gameplay resumed after closing the menu and after loading Hyrule Field. The load window went to `unknown` where it lacked a qualifying player update. The next checks are disabled and enabled overhead against current main, Linux runtime, and an in-game load that produces a positive loading hint. The trace labels host-present intervals. Linking those intervals to renderer replay and confirmed display times remains part of this issue.
Sign in to join this conversation.
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot#1518
No description provided.