[Nesyth]

What

A depth surface the driver creates for a depth target starts from DB_DEPTH_CLEAR: the DepthSurface constructor clears the new image and never reads guest memory. Storage writes made to the plane's memory before any surface existed at that address therefore do not reach it. At that time the view is an ordinary storage image, since a plane's own storage view (#4500) exists only once its surface does. The first depth test against the plane reads the clear value instead of what the kernel wrote.

DepthSurfaceView now gives a surface it creates for a target without HTILE (DB_HTILE_DATA_BASE 0), and without an earlier surface whose planes it takes over (#4683), the depth those writes left (Graphics/src/DepthSurface.cpp):

• It looks for a storage image at the depth plane's address: first one with results pending, which may be larger than the plane (StorageTexture::FindPending), then a cached one of exactly the plane's size (FindLive).
• It takes the image only when it fits the plane: the plane's width and height, one level, a 2D or 2D array view, and an R16 format (UINT, UNORM, SINT, SNORM or SFLOAT) for a 16-bit plane (D16, D16S8) or an R32 format (SFLOAT, UINT or SINT) for a 32-bit one (D32, D32S8).
• The image is first brought up to date with guest memory (Refresh). Its layer 0 is then copied into the surface's depth aspect through the plane's staging buffer: in the active recorder, which keeps the image alive until the copy has run, or else in a batch of its own that is submitted and waited for.
• Only the depth aspect is copied. The stencil plane of a new D32S8 surface still starts from DB_STENCIL_CLEAR.
• These surfaces still start from DB_DEPTH_CLEAR, as on main:
  • a surface with HTILE, where the HTILE state decides, so an HTILE clear after the storage write wins;
  • a multisampled surface;
  • a surface the device stores in another format than the guest's (16-bit depth with stencil on a device without D16_UNORM_S8_UINT, fix(agc): store D16 depth with stencil as D24 or D32 where the device lacks it #3846);
  • a surface with no fitting image at its address (another extent, level count, dimension or format size).
• A surface that already exists is never seeded again, including one DepthSurfaceView finds again for the same target. fix(agc): store a written storage image over a depth plane into the surface #5113 keeps such a surface up to date when a storage image over its plane is stored back.
• DepthSurfaceView now takes GuestMemory::GpuMutex() (recursive) before the surfaces' mutex, the same order DepthSurfaceTexture uses, because the lookup and Refresh run under the GPU mutex. Its only caller in the driver is the draw path.
• docs/dev/debt/libSceAgcDriver.md records the rule. On the console the plane is the memory the kernel wrote, so there is nothing to seed; none of this is measured there.

Ready or Not (PPSA18605) clears its shadow maps this way. Traced with temporary logging on my bring-up build (run 205): six 1024x1024 D16 planes were each written through a storage image, then bound as a depth target for the first time and created from DB_DEPTH_CLEAR 0.0 without HTILE. On main the two operators in the main menu are black silhouettes, while the PS5 shows a red rim light on them. With this change they are lit (see Tested).

Test: new tests/execution/DepthSurfaceFromStorage.cpp (ctest agc_driver_depth_surface_from_storage). A compute kernel stores row 0 of a 64x32 plane whose memory holds 0.25, 32 values from 0 to 0.94, through a storage view. A full-screen draw at depth 0.5 with LESS then tests against a new surface over the plane, whose clear value is 1.0. The draw passes 15 of the 2048 pixels when the surface took the storage image (the stored values above 0.5) and all 2048 when the surface started from its clear value:

• a new D32 surface over a pending R32F view, a new D16 surface over a pending R16 unorm view, and a new D32 surface over a flushed R32F view (FindLive): 15 each;
• a new D32 surface over a pending two-layer R32F 2D array view, which stores into layer 0: 15. The image is larger than the plane, so only FindPending finds it; the case requires FindLive to miss it;
• a new D32 surface whose HTILE was cleared (NoteHtileDepthClear) after the storage write: 2048;
• a new D32S8 surface over a pending R32F view: 15. A stencil EQUAL 0 draw without the depth test then passes all 2048 pixels (the stencil plane kept its clear value).

Not covered by a test:

• The multisample and host format check, and the image's extent, level, dimension and format checks.
• Which image wins when a pending one and a cached one of the plane's size are both at the address: FindPending comes first, so the one with pending results.
• Skipping a new surface that takes its planes from an earlier one: without that check, the depth tests (ctest -R depth, 10 tests) still pass. It keeps an image that is still cached at the address from overwriting depth drawn after the image was written.

Related, both merged:

• fix(agc): store a written storage image over a depth plane into the surface #5113 copies a written storage image that covers a depth plane into a surface that exists when the image is stored back. This PR seeds a surface that is created after the write. On main 32e810d, which has fix(agc): store a written storage image over a depth plane into the surface #5113, this PR's test fails its five new-surface cases ("2048 pixels passed, expected 15"). Earlier, on main 18c438b, Ready or Not's menu operators stayed black with fix(agc): store a written storage image over a depth plane into the surface #5113 alone (run 702) and were lit with both (run 709).
• fix(agc): share a depth plane's contents across its stencil pairings #4683 rewrote the block of DepthSurfaceView that creates a surface, so that a new surface takes its planes from their last owner. The TakeStorage call now sits in that block and runs only when there is no such owner.

Tested

Windows 11 Pro 10.0.22631, AMD Ryzen 7 7800X3D, AMD Radeon RX 7900 XTX, WinLibs GCC 15.2.0, Release, BUILD_TESTING=ON, this head on main 32e810d:

• ctest -R "^agc_" -j 2: 539 of 544 pass, with 4 skips. The failure, agc_driver_layered_volume_vertex_no_gpl ("vertex draw: slice 1 texel (0, 0) channel 0 is 64, expected 255"), also fails on main 4ae78dc without this change on this GPU.
• One change at a time, rebuilding and running agc_driver_depth_surface_from_storage:
  • on main 32e810d without this change, it fails in the five new-surface cases ("a new D32 depth surface over a pending R32F storage write: 2048 pixels passed, expected 15", and the same for D16, the flushed image, the two-layer view and D32S8);
  • taking the image for a surface with HTILE as well (without target.htileAddress == 0): "a new D32 depth surface whose HTILE was cleared after a storage write: 15 pixels passed, expected 2048";
  • without FindLive: "a new D32 depth surface over a flushed R32F storage write: 2048 pixels passed, expected 15";
  • with FindLive alone, without FindPending: "a new D32 depth surface over a pending R32F storage write through a two-layer 2D array view: 2048 pixels passed, expected 15".
• tools/check_conventions.py --base origin/main passes.

Ready or Not (PPSA18605), main menu, measured before this rebase on main 18c438b, which main dacd785 differs from only in libSceAgcDriver (#4949). The runtime's libs held the 127 modules built from 18c438b, with libSceAgcDriver swapped per run, and app.exe is the title relinked by that commit's relinker. APS5_HOST_IMPORT_MIB=10240, and the runtime's saved\ps5\engine.ini raises UE's render fence timeout (g.TimeoutForBlockOnRenderFence=1800000). The red light is measured on the 9 menu frames each run dumped (1280x720), in the 500x380 box around the operators, as the share of pixels with R >= 60 and R at least twice G and B:

• main (runs 700, 704, 706 and 708): 0.07-0.14%, mean R 14-16: black silhouettes.
• main + this change (run 701): 2.9-4.7%, mean R 28-34: lit by the red rim light.
• main + fix(agc): store a written storage image over a depth plane into the surface #5113 (run 702): 0.07-0.13%, mean R 16: black silhouettes.
• main + this change + fix(agc): store a written storage image over a depth plane into the surface #5113 (run 709): 7.1-10.3%, mean R 30-37: lit.
• The previous head, with libSceAgcDriver built on main dacd785 (run 710): 3.2-12.0%, mean R 32-41: lit.

Main menu, one dumped frame (1280x720) from each session. Top left: main 18c438b (run 700). Top right: main + this PR (run 701). Bottom left: main + #5113 (run 702). Bottom right: the PS5, for reference. The two operators stand in front of a red light. On the PS5 it lights their outlines. On main and with #5113 alone they are black silhouettes; with this PR they get the same rim light.

Linux: not run.

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: none
• Unblocks: PPSA18605 Ready or Not (PPSA18605) #4184
• GPUs tested: AMD Radeon RX 7900 XTX, AMD Software Adrenalin 26.8.1 (driver 32.0.31041.1004), Windows 11 Pro 10.0.22631
• AI-assisted: yes

[KauaSantos702]

NVIDIA run at this head (284011b8b), adding a vendor to the AMD results in the body: no agc_* test fails.

• NVIDIA GeForce RTX 5070 (Blackwell), driver 32.0.16.1714, Windows 11
• WinLibs GCC 15.2.0 r7, Release, BUILD_TESTING=ON
• ctest -R '^agc_' -j2: 484 tests, 483 passed, 0 failed, 1 skipped. The skipped test is agc_driver_stencil_ref_export, because the device lacks VK_EXT_shader_stencil_export; it is also skipped on main.

[adriadam10]

Checked: the merged tree builds and agc_driver_depth_surface_from_storage passes on Linux; with DepthSurface.cpp reverted it fails, so the test pins the change. The rest of the libSceAgcDriver scope is green except agc_driver_tessellation, which segfaults on main as well. Lock order (GpuMutex before the surfaces mutex), the recorder/batch copy path and the debt entry look right; thanks for the NVIDIA run, @KauaSantos702. Merging once the full Build is green.