WIP: fix(vk): the presenter thread keeps the swapchain's external sync, and a drain that gives up is safe #1043

Draft
TrashPanda wants to merge 2 commits from TrashPanda/Longshot:perf/stage2-presenter into main
Contributor

Type: fix · Risk: low · Tested on: Linux, RTX 4070 Ti · Needs: AMD (Windows and Linux), Windows NVIDIA and the Steam Deck before RX_VK_PRESENT_THREAD could become the default (a later PR, only if it measures faster there)

Stage 2 of the renderer memory-sync redesign. Independent of #1034 and #1037: it branches from main.

Why

The presenter thread (RX_VK_PRESENT_THREAD=1) presents each frame off the game's thread once its copy is done, which measured 19-20 ms a frame against 22-23 ms on an RTX 3090 under Wayland. It stayed off because of two problems written up next to it in vk_replay.cpp: the swapchain was used from two threads without the external synchronization Vulkan requires, and a drain that gave up after 5 s could leave the presenter presenting to a destroyed swapchain. This PR fixes both, so the switch is safe to measure on more hardware. It does not turn it on.

What changed

  • External sync: every host access to the swapchain takes the new dev.swapchain_mu (gpu/vk/vk_internal.h): the acquire, both present paths, the presenter's wait for a present to be shown (in short polls, so the acquire doesn't wait for the frame to be shown), and create_swapchain/retire_swapchain. Lock order: after present_mu, before present_queue_mu and presenter_queue_mu; never held over device_wait_idle_locked.
  • A drain that gives up is safe: the presenter presents only to the swapchain it was handed, and only while it is still the current one (dev.swapchain_generation), checked under the lock. A present dropped that way is counted in its 600-present line ("N not made (their swapchain made again)").
  • No acquire waits on the presenter under the lock: when the swapchain has no spare image for the one the presenter still holds (swap_spare), the acquire drains the presenter first.
  • Tests: tests/test_present_thread.py checks the lock around each swapchain call and the generation check; tests/test_present_semaphores.py follows the moved semaphore line.

Measurements

