perf(vk): an import mostly outside every game pool is trimmed back to its live parts

github-sync commented

2026-11-12 15:49:11 +00:00

Owner

@klikso opened this pull request on GitHub · 2026-11-12 15:34 UTC · original
Merged on GitHub in ab2d4cc104

Why. On an 8 GB card, Castle Town Market runs at ~54 fps with almost no long frames when it is loaded from a save, and at ~45 fps with a long frame every second or two when the player walks in from Hyrule Field, for as long as they stay. Part of the difference is VRAM the previous scene's pools still hold: imports never shrink.

An import only grows: a binding across its end makes it again, larger, and a pool the game binds whole is imported whole. A pool's VRAM mirror, and its write-back shadow, are its import's whole range.
When the game frees a scene's large pools and makes the next scene's smaller ones at the same addresses, the import keeps the old range. It is bound every frame through the small live pool inside it, so no idle rule ever lets its mirror go.
Measured (the two largest; from a local diagnostic that lists the live mirrors, not in this PR): the field's 213 MB pool at 0x108c711000 leaves a 224 MB mirror where the Market loaded from a save has 48 MB; the culling lists' pool is 152 MB where it has 104 MB. With their shadows that is ~260 MB the scene does not bind, on a card where the Market's textures sit right at the 90% line.

This is the launch-to-launch "fast or slow Market" from #995 and my note on #2685: it was not the launch, it was whether the save was in the Market or in the field.

What

gpu/vk/mirror_trim.h (rules only) and mirrors_trim() in vk_memory.cpp, called from memory_begin_submission every 64 submissions:

