perf(host): the game's texture heap is compacted at most once a second, not at every frame (HOS_TEX_COMPACT_MS) #1478

Merged
HumanBean merged 1 commit from GummiNaomi/Longshot:perf/tex-compact-gap into main 2026-11-17 22:48:22 +00:00
Member

Type: perf · Risk: medium · Tested on: Windows 11, RTX 4070 SUPER (NVIDIA 617.42), Ryzen 9 9950X3D · Needs: a long played session; Linux; an AMD card; a Steam Deck or another CPU of four cores

TL;DR

In busy places like Castle Town's market the game often hitched every few frames, even standing still. The game was tidying its texture memory at every frame, and each texture it moved had to be set up again by Longshot. This PR lets the game start that tidying at most once a second. Standing in the market on my PC, frames too long for 60 fps fell from 5 to 13 % to 1 to 1.5 %, and six areas look the same as before; a new test covers the rule and the patch.

Breakdown

  • Who it helps: anyone who sees uneven frame times in crowded places, the market above all.
  • What was wrong: the game asks for a tidy-up round of its texture memory at every frame, and every texture a round moves arrives at the renderer as a brand-new one.
  • What changes: the game may start a round at most once a second.
  • What does not change: the round itself, what it moves and how; saves; the picture; a build of another game version.
  • How it was checked: two runs each way standing in the market (frames over 16.7 ms 5.4 and 12.6 % against 1.0 and 1.5 %), six areas' pictures by eye, a new test, the whole test suite against main.
  • What is still open: a long played session, Linux, AMD and Intel cards, a CPU of four cores.
  • Risk: medium: the game's texture memory is tidied far less often than the game expects, and what it does when a large texture then does not fit is not known.

Why

Standing in Castle Town's market, some starts of the same build have 1 to 3 % of frames over 16.7 ms and others 10 to 14 %. In the rough ones the long frames come every 4, 10 or 14 frames, and each carries a batch of new textures: about 23 of them (10 MB) in one frame, 3 to 5 ms of uploads, descriptor builds and memory sync.

Those textures are not new to the game. The game keeps its textures' storage in one heap of 2,400 MB, which in the market stays at its line of 5 % free (read from the running game: 120.1 to 120.3 MB free, the line at 120.0). Its texture data manager's per-frame step (f_80797240) asks the heap's Compaction thread for a round at every frame none is running (the manager's flag bit 1, which its setup sets once, unconditionally), and every texture a round moved is finalized and made again at its new address (f_80797da0). On the console that is a copy and a new texture object. Here each one is a new texture to the renderer: its storage is hashed to find the image it had (#1222), an image is made and that one's copied in, and the bytes the game moved are synced to the mirrors.

How I found the caller: a temporary log of the game's call chain at nvnTextureFinalize (not in this PR) named one pool B job for the asset textures; the manager's fields are from reading that job's code and from the running game. With the flag's bit cleared in a running test game by a write from outside, the batches stopped at once and the long frames went from 3.4 to 4.0 % to 0.3 to 0.5 % in each of the three runs measured (a fourth left no trace).

The market's rough frame times are reported in #597, #1153 and #996. I have not shown that any of those is this; they are the same place.

What changed

The texture data manager asks for a compaction round at most once a second. The round itself is the game's, untouched: what it moves, how much, and how its textures are made again.

  • host: host/oot_tex_compact.h holds the rule (a gap of 0 is the game's own; below 0 never; else at least that long from one round's start to the next) and the switch's reading. host/oot_tex_compact.c holds the state, the default of 1000 ms and two log lines: what was chosen, and every 3,600 asks how many rounds were let through.
  • lift: nx2/oot_patches.py patch_tex_compact makes the request's second test ask the host too (!((flags >> 1) & 1) || !hos_oot_tex_compact_due()), in f_80797240 only. A file patched before, or whose code differs (another game version), is left as it is, and the report warns when the place is not found exactly once. The manager only asks when no round is running, so a round that has started always finishes.
  • switch: HOS_TEX_COMPACT_MS=<ms> sets another gap; 0 is at every frame, as the game has it; off never asks. Rows in gpu/vk/switches.def and docs/development.md.
  • tests: tests/test_tex_compact.py.
  • docs: four files under docs/tested/.

Measurements

Verdict: standing in the market, frames over 16.7 ms fall from 5.4 and 12.6 % to 1.0 and 1.5 %, the 99th percentile from 18.5 and 23.5 ms to 16.7 and 17.0 ms, and the frame rate rises from 70.8 and 67.2 to 75.4 and 74.9. The heap is still compacted: 89 and 84 rounds were asked for in those runs.

Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB
Scene: the repository's kokiri-start save, the debug teleport to Market_Child, then 55 s standing, no input; headless, scripts/longshot_ctl.py launch --profile test, uncapped (HOS_FPS_MAX=1000)
Method: one build, the two sides in turn, twice; the last 2,600 frames of the frame trace (RX_VK_FRAME_TRACE=1, about 35 s)
Baseline: this PR's code with HOS_TEX_COMPACT_MS=0, which is main's behaviour (the game's own request at every frame). The build is main 50170f81 with this change in the working tree; the PR's head, 54a42715, is that change unchanged on main 359131b4, and was not measured again after the rebase
How to reproduce: HOS_TEX_COMPACT_MS=0 against no switch, standing in the market for a minute after longshot_ctl.py teleport Market_Child; the log's decoded ASTC used again: N textures line counts the textures the game made again, and tex: the game's texture heap: N compaction rounds asked for the rounds

Before, HOS_TEX_COMPACT_MS=0: this change on main @ 50170f81 (two runs) After: this change on main @ 50170f81 (two runs)
Frames of 16.7 ms or more 5.4, 12.6 % 1.0, 1.5 %
Frames a second 70.8, 67.2 75.4, 74.9
Frame time, median 13.92, 14.04 ms 13.11, 13.23 ms
Frame time, 99th percentile 18.5, 23.5 ms 16.7, 17.0 ms
Frame time, the worst 31.0, 221.2 ms 20.5, 21.0 ms
Texture uploads a frame 0.49, 1.26 0.10, 0.13
Frames with 12 or more uploads 16, 109 4, 7
Memory sync, mean a frame 0.633, 0.790 ms 0.383, 0.389 ms
ASTC textures the game made again over the run 1,185, 2,489 221, 275
Compaction rounds asked for every frame none ran 89, 84
Errors, device loss none none

The choice of a second, from an earlier set on the same code with the default still 0 and the switch set by hand (the same scene and method, two runs each):

HOS_TEX_COMPACT_MS=0 =1000 =3000 =off
Frames of 16.7 ms or more 11.7, 10.1 % 1.5, 1.4 % 1.5, 1.4 % 3.2, 1.2 %
Frames a second (the last 40 s) 70.6, 70.9 74.7, 74.2 72.9, 74.1 71.6, 74.5
Frames with 12 or more uploads 235, 133 13, 11 0, 2 0, 0

A second gives the frames of three seconds or of never, and keeps the most compaction of the three.

Area changes, with no compaction at all (the outside write, before the switch existed; one tour each, 8 minutes, 29 and 30 debug teleports round six areas): 24,327 texture uploads against 48,758 with the game's own; frames of 50 ms or more 125 (11.4 s) against 156 (14.5 s); none of 250 ms or more against 2. That is the off end, not this PR's default, and one tour a side.

The picture: one full-size shot in each of six areas (Kokiri Forest, the market, Hyrule Field, Kakariko, the Lost Woods, Zora's River) with HOS_TEX_COMPACT_MS=0 and with =1000, compared by eye: the same things are drawn on both, and what differs is what two runs differ by (the pose, Navi, fireflies, the camera still settling after the save's load).

Flags and settings

One new switch.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
HOS_TEX_COMPACT_MS the least time between two compaction rounds of the game's texture data heap, in ms did not exist: a round asked for at every frame none ran 1000 (unset); 0 the game's own; off never fewer textures made again by the game, so fewer batches of new textures for the renderer helps standing in the market on a 9950X3D with an RTX 4070 SUPER on Windows; untested on Linux, on AMD and Intel cards, on a CPU of four cores, in a long session unset (1000)

Testing

Tested: Windows 11, RTX 4070 SUPER, NVIDIA 617.42: the four runs above on this PR's code, the eight of the earlier set and the two tours, no error or device loss in any log; the six areas' shots by eye. tests/test_tex_compact.py passes (the rule and the switch's values compiled alone with clang, the patch over the step as lifted, patch_file's count); patch_tex_compact over this PC's lifted code_004.c finds the place once and leaves a patched file as it is. python -I -B tests/run_all.py with clang here, this PR @ 54a42715: 399 passed, 113 failed, 229 skipped; main @ 359131b4 in the same session: 399 passed, 112 failed, 229 skipped. The 112 are the same on both (this PC's toolchain: no gcc, Windows line endings, fixtures needing tools not installed; tests/test_switch_table.py fails on main itself now, RX_VK_INVALIDATE_WAIT listed as gone and still read). The one more here is tests/test_longshot_ctl.py, which passes run by itself on this PR (51 tests, 2 skipped) and does not touch this change.

Not tested: a session longer than a few minutes with the default, and so what the heap does when it is compacted a sixtieth as often for hours (a texture that cannot be placed would not be in the log); walking and camera turns; adult Link, dungeons, cutscenes; Linux; AMD and Intel cards; a CPU with few cores; a build without the supported game version (the patch leaves other code as it is: by the test only).

Must be tested:

  • Windows 11, any GPU, any driver: a played session of half an hour or more through several areas with no switch, watching for textures that stay blurry, missing or wrong, expecting none (by hand: the log would not say)
  • Linux, any GPU: standing in the market a minute, with no switch and with HOS_TEX_COMPACT_MS=0, expecting no crash, the same picture, and fewer frames over 16.7 ms with no switch (Test Farm: @Beanstalk linux)
  • Windows, an AMD card: the same, expecting the same (Test Farm: @Beanstalk windows amd)
  • A Steam Deck: the same, expecting the same or better frame times with no switch (Test Farm: @Beanstalk steamdeck)

Risks

What could break: the game's heap is compacted far less often than the game asks for, so it can be more fragmented than on the console. If a large texture then cannot be placed, I do not know what the game does: I did not find that path, and nothing in these runs showed it (the heap moved between 120 MB and 1,073 MB free over a tour with no compaction at all, and the game kept dropping and loading textures). A round still runs every second, and a round that has started always finishes.

Turning it off: HOS_TEX_COMPACT_MS=0.

Compatibility: no saved data or file format changes. A build of another game version keeps the game's own behaviour (the patch does not apply; the report says so).

Issues

Not shown to fix any, the same place: #597, #1153, #996. Searched compaction, texture heap, market, stutter, long frame: no issue or pull request on the game's own texture heap compaction. #1222 is the reuse these textures go through; #1281 (open) touches how they are hashed.

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).
  • Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what
    can't be run by hand is in Testing's Not testable by hand, with why.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and
    in Risks.
  • 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.
  • 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 file in docs/tested/ for each new measured run (format in docs/tested-configurations.md).
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.
  • Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows for the MSVC target only.)

🤖 Generated with Claude Code

**Type:** perf · **Risk:** medium · **Tested on:** Windows 11, RTX 4070 SUPER (NVIDIA 617.42), Ryzen 9 9950X3D · **Needs:** a long played session; Linux; an AMD card; a Steam Deck or another CPU of four cores ## TL;DR In busy places like Castle Town's market the game often hitched every few frames, even standing still. The game was tidying its texture memory at every frame, and each texture it moved had to be set up again by Longshot. This PR lets the game start that tidying at most once a second. Standing in the market on my PC, frames too long for 60 fps fell from 5 to 13 % to 1 to 1.5 %, and six areas look the same as before; a new test covers the rule and the patch. ## Breakdown - **Who it helps:** anyone who sees uneven frame times in crowded places, the market above all. - **What was wrong:** the game asks for a tidy-up round of its texture memory at every frame, and every texture a round moves arrives at the renderer as a brand-new one. - **What changes:** the game may start a round at most once a second. - **What does not change:** the round itself, what it moves and how; saves; the picture; a build of another game version. - **How it was checked:** two runs each way standing in the market (frames over 16.7 ms 5.4 and 12.6 % against 1.0 and 1.5 %), six areas' pictures by eye, a new test, the whole test suite against main. - **What is still open:** a long played session, Linux, AMD and Intel cards, a CPU of four cores. - **Risk:** medium: the game's texture memory is tidied far less often than the game expects, and what it does when a large texture then does not fit is not known. ## Why Standing in Castle Town's market, some starts of the same build have 1 to 3 % of frames over 16.7 ms and others 10 to 14 %. In the rough ones the long frames come every 4, 10 or 14 frames, and each carries a batch of new textures: about 23 of them (10 MB) in one frame, 3 to 5 ms of uploads, descriptor builds and memory sync. Those textures are not new to the game. The game keeps its textures' storage in one heap of 2,400 MB, which in the market stays at its line of 5 % free (read from the running game: 120.1 to 120.3 MB free, the line at 120.0). Its texture data manager's per-frame step (`f_80797240`) asks the heap's Compaction thread for a round at every frame none is running (the manager's flag bit 1, which its setup sets once, unconditionally), and every texture a round moved is finalized and made again at its new address (`f_80797da0`). On the console that is a copy and a new texture object. Here each one is a new texture to the renderer: its storage is hashed to find the image it had (#1222), an image is made and that one's copied in, and the bytes the game moved are synced to the mirrors. How I found the caller: a temporary log of the game's call chain at `nvnTextureFinalize` (not in this PR) named one pool B job for the asset textures; the manager's fields are from reading that job's code and from the running game. With the flag's bit cleared in a running test game by a write from outside, the batches stopped at once and the long frames went from 3.4 to 4.0 % to 0.3 to 0.5 % in each of the three runs measured (a fourth left no trace). The market's rough frame times are reported in #597, #1153 and #996. I have not shown that any of those is this; they are the same place. ## What changed The texture data manager asks for a compaction round at most once a second. The round itself is the game's, untouched: what it moves, how much, and how its textures are made again. - host: `host/oot_tex_compact.h` holds the rule (a gap of 0 is the game's own; below 0 never; else at least that long from one round's start to the next) and the switch's reading. `host/oot_tex_compact.c` holds the state, the default of 1000 ms and two log lines: what was chosen, and every 3,600 asks how many rounds were let through. - lift: `nx2/oot_patches.py` `patch_tex_compact` makes the request's second test ask the host too (`!((flags >> 1) & 1) || !hos_oot_tex_compact_due()`), in `f_80797240` only. A file patched before, or whose code differs (another game version), is left as it is, and the report warns when the place is not found exactly once. The manager only asks when no round is running, so a round that has started always finishes. - switch: `HOS_TEX_COMPACT_MS=<ms>` sets another gap; `0` is at every frame, as the game has it; `off` never asks. Rows in `gpu/vk/switches.def` and `docs/development.md`. - tests: `tests/test_tex_compact.py`. - docs: four files under `docs/tested/`. ## Measurements **Verdict:** standing in the market, frames over 16.7 ms fall from 5.4 and 12.6 % to 1.0 and 1.5 %, the 99th percentile from 18.5 and 23.5 ms to 16.7 and 17.0 ms, and the frame rate rises from 70.8 and 67.2 to 75.4 and 74.9. The heap is still compacted: 89 and 84 rounds were asked for in those runs. Hardware: Windows 11 Pro 26200, RTX 4070 SUPER 12 GB (NVIDIA 617.42), Ryzen 9 9950X3D (16 cores, SMT off), 32 GB Scene: the repository's `kokiri-start` save, the debug teleport to `Market_Child`, then 55 s standing, no input; headless, `scripts/longshot_ctl.py launch --profile test`, uncapped (`HOS_FPS_MAX=1000`) Method: one build, the two sides in turn, twice; the last 2,600 frames of the frame trace (`RX_VK_FRAME_TRACE=1`, about 35 s) Baseline: this PR's code with `HOS_TEX_COMPACT_MS=0`, which is main's behaviour (the game's own request at every frame). The build is main 50170f81 with this change in the working tree; the PR's head, 54a42715, is that change unchanged on main 359131b4, and was not measured again after the rebase How to reproduce: `HOS_TEX_COMPACT_MS=0` against no switch, standing in the market for a minute after `longshot_ctl.py teleport Market_Child`; the log's `decoded ASTC used again: N textures` line counts the textures the game made again, and `tex: the game's texture heap: N compaction rounds asked for` the rounds | | Before, `HOS_TEX_COMPACT_MS=0`: this change on main @ 50170f81 (two runs) | After: this change on main @ 50170f81 (two runs) | |---|---|---| | Frames of 16.7 ms or more | 5.4, 12.6 % | 1.0, 1.5 % | | Frames a second | 70.8, 67.2 | 75.4, 74.9 | | Frame time, median | 13.92, 14.04 ms | 13.11, 13.23 ms | | Frame time, 99th percentile | 18.5, 23.5 ms | 16.7, 17.0 ms | | Frame time, the worst | 31.0, 221.2 ms | 20.5, 21.0 ms | | Texture uploads a frame | 0.49, 1.26 | 0.10, 0.13 | | Frames with 12 or more uploads | 16, 109 | 4, 7 | | Memory sync, mean a frame | 0.633, 0.790 ms | 0.383, 0.389 ms | | ASTC textures the game made again over the run | 1,185, 2,489 | 221, 275 | | Compaction rounds asked for | every frame none ran | 89, 84 | | Errors, device loss | none | none | The choice of a second, from an earlier set on the same code with the default still 0 and the switch set by hand (the same scene and method, two runs each): | | `HOS_TEX_COMPACT_MS=0` | `=1000` | `=3000` | `=off` | |---|---|---|---|---| | Frames of 16.7 ms or more | 11.7, 10.1 % | 1.5, 1.4 % | 1.5, 1.4 % | 3.2, 1.2 % | | Frames a second (the last 40 s) | 70.6, 70.9 | 74.7, 74.2 | 72.9, 74.1 | 71.6, 74.5 | | Frames with 12 or more uploads | 235, 133 | 13, 11 | 0, 2 | 0, 0 | A second gives the frames of three seconds or of never, and keeps the most compaction of the three. Area changes, with no compaction at all (the outside write, before the switch existed; one tour each, 8 minutes, 29 and 30 debug teleports round six areas): 24,327 texture uploads against 48,758 with the game's own; frames of 50 ms or more 125 (11.4 s) against 156 (14.5 s); none of 250 ms or more against 2. That is the `off` end, not this PR's default, and one tour a side. The picture: one full-size shot in each of six areas (Kokiri Forest, the market, Hyrule Field, Kakariko, the Lost Woods, Zora's River) with `HOS_TEX_COMPACT_MS=0` and with `=1000`, compared by eye: the same things are drawn on both, and what differs is what two runs differ by (the pose, Navi, fireflies, the camera still settling after the save's load). ### Flags and settings One new switch. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `HOS_TEX_COMPACT_MS` | the least time between two compaction rounds of the game's texture data heap, in ms | did not exist: a round asked for at every frame none ran | `1000` (unset); `0` the game's own; `off` never | fewer textures made again by the game, so fewer batches of new textures for the renderer | helps standing in the market on a 9950X3D with an RTX 4070 SUPER on Windows; untested on Linux, on AMD and Intel cards, on a CPU of four cores, in a long session | unset (1000) | ## Testing **Tested:** Windows 11, RTX 4070 SUPER, NVIDIA 617.42: the four runs above on this PR's code, the eight of the earlier set and the two tours, no error or device loss in any log; the six areas' shots by eye. `tests/test_tex_compact.py` passes (the rule and the switch's values compiled alone with clang, the patch over the step as lifted, `patch_file`'s count); `patch_tex_compact` over this PC's lifted `code_004.c` finds the place once and leaves a patched file as it is. `python -I -B tests/run_all.py` with clang here, this PR @ 54a42715: 399 passed, 113 failed, 229 skipped; main @ 359131b4 in the same session: 399 passed, 112 failed, 229 skipped. The 112 are the same on both (this PC's toolchain: no gcc, Windows line endings, fixtures needing tools not installed; `tests/test_switch_table.py` fails on main itself now, `RX_VK_INVALIDATE_WAIT` listed as gone and still read). The one more here is `tests/test_longshot_ctl.py`, which passes run by itself on this PR (51 tests, 2 skipped) and does not touch this change. **Not tested:** a session longer than a few minutes with the default, and so what the heap does when it is compacted a sixtieth as often for hours (a texture that cannot be placed would not be in the log); walking and camera turns; adult Link, dungeons, cutscenes; Linux; AMD and Intel cards; a CPU with few cores; a build without the supported game version (the patch leaves other code as it is: by the test only). **Must be tested:** - Windows 11, any GPU, any driver: a played session of half an hour or more through several areas with no switch, watching for textures that stay blurry, missing or wrong, expecting none (by hand: the log would not say) - Linux, any GPU: standing in the market a minute, with no switch and with `HOS_TEX_COMPACT_MS=0`, expecting no crash, the same picture, and fewer frames over 16.7 ms with no switch (Test Farm: @Beanstalk linux) - Windows, an AMD card: the same, expecting the same (Test Farm: @Beanstalk windows amd) - A Steam Deck: the same, expecting the same or better frame times with no switch (Test Farm: @Beanstalk steamdeck) ## Risks **What could break:** the game's heap is compacted far less often than the game asks for, so it can be more fragmented than on the console. If a large texture then cannot be placed, I do not know what the game does: I did not find that path, and nothing in these runs showed it (the heap moved between 120 MB and 1,073 MB free over a tour with no compaction at all, and the game kept dropping and loading textures). A round still runs every second, and a round that has started always finishes. **Turning it off:** `HOS_TEX_COMPACT_MS=0`. **Compatibility:** no saved data or file format changes. A build of another game version keeps the game's own behaviour (the patch does not apply; the report says so). ## Issues Not shown to fix any, the same place: #597, #1153, #996. Searched `compaction`, `texture heap`, `market`, `stutter`, `long frame`: no issue or pull request on the game's own texture heap compaction. #1222 is the reuse these textures go through; #1281 (open) touches how they are hashed. ## 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] Tested on my own PC where it runs (in the game, for a change the game runs), as Testing's Tested says; what can't be run by hand is in Testing's Not testable by hand, with why. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. - [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] 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 file in `docs/tested/` for each new measured run (format in `docs/tested-configurations.md`). - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated. - [ ] Host code builds on both Windows (llvm-mingw) and Linux, with UTF-8 paths. (Built on Windows for the MSVC target only.) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
perf(host): the game's texture heap is compacted at most once a second, not at every frame (HOS_TEX_COMPACT_MS)
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
Website / Website on Cloudflare (pull_request_target) 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 19s
CI / Workflow lint (actionlint) (pull_request) Successful in 21s
Third-party parts / As their notes say (pull_request) Successful in 41s
PR description / Description follows the template (pull_request_target) Failing after 4s
beanstalk/approval approved by GummiNaomi, futondestroyer (double-reviewed)
beanstalk/linux+amd 0/1 pass, 0 running, 0 queued
beanstalk/windows+amd 0/1 pass, 0 running, 0 queued
54a4271598
The game keeps its textures' storage in one heap of 2,400 MB, which in Castle
Town's market stays at its line of 5 % free. Its texture data manager's
per-frame step (f_80797240) asks the heap's Compaction thread for a round at
every frame none runs (the manager's flag bit 1, which its setup always sets),
and every texture a round moved is finalized and made again at its new address.
On the console that is a copy and a new texture object. Here each one is a new
texture to the renderer: its storage is hashed to find the image it had, an
image is made and that one's copied in, and the bytes the game moved are synced
to the mirrors. Standing in the market that was a batch of about 23 textures
(10 MB) every 9 frames or so, 3 to 5 ms in that frame, and those frames were
the long ones.

The manager now asks for a round only when the last one it asked for is a
second ago. The round itself is the game's, untouched.

- host: host/oot_tex_compact.h holds the rule (a gap of 0 is the game's own,
  below 0 never, else at least that long between two rounds' starts) and the
  switch's reading; host/oot_tex_compact.c the state, the default of 1000 ms
  and the log lines.
- lift: nx2/oot_patches.py patch_tex_compact makes the request's second test
  ask hos_oot_tex_compact_due as well, in f_80797240 only; a file patched
  before, or whose code differs, is left as it is, and the report warns when
  the place is not found once.
- HOS_TEX_COMPACT_MS=<ms>: another gap; 0: at every frame, as the game has it;
  off: never. Rows in gpu/vk/switches.def and docs/development.md.
- tests/test_tex_compact.py: the rule and the switch's values compiled alone,
  the patch over the step as lifted, patch_file's count.

Standing in the market, a 9950X3D with an RTX 4070 SUPER, the last 2,600
frames, two runs each in turn on one build: frames of 16.7 ms or more 5.4 and
12.6 % with HOS_TEX_COMPACT_MS=0 against 1.0 and 1.5 % with no switch; 70.8 and
67.2 against 75.4 and 74.9 frames a second; the 99th percentile 18.5 and
23.5 ms against 16.7 and 17.0 ms. 89 and 84 rounds were still asked for.

Assisted-by: Claude Mythos 5.2
Co-Authored-By: Claude Mythos 5.2 <[email protected]>
Author
Member

@Beanstalk linux and windows amd: stand in Castle Town's market for a minute (the debug teleport to Market_Child, no input), once with this PR's default and once with HOS_TEX_COMPACT_MS=0 (the game's own compaction request at every frame, as on main). Expecting: no crash; the same picture on both; with the default no more frames over 16.7 ms than with the switch at 0 (here, on a 9950X3D with an RTX 4070 SUPER on Windows: 1.0 and 1.5 % against 5.4 and 12.6 %); and in the log the line tex: the game's texture heap is compacted at most every 1000 ms with the default and no such line with the switch at 0. A build on Linux is the other thing this asks for: the checklist's Linux build box is still open.

🤖 Generated with Claude Code

@Beanstalk linux and windows amd: stand in Castle Town's market for a minute (the debug teleport to `Market_Child`, no input), once with this PR's default and once with `HOS_TEX_COMPACT_MS=0` (the game's own compaction request at every frame, as on main). Expecting: no crash; the same picture on both; with the default no more frames over 16.7 ms than with the switch at 0 (here, on a 9950X3D with an RTX 4070 SUPER on Windows: 1.0 and 1.5 % against 5.4 and 12.6 %); and in the log the line `tex: the game's texture heap is compacted at most every 1000 ms` with the default and no such line with the switch at 0. A build on Linux is the other thing this asks for: the checklist's Linux build box is still open. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Member

@GummiNaomi approval of 54a4271 recorded. This diff touches sensitive paths, so a second member of BigBeans must approve it too.

@GummiNaomi approval of `54a4271` recorded. This diff touches sensitive paths, so a second member of `BigBeans` must approve it too.
Member

Beanstalk test farm

Commit 54a4271 · tier double-reviewed · approved by GummiNaomi, futondestroyer · dashboard

What will be tested · AI plan (gpt-6.1-terra)

On Linux and Windows AMD, the farm builds both revisions and idles in the child Market for one minute per run, using the PR default and its zero-gap switch. Screenshots and p99 frame times are compared with main; crashes, substantial picture differences, or a p99 regression fail the plan. The farm cannot directly compare the two PR settings’ counts of frames over 16.7 ms or apply the requested setting-specific log checks, so p99 is a proxy. Gameplay takes about 24 minutes per PC, apart from timed lift builds; either hardware target waits if no matching PC is online.

  • Where: linux+amd (1-2 reports), windows+amd (1-2 reports).
  • Matrix: 1 cell, each on main and the PR: HOS_TEX_COMPACT_MS 0 (PR only).
  • market-default: from the repository's save kokiri-start (settings vsync=2, frame_rate_cap=6, frame_generation=0), then teleport to Market, measure market for 60 s (after 5 s warm-up), take the picture market-default to compare with main; 1 run on each side.
  • market-zero-gap: from the repository's save kokiri-start (settings vsync=2, frame_rate_cap=6, frame_generation=0), then teleport to Market, measure market for 60 s (after 5 s warm-up), take the picture market-zero-gap to compare with main; 1 run on each side.
  • Build times: main and the PR each built 2 times, alternating, each whole in a fresh folder: the lift again (no kept lift, main's compiled objects kept); every stage timed (shader preparation is not), and the lifted C compared.
  • Measured: crashes, frame times, stutters and hitches.
  • The PR fails if: it crashes; or a picture differs from main by more than 5%; or frame time (p99) is more than 15% above main.
  • Time: about 25 min of game runs per tester (4 game starts), plus the two builds and 4 timed builds (about 80 min).

Done (started 22:40 UTC). Run 2: re-planned by futondestroyer. Comment @Beanstalk to run it again.

This diff touches sensitive paths, so it needs two members of BigBeans: nx2/oot_patches.py

Target Reports Crash Frame p99 (ms) vs main VRAM peak (MB) vs main Result
linux+amd 0/1 — — — queued
windows+amd 0/1 — — — queued
<!-- beanstalk:sticky --> ### Beanstalk test farm Commit `54a4271` · tier **double-reviewed** · approved by GummiNaomi, futondestroyer · [dashboard](https://beanstalk.magicbean.dev/prs/1478) **What will be tested** · AI plan (`gpt-6.1-terra`) On Linux and Windows AMD, the farm builds both revisions and idles in the child Market for one minute per run, using the PR default and its zero-gap switch. Screenshots and p99 frame times are compared with main; crashes, substantial picture differences, or a p99 regression fail the plan. The farm cannot directly compare the two PR settings’ counts of frames over 16.7 ms or apply the requested setting-specific log checks, so p99 is a proxy. Gameplay takes about 24 minutes per PC, apart from timed lift builds; either hardware target waits if no matching PC is online. - **Where:** linux+amd (1-2 reports), windows+amd (1-2 reports). - **Matrix:** 1 cell, each on main and the PR: HOS_TEX_COMPACT_MS `0` (PR only). - **market-default:** from the repository's save `kokiri-start` (settings vsync=2, frame_rate_cap=6, frame_generation=0), then teleport to Market, measure market for 60 s (after 5 s warm-up), take the picture market-default to compare with main; 1 run on each side. - **market-zero-gap:** from the repository's save `kokiri-start` (settings vsync=2, frame_rate_cap=6, frame_generation=0), then teleport to Market, measure market for 60 s (after 5 s warm-up), take the picture market-zero-gap to compare with main; 1 run on each side. - **Build times:** main and the PR each built 2 times, alternating, each whole in a fresh folder: the lift again (no kept lift, main's compiled objects kept); every stage timed (shader preparation is not), and the lifted C compared. - **Measured:** crashes, frame times, stutters and hitches. - **The PR fails if:** it crashes; or a picture differs from main by more than 5%; or frame time (p99) is more than 15% above main. - **Time:** about 25 min of game runs per tester (4 game starts), plus the two builds and 4 timed builds (about 80 min). Done (started 22:40 UTC). Run 2: re-planned by futondestroyer. Comment `@Beanstalk` to run it again. This diff touches sensitive paths, so it needs two members of `BigBeans`: `nx2/oot_patches.py` | Target | Reports | Crash | Frame p99 (ms) vs main | VRAM peak (MB) vs main | Result | | --- | --- | --- | --- | --- | --- | | linux+amd | 0/1 | — | — | — | queued | | windows+amd | 0/1 | — | — | — | queued |
Member

@Beanstalk

@Beanstalk
Member

@Beanstalk linux and windows amd: stand in Castle Town's market for a minute (the debug teleport to Market_Child, no input), once with this PR's default and once with HOS_TEX_COMPACT_MS=0 (the game's own compaction request at every frame, as on main). Expecting: no crash; the same picture on both; with the default no more frames over 16.7 ms than with the switch at 0 (here, on a 9950X3D with an RTX 4070 SUPER on Windows: 1.0 and 1.5 % against 5.4 and 12.6 %); and in the log the line tex: the game's texture heap is compacted at most every 1000 ms with the default and no such line with the switch at 0. A build on Linux is the other thing this asks for: the checklist's Linux build box is still open.

@Beanstalk linux and windows amd: stand in Castle Town's market for a minute (the debug teleport to Market_Child, no input), once with this PR's default and once with HOS_TEX_COMPACT_MS=0 (the game's own compaction request at every frame, as on main). Expecting: no crash; the same picture on both; with the default no more frames over 16.7 ms than with the switch at 0 (here, on a 9950X3D with an RTX 4070 SUPER on Windows: 1.0 and 1.5 % against 5.4 and 12.6 %); and in the log the line tex: the game's texture heap is compacted at most every 1000 ms with the default and no such line with the switch at 0. A build on Linux is the other thing this asks for: the checklist's Linux build box is still open.
GummiNaomi changed title from WIP: perf(host): the game's texture heap is compacted at most once a second, not at every frame (HOS_TEX_COMPACT_MS) to perf(host): the game's texture heap is compacted at most once a second, not at every frame (HOS_TEX_COMPACT_MS) 2026-11-17 22:45:55 +00:00
HumanBean deleted branch perf/tex-compact-gap 2026-11-17 22:48:23 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 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!1478
No description provided.