feat(libSceAgcDriver): take a one-layer 2D array view of a depth surface plane as the plane

[jdmagic]

What

Depends on: #4500; its two commits are included. Only the last commit belongs to this PR.

#4500 takes a storage view of a depth or stencil plane for the depth surface only when the view is a 2D image. A 2D array view of layer 0 with one layer and the plane's extent and format is the same plane, but it took the ordinary storage path and read guest memory instead of the plane.

• Such a view now gets the plane's storage image, seeded and copied back as feat(libSceAgcDriver): storage image access to depth surfaces #4500 does for a 2D view. A view with more layers, or another extent or format, still takes the ordinary path.
• The plane's storage image is recreated when the view's dimension changes.
• agc_driver_depth_storage: a one-layer 2D array view of the depth plane reads back depth stored into the surface (0.5 while guest memory holds 0.75), a one-layer 2D array view of the stencil plane reads back the cleared stencil over zeroed guest memory, and a two-layer array view of the stencil plane is not taken for the surface.

Sackboy: A Big Adventure (PPSA01289) binds the stencil plane of its 2880x1620 D32_SFLOAT_S8_UINT surface as a one-layer R8_UINT 2D array from a compute shader during presentation.

Tested

Windows 11, MinGW-w64 GCC 15.2.0 (WinLibs r7), NVIDIA GPU, on #4500's head cdfba51 (main 5efd09a + #4500).

• agc_driver_depth_storage, agc_driver_depth_storage_reuse, agc_driver_depth_compare_copy, agc_driver_depth_fast_clear, agc_driver_depth_fast_clear_submit, agc_driver_depth_bias_per_face, agc_driver_graphics: 7/7 passed. The full ctest was not run on this branch.
• On feat(libSceAgcDriver): storage image access to depth surfaces #4500 alone (without this commit), agc_driver_depth_storage fails with a one-layer 2D array view of the depth plane was not taken for the depth surface.
• PPSA01289: the title's storage views of that shape are in its logs (2880x1620, guest format 5, 2D array, one layer). The title has not been rerun on this head.

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 in TechnicalDebt
• 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: feat(libSceAgcDriver): storage image access to depth surfaces #4500
• AI-assisted: yes

🤖 Generated with Claude Code

[fisherjoey]

For reviewers: #2325 (mine) duplicates the stencil-plane part of this PR. I've closed #2325. Its two extra pieces, an HTILE stencil fast clear and a stencil storage test, are in commit 598f788 if you want to cherry-pick them.

AI-assisted: yes

[jdmagic]

Thanks for the review. Both points are addressed; details are in the updated description.

• The refused-view check uses an R16_UINT image_store: a 16-bit image_load at the stencil address isn't refused today, so a load can't serve as the case that must throw.
• The branch is now main a11c8f7 + feat(agc): depth planes sampled as 2D arrays, cubes and integer views #425's four commits + this PR's three, and merges cleanly; it no longer depends on feat(agc): multisampled color and depth targets with CB resolves #419, fix(libSceAgcDriver): retire a depth surface once another writer covers its memory #454, feat(agc): sample depth plane arrays from a later base slice #1186, fix(agc): CB resolve into any tiled color target #1189 or fix(agc): take depth fast clears from HTILE written by any kernel #2053. I'll rebase again once feat(agc): depth planes sampled as 2D arrays, cubes and integer views #425 lands so only this PR's commits remain.

[queeeef]

A case this PR should handle: a storage image at a stencil plane's address that is not the stencil plane.

In Palworld (PPSA23126), with this PR's SeedStorageFromStencil (unchanged at f08fc2291) merged locally, a 2536x1428 depth surface (D32_SFLOAT_S8_UINT) has its stencil plane at 0x3027630000. Later in the frame the title places a 2536x1428 A2B10G10R10 color target at that same address: Unreal's transient allocator reuses the memory. That image is 14.5 MB, the stencil plane 3.6 MB.

cachedStorageTexture calls SeedStorageFromStencil for any storage image whose base is a stencil plane's address, and Transfer then throws. This happened 36 times in one run:

storage image access to the stencil plane of depth surface 0x3027630000 (2536x1428, vk format 130) as a 2536x1428 image of vk format 64, dimension 1, 1 mips is not implemented

The color target stays non-resident ([gpu] color target ... stays non-resident), and textures over it keep the snapshot path.

Seeding only an image shaped like the plane (an R8 format, one slice, one mip, the surface's extent) and treating anything else as reused memory fixes it locally:

@@ void SeedStorageFromStencil(const Context& context, const std::shared_ptr<StorageTexture>& storage) {
     if (found == list.rend()) return;
     auto& surface = **found;
+    const auto& descriptor = storage->Descriptor();
+    const auto storageFormat = storage->StorageFormat();
+    const bool r8 = storageFormat == VK_FORMAT_R8_UINT || storageFormat == VK_FORMAT_R8_UNORM || storageFormat == VK_FORMAT_R8_SINT || storageFormat == VK_FORMAT_R8_SNORM;
+    const bool oneSlice = descriptor.dimension == TextureDimension::k2D || (descriptor.dimension == TextureDimension::k2DArray && descriptor.depthOrLastArray == 0);
+    if (!r8 || !oneSlice || descriptor.mipCount != 1 || descriptor.width != surface.target.extent.width || descriptor.height != surface.target.extent.height) return;
     if (surface.stencilSeeded == storage.get() && surface.stencilWriter.lock() == storage) return;

The condition is the one Transfer already checks for the stencil aspect, so a plane-shaped image is seeded exactly as before, and the depth and stencil tests still pass.

Limits of this report:

• The title hit this in one of eight runs, so the runs since the patch show no refusal, but they don't prove the patch is what removed it.
• I haven't written a test for the reuse case. If you prefer it as a commit on your branch, I can open a PR against it.

AI-assisted (Claude Code)

[ee6aba54]

@jdmagic for coordination, since the two overlap: #4500 adds storage images over both planes of a depth surface. The stencil plane is bound as an R8_UINT image of the surface's extent, seeded with a copy of the stencil aspect before the dispatch and copied back at write-back. I missed this pull request when I opened #4500. The depth-plane storage path of #425 that this one builds on has since been taken out of #425 (its author describes the split on #4500).

What this pull request covers beyond #4500:

• 8-bit UNORM, SINT and SNORM views of the stencil plane, and layer 0 of a 2D array;
• dropping a stencil writer when a fast clear covers the stencil aspect;
• agc_driver_stencil_plane_storage with the R16_UINT refusal.

The case @queeeef describes (a 2536x1428 A2B10G10R10 image placed at the stencil plane's address) takes the ordinary storage path in #4500, because a view whose format or extent is not the plane's is not treated as the plane.

If that works for you, these parts could build on #4500 once it merges. If you would rather structure it differently, I can adjust #4500.

[jdmagic]

@ee6aba54 Thanks, building on #4500 works for me. I reworked this PR onto it; the description is updated.

Of the parts you listed, only the one-layer 2D array view is still needed: PPSA01289 binds its stencil plane as a one-layer R8_UINT 2D array, which #4500 sends down the ordinary path. This PR is now that one commit on top of #4500. The rest is dropped:

• the stencil writer belonged to the old lazy copy-back, which feat(libSceAgcDriver): storage image access to depth surfaces #4500 replaces with a copy at write-back;
• no title I know of binds the plane as 8-bit UNORM, SINT or SNORM;
• the R16_UINT refusal contradicts feat(libSceAgcDriver): storage image access to depth surfaces #4500 sending a view of another format down the ordinary path, which also covers @queeeef's A2B10G10R10 case.

@fisherjoey, thanks for 598f788. Its coverage is now in #4500's agc_driver_depth_storage, so it is no longer on this branch.

[adriadam10]

#4500 is merged, and it landed with two extra commits from @oneandonlydean (26dfc464a7, 848b97b611) that this PR's last commit doesn't contain. It conflicts with main in DepthSurface.cpp, tests/DepthSurfaceReuse.cpp and tests/execution/DepthStorage.cpp (add/add), and it isn't a mechanical rebase:

• 26dfc464a7 makes a storage view that is not 2D throw storage image access to depth/stencil surface ... is not implemented (DepthSurface.cpp:165). This PR's change is to take a one-layer 2D array view as the plane, so it has to be reworked as a narrow exception to that check (layer 0, one layer, plane extent and format), keeping the throw for every other non-2D view.
• Main now has agc_driver_depth_storage_dispatch (dispatch-based test with the refusals). Please put the one-layer array cases (depth, stencil, and the two-layer view that must still throw) there as well as in agc_driver_depth_storage, and check the new tests fail without the change.
• StoreBack through a view replaced by another view of the same plane now throws; say what happens when the dimension change recreates the storage image (the "recreated when the view's dimension changes" part) with respect to that.
• Dean noted that #2491 will conflict in DepthSurface.cpp and that StoreBack has to bump the write serial there; keep that in mind when rebasing.

Please rebase on current main so the PR is only its own commit, rerun the depth/agc tests, and update the body's Tested section for that head (it now says it was tested on #4500's old head and the full ctest wasn't run).

[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
#4551	docs/dev/debt/libSceAgcDriver.md L28-29
#5003	core/libs/prx/libSceAgcDriver/Graphics/src/DepthSurface.cpp L162-167 core/libs/prx/libSceAgcDriver/tests/execution/DepthStorageDispatch.cpp L48, L218, L220, L222-224, L304 docs/dev/debt/libSceAgcDriver.md L29

[oneandonlydean]

Rebased onto main 77b9f72 so only your commit remains, and added one on top for the review:

• DepthSurface.cpp: a 2D array view is taken as the plane only at layer 0 with one layer; every other non-2D view still throws storage image access to depth/stencil surface ... is not implemented. Your commit keeps the recreate when the view's dimension changes.
• StoreBack: a one-layer array view replaces an earlier 2D view of the plane like any other view, so a store back through the replaced 2D view throws. agc_driver_depth_storage now checks that, and that two-layer and layer-1 views throw.
• agc_driver_depth_storage_dispatch: one-layer array views of the depth and stencil planes are dispatched and checked with depth and stencil tests, and a two-layer view still throws. Both tests fail on main and pass here. The debt entry in docs/dev/debt/libSceAgcDriver.md now names the one-layer case.
  Your commit keeps your authorship. Depth tests and the agc_/guest_ ctest set pass on Linux. Merging.

Met in cc3b47d: the one-layer array view is a narrow exception (layer 0, one layer) and every other non-2D view still throws; the cases are in agc_driver_depth_storage and agc_driver_depth_storage_dispatch and fail without the change; a store back through a replaced view throws. See the comment above.