WIP: perf(vk): a stage's descriptors are kept across draws in a recording part while what they were resolved from stands #794

Draft

dyst wants to merge 1 commit from dyst/Longshot:perf/vk-descriptor-cache into main

pull from: dyst/Longshot:perf/vk-descriptor-cache

merge into: MagicBeanDev:main

MagicBeanDev:main

Conversation 2 Commits 1 Files changed 10 +479 -25

dyst commented 2026-11-15 12:23:00 +00:00

Member

• Copy link
• Copy Markdown

Type: perf · Risk: medium · Tested on: Windows 11 (the game-free checks; the game A/B is next) · Needs: a game run on NVIDIA, AMD and Intel

Why

Every draw rebuilt its descriptors from scratch on the replay thread, because any bind anywhere counted as a change and the game binds a new uniform buffer for nearly every draw. In Kokiri Forest that rebuild (build_descriptors) is about 1.3 ms of the serial replay thread a frame (docs/cpu-profile.md), most of it resolving textures, samplers and buffers that had not changed since the draw before. Found in an audit of the renderer's per-draw path; no issue on the tracker.

What changed

Each program's stages now keep, for one recording part, the texture, storage-buffer and uniform-buffer descriptors their last build resolved, and use them while what they came from stands. Anything that has to be noted at each draw (written buffers, storage images) or that reads guest memory without a generation (handles from c3+, handle programs, compute/task/mesh stages) is still resolved every time.

• draw: kept_program, KeptStage, kept_tex_holds, kept_buf_holds, kept_ubo_holds, desc_keep_textures, desc_keep_storage and the kept paths in build_descriptors (gpu/vk/vk_draw.cpp); desc_kept_part counted in draw_begin_recording
• memory, replay: guest_pools_stamp() (gpu/vk/vk_memory.cpp), ub_list_generation() (gpu/vk/vk_replay.cpp), read by the keys
• tests: tests/test_desc_keep.py; three fixtures that compile draw_begin_recording get the new counter

Measurements

Verdict: not measured yet: A/B runs in the game (this PR against main on one base, interleaved) are next and will replace this section.

Flags and settings

Switches:

Flag	What it is	Before this PR	After this PR	Effect	Helps / doesn't help / untested	Recommendation
RX_VK_DESC_KEEP=0	Every descriptor resolved at every build	-	unset (kept)	Off: the old path	measurement pending	leave unset; =0 for an A/B or if a draw shows the wrong texture
RX_VK_TRACE_TEX, RX_VK_LOG_IMG, RX_VK_WATCH_PROG, RX_VK_DRAW_STATS, RX_VK_PEEK_PROG, RX_VK_LOG_TABLE, RX_VK_SLOW_DESC, RX_VK_ASYNC_IMPORT (existing, unchanged)	Diagnostics that log each descriptor as it is resolved, and the async import that resolves storage buffers into stream copies	as before	as before; set, the descriptors are not kept	Their logs and copies stay complete	-	unchanged

Testing