Verdict: On this PC the presenter thread neither helps nor hurts: the frame here is not waiting on the present (the copy's fence is 2-5 ms, the present 0.04-0.11 ms). It stays off by default. No present was dropped and no error appeared, so the fix holds in normal running; a resize during the drain was not exercised (headless).

Hardware: Ubuntu 26.04.1 LTS (kernel 7.0.0-43), RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D, 32 GB
Scene: Kokiri Forest (teleport 0) and Hyrule Field (teleport 1) from the repo save kokiri-start, the camera turning; 1920x1080, no upscaler, HOS_FPS_MAX=240, headless (HOS_NO_SDL=1)
Method: this PR @ 178a1794 with RX_VK_PRESENT_THREAD=1 against unset, the runs alternated; each run's second 20 s window, fps from HOS_PRESENT_TRACE

off (main's behaviour) RX_VK_PRESENT_THREAD=1
Kokiri Forest, fps (median frame) 116.1 (8.40 ms), 120.1 (8.23) 119.6 (8.29), 120.6 (8.25)
Hyrule Field, fps (median frame) 113.1 (8.82), 113.8 (8.77), 113.3 (8.79) 112.4 (8.82), 112.4 (8.83), 100.5 (9.43)*
Hyrule Field, p99 9.7-10.2 ms 10.8 ms

* One run had 91 ms hitches that its log doesn't explain: as many slow submits as an off run (23), the same VRAM. The two runs either side of it are 112.4.

vk: presenter thread: the copy's fence 2.46 ms, the present 0.06 ms a present; 0 not made (their swapchain made again)
vk: presenter thread: the copy's fence 4.48 ms, the present 0.06 ms a present; 0 not made (their swapchain made again)

The tested-configurations row is docs/tested/2026-11-15-present-thread-trashpanda-ab.md.

Flags and settings

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_PRESENT_THREAD=1 presents on a thread and queue of their own off, unsafe with two threads on the swapchain off, safe the game's thread doesn't wait in vkQueuePresentKHR doesn't help on RTX 4070 Ti, Linux; helped on RTX 3090, Wayland before (19-20 ms against 22-23); untested on AMD, Windows, Deck off until measured where the present wait costs

Testing

Tested: tests/test_present_thread.py and tests/test_present_semaphores.py, and python -I -B tests/run_all.py with only the failures main has too. In the game: the runs above, 5 with the thread on.

Not tested: Windows, AMD, the Steam Deck; a window resized or the surface lost while the presenter holds a present (the drain path).

Must be tested: before the default flips, frame time with and without the switch on AMD (Windows and Linux), Windows NVIDIA and the Deck, with a window resized during play. A test request will follow.

Risks

What could break: the lock is taken around the acquire and the present with the switch off too; it is uncontended there (one thread), so it costs a lock a call. A wrong lock order would deadlock at a resize; the order is written next to the mutex and the test checks the calls.

Turning it off: RX_VK_PRESENT_THREAD unset (the default) for the presenter; revert for the lock.

Compatibility: no API change.

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

  • 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: not needed, vk_api.h unchanged.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.
**Type:** fix · **Risk:** low · **Tested on:** Linux, RTX 4070 Ti · **Needs:** AMD (Windows and Linux), Windows NVIDIA and the Steam Deck before `RX_VK_PRESENT_THREAD` could become the default (a later PR, only if it measures faster there) Stage 2 of the renderer memory-sync redesign. Independent of #1034 and #1037: it branches from `main`. ## Why The presenter thread (`RX_VK_PRESENT_THREAD=1`) presents each frame off the game's thread once its copy is done, which measured 19-20 ms a frame against 22-23 ms on an RTX 3090 under Wayland. It stayed off because of two problems written up next to it in `vk_replay.cpp`: the swapchain was used from two threads without the external synchronization Vulkan requires, and a drain that gave up after 5 s could leave the presenter presenting to a destroyed swapchain. This PR fixes both, so the switch is safe to measure on more hardware. It does not turn it on. ## What changed - **External sync:** every host access to the swapchain takes the new `dev.swapchain_mu` (`gpu/vk/vk_internal.h`): the acquire, both present paths, the presenter's wait for a present to be shown (in short polls, so the acquire doesn't wait for the frame to be shown), and `create_swapchain`/`retire_swapchain`. Lock order: after `present_mu`, before `present_queue_mu` and `presenter_queue_mu`; never held over `device_wait_idle_locked`. - **A drain that gives up is safe:** the presenter presents only to the swapchain it was handed, and only while it is still the current one (`dev.swapchain_generation`), checked under the lock. A present dropped that way is counted in its 600-present line ("N not made (their swapchain made again)"). - **No acquire waits on the presenter under the lock:** when the swapchain has no spare image for the one the presenter still holds (`swap_spare`), the acquire drains the presenter first. - Tests: `tests/test_present_thread.py` checks the lock around each swapchain call and the generation check; `tests/test_present_semaphores.py` follows the moved semaphore line. ## Measurements **Verdict:** On this PC the presenter thread neither helps nor hurts: the frame here is not waiting on the present (the copy's fence is 2-5 ms, the present 0.04-0.11 ms). It stays off by default. No present was dropped and no error appeared, so the fix holds in normal running; a resize during the drain was not exercised (headless). Hardware: Ubuntu 26.04.1 LTS (kernel 7.0.0-43), RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D, 32 GB Scene: Kokiri Forest (teleport 0) and Hyrule Field (teleport 1) from the repo save `kokiri-start`, the camera turning; 1920x1080, no upscaler, `HOS_FPS_MAX=240`, headless (`HOS_NO_SDL=1`) Method: this PR @ 178a1794 with `RX_VK_PRESENT_THREAD=1` against unset, the runs alternated; each run's second 20 s window, fps from `HOS_PRESENT_TRACE` | | off (main's behaviour) | `RX_VK_PRESENT_THREAD=1` | |---|---|---| | Kokiri Forest, fps (median frame) | 116.1 (8.40 ms), 120.1 (8.23) | 119.6 (8.29), 120.6 (8.25) | | Hyrule Field, fps (median frame) | 113.1 (8.82), 113.8 (8.77), 113.3 (8.79) | 112.4 (8.82), 112.4 (8.83), 100.5 (9.43)* | | Hyrule Field, p99 | 9.7-10.2 ms | 10.8 ms | \* One run had 91 ms hitches that its log doesn't explain: as many slow submits as an off run (23), the same VRAM. The two runs either side of it are 112.4. ``` vk: presenter thread: the copy's fence 2.46 ms, the present 0.06 ms a present; 0 not made (their swapchain made again) vk: presenter thread: the copy's fence 4.48 ms, the present 0.06 ms a present; 0 not made (their swapchain made again) ``` The tested-configurations row is `docs/tested/2026-11-15-present-thread-trashpanda-ab.md`. ### Flags and settings | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_PRESENT_THREAD=1` | presents on a thread and queue of their own | off, unsafe with two threads on the swapchain | off, safe | the game's thread doesn't wait in `vkQueuePresentKHR` | doesn't help on RTX 4070 Ti, Linux; helped on RTX 3090, Wayland before (19-20 ms against 22-23); untested on AMD, Windows, Deck | off until measured where the present wait costs | ## Testing **Tested:** `tests/test_present_thread.py` and `tests/test_present_semaphores.py`, and `python -I -B tests/run_all.py` with only the failures `main` has too. In the game: the runs above, 5 with the thread on. **Not tested:** Windows, AMD, the Steam Deck; a window resized or the surface lost while the presenter holds a present (the drain path). **Must be tested:** before the default flips, frame time with and without the switch on AMD (Windows and Linux), Windows NVIDIA and the Deck, with a window resized during play. A test request will follow. ## Risks **What could break:** the lock is taken around the acquire and the present with the switch off too; it is uncontended there (one thread), so it costs a lock a call. A wrong lock order would deadlock at a resize; the order is written next to the mutex and the test checks the calls. **Turning it off:** `RX_VK_PRESENT_THREAD` unset (the default) for the presenter; revert for the lock. **Compatibility:** no API change. ## 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] 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`). - [ ] `MKWVK_API_VERSION` bumped: not needed, `vk_api.h` unchanged. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated.
RX_VK_PRESENT_THREAD stayed off until two findings were fixed:

- The swapchain is externally synchronized in Vulkan, but the presenter presented (and waited for
  the present to be shown) on it while the game's thread acquired its next image, and
  create_swapchain passed it as oldSwapchain. Every host access now takes dev.swapchain_mu:
  acquire, both present paths, the presenter's wait (in short polls, the lock let go between them,
  so the acquire does not wait for the frame to be shown), create and destroy.
- present_thread_drain gives up after 5 s, after which the swapchain may be made again and the old
  one destroyed with its semaphores, while the presenter could still present to it. The presenter
  now presents only to the swapchain it was handed, if it is still the current one (its
  generation), checked under the lock; presents dropped that way are counted in its 600-present line.

The acquire also drains the presenter first when the swapchain has no spare image for the one the
presenter still holds (swap_spare), so the acquire cannot wait on that present under the lock.
docs(tested): the presenter thread A/B on an RTX 4070 Ti, Linux
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
PR description / Description follows the template (pull_request_target) Successful in 3s
Website / Website on Cloudflare (pull_request_target) Has been skipped
58b492249c
Author
Contributor

Tested in game: Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02: Kokiri Forest and Hyrule Field from kokiri-start, the camera turning, RX_VK_PRESENT_THREAD=1 against unset alternated (5 runs on, 5 off). Same fps both ways (Kokiri 119.6/120.6 on against 116.1/120.1 off; Hyrule 112.4 on against 113.1-113.8 off); presenter's copy fence 2-5 ms, present 0.04-0.11 ms, 0 presents dropped, no error lines. Resize during the drain not exercised (headless).

Tested in game: Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02: Kokiri Forest and Hyrule Field from kokiri-start, the camera turning, RX_VK_PRESENT_THREAD=1 against unset alternated (5 runs on, 5 off). Same fps both ways (Kokiri 119.6/120.6 on against 116.1/120.1 off; Hyrule 112.4 on against 113.1-113.8 off); presenter's copy fence 2-5 ms, present 0.04-0.11 ms, 0 presents dropped, no error lines. Resize during the drain not exercised (headless).
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
PR description / Description follows the template (pull_request_target) Successful in 3s
Website / Website on Cloudflare (pull_request_target) Has been skipped
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/stage2-presenter:TrashPanda-perf/stage2-presenter'
git switch 'TrashPanda-perf/stage2-presenter'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!1043
No description provided.