feat(vk): the renderer's switches in one table (gpu/vk/switches.def), and a start that says which are set #1300

Merged
HumanBean merged 2 commits from HumanBean/Longshot:feat/switch-table into main 2026-11-17 01:36:35 +00:00
Owner

Type: feat · Risk: low · Tested on: Linux, RTX 3090 · Needs: Windows, any GPU (the report reads the environment through _environ there)

Depends on #1288 (M0 of the renderer rework plan): this branch is stacked on it. Review the last commit.

Why

The renderer reads 571 switches from the environment, each where it is used, and nothing lists them: 126 have a row in docs/development.md. So nobody can say which ones still matter, which only turn an old path back on, and which decide something by the GPU. A switch set with a misspelt name, or one that was removed, does nothing and says nothing, and a bug report's log doesn't show how far the run was from the defaults. This is the plan's M2: one table of the switches, as the base for removing most of them and for deciding the per-GPU defaults in one place.

What changed

Every RX_ switch now has a row in one table, a check holds the table and the source to each other, and the renderer says at its start which switches the run has set. No switch changes what it does, except one second name that is removed.

  • The table: gpu/vk/switches.def, one row a switch: its name, its kind, what the renderer does with it unset, and what setting it does. The kinds (gpu/vk/switches.h): diag 189, kill 177 (turns off something that is on for everyone), tune 73, attempt 57 (turns on something nobody ships), hw 49 (unset, it follows the PC), player 26. The rows were written from a reading of each switch's code; where a row and the code disagree the code is right.
  • The start's report: switches::report in gpu/vk/switches.h, called from start() in gpu/vk/vk_main.cpp. One line names every switch set with its value and kind; a value that is a path is said as <a path>. Each RX_ name set that is no switch gets a line: a removed one with what became of it, another as misspelt or from another build.
  • Removed switches: a GONE(name, date, what became of it) row. The nine RX_ names of removed_switch_notes() in host/hos_main.c moved there (the host keeps its own HOS_ ones), and RX_VK_GPU_PROFILE, a second name for RX_VK_PASS_TIMING=1, is removed (gpu/vk/vk_gprof.cpp).
  • Four names nothing reads (RX_DUMP_WGSL, RX_DUMP_SLOW_WGSL, RX_DUMP_TICS, RX_WGSL_OVERRIDE) leave the list of names longshot_env.txt may not set (host/hos_main.c).
  • The check: tests/test_switch_table.py fails on a name the source reads without a row, a row nothing reads, a removed name still read, and a table out of order; it compiles switches.h alone and runs the report on made-up environments.
  • Docs: docs/development.md (Switches for testing and debugging) and AGENTS.md: a new switch needs a row.

The reads stay at their sites: the plan's M2 said "no file but the table's reads the environment", and this PR holds each read to the table by a check instead, so the four large renderer files are not touched while 77 pull requests are open against them.

Measurements

Verdict: nothing to gain in speed, and none lost: the report runs once at the start. One session of this PR's build ran Kokiri Forest and Hyrule Field at the frame rates main had in the same day's sessions (Hyrule Field standing 79.5 fps here, 78.9 and 77.5 on main; Kokiri Forest standing 56.5, 55.5 and 55.0). That is one run, so it shows nothing broke, not a comparison.

[hos host] vk: RX_VK_GPU_PROFILE is set, and is no longer a switch (since 2026-11-16): use RX_VK_PASS_TIMING=1, which it was another name for
[hos host] vk: RX_VK_OOT_FOG is set, and is no longer a switch (since 2026-11-11): it does nothing
[hos host] vk: RX_VK_NOT_A_SWITCH is set, and is not a switch of this build: a misspelt name, or one from another build
[hos host] vk: switches set (3): RX_VK_FRAME_LOG=/home/<user>/.cache/hookshot-work/perf/runs/... (diag), RX_VK_AUTO_PRESET=0 (kill), RX_VK_DESC_REUSE=1 (player)

(Those lines are from the commit before the last edit, which now prints a path as <a path>; the home folder's name is cut here by hand.)

Flags and settings

One switch removed, none added.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_GPU_PROFILE a second name for RX_VK_PASS_TIMING=1 read not read; a run that sets it is told to use RX_VK_PASS_TIMING=1 none for a run that doesn't set it undocumented, and no script in the repository sets it removed

Testing

Tested: Linux, RTX 3090 (NVIDIA 620.70), a dev pack over base 8e9cfc3a: the game from the Kokiri Forest save, then Hyrule Field by the debug teleport, standing and turning in each, 2560x1440; with RX_VK_GPU_PROFILE=1, RX_VK_OOT_FOG=1, RX_VK_NOT_A_SWITCH=1 and RX_VK_DESC_REUSE=1 set. The four lines above came out, the scenes drew, and the run ended cleanly. The last edit (a path's value) was built but not run in the game.

Not tested: Windows. tests/test_switch_table.py was not run on this PC (no checks are run here); the forge's checks run it. The rows' texts were not each checked against the code by a second reader: 571 rows, read once.

Must be tested:

  • Windows, any GPU: start the game with RX_VK_DRAW_STATS=1 set, expecting vk: switches set (1): RX_VK_DRAW_STATS=1 (diag) in longshot_log.txt (Test Farm: @Beanstalk windows, a start with RX_VK_DRAW_STATS=1 set and the log's "switches set" line)

Risks

What could break: a start on Windows where _environ is not filled (the report then says none are set; nothing else reads it). A pull request that adds a switch now fails tests/test_switch_table.py until it adds a row.

Turning it off: revert the commit

Compatibility: a run that set RX_VK_GPU_PROFILE=1 no longer gets the GPU profile and is told to set RX_VK_PASS_TIMING=1. Nothing else changes.

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.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux only here; the Windows build is left to the forge's checks.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Linux, RTX 3090 · **Needs:** Windows, any GPU (the report reads the environment through `_environ` there) **Depends on #1288** (M0 of the [renderer rework plan](https://git.magicbean.dev/MagicBeanDev/Longshot/wiki/Renderer-rework-plan)): this branch is stacked on it. Review the last commit. ## Why The renderer reads 571 switches from the environment, each where it is used, and nothing lists them: 126 have a row in `docs/development.md`. So nobody can say which ones still matter, which only turn an old path back on, and which decide something by the GPU. A switch set with a misspelt name, or one that was removed, does nothing and says nothing, and a bug report's log doesn't show how far the run was from the defaults. This is the plan's M2: one table of the switches, as the base for removing most of them and for deciding the per-GPU defaults in one place. ## What changed Every `RX_` switch now has a row in one table, a check holds the table and the source to each other, and the renderer says at its start which switches the run has set. No switch changes what it does, except one second name that is removed. - **The table:** `gpu/vk/switches.def`, one row a switch: its name, its kind, what the renderer does with it unset, and what setting it does. The kinds (`gpu/vk/switches.h`): `diag` 189, `kill` 177 (turns off something that is on for everyone), `tune` 73, `attempt` 57 (turns on something nobody ships), `hw` 49 (unset, it follows the PC), `player` 26. The rows were written from a reading of each switch's code; where a row and the code disagree the code is right. - **The start's report:** `switches::report` in `gpu/vk/switches.h`, called from `start()` in `gpu/vk/vk_main.cpp`. One line names every switch set with its value and kind; a value that is a path is said as `<a path>`. Each `RX_` name set that is no switch gets a line: a removed one with what became of it, another as misspelt or from another build. - **Removed switches:** a `GONE(name, date, what became of it)` row. The nine `RX_` names of `removed_switch_notes()` in `host/hos_main.c` moved there (the host keeps its own `HOS_` ones), and `RX_VK_GPU_PROFILE`, a second name for `RX_VK_PASS_TIMING=1`, is removed (`gpu/vk/vk_gprof.cpp`). - **Four names nothing reads** (`RX_DUMP_WGSL`, `RX_DUMP_SLOW_WGSL`, `RX_DUMP_TICS`, `RX_WGSL_OVERRIDE`) leave the list of names `longshot_env.txt` may not set (`host/hos_main.c`). - **The check:** `tests/test_switch_table.py` fails on a name the source reads without a row, a row nothing reads, a removed name still read, and a table out of order; it compiles `switches.h` alone and runs the report on made-up environments. - **Docs:** `docs/development.md` (Switches for testing and debugging) and `AGENTS.md`: a new switch needs a row. The reads stay at their sites: the plan's M2 said "no file but the table's reads the environment", and this PR holds each read to the table by a check instead, so the four large renderer files are not touched while 77 pull requests are open against them. ## Measurements **Verdict:** nothing to gain in speed, and none lost: the report runs once at the start. One session of this PR's build ran Kokiri Forest and Hyrule Field at the frame rates `main` had in the same day's sessions (Hyrule Field standing 79.5 fps here, 78.9 and 77.5 on `main`; Kokiri Forest standing 56.5, 55.5 and 55.0). That is one run, so it shows nothing broke, not a comparison. ``` [hos host] vk: RX_VK_GPU_PROFILE is set, and is no longer a switch (since 2026-11-16): use RX_VK_PASS_TIMING=1, which it was another name for [hos host] vk: RX_VK_OOT_FOG is set, and is no longer a switch (since 2026-11-11): it does nothing [hos host] vk: RX_VK_NOT_A_SWITCH is set, and is not a switch of this build: a misspelt name, or one from another build [hos host] vk: switches set (3): RX_VK_FRAME_LOG=/home/<user>/.cache/hookshot-work/perf/runs/... (diag), RX_VK_AUTO_PRESET=0 (kill), RX_VK_DESC_REUSE=1 (player) ``` (Those lines are from the commit before the last edit, which now prints a path as `<a path>`; the home folder's name is cut here by hand.) ### Flags and settings One switch removed, none added. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_GPU_PROFILE` | a second name for `RX_VK_PASS_TIMING=1` | read | not read; a run that sets it is told to use `RX_VK_PASS_TIMING=1` | none for a run that doesn't set it | undocumented, and no script in the repository sets it | removed | ## Testing **Tested:** Linux, RTX 3090 (NVIDIA 620.70), a dev pack over base 8e9cfc3a: the game from the Kokiri Forest save, then Hyrule Field by the debug teleport, standing and turning in each, 2560x1440; with `RX_VK_GPU_PROFILE=1`, `RX_VK_OOT_FOG=1`, `RX_VK_NOT_A_SWITCH=1` and `RX_VK_DESC_REUSE=1` set. The four lines above came out, the scenes drew, and the run ended cleanly. The last edit (a path's value) was built but not run in the game. **Not tested:** Windows. `tests/test_switch_table.py` was not run on this PC (no checks are run here); the forge's checks run it. The rows' texts were not each checked against the code by a second reader: 571 rows, read once. **Must be tested:** - Windows, any GPU: start the game with `RX_VK_DRAW_STATS=1` set, expecting `vk: switches set (1): RX_VK_DRAW_STATS=1 (diag)` in `longshot_log.txt` (Test Farm: `@Beanstalk windows, a start with RX_VK_DRAW_STATS=1 set and the log's "switches set" line`) ## Risks **What could break:** a start on Windows where `_environ` is not filled (the report then says none are set; nothing else reads it). A pull request that adds a switch now fails `tests/test_switch_table.py` until it adds a row. **Turning it off:** revert the commit **Compatibility:** a run that set `RX_VK_GPU_PROFILE=1` no longer gets the GPU profile and is told to set `RX_VK_PASS_TIMING=1`. Nothing else changes. ## 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] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux only here; the Windows build is left to the forge's checks. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(scripts): crash_groups.py lists the crash reports in named groups, the largest first
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
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 10s
CI / Workflow lint (actionlint) (pull_request) Successful in 11s
Third-party parts / As their notes say (pull_request) Successful in 14s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Failing after 4s
f2a06ee7c5
The renderer rework plan's M0 (https://git.magicbean.dev/MagicBeanDev/Longshot/wiki/Renderer-rework-plan): every open
crash report in a named group. A group is named by how the run ended, whose code the fault was in and whether VRAM or
Windows' commit was at its limit; none of the three changes between builds. Reads the issues the crash window titled,
their attached records and the ends of their logs; sends nothing.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
feat(vk): the renderer's switches in one table (gpu/vk/switches.def), and a start that says which are set
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 10s
CI / Workflow lint (actionlint) (pull_request) Successful in 12s
Third-party parts / As their notes say (pull_request) Successful in 15s
PR description / Description follows the template (pull_request_target) Failing after 4s
e8bbc2e44f
The renderer rework plan's M2 (https://git.magicbean.dev/MagicBeanDev/Longshot/wiki/Renderer-rework-plan). Every RX_
name read from the environment has a row: its kind, what the renderer does with it unset, what setting it does.
tests/test_switch_table.py holds the table and the source to each other. At its start the renderer logs the switches
the run has set, and each RX_ name set that is none: removed (a GONE row says what became of it) or misspelt. The
host's nine removed RX_ names move to GONE rows; RX_VK_GPU_PROFILE, a second name for RX_VK_PASS_TIMING=1, goes.

Co-Authored-By: Claude Fable 5.2 <[email protected]>
Author
Owner

Tested in game: RTX 3090, NVIDIA 620.70, Linux: a dev pack over base 8e9cfc3a from the Kokiri Forest save, then Hyrule Field by the debug teleport, standing and turning in each at 2560x1440, with RX_VK_GPU_PROFILE=1, RX_VK_OOT_FOG=1, RX_VK_NOT_A_SWITCH=1 and RX_VK_DESC_REUSE=1 set. The start logged the removed, the misspelt and the set switches, both scenes drew at main's frame rates (Hyrule Field standing 79.5 fps), and the run ended cleanly. The last edit (a path's value said as ) was built, not run.

Tested in game: RTX 3090, NVIDIA 620.70, Linux: a dev pack over base 8e9cfc3a from the Kokiri Forest save, then Hyrule Field by the debug teleport, standing and turning in each at 2560x1440, with RX_VK_GPU_PROFILE=1, RX_VK_OOT_FOG=1, RX_VK_NOT_A_SWITCH=1 and RX_VK_DESC_REUSE=1 set. The start logged the removed, the misspelt and the set switches, both scenes drew at main's frame rates (Hyrule Field standing 79.5 fps), and the run ended cleanly. The last edit (a path's value said as <a path>) was built, not run.
HumanBean changed title from WIP: feat(vk): the renderer's switches in one table (gpu/vk/switches.def), and a start that says which are set to feat(vk): the renderer's switches in one table (gpu/vk/switches.def), and a start that says which are set 2026-11-17 01:36:21 +00:00
HumanBean deleted branch feat/switch-table 2026-11-17 01:36:36 +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!1300
No description provided.