perf(vk): a start whose driver lost its shader cache builds the pipelines again before the title, not with draws left out in play #1188

Merged
HumanBean merged 1 commit from GummiNaomi/Longshot:perf/cold-cache-check into main 2026-11-16 17:24:42 +00:00
Member

Type: perf · Risk: low · Tested on: Windows 11, RTX 4070 SUPER (NVIDIA 617.42) · Needs: AMD on Windows; Linux (RADV, NVIDIA); a Steam Deck; a real driver update

Why

After a driver update, or once NVIDIA's shader cache evicts past its size (it is shared with every other game), the first session plays with large parts of the picture missing for seconds at a time, and only the next start puts it right.

A start that loads programs at their create calls (RX_VK_LOAD=create, the default) trusts the marker that says every noted pipeline was built into the pipeline cache. On NVIDIA that cache only refers to the driver's own: with the driver's cache gone, each listed pipeline is in no cache, is compiled in play, and its draws are left out meanwhile. Measured on the gate route with NVIDIA's cache pointed at an empty folder: 10,263 listed pipelines in no cache, 702,312 draws left out in 140 s (in 21 of 163 two-second spans, up to 1,172 a frame there, of about 2,500), and 21 s of draw waits. The safety net then sends the next start to building every listed program before the title (longshot_load_start.txt, which keeps them all for good, 4-5 GB of memory at every later start per load_default.h).

Things that did not help here, for the record: stage libraries (RX_VK_GPL=1) kept in our pipeline cache came back cold too (1,968 of 2,070 libraries, 964,332 draws left out); quick pipelines (RX_VK_QUICK_MS=8) left out 92 % fewer draws but each took 14-80 ms on NVIDIA (frames over 50 ms 46 -> 148, 1 % low 47 -> 29 fps); VK_KHR_pipeline_binary binaries kept by us also need NVIDIA's cache warm (143 of 8,000 made from them on another empty cache).

What changed

A start that would load at create calls first asks the driver whether it still has a sample of the noted pipelines; where it has lost most of them, it builds them all again before the title, behind the progress screen, instead of in play.

  • vk: notes_lost_by_driver() asks the driver alone (an empty scratch pipeline cache) for 48 noted pipelines spread over the notes file, without compiling (VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT, needs pipelineCreationCacheControl). Where at least a third were asked and over half are cold, precompile_run removes the built marker and runs the existing warm pass (precompile_warm) at this start (gpu/vk/vk_draw.cpp). Not in the preparation's own process (LONGSHOT_PREPARE_ONLY, read here, not a new switch). The thread's driver-only state, the scratch cache and the file are put back by a guard however the function ends. RX_VK_COLD_CHECK=0: not asked.
  • tests: tests/test_cold_cache_check.py (the sample asked of the driver alone without a compile, the threshold, the warm pass run after a lost sample, the guard).
  • docs: RX_VK_COLD_CHECK in docs/development.md; docs/tested/2026-11-16-cold-cache-check-gumminaomi.md.

Measurements

Verdict: with the driver's cache lost, the first session draws almost everything (456 draws left out against 702,312, no waits against 21 s), for a 4.5-minute build before the title on 16 threads; with it intact, the check costs about 0.2 s a start and changes nothing.

Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB
Scene: save set "First Step into Hyrule Town", Castle Town's gate into Hyrule Field and back (gate-bridge-wall.txt, wall clock), 2560x1440, DLAA, uncapped, RX_VK_LOAD=create
Method: headless runs; a cold driver cache by __GL_SHADER_DISK_CACHE_PATH=<an empty folder> (NVIDIA's Windows driver honours it; the player's own cache untouched); the log's a frame: lines summed (draws left out, waits) and its shader cache has and precompile: lines
Baseline: main's behaviour is this PR with RX_VK_COLD_CHECK=0; the before column is main 13e90a5e's run (cold-1) with #1158's changes beside it, the after column this change on main 71b1edd8, then rebased onto main 26ce01b5 (warm check run again there: 48 of 48 in 220 ms). The numbers still hold on 26ce01b5: the one change to this path since 13e90a5e is #903 (f9a2195c), which writes the pipeline cache before the title after a long build; on NVIDIA that cache refers to the driver's own, so with the driver's cache emptied the listed pipelines are cold just the same (the cold run itself was on 71b1edd8, which has #903)
How to reproduce: point __GL_SHADER_DISK_CACHE_PATH at an empty folder on NVIDIA, start once; compare with RX_VK_COLD_CHECK=0

