perf(agc): avoid redundant texture-array CPU transfers - #6718

What

Scoped texture-array refresh can still perform unnecessary CPU transfers after #6202: its CPU fallback uploads the whole image, and a failed whole-descriptor write collection can erase valid history for an active committed slice.

This PR addresses that resource path in separately reviewable implementation commits:

• For uncompressed, single-mip, non-thick 2D arrays with selections covering complete physical layers, read/snapshot, copy, detile and upload only selected layers. Refresh and upload use one eligibility check. Unselected image contents and pending GPU results remain intact. Unsupported layouts and partial physical-layer selections keep the whole-image fallback. Staging/device allocations remain full-sized.

• If unused slices include uncommitted memory, preserve generations obtained from successful collections of committed tracked units. Collect the selected scope before examining write stamps and report range-specific generations. Unknown units remain unknown; actual CPU writes still invalidate the affected content. Apply the collection fallback after uploads, clears, copies and write-back settlement.

• Expire collection memo hits when the allocation-registry generation changes, in the epoch map, per-thread ring and shared ring. A proof from an earlier mapping at the same address must not hide genuine CPU writes or give an unregistered slice complete history. The direct CPU-write regression covers all three caches and an uncached control.

No title checks, skipped passes, fabricated success, public API changes or shader-semantic changes. W/keyboard configuration is local and excluded.

Dependencies: #6202. #6367 is merged upstream; its duplicate integration commit has been dropped while its regression remains available from main. The first commit integrates #6202 with attribution, retaining its overlapping-array regression. #6202 is MiguelAdolfsen's revision 60229fae6469. Our incremental review range is a8360de91...stk-resource-performance-pr, limited to texture handling, its private header, test registration and the array regression. Dependency commits can be dropped as upstream merges them.

Upstream overlap rechecked before publication. #6202 supplies scoped refresh but its CPU fallback still uploads the whole array. Related #6273/#6346 optimize write-tracker proofs, #6678 defers import settling, and #6701 changes Windows stamp allocation; those mechanisms are separate. #1191 residency, #6197 import-window changes and the separate write-watch restoration experiment are excluded from this source branch.

Tested

Latest conflict-resolution validation — 2026-10-20. Rebased onto upstream main 43cd8f4c47f4c81185c4ca14b84240e0748e3459. Current head: c778381786adc976f53e7761551751eb0fbae955. Resolved the new conflict with merged #6772: cachedStorageTexture retains main's ArrayLayerWindow transformation and resets precomputed guest size when the window changes the base, while accepting the optional scoped layer-refresh range. The attributed #6202 integration is now a8360de91; all remaining implementation and regression commits are patch-equivalent to the previous head. Original authorship is retained.

Fresh Release focused targets rebuilt on Windows 11 build 26200, Intel Core i7-13700, NVIDIA GeForce RTX 4070 / driver 610.88, GCC 15.2, SPIR-V Tools enabled. Main: 10/10 pass, zero skips, 15.41 s; its array fixture also passes 1/1 in 1.77 s with APS5_NO_HOST_IMPORT=1 to match the added CPU-only array configuration. PR: 15/15 pass, zero skips, 23.01 s. Both use ANYPS5_REQUIRE_VULKAN=1, ANYPS5_NO_SHADER_CACHE=1, VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation and the same GPU. Logs confirm the Khronos 1.4.304 layer actually loads, with no missing-layer diagnostics. Comparing the shared tests and the matched no-import configuration finds no new VUID error signatures: main's ordinary suite plus its no-import control produce the same two unknown-extension-structure device-create errors as the candidate (VUID-VkDeviceCreateInfo-pNext-pNext, structure 1000574000 unknown to this older layer). Zero total validation errors is not claimed.

Upstream Windows test-build limitation: unmodified main's newly merged agc_driver_image_array_window_past_layer_limit_tests does not compile with the supported Windows GCC: ImageArrayWindowPastLayerLimit.cpp:33: requested alignment '65536' exceeds object file maximum 8192. The focused passing suites exclude that dedicated GPU test; the shared graphics binary does run RunTextureTilingTests, including main's array-window layout checks. No unrelated fixture change is included in this rebase. Full-suite Windows success is not claimed.

Conventions against canonical upstream/main and diff checks pass; the stale fork origin/main checker still hits Windows command-line length limits. No fresh gameplay/performance measurement, raw evidence upload, or Linux/vendor retest is claimed.

