sharpemu/src/SharpEmu.Libs/Agc/GnmTiling.cs

// Copyright (C) 2026 SharpEmu Emulator Project
// SPDX-License-Identifier: GPL-2.0-or-later

using System.Collections.Concurrent;
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 1/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
/// selected by the 5-bit SWIZZLE_MODE in the image descriptor; uploading those
/// bytes verbatim samples as garbage.
///
/// The GFX10 addressing uses power-of-two swizzle blocks (256 B / 4 KiB /
/// 64 KiB) whose internal element order follows the standard (S), display (D),
/// render (R), or z-order/depth (Z) equations. This implements the exact base
/// S and Z 2D single-sample modes plus the PS5's RB+ 64 KiB Z_X/R_X equations;
/// other D/R and pipe/bank-XOR modes stay opt-in while their complete AddrLib
/// equations are being ported.
/// </summary>
internal static unsafe class GnmTiling
{
    private const int ParallelDetileElementThreshold = 512 * 512;
    private const int MaxDetileWorkers = 4;

    // Oberon uses the 16-pipe / 8-pixel-packer RB+ topology. These are the
    // single-sample 64 KiB equations generated by AMD AddrLib for that exact
    // topology. Each entry describes one address bit as an XOR of X/Y bits.
    private readonly record struct AddressBit(uint XMask, uint YMask);

    private static readonly AddressBit[][] RbPlus64KRenderX =
    [
        // 1 byte/element: nibble01=0, nibble2=307, nibble3=379.
        [X(0), X(1), X(2), X(3), Y(0), Y(1), Y(2), Y(3),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(6), Y(6), XY(7, 8), XY(8, 7)],
        // 2 bytes/element: nibble01=1, nibble2=307, nibble3=389.
        [Zero, X(0), X(1), X(2), Y(0), Y(1), Y(2), X(3),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         Y(3), X(6), XY(7, 7), XY(8, 6)],
        // 4 bytes/element: nibble01=39, nibble2=307, nibble3=381.
        [Zero, Zero, X(0), X(1), Y(0), Y(1), X(2), Y(2),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(3), Y(3), XY(6, 7), XY(7, 6)],
        // 8 bytes/element: nibble01=6, nibble2=307, nibble3=382.
        [Zero, Zero, Zero, X(0), Y(0), X(1), X(2), Y(1),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         Y(2), X(3), XY(7, 3), XY(6, 6)],
        // 16 bytes/element: nibble01=7, nibble2=307, nibble3=390.
        [Zero, Zero, Zero, Zero, X(0), Y(0), X(1), Y(1),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(2), Y(2), XY(6, 3), XY(3, 6)],
    ];

    private static readonly AddressBit[][] RbPlus64KDepthX =
    [
        // 1 byte/element: nibble01=8, nibble2=306, nibble3=379.
        [X(0), Y(0), X(1), Y(1), X(2), Y(2), X(3), Y(3),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(6), Y(6), XY(7, 8), XY(8, 7)],
        // 2 bytes/element: nibble01=9, nibble2=306, nibble3=389.
        [Zero, X(0), Y(0), X(1), Y(1), X(2), Y(2), X(3),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         Y(3), X(6), XY(7, 7), XY(8, 6)],
        // 4 bytes/element: nibble01=10, nibble2=306, nibble3=381.
        [Zero, Zero, X(0), Y(0), X(1), Y(1), X(2), Y(2),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(3), Y(3), XY(6, 7), XY(7, 6)],
        // 8 bytes/element: nibble01=11, nibble2=307, nibble3=382.
        [Zero, Zero, Zero, X(0), Y(0), X(1), Y(1), X(2),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         Y(2), X(3), XY(7, 3), XY(6, 6)],
        // 16 bytes/element is identical to R_X for a 2D single-sample image.
        [Zero, Zero, Zero, Zero, X(0), Y(0), X(1), Y(1),
         XY(7, 4, 7), XY(4, 4), XY(6, 5), XY(5, 6),
         X(2), Y(2), XY(6, 3), XY(3, 6)],
    ];

    private static readonly AddressBit[][] RbPlus64KStandard =
    [
        // GFX10_SW_64K_S_RBPLUS_PATINFO, 1 byte/element.
        [X(0), X(1), X(2), X(3), Y(0), Y(1), Y(2), Y(3),
         Y(4), X(4), Y(5), X(5), Y(6), X(6), Y(7), X(7)],
        // 2 bytes/element.
        [Zero, X(0), X(1), X(2), Y(0), Y(1), Y(2), X(3),
         Y(3), X(4), Y(4), X(5), Y(5), X(6), Y(6), X(7)],
        // 4 bytes/element.
        [Zero, Zero, X(0), X(1), Y(0), Y(1), Y(2), X(2),
         Y(3), X(3), Y(4), X(4), Y(5), X(5), Y(6), X(6)],
        // 8 bytes/element (also BC1/BC4 compressed blocks).
        [Zero, Zero, Zero, X(0), Y(0), Y(1), X(1), X(2),
         Y(2), X(3), Y(3), X(4), Y(4), X(5), Y(5), X(6)],
        // 16 bytes/element (also 16-byte BC compressed blocks).
        [Zero, Zero, Zero, Zero, Y(0), Y(1), X(0), X(1),
         Y(2), X(2), Y(3), X(3), Y(4), X(4), Y(5), X(5)],
    ];

    // GFX10 256B_S: 8-bit micro-tile equation (low octet of the 4K_S pattern).
    // The generic StandardSwizzle bit-interleave is a different layout and leaves
    // a broken grid on Gen5 UI atlases that ship as Standard256B.
    private static readonly AddressBit[][] Standard256 =
    [
        [X(0), X(1), X(2), X(3), Y(0), Y(1), Y(2), Y(3)],
        [Zero, X(0), X(1), X(2), Y(0), Y(1), Y(2), X(3)],
        [Zero, Zero, X(0), X(1), Y(0), Y(1), Y(2), X(2)],
        [Zero, Zero, Zero, X(0), Y(0), Y(1), X(1), X(2)],
        [Zero, Zero, Zero, Zero, Y(0), Y(1), X(0), X(1)],
    ];

    // GFX10 4K_S has a separate 12-bit micro-tile equation. It is not the
    // generic x/y interleave used by the 64K standard block; using that larger
    // equation leaves a regular grid in linearized atlases.
    private static readonly AddressBit[][] Standard4K =
    [
        [X(0), X(1), X(2), X(3), Y(0), Y(1), Y(2), Y(3),
         Y(4), X(4), Y(5), X(5)],
        [Zero, X(0), X(1), X(2), Y(0), Y(1), Y(2), X(3),
         Y(3), X(4), Y(4), X(5)],
        [Zero, Zero, X(0), X(1), Y(0), Y(1), Y(2), X(2),
         Y(3), X(3), Y(4), X(4)],
        [Zero, Zero, Zero, X(0), Y(0), Y(1), X(1), X(2),
         Y(2), X(3), Y(3), X(4)],
        [Zero, Zero, Zero, Zero, Y(0), Y(1), X(0), X(1),
         Y(2), X(2), Y(3), X(3)],
    ];

    private static readonly bool _enabled = string.Equals(
        Environment.GetEnvironmentVariable("SHARPEMU_DETILE"),
        "1",
        StringComparison.Ordinal);

    private static readonly bool _disabled = string.Equals(
        Environment.GetEnvironmentVariable("SHARPEMU_DETILE"),
        "0",
        StringComparison.Ordinal);

    private static readonly HashSet<uint> _reportedModes = new();
    private static readonly ConcurrentDictionary<(uint SwizzleMode, int BppLog2), PatternTerms>
        _patternTermCache = new();
    private static readonly ConcurrentDictionary<(SwizzleKind Kind, int Width, int Height), int[]>
        _blockTableCache = new();
    private static readonly ParallelOptions _parallelDetileOptions = new()
    {
        MaxDegreeOfParallelism = Math.Min(MaxDetileWorkers, Environment.ProcessorCount),
    };

    public static bool Enabled => _enabled || !_disabled;

    /// <summary>
    /// Base S/Z modes and the Oberon RB+ 64 KiB Z_X/R_X modes for which this
    /// implementation carries the exact AddrLib address equations. Other
    /// bank/pipe-XOR variants remain opt-in.
    /// </summary>
    private static bool IsTrustedByDefault(uint swizzleMode) =>
        // Exact base S/Z modes. D/R use different GFX10 swizzle equations and
        // the T/X modes additionally apply pipe/bank XOR between blocks.
        swizzleMode is 1 or 4 or 5 or 8 or 9 or 24 or 27;

    // Detile a surface when it is verified-correct by default (trusted base mode),
    // or when the user opts the approximate modes in with SHARPEMU_DETILE=1.
    // SHARPEMU_DETILE=0 forces the old raw-upload behavior for everything.
    private static bool ShouldDetile(uint swizzleMode) =>
        swizzleMode != 0 && !_disabled && (_enabled || IsTrustedByDefault(swizzleMode));

    /// <summary>
    /// True when a surface with the given swizzle mode needs deswizzling.
    /// Mode 0 is linear and never needs it.
    /// </summary>
    public static bool NeedsDetile(uint swizzleMode) => ShouldDetile(swizzleMode);

    /// <summary>
    /// Gets the physical byte span occupied by a tiled mip. GNM allocates whole
    /// swizzle blocks even when the logical image is much smaller than a block;
    /// reading only the logical texel count truncates most source offsets during
    /// detiling (a 64x64 BC1 mode-9 image is 2 KiB logically but occupies one
    /// 64 KiB swizzle block).
    /// </summary>
    public static bool TryGetTiledByteCount(
        uint swizzleMode,
        int elementsWide,
        int elementsHigh,
        int bytesPerElement,
        out ulong byteCount)
    {
        byteCount = 0;
        if (!ShouldDetile(swizzleMode) ||
            elementsWide <= 0 ||
            elementsHigh <= 0 ||
            bytesPerElement <= 0 ||
            !TryGetSwizzleKind(swizzleMode, out _, out var blockBytes))
        {
            return false;
        }

        var bppLog2 = BitLog2((uint)bytesPerElement);
        if (bppLog2 < 0)
        {
            return false;
        }

        var blockElements = blockBytes >> bppLog2;
        var (blockWidth, blockHeight) = SquareBlockDimensions(blockElements);
        if (blockWidth == 0 || blockHeight == 0)
        {
            return false;
        }

        var blocksWide = ((ulong)elementsWide + (ulong)blockWidth - 1) / (ulong)blockWidth;
        var blocksHigh = ((ulong)elementsHigh + (ulong)blockHeight - 1) / (ulong)blockHeight;
        try
        {
            byteCount = checked(blocksWide * blocksHigh * (ulong)blockBytes);
            return true;
        }
        catch (OverflowException)
        {
            byteCount = 0;
            return false;
        }
    }

    public static bool TryGetBlockElementDimensions(
        uint swizzleMode,
        int bytesPerElement,
        out int blockWidth,
        out int blockHeight)
    {
        blockWidth = 0;
        blockHeight = 0;
        if (bytesPerElement <= 0 ||
            !TryGetSwizzleKind(swizzleMode, out _, out var blockBytes))
        {
            return false;
        }

        var bppLog2 = BitLog2((uint)bytesPerElement);
        if (bppLog2 < 0)
        {
            return false;
        }

        (blockWidth, blockHeight) = SquareBlockDimensions(blockBytes >> bppLog2);
        return blockWidth != 0 && blockHeight != 0;
    }

    /// <summary>
    /// Locates mip 0 in a GFX10 mip chain, which AddrLib stores smallest-first
    /// (Gfx10Lib::ComputeSurfaceInfoMacroTiled/MicroTiled).
    /// </summary>
    public static bool TryGetBaseMipPlacement(
        uint swizzleMode,
        int elementsWide,
        int elementsHigh,
        int bytesPerElement,
        uint resourceMipLevels,
        out ulong byteOffset,
        out bool inMipTail,
        out int tailElementX,
        out int tailElementY,
        out ulong chainSliceBytes)
    {
        byteOffset = 0;
        inMipTail = false;
        tailElementX = 0;
        tailElementY = 0;
        chainSliceBytes = 0;
        if (resourceMipLevels <= 1 ||
            !ShouldDetile(swizzleMode) ||
            elementsWide <= 0 ||
            elementsHigh <= 0 ||
            bytesPerElement <= 0 ||
            !TryGetSwizzleKind(swizzleMode, out _, out var blockBytes))
        {
            return false;
        }

        var bppLog2 = BitLog2((uint)bytesPerElement);
        if (bppLog2 < 0)
        {
            return false;
        }

        var (blockWidth, blockHeight) = SquareBlockDimensions(blockBytes >> bppLog2);
        var blockSizeLog2 = BitLog2((uint)blockBytes);
        if (blockWidth == 0 || blockHeight == 0 || blockSizeLog2 < 8)
        {
            return false;
        }

        var mipLevels = (int)Math.Min(resourceMipLevels, 16u);
        var maxMipsInTail = blockSizeLog2 <= 8 ? 0
            : blockSizeLog2 <= 11
                ? 1 + (1 << (blockSizeLog2 - 9))
                : blockSizeLog2 - 4;
        var tailWidth = (blockSizeLog2 & 1) != 0 ? blockWidth >> 1 : blockWidth;
        var tailHeight = (blockSizeLog2 & 1) != 0 ? blockHeight : blockHeight >> 1;

        var firstMipInTail = mipLevels;
        var mipSizes = new ulong[mipLevels];
        for (var i = 0; i < mipLevels; i++)
        {
            var mipWidth = Math.Max(elementsWide >> i, 1);
            var mipHeight = Math.Max(elementsHigh >> i, 1);
            if (maxMipsInTail > 0 &&
                mipWidth <= tailWidth &&
                mipHeight <= tailHeight &&
                mipLevels - i <= maxMipsInTail)
            {
                firstMipInTail = i;
                break;
            }

            var alignedWidth = (ulong)(mipWidth + blockWidth - 1) / (ulong)blockWidth * (ulong)blockWidth;
            var alignedHeight = (ulong)(mipHeight + blockHeight - 1) / (ulong)blockHeight * (ulong)blockHeight;
            mipSizes[i] = alignedWidth * alignedHeight * (ulong)bytesPerElement;
        }

        if (firstMipInTail == 0)
        {
            var m = maxMipsInTail - 1;
            var mipOffset = m > 6 ? 16 << m : m << 8;
            var mipX = ((mipOffset >> 9) & 1) |
                       ((mipOffset >> 10) & 2) |
                       ((mipOffset >> 11) & 4) |
                       ((mipOffset >> 12) & 8) |
                       ((mipOffset >> 13) & 16) |
                       ((mipOffset >> 14) & 32);
            var mipY = ((mipOffset >> 8) & 1) |
                       ((mipOffset >> 9) & 2) |
                       ((mipOffset >> 10) & 4) |
                       ((mipOffset >> 11) & 8) |
                       ((mipOffset >> 12) & 16) |
                       ((mipOffset >> 13) & 32);
            if ((blockSizeLog2 & 1) != 0)
            {
                (mipX, mipY) = (mipY, mipX);
                if ((bppLog2 & 1) != 0)
                {
                    mipY = (mipY << 1) | (mipX & 1);
                    mipX >>= 1;
                }
            }

            var (microWidth, microHeight) = SquareBlockDimensions(256 >> bppLog2);
            if (microWidth == 0 || microHeight == 0)
            {
                return false;
            }

            tailElementX = mipX * microWidth;
            tailElementY = mipY * microHeight;
            if (tailElementX + elementsWide > blockWidth ||
                tailElementY + elementsHigh > blockHeight)
            {
                tailElementX = 0;
                tailElementY = 0;
                return false;
            }

            inMipTail = true;
            chainSliceBytes = (ulong)blockBytes;
            return true;
        }

        byteOffset = firstMipInTail < mipLevels ? (ulong)blockBytes : 0;
        chainSliceBytes = byteOffset;
        for (var i = firstMipInTail - 1; i >= 1; i--)
        {
            byteOffset += mipSizes[i];
        }

        for (var i = 0; i < firstMipInTail; i++)
        {
            chainSliceBytes += mipSizes[i];
        }

        return true;
    }

    /// <summary>
    /// Deswizzles <paramref name="tiled"/> into linear row-major order.
    /// Elements are pixels for uncompressed formats and 4x4 blocks for
    /// block-compressed formats, so callers pass the element grid dimensions
    /// and the bytes per element. Returns false (leaving output untouched) for
    /// unsupported swizzle modes so the caller can fall back to the raw bytes.
    /// </summary>
    public static bool TryDetile(
        ReadOnlySpan<byte> tiled,
        Span<byte> linear,
        uint swizzleMode,
        int elementsWide,
        int elementsHigh,
        int bytesPerElement)
    {
        if (!ShouldDetile(swizzleMode) || elementsWide <= 0 || elementsHigh <= 0 || bytesPerElement <= 0)
        {
            return false;
        }

        if (!TryGetSwizzleKind(swizzleMode, out var kind, out var blockBytes))
        {
            ReportUnsupported(swizzleMode);
            return false;
        }

        var bppLog2 = BitLog2((uint)bytesPerElement);
        if (bppLog2 < 0)
        {
            // Non-power-of-two element size (e.g. 24-bit) is not swizzled in a
            // way this equation models.
            ReportUnsupported(swizzleMode);
            return false;
        }

        // Block dimensions in elements: a swizzle block holds blockBytes bytes,
        // laid out as a square-ish power-of-two element grid scaled by bpp.
        var blockElements = blockBytes >> bppLog2;
        var (blockWidth, blockHeight) = SquareBlockDimensions(blockElements);
        if (blockWidth == 0 || blockHeight == 0)
        {
            ReportUnsupported(swizzleMode);
            return false;
        }

        var blocksPerRow = (elementsWide + blockWidth - 1) / blockWidth;
        var requiredLinear = (long)elementsWide * elementsHigh * bytesPerElement;
        if (linear.Length < requiredLinear)
        {
            return false;
        }

        // Address tables depend only on the swizzle equation and element size,
        // so retain them across textures instead of rebuilding them per upload.
        var hasExactXorPattern = TryGetExactXorPattern(swizzleMode, bppLog2, out var xorPattern);
        var patternTerms = hasExactXorPattern
            ? _patternTermCache.GetOrAdd(
                (swizzleMode, bppLog2),
                _ => CreatePatternTerms(xorPattern))
            : default;
        var blockTable = hasExactXorPattern
            ? []
            : _blockTableCache.GetOrAdd(
                (kind, blockWidth, blockHeight),
                static key => CreateBlockTable(key.Kind, key.Width, key.Height));

        // The XOR equation offset factors cleanly into independent X and Y
        // fields — each output bit is parity(x & XMask) XOR parity(y & YMask),
        // and parity distributes over XOR, so offset(x, y) == xTerm(x) ^ yTerm(y).
        // Exact equations repeat at a small power-of-two period. Cached axis
        // terms reduce the inner loop to two array loads and one XOR.
        fixed (byte* tiledPointer = tiled)
        fixed (byte* linearPointer = linear)
        {
            var sourceAddress = (nint)tiledPointer;
            var destinationAddress = (nint)linearPointer;
            var sourceLength = tiled.Length;
            var destinationLength = linear.Length;
            var blockWidthShift = BitLog2((uint)blockWidth);
            var blockWidthMask = blockWidth - 1;
            var detileRow = (int y) =>
            {
                var blockY = y / blockHeight;
                var inBlockY = y & (blockHeight - 1);
                var rowBlockBase = (long)blockY * blocksPerRow;
                var tableRowBase = inBlockY * blockWidth;
                var destRowBase = (long)y * elementsWide * bytesPerElement;
                var yTerm = hasExactXorPattern
                    ? patternTerms.Y[y & patternTerms.YMask]
                    : 0;
                for (var x = 0; x < elementsWide; x++)
                {
                    var blockX = x >> blockWidthShift;
                    var inBlockX = x & blockWidthMask;
                    var blockIndex = rowBlockBase + blockX;
                    var sourceByte = hasExactXorPattern
                        ? blockIndex * blockBytes + (patternTerms.X[x & patternTerms.XMask] ^ yTerm)
                        : (blockIndex * blockElements + blockTable[tableRowBase + inBlockX]) *
                          (long)bytesPerElement;
                    var destByte = destRowBase + (long)x * bytesPerElement;
                    if (sourceByte < 0 ||
                        sourceByte + bytesPerElement > sourceLength ||
                        destByte + bytesPerElement > destinationLength)
                    {
                        continue;
                    }

                    CopyElement(
                        (byte*)sourceAddress + sourceByte,
                        (byte*)destinationAddress + destByte,
                        bytesPerElement);
                }
            };

            var elementCount = (long)elementsWide * elementsHigh;
            if (elementCount >= ParallelDetileElementThreshold && Environment.ProcessorCount > 1)
            {
                Parallel.For(
                    0,
                    elementsHigh,
                    _parallelDetileOptions,
                    detileRow);
            }
            else
            {
                for (var y = 0; y < elementsHigh; y++)
                {
                    detileRow(y);
                }
            }
        }

        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,
        ZOrder,
    }

    private readonly record struct PatternTerms(int[] X, int XMask, int[] Y, int YMask);

    private static PatternTerms CreatePatternTerms(AddressBit[] pattern)
    {
        uint xMask = 0;
        uint yMask = 0;
        foreach (var bit in pattern)
        {
            xMask |= bit.XMask;
            yMask |= bit.YMask;
        }

        var xLength = AxisTermPeriod(xMask);
        var yLength = AxisTermPeriod(yMask);
        var xTerms = new int[xLength];
        var yTerms = new int[yLength];
        for (var x = 0; x < xTerms.Length; x++)
        {
            xTerms[x] = (int)PatternAxisTerm((uint)x, pattern, useX: true);
        }

        for (var y = 0; y < yTerms.Length; y++)
        {
            yTerms[y] = (int)PatternAxisTerm((uint)y, pattern, useX: false);
        }

        return new PatternTerms(xTerms, xLength - 1, yTerms, yLength - 1);
    }

    private static int AxisTermPeriod(uint mask) =>
        mask == 0 ? 1 : 1 << (32 - System.Numerics.BitOperations.LeadingZeroCount(mask));

    private static int[] CreateBlockTable(SwizzleKind kind, int blockWidth, int blockHeight)
    {
        var table = new int[blockWidth * blockHeight];
        for (var y = 0; y < blockHeight; y++)
        {
            for (var x = 0; x < blockWidth; x++)
            {
                table[y * blockWidth + x] = (int)(kind == SwizzleKind.ZOrder
                    ? MortonInterleave((uint)x, (uint)y, blockWidth, blockHeight)
                    : StandardSwizzleOffset((uint)x, (uint)y, blockWidth, blockHeight));
            }
        }

        return table;
    }

    [MethodImpl(MethodImplOptions.AggressiveInlining)]
    private static void CopyElement(byte* source, byte* destination, int bytesPerElement)
    {
        switch (bytesPerElement)
        {
            case 1:
                *destination = *source;
                break;
            case 2:
                Unsafe.WriteUnaligned(destination, Unsafe.ReadUnaligned<ushort>(source));
                break;
            case 4:
                Unsafe.WriteUnaligned(destination, Unsafe.ReadUnaligned<uint>(source));
                break;
            case 8:
                Unsafe.WriteUnaligned(destination, Unsafe.ReadUnaligned<ulong>(source));
                break;
            case 16:
                Unsafe.WriteUnaligned(destination, Unsafe.ReadUnaligned<UInt128>(source));
                break;
            default:
                Unsafe.CopyBlockUnaligned(destination, source, (uint)bytesPerElement);
                break;
        }
    }

    private static readonly AddressBit Zero = new(0, 0);

    private static AddressBit X(int bit) => new(1u << bit, 0);

    private static AddressBit Y(int bit) => new(0, 1u << bit);

    private static AddressBit XY(int xBit, int yBit) => new(1u << xBit, 1u << yBit);

    private static AddressBit XY(int xBit, int yBit1, int yBit2) =>
        new(1u << xBit, (1u << yBit1) | (1u << yBit2));

    private static bool TryGetExactXorPattern(
        uint swizzleMode,
        int bytesPerElementLog2,
        out AddressBit[] pattern)
    {
        pattern = [];
        if ((uint)bytesPerElementLog2 >= RbPlus64KRenderX.Length)
        {
            return false;
        }

        pattern = swizzleMode switch
        {
            1 => Standard256[bytesPerElementLog2],
            5 => Standard4K[bytesPerElementLog2],
            9 => RbPlus64KStandard[bytesPerElementLog2],
            24 => RbPlus64KDepthX[bytesPerElementLog2],
            27 => RbPlus64KRenderX[bytesPerElementLog2],
            _ => [],
        };
        return pattern.Length != 0;
    }

    // The AddrLib within-block byte offset is a per-bit XOR equation:
    //   offset = OR over bits of ( parity(x & XMask) XOR parity(y & YMask) ) << bit
    // Because parity distributes over XOR, that whole offset factors into two
    // independent axis terms: PatternAxisTerm(x, useX: true) ^
    // PatternAxisTerm(y, useX: false). Splitting the axes lets TryDetile cache
    // the X term per column and hoist the Y term per row instead of recomputing
    // the full 16-bit interleave (32 PopCounts) for every element.
    private static uint PatternAxisTerm(uint coordinate, AddressBit[] pattern, bool useX)
    {
        uint offset = 0;
        for (var bit = 0; bit < pattern.Length; bit++)
        {
            var mask = useX ? pattern[bit].XMask : pattern[bit].YMask;
            var parity = System.Numerics.BitOperations.PopCount(coordinate & mask) & 1;
            offset |= (uint)parity << bit;
        }

        return offset;
    }

    private static bool TryGetSwizzleKind(uint swizzleMode, out SwizzleKind kind, out int blockBytes)
    {
        // GFX10 AddrLib SWIZZLE_MODE enumeration:
        //   1-3   = 256 B S/D/R
        //   4-7   = 4 KiB Z/S/D/R
        //   8-11  = 64 KiB Z/S/D/R
        //   16-19 = 64 KiB Z/S/D/R _T
        //   20-23 = 4 KiB Z/S/D/R _X
        //   24-27 = 64 KiB Z/S/D/R _X
        // The pipe/bank XOR (_T/_X) affects which block a given tile lands in,
        // but the *within-block* element order matches the base S/Z equation,
        // which is what dominates visible correctness. We model the block
        // interior and treat blocks as linear-ordered.
        kind = SwizzleKind.Standard;
        blockBytes = 0;
        switch (swizzleMode)
        {
            case 4: case 8: case 16: case 20: case 24:
                kind = SwizzleKind.ZOrder;
                break;
            case 1: case 2: case 3:
            case 5: case 6: case 7:
            case 9: case 10: case 11:
            case 17: case 18: case 19:
            case 21: case 22: case 23:
            case 25: case 26: case 27:
                kind = SwizzleKind.Standard;
                break;
            default:
                return false;
        }

        blockBytes = swizzleMode switch
        {
            >= 1 and <= 3 => 256,
            >= 4 and <= 7 => 4096,
            >= 20 and <= 23 => 4096,
            _ => 65536,
        };
        return true;
    }

    // Standard (S) 2D swizzle: within a block, the element order interleaves x
    // and y bits with x taking the low bit — the AMD "standard" microtile.
    private static long StandardSwizzleOffset(uint x, uint y, int blockWidth, int blockHeight)
    {
        var widthBits = BitLog2((uint)blockWidth);
        var heightBits = BitLog2((uint)blockHeight);
        long offset = 0;
        var outBit = 0;
        var xi = 0;
        var yi = 0;
        while (xi < widthBits || yi < heightBits)
        {
            if (xi < widthBits)
            {
                offset |= (long)((x >> xi) & 1u) << outBit++;
                xi++;
            }

            if (yi < heightBits)
            {
                offset |= (long)((y >> yi) & 1u) << outBit++;
                yi++;
            }
        }

        return offset;
    }

    // Z-order (Morton) swizzle: pure bit interleave, y taking the low bit.
    private static long MortonInterleave(uint x, uint y, int blockWidth, int blockHeight)
    {
        var widthBits = BitLog2((uint)blockWidth);
        var heightBits = BitLog2((uint)blockHeight);
        long offset = 0;
        var outBit = 0;
        var xi = 0;
        var yi = 0;
        while (xi < widthBits || yi < heightBits)
        {
            if (yi < heightBits)
            {
                offset |= (long)((y >> yi) & 1u) << outBit++;
                yi++;
            }

            if (xi < widthBits)
            {
                offset |= (long)((x >> xi) & 1u) << outBit++;
                xi++;
            }
        }

        return offset;
    }

    private static (int Width, int Height) SquareBlockDimensions(int blockElements)
    {
        if (blockElements <= 0 || (blockElements & (blockElements - 1)) != 0)
        {
            return (0, 0);
        }

        var totalBits = BitLog2((uint)blockElements);
        // Split as evenly as possible with width >= height (x gets the extra bit).
        var widthBits = (totalBits + 1) / 2;
        var heightBits = totalBits - widthBits;
        return (1 << widthBits, 1 << heightBits);
    }

    private static int BitLog2(uint value)
    {
        if (value == 0 || (value & (value - 1)) != 0)
        {
            return -1;
        }

        return System.Numerics.BitOperations.TrailingZeroCount(value);
    }

    private static void ReportUnsupported(uint swizzleMode)
    {
        lock (_reportedModes)
        {
            if (!_reportedModes.Add(swizzleMode))
            {
                return;
            }
        }

        Console.Error.WriteLine(
            $"[LOADER][WARN] GNM detile: unsupported swizzle mode {swizzleMode}; texture uploaded linear.");
    }
}