WIP: perf(nvn): the game's frame limiter waits for the frame before last on the GPU, so heavy scenes run 11 to 15 % faster #916

Closed
GummiNaomi wants to merge 1 commit from GummiNaomi/Longshot:perf/frame-limiter-ahead into main
Member

Not ready: this change makes shadows flicker (walls and floors, every other frame); see the comments. Do not test it.

Type: perf · Risk: high · Tested on: Windows 11, RTX 4070 SUPER (NVIDIA 617.42) · Needs: Linux; AMD; Intel; a Steam Deck

Why

In heavy scenes the game holds itself back. Once a frame, Ocarina of Time's frame limiter waits, with no timeout, until
the GPU has finished the frame before. On the console that wait is short. In Longshot the replay sits between the game
and the GPU, so the frame before ends later, and at Castle Town's south gate the wait took 4.2 ms of a 14.9 ms frame
while the GPU (75 % busy) and the render thread both had time to spare. Every PC pays this, whatever its GPU.

See #995.

What changed

The limiter's one wait (the nvnSyncWait that returns to 0x8042cde0, in f_8042cd20) now waits for the GPU only up
to the frame before last: the game runs at most two frames ahead of the GPU instead of one. It also waits until the
replay has replayed the frame before, because what that wait really guarded on the console is the game's per-frame
memory: it fills frame N + 2's scene buffer in the one frame N used (two in turn). Here the replay is what reads that
memory, so the replay must be done with it. A first version without that second wait gave the same frame rate but
drew Link and the scene dark for single frames in Hyrule Field (3 and 5 times in two 100 s runs).

  • nvn: NV(nvnSyncWait) in host/nvn_native.c: the limiter's call site only; every other sync wait the game makes
    (those before it reads GPU results back) waits for its own fence as before. HOS_FRAME_AHEAD=0: as before.
  • vk: replayed_wait in gpu/vk/vk_replay.cpp (MkwVkRenderer::nvn_replayed_wait, MKWVK_API_VERSION 24): waits until
    the render thread has replayed the hand-over a fence value belongs to (q_done against the hand-over number kept in
    handed_values). Without the render thread a submit is replayed where it is made, so it answers at once.
  • host: rx_nvn_replayed_wait in host/rx_backend.c (1 at once on the WebGPU back end).
  • tests: tests/test_frame_ahead.py builds the real NV(nvnSyncWait) with a fake GPU and replay: the limiter waits for
    the GPU two frames back and the replay one frame back, other callers for their own fence, and HOS_FRAME_AHEAD=0
    restores the old wait. It fails on main.
  • docs: the switch in docs/development.md.

Measurements

Verdict: faster in every round taken: Hyrule Field +12 % (67.9 -> 76.2 fps, six rounds), Castle Town's heavy scene
+15 % (66.2 -> 76.3 fps, two rounds). The slowest run with the change is faster than the fastest without it. No dark
frames in these 16 runs. With the render thread off (what PCs under 12 logical processors get) +4 % (67.3 -> 70.2
fps), and the dark-Link frames of #366 on that path fall from 13-25 a run to 0-1: the game no longer races the replay
there either. #769 fixes those frames at their cause; this change does not replace it.

Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB
Scene: Castle Town's south gate into Hyrule Field (save set "First Step into Hyrule Town"); 2560x1440, DLAA, no frame
generation, uncapped; render thread on (Auto on this PC)
Method: headless runs on a wall-clock script, the change off (HOS_FRAME_AHEAD=0) and on in turn, the same build; the
frame rate is the median of the log's 120-present fps lines with 2,000+ draws (the heavy scene), dark frames counted by a
local counter in the build (frames drawn with the scene buffer's light grid empty, the dark-Link frames of #366; not in
this change)
How to reproduce: the save set above; walk out of the south gate to the drawbridge and into the field; compare
HOS_FRAME_AHEAD=0 against the default

Before: HOS_FRAME_AHEAD=0, this PR @ 14e165ab After: this PR @ 14e165ab
Hyrule Field from the gate, heavy-scene fps, six rounds 68.2, 67.8, 67.7, 67.3, 68.0, 68.3 (median 67.9) 74.8, 76.1, 76.7, 76.2, 76.3, 75.5 (median 76.2)
Castle Town's south gate, standing, heavy-scene fps, two rounds 66.3, 66.1 (median 66.2) 76.2, 76.3 (median 76.3)
Dark-Link frames in those 16 runs 0 0
The game's sync waits that blocked (field, a run) 330-334 4-191
Hyrule Field from the gate, render thread off (RX_VK_ASYNC=0), heavy-scene fps, three rounds 66.8, 67.3, 68.0 (median 67.3) 70.2, 70.9, 69.5 (median 70.2)
Dark-Link frames in those runs (render thread off) 13, 25, 24 0, 1, 0

Baseline: the same build with the change switched off, because the dark-frame count needs the local counter in the build.
Earlier runs of the same build add one flash (two frames) in 20 runs with the change, during a 50 ms render-thread stall,
against none in 10 runs without; the first version (no replay wait) had 8 flashes in 2 field runs.

fac-a01  HOS_FRAME_AHEAD=0  fps heavy: median 68.1 | dark frames: 0
fac-a11  (default)          fps heavy: median 74.8 | dark frames: 0
... (the 22 rows are in docs/tested/2026-11-15-frame-ahead-gumminaomi-*.md)

Flags and settings

One new switch, on by default.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_FRAME_AHEAD 0: the game's frame limiter waits for the frame before on the GPU, as on the console (no switch: the frame before) on (unset): the frame before last on the GPU, the frame before on the replay +11-15 % in heavy scenes here helps: RTX 4070 SUPER, render thread on; helps, render thread off: +4 %, and fewer dark frames; untested: AMD, Intel, Linux, Steam Deck on for everyone

Testing

