WIP: perf(vk): the render thread replays jobs as they come; whole frames are a test #1121

Draft
nyannoying wants to merge 2 commits from nyannoying/Longshot:perf/vk-frames-as-they-come into main
Contributor

Type: perf · Risk: medium · Tested on: Windows 11, Arc B580 · Needs: Linux, AMD and NVIDIA (Kokiri Forest and the Market standing, the frame log's flash count)

Why

With Threaded rendering on (Auto turns it on with 12 or more logical processors), the render thread waits for each frame's present before it replays any of that frame's work ("whole frames", PR 588). The wait was added because replaying a frame's first submits while the game was still writing the rest drew the lit scene black for one frame. Those moments were also where a submit's capture missed the pages the replay's collection was marking again, which #1083 fixed (merged). With that fix, replaying jobs as they come drew no such frame here, and the wait costs about 6% of the frame rate in Kokiri Forest and 8% in the Market standing, and 10% and 4% walking in Kakariko Village and the Market on an Arc B580.

What changed

The render thread replays jobs as they come again; whole frames become a test switch (RX_VK_FRAME_GATE=1). The present is still handed over after the main thread's signal for its frame, as it was with whole frames, which is what was measured.

  • render thread: gate_on() in gpu/vk/vk_replay.cpp is off unless RX_VK_FRAME_GATE is on; present()'s wait for the CPU's signal no longer follows the gate (on unless RX_VK_PRESENT_AFTER_SIGNAL=0). The comments say why.
  • docs: docs/development.md's RX_VK_ASYNC=1 row; vk_memory.cpp's collect_mu comment names the new default.

Measurements

Verdict: Faster, and no dark frame standing either way. With the defaults, 4 and 4 interleaved sessions standing: Kokiri Forest 86.95 -> 92.4 fps (+6.3%), the Market 53.6 -> 58.0 fps (+8.2%), the medians; the region test counted 0 dark frames in 21,600 before and 0 in 23,400 with this PR. Walking, where the walks take the same way for their first ~9 s (four 120-present windows): Kakariko Village 50.15 -> 55.2 fps (+10.1%), the Market 53.23 -> 55.6 (+4.5%), 4 and 4 sessions; and on one build with only the switch differing (4 sessions with RX_VK_FRAME_GATE=1, 4 with the default), 50.83 -> 54.0 (+6.2%) and 53.62 -> 55.78 (+4.0%). Walking, the region test flags frames with whole frames on as with this PR (the camera passing people, doorways and shadows): over those first 600 frames of each area, 5 darker and 7 brighter in 8 walks with whole frames, 5 and 9 in 8 with this PR; later, once the walks have parted, the Market's are alike (62 and 85 against 61 and 78) and Kakariko Village's are not (7 and 2 against 30 and 16, most of them one walk's burst on its own way). Whole pictures dark while walking: 0 in 8 walks with whole frames, 4 in 8 with this PR and 3 in 2 earlier ones; the 2 the brightness window logged were all still as dark 10 frames later, with the final pass's exposure unchanged: the picture changed and stayed so, not the one-frame black of PR 588. A later walk with whole frames on had 4 too (3 in Kakariko Village, 1 in the Market; a #446 session whose guard bound nothing in place, so the build before's picture): they come with where a walk goes, not with the switch. On the build before, RX_VK_FRAME_GATE=0 (this PR's default) took the Market from 56.8 to 59.85 fps standing (5 and 6 interleaved sessions), 0 and 0 dark frames in 9,000 and 13,800.

Hardware: Windows 11 Pro 10.0.29704, Intel Arc B580 12 GB (driver 32.0.101.9154), Core i5-13600K (20 threads), 64 GB
Scene: Kokiri Forest and Castle Town Market standing, Kakariko Village and the Market walking (child); 1280x720 window, the scene rendered at 960x540 and upscaled with Intel XeSS 2.0.2 (Ultra Quality, #459), no frame generation, HOS_FPS_MAX=240
Method: each session a new start of the game: Kokiri Forest, then the Market by the debug teleport, 40 s to settle and 40 s measured in each: the frame rate from the log's 5 s vi: windows (the median of 8 or 9); dark frames from the region test in the renderer (a local patch, not in this PR, as in #1083: 16x9 regions of every presented frame, a frame counted when 2+ regions are more than 10 levels darker than in both neighbouring frames), over both measured windows. The frame log on over every measured window (RX_VK_FRAMELOG_DROP=1), both sides alike. 8 sessions interleaved (B P P B B P P B). Walking: Kakariko Village, then the Market, the stick held forward 150 frames, right 20, forward 90, left 45, over and over. The walks take the same way for about 10 s and then part (the game's characters move; the draws a frame show it), so their frame rate is compared over each walk's first four windows of 120 presents (the renderer's vk: N presents lines; the median of a session's four, then of the sessions), and their region flashes over the first 600 frames of each area and after. 8 walking sessions interleaved (B P P B B P P B), 2 earlier with this PR alone, and 8 on this PR's build with a second local diagnostic (the picture's brightness 6 frames before and 10 after each whole picture dark, and the final pass's exposure by present), whole frames switched on (RX_VK_FRAME_GATE=1, G) and off (P), interleaved (G P P G G P P G). Before those, the Market alone on the build before, 11 sessions interleaved: whole frames on against RX_VK_FRAME_GATE=0 with RX_VK_PRESENT_AFTER_SIGNAL=1. The Market's frame rate follows its crowd (its draws a frame went from 2,410 to 2,724 between sessions), so it is the noisier of the two
How to reproduce: longshot_ctl.py teleport KokiriForest_Child --arrive 60 then Market_Child; the FPS counter's vi: ... frames presented lines over the window; the frame log RX_VK_FRAMELOG=<file> with scripts/framelog.py <file>.

Baseline: the game folder here runs host 690d8446 (renderer API 22); main's renderer (API 24) does not load in it, so both columns are 690d8446 + #761, #838 + #1083's commits, built from the same source, with and without this PR's commit.

Before: #1083 on 690d8446 + #761, #838 @ fd5238f7 After: this PR @ 862f73d7, on the same
Kokiri Forest fps standing, defaults (4 and 4 sessions; the median) 88.0, 86.7, 87.2, 86.0 (86.95) 93.5, 92.6, 91.9, 92.2 (92.4)
the Market fps standing, the same sessions 55.5, 52.3, 53.3, 53.9 (53.6) 57.8, 53.1, 58.9, 58.2 (58.0)
the Market's draws a frame (its crowd moves; the median) 2,522 2,663
dark frames in the region test standing, both windows of each session 0 of 21,600 0 of 23,400
walking, Kakariko Village fps over the first four 120-present windows (4 and 4 sessions; each session's median, and theirs) 49.5, 48.8, 50.8, 53.3 (50.15) 54.0, 56.3, 57.1, 54.0 (55.2)
walking, the Market fps over the first four 120-present windows (4 and 4 sessions; each session's median, and theirs) 53.2, 57.0, 53.2, 52.5 (53.23) 54.5, 56.0, 56.0, 55.2 (55.6)
the same, this PR's build with whole frames switched on (RX_VK_FRAME_GATE=1, left) and off (4 and 4 sessions), Kakariko Village 53.0, 50.5, 48.0, 51.2 (50.83) 53.8, 54.2, 57.1, 53.1 (54.0)
the same, this PR's build with whole frames switched on (RX_VK_FRAME_GATE=1, left) and off (4 and 4 sessions), the Market 53.8, 53.6, 52.8, 53.7 (53.62) 55.6, 55.9, 56.7, 55.7 (55.78)
walking, Kakariko Village fps over the whole 40 s (not alike: the walks part after ~10 s; 4 and 4 sessions) 52.0, 62.7, 66.5, 61.4 (62.05) 64.9, 67.2, 64.2, 70.4 (66.05)
walking, the Market fps over the whole 40 s (not alike: the walks part after ~10 s; 4 and 4 sessions) 66.7, 62.1, 59.8, 56.7 (60.95) 53.0, 54.3, 53.9, 64.3 (54.1)
walking, region flashes darker / brighter in each area's first 600 frames, the walks still alike (8 walks with whole frames on, left; 8 with this PR) Kakariko Village 5 / 7 · the Market 0 / 0 Kakariko Village 2 / 9 · the Market 3 / 0
the same after, once the walks have parted Kakariko Village 7 / 2 · the Market 62 / 85 Kakariko Village 30 / 16 · the Market 61 / 78
walking, both windows: frames the region test flags, darker and brighter; whole pictures dark 54 darker, 55 brighter of 19,200 (the largest change 90.0); 0 (WB); 20 darker, 39 brighter of 19,800 (the largest change 55.4); 0 (G) 61 darker, 71 brighter of 19,800 (the largest change 74.1); 2 (WP); 35 darker, 34 brighter of 20,400 (the largest change 68.3); 2 (P)
walking, 2 earlier sessions with this PR alone: the same not run 36 darker, 26 brighter of 9,000 (the largest change 37.3); 3
walking, a later session with whole frames on: #446's guard build, which bound nothing in place in it (the build before's picture; #446's docs/tested run05): the same 6 darker, 15 brighter of 4,200 (the largest change 94.3); 4 not run
the build before only, the Market standing: whole frames on (left) against RX_VK_FRAME_GATE=0 + RX_VK_PRESENT_AFTER_SIGNAL=1 (right), 5 and 6 sessions 56.9, 55.6, 57.2, 56.8, 56.1 (56.8) 59.0, 60.3, 60.0, 59.8, 59.6, 59.9 (59.85)
dark frames, the same 0 of 9,000 0 of 13,800
the log's whole-frames line (the gate on) / present-after-signal line, a session 34, 35, 34, 35 / 34, 35, 34, 35 0, 0, 0, 0 / 35, 35, 35, 36
Before (YB1), the last of the render thread's whole-frames lines and the region test at the session's end:
vk: the render thread's whole frames (600 presents): 0 jobs went on before their present after 1000 ms, 0 times a game's thread waited for the work handed over, 0 times for a fence of the frame in the making
vk: region test: 5400 frames compared, 0 with 2+ regions darker than both neighbours by more than 10, 0 brighter; largest darkening 0.7
After (YP1): no whole-frames line; the present still after the CPU's signal, and the region test:
vk: presents after the CPU's signal (600): 459 waited for it, 1.73 ms each, 0 let go after RX_VK_FRAME_GATE_MS
vk: region test: 6000 frames compared, 0 with 2+ regions darker than both neighbours by more than 10, 0 brighter; largest darkening 1.1
DP2, a whole picture dark walking, the picture's mean brightness: the frame before, the dark frame, then the 10 after: 102 -> 48 -> 47 48 49 51 52 53 54 54 54 54
DP2, a whole picture dark walking, the picture's mean brightness: the frame before, the dark frame, then the 10 after: 113 -> 35 -> 35 35 34 34 34 33 32 32 31 32

Flags and settings

One switch changes its default, one becomes independent of it.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_FRAME_GATE Whole frames: the render thread starts a frame's jobs at its present on (=0 turned it off) off (=1 turns it on) +6% fps in Kokiri Forest, +8% in the Market standing here, +10% and +4% walking; no dark frame standing either way helps on an Arc B580; untested on AMD, NVIDIA, Linux off for everyone
RX_VK_PRESENT_AFTER_SIGNAL The present handed over after the main thread's signal for its frame on, following the gate on (=0 turns it off) none: as before as measured on for everyone

Testing

Tested: Windows 11 Pro 10.0.29704, Arc B580 (driver 32.0.101.9154), the renderer built alone with llvm-mingw: 37 runs in docs/tested/ (2026-11-16-frames-as-they-come-nyannoying-run01 to run37): the Market standing on the build before with whole frames on and with RX_VK_FRAME_GATE=0 (11 sessions), Kokiri Forest and the Market standing before and after (8 sessions, no dark frame in any), Kakariko Village and the Market walking before and after (8 sessions), with this PR alone (2) and with this PR's build and a brightness diagnostic, whole frames switched on and off (8); no device loss in any. python -I -B tests/run_all.py at 892c106e (llvm-mingw, Windows, the toolchain's Vulkan headers): 621 passed, 25 failed, 44 skipped; main 60bf15bd on this PC: the same 621, 25 and 44, and the same 25 fail on both test_coverage_run passed in both suites but fails on both whenever no game is running (scripts/coverage/cover.py reads tasklist's German "no tasks" line as cp1252): run alone afterwards, it failed on both.

Not tested: AMD, NVIDIA, Linux, an Intel iGPU, the Steam Deck. Areas other than Kokiri Forest, the Market and their loads.

Must be tested:

  • linux, any GPU: Kokiri Forest and the Market standing 60 s each with RX_VK_FRAMELOG=<file> (pictures kept on your PC), then python -I scripts/framelog.py <file>, expecting no one-frame dark patch more than on main, and fps at least main's (Test Farm: @Beanstalk)
  • windows, amd and nvidia: Kokiri Forest and the Market standing 60 s each with RX_VK_FRAMELOG=<file> (pictures kept on your PC), then python -I scripts/framelog.py <file>, expecting no one-frame dark patch more than on main, and fps at least main's (Test Farm: @Beanstalk)

Risks

What could break: a one-frame black lit scene or ground patch where the render thread catches up with the game, on hardware or in areas not run here.

Turning it off: RX_VK_FRAME_GATE=1, or revert the commit.

Compatibility: Nothing changes: no option, cache or API.

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. (main 60bf15bd: the perf commit's RX_VK_ASYNC row in docs/development.md met main's change to the row above it, and each side's row is kept; git range-diff shows the code unchanged)
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). At 892c106e, with the toolchain's llvm-mingw (bin and its runtime folder first on PATH) and Vulkan headers (RX_CPM): 621 passed, 25 failed, 44 skipped; main 60bf15bd the same (621, 25, 44), the same 25 failing: test_audio_output_devices, test_auto_handheld, test_bug_report_defaults, test_crash_dialog, test_crt_options, test_dlss_feature_size, test_failed_compile_keeps_objects, test_fastfp_fma, test_fpx_sticky, test_fsr_uniform_ownership, test_guest_imported, test_import_reach, test_job_queue, test_linux_preflight, test_make_game_cache, test_missing_nup, test_pads_after_menu, test_parallel_init_order, test_pending_guest_import, test_replay_write_order, test_run_all_changed, test_spawn_emit, test_tested_configurations, test_vk_occlusion_queries, test_walk_key
  • 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).
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Windows (llvm-mingw): yes; Linux: not built here, the Test Farm's Linux run under Must be tested builds it.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Windows 11, Arc B580 · **Needs:** Linux, AMD and NVIDIA (Kokiri Forest and the Market standing, the frame log's flash count) ## Why With Threaded rendering on (Auto turns it on with 12 or more logical processors), the render thread waits for each frame's present before it replays any of that frame's work ("whole frames", PR 588). The wait was added because replaying a frame's first submits while the game was still writing the rest drew the lit scene black for one frame. Those moments were also where a submit's capture missed the pages the replay's collection was marking again, which #1083 fixed (merged). With that fix, replaying jobs as they come drew no such frame here, and the wait costs about 6% of the frame rate in Kokiri Forest and 8% in the Market standing, and 10% and 4% walking in Kakariko Village and the Market on an Arc B580. ## What changed The render thread replays jobs as they come again; whole frames become a test switch (`RX_VK_FRAME_GATE=1`). The present is still handed over after the main thread's signal for its frame, as it was with whole frames, which is what was measured. - render thread: `gate_on()` in `gpu/vk/vk_replay.cpp` is off unless `RX_VK_FRAME_GATE` is on; `present()`'s wait for the CPU's signal no longer follows the gate (on unless `RX_VK_PRESENT_AFTER_SIGNAL=0`). The comments say why. - docs: `docs/development.md`'s `RX_VK_ASYNC=1` row; `vk_memory.cpp`'s `collect_mu` comment names the new default. ## Measurements **Verdict:** Faster, and no dark frame standing either way. With the defaults, 4 and 4 interleaved sessions standing: Kokiri Forest 86.95 -> 92.4 fps (+6.3%), the Market 53.6 -> 58.0 fps (+8.2%), the medians; the region test counted 0 dark frames in 21,600 before and 0 in 23,400 with this PR. Walking, where the walks take the same way for their first ~9 s (four 120-present windows): Kakariko Village 50.15 -> 55.2 fps (+10.1%), the Market 53.23 -> 55.6 (+4.5%), 4 and 4 sessions; and on one build with only the switch differing (4 sessions with `RX_VK_FRAME_GATE=1`, 4 with the default), 50.83 -> 54.0 (+6.2%) and 53.62 -> 55.78 (+4.0%). Walking, the region test flags frames with whole frames on as with this PR (the camera passing people, doorways and shadows): over those first 600 frames of each area, 5 darker and 7 brighter in 8 walks with whole frames, 5 and 9 in 8 with this PR; later, once the walks have parted, the Market's are alike (62 and 85 against 61 and 78) and Kakariko Village's are not (7 and 2 against 30 and 16, most of them one walk's burst on its own way). Whole pictures dark while walking: 0 in 8 walks with whole frames, 4 in 8 with this PR and 3 in 2 earlier ones; the 2 the brightness window logged were all still as dark 10 frames later, with the final pass's exposure unchanged: the picture changed and stayed so, not the one-frame black of PR 588. A later walk with whole frames on had 4 too (3 in Kakariko Village, 1 in the Market; a #446 session whose guard bound nothing in place, so the build before's picture): they come with where a walk goes, not with the switch. On the build before, `RX_VK_FRAME_GATE=0` (this PR's default) took the Market from 56.8 to 59.85 fps standing (5 and 6 interleaved sessions), 0 and 0 dark frames in 9,000 and 13,800. Hardware: Windows 11 Pro 10.0.29704, Intel Arc B580 12 GB (driver 32.0.101.9154), Core i5-13600K (20 threads), 64 GB Scene: Kokiri Forest and Castle Town Market standing, Kakariko Village and the Market walking (child); 1280x720 window, the scene rendered at 960x540 and upscaled with Intel XeSS 2.0.2 (Ultra Quality, #459), no frame generation, `HOS_FPS_MAX=240` Method: each session a new start of the game: Kokiri Forest, then the Market by the debug teleport, 40 s to settle and 40 s measured in each: the frame rate from the log's 5 s `vi:` windows (the median of 8 or 9); dark frames from the region test in the renderer (a local patch, not in this PR, as in #1083: 16x9 regions of every presented frame, a frame counted when 2+ regions are more than 10 levels darker than in both neighbouring frames), over both measured windows. The frame log on over every measured window (`RX_VK_FRAMELOG_DROP=1`), both sides alike. 8 sessions interleaved (B P P B B P P B). Walking: Kakariko Village, then the Market, the stick held forward 150 frames, right 20, forward 90, left 45, over and over. The walks take the same way for about 10 s and then part (the game's characters move; the draws a frame show it), so their frame rate is compared over each walk's first four windows of 120 presents (the renderer's `vk: N presents` lines; the median of a session's four, then of the sessions), and their region flashes over the first 600 frames of each area and after. 8 walking sessions interleaved (B P P B B P P B), 2 earlier with this PR alone, and 8 on this PR's build with a second local diagnostic (the picture's brightness 6 frames before and 10 after each whole picture dark, and the final pass's exposure by present), whole frames switched on (`RX_VK_FRAME_GATE=1`, G) and off (P), interleaved (G P P G G P P G). Before those, the Market alone on the build before, 11 sessions interleaved: whole frames on against `RX_VK_FRAME_GATE=0` with `RX_VK_PRESENT_AFTER_SIGNAL=1`. The Market's frame rate follows its crowd (its draws a frame went from 2,410 to 2,724 between sessions), so it is the noisier of the two How to reproduce: `longshot_ctl.py teleport KokiriForest_Child --arrive 60` then `Market_Child`; the FPS counter's `vi: ... frames presented` lines over the window; the frame log `RX_VK_FRAMELOG=<file>` with `scripts/framelog.py <file>`. Baseline: the game folder here runs host 690d8446 (renderer API 22); main's renderer (API 24) does not load in it, so both columns are 690d8446 + #761, #838 + #1083's commits, built from the same source, with and without this PR's commit. | | Before: #1083 on 690d8446 + #761, #838 @ fd5238f7 | After: this PR @ 862f73d7, on the same | |---|---|---| | Kokiri Forest fps standing, defaults (4 and 4 sessions; the median) | 88.0, 86.7, 87.2, 86.0 (86.95) | 93.5, 92.6, 91.9, 92.2 (92.4) | | the Market fps standing, the same sessions | 55.5, 52.3, 53.3, 53.9 (53.6) | 57.8, 53.1, 58.9, 58.2 (58.0) | | the Market's draws a frame (its crowd moves; the median) | 2,522 | 2,663 | | dark frames in the region test standing, both windows of each session | 0 of 21,600 | 0 of 23,400 | | walking, Kakariko Village fps over the first four 120-present windows (4 and 4 sessions; each session's median, and theirs) | 49.5, 48.8, 50.8, 53.3 (50.15) | 54.0, 56.3, 57.1, 54.0 (55.2) | | walking, the Market fps over the first four 120-present windows (4 and 4 sessions; each session's median, and theirs) | 53.2, 57.0, 53.2, 52.5 (53.23) | 54.5, 56.0, 56.0, 55.2 (55.6) | | the same, this PR's build with whole frames switched on (`RX_VK_FRAME_GATE=1`, left) and off (4 and 4 sessions), Kakariko Village | 53.0, 50.5, 48.0, 51.2 (50.83) | 53.8, 54.2, 57.1, 53.1 (54.0) | | the same, this PR's build with whole frames switched on (`RX_VK_FRAME_GATE=1`, left) and off (4 and 4 sessions), the Market | 53.8, 53.6, 52.8, 53.7 (53.62) | 55.6, 55.9, 56.7, 55.7 (55.78) | | walking, Kakariko Village fps over the whole 40 s (not alike: the walks part after ~10 s; 4 and 4 sessions) | 52.0, 62.7, 66.5, 61.4 (62.05) | 64.9, 67.2, 64.2, 70.4 (66.05) | | walking, the Market fps over the whole 40 s (not alike: the walks part after ~10 s; 4 and 4 sessions) | 66.7, 62.1, 59.8, 56.7 (60.95) | 53.0, 54.3, 53.9, 64.3 (54.1) | | walking, region flashes darker / brighter in each area's first 600 frames, the walks still alike (8 walks with whole frames on, left; 8 with this PR) | Kakariko Village 5 / 7 · the Market 0 / 0 | Kakariko Village 2 / 9 · the Market 3 / 0 | | the same after, once the walks have parted | Kakariko Village 7 / 2 · the Market 62 / 85 | Kakariko Village 30 / 16 · the Market 61 / 78 | | walking, both windows: frames the region test flags, darker and brighter; whole pictures dark | 54 darker, 55 brighter of 19,200 (the largest change 90.0); 0 (WB); 20 darker, 39 brighter of 19,800 (the largest change 55.4); 0 (G) | 61 darker, 71 brighter of 19,800 (the largest change 74.1); 2 (WP); 35 darker, 34 brighter of 20,400 (the largest change 68.3); 2 (P) | | walking, 2 earlier sessions with this PR alone: the same | not run | 36 darker, 26 brighter of 9,000 (the largest change 37.3); 3 | | walking, a later session with whole frames on: #446's guard build, which bound nothing in place in it (the build before's picture; #446's docs/tested run05): the same | 6 darker, 15 brighter of 4,200 (the largest change 94.3); 4 | not run | | the build before only, the Market standing: whole frames on (left) against `RX_VK_FRAME_GATE=0` + `RX_VK_PRESENT_AFTER_SIGNAL=1` (right), 5 and 6 sessions | 56.9, 55.6, 57.2, 56.8, 56.1 (56.8) | 59.0, 60.3, 60.0, 59.8, 59.6, 59.9 (59.85) | | dark frames, the same | 0 of 9,000 | 0 of 13,800 | | the log's whole-frames line (the gate on) / present-after-signal line, a session | 34, 35, 34, 35 / 34, 35, 34, 35 | 0, 0, 0, 0 / 35, 35, 35, 36 | ``` Before (YB1), the last of the render thread's whole-frames lines and the region test at the session's end: vk: the render thread's whole frames (600 presents): 0 jobs went on before their present after 1000 ms, 0 times a game's thread waited for the work handed over, 0 times for a fence of the frame in the making vk: region test: 5400 frames compared, 0 with 2+ regions darker than both neighbours by more than 10, 0 brighter; largest darkening 0.7 After (YP1): no whole-frames line; the present still after the CPU's signal, and the region test: vk: presents after the CPU's signal (600): 459 waited for it, 1.73 ms each, 0 let go after RX_VK_FRAME_GATE_MS vk: region test: 6000 frames compared, 0 with 2+ regions darker than both neighbours by more than 10, 0 brighter; largest darkening 1.1 DP2, a whole picture dark walking, the picture's mean brightness: the frame before, the dark frame, then the 10 after: 102 -> 48 -> 47 48 49 51 52 53 54 54 54 54 DP2, a whole picture dark walking, the picture's mean brightness: the frame before, the dark frame, then the 10 after: 113 -> 35 -> 35 35 34 34 34 33 32 32 31 32 ``` ### Flags and settings One switch changes its default, one becomes independent of it. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_FRAME_GATE` | Whole frames: the render thread starts a frame's jobs at its present | on (`=0` turned it off) | off (`=1` turns it on) | +6% fps in Kokiri Forest, +8% in the Market standing here, +10% and +4% walking; no dark frame standing either way | helps on an Arc B580; untested on AMD, NVIDIA, Linux | off for everyone | | `RX_VK_PRESENT_AFTER_SIGNAL` | The present handed over after the main thread's signal for its frame | on, following the gate | on (`=0` turns it off) | none: as before | as measured | on for everyone | ## Testing **Tested:** Windows 11 Pro 10.0.29704, Arc B580 (driver 32.0.101.9154), the renderer built alone with llvm-mingw: 37 runs in `docs/tested/` (`2026-11-16-frames-as-they-come-nyannoying-run01` to `run37`): the Market standing on the build before with whole frames on and with `RX_VK_FRAME_GATE=0` (11 sessions), Kokiri Forest and the Market standing before and after (8 sessions, no dark frame in any), Kakariko Village and the Market walking before and after (8 sessions), with this PR alone (2) and with this PR's build and a brightness diagnostic, whole frames switched on and off (8); no device loss in any. `python -I -B tests/run_all.py` at 892c106e (llvm-mingw, Windows, the toolchain's Vulkan headers): 621 passed, 25 failed, 44 skipped; `main` 60bf15bd on this PC: the same 621, 25 and 44, and the same 25 fail on both `test_coverage_run` passed in both suites but fails on both whenever no game is running (`scripts/coverage/cover.py` reads `tasklist`'s German "no tasks" line as cp1252): run alone afterwards, it failed on both. **Not tested:** AMD, NVIDIA, Linux, an Intel iGPU, the Steam Deck. Areas other than Kokiri Forest, the Market and their loads. **Must be tested:** - linux, any GPU: Kokiri Forest and the Market standing 60 s each with `RX_VK_FRAMELOG=<file>` (pictures kept on your PC), then `python -I scripts/framelog.py <file>`, expecting no one-frame dark patch more than on main, and fps at least main's (Test Farm: @Beanstalk) - windows, amd and nvidia: Kokiri Forest and the Market standing 60 s each with `RX_VK_FRAMELOG=<file>` (pictures kept on your PC), then `python -I scripts/framelog.py <file>`, expecting no one-frame dark patch more than on main, and fps at least main's (Test Farm: @Beanstalk) ## Risks **What could break:** a one-frame black lit scene or ground patch where the render thread catches up with the game, on hardware or in areas not run here. **Turning it off:** `RX_VK_FRAME_GATE=1`, or revert the commit. **Compatibility:** Nothing changes: no option, cache or API. ## 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`. (main 60bf15bd: the perf commit's `RX_VK_ASYNC` row in `docs/development.md` met main's change to the row above it, and each side's row is kept; `git range-diff` shows the code unchanged) - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). At 892c106e, with the toolchain's llvm-mingw (`bin` and its runtime folder first on `PATH`) and Vulkan headers (`RX_CPM`): 621 passed, 25 failed, 44 skipped; `main` 60bf15bd the same (621, 25, 44), the same 25 failing: `test_audio_output_devices`, `test_auto_handheld`, `test_bug_report_defaults`, `test_crash_dialog`, `test_crt_options`, `test_dlss_feature_size`, `test_failed_compile_keeps_objects`, `test_fastfp_fma`, `test_fpx_sticky`, `test_fsr_uniform_ownership`, `test_guest_imported`, `test_import_reach`, `test_job_queue`, `test_linux_preflight`, `test_make_game_cache`, `test_missing_nup`, `test_pads_after_menu`, `test_parallel_init_order`, `test_pending_guest_import`, `test_replay_write_order`, `test_run_all_changed`, `test_spawn_emit`, `test_tested_configurations`, `test_vk_occlusion_queries`, `test_walk_key` - [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`). - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Windows (llvm-mingw): yes; Linux: not built here, the Test Farm's Linux run under Must be tested builds it. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
With Threaded rendering on, the render thread waited for each frame's present before it
replayed any of that frame's work (whole frames, PR 588), because replaying a frame's first
submits while the game was still writing the rest drew the lit scene black for one frame.
Those moments were also where a submit's capture missed the pages the replay's collection was
marking again, which #1083 fixes. With that fixed, jobs replayed as they come drew no such
frame in 23,400 frames on an Arc B580 (Kokiri Forest and the Market standing, four sessions
interleaved with four of whole frames), and the wait cost 86.95 -> 92.4 fps in Kokiri Forest
and 53.6 -> 58.0 in the Market (medians).

gate_on() is now off unless RX_VK_FRAME_GATE is on (=1: whole frames, a test). The present
is still handed over after the main thread's signal for its frame, as with whole frames,
which is what was measured (RX_VK_PRESENT_AFTER_SIGNAL=0, a test: at once).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs(tested): jobs replayed as they come on an Arc B580, 37 files
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
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
Guide screenshots / Guide images and local UI source review (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
Website / Website on Cloudflare (pull_request) Has been cancelled
9d5e0897f0
One file a measured run, Windows 11, Arc B580 (101.9154): the Market standing on the build before with whole frames on
and with RX_VK_FRAME_GATE=0 (11 sessions); Kokiri Forest and the Market standing before and after (8); Kakariko Village
and the Market walking before and after (8) and with this branch alone (2); and the same walks on this branch with a
local brightness diagnostic, whole frames switched on and off (8). No device loss in any.

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

Tested in game: Windows 11 Pro 10.0.29704, Intel Arc B580 12 GB (driver 32.0.101.9154), Core i5-13600K. Kokiri Forest and Castle Town Market standing, 4 and 4 interleaved sessions: 86.95 -> 92.4 fps and 53.6 -> 58.0 fps (medians); the region test counted 0 dark frames in 23,400 with this PR (0 in 21,600 before). Kakariko Village and the Market walking, 4 and 4 sessions: 50.15 -> 55.2 and 53.23 -> 55.6 fps over the walks' first ~9 s. Whole pictures dark while walking come with where a walk goes, with whole frames on as well as off (4 in a later walk with them on). No device loss in 37 runs.

Tested in game: Windows 11 Pro 10.0.29704, Intel Arc B580 12 GB (driver 32.0.101.9154), Core i5-13600K. Kokiri Forest and Castle Town Market standing, 4 and 4 interleaved sessions: 86.95 -> 92.4 fps and 53.6 -> 58.0 fps (medians); the region test counted 0 dark frames in 23,400 with this PR (0 in 21,600 before). Kakariko Village and the Market walking, 4 and 4 sessions: 50.15 -> 55.2 and 53.23 -> 55.6 fps over the walks' first ~9 s. Whole pictures dark while walking come with where a walk goes, with whole frames on as well as off (4 in a later walk with them on). No device loss in 37 runs.
Author
Contributor

@Beanstalk please run this PR against main on Linux (any GPU), and on Windows with an AMD and an NVIDIA card: Kokiri Forest and Castle Town Market standing, 60 s each, with the frame log on (RX_VK_FRAMELOG=; the pictures stay on your PC), then python -I scripts/framelog.py . Expected: no more one-frame dark patches than on main, and fps at least main's. With this PR the render thread replays a frame's jobs as they come instead of waiting for its present (whole frames, now RX_VK_FRAME_GATE=1).

@Beanstalk please run this PR against main on Linux (any GPU), and on Windows with an AMD and an NVIDIA card: Kokiri Forest and Castle Town Market standing, 60 s each, with the frame log on (RX_VK_FRAMELOG=<file>; the pictures stay on your PC), then python -I scripts/framelog.py <file>. Expected: no more one-frame dark patches than on main, and fps at least main's. With this PR the render thread replays a frame's jobs as they come instead of waiting for its present (whole frames, now RX_VK_FRAME_GATE=1).
Collaborator

Possibly related, for context:

  • PR #588 perf(vk): a render thread for the replay, behind a Threaded rendering setting (Auto: on from 12 logical processors) — Merged whole-frame replay gate being made optional.
Possibly related, for context: - PR #588 perf(vk): a render thread for the replay, behind a Threaded rendering setting (Auto: on from 12 logical processors) — Merged whole-frame replay gate being made optional.
Member

@nyannoying only members of BigBeans can start the farm.

One of them can approve this request by reacting 👍 to it. This request was for 9d5e089, and the PR has changed since (892c106), so a 👍 no longer approves it. Comment @Beanstalk again to ask for the new commit.

@nyannoying only members of `BigBeans` can start the farm. ~~One of them can approve this request by reacting 👍 to it.~~ This request was for `9d5e089`, and the PR has changed since (`892c106`), so a 👍 no longer approves it. Comment `@Beanstalk` again to ask for the new commit.
Owner

Tested on Linux NVIDIA, which "Must be tested" asks for. Both commits are rebased onto main @ 43f40b87 with no conflicts, as one build. The default (jobs as they come) is run against RX_VK_FRAME_GATE=1 (whole frames, main's behaviour), interleaved, two sessions each.

Hardware: RTX 3090, NVIDIA 620.70.06, Ryzen 9 7900X (24 threads: render thread and the recorder thread), CachyOS.
Settings: DLAA 2560x1440, uncapped.
Route: Hyrule Field, then the Market (teleports), walking and then turning.

The switch does what it says. With =1 the log has the whole frames (600 presents) lines, as main does. With the default there are none, and presents after the CPU's signal shows the present still waits for the signal.

fps (GPU ms) RX_VK_FRAME_GATE=1 (whole frames) default (this PR)
Hyrule Field, walking 80.2, 79.9 81.5, 78.3
Hyrule Field, turning 77.8, 81.7 81.8, 81.9
Market, walking 63.6, 61.5 60.7, 62.6
Market, turning 72.2, 71.3 (8.90, 8.80) 72.8, 72.6 (8.80, 8.50)

On this PC there is no measurable difference: everything is within 1 to 2%, and in no consistent direction. The whole-frames wait doesn't cost anything here, unlike the 6 to 8% on your Arc B580. Frame-time tails are the same either way, with p99 17 to 24 ms in both arms.

Not counted: dark frames. My bench walks and turns, headless and with no frame log, so neither the region test you describe nor scripts/framelog.py was run here.

🤖 Generated with Claude Code

Tested on Linux NVIDIA, which "Must be tested" asks for. Both commits are rebased onto `main` @ 43f40b87 with no conflicts, as one build. The default (jobs as they come) is run against `RX_VK_FRAME_GATE=1` (whole frames, main's behaviour), interleaved, two sessions each. **Hardware:** RTX 3090, NVIDIA 620.70.06, Ryzen 9 7900X (24 threads: `render thread and the recorder thread`), CachyOS. **Settings:** DLAA 2560x1440, uncapped. **Route:** Hyrule Field, then the Market (teleports), walking and then turning. The switch does what it says. With `=1` the log has the `whole frames (600 presents)` lines, as main does. With the default there are none, and `presents after the CPU's signal` shows the present still waits for the signal. | fps (GPU ms) | `RX_VK_FRAME_GATE=1` (whole frames) | default (this PR) | |---|---|---| | Hyrule Field, walking | 80.2, 79.9 | 81.5, 78.3 | | Hyrule Field, turning | 77.8, 81.7 | 81.8, 81.9 | | Market, walking | 63.6, 61.5 | 60.7, 62.6 | | Market, turning | 72.2, 71.3 (8.90, 8.80) | 72.8, 72.6 (8.80, 8.50) | On this PC there is no measurable difference: everything is within 1 to 2%, and in no consistent direction. The whole-frames wait doesn't cost anything here, unlike the 6 to 8% on your Arc B580. Frame-time tails are the same either way, with p99 17 to 24 ms in both arms. **Not counted:** dark frames. My bench walks and turns, headless and with no frame log, so neither the region test you describe nor `scripts/framelog.py` was run here. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Author
Contributor

Description only, no code change:

  • The After column's header now reads After: this PR @ 862f73d7, on the same (the template's form).
  • Must be tested's AMD and NVIDIA line now says what to run and what to expect, as the Linux line does.

What is left before ready: the Linux build, which the Test Farm's Linux run under Must be tested makes (its request waits for a BigBean's approval).

🤖 Generated with Claude Code

Description only, no code change: - The After column's header now reads `After: this PR @ 862f73d7, on the same` (the template's form). - Must be tested's AMD and NVIDIA line now says what to run and what to expect, as the Linux line does. What is left before ready: the Linux build, which the Test Farm's Linux run under Must be tested makes (its request waits for a BigBean's approval). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
nyannoying force-pushed perf/vk-frames-as-they-come from 9d5e0897f0
Some checks failed
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
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
Guide screenshots / Guide images and local UI source review (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
Website / Website on Cloudflare (pull_request) Has been cancelled
to 892c106ef0
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 4s
2026-11-16 18:11:53 +00:00
Compare
Author
Contributor

Rebased onto main 60bf15bd: head 892c106e.

  • One conflict, in docs/development.md: main dropped ", GCN" from the Threaded rendering row (#1187), and this PR rewrites the RX_VK_ASYNC row under it. Each side's row is kept.
  • gpu/vk/vk_replay.cpp and gpu/vk/vk_memory.cpp merged without a conflict; git range-diff shows this PR's code unchanged.

Checked at 892c106e:

  • Built at the new head: the renderer alone (RX_VK_ONLY, llvm-mingw), 0 warnings.
  • python -I -B tests/run_all.py (llvm-mingw and the toolchain's Vulkan headers): 621 passed, 25 failed, 44 skipped, the same as main 60bf15bd, with the same 25 failing. More checks run than at the last count (559 passed), because the Vulkan headers were on hand this time.

Why the numbers still hold, not measured again: the code diff is the same, and the A/B was this diff on and off on one build of the game folder's source (the Baseline line). Of main's changes to the same files, #977's early reads never run with the render thread (readback_early.h), and #1187's mirrors are for GCN cards.

🤖 Generated with Claude Code

Rebased onto `main` 60bf15bd: head 892c106e. - One conflict, in `docs/development.md`: `main` dropped ", GCN" from the Threaded rendering row (#1187), and this PR rewrites the `RX_VK_ASYNC` row under it. Each side's row is kept. - `gpu/vk/vk_replay.cpp` and `gpu/vk/vk_memory.cpp` merged without a conflict; `git range-diff` shows this PR's code unchanged. Checked at 892c106e: - Built at the new head: the renderer alone (`RX_VK_ONLY`, llvm-mingw), 0 warnings. - `python -I -B tests/run_all.py` (llvm-mingw and the toolchain's Vulkan headers): 621 passed, 25 failed, 44 skipped, the same as `main` 60bf15bd, with the same 25 failing. More checks run than at the last count (559 passed), because the Vulkan headers were on hand this time. Why the numbers still hold, not measured again: the code diff is the same, and the A/B was this diff on and off on one build of the game folder's source (the Baseline line). Of `main`'s changes to the same files, #977's early reads never run with the render thread (`readback_early.h`), and #1187's mirrors are for GCN cards. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Some checks are pending
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
beanstalk/approval changed since the request: ask again
PR description / Description follows the template (pull_request_target) Successful in 4s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/vk-frames-as-they-come:nyannoying-perf/vk-frames-as-they-come'
git switch 'nyannoying-perf/vk-frames-as-they-come'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
4 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!1121
No description provided.