Earlier rebase validation — 2026-10-20 (main 661f8b717, historical). Rebased onto upstream main 661f8b717. Current head: 6ef3a78d872bd2057bd61c564db2b79c79e3d270; original authorship is retained. The #6202 integration now preserves main's per-layer GuestLayerOffset/color-view pitch checks and the newer BuildLookups lifetime management. Scoped layer refresh and all allocation-generation regression assertions are retained. The attributed #6202 integration is ad7bd6020; no unrelated integration code was added.

Windows 11 build 26200, Intel Core i7-13700, NVIDIA GeForce RTX 4070 / driver 610.88, GCC 15.2 / Release / SPIR-V Tools. Fresh focused targets rebuilt for main and this head. Main: 10/10 pass, zero skips, 11.98 s. PR: 15/15 pass, zero skips, 13.95 s, including both array-layer modes and all four allocation-history cache/control tests. Both use ANYPS5_REQUIRE_VULKAN=1, ANYPS5_NO_SHADER_CACHE=1, VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation and the same GPU. Loader logs confirm the Khronos 1.4.304 layer actually loads; neither log reports a missing requested layer. No new VUID errors compared with main. Both include the same VUID-VkDeviceCreateInfo-pNext-pNext for an extension structure unknown to that older validation layer; zero total VUIDs is not claimed.

The final runs load rebuilt unpatched libraries, with older DLL copies beside the test executables moved aside. Conventions against canonical upstream/main and diff checks pass. The required origin/main check was attempted but its stale fork baseline hits Windows command-line length limits; the canonical target baseline succeeds. No fresh gameplay/performance measurement, raw-trace upload or Linux/vendor retest is claimed. Earlier performance numbers remain historical evidence for their explicitly named revisions.

Previous rebase validation — 2026-10-19 (historical). Rebased onto upstream main 6b8228b2bfecb895010e379362c6d0bb288c2d47. Current head: 1505305e1722698d90ae9340d223852baf05773b. Original authorship is retained.

The duplicate #6367 commit is dropped because #6367 is merged upstream. #6202 remains an attributed dependency; its rebased integration commit is ad67b6455. The test-registration conflict keeps all current upstream abi_deferred_*, lazy and lazy_sync modes and our host-import-disabled array test. Collection-cache regression assertions remain intact.

• Windows RTX 4070: 25/25 focused tests pass, zero skips, 26.65 s summed test time; longest 11.57 s.
• Ubuntu/WSL2 lavapipe: 24/24 focused tests pass, zero skips, 14.00 s summed test time; longest 6.20 s.
• Release / GCC 15.2 / SPIR-V Tools; current bundled dependency gitlinks. Every individual test stays within 30 seconds. Conventions against canonical upstream and diff checks pass. WSL/lavapipe is software-Vulkan coverage, not a native Linux vendor-driver retest.
• These are fresh source-correctness results, not new gameplay or performance measurements. Earlier game measurements and independent hardware reports below apply to their explicitly named pre-rebase revisions. No game/runtime snapshot, evidence bundle or PR status is changed by this rebase.

Earlier validation and investigation (historical revisions):

Rebased using blawesom's handoff, preserving the original seven commits and authorship, onto upstream 8f0e276c61086c5192077018910e5dbc04c3a96b. Previous review-repair head: 619e4c9c6e281df0a68ce5cd42a364df6de9bf10. The extra commits add a failing collection-history regression, its mapping-generation repair, and an uncached-backend precondition for the existing array fixture. Existing lazy/lazy_sync test modes and dependency regressions are retained.

Review failure reproduced and repaired on Linux. Ubuntu 26.04.1 under WSL 2, kernel 6.18.54.1-microsoft-standard-WSL2, GCC 15.2.0, CMake 4.2.3, Release, SPIR-V Tools enabled, bundled dependency revisions. Vulkan: Mesa 26.0.8 lavapipe/llvmpipe, LLVM 21.1.8 (software driver). The production write-watch availability probe passes; none of the tests below skipped.

Matched reproduction, before a26b8d887 and repaired d6f654b92, both on upstream 084bd39a0:

The memo cache matched the ordering epoch and unwatch serial but not the allocation registry generation. Mapping replacement in the same epoch could therefore reuse stale write history. The repair requires the registry generation to match in every memo mode. The original array assertion is retained, with an added uncached collection check; no assertion was weakened.

Final-rebase validation at 619e4c9c6:

• Linux/lavapipe: 24/24 pass, no skips, 14.36 s total, longest test 5.59 s.
• Windows RTX 4070: 25/25 pass, 22.79 s total, longest test 7.44 s.
• All tests use a 30-second timeout. The Windows-only CPU-snapshot test is not registered on Linux.
• Conventions against canonical upstream main and diff checks pass.