Which import. One with a mirror whose game pools (the host's table, each out to its 4 MB chunks, parts closer than 8 MB joined) leave at least 24 MB and a quarter of it outside every pool, in 1 to 4 live parts, and that has stayed so for 1800 submissions (~5 s). Only while VRAM is over 80% of the allowance: with room to spare nothing is gained.
How. Its live parts are imported first (a failed import leaves everything as it was). Then it is retired with retire_pool, as a pool made again larger is, and each part gets its page table entries and a mirror in the same submission's uploads, before anything is recorded. Each new mirror takes what the GPU wrote from the old one through mirror_make's existing inherit (pages the CPU stamped since come from guest memory, as there). The old mirror goes once the GPU is done with it.
Room. Nothing is trimmed unless the new mirrors fit the mirror budget beside the old one.
No thrash. A range the game binds across again right after a trim is made larger again by the existing path; it then waits 4x and 16x longer, and after three trims in ~2 minutes it is left alone. The count starts over after 36,000 submissions without a trim, so a scene change every few minutes over a session is still trimmed.
Not touched: an import with no game pool in it at all (nothing binds it: the idle rules, and #2759's retire of finalized pools, cover that case; this PR is the partly-live one, which #2759 leaves as "alive"), parallel replay segments, cards without mirrors.
RX_VK_MIRROR_TRIM=0: off. One log line a trim.

What is given up: what the GPU wrote into the dead part of the old mirror and never wrote back. No game pool covers that memory any more, so nothing can bind it; a pool the game makes there later gets a mirror from guest memory, as any new pool does.

Measured

Note: every run below had this PC's DLSS model row on Transformer 2 (L), not the default K: the harder case (more GPU time and VRAM, #2836). With K the gain is smaller; those numbers are in the comment below.

Windows 11, RTX 3060 Ti 8 GB (driver 32.0.16.2114), Ryzen 5 5600X, 2560x1440 DLSS. main ba005ca4 with #2711, #2731 (at bce3d17e, where it was still on by default), #2685 and #2709 merged locally (the VRAM picture on this card without #2711 is the #2690 regression). Load the save, teleport to Hyrule Field, 10 s there, teleport to the Market, settle, then 80 s of the camera turning. RX_VK_FRAMEGEN=0, HOS_FPS_MAX=240. Three runs an arm, arms alternated. The fourth arm adds #2826 (the 90% rule evicting its excess instead of an eighth of the cache), which is the other half of the same stutter.

arm	fps mean	frames over 50 ms in 80 s	after the first 20 s: fps	after the first 20 s: frames over 50 ms per 20 s
main stack	44.4 / 45.0 / 45.0	100 / 69 / 60	46.5	12.3
this PR	45.7 / 47.2 / 47.4	66 / 37 / 28	48.5	4.7
#2826 alone	43.3 / 46.6 / 46.2	75 / 25 / 60	47.0	7.0
this PR + #2826	49.7 / 48.8 / 49.3	10 / 15 / 22	50.6	0.3

The first 20 s are the arrival itself (the trim only starts ~6 s after the old pools die), and are about the same in every arm.
Both trims happen in every run: pool 0x108c000000..0x109a400000 (228 MB) trimmed to its 1 live part(s), 48 MB and 0x1178400000..0x1181c00000 (152 MB) ... 104 MB. Mirrors at the end of a run: 1,584 MB against 1,820 MB. The new imports took under 2 ms each (no imported in line, which is logged from 2 ms).
Loaded from a save in the Market, no import qualifies and no trim runs (0 in two 30 s runs, 47.1 / 47.9 fps; with this and #2826 off 46.5 / 46.0). Those are lower than the 53-55 fps the same load gave in the morning: the driver's allowance was ~100 MB lower by then (6,944 against 7,043 MB), which is enough to put the direct load over the 90% line too.

A session: two rounds of 12 scenes by teleport (Hyrule Field, Kokiri Forest, Market, Kakariko, Lost Woods, Goron City, Zora's Domain, Graveyard, Death Mountain Trail, Zora's River, Sacred Forest Meadow, Gerudo Valley), 20 s of camera turning in each, with the flash detector on (RX_VK_FLASH=1, RX_VK_SHOT_EVERY=1): 24 of 24 scenes reached, 13 trims (600 MB given back in all), no flash detected, no device loss, no failed import. The mirrors moved between 1.2 and 2.0 GB and ended at 1,656 MB; the same tour before this sat at the 2,000 MB budget. Screenshots after the camera turn in Kokiri Forest (foliage, grass), Hyrule Field and the Market look right; I did not watch the runs live.

Not tested

AMD, Intel, Linux. On Windows the retired import goes back by the existing rules; AMD and Intel hold retired imports for a grace time there (retired_give_back.h), which this does not change but does feed.
RX_VK_PARALLEL (the trim does not run inside its segments, and was not run with it on).
A card with more VRAM than it needs: the 80% gate means it should never run there.
Long play (hours).

Tests

New tests/test_mirror_trim.py compiles and runs tests/test_mirror_trim.cpp (the Market's case, imports their pools fill, a small dead share, no live pool, parts joined and kept apart, too many parts, the waits and the count that starts over, the VRAM gate) and checks vk_memory.cpp keeps the order: parts imported before the retire, mirrors made before the old one stops waiting to be inherited, room in the budget first.
nx2/test_import_windows.py's model of Pool gets the two new fields pool_lookup carries over; tests/test_texel_buffer_ownership.py counts the trim's rollback among the callers of destroy_import_buffer (10).
python -I -B tests/run_all.py on Windows: 460 passed, 2 failed, 34 skipped; the two (nx2/test_nup_paths.py, tests/test_input_background.py) fail on unchanged main here too.

🤖 Generated with Claude Code

> [@klikso](https://github.com/klikso) opened this pull request on GitHub · 2026-11-12 15:34 UTC · [original](https://github.com/NotRexed/Hookshot/pull/2825) > **Merged on GitHub** in https://git.magicbean.dev/MagicBeanDev/Hookshot/commit/ab2d4cc104066b155498731a7b8a10eef2f72f5e **Why.** On an 8 GB card, Castle Town Market runs at ~54 fps with almost no long frames when it is loaded from a save, and at ~45 fps with a long frame every second or two when the player walks in from Hyrule Field, for as long as they stay. Part of the difference is VRAM the previous scene's pools still hold: imports never shrink. - An import only grows: a binding across its end makes it again, larger, and a pool the game binds whole is imported whole. A pool's VRAM mirror, and its write-back shadow, are its import's whole range. - When the game frees a scene's large pools and makes the next scene's smaller ones at the same addresses, the import keeps the old range. It is bound every frame through the small live pool inside it, so no idle rule ever lets its mirror go. - Measured (the two largest; from a local diagnostic that lists the live mirrors, not in this PR): the field's 213 MB pool at `0x108c711000` leaves a **224 MB** mirror where the Market loaded from a save has **48 MB**; the culling lists' pool is **152 MB** where it has **104 MB**. With their shadows that is ~260 MB the scene does not bind, on a card where the Market's textures sit right at the 90% line. This is the launch-to-launch "fast or slow Market" from #995 and my note on #2685: it was not the launch, it was whether the save was in the Market or in the field. ## What `gpu/vk/mirror_trim.h` (rules only) and `mirrors_trim()` in `vk_memory.cpp`, called from `memory_begin_submission` every 64 submissions: - **Which import.** One with a mirror whose game pools (the host's table, each out to its 4 MB chunks, parts closer than 8 MB joined) leave at least 24 MB and a quarter of it outside every pool, in 1 to 4 live parts, and that has stayed so for 1800 submissions (~5 s). Only while VRAM is over 80% of the allowance: with room to spare nothing is gained. - **How.** Its live parts are imported first (a failed import leaves everything as it was). Then it is retired with `retire_pool`, as a pool made again larger is, and each part gets its page table entries and a mirror **in the same submission's uploads**, before anything is recorded. Each new mirror takes what the GPU wrote from the old one through `mirror_make`'s existing inherit (pages the CPU stamped since come from guest memory, as there). The old mirror goes once the GPU is done with it. - **Room.** Nothing is trimmed unless the new mirrors fit the mirror budget beside the old one. - **No thrash.** A range the game binds across again right after a trim is made larger again by the existing path; it then waits 4x and 16x longer, and after three trims in ~2 minutes it is left alone. The count starts over after 36,000 submissions without a trim, so a scene change every few minutes over a session is still trimmed. - **Not touched:** an import with no game pool in it at all (nothing binds it: the idle rules, and #2759's retire of finalized pools, cover that case; this PR is the partly-live one, which #2759 leaves as "alive"), parallel replay segments, cards without mirrors. - `RX_VK_MIRROR_TRIM=0`: off. One log line a trim. What is given up: what the GPU wrote into the **dead** part of the old mirror and never wrote back. No game pool covers that memory any more, so nothing can bind it; a pool the game makes there later gets a mirror from guest memory, as any new pool does. ## Measured **Note:** every run below had this PC's DLSS model row on Transformer 2 (L), not the default K: the harder case (more GPU time and VRAM, #2836). With K the gain is smaller; those numbers are in the comment below. Windows 11, RTX 3060 Ti 8 GB (driver 32.0.16.2114), Ryzen 5 5600X, 2560x1440 DLSS. `main` ba005ca4 with #2711, #2731 (at bce3d17e, where it was still on by default), #2685 and #2709 merged locally (the VRAM picture on this card without #2711 is the #2690 regression). Load the save, teleport to Hyrule Field, 10 s there, teleport to the Market, settle, then **80 s** of the camera turning. `RX_VK_FRAMEGEN=0`, `HOS_FPS_MAX=240`. Three runs an arm, arms alternated. The fourth arm adds #2826 (the 90% rule evicting its excess instead of an eighth of the cache), which is the other half of the same stutter. | arm | fps mean | frames over 50 ms in 80 s | after the first 20 s: fps | after the first 20 s: frames over 50 ms per 20 s | |---|---|---|---|---| | main stack | 44.4 / 45.0 / 45.0 | 100 / 69 / 60 | 46.5 | 12.3 | | **this PR** | 45.7 / 47.2 / 47.4 | 66 / 37 / 28 | 48.5 | 4.7 | | #2826 alone | 43.3 / 46.6 / 46.2 | 75 / 25 / 60 | 47.0 | 7.0 | | this PR + #2826 | 49.7 / 48.8 / 49.3 | 10 / 15 / 22 | 50.6 | 0.3 | - The first 20 s are the arrival itself (the trim only starts ~6 s after the old pools die), and are about the same in every arm. - Both trims happen in every run: `pool 0x108c000000..0x109a400000 (228 MB) trimmed to its 1 live part(s), 48 MB` and `0x1178400000..0x1181c00000 (152 MB) ... 104 MB`. Mirrors at the end of a run: 1,584 MB against 1,820 MB. The new imports took under 2 ms each (no `imported in` line, which is logged from 2 ms). - Loaded from a save in the Market, no import qualifies and no trim runs (0 in two 30 s runs, 47.1 / 47.9 fps; with this and #2826 off 46.5 / 46.0). Those are lower than the 53-55 fps the same load gave in the morning: the driver's allowance was ~100 MB lower by then (6,944 against 7,043 MB), which is enough to put the direct load over the 90% line too. **A session:** two rounds of 12 scenes by teleport (Hyrule Field, Kokiri Forest, Market, Kakariko, Lost Woods, Goron City, Zora's Domain, Graveyard, Death Mountain Trail, Zora's River, Sacred Forest Meadow, Gerudo Valley), 20 s of camera turning in each, with the flash detector on (`RX_VK_FLASH=1`, `RX_VK_SHOT_EVERY=1`): 24 of 24 scenes reached, **13 trims (600 MB given back in all), no flash detected, no device loss, no failed import**. The mirrors moved between 1.2 and 2.0 GB and ended at 1,656 MB; the same tour before this sat at the 2,000 MB budget. Screenshots after the camera turn in Kokiri Forest (foliage, grass), Hyrule Field and the Market look right; I did not watch the runs live. ## Not tested - AMD, Intel, Linux. On Windows the retired import goes back by the existing rules; AMD and Intel hold retired imports for a grace time there (`retired_give_back.h`), which this does not change but does feed. - `RX_VK_PARALLEL` (the trim does not run inside its segments, and was not run with it on). - A card with more VRAM than it needs: the 80% gate means it should never run there. - Long play (hours). ## Tests - New `tests/test_mirror_trim.py` compiles and runs `tests/test_mirror_trim.cpp` (the Market's case, imports their pools fill, a small dead share, no live pool, parts joined and kept apart, too many parts, the waits and the count that starts over, the VRAM gate) and checks `vk_memory.cpp` keeps the order: parts imported before the retire, mirrors made before the old one stops waiting to be inherited, room in the budget first. - `nx2/test_import_windows.py`'s model of `Pool` gets the two new fields `pool_lookup` carries over; `tests/test_texel_buffer_ownership.py` counts the trim's rollback among the callers of `destroy_import_buffer` (10). - `python -I -B tests/run_all.py` on Windows: 460 passed, 2 failed, 34 skipped; the two (`nx2/test_nup_paths.py`, `tests/test_input_background.py`) fail on unchanged `main` here too. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

github-sync added 1 commit

2026-11-12 15:49:11 +00:00

perf(vk): an import mostly outside every game pool is trimmed back to its live parts 423fbd32c6

Imports only grew: a binding across an import's end makes it again larger, and a pool the game
binds whole is imported whole. A pool's VRAM mirror and its write-back shadow are its import's
whole range. After the game frees a scene's large pools and makes the next scene's smaller ones
at the same addresses, the import keeps the old range, bound every frame through the small live
pool inside it, and its mirror holds the dead rest for the session. Castle Town Market entered
from Hyrule Field on an 8 GB card: a 224 MB mirror where the Market loaded from a save has 48,
and 152 MB where it has 104.

While VRAM is over 80% full, a mirrored import that has been mostly outside every game pool for
1800 submissions is retired and each of its live parts imported again with a mirror made in the
same submission's uploads, taking the GPU's contents from the old mirror as a pool made again
larger does (gpu/vk/mirror_trim.h, mirrors_trim). RX_VK_MIRROR_TRIM=0: off.

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

arm (DLSS K)	fps mean	frames over 50 ms in 80 s	fps by 20 s quarter
main stack	50.4 / 52.0	10 / 8	47.7 50.8 49.7 53.9 / 51.7 50.0 53.2 53.4
both	50.6 / 54.2	6 / 1	45.5 48.6 53.4 56.3 / 51.8 54.4 56.3 54.7

arm	fps mean	frames over 50 ms	uploads a frame	textures let go for the budget (passes)	texture cache, low-high MB	compaction runs	replay submit
trim off, excess off	53.3 / 50.6 / 51.5	8 / 25 / 12	5.5 / 6.4 / 6.6	22,323 (203) / 24,588 (222) / 23,415 (209)	2,099-2,862 / 2,076-2,883 / 2,196-2,921	19 / 20 / 20	12.8 / 12.9 / 12.3 ms
#2825 alone (excess off)	56.5 / 56.0 / 53.5	2 / 4 / 22	2.6 / 2.3 / 3.3	10,559 (66) / 8,285 (47) / 13,359 (108)	2,381-2,908 / 2,313-2,854 / 2,355-2,903	8 / 9 / 15	12.3 / 12.2 / 12.1 ms
#2825 + #2826	56.5 / 54.7 / 54.4	7 / 2 / 16	0.7 / 2.4 / 1.3	2,282 (34) / 9,231 (135) / 3,299 (51)	2,498-3,078 / 2,483-3,009 / 2,585-3,008	4 / 12 / 5	11.4 / 11.4 / 11.3 ms

Rows
Columns

perf(vk): an import mostly outside every game pool is trimmed back to its live parts #2825

What

Measured

Not tested

Tests