WIP: refactor(vk): the draw code's pure predicates move to draw_key.h, and their checks include it #1340

Closed
HumanBean wants to merge 5 commits from HumanBean/Longshot:refactor/draw-key into main
Owner

Type: refactor · Risk: low · Tested on: Linux, RTX 3090 · Needs: the checks' first run

Why

vk_draw.cpp is 11,000 lines doing four jobs, and nothing in it links alone, so 124 checks cut functions out of it by their text and compile them with stubs. A rename far away breaks them, and the per-draw path cannot be reworked safely. Track D of the renderer rework plan, step 1 of nine: the part that is already pure gets a header of its own. Stacked on #1309, #1325 and #1326: review the last commit only.

What changed

  • gpu/vk/draw_key.h (new): 15 functions moved verbatim from vk_draw.cpp (pipe_same, dyn_same, vertex_set_same, vertex_bind_range, vertex_bind_reuse, index_bind_same, writes_sampled_target, words_append, words_same_store, desc_counts_pack, desc_counts_unpack, table_track_open, compare_op, stencil_op, topology_class). They take scalars and arrays only, call no Vulkan function and read no state. The header compiles with the Vulkan headers and the standard library alone.
  • vk_draw.cpp includes it and loses the definitions. No call site changed.
  • 12 checks include the header in place of a text cut, with every behaviour assertion kept. Two (test_push_state.py, test_vertex_bind_range.py) now use the real Vulkan types where they had stand-ins.
  • Left for later steps, each for a stated reason: topology (logs), the blend and vertex format maps (need the NVN constants), mix (nx2/bake.py mirrors it).

Measurements

Nothing to measure: the same code in another file. One session as a check: Kokiri Forest 67.2 fps standing, Hyrule Field 93.1, main's draw counts and GPU times.

Testing

Tested: Linux, RTX 3090: built; one session through Kokiri Forest and Hyrule Field, both drew as main does, no error line.

Not tested:

  • tests/run_all.py: not run on this PC. The 12 edited checks were changed by reading alone, and this is the part most likely to be wrong: nine of them now need Vulkan headers to compile, and run_all.py skips them where it finds none.
  • Windows.

Must be tested:

  • The forge's checks, reading the result of the 12 edited files one by one.

Risks

What could break: a check that no longer compiles or silently skips. The game's code is unchanged in behaviour.

Turning it off: revert the commit.

Compatibility: none: no cache is rebuilt, MKWVK_API_VERSION stays, no setting changes.

Issues

See #1300

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). Not run on this PC; left to the forge's checks.
  • 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 check under tests/ that reads changed source updated in this PR, not weakened.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux only here.
  • Docs updated.

🤖 Generated with Claude Code

https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9

**Type:** refactor · **Risk:** low · **Tested on:** Linux, RTX 3090 · **Needs:** the checks' first run ## Why `vk_draw.cpp` is 11,000 lines doing four jobs, and nothing in it links alone, so 124 checks cut functions out of it by their text and compile them with stubs. A rename far away breaks them, and the per-draw path cannot be reworked safely. Track D of the [renderer rework plan](https://git.magicbean.dev/MagicBeanDev/Longshot/wiki/Renderer-rework-plan), step 1 of nine: the part that is already pure gets a header of its own. Stacked on #1309, #1325 and #1326: review the last commit only. ## What changed - `gpu/vk/draw_key.h` (new): 15 functions moved verbatim from `vk_draw.cpp` (`pipe_same`, `dyn_same`, `vertex_set_same`, `vertex_bind_range`, `vertex_bind_reuse`, `index_bind_same`, `writes_sampled_target`, `words_append`, `words_same_store`, `desc_counts_pack`, `desc_counts_unpack`, `table_track_open`, `compare_op`, `stencil_op`, `topology_class`). They take scalars and arrays only, call no Vulkan function and read no state. The header compiles with the Vulkan headers and the standard library alone. - `vk_draw.cpp` includes it and loses the definitions. No call site changed. - 12 checks include the header in place of a text cut, with every behaviour assertion kept. Two (`test_push_state.py`, `test_vertex_bind_range.py`) now use the real Vulkan types where they had stand-ins. - Left for later steps, each for a stated reason: `topology` (logs), the blend and vertex format maps (need the NVN constants), `mix` (`nx2/bake.py` mirrors it). ## Measurements Nothing to measure: the same code in another file. One session as a check: Kokiri Forest 67.2 fps standing, Hyrule Field 93.1, main's draw counts and GPU times. ## Testing **Tested:** Linux, RTX 3090: built; one session through Kokiri Forest and Hyrule Field, both drew as main does, no error line. **Not tested:** - `tests/run_all.py`: not run on this PC. The 12 edited checks were changed by reading alone, and this is the part most likely to be wrong: nine of them now need Vulkan headers to compile, and `run_all.py` skips them where it finds none. - Windows. **Must be tested:** - The forge's checks, reading the result of the 12 edited files one by one. ## Risks **What could break:** a check that no longer compiles or silently skips. The game's code is unchanged in behaviour. **Turning it off:** revert the commit. **Compatibility:** none: no cache is rebuilt, `MKWVK_API_VERSION` stays, no setting changes. ## Issues See #1300 ## 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`. - [ ] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). Not run on this PC; left to the forge's checks. - [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 check under `tests/` that reads changed source updated in this PR, not weakened. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux only here. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
refactor(vk): 93 kill switches and the older paths they kept are deleted from the four large renderer files
All checks were successful
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
Guide screenshots / Guide images and local UI source review (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 19s
PR description / Description follows the template (pull_request_target) Successful in 5s
Website / Website on Cloudflare (pull_request_target) Has been skipped
b9805ef295
The renderer rework plan's track F. A kill switch turned off, or back to an older way, something that is on for
every PC; nobody ships with one set, and each kept an old path alive. vk_draw.cpp 32, vk_texture.cpp 21,
vk_replay.cpp 20, vk_memory.cpp 20: the read and the path are gone, the default is the only behaviour, and each name
is a GONE row of gpu/vk/switches.def, so a run that still sets one is told. 26 are kept, each for a reason (a value
set by a tool or named in the README, a default that follows the PC, a young fix's way out).

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
refactor(vk): 18 more kill switches and their older paths are deleted from the smaller renderer files
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 8s
PR description / Description follows the template (pull_request_target) Successful in 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 20s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 23s
5742f65ca1
The renderer rework plan's track F, after the four large files (#1309). vk_vma.cpp, vk_main.cpp, vk_temporal.cpp,
vk_xfer.cpp, vk_dlss.cpp, vk_fsr4.cpp, vk_jobs.cpp, vk_reflex.cpp, vk_framegen.cpp, vk_programs.cpp and vk_progcache.cpp
lose the read and the path; each name is a GONE row of gpu/vk/switches.def. 18 are kept: the README or a script
names them, the shader cache's stamp holds them, or they are a way out that measurement runs or a driver still need.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
feat(host): the host's switches join the table: every HOS_ and LONGSHOT_ name the game reads has a row
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 13s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 15s
CI / Workflow lint (actionlint) (pull_request) Successful in 17s
Third-party parts / As their notes say (pull_request) Successful in 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 5s
2e0743237d
The renderer rework plan's track F. gpu/vk/switches.def gains the host's 216 switches (89 diagnostics, 50 that turn
something off, 23 player settings, 24 numbers, 20 that turn on something nobody ships, 8 that follow the PC), read
once each from the code. The start's report names them when set and says a HOS_ name that is none; a LONGSHOT_ name
that is none is passed over (the launcher and the Builder have their own). The host's three removed HOS_ names become
GONE rows.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
refactor(vk): the draw code's pure predicates move to draw_key.h, and their checks include it
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 13s
PR description / Description follows the template (pull_request_target) Successful in 18s
CI / Workflow lint (actionlint) (pull_request) Successful in 21s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 17s
Third-party parts / As their notes say (pull_request) Successful in 23s
Website / Website on Cloudflare (pull_request_target) Has been skipped
4b25ccf1ff
The renderer rework plan's track D, step 1. Fifteen functions that take only scalars and arrays leave vk_draw.cpp
verbatim for an inline header that compiles alone; twelve checks include the header in place of a text cut.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
Author
Owner

Tested in game: Linux, RTX 3090, NVIDIA 620.70: one session through Kokiri Forest and Hyrule Field at 2560x1440; both drew with main's draw counts and GPU times.

Tested in game: Linux, RTX 3090, NVIDIA 620.70: one session through Kokiri Forest and Hyrule Field at 2560x1440; both drew with main's draw counts and GPU times.
Author
Owner

A second commit is on this branch: the next two steps of the split. No behaviour change is intended.

  • The pipeline key is a pure function. draw_key.h gains blend_factor, blend_op, vertex_format, a pure topology (its log-once stays at the call), mix, and pipeline_key(const KeyInputs&); vk_draw.cpp fills KeyInputs from the program, state, targets and device and calls it. The terms and their order are the same, so every persisted key is the same. cur_program, a thread-local standing in for an argument, is an argument of dyn_pack and dynamic_state.
  • What a command buffer has bound is one struct. The twelve thread-locals reset by hand at four sites are CmdBound with reset() and reset_keeping_index(): the four sites were not alike (the masked clear never forgot the index buffer), and each resets exactly what it did.
  • tests/test_pipeline_key_values.py (new) pins four keys and 160 seeded cases against a restatement of the old arithmetic, and holds nx2/bake.py's copy to the same values. Eleven existing checks follow the moved text.

Run in the game (RTX 3090, NVIDIA 620.70, Linux, 2560x1440), against the commit before:

Kokiri Forest Hyrule Field the Market pipelines made at a second start
before 64.2 fps 90.6 67.3 10,093 in 2.2 s
this commit (two sessions) 64.9, 62.8 91.4, 90.5 72.2, 67.8 10,082 in 2.2 s

A changed key would have built the pipelines again at the second start; they came from the caches. Screenshots differ from the commit before by 0.021 / 0.009 / 0.009 (mean absolute error of 1), as two sessions of this commit do from each other (0.017 / 0.009 / 0.010).

Not tested: tests/run_all.py (the pinned keys come from a restatement of the old code, not from running it, so the new check's first run is the real test), Windows, and any GPU that takes vertex_format's or the blend maps' other branches. The split's next step reshapes draw() itself and waits for these edits to pass the checks.

A second commit is on this branch: the next two steps of the split. No behaviour change is intended. - **The pipeline key is a pure function.** `draw_key.h` gains `blend_factor`, `blend_op`, `vertex_format`, a pure `topology` (its log-once stays at the call), `mix`, and `pipeline_key(const KeyInputs&)`; `vk_draw.cpp` fills `KeyInputs` from the program, state, targets and device and calls it. The terms and their order are the same, so every persisted key is the same. `cur_program`, a thread-local standing in for an argument, is an argument of `dyn_pack` and `dynamic_state`. - **What a command buffer has bound is one struct.** The twelve thread-locals reset by hand at four sites are `CmdBound` with `reset()` and `reset_keeping_index()`: the four sites were not alike (the masked clear never forgot the index buffer), and each resets exactly what it did. - `tests/test_pipeline_key_values.py` (new) pins four keys and 160 seeded cases against a restatement of the old arithmetic, and holds `nx2/bake.py`'s copy to the same values. Eleven existing checks follow the moved text. **Run in the game** (RTX 3090, NVIDIA 620.70, Linux, 2560x1440), against the commit before: | | Kokiri Forest | Hyrule Field | the Market | pipelines made at a second start | |---|---|---|---|---| | before | 64.2 fps | 90.6 | 67.3 | 10,093 in 2.2 s | | this commit (two sessions) | 64.9, 62.8 | 91.4, 90.5 | 72.2, 67.8 | 10,082 in 2.2 s | A changed key would have built the pipelines again at the second start; they came from the caches. Screenshots differ from the commit before by 0.021 / 0.009 / 0.009 (mean absolute error of 1), as two sessions of this commit do from each other (0.017 / 0.009 / 0.010). Not tested: `tests/run_all.py` (the pinned keys come from a restatement of the old code, not from running it, so the new check's first run is the real test), Windows, and any GPU that takes `vertex_format`'s or the blend maps' other branches. The split's next step reshapes `draw()` itself and waits for these edits to pass the checks.
refactor(vk): the pipeline key is a pure function of plain words, and what a command buffer has bound is one struct
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 9s
PR description / Description follows the template (pull_request_target) Successful in 12s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 20s
13eade6c52
The renderer rework plan's track D, steps 2 and 3. draw_key.h gains the blend, vertex-format and topology maps, mix,
and pipeline_key(KeyInputs): the same terms in the same order, so every persisted key is the same (a second start
made 10,082 pipelines in 2.2 s from the caches, as before). cur_program, a thread-local standing in for an argument,
is an argument. The twelve 'what is bound' thread-locals are CmdBound, reset by reset() at three sites and
reset_keeping_index() at the masked clear, which never forgot the index buffer. tests/test_pipeline_key_values.py
pins key values and holds nx2/bake.py's arithmetic to them.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Claude-Session: https://claude.ai/code/session_017vw8dzCsAL3UdW7ft8ptL9
Author
Owner

Folded into #1354, which is now the one pull request for frame pipeline and the draw split. The commits are unchanged apart from being rebased into one stack and carrying the fixes the check suite asked for; nothing was dropped.

Folded into #1354, which is now the one pull request for frame pipeline and the draw split. The commits are unchanged apart from being rebased into one stack and carrying the fixes the check suite asked for; nothing was dropped.
HumanBean closed this pull request 2026-11-17 15:48:23 +00:00
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 9s
PR description / Description follows the template (pull_request_target) Successful in 12s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 14s
CI / Workflow lint (actionlint) (pull_request) Successful in 16s
Third-party parts / As their notes say (pull_request) Successful in 20s

Pull request closed

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!1340
No description provided.