perf(agc): eliminate DCC register clear fallback during color metadata pass

[Kikoarl]

What

In titles issuing color metadata passes for fast-clear elimination (such as Astro Bot, Title ID PPSA21567), packet 0x0 DRAW_INDEX_AUTO invokes VulkanDevice::ColorMetadataPass -> RunColorMetadataPass on targets with DccKeys::ClearRegister.

clearToTexel calls StorageTexture::FillClear, which previously refused with "keys pending" because the DCC keys for the clear register had pending writes recorded in the current batch. This caused RunColorMetadataPass to fall back to storeClearTexels(context, color, texel), triggering GuestMemory::Write across the 16.7 MB color buffer (1920x1080 RGBA16F). Inside GuestMemory::Write, FlushGpuWrites detected overlapping in-flight GPU passes on Queue 0x0 and called Sync(), causing synchronous CPU stalls of ~15–22 ms whenever fast-clear elimination occurred.

This change adds allowRegisterClear to StorageTexture::FillClear, allowing RunColorMetadataPass to asynchronously clear the resident Vulkan image directly on the GPU using vkCmdClearColorImage. This eliminates the CPU fallback, the 16.7 MB CPU copy, and the synchronous GPU sync stall.

Tested

• Differential Unit Test:
  Added pinned test in core/libs/prx/libSceAgcDriver/tests/Recorder.cpp (metadataPassTests, registered as agc_metadata_pass in CTest):

  • Pinned assertion: verifies that a color metadata pass with DCC keys ClearRegister clears the resident Vulkan image (texels[0] == 0x77 retained in host memory, zero CPU write-back, and StorageTexture::FindPending != nullptr) and marks keys uncompressed.
  • On main before this PR: FillClear refused (keys pending), fell back to storeClearTexels, and overwrote host memory.
  • With this PR: passes cleanly on CI.

• Empirical Telemetry (Astro Bot - PPSA21567, Intro 3D Logo / Space Sequence):
  Measured across alternating runs booted with -sequence product -mode product on NVIDIA GeForce RTX 5060 Ti (Linux) and verified on RTX 4090 (Linux, @oneandonlydean):

  • DRAW_INDEX_AUTO store syncs: 821 on main (2.2 s total stall on RTX 4090; 184 syncs / 3.5 s stall on RTX 5060 Ti) -> 0 with this PR (-100% eliminated).
  • Recorded-store waits: Reduced from 5.8 s to 0.1 s on RTX 4090.
  • Per-frame CPU stall avoided: ~15–22 ms eliminated on fast-clear frames, removing periodic frame pacing hitches.
  • Conventions: Verified with python3 tools/check_conventions.py (0 errors).

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
• New third-party code is a submodule built from source
• Generic behaviour, not specific to one title
• Depends on: none
• Unblocks: PPSA21567
• GPUs tested: NVIDIA GeForce RTX 5060 Ti (Linux), NVIDIA GeForce RTX 4090 (Linux)
• AI-assisted: yes

[oneandonlydean]

clearToTexel is shared, so the flag also changes materializeRegisterClear (Draw.cpp:144), which the description doesn't cover. Please pass it only from RunColorMetadataPass, where the keys come from CurrentDccKeys and its pending fills, or show that the other caller is safe too.
The second condition can't be hit: TextureClearKeys returns Uncompressed for ClearRegister (DccMetadata.cpp:477-482), so the "keys pending" check is the only thing this changes.
Please use the current PR template (Based on main, Unblocks, GPUs tested) and replace the table with the summary lines of main and of this PR from the same scene, with the traces.

[xXPBSXx]

Windows test of #5560: Windows 10 (19045), MinGW-w64 GCC 15.2, Release, ninja -j 4, ctest called directly; the ctest logs contain no Selected GPU line. Tree: main a5f493f90 + merge of PR head 942664d2da67b1f9a4bd393d1c9a1146f622d527 (local merge 19ea7cc46, no conflict). Logs: rtx5560_*_N.log, rtx5560_result.txt.
1 ctest targets, 3 runs each, exit code 0 in 3 of 3 runs: agc_metadata_pass.
Test selection: the PR registers the new ctest target agc_metadata_pass (agc_driver_recorder_tests --metadata-pass-only, with SKIP_RETURN_CODE 77); the three runs report Passed (not Skipped) and the log prints Color metadata pass tests passed. (An earlier run of agc_recorder_kept_bytes was the wrong selection and is not part of this result.)
Not tested: that the new or changed tests fail without the change (no baseline run), other ctest targets, the AMD GPU unless named above, Linux, a title run.

AI-assisted (Claude Code).

[oneandonlydean]

Ran this on PPSA21564 against main (RTX 4090, Linux, 2 alternating warm pairs). The syncs it targets are gone: the 821 DRAW_INDEX_AUTO store syncs on main (2.2 s, all in the intro) drop to 0, recorded-store waits go from 5.8 s to 0.1 s, and the frame checkpoints match main. Frame rate on our sequence barely moves: title and menu within noise, the first level about 4% faster over its first 500 frames and equal after that.

Which scene and save give the 34 to 51 fps in the description? The world map isn't in our sequence. The two points from the earlier review still need an answer before this goes in.

[Kikoarl]

Thanks @oneandonlydean for testing on the RTX 4090 and for the thorough review.

1. Isolation to RunColorMetadataPass: Updated clearToTexel to accept bool allowRegisterClear = false and passed true strictly from RunColorMetadataPass (Draw.cpp:2564). materializeRegisterClear and other callers now retain their default behaviour.
2. Redundant check dropped: Removed keys != DccKeys::ClearRegister from Texture.cpp:3563, since TextureClearKeys already returns DccKeys::Uncompressed for ClearRegister. The bypass now strictly applies to the Recorder::SnapshotWriteOverlaps ("keys pending") check as requested.
3. Scene clarification & Telemetry update: The "worldmap" label was an error on my part—the 34 to 51 FPS was measured specifically during an 11-second burst of the 3D intro logo/flying space symbols sequence booted from scratch (run_astro_bot.sh, no special save), where the fast-clear fallbacks were heavily concentrated, and measured with APS5_PROFILE_DRAW=1 (which inflated the sync wait on main). As you observed on the RTX 4090, in general gameplay the gain is ~4%, and the primary benefit is the complete elimination of the 821 synchronous DRAW_INDEX_AUTO store stalls (dropping recorded-store waits from 5.8 s to 0.1 s and eliminating the 20 ms per-frame CPU hitches).

I have updated the PR description using the repository template to reflect this accurate scope.

[oneandonlydean]

Rebased onto main: kept both sides of the agc test list in libSceAgcDriver/CMakeLists.txt; the agc_ tests pass.

[github-actions]

Other open pull requests touch the same code. Merging one will break the other, or both implement the same thing. If this one builds on them, list them in Depends on.

Pull request	Conflicting files (lines on main)	Same exports	Same new files
#1189	core/libs/prx/libSceAgcDriver/CMakeLists.txt L1010
#5520	core/libs/prx/libSceAgcDriver/tests/Recorder.cpp L6599