Tested: Windows 11, RTX 4070 SUPER, NVIDIA 617.42: the 22 runs above (Hyrule Field six rounds, Castle Town's gate two, the field with the render thread off three,
each side in turn), plus 20 more runs of the same build with the change on (field and town, dark frames counted);
tests/test_frame_ahead.py passes here and fails on main; python -I -B tests/run_all.py: 331 passed, 79 failed, 189 skipped; main 772fe283 on the same PC the same hour: 329
passed, 80 failed, 189 skipped. Every failure here also fails on main (this PC's toolchain: Windows line endings in
test_tested_configurations.py's pipe test, the fixtures that compile with -Werror or need gcc; the list is below).

The 79 checks that fail here, all of them on main too
  • tests/test_alt_enter.py
  • tests/test_appimage_player_build.py
  • tests/test_audio_deadline.py
  • tests/test_audio_output_errors.py
  • tests/test_audio_wave_buffer_release.py
  • tests/test_bc_levels.py
  • tests/test_bind_memo.py
  • tests/test_capture_copy_helpers.py
  • tests/test_collect_wide.py
  • tests/test_crash_dialog.py
  • tests/test_dlss_actor.py
  • tests/test_dlss_checks.py
  • tests/test_dlss_math.py
  • tests/test_draw_binds.py
  • tests/test_env_file.py
  • tests/test_env_on.py
  • tests/test_fps_overlay_order.py
  • tests/test_fps_rate.py
  • tests/test_fps_stats.py
  • tests/test_frame_whole.py
  • tests/test_framegen_auto.py
  • tests/test_framegen_gate.py
  • tests/test_fsr3_math.py
  • tests/test_game_font.py
  • tests/test_gpu_choice.py
  • tests/test_hd_rumble.py
  • tests/test_high_fps_fixes.py
  • tests/test_import_span.py
  • tests/test_jobs_wait_runs_queued.py
  • tests/test_lift_cleanup_error.py
  • tests/test_linux_preflight.py
  • tests/test_make_game_cache.py
  • tests/test_make_game_prepare.py
  • tests/test_menu_mouse_scroll.py
  • tests/test_mirror_inherit.py
  • tests/test_missing_nup.py
  • tests/test_movie_upscale_policy.py
  • tests/test_oot_jitter.py
  • tests/test_options_budget_once.py
  • tests/test_pass_hazard.py
  • tests/test_pool_span.py
  • tests/test_precompile_compute_guard.py
  • tests/test_present_ahead.py
  • tests/test_present_thread.py
  • tests/test_prof_clock.py
  • tests/test_program_cache_cleanup.py
  • tests/test_prompt_auto_face.py
  • tests/test_psychov35_default.py
  • tests/test_psychov35_dlss.py
  • tests/test_push_state.py
  • tests/test_quick_pipelines.py
  • tests/test_readback_late.py
  • tests/test_report_words.py
  • tests/test_rumble_mapping.py
  • tests/test_rumble_menu.py
  • tests/test_rumble_refresh.py
  • tests/test_run_all_junit.py
  • tests/test_same_bind.py
  • tests/test_same_draw.py
  • tests/test_same_dyn.py
  • tests/test_seed_reader.py
  • tests/test_shader_module_guard.py
  • tests/test_skip_code.py
  • tests/test_status_line.py
  • tests/test_submitted_page.py
  • tests/test_table_track.py
  • tests/test_task_mesh_fallback_devices.py
  • tests/test_tested_configurations.py
  • tests/test_tex_spans_once_a_present.py
  • tests/test_texture_layout_sizes.py
  • tests/test_ub_gap.py
  • tests/test_upscale_independent.py
  • tests/test_upscale_label.py
  • tests/test_utf8_paths.py
  • tests/test_vertex_bind.py
  • tests/test_vk_occlusion_queries.py
  • tests/test_vk_pgo.py
  • tests/test_walk_key.py
  • tests/test_wb_pages.py

Not tested: AMD and Intel GPUs, Linux, a Steam Deck (no such hardware here); a 60 fps cap (where the gain is room
under the cap, not a higher number); other areas than Castle Town and the field.

Must be tested:

  • Linux, any GPU: Castle Town's south gate out to Hyrule Field and back for a few minutes, the FPS counter on, then the
    same with HOS_FRAME_AHEAD=0, expecting a higher frame rate in the heavy scenes with the default and no frame where
    Link or the scene goes dark (Test Farm: @Beanstalk linux, the gate route with and without HOS_FRAME_AHEAD=0)
  • AMD, Windows or Linux: the same, expecting the same (Test Farm: @Beanstalk amd, the gate route with and without HOS_FRAME_AHEAD=0)
  • Steam Deck: the same at its default settings, expecting no dark frame and the frame rate no lower than with
    HOS_FRAME_AHEAD=0 (Test Farm: @Beanstalk steamdeck)

Risks

What could break: found: shadows on walls and floors flicker every other frame (night, Castle Town); see the comments. Also: a frame drawn with data the game has already overwritten for a later frame (a dark or wrong
frame), if some per-frame memory is read later than the replay's own pass over it. The replay wait covers what the
dark-frame counter found; other data was not watched. Input lag: the game may be one frame further ahead of the screen
(about 13 ms at 76 fps), which matters most uncapped.

Turning it off: HOS_FRAME_AHEAD=0.

Compatibility: MKWVK_API_VERSION goes to 24: the game and longshot_vk.dll come from the same build as always.
Saves, options and caches unchanged.

Issues

See #995. Related: #656 (a menu row for the present poll answered at once) is a different wait, the Presentation thread's poll of its frame's event; this change is the main thread's sync wait in the frame limiter. The two do not touch the same code.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named).
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • A file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • MKWVK_API_VERSION bumped (gpu/vk/vk_api.h's MkwVkHost or MkwVkRenderer changed).
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened. (None needed a change: every check that reads these files passes as on main.)
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows only; no Linux build
    here: the host change is plain C with the calls the Linux build already has, InterlockedIncrement64 as the file uses
    elsewhere. Asked of the Test Farm's Linux run above.)
  • Docs updated.

🤖 Generated with Claude Code

> **Not ready: this change makes shadows flicker (walls and floors, every other frame); see the comments. Do not test it.** **Type:** perf · **Risk:** high · **Tested on:** Windows 11, RTX 4070 SUPER (NVIDIA 617.42) · **Needs:** Linux; AMD; Intel; a Steam Deck ## Why In heavy scenes the game holds itself back. Once a frame, Ocarina of Time's frame limiter waits, with no timeout, until the GPU has finished the frame before. On the console that wait is short. In Longshot the replay sits between the game and the GPU, so the frame before ends later, and at Castle Town's south gate the wait took 4.2 ms of a 14.9 ms frame while the GPU (75 % busy) and the render thread both had time to spare. Every PC pays this, whatever its GPU. See #995. ## What changed The limiter's one wait (the `nvnSyncWait` that returns to `0x8042cde0`, in `f_8042cd20`) now waits for the GPU only up to the frame before last: the game runs at most two frames ahead of the GPU instead of one. It also waits until the replay has replayed the frame before, because what that wait really guarded on the console is the game's per-frame memory: it fills frame N + 2's scene buffer in the one frame N used (two in turn). Here the replay is what reads that memory, so the replay must be done with it. A first version without that second wait gave the same frame rate but drew Link and the scene dark for single frames in Hyrule Field (3 and 5 times in two 100 s runs). - nvn: `NV(nvnSyncWait)` in `host/nvn_native.c`: the limiter's call site only; every other sync wait the game makes (those before it reads GPU results back) waits for its own fence as before. `HOS_FRAME_AHEAD=0`: as before. - vk: `replayed_wait` in `gpu/vk/vk_replay.cpp` (`MkwVkRenderer::nvn_replayed_wait`, `MKWVK_API_VERSION` 24): waits until the render thread has replayed the hand-over a fence value belongs to (`q_done` against the hand-over number kept in `handed_values`). Without the render thread a submit is replayed where it is made, so it answers at once. - host: `rx_nvn_replayed_wait` in `host/rx_backend.c` (1 at once on the WebGPU back end). - tests: `tests/test_frame_ahead.py` builds the real `NV(nvnSyncWait)` with a fake GPU and replay: the limiter waits for the GPU two frames back and the replay one frame back, other callers for their own fence, and `HOS_FRAME_AHEAD=0` restores the old wait. It fails on main. - docs: the switch in `docs/development.md`. ## Measurements **Verdict:** faster in every round taken: Hyrule Field +12 % (67.9 -> 76.2 fps, six rounds), Castle Town's heavy scene +15 % (66.2 -> 76.3 fps, two rounds). The slowest run with the change is faster than the fastest without it. No dark frames in these 16 runs. With the render thread off (what PCs under 12 logical processors get) +4 % (67.3 -> 70.2 fps), and the dark-Link frames of #366 on that path fall from 13-25 a run to 0-1: the game no longer races the replay there either. #769 fixes those frames at their cause; this change does not replace it. Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB Scene: Castle Town's south gate into Hyrule Field (save set "First Step into Hyrule Town"); 2560x1440, DLAA, no frame generation, uncapped; render thread on (Auto on this PC) Method: headless runs on a wall-clock script, the change off (`HOS_FRAME_AHEAD=0`) and on in turn, the same build; the frame rate is the median of the log's 120-present fps lines with 2,000+ draws (the heavy scene), dark frames counted by a local counter in the build (frames drawn with the scene buffer's light grid empty, the dark-Link frames of #366; not in this change) How to reproduce: the save set above; walk out of the south gate to the drawbridge and into the field; compare `HOS_FRAME_AHEAD=0` against the default | | Before: `HOS_FRAME_AHEAD=0`, this PR @ 14e165ab | After: this PR @ 14e165ab | |---|---|---| | Hyrule Field from the gate, heavy-scene fps, six rounds | 68.2, 67.8, 67.7, 67.3, 68.0, 68.3 (median 67.9) | 74.8, 76.1, 76.7, 76.2, 76.3, 75.5 (median 76.2) | | Castle Town's south gate, standing, heavy-scene fps, two rounds | 66.3, 66.1 (median 66.2) | 76.2, 76.3 (median 76.3) | | Dark-Link frames in those 16 runs | 0 | 0 | | The game's sync waits that blocked (field, a run) | 330-334 | 4-191 | | Hyrule Field from the gate, render thread off (`RX_VK_ASYNC=0`), heavy-scene fps, three rounds | 66.8, 67.3, 68.0 (median 67.3) | 70.2, 70.9, 69.5 (median 70.2) | | Dark-Link frames in those runs (render thread off) | 13, 25, 24 | 0, 1, 0 | Baseline: the same build with the change switched off, because the dark-frame count needs the local counter in the build. Earlier runs of the same build add one flash (two frames) in 20 runs with the change, during a 50 ms render-thread stall, against none in 10 runs without; the first version (no replay wait) had 8 flashes in 2 field runs. ``` fac-a01 HOS_FRAME_AHEAD=0 fps heavy: median 68.1 | dark frames: 0 fac-a11 (default) fps heavy: median 74.8 | dark frames: 0 ... (the 22 rows are in docs/tested/2026-11-15-frame-ahead-gumminaomi-*.md) ``` ### Flags and settings One new switch, on by default. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_FRAME_AHEAD` | `0`: the game's frame limiter waits for the frame before on the GPU, as on the console | (no switch: the frame before) | on (unset): the frame before last on the GPU, the frame before on the replay | +11-15 % in heavy scenes here | helps: RTX 4070 SUPER, render thread on; helps, render thread off: +4 %, and fewer dark frames; untested: AMD, Intel, Linux, Steam Deck | on for everyone | ## Testing **Tested:** Windows 11, RTX 4070 SUPER, NVIDIA 617.42: the 22 runs above (Hyrule Field six rounds, Castle Town's gate two, the field with the render thread off three, each side in turn), plus 20 more runs of the same build with the change on (field and town, dark frames counted); `tests/test_frame_ahead.py` passes here and fails on main; `python -I -B tests/run_all.py`: 331 passed, 79 failed, 189 skipped; main 772fe283 on the same PC the same hour: 329 passed, 80 failed, 189 skipped. Every failure here also fails on main (this PC's toolchain: Windows line endings in `test_tested_configurations.py`'s pipe test, the fixtures that compile with `-Werror` or need gcc; the list is below). <details><summary>The 79 checks that fail here, all of them on main too</summary> - `tests/test_alt_enter.py` - `tests/test_appimage_player_build.py` - `tests/test_audio_deadline.py` - `tests/test_audio_output_errors.py` - `tests/test_audio_wave_buffer_release.py` - `tests/test_bc_levels.py` - `tests/test_bind_memo.py` - `tests/test_capture_copy_helpers.py` - `tests/test_collect_wide.py` - `tests/test_crash_dialog.py` - `tests/test_dlss_actor.py` - `tests/test_dlss_checks.py` - `tests/test_dlss_math.py` - `tests/test_draw_binds.py` - `tests/test_env_file.py` - `tests/test_env_on.py` - `tests/test_fps_overlay_order.py` - `tests/test_fps_rate.py` - `tests/test_fps_stats.py` - `tests/test_frame_whole.py` - `tests/test_framegen_auto.py` - `tests/test_framegen_gate.py` - `tests/test_fsr3_math.py` - `tests/test_game_font.py` - `tests/test_gpu_choice.py` - `tests/test_hd_rumble.py` - `tests/test_high_fps_fixes.py` - `tests/test_import_span.py` - `tests/test_jobs_wait_runs_queued.py` - `tests/test_lift_cleanup_error.py` - `tests/test_linux_preflight.py` - `tests/test_make_game_cache.py` - `tests/test_make_game_prepare.py` - `tests/test_menu_mouse_scroll.py` - `tests/test_mirror_inherit.py` - `tests/test_missing_nup.py` - `tests/test_movie_upscale_policy.py` - `tests/test_oot_jitter.py` - `tests/test_options_budget_once.py` - `tests/test_pass_hazard.py` - `tests/test_pool_span.py` - `tests/test_precompile_compute_guard.py` - `tests/test_present_ahead.py` - `tests/test_present_thread.py` - `tests/test_prof_clock.py` - `tests/test_program_cache_cleanup.py` - `tests/test_prompt_auto_face.py` - `tests/test_psychov35_default.py` - `tests/test_psychov35_dlss.py` - `tests/test_push_state.py` - `tests/test_quick_pipelines.py` - `tests/test_readback_late.py` - `tests/test_report_words.py` - `tests/test_rumble_mapping.py` - `tests/test_rumble_menu.py` - `tests/test_rumble_refresh.py` - `tests/test_run_all_junit.py` - `tests/test_same_bind.py` - `tests/test_same_draw.py` - `tests/test_same_dyn.py` - `tests/test_seed_reader.py` - `tests/test_shader_module_guard.py` - `tests/test_skip_code.py` - `tests/test_status_line.py` - `tests/test_submitted_page.py` - `tests/test_table_track.py` - `tests/test_task_mesh_fallback_devices.py` - `tests/test_tested_configurations.py` - `tests/test_tex_spans_once_a_present.py` - `tests/test_texture_layout_sizes.py` - `tests/test_ub_gap.py` - `tests/test_upscale_independent.py` - `tests/test_upscale_label.py` - `tests/test_utf8_paths.py` - `tests/test_vertex_bind.py` - `tests/test_vk_occlusion_queries.py` - `tests/test_vk_pgo.py` - `tests/test_walk_key.py` - `tests/test_wb_pages.py` </details> **Not tested:** AMD and Intel GPUs, Linux, a Steam Deck (no such hardware here); a 60 fps cap (where the gain is room under the cap, not a higher number); other areas than Castle Town and the field. **Must be tested:** - Linux, any GPU: Castle Town's south gate out to Hyrule Field and back for a few minutes, the FPS counter on, then the same with `HOS_FRAME_AHEAD=0`, expecting a higher frame rate in the heavy scenes with the default and no frame where Link or the scene goes dark (Test Farm: @Beanstalk linux, the gate route with and without HOS_FRAME_AHEAD=0) - AMD, Windows or Linux: the same, expecting the same (Test Farm: @Beanstalk amd, the gate route with and without HOS_FRAME_AHEAD=0) - Steam Deck: the same at its default settings, expecting no dark frame and the frame rate no lower than with `HOS_FRAME_AHEAD=0` (Test Farm: @Beanstalk steamdeck) ## Risks **What could break:** found: shadows on walls and floors flicker every other frame (night, Castle Town); see the comments. Also: a frame drawn with data the game has already overwritten for a later frame (a dark or wrong frame), if some per-frame memory is read later than the replay's own pass over it. The replay wait covers what the dark-frame counter found; other data was not watched. Input lag: the game may be one frame further ahead of the screen (about 13 ms at 76 fps), which matters most uncapped. **Turning it off:** `HOS_FRAME_AHEAD=0`. **Compatibility:** `MKWVK_API_VERSION` goes to 24: the game and `longshot_vk.dll` come from the same build as always. Saves, options and caches unchanged. ## Issues See #995. Related: #656 (a menu row for the present poll answered at once) is a different wait, the Presentation thread's poll of its frame's event; this change is the main thread's sync wait in the frame limiter. The two do not touch the same code. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Numbers from the same PC, scene and settings, at least 2 interleaved runs each, the median reported. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] A file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] `MKWVK_API_VERSION` bumped (`gpu/vk/vk_api.h`'s `MkwVkHost` or `MkwVkRenderer` changed). - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. (None needed a change: every check that reads these files passes as on main.) - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows only; no Linux build here: the host change is plain C with the calls the Linux build already has, `InterlockedIncrement64` as the file uses elsewhere. Asked of the Test Farm's Linux run above.) - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
perf(nvn): the game's frame limiter waits for the frame before last on the GPU, so heavy scenes run 11 to 15 % faster
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
beanstalk/approval approved by futondestroyer (reviewed)
beanstalk/steamdeck 0/1 pass, 0 running, 0 queued
14e165ab6b
Once a frame Ocarina of Time's frame limiter (f_8042cd20, the nvnSyncWait
returning to 0x8042cde0) waits with no timeout until the GPU has finished the
frame before. With the replay between the game and the GPU that frame ends
later than on the console: at Castle Town's south gate the wait was 4.2 ms of a
14.9 ms frame while the GPU and the render thread both had time to spare.

That one wait now waits for the GPU only up to the frame before last, and for
the replay to have replayed the frame before (MkwVkRenderer::nvn_replayed_wait,
MKWVK_API_VERSION 24): the game fills frame N + 2's scene buffer in the one
frame N used, and here the replay is what reads it. Without the replay wait a
first version drew Link and the scene dark for single frames in Hyrule Field.
Every other sync wait is as before. HOS_FRAME_AHEAD=0: as before.

Measured on Windows 11, RTX 4070 SUPER, Ryzen 9 9950X3D, 2560x1440 DLAA,
uncapped, the change off and on in turn in one build: Hyrule Field from the
gate 67.9 -> 76.2 fps (six rounds), Castle Town's gate 66.2 -> 76.3 (two);
with the render thread off 67.3 -> 70.2 (three), where the dark-Link frames of
#366 fell from 13-25 a run to 0-1. No dark frames with the render thread on in
those runs. Not run on Linux, AMD, Intel or a Steam Deck.

Tests: tests/test_frame_ahead.py (the real NV(nvnSyncWait) with a fake GPU and
replay; fails on main). The switch is in docs/development.md; the measured runs
in docs/tested/.

See #995

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Member

@Beanstalk linux, any GPU: the build itself (host code on Linux) and Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.

@Beanstalk linux, any GPU: the build itself (host code on Linux) and Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.
Author
Member

@Beanstalk amd, Windows or Linux: Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.

@Beanstalk amd, Windows or Linux: Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.
Member

@GummiNaomi only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it.

@GummiNaomi only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it.
Author
Member

@Beanstalk steamdeck, its default settings: Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.

@Beanstalk steamdeck, its default settings: Castle Town's south gate (a save at the gate) out to the drawbridge and into Hyrule Field and back, a few minutes, uncapped, the FPS counter on; then the same with HOS_FRAME_AHEAD=0. Expect a higher frame rate in the heavy scenes with the default, and no single frame where Link or the scene goes dark. Please post both frame rates and whether any dark frame was seen.
Member

@GummiNaomi only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it.

@GummiNaomi only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it.
Member

@GummiNaomi only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it.

@GummiNaomi only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it.
futondestroyer left a comment

Readiness assessment at 14e165ab6b51151a20bedb2881eaa823826912d0; this is not a source-code review or approval. I read the description, test evidence, current checks and farm-request discussion. No build, tests or game run were performed for this assessment.

The reported Windows/NVIDIA gains make this worth prioritizing, but it is not ready for final approval:

  • The Linux host build checkbox is still unticked, and the Linux, AMD and Steam Deck runs explicitly listed under Must be tested have no results yet.
  • Beanstalk says those requests require a BigBeans member's approval. Please react thumbs-up to the existing Linux, AMD and Steam Deck request comments rather than create duplicate requests:
  • CI checks are pending; a passing description check alone does not establish build/runtime readiness.

Please incorporate the resulting exact-head build and paired default/HOS_FRAME_AHEAD=0 runtime evidence into the description, including any dark frames, test duration and limitations. Keep the disclosed earlier flashes and extra-frame latency risk visible. Once the required coverage and checks are settled, update the checklist and mark the PR ready for code review under the repository workflow.

No new correctness finding is asserted here; this comment records the outstanding readiness gates, not a verdict on the synchronization implementation.

Readiness assessment at `14e165ab6b51151a20bedb2881eaa823826912d0`; this is not a source-code review or approval. I read the description, test evidence, current checks and farm-request discussion. No build, tests or game run were performed for this assessment. The reported Windows/NVIDIA gains make this worth prioritizing, but it is not ready for final approval: - The Linux host build checkbox is still unticked, and the Linux, AMD and Steam Deck runs explicitly listed under Must be tested have no results yet. - Beanstalk says those requests require a BigBeans member's approval. Please react thumbs-up to the existing Linux, AMD and Steam Deck request comments rather than create duplicate requests: - Linux: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/916#issuecomment-29363 - AMD: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/916#issuecomment-29364 - Steam Deck: https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/916#issuecomment-29366 - CI checks are pending; a passing description check alone does not establish build/runtime readiness. Please incorporate the resulting exact-head build and paired default/HOS_FRAME_AHEAD=0 runtime evidence into the description, including any dark frames, test duration and limitations. Keep the disclosed earlier flashes and extra-frame latency risk visible. Once the required coverage and checks are settled, update the checklist and mark the PR ready for code review under the repository workflow. No new correctness finding is asserted here; this comment records the outstanding readiness gates, not a verdict on the synchronization implementation.
Member

Beanstalk test farm

Commit 14e165a · tier reviewed · approved by futondestroyer (👍 on GummiNaomi's request) · dashboard

What will be tested · AI plan (gpt-6.1-terra)

This plan waits for a Steam Deck tester; none is currently online. In roughly 25 minutes it compares uncapped frame rates and sampled images in the Market and Hyrule Field, with frame-ahead enabled and disabled because the switch controls the changed limiter. The gate save is unavailable, so teleports substitute for the requested gate-to-drawbridge route. A crash, a frame-rate drop over 10%, or a substantial sampled image difference fails the plan; the sampled images cannot establish whether any single dark frame occurred. No tester online now matches steamdeck: that target waits for one.

  • Where: steamdeck (1 report).
  • Matrix: 2 cells, each on main and the PR: HOS_FRAME_AHEAD 1 or 0 (PR only).
  • market-field: from a new save (settings fps_counter=1, frame_rate_cap=6), then teleport to Market, measure market for 30 s (after 5 s warm-up), take the picture market to compare with main, teleport to Hyrule Field, move the stick, measure field for 60 s (after 5 s warm-up), take the picture field to compare with main; 1 run on each side for each of 2 cells (2 game starts a run).
  • Measured: crashes, draws and frame rate, frame times, stutters and hitches, screenshots against main.
  • The PR fails if: it crashes; or frame rate is more than 10% below main; or a picture differs from main by more than 15%.
  • Time: about 31 min of game runs per tester (4 game starts), plus the two builds.

Done. Run 2: the farm's reports were cleared after its Windows and Linux fixes: started again. Comment @Beanstalk to run it again.

Target Reports Crash Frame p99 (ms) vs main VRAM peak (MB) vs main Result
steamdeck 0/1 — — — queued
Scenario · matrix cell Target Frame p99 (ms) vs main Result
market-field · HOS_FRAME_AHEAD=1 (PR only) steamdeck — —
market-field · HOS_FRAME_AHEAD=0 (PR only) steamdeck — —
<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `14e165a` · tier **reviewed** · approved by futondestroyer (👍 on GummiNaomi's request) · [dashboard](https://beanstalk.magicbean.dev/prs/916) **What will be tested** · AI plan (`gpt-6.1-terra`) This plan waits for a Steam Deck tester; none is currently online. In roughly 25 minutes it compares uncapped frame rates and sampled images in the Market and Hyrule Field, with frame-ahead enabled and disabled because the switch controls the changed limiter. The gate save is unavailable, so teleports substitute for the requested gate-to-drawbridge route. A crash, a frame-rate drop over 10%, or a substantial sampled image difference fails the plan; the sampled images cannot establish whether any single dark frame occurred. No tester online now matches steamdeck: that target waits for one. - **Where:** steamdeck (1 report). - **Matrix:** 2 cells, each on main and the PR: HOS_FRAME_AHEAD `1` or `0` (PR only). - **market-field:** from a new save (settings fps_counter=1, frame_rate_cap=6), then teleport to Market, measure market for 30 s (after 5 s warm-up), take the picture market to compare with main, teleport to Hyrule Field, move the stick, measure field for 60 s (after 5 s warm-up), take the picture field to compare with main; 1 run on each side for each of 2 cells (2 game starts a run). - **Measured:** crashes, draws and frame rate, frame times, stutters and hitches, screenshots against main. - **The PR fails if:** it crashes; or frame rate is more than 10% below main; or a picture differs from main by more than 15%. - **Time:** about 31 min of game runs per tester (4 game starts), plus the two builds. Done. Run 2: the farm's reports were cleared after its Windows and Linux fixes: started again. Comment `@Beanstalk` to run it again. | Target | Reports | Crash | Frame p99 (ms) vs main | VRAM peak (MB) vs main | Result | | --- | --- | --- | --- | --- | --- | | steamdeck | 0/1 | — | — | — | queued | | Scenario · matrix cell | Target | Frame p99 (ms) vs main | Result | | --- | --- | --- | --- | | market-field · `HOS_FRAME_AHEAD=1 (PR only)` | steamdeck | — | — | | market-field · `HOS_FRAME_AHEAD=0 (PR only)` | steamdeck | — | — |
Author
Member

Not ready: this change makes shadows flicker. Found in a played session (night, Castle Town's gate tunnel and market): walls and floors go lighter and darker every other frame. The dark-frame counter used for the measurements only watches the scene buffer's light grid, so it missed this.

Measured since, Castle Town's gate to the drawbridge at night (!cheat 121), uncapped, a 320x180 picture of every present, counting the frames in which at least 1 % of the picture goes brighter or darker by more than 18 (of 255) for exactly one frame and comes back:

Frames with a one-frame flip over 1 % of the picture Worst frame
HOS_FRAME_AHEAD=0 17 of 14,667 (0.1 %) 2.3 % of the picture
default (this change on) 493 of 14,010 (3.5 %) 32.3 %
default, with the late pages' fix and sparse mirrors at main's defaults 236 of 13,238 (1.8 %) 21.5 %

So the frame limiter's wait guards more than the memory the replay reads: something the GPU itself reads while it runs the frame is rewritten by the game once it may run a frame further ahead. Waiting for the replay is not enough. I'm looking for what that is; until then this stays a draft and nobody should test it. The Test Farm requests above can be ignored for now.

**Not ready: this change makes shadows flicker.** Found in a played session (night, Castle Town's gate tunnel and market): walls and floors go lighter and darker every other frame. The dark-frame counter used for the measurements only watches the scene buffer's light grid, so it missed this. Measured since, Castle Town's gate to the drawbridge at night (`!cheat 121`), uncapped, a 320x180 picture of every present, counting the frames in which at least 1 % of the picture goes brighter or darker by more than 18 (of 255) for exactly one frame and comes back: | | Frames with a one-frame flip over 1 % of the picture | Worst frame | |---|---|---| | `HOS_FRAME_AHEAD=0` | 17 of 14,667 (0.1 %) | 2.3 % of the picture | | default (this change on) | 493 of 14,010 (3.5 %) | 32.3 % | | default, with the late pages' fix and sparse mirrors at main's defaults | 236 of 13,238 (1.8 %) | 21.5 % | So the frame limiter's wait guards more than the memory the replay reads: something the GPU itself reads while it runs the frame is rewritten by the game once it may run a frame further ahead. Waiting for the replay is not enough. I'm looking for what that is; until then this stays a draft and nobody should test it. The Test Farm requests above can be ignored for now.
Member

Local Windows/NVIDIA test results for exact head 14e165ab6b51151a20bedb2881eaa823826912d0 (2026-11-15): mixed result; recommend holding approval pending investigation of visual flashes.

Posting the already-completed local tests. I see the description now warns about shadow flicker; our observations below may be related, but do not establish the same mechanism. No further game runs are being started.

The human observer watched two separate visible passes, control first and default-on second, from Castle Town's south gate into Hyrule Field, walking and rotating the camera, then returning into Market. Asked specifically about brief dark flashes excluding normal loading fades, they reported:

  • HOS_FRAME_AHEAD=0: no flashes.
  • Default-on (variable unset): flashes on both Link and the scene.

Both passes completed the route and exited cleanly. This is a potential regression observed in one visible pass per arm, not yet a repeated or instrumented reproduction. The precise route segment and frequency were not recorded. Link wears a Keaton mask in this save. The author's private dark-frame counter is absent from this unchanged build; no automated dark-frame count is claimed.

Performance improved in a separate headless ABBA comparison using the same exact PR host and renderer, toggling only HOS_FRAME_AHEAD=0 versus unset:

Scene Control median FPS Default-on median FPS Change Control / on p99 interval
Castle Town south gate, facing town 63.50 67.78 +6.75% 20.66 / 20.04 ms
Hyrule Field drawbridge, facing outward 67.30 72.93 +8.36% 16.99 / 16.62 ms

Hardware/settings: Windows 11 Home 26300; RTX 4070 12 GB, NVIDIA 621.01; i7-13700F, 32 GB RAM; matching API 24 modules. DLAA render/output 2560x1440, SDR, frame generation and VSync off, cap 1000, real-time game speed, render thread Auto/on. Headless sink 1920x1080; visible passes used a 1920x1080 window with the same DLAA render/output settings.

Method: one excluded warm-up per arm, then off/on/on/off, with a settled 60-second stationary window at each scene per trial. Fresh copies of the private save and matching positions/cameras; all eight windows passed gameplay stability and background-load guards. No screenshots or profiling during timed windows. FPS is the median of two per-run rates; p99 is the median of two per-run p99 values. These are CPU game-present-return intervals from HOS_PRESENT_TRACE, not GPU-completion, scanout or input-latency measurements. This isolates the switch; it is not a comparison against current main or an exact reproduction of the author's save/time of day.

All timed runs exited 0, activation log messages matched their arms, and no timed interval exceeded 100 ms. No Vulkan/device-loss/fatal-error matches were found in the timed or visible logs; that does not negate the human-observed flashes. The focused tests/test_frame_ahead.py check passed; the full game-free suite was not rerun for these trials.

Input latency and the extra-frame tradeoff remain unmeasured. Linux, AMD/Intel, Steam Deck, HDR, frame generation, async-off and long-session behavior were not tested here. The performance gain is encouraging, but the default-on flashes need investigation before this local test can support approval. No game files, saves, binaries or raw traces are attached.

Local Windows/NVIDIA test results for exact head `14e165ab6b51151a20bedb2881eaa823826912d0` (2026-11-15): **mixed result; recommend holding approval pending investigation of visual flashes.** Posting the already-completed local tests. I see the description now warns about shadow flicker; our observations below may be related, but do not establish the same mechanism. No further game runs are being started. The human observer watched two separate visible passes, control first and default-on second, from Castle Town's south gate into Hyrule Field, walking and rotating the camera, then returning into Market. Asked specifically about brief dark flashes excluding normal loading fades, they reported: - `HOS_FRAME_AHEAD=0`: **no flashes**. - Default-on (variable unset): **flashes on both Link and the scene**. Both passes completed the route and exited cleanly. This is a potential regression observed in one visible pass per arm, not yet a repeated or instrumented reproduction. The precise route segment and frequency were not recorded. Link wears a Keaton mask in this save. The author's private dark-frame counter is absent from this unchanged build; no automated dark-frame count is claimed. Performance improved in a separate headless ABBA comparison using the **same exact PR host and renderer**, toggling only `HOS_FRAME_AHEAD=0` versus unset: | Scene | Control median FPS | Default-on median FPS | Change | Control / on p99 interval | |---|---:|---:|---:|---:| | Castle Town south gate, facing town | 63.50 | 67.78 | +6.75% | 20.66 / 20.04 ms | | Hyrule Field drawbridge, facing outward | 67.30 | 72.93 | +8.36% | 16.99 / 16.62 ms | Hardware/settings: Windows 11 Home 26300; RTX 4070 12 GB, NVIDIA 621.01; i7-13700F, 32 GB RAM; matching API 24 modules. DLAA render/output 2560x1440, SDR, frame generation and VSync off, cap 1000, real-time game speed, render thread Auto/on. Headless sink 1920x1080; visible passes used a 1920x1080 window with the same DLAA render/output settings. Method: one excluded warm-up per arm, then off/on/on/off, with a settled 60-second stationary window at each scene per trial. Fresh copies of the private save and matching positions/cameras; all eight windows passed gameplay stability and background-load guards. No screenshots or profiling during timed windows. FPS is the median of two per-run rates; p99 is the median of two per-run p99 values. These are CPU game-present-return intervals from `HOS_PRESENT_TRACE`, **not GPU-completion, scanout or input-latency measurements**. This isolates the switch; it is not a comparison against current main or an exact reproduction of the author's save/time of day. All timed runs exited 0, activation log messages matched their arms, and no timed interval exceeded 100 ms. No Vulkan/device-loss/fatal-error matches were found in the timed or visible logs; that does not negate the human-observed flashes. The focused `tests/test_frame_ahead.py` check passed; the full game-free suite was not rerun for these trials. Input latency and the extra-frame tradeoff remain unmeasured. Linux, AMD/Intel, Steam Deck, HDR, frame generation, async-off and long-session behavior were not tested here. The performance gain is encouraging, but the default-on flashes need investigation before this local test can support approval. No game files, saves, binaries or raw traces are attached.
Owner

Let's retest this after #1083 is merged

Let's retest this after https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1083 is merged
dyst left a comment

Nice, narrow change: only the limiter's call site is touched, and HOS_FRAME_AHEAD=0 gives back exactly the old path. I think I see where the flicker comes from, and it reaches further than shadows:

  1. "Replayed" doesn't mean the GPU is done reading the game's memory. The replay wait assumes the frame's reads were copied or captured (vk_api.h:308, vk_replay.cpp:5829). But imported pools are read by the GPU "where it is" (vk_memory.cpp:2), the submit capture covers "only the pools mirrored in VRAM", and mirror_on() defaults to discrete && !gcn. So on every iGPU (Steam Deck, Intel, APUs) and on GCN, the GPU reads frame N-1's buffers live while the game, now waiting only for N-2, rewrites them. On your 4070 the same happens for pools outside the mirror budget, which fits the flicker and fits sparse mirrors helping. I'd gate the run-ahead on the renderer vouching that nothing was read live (at least off when mirror_on() is false) and otherwise use the old wait.
  2. API version: main already uses 24 and 25 (MkwVkHost), so this needs 26. The branch is 96 commits behind main.
  3. Numbers: the docs/tested runs used RX_VK_MIRROR_SPARSE=1, RX_VK_COMPACT=1 and other non-default switches, which change what is read live. Please re-measure at defaults. futondestroyer's default runs gave +7-8%, and an iGPU run with your flicker counter would test point 1.

This is from reading the code only: nothing was built or run.

🤖 Generated with Claude Code

Nice, narrow change: only the limiter's call site is touched, and `HOS_FRAME_AHEAD=0` gives back exactly the old path. I think I see where the flicker comes from, and it reaches further than shadows: 1. **"Replayed" doesn't mean the GPU is done reading the game's memory.** The replay wait assumes the frame's reads were copied or captured (`vk_api.h:308`, `vk_replay.cpp:5829`). But imported pools are read by the GPU "where it is" (`vk_memory.cpp:2`), the submit capture covers "only the pools mirrored in VRAM", and `mirror_on()` defaults to `discrete && !gcn`. So on every iGPU (Steam Deck, Intel, APUs) and on GCN, the GPU reads frame N-1's buffers live while the game, now waiting only for N-2, rewrites them. On your 4070 the same happens for pools outside the mirror budget, which fits the flicker and fits sparse mirrors helping. I'd gate the run-ahead on the renderer vouching that nothing was read live (at least off when `mirror_on()` is false) and otherwise use the old wait. 2. **API version:** main already uses 24 and 25 (`MkwVkHost`), so this needs 26. The branch is 96 commits behind main. 3. **Numbers:** the docs/tested runs used `RX_VK_MIRROR_SPARSE=1`, `RX_VK_COMPACT=1` and other non-default switches, which change what is read live. Please re-measure at defaults. futondestroyer's default runs gave +7-8%, and an iGPU run with your flicker counter would test point 1. This is from reading the code only: nothing was built or run. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
@ -15,3 +15,3 @@
#endif
#define MKWVK_API_VERSION 23
#define MKWVK_API_VERSION 24
Member

Main has moved on: version 24 is the audio playback functions and 25 the microphone test (MkwVkHost on forge/main). This needs to become 26 when you rebase, and the (version 24, ...) note on nvn_replayed_wait should change to match.

Main has moved on: version 24 is the audio playback functions and 25 the microphone test (`MkwVkHost` on forge/main). This needs to become 26 when you rebase, and the `(version 24, ...)` note on `nvn_replayed_wait` should change to match.
@ -5821,2 +5826,4 @@
bh_st.catchup_ns += bh_now() - t0, bh_st.catchup_n++;
}
/// (longshot, MkwVkRenderer::nvn_replayed_wait) Waits until the render thread has replayed what was handed over up to fence value
/// f: its submits have read the game's memory by then (uniform data copied into the streams, captures taken at the submit or at
Member

This only holds for mirrored pools. memory_capture_submit / capture_make capture "only the pools mirrored in VRAM" (vk_memory.cpp), and everything else is an imported pool the GPU reads in place while it runs. mirror_on() defaults to discrete && !gcn, so on iGPUs (Deck, Intel, APUs) and GCN cards none of the frame's buffers are captured, and q_done >= number says nothing about whether the game may rewrite them.

This only holds for mirrored pools. `memory_capture_submit` / `capture_make` capture "only the pools mirrored in VRAM" (vk_memory.cpp), and everything else is an imported pool the GPU reads in place while it runs. `mirror_on()` defaults to `discrete && !gcn`, so on iGPUs (Deck, Intel, APUs) and GCN cards none of the frame's buffers are captured, and `q_done >= number` says nothing about whether the game may rewrite them.
@ -1114,0 +1127,4 @@
const char *e = getenv("HOS_FRAME_AHEAD");
ahead = !(e && env_value_off(e));
}
if (ahead && c->x[30] == 0x8042cde0ull) {
Member

Suggest gating ahead on the renderer here, not only the switch. For example, nvn_replayed_wait could return "can't vouch" (or the host could ask once) when mirrors are off, or when the frame bound a range with no mirror. In that case fall through to the old wait for s->fence. As it stands, the hardware with no mirrors gets the write-after-read race every frame.

Suggest gating `ahead` on the renderer here, not only the switch. For example, `nvn_replayed_wait` could return "can't vouch" (or the host could ask once) when mirrors are off, or when the frame bound a range with no mirror. In that case fall through to the old wait for `s->fence`. As it stands, the hardware with no mirrors gets the write-after-read race every frame.
Owner

Tested on Linux, which the description lists as not yet run. This PR's commit is rebased onto main @ 43f40b87, which already has #1083. Two conflicts came up: MKWVK_API_VERSION is now 26 (main is at 25), and docs/development.md keeps both sides' rows. The rebased branch is on my fork if you want it: HumanBean:rebase/pr916-on-main. The comment in vk_api.h still says "(version 24)".

The Linux host builds and runs. The log has nvn: the frame limiter waits for the frame before last (HOS_FRAME_AHEAD=0: the frame before).

Hardware: RTX 3090, NVIDIA 620.70.06, Ryzen 9 7900X (24 threads, so the render thread is on), CachyOS.
Settings: DLAA 2560x1440, uncapped.
Route: Hyrule Field, then the Market (teleports), walking and then turning. One build, the default against HOS_FRAME_AHEAD=0, interleaved, two sessions each.

fps (GPU ms) HOS_FRAME_AHEAD=0 default (frame ahead)
Hyrule Field, walking 81.0, 79.5 80.3, 81.6
Hyrule Field, turning 77.7, 79.0 78.5, 80.2
Market, walking 62.8, 64.4 (10.75, 10.65) 62.9, 62.4 (10.70, 10.85)
Market, turning 69.6, 74.0 (8.80, 8.90) 77.5, 77.0 (8.80, 8.50)

On this PC it helps only while turning in the Market, by +4 to +11%. Walking is the same, and Hyrule Field is about +1%. That's smaller than your +12 to 15% on the 4070 SUPER. Here the Field and the Market walking are not held back by the frame limiter's wait.

The flicker isn't counted by this bench: no night scene, and no capture of every present. So the flips you saw are neither confirmed nor ruled out on NVIDIA Linux.

🤖 Generated with Claude Code

Tested on Linux, which the description lists as not yet run. This PR's commit is rebased onto `main` @ 43f40b87, which already has #1083. Two conflicts came up: `MKWVK_API_VERSION` is now 26 (main is at 25), and `docs/development.md` keeps both sides' rows. The rebased branch is on my fork if you want it: [`HumanBean:rebase/pr916-on-main`](https://git.magicbean.dev/HumanBean/Longshot/src/branch/rebase/pr916-on-main). The comment in `vk_api.h` still says "(version 24)". The Linux host builds and runs. The log has `nvn: the frame limiter waits for the frame before last (HOS_FRAME_AHEAD=0: the frame before)`. **Hardware:** RTX 3090, NVIDIA 620.70.06, Ryzen 9 7900X (24 threads, so the render thread is on), CachyOS. **Settings:** DLAA 2560x1440, uncapped. **Route:** Hyrule Field, then the Market (teleports), walking and then turning. One build, the default against `HOS_FRAME_AHEAD=0`, interleaved, two sessions each. | fps (GPU ms) | `HOS_FRAME_AHEAD=0` | default (frame ahead) | |---|---|---| | Hyrule Field, walking | 81.0, 79.5 | 80.3, 81.6 | | Hyrule Field, turning | 77.7, 79.0 | 78.5, 80.2 | | Market, walking | 62.8, 64.4 (10.75, 10.65) | 62.9, 62.4 (10.70, 10.85) | | Market, turning | 69.6, 74.0 (8.80, 8.90) | **77.5, 77.0** (8.80, 8.50) | On this PC it helps only while turning in the Market, by +4 to +11%. Walking is the same, and Hyrule Field is about +1%. That's smaller than your +12 to 15% on the 4070 SUPER. Here the Field and the Market walking are not held back by the frame limiter's wait. The flicker isn't counted by this bench: no night scene, and no capture of every present. So the flips you saw are neither confirmed nor ruled out on NVIDIA Linux. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Member

Closing this: it isn't useful.

The 11-15 % came from letting the game run one frame further ahead of the GPU, but the game reads GPU results (readbacks, occlusion) from the frame before every frame, and its limiter is what makes them ready. With the change it read them a frame early: the shadow and light flicker described above (3.5 % of frames with one-frame flips against 0.1 % without). Made to wait for those results properly (RX_VK_READBACK_EXACT=1) the flicker went and so did the gain (61.5 -> 56.2 and 65.0 -> 63.0 fps in the field). So the speed was the stale reads themselves; there's no version of this that is both faster and correct.

Left here as a record for anyone who tries the same idea.

Closing this: it isn't useful. The 11-15 % came from letting the game run one frame further ahead of the GPU, but the game reads GPU results (readbacks, occlusion) from the frame before every frame, and its limiter is what makes them ready. With the change it read them a frame early: the shadow and light flicker described above (3.5 % of frames with one-frame flips against 0.1 % without). Made to wait for those results properly (`RX_VK_READBACK_EXACT=1`) the flicker went and so did the gain (61.5 -> 56.2 and 65.0 -> 63.0 fps in the field). So the speed was the stale reads themselves; there's no version of this that is both faster and correct. Left here as a record for anyone who tries the same idea.
GummiNaomi closed this pull request 2026-11-16 15:43:28 +00:00
Contributor

Deck measurements, for the record (the PR is closed)

Verdict: on a Steam Deck OLED, this head in a test build (main 0cab3548 + #1150 #1122 #936 #1073 #1104 + this PR) ran within the spread of the same stack without it: 18.37 and 18.04 game fps against 18.57 and 17.64 (+0.6%), with more frames over 100 ms (57 and 66 against 45 and 46). No gain on the Deck. Shadows were not looked at.

Baseline: the before column is the five-PR stack on main 0cab3548 (@ 0b4fd1a3), not main alone. This head (14e165ab) was merged over it for the test, with the MKWVK_API_VERSION clash against #1150 resolved as 27 and both new fields kept (a test build only, never installed).

Hardware, scene, method: as in the other Deck posts of this round: Steam Deck OLED, SteamOS 3.9.5, Mesa 26.2.0-devel, docked 1280x800, Game Mode, 15 W, the GPU at a manual 1600 MHz; the moving Kokiri route through the control bridge, 75 s; a player's options with frame generation and V-Sync off, pinned with HOS_OPTIONS_FILE; 2 runs each interleaved after a warm-up; the game's own fps.

setup D Before: the stack @ 0b4fd1a3 After: the stack + this PR @ 482a2a54
game fps (run 1, run 2; median) 18.57, 17.64; 18.11 18.37, 18.04; 18.21
1% low fps 5.32, 4.69 5.00, 5.29
median / p99 frame time (ms) 49.8 / 152.2, 52.1 / 156.9 50.2 / 155.0, 49.6 / 155.0
frames over 100 ms 45, 46 57, 66
nvn: the frame limiter waits for the frame before last (HOS_FRAME_AHEAD=0: the frame before)
## Deck measurements, for the record (the PR is closed) **Verdict:** on a Steam Deck OLED, this head in a test build (main 0cab3548 + #1150 #1122 #936 #1073 #1104 + this PR) ran within the spread of the same stack without it: 18.37 and 18.04 game fps against 18.57 and 17.64 (+0.6%), with more frames over 100 ms (57 and 66 against 45 and 46). No gain on the Deck. Shadows were not looked at. **Baseline:** the before column is the five-PR stack on main 0cab3548 (@ 0b4fd1a3), not main alone. This head (14e165ab) was merged over it for the test, with the `MKWVK_API_VERSION` clash against #1150 resolved as 27 and both new fields kept (a test build only, never installed). **Hardware, scene, method:** as in the other Deck posts of this round: Steam Deck OLED, SteamOS 3.9.5, Mesa 26.2.0-devel, docked 1280x800, Game Mode, 15 W, the GPU at a manual 1600 MHz; the moving Kokiri route through the control bridge, 75 s; a player's options with frame generation and V-Sync off, pinned with `HOS_OPTIONS_FILE`; 2 runs each interleaved after a warm-up; the game's own fps. | setup D | Before: the stack @ 0b4fd1a3 | After: the stack + this PR @ 482a2a54 | |---|---|---| | game fps (run 1, run 2; median) | 18.57, 17.64; 18.11 | 18.37, 18.04; 18.21 | | 1% low fps | 5.32, 4.69 | 5.00, 5.29 | | median / p99 frame time (ms) | 49.8 / 152.2, 52.1 / 156.9 | 50.2 / 155.0, 49.6 / 155.0 | | frames over 100 ms | 45, 46 | 57, 66 | nvn: the frame limiter waits for the frame before last (HOS_FRAME_AHEAD=0: the frame before)
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 4s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
beanstalk/approval approved by futondestroyer (reviewed)
beanstalk/steamdeck 0/1 pass, 0 running, 0 queued

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
6 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!916
No description provided.