fix(shader): read cube T#s through DIM 2D image_sample and image_load as face 0

[billythemenace2]

What

Before: a DIM 2D image_sample or image_load bound to a cube T# had no runtime image mode. The draw threw "image descriptor is incompatible with the static runtime image interface ... {class 1, dim 5, ..., cube 1, ...}". This is shape 2 of #4139: High on Life (PPSA15388) samples a 32x32 cube placeholder through dim:SQ_RSRC_IMG_2D.

After: these accesses get a cube mode, the one DIM CUBE accesses already use, with face coordinate 0. Sampling sees the BASE_ARRAY face of the cube's 2D-array view at (u - 1, v - 1). A load reads texel (x, y) of that face. The mode is offered only when every access is image_sample_lz, plain image_sample, image_sample_l or a mip-less image_load; other DIM 2D accesses on a cube T# still throw. Shape 1 of #4139 (a non-image descriptor in an image slot) is not addressed here.

Hardware semantics, measured on RDNA1 (gfx1010, AMD Radeon RX 5700 XT) with the tools/hw-oracle template. The kernels were assembled with the Windows driver's amd_comgr_2.dll and launched with its HIP runtime. The cubes were 8x8 and 32x32 32_FLOAT, with DEPTH 5 and 11 and BASE_ARRAY 0 and 6, and every texel holds its own word index.

• Samples: DIM 2D image_sample_lz equals DIM CUBE image_sample_lz with face coordinate 0 on every row. That covers point and bilinear filters, wrap, clamp and mirror addressing, DISABLE_CUBE_WRAP 0 and 1, and coordinates from -1 to 4. The same holds for plain image_sample (one level, and six levels in 2x2 compute quads with steps of 1-32 texels) and image_sample_l (the third address VGPR is the LOD, integer and fractional). Explicit LOD matched 24/24 rows and implicit LOD 24/24.
• Face selection: the VGPR after the two coordinates is not read. Face coordinates 0, 1 and 3 in it all give the BASE_ARRAY face.
• Coordinate range: the face coordinates are cube coordinates in [1, 2], and the texel is floor((u - 1) * width).
• Loads: DIM 2D image_load reads texel (x, y) of the BASE_ARRAY face, the same word as a DIM 2D load on a 2D T# for base 0.

The measurement write-up is attached.
measurement-results-cube-2d-gfx1010.md

Outside the face the translation follows the DIM CUBE path and samples the 2D-array view with the S# addressing. That matches the hardware only inside [1, 2). On the hardware:

• a coordinate below 1 clamps to the first texel for every filter, wrap mode and DISABLE_CUBE_WRAP setting measured;
• with DISABLE_CUBE_WRAP 0, a coordinate of 2 or more clamps to the last texel (point filter), and bilinear filtering blends texels of the neighbouring faces at the edges;
• with DISABLE_CUBE_WRAP 1, a coordinate of 2 or more follows the S# addressing.

This is recorded in technical debt, together with the accesses that still throw.

Tested

• Windows 11, AMD Radeon RX 5700 XT, Adrenalin 32.0.21045.5002, MinGW GCC 15.2.0. The full build is clean.
• New test agc_driver_image_plane_address_on_cube runs DIM 2D image_sample_lz, image_sample_l, plain image_sample and image_load on an 8x8 32_FLOAT cube (six faces) over 32 lanes. The same kernel semantics ran on the RX 5700 XT through the oracle, and its expected values matched all 32 lanes. The test passes. Without the change it fails with the error above.
• ctest -R "image_|shader_memory|disk_cache|runtime_images|cube|sampl|emulated_color_compare": no test fails that does not also fail on unchanged main (dacd785) on this machine.
• python3 tools/check_conventions.py --base origin/main passes.
• Not tested: High on Life itself (not my dump).

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 (merges cleanly with fix(shader): read 1D T#s through 3D image_sample and image_load accesses #5375, fix(shader): compare through 2D image_sample_c on 1D T#s #5456, feat(shader): translate the 64-bit and f32/f64 min/max DS src2 forms #5474, fix(shader): flush ds_add_f32 denormals and NaNs as the hardware does #5492, fix(shader): run DS src2 lanes one at a time in lane order #5498 and fix(shader): update per-invocation LDS without atomics #5160)
• Unblocks: PPSA15388 (shape 2 of issue AGC: a draw whose image slot holds a sampler/buffer descriptor, or a cube T# read with dim 2D, is refused (High on Life PPSA15388) #4139; shape 1 remains)
• GPUs tested: AMD Radeon RX 5700 XT (gfx1010), Adrenalin 32.0.21045.5002, Windows 11
• AI-assisted: yes. Claude wrote the change, the test and the measurement kernels; I reviewed it and ran the measurements and tests on my machine.

[xXPBSXx]

Windows test of #5509: Windows 10 (19045), MinGW-w64 GCC 15.2, Release, ninja -j 4, ctest called directly. Tree: main d1670009f + merge of da58289f0ea7e540caf3c2baced8d8f7bd586ae6 (local merge 799a8b817).
Six ctest targets, 3 runs each, exit code 0 in every run (18 of 18): agc_driver_image_plane_address_on_cube (the new test of this PR), agc_driver_image_plane_address_on_line, agc_driver_image_plane_address_on_line_implicit_lod, agc_driver_image_sample_cube_derivatives, agc_driver_vop3_cube_clamp, agc_shader_disk_cache.
Additional run, same main d1670009f + the same PR head (local merge 27519610d): agc_shader_bindless and agc_shader_memory (both cover recompiler files this PR changes), exit code 0, 3 of 3 each.
Not tested: that the new test fails without the change (no baseline run), other ctest targets that touch ResourceMaterializer.cpp, which GPU the execution tests used (not recorded in the ctest output; the machine has an NVIDIA GeForce RTX 4080 SUPER and an AMD Radeon RX 6400), Linux, a title run (PPSA15388 not available here).

AI-assisted (Claude Code).

[xXPBSXx]

Windows build check of #5509 (head da58289f0ea7e540caf3c2baced8d8f7bd586ae6) on main 52d134c02: Windows 10 (19045), MinGW-w64 GCC 15.2, Release. The merge has no textual conflict, but compiling core/shader/recompiler/ShaderDiskCache.cpp fails: static assertion failed: ImageResource changed: update the info encoder. With this PR merged the assertion on ImageResource fires: the shader disk cache pins the field counts of the structures it encodes (assertions from 664ad7703, 13 October), so the PR needs the info encoder and the count updated. Only this one object file was built (ninja ...ShaderDiskCache.cpp.obj, log dc_check_result.txt); a full build of the merge was not run. My earlier test of this PR (all tests exit 0, 18 of 18 + agc_shader_bindless/agc_shader_memory) was on main d1670009f.

AI-assisted (Claude Code).

[oneandonlydean]

This no longer builds on main: ShaderDiskCache.cpp asserts fieldCount<ImageResource>() == 37 (664ad77), and cubeFaceCompatible makes it 38. Please update that count and bump FormatVersion in ShaderDiskCache.hpp (30 on main), since the encoded info changed.

[billythemenace2]

Rebased on main. fieldCount<ImageResource>() is now 38, the minimum image record is 76 bytes and FormatVersion is 33. The new cube test, the cube derivative and clamp tests, agc_shader_disk_cache and agc_shader_memory pass on an RX 5700 XT. image_plane_address_on_line and its implicit-LOD variant fail on this GPU on plain main too.

[adriadam10]

Checked on the HW oracle (gfx1035, IEEE off): on 8x8 32_FLOAT cubes (DEPTH 5 with BASE_ARRAY 0, DEPTH 11 with BASE_ARRAY 6), DIM 2D image_sample_lz, image_sample_l and plain image_sample equal DIM CUBE with face 0 bit for bit over 484 rows per mode (wrap/mirror/clamp, point/bilinear, DISABLE_CUBE_WRAP 0 and 1, u and v from -1 to 4), and image_load reads texel (x, y) of the BASE_ARRAY face, matching your gfx1010 measurements. The new test fails without the change and passes here on RADV and on CI's lavapipe.

What we added on your branch:

• Rebased on main. Main's shader disk cache now pins 37 fields and sizeof(ImageResource) == 88, so with cubeFaceCompatible they are 38 and 92, the minimum image record is 77 bytes and FormatVersion is 36.
• One correction to the technical debt line: inside the face, a bilinear sample with DISABLE_CUBE_WRAP 0 within half a texel of the face edge already blends texels of the neighbouring faces on hardware (e.g. u = 1.0625, v = 1.03125 on face 0), so the translation matches only away from those edges. The line now says so.

Merging once the full Build is green.

[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
#5841	core/shader/recompiler/Optimization/src/ResourceMaterializer.cpp L1240-1241

[adriadam10]

Checked on the HW oracle (gfx1035, IEEE off): on 8x8 32_FLOAT cubes (DEPTH 5 with BASE_ARRAY 0, DEPTH 11 with BASE_ARRAY 6), DIM 2D image_sample_lz, image_sample_l and plain image_sample equal DIM CUBE with face 0 bit for bit over 484 rows per mode (wrap/mirror/clamp, point/bilinear, DISABLE_CUBE_WRAP 0 and 1, u and v from -1 to 4), and image_load reads texel (x, y) of the BASE_ARRAY face, matching your gfx1010 measurements. The new test fails without the change and passes here on RADV and on CI's lavapipe.

What we added on your branch:

• Rebased on main. Main's shader disk cache now pins 37 fields and sizeof(ImageResource) == 88, so with cubeFaceCompatible they are 38 and 92, the minimum image record is 77 bytes and FormatVersion is 36.
• One correction to the technical debt line: inside the face, a bilinear sample with DISABLE_CUBE_WRAP 0 within half a texel of the face edge already blends texels of the neighbouring faces on hardware (e.g. u = 1.0625, v = 1.03125 on face 0), so the translation matches only away from those edges. The line now says so.

Merging once the full Build is green.