fix(vk): make the swapchain again when the window's held image never comes back #2083

Merged
HumanBean merged 2 commits from HumanBean/Longshot:fix/fg-held-image-remake into main 2026-11-21 17:26:44 +00:00
Owner

Summary

With frame generation on (the built-in one or FSR 3), on an RX 9070 XT under Windows in full screen, the picture froze after Alt+Tab while the game and its sound went on; leaving full screen (F11) brought it back. Five reports, still on nightly-617 and v3.0.0, and lately sometimes with no Alt+Tab at all.

The cause is in the hold that #1458 added for #1376. AMD's Windows driver hands an image back from vkAcquireNextImageKHR at once and signals its fence once the system lets the image go. An image that isn't free within 250 ms is held, and every later present looks at it again without waiting, and presents nothing else. The system lets an image go when another one is shown, and none ever is, so the image never comes back, even once the game is in front again. Only a new swapchain (F11) lets it go. The reporter's log (#1482, nightly-455) shows it: the window's image was not given back in 250 ms right after game window not in front, still no given back after game window in front, and the picture back only after display: windowed made the swapchain again. Frame generation makes it far more likely: two presents a frame, a set's images acquired ahead, and the display thread's presents waiting on each other. Any single 250 ms hitch (Alt+Tab, an overlay, a mode switch in full screen) then freezes the picture for good. That would also explain the freezes with no Alt+Tab.

