feat(vk): RX_VK_TEST_VRAM_MB takes the card's VRAM as at most n MiB wherever the renderer sizes something by it #1107

Merged
HumanBean merged 1 commit from HumanBean/Longshot:feat/test-vram-mb into main 2026-11-16 10:25:42 +00:00
Owner

Type: feat · Risk: low · Tested on: Linux, RTX 3090 · Needs: a Windows build (llvm-mingw)

Why

The renderer sizes several things by how much video memory the card has, not only by what the driver allows: how many texture blocks it makes at the start, the mirrors' budget, the texture budget's rule and the auto settings. RX_VK_TEST_ALLOWED_MB lowers the allowance alone, so on a large card those parts still follow its real heap. A 6 GB card's rules can't be played on a 24 GB card, and the open small-card PRs gated on the card's size (#1057, #1073, #637) can't be measured on one.

RX_VK_TEST_VRAM_MB=<MiB> takes the card's VRAM as at most that much in every place that reads it. With both switches a large card runs a small one's whole policy: RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233 is the RTX 3050 6 GB Laptop of #637, #1057 and #1073.

What changed

One helper caps the card's VRAM at RX_VK_TEST_VRAM_MB for every place that sizes something by it. Unset, it returns the heap as it is, so nothing changes for players.

  • vk/memory: test_vram_bytes(heap) in gpu/vk/vk_memory.cpp (declared in vk_internal.h) returns the heap capped at RX_VK_TEST_VRAM_MB, or the heap when it's unset. device_vram_bytes() returns it, so the mirrors' budget (mirror_budget) and the texture budget's rule (texture_rule::dedicated_bytes) follow.
  • vk/vma: blocks_at_start() in gpu/vk/vk_vma.cpp reads the heap through it.
  • vk/main: auto_profile() in gpu/vk/vk_main.cpp reads hw.vram_mb through it.
  • tests: tests/test_blocks_at_start.py's fixture compiles blocks_at_start cut from vk_vma.cpp, so it gets a stand-in test_vram_bytes that returns the heap.
  • docs: the switch in docs/development.md, beside RX_VK_TEST_ALLOWED_MB, whose row now points to it.

Measurements

Verdict: with the switch set the renderer reads the 3090 as a 6 GB card: the texture budget comes from 6,144 MB and the texture pool starts with 7 blocks, against 24 with it unset. Nothing changes with it unset.

Hardware: Linux (CachyOS, kernel 7.3.3), RTX 3090 24 GB, NVIDIA 620.70.06, Ryzen 9 7900X, 30 GB
Scene: Hyrule Field then Castle Town Market (teleports), walking and turning; 2560x1440
Method: the startup lines of longshot_log.txt in two sessions of one build (main c167ec67 with this change, as a dev_packs pack): one with RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233, one with neither
How to reproduce: start the game with and without the two switches and read the lines below
Baseline: both columns are one build: this change on main c167ec67 (a dev_packs pack), rebased since onto main 13e90a5e, whose commits don't touch these lines. Unset is main's behaviour, so no separate main column.

After, RX_VK_TEST_VRAM_MB unset: this PR @ 7bc398f4 After, RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233: this PR @ 7bc398f4
Texture budget's line 11000 MB (driver allows 21279 MB, the card has 24576 MB, ...) 3584 MB (driver allows 5233 MB, the card has 6144 MB, ...)
Texture pool's blocks made at the start 24 7
unset: vk: texture budget: 11000 MB (driver allows 21279 MB, the card has 24576 MB, RAM 31658 MB)
unset: vk: textures from a pool of their own, 128 MB blocks (RX_VK_COMPACT), 24 made at the start
set:   vk: texture budget: 3584 MB (driver allows 5233 MB, the card has 6144 MB, RAM 31658 MB)
set:   vk: textures from a pool of their own, 128 MB blocks (RX_VK_COMPACT), 7 made at the start

The mirrors' budget isn't logged; it reads device_vram_bytes(), which returns the capped size.

Builds with this change (main, and main with #637, its parts and #1073) ran about 20 sessions with the switch set, measuring a 6 GB card's rules on the 3090 against each other. Like RX_VK_TEST_ALLOWED_MB, it does not make the driver short of memory: going over the allowance costs a Linux NVIDIA card next to nothing, so it tests a small card's policy, not its paging.

Flags and settings

One diagnostic switch, unset for everyone.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_TEST_VRAM_MB=<MiB> The card's VRAM taken as at most this many MiB (none) unset Starting blocks, mirrors' budget, texture budget's rule and auto settings as on a card of that size Ran a 6 GB card's rules on an RTX 3090 Unset: only for testing

Testing

Tested: Linux, RTX 3090, NVIDIA 620.70.06, in the game: Hyrule Field and the Market, about 20 sessions with the switch set and several with it unset (lines above). The renderer built from this change ran in a game folder built from main c167ec67; it is rebased since onto main 13e90a5e, whose commits don't touch these lines.

Not tested:

  • python -I -B tests/run_all.py: not run on this PC (no test suites run on it); left to CI. The checks that read the changed source: tests/test_blocks_at_start.py (fixture given a stand-in), tests/test_mirror_budget.py (reads mirror_budget, unchanged), tests/test_auto_handheld.py (leaves out the hw.vram_mb line).
  • Windows: the change is portable C++ (getenv, atoi); not built for Windows here.

Must be tested:

  • Windows: the renderer built with llvm-mingw, by hand or by CI's Windows build, expecting gpu/vk/vk_memory.cpp, vk_vma.cpp and vk_main.cpp to build with no error or warning

Risks

What could break: nothing with the switch unset: test_vram_bytes returns the heap unchanged.

Turning it off: leave RX_VK_TEST_VRAM_MB unset.

Compatibility: no cache, save or options file changes; the renderer's interface is unchanged.

Issues

See #637
See #1057
See #1073

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 (no test suites run on it); left to CI.
  • 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. tests/test_blocks_at_start.py's fixture gets a stand-in for the new call; the others are unaffected (Testing).
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux; not yet built for Windows. Renderer only, getenv and atoi.
  • Docs updated.

🤖 Generated with Claude Code

**Type:** feat · **Risk:** low · **Tested on:** Linux, RTX 3090 · **Needs:** a Windows build (llvm-mingw) ## Why The renderer sizes several things by how much video memory the card has, not only by what the driver allows: how many texture blocks it makes at the start, the mirrors' budget, the texture budget's rule and the auto settings. `RX_VK_TEST_ALLOWED_MB` lowers the allowance alone, so on a large card those parts still follow its real heap. A 6 GB card's rules can't be played on a 24 GB card, and the open small-card PRs gated on the card's size ([#1057](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1057), [#1073](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/1073), [#637](https://git.magicbean.dev/MagicBeanDev/Longshot/pulls/637)) can't be measured on one. `RX_VK_TEST_VRAM_MB=<MiB>` takes the card's VRAM as at most that much in every place that reads it. With both switches a large card runs a small one's whole policy: `RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233` is the RTX 3050 6 GB Laptop of #637, #1057 and #1073. ## What changed One helper caps the card's VRAM at `RX_VK_TEST_VRAM_MB` for every place that sizes something by it. Unset, it returns the heap as it is, so nothing changes for players. - vk/memory: `test_vram_bytes(heap)` in `gpu/vk/vk_memory.cpp` (declared in `vk_internal.h`) returns the heap capped at `RX_VK_TEST_VRAM_MB`, or the heap when it's unset. `device_vram_bytes()` returns it, so the mirrors' budget (`mirror_budget`) and the texture budget's rule (`texture_rule::dedicated_bytes`) follow. - vk/vma: `blocks_at_start()` in `gpu/vk/vk_vma.cpp` reads the heap through it. - vk/main: `auto_profile()` in `gpu/vk/vk_main.cpp` reads `hw.vram_mb` through it. - tests: `tests/test_blocks_at_start.py`'s fixture compiles `blocks_at_start` cut from `vk_vma.cpp`, so it gets a stand-in `test_vram_bytes` that returns the heap. - docs: the switch in `docs/development.md`, beside `RX_VK_TEST_ALLOWED_MB`, whose row now points to it. ## Measurements **Verdict:** with the switch set the renderer reads the 3090 as a 6 GB card: the texture budget comes from 6,144 MB and the texture pool starts with 7 blocks, against 24 with it unset. Nothing changes with it unset. Hardware: Linux (CachyOS, kernel 7.3.3), RTX 3090 24 GB, NVIDIA 620.70.06, Ryzen 9 7900X, 30 GB Scene: Hyrule Field then Castle Town Market (teleports), walking and turning; 2560x1440 Method: the startup lines of `longshot_log.txt` in two sessions of one build (main c167ec67 with this change, as a dev_packs pack): one with `RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233`, one with neither How to reproduce: start the game with and without the two switches and read the lines below Baseline: both columns are one build: this change on main c167ec67 (a dev_packs pack), rebased since onto main 13e90a5e, whose commits don't touch these lines. Unset is main's behaviour, so no separate main column. | | After, RX_VK_TEST_VRAM_MB unset: this PR @ 7bc398f4 | After, RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233: this PR @ 7bc398f4 | |---|---|---| | Texture budget's line | `11000 MB (driver allows 21279 MB, the card has 24576 MB, ...)` | `3584 MB (driver allows 5233 MB, the card has 6144 MB, ...)` | | Texture pool's blocks made at the start | 24 | 7 | ``` unset: vk: texture budget: 11000 MB (driver allows 21279 MB, the card has 24576 MB, RAM 31658 MB) unset: vk: textures from a pool of their own, 128 MB blocks (RX_VK_COMPACT), 24 made at the start set: vk: texture budget: 3584 MB (driver allows 5233 MB, the card has 6144 MB, RAM 31658 MB) set: vk: textures from a pool of their own, 128 MB blocks (RX_VK_COMPACT), 7 made at the start ``` The mirrors' budget isn't logged; it reads `device_vram_bytes()`, which returns the capped size. Builds with this change (main, and main with #637, its parts and #1073) ran about 20 sessions with the switch set, measuring a 6 GB card's rules on the 3090 against each other. Like `RX_VK_TEST_ALLOWED_MB`, it does not make the driver short of memory: going over the allowance costs a Linux NVIDIA card next to nothing, so it tests a small card's policy, not its paging. ### Flags and settings One diagnostic switch, unset for everyone. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_TEST_VRAM_MB=<MiB>` | The card's VRAM taken as at most this many MiB | (none) | unset | Starting blocks, mirrors' budget, texture budget's rule and auto settings as on a card of that size | Ran a 6 GB card's rules on an RTX 3090 | Unset: only for testing | ## Testing **Tested:** Linux, RTX 3090, NVIDIA 620.70.06, in the game: Hyrule Field and the Market, about 20 sessions with the switch set and several with it unset (lines above). The renderer built from this change ran in a game folder built from main c167ec67; it is rebased since onto main 13e90a5e, whose commits don't touch these lines. **Not tested:** - `python -I -B tests/run_all.py`: not run on this PC (no test suites run on it); left to CI. The checks that read the changed source: `tests/test_blocks_at_start.py` (fixture given a stand-in), `tests/test_mirror_budget.py` (reads `mirror_budget`, unchanged), `tests/test_auto_handheld.py` (leaves out the `hw.vram_mb` line). - Windows: the change is portable C++ (`getenv`, `atoi`); not built for Windows here. **Must be tested:** - Windows: the renderer built with llvm-mingw, by hand or by CI's Windows build, expecting `gpu/vk/vk_memory.cpp`, `vk_vma.cpp` and `vk_main.cpp` to build with no error or warning ## Risks **What could break:** nothing with the switch unset: `test_vram_bytes` returns the heap unchanged. **Turning it off:** leave `RX_VK_TEST_VRAM_MB` unset. **Compatibility:** no cache, save or options file changes; the renderer's interface is unchanged. ## Issues See #637 See #1057 See #1073 ## 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 (no test suites run on it); left to CI. - [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. `tests/test_blocks_at_start.py`'s fixture gets a stand-in for the new call; the others are unaffected (Testing). - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. Built on Linux; not yet built for Windows. Renderer only, `getenv` and `atoi`. - [x] Docs updated. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(vk): RX_VK_TEST_VRAM_MB takes the card's VRAM as at most n MiB wherever the renderer sizes something by 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 9s
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 17s
Website / Website on Cloudflare (pull_request_target) Has been skipped
PR description / Description follows the template (pull_request_target) Failing after 4s
7bc398f419
RX_VK_TEST_ALLOWED_MB lowers what the driver allows, but the texture pool's starting blocks, the mirrors' budget, the
texture budget's rule and the auto settings still follow the card's real heap: on an RTX 3090 a 6 GB card's rules
could not run (#637's, #1057's and #1073's, gated on the card's size). test_vram_bytes() (vk_memory.cpp) caps the heap
each of them reads; unset, nothing changes. A diagnostic switch, off for everyone.

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

Tested in game: RTX 3090, NVIDIA 620.70.06, Linux (CachyOS): Hyrule Field and Castle Town Market, about 20 sessions with RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233 and several with it unset. Set, the log reads the card as 6144 MB (texture budget 3584 MB, 7 starting blocks); unset, as 24576 MB (11000 MB, 24 blocks). No crash or device loss in any session.

Tested in game: RTX 3090, NVIDIA 620.70.06, Linux (CachyOS): Hyrule Field and Castle Town Market, about 20 sessions with RX_VK_TEST_VRAM_MB=6144 RX_VK_TEST_ALLOWED_MB=5233 and several with it unset. Set, the log reads the card as 6144 MB (texture budget 3584 MB, 7 starting blocks); unset, as 24576 MB (11000 MB, 24 blocks). No crash or device loss in any session.
Collaborator

Possibly related, for context:

  • issue #939 Game: on a 6 GB card VRAM goes over the driver's allowance after a few area changes, Hyrule Field falls from 31 to 14 fps until a restart (GTX 1060, nightly-189) — Open issue documents VRAM pressure on a 6 GB NVIDIA card; pertinent test scenario.
  • issue #585 Idea: sparse mirrors cost 1-4 ms of GPU a frame on an RX 5600 XT; whole mirrors are faster until their budget fills (runs wanted on other 6 GB cards) — Open issue compares mirror policies on 6 GB cards, relevant to the capped mirror budget.
Possibly related, for context: - issue #939 Game: on a 6 GB card VRAM goes over the driver's allowance after a few area changes, Hyrule Field falls from 31 to 14 fps until a restart (GTX 1060, nightly-189) — Open issue documents VRAM pressure on a 6 GB NVIDIA card; pertinent test scenario. - issue #585 Idea: sparse mirrors cost 1-4 ms of GPU a frame on an RX 5600 XT; whole mirrors are faster until their budget fills (runs wanted on other 6 GB cards) — Open issue compares mirror policies on 6 GB cards, relevant to the capped mirror budget.
HumanBean changed title from WIP: feat(vk): RX_VK_TEST_VRAM_MB takes the card's VRAM as at most n MiB wherever the renderer sizes something by it to feat(vk): RX_VK_TEST_VRAM_MB takes the card's VRAM as at most n MiB wherever the renderer sizes something by it 2026-11-16 10:25:23 +00:00
HumanBean deleted branch feat/test-vram-mb 2026-11-16 10:25:43 +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!1107
No description provided.