perf(vk): a new ASTC texture's blocks are hashed at upload only when a finalized one has its shape #1281

Open
TrashPanda wants to merge 1 commit from TrashPanda/Longshot:perf/astc-hash-later into main
Contributor

Type: perf · Risk: medium · Tested on: Linux, RTX 4070 Ti · Needs: Windows build, AMD (RADV), Steam Deck

Why

When an area loads, more new textures than before show up a frame or more late. Since #1222, every new ASTC texture's
blocks are hashed on the replay thread at its upload, so a revisit can reuse an earlier decode. That hashing took about
0.55 s of the replay thread over a Kokiri tour, inside the 40 ms per-frame upload budget, so the budget runs out sooner
in a load and more textures wait for a later frame. Only some of those hashes can ever find a match. See #1069.

What changed

A new texture's blocks are hashed at its upload only when a finalized texture of the same shape is listed, since no
other can take an image there. The rest are hashed on a background thread, and the hash is kept only if the CPU did not
write the texture's storage between the upload and the hash. That way, when the game finalizes the texture it can still
be listed as a source for a later revisit.

  • gpu/vk/astc_reuse.h: Freed counts its entries by shape (has_shape, with list and unlist taking the shape),
    and hash_storage() hashes a storage in the same 64 MB pieces as the upload, so both places give the same hash.
  • gpu/vk/vk_texture.cpp, reuse_upload(): hashes now when freed.has_shape() is true. Otherwise it queues the
    storage (a live guest-window pointer, its size and the memory generation) for reuse_hash_queue()'s thread.
    Storage that is sparse, virtual, not contiguous or shadowed by the capture is hashed at upload, as before.
  • reuse_hash_frame(), called from texture_frame(): takes the hashes that came back. It keeps a hash only if
    texture_dirty() finds no writes since the upload's generation, and lists a texture the game finalized before its
    hash came (list_when_hashed). A texture that goes or is uploaded again in the meantime drops its job in
    reuse_drop() (the result is matched by a sequence number, never by a pointer alone).
  • docs/development.md: the RX_VK_ASTC_HASH_LATER switch.

Measurements

Verdict: helps, less than hoped. The replay thread hashes about 100 ms less per tour and about 23% fewer new textures
wait a frame, with no loss of reuse. Most of the remaining upload-time hashing is for textures that do find a match;
the decode it replaces runs on the GPU, so that cost stays.

Hardware: Ubuntu 26.04.1, kernel 7.0.0-43, RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D, 32 GB
Scene: Kakariko and the Market (child), four visits each; 2560x1440, defaults, RX_VK_VRAM_MB=8192
Method: the last vk: decoded ASTC used again and left for a later frame ... N so far lines and the slowest
vk: status frame in each run's longshot_log.txt. Three runs a side, interleaved, each alone on the PC through
scripts/job_queue.py timing mode; the median of the three.
How to reproduce: RX_VK_VRAM_MB=8192 python -I scripts/memtour.py <game> --repo-save kokiri-start --dests 2,3,2,3,2,3,2,3 --dwell 25 --settle 20, with and without --env RX_VK_ASTC_HASH_LATER=0
Baseline: the same build with RX_VK_ASTC_HASH_LATER=0, which hashes everything at upload as main does. It's an
in-session A/B on one build instead of two builds.

Before: this PR @ 824fa2c4, RX_VK_ASTC_HASH_LATER=0 After: this PR @ 824fa2c4
blocks hashed on the replay thread (ms) 554 (554 / 597 / 451) 452 (556 / 430 / 452)
blocks hashed on the replay thread (MB) 6,213 (6,213 / 6,754 / 5,658) 4,704 (5,104 / 4,704 / 4,518)
hashed on the background thread, kept / written meanwhile none 3,701 textures, 1,754 MB; all kept, 0 written
new ASTC textures left for a later frame 678 (784 / 673 / 678) 519 (691 / 494 / 519)
textures copied from finalized ones, not decoded 5,703 (5,703 / 7,685 / 5,602) 6,693 (7,581 / 6,693 / 6,627)
the slowest frame of the tour (ms) 555.0 (460.8 / 555.0 / 566.0) 550.2 (550.2 / 416.0 / 586.8)
VRAM used at its peak (MB) 8,233 (8,233 / 8,184 / 8,396) 8,101 (7,987 / 8,248 / 8,101)

An earlier A/B, before the fallback for storage that can't be hashed later, gave the same picture: 531 to 426 ms
hashed and 662 to 385 left for a later frame. Its reuse count was lower (6,657 to 5,814), which is why the fallback
was added.

The last such line of the second run with the change:

vk: decoded ASTC used again: 6693 textures (17036 MB) copied from ones the game finalized, not decoded; 6693 of those retired, 69 listed; 4704 MB of blocks hashed at upload in 430 ms; 3181 textures (1532 MB) hashed later, 3181 kept, 0 written meanwhile

Flags and settings

One new switch, on by default.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_ASTC_HASH_LATER hash only the textures that could match at upload, the rest on a background thread (none: all hashed at upload) 1 less replay-thread time in area loads, fewer textures a frame late helps on Linux, RTX 4070 Ti; untested elsewhere on for everyone; =0 only to compare

Testing

Tested: python -I -B tests/run_all.py on Linux: 652 passed, 21 failed, 21 skipped. The same 21 also fail on this
branch's base without the change: game-file caches, Linux preflight, DLSS and others not touched here. Six tours in
the game as above, with no crash, hang or visible texture problem.

Not tested: the Windows build (llvm-mingw); only std::thread and std::condition_variable are new to this code.
Other GPUs, and a Steam Deck, where the extra thread competes with the game for four cores.

Must be tested:

  • Windows, any GPU: build, then teleport between two areas a few times, expecting the vk: decoded ASTC used again
    line to show textures hashed later and kept (Test Farm: @Beanstalk windows, the ASTC hash line after a few area changes)
  • Steam Deck: the same tour, expecting no more slow frames than with RX_VK_ASTC_HASH_LATER=0 (Test Farm: @Beanstalk steamdeck)

Risks

What could break: a hash that no longer matches the decoded image, if a write to the storage got past the
generation check, would let a later revisit copy the wrong image. That would show as a wrong texture on a revisit.
texture_dirty() is the same check the texture cache uses to decide on re-uploads.

Turning it off: RX_VK_ASTC_HASH_LATER=0, or RX_VK_ASTC_REUSE=0 for no reuse at all.

Compatibility: nothing changes.

Issues

See #1069

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. Not ticked yet: Testing says the extra thread's CPU cost on the Steam Deck is not measured, and Risks does not name it.
  • 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.
**Type:** perf · **Risk:** medium · **Tested on:** Linux, RTX 4070 Ti · **Needs:** Windows build, AMD (RADV), Steam Deck ## Why When an area loads, more new textures than before show up a frame or more late. Since #1222, every new ASTC texture's blocks are hashed on the replay thread at its upload, so a revisit can reuse an earlier decode. That hashing took about 0.55 s of the replay thread over a Kokiri tour, inside the 40 ms per-frame upload budget, so the budget runs out sooner in a load and more textures wait for a later frame. Only some of those hashes can ever find a match. See #1069. ## What changed A new texture's blocks are hashed at its upload only when a finalized texture of the same shape is listed, since no other can take an image there. The rest are hashed on a background thread, and the hash is kept only if the CPU did not write the texture's storage between the upload and the hash. That way, when the game finalizes the texture it can still be listed as a source for a later revisit. - `gpu/vk/astc_reuse.h`: `Freed` counts its entries by shape (`has_shape`, with `list` and `unlist` taking the shape), and `hash_storage()` hashes a storage in the same 64 MB pieces as the upload, so both places give the same hash. - `gpu/vk/vk_texture.cpp`, `reuse_upload()`: hashes now when `freed.has_shape()` is true. Otherwise it queues the storage (a live guest-window pointer, its size and the memory generation) for `reuse_hash_queue()`'s thread. Storage that is sparse, virtual, not contiguous or shadowed by the capture is hashed at upload, as before. - `reuse_hash_frame()`, called from `texture_frame()`: takes the hashes that came back. It keeps a hash only if `texture_dirty()` finds no writes since the upload's generation, and lists a texture the game finalized before its hash came (`list_when_hashed`). A texture that goes or is uploaded again in the meantime drops its job in `reuse_drop()` (the result is matched by a sequence number, never by a pointer alone). - `docs/development.md`: the `RX_VK_ASTC_HASH_LATER` switch. ## Measurements **Verdict:** helps, less than hoped. The replay thread hashes about 100 ms less per tour and about 23% fewer new textures wait a frame, with no loss of reuse. Most of the remaining upload-time hashing is for textures that do find a match; the decode it replaces runs on the GPU, so that cost stays. Hardware: Ubuntu 26.04.1, kernel 7.0.0-43, RTX 4070 Ti 12 GB, NVIDIA 595.99.02, Ryzen 7 9800X3D, 32 GB Scene: Kakariko and the Market (child), four visits each; 2560x1440, defaults, `RX_VK_VRAM_MB=8192` Method: the last `vk: decoded ASTC used again` and `left for a later frame ... N so far` lines and the slowest `vk: status` frame in each run's `longshot_log.txt`. Three runs a side, interleaved, each alone on the PC through `scripts/job_queue.py` timing mode; the median of the three. How to reproduce: `RX_VK_VRAM_MB=8192 python -I scripts/memtour.py <game> --repo-save kokiri-start --dests 2,3,2,3,2,3,2,3 --dwell 25 --settle 20`, with and without `--env RX_VK_ASTC_HASH_LATER=0` Baseline: the same build with `RX_VK_ASTC_HASH_LATER=0`, which hashes everything at upload as main does. It's an in-session A/B on one build instead of two builds. | | Before: this PR @ 824fa2c4, `RX_VK_ASTC_HASH_LATER=0` | After: this PR @ 824fa2c4 | |---|---|---| | blocks hashed on the replay thread (ms) | 554 (554 / 597 / 451) | 452 (556 / 430 / 452) | | blocks hashed on the replay thread (MB) | 6,213 (6,213 / 6,754 / 5,658) | 4,704 (5,104 / 4,704 / 4,518) | | hashed on the background thread, kept / written meanwhile | none | 3,701 textures, 1,754 MB; all kept, 0 written | | new ASTC textures left for a later frame | 678 (784 / 673 / 678) | 519 (691 / 494 / 519) | | textures copied from finalized ones, not decoded | 5,703 (5,703 / 7,685 / 5,602) | 6,693 (7,581 / 6,693 / 6,627) | | the slowest frame of the tour (ms) | 555.0 (460.8 / 555.0 / 566.0) | 550.2 (550.2 / 416.0 / 586.8) | | VRAM used at its peak (MB) | 8,233 (8,233 / 8,184 / 8,396) | 8,101 (7,987 / 8,248 / 8,101) | An earlier A/B, before the fallback for storage that can't be hashed later, gave the same picture: 531 to 426 ms hashed and 662 to 385 left for a later frame. Its reuse count was lower (6,657 to 5,814), which is why the fallback was added. The last such line of the second run with the change: ``` vk: decoded ASTC used again: 6693 textures (17036 MB) copied from ones the game finalized, not decoded; 6693 of those retired, 69 listed; 4704 MB of blocks hashed at upload in 430 ms; 3181 textures (1532 MB) hashed later, 3181 kept, 0 written meanwhile ``` ### Flags and settings One new switch, on by default. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_ASTC_HASH_LATER` | hash only the textures that could match at upload, the rest on a background thread | (none: all hashed at upload) | 1 | less replay-thread time in area loads, fewer textures a frame late | helps on Linux, RTX 4070 Ti; untested elsewhere | on for everyone; `=0` only to compare | ## Testing **Tested:** `python -I -B tests/run_all.py` on Linux: 652 passed, 21 failed, 21 skipped. The same 21 also fail on this branch's base without the change: game-file caches, Linux preflight, DLSS and others not touched here. Six tours in the game as above, with no crash, hang or visible texture problem. **Not tested:** the Windows build (llvm-mingw); only `std::thread` and `std::condition_variable` are new to this code. Other GPUs, and a Steam Deck, where the extra thread competes with the game for four cores. **Must be tested:** - Windows, any GPU: build, then teleport between two areas a few times, expecting the `vk: decoded ASTC used again` line to show textures hashed later and kept (Test Farm: @Beanstalk windows, the ASTC hash line after a few area changes) - Steam Deck: the same tour, expecting no more slow frames than with `RX_VK_ASTC_HASH_LATER=0` (Test Farm: @Beanstalk steamdeck) ## Risks **What could break:** a hash that no longer matches the decoded image, if a write to the storage got past the generation check, would let a later revisit copy the wrong image. That would show as a wrong texture on a revisit. `texture_dirty()` is the same check the texture cache uses to decide on re-uploads. **Turning it off:** `RX_VK_ASTC_HASH_LATER=0`, or `RX_VK_ASTC_REUSE=0` for no reuse at all. **Compatibility:** nothing changes. ## Issues See #1069 ## 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. - [ ] Nothing gets worse that I know of: any cost (speed, latency, memory, a setup that worked before) is measured and in Risks. Not ticked yet: Testing says the extra thread's CPU cost on the Steam Deck is not measured, and Risks does not name it. - [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.
perf(vk): a new ASTC texture's blocks are hashed at upload only when a finalized one has its shape
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
PR description / Description follows the template (pull_request_target) Failing after 8s
824fa2c4bd
Hashing every new ASTC texture's blocks at its upload took ~0.55 s of the
replay thread over a Kokiri tour, inside the 40 ms upload budget, so more
new textures waited a frame. Only a texture of a shape a finalized one has
can take an image at its upload, so only those are hashed there now; the
rest are hashed on a thread of their own, and the hash is kept at a
texture_frame if the CPU did not write the storage since the upload. One
finalized before its hash came is listed when it comes; one whose storage
is not plain live guest memory is hashed at upload, as before.
RX_VK_ASTC_HASH_LATER=0: all hashed at upload, as before.

Three tours a side on an RTX 4070 Ti (medians): hashed at upload 554 ->
452 ms, new textures left for a later frame 678 -> 519, textures copied
instead of decoded 5703 -> 6693 (within the runs' spread).

See #1069

Assisted-by: Claude
Author
Contributor

Tested in game: Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02: six Kokiri tours (Kakariko and the Market, child, four visits each), three with RX_VK_ASTC_HASH_LATER=0 and three without, interleaved. No crash or wrong texture; replay-thread hashing 554 -> 452 ms, new textures left for a later frame 678 -> 519 (medians), reuse unchanged.

Tested in game: Linux (Ubuntu 26.04.1), RTX 4070 Ti, NVIDIA 595.99.02: six Kokiri tours (Kakariko and the Market, child, four visits each), three with RX_VK_ASTC_HASH_LATER=0 and three without, interleaved. No crash or wrong texture; replay-thread hashing 554 -> 452 ms, new textures left for a later frame 678 -> 519 (medians), reuse unchanged.
Author
Contributor

@Beanstalk windows and steamdeck: build this PR, then from the repository save kokiri-start teleport Kakariko, the Market, Kakariko, the Market (scripts/memtour.py --repo-save kokiri-start --dests 2,3,2,3,2,3,2,3). Expect the last 'vk: decoded ASTC used again' line in longshot_log.txt to show textures hashed later and kept with few or none written meanwhile, no wrong textures on the revisits, and on the Deck no more slow frames than the same tour with RX_VK_ASTC_HASH_LATER=0.

@Beanstalk windows and steamdeck: build this PR, then from the repository save kokiri-start teleport Kakariko, the Market, Kakariko, the Market (scripts/memtour.py --repo-save kokiri-start --dests 2,3,2,3,2,3,2,3). Expect the last 'vk: decoded ASTC used again' line in longshot_log.txt to show textures hashed later and kept with few or none written meanwhile, no wrong textures on the revisits, and on the Deck no more slow frames than the same tour with RX_VK_ASTC_HASH_LATER=0.
Member

@TrashPanda only members of BigBeans can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.

@TrashPanda only members of `BigBeans` can start the farm. One of them can approve this request by reacting 👍 to it or to this comment.
TrashPanda left a comment

A new texture is hashed on the replay thread only when a finalized one of its shape is already listed. The rest are hashed later, and the hash is kept only when nothing wrote the storage after the upload. I read head 824fa2c4. It applies onto current main. This account opened the pull request, so this is not an approval.

The later job keeps the guest pointer, the size and the memory generation. texture_frame takes the result only when that job is still the texture's, then drops it if texture_dirty saw a write. A texture that goes, or is uploaded again, drops the job before the result is applied. Sparse, virtual and captured storage is still hashed at the upload. The same 64 MB pieces are hashed in both places. RX_VK_ASTC_HASH_LATER=0 is the old path.

The two runs in Must be tested are still open. Windows, any GPU: a few area changes, and the vk: decoded ASTC used again line showing textures hashed later and kept. A Steam Deck: the same tour no slower than RX_VK_ASTC_HASH_LATER=0. Only a BigBean can start those.

A new texture is hashed on the replay thread only when a finalized one of its shape is already listed. The rest are hashed later, and the hash is kept only when nothing wrote the storage after the upload. I read head `824fa2c4`. It applies onto current main. This account opened the pull request, so this is not an approval. The later job keeps the guest pointer, the size and the memory generation. `texture_frame` takes the result only when that job is still the texture's, then drops it if `texture_dirty` saw a write. A texture that goes, or is uploaded again, drops the job before the result is applied. Sparse, virtual and captured storage is still hashed at the upload. The same 64 MB pieces are hashed in both places. `RX_VK_ASTC_HASH_LATER=0` is the old path. The two runs in Must be tested are still open. Windows, any GPU: a few area changes, and the `vk: decoded ASTC used again` line showing textures hashed later and kept. A Steam Deck: the same tour no slower than `RX_VK_ASTC_HASH_LATER=0`. Only a BigBean can start those.
Owner

Brought up to the ready-for-review standard (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know).

  • Tested on my own PC: ticked: Testing's Tested and the author's comments: six Kokiri tours in the game on Linux, RTX 4070 Ti, this change.
  • Nothing gets worse that I know of: not ticked: Testing says the extra thread's CPU cost on the Steam Deck is not measured, and Risks does not name it. Measure that cost and state it in Risks, then tick it.
Brought up to the [ready-for-review standard](https://git.magicbean.dev/MagicBeanDev/Longshot/src/branch/main/CONTRIBUTING.md#ready-for-review-out-of-wip) (#1454): the checklist's Everyone list has two new boxes, added here from what this PR's description and comments show (please check they match what you know). - *Tested on my own PC*: ticked: Testing's Tested and the author's comments: six Kokiri tours in the game on Linux, RTX 4070 Ti, this change. - *Nothing gets worse that I know of*: not ticked: Testing says the extra thread's CPU cost on the Steam Deck is not measured, and Risks does not name it. Measure that cost and state it in Risks, then tick it.
Some checks failed
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request_target) Has been skipped
beanstalk/approval waiting for a BigBean's 👍 on the request
PR description / Description follows the template (pull_request_target) Failing after 8s
This pull request has changes conflicting with the target branch.
  • docs/development.md
  • gpu/vk/vk_texture.cpp
  • tests/test_astc_reuse.py
Some workflows are waiting to be reviewed.
View command line instructions

Manual merge helper

Use this merge commit message when completing the merge manually.

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/astc-hash-later:TrashPanda-perf/astc-hash-later'
git switch 'TrashPanda-perf/astc-hash-later'
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!1281
No description provided.