[Refactor] (MG_Config, DirectVulkan): route the blended depth-write quirk through the FeaturesTable as MOBILEGL_MAGMA_DISABLE_BLENDED_DEPTH_WRITE instead of an ad-hoc getenv

.github/scripts/fetch-trace-fixture-lfs.sh

@@ -9,7 +9,23 @@ fi
 case_name="$1"
 fixture_dir="${2:-tools/trace_replay/fixtures}"
 python_bin="${PYTHON:-python3}"
-mirror_base="${MOBILEGL_TRACE_FIXTURE_MIRROR_BASE:-https://repo.miawa.cn/mgl/tools/trace_replay/fixtures}"
+# Fixture mirrors, tried in order before falling back to Git LFS. Override the
+# whole list with MOBILEGL_TRACE_FIXTURE_MIRROR_BASES (whitespace separated);
+# MOBILEGL_TRACE_FIXTURE_MIRROR_BASE still works and is tried first.
+default_mirror_bases=(
+  "https://git.hit.moe/swung0x48/MobileGL/media/branch/dev/tools/trace_replay/fixtures"
+  "https://repo.miawa.cn/mgl/tools/trace_replay/fixtures"
+)
+if [ -n "${MOBILEGL_TRACE_FIXTURE_MIRROR_BASES:-}" ]; then
+  read -r -a mirror_bases <<< "${MOBILEGL_TRACE_FIXTURE_MIRROR_BASES}"
+else
+  mirror_bases=("${default_mirror_bases[@]}")
+fi
+if [ -n "${MOBILEGL_TRACE_FIXTURE_MIRROR_BASE:-}" ]; then
+  mirror_bases=("${MOBILEGL_TRACE_FIXTURE_MIRROR_BASE}" "${mirror_bases[@]}")
+fi
+# Optional bearer token for mirrors that require authentication (private Gitea).
+mirror_token="${MOBILEGL_TRACE_FIXTURE_MIRROR_TOKEN:-}"
 download_attempts="${MOBILEGL_TRACE_FIXTURE_DOWNLOAD_ATTEMPTS:-5}"
 retry_delay="${MOBILEGL_TRACE_FIXTURE_RETRY_DELAY:-2}"
 
@@ -30,7 +46,8 @@ fixture_list="$("${python_bin}" tools/trace_replay/trace_cases.py \
   --format fixture-files \
   --case "${case_name}" \
   --fixture-root "${fixture_dir}")"
-mapfile -t files <<< "${fixture_list}"
+# Strip CR so the script also works when python emits CRLF (Git Bash on Windows).
+mapfile -t files < <(printf '%s\n' "${fixture_list}" | tr -d '\r')
 
 include="$(IFS=,; echo "${files[*]}")"
 if [ "${case_name}" = "OpenRA" ]; then
@@ -106,6 +123,7 @@ fetch_file_from_mirror() {
   local attempt
   local partial_size
   local curl_status
+  local curl_auth
 
   metadata="$(get_lfs_metadata "${file}")" || return 1
   read -r expected_oid expected_size <<< "${metadata}"
@@ -136,7 +154,11 @@ fetch_file_from_mirror() {
       echo "Starting mirror download for ${file} (attempt ${attempt}/${download_attempts})"
     fi
 
-    if curl -L --fail --show-error --continue-at - --output "${tmp_file}" "${url}"; then
+    curl_auth=()
+    if [ -n "${mirror_token}" ]; then
+      curl_auth=(--header "Authorization: token ${mirror_token}")
+    fi
+    if curl -L --fail --show-error --continue-at - "${curl_auth[@]}" --output "${tmp_file}" "${url}"; then
       if verify_fixture_file "${tmp_file}" "${file}" "${expected_oid}" "${expected_size}"; then
         mv "${tmp_file}" "${file}"
         return 0
@@ -184,10 +206,19 @@ fetch_from_mirror() {
   for file in "${files[@]}"; do
     local name
     local url
+    local base
+    local fetched=0
     name="$(basename "${file}")"
-    url="${mirror_base%/}/${name}"
+    for base in "${mirror_bases[@]}"; do
-    echo "Fetching trace fixture from mirror: ${url}"
+      url="${base%/}/${name}"
-    if ! fetch_file_from_mirror "${file}" "${url}"; then
+      echo "Fetching trace fixture from mirror: ${url}"
+      if fetch_file_from_mirror "${file}" "${url}"; then
+        fetched=1
+        break
+      fi
+      echo "Mirror did not serve ${name}; trying the next mirror" >&2
+    done
+    if [ "${fetched}" -ne 1 ]; then
       return 1
     fi
   done
@@ -196,7 +227,7 @@ fetch_from_mirror() {
 if fetch_from_mirror; then
   echo "Fetched trace fixture files for ${case_name} from mirror: ${include}"
 else
-  echo "Mirror fetch failed for ${case_name}; falling back to Git LFS: ${include}"
+  echo "All mirrors failed for ${case_name}; falling back to Git LFS: ${include}"
   git lfs install --local
   git lfs pull --include="${include}" --exclude=""
 fi

MobileGL/Config.h

@@ -20,6 +20,15 @@ namespace MobileGL::MG_Config {
 
     extern BackendType ActiveBackendType;
 
+    // Tri-state override for device-specific quirks: Auto lets the detected device decide,
+    // ForceOn/ForceOff bypass the detection in either direction. ForceOn only bypasses the
+    // device gate - each quirk keeps its structural safety checks.
+    enum class QuirkOverride : Uint8 {
+        Auto = 0,
+        ForceOn,
+        ForceOff,
+    };
+
     // Feature toggles parsed once from environment variables in MG_ConfigLoader::Init()
     // (ConfigLoader.cpp), before the accepted-env map is destroyed. All Bool fields share
     // one truthy rule: the variable is set, non-empty, not "0", and not "false"
@@ -67,6 +76,19 @@ namespace MobileGL::MG_Config {
         // explicitly request a core profile via EGL_CONTEXT_OPENGL_PROFILE_MASK / a >=3.1
         // version request.
         Bool RelaxedSemantics = false;
+        // MOBILEGL_QUIRK_SUBGROUP_PREFIX_SCAN: overrides the shader-source quirk that
+        // rewrites the recognized workgroup prefix-scan template on Qualcomm devices with
+        // subgroups wider than 32 lanes (see ShaderSourceProcessor's quirk registry).
+        QuirkOverride SubgroupPrefixScanQuirk = QuirkOverride::Auto;
+        // MOBILEGL_MAGMA_DISABLE_BLENDED_DEPTH_WRITE: overrides the DirectVulkan quirk that
+        // strips depth writes from blended pipelines on drivers without cross-pipeline
+        // vertex position invariance (see VulkanRenderer's PipelineFactory setup). Auto
+        // detects Qualcomm.
+        QuirkOverride MagmaDisableBlendedDepthWriteQuirk = QuirkOverride::Auto;
+        // MOBILEGL_DISABLE_ROBUST_BUFFER_ACCESS: leave the Vulkan robustBufferAccess device
+        // feature off. It is enabled by default to match GL's defined out-of-range fetch
+        // behavior; this escape hatch exists to measure or dodge its GPU cost on a device.
+        Bool DisableRobustBufferAccess = false;
     };
     extern FeaturesTable Features;
 } // namespace MobileGL::MG_Config

MobileGL/ConfigLoader.cpp

@@ -86,6 +86,17 @@ namespace MobileGL::MG_ConfigLoader {
         return it != acceptedEnvVariablesMap->end() && IsTruthyValue(it->second);
     }
 
+    // Quirk overrides are tri-state: an unset variable keeps device auto-detection, a truthy
+    // value forces the quirk on, anything else set ("0", "false", "") forces it off.
+    inline MG_Config::QuirkOverride QueryEnvQuirkOverride(const String& key) {
+        auto it = acceptedEnvVariablesMap->find(key);
+        if (it == acceptedEnvVariablesMap->end()) {
+            return MG_Config::QuirkOverride::Auto;
+        }
+        return IsTruthyValue(it->second) ? MG_Config::QuirkOverride::ForceOn
+                                         : MG_Config::QuirkOverride::ForceOff;
+    }
+
     inline Uint32 QueryEnvUint32(const String& key, Uint32 defaultValue, Uint32 minValue, Uint32 maxValue) {
         auto it = acceptedEnvVariablesMap->find(key);
         if (it == acceptedEnvVariablesMap->end()) {
@@ -123,6 +134,10 @@ namespace MobileGL::MG_ConfigLoader {
         features.TraceSkipAutodestroy = QueryEnvFlag("MOBILEGL_TRACE_SKIP_AUTODESTROY");
         features.DisableUboRing = QueryEnvFlag("MOBILEGL_DISABLE_UBO_RING");
         features.RelaxedSemantics = QueryEnvFlag("MOBILEGL_RELAXED_SEMANTICS");
+        features.SubgroupPrefixScanQuirk = QueryEnvQuirkOverride("MOBILEGL_QUIRK_SUBGROUP_PREFIX_SCAN");
+        features.MagmaDisableBlendedDepthWriteQuirk =
+            QueryEnvQuirkOverride("MOBILEGL_MAGMA_DISABLE_BLENDED_DEPTH_WRITE");
+        features.DisableRobustBufferAccess = QueryEnvFlag("MOBILEGL_DISABLE_ROBUST_BUFFER_ACCESS");
     }
 
     inline void InitBackendType() {

MobileGL/MG_Backend/BackendObject.h

@@ -230,6 +230,21 @@ namespace MobileGL {
             void (*SetSwapInterval)(Int interval);
         };
 
+        // Coarse GPU vendor identity for gating device-specific quirks. Detected from the
+        // Vulkan physical-device vendorID or the GLES GL_VENDOR/GL_RENDERER strings; stays
+        // Unknown when detection is inconclusive, in which case auto-gated quirks stay off.
+        enum class GpuVendorKind : Uint8 {
+            Unknown = 0,
+            Qualcomm,
+            Arm,
+            Nvidia,
+            Amd,
+            Intel,
+            ImgTec,
+            // Software rasterizers (llvmpipe/lavapipe, SwiftShader).
+            Software,
+        };
+
         struct DynamicBackendParameters {
             SizeT UniformBufferOffsetAlignment = 256;
             // GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT. 1.0 means the backend cannot filter anisotropically,
@@ -291,6 +306,7 @@ namespace MobileGL {
             Uint32 SubgroupSupportedStages = 0;
             Uint32 SubgroupSupportedFeatures = 0;
             Bool SubgroupQuadOperationsInAllStages = false;
+            GpuVendorKind GpuVendor = GpuVendorKind::Unknown;
         };
 
         enum class WindowBackend {

MobileGL/MG_Backend/DirectGLES/BackendObject_DirectGLES.cpp

@@ -826,7 +826,7 @@ namespace MobileGL::MG_Backend::DirectGLES {
                                           E_GL_ARB_program_interface_query, E_GL_ARB_framebuffer_object,
                                           E_GL_EXT_framebuffer_object, E_GL_ARB_depth_texture, E_GL_ARB_buffer_storage,
                                           E_GL_ARB_texture_storage, E_GL_ARB_texture_storage_multisample,
-                                          E_GL_ARB_direct_state_access,
+                                          E_GL_ARB_clear_texture, E_GL_ARB_direct_state_access,
                                           E_GL_ARB_multi_draw_indirect, E_GL_ARB_indirect_parameters,
                                           E_GL_ARB_shader_draw_parameters, E_GL_ARB_gpu_shader5, E_GL_ARB_multi_bind,
                                           E_GL_ARB_shading_language_420pack, E_GL_ARB_vertex_attrib_binding,
@@ -1035,6 +1035,32 @@ namespace MobileGL::MG_Backend::DirectGLES {
         m_dynamicParameters.ViewportSubpixelBits = m_GLESCapabilities.ViewportSubpixelBits;
         m_dynamicParameters.SupportsWideLines =
             m_GLESCapabilities.AliasedLineWidthRangeMax > 1.0f || m_GLESCapabilities.SmoothLineWidthRangeMax > 1.0f;
+
+        const auto containsAny = [](const String& haystack, std::initializer_list<const char*> needles) {
+            return std::any_of(needles.begin(), needles.end(), [&](const char* needle) {
+                return haystack.find(needle) != String::npos;
+            });
+        };
+        const String vendorAndRenderer =
+            m_GLESCapabilities.GLESVendorString + " " + m_GLESCapabilities.GLESRendererString;
+        if (containsAny(vendorAndRenderer, {"llvmpipe", "SwiftShader", "softpipe"})) {
+            // Check software rasterizers first: ANGLE-on-llvmpipe reports both.
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Software;
+        } else if (containsAny(vendorAndRenderer, {"Qualcomm", "Adreno"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Qualcomm;
+        } else if (containsAny(vendorAndRenderer, {"Mali", "ARM"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Arm;
+        } else if (containsAny(vendorAndRenderer, {"NVIDIA"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Nvidia;
+        } else if (containsAny(vendorAndRenderer, {"AMD", "Radeon"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Amd;
+        } else if (containsAny(vendorAndRenderer, {"Intel"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Intel;
+        } else if (containsAny(vendorAndRenderer, {"Imagination", "PowerVR"})) {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::ImgTec;
+        } else {
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Unknown;
+        }
     }
 
     const MG_External::GLESFunctionsTable& BackendObject_DirectGLES::GetGLESFunctions() const {

MobileGL/MG_Backend/DirectVulkan/BackendObject_DirectVulkan.cpp

@@ -794,5 +794,32 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                     m_vulkanCaps.MaxShaderStorageBlockSize,
                     m_dynamicParameters.MaxShaderStorageBlockSize);
         }
+        switch (m_vulkanCaps.VendorId) {
+        case 0x5143u: // VK_VENDOR_ID: Qualcomm
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Qualcomm;
+            break;
+        case 0x13B5u: // ARM
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Arm;
+            break;
+        case 0x10DEu: // NVIDIA
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Nvidia;
+            break;
+        case 0x1002u: // AMD
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Amd;
+            break;
+        case 0x8086u: // Intel
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Intel;
+            break;
+        case 0x1010u: // Imagination
+            m_dynamicParameters.GpuVendor = GpuVendorKind::ImgTec;
+            break;
+        case 0x10005u: // Mesa software (lavapipe)
+        case 0x1AE0u:  // Google (SwiftShader)
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Software;
+            break;
+        default:
+            m_dynamicParameters.GpuVendor = GpuVendorKind::Unknown;
+            break;
+        }
     }
 } // namespace MobileGL::MG_Backend::DirectVulkan

MobileGL/MG_Backend/DirectVulkan/Renderer/PipelineFactory.cpp

@@ -8,6 +8,7 @@
 
 #include "PipelineFactory.h"
 
+
 namespace MobileGL::MG_Backend::DirectVulkan {
     static const char* PrimitiveTopologyToString(VkPrimitiveTopology topology) {
         switch (topology) {
@@ -108,6 +109,10 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                   "vkCreatePipelineCache");
     }
 
+    void PipelineFactory::SetSuppressBlendedDepthWrite(Bool enabled) {
+        s_suppressBlendedDepthWrite = enabled;
+    }
+
     PipelineFactory::~PipelineFactory() {
         DestroyAll();
         if (m_pipelineCache != VK_NULL_HANDLE) {
@@ -258,6 +263,18 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         for (Uint32 i = 0; i < payload.colorAttachmentCount; ++i) {
             colorAttachments[i] = payload.colorBlendAttachments[i];
         }
+        // Suppress depth writes on blended pipelines when the active driver cannot keep
+        // vertex positions invariant across the pipelines of a multi-pass depth-equality
+        // chain (see SetSuppressBlendedDepthWrite). Blended draws that write depth are rare
+        // and the equality-dependent prepass pattern is exactly the case that breaks.
+        if (s_suppressBlendedDepthWrite && depthStencil.depthWriteEnable == VK_TRUE) {
+            for (Uint32 i = 0; i < payload.colorAttachmentCount; ++i) {
+                if (colorAttachments[i].blendEnable == VK_TRUE) {
+                    depthStencil.depthWriteEnable = VK_FALSE;
+                    break;
+                }
+            }
+        }
         VkPipelineColorBlendStateCreateInfo blend{VK_STRUCTURE_TYPE_PIPELINE_COLOR_BLEND_STATE_CREATE_INFO};
         blend.logicOpEnable = payload.logicOpEnable ? VK_TRUE : VK_FALSE;
         blend.logicOp = payload.logicOp;

MobileGL/MG_Backend/DirectVulkan/Renderer/PipelineFactory.h

@@ -62,6 +62,14 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         VkPipeline GetOrCreatePipeline(const PipelineCreatePayload& payload);
         void DestroyAll();
 
+        // Driver quirk: suppress depth writes on blended pipelines. Multi-pass depth-equality
+        // rendering (a blended prepass writes depth that later passes re-test with an
+        // equality-inclusive compare on the re-rasterized geometry) requires cross-pipeline
+        // position invariance that some mobile compilers do not provide, even with the
+        // SPIR-V Invariant decoration; whole primitives then drop out of the later passes.
+        // Set at renderer initialization based on the active driver.
+        static void SetSuppressBlendedDepthWrite(Bool enabled);
+
     private:
         VkPipeline CreatePipeline(const PipelineCreatePayload& payload) const;
 
@@ -70,5 +78,6 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         VkPipelineCache m_pipelineCache = VK_NULL_HANDLE;
         UnorderedMap<HashType, VkPipeline> m_cache;
         static inline XXH64_state_t* m_hashState = XXH64_createState();
+        static inline Bool s_suppressBlendedDepthWrite = false;
     };
 } // namespace MobileGL::MG_Backend::DirectVulkan

MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.cpp

@@ -1808,6 +1808,7 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                 layoutBinding.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_BUFFER;
             } else if (kind == DescriptorBindingKind::StorageImage) {
                 layoutBinding.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_IMAGE;
+                entry.hasStorageImages = true;
             } else {
                 layoutBinding.descriptorType = VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER;
             }
@@ -1862,6 +1863,22 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                 moduleSpirvs[i] = spv;
             }
 
+            // GL apps depend on cross-program position invariance for multi-pass equality
+            // depth tests (MC 26.3's OIT re-draws the cloud geometry with GEQUAL against the
+            // depth its own first pass wrote); decorate Position outputs Invariant so
+            // per-pipeline compilers cannot vary the position math between passes.
+            {
+                Vector<Uint> invariantSpirv;
+                if (MG_Util::ShaderTranspiler::ShaderCompiler::DecoratePositionInvariantForVulkan(
+                        moduleSpirvs[i], invariantSpirv)) {
+                    moduleSpirvs[i] = std::move(invariantSpirv);
+                } else {
+                    MGLOG_W("ProgramFactory: position-invariant decoration failed for program %u; "
+                            "keeping the original module",
+                            program.GetExternalIndex());
+                }
+            }
+
             // glslang's relaxed-Vulkan mode aliases GL's zero-based gl_InstanceID to Vulkan's
             // gl_InstanceIndex, which wrongly includes the draw's baseInstance. Rebase vertex-stage
             // loads to (InstanceIndex - BaseInstance) so shaders observe GL semantics. Reflection

MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.h

@@ -67,6 +67,9 @@ namespace MobileGL::MG_Backend::DirectVulkan {
             Vector<Bool> storageImageUsesBindingFormatByBinding;
             Vector<String> storageBlockNameByBinding;
             Vector<Int> storageBlockIndexByBinding;
+            // Set once during ReflectLayout so the per-draw path can skip the whole
+            // storage-image preparation for the overwhelming majority of programs.
+            Bool hasStorageImages = false;
             Int globalUboBinding = -1;
             Uint32 activeVertexInputLocationMask = 0;
             Array<GLenum, kMaxVertexInputLocations> vertexInputTypes{};
@@ -99,6 +102,7 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                     std::move(other.storageImageUsesBindingFormatByBinding);
                 storageBlockNameByBinding = std::move(other.storageBlockNameByBinding);
                 storageBlockIndexByBinding = std::move(other.storageBlockIndexByBinding);
+                hasStorageImages = other.hasStorageImages;
                 globalUboBinding = other.globalUboBinding;
                 activeVertexInputLocationMask = other.activeVertexInputLocationMask;
                 vertexInputTypes = other.vertexInputTypes;
@@ -110,6 +114,7 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                 other.hash = 0;
                 other.descriptorSetLayout = VK_NULL_HANDLE;
                 other.pipelineLayout = VK_NULL_HANDLE;
+                other.hasStorageImages = false;
                 other.globalUboBinding = -1;
                 other.activeVertexInputLocationMask = 0;
                 other.activeFragmentOutputLocationMask = 0;
@@ -139,6 +144,7 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                     std::move(other.storageImageUsesBindingFormatByBinding);
                 storageBlockNameByBinding = std::move(other.storageBlockNameByBinding);
                 storageBlockIndexByBinding = std::move(other.storageBlockIndexByBinding);
+                hasStorageImages = other.hasStorageImages;
                 globalUboBinding = other.globalUboBinding;
                 activeVertexInputLocationMask = other.activeVertexInputLocationMask;
                 vertexInputTypes = other.vertexInputTypes;
@@ -150,6 +156,7 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                 other.hash = 0;
                 other.descriptorSetLayout = VK_NULL_HANDLE;
                 other.pipelineLayout = VK_NULL_HANDLE;
+                other.hasStorageImages = false;
                 other.globalUboBinding = -1;
                 other.activeVertexInputLocationMask = 0;
                 other.activeFragmentOutputLocationMask = 0;

MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp

@@ -298,8 +298,23 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         // descriptor valid.
         const Bool forceNearestFiltering = numericDomain == SamplerNumericDomain::SignedInteger ||
                                            numericDomain == SamplerNumericDomain::UnsignedInteger;
-        const VkFormat sampledViewFormat =
+        SamplerResolveMemo* viewFormatMemo =
-            VkTextureManager::ResolveSampledImageViewFormat(resource->format, numericDomain);
+            binding < m_samplerResolveMemo.size() ? &m_samplerResolveMemo[binding] : nullptr;
+        VkFormat sampledViewFormat;
+        if (viewFormatMemo != nullptr && viewFormatMemo->viewFormatValid &&
+            viewFormatMemo->viewFormatSource == resource->format &&
+            viewFormatMemo->viewFormatDomain == numericDomain) {
+            sampledViewFormat = viewFormatMemo->viewFormat;
+        } else {
+            sampledViewFormat =
+                VkTextureManager::ResolveSampledImageViewFormat(resource->format, numericDomain);
+            if (viewFormatMemo != nullptr) {
+                viewFormatMemo->viewFormatSource = resource->format;
+                viewFormatMemo->viewFormatDomain = numericDomain;
+                viewFormatMemo->viewFormat = sampledViewFormat;
+                viewFormatMemo->viewFormatValid = true;
+            }
+        }
         if (sampledViewFormat == VK_FORMAT_UNDEFINED) {
             MGLOG_E("ResolveSamplerDescriptor: no compatible sampled view for binding=%u ('%s') "
                     "textureId=%d imageFormat=%d numericDomain=%d",
@@ -307,8 +322,12 @@ namespace MobileGL::MG_Backend::DirectVulkan {
                     static_cast<Int>(resource->format), static_cast<Int>(numericDomain));
             return false;
         }
+        // No reinterpretation requested: bind the depth-or-color aspect view the sync above
+        // already produced instead of re-entering GetOrCreateSampledImageView's sync path.
         const VkImageView sampledImageView =
-            m_textureManager->GetOrCreateSampledImageView(*texture, sampledViewFormat);
+            sampledViewFormat == resource->format
+                ? resource->sampledView
+                : m_textureManager->GetOrCreateSampledImageView(*texture, sampledViewFormat);
         if (sampledImageView == VK_NULL_HANDLE) {
             MGLOG_E("ResolveSamplerDescriptor: failed to resolve sampled view for binding=%u ('%s') "
                     "textureId=%d imageFormat=%d viewFormat=%d numericDomain=%d",

MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.h

@@ -176,6 +176,13 @@ namespace MobileGL::MG_Backend::DirectVulkan {
             Uint16 textureParamsVersion = 0;
             Bool forceNearestFiltering = false;
             Bool valid = false;
+            // ResolveSampledImageViewFormat is pure in (image format, numeric domain), but a
+            // domain mismatch walks a ~184-entry format table. Memo the resolution per binding
+            // so a reinterpreted sampler pays that scan once, not once per draw.
+            VkFormat viewFormatSource = VK_FORMAT_UNDEFINED;
+            SamplerNumericDomain viewFormatDomain = SamplerNumericDomain::Unknown;
+            VkFormat viewFormat = VK_FORMAT_UNDEFINED;
+            Bool viewFormatValid = false;
         };
         mutable Vector<SamplerResolveMemo> m_samplerResolveMemo;
     };

MobileGL/MG_Backend/DirectVulkan/Renderer/VertexInputStateFactory.cpp

@@ -126,8 +126,13 @@ namespace MobileGL::MG_Backend::DirectVulkan {
             const Bool packedAttribute = attr.Type == DataType::Int2101010Rev ||
                                          attr.Type == DataType::Uint2101010Rev;
             const SizeT requiredAlignment = packedAttribute ? attribByteSize : GetComponentSize(attr.Type);
+            // For a client-memory array attr.Offset holds the raw client pointer, and the
+            // draw path re-uploads the data to a 16-aligned transient slice with attribute
+            // offset 0, so only the stride can violate Vulkan's fetch alignment there.
+            const Bool clientMemoryAttribute = attr.Buffer == nullptr;
             if (conversion == VertexStreamConversion::None && requiredAlignment > 1 &&
-                ((sourceStride % requiredAlignment) != 0 || (attr.Offset % requiredAlignment) != 0)) {
+                ((sourceStride % requiredAlignment) != 0 ||
+                 (!clientMemoryAttribute && (attr.Offset % requiredAlignment) != 0))) {
                 // GL accepts arbitrary byte strides and offsets. Core Vulkan vertex fetches do not
                 // unless VK_EXT_legacy_vertex_attributes is available, so deinterleave this one
                 // attribute into a tightly packed transient stream without changing its format.

MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.cpp

@@ -1140,6 +1140,24 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         return ok;
     }
 
+    Bool VkTextureManager::NeedsStorageImagePreparation(MG_State::GLState::ITextureObject& texture) const {
+        const auto it = m_textureResources.find(MakeTextureIdentity(&texture));
+        if (it == m_textureResources.end()) {
+            return true;
+        }
+        const TextureResource& resource = it->second;
+        if (resource.image == VK_NULL_HANDLE || resource.layout != VK_IMAGE_LAYOUT_GENERAL) {
+            return true;
+        }
+        // Mirror SyncTexture's cross-draw skip condition: any version drift means the sync
+        // path may upload or rebuild, both of which need the render pass ended first.
+        const auto* mipTexture = MG_State::GLState::AsMipmapTexture(&texture);
+        const Uint32 mipLevelCount = mipTexture != nullptr ? mipTexture->GetMipmapLevelCount() : 0u;
+        return resource.syncedContentVersion != texture.GetContentVersion() ||
+               resource.syncedTextureParamsVersion != texture.GetTextureParamsVersion() ||
+               resource.syncedMipLevelCount != mipLevelCount;
+    }
+
     Bool VkTextureManager::TransitionImageLayout(VkCommandBuffer commandBuffer, VkImage image,
                                                  VkImageLayout& trackedLayout, VkImageLayout newLayout,
                                                  VkPipelineStageFlags srcStageMask, VkPipelineStageFlags dstStageMask,
@@ -1323,7 +1341,8 @@ namespace MobileGL::MG_Backend::DirectVulkan {
             (aspect & VK_IMAGE_ASPECT_COLOR_BIT) != 0 &&
             (formatProperties.optimalTilingFeatures & VK_FORMAT_FEATURE_STORAGE_IMAGE_BIT) != 0;
         VkImageCreateFlags imageCreateFlags = shapeInfo.imageFlags;
-        if (supportsStorageImage && IsMutableStorageImageFormat(format)) {
+        if (supportsStorageImage && IsMutableStorageImageFormat(format) &&
+            m_mutableFormatUnsupported.find(format) == m_mutableFormatUnsupported.end()) {
             imageCreateFlags |= VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT;
         }
 
@@ -1391,9 +1410,27 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         imageInfo.samples = resolvedSampleCount;
         if (isMultisampleTexture || (imageInfo.flags & VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT) != 0) {
             VkImageFormatProperties imageFormatProperties{};
-            const VkResult imageFormatResult = vkGetPhysicalDeviceImageFormatProperties(
+            VkResult imageFormatResult = vkGetPhysicalDeviceImageFormatProperties(
                 m_physicalDevice, format, imageInfo.imageType, imageInfo.tiling, imageInfo.usage,
                 imageInfo.flags, &imageFormatProperties);
+            if (imageFormatResult != VK_SUCCESS && !isMultisampleTexture &&
+                (imageInfo.flags & VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT) != 0) {
+                // Losing reinterpreted views only degrades the formatless-image feature for
+                // this texture; failing creation would lose the texture entirely, so retry
+                // as a plain immutable-format image.
+                MGLOG_W("%s: mutable image format=%d is unsupported for textureId=%d; creating "
+                        "without VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT (format reinterpretation "
+                        "will be unavailable for it)",
+                        __func__, static_cast<Int>(format), texture.GetExternalIndex());
+                // Remember the verdict so later syncs of same-format textures neither retry
+                // the probe nor flag-mismatch against this image and recreate it.
+                m_mutableFormatUnsupported.insert(format);
+                imageInfo.flags &= ~VK_IMAGE_CREATE_MUTABLE_FORMAT_BIT;
+                imageCreateFlags = imageInfo.flags;
+                imageFormatResult = vkGetPhysicalDeviceImageFormatProperties(
+                    m_physicalDevice, format, imageInfo.imageType, imageInfo.tiling, imageInfo.usage,
+                    imageInfo.flags, &imageFormatProperties);
+            }
             if (imageFormatResult != VK_SUCCESS ||
                 (isMultisampleTexture && (imageFormatProperties.sampleCounts & resolvedSampleCount) == 0)) {
                 MGLOG_D("%s: image flags=0x%x sampleCount=%d are unsupported for textureId=%d target=%s "
@@ -1921,6 +1958,15 @@ namespace MobileGL::MG_Backend::DirectVulkan {
 
     VkFormat VkTextureManager::ResolveSampledImageViewFormat(VkFormat imageFormat,
                                                               SamplerNumericDomain numericDomain) {
+        // Depth/stencil images always sample through the existing depth-aspect sampledView.
+        // Combined formats (D24S8, D32FS8) are multi-numeric, so vkuFormatIsSampledFloat is
+        // false for them by design, yet their depth aspect reads as float in every GL depth
+        // texture mode; Vulkan also forbids reinterpreting them through color-class views.
+        // Integer domains keep the same view (pre-reinterpretation behavior for stencil-index
+        // style access) rather than failing the draw.
+        if (vkuFormatIsDepthOrStencil(imageFormat)) {
+            return imageFormat;
+        }
         if (imageFormat == VK_FORMAT_UNDEFINED || numericDomain == SamplerNumericDomain::Unknown ||
             FormatMatchesSamplerNumericDomain(imageFormat, numericDomain)) {
             return imageFormat;

MobileGL/MG_Backend/DirectVulkan/Renderer/VkTextureManager.h

@@ -13,6 +13,7 @@
 #include <MG_State/GLState/TextureState/TextureObject.h>
 #include <vk_mem_alloc.h>
 #include <unordered_map>
+#include <unordered_set>
 
 namespace MobileGL::MG_State::GLState {
 class ITextureObject;
@@ -284,6 +285,11 @@ public:
                                                       VkImageLayout newLayout);
     Bool TransitionTextureForSampling(VkCommandBuffer commandBuffer, MG_State::GLState::ITextureObject& texture);
     Bool TransitionTextureForStorageImage(VkCommandBuffer commandBuffer, MG_State::GLState::ITextureObject& texture);
+    // Non-mutating probe for the per-draw storage-image fast path: true when preparing this
+    // texture as a storage image may need work that is illegal inside a render pass (resource
+    // creation, dirty-content upload, or a layout transition to GENERAL). Unknown state reports
+    // true - a false positive merely ends the render pass, a false negative would skip a barrier.
+    Bool NeedsStorageImagePreparation(MG_State::GLState::ITextureObject& texture) const;
 
     static VkImageAspectFlags ResolveSampledImageViewAspectMask(VkImageAspectFlags imageAspect);
     static VkFormat ResolveSampledImageViewFormat(VkFormat imageFormat, SamplerNumericDomain numericDomain);
@@ -379,6 +385,9 @@ private:
         TextureResource* resource = nullptr;
     };
     Vector<DrawSyncedTexture> m_drawSyncedThisDraw;
+    // Formats whose mutable-image probe failed on this device; their images are created
+    // without MUTABLE_FORMAT_BIT so repeat syncs neither re-probe nor flag-mismatch.
+    std::unordered_set<VkFormat> m_mutableFormatUnsupported;
     std::unordered_map<TextureIdentity, WeakPtr<MG_State::GLState::ITextureObject>, TextureIdentityHash> m_aliveObjects;
     std::unordered_map<TextureIdentity, TextureResource, TextureIdentityHash> m_textureResources;
     Vector<Vector<TextureResource>> m_deferredReleases;

MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp

@@ -27,6 +27,9 @@
 #include <cstring>
 #include <vulkan/utility/vk_format_utils.h>
 #include <vulkan/vulkan_core.h>
+#ifdef __ANDROID__
+#include <sys/system_properties.h>
+#endif
 
 #if defined(__APPLE__)
 #include <CoreGraphics/CoreGraphics.h>
@@ -1031,6 +1034,7 @@ void main() {
 }
 )";
 
+
         static Uint32 ComputeFullMipLevelCount(const IntVec3& baseTexelSize) {
             Int maxDimension = std::max<Int>(
                 baseTexelSize.x(),
@@ -1618,6 +1622,63 @@ void main() {
                 case VK_FORMAT_R32G32B32A32_SFLOAT:
                     Memcpy(rgba, source, sizeof(Float) * 4);
                     return true;
+                // Single- and dual-channel formats the reinterpretation feature makes common
+                // as readback sources (iterationRP custom images are R32F/R32UI-class).
+                // Missing channels take GL's defaults: 0 for GB, 1 for alpha.
+                case VK_FORMAT_R32_SFLOAT: {
+                    Float value = 0.0f;
+                    Memcpy(&value, source, sizeof(value));
+                    rgba[0] = value;
+                    rgba[1] = 0.0f;
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
+                }
+                case VK_FORMAT_R32G32_SFLOAT: {
+                    Float values[2] = {0.0f, 0.0f};
+                    Memcpy(values, source, sizeof(values));
+                    rgba[0] = values[0];
+                    rgba[1] = values[1];
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
+                }
+                case VK_FORMAT_R32_UINT: {
+                    Uint32 value = 0;
+                    Memcpy(&value, source, sizeof(value));
+                    rgba[0] = static_cast<Float>(value);
+                    rgba[1] = 0.0f;
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
+                }
+                case VK_FORMAT_R32_SINT: {
+                    Int32 value = 0;
+                    Memcpy(&value, source, sizeof(value));
+                    rgba[0] = static_cast<Float>(value);
+                    rgba[1] = 0.0f;
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
+                }
+                case VK_FORMAT_R16_SFLOAT: {
+                    Uint16 value = 0;
+                    Memcpy(&value, source, sizeof(value));
+                    rgba[0] = MG_Util::DecodeHalfBitsToFloat(value);
+                    rgba[1] = 0.0f;
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
+                }
+                case VK_FORMAT_R16G16_SFLOAT:
+                    for (SizeT component = 0; component < 2; ++component) {
+                        Uint16 value = 0;
+                        Memcpy(&value, source + component * sizeof(value), sizeof(value));
+                        rgba[component] = MG_Util::DecodeHalfBitsToFloat(value);
+                    }
+                    rgba[2] = 0.0f;
+                    rgba[3] = 1.0f;
+                    return true;
                 default:
                     return false;
             }
@@ -2046,6 +2107,28 @@ void main() {
 
         m_pipelineFactory = MakeUnique<PipelineFactory>(m_device, m_config);
         MOBILEGL_ASSERT(m_pipelineFactory != nullptr, "PipelineFactory creation failed.");
+        {
+            // Qualcomm's pipeline compiler does not keep vertex positions invariant across
+            // the pipelines of a multi-pass depth-equality chain (even with the SPIR-V
+            // Invariant decoration), so a blended depth-writing prepass makes later
+            // equality-compare passes drop whole primitives (MC 26.3 improved-transparency
+            // clouds flicker black). Suppress blended depth writes there;
+            // MOBILEGL_MAGMA_DISABLE_BLENDED_DEPTH_WRITE forces the quirk on or off on any
+            // driver.
+            static constexpr Uint32 kVendorIdQualcomm = 0x5143;
+            const MG_Config::QuirkOverride quirkOverride =
+                MG_Config::Features.MagmaDisableBlendedDepthWriteQuirk;
+            const Bool suppressBlendedDepthWrite =
+                quirkOverride == MG_Config::QuirkOverride::ForceOn ||
+                (quirkOverride == MG_Config::QuirkOverride::Auto &&
+                 m_physicalDevice.properties.vendorID == kVendorIdQualcomm);
+            if (suppressBlendedDepthWrite) {
+                MGLOG_I("DirectVulkan: suppressing depth writes on blended pipelines "
+                        "(driver lacks cross-pipeline position invariance)%s",
+                        quirkOverride == MG_Config::QuirkOverride::ForceOn ? " (forced on)" : "");
+            }
+            PipelineFactory::SetSuppressBlendedDepthWrite(suppressBlendedDepthWrite);
+        }
         m_programFactory = MakeUnique<ProgramFactory>(m_device, m_config, maxProgramBindings,
                                                       m_shaderDrawParametersFeatureEnabled,
                                                       m_unformattedFloatStorageImagesEnabled);
@@ -2200,10 +2283,94 @@ void main() {
         MGLOG_I("VulkanRenderer shut down completed");
     }
 
+    // Scans the draw's index range from host-visible index bytes and returns the largest
+    // fetchable vertex index. Usable only when the draw's range is exactly its
+    // IndexBufferView (drawParams.indexRangeIsExactView). The view's byte offset is either
+    // an offset into the bound element-array buffer or, with no bound buffer, a raw client
+    // pointer. Primitive-restart sentinels are skipped so they cannot inflate the bound.
+    static Bool TryComputeMaxIndexFromHostBytes(const MG_State::GLState::VertexArrayObject& vao,
+                                                const IndexBufferView& indexView, Uint32& outMaxIndex) {
+        SizeT indexSize = 0;
+        switch (indexView.indexType) {
+        case GL_UNSIGNED_BYTE: indexSize = 1; break;
+        case GL_UNSIGNED_SHORT: indexSize = 2; break;
+        case GL_UNSIGNED_INT: indexSize = 4; break;
+        default: return false;
+        }
+
+        const Uint8* indexBytes = nullptr;
+        const auto& indexBufferShared = vao.GetIndexBufferBindingSlot().GetBoundObject();
+        if (indexBufferShared != nullptr) {
+            const SizeT bufferSize = indexBufferShared->GetSize();
+            if (indexBufferShared->MappedData() == nullptr || indexView.indexByteOffset > bufferSize ||
+                indexView.indexByteSize > bufferSize - indexView.indexByteOffset) {
+                return false;
+            }
+            indexBufferShared->SyncPersistentMappedRange();
+            indexBytes = indexBufferShared->MappedData() + indexView.indexByteOffset;
+        } else {
+            indexBytes = reinterpret_cast<const Uint8*>(indexView.indexByteOffset);
+            if (indexBytes == nullptr) {
+                return false;
+            }
+        }
+
+        const SizeT indexCount = indexView.indexByteSize / indexSize;
+        // The all-ones sentinel is only a restart marker when primitive restart is enabled;
+        // with restart off it is a legitimate index and excluding it would truncate the
+        // converted stream by exactly that vertex.
+        const Bool primitiveRestartActive =
+            MG_State::pGLContext->IsCapabilityEnabled(CapabilityInput::PrimitiveRestart) ||
+            MG_State::pGLContext->IsCapabilityEnabled(CapabilityInput::PrimitiveRestartFixedIndex);
+        const Uint32 restartSentinel = indexSize == 1 ? 0xFFu : indexSize == 2 ? 0xFFFFu : 0xFFFFFFFFu;
+        Uint32 maxIndex = 0;
+        Bool sawIndex = false;
+        for (SizeT i = 0; i < indexCount; ++i) {
+            Uint32 index = 0;
+            switch (indexSize) {
+            case 1: index = indexBytes[i]; break;
+            case 2: index = reinterpret_cast<const Uint16*>(indexBytes)[i]; break;
+            default: index = reinterpret_cast<const Uint32*>(indexBytes)[i]; break;
+            }
+            if (primitiveRestartActive && index == restartSentinel) {
+                continue;
+            }
+            maxIndex = std::max(maxIndex, index);
+            sawIndex = true;
+        }
+        if (!sawIndex) {
+            return false;
+        }
+        outMaxIndex = maxIndex;
+        return true;
+    }
+
     Bool VulkanRenderer::UploadAndBindVertexBuffers(
         VkCommandBuffer commandBuffer, const MG_State::GLState::VertexArrayObject& vao,
         const ProgramFactory::VkProgramObject& programObj, const DrawCmdParam& drawParams,
-        Bool indexedDraw) {
+        const IndexBufferView* pIndexBufferView) {
+        const Bool indexedDraw = pIndexBufferView != nullptr;
+        // Exclusive upper bound on the vertex-stream elements this draw can fetch through
+        // vertex-rate bindings, or 0 when unbounded (indirect/multi draws). Computed lazily
+        // because the index scan is only worth doing when a conversion actually needs it.
+        SizeT drawElementBound = 0;
+        Bool drawElementBoundComputed = false;
+        auto resolveDrawElementBound = [&]() -> SizeT {
+            if (drawElementBoundComputed) {
+                return drawElementBound;
+            }
+            drawElementBoundComputed = true;
+            if (!indexedDraw) {
+                drawElementBound = static_cast<SizeT>(drawParams.firstVertex) + drawParams.vertexCount;
+            } else if (drawParams.indexRangeIsExactView) {
+                Uint32 maxIndex = 0;
+                if (TryComputeMaxIndexFromHostBytes(vao, *pIndexBufferView, maxIndex)) {
+                    drawElementBound = static_cast<SizeT>(maxIndex) + 1 +
+                                       static_cast<SizeT>(std::max(drawParams.baseVertex, 0));
+                }
+            }
+            return drawElementBound;
+        };
         // programObj is resolved once in SetupDraw and passed in; re-resolving it here would repeat
         // the GetCurrentProgram + GetOrCreateProgram hash lookup every draw.
         auto& vertexInputState = m_vertexInputStateFactory->GetOrCreateVertexInputState(vao);
@@ -2289,33 +2456,35 @@ void main() {
                     return false;
                 }
 
-                if (conversion != VertexInputStateFactory::VertexStreamConversion::None && indexedDraw) {
+                // Client arrays have no queryable size, so bound the upload by the draw's
-                    // The current indexed setup only carries indexCount, not the maximum effective
+                // real fetch range. For indexed draws that means scanning the index bytes:
-                    // index. Guessing a client-memory range here can truncate the converted stream.
+                // the guessed vertexCount (indexCount + baseVertex) can both truncate draws
-                    MGLOG_E("UploadAndBindVertexStreams skipped: converted client-memory attribute "
+                // whose max index exceeds their index count and over-read below it.
-                            "location=%u requires an indexed vertex range", location);
+                const SizeT clientElementBound = resolveDrawElementBound();
-                    return false;
-                }
-                if (conversion != VertexInputStateFactory::VertexStreamConversion::None &&
-                    drawParams.vertexCount == 0) {
-                    MGLOG_E("UploadAndBindVertexStreams skipped: converted client-memory attribute "
-                            "location=%u has an unknown vertex range", location);
-                    return false;
-                }
-
-                const Uint32 lastVertex = drawParams.vertexCount > 0
-                                              ? drawParams.firstVertex + drawParams.vertexCount - 1
-                                              : drawParams.firstVertex;
                 BufferSlice slice{};
                 Bool uploaded = false;
                 if (conversion == VertexInputStateFactory::VertexStreamConversion::None) {
-                    const SizeT uploadSize = static_cast<SizeT>(lastVertex) * stride + elementSize;
+                    const SizeT lastVertex =
+                        clientElementBound > 0
+                            ? clientElementBound - 1
+                            : (drawParams.vertexCount > 0
+                                   ? static_cast<SizeT>(drawParams.firstVertex) + drawParams.vertexCount - 1
+                                   : static_cast<SizeT>(drawParams.firstVertex));
+                    const SizeT uploadSize = lastVertex * stride + elementSize;
                     uploaded = m_bufferManager.UploadTransient(
                         BufferKind::Vertex, m_frameContext.GetCurrentFrameIndex(), clientData,
                         static_cast<VkDeviceSize>(uploadSize), 16, slice);
                 } else {
+                    if (clientElementBound == 0) {
+                        // Indirect/multi indexed draws have no CPU-visible index range and a
+                        // client array has no size to fall back to; a guessed range could
+                        // truncate the converted stream, so skip the draw loudly.
+                        MGLOG_E("UploadAndBindVertexStreams skipped: converted client-memory attribute "
+                                "location=%u has no computable vertex range", location);
+                        return false;
+                    }
                     uploaded = uploadConvertedStream(conversion, attr, clientData, stride, elementSize,
-                                                     static_cast<SizeT>(lastVertex) + 1, slice);
+                                                     clientElementBound, slice);
                 }
                 if (!uploaded) {
                     MOBILEGL_ASSERT(false,
@@ -2362,7 +2531,23 @@ void main() {
                 }
 
                 sourceBufferShared->SyncPersistentMappedRange();
-                const SizeT elementCount = 1 + (sourceSize - baseOffset - elementSize) / sourceStride;
+                const SizeT availableElementCount = 1 + (sourceSize - baseOffset - elementSize) / sourceStride;
+                const Bool cacheable = !sourceBufferShared->IsBackendPersistentMapped();
+                // Convert only what this draw can fetch instead of the whole buffer tail.
+                // Instance-rate bindings index by instance, not the vertex range, so they
+                // keep the tail. Indexed draws from cacheable buffers also keep the tail: a
+                // single cached whole-range conversion per frame is cheaper than a per-draw
+                // index scan. Persistent-mapped buffers are uncacheable and reconvert every
+                // draw, so for them the scan plus bounded conversion is the cheaper trade.
+                const Bool vertexRateBinding =
+                    vertexInputState.bindings[binding].inputRate == VK_VERTEX_INPUT_RATE_VERTEX;
+                SizeT elementCount = availableElementCount;
+                if (vertexRateBinding && (!indexedDraw || !cacheable)) {
+                    const SizeT elementBound = resolveDrawElementBound();
+                    if (elementBound > 0) {
+                        elementCount = std::min(elementCount, elementBound);
+                    }
+                }
                 const ConvertedVertexStreamKey cacheKey{
                     .buffer = sourceBufferShared.get(),
                     .changeSerial = sourceBufferShared->GetChangeSerial(),
@@ -2375,12 +2560,18 @@ void main() {
                     .conversion = conversion,
                 };
 
-                const Bool cacheable = !sourceBufferShared->IsBackendPersistentMapped();
+                Bool reusedCachedStream = false;
-                auto cached = cacheable ? m_convertedVertexStreams.find(cacheKey)
+                if (cacheable) {
-                                        : m_convertedVertexStreams.end();
+                    const auto cached = m_convertedVertexStreams.find(cacheKey);
-                if (cached != m_convertedVertexStreams.end()) {
+                    // A cached conversion covering at least this draw's range is a strict
-                    slice = cached->second;
+                    // prefix match: converted streams are tightly packed from element 0.
-                } else {
+                    if (cached != m_convertedVertexStreams.end() &&
+                        cached->second.elementCount >= elementCount) {
+                        slice = cached->second.slice;
+                        reusedCachedStream = true;
+                    }
+                }
+                if (!reusedCachedStream) {
                     const Uint8* sourceData = sourceBufferShared->MappedData() + baseOffset;
                     if (!uploadConvertedStream(conversion, attr, sourceData, sourceStride,
                                                elementSize, elementCount, slice)) {
@@ -2389,7 +2580,8 @@ void main() {
                         return false;
                     }
                     if (cacheable) {
-                        m_convertedVertexStreams.emplace(cacheKey, slice);
+                        m_convertedVertexStreams[cacheKey] =
+                            ConvertedVertexStream{slice, elementCount, sourceBufferShared};
                     }
                 }
                 vkBuffers[binding] = slice.buffer;
@@ -3526,6 +3718,9 @@ void main() {
         VkCommandBuffer commandBuffer,
         const MG_State::GLState::ProgramObject& program,
         const ProgramFactory::VkProgramObject& programObj) {
+        if (!programObj.hasStorageImages) {
+            return true;
+        }
         auto& storageTextures = m_storageImageTexturesScratch;
         if (!m_uniformManager->CollectStorageImageTextures(program, programObj, storageTextures)) {
             MGLOG_E("%s: failed to collect storage images for program=%u",
@@ -3536,6 +3731,24 @@ void main() {
             return true;
         }
 
+        // Steady-state fast path: when every collected texture is already resident in GENERAL
+        // with no pending clear and no dirty content, the loop below has nothing to record, so
+        // keep the render pass alive instead of splitting it on every storage-image draw (on
+        // tiled GPUs each split is a full tile load/store). GL makes cross-draw image-store
+        // coherence the app's job (glMemoryBarrier), so no implicit barrier is owed here.
+        Bool anyNeedsPreparation = false;
+        for (auto* texture : storageTextures) {
+            MOBILEGL_ASSERT(texture != nullptr, "%s: collected a null storage texture", __func__);
+            if (m_textureManager->NeedsStorageImagePreparation(*texture) ||
+                m_clearManager->HasPendingClear(texture)) {
+                anyNeedsPreparation = true;
+                break;
+            }
+        }
+        if (!anyNeedsPreparation) {
+            return true;
+        }
+
         // Image uploads, deferred-clear materialization, and layout barriers are illegal inside
         // a classic render pass. Do this before sampler preparation as well: a texture used by
         // both a sampler and an image must stay in GENERAL, and both descriptors must name that
@@ -3545,7 +3758,6 @@ void main() {
         }
 
         for (auto* texture : storageTextures) {
-            MOBILEGL_ASSERT(texture != nullptr, "%s: collected a null storage texture", __func__);
             if (!MaterializePendingClearForTexture(commandBuffer, *texture)) {
                 MGLOG_E("%s: failed to materialize pending clear for storage textureId=%d",
                         __func__, texture->GetExternalIndex());
@@ -3763,7 +3975,7 @@ void main() {
         }
 
         auto vtxUploadOk = UploadAndBindVertexBuffers(
-            frame.commandBuffer, vao, programObj, drawParams, pIndexBufferView != nullptr);
+            frame.commandBuffer, vao, programObj, drawParams, pIndexBufferView);
         if (!vtxUploadOk) {
             MGLOG_E("SetupDraw skipped: failed to upload vertex buffers");
             return false;
@@ -5977,6 +6189,10 @@ void main() {
         vertexRange.instanceCount = payload.params.instanceCount;
         vertexRange.firstVertex = 0;
         vertexRange.firstInstance = static_cast<Uint32>(payload.params.firstInstance);
+        vertexRange.baseVertex = payload.params.vertexOffset;
+        // Direct DrawElements fetches exactly the indices in its view, so vertex-stream
+        // conversion may bound its work by scanning them.
+        vertexRange.indexRangeIsExactView = true;
 
         if (!SetupDraw(frame, payload.mode, DrawSetupAspect::IndexBuffer, vertexRange,
                        &payload.indexBufferView)) {
@@ -7007,7 +7223,10 @@ void main() {
         // Match GL's robust buffer-fetch behavior where the Vulkan device supports it. This covers
         // out-of-range fetches; arbitrary GL vertex strides/offsets still need the explicit tight
         // repack in VertexInputStateFactory when they violate Vulkan's address-alignment rules.
-        deviceFeatures.robustBufferAccess = supportedDeviceFeatures.robustBufferAccess;
+        // MOBILEGL_DISABLE_ROBUST_BUFFER_ACCESS leaves it off to measure or dodge its GPU cost.
+        deviceFeatures.robustBufferAccess = MG_Config::Features.DisableRobustBufferAccess
+                                                ? VK_FALSE
+                                                : supportedDeviceFeatures.robustBufferAccess;
         deviceFeatures.geometryShader = supportedDeviceFeatures.geometryShader;
         deviceFeatures.independentBlend = supportedDeviceFeatures.independentBlend;
         m_independentBlendFeatureEnabled = deviceFeatures.independentBlend == VK_TRUE;
@@ -7037,6 +7256,15 @@ void main() {
         if (m_unformattedFloatStorageImagesEnabled) {
             deviceFeatures.shaderStorageImageReadWithoutFormat = VK_TRUE;
             deviceFeatures.shaderStorageImageWriteWithoutFormat = VK_TRUE;
+        } else {
+            // Surface the degradation instead of failing silently: shader packs that bind a
+            // float storage image with a format different from its declaration (e.g.
+            // iterationRP) will render incorrectly on this device.
+            MGLOG_W("CreateLogicalDeviceAndQueues: shaderStorageImage*WithoutFormat unavailable "
+                    "(read=%d write=%d); float storage-image format reinterpretation is disabled "
+                    "and packs relying on it may misrender",
+                    supportedDeviceFeatures.shaderStorageImageReadWithoutFormat,
+                    supportedDeviceFeatures.shaderStorageImageWriteWithoutFormat);
         }
         deviceFeatures.drawIndirectFirstInstance = supportedDeviceFeatures.drawIndirectFirstInstance;
         deviceFeatures.multiDrawIndirect = supportedDeviceFeatures.multiDrawIndirect;

MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h

@@ -51,6 +51,12 @@ namespace MobileGL::MG_Backend::DirectVulkan {
         Uint32 instanceCount = 1;
         Uint32 firstVertex = 0;
         Uint32 firstInstance = 0;
+        // Indexed-draw metadata for bounding vertex-stream conversion. baseVertex is the
+        // draw's base-vertex offset; indexRangeIsExactView is true only when the draw
+        // fetches exactly the indices its IndexBufferView describes (direct DrawElements;
+        // multi/indirect forms leave it false because the CPU cannot bound their ranges).
+        Int32 baseVertex = 0;
+        Bool indexRangeIsExactView = false;
     };
 
     struct DrawIndexedCmdParam {
@@ -488,7 +494,18 @@ namespace MobileGL::MG_Backend::DirectVulkan {
             }
         };
 
-        UnorderedMap<ConvertedVertexStreamKey, BufferSlice, ConvertedVertexStreamKeyHash>
+        struct ConvertedVertexStream {
+            BufferSlice slice;
+            // Number of source elements the cached slice covers. A draw needing a prefix of
+            // this range reuses the slice (converted streams are tightly packed); a draw
+            // needing more reconverts and replaces the entry, so per (buffer, layout) a
+            // frame converts at most the largest range any draw asked for.
+            SizeT elementCount = 0;
+            // Pins the source buffer for the frame so its heap address cannot be reused by
+            // a new BufferObject while this pointer-keyed entry is alive.
+            SharedPtr<const MG_State::GLState::BufferObject> sourcePin;
+        };
+        UnorderedMap<ConvertedVertexStreamKey, ConvertedVertexStream, ConvertedVertexStreamKeyHash>
             m_convertedVertexStreams;
 
         void CreateInstance();
@@ -519,7 +536,8 @@ namespace MobileGL::MG_Backend::DirectVulkan {
 
         Bool UploadAndBindVertexBuffers(VkCommandBuffer commandBuffer, const MG_State::GLState::VertexArrayObject& vao,
                                         const ProgramFactory::VkProgramObject& programObj,
-                                        const DrawCmdParam& drawParams, Bool indexedDraw);
+                                        const DrawCmdParam& drawParams,
+                                        const IndexBufferView* pIndexBufferView);
         Bool UploadAndBindIndexBuffer(FrameContext::FrameData& frame,
                                      const MG_State::GLState::VertexArrayObject& vao,
                                       const IndexBufferView* pIndexBufferView = nullptr);

MobileGL/MG_Impl/GLImpl/Texture/GL_Texture.cpp

@@ -493,8 +493,15 @@ namespace MobileGL::MG_Impl::GLImpl {
             }
 
             auto mipmapTexture = std::static_pointer_cast<MG_State::GLState::TextureObjectMipmap>(textureObject);
-            if (level < 0 || static_cast<Uint>(level) >= mipmapTexture->GetMipmapLevelCount()) {
+            if (level < 0) {
                 RecordClearTextureError(caller, ErrorCode::InvalidValue,
+                                        std::format("Texture level {} is negative.", level));
+                return nullptr;
+            }
+            // ARB_clear_texture: clearing an image that was never defined by TexImage*/
+            // TexStorage* is INVALID_OPERATION, not INVALID_VALUE.
+            if (static_cast<Uint>(level) >= mipmapTexture->GetMipmapLevelCount()) {
+                RecordClearTextureError(caller, ErrorCode::InvalidOperation,
                                         std::format("Texture level {} is not defined.", level));
                 return nullptr;
             }
@@ -536,6 +543,12 @@ namespace MobileGL::MG_Impl::GLImpl {
             return true;
         }
 
+        // Writes the clear into the CPU shadow and marks the whole level dirty, exactly like
+        // TexSubImage*_State does. Shared limitation of the level-granular shadow sync: the
+        // shadow does not reflect GPU-side writes (FBO rendering, imageStore), so a PARTIAL
+        // clear of a GPU-written level re-uploads stale shadow bytes outside the region on
+        // the next sync. Full-level clears (glClearTexImage, or a sub-clear covering the
+        // level) rewrite the entire shadow and are always correct.
         Bool ClearMipmapRegion(const SharedPtr<MG_State::GLState::TextureObjectMipmap>& textureObject,
                                TextureUploadTarget uploadTarget, GLint level,
                                GLint xoffset, GLint yoffset, GLint zoffset,
@@ -4025,8 +4038,21 @@ namespace MobileGL::MG_Impl::GLImpl {
     void CopyTextureSubImage2D(GLuint texture, GLint level, GLint xoffset, GLint yoffset, GLint x, GLint y,
                                GLsizei width, GLsizei height) {
         auto textureObject = GetTextureObjectByName(texture, __func__);
-        WithTemporarilyBoundNamedTexture(textureObject, [&](GLenum target) {
+        if (!textureObject) return;
-            CopyTexSubImage2D_Backend(target, level, xoffset, yoffset, x, y, width, height);
+        // GL 4.6 sec. 8.8: the 2D form only accepts these effective targets; cube maps must
+        // go through CopyTextureSubImage3D with the face as a layer.
+        const auto target = textureObject->GetTarget();
+        if (target != TextureTarget::Texture2D && target != TextureTarget::Texture1DArray &&
+            target != TextureTarget::TextureRectangle) {
+            MG_State::pGLContext->RecordError(
+                ErrorCode::InvalidOperation,
+                MakeUnique<GenericErrorInfo>("MG_Impl/GLImpl", __func__,
+                                             "CopyTextureSubImage2D requires a 2D, 1D-array, or "
+                                             "rectangle texture."));
+            return;
+        }
+        WithTemporarilyBoundNamedTexture(textureObject, [&](GLenum glTarget) {
+            CopyTexSubImage2D_Backend(glTarget, level, xoffset, yoffset, x, y, width, height);
         });
     }
 

MobileGL/MG_Test/Program/ProgramUtilTest.cpp

@@ -1623,4 +1623,26 @@ TEST_F(ProgramUtilTest, RewriteLinearSubgroupPrefixScanRejectsPartialOrUnsafeTem
     ASSERT_NE(consumerEnd, String::npos);
     nestedScan.insert(consumerEnd + 1, "\n    }");
     expectUnchanged(std::move(nestedScan));
+
+    // ARB/NV spellings of lane-width-sensitive builtins must block the rewrite exactly
+    // like their KHR counterparts.
+    String arbSubgroupBuiltin = MakeLinearSubgroupPrefixScanShader();
+    arbSubgroupBuiltin.insert(arbSubgroupBuiltin.find("float importance"),
+                              "uint arbLane = gl_SubGroupInvocationARB;\n    ");
+    expectUnchanged(std::move(arbSubgroupBuiltin));
+
+    String arbBallotCall = MakeLinearSubgroupPrefixScanShader();
+    arbBallotCall.insert(arbBallotCall.find("float importance"),
+                         "uint64_t arbMask = ballotARB(true);\n    ");
+    expectUnchanged(std::move(arbBallotCall));
+
+    String nvWarpBuiltin = MakeLinearSubgroupPrefixScanShader();
+    nvWarpBuiltin.insert(nvWarpBuiltin.find("float importance"),
+                         "uint warpSize = gl_WarpSizeNV;\n    ");
+    expectUnchanged(std::move(nvWarpBuiltin));
+
+    String nvShuffleCall = MakeLinearSubgroupPrefixScanShader();
+    nvShuffleCall.insert(nvShuffleCall.find("float importance"),
+                         "float other = shuffleNV(1.0f, 0u, 32u);\n    ");
+    expectUnchanged(std::move(nvShuffleCall));
 }

MobileGL/MG_Test/SanityTest.cpp

@@ -794,6 +794,33 @@ TEST(DirectVulkanSanity, ReadbackConvertsRgba8AndRgba16fPixels) {
     EXPECT_FLOAT_EQ(rgba16fFloatResult[3], 1.0f);
 }
 
+TEST(DirectVulkanSanity, ReadbackDecodesSingleChannel32BitFormats) {
+    using MobileGL::MG_Backend::DirectVulkan::VulkanRenderer;
+
+    // The reinterpretation feature makes R32F/R32UI-class images common readback sources
+    // (iterationRP custom images). Missing channels take GL defaults: 0 for GB, 1 for alpha.
+    const MobileGL::Float r32f[] = {0.75f, -2.0f};
+    MobileGL::Float r32fResult[8]{};
+    ASSERT_TRUE(VulkanRenderer::ConvertReadbackPixels(
+        reinterpret_cast<const MobileGL::Uint8*>(r32f), VK_FORMAT_R32_SFLOAT,
+        2, 1, GL_RGBA, GL_FLOAT, sizeof(MobileGL::Float) * 8,
+        reinterpret_cast<MobileGL::Uint8*>(r32fResult)));
+    EXPECT_FLOAT_EQ(r32fResult[0], 0.75f);
+    EXPECT_FLOAT_EQ(r32fResult[1], 0.0f);
+    EXPECT_FLOAT_EQ(r32fResult[2], 0.0f);
+    EXPECT_FLOAT_EQ(r32fResult[3], 1.0f);
+    EXPECT_FLOAT_EQ(r32fResult[4], -2.0f);
+
+    const MobileGL::Uint32 r32ui[] = {12345u};
+    MobileGL::Float r32uiResult[4]{};
+    ASSERT_TRUE(VulkanRenderer::ConvertReadbackPixels(
+        reinterpret_cast<const MobileGL::Uint8*>(r32ui), VK_FORMAT_R32_UINT,
+        1, 1, GL_RGBA, GL_FLOAT, sizeof(MobileGL::Float) * 4,
+        reinterpret_cast<MobileGL::Uint8*>(r32uiResult)));
+    EXPECT_FLOAT_EQ(r32uiResult[0], 12345.0f);
+    EXPECT_FLOAT_EQ(r32uiResult[3], 1.0f);
+}
+
 TEST(DirectVulkanSanity, DrawIndexedIndirectCommandMatchesGlAndVulkanLayout) {
     using namespace MobileGL::MG_Backend::DirectVulkan;
 
@@ -999,9 +1026,27 @@ TEST(DirectVulkanSanity, SampledViewFormatMatchesSamplerNumericDomainWithoutChan
     EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
                   VK_FORMAT_B10G11R11_UFLOAT_PACK32, SamplerNumericDomain::UnsignedInteger),
               VK_FORMAT_UNDEFINED);
+
+    // Depth/stencil formats never resolve through color-class reinterpretation; they pass
+    // through unchanged so the existing depth-aspect sampled view is used. Combined
+    // depth-stencil formats are multi-numeric (vkuFormatIsSampledFloat is false for them),
+    // so without the passthrough a plain sampler2D/sampler2DShadow on GL_DEPTH24_STENCIL8
+    // would resolve to UNDEFINED and the draw would be dropped.
+    EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
+                  VK_FORMAT_D24_UNORM_S8_UINT, SamplerNumericDomain::Float),
+              VK_FORMAT_D24_UNORM_S8_UINT);
+    EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
+                  VK_FORMAT_D32_SFLOAT_S8_UINT, SamplerNumericDomain::Float),
+              VK_FORMAT_D32_SFLOAT_S8_UINT);
+    EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
+                  VK_FORMAT_D32_SFLOAT, SamplerNumericDomain::Float),
+              VK_FORMAT_D32_SFLOAT);
+    EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
+                  VK_FORMAT_D24_UNORM_S8_UINT, SamplerNumericDomain::UnsignedInteger),
+              VK_FORMAT_D24_UNORM_S8_UINT);
     EXPECT_EQ(VkTextureManager::ResolveSampledImageViewFormat(
                   VK_FORMAT_D32_SFLOAT, SamplerNumericDomain::UnsignedInteger),
-              VK_FORMAT_UNDEFINED);
+              VK_FORMAT_D32_SFLOAT);
 
     EXPECT_TRUE(VkTextureManager::AreSampledImageViewFormatsCompatible(
         VK_FORMAT_R32_SFLOAT, VK_FORMAT_R32_UINT));

MobileGL/MG_Test/Texture/TextureTest.cpp

@@ -318,6 +318,49 @@ TEST_F(TextureTest, CopyTextureSubImage2DUsesNamedObjectAndRestoresBinding) {
     EXPECT_EQ(MG_Impl::GLImpl::GetError(), GL_NO_ERROR);
 }
 
+TEST_F(TextureTest, CopyTextureSubImage2DRejectsCubeMapTargets) {
+    const ScopedTextureBackendFunctionsOverride backendGuard;
+    MG_Backend::gBackendFunctionsTable.GL.CopyTexSubImage2D = RecordCopyTexSubImage2D;
+    g_copyTexSubImage2DCall = {};
+
+    GLuint cubeTexture = 0;
+    MG_Impl::GLImpl::CreateTextures(GL_TEXTURE_CUBE_MAP, 1, &cubeTexture);
+    MG_Impl::GLImpl::CopyTextureSubImage2D(cubeTexture, 0, 0, 0, 0, 0, 1, 1);
+
+    // GL 4.6 sec. 8.8: the 2D form only accepts 2D/1D-array/rectangle effective targets.
+    EXPECT_FALSE(g_copyTexSubImage2DCall.Called);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_OPERATION));
+}
+
+TEST_F(TextureTest, ClearTexImageErrorContracts) {
+    GLuint texture = 0;
+    MG_Impl::GLImpl::GenTextures(1, &texture);
+    MG_Impl::GLImpl::BindTexture(GL_TEXTURE_2D, texture);
+    MG_Impl::GLImpl::TexImage2D(GL_TEXTURE_2D, 0, GL_RGBA8, 2, 2, 0,
+                                GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+
+    // Zero texture name is INVALID_OPERATION (ARB_clear_texture).
+    MG_Impl::GLImpl::ClearTexImage(0, 0, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_OPERATION));
+
+    // A negative level is INVALID_VALUE...
+    MG_Impl::GLImpl::ClearTexImage(texture, -1, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_VALUE));
+
+    // ...but clearing a level that was never defined is INVALID_OPERATION.
+    MG_Impl::GLImpl::ClearTexImage(texture, 5, GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_OPERATION));
+
+    // A clear region outside the level is INVALID_VALUE.
+    MG_Impl::GLImpl::ClearTexSubImage(texture, 0, 1, 1, 0, 4, 4, 1,
+                                      GL_RGBA, GL_UNSIGNED_BYTE, nullptr);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_VALUE));
+
+    // An invalid pixel-transfer format is INVALID_ENUM from the shared validators.
+    MG_Impl::GLImpl::ClearTexImage(texture, 0, GL_NONE, GL_UNSIGNED_BYTE, nullptr);
+    EXPECT_EQ(MG_Impl::GLImpl::GetError(), static_cast<GLenum>(GL_INVALID_ENUM));
+}
+
 // GL_MAX_TEXTURE_MAX_ANISOTROPY_EXT is float state that must answer every numeric query: GetFloatv
 // is authoritative and GetIntegerv would otherwise fall through to its INVALID_ENUM default.
 TEST_F(TextureTest, MaxTextureMaxAnisotropyIsAnsweredFromTheBackendLimit) {

MobileGL/MG_Util/BackendLoaders/Vulkan/Loader.cpp

@@ -121,6 +121,7 @@ namespace MobileGL::MG_Util::BackendLoader {
         caps.VulkanAPIVersion = DecodeApiVersion(p.apiVersion);
         caps.DeviceName = p.deviceName;
         caps.DriverVersionString = DecodeDriverVersion(p.driverVersion);
+        caps.VendorId = p.vendorID;
         caps.UniformBufferOffsetAlignment = static_cast<int>(p.limits.minUniformBufferOffsetAlignment);
         caps.AliasedLineWidthRangeMin = p.limits.lineWidthRange[0];
         caps.AliasedLineWidthRangeMax = p.limits.lineWidthRange[1];
@@ -210,6 +211,7 @@ namespace MobileGL::MG_Util::BackendLoader {
         caps.VulkanAPIVersion = DecodeApiVersion(properties.apiVersion);
         caps.DeviceName = properties.deviceName;
         caps.DriverVersionString = DecodeDriverVersion(properties.driverVersion);
+        caps.VendorId = properties.vendorID;
         caps.UniformBufferOffsetAlignment = static_cast<int>(properties.limits.minUniformBufferOffsetAlignment);
         caps.AliasedLineWidthRangeMin = properties.limits.lineWidthRange[0];
         caps.AliasedLineWidthRangeMax = properties.limits.lineWidthRange[1];

MobileGL/MG_Util/BackendLoaders/Vulkan/Loader.h

@@ -15,6 +15,8 @@ namespace MobileGL {
             Version VulkanAPIVersion{1, 0, 0};
             String DeviceName;
             String DriverVersionString;
+            // VkPhysicalDeviceProperties::vendorID, for device-quirk vendor gating.
+            Uint32 VendorId = 0;
             Int UniformBufferOffsetAlignment = 256;
             Float AliasedLineWidthRangeMin = 1.0f;
             Float AliasedLineWidthRangeMax = 1.0f;

MobileGL/MG_Util/ShaderTranspiler/ShaderCompiler.cpp

@@ -26,6 +26,7 @@
 #include <MG_Backend/BackendObjects.h>
 #include <MG_Util/Converters/GLToStr/GLEnumConverter.h>
 #include <MG_Util/Converters/GLToGlslang/ProgramEnumConverter.h>
+#include <cstdlib>
 
 namespace MobileGL {
     namespace MG_Util {
@@ -344,6 +345,75 @@ namespace MobileGL {
                 return optimizer.Run(inputBinary.data(), inputBinary.size(), &outputBinary, options);
             }
 
+            bool ShaderCompiler::DecoratePositionInvariantForVulkan(const Vector<Uint32>& inputBinary,
+                                                                    Vector<uint32_t>& outputBinary) {
+                static constexpr Uint32 kHeaderWords = 5;
+                static constexpr Uint32 kOpDecorate = 71;
+                static constexpr Uint32 kOpMemberDecorate = 72;
+                static constexpr Uint32 kDecorationInvariant = 18;
+                static constexpr Uint32 kDecorationBuiltIn = 11;
+                static constexpr Uint32 kBuiltInPosition = 0;
+                if (inputBinary.size() < kHeaderWords) {
+                    return false;
+                }
+
+                // First pass: find targets that already carry Invariant so we never duplicate.
+                struct MemberKey {
+                    Uint32 id;
+                    Uint32 member;
+                    bool operator==(const MemberKey& o) const { return id == o.id && member == o.member; }
+                };
+                Vector<Uint32> invariantIds;
+                Vector<MemberKey> invariantMembers;
+                for (SizeT i = kHeaderWords; i < inputBinary.size();) {
+                    const Uint32 word0 = inputBinary[i];
+                    const Uint32 opcode = word0 & 0xFFFFu;
+                    const Uint32 length = word0 >> 16;
+                    if (length == 0 || i + length > inputBinary.size()) {
+                        return false;
+                    }
+                    if (opcode == kOpDecorate && length >= 3 && inputBinary[i + 2] == kDecorationInvariant) {
+                        invariantIds.push_back(inputBinary[i + 1]);
+                    } else if (opcode == kOpMemberDecorate && length >= 4 &&
+                               inputBinary[i + 3] == kDecorationInvariant) {
+                        invariantMembers.push_back({inputBinary[i + 1], inputBinary[i + 2]});
+                    }
+                    i += length;
+                }
+
+                outputBinary.clear();
+                outputBinary.reserve(inputBinary.size() + 8);
+                outputBinary.insert(outputBinary.end(), inputBinary.begin(), inputBinary.begin() + kHeaderWords);
+                for (SizeT i = kHeaderWords; i < inputBinary.size();) {
+                    const Uint32 word0 = inputBinary[i];
+                    const Uint32 opcode = word0 & 0xFFFFu;
+                    const Uint32 length = word0 >> 16;
+                    outputBinary.insert(outputBinary.end(), inputBinary.begin() + i,
+                                        inputBinary.begin() + i + length);
+                    if (opcode == kOpDecorate && length == 4 &&
+                        inputBinary[i + 2] == kDecorationBuiltIn && inputBinary[i + 3] == kBuiltInPosition) {
+                        const Uint32 target = inputBinary[i + 1];
+                        if (std::find(invariantIds.begin(), invariantIds.end(), target) == invariantIds.end()) {
+                            outputBinary.push_back((3u << 16) | kOpDecorate);
+                            outputBinary.push_back(target);
+                            outputBinary.push_back(kDecorationInvariant);
+                        }
+                    } else if (opcode == kOpMemberDecorate && length == 5 &&
+                               inputBinary[i + 3] == kDecorationBuiltIn && inputBinary[i + 4] == kBuiltInPosition) {
+                        const MemberKey key{inputBinary[i + 1], inputBinary[i + 2]};
+                        if (std::find(invariantMembers.begin(), invariantMembers.end(), key) ==
+                            invariantMembers.end()) {
+                            outputBinary.push_back((4u << 16) | kOpMemberDecorate);
+                            outputBinary.push_back(key.id);
+                            outputBinary.push_back(key.member);
+                            outputBinary.push_back(kDecorationInvariant);
+                        }
+                    }
+                    i += length;
+                }
+                return true;
+            }
+
             bool ShaderCompiler::UseUnformattedFloatStorageImagesForVulkan(
                 const Vector<Uint32>& inputBinary, Vector<uint32_t>& outputBinary) {
                 constexpr SizeT kSpirvHeaderWordCount = 5;

MobileGL/MG_Util/ShaderTranspiler/ShaderCompiler.h

@@ -39,6 +39,13 @@ namespace MobileGL {
                 // which wrongly includes baseInstance).
                 static bool RebaseInstanceIndexForVulkan(const Vector<Uint32>& inputBinary,
                                                          Vector<uint32_t>& outputBinary);
+                // Adds the Invariant decoration to every Position builtin output. GL apps
+                // routinely rely on cross-program position invariance for multi-pass
+                // equality depth tests (e.g. GEQUAL re-draws of the same geometry), and
+                // mobile drivers that optimize per-pipeline break that without the
+                // decoration. DirectVulkan only.
+                static bool DecoratePositionInvariantForVulkan(const Vector<Uint32>& inputBinary,
+                                                               Vector<uint32_t>& outputBinary);
                 // Replaces the declared format of float storage images with Unknown and adds the
                 // matching SPIR-V capabilities. DirectVulkan uses this only when both Vulkan
                 // shaderStorageImage*WithoutFormat features are enabled, allowing the

MobileGL/MG_Util/ShaderTranspiler/ShaderSourceProcessor.cpp

@@ -12,6 +12,7 @@
 #include <cctype>
 #include <initializer_list>
 #include <utility>
+#include <Config.h>
 #include <MG_Backend/BackendObjects.h>
 
 namespace {
@@ -365,7 +366,21 @@ namespace {
             HasIdentifierWithPrefixOutsideAllowed(tokens, "subgroup", {"subgroupInclusiveAdd"}) ||
             HasIdentifierWithPrefixOutsideAllowed(
                 tokens, "gl_Subgroup",
-                {"gl_SubgroupInvocationID", "gl_SubgroupSize", "gl_SubgroupID", "gl_NumSubgroups"})) {
+                {"gl_SubgroupInvocationID", "gl_SubgroupSize", "gl_SubgroupID", "gl_NumSubgroups"}) ||
+            // ARB/NV spellings of lane-width-sensitive builtins and functions
+            // (gl_SubGroupSizeARB, ballotARB, gl_WarpSizeNV, shuffleNV, ...) must block the
+            // rewrite just like their KHR counterparts: they would silently keep native-width
+            // semantics in a module rewritten to the virtual 32-lane model.
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "gl_SubGroup", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "gl_Warp", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "gl_Thread", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "gl_SMID", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "ballot", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "shuffle", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "readInvocation", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "readFirstInvocation", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "anyInvocation", {}) ||
+            HasIdentifierWithPrefixOutsideAllowed(tokens, "allInvocations", {})) {
             return false;
         }
 
@@ -967,6 +982,14 @@ namespace MobileGL {
                 const Vector<CodeToken> tokens = TokenizeCode(source);
                 LinearPrefixScanMatch match;
                 if (!ParseLinearPrefixScanTemplate(tokens, match)) {
+                    // Diagnosability: when the trigger op is present but the template no longer
+                    // matches (e.g. the pack shipped a new shader revision), the affected device
+                    // silently falls back to the driver's miscompiled path. Make that visible.
+                    if (CountToken(tokens, "subgroupInclusiveAdd") > 0) {
+                        MGLOG_W("%s: subgroupInclusiveAdd present but the linear prefix-scan template "
+                                "did not match; the wide-subgroup rewrite was NOT applied",
+                                __func__);
+                    }
                     return false;
                 }
 
@@ -979,6 +1002,76 @@ namespace MobileGL {
                 return true;
             }
 
+            namespace {
+                struct ShaderSourceQuirkContext {
+                    ShaderStage stage = ShaderStage::Unknown;
+                    BackendType backend = BackendType::Unknown;
+                    MG_Backend::GpuVendorKind vendor = MG_Backend::GpuVendorKind::Unknown;
+                    Uint32 subgroupSize = 0;
+                };
+
+                // Device-quirk registry. Every entry is a narrowly scoped source rewrite that
+                // works around a specific driver defect. A quirk runs when its env override
+                // forces it on, or when the override is Auto and DeviceApplies matches the
+                // detected device. ForceOn bypasses only the device gate - each Apply keeps
+                // its own structural safety checks. Add new per-device workarounds here
+                // instead of open-coding them in PreprocessShaderSource.
+                struct ShaderSourceQuirk {
+                    const char* name;
+                    MG_Config::QuirkOverride (*GetOverride)();
+                    Bool (*DeviceApplies)(const ShaderSourceQuirkContext&);
+                    Bool (*Apply)(const ShaderSourceQuirkContext&, String&);
+                };
+
+                constexpr ShaderSourceQuirk kShaderSourceQuirks[] = {
+                    {
+                        // MOBILEGL_QUIRK_SUBGROUP_PREFIX_SCAN
+                        "subgroup-prefix-scan-rewrite",
+                        [] { return MG_Config::Features.SubgroupPrefixScanQuirk; },
+                        [](const ShaderSourceQuirkContext& ctx) {
+                            // Qualcomm's Vulkan driver miscompiles the recognized float
+                            // InclusiveScan pattern for native subgroups wider than the
+                            // captured 32 lanes; other vendors compile it correctly and
+                            // should keep their native scan.
+                            return ctx.backend == BackendType::DirectVulkan &&
+                                   ctx.vendor == MG_Backend::GpuVendorKind::Qualcomm;
+                        },
+                        [](const ShaderSourceQuirkContext& ctx, String& source) {
+                            return RewriteLinearSubgroupPrefixScanForVulkan(ctx.stage, ctx.subgroupSize,
+                                                                            source);
+                        },
+                    },
+                };
+
+                void ApplyShaderSourceQuirks(ShaderStage stage, String& source) {
+                    const auto& activeBackend = MG_Backend::pActiveBackendObject;
+                    if (!activeBackend) {
+                        return;
+                    }
+                    const auto& dynamicParameters = activeBackend->GetDynamicParameters();
+                    const ShaderSourceQuirkContext quirkContext{
+                        stage,
+                        activeBackend->GetBackendType(),
+                        dynamicParameters.GpuVendor,
+                        dynamicParameters.SubgroupSize,
+                    };
+                    for (const ShaderSourceQuirk& quirk : kShaderSourceQuirks) {
+                        const MG_Config::QuirkOverride quirkOverride = quirk.GetOverride();
+                        if (quirkOverride == MG_Config::QuirkOverride::ForceOff) {
+                            continue;
+                        }
+                        if (quirkOverride == MG_Config::QuirkOverride::Auto &&
+                            !quirk.DeviceApplies(quirkContext)) {
+                            continue;
+                        }
+                        if (quirk.Apply(quirkContext, source)) {
+                            MGLOG_I("ApplyShaderSourceQuirks: applied '%s'%s", quirk.name,
+                                    quirkOverride == MG_Config::QuirkOverride::ForceOn ? " (forced on)" : "");
+                        }
+                    }
+                }
+            } // namespace
+
             void PreprocessShaderSource(ShaderStage stage, String& source) {
                 // Normalize while the inspector's source span still refers to the untouched input. Later passes
                 // remove comments and directives, so any subsequent insertion re-inspects the current source.
@@ -1035,12 +1128,7 @@ namespace MobileGL {
                 ModernizeLegacyGLSL(stage, source);
                 InjectDepthRangeBuiltinShim(stage, source);
 
-                const auto& activeBackend = MG_Backend::pActiveBackendObject;
+                ApplyShaderSourceQuirks(stage, source);
-                if (stage == ShaderStage::Compute && activeBackend &&
-                    activeBackend->GetBackendType() == BackendType::DirectVulkan) {
-                    RewriteLinearSubgroupPrefixScanForVulkan(stage, activeBackend->GetDynamicParameters().SubgroupSize,
-                                                             source);
-                }
             }
 
             Bool RetargetLegacyVersionDirectiveTo460(String& source) {

MobileGL/MG_Util/ShaderTranspiler/ShaderSourceProcessor.h

@@ -27,8 +27,10 @@ namespace MobileGL {
             // wider than the capture's 32 lanes. For the narrowly recognized, uniform-control-
             // flow template, replace the subgroup-local scan with a shared-memory, strict
             // left-fold over virtual 32-lane segments. Returns true only when the complete safe
-            // template was recognized and rewritten. DirectVulkan calls this through
+            // template was recognized and rewritten. PreprocessShaderSource reaches this through
-            // PreprocessShaderSource; the explicit entry point exists for deterministic tests.
+            // its device-quirk registry: by default only on detected Qualcomm Vulkan devices,
+            // overridable either way with MOBILEGL_QUIRK_SUBGROUP_PREFIX_SCAN=1/0. The explicit
+            // entry point exists for deterministic tests.
             Bool RewriteLinearSubgroupPrefixScanForVulkan(ShaderStage stage, Uint32 nativeSubgroupSize, String& source);
 
             // Rewrites a "#version 330 core" directive that PreprocessShaderSource normalized down

tools/trace_replay/README.md

@@ -93,6 +93,15 @@ The bundled fixtures cover:
 - minecraft-1.21.4-fabric-iris-iterationt-nodsa-in-world: captured from Minecraft 1.21.4 Fabric with Sodium, Iris, and
   iterationT after entering a singleplayer world, with Iris' DSA path disabled.
   ![Minecraft 1.21.4 Fabric Iris iterationT no-DSA in-world golden](fixtures/minecraft-1.21.4-fabric-iris-iterationt-nodsa-in-world.0000115019.png)
+- minecraft-1.21.4-fabric-iris-iterationrp-in-world: captured from Minecraft 1.21.4 Fabric with Sodium, Iris, and
+  iterationRP after entering a singleplayer world, framing the iterationRP name overlay over a lake with far-shore
+  tree reflections. iterationRP's temporal auto-exposure makes a single-frame trim overexpose and drop the overlay,
+  so the fixture is a prefix trace (all calls up to the target frame) that replays the temporal state. The pack also
+  gates an NVIDIA-only shadow path (`subgroupPartitionNV`, `GL_NV_shader_subgroup_partitioned`) on the GL vendor
+  string, so the capture reports a masked vendor and the trace carries the portable `subgroupShuffleXor` path that
+  non-NVIDIA GPUs take.
+  The trace archive and golden are not committed yet (the repository's Git LFS quota rejects new objects with
+  `GH009`); the case stays registered and its fixture files are hydrated from the trace fixture mirror.
 - minecraft-1.21.4-fabric-iris-photon-v1.1-in-world: captured from Minecraft 1.21.4 Fabric with Sodium, Iris, and
   Photon v1.1 after entering a singleplayer world.
   ![Minecraft 1.21.4 Fabric Iris Photon v1.1 in-world golden](fixtures/minecraft-1.21.4-fabric-iris-photon-v1.1-in-world.0000159866.png)

tools/trace_replay/renderdoc_trace_capture/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Capture RenderDoc Trace Frame"
-  short_description: "Capture exact Android Vulkan/GLES trace frames"
-  default_prompt: "Use $renderdoc-capture-trace-frame to capture and validate an exact Android retrace frame."

tools/trace_replay/run_macos_window_retrace_local.py

@@ -19,7 +19,12 @@ RESULT_ROOT = ROOT / ".trace-work" / "macos-window-retrace-result"
 WORK_ROOT = ROOT / ".trace-work" / "macos-window-retrace-work"
 SUMMARY_DIR = ROOT / ".trace-work" / "macos-window-retrace-summary"
 SUMMARY_HTML = "mobilegl-macos-window-vulkan-retrace-overview.html"
-DEFAULT_MIRROR_BASE = "https://repo.miawa.cn/mgl/tools/trace_replay/fixtures"
+# Fixture mirrors, tried in order before Git LFS.
+DEFAULT_MIRROR_BASES = [
+    "https://git.hit.moe/swung0x48/MobileGL/media/branch/dev/tools/trace_replay/fixtures",
+    "https://repo.miawa.cn/mgl/tools/trace_replay/fixtures",
+]
+DEFAULT_MIRROR_BASE = DEFAULT_MIRROR_BASES[0]
 BACKENDS = ("DirectVulkan",)
 CASES = load_trace_cases()
 
@@ -100,34 +105,35 @@ def default_vulkan_icd(mobilegl_library):
     return ""
 
 
-def download_fixture(path, mirror_base):
+def download_fixture(path, mirror_bases):
+    """Try each mirror in order; return on the first that serves a good file."""
+    if isinstance(mirror_bases, str):
+        mirror_bases = [mirror_bases]
     path.parent.mkdir(parents=True, exist_ok=True)
-    url = f"{mirror_base.rstrip('/')}/{path.name}"
     tmp = path.with_suffix(path.suffix + ".tmp")
-    command = [
+    token = os.environ.get("MOBILEGL_TRACE_FIXTURE_MIRROR_TOKEN", "")
-        "curl",
+    errors = []
-        "-L",
+    for mirror_base in mirror_bases:
-        "--fail",
+        url = f"{mirror_base.rstrip('/')}/{path.name}"
-        "--retry",
+        command = ["curl", "-L", "--fail", "--retry", "3", "--retry-delay", "2",
-        "3",
+                   "--continue-at", "-"]
-        "--retry-delay",
+        if token:
-        "2",
+            command += ["--header", f"Authorization: token {token}"]
-        "--continue-at",
+        command += ["-o", str(tmp), url]
-        "-",
+        result = subprocess.run(command, text=True, capture_output=True)
-        "-o",
+        if result.returncode != 0:
-        str(tmp),
+            errors.append(f"{mirror_base}: {result.stderr.strip() or result.stdout.strip()}")
-        url,
+            tmp.unlink(missing_ok=True)
-    ]
+            continue
-    result = subprocess.run(command, text=True, capture_output=True)
+        tmp.replace(path)
-    if result.returncode != 0:
+        if is_bad_fixture(path):
-        return path, False, result.stderr.strip() or result.stdout.strip()
+            errors.append(f"{mirror_base}: downloaded fixture is empty or still an LFS pointer")
-    tmp.replace(path)
+            continue
-    if is_bad_fixture(path):
+        return path, True, ""
-        return path, False, "downloaded fixture is empty or still an LFS pointer"
+    return path, False, "; ".join(errors)
-    return path, True, ""
 
 
-def hydrate_fixtures(cases, fetch, mirror_base, download_jobs):
+def hydrate_fixtures(cases, fetch, mirror_bases, download_jobs):
     required = []
     seen = set()
     for case in cases:
@@ -149,7 +155,7 @@ def hydrate_fixtures(cases, fetch, mirror_base, download_jobs):
     print(f"fixtures: downloading {len(required)} file(s) with {download_jobs} worker(s)", flush=True)
     failures = []
     with concurrent.futures.ThreadPoolExecutor(max_workers=download_jobs) as executor:
-        futures = [executor.submit(download_fixture, path, mirror_base) for path in required]
+        futures = [executor.submit(download_fixture, path, mirror_bases) for path in required]
         for future in concurrent.futures.as_completed(futures):
             path, ok, message = future.result()
             if ok:
@@ -434,7 +440,9 @@ def parse_args():
     parser.add_argument("--keep-results", action="store_true", help="Do not clear previous result/work roots.")
     parser.add_argument("--no-render", action="store_true", help="Do not render the HTML summary.")
     parser.add_argument("--fetch-fixtures", action=argparse.BooleanOptionalAction, default=True, help="Hydrate missing fixtures before running.")
-    parser.add_argument("--fixture-mirror-base", default=os.environ.get("MOBILEGL_TRACE_FIXTURE_MIRROR_BASE", DEFAULT_MIRROR_BASE))
+    parser.add_argument("--fixture-mirror-base", action="append", dest="fixture_mirror_bases",
+                        help="Fixture mirror base URL; repeatable, tried in order. "
+                             "Defaults to the hit.moe mirror then the miawa mirror.")
     parser.add_argument("--download-jobs", type=int, default=4, help="Parallel fixture download count.")
     parser.add_argument("--continue-after-fatal", action="store_true", help="Continue launching later cases after a fatal native-window replay.")
     return parser.parse_args()
@@ -463,7 +471,10 @@ def main():
         print(f"missing MobileGL library: {mobilegl_library}", file=sys.stderr)
         return 2
 
-    if not hydrate_fixtures(selected_cases, args.fetch_fixtures, args.fixture_mirror_base, max(1, args.download_jobs)):
+    mirror_bases = args.fixture_mirror_bases or [
+        b for b in os.environ.get("MOBILEGL_TRACE_FIXTURE_MIRROR_BASES", "").split() or []
+    ] or ([os.environ["MOBILEGL_TRACE_FIXTURE_MIRROR_BASE"]] if os.environ.get("MOBILEGL_TRACE_FIXTURE_MIRROR_BASE") else DEFAULT_MIRROR_BASES)
+    if not hydrate_fixtures(selected_cases, args.fetch_fixtures, mirror_bases, max(1, args.download_jobs)):
         return 2
 
     if not args.keep_results:

tools/trace_replay/skills/README.md

@@ -0,0 +1,20 @@
+# MobileGL trace-replay skills
+
+Task-focused skills for capturing, replaying, debugging, and authoring MobileGL
+apitrace fixtures. Each skill is a self-contained package:
+
+- `SKILL.md` — the skill (frontmatter `name` + `description`, then the body). The
+  directory name equals the frontmatter `name`.
+- `agents/openai.yaml` — OpenAI agent descriptor (`display_name`,
+  `short_description`, `default_prompt`).
+- `scripts/` and/or `references/` — bundled tooling and supporting docs, when the
+  skill has them.
+
+## Skills
+
+| Skill | What it does |
+| --- | --- |
+| [trace-fixture-authoring-on-android-fcl](trace-fixture-authoring-on-android-fcl/SKILL.md) | Capture an on-device Android apitrace from FCL's MobileGL renderers (DirectGLES / Magma / SimpleFPEWrapper), mark the defect frame, and pull `full.trace`. |
+| [renderdoc-debug-on-trace-replay](renderdoc-debug-on-trace-replay/SKILL.md) | Capture and validate an exact frame from a MobileGL retrace on a connected Android device with RenderDoc / rdc-cli. |
+| [mismatch-retrace-debugging](mismatch-retrace-debugging/SKILL.md) | Localize the first divergent render pass and draw call when a fixture replays correctly in a golden environment but renders differently on a target backend. |
+| [trace-fixture-authoring](trace-fixture-authoring/SKILL.md) | Author a deterministic trace-replay fixture — trim, golden, package under the size budget, register in `trace_cases.json`, and validate on Linux and Android. |

tools/trace_replay/skills/mismatch-retrace-debugging/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: mismatch-retrace-debugging
+description: Localize the first divergent render pass and draw call when a MobileGL apitrace fixture replays correctly in a golden environment but renders differently under mobilegl_trace_replay, Android trace replay, or another backend. Use to binary-search pass/draw endpoints, diff GL state around the first bad call, and classify the fault as a vertex/VS, fragment/FS, or framebuffer/composition mismatch.
+---
+
 # Mismatch retrace debugging
 
 Use this when an apitrace fixture replays correctly on one environment but

tools/trace_replay/skills/mismatch-retrace-debugging/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MobileGL Mismatch Retrace Debugging"
+  short_description: "Localize the first divergent draw in a mismatching MobileGL retrace"
+  default_prompt: "Use $mismatch-retrace-debugging to find the first divergent render pass and draw call in a MobileGL retrace mismatch."

tools/trace_replay/skills/renderdoc-debug-on-trace-replay/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: renderdoc-capture-trace-frame
+name: renderdoc-debug-on-trace-replay
 description: Capture and validate an exact frame from a MobileGL apitrace retrace on a connected Android device with RenderDoc/rdc-cli. Use for DirectVulkan or DirectGLES trace replay, mapping a target API call to an eglSwapBuffers frame, producing an .rdc plus a complete command manifest, checking capture stability, or troubleshooting Android TargetControl timing and replay failures.
 ---
 
@@ -19,20 +19,20 @@ adb -s SERIAL shell pm path top.mobilegl.plugin.trace
 rdc doctor
 ```
 
-4. Pass the unpacked `trace.trace`, its golden PNG, the fixture target call, backend, and output path to `tools/trace_replay/capture_android_retrace.py`.
+4. Pass the unpacked `trace.trace`, its golden PNG, the fixture target call, backend, and output path to `tools/trace_replay/skills/renderdoc-debug-on-trace-replay/scripts/capture_android_retrace.py`.
 
 ## Capture
 
 Let the tool infer the zero-based target swap from `eglSwapBuffers` calls:
 
 ```powershell
-python tools/trace_replay/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectVulkan --output captures/case-vulkan.rdc --serial SERIAL --json
+python tools/trace_replay/skills/renderdoc-debug-on-trace-replay/scripts/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectVulkan --output captures/case-vulkan.rdc --serial SERIAL --json
 ```
 
 Change only the backend and output for GLES:
 
 ```powershell
-python tools/trace_replay/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectGLES --output captures/case-gles.rdc --serial SERIAL --json
+python tools/trace_replay/skills/renderdoc-debug-on-trace-replay/scripts/capture_android_retrace.py --trace .trace-work/case/trace.trace --golden tools/trace_replay/fixtures/case.0002667619.png --target-call 2667619 --backend DirectGLES --output captures/case-gles.rdc --serial SERIAL --json
 ```
 
 Use `--target-swap N` when the mapping is already known. Use `--capture-frame N` only to override the backend rule deliberately.

tools/trace_replay/skills/renderdoc-debug-on-trace-replay/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "RenderDoc Debug on Trace Replay"
+  short_description: "Capture and debug an exact MobileGL trace-replay frame in RenderDoc"
+  default_prompt: "Use $renderdoc-debug-on-trace-replay to capture and validate an exact Android trace-replay frame in RenderDoc."

tools/trace_replay/skills/renderdoc-debug-on-trace-replay/references/android-renderdoc-troubleshooting.md

@@ -2,7 +2,7 @@
 
 ## TargetControl timing
 
-- Start `tools/trace_replay/queue_android_frame.py` before launching `TraceReplayActivity`. A fast retrace can pass the requested frame before a late client connects.
+- Start `tools/trace_replay/skills/renderdoc-debug-on-trace-replay/scripts/queue_android_frame.py` before launching `TraceReplayActivity`. A fast retrace can pass the requested frame before a late client connects.
 - Keep TargetControl connected until `NewCapture` arrives. A queued request alone is not sufficient evidence that the RDC finished.
 - Drain the asynchronous `RegisterAPI` and `CapturableWindowCount` messages before calling `QueueCapture`; otherwise `NewCapture` can be lost.
 - Do not use the daemon-backed `rdc script` path for a capture that may exceed 30 seconds. Its outer RPC times out even when the device later writes a valid RDC. The repository helper imports the RenderDoc module discovered by `rdc` directly and has an independent capture timeout.

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: trace-fixture-authoring-on-android-fcl
+description: Capture an on-device Android apitrace from FCL's MobileGL renderers. Use when preparing a reproducible MobileGL DirectGLES, Magma (DirectVulkan), or SimpleFPEWrapper rendering trace, marking the frame of a visual defect, pulling the resulting full.trace, or turning a device capture into a replay fixture.
+---
+
+# MobileGL Android trace capture
+
+## Overview
+
+Use FCL's Android `egltrace.so` wrapper, not Perfetto. When enabled before
+launch, it records the complete EGL/GL call stream to `full.trace`. The game's
+**MobileGL Trace → Capture** control marks the next swap frame in
+`capture-result.json`; it does not start or stop recording and does not produce
+a one-frame trace by itself.
+
+Run commands from the FoldCraftLauncher repository root:
+
+```sh
+export REPO="$PWD"
+export CAPTURE="$REPO/MobileGL/tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts"
+export SERIAL=<adb-device-serial> # omit --serial only if exactly one device is attached
+```
+
+The capture scripts are bundled inside this skill under `scripts/`; they
+auto-detect the FoldCraftLauncher repository root from their own location, so
+`--repo` only needs to be passed for a non-standard checkout layout.
+
+## Prerequisites
+
+- Use an FCL build containing `MobileGLTraceCapture` and the in-game Capture
+  menu entry.
+- Select one of these renderers: MobileGL (DirectGLES), MobileGL Magma
+  (DirectVulkan), or SimpleFPEWrapper. MobileGlues is not supported by this
+  capture wrapper.
+- Install `adb` and make it available on `PATH`; authorize USB debugging.
+- Build the wrapper with Android NDK, CMake, Ninja, Python 3, and the checked
+  out in-tree `MobileGL/3rdparty/apitrace` submodule.
+
+Confirm the attached device and ABI before building. The wrapper ABI must match
+the device process ABI.
+
+```sh
+adb devices -l
+adb -s "$SERIAL" shell getprop ro.product.cpu.abi
+```
+
+Use `arm64-v8a` for the usual `arm64-v8a` result; use the matching NDK ABI for
+other devices.
+
+## Build and install the wrapper
+
+Build once per ABI or after changing apitrace/wrapper sources:
+
+```sh
+python3 "$CAPTURE/build_android_egltrace.py" --abi arm64-v8a
+```
+
+This generates `egltrace.so` under the skill's `scripts/out/` directory. Push
+it and write FCL's enable sentinel before launching the game:
+
+```sh
+python3 "$CAPTURE/adb_capture.py" --serial "$SERIAL" install-wrapper
+python3 "$CAPTURE/adb_capture.py" --serial "$SERIAL" enable
+```
+
+The device-side control directory is `/sdcard/FCL/mobilegl-trace`. FCL copies
+the shared `egltrace.so` into its private files directory at launch, replaces
+the renderer's EGL library with it, and forwards to the real MobileGL library.
+
+## Capture a reproduction
+
+1. Start FCL after the wrapper and enable sentinel are in place. Select the
+   intended supported MobileGL renderer and launch the game.
+2. Trace mode forces the game to `854x480`; account for that when reproducing
+   and comparing output.
+3. Reproduce the issue. Start close to the target scene because tracing starts
+   when the game launches and trace files can grow rapidly.
+4. At the desired visual state, open FCL's right-side game menu and press
+   **MobileGL Trace → Capture**. Let at least one frame present afterward.
+5. Exit the game cleanly, then pull the latest session:
+
+```sh
+python3 "$CAPTURE/adb_capture.py" --serial "$SERIAL" pull-latest
+```
+
+The default local result is:
+
+```text
+.trace-work/pulled-mobilegl-captures/capture-YYYYMMDD-HHMMSS-<renderer>/
+  full.trace
+  capture-status.json
+  capture-result.json
+```
+
+`capture-result.json` must show `"status": "captured"`. Its `targetFrame`
+is the one-based swap count used by `gltrim`; `zeroBasedFrame` is included for
+tools that use zero-based indexing.
+
+## Diagnose setup failures
+
+Inspect the active device session directly:
+
+```sh
+adb -s "$SERIAL" shell cat /sdcard/FCL/mobilegl-trace/latest-session.txt
+adb -s "$SERIAL" shell ls -lh /sdcard/FCL/mobilegl-trace
+adb -s "$SERIAL" shell cat /sdcard/FCL/mobilegl-trace/capture-*/capture-status.json
+adb -s "$SERIAL" shell cat /sdcard/FCL/mobilegl-trace/capture-*/capture-result.json
+```
+
+If `capture-status.json` reports a missing `egltrace.so`, rebuild/push the
+correct ABI and relaunch. If `capture-result.json` is absent, Capture was
+pressed without an active trace session, or no subsequent `eglSwapBuffers`
+occurred. The menu button itself only writes `capture-once.request`.
+
+Disable tracing when finished; otherwise the next supported MobileGL launch
+will trace again:
+
+```sh
+python3 "$CAPTURE/adb_capture.py" --serial "$SERIAL" disable
+```
+
+## Create a replay fixture (optional)
+
+Keep the raw `full.trace` until replay validation succeeds. To frame-trim and
+package the marked frame for MobileGL trace replay, use the existing helper:
+
+```sh
+python3 "$CAPTURE/package_capture_fixture.py" \
+  --serial "$SERIAL" \
+  --case <case-name> \
+  --apitrace <path-to-in-tree-apitrace>
+```
+
+It pulls the latest capture if necessary, uses `capture-result.json` to select
+the frame, runs `apitrace gltrim`, creates a golden image, and enforces the
+fixture archive-size limit. Follow `../trace-fixture-authoring/SKILL.md` for
+deterministic scene setup, verification, and registry changes.

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Trace Fixture Authoring on Android (FCL)"
+  short_description: "Capture and package a MobileGL trace fixture on Android FCL"
+  default_prompt: "Use $trace-fixture-authoring-on-android-fcl to capture a MobileGL trace on my Android device and package it into a replay fixture."

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/.gitignore

@@ -0,0 +1,3 @@
+# Build output produced by build_android_egltrace.py (ABI-specific, regenerated).
+out/
+__pycache__/

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/adb_capture.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+import argparse
+import subprocess
+from pathlib import Path
+
+
+REMOTE_ROOT = "/sdcard/FCL/mobilegl-trace"
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_WRAPPER = SCRIPT_DIR / "out" / "egltrace.so"
+
+
+def adb(serial, args):
+    cmd = ["adb"]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += args
+    print("+", " ".join(cmd), flush=True)
+    subprocess.run(cmd, check=True)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--serial")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    install = sub.add_parser("install-wrapper")
+    install.add_argument("--wrapper", default=str(DEFAULT_WRAPPER))
+
+    sub.add_parser("enable")
+    sub.add_parser("disable")
+    sub.add_parser("capture-once")
+
+    pull = sub.add_parser("pull-latest")
+    pull.add_argument("--output", default=".trace-work/pulled-mobilegl-captures")
+
+    args = parser.parse_args()
+    serial = args.serial
+
+    if args.command == "install-wrapper":
+        wrapper = Path(args.wrapper)
+        if not wrapper.exists():
+            raise SystemExit(f"missing wrapper: {wrapper}")
+        adb(serial, ["shell", "mkdir", "-p", REMOTE_ROOT])
+        adb(serial, ["push", str(wrapper), f"{REMOTE_ROOT}/egltrace.so"])
+    elif args.command == "enable":
+        adb(serial, ["shell", "mkdir", "-p", REMOTE_ROOT])
+        adb(serial, ["shell", f"printf enabled > {REMOTE_ROOT}/enable"])
+    elif args.command == "disable":
+        adb(serial, ["shell", "rm", "-f", f"{REMOTE_ROOT}/enable"])
+    elif args.command == "capture-once":
+        adb(serial, ["shell", "mkdir", "-p", REMOTE_ROOT])
+        adb(serial, ["shell", f"date +%s%3N > {REMOTE_ROOT}/capture-once.request"])
+    elif args.command == "pull-latest":
+        tmp = subprocess.check_output((["adb"] + (["-s", serial] if serial else []) +
+                                      ["shell", "cat", f"{REMOTE_ROOT}/latest-session.txt"]),
+                                      text=True, encoding="utf-8", errors="replace").strip()
+        if not tmp:
+            raise SystemExit("no latest-session.txt on device")
+        output = Path(args.output)
+        output.mkdir(parents=True, exist_ok=True)
+        adb(serial, ["pull", tmp, str(output / Path(tmp).name)])
+
+
+if __name__ == "__main__":
+    main()

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/android_egltrace/CMakeLists.txt

@@ -0,0 +1,191 @@
+cmake_minimum_required(VERSION 3.22.1)
+
+project(mobilegl_android_egltrace)
+
+set(APITRACE_ROOT "" CACHE PATH "Path to apitrace source tree")
+set(PATCHED_EGLTRACE_CPP "" CACHE FILEPATH "Generated and patched egltrace.cpp")
+set(PATCHED_GLPROC_EGL_CPP "" CACHE FILEPATH "Patched glproc_egl.cpp")
+if(NOT EXISTS "${APITRACE_ROOT}/wrappers")
+    message(FATAL_ERROR "APITRACE_ROOT must point to apitrace")
+endif()
+if(NOT EXISTS "${PATCHED_EGLTRACE_CPP}")
+    message(FATAL_ERROR "PATCHED_EGLTRACE_CPP is required")
+endif()
+if(NOT EXISTS "${PATCHED_GLPROC_EGL_CPP}")
+    message(FATAL_ERROR "PATCHED_GLPROC_EGL_CPP is required")
+endif()
+
+set(APITRACE_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}/apitrace")
+set(APITRACE_VERSION "mobilegl-capture")
+
+find_package(Python3 REQUIRED)
+find_package(Threads REQUIRED)
+
+include("${APITRACE_ROOT}/cmake/ConvenienceLibrary.cmake")
+
+set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
+set(ENABLE_STATIC_SNAPPY ON CACHE BOOL "" FORCE)
+set(DOC_INSTALL_DIR "doc" CACHE PATH "" FORCE)
+set(HAVE_X86 OFF CACHE BOOL "" FORCE)
+set(ZLIB_FOUND OFF CACHE BOOL "" FORCE)
+set(PNG_FOUND OFF CACHE BOOL "" FORCE)
+set(Snappy_FOUND OFF CACHE BOOL "" FORCE)
+set(BROTLIDEC_FOUND OFF CACHE BOOL "" FORCE)
+set(BROTLIENC_FOUND OFF CACHE BOOL "" FORCE)
+set(ZSTD_FOUND OFF CACHE BOOL "" FORCE)
+set(CMAKE_EXECUTABLE_FORMAT "MobileGLAndroid" CACHE INTERNAL "" FORCE)
+
+add_custom_target(check)
+add_subdirectory("${APITRACE_ROOT}/thirdparty" "${APITRACE_BINARY_DIR}/thirdparty")
+
+set(APITRACE_GENERATED_DIR "${APITRACE_BINARY_DIR}/generated")
+file(MAKE_DIRECTORY "${APITRACE_GENERATED_DIR}")
+configure_file("${APITRACE_ROOT}/version.h.in" "${APITRACE_GENERATED_DIR}/version.h" @ONLY)
+
+add_custom_command(
+        OUTPUT
+        "${APITRACE_GENERATED_DIR}/glproc.hpp"
+        "${APITRACE_GENERATED_DIR}/glproc.cpp"
+        COMMAND ${Python3_EXECUTABLE}
+        "${APITRACE_ROOT}/dispatch/glproc.py"
+        "${APITRACE_GENERATED_DIR}/glproc.hpp"
+        "${APITRACE_GENERATED_DIR}/glproc.cpp"
+        DEPENDS
+        "${APITRACE_ROOT}/dispatch/glproc.py"
+        "${APITRACE_ROOT}/dispatch/dispatch.py"
+        "${APITRACE_ROOT}/specs/wglapi.py"
+        "${APITRACE_ROOT}/specs/glxapi.py"
+        "${APITRACE_ROOT}/specs/cglapi.py"
+        "${APITRACE_ROOT}/specs/eglapi.py"
+        "${APITRACE_ROOT}/specs/glapi.py"
+        "${APITRACE_ROOT}/specs/gltypes.py"
+        "${APITRACE_ROOT}/specs/stdapi.py")
+
+add_library(apitrace_os STATIC
+        "${APITRACE_ROOT}/lib/os/os_backtrace.cpp"
+        "${APITRACE_ROOT}/lib/os/os_crtdbg.cpp"
+        "${APITRACE_ROOT}/lib/os/os_posix.cpp")
+target_include_directories(apitrace_os PUBLIC
+        "${APITRACE_ROOT}/compat"
+        "${APITRACE_ROOT}/thirdparty"
+        "${APITRACE_ROOT}/lib/os"
+        "${APITRACE_ROOT}/lib/trace")
+target_link_libraries(apitrace_os PUBLIC Threads::Threads)
+
+add_library(glproc STATIC
+        "${APITRACE_GENERATED_DIR}/glproc.cpp"
+        "${PATCHED_GLPROC_EGL_CPP}")
+target_include_directories(glproc PUBLIC
+        "${APITRACE_GENERATED_DIR}"
+        "${APITRACE_ROOT}/wrappers"
+        "${APITRACE_ROOT}/dispatch"
+        "${APITRACE_ROOT}/lib/os"
+        "${APITRACE_ROOT}/thirdparty/khronos")
+target_link_libraries(glproc PUBLIC apitrace_os dl)
+
+add_library(highlight STATIC "${APITRACE_ROOT}/lib/highlight/highlight.cpp")
+target_include_directories(highlight PUBLIC "${APITRACE_ROOT}/lib/highlight")
+
+add_library(guids STATIC "${APITRACE_ROOT}/lib/guids/guids.cpp")
+target_include_directories(guids PUBLIC
+        "${APITRACE_ROOT}/lib/guids"
+        "${APITRACE_ROOT}/lib/os")
+
+add_library(common STATIC
+        "${APITRACE_ROOT}/lib/trace/trace_callset.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_dump.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_fast_callset.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_read.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_zlib.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_brotli.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_snappy.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_zstd.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_file_zstd_seekable.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_model.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_option.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_ostream_snappy.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_ostream_zlib.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_ostream_zstd.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_parser.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_parser_flags.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_parser_loop.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_profiler.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_writer.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_writer_local.cpp"
+        "${APITRACE_ROOT}/lib/trace/trace_writer_model.cpp")
+target_include_directories(common PUBLIC
+        "${APITRACE_ROOT}/compat"
+        "${APITRACE_ROOT}/thirdparty"
+        "${APITRACE_ROOT}/lib/guids"
+        "${APITRACE_ROOT}/lib/highlight"
+        "${APITRACE_ROOT}/lib/os"
+        "${APITRACE_ROOT}/lib/trace"
+        "${APITRACE_ROOT}/lib/ubjson")
+target_link_libraries(common PUBLIC
+        guids
+        highlight
+        apitrace_os
+        Snappy::snappy
+        ZLIB::ZLIB
+        PkgConfig::BROTLIDEC
+        PkgConfig::ZSTD
+        zstd_seekable)
+
+add_convenience_library(trace
+        "${APITRACE_ROOT}/wrappers/memtrace.hpp"
+        "${APITRACE_ROOT}/wrappers/memtrace.cpp")
+target_include_directories(trace PUBLIC
+        "${APITRACE_ROOT}/thirdparty/crc32c")
+target_link_libraries(trace
+        common
+        guids
+        crc32c)
+
+add_library(glhelpers STATIC
+        "${APITRACE_ROOT}/helpers/glfeatures.cpp"
+        "${APITRACE_ROOT}/helpers/eglsize.cpp")
+target_include_directories(glhelpers PUBLIC
+        "${APITRACE_GENERATED_DIR}"
+        "${APITRACE_ROOT}/dispatch"
+        "${APITRACE_ROOT}/helpers"
+        "${APITRACE_ROOT}/lib/os"
+        "${APITRACE_ROOT}/thirdparty/khronos")
+target_link_libraries(glhelpers PUBLIC glproc apitrace_os)
+
+add_convenience_library(gltrace_common
+        "${APITRACE_ROOT}/wrappers/glcaps.cpp"
+        "${APITRACE_ROOT}/wrappers/config.cpp"
+        "${APITRACE_ROOT}/wrappers/gltrace_arrays.cpp"
+        "${APITRACE_ROOT}/wrappers/gltrace_state.cpp"
+        "${APITRACE_ROOT}/wrappers/glmemshadow.hpp"
+        "${APITRACE_ROOT}/wrappers/glmemshadow.cpp"
+        "${APITRACE_ROOT}/wrappers/gltrace_unpack_compressed.hpp"
+        "${APITRACE_ROOT}/wrappers/gltrace_unpack_compressed.cpp")
+add_dependencies(gltrace_common glproc)
+target_include_directories(gltrace_common PUBLIC
+        "${APITRACE_ROOT}/wrappers")
+target_link_libraries(gltrace_common
+        glhelpers
+        trace)
+
+add_library(egltrace SHARED
+        "${PATCHED_EGLTRACE_CPP}"
+        "${APITRACE_ROOT}/wrappers/dlsym.cpp"
+        "${PATCHED_GLPROC_EGL_CPP}")
+add_dependencies(egltrace glproc)
+set_target_properties(egltrace PROPERTIES PREFIX "")
+target_compile_definitions(egltrace PRIVATE -DEGLTRACE=1)
+target_include_directories(egltrace PRIVATE
+        "${APITRACE_ROOT}/wrappers"
+        "${APITRACE_GENERATED_DIR}"
+        "${APITRACE_ROOT}/helpers"
+        "${APITRACE_ROOT}/dispatch"
+        "${APITRACE_ROOT}/lib/os"
+        "${APITRACE_ROOT}/lib/trace"
+        "${APITRACE_ROOT}/thirdparty/khronos")
+target_link_libraries(egltrace
+        gltrace_common
+        glproc
+        Threads::Threads
+        dl)

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/build_android_egltrace.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# This script is bundled inside the trace-fixture-authoring-on-android-fcl skill at
+# <FCL>/MobileGL/tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/.
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_REPO = SCRIPT_DIR.parents[5]  # -> FoldCraftLauncher repo root
+DEFAULT_OUTPUT = SCRIPT_DIR / "out" / "egltrace.so"
+
+
+def run(cmd, cwd=None):
+    print("+", " ".join(str(part) for part in cmd), flush=True)
+    subprocess.run(cmd, cwd=cwd, check=True)
+
+
+def find_ndk(repo):
+    for key in ("ANDROID_NDK_HOME", "ANDROID_NDK_ROOT"):
+        value = os.environ.get(key)
+        if value:
+            return Path(value)
+    for key in ("ANDROID_HOME", "ANDROID_SDK_ROOT"):
+        value = os.environ.get(key)
+        if value:
+            ndk_root = Path(value) / "ndk"
+            if ndk_root.exists():
+                versions = sorted([p for p in ndk_root.iterdir() if p.is_dir()])
+                if versions:
+                    return versions[-1]
+    local = repo / "local.properties"
+    if local.exists():
+        sdk = None
+        ndk = None
+        for line in local.read_text(encoding="utf-8", errors="ignore").splitlines():
+            if line.startswith("sdk.dir="):
+                sdk = Path(line.split("=", 1)[1].replace("\\:", ":"))
+            if line.startswith("ndk.dir="):
+                ndk = Path(line.split("=", 1)[1].replace("\\:", ":"))
+        if ndk:
+            return ndk
+        if sdk:
+            ndk_root = sdk / "ndk"
+            if ndk_root.exists():
+                versions = sorted([p for p in ndk_root.iterdir() if p.is_dir()])
+                if versions:
+                    return versions[-1]
+    raise SystemExit("Android NDK not found; set ANDROID_NDK_HOME or local.properties sdk.dir/ndk.dir")
+
+
+def generate_and_patch(repo, build_dir):
+    wrapper_dir = repo / "MobileGL" / "3rdparty" / "apitrace" / "wrappers"
+    generated = build_dir / "patched" / "egltrace.cpp"
+    generated.parent.mkdir(parents=True, exist_ok=True)
+    with generated.open("w", encoding="utf-8", newline="\n") as out:
+        subprocess.run([sys.executable, str(wrapper_dir / "egltrace.py")], cwd=wrapper_dir, stdout=out, check=True)
+
+    text = generated.read_text(encoding="utf-8")
+    helper = r'''
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/stat.h>
+#include <time.h>
+#include <unistd.h>
+
+static unsigned long long mobilegl_capture_swap_count = 0;
+
+static long long mobilegl_capture_time_ms(void) {
+    struct timespec ts;
+    clock_gettime(CLOCK_REALTIME, &ts);
+    return (long long) ts.tv_sec * 1000LL + ts.tv_nsec / 1000000LL;
+}
+
+static int mobilegl_capture_exists(const char *path) {
+    return path != NULL && path[0] != '\0' && access(path, F_OK) == 0;
+}
+
+static void mobilegl_capture_record_request(void) {
+    ++mobilegl_capture_swap_count;
+    const char *request = getenv("MOBILEGL_TRACE_CAPTURE_REQUEST_FILE");
+    const char *output = getenv("MOBILEGL_TRACE_CAPTURE_FRAME_FILE");
+    if (!mobilegl_capture_exists(request) || output == NULL || output[0] == '\0') {
+        return;
+    }
+    unlink(request);
+    FILE *file = fopen(output, "w");
+    if (file == NULL) {
+        return;
+    }
+    const char *trace_file = getenv("TRACE_FILE");
+    fprintf(file,
+            "{\n"
+            "  \"status\": \"captured\",\n"
+            "  \"swapCount\": %llu,\n"
+            "  \"targetFrame\": %llu,\n"
+            "  \"zeroBasedFrame\": %llu,\n"
+            "  \"capturedAtMs\": %lld,\n"
+            "  \"traceFile\": \"%s\"\n"
+            "}\n",
+            mobilegl_capture_swap_count,
+            mobilegl_capture_swap_count,
+            mobilegl_capture_swap_count == 0 ? 0 : mobilegl_capture_swap_count - 1,
+            mobilegl_capture_time_ms(),
+            trace_file == NULL ? "" : trace_file);
+    fclose(file);
+}
+'''
+    insert_at = text.find("#include")
+    if insert_at < 0:
+        raise SystemExit("generated egltrace.cpp has no include block")
+    next_block = text.find("\n\n", insert_at)
+    text = text[:next_block] + "\n" + helper + text[next_block:]
+
+    needle = "EGLBoolean EGLAPIENTRY eglSwapBuffers(EGLDisplay dpy, EGLSurface surface)"
+    start = text.find(needle)
+    if start < 0:
+        raise SystemExit("generated egltrace.cpp has no eglSwapBuffers wrapper to patch")
+    brace = text.find("{", start)
+    if brace < 0:
+        raise SystemExit("eglSwapBuffers wrapper has no function body")
+    text = text[:brace + 1] + "\n    mobilegl_capture_record_request();" + text[brace + 1:]
+    generated.write_text(text, encoding="utf-8", newline="\n")
+    return generated
+
+
+def patch_glproc_egl(repo, build_dir):
+    source = repo / "MobileGL" / "3rdparty" / "apitrace" / "wrappers" / "glproc_egl.cpp"
+    patched = build_dir / "patched" / "glproc_egl.cpp"
+    patched.parent.mkdir(parents=True, exist_ok=True)
+    text = source.read_text(encoding="utf-8")
+    text = text.replace('#include "dlopen.hpp"\n', '#include "dlopen.hpp"\n#include <stdlib.h>\n')
+    needle = """void *
+_getPublicProcAddress(const char *procName)
+{
+    void *proc;
+
+"""
+    replacement = """void *
+_getPublicProcAddress(const char *procName)
+{
+    void *proc;
+
+    static void *traceLibGL = NULL;
+    static bool triedTraceLibGL = false;
+    if (!triedTraceLibGL) {
+        triedTraceLibGL = true;
+        const char *traceLibGLName = getenv("TRACE_LIBGL");
+        if (traceLibGLName && traceLibGLName[0]) {
+            traceLibGL = _dlopen(traceLibGLName, RTLD_GLOBAL | RTLD_LAZY | RTLD_DEEPBIND);
+        }
+    }
+    if (traceLibGL) {
+        proc = dlsym(traceLibGL, procName);
+        if (proc) {
+            return proc;
+        }
+    }
+
+"""
+    if needle not in text:
+        raise SystemExit("glproc_egl.cpp patch point not found")
+    text = text.replace(needle, replacement, 1)
+    patched.write_text(text, encoding="utf-8", newline="\n")
+    return patched
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--repo", default=str(DEFAULT_REPO), help="FoldCraftLauncher repo root")
+    parser.add_argument("--abi", default="arm64-v8a")
+    parser.add_argument("--android-platform", default="android-23")
+    parser.add_argument("--build-dir", default=".trace-work/build-android-egltrace")
+    parser.add_argument("--output", default=str(DEFAULT_OUTPUT))
+    args = parser.parse_args()
+
+    repo = Path(args.repo).resolve()
+    ndk = find_ndk(repo)
+    build_dir = (repo / args.build_dir / args.abi).resolve()
+    apitrace = repo / "MobileGL" / "3rdparty" / "apitrace"
+    source_dir = SCRIPT_DIR / "android_egltrace"
+    toolchain = ndk / "build" / "cmake" / "android.toolchain.cmake"
+    if not apitrace.exists():
+        raise SystemExit(f"missing apitrace checkout: {apitrace}")
+    if not source_dir.exists():
+        raise SystemExit(f"missing wrapper CMake project: {source_dir}")
+    if not toolchain.exists():
+        raise SystemExit(f"missing Android toolchain: {toolchain}")
+    cache = build_dir / "CMakeCache.txt"
+    if cache.exists() and "CMAKE_GENERATOR:INTERNAL=Ninja" not in cache.read_text(encoding="utf-8", errors="ignore"):
+        shutil.rmtree(build_dir)
+    elif cache.exists() and str(source_dir).replace("\\", "/") not in cache.read_text(encoding="utf-8", errors="ignore").replace("\\", "/"):
+        shutil.rmtree(build_dir)
+
+    ninja = shutil.which("ninja")
+    if ninja is None:
+        cmake_ninjas = sorted((Path(os.environ.get("ANDROID_HOME", "")) / "cmake").glob("*/bin/ninja.exe"))
+        ninja = str(cmake_ninjas[-1]) if cmake_ninjas else None
+    if ninja is None:
+        raise SystemExit("ninja not found; install Ninja or Android SDK CMake")
+
+    patched_egltrace = generate_and_patch(repo, build_dir)
+    patched_glproc_egl = patch_glproc_egl(repo, build_dir)
+
+    run([
+        "cmake", "-G", "Ninja", "-S", str(source_dir), "-B", str(build_dir),
+        "-DCMAKE_BUILD_TYPE=Release",
+        f"-DCMAKE_TOOLCHAIN_FILE={toolchain}",
+        f"-DCMAKE_MAKE_PROGRAM={ninja}",
+        f"-DANDROID_ABI={args.abi}",
+        f"-DANDROID_PLATFORM={args.android_platform}",
+        f"-DAPITRACE_ROOT={apitrace}",
+        f"-DPATCHED_EGLTRACE_CPP={patched_egltrace}",
+        f"-DPATCHED_GLPROC_EGL_CPP={patched_glproc_egl}",
+    ])
+    run(["cmake", "--build", str(build_dir), "--target", "egltrace", "--parallel"])
+
+    output = Path(args.output)
+    if not output.is_absolute():
+        output = repo / output
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    candidates = list(build_dir.rglob("egltrace.so"))
+    if not candidates:
+        raise SystemExit("egltrace.so was not produced")
+    shutil.copy2(candidates[0], output)
+    print(output)
+
+
+if __name__ == "__main__":
+    main()

tools/trace_replay/skills/trace-fixture-authoring-on-android-fcl/scripts/package_capture_fixture.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import tarfile
+from pathlib import Path
+
+DEFAULT_MAX_ARCHIVE_BYTES = 20 * 1024 * 1024
+# Bundled under the skill at .../skills/trace-fixture-authoring-on-android-fcl/scripts/.
+SCRIPT_DIR = Path(__file__).resolve().parent
+DEFAULT_REPO = SCRIPT_DIR.parents[5]  # -> FoldCraftLauncher repo root
+
+
+def run(cmd, cwd=None, capture=False):
+    print("+", " ".join(str(part) for part in cmd), flush=True)
+    if capture:
+        return subprocess.check_output(cmd, cwd=cwd, text=True, encoding="utf-8", errors="replace")
+    subprocess.run(cmd, cwd=cwd, check=True)
+    return ""
+
+
+def adb(args, serial=None):
+    cmd = ["adb"]
+    if serial:
+        cmd += ["-s", serial]
+    cmd += args
+    return run(cmd, capture=True)
+
+
+def pull_latest(serial, dest):
+    latest = adb(["shell", "cat", "/sdcard/FCL/mobilegl-trace/latest-session.txt"], serial).strip()
+    if not latest:
+        raise SystemExit("device has no /sdcard/FCL/mobilegl-trace/latest-session.txt")
+    dest.mkdir(parents=True, exist_ok=True)
+    local = dest / Path(latest).name
+    if local.exists():
+        shutil.rmtree(local)
+    adb(["pull", latest, str(local)], serial)
+    return local
+
+
+def choose_target_frame(capture_dir, explicit_frame):
+    if explicit_frame is not None:
+        return explicit_frame
+    result = capture_dir / "capture-result.json"
+    if not result.exists():
+        raise SystemExit(f"missing {result}; press the FCL capture button or create capture-once.request first")
+    data = json.loads(result.read_text(encoding="utf-8"))
+    if "targetFrame" not in data:
+        raise SystemExit(f"{result} has no targetFrame")
+    return int(data["targetFrame"])
+
+
+def choose_snapshot(golden_dir):
+    pngs = sorted(golden_dir.glob("*.png"))
+    if not pngs:
+        raise SystemExit(f"no snapshots produced in {golden_dir}")
+    def call_no(path):
+        match = re.search(r"\.(\d+)\.png$", path.name)
+        return int(match.group(1)) if match else -1
+    return max(pngs, key=call_no)
+
+
+def choose_target_call(explicit_call, golden):
+    if explicit_call is not None:
+        return explicit_call
+    if golden is None:
+        return None
+    match = re.search(r"\.(\d+)\.png$", golden.name)
+    return int(match.group(1)) if match else None
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--repo", default=str(DEFAULT_REPO), help="FoldCraftLauncher repo root")
+    parser.add_argument("--serial", help="adb serial; when set, pull latest capture from device")
+    parser.add_argument("--capture-dir", help="local capture directory; defaults to pulled latest")
+    parser.add_argument("--pull-root", default=".trace-work/pulled-mobilegl-captures")
+    parser.add_argument("--case", required=True)
+    parser.add_argument("--target-frame", type=int)
+    parser.add_argument("--target-call", type=int)
+    parser.add_argument("--golden", help="existing golden PNG, normally produced by Android replay")
+    parser.add_argument("--skip-desktop-golden", action="store_true",
+                        help="skip apitrace replay --headless; requires --golden and --target-call")
+    parser.add_argument("--apitrace", default="apitrace")
+    parser.add_argument("--fixtures-dir", default="MobileGL/tools/trace_replay/fixtures")
+    parser.add_argument("--width", type=int, default=854)
+    parser.add_argument("--height", type=int, default=480)
+    parser.add_argument("--ssim-threshold", default="0.99")
+    parser.add_argument("--max-archive-bytes", type=int, default=DEFAULT_MAX_ARCHIVE_BYTES)
+    args = parser.parse_args()
+
+    repo = Path(args.repo).resolve()
+    if args.capture_dir:
+        capture_dir = Path(args.capture_dir).resolve()
+    elif args.serial:
+        capture_dir = pull_latest(args.serial, repo / args.pull_root)
+    else:
+        raise SystemExit("pass --capture-dir or --serial")
+
+    full_trace = capture_dir / "full.trace"
+    if not full_trace.exists():
+        raise SystemExit(f"missing trace: {full_trace}")
+    target_frame = choose_target_frame(capture_dir, args.target_frame)
+    work = capture_dir / "fixture-work"
+    if work.exists():
+        shutil.rmtree(work)
+    work.mkdir(parents=True)
+
+    frames_txt = work / "frames.txt"
+    frames_txt.write_text(run([args.apitrace, "dump", "--calls=frame", str(full_trace)], capture=True), encoding="utf-8")
+
+    trimmed = work / "trace.trace"
+    run([args.apitrace, "gltrim", "-f", str(target_frame), "--output", str(trimmed), str(full_trace)])
+
+    supplied_golden = Path(args.golden).resolve() if args.golden else None
+    target_call = choose_target_call(args.target_call, supplied_golden)
+    if args.skip_desktop_golden:
+        if supplied_golden is None or target_call is None:
+            raise SystemExit("--skip-desktop-golden requires --golden and --target-call")
+        golden = supplied_golden
+    else:
+        golden_dir = work / "golden"
+        golden_dir.mkdir()
+        prefix = golden_dir / f"{args.case}."
+        run([args.apitrace, "replay", "--headless", "--snapshot-prefix", str(prefix), "--call-nos", str(trimmed)])
+        golden = choose_snapshot(golden_dir)
+        target_call = choose_target_call(args.target_call, golden)
+        if target_call is None:
+            raise SystemExit(f"cannot infer target call from {golden}")
+
+    fixtures = (repo / args.fixtures_dir).resolve()
+    fixtures.mkdir(parents=True, exist_ok=True)
+    archive_root = work / "archive"
+    archive_root.mkdir()
+    shutil.copy2(trimmed, archive_root / "trace.trace")
+    tgz = fixtures / f"{args.case}.tgz"
+    with tarfile.open(tgz, "w:gz") as tar:
+        tar.add(archive_root / "trace.trace", arcname="trace.trace")
+    archive_size = tgz.stat().st_size
+    if archive_size > args.max_archive_bytes:
+        raise SystemExit(
+            f"{tgz} is {archive_size} bytes, over the {args.max_archive_bytes} byte fixture limit; "
+            "choose an earlier/smaller frame and re-run gltrim"
+        )
+    golden_out = fixtures / f"{args.case}.{target_call:010d}.png"
+    shutil.copy2(golden, golden_out)
+
+    manifest = {
+        "name": args.case,
+        "trace_archive": tgz.name,
+        "trace_file": "trace.trace",
+        "golden": golden_out.name,
+        "target_call": target_call,
+        "width": args.width,
+        "height": args.height,
+        "ssim_threshold": float(args.ssim_threshold),
+        "archive_size": archive_size,
+    }
+    manifest_path = capture_dir / f"{args.case}.fixture.json"
+    manifest_path.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    print(json.dumps(manifest, indent=2))
+
+
+if __name__ == "__main__":
+    main()

tools/trace_replay/skills/trace-fixture-authoring/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: trace-fixture-authoring
+description: Author a deterministic MobileGL trace-replay fixture from a captured apitrace - build the in-tree apitrace fork, capture a reproducible scene, frame-trim with gltrim, generate and verify a golden image, package under the archive-size budget, register the case in trace_cases.json, and validate on Linux and Android. Use when adding or re-trimming a trace_replay regression fixture.
+---
+
 # Trace fixture authoring
 
 ## Variables
@@ -75,10 +80,19 @@ Minecraft specifics that keep the capture deterministic and small:
   `doMobSpawning`, `randomTickSpeed 0`, a fixed `DayTime`, and the player
   `Rotation` that frames the intended subject. The camera snaps to the saved
   rotation on world join, so composition is edited in the save, not in-game.
-- `options.txt`: `pauseOnLostFocus:false`, a low `maxFps` (10 works), and a
+- `options.txt`: `pauseOnLostFocus:false`, a low `maxFps` (10 works), a small
-  small `renderDistance` (3). Frame rate and render distance are the two main
+  `renderDistance` (3), and the capture resolution pinned to `WIDTH` x `HEIGHT`
-  levers on trace size; a ~35 s in-world session at 10 fps lands well under
+  (854x480) via `overrideWidth`/`overrideHeight` (or `--width`/`--height`).
-  the archive budget after repack.
+  These are the main levers on fixture size: a low frame rate keeps the full
+  trace short, a small render distance keeps per-frame geometry down, and the
+  854x480 resolution keeps every render target the frame references small (a
+  trimmed frame's framebuffer/attachment textures scale with resolution
+  squared). A ~35 s in-world session at 10 fps and 854x480 lands well under the
+  archive budget after repack.
+- `maxFps` has a practical floor: Minecraft ignores values below ~10 and falls
+  back to unlimited/vsync (a `maxFps:1` capture rendered ~60 fps and ballooned
+  the trace). 10 is as low as this lever goes, so do not count on a lower frame
+  rate to shrink the frame count further.
 - Enter the world non-interactively with `--quickPlaySingleplayer <world>` so
   every capture takes the same path from boot to gameplay.
 - Keep the game window UNFOCUSED for the whole capture (focus the desktop
@@ -111,6 +125,61 @@ For Java:
 An `@argfile` with the full JVM+game command line keeps the invocation
 reproducible across recaptures.
 
+NEVER put a real credential on the traced command line. apitrace records the
+traced process's argv into the trace as a `process.commandLine` property, so
+anything passed there - `--accessToken`, session tokens, API keys - is embedded
+in the trace and ships inside the committed fixture. Minecraft never validates
+`--accessToken` for singleplayer, so pass a placeholder (`--accessToken 0`);
+`--username`/`--uuid` are public and may stay real. Before packaging, grep the
+UNCOMPRESSED trace for the secret to confirm it is absent:
+
+```sh
+"$APITRACE" repack "$WORK/$CASE/trace.trace" /tmp/plain.trace   # decompress
+grep -ac "<secret-prefix>" /tmp/plain.trace                     # must be 0
+```
+
+If a secret has already been captured, it can be scrubbed in place instead of
+recapturing: apitrace's snappy container is `[length][raw snappy]` chunks with
+no checksum, and a high-entropy secret is stored as literal bytes, so replacing
+those bytes with an EQUAL-LENGTH filler keeps the container valid and leaves the
+GL call stream byte-identical. Blank every maximal run of the secret (it splits
+across chunks), then verify: frame count unchanged, the decompressed trace no
+longer contains the secret, and the replayed target frame still matches the
+golden. Treat any already-pushed trace as leaked regardless - rotate the
+credential, since a force-push does not purge the LFS object from the remote.
+
+Watch for vendor-gated shader paths. Shader packs branch on the GL vendor that
+Iris injects (`MC_GL_VENDOR_NVIDIA` / `_AMD` / ...) and compile a
+vendor-exclusive path, so capturing on an NVIDIA card can bake NVIDIA-only GLSL
+into the fixture (iterationRP selects `subgroupPartitionNV` /
+`GL_NV_shader_subgroup_partitioned` instead of the portable
+`subgroupShuffleXor`). Iris resolves the `#ifdef` before `glShaderSource`, so
+only the taken branch is in the trace and the fixture cannot replay on the
+mobile GPUs MobileGL targets. Rather than hunting for a second GPU (the Windows
+per-app GPU preference does NOT change which OpenGL ICD is loaded), mask the
+vendor at capture time with apitrace's own config - point `GLTRACE_CONF` at a
+file containing:
+
+```
+GL_VENDOR = "NoVIDIA (MobileGL spoof)"
+GL_RENDERER = "NoVIDIA (MobileGL spoof)"
+```
+
+The wrapper then returns that from `glGetString`, so the pack compiles the
+portable path while still running on the fast driver. Pick a string that does
+NOT contain the real vendor name as a substring (Iris matches by substring, so
+"Not NVIDIA ..." would still match) and that is self-describing, so nobody later
+mistakes the trace for a capture on different hardware. Afterwards, grep the
+decoded trace to confirm the vendor-exclusive symbols are gone:
+
+```sh
+"$APITRACE" dump "$WORK/$CASE/full.trace" | grep -c subgroupPartitionNV   # must be 0
+```
+
+Software rasterisers are not a substitute here: llvmpipe exposes no
+`GL_KHR_shader_subgroup` at all, and packs that use subgroup ops unguarded
+cannot run on it in any vendor configuration.
+
 Keep `full.trace` until both backends are validated.
 
 Persistent-mapped buffers: apps may legally write a `GL_MAP_PERSISTENT_BIT`
@@ -172,12 +241,37 @@ name"-style retrace warnings. If content is missing from the trimmed trace
 but present in the full trace, the fix belongs in `3rdparty/apitrace`'s
 frametrim, not in the fixture.
 
+Temporal shaders (auto-exposure / eye adaptation, TAA, temporal reflections -
+e.g. the iterationRP shader pack) break a single-frame `gltrim -f`: the target
+frame reads its predecessors' feedback buffers, which the isolated frame no
+longer contains, so a mid-sequence frame replays overexposed to white (and any
+timed name/version overlay the pack draws in its first seconds silently drops).
+The symptom is a trimmed frame that looks blown-out or washed while the same
+frame of `full.trace` renders correctly, and it gets worse the later the frame.
+When a single-frame trim of such a pack cannot be made to render correctly, keep
+the temporal history instead of the dependency slice: select an early in-world
+target frame and trim a PREFIX with `apitrace trim --calls=0-<target-swap-call>`
+(it preserves call numbers, so `target_call` is just that swap call). The prefix
+replays every frame up to the target, so its temporal buffers are correct.
+Prefer the earliest frame that already shows the intended subject - fewer lead-in
+frames means a smaller archive and a faster CI replay. This deviates from the
+single-frame rule deliberately; note it in the README entry.
+
 ## Generate golden
 
 Generate frame snapshots from the trimmed trace, then choose the snapshot that
 matches the selected frame. The target call used by replay registration must
 come from the trimmed trace, not from a call-filtered full-trace selection.
 
+Generate the golden with the same GL stack the scene was captured on. A headless
+software renderer (llvmpipe) is fine for vanilla and light packs, but heavy
+ray-traced shader packs (compute-driven atmosphere LUTs, screen-space tracing -
+e.g. iterationRP) render as solid black or blown-out white under llvmpipe. Drive
+the golden from a real GPU instead: on Windows a stock `glretrace.exe` (an
+upstream apitrace release works for replay even on an in-tree-fork trace) replays
+the trace on the discrete GPU and snapshots the target call. Read the resulting
+PNG back and confirm the subject actually rendered before trusting it as golden.
+
 ```sh
 mkdir -p "$WORK/$CASE/golden"
 "$APITRACE" replay --headless \
@@ -255,6 +349,15 @@ Check the final archive size. The committed fixture archive should be less than
 with a shorter run or a lower frame rate / render distance instead of adding
 call-based filtering.
 
+Some packs have an irreducible size floor: a large static lookup table baked
+into the pack (iterationRP ships a ~17 MiB half-float atmosphere LUT that the
+target frame samples) lands in the trace once and does not compress, so every
+variant - single frame, prefix, or full - sits near the same size regardless of
+frame count. When the floor alone exceeds the budget, neither a lower frame rate
+nor fewer frames helps; confirm the fixture is worth the exception and record the
+measured size in the case's README entry rather than chasing an unreachable
+target.
+
 ```sh
 du -h "$REPO/tools/trace_replay/fixtures/$CASE.tgz"
 tar -tzf "$REPO/tools/trace_replay/fixtures/$CASE.tgz"

tools/trace_replay/skills/trace-fixture-authoring/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MobileGL Trace Fixture Authoring"
+  short_description: "Author and register a MobileGL trace-replay fixture"
+  default_prompt: "Use $trace-fixture-authoring to author and register a MobileGL trace replay fixture."

tools/trace_replay/trace_cases.json

@@ -276,12 +276,10 @@
     },
     {
       "name": "improved-transparency-minecraft-26.3",
-      "ci": false,
       "trace_archive": "improved-transparency-minecraft-26.3.tgz",
       "golden": "improved-transparency-minecraft-26.3.0002667619.png",
       "target_call": 2667619,
-      "timeout_seconds": 1800,
+      "timeout_seconds": 1800
-      "coherent_as_flush": true
     },
     {
       "name": "minecraft-1.21.4-fabric-iris-iterationrp-in-world",