Before: main @ 13e90a5e (cold-1) After: this PR @ 5045adf3
Warm driver cache: the check — 48 of 48 asked, 220-224 ms, nothing built
Cold driver cache: the check — 0 of 48, 87 ms: lost
Cold: built before the title none (the next start does) 39,171 noted + 9,927 compute pipelines in 271 s on 16 threads
Cold: draws left out in play (140 s) 702,312 (21 of 163 spans) 456 (5 of 191 spans)
Cold: draw waits in play 21.3 s 0

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
RX_VK_COLD_CHECK ask the driver for a sample of the notes at a load-at-create start (none) 1 a lost driver cache built again before the title helps on the RTX 4070 SUPER with NVIDIA's cache emptied; untested on AMD, Intel, RADV 1

Testing

Tested: Windows 11, RTX 4070 SUPER, NVIDIA 617.42: warm starts (the check passes, nothing built) and a cold start (lost, built, played); tests/test_cold_cache_check.py passes; python -I -B tests/run_all.py: the same 64 failing tests as main 26ce01b5 on this PC (its toolchain: Windows line endings, fixtures needing gcc or clang++), plus tests/test_longshot_ctl.py's relaunch case, which fails in some full runs on Windows and passes alone here and on main (a timing flake in the control bridge's stand-in; nothing this PR touches).

Not tested: a real driver update, AMD (whose Windows driver keeps few entries of its cache), Intel, Linux, the Steam Deck, where 4 cores make the build before the title much longer.

Must be tested:

  • AMD on Windows: start, then start again a few minutes later, expecting the log's the driver's shader cache has N of 48 line; on a driver that keeps its cache a high N and nothing built, else the build before the title and no draws left out in play (by hand)
  • Linux, any GPU: the same, expecting the same (Test Farm: @Beanstalk linux)
  • A Steam Deck: a start after a Mesa update, expecting the build before the title and how long it took on 4 cores (by hand)

Risks

What could break: a driver that answers a cache ask wrongly as cold makes every start build the notes again before the title (3-4 s with them in the driver's cache, as the first start after a preparation; minutes if not). A long build before the title on a slow CPU after a driver update, which the next start did anyway; the check moves it to the start that needs it.

Turning it off: RX_VK_COLD_CHECK=0.

Compatibility: Nothing changes.

Issues

None found for this exactly; the safety net it comes before is load_default.h's.

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.
  • 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).
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows only.)

🤖 Generated with Claude Code

**Type:** perf · **Risk:** low · **Tested on:** Windows 11, RTX 4070 SUPER (NVIDIA 617.42) · **Needs:** AMD on Windows; Linux (RADV, NVIDIA); a Steam Deck; a real driver update ## Why After a driver update, or once NVIDIA's shader cache evicts past its size (it is shared with every other game), the first session plays with large parts of the picture missing for seconds at a time, and only the next start puts it right. A start that loads programs at their create calls (`RX_VK_LOAD=create`, the default) trusts the marker that says every noted pipeline was built into the pipeline cache. On NVIDIA that cache only refers to the driver's own: with the driver's cache gone, each listed pipeline is in no cache, is compiled in play, and its draws are left out meanwhile. Measured on the gate route with NVIDIA's cache pointed at an empty folder: 10,263 listed pipelines in no cache, 702,312 draws left out in 140 s (in 21 of 163 two-second spans, up to 1,172 a frame there, of about 2,500), and 21 s of draw waits. The safety net then sends the next start to building every listed program before the title (`longshot_load_start.txt`, which keeps them all for good, 4-5 GB of memory at every later start per `load_default.h`). Things that did not help here, for the record: stage libraries (`RX_VK_GPL=1`) kept in our pipeline cache came back cold too (1,968 of 2,070 libraries, 964,332 draws left out); quick pipelines (`RX_VK_QUICK_MS=8`) left out 92 % fewer draws but each took 14-80 ms on NVIDIA (frames over 50 ms 46 -> 148, 1 % low 47 -> 29 fps); `VK_KHR_pipeline_binary` binaries kept by us also need NVIDIA's cache warm (143 of 8,000 made from them on another empty cache). ## What changed A start that would load at create calls first asks the driver whether it still has a sample of the noted pipelines; where it has lost most of them, it builds them all again before the title, behind the progress screen, instead of in play. - vk: `notes_lost_by_driver()` asks the driver alone (an empty scratch pipeline cache) for 48 noted pipelines spread over the notes file, without compiling (`VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT`, needs `pipelineCreationCacheControl`). Where at least a third were asked and over half are cold, `precompile_run` removes the built marker and runs the existing warm pass (`precompile_warm`) at this start (`gpu/vk/vk_draw.cpp`). Not in the preparation's own process (`LONGSHOT_PREPARE_ONLY`, read here, not a new switch). The thread's driver-only state, the scratch cache and the file are put back by a guard however the function ends. `RX_VK_COLD_CHECK=0`: not asked. - tests: `tests/test_cold_cache_check.py` (the sample asked of the driver alone without a compile, the threshold, the warm pass run after a lost sample, the guard). - docs: `RX_VK_COLD_CHECK` in `docs/development.md`; `docs/tested/2026-11-16-cold-cache-check-gumminaomi.md`. ## Measurements **Verdict:** with the driver's cache lost, the first session draws almost everything (456 draws left out against 702,312, no waits against 21 s), for a 4.5-minute build before the title on 16 threads; with it intact, the check costs about 0.2 s a start and changes nothing. Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB Scene: save set "First Step into Hyrule Town", Castle Town's gate into Hyrule Field and back (gate-bridge-wall.txt, wall clock), 2560x1440, DLAA, uncapped, `RX_VK_LOAD=create` Method: headless runs; a cold driver cache by `__GL_SHADER_DISK_CACHE_PATH=<an empty folder>` (NVIDIA's Windows driver honours it; the player's own cache untouched); the log's `a frame:` lines summed (draws left out, waits) and its `shader cache has` and `precompile:` lines Baseline: main's behaviour is this PR with `RX_VK_COLD_CHECK=0`; the before column is main 13e90a5e's run (cold-1) with #1158's changes beside it, the after column this change on main 71b1edd8, then rebased onto main 26ce01b5 (warm check run again there: 48 of 48 in 220 ms). The numbers still hold on 26ce01b5: the one change to this path since 13e90a5e is #903 (f9a2195c), which writes the pipeline cache before the title after a long build; on NVIDIA that cache refers to the driver's own, so with the driver's cache emptied the listed pipelines are cold just the same (the cold run itself was on 71b1edd8, which has #903) How to reproduce: point `__GL_SHADER_DISK_CACHE_PATH` at an empty folder on NVIDIA, start once; compare with `RX_VK_COLD_CHECK=0` | | Before: main @ 13e90a5e (cold-1) | After: this PR @ 5045adf3 | |---|---|---| | Warm driver cache: the check | — | 48 of 48 asked, 220-224 ms, nothing built | | Cold driver cache: the check | — | 0 of 48, 87 ms: lost | | Cold: built before the title | none (the next start does) | 39,171 noted + 9,927 compute pipelines in 271 s on 16 threads | | Cold: draws left out in play (140 s) | 702,312 (21 of 163 spans) | 456 (5 of 191 spans) | | Cold: draw waits in play | 21.3 s | 0 | ### 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 | |---|---|---|---|---|---|---| | `RX_VK_COLD_CHECK` | ask the driver for a sample of the notes at a load-at-create start | (none) | 1 | a lost driver cache built again before the title | helps on the RTX 4070 SUPER with NVIDIA's cache emptied; untested on AMD, Intel, RADV | 1 | ## Testing **Tested:** Windows 11, RTX 4070 SUPER, NVIDIA 617.42: warm starts (the check passes, nothing built) and a cold start (lost, built, played); `tests/test_cold_cache_check.py` passes; `python -I -B tests/run_all.py`: the same 64 failing tests as main 26ce01b5 on this PC (its toolchain: Windows line endings, fixtures needing gcc or clang++), plus `tests/test_longshot_ctl.py`'s relaunch case, which fails in some full runs on Windows and passes alone here and on main (a timing flake in the control bridge's stand-in; nothing this PR touches). **Not tested:** a real driver update, AMD (whose Windows driver keeps few entries of its cache), Intel, Linux, the Steam Deck, where 4 cores make the build before the title much longer. **Must be tested:** - AMD on Windows: start, then start again a few minutes later, expecting the log's `the driver's shader cache has N of 48` line; on a driver that keeps its cache a high N and nothing built, else the build before the title and no draws left out in play (by hand) - Linux, any GPU: the same, expecting the same (Test Farm: @Beanstalk linux) - A Steam Deck: a start after a Mesa update, expecting the build before the title and how long it took on 4 cores (by hand) ## Risks **What could break:** a driver that answers a cache ask wrongly as cold makes every start build the notes again before the title (3-4 s with them in the driver's cache, as the first start after a preparation; minutes if not). A long build before the title on a slow CPU after a driver update, which the next start did anyway; the check moves it to the start that needs it. **Turning it off:** `RX_VK_COLD_CHECK=0`. **Compatibility:** Nothing changes. ## Issues None found for this exactly; the safety net it comes before is `load_default.h`'s. ## 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] 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] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows only.) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
perf(vk): a start whose driver lost its shader cache builds the pipelines again before the title, not with draws left out in play
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
CI / Conventional Commit title (pull_request) Successful in 7s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 11s
CI / Workflow lint (actionlint) (pull_request) Successful in 12s
Third-party parts / As their notes say (pull_request) Successful in 16s
PR description / Description follows the template (pull_request_target) Failing after 4s
5045adf3fb
A start that loads at create calls trusts the marker that says every note
was built into the pipeline cache. On NVIDIA that cache only refers to the
driver's own, which a driver update empties and which evicts past its size
(it is shared with every other game): each listed pipeline was then compiled
in play with its draws left out. On the gate route with NVIDIA's cache
pointed at an empty folder: 10,263 listed pipelines in no cache, 702,312
draws left out in 140 s, 21 s of draw waits; only the next start built them
before the title (and through load_default's marker kept them all for good).

Now such a start first asks the driver alone (an empty scratch pipeline
cache, without compiling) for 48 notes spread over the file; where most are
gone the marker goes and the warm pass runs at this start, behind its
progress. Warm: 48 of 48 in 224 ms, nothing more. Cold: 0 of 48 in 87 ms,
the notes built in 271 s on 16 threads, then 456 draws left out and no
waits. RX_VK_COLD_CHECK=0: not asked.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
GummiNaomi changed title from WIP: perf(vk): a start whose driver lost its shader cache builds the pipelines again before the title, not with draws left out in play to perf(vk): a start whose driver lost its shader cache builds the pipelines again before the title, not with draws left out in play 2026-11-16 17:15:38 +00:00
HumanBean deleted branch perf/cold-cache-check 2026-11-16 17:24:42 +00:00
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!1188
No description provided.