feat(gpu): GPU compute detile for guest tiled textures (Vulkan + Metal) (#592)

* feat(gpu): GPU compute detile for guest tiled textures (Vulkan + Metal) Move RDNA2 exact-XOR deswizzle (swizzle modes 5/9/24/27, 4bpp) off the CPU onto a GPU compute pass. GnmTiling.GetDetileParams resolves the shared addressing into DetileParams; the CPU fallback and both GPU kernels consume the same params so they never disagree. Vulkan (verified bit-exact on NVIDIA): SpirvFixedShaders.CreateDetileCompute hand-emits the SPIR-V kernel; VulkanDetilePass.RecordDetile records the dispatch into the async batch command buffer (never a blocking submit on the render thread) with transients retired via fence; VulkanDetileSelfTest (SHARPEMU_DETILE_SELFTEST=1) checks both entry points against the CPU detile. Metal (Mac-untested): detile_compute.msl (detile_cs) + MetalDetilePass mirror the Vulkan pass. The active Metal path CPU-detiles via the new GnmTiling.DetileWithParams when a texture arrives packaged (empty RgbaPixels + TiledSource/Detile), keeping Metal correct under default-on with no regression; wiring MetalDetilePass live is the remaining on-device step. Flags: GPU detile is default-on (SHARPEMU_GPU_DETILE=0 disables); [GPU-DETILE] diagnostics gated behind SHARPEMU_LOG_GPU_DETILE=1. Tests: 17 detile unit tests pass, incl. DetileWithParams and GetDetileParams each matching TryDetile bit-for-bit across all supported modes/bpp, plus a SPIR-V structural-validity test. * feat(gpu): GPU compute detile for guest tiled textures (Vulkan + Metal) Move RDNA2 exact-XOR deswizzle (swizzle modes 5/9/24/27, 4bpp) off the CPU onto a GPU compute pass. GnmTiling.GetDetileParams resolves the shared addressing into DetileParams that the CPU fallback and both GPU kernels consume, so they never disagree; everything else keeps the CPU path. Vulkan (verified bit-exact on NVIDIA): SpirvFixedShaders.CreateDetileCompute hand-emits the kernel; VulkanDetilePass.RecordDetile records into the async batch command buffer (never a blocking submit on the render thread) with transients retired via fence, falling back to CPU detile on failure. VulkanDetileSelfTest (SHARPEMU_DETILE_SELFTEST=1) checks both entry points. Metal (Mac-untested): detile_compute.msl + MetalDetilePass mirror the Vulkan pass; the active Metal path CPU-detiles via GnmTiling.DetileWithParams so it stays correct under default-on. Wiring MetalDetilePass live is a follow-up. Flags: default-on (SHARPEMU_GPU_DETILE=0 disables); diagnostics behind SHARPEMU_LOG_GPU_DETILE=1. Adds 17 passing detile unit tests. * Fix: added support layered texture support for the GPU-Detiling. * Fix: Added support for BlockTable (1 / 4 / 8 (Morton/Z-order)) * feat: added support for 8 and 16 bpp (bytes per element) * Fixed a build failure specific to this branch ---------
2026-07-31 23:19:44 +08:00 · 2026-07-24 19:13:02 +02:00
parent 5228335f15
commit a158960c20
13 changed files with 2702 additions and 27 deletions
@@ -271,6 +271,25 @@ public static partial class AgcExports
        Environment.GetEnvironmentVariable("SHARPEMU_NO_TEXTURE_SKIP"),
        "1",
        StringComparison.Ordinal);
+
+    // GPU deswizzle: ship raw tiled bytes + params to the backend instead of
+    // detiling on the CPU. On by default; SHARPEMU_GPU_DETILE=0 forces the CPU
+    // path. Backend-agnostic here (only inspects DetileParams); the Vulkan/Metal
+    // backends detile on the GPU, others fall back to the CPU path.
+    private static readonly bool _gpuDetileEnabled = !string.Equals(
+        Environment.GetEnvironmentVariable("SHARPEMU_GPU_DETILE"),
+        "0",
+        StringComparison.Ordinal);
+
+    // Diagnostics (SHARPEMU_LOG_GPU_DETILE=1): one line per distinct texture tile
+    // mode and per-gate decision, so we can see which swizzle modes/formats a
+    // title uses and whether each takes the GPU or CPU path.
+    private static readonly bool _gpuDetileLog = string.Equals(
+        Environment.GetEnvironmentVariable("SHARPEMU_LOG_GPU_DETILE"),
+        "1",
+        StringComparison.Ordinal);
+    private static readonly HashSet<uint> _seenTextureTileModes = new();
+    private static readonly HashSet<uint> _gpuDetileGateDiag = new();
    private static long _dcbWriteDataTraceCount;
    private static int _tracedVertexRangeCount;
    private static long _dcbWaitRegMemTraceCount;
@@ -8235,6 +8254,15 @@ public static partial class AgcExports
    /// enabled and the format is understood; returns null to keep the raw
    /// bytes (linear surfaces, unknown modes, or non-power-of-two elements).
    /// </summary>
+    // The GPU detile kernel implements these two equation families at 4/8/16 bpp
+    // (one/two/four 32-bit words per element; 1/2 bpp are sub-word and stay on the
+    // CPU). Keep in lockstep with VulkanDetilePass.Supports / MetalDetilePass.Supports.
+    private static bool IsGpuDetileEquation(DetileEquation equation) =>
+        equation == DetileEquation.ExactXor || equation == DetileEquation.BlockTable;
+
+    private static bool IsGpuDetileBytesPerElement(int bytesPerElement) =>
+        bytesPerElement is 4 or 8 or 16;
+
    private static bool TryGetTextureElementLayout(
        TextureDescriptor descriptor,
        uint sourceWidth,
@@ -8411,6 +8439,20 @@ public static partial class AgcExports
            return true;
        }

+        if (_gpuDetileLog)
+        {
+            lock (_seenTextureTileModes)
+            {
+                if (_seenTextureTileModes.Add(descriptor.TileMode))
+                {
+                    Console.Error.WriteLine(
+                        $"[GPU-DETILE] texture tile_mode={descriptor.TileMode} fmt={descriptor.Format} " +
+                        $"{descriptor.Width}x{descriptor.Height} " +
+                        $"(0=linear; GPU covers exact-XOR 5/9/24/27 @ 4bpp).");
+                }
+            }
+        }
+
        var sourceWidth = descriptor.TileMode == 0
            ? GetLinearTexturePitch(
                Math.Max(descriptor.Width, descriptor.Pitch),
@@ -8695,6 +8737,65 @@ public static partial class AgcExports
            var arrayLayers = arrayUploadLayers;
            var layerBytes = checked((int)sourceSliceByteCount);
            var totalBytes = (long)layerBytes * arrayLayers;
+
+            // GPU detile for arrayed exact-XOR/4bpp textures: pack the tiled array
+            // slices contiguously and hand them to the GPU pass (one dispatch-Z
+            // layer per slice), mirroring the single-layer gate above. The backend
+            // deswizzles every layer on the GPU; only unsupported cases fall to the
+            // CPU per-layer detile below. Font/text atlases uploaded as 2D arrays
+            // take this path.
+            if (_gpuDetileEnabled && hasElementLayout && !baseMipInTail &&
+                IsGpuDetileBytesPerElement(bytesPerElement) &&
+                (long)physicalSourceByteCount * arrayLayers <= int.MaxValue)
+            {
+                var gpuArrayParams = GnmTiling.GetDetileParams(
+                    descriptor.TileMode, bytesPerElement, elementsWide, elementsHigh);
+                if (IsGpuDetileEquation(gpuArrayParams.Equation) &&
+                    (long)elementsWide * elementsHigh * bytesPerElement <= (long)physicalSourceByteCount)
+                {
+                    var sliceBytes = checked((int)physicalSourceByteCount);
+                    var tiledLayers = new byte[(long)sliceBytes * arrayLayers];
+                    var readAllLayers = true;
+                    for (var layer = 0u; layer < arrayLayers; layer++)
+                    {
+                        if (!ctx.Memory.TryRead(
+                                descriptor.Address + layer * chainSliceBytes + baseMipByteOffset,
+                                tiledLayers.AsSpan(checked((int)(layer * (uint)sliceBytes)), sliceBytes)))
+                        {
+                            readAllLayers = false;
+                            break;
+                        }
+                    }
+
+                    if (readAllLayers)
+                    {
+                        texture = new GuestDrawTexture(
+                            descriptor.Address,
+                            descriptor.Width,
+                            descriptor.Height,
+                            descriptor.Format,
+                            descriptor.NumberType,
+                            [],
+                            IsFallback: false,
+                            IsStorage: false,
+                            MipLevels: descriptor.MipLevels,
+                            MipLevel: mipLevel,
+                            BaseMipLevel: descriptor.ViewBaseLevel,
+                            ResourceMipLevels: descriptor.ResourceMipLevels,
+                            Pitch: sourceWidth,
+                            TileMode: descriptor.TileMode,
+                            DstSelect: descriptor.DstSelect,
+                            Sampler: sampler,
+                            WriteGeneration: hasWriteGeneration ? writeGeneration : -1,
+                            ArrayedView: true,
+                            ArrayLayers: arrayLayers,
+                            TiledSource: tiledLayers,
+                            Detile: gpuArrayParams);
+                        return true;
+                    }
+                }
+            }
+
            if (totalBytes <= int.MaxValue)
            {
                var layered = new byte[totalBytes];
@@ -8792,6 +8893,65 @@ public static partial class AgcExports
        }
        DumpTextureSourceIfRequested(descriptor, sourceWidth, source);

+        if (_gpuDetileLog && descriptor.TileMode != 0)
+        {
+            lock (_gpuDetileGateDiag)
+            {
+                if (_gpuDetileGateDiag.Add(descriptor.TileMode))
+                {
+                    var eq = hasElementLayout
+                        ? GnmTiling.GetDetileParams(
+                            descriptor.TileMode, bytesPerElement, elementsWide, elementsHigh).Equation
+                        : DetileEquation.None;
+                    Console.Error.WriteLine(
+                        $"[GPU-DETILE] gate mode={descriptor.TileMode} fmt={descriptor.Format} " +
+                        $"bpp={bytesPerElement} hasLayout={hasElementLayout} mipTail={baseMipInTail} " +
+                        $"storage={isStorage} arrayed={isArrayed} eq={eq} -> " +
+                        $"{(hasElementLayout && !baseMipInTail && IsGpuDetileBytesPerElement(bytesPerElement) && IsGpuDetileEquation(eq) ? "GPU" : "CPU")}");
+                }
+            }
+        }
+
+        // GPU detile: for the 4/8/16-bytes/element base-mip case the backend can
+        // deswizzle on the GPU (exact-XOR and block-table equations, including
+        // block-compressed formats), so ship the raw tiled bytes + params rather
+        // than paying the CPU detile. Everything else keeps the CPU path below.
+        //
+        // Arrayed textures are handled by the arrayed branch above (they package
+        // every layer's tiled slice); this branch is the single-layer case.
+        if (_gpuDetileEnabled && hasElementLayout && !baseMipInTail &&
+            IsGpuDetileBytesPerElement(bytesPerElement) && !isArrayed)
+        {
+            var gpuDetileParams = GnmTiling.GetDetileParams(
+                descriptor.TileMode, bytesPerElement, elementsWide, elementsHigh);
+            if (IsGpuDetileEquation(gpuDetileParams.Equation) &&
+                (long)elementsWide * elementsHigh * bytesPerElement <= source.Length)
+            {
+                texture = new GuestDrawTexture(
+                    descriptor.Address,
+                    descriptor.Width,
+                    descriptor.Height,
+                    descriptor.Format,
+                    descriptor.NumberType,
+                    [],
+                    IsFallback: false,
+                    IsStorage: isStorage,
+                    MipLevels: descriptor.MipLevels,
+                    MipLevel: mipLevel,
+                    BaseMipLevel: descriptor.ViewBaseLevel,
+                    ResourceMipLevels: descriptor.ResourceMipLevels,
+                    Pitch: sourceWidth,
+                    TileMode: descriptor.TileMode,
+                    DstSelect: descriptor.DstSelect,
+                    Sampler: ToGuestSampler(samplerDescriptor),
+                    WriteGeneration: hasWriteGeneration ? writeGeneration : -1,
+                    ArrayedView: isArrayed,
+                    TiledSource: source,
+                    Detile: gpuDetileParams);
+                return true;
+            }
+        }
+
        var rgba = TryDetileTextureSource(
            descriptor,
            sourceWidth,
@@ -6,6 +6,55 @@ using System.Runtime.CompilerServices;

 namespace SharpEmu.Libs.Agc;

+/// <summary>Which in-block address equation a <see cref="DetileParams"/> carries.</summary>
+internal enum DetileEquation
+{
+    /// <summary>Unsupported mode/format; caller must use the CPU path or raw upload.</summary>
+    None,
+
+    /// <summary>Exact AddrLib XOR equation (RDNA2 modes 5/9/24/27): factored X/Y terms.</summary>
+    ExactXor,
+
+    /// <summary>Other modes: a precomputed in-block Morton/standard element-offset table.</summary>
+    BlockTable,
+}
+
+/// <summary>
+/// Backend-agnostic description of how to deswizzle one surface, produced by
+/// <see cref="GnmTiling.GetDetileParams"/>. Holds only plain integers and small
+/// int[] tables — no host graphics-API types — so it can cross the guest-GPU
+/// backend seam and drive a Vulkan (SPIR-V) or Metal (MSL) detile compute kernel
+/// identically to the CPU <see cref="GnmTiling.TryDetile"/> fallback. The single
+/// shared addressing formula both consume is:
+/// <code>
+///   inBlockByte = Equation == ExactXor
+///       ? XByteTerm[x &amp; XMask] ^ YByteTerm[y &amp; YMask]
+///       : BlockTable[(y % BlockHeight) * BlockWidth + (x % BlockWidth)] * BytesPerElement;
+///   srcByte = ((y / BlockHeight) * BlocksPerRow + (x / BlockWidth)) * BlockBytes + inBlockByte;
+/// </code>
+/// </summary>
+internal readonly record struct DetileParams(
+    DetileEquation Equation,
+    int ElementsWide,
+    int ElementsHigh,
+    int BytesPerElement,
+    int BlockWidth,
+    int BlockHeight,
+    int BlockElements,
+    int BlockBytes,
+    int BlocksPerRow,
+    // ExactXor: within-block BYTE offset = XByteTerm[x & XMask] ^ YByteTerm[y & YMask].
+    int[] XByteTerm,
+    int XMask,
+    int[] YByteTerm,
+    int YMask,
+    // BlockTable: within-block ELEMENT offset = BlockTable[inBlockY * BlockWidth + inBlockX].
+    int[] BlockTable)
+{
+    /// <summary>False when the mode/format is not GPU-portable (Equation == None).</summary>
+    public bool IsSupported => Equation != DetileEquation.None;
+}
+
 /// <summary>
 /// Deswizzles RDNA2 (GFX10) tiled texture surfaces into linear layout so they
 /// can be uploaded to Vulkan. PS5 stores most textures in a swizzled layout
@@ -501,6 +550,141 @@ internal static unsafe class GnmTiling
        return true;
    }

+    /// <summary>
+    /// Computes the detile parameters for a surface without performing the copy,
+    /// so a GPU compute kernel can run the deswizzle instead of the CPU. Returns
+    /// <see cref="DetileParams.IsSupported"/> == false (Equation == None) when the
+    /// mode/format is not GPU-portable, so the caller keeps the CPU
+    /// <see cref="TryDetile"/> path or a raw upload. Reuses the same helpers and
+    /// caches as <see cref="TryDetile"/>, so the two never disagree on addressing.
+    /// </summary>
+    public static DetileParams GetDetileParams(
+        uint swizzleMode,
+        int bytesPerElement,
+        int elementsWide,
+        int elementsHigh)
+    {
+        if (!ShouldDetile(swizzleMode) ||
+            bytesPerElement <= 0 ||
+            elementsWide <= 0 ||
+            elementsHigh <= 0 ||
+            !TryGetSwizzleKind(swizzleMode, out var kind, out var blockBytes))
+        {
+            return default;
+        }
+
+        var bppLog2 = BitLog2((uint)bytesPerElement);
+        if (bppLog2 < 0)
+        {
+            return default;
+        }
+
+        var blockElements = blockBytes >> bppLog2;
+        var (blockWidth, blockHeight) = SquareBlockDimensions(blockElements);
+        if (blockWidth == 0 || blockHeight == 0)
+        {
+            return default;
+        }
+
+        var blocksPerRow = (elementsWide + blockWidth - 1) / blockWidth;
+
+        if (TryGetExactXorPattern(swizzleMode, bppLog2, out var pattern))
+        {
+            var terms = _patternTermCache.GetOrAdd(
+                (swizzleMode, bppLog2),
+                _ => CreatePatternTerms(pattern));
+            return new DetileParams(
+                DetileEquation.ExactXor,
+                elementsWide,
+                elementsHigh,
+                bytesPerElement,
+                blockWidth,
+                blockHeight,
+                blockElements,
+                blockBytes,
+                blocksPerRow,
+                terms.X,
+                terms.XMask,
+                terms.Y,
+                terms.YMask,
+                []);
+        }
+
+        var blockTable = _blockTableCache.GetOrAdd(
+            (kind, blockWidth, blockHeight),
+            static key => CreateBlockTable(key.Kind, key.Width, key.Height));
+        return new DetileParams(
+            DetileEquation.BlockTable,
+            elementsWide,
+            elementsHigh,
+            bytesPerElement,
+            blockWidth,
+            blockHeight,
+            blockElements,
+            blockBytes,
+            blocksPerRow,
+            [],
+            0,
+            [],
+            0,
+            blockTable);
+    }
+
+    /// <summary>
+    /// CPU deswizzle driven entirely by a resolved <see cref="DetileParams"/> — the
+    /// exact addressing the Vulkan/Metal compute kernel runs per texel, so a
+    /// backend that packaged <paramref name="parameters"/> for the GPU path can
+    /// fall back to this without re-deriving the swizzle. Copies
+    /// <c>ElementsWide * ElementsHigh</c> elements from <paramref name="tiled"/>
+    /// into <paramref name="linear"/>; returns false when unsupported or the output
+    /// span is too small. Out-of-range source elements are left zero (matching the
+    /// reference), so a truncated <paramref name="tiled"/> degrades gracefully.
+    /// </summary>
+    public static bool DetileWithParams(
+        in DetileParams parameters,
+        ReadOnlySpan<byte> tiled,
+        Span<byte> linear)
+    {
+        if (!parameters.IsSupported)
+        {
+            return false;
+        }
+
+        var width = parameters.ElementsWide;
+        var height = parameters.ElementsHigh;
+        var bpp = parameters.BytesPerElement;
+        var requiredLinear = (long)width * height * bpp;
+        if (width <= 0 || height <= 0 || bpp <= 0 || linear.Length < requiredLinear)
+        {
+            return false;
+        }
+
+        var isExactXor = parameters.Equation == DetileEquation.ExactXor;
+        for (var y = 0; y < height; y++)
+        {
+            var blockY = y / parameters.BlockHeight;
+            var inY = y % parameters.BlockHeight;
+            var yTerm = isExactXor ? parameters.YByteTerm[y & parameters.YMask] : 0;
+            for (var x = 0; x < width; x++)
+            {
+                var blockX = x / parameters.BlockWidth;
+                var inBlockByte = isExactXor
+                    ? parameters.XByteTerm[x & parameters.XMask] ^ yTerm
+                    : parameters.BlockTable[inY * parameters.BlockWidth + (x % parameters.BlockWidth)] * bpp;
+                var srcByte = ((long)blockY * parameters.BlocksPerRow + blockX) * parameters.BlockBytes + inBlockByte;
+                var dstByte = ((long)y * width + x) * bpp;
+                if (srcByte < 0 || srcByte + bpp > tiled.Length)
+                {
+                    continue;
+                }
+
+                tiled.Slice((int)srcByte, bpp).CopyTo(linear.Slice((int)dstByte, bpp));
+            }
+        }
+
+        return true;
+    }
+
    private enum SwizzleKind
    {
        Standard,