Tested: Windows 11, llvm-mingw (the builder's v2.0.14 tools): the new and changed checks; every check that reads the
changed code; -fsyntax-only of the changed renderer files with the build's flags and headers; python -I -B tests/run_all.py on this branch and on main @ aa95d35f, same PC and environment: the same results apart from the new test_desc_keep; the failures main has here are named in the first comment.

Not tested: the game yet. This PR is WIP until its A/B is in (next: this PR against main on one dev_packs base of
main @ aa95d35f, on an RTX 3080 with a Ryzen 9 3900X, Windows 11; AMD and Intel need other testers).

Must be tested:

• Any OS and GPU, defaults and once with RX_VK_DESC_KEEP=0: Kokiri Forest, Castle Town and a dungeon a few minutes each, expecting the same picture (no wrong or flickering textures, no missing objects) and a lower replay time (vk: a frame's replay time (ms): submit) (Test Farm: @Beanstalk any, those scenes with and without RX_VK_DESC_KEEP=0)

Risks

What could break: A kept descriptor that should have changed: an object drawn with another's texture or buffer for the rest of a recording part (about 120 draws). Every input the build reads is in a key or excluded from keeping; the parallel replay's workers keep their own.

Turning it off: RX_VK_DESC_KEEP=0

Compatibility: Nothing changes: no caches, settings or vk ABI involved.

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 check under tests/ that reads changed source updated in this PR, not weakened.
• A game-free test added for the fix, failing on main and passing here.
• Docs updated.

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Windows 11 (the game-free checks; the game A/B is next) · **Needs:** a game run on NVIDIA, AMD and Intel ## Why Every draw rebuilt its descriptors from scratch on the replay thread, because any bind anywhere counted as a change and the game binds a new uniform buffer for nearly every draw. In Kokiri Forest that rebuild (`build_descriptors`) is about 1.3 ms of the serial replay thread a frame (docs/cpu-profile.md), most of it resolving textures, samplers and buffers that had not changed since the draw before. Found in an audit of the renderer's per-draw path; no issue on the tracker. ## What changed Each program's stages now keep, for one recording part, the texture, storage-buffer and uniform-buffer descriptors their last build resolved, and use them while what they came from stands. Anything that has to be noted at each draw (written buffers, storage images) or that reads guest memory without a generation (handles from c3+, handle programs, compute/task/mesh stages) is still resolved every time. - draw: `kept_program`, `KeptStage`, `kept_tex_holds`, `kept_buf_holds`, `kept_ubo_holds`, `desc_keep_textures`, `desc_keep_storage` and the kept paths in `build_descriptors` (`gpu/vk/vk_draw.cpp`); `desc_kept_part` counted in `draw_begin_recording` - memory, replay: `guest_pools_stamp()` (`gpu/vk/vk_memory.cpp`), `ub_list_generation()` (`gpu/vk/vk_replay.cpp`), read by the keys - tests: `tests/test_desc_keep.py`; three fixtures that compile `draw_begin_recording` get the new counter ## Measurements **Verdict:** not measured yet: A/B runs in the game (this PR against main on one base, interleaved) are next and will replace this section. ### Flags and settings Switches: | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_DESC_KEEP=0` | Every descriptor resolved at every build | - | unset (kept) | Off: the old path | measurement pending | leave unset; `=0` for an A/B or if a draw shows the wrong texture | | `RX_VK_TRACE_TEX`, `RX_VK_LOG_IMG`, `RX_VK_WATCH_PROG`, `RX_VK_DRAW_STATS`, `RX_VK_PEEK_PROG`, `RX_VK_LOG_TABLE`, `RX_VK_SLOW_DESC`, `RX_VK_ASYNC_IMPORT` (existing, unchanged) | Diagnostics that log each descriptor as it is resolved, and the async import that resolves storage buffers into stream copies | as before | as before; set, the descriptors are not kept | Their logs and copies stay complete | - | unchanged | ## Testing **Tested:** Windows 11, llvm-mingw (the builder's v2.0.14 tools): the new and changed checks; every check that reads the changed code; `-fsyntax-only` of the changed renderer files with the build's flags and headers; python -I -B tests/run_all.py on this branch and on main @ aa95d35f, same PC and environment: the same results apart from the new `test_desc_keep`; the failures main has here are named in the first comment. **Not tested:** the game yet. This PR is WIP until its A/B is in (next: this PR against main on one dev_packs base of main @ aa95d35f, on an RTX 3080 with a Ryzen 9 3900X, Windows 11; AMD and Intel need other testers). **Must be tested:** - Any OS and GPU, defaults and once with `RX_VK_DESC_KEEP=0`: Kokiri Forest, Castle Town and a dungeon a few minutes each, expecting the same picture (no wrong or flickering textures, no missing objects) and a lower replay time (`vk: a frame's replay time (ms): submit`) (Test Farm: @Beanstalk any, those scenes with and without RX_VK_DESC_KEEP=0) ## Risks **What could break:** A kept descriptor that should have changed: an object drawn with another's texture or buffer for the rest of a recording part (about 120 draws). Every input the build reads is in a key or excluded from keeping; the parallel replay's workers keep their own. **Turning it off:** `RX_VK_DESC_KEEP=0` **Compatibility:** Nothing changes: no caches, settings or vk ABI involved. ## 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 check under `tests/` that reads changed source updated in this PR, not weakened. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dyst added 1 commit 2026-11-15 12:23:01 +00:00

perf(vk): a stage's descriptors are kept across draws in a recording part while what they were resolved from stands ... 1f00672f8e

Descriptors were rebuilt whenever anything at all was bound (the global bind generation), and the game binds a uniform buffer
for nearly every draw: build_descriptors resolved every uniform buffer, storage buffer and texture of every stage again, about
1.3 ms a frame in Kokiri Forest on the serial replay thread, while bind_descriptors then found most writes unchanged.

Each program and stage now keeps, per thread and for one recording part (desc_kept_part, counted by draw_begin_recording), what
its last build resolved, and uses it while its inputs stand:
- textures, for a vertex to fragment stage whose every handle is a word of its own c2 (no handle program): the same state, the
  texture destroy, sampler registration and texture epochs, and every slot its handles named at the same version; when the
  stage's texture bindings moved, the handles are read again and the kept ones used if they are the same;
- storage buffers, for a stage whose buffers are all read only and named in c0 or c1: the stage's storage bindings and the
  pools' bind stamps, every buffer bound and below 1 TB;
- uniform buffers, each element: c1 for the part; a user buffer bound where it is, with no stream update over it, while its
  range, the updates and the bind stamp stand.
Written storage buffers, storage images, texel buffers, handles from c3+ or handle programs, and compute, task and mesh stages
are resolved at every build as before. The kept textures are put in draw_sampled and the reuse fingerprint as a build would.
RX_VK_DESC_KEEP=0 (or RX_VK_DESC_REUSE=never, or a descriptor diagnostic): every build resolves everything, as before.
RX_VK_PROF_FINE=1 counts the kept uniform buffers, storage stages and texture stages.

tests/test_desc_keep.py compiles the keys' rules and checks each invalidation, the side effects a kept stage repeats, what is
never kept, the part's count and the switch.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

dyst commented 2026-11-15 12:23:02 +00:00

Author

Member

• Copy link
• Copy Markdown

The checks on this PC (Windows 11, RTX 3080, Ryzen 9 3900X, llvm-mingw from the builder's v2.0.14 tools): python -I -B tests/run_all.py on main @ aa95d35f fails these 19 here, and so does this branch: test_appimage_player_build.py, test_bake_portability.py, test_cpm_discovery.py, test_cpp_preflight.py, test_crash_dialog.py, test_env_on.py, test_fpx_sticky.py, test_lift_cleanup_error.py, test_linux_preflight.py, test_make_game_cache.py, test_make_game_prepare.py, test_missing_nup.py, test_oot_state_tap.py, test_options_budget_once.py, test_readback_late.py, test_spawn_emit.py, test_tested_configurations.py, test_vk_pgo.py, test_walk_key.py. Any other failure in a full run on this branch was rerun on its own and passed (the full runs shared the PC with dev_packs builds: timing checks).

Next: an interleaved A/B in the game against main on one dev_packs base of aa95d35f; the numbers will replace the Measurements section.

The checks on this PC (Windows 11, RTX 3080, Ryzen 9 3900X, llvm-mingw from the builder's v2.0.14 tools): `python -I -B tests/run_all.py` on main @ aa95d35f fails these 19 here, and so does this branch: `test_appimage_player_build.py`, `test_bake_portability.py`, `test_cpm_discovery.py`, `test_cpp_preflight.py`, `test_crash_dialog.py`, `test_env_on.py`, `test_fpx_sticky.py`, `test_lift_cleanup_error.py`, `test_linux_preflight.py`, `test_make_game_cache.py`, `test_make_game_prepare.py`, `test_missing_nup.py`, `test_oot_state_tap.py`, `test_options_budget_once.py`, `test_readback_late.py`, `test_spawn_emit.py`, `test_tested_configurations.py`, `test_vk_pgo.py`, `test_walk_key.py`. Any other failure in a full run on this branch was rerun on its own and passed (the full runs shared the PC with dev_packs builds: timing checks). Next: an interleaved A/B in the game against main on one dev_packs base of aa95d35f; the numbers will replace the Measurements section.

mooki added the

area/renderer

kind

performance

platform/linux

platform/windows

priority

high

labels 2026-11-15 14:00:10 +00:00

dyst commented 2026-11-15 18:33:29 +00:00

Author

Member

• Copy link
• Copy Markdown

First in-game numbers (RTX 3080, Ryzen 9 3900X, Windows 11; dev_packs runtimes of this PR and main @ aa95d35f on one base; Kokiri Forest from the repo save kokiri-start): this is slower, not faster, as it stands. The descriptors' time went up in every run:

• the fps A/B with the camera turning (3 interleaved runs each, the renderer's 'a frame's replay time' line): descriptors 3.44 / 3.95 / 3.69 ms a frame here against 2.78 / 2.52 / 2.89 on main;
• RX_VK_BENCH=2600,100 (the same frame replayed 100 times, one run each): descriptors 1.79 ms against 1.25 on main, the whole replay 7.82 against 7.68 ms.

Likely cause, not yet confirmed with RX_VK_PROF_FINE's kept counters: few kept stages are used (keys that move often: the texture destroy and epoch generations, ub_gen with every uniform update), while every build now also pays for the handles read twice, the slot versions and refilling the kept vectors. Next: the fine counters' hit rates, then either keys that hold or this closed. Stays WIP.

First in-game numbers (RTX 3080, Ryzen 9 3900X, Windows 11; dev_packs runtimes of this PR and main @ aa95d35f on one base; Kokiri Forest from the repo save kokiri-start): **this is slower, not faster, as it stands.** The descriptors' time went up in every run: - the fps A/B with the camera turning (3 interleaved runs each, the renderer's 'a frame's replay time' line): descriptors 3.44 / 3.95 / 3.69 ms a frame here against 2.78 / 2.52 / 2.89 on main; - RX_VK_BENCH=2600,100 (the same frame replayed 100 times, one run each): descriptors 1.79 ms against 1.25 on main, the whole replay 7.82 against 7.68 ms. Likely cause, not yet confirmed with RX_VK_PROF_FINE's kept counters: few kept stages are used (keys that move often: the texture destroy and epoch generations, ub_gen with every uniform update), while every build now also pays for the handles read twice, the slot versions and refilling the kept vectors. Next: the fine counters' hit rates, then either keys that hold or this closed. Stays WIP.

dyst force-pushed perf/vk-descriptor-cache from 1f00672f8e to 86389b3583 2026-11-15 18:53:10 +00:00 Compare

Some checks are pending

Hide checks

PR description / Description follows the template (pull_request_target) Waiting to run

Details

CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped

Details

CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped

Details

CI / Workflow lint (actionlint) (pull_request) Waiting to run

Details

CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped

Details

CI / Conventional Commit title (pull_request) Waiting to run

Details

Guide screenshots / Guide images and local UI source review (pull_request) Waiting to run

Details

Third-party parts / The same as upstream (pull_request) Has been skipped

Details

Third-party parts / As their notes say (pull_request) Waiting to run

Details

Website / Website on Cloudflare (pull_request) Has been skipped

Details

This pull request is marked as a work in progress.

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-descriptor-cache:dyst-perf/vk-descriptor-cache'

git switch 'dyst-perf/vk-descriptor-cache'

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area/accessibility

Barriers for people with disabilities

  

area/audio

Sound and music

  

area/input

Controllers, keyboard, mouse

  

area/install

Installing, updating, building from your game

  

area/menu

In-game menu and settings

  

area/renderer

Vulkan renderer, shaders, effects

  

area/saves

Save files

  

area/upscaling

DLSS, FSR, frame generation

  

beanstalk: approved @ 1697603

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 2c5a62e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 4fd82b7

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 64d6d09

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 6f91fae

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 70a78f9

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8015c9a

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 8d361dc

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ 9d8356e

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ abf2227

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ d82f202

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ e5f1e40

Set by Beanstalk for show; the farm's database is what counts

  

beanstalk: approved @ ee8ab5f

Set by Beanstalk for show; the farm's database is what counts

  

ci: approved

A maintainer approved CircleCI for this fork PR (sticky; removed after 14 quiet days)

  

good first issue

A good start for a new contributor

  

gpu/amd

AMD GPUs

  

gpu/igpu

Integrated GPUs

  

gpu/intel

Intel GPUs

  

gpu/nvidia

NVIDIA GPUs

  

help wanted

Extra hands or knowledge wanted

  

kind

bug

Something doesn't work as it should

  

kind

chore

Build, CI, dependencies, tidying

  

kind

docs

Documentation

  

kind

feature

A new feature or an improvement

  

kind

performance

Frame rate, frame time, loading, memory

  

kind

question

A question rather than a change

  

needs measurements

Waiting for before/after measurements

  

platform/linux

Affects Linux (a change for every system carries both Windows and Linux)

  

platform/macos

macOS (Apple silicon or Intel Macs)

  

platform/steam-deck

Steam Deck

  

platform/windows

Affects Windows (a change for every system carries both Windows and Linux)

  

preview

Maintainers: deploy a preview of this PR's website (read its changes first). Removed after the run.

  

priority

critical

Crashes, data loss, or blocks most players

  

priority

high

Important: next in line

  

priority

low

Nice to have

  

regression

Worked in an earlier build, broken in a newer one: highest priority, above other bugs

  

status

blocked

Waits on something else first

  

status

confirmed

Reproduced or agreed on

  

status

duplicate

Already reported or proposed

  

status

invalid

Not a problem in this project

  

status

needs-info

Waiting for more information from the reporter

  

status

wontfix

Will not be worked on

  

testing wanted

Wanted: a test on other hardware (posts a test request in #test-requests)

  

ci: approved

No labels

area/accessibility

area/audio

area/input

area/install

area/menu

area/renderer

area/saves

area/upscaling

beanstalk: approved @ 1697603

beanstalk: approved @ 2c5a62e

beanstalk: approved @ 4fd82b7

beanstalk: approved @ 64d6d09

beanstalk: approved @ 6f91fae

beanstalk: approved @ 70a78f9

beanstalk: approved @ 8015c9a

beanstalk: approved @ 8d361dc

beanstalk: approved @ 9d8356e

beanstalk: approved @ abf2227

beanstalk: approved @ d82f202

beanstalk: approved @ e5f1e40

beanstalk: approved @ ee8ab5f

ci: approved

good first issue

gpu/amd

gpu/igpu

gpu/intel

gpu/nvidia

help wanted

kind

bug

kind

chore

kind

docs

kind

feature

kind

performance

kind

question

needs measurements

platform/linux

platform/macos

platform/steam-deck

platform/windows

preview

priority

critical

priority

high

priority

low

regression

status

blocked

status

confirmed

status

duplicate

status

invalid

status

needs-info

status

wontfix

testing wanted

ci: approved

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

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!794

No description provided.