Now an image held for 1 s counts as never coming back, and the present makes the swapchain again itself, the same remake F11 does: the presenter drained first, the queue's lock held, the held image and its fence let go as #1458 already handles at a new swapchain. While the window stays hidden, the new chain's first image is held again, so the remakes are kept apart: the next one after 2 s, then every 4 s while no image comes back, and the count starts over once one does. A remake that cannot be made (a window with no size) is tried again only after that wait, not at every present. Each remake is logged (vk: the window's image was not given back in N s: the swapchain made again, the first 16).

Read first: present_image_with_trial's hold in gpu/vk/vk_replay.cpp (after image_free), and held_remake_due / kHeldRemakeNs beside kImageFreeNs.

Fixes #1482. See #1376, #1458.

Testing

Tested: Linux (X11), RTX 3090, NVIDIA 620.70.06, this PR @ 19680d95 as a pack over main 9dd41326's base, through the job queue, with fg_alttab_run.py: kokiri-start save to play, frame generation 2x by the built-in generator, then by FSR 3.1 FG; for each, F11 twice (windowed and back), the window minimized and raised with xdotool, and a walk. After each of the 12 steps the presents went on (frames replayed before and after, about 60 fps) and the shot showed the scene moving. No crash or device loss. As expected on NVIDIA, no image was held, so the log has no not given back or the swapchain made again line: the new code didn't run here. The held-image path needs AMD on Windows (Beanstalk).

Checks: tests/test_present_held_image.py is new. It cuts present_image's acquire, its submit and the image helpers out of vk_replay.cpp and runs them, on each platform's side of _WIN32, against a model engine that hands images back at once and lets them go later (AMD on Windows), with a clock. On main it fails ("the window seen again, its held image never let go: no frame copied in 3 s"). Here it checks:

  • a hold the system ends itself within a second makes no new swapchain;
  • a held image that is never let go makes the swapchain again within 1.5 s, with the presenter drained and the queue's lock held, and one frame is copied for each present after it;
  • with the window hidden for 20 s, the remakes are kept apart (3 to 7), and frames are shown within 5 s of the window being seen again;
  • a failed remake is not tried again at every present.

Three broken variants (no remake, no back-off, a failed remake retried at each present) must fail. test_present_image_free.py and test_present_acquire_ahead.py cut the same code; their models' holds stay under 1 s, so they don't change. The tests were not run on this PC (its rule: no test suites here). CI on the forge runs them.

Still to test:

  • Windows, AMD RX 9000 or 7000, frame generation on (the built-in one, then FSR 3), full screen: Alt+Tab to another window for 10 s and back, several times, then play 10 minutes in full screen. Expect the picture to come back within about 1 to 5 s of returning, never frozen until F11, and the swapchain made again lines in the log at those times (@Beanstalk, request below).
  • Windows, NVIDIA, frame generation on, the same Alt+Tab steps. Expect no change: those drivers wait in the acquire, so no hold (@Beanstalk).

Beanstalk request (to post as a comment):

@Beanstalk Windows with an AMD RX 9000 or 7000 card, and one NVIDIA RTX card: set frame generation on (the built-in 2x first, then FSR 3 frame generation), full screen, in Hyrule Field. Alt+Tab to another window for about 10 seconds and back, 5 times; then play 10 minutes in full screen without Alt+Tab. Check that the picture always comes back moving within 5 seconds of returning (on main, the picture stays frozen until F11 while the sound goes on). Post the log lines with "not given back" and "the swapchain made again", and say whether the picture ever froze.

Measurements

Verdict: fixes the freeze in the model, the test failing on main and passing here. This PC can't reach the hold (NVIDIA on Linux waits in the acquire), so there is no on-screen before and after here. No cost while the window is seen: the new code runs only on a present that finds its image held.

Setup: tests/test_present_held_image.py (CI); in-game: one run on this PC (Testing)

Before: main @ 9dd41326 After: this PR @ 19680d95
test_present_held_image.py fails: no frame copied in 3 s after the window is seen again passes (CI)
reporter's log (RX 9070 XT, FG 2x, full screen) not given back in 250 ms, then frozen until display: windowed Beanstalk to confirm
in-game here (RTX 3090, Linux, FG on, F11 and focus changes) same path, not reached here presents go on after each of 12 steps; the hold not reached

Risks

  • While the window stays hidden behind another one with an image held (AMD on Windows, full screen), the swapchain is made again after 1 s, then after 2 s, then every 4 s: each time a device idle wait and a new swapchain while nothing is shown, and a few log lines. The game is in the background then.
  • Back from Alt+Tab, the picture can take up to 4 s to come back (the back-off) instead of staying frozen.
  • Nothing changes when no image is held: other GPUs, windows that are shown, Linux (where the acquire waits, or unseen gives none). A revert is enough to undo it. No switch, no saved setting.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit.
  • Tested on my own PC, in the game for a change the game runs, as Testing says.
  • mise run test passes (any failure that also fails on main is named). (Not run on this PC, its rule: CI on the forge runs it.)
  • Measured against main, or Measurements says why there is nothing to measure.
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

  • A fix: a game-free test that fails on main and passes here. (Written to fail on main and pass here; not run on this PC, CI to confirm.)
  • A check under tests/ that reads changed source is updated, not weakened. (test_present_image_free.py and test_present_acquire_ahead.py read the changed hold. Their holds stay under 1 s, so they need no change. CI to confirm.)
  • Docs updated. (docs/dev/reference/threads.md, the present's hold.)
  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.

Ready to merge

  • Everything in Still to test has run, its results in Tested.
  • Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers").
  • Approved in review, every comment answered.
  • CI passes on the head; on current main, measured again or a comment says why the numbers still hold.

🤖 Generated with Claude Code

https://claude.ai/code/session_017vw8e2uxGKQxzDeQ15jjNK

## Summary With frame generation on (the built-in one or FSR 3), on an RX 9070 XT under Windows in full screen, the picture froze after Alt+Tab while the game and its sound went on; leaving full screen (F11) brought it back. Five reports, still on nightly-617 and v3.0.0, and lately sometimes with no Alt+Tab at all. The cause is in the hold that [#1458](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1458) added for [#1376](https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1376). AMD's Windows driver hands an image back from `vkAcquireNextImageKHR` at once and signals its fence once the system lets the image go. An image that isn't free within 250 ms is held, and every later present looks at it again without waiting, and presents nothing else. The system lets an image go when another one is shown, and none ever is, so the image never comes back, even once the game is in front again. Only a new swapchain (F11) lets it go. The reporter's log ([#1482](https://git.magicbean.dev/MagicBeanDev/Longshot/issues/1482), nightly-455) shows it: `the window's image was not given back in 250 ms` right after `game window not in front`, still no `given back` after `game window in front`, and the picture back only after `display: windowed` made the swapchain again. Frame generation makes it far more likely: two presents a frame, a set's images acquired ahead, and the display thread's presents waiting on each other. Any single 250 ms hitch (Alt+Tab, an overlay, a mode switch in full screen) then freezes the picture for good. That would also explain the freezes with no Alt+Tab. Now an image held for 1 s counts as never coming back, and the present makes the swapchain again itself, the same remake F11 does: the presenter drained first, the queue's lock held, the held image and its fence let go as #1458 already handles at a new swapchain. While the window stays hidden, the new chain's first image is held again, so the remakes are kept apart: the next one after 2 s, then every 4 s while no image comes back, and the count starts over once one does. A remake that cannot be made (a window with no size) is tried again only after that wait, not at every present. Each remake is logged (`vk: the window's image was not given back in N s: the swapchain made again`, the first 16). Read first: `present_image_with_trial`'s hold in `gpu/vk/vk_replay.cpp` (after `image_free`), and `held_remake_due` / `kHeldRemakeNs` beside `kImageFreeNs`. Fixes #1482. See #1376, #1458. ## Testing **Tested:** Linux (X11), RTX 3090, NVIDIA 620.70.06, this PR @ 19680d95 as a pack over main 9dd41326's base, through the job queue, with `fg_alttab_run.py`: kokiri-start save to play, frame generation 2x by the built-in generator, then by FSR 3.1 FG; for each, F11 twice (windowed and back), the window minimized and raised with xdotool, and a walk. After each of the 12 steps the presents went on (frames replayed before and after, about 60 fps) and the shot showed the scene moving. No crash or device loss. As expected on NVIDIA, no image was held, so the log has no `not given back` or `the swapchain made again` line: the new code didn't run here. The held-image path needs AMD on Windows (Beanstalk). Checks: `tests/test_present_held_image.py` is new. It cuts `present_image`'s acquire, its submit and the image helpers out of `vk_replay.cpp` and runs them, on each platform's side of `_WIN32`, against a model engine that hands images back at once and lets them go later (AMD on Windows), with a clock. On `main` it fails ("the window seen again, its held image never let go: no frame copied in 3 s"). Here it checks: - a hold the system ends itself within a second makes no new swapchain; - a held image that is never let go makes the swapchain again within 1.5 s, with the presenter drained and the queue's lock held, and one frame is copied for each present after it; - with the window hidden for 20 s, the remakes are kept apart (3 to 7), and frames are shown within 5 s of the window being seen again; - a failed remake is not tried again at every present. Three broken variants (no remake, no back-off, a failed remake retried at each present) must fail. `test_present_image_free.py` and `test_present_acquire_ahead.py` cut the same code; their models' holds stay under 1 s, so they don't change. **The tests were not run on this PC (its rule: no test suites here). CI on the forge runs them.** **Still to test:** - Windows, AMD RX 9000 or 7000, frame generation on (the built-in one, then FSR 3), full screen: Alt+Tab to another window for 10 s and back, several times, then play 10 minutes in full screen. Expect the picture to come back within about 1 to 5 s of returning, never frozen until F11, and `the swapchain made again` lines in the log at those times (@Beanstalk, request below). - Windows, NVIDIA, frame generation on, the same Alt+Tab steps. Expect no change: those drivers wait in the acquire, so no hold (@Beanstalk). Beanstalk request (to post as a comment): > @Beanstalk Windows with an AMD RX 9000 or 7000 card, and one NVIDIA RTX card: set frame generation on (the built-in 2x first, then FSR 3 frame generation), full screen, in Hyrule Field. Alt+Tab to another window for about 10 seconds and back, 5 times; then play 10 minutes in full screen without Alt+Tab. Check that the picture always comes back moving within 5 seconds of returning (on main, the picture stays frozen until F11 while the sound goes on). Post the log lines with "not given back" and "the swapchain made again", and say whether the picture ever froze. ## Measurements **Verdict:** fixes the freeze in the model, the test failing on `main` and passing here. This PC can't reach the hold (NVIDIA on Linux waits in the acquire), so there is no on-screen before and after here. No cost while the window is seen: the new code runs only on a present that finds its image held. Setup: `tests/test_present_held_image.py` (CI); in-game: one run on this PC (Testing) | | Before: main @ 9dd41326 | After: this PR @ 19680d95 | |---|---|---| | test_present_held_image.py | fails: no frame copied in 3 s after the window is seen again | passes (CI) | | reporter's log (RX 9070 XT, FG 2x, full screen) | `not given back in 250 ms`, then frozen until `display: windowed` | Beanstalk to confirm | | in-game here (RTX 3090, Linux, FG on, F11 and focus changes) | same path, not reached here | presents go on after each of 12 steps; the hold not reached | ## Risks - While the window stays hidden behind another one with an image held (AMD on Windows, full screen), the swapchain is made again after 1 s, then after 2 s, then every 4 s: each time a device idle wait and a new swapchain while nothing is shown, and a few log lines. The game is in the background then. - Back from Alt+Tab, the picture can take up to 4 s to come back (the back-off) instead of staying frozen. - Nothing changes when no image is held: other GPUs, windows that are shown, Linux (where the acquire waits, or `unseen` gives none). A revert is enough to undo it. No switch, no saved setting. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [x] Tested on my own PC, in the game for a change the game runs, as Testing says. - [ ] `mise run test` passes (any failure that also fails on `main` is named). (Not run on this PC, its rule: CI on the forge runs it.) - [x] Measured against `main`, or Measurements says why there is nothing to measure. - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [ ] A fix: a game-free test that fails on `main` and passes here. (Written to fail on `main` and pass here; not run on this PC, CI to confirm.) - [x] A check under `tests/` that reads changed source is updated, not weakened. (`test_present_image_free.py` and `test_present_acquire_ahead.py` read the changed hold. Their holds stay under 1 s, so they need no change. CI to confirm.) - [x] Docs updated. (`docs/dev/reference/threads.md`, the present's hold.) - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. ### Ready to merge - [ ] Everything in Still to test has run, its results in Tested. - [ ] Tier 1 hardware it can affect is tested (docs/dev/standards.md, "Hardware tiers"). - [ ] Approved in review, every comment answered. - [ ] CI passes on the head; on current `main`, measured again or a comment says why the numbers still hold. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017vw8e2uxGKQxzDeQ15jjNK
Fails on main: the held image is looked at forever and no frame is copied again.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
fix(vk): make the swapchain again when the window's held image never comes back (#1482)
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 20s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 28s
CI / Workflow lint (actionlint) (pull_request) Successful in 33s
Third-party parts / As their notes say (pull_request) Successful in 35s
CI / Website build and checks (pull_request) Successful in 4m10s
beanstalk/approval can't be tested as asked: see the farm's comment
PR description / Description follows the template (pull_request_target) Failing after 28s
19680d95d4
With frame generation on an RX 9070 XT (Windows, full screen) an image held after Alt+Tab
(#1458's hold) was never given back, even with the game in front again: nothing else was
presented while it was held, and the system lets an image go when another is shown. The game
and its sound went on, the picture froze until F11 made the swapchain again. An image held for
1 s now makes the swapchain again, then after 2 s and every 4 s while none comes back.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Author
Owner

Tested in game: Linux X11, RTX 3090, NVIDIA 620.70.06, this PR @ 19680d95 over main 9dd41326's base, through the job queue: kokiri-start, frame generation 2x built-in then FSR 3.1 FG; F11 twice, minimize and raise, walk, for each. Presents went on after all 12 steps at ~60 fps, no crash. NVIDIA holds no image, so the new remake path didn't run here: it needs AMD on Windows (Beanstalk).

Tested in game: Linux X11, RTX 3090, NVIDIA 620.70.06, this PR @ 19680d95 over main 9dd41326's base, through the job queue: kokiri-start, frame generation 2x built-in then FSR 3.1 FG; F11 twice, minimize and raise, walk, for each. Presents went on after all 12 steps at ~60 fps, no crash. NVIDIA holds no image, so the new remake path didn't run here: it needs AMD on Windows (Beanstalk).
Author
Owner

@Beanstalk Windows with an AMD RX 9000 or 7000 card, and one NVIDIA RTX card: set frame generation on (the built-in 2x first, then FSR 3 frame generation), full screen, in Hyrule Field. Alt+Tab to another window for about 10 seconds and back, 5 times; then play 10 minutes in full screen without Alt+Tab. Check that the picture always comes back moving within 5 seconds of returning (on main, the picture stays frozen until F11 while the sound goes on). Post the log lines with "not given back" and "the swapchain made again", and say whether the picture ever froze.

@Beanstalk Windows with an AMD RX 9000 or 7000 card, and one NVIDIA RTX card: set frame generation on (the built-in 2x first, then FSR 3 frame generation), full screen, in Hyrule Field. Alt+Tab to another window for about 10 seconds and back, 5 times; then play 10 minutes in full screen without Alt+Tab. Check that the picture always comes back moving within 5 seconds of returning (on main, the picture stays frozen until F11 while the sound goes on). Post the log lines with "not given back" and "the swapchain made again", and say whether the picture ever froze.
Member

Beanstalk test farm · ⛔ can't be tested as asked

Commit 19680d9 · approved by HumanBean (untrusted) · dashboard

Not run: the farm can't test this as asked, so nothing is built or run:

The requested Alt+Tab cycles, visible-picture recovery within five seconds, and freeze assessment cannot be exercised or observed by the farm's unattended hidden-window scenarios. The alternative can exercise the present path and collect matching logs, but cannot establish that the reported freeze is fixed.

⚠️ Note: The alternative omits the five focus changes and ten-minute full-screen play period; missing held-image logs are unjudged because the run may never reach that path.
⚠️ Note: Frame-time measurements are not proof that the displayed picture is moving.

What it could test instead: The alternative plan runs full-screen Hyrule Field on Windows AMD RX 7000/9000 and NVIDIA RTX PCs, comparing main and the PR with built-in and FSR frame generation. It measures frame times and records whether held-image log lines appear; a crash, device loss, or substantial frame-time regression fails the plan. The two frame-generation modes are separate matrix cells, and the run takes about 21 minutes per tester.

A member of BigBeans can comment @Beanstalk <new words> to ask for something else, or @Beanstalk test it anyway to run the plan regardless.

<!-- beanstalk:sticky --> ### Beanstalk test farm · ⛔ can't be tested as asked Commit `19680d9` · approved by HumanBean (untrusted) · [dashboard](https://beanstalk.magicbean.dev/prs/2083) **Not run: the farm can't test this as asked**, so nothing is built or run: > The requested Alt+Tab cycles, visible-picture recovery within five seconds, and freeze assessment cannot be exercised or observed by the farm's unattended hidden-window scenarios. The alternative can exercise the present path and collect matching logs, but cannot establish that the reported freeze is fixed. ⚠️ **Note:** The alternative omits the five focus changes and ten-minute full-screen play period; missing held-image logs are unjudged because the run may never reach that path. ⚠️ **Note:** Frame-time measurements are not proof that the displayed picture is moving. What it could test instead: The alternative plan runs full-screen Hyrule Field on Windows AMD RX 7000/9000 and NVIDIA RTX PCs, comparing main and the PR with built-in and FSR frame generation. It measures frame times and records whether held-image log lines appear; a crash, device loss, or substantial frame-time regression fails the plan. The two frame-generation modes are separate matrix cells, and the run takes about 21 minutes per tester. A member of `BigBeans` can comment `@Beanstalk <new words>` to ask for something else, or `@Beanstalk test it anyway` to run the plan regardless.
HumanBean changed title from WIP: fix(vk): make the swapchain again when the window's held image never comes back to fix(vk): make the swapchain again when the window's held image never comes back 2026-11-21 17:26:11 +00:00
HumanBean deleted branch fix/fg-held-image-remake 2026-11-21 17:26:48 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
2 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!2083
No description provided.