perf(vk): hoist block-invariant ASTC decoder work

docs/astc-decoder.md

@@ -0,0 +1,65 @@
+# ASTC decoder invariants and regression checks
+
+The compute decoder calculates partition hash/scales and the weight-grid scale once
+per ASTC block, then reuses them for its pixels. Endpoint encoding uses a boundary
+search with the original tie rule. Descriptor bindings, push constants, workgroup
+size, tiling, HDR branches and the upload/BC conversion policy are unchanged.
+
+The optimization follows [Lichii's decoder change](https://github.com/zortos293/Lichii/commit/d590d51820f99447bd7056920e28eaeab510e4f1),
+including justr4mzi/SmileyTatsu's work. The existing Eden/yuzu GPL notices remain in
+the shader; the frozen test reference carries its own notices. This is relative
+output preservation, not a new independent ASTC conformance implementation.
+
+## Game-free checks
+
+`tests/test_astc_decoder.py` compiles the actual partition and endpoint logic
+against frozen pre-change GPL logic. It compares 3,935,232 partition positions and
+8,448 endpoint choices. This covers those domains, not every ASTC decoding mode.
+
+`tests/test_astc_decoder_gpu.py` compiles a standalone Vulkan fixture in the normal
+source suite. It **does not execute GPU work by default**. To opt in locally:
+
+```sh
+python -I -B tests/test_astc_decoder_gpu.py --cxx clang++ --headers /path/to/vulkan/include --run
+```
+
+On Windows, pass llvm-mingw's `clang++.exe`. `--device NVIDIA` selects a device by
+name; with no name, CPU devices are excluded. Explicit `--device llvmpipe` is a
+software Vulkan check, not a hardware result. A missing compatible device is a
+failure of an explicitly requested run, never a GPU pass.
+
+The fixture compares the shipped generated shader against the header at
+`51da0464b4cf0c7f56b81ebd6bb309325835e175`. Fetch that Git object first if absent,
+or supply its GPL header with `--baseline-header`; the pinned binary SHA-256 is
+checked. No automatic fetch, encoder download or game input is used. Authored
+blocks exercise 88 cases: 22 footprints/orientations, two input layouts, and full
+or clipped edges. Checks include a known-color valid void-extent block, exact
+RGBA8 equality and readback padding. `--candidate-spirv` supports intentional
+wrong-output controls. The fixture does not measure performance.
+
+Windows RTX 5070 Ti and Linux llvmpipe passed all 88 cases. Wrong-zero-store and
+wrong-partition-tie shader controls failed on actual NVIDIA pixel differences.
+Khronos validation was unavailable. Random blocks include invalid encodings;
+agreement with the baseline does not establish independent ASTC conformance.
+Separate authored valid-block comparisons against Arm's reference still differ
+identically on baseline and candidate; that pre-existing discrepancy is not fixed.
+
+## Native measurement scope
+
+[Recorded runs](tested-configurations.md) use source `51da0464` versus `3d7c7a22`,
+with identical private GPU timestamp instrumentation in both renderers and the
+same host, checkpoint, options and cache seed. The timestamp span covers the
+actual ASTC upload commands, including barriers, BC conversion and copies.
+Matching uses staging-input snapshot fingerprints, shape/format/BC flag and
+dispatch/byte counts; unmatched groups are excluded and retained in local evidence.
+
+Three AB/BA/AB pairs reduce matched upload GPU time by 2.44%, 3.29% and 3.66%
+(median 3.29%, 5.46-8.17 ms saved over approximately 223 ms of upload GPU work).
+The A/A control differs by 0.26%. Matched time covers 100% of baseline and at least
+99.9976% of candidate upload time. GPU clocks were dynamic. Eight processes exited
+normally with the source checkpoint unchanged; an additional uninstrumented
+baseline/candidate pair loaded and rendered early Kokiri normally.
+
+These are Windows/NVIDIA early-load measurements, not FPS, uninstrumented startup,
+CPU time, campaign, HDR conformance, Linux hardware, AMD or Intel results. The
+private profiler is not part of this patch. Other Tier 1 hardware remains to test.

docs/tested-configurations.md

@@ -33,6 +33,14 @@ otherwise.
 | 2026-11-12 | v2.1.0-rc.3-153-g15646d18-dirty (source f0a7c2bd): main 15646d18 with a temporary measuring patch (the mirrors' padding counted); `RX_VK_IMPORT_CHUNK_MB=4` against unset (16) | Windows 11, no window (unattended, scripted input) | RTX 4070 SUPER 12 GB, 617.42 | Ryzen 9 9950X3D (SMT off), 32 GB | 2560x1440, DLAA, `RX_VK_COMPACT=1`, `RX_VK_COMPACT_PCT=85`, `RX_VK_ASTC_BC_ALL=1`, `RX_VK_IMAGE_BLOCK_MB=32`; nothing else running, `RX_VK_TEST_ALLOWED_MB=10200` | Hyrule Field, a scripted five-minute walk; Castle Town to Hyrule Field (an area change) | Walk: mirrors 1,236-1,268 MB with 4 MB chunks against 1,645-1,657 MB with 16, 58.1 / 58.6 fps against 59.0 / 58.2, imports 91-94 (0.8 s in the driver) against 59-65 (0.7 s). Area change: VRAM mean 7,859 against 8,357 MB, 50.5 against 50.4 fps. No device lost |
 | 2026-11-11 | v2.1.0-rc.3-156-g50a6887e (source 44083c56): main 15646d18 + #2683 + this change; against v2.1.0-rc.3-154-g3c89158e (source 1eba3e78): main 15646d18 + #2683 | Windows 11, no window (unattended, scripted input) | RTX 4070 SUPER 12 GB, 617.42 | Ryzen 9 9950X3D (SMT off), 32 GB | 2560x1440, DLAA, `RX_VK_COMPACT=1`, `RX_VK_COMPACT_PCT=85`, `RX_VK_ASTC_BC_ALL=1`, `RX_VK_IMAGE_BLOCK_MB=32`; nothing else running, `RX_VK_TEST_ALLOWED_MB=10200` | From the title into Castle Town (the title-to-game load), then out to Hyrule Field | Two runs each. The frame at the title-to-game load (the movie's end) took 258 and 259 ms without the change; with it no frame in that stretch was over 60 ms. No device lost |
 | 2026-11-12 | v2.1.0-rc.3-260-gb7d175e4f (source 43edcbeb), stock fixed build before rebase, no local counters | Arch Linux, kernel 7.2.15-1-omarchy, headless | Intel UHD 770 (RPL-S), Mesa ANV 26.2.5-arch1.1 | Core i9-13900K, 93 GB reported by the game | 1920x1080, Minimum, FG off, precompile/warm/prediction off, 32 GiB process limit; warmed save/cache; Khronos validation 1.4.363 (`RX_VK_VALIDATION=1`), duplicate-message cap off | Kokiri Forest, child, standing; 60 s of confirmed play | VUID-vkCmdDrawIndirect-pStrides-04913: 0 (stock main 51da0464 control: 968 overall, 957 in its 60 s play window). No other errors or new message IDs; existing unused-fragment-output warnings remain. Exit 0, no device loss or GPU fault. Forest/HUD render with this iGPU's known false colours. No performance claim; full per-ID counts in PR #2796 |
+| 2026-11-12 | Source `51da0464`, matched host `51da0464`, identical private upload instrumentation; r1-AA-1 | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 222.197344 ms, 577 groups, 7433 dispatches, 454,269,440 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `51da0464`, matched host `51da0464`, identical private upload instrumentation; r1-AA-2 | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 222.769024 ms, 577 groups, 7433 dispatches, 454,269,440 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `51da0464`, matched host `51da0464`, identical private upload instrumentation; r1-AB-1-A | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 224.278816 ms, 576 groups, 7424 dispatches, 454,227,456 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `3d7c7a22`, matched host `51da0464`, identical private upload instrumentation; r1-AB-1-B | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 218.817408 ms, 576 groups, 7424 dispatches, 454,227,456 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `3d7c7a22`, matched host `51da0464`, identical private upload instrumentation; r1-BA-2-B | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 217.310432 ms, 576 groups, 7424 dispatches, 454,227,456 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `51da0464`, matched host `51da0464`, identical private upload instrumentation; r1-BA-2-A | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 224.696960 ms, 576 groups, 7424 dispatches, 454,227,456 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `51da0464`, matched host `51da0464`, identical private upload instrumentation; r1-AB-3-A | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 223.362880 ms, 575 groups, 7415 dispatches, 454,176,256 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
+| 2026-11-12 | Source `3d7c7a22`, matched host `51da0464`, identical private upload instrumentation; r1-AB-3-B | Windows 11 | RTX 5070 Ti, 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720 output/window, 16:9, 60 cap, FG off; same checkpoint/options/cache seed; private GPU timestamps | Kokiri Forest child checkpoint load, then 30 s stationary | Matched ASTC-upload GPU spans: 215.190240 ms, 575 groups, 7415 dispatches, 454,176,256 input bytes. Exit 0, checkpoint preserved. [Method and limits](astc-decoder.md#native-measurement-scope); no FPS/startup claim |
 | 2026-11-11 | v2.1.0-rc.3-246-g87991bc8 (source 6d41d308), main built from source (llvm-mingw, no DLSS) | Windows 11, 1280x720 window (mailbox, V-Sync Auto) | RTX 3080 10 GB, 621.14 | Core i9-12900K, 64 GB | Default options, uncapped (`HOS_FPS_MAX=1000`); a warm-up run first, no pipeline compiled while measuring | Hyrule Field (adult), by the Lost Woods bridge where the Cheats teleport puts Link, standing; 120 s from 45 s after the teleport | Two runs: 78.4 and 79.3 fps, median frame 12.18 and 12.23 ms, 30 and 37 frames over 20 ms, 1,335-1,453 draws. Readbacks of GPU results: about 1,550 of 3,000 waited, 0.04-0.07 ms each (medians). Against the nightly below for [#2602](https://github.com/NotRexed/Hookshot/pull/2602) |
 | 2026-11-11 | v2.1.0-rc.3-193-g55b976c0 (source ae9e7c1b), the last nightly before #2602, built from source as above | as above | as above | as above | as above | as above | Two runs, interleaved with the two above: 59.7 and 60.8 fps, median frame 16.39 and 16.32 ms, 264 and 22 frames over 20 ms, 1,355-1,445 draws. Readbacks of GPU results: 172 of 3,000 waited, 5.80 and 5.56 ms each (medians) |
 | 2026-11-12 UTC | main 51da0464 / PR2649 84a006d5, matching host and renderer | Windows 11, windowed | RTX 5070 Ti 16 GB, NVIDIA 621.01 | Ryzen 7 9800X3D, 32 GB | 1280x720, 60 fps cap, FG off, precompile/prediction off, RX_VK_PLAY_CACHE=0; identical 1,124,480,456-byte base plus one play file and warmed translator inputs restored before each process | Kokiri balcony checkpoint, 30 s after loaded state; eight fresh processes: A/A then AB, BA, AB | All exit 0; checkpoint and final cache hashes match. Paired peak private reductions 924.9 / 1,064.3 / 900.3 MiB, but A/A varied 979.9 MiB. Working-set peak deltas -8.7 / -59.9 / +74.3 MiB; no consistent steady-memory, physical-memory, FPS or startup benefit established |

docs/worklist.md

@@ -50,6 +50,7 @@ Agents may add and re-score rows; a person reviews the change like any other PR.
 | 0.22 | RTX 3070 with Frame generation on: uncaught C++ exception in hookshot_vk.dll on the first FSR 3 frame-generation inputs as gameplay starts (v2.0.13) | S0 | 0.07 | 0.4 | | #1786 (closed as a duplicate of #1697, but a different crash) |
 | 0.2 | Linux with an AMD card runs slower than Windows on the same PC, and loses performance over a session. Merged after v2.1.0: #2263, #2637 (short sleeps on the timer) | S2 | 0.17 upper bound | 0.4 |  | #1000; #bug-reporting "AMD GPU losing performance on linux", "Much better performance on Windows then on Linux" |
 | 0.2 | Intel GPU: black screen or crash after the intro or after loading a save (or on the Deku Tree), sound only, very low fps; six reports, three of them after v2.1.0 (Arc B580, Arc G3 Extreme, an Intel iGPU). Merged after v2.1.0: #2464, #2513, #2603; open: #2456, #2564, #2629 | S0 | 0.035 | 0.7 | | #999 (logs from 21 commenters); #bug-reporting "Blackscreen and crash after intro", "Crashes upon finishing the initial intro video.", "Entire world is broken", #bug-reporting "Intel G3E. Title and intro loads...", "intel arc b580 problems", "game gets stuck on a black screen when loading a save (intel gpu... gulp...)" |
+| 0.085 | ASTC decoder repeats block-invariant arithmetic per pixel; matched native GPU upload spans improve 2.44-3.66% on RTX 5070 Ti, not an FPS claim | S3 | 0.085 provisional measured RTX 50 reporter class; wider benefit unmeasured | 1.0 | Arkex-ai | [Claim](https://matrix.to/#/#agent-updates:magicbean.dev/$yskpnAFYYuMRnjcaBYB4Q4rZBYxUpf1lLgtiN2PD_tw); [measurement and regression](astc-decoder.md) |
 | 0.04 | FSR 4 ticked in the Builder after the game was built does not rebuild it (the Builder says up to date); FSR 4 DLLs added by hand get no AMD license prompt, as expected. Open: #2591 | S3 | 0.10 (RX 9000) | 0.4 |  | #2511; #bug-reporting "Not Getting AMD License Agreement Message" |
 | 0.04 | Linux: at the first start that moves `user/` into `~/.local/share/hookshot`, an absolute symlink listed after the entry it names keeps pointing at the old, deleted place, so a linked save is lost to the game; whether it happens depends on the filesystem's directory order (seen as `test_linux_saves_move` failing now and then in CI) | S0 | 0.005 (Linux and SteamOS 17% of reports, and only a `user/` holding an absolute symlink into itself) | 1.0 | nullifyshot | #2832 (fix, game-free test); #2317 overlaps |
 | 0.01 (provisional) | Pipeline cache persistence holds a complete temporary heap copy on top of the driver cache. Preserve the warm cache with file-backed storage; measured preparation memory, no crash/FPS fix claimed. Reach is an unmeasured 1% planning assumption for large-cache installations | S3 | 0.01 | 1.0 | Arkex-ai | #2623; [claim](https://discord.com/channels/1568810484818378804/1570103281856806962/1570255465806565520); native Windows/Linux file tests and Windows preparation/checkpoint reload |