These are correctness results, not new game-performance measurements. The Linux AMD reviewer machine has not been retested here; WSL/lavapipe does not qualify native AMD/NVIDIA driver behavior. #6820's separate native Linux NVIDIA report is outside this update. No shader/residency changes, local input configuration or evidence bundle are included.

Independent Windows AMD validation — LeandroLP23, 2026-10-18. The reviewer tested PR head 619e4c9c6 merged cleanly onto main 6efb7261b: Radeon 860M (RDNA 3.5 APU, driver 32.0.13058.8001), Ryzen AI 7 350, Windows 11 26300, WinLibs GCC 15.2.0, Release. Both agc_driver_array_layer_target and agc_driver_array_layer_target_cpu passed all three runs; the 14 tests selected by agc_recorder|agc_collect|write_watch|write_history|shared_write|array_layer also passed.

Their SuperTuxKart PPSA69421 00.001.000 performance check measured the menu with no input, 60 seconds per run, using tools/title_run.py and presents per second over the whole run. The first run of each build started with an empty AnyPS5 shader cache; both builds ran consecutively on mains power.

Scene distinction: the reviewer measured the menu; our historical performance measurements below used the Abyss race scene at the starting grid, with Tux, easy difficulty and four karts. The reviewer found no menu FPS improvement and did not measure racing performance. Their results add independent Windows AMD correctness coverage; they neither confirm nor contradict our race-scene measurements, and do not establish whether the menu exercises the selected-layer transfers this PR removes. The hardware, builds and capture windows also differ, so these FPS values must not be compared directly.

Related overlap: #6169 changes which completed tracker generation a concurrent memo hit returns; this repair adds allocation-generation eligibility. The conditions are distinct, and reconciliation must retain both if both changes land. #6759 remains separate.

Historical publication validation: upstream 5d9dcc42d2ec5401aebd089028b8d4d7410a77b4, PR head 3fc42c0a221ee93b93acfb7cecb64840c80a3972. Complete Release libs and focused test targets rebuilt with GCC 15.2, -O3 -DNDEBUG, BUILD_TESTING=ON, SPIR-V Tools enabled. Windows 10.0.26200, Intel Core i7-13700, 32 GiB RAM, NVIDIA RTX 4070 12 GiB, driver 591.86. Complete runtime snapshots record source/dependency revisions, flags and SHA-256 hashes.

At publication: 16/16 focused tests pass in 20.02 seconds, each under 30 seconds. Conventions and diff checks pass. These tests cover array layers with host imports enabled/disabled, retained units, upload lifetime/failure, split write-back, host-import retirement, CPU snapshots, graphics, depth clears/storage/reuse, one-slice aliasing, write-back overhang and write-watch coverage. Linux/lavapipe was untested at publication; the new Linux results are recorded above. Native AMD/Intel hardware remains untested locally.

Pre-fix evidence from the preserved regression runs (included with logs):

CPU fallback: a draw into slice 0 of the first array stored the next target's results,
which only its unused second slice overlaps
Write history: an uncommitted unused slice erased the active slice's write history

The array tests check first/last active slices, untouched neighboring GPU results, subsequent alias reads, genuine CPU writes, repeated unchanged refreshes, pending-result retention and image version. #6367's separate unregistered-unused-slice and retirement cases remain present. Existing graphics/resource tests exercise broader layouts; targeted exhaustive coverage of every unsupported-layout combination is not claimed.

Gameplay measurements below are historical equivalent integration builds, not measurements of the rebased head or bare current main. They compare both our resource changes together. Baseline ebc89db25587 and candidate 791d12671372 hold #6367, #6202's original 3a39b6cfd implementation, and Scott Schuster/TheAggie's rendering experiment 45944fbbe0dc constant. The updated #6202 revision adapts the newer upstream API; current-head game measurements must be repeated before readiness. No dependency or shader improvement is credited to this PR.

SuperTuxKart PPSA69421: Abyss starting grid, Tux, easy, four karts, 1920x1080, identical settings/configuration, same machine/session. Three alternating baseline/candidate pairs, warmed caches and separate restarts, 60-second lead-in, 120-second window, no input, inherited game logs. Only APS5_TRACE_SECONDS=60:120 enabled for acceptance captures.

The candidate remains around 8 FPS; it is not smooth gameplay. Baseline variability remains unexplained. A repeatable 20% gain is not established: pair 1 improves only 5.60%. The larger pairwise gains must not be presented alone as representative.

All six frame windows and runtime hashes were verified. Long detailed event timelines overflowed; independently recorded frame timestamps/percentiles and phase totals remained complete. trace_dropped is retained in the summary lines. Complete separate 10-second diagnostics attribute the mechanism: adding the history fix to the selected-layer runtime reduces upload waits from 5 to 2/frame and refresh write-back waits from 3 to 0/frame; median 160.132 to 138.795 ms. Measured GPU batches including synchronous work fall from 45.884 to 37.730 ms/frame. Recorded-only summary GPU numbers omit synchronous fallback batches; nested/concurrent CPU/GPU costs must not be added.

The preserved candidate integration completed 900.578 seconds of automatic driving across multiple laps, with sampled scenery correct and no matched fatal/assertion/device-loss signatures. A clean finite race finish is not a pass: baseline and candidate both exit 0xc0000409; baseline debugging reached LibcException::DefaultTerminate() / abort(), with the underlying exception unresolved. vkQuake produced no frames in either 40-second startup check, so cross-title rendering is inconclusive. Controls/audio were previously user-confirmed on the integration; fresh confirmation on this rebased head is pending.

The rendering experiment is absent from the PR source. It has a known flat-interpolation semantic-test failure in game integrations; the publishable source graphics test passes, and no semantic guard was weakened. The 15-minute integration check does not validate that separate shader experiment's semantics.

Evidence: the six original acceptance summary lines are included below. Full trace files, trace-digest reports and SHA-256 digests, runtime manifests, pre-fix failure logs and fresh correctness results are packaged locally in an 18.37 MiB review bundle; the bundle is retained locally and has not been uploaded, at the author's request. No game assets or binaries are included. Full trace evidence is not publicly attached.

{"commit":"ebc89db25587","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":338,"ms":120006.155},"presents":901,"frame_ms":{"p50":136.931,"p90":160.672,"p99":166.014,"max":203.87},"gpu_busy_ms_per_present":10.172,"worker_busy_pct":{"queue worker 0x0":15.862},"top_phases_ms_per_frame":{"Driver.EndSubmission":10.875,"Driver.Packet":10.245,"Driver.Packet.draw":8.345,"Driver.Draw":8.288,"Driver.Draw.draw_enqueued":5.677,"Driver.Draw.shader_compile_and_link":2.082,"Shader.DrawStage":1.231,"Shader.DrawStage.capture_resources":0.736},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":72.903,"events_lost":149219,"totals_full":false}},"trace":"aps5-trace-ebc89db25587-39984.json.gz"}
{"commit":"791d12671372","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":392,"ms":120077.139},"presents":952,"frame_ms":{"p50":123.868,"p90":136.366,"p99":142.151,"max":153.52},"gpu_busy_ms_per_present":11.698,"worker_busy_pct":{"queue worker 0x0":10.584},"top_phases_ms_per_frame":{"Driver.Packet":12.569,"Driver.Packet.draw":8.278,"Driver.Draw":8.223,"Driver.Draw.draw_enqueued":5.476,"Driver.Draw.shader_compile_and_link":2.223,"Shader.DrawStage":1.399,"Shader.DrawStage.capture_resources":0.796,"Driver.EndSubmission":0.775},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":64.349,"events_lost":200185,"totals_full":false}},"trace":"aps5-trace-791d12671372-55468.json.gz"}
{"commit":"ebc89db25587","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":267,"ms":120050.913},"presents":623,"frame_ms":{"p50":188.031,"p90":198.624,"p99":295.121,"max":299.775},"gpu_busy_ms_per_present":9.824,"worker_busy_pct":{"queue worker 0x0":21.551},"top_phases_ms_per_frame":{"Driver.EndSubmission":29.752,"Driver.Packet":11.769,"Driver.Packet.draw":8.613,"Driver.Draw":8.557,"Driver.Draw.draw_enqueued":5.662,"Driver.Draw.shader_compile_and_link":2.366,"GpuMutex.wait.flush":1.585,"Shader.DrawStage":1.529},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":93.655,"events_lost":56162,"totals_full":false}},"trace":"aps5-trace-ebc89db25587-33172.json.gz"}
{"commit":"791d12671372","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":361,"ms":120051.935},"presents":972,"frame_ms":{"p50":118.283,"p90":140.11,"p99":144.278,"max":148.017},"gpu_busy_ms_per_present":11.672,"worker_busy_pct":{"queue worker 0x0":8.674},"top_phases_ms_per_frame":{"Driver.Packet":10.019,"Driver.Packet.draw":8.225,"Driver.Draw":8.172,"Driver.Draw.draw_enqueued":5.708,"Driver.Draw.shader_compile_and_link":1.97,"Shader.DrawStage":1.19,"Shader.DrawStage.capture_resources":0.72,"Driver.EndSubmission":0.688},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":68.984,"events_lost":183536,"totals_full":false}},"trace":"aps5-trace-791d12671372-51232.json.gz"}
{"commit":"ebc89db25587","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":252,"ms":120078.225},"presents":583,"frame_ms":{"p50":199.604,"p90":215.177,"p99":307.007,"max":314.4},"gpu_busy_ms_per_present":10.816,"worker_busy_pct":{"queue worker 0x0":19.529},"top_phases_ms_per_frame":{"Driver.EndSubmission":27.794,"Driver.Packet":12.423,"Driver.Packet.draw":9.623,"Driver.Draw":9.558,"Driver.Draw.draw_enqueued":6.488,"Driver.Draw.shader_compile_and_link":2.469,"GpuMutex.wait.flush":2.018,"Shader.DrawStage":1.54},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":93.336,"events_lost":69182,"totals_full":false}},"trace":"aps5-trace-ebc89db25587-49216.json.gz"}
{"commit":"791d12671372","dirty":false,"env":{"APS5_PAD_INPUT_FILE":"<path>","APS5_TRACE_SECONDS":"60:120"},"gpu":"NVIDIA GeForce RTX 4070","driver":"NVIDIA 591.86","os":"Windows 10.0.26200","resolution":"1920x1080","window":{"spec":"seconds 60:120","first_present":352,"ms":120085.693},"presents":954,"frame_ms":{"p50":120.602,"p90":144.078,"p99":148.899,"max":152.774},"gpu_busy_ms_per_present":11.716,"worker_busy_pct":{"queue worker 0x0":12.609},"top_phases_ms_per_frame":{"Driver.Packet":10.967,"Driver.Packet.draw":8.099,"Driver.Draw":8.046,"Driver.Draw.draw_enqueued":5.38,"Driver.EndSubmission":4.898,"Driver.Draw.shader_compile_and_link":2.154,"Shader.DrawStage":1.345,"Shader.DrawStage.capture_resources":0.771},"trace_dropped":true,"trace_dropped_threads":{"queue worker 0x0":{"events_full_after_s":65.201,"events_lost":180884,"totals_full":false}},"trace":"aps5-trace-791d12671372-52320.json.gz"}

Checklist

• Based on current main; no other open PR implements the same functions
• One topic per PR; follow-ups go in a new PR
• No comments in code except technical debt
• Unimplemented paths throw (NotImplemented_nid_no_patch); silent stubs are listed under Silent stubs in their library's technical debt file
• No notes, investigation .md files or images added to the repository (attach them to this PR)
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: perf(agc): refresh only the layers a use of an array color target covers #6202
• Fixes: none
• Unblocks: none claimed; SuperTuxKart PPSA69421 is the regression workload
• GPUs tested: NVIDIA GeForce RTX 4070, driver 610.88, Windows 11 build 26200 (latest rebase); earlier validation: NVIDIA RTX 4070, driver 591.86, Windows 11 10.0.26200; Mesa 26.0.8 lavapipe/llvmpipe (LLVM 21.1.8), Ubuntu 26.04.1/WSL 2; independent reviewer: AMD Radeon 860M, driver 32.0.13058.8001, Windows 11 26300; native Linux hardware retest pending
• AI-assisted: yes, OpenAI Codex

Remaining validation: dependency reconciliation, fresh current-head gameplay comparisons, cross-title validation and investigation of the finite-race exit failure. Marked ready for review at the author's request; these gaps remain unresolved. No black-rendering, 30-FPS or repeatable-20%-gain claim.

Separate follow-up: partial-page write-watch restoration

A standalone correctness follow-up is published: restore write-watch coverage for remapped pages. It restores CPU-write tracking for complete 4 KiB private remappings inside an excluded 64 KiB import block, preserving neighboring exclusions and stale-generation checks. It has no dependency on this PR and includes no residency or shader changes.

Separately, a local integration of this PR, that repair and #1191's opt-in linear-target residency was evaluated with the same shader revision held constant. Three alternating 120-second residency-off/on pairs averaged 8.35/10.99, 8.20/10.80 and 8.38/11.27 FPS. These local results isolate the residency toggle: the 31.6–34.4% gain belongs to #1191's residency work and is not an additional gain claimed by this PR or by the write-watch repair. Detailed long event timelines overflowed; frame windows were complete, and separate complete short diagnostics showed the three synchronous draw waits disappear.

Clean-source integration passes 18 focused tests with residency off/on. Both automated one-lap races exit cleanly. The extended run has incomplete screenshot coverage, and vkQuake startup remains inconclusive. The playable shader experiment retains its known semantic-test failure and is excluded from publishable source. These residency measurements predate the review repair above and remain separate from this PR's original performance evidence.