matc: treat DYN DIR and SRE as spec constants

This commit does not exhaustively replace these variants with spec constants.
Rather, this is a necessary first step into full replacement.

As was the case before this commit, all combinations of variants are still
generated as their own individual sources. However, matc has been changed in the
way that it generates these variants, such that it will be trivial to later
remove them.

Firstly, instead of matc selectively generating specific uniform buffers and
structs specific to these variants per-specialization, generates them *always*
as long as the specialization "has lighting". Specifically, a specialization
"has lighting" if all of the following conditions are true:

- It's a lit material, or it's an unlit material with a shadow multiplier.
- It's not an SSR variant.

As a result, there is some redundant, potentially unused code generated in all
variants.

Additionally, all shader code has been refactored to replace `#if VARIANT_X`
preprocessor directives with `if (MATERIAL_HAS_X)` statements, where
`MATERIAL_HAS_X` is a spec constant. The *only difference* the code generated
between a specialization with DYN, DIR, and SRE turned on or off is the *default
value* of this spec constant.

Technically, assuming that all shader code optimizations are deterministic, we
should see some reduction of material file sizes, since only one line of code
would differ between these variants being turned on and left off. However, we
may add to some of that size given the redundant information added to all other
variants.

I tested this experimentally by compiling gltf_viewer at this commit and the
commit before it in release mode and totalling the size of all of the filamat
files generated.

- Parent commit: 44.44 MiB
- This commit: 36.67 MiB

So we have a reduction of about 8 MiB, which is around 20% of the original file
size.

(Note that I took these measurements a long time ago and they might not be still
accurate...)

.github/actions/get-commit-msg/action.yml

@@ -27,17 +27,24 @@ runs:
         echo "$HASH" > /tmp/commit_hash.txt
     - name: Find commit message (PR)
       shell: bash
-      id: checkout_code
       if: github.event_name == 'pull_request'
       run: |
-        BEFORE_HASH=$(git rev-parse HEAD)
-        echo "hash=$BEFORE_HASH" >> "$GITHUB_OUTPUT"
-        # Next we will checkout the actual head (not the merge commits) of the PR
-        AFTER_HASH="${{ github.event.pull_request.head.sha }}"
-        git checkout $AFTER_HASH
-        COMMIT_MESSAGE=$(git log -1 --no-merges)
-        echo "$COMMIT_MESSAGE" > /tmp/commit_msg.txt
-        echo "$AFTER_HASH" > /tmp/commit_hash.txt
+        PR_NUMBER="${{ github.event.pull_request.number }}"
+        # Fetch the head of the PR explicitly to handle forks. Depth 50 ensures we can traverse past recent merge commits.
+        git fetch --depth=50 origin "pull/$PR_NUMBER/head:pr-head"
+
+        COMMIT_HASH=$(git log -1 --no-merges pr-head --format=%H)
+        AUTHOR_NAME=$(git log -1 --no-merges pr-head --format=%an)
+        AUTHOR_EMAIL=$(git log -1 --no-merges pr-head --format=%ae)
+        TSTAMP=$(git log -1 --no-merges pr-head --format=%aI)
+        COMMIT_MESSAGE=$(git log -1 --no-merges pr-head --format=%B)
+
+        echo "commit $COMMIT_HASH" > /tmp/commit_msg.txt
+        echo "Author: ${AUTHOR_NAME}<${AUTHOR_EMAIL}>" >> /tmp/commit_msg.txt
+        echo "Date: ${TSTAMP}" >> /tmp/commit_msg.txt
+        echo "" >> /tmp/commit_msg.txt
+        echo "$COMMIT_MESSAGE" >> /tmp/commit_msg.txt
+        echo "$COMMIT_HASH" > /tmp/commit_hash.txt
     - shell: bash
       id: action_output
       run: |
@@ -47,9 +54,4 @@ runs:
         cat /tmp/commit_msg.txt >> "$GITHUB_OUTPUT"
         echo "$DELIMITER" >> "$GITHUB_OUTPUT"
         # Get the commit hash
-        echo "hash=$(cat /tmp/commit_hash.txt)" >> "$GITHUB_OUTPUT"
-    - name: Cleanup Find commit message (PR)
-      shell: bash
-      if: github.event_name == 'pull_request'
-      run: |
-        git checkout ${{ steps.checkout_code.outputs.hash }}
+        echo "hash=$(cat /tmp/commit_hash.txt)" >> "$GITHUB_OUTPUT"

.github/actions/renderdiff-generate/action.yml

@@ -0,0 +1,26 @@
+name: 'Renderdiff Generate'
+description: 'Sets up prerequisites and runs the generate script for renderdiff'
+runs:
+  using: "composite"
+  steps:
+    - uses: ./.github/actions/mac-prereq
+    - uses: ./.github/actions/get-gltf-assets
+    - uses: ./.github/actions/get-mesa
+    - uses: ./.github/actions/get-vulkan-sdk
+    - name: Prerequisites
+      run: |
+        # Must have at least clang-16 for a webgpu/dawn build.
+        sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer
+      shell: bash
+    - name: Generate images
+      run: |
+        TEST_DIR=test/renderdiff
+        source ${TEST_DIR}/src/preamble.sh
+        set -eux
+        bash ${TEST_DIR}/generate.sh
+        set +eux
+      shell: bash
+    - name: Build diffimg tool
+      run: |
+        ./build.sh release diffimg
+      shell: bash

.github/workflows/postsubmit-main.yml

@@ -10,16 +10,27 @@ jobs:
   # a branch on filament-assets.
   update-renderdiff-goldens:
     name: update-renderdiff-goldens
-    runs-on: 'ubuntu-24.04-4core'
+    runs-on: 'macos-14-xlarge'
     steps:
       - uses: actions/checkout@v4.1.6
         with:
           fetch-depth: 0
-      - uses: ./.github/actions/linux-prereq
       - id: get_commit_msg
         uses: ./.github/actions/get-commit-msg
-      - name: Build diffimg
-        run: ./build.sh release diffimg
+      - name: Check if accepting new goldens
+        id: check_accept
+        env:
+          COMMIT_MESSAGE: ${{ steps.get_commit_msg.outputs.msg }}
+        run: |
+          if echo "${COMMIT_MESSAGE}" | python3 test/renderdiff/src/commit_msg.py --mode=accept_new_goldens; then
+            echo "accept=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "accept=false" >> "$GITHUB_OUTPUT"
+          fi
+        shell: bash
+      - name: Renderdiff Generate for new goldens
+        if: steps.check_accept.outputs.accept == 'true'
+        uses: ./.github/actions/renderdiff-generate
       - name: Run update script
         env:
           GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
@@ -27,10 +38,24 @@ jobs:
         run: |
           GOLDEN_BRANCH=$(echo "${COMMIT_MESSAGE}" | python3 test/renderdiff/src/commit_msg.py)
           COMMIT_HASH="${{ steps.get_commit_msg.outputs.hash }}"
+
+          git config --global user.email "filament.bot@gmail.com"
+          git config --global user.name "Filament Bot"
+          git config --global credential.helper cache
+
+          if [[ "${{ steps.check_accept.outputs.accept }}" == "true" ]]; then
+              SHORT_HASH="${COMMIT_HASH:0:8}"
+              GOLDEN_BRANCH="accept-goldens-${SHORT_HASH}"
+              echo "Generating new goldens for branch ${GOLDEN_BRANCH}"
+              python3 test/renderdiff/src/update_golden.py \
+                  --branch=${GOLDEN_BRANCH} \
+                  --source=$(pwd)/out/renderdiff/renders \
+                  --commit-msg="Auto-update goldens from ${COMMIT_HASH}" \
+                  --push-to-remote \
+                  --golden-repo-token=${GH_TOKEN}
+          fi
+
           if [[ "${GOLDEN_BRANCH}" != "main" ]]; then
-              git config --global user.email "filament.bot@gmail.com"
-              git config --global user.name "Filament Bot"
-              git config --global credential.helper cache
               echo "branch==${GOLDEN_BRANCH}"
               echo "hash==${COMMIT_HASH}"
               python3 test/renderdiff/src/update_golden.py --branch=${GOLDEN_BRANCH} \

.github/workflows/presubmit.yml

@@ -126,18 +126,24 @@ jobs:
       - uses: actions/checkout@v4.1.6
         with:
           fetch-depth: 0
-      - uses: ./.github/actions/mac-prereq
-      - uses: ./.github/actions/get-gltf-assets
-      - uses: ./.github/actions/get-mesa
-      - uses: ./.github/actions/get-vulkan-sdk
       - id: get_commit_msg
         uses: ./.github/actions/get-commit-msg
-      - name: Prerequisites
+      - name: Check if accepting new goldens
+        id: check_accept
+        env:
+          COMMIT_MESSAGE: ${{ steps.get_commit_msg.outputs.msg }}
         run: |
-          # Must have at least clang-16 for a webgpu/dawn build.
-          sudo xcode-select -s /Applications/Xcode_16.2.app/Contents/Developer
+          if echo "${COMMIT_MESSAGE}" | python3 test/renderdiff/src/commit_msg.py --mode=accept_new_goldens; then
+            echo "accept=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "accept=false" >> "$GITHUB_OUTPUT"
+          fi
         shell: bash
+      - name: Renderdiff Generate
+        if: steps.check_accept.outputs.accept != 'true'
+        uses: ./.github/actions/renderdiff-generate
       - name: Render and compare
+        if: steps.check_accept.outputs.accept != 'true'
         id: render_compare
         env:
           COMMIT_MESSAGE: ${{ steps.get_commit_msg.outputs.msg }}
@@ -146,9 +152,6 @@ jobs:
           source ${TEST_DIR}/src/preamble.sh
           set -eux
           GOLDEN_BRANCH=$(echo "${COMMIT_MESSAGE}" | python3 ${TEST_DIR}/src/commit_msg.py)
-          bash ${TEST_DIR}/generate.sh
-          # Build diffimg tool
-          ./build.sh release diffimg
 
           python3 ${TEST_DIR}/src/golden_manager.py \
                   --branch=${GOLDEN_BRANCH} \
@@ -172,10 +175,12 @@ jobs:
           fi
         shell: bash
       - uses: actions/upload-artifact@v4
+        if: steps.check_accept.outputs.accept != 'true'
         with:
           name: presubmit-renderdiff-result
           path: ./out/renderdiff
       - name: Compare result
+        if: steps.check_accept.outputs.accept != 'true'
         run: |
           ERROR_STR="${{ steps.render_compare.outputs.err }}"
           if [ -n "${ERROR_STR}" ]; then

.github/workflows/release.yml

@@ -188,6 +188,54 @@ jobs:
             const globber = await glob.create(['out/*.aar', 'out/*.apk', 'out/*.tgz'].join('\n'));
             await upload({ github, context }, await globber.glob(), TAG);
 
+  sonatype-publish:
+    name: sonatype-publish
+    runs-on: 'ubuntu-24.04-16core'
+    # Depends on the the Android build for the Android binaries.
+    # Depends on the Mac, Linux, and Windows builds for host tools.
+    needs: [build-mac, build-linux, build-windows, build-android]
+    if: github.event_name == 'release' || github.event.inputs.platform == 'android'
+
+    steps:
+      - name: Decide Git ref
+        id: git_ref
+        run: |
+          REF=${RELEASE_TAG:-${GITHUB_REF}}
+          TAG=${REF##*/}
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@v4.1.6
+        with:
+          ref: ${{ steps.git_ref.outputs.ref }}
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - uses: ./.github/actions/linux-prereq
+      - name: Download Android Release
+        run: |
+          gh release download ${TAG} \
+            --repo ${{ github.repository }} \
+            --pattern 'filament-*-android-native.tgz'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.git_ref.outputs.tag }}
+      - name: Unzip Android Release
+        run: |
+          mkdir -p out/android-release
+          tar -xzvf filament-${TAG}-android-native.tgz -C out/android-release/
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
+      - name: Publish To Sonatype
+        run: |
+          cd android
+          ./gradlew publishToSonatype closeSonatypeStagingRepository
+        env:
+          ORG_GRADLE_PROJECT_sonatypeUsername: ${{ secrets.SONATYPE_USERNAME }}
+          ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.SONATYPE_PASSWORD }}
+          ORG_GRADLE_PROJECT_signingKey: ${{ secrets.MAVEN_SIGNING_KEY }}
+          ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.MAVEN_SIGNING_PASSWORD }}
+
   build-ios:
     name: build-ios
     runs-on: macos-14-xlarge

NEW_RELEASE_NOTES.md

@@ -6,5 +6,3 @@
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
-- engine: fix crash when using variance shadow maps

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.69.3'
+    implementation 'com.google.android.filament:filament-android:1.69.5'
 }
 ```
 
@@ -50,7 +50,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.69.3'
+pod 'Filament', '~> 1.69.5'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,6 +7,15 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.70.0
+
+- engine: fix crash when using variance shadow maps
+- materials: better shadow normal-bias calculations [⚠️ **New Material Version**]
+
+## v1.69.5
+
+- engine: fix crash when using variance shadow maps
+
 ## v1.69.4
 
 

android/build.gradle

@@ -40,15 +40,21 @@
 //   - Build and upload artifacts with ./gradlew publish
 //   - Close and release staging repo on Nexus with ./gradlew closeAndReleaseStagingRepository
 //
-// The following is needed in ~/gradle/gradle.properties:
+// The following properties need to be set (either in ~/gradle/gradle.properties, on the command
+// line, or as environment variables, e.g.: ORG_GRADLE_PROJECT_property=value):
 //
 //     sonatypeUsername=nexus_user
 //     sonatypePassword=nexus_password
 //
+//     To sign with a key ring file:
 //     signing.keyId=pgp_key_id
 //     signing.password=pgp_key_password
 //     signing.secretKeyRingFile=/Users/user/.gnupg/maven_signing.key
 //
+//     To sign with in-memory keys (useful for CI):,
+//     signingKey=ASCII armored key (begins with -----BEGIN PGP PRIVATE KEY BLOCK-----)
+//     signingPassword=key password
+//
 
 buildscript {
     def path = providers

android/filament-android/src/main/java/com/google/android/filament/View.java

@@ -2121,7 +2121,7 @@ public class View {
          */
         public boolean highPrecision = false;
         /**
-         * VSM minimum variance scale, must be positive.
+         * @deprecated has no effect.
          */
         public float minVarianceScale = 0.5f;
         /**

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.69.3
+VERSION_NAME=1.69.5
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 

android/gradle/gradle-mvn-push.gradle

@@ -94,6 +94,13 @@ afterEvaluate { project ->
     }
 
     signing {
+        def signingKey = findProperty("signingKey")
+        def signingPassword = findProperty("signingPassword")
+        if (signingKey && signingPassword) {
+            println("Signing with in-memory keys")
+            useInMemoryPgpKeys(signingKey, signingPassword)
+        }
+
         publishing.publications.all { publication ->
             sign publication
         }

android/samples/sample-render-validation/build.gradle

@@ -26,7 +26,8 @@ tasks.register('copyDamagedHelmetGltf', Copy) {
 preBuild.dependsOn copyDamagedHelmetGltf
 
 clean.doFirst {
-    delete "src/main/assets"
+    delete "src/main/assets/envs"
+    delete "src/main/assets/models"
 }
 
 android {
@@ -48,6 +49,7 @@ android {
 dependencies {
     implementation deps.kotlin
     implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    implementation 'com.google.android.material:material:1.10.0'
     implementation deps.coroutines.core
     implementation project(':filament-android')
     implementation project(':gltfio-android')

android/samples/sample-render-validation/src/main/AndroidManifest.xml

@@ -12,10 +12,11 @@
         android:supportsRtl="true"
         android:largeHeap="true"
         android:requestLegacyExternalStorage="true"
-        android:theme="@android:style/Theme.NoTitleBar">
+        android:theme="@style/Theme.Material3.DayNight.NoActionBar">
         <activity
             android:name=".MainActivity"
             android:exported="true"
+            android:launchMode="singleTop"
             android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"
             android:screenOrientation="fullSensor">
             <intent-filter>

android/samples/sample-render-validation/src/main/assets/default_test.json

@@ -0,0 +1,899 @@
+{
+  "name": "Default Test",
+  "backends": [
+    "opengl"
+  ],
+  "models": {
+    "DamagedHelmet": "helmet.glb"
+  },
+  "presets": [
+    {
+      "name": "base",
+      "models": [
+        "DamagedHelmet"
+      ],
+      "rendering": {
+        "camera": {
+          "enabled": true,
+          "horizontalFov": 45.0,
+          "center": [
+            0,
+            0,
+            0
+          ],
+          "lookAt": [
+            0,
+            0,
+            -1
+          ]
+        },
+        "view": {
+          "postProcessingEnabled": true,
+          "dithering": "NONE"
+        },
+        "tolerance": {
+          "maxAbsDiff": 0.1,
+          "maxFailingPixelsFraction": 0.0
+        }
+      }
+    },
+    {
+      "name": "tilted",
+      "rendering": {
+        "camera": {
+          "enabled": true,
+          "horizontalFov": 45.0,
+          "center": [
+            -4,
+            -2,
+            -3
+          ],
+          "lookAt": [
+            0,
+            0,
+            -4
+          ]
+        }
+      }
+    }
+  ],
+  "tests": [
+    {
+      "name": "basic",
+      "apply_presets": [
+        "base"
+      ]
+    },
+    {
+      "name": "rotated",
+      "apply_presets": [
+        "base",
+        "tilted"
+      ]
+    },
+    {
+      "name": "ssao",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true
+      }
+    },
+    {
+      "name": "msaa",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.msaa.enabled": true
+      }
+    },
+    {
+      "name": "bloom",
+      "apply_presets": [
+        "base",
+        "tilted"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true
+      }
+    },
+    {
+      "name": "aa_none",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.antiAliasing": "NONE"
+      }
+    },
+    {
+      "name": "aa_fxaa",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.antiAliasing": "FXAA"
+      }
+    },
+    {
+      "name": "dithering_none",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dithering": "NONE"
+      }
+    },
+    {
+      "name": "msaa_8",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.msaa.enabled": true,
+        "view.msaa.sampleCount": 8
+      }
+    },
+    {
+      "name": "taa_custom",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.taa.enabled": true,
+        "view.taa.feedback": 0.2,
+        "view.taa.jitterPattern": "HALTON_23_X16"
+      }
+    },
+    {
+      "name": "ssao_gtao",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.aoType": "GTAO"
+      }
+    },
+    {
+      "name": "ssao_sao",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.aoType": "SAO"
+      }
+    },
+    {
+      "name": "ssao_radius_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.radius": 1.0
+      }
+    },
+    {
+      "name": "ssao_radius_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.radius": 0.1
+      }
+    },
+    {
+      "name": "ssao_power_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.power": 2.0
+      }
+    },
+    {
+      "name": "ssao_power_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.power": 0.5
+      }
+    },
+    {
+      "name": "ssao_bias_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.bias": 0.05
+      }
+    },
+    {
+      "name": "ssao_resolution_half",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.resolution": 0.5
+      }
+    },
+    {
+      "name": "ssao_resolution_full",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.resolution": 1.0
+      }
+    },
+    {
+      "name": "ssao_intensity_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.intensity": 2.0
+      }
+    },
+    {
+      "name": "ssao_bent_normals",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.bentNormals": true
+      }
+    },
+    {
+      "name": "ssao_quality_ultra",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.quality": "ULTRA"
+      }
+    },
+    {
+      "name": "ssao_quality_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.quality": "LOW"
+      }
+    },
+    {
+      "name": "ssao_lowPassFilter_ultra",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.lowPassFilter": "ULTRA"
+      }
+    },
+    {
+      "name": "ssao_upsampling_ultra",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.ssao.enabled": true,
+        "view.ssao.upsampling": "ULTRA"
+      }
+    },
+    {
+      "name": "ssr_basic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true
+      }
+    },
+    {
+      "name": "ssr_thickness_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.thickness": 0.5
+      }
+    },
+    {
+      "name": "ssr_bias_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.bias": 0.1
+      }
+    },
+    {
+      "name": "ssr_maxDistance_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.maxDistance": 5.0
+      }
+    },
+    {
+      "name": "ssr_stride_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.stride": 4.0
+      }
+    },
+    {
+      "name": "ssr_stride_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.stride": 1.0
+      }
+    },
+    {
+      "name": "ssr_thickness_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.thickness": 0.01
+      }
+    },
+    {
+      "name": "ssr_maxDistance_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.maxDistance": 1.0
+      }
+    },
+    {
+      "name": "ssr_bias_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.bias": 0.001
+      }
+    },
+    {
+      "name": "ssr_quality_combo",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.screenSpaceReflections.enabled": true,
+        "view.screenSpaceReflections.thickness": 0.2,
+        "view.screenSpaceReflections.stride": 2.0
+      }
+    },
+    {
+      "name": "bloom_levels_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.levels": 8
+      }
+    },
+    {
+      "name": "bloom_levels_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.levels": 4
+      }
+    },
+    {
+      "name": "bloom_resolution_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.resolution": 1024
+      }
+    },
+    {
+      "name": "bloom_strength_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.strength": 0.5
+      }
+    },
+    {
+      "name": "bloom_strength_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.strength": 0.01
+      }
+    },
+    {
+      "name": "bloom_blendMode_interpolate",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.blendMode": "INTERPOLATE"
+      }
+    },
+    {
+      "name": "bloom_no_threshold",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.threshold": false
+      }
+    },
+    {
+      "name": "bloom_quality_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.quality": "HIGH"
+      }
+    },
+    {
+      "name": "bloom_lensflare",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true
+      }
+    },
+    {
+      "name": "bloom_lensflare_no_starburst",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.starburst": false
+      }
+    },
+    {
+      "name": "bloom_lensflare_chromatic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.chromaticAberration": 0.05
+      }
+    },
+    {
+      "name": "bloom_lensflare_ghosts",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.ghostCount": 8
+      }
+    },
+    {
+      "name": "bloom_lensflare_ghostSpacing",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.ghostSpacing": 0.8
+      }
+    },
+    {
+      "name": "bloom_halo_thick",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.haloThickness": 0.2
+      }
+    },
+    {
+      "name": "bloom_halo_radius",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.bloom.enabled": true,
+        "view.bloom.lensFlare": true,
+        "view.bloom.haloRadius": 0.5
+      }
+    },
+    {
+      "name": "dof_basic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true
+      }
+    },
+    {
+      "name": "dof_cocScale_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.cocScale": 2.0
+      }
+    },
+    {
+      "name": "dof_cocScale_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.cocScale": 0.5
+      }
+    },
+    {
+      "name": "dof_cocAspectRatio",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.cocAspectRatio": 2.0
+      }
+    },
+    {
+      "name": "dof_maxApertureDiameter",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.maxApertureDiameter": 0.05
+      }
+    },
+    {
+      "name": "dof_filter_none",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.filter": "NONE"
+      }
+    },
+    {
+      "name": "dof_nativeResolution",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.nativeResolution": true
+      }
+    },
+    {
+      "name": "dof_rings_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.foregroundRingCount": 5,
+        "view.dof.backgroundRingCount": 5
+      }
+    },
+    {
+      "name": "dof_rings_low",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.foregroundRingCount": 3,
+        "view.dof.backgroundRingCount": 3
+      }
+    },
+    {
+      "name": "dof_max_coc",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.dof.enabled": true,
+        "view.dof.maxForegroundCOC": 16,
+        "view.dof.maxBackgroundCOC": 16
+      }
+    },
+    {
+      "name": "fog_basic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true
+      }
+    },
+    {
+      "name": "fog_distance",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.distance": 10.0
+      }
+    },
+    {
+      "name": "fog_cutOffDistance",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.cutOffDistance": 100.0
+      }
+    },
+    {
+      "name": "fog_maximumOpacity",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.maximumOpacity": 0.5
+      }
+    },
+    {
+      "name": "fog_height",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.height": 5.0
+      }
+    },
+    {
+      "name": "fog_heightFalloff",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.heightFalloff": 0.5
+      }
+    },
+    {
+      "name": "fog_density_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.density": 0.5
+      }
+    },
+    {
+      "name": "fog_inScatteringStart",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.inScatteringStart": 5.0
+      }
+    },
+    {
+      "name": "fog_inScatteringSize",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.inScatteringSize": 10.0
+      }
+    },
+    {
+      "name": "fog_fogColorFromIbl",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.fog.enabled": true,
+        "view.fog.fogColorFromIbl": true
+      }
+    },
+    {
+      "name": "vignette_basic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.vignette.enabled": true
+      }
+    },
+    {
+      "name": "vignette_midPoint",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.vignette.enabled": true,
+        "view.vignette.midPoint": 0.8
+      }
+    },
+    {
+      "name": "vignette_roundness_circle",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.vignette.enabled": true,
+        "view.vignette.roundness": 1.0
+      }
+    },
+    {
+      "name": "vignette_roundness_rect",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.vignette.enabled": true,
+        "view.vignette.roundness": 0.0
+      }
+    },
+    {
+      "name": "vignette_feather_sharp",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.vignette.enabled": true,
+        "view.vignette.feather": 0.1
+      }
+    },
+    {
+      "name": "cg_filmic",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.toneMapping": "FILMIC"
+      }
+    },
+    {
+      "name": "cg_aces",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.toneMapping": "ACES"
+      }
+    },
+    {
+      "name": "cg_agx",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.toneMapping": "AGX"
+      }
+    },
+    {
+      "name": "cg_pbr_neutral",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.toneMapping": "PBR_NEUTRAL"
+      }
+    },
+    {
+      "name": "cg_contrast_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.contrast": 1.5
+      }
+    },
+    {
+      "name": "cg_saturation_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.saturation": 1.5
+      }
+    },
+    {
+      "name": "cg_exposure_high",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.colorGrading.exposure": 1.0
+      }
+    },
+    {
+      "name": "shadow_vsm",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.shadowType": "VSM"
+      }
+    },
+    {
+      "name": "shadow_vsm_anisotropy",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.shadowType": "VSM",
+        "view.vsmShadowOptions.anisotropy": 2
+      }
+    },
+    {
+      "name": "shadow_vsm_highPrecision",
+      "apply_presets": [
+        "base"
+      ],
+      "rendering": {
+        "view.shadowType": "VSM",
+        "view.vsmShadowOptions.highPrecision": true
+      }
+    }
+  ]
+}

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/MainActivity.kt

@@ -17,36 +17,35 @@
 package com.google.android.filament.validation
 
 import android.app.Activity
+import android.app.AlertDialog
+import android.content.Intent
 import android.graphics.Bitmap
+import android.graphics.Color
 import android.os.Bundle
+import android.text.Html
 import android.util.Log
 import android.view.Choreographer
 import android.view.SurfaceView
 import android.view.View
 import android.view.WindowManager
+import android.widget.ArrayAdapter
+import android.widget.Button
 import android.widget.ImageView
 import android.widget.LinearLayout
-import android.widget.ScrollView
+import android.widget.Spinner
 import android.widget.TextView
+import com.google.android.filament.utils.KTX1Loader
 import com.google.android.filament.utils.ModelViewer
 import com.google.android.filament.utils.Utils
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
-import com.google.android.filament.utils.KTX1Loader
-import com.google.android.filament.IndirectLight
-import com.google.android.filament.Skybox
-import android.graphics.Color
 import java.io.File
-import java.io.FileOutputStream
-import java.net.HttpURLConnection
-import java.net.URL
 import java.nio.ByteBuffer
-import android.widget.ArrayAdapter
-import android.widget.Button
-import android.widget.Spinner
-import android.widget.AdapterView
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
 
 class MainActivity : Activity(), ValidationRunner.Callback {
 
@@ -62,13 +61,17 @@ class MainActivity : Activity(), ValidationRunner.Callback {
     private lateinit var choreographer: Choreographer
     private lateinit var modelViewer: ModelViewer
     private lateinit var statusTextView: TextView
+    private lateinit var testResultsHeader: TextView
     private lateinit var resultsContainer: LinearLayout
     private lateinit var inputManager: ValidationInputManager
     private var currentInput: ValidationInputManager.ValidationInput? = null
-    private lateinit var modeSpinner: Spinner
-    private lateinit var runButton: Button
-    private var resultManager: ValidationResultManager? = null
 
+    // UI Elements
+    private lateinit var runButton: Button
+    private lateinit var loadButton: Button
+    private lateinit var optionsButton: Button
+
+    private var resultManager: ValidationResultManager? = null
     private var validationRunner: ValidationRunner? = null
 
     // Frame callback
@@ -89,25 +92,53 @@ class MainActivity : Activity(), ValidationRunner.Callback {
         surfaceView.holder.setFixedSize(512, 512)
 
         statusTextView = findViewById(R.id.status_text)
-        modeSpinner = findViewById(R.id.mode_spinner)
-        runButton = findViewById(R.id.run_button)
+        testResultsHeader = findViewById(R.id.test_results_header)
         resultsContainer = findViewById(R.id.results_container)
 
-        // Setup Spinner
-        val modes = arrayOf("Run Validation", "Generate Goldens")
-        val adapter = ArrayAdapter(this, android.R.layout.simple_spinner_item, modes)
-        adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item)
-        modeSpinner.adapter = adapter
+        runButton = findViewById(R.id.run_button)
+        loadButton = findViewById(R.id.load_button)
+        optionsButton = findViewById(R.id.options_button)
 
         // Setup Run Button
         runButton.setOnClickListener {
             currentInput?.let { input ->
-                val generateGoldens = modeSpinner.selectedItemPosition == 1
-                val newInput = input.copy(generateGoldens = generateGoldens)
-                startValidation(newInput)
+                // Always use the generateGoldens flag from the intent/input
+                startValidation(input)
             }
         }
 
+        // Setup Load Button
+        loadButton.setOnClickListener {
+            showLoadDialog()
+        }
+
+        // Setup Options Menu Button
+        optionsButton.setOnClickListener { view ->
+            val popup = android.widget.PopupMenu(this, view)
+            popup.menu.add(0, 1, 0, "Generate Golden")
+            popup.menu.add(0, 2, 0, "Export Test")
+            popup.menu.add(0, 3, 0, "Export Result")
+            popup.menu.add(0, 4, 0, "Test ADB Info")
+            popup.menu.add(0, 5, 0, "Result ADB Info")
+
+            popup.setOnMenuItemClickListener { item ->
+                when (item.itemId) {
+                    1 -> {
+                        currentInput?.let { input ->
+                            val goldenInput = input.copy(generateGoldens = true)
+                            startValidation(goldenInput)
+                        }
+                    }
+                    2 -> exportTestBundleAction()
+                    3 -> exportTestResultsAction()
+                    4 -> showTestAdbInfo()
+                    5 -> showResultAdbInfo()
+                }
+                true
+            }
+            popup.show()
+        }
+
         window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
 
         choreographer = Choreographer.getInstance()
@@ -120,6 +151,134 @@ class MainActivity : Activity(), ValidationRunner.Callback {
         handleIntent()
     }
 
+    private fun showLoadDialog() {
+        val exportDir = getExternalFilesDir(null) ?: filesDir
+        // Filter out result zips (starting with "results_") to only show test bundles
+        val zips = exportDir.listFiles { _, name ->
+            name.endsWith(".zip") && !name.startsWith("results_")
+        }?.sortedByDescending { it.lastModified() } ?: emptyList()
+
+        if (zips.isEmpty()) {
+            AlertDialog.Builder(this)
+                .setTitle("Load Test")
+                .setMessage("No test bundles found.")
+                .setPositiveButton("OK", null)
+                .show()
+            return
+        }
+
+        val builder = AlertDialog.Builder(this)
+        builder.setTitle("Select Test Bundle")
+
+        val items = zips.map { it.name }.toTypedArray()
+
+        builder.setItems(items) { dialog, which ->
+            val selectedFile = zips[which]
+            loadZipBundle(selectedFile)
+            dialog.dismiss()
+        }
+
+        builder.setNegativeButton("Cancel", null)
+        builder.show()
+    }
+
+    private fun showTestAdbInfo() {
+        val exportDir = getExternalFilesDir(null) ?: filesDir
+        val path = exportDir.absolutePath
+        val isInternal = path.startsWith(filesDir.absolutePath)
+        val message = StringBuilder()
+
+        message.append("Storage Path: $path<br><br>")
+
+        message.append("<b>--- PULL FROM DEVICE ---</b><br>")
+        if (isInternal) {
+            message.append("<tt>adb shell \"run-as $packageName cat files/&lt;filename&gt;\" &gt; &lt;filename&gt;</tt><br><br>")
+        } else {
+            message.append("<tt>adb pull $path/&lt;filename&gt; .</tt><br><br>")
+        }
+
+        message.append("<b>--- PUSH TO DEVICE ---</b><br>")
+        if (isInternal) {
+            message.append("1. <tt>adb push &lt;filename&gt; /sdcard/Download/</tt><br>")
+            message.append("2. <tt>adb shell \"run-as $packageName cp /sdcard/Download/&lt;filename&gt; files/\"</tt><br>")
+        } else {
+            message.append("<tt>adb push &lt;filename&gt; $path/</tt><br>")
+        }
+        message.append("<br>Note: Use underscores instead of spaces in &lt;filename&gt;.")
+
+        AlertDialog.Builder(this)
+            .setTitle("Test Bundle ADB Info")
+            .setMessage(Html.fromHtml(message.toString(), Html.FROM_HTML_MODE_LEGACY))
+            .setPositiveButton("OK", null)
+            .show()
+    }
+
+    private fun showResultAdbInfo() {
+        val exportDir = getExternalFilesDir(null) ?: filesDir
+        val path = exportDir.absolutePath
+        val isInternal = path.startsWith(filesDir.absolutePath)
+        val message = StringBuilder()
+
+        message.append("<b>--- PULL RESULTS ---</b><br>")
+        if (isInternal) {
+            message.append("<tt>adb shell \"run-as $packageName cat files/&lt;filename&gt;\" &gt; &lt;filename&gt;</tt><br><br>")
+        } else {
+            message.append("<tt>adb pull $path/&lt;filename&gt; .</tt><br><br>")
+        }
+
+        message.append("<b>--- AVAILABLE RESULTS ---</b><br>")
+        val zips = exportDir.listFiles { _, name ->
+            name.endsWith(".zip") && name.startsWith("results_")
+        }?.sortedByDescending { it.lastModified() } ?: emptyList()
+
+        if (zips.isEmpty()) {
+            message.append("No result zips found.<br>")
+        } else {
+            zips.forEach { file ->
+                message.append("${file.name}<br>")
+            }
+        }
+
+        AlertDialog.Builder(this)
+            .setTitle("Result ADB Info")
+            .setMessage(Html.fromHtml(message.toString(), Html.FROM_HTML_MODE_LEGACY))
+            .setPositiveButton("OK", null)
+            .show()
+    }
+
+    private fun loadZipBundle(file: File) {
+         statusTextView.text = "Loading ${file.name}..."
+         CoroutineScope(Dispatchers.Main).launch {
+             try {
+                 val config = inputManager.loadFromZip(file)
+                 val baseDir = getExternalFilesDir(null) ?: filesDir
+                 val outputDir = File(baseDir, "validation_results").apply { mkdirs() }
+
+                 // Clear existing results UI and state
+                 resultsContainer.removeAllViews()
+                 resultManager = null
+
+                 val newInput = ValidationInputManager.ValidationInput(
+                     config = config,
+                     outputDir = outputDir,
+                     generateGoldens = false,
+                     autoRun = false,
+                     autoExport = false,
+                     autoExportResults = false,
+                     sourceZip = file
+                 )
+
+                 currentInput = newInput
+                 statusTextView.text = "Loaded ${config.name}"
+                 Log.i(TAG, "Setting header to: Test Results: ${config.name}")
+                 testResultsHeader.text = "${config.name}"
+             } catch (e: Exception) {
+                 Log.e(TAG, "Failed to load zip", e)
+                 statusTextView.text = "Error: ${e.message}"
+             }
+         }
+    }
+
     private fun createIndirectLight() {
         try {
             val engine = modelViewer.engine
@@ -156,12 +315,18 @@ class MainActivity : Activity(), ValidationRunner.Callback {
         CoroutineScope(Dispatchers.Main).launch {
             try {
                 val input = inputManager.resolveConfig(intent)
+
+                // Update header
+                Log.i(TAG, "handleIntent: Setting header to: Test Results: ${input.config.name}")
+                testResultsHeader.text = "${input.config.name}"
                 currentInput = input
 
-                // Sync spinner with intent
-                modeSpinner.setSelection(if (input.generateGoldens) 1 else 0)
-
-                startValidation(input)
+                if (input.autoRun) {
+                    startValidation(input)
+                } else {
+                    // Just show status
+                    statusTextView.text = "Ready: ${input.config.name}"
+                }
             } catch (e: Exception) {
                 Log.e(TAG, "Failed to resolve config", e)
                 statusTextView.text = "Error: ${e.message}"
@@ -175,6 +340,8 @@ class MainActivity : Activity(), ValidationRunner.Callback {
             Log.i(TAG, "Starting validation with config: ${input.config.name}")
             Log.i(TAG, "Output dir: ${input.outputDir.absolutePath}")
 
+            testResultsHeader.text = "${input.config.name}"
+
             resultManager = ValidationResultManager(input.outputDir)
 
             validationRunner = ValidationRunner(this, modelViewer, input.config, resultManager!!)
@@ -182,9 +349,6 @@ class MainActivity : Activity(), ValidationRunner.Callback {
             validationRunner?.generateGoldens = input.generateGoldens
             validationRunner?.start()
 
-            // Sync spinner in case it was called programmatically or changed implicitly
-            modeSpinner.setSelection(if (input.generateGoldens) 1 else 0)
-
         } catch (e: Exception) {
             Log.e(TAG, "Failed to start validation", e)
             statusTextView.text = "Error: ${e.message}"
@@ -196,6 +360,12 @@ class MainActivity : Activity(), ValidationRunner.Callback {
         choreographer.postFrameCallback(frameScheduler)
     }
 
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        handleIntent()
+    }
+
     override fun onPause() {
         super.onPause()
         choreographer.removeFrameCallback(frameScheduler)
@@ -221,13 +391,30 @@ class MainActivity : Activity(), ValidationRunner.Callback {
             resultContainer.orientation = LinearLayout.VERTICAL
             resultContainer.setPadding(0, 10, 0, 20)
 
-            // Header
-            val resultView = TextView(this)
-            resultView.text = "${result.testName}: ${if(result.passed) "PASS" else "FAIL"} (Diff: ${result.diffMetric})"
-            resultView.setTextColor(if(result.passed) Color.GREEN else Color.RED)
-            resultView.textSize = 16f
-            resultView.setTypeface(null, android.graphics.Typeface.BOLD)
-            resultContainer.addView(resultView)
+            // Header Layout
+            val headerRow = LinearLayout(this)
+            headerRow.orientation = LinearLayout.HORIZONTAL
+            headerRow.gravity = android.view.Gravity.CENTER_VERTICAL
+
+            // Status Icon + Name
+            val statusView = TextView(this)
+            val icon = if (result.passed) "✔" else "✖"
+
+            statusView.text = "$icon ${result.testName}"
+            statusView.setTextColor(
+                if (result.passed) Color.parseColor("#4CAF50") else Color.parseColor("#F44336")
+            )
+            statusView.textSize = 12f
+            statusView.setTypeface(null, android.graphics.Typeface.BOLD)
+            headerRow.addView(statusView)
+
+            // Diff Metric (only show if it's relevant/there's a diff or we just always show it like before)
+            val diffView = TextView(this)
+            diffView.text = "  (Diff: ${result.diffMetric})"
+            diffView.textSize = 12f
+            diffView.setTextColor(Color.GRAY)
+            headerRow.addView(diffView)
+            resultContainer.addView(headerRow)
 
             // Images Row
             val imagesRow = LinearLayout(this)
@@ -241,7 +428,7 @@ class MainActivity : Activity(), ValidationRunner.Callback {
 
                     val labelView = TextView(this)
                     labelView.text = label
-                    labelView.textSize = 12f
+                    labelView.textSize = 9f
                     container.addView(labelView)
 
                     val iv = ImageView(this)
@@ -274,7 +461,46 @@ class MainActivity : Activity(), ValidationRunner.Callback {
     override fun onAllTestsFinished() {
         runOnUiThread {
             statusTextView.text = "All tests finished!"
-            Log.i(TAG, "All tests finished")
+            Log.i(TAG, "All tests finished " + if (currentInput?.autoExport == true) "Exporting bundle" else "x")
+
+            if (currentInput?.autoExport == true) {
+                exportTestBundleAction()
+            }
+            if (currentInput?.autoExportResults == true) {
+                exportTestResultsAction()
+            }
+        }
+    }
+
+    private fun exportTestBundleAction() {
+        currentInput?.let { input ->
+            val timestamp = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.US).format(Date())
+            val rm = resultManager ?: ValidationResultManager(input.outputDir)
+            val zip = rm.exportTestBundle(input.config, timestamp)
+            if (zip != null) {
+                val msg = "Exported Bundle: ${zip.name}"
+                statusTextView.text = msg
+                Log.i(TAG, "Exported test bundle to ${zip.absolutePath}")
+            } else {
+                statusTextView.text = "Export Bundle failed"
+                Log.e(TAG, "Export Bundle failed")
+            }
+        }
+    }
+
+    private fun exportTestResultsAction() {
+        currentInput?.let { input ->
+            val timestamp = SimpleDateFormat("yyyyMMdd_HHmmss", Locale.US).format(Date())
+            val rm = resultManager ?: ValidationResultManager(input.outputDir)
+            val zip = rm.exportTestResults(input.sourceZip, timestamp)
+            if (zip != null) {
+                val msg = "Exported Results: ${zip.name}"
+                statusTextView.text = msg
+                Log.i(TAG, "Exported results to ${zip.absolutePath}")
+            } else {
+                statusTextView.text = "Export Results failed"
+                Log.e(TAG, "Export Results failed")
+            }
         }
     }
 
@@ -301,50 +527,3 @@ class MainActivity : Activity(), ValidationRunner.Callback {
         }
     }
 }
-
-/*
- * Scripts for reference:
- *
- * generate_goldens.sh:
- * --------------------
- * #!/bin/bash
- * set -e
- *
- * # Config path (on device)
- * CONFIG_PATH=$1
- * if [ -z "$CONFIG_PATH" ]; then
- *     echo "Usage: $0 <device_config_path>"
- *     echo "Example: $0 /sdcard/Android/data/com.google.android.filament.validation/files/default_test.json"
- *     exit 1
- * fi
- *
- * echo "Starting Golden Generation for $CONFIG_PATH..."
- * adb shell am force-stop com.google.android.filament.validation
- * adb shell am start -n com.google.android.filament.validation/.MainActivity \
- *     -e test_config "$CONFIG_PATH" \
- *     --ez generate_goldens true
- *
- * echo "Check device or logcat for progress."
- * echo "adb logcat -s FilamentValidation:I ValidationRunner:I"
- * echo "To pull results: ./samples/sample-render-validation/pull_goldens.sh"
- *
- * pull_goldens.sh:
- * ----------------
- * #!/bin/bash
- * set -e
- *
- * # Default destination is local golden directory relative to script
- * SCRIPT_DIR=$(cd $(dirname $0); pwd)
- * DEST_DIR=${1:-"$SCRIPT_DIR/golden"}
- *
- * echo "Pulling goldens to $DEST_DIR..."
- * mkdir -p "$DEST_DIR"
- *
- * # Path on device
- * DEVICE_GOLDEN_DIR="/storage/emulated/0/Android/data/com.google.android.filament.validation/files/golden/."
- *
- * adb pull "$DEVICE_GOLDEN_DIR" "$DEST_DIR"
- *
- * echo "Done."
- * ls -l "$DEST_DIR"
- */

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationInputManager.kt

@@ -26,6 +26,7 @@ import java.io.File
 import java.io.FileOutputStream
 import java.net.HttpURLConnection
 import java.net.URL
+import java.util.zip.ZipFile
 
 /**
  * Handles the retrieval and preparation of test configuration and assets.
@@ -42,7 +43,11 @@ class ValidationInputManager(private val context: Context) {
     data class ValidationInput(
         val config: RenderTestConfig,
         val outputDir: File,
-        val generateGoldens: Boolean
+        val generateGoldens: Boolean,
+        val autoRun: Boolean = false,
+        val autoExport: Boolean = false,
+        val autoExportResults: Boolean = false,
+        val sourceZip: File? = null
     )
 
     /**
@@ -53,22 +58,111 @@ class ValidationInputManager(private val context: Context) {
         val testConfigPath = intent.getStringExtra("test_config")
         val urlConfig = intent.getStringExtra("url_config")
         val urlModelsBase = intent.getStringExtra("url_models_base")
+        val zipPath = intent.getStringExtra("zip_path")
         val generateGoldens = intent.getBooleanExtra("generate_goldens", false)
+        val autoRun = intent.getBooleanExtra("auto_run", false)
+        val autoExport = intent.getBooleanExtra("auto_export", false)
+        val autoExportResults = intent.getBooleanExtra("auto_export_results", false)
         val outputPath = intent.getStringExtra("output_path")
 
-        val outputDir = if (outputPath != null) {
-            File(outputPath).apply { mkdirs() }
+        Log.i(TAG, "Resolving config with outputPath: $outputPath")
+
+        val baseDir = context.getExternalFilesDir(null) ?: context.filesDir
+        Log.i(TAG, "Base directory for resolution: ${baseDir.absolutePath}")
+        
+        val outputDir = if (!outputPath.isNullOrBlank()) {
+            val file = File(outputPath)
+            val resolved = if (file.isAbsolute) {
+                file
+            } else {
+                File(baseDir, outputPath)
+            }
+            
+            // Critical check: if resolved is root or very short, it's likely wrong
+            if (resolved.absolutePath == "/" || resolved.parent == null) {
+                Log.w(TAG, "Resolved outputDir is root ($resolved), defaulting to app-specific dir")
+                File(baseDir, "validation_results")
+            } else {
+                resolved
+            }
         } else {
-            File(context.getExternalFilesDir(null), "validation_results").apply { mkdirs() }
+            File(baseDir, "validation_results")
+        }
+        
+        if (!outputDir.exists() && !outputDir.mkdirs()) {
+            Log.e(TAG, "Failed to create outputDir: ${outputDir.absolutePath}")
+        }
+        Log.i(TAG, "Final outputDir: ${outputDir.absolutePath}")
+
+        val sourceZipFile = if (zipPath != null) {
+            val file = File(zipPath)
+            if (file.isAbsolute) {
+                file
+            } else {
+                File(baseDir, zipPath)
+            }
+        } else {
+            null
         }
 
         val config = when {
+            sourceZipFile != null && sourceZipFile.exists() -> loadFromZip(sourceZipFile)
             urlConfig != null -> downloadConfig(urlConfig, urlModelsBase)
             testConfigPath != null -> ConfigParser.parseFromPath(testConfigPath)
             else -> extractDefaultAssets()
         }
 
-        return@withContext ValidationInput(config, outputDir, generateGoldens)
+        return@withContext ValidationInput(config, outputDir, generateGoldens, autoRun, autoExport, autoExportResults, sourceZipFile)
+    }
+
+    suspend fun loadFromZip(zipFile: File): RenderTestConfig {
+        Log.i(TAG, "Unzipping validation bundle: ${zipFile.absolutePath}")
+        // Use a unique cache dir based on timestamp or just overwrite a common one
+        // Overwriting is safer to avoid filling up disk, but we must ensure we don't conflict with current run
+        val baseCacheDir = context.externalCacheDir ?: context.cacheDir
+        val cacheDir = File(baseCacheDir, "unzipped_validation")
+        if (cacheDir.exists()) cacheDir.deleteRecursively()
+        cacheDir.mkdirs()
+
+        Log.i(TAG, "Using cacheDir: ${cacheDir.absolutePath}")
+
+        ZipFile(zipFile).use { zip ->
+            val entries = zip.entries()
+            while (entries.hasMoreElements()) {
+                val entry = entries.nextElement()
+                val entryFile = File(cacheDir, entry.name)
+                // specific check to avoid zip slip vulnerability (though low risk here)
+                if (!entryFile.canonicalPath.startsWith(cacheDir.canonicalPath)) {
+                    throw SecurityException("Zip entry is outside of the target dir: ${entry.name}")
+                }
+                
+                if (entry.isDirectory) {
+                    entryFile.mkdirs()
+                } else {
+                    entryFile.parentFile?.mkdirs()
+                    zip.getInputStream(entry).use { input ->
+                         FileOutputStream(entryFile).use { output ->
+                             input.copyTo(output)
+                         }
+                    }
+                }
+            }
+        }
+        
+        // Find config.json
+        // We look for a file ending in .json within the unzipped structure
+        // Exclude results.json if it happened to be there
+        val jsonFiles = cacheDir.walkTopDown()
+            .filter { it.isFile && it.extension == "json" && it.name != "results.json" }
+            .toList()
+            
+        if (jsonFiles.isEmpty()) throw IllegalStateException("No config.json found in zip")
+        
+        // Prefer one named config.json or take the first one
+        val configFile = jsonFiles.find { it.name == "config.json" } ?: jsonFiles.first()
+
+        Log.i(TAG, "Parsed config from ${configFile.absolutePath}")
+        return ConfigParser.parseFromPath(configFile.absolutePath)
     }
 
     private suspend fun extractDefaultAssets(): RenderTestConfig {
@@ -90,9 +184,9 @@ class ValidationInputManager(private val context: Context) {
         // Copy DamagedHelmet.glb
         val modelsDir = File(filesDir, "models")
         modelsDir.mkdirs()
-        val modelOut = File(modelsDir, "DamagedHelmet.glb")
+        val modelOut = File(modelsDir, "helmet.glb")
 
-        assetManager.open("DamagedHelmet.glb").use { input ->
+        assetManager.open("models/helmet.glb").use { input ->
             FileOutputStream(modelOut).use { output ->
                 input.copyTo(output)
             }

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationResultManager.kt

@@ -67,22 +67,201 @@ class ValidationResultManager(private val outputDir: File) {
     fun finalizeResults(): File? {
         // Write results JSON
         writeResultsJson()
+        return null
+    }
+
+    /**
+     * Exports a zip containing:
+     * - results.json
+     * - input test bundle (as nested zip), if provided
+     * - diff images (if any failure)
+     */
+    fun exportTestResults(sourceZip: File?, timestamp: String): File? {
+        // Safe parent dir resolution
+        val parentDir = outputDir.canonicalFile.parentFile ?: outputDir.parentFile
+        if (parentDir == null) return null
+
+        val resultZipName = "results_$timestamp"
+        val zipFile = File(parentDir, "$resultZipName.zip")
+
+        Log.i(TAG, "Exporting results to ${zipFile.absolutePath}")
 
-        // Zip results
-        val zipFile = File(outputDir, "results.zip")
         try {
             ZipOutputStream(FileOutputStream(zipFile)).use { zos ->
-                outputDir.walkTopDown().filter { it.isFile && it.name != "results.zip" }.forEach { file ->
-                    val entryName = file.relativeTo(outputDir).path
-                    zos.putNextEntry(ZipEntry(entryName))
-                    file.inputStream().use { it.copyTo(zos) }
+                // 1. Add results.json
+                val resultsJson = File(outputDir, "results.json")
+                if (resultsJson.exists()) {
+                    zos.putNextEntry(ZipEntry("results.json"))
+                    resultsJson.inputStream().use { it.copyTo(zos) }
+                    zos.closeEntry()
+                }
+
+                // 2. Add source zip if exists
+                if (sourceZip != null && sourceZip.exists()) {
+                    zos.putNextEntry(ZipEntry(sourceZip.name))
+                    sourceZip.inputStream().use { it.copyTo(zos) }
+                    zos.closeEntry()
+                }
+
+                // 3. Add diff images (any file ending in _diff.png in outputDir)
+                outputDir.listFiles { _, name -> name.endsWith("_diff.png") }?.forEach { diffFile ->
+                    zos.putNextEntry(ZipEntry(diffFile.name))
+                    diffFile.inputStream().use { it.copyTo(zos) }
                     zos.closeEntry()
                 }
             }
-            Log.i(TAG, "Zipped results to ${zipFile.absolutePath}")
+            Log.i(TAG, "Exported results to ${zipFile.absolutePath}")
             return zipFile
         } catch (e: Exception) {
-            Log.e(TAG, "Failed to zip results", e)
+            Log.e(TAG, "Failed to export results", e)
+            return null
+        }
+    }
+
+    /**
+     * Exports a zip bundle containing:
+     * - Modified config.json (with updated name and relative paths)
+     * - Models (in models/ subdirectory)
+     * - Golden images (in goldens/ subdirectory)
+     *
+     * Structure:
+     *   test_name_TIMESTAMP/
+     *     config.json
+     *     models/
+     *       model.glb
+     *     goldens/
+     *       test_result.png
+     */
+    fun exportTestBundle(config: RenderTestConfig, timestamp: String): File? {
+        Log.i(TAG, "Starting exportTestBundle for ${config.name} at $timestamp")
+        Log.i(TAG, "OutputDir: ${outputDir.absolutePath}")
+
+        val parentDir = outputDir.canonicalFile.parentFile ?: outputDir.parentFile
+        if (parentDir == null) {
+            Log.e(TAG, "OutputDir parent is null: ${outputDir.absolutePath}")
+            return null
+        }
+        Log.i(TAG, "Using parentDir for export: ${parentDir.absolutePath}")
+
+        val testNameWithTimestamp = "${config.name}_$timestamp"
+        val exportNameNoSpaces = testNameWithTimestamp.replace(" ", "_")
+
+        val exportDir = File(parentDir, "export_temp_$timestamp")
+
+        Log.i(TAG, "Creating export temp dir: ${exportDir.absolutePath}")
+        if (exportDir.exists()) exportDir.deleteRecursively()
+        if (!exportDir.mkdirs()) {
+             Log.e(TAG, "Failed to create export dir: ${exportDir.absolutePath}")
+             return null
+        }
+
+        val rootDir = File(exportDir, exportNameNoSpaces)
+        rootDir.mkdirs()
+
+        val modelsDir = File(rootDir, "models")
+        modelsDir.mkdirs()
+
+        val goldensDir = File(rootDir, "goldens")
+        goldensDir.mkdirs()
+
+        try {
+            // 1. Copy Models and update config map
+            val newModelsMap = mutableMapOf<String, String>()
+            Log.i(TAG, "Copying models...")
+            for ((modelName, modelPath) in config.models) {
+                val sourceFile = File(modelPath)
+                if (sourceFile.exists()) {
+                    val destFile = File(modelsDir, sourceFile.name)
+                    Log.d(TAG, "Copying model $modelName: $modelPath -> ${destFile.name}")
+                    sourceFile.copyTo(destFile, overwrite = true)
+                    // Use relative path for the new config
+                    newModelsMap[modelName] = "models/${sourceFile.name}"
+                } else {
+                    Log.w(TAG, "Model file not found: $modelPath")
+                }
+            }
+
+            // 2. Copy Golden Images
+            // We assume goldens are in outputDir with .png extension
+            Log.i(TAG, "Copying goldens from ${outputDir.absolutePath}...")
+            outputDir.listFiles { _, name -> name.endsWith(".png") }?.forEach { file ->
+                Log.d(TAG, "Copying golden: ${file.name}")
+                file.copyTo(File(goldensDir, file.name), overwrite = true)
+            }
+
+            // 3. Create modified config JSON
+            Log.i(TAG, "Creating config.json...")
+            val newConfigJson = JSONObject()
+            newConfigJson.put("name", testNameWithTimestamp) // Keep spaces in JSON name
+
+            // Reconstruct backends
+            val backendsArray = JSONArray()
+            config.backends.forEach { backendsArray.put(it) }
+            newConfigJson.put("backends", backendsArray)
+
+            // Reconstruct models
+            val modelsJson = JSONObject()
+            for ((k, v) in newModelsMap) {
+                modelsJson.put(k, v)
+            }
+            newConfigJson.put("models", modelsJson)
+
+            // Reconstruct tests
+            val testsArray = JSONArray()
+            for (test in config.tests) {
+                val testJson = JSONObject()
+                testJson.put("name", test.name)
+                if (test.description != null) testJson.put("description", test.description)
+
+                // Models for this test (set of strings)
+                val testModelsArray = JSONArray()
+                test.models.forEach { testModelsArray.put(it) }
+                testJson.put("models", testModelsArray)
+
+                // Rendering settings
+                testJson.put("rendering", test.rendering)
+
+                // Tolerance
+                if (test.tolerance != null) {
+                    testJson.put("tolerance", test.tolerance)
+                }
+
+                // Backends (optional override)
+                 val testBackends = JSONArray()
+                 test.backends.forEach { testBackends.put(it) }
+                 testJson.put("backends", testBackends)
+
+                testsArray.put(testJson)
+            }
+            newConfigJson.put("tests", testsArray)
+
+            // Write config.json
+            File(rootDir, "config.json").writeText(newConfigJson.toString(4))
+
+            // 4. Zip it
+            val zipFile = File(parentDir, "$exportNameNoSpaces.zip")
+            Log.i(TAG, "Zipping to ${zipFile.absolutePath}...")
+
+            ZipOutputStream(FileOutputStream(zipFile)).use { zos ->
+                rootDir.walkTopDown().forEach { file ->
+                    if (file.isFile) {
+                        val entryName = file.relativeTo(exportDir).path
+                        zos.putNextEntry(ZipEntry(entryName))
+                        file.inputStream().use { it.copyTo(zos) }
+                        zos.closeEntry()
+                    }
+                }
+            }
+
+            // Cleanup temp dir
+            exportDir.deleteRecursively()
+
+            Log.i(TAG, "Exported test bundle to ${zipFile.absolutePath}")
+            return zipFile
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to export test bundle", e)
+            exportDir.deleteRecursively()
             return null
         }
     }

android/samples/sample-render-validation/src/main/java/com/google/android/filament/validation/ValidationRunner.kt

@@ -41,18 +41,13 @@ class ValidationRunner(
     private var currentTestConfig: TestConfig? = null
     private var currentModelName: String? = null
 
-    private var loadStartFence: com.google.android.filament.Fence? = null
-    private var loadStartTime = 0L
     private var frameCounter = 0
 
     enum class State {
         IDLE,
-        LOADING_MODEL,
-        WAITING_FOR_FENCE,
         WAITING_FOR_RESOURCES,
         WARMUP,
-        RUNNING_TEST,
-        COMPARING
+        RUNNING_TEST
     }
 
     interface Callback {
@@ -93,8 +88,6 @@ class ValidationRunner(
             nextModel()
             return
         }
-
-        currentState = State.LOADING_MODEL
         callback?.onStatusChanged("Loading $modelName for ${currentTestConfig?.name}")
 
         // Load model on main thread (required by ModelViewer)
@@ -110,51 +103,24 @@ class ValidationRunner(
             Log.i("ValidationRunner", "Loading GLB buffer... (${bytes.size} bytes)")
             val buffer = ByteBuffer.wrap(bytes)
             modelViewer.loadModelGlb(buffer)
-            Log.i("ValidationRunner", "Model loaded. initializing fence.")
+            Log.i("ValidationRunner", "Model loaded.")
             modelViewer.transformToUnitCube()
-            loadStartFence = modelViewer.engine.createFence()
-            loadStartTime = System.nanoTime()
-            currentState = State.WAITING_FOR_FENCE
-            frameCounter = 0 // Reset for fence timeout tracking
-            Log.i("ValidationRunner", "State set to WAITING_FOR_FENCE")
+            currentState = State.WAITING_FOR_RESOURCES
+            frameCounter = 0
+            Log.i("ValidationRunner", "State set to WAITING_FOR_RESOURCES")
         } catch (e: Exception) {
-             Log.e("ValidationRunner", "Failed to load $path", e)
-             nextModel()
+            Log.e("ValidationRunner", "Failed to load $path", e)
+            nextModel()
         }
     }
 
     fun onFrame(frameTimeNanos: Long) {
         if (frameCounter % 60 == 0) {
-             Log.i("ValidationRunner", "onFrame: $currentState (frame: $frameCounter)")
+            Log.i("ValidationRunner", "onFrame: $currentState (frame: $frameCounter)")
         }
 
         when (currentState) {
             State.IDLE -> {}
-            State.WAITING_FOR_FENCE -> {
-                frameCounter++
-                if (frameCounter > 600) {
-                     Log.w("ValidationRunner", "Fence timed out after 600 frames! Forcing proceed.")
-                     modelViewer.engine.destroyFence(loadStartFence!!)
-                     loadStartFence = null
-                     currentState = State.WAITING_FOR_RESOURCES
-                     return
-                }
-
-                loadStartFence?.let { fence ->
-                     if (fence.wait(com.google.android.filament.Fence.Mode.FLUSH, 0) ==
-                            com.google.android.filament.Fence.FenceStatus.CONDITION_SATISFIED) {
-                         modelViewer.engine.destroyFence(fence)
-                         loadStartFence = null
-
-                         // Compile materials (simplified)
-                         modelViewer.scene.forEach { entity ->
-                             // ... existing material compilation logic ...
-                         }
-
-                         currentState = State.WAITING_FOR_RESOURCES
-                     }
-                }
-            }
             State.WAITING_FOR_RESOURCES -> {
                  val progress = modelViewer.progress
                  if (progress >= 1.0f) {
@@ -166,12 +132,12 @@ class ValidationRunner(
             State.WARMUP -> {
                 frameCounter++
                 if (frameCounter > 5) { // 5 frames warmup
-                     startAutomation()
+                    startAutomation()
                 }
             }
             State.RUNNING_TEST -> {
-                 // Log.i("ValidationRunner", "Running test...")
-                 currentEngine?.let { engine ->
+                // Log.i("ValidationRunner", "Running test...")
+                currentEngine?.let { engine ->
                     val content = AutomationEngine.ViewerContent()
                     content.view = modelViewer.view
                     content.renderer = modelViewer.renderer
@@ -186,13 +152,11 @@ class ValidationRunner(
                     if (engine.shouldClose()) {
                         Log.i("ValidationRunner", "Finishing test (frames: $frameCounter)")
                         // Test finished (for this spec)
-                        currentState = State.COMPARING
+                        currentState = State.IDLE
                         captureAndCompare()
                     }
                 }
             }
-            State.COMPARING -> {} // Busy
-            State.LOADING_MODEL -> {}
         }
     }
 
@@ -233,7 +197,36 @@ class ValidationRunner(
 
          // Golden path
          val modelFile = File(config.models.get(modelName)!!)
-         val goldenFile = modelFile.parentFile!!.parentFile!!.resolve("golden/${testFullName}.png")
+         val modelParent = modelFile.parentFile!!
+
+         // Search for golden in:
+         // 1. ../golden/ (standard structure)
+         // 2. ../goldens/ (exported structure, sibling of models)
+         // 3. ./goldens/ (backup)
+
+         val searchPaths = mutableListOf<File>()
+         modelParent.parentFile?.let {
+             searchPaths.add(it.resolve("golden"))
+             searchPaths.add(it.resolve("goldens"))
+         }
+         searchPaths.add(modelParent.resolve("goldens"))
+
+         var goldenFile: File? = null
+         for (path in searchPaths) {
+             val f = path.resolve("${testFullName}.png")
+             if (f.exists()) {
+                 goldenFile = f
+                 break
+             }
+         }
+
+         if (goldenFile != null) {
+             Log.i("ValidationRunner", "Found golden at ${goldenFile.absolutePath}")
+         } else {
+             Log.w("ValidationRunner", "Golden not found for $testFullName. Searched in: ${searchPaths.joinToString { it.absolutePath }}")
+             // Fallback to old behavior for reference if everything else fails
+             goldenFile = modelParent.parentFile?.resolve("golden/${testFullName}.png") ?: File("nonexistent")
+         }
 
          Thread {
              try {
@@ -245,14 +238,15 @@ class ValidationRunner(
                 var diffMetric = 0f
 
                 if (generateGoldens) {
-                    goldenFile.parentFile?.mkdirs()
-                    FileOutputStream(goldenFile).use { out ->
+                    val targetGolden = goldenFile ?: modelParent.parentFile?.resolve("golden/${testFullName}.png") ?: File(modelParent, "golden/${testFullName}.png")
+                    targetGolden.parentFile?.mkdirs()
+                    FileOutputStream(targetGolden).use { out ->
                         flipped.compress(Bitmap.CompressFormat.PNG, 100, out)
                     }
                     passed = true // Generating goldens always passes if successful
                     callback?.onStatusChanged("Golden generated")
                 } else {
-                    if (goldenFile.exists()) {
+                    if (goldenFile != null && goldenFile.exists()) {
                         val golden = android.graphics.BitmapFactory.decodeFile(goldenFile.absolutePath)
                         if (golden != null) {
                             callback?.onImageResult("Golden", golden)
@@ -273,7 +267,7 @@ class ValidationRunner(
                             callback?.onStatusChanged("Failed to load golden")
                         }
                     } else {
-                        Log.w("ValidationRunner", "Golden not found: ${goldenFile.absolutePath}")
+                        Log.w("ValidationRunner", "Golden not found: ${goldenFile?.absolutePath}")
                         callback?.onStatusChanged("Golden not found")
                     }
                 }

android/samples/sample-render-validation/src/main/res/layout/activity_main.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<androidx.constraintlayout.widget.ConstraintLayout 
+<androidx.constraintlayout.widget.ConstraintLayout
     xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     android:layout_width="match_parent"
@@ -10,6 +10,8 @@
         android:layout_width="0dp"
         android:layout_height="0dp"
         app:layout_constraintDimensionRatio="1:1"
+        app:layout_constraintWidth_percent="0.6"
+        android:layout_marginTop="32dp"
         app:layout_constraintTop_toTopOf="parent"
         app:layout_constraintStart_toStartOf="parent"
         app:layout_constraintEnd_toEndOf="parent">
@@ -20,10 +22,83 @@
             android:layout_height="match_parent" />
     </FrameLayout>
 
+    <LinearLayout
+        android:id="@+id/controls_container"
+        android:layout_width="0dp"
+        android:layout_height="wrap_content"
+        android:orientation="vertical"
+        android:paddingStart="20dp"
+        android:paddingEnd="20dp"
+        android:paddingTop="20dp"
+        android:paddingBottom="0dp"
+        app:layout_constraintTop_toBottomOf="@id/surface_container"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintEnd_toEndOf="parent">
+
+        <TextView
+            android:id="@+id/status_text"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:text="Initializing..."
+            android:textSize="12sp" />
+
+        <LinearLayout
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:orientation="vertical"
+            android:paddingTop="10dp"
+            android:paddingBottom="10dp">
+
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="horizontal"
+                android:gravity="center_vertical"
+                android:paddingBottom="8dp">
+
+                <com.google.android.material.button.MaterialButton
+                    android:id="@+id/run_button"
+                    android:layout_width="0dp"
+                    android:layout_height="wrap_content"
+                    android:layout_weight="1"
+                    style="@style/Widget.Material3.Button"
+                    android:text="Run Test" />
+
+                <com.google.android.material.button.MaterialButton
+                    android:id="@+id/load_button"
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    style="@style/Widget.Material3.Button.TonalButton"
+                    android:text="Load Test"
+                    android:layout_marginStart="8dp"/>
+
+                <com.google.android.material.button.MaterialButton
+                    android:id="@+id/options_button"
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    style="@style/Widget.Material3.Button.IconButton.Outlined"
+                    app:icon="@android:drawable/ic_menu_more"
+                    android:contentDescription="More Options"
+                    android:layout_marginStart="8dp"/>
+            </LinearLayout>
+        </LinearLayout>
+
+        <TextView
+            android:id="@+id/test_results_header"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:text="Test Results"
+            android:gravity="center"
+            android:textSize="14sp"
+            android:paddingTop="0dp"
+            android:paddingBottom="8dp" />
+
+    </LinearLayout>
+
     <ScrollView
         android:layout_width="0dp"
         android:layout_height="0dp"
-        app:layout_constraintTop_toBottomOf="@id/surface_container"
+        app:layout_constraintTop_toBottomOf="@id/controls_container"
         app:layout_constraintBottom_toBottomOf="parent"
         app:layout_constraintStart_toStartOf="parent"
         app:layout_constraintEnd_toEndOf="parent">
@@ -32,41 +107,9 @@
             android:layout_width="match_parent"
             android:layout_height="wrap_content"
             android:orientation="vertical"
-            android:padding="20dp">
-
-            <TextView
-                android:id="@+id/status_text"
-                android:layout_width="match_parent"
-                android:layout_height="wrap_content"
-                android:text="Initializing..."
-                android:textSize="14sp" />
-
-            <LinearLayout
-                android:layout_width="match_parent"
-                android:layout_height="wrap_content"
-                android:orientation="horizontal"
-                android:paddingTop="10dp"
-                android:paddingBottom="10dp">
-
-                <Spinner
-                    android:id="@+id/mode_spinner"
-                    android:layout_width="wrap_content"
-                    android:layout_height="wrap_content" />
-
-                <Button
-                    android:id="@+id/run_button"
-                    android:layout_width="wrap_content"
-                    android:layout_height="wrap_content"
-                    android:text="Run" />
-            </LinearLayout>
-
-            <TextView
-                android:layout_width="match_parent"
-                android:layout_height="wrap_content"
-                android:text="Test Results"
-                android:textSize="18sp"
-                android:paddingTop="20dp"
-                android:paddingBottom="10dp" />
+            android:paddingStart="20dp"
+            android:paddingEnd="20dp"
+            android:paddingBottom="20dp">
 
             <LinearLayout
                 android:id="@+id/results_container"
@@ -74,7 +117,6 @@
                 android:layout_height="wrap_content"
                 android:orientation="vertical" />
 
-
         </LinearLayout>
     </ScrollView>
 

build/common/upload-release-assets/package-lock.json

@@ -235,9 +235,9 @@
       "license": "MIT"
     },
     "node_modules/minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.3.tgz",
+      "integrity": "sha512-M2GCs7Vk83NxkUyQV1bkABc4yxgz9kILhHImZiBPAZ9ybuvCb0/H7lEl5XvIg3g+9d4eNotkZA5IWwYl0tibaA==",
       "dependencies": {
         "brace-expansion": "^1.1.7"
       },
@@ -429,9 +429,9 @@
       "integrity": "sha512-nGqtvLrj5w0naR6tDPfB4cUmYCqouzyQiz6C5y/LtcDllJdrcc6WaWW6iXyIIOErTa/XRybj28aasdn4LkVk6Q=="
     },
     "minimatch": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
-      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.3.tgz",
+      "integrity": "sha512-M2GCs7Vk83NxkUyQV1bkABc4yxgz9kILhHImZiBPAZ9ybuvCb0/H7lEl5XvIg3g+9d4eNotkZA5IWwYl0tibaA==",
       "requires": {
         "brace-expansion": "^1.1.7"
       }

docs/dup/intro.html

@@ -181,7 +181,7 @@ important for <code>matc</code> (material compiler).</p>
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.69.3'
+    implementation 'com.google.android.filament:filament-android:1.69.5'
 }
 </code></pre>
 <p>Here are all the libraries available in the group <code>com.google.android.filament</code>:</p>
@@ -195,7 +195,7 @@ dependencies {
 </div>
 <h3 id="ios"><a class="header" href="#ios">iOS</a></h3>
 <p>iOS projects can use CocoaPods to install the latest release:</p>
-<pre><code class="language-shell">pod 'Filament', '~&gt; 1.69.3'
+<pre><code class="language-shell">pod 'Filament', '~&gt; 1.69.5'
 </code></pre>
 <h2 id="documentation"><a class="header" href="#documentation">Documentation</a></h2>
 <ul>

docs/dup/test_ci_renderdiff.html

@@ -225,9 +225,10 @@ into <strong>branch</strong> of <code>filament-assets</code>. This branch is pai
 <code>filament</code> repo.</p>
 <p>As an example, imagine I am working on a PR, and I've uploaded my change, which is in a
 branch called <code>my-pr-branch</code>, to <code>filament</code>. This PR requires updating the golden. We would do
-it in the following fashion</p>
+it in the following fashion on a macOS machine:</p>
 <h3 id="using-a-script-to-update-the-golden-repo"><a class="header" href="#using-a-script-to-update-the-golden-repo">Using a script to update the golden repo</a></h3>
 <ul>
+<li>Make sure you've completed the steps in 'Setting up python'</li>
 <li>Run interactive mode in the <code>update_golden.py</code> script.
 <pre><code>python3 test/renderdiff/src/update_golden.py
 </code></pre>
@@ -263,6 +264,27 @@ branch of the golden repo (i.e. <code>my-pr-branch-golden</code>).</li>
 <li>If the PR is merged, then there is another workflow that will merge <code>my-pr-branch-golden</code>
 to the <code>main</code> branch of the golden repo.</li>
 </ul>
+<h3 id="automated-update-via-commit-message"><a class="header" href="#automated-update-via-commit-message">Automated update via commit message</a></h3>
+<p>Alternatively, if you are confident in your changes and want the CI to handle the update
+for you, you can use the following tag in your commit message:</p>
+<ul>
+<li>In the commit message of your working branch on <code>filament</code>, add the following line:
+<pre><code>RDIFF_ACCEPT_NEW_GOLDENS
+</code></pre>
+</li>
+</ul>
+<p>This has the following effects:</p>
+<ul>
+<li>The presubmit test <code>test-renderdiff</code> will be bypassed (it will not perform rendering or
+comparison).</li>
+<li>When the PR is merged, the postsubmit CI will automatically:
+<ol>
+<li>Build Filament and generate the new images.</li>
+<li>Upload them to a temporary branch in <code>filament-assets</code>.</li>
+<li>Merge that branch into <code>main</code>.</li>
+</ol>
+</li>
+</ul>
 <h2 id="viewing-test-results"><a class="header" href="#viewing-test-results">Viewing test results</a></h2>
 <p>We provide a viewer for looking at the result of a test run. The viewer is a webapp that can
 be used by pointing your browser to a localhost port. If you input the viewer with a PR or a

filament/CMakeLists.txt

@@ -93,6 +93,7 @@ set(SRCS
         src/MorphTargetBuffer.cpp
         src/PostProcessManager.cpp
         src/ProgramSpecialization.cpp
+        src/LocalProgramCache.cpp
         src/RenderPass.cpp
         src/RenderPrimitive.cpp
         src/RenderTarget.cpp
@@ -186,6 +187,7 @@ set(PRIVATE_HDRS
         src/MaterialCache.h
         src/MaterialDefinition.h
         src/MaterialParser.h
+        src/LocalProgramCache.h
         src/MaterialInstanceManager.h
         src/PIDController.h
         src/PostProcessManager.h

filament/backend/CMakeLists.txt

@@ -564,170 +564,170 @@ endif()
 # ==================================================================================================
 # Test
 # ==================================================================================================
-option(INSTALL_BACKEND_TEST "Install the backend test library so it can be consumed on iOS" OFF)
+if (FILAMENT_BUILD_TESTING)
+    option(INSTALL_BACKEND_TEST "Install the backend test library so it can be consumed on iOS" OFF)
 
-if (APPLE OR LINUX)
-    set(BACKEND_TEST_SRC
-        test/BackendTest.cpp
-        test/ShaderGenerator.cpp
-        test/TrianglePrimitive.cpp
-        test/Arguments.cpp
-        test/ImageExpectations.cpp
-        test/Lifetimes.cpp
-        test/PlatformRunner.cpp
-        test/Shader.cpp
-        test/SharedShaders.cpp
-        test/Skip.cpp
-        test/test_Autoresolve.cpp
-        test/test_FeedbackLoops.cpp
-        test/test_Blit.cpp
-        test/test_MissingRequiredAttributes.cpp
-        test/test_ReadPixels.cpp
-        test/test_ReadTexture.cpp
-        test/test_BufferUpdates.cpp
-        test/test_Callbacks.cpp
-        test/test_JobQueue.cpp
-        test/test_MemoryMappedBuffer.cpp
-        test/test_MsaaSwapChain.cpp
-        test/test_MRT.cpp
-        test/test_PushConstants.cpp
-        test/test_LoadImage.cpp
-        test/test_StencilBuffer.cpp
-        test/test_Scissor.cpp
-        test/test_MipLevels.cpp
-        test/test_Handles.cpp
-        test/test_CircularBuffer.cpp
-        test/test_CommandBufferQueue.cpp
-        test/test_Template.cpp
-    )
-    if (FILAMENT_SUPPORTS_WEBGPU)
-        list(APPEND BACKEND_TEST_SRC
-                test/test_WebGPUAsyncTaskCounter.cpp
-                test/test_WebGPUComposeSwizzle.cpp)
-    endif()
-    if (APPLE)
-        # Metal-specific tests
-        list(APPEND BACKEND_TEST_SRC
-            test/test_MetalBlitter.mm
+    if (APPLE OR LINUX)
+        set(BACKEND_TEST_SRC
+            test/BackendTest.cpp
+            test/ShaderGenerator.cpp
+            test/TrianglePrimitive.cpp
+            test/Arguments.cpp
+            test/ImageExpectations.cpp
+            test/Lifetimes.cpp
+            test/PlatformRunner.cpp
+            test/Shader.cpp
+            test/SharedShaders.cpp
+            test/Skip.cpp
+            test/test_Autoresolve.cpp
+            test/test_FeedbackLoops.cpp
+            test/test_Blit.cpp
+            test/test_MissingRequiredAttributes.cpp
+            test/test_ReadPixels.cpp
+            test/test_ReadTexture.cpp
+            test/test_BufferUpdates.cpp
+            test/test_Callbacks.cpp
+            test/test_JobQueue.cpp
+            test/test_MemoryMappedBuffer.cpp
+            test/test_MsaaSwapChain.cpp
+            test/test_MRT.cpp
+            test/test_PushConstants.cpp
+            test/test_LoadImage.cpp
+            test/test_StencilBuffer.cpp
+            test/test_Scissor.cpp
+            test/test_MipLevels.cpp
+            test/test_Handles.cpp
+            test/test_CircularBuffer.cpp
+            test/test_CommandBufferQueue.cpp
+            test/test_Template.cpp
         )
-    endif()
-    set(BACKEND_TEST_LIBS
-        absl::str_format
-        backend
-        getopt
-        gtest
-        imageio
-        filamat
-        SPIRV
-        spirv-cross-glsl)
-    # Create input/output directories for test result images.
-    file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/images/actual_images)
-    file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/images/diff_images)
-    file(COPY test/expected_images DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/images)
-endif()
-
-# TODO: Disabling IOS test due to breakage wrt glslang update
-if (APPLE AND NOT IOS)
-    # TODO: we should expand this test to Linux and other platforms.
-    list(APPEND BACKEND_TEST_SRC
-         test/test_RenderExternalImage.cpp)
-    add_library(backend_test STATIC ${BACKEND_TEST_SRC})
-    target_link_libraries(backend_test PUBLIC ${BACKEND_TEST_LIBS})
-    target_compile_options(backend_test PRIVATE "-fobjc-arc")
-
-    set(BACKEND_TEST_DEPS
-            OSDependent
-            SPIRV
-            SPIRV-Tools
-            SPIRV-Tools-opt
-            backend_test
+        if (FILAMENT_SUPPORTS_WEBGPU)
+            list(APPEND BACKEND_TEST_SRC
+                    test/test_WebGPUAsyncTaskCounter.cpp
+                    test/test_WebGPUComposeSwizzle.cpp)
+        endif()
+        if (APPLE)
+            # Metal-specific tests
+            list(APPEND BACKEND_TEST_SRC
+                test/test_MetalBlitter.mm
+            )
+        endif()
+        set(BACKEND_TEST_LIBS
+            absl::str_format
+            backend
             getopt
             gtest
-            glslang
-            spirv-cross-core
-            spirv-cross-glsl
-            spirv-cross-msl)
-
-    if (NOT IOS)
-        target_link_libraries(backend_test PRIVATE image imageio)
-        list(APPEND BACKEND_TEST_DEPS image)
-    endif()
-    if (FILAMENT_SUPPORTS_WEBGPU)
-        target_link_libraries(backend_test PRIVATE webgpu_dawn dawncpp_headers)
-        list(APPEND BACKEND_TEST_DEPS webgpu_dawn dawncpp_headers)
+            imageio
+            filamat
+            SPIRV
+            spirv-cross-glsl)
+        # Create input/output directories for test result images.
+        file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/images/actual_images)
+        file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/images/diff_images)
+        file(COPY test/expected_images DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/images)
     endif()
 
-    set(BACKEND_TEST_COMBINED_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/libbackendtest_combined.a")
-    combine_static_libs(backend_test "${BACKEND_TEST_COMBINED_OUTPUT}" "${BACKEND_TEST_DEPS}")
+    # TODO: Disabling IOS test due to breakage wrt glslang update
+    if (APPLE AND NOT IOS)
+        # TODO: we should expand this test to Linux and other platforms.
+        list(APPEND BACKEND_TEST_SRC
+            test/test_RenderExternalImage.cpp)
+        add_library(backend_test STATIC ${BACKEND_TEST_SRC})
+        target_link_libraries(backend_test PUBLIC ${BACKEND_TEST_LIBS})
+        target_compile_options(backend_test PRIVATE "-fobjc-arc")
 
-    set(BACKEND_TEST_LIB_NAME ${CMAKE_STATIC_LIBRARY_PREFIX}backend_test${CMAKE_STATIC_LIBRARY_SUFFIX})
+        set(BACKEND_TEST_DEPS
+                OSDependent
+                SPIRV
+                SPIRV-Tools
+                SPIRV-Tools-opt
+                backend_test
+                getopt
+                gtest
+                glslang
+                spirv-cross-core
+                spirv-cross-glsl
+                spirv-cross-msl)
 
-    if (INSTALL_BACKEND_TEST)
-        install(FILES "${BACKEND_TEST_COMBINED_OUTPUT}" DESTINATION lib/${DIST_DIR} RENAME ${BACKEND_TEST_LIB_NAME})
-        install(FILES test/PlatformRunner.h DESTINATION include/backend_test)
+        if (NOT IOS)
+            target_link_libraries(backend_test PRIVATE image imageio)
+            list(APPEND BACKEND_TEST_DEPS image)
+        endif()
+        if (FILAMENT_SUPPORTS_WEBGPU)
+            target_link_libraries(backend_test PRIVATE webgpu_dawn dawncpp_headers)
+            list(APPEND BACKEND_TEST_DEPS webgpu_dawn dawncpp_headers)
+        endif()
+
+        set(BACKEND_TEST_COMBINED_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/libbackendtest_combined.a")
+        combine_static_libs(backend_test "${BACKEND_TEST_COMBINED_OUTPUT}" "${BACKEND_TEST_DEPS}")
+
+        set(BACKEND_TEST_LIB_NAME ${CMAKE_STATIC_LIBRARY_PREFIX}backend_test${CMAKE_STATIC_LIBRARY_SUFFIX})
+
+        if (INSTALL_BACKEND_TEST)
+            install(FILES "${BACKEND_TEST_COMBINED_OUTPUT}" DESTINATION lib/${DIST_DIR} RENAME ${BACKEND_TEST_LIB_NAME})
+            install(FILES test/PlatformRunner.h DESTINATION include/backend_test)
+        endif()
+
+        set_target_properties(backend_test PROPERTIES FOLDER Tests)
+
+        if (APPLE AND NOT IOS)
+            add_executable(backend_test_mac test/mac_runner.mm)
+            target_link_libraries(backend_test_mac PRIVATE "-framework Metal -framework AppKit -framework QuartzCore")
+            # Because each test case is a separate file, the -force_load flag is necessary to prevent the
+            # linker from removing "unused" symbols.
+            target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
+            set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+
+            # This is needed after XCode 15.3
+            set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
+            set_target_properties(backend_test_mac PROPERTIES INSTALL_RPATH /usr/local/lib)
+        endif()
     endif()
 
-    set_target_properties(backend_test PROPERTIES FOLDER Tests)
+    if (LINUX)
+        add_executable(backend_test_linux test/linux_runner.cpp ${BACKEND_TEST_SRC})
+        target_link_libraries(backend_test_linux PRIVATE ${BACKEND_TEST_LIBS})
+        set_target_properties(backend_test_linux PROPERTIES FOLDER Tests)
+        if (FILAMENT_SUPPORTS_WEBGPU)
+            target_link_libraries(backend_test_linux PRIVATE webgpu_dawn dawncpp_headers)
+        endif()
+    endif()
+
+    # ==================================================================================================
+    # Compute tests
+    #
+    #if (NOT IOS AND NOT WEBGL)
+    #
+    #add_executable(compute_test
+    #        test/ComputeTest.cpp
+    #        test/Arguments.cpp
+    #        test/test_ComputeBasic.cpp
+    #        )
+    #
+    #target_link_libraries(compute_test PRIVATE
+    #        backend
+    #        getopt
+    #        gtest
+    #        )
+    #
+    #set_target_properties(compute_test PROPERTIES FOLDER Tests)
+    #
+    #endif()
+
+    # ==================================================================================================
+    # Metal utils tests
 
     if (APPLE AND NOT IOS)
-       add_executable(backend_test_mac test/mac_runner.mm)
-       target_link_libraries(backend_test_mac PRIVATE "-framework Metal -framework AppKit -framework QuartzCore")
-       # Because each test case is a separate file, the -force_load flag is necessary to prevent the
-       # linker from removing "unused" symbols.
-       target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
-       set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+        add_executable(metal_utils_test test/MetalTest.mm)
 
-       # This is needed after XCode 15.3
-       set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
-       set_target_properties(backend_test_mac PROPERTIES INSTALL_RPATH /usr/local/lib)
+        target_compile_options(metal_utils_test PRIVATE "-fobjc-arc")
+
+        target_link_libraries(metal_utils_test PRIVATE
+                backend
+                getopt
+                gtest
+                )
+
+        set_target_properties(metal_utils_test PROPERTIES FOLDER Tests)
     endif()
-endif()
-
-if (LINUX)
-    add_executable(backend_test_linux test/linux_runner.cpp ${BACKEND_TEST_SRC})
-    target_link_libraries(backend_test_linux PRIVATE ${BACKEND_TEST_LIBS})
-    set_target_properties(backend_test_linux PROPERTIES FOLDER Tests)
-    if (FILAMENT_SUPPORTS_WEBGPU)
-        target_link_libraries(backend_test_linux PRIVATE webgpu_dawn dawncpp_headers)
-    endif()
-endif()
-
-# ==================================================================================================
-# Compute tests
-#
-#if (NOT IOS AND NOT WEBGL)
-#
-#add_executable(compute_test
-#        test/ComputeTest.cpp
-#        test/Arguments.cpp
-#        test/test_ComputeBasic.cpp
-#        )
-#
-#target_link_libraries(compute_test PRIVATE
-#        backend
-#        getopt
-#        gtest
-#        )
-#
-#set_target_properties(compute_test PROPERTIES FOLDER Tests)
-#
-#endif()
-
-# ==================================================================================================
-# Metal utils tests
-
-if (APPLE AND NOT IOS)
-
-add_executable(metal_utils_test test/MetalTest.mm)
-
-target_compile_options(metal_utils_test PRIVATE "-fobjc-arc")
-
-target_link_libraries(metal_utils_test PRIVATE
-        backend
-        getopt
-        gtest
-        )
-
-set_target_properties(metal_utils_test PROPERTIES FOLDER Tests)
-
-endif()
+endif()

filament/backend/src/VirtualMachineEnv.cpp

@@ -25,6 +25,11 @@
 
 #include <mutex>
 
+#ifdef __ANDROID__
+#include <pthread.h>
+#endif
+
+
 namespace filament {
 
 using namespace utils;
@@ -105,8 +110,21 @@ JNIEnv* VirtualMachineEnv::getEnvironmentSlow() {
     FILAMENT_CHECK_PRECONDITION(mVirtualMachine)
             << "JNI_OnLoad() has not been called";
 
-#if defined(__ANDROID__)
-    jint const result = mVirtualMachine->AttachCurrentThread(&mJniEnv, nullptr);
+#ifdef __ANDROID__
+    JavaVMAttachArgs args;
+    args.version = JNI_VERSION_1_6;
+    args.group = nullptr;
+    char threadName[16]; // pthread_getname_np returns at most 16 bytes
+    if (__builtin_available(android 26, *)) {
+        if (pthread_getname_np(pthread_self(), threadName, sizeof(threadName)) == 0) {
+            args.name = threadName;
+        } else {
+            args.name = nullptr;
+        }
+    } else {
+        args.name = nullptr;
+    }
+    jint const result = mVirtualMachine->AttachCurrentThread(&mJniEnv, &args);
 #else
     jint const result = mVirtualMachine->AttachCurrentThread(reinterpret_cast<void**>(&mJniEnv), nullptr);
 #endif

filament/backend/src/opengl/OpenGLContext.h

@@ -91,7 +91,7 @@ public:
         GLenum getIndicesType() const noexcept {
             return indicesType;
         }
-    } gl;
+    };
 
     static bool queryOpenGLVersion(GLint* major, GLint* minor) noexcept;
 

filament/backend/src/vulkan/VulkanAsyncHandles.cpp

@@ -29,6 +29,12 @@ using namespace bluevk;
 
 namespace filament::backend {
 
+std::shared_ptr<VulkanCmdFence> VulkanCmdFence::completed() noexcept {
+    auto cmdFence = std::make_shared<VulkanCmdFence>(VK_NULL_HANDLE);
+    cmdFence->mStatus = VK_SUCCESS;
+    return cmdFence;
+}
+
 FenceStatus VulkanCmdFence::wait(VkDevice device, uint64_t const timeout,
     std::chrono::steady_clock::time_point const until) {
 

filament/backend/src/vulkan/VulkanAsyncHandles.h

@@ -40,6 +40,13 @@ struct VulkanCmdFence {
     explicit VulkanCmdFence(VkFence fence) : mFence(fence) { }
     ~VulkanCmdFence() = default;
 
+    // Creates a VulkanCmdFence with its status set to VK_SUCCESS. It holds
+    // a null handle; it is assumed that any user of this object will avoid
+    // using the fence handle directly if getStatus() returns VK_SUCCESS, as
+    // in that case, it's likely the fence is being reused for other passes,
+    // and is not in the expected state anyway.
+    static std::shared_ptr<VulkanCmdFence> completed() noexcept;
+
     void setStatus(VkResult const value) {
         std::lock_guard const l(mLock);
         mStatus = value;

filament/backend/src/vulkan/VulkanCommands.h

@@ -277,7 +277,11 @@ private:
     fvkmemory::resource_ptr<VulkanSemaphore> mLastSubmit;
 
     VkFence mLastFence = VK_NULL_HANDLE;
-    std::shared_ptr<VulkanCmdFence> mLastFenceStatus;
+    // Start out with a completed fence, because if no commands have
+    // been queued or submited, then by definition, all pending work
+    // is complete.
+    std::shared_ptr<VulkanCmdFence> mLastFenceStatus =
+            VulkanCmdFence::completed();
 
     VkPipelineStageFlags mInjectedDependencyWaitStage = 0;
 };

filament/backend/src/vulkan/VulkanContext.h

@@ -36,6 +36,7 @@ VK_DEFINE_HANDLE(VmaPool)
 namespace filament::backend {
 
 struct VulkanCommandBuffer;
+struct VulkanRenderPass;
 struct VulkanRenderTarget;
 struct VulkanSwapChain;
 struct VulkanTexture;
@@ -58,11 +59,11 @@ struct VulkanAttachment {
     VkImageSubresourceRange getSubresourceRange() const;
 };
 
-struct VulkanRenderPass {
+struct VulkanRenderPassContext {
     // Between the begin and end command render pass we cache the command buffer
     VulkanCommandBuffer* commandBuffer;
     fvkmemory::resource_ptr<VulkanRenderTarget> renderTarget;
-    VkRenderPass renderPass;
+    fvkmemory::resource_ptr<VulkanRenderPass> renderPass;
     RenderPassParams params;
     int currentSubpass;
 };

filament/backend/src/vulkan/VulkanDescriptorSetCache.cpp

@@ -355,35 +355,8 @@ void VulkanDescriptorSetCache::updateBuffer(fvkmemory::resource_ptr<VulkanDescri
 }
 
 void VulkanDescriptorSetCache::updateSampler(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
-        uint8_t binding, fvkmemory::resource_ptr<VulkanTexture> texture, VkSampler sampler,
-        VkDescriptorSetLayout externalSamplerLayout) noexcept {
-
-    // We have to update a bound set for two use cases
-    //   - streaming API (a changing feed of AHardwareBuffer)
-    //   - external samplers - potential changing of dataspace per-frame
-
-    // TODO: Fix the stream flow case base on the above comment!!
-    if (set->isAnExternalSamplerBound) {
-        auto layout = set->getLayout();
-        // Build a new descriptor set from the new layout
-        VkDescriptorSetLayout const genLayout = set->boundLayout;
-        VkDescriptorSet const newSet = getVkSet(layout->count, genLayout);
-        Bitmask const ubo = layout->bitmask.ubo | layout->bitmask.dynamicUbo;
-        Bitmask samplers = layout->bitmask.sampler;
-        samplers.unset(binding);
-
-        // Each bitmask denotes a binding index, and separated into two stages - vertex and buffer
-        // We fold the two stages into just the lower half of the bits to denote a combined set of
-        // bindings.
-        Bitmask const copyBindings = foldBitsInHalf(ubo | samplers);
-        VkDescriptorSet const srcSet = set->getVkSet();
-        copySet(srcSet, newSet, copyBindings);
-        set->addNewSet(newSet,
-                [this, layoutCount = layout->count, genLayout, newSet](VulkanDescriptorSet*) {
-                    this->manualRecycle(layoutCount, genLayout, newSet);
-                });
-    }
-
+        uint8_t binding, fvkmemory::resource_ptr<VulkanTexture> texture,
+        VkSampler sampler, VkDescriptorSetLayout externalSamplerLayout) noexcept {
     VkDescriptorSet const vkset = set->getVkSet();
     VkImageSubresourceRange range = texture->getPrimaryViewRange();
     VkImageViewType const expectedType = texture->getViewType();
@@ -432,6 +405,28 @@ fvkmemory::resource_ptr<VulkanDescriptorSet> VulkanDescriptorSetCache::createSet
     return set;
 }
 
+void VulkanDescriptorSetCache::cloneSet(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
+        fvkutils::SamplerBitmask samplerMask) noexcept {
+    auto const& layout = set->getLayout();
+    // Build a new descriptor set from layout
+    VkDescriptorSetLayout const genLayout = set->boundLayout;
+    VkDescriptorSet const newSet = getVkSet(layout->count, genLayout);
+
+    // Each bitmask denotes a binding index, and separated into two stages - vertex and buffer
+    // We fold the two stages into just the lower half of the bits to denote a combined set of
+    // bindings.
+    Bitmask const ubo = layout->bitmask.ubo | layout->bitmask.dynamicUbo;
+    // Don't copy the samplers in the mask
+    Bitmask samplers = layout->bitmask.sampler ^ samplerMask;
+    Bitmask const copyBindings = foldBitsInHalf(ubo | samplers);
+
+    VkDescriptorSet const srcSet = set->getVkSet();
+    copySet(srcSet, newSet, copyBindings);
+    set->addNewSet(newSet,
+            [this, layoutCount = layout->count, genLayout, newSet](
+                    VulkanDescriptorSet*) { this->manualRecycle(layoutCount, genLayout, newSet); });
+}
+
 VkDescriptorSet VulkanDescriptorSetCache::getVkSet(DescriptorCount const& count,
         VkDescriptorSetLayout vklayout) {
     return mDescriptorPool->obtainSet(count, vklayout);

filament/backend/src/vulkan/VulkanDescriptorSetCache.h

@@ -76,6 +76,11 @@ public:
     fvkmemory::resource_ptr<VulkanDescriptorSet> createSet(Handle<HwDescriptorSet> handle,
             fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout);
 
+    // Create and set as current a new VkDescriptorSet using the `set` currently bound layout and
+    // copy all the bindings and ignoring the samplers bindings in the `samplerMask`.
+    void cloneSet(fvkmemory::resource_ptr<VulkanDescriptorSet> set,
+            fvkutils::SamplerBitmask samplerMask) noexcept;
+
     // This method is meant to be used with external samplers
     VkDescriptorSet getVkSet(DescriptorCount const& count, VkDescriptorSetLayout vklayout);
 

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -1913,9 +1913,6 @@ void VulkanDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
 
     auto rt = resource_ptr<VulkanRenderTarget>::cast(&mResourceManager, rth);
 
-    VulkanCommandBuffer* commandBuffer = rt->isProtected() ?
-           &mCommands.getProtected() : &mCommands.get();
-
     // Filament has the expectation that the contents of the swap chain are not preserved on the
     // first render pass. Note however that its contents are often preserved on subsequent render
     // passes, due to multiple views.
@@ -1930,6 +1927,11 @@ void VulkanDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
         }
     }
 
+    // Note that this needs to come after the acquireNextswapchainImage() above because that path
+    // might flush the current command buffer.
+    VulkanCommandBuffer* commandBuffer =
+            rt->isProtected() ? &mCommands.getProtected() : &mCommands.get();
+
     // Note that retrieving the extent must come after the acquireNextSwapchainImage() above;
     // otherwise it might be 0.
     VkExtent2D const extent = rt->getExtent();
@@ -1975,17 +1977,19 @@ void VulkanDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
     rpkey.initialDepthLayout = currentDepthLayout;
     rpkey.subpassMask = uint8_t(params.subpassMask);
 
-    VkRenderPass renderPass = mFramebufferCache.getRenderPass(rpkey);
+    fvkmemory::resource_ptr<VulkanRenderPass> renderPass =
+            mFramebufferCache.getRenderPass(rpkey, &mResourceManager);
     mPipelineCache.bindRenderPass(renderPass, 0);
 
     // Create the VkFramebuffer or fetch it from cache.
     VulkanFboCache::FboKey fbkey = rt->getFboKey();
-    fbkey.renderPass = renderPass;
+    fbkey.renderPass = renderPass->getVkRenderPass();
     fbkey.layers = 1;
 
     rt->emitBarriersBeginRenderPass(*commandBuffer);
 
-    VkFramebuffer vkfb = mFramebufferCache.getFramebuffer(fbkey);
+    fvkmemory::resource_ptr<VulkanFramebuffer> vkfb =
+            mFramebufferCache.getFramebuffer(fbkey, &mResourceManager, rt);
 
 // Assign a label to the framebuffer for debugging purposes.
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS | FVK_DEBUG_DEBUG_UTILS)
@@ -1998,12 +2002,14 @@ void VulkanDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
 
     // The current command buffer now has references to the render target and its attachments.
     commandBuffer->acquire(rt);
+    commandBuffer->acquire(renderPass);
+    commandBuffer->acquire(vkfb);
 
     // Populate the structures required for vkCmdBeginRenderPass.
     VkRenderPassBeginInfo renderPassInfo {
         .sType = VK_STRUCTURE_TYPE_RENDER_PASS_BEGIN_INFO,
-        .renderPass = renderPass,
-        .framebuffer = vkfb,
+        .renderPass = renderPass->getVkRenderPass(),
+        .framebuffer = vkfb->getVkFramebuffer(),
 
         // The renderArea field constrains the LoadOp, but scissoring does not.
         // Therefore, we do not set the scissor rect here, we only need it in draw().
@@ -2058,7 +2064,7 @@ void VulkanDriver::beginRenderPass(Handle<HwRenderTarget> rth, const RenderPassP
     mCurrentRenderPass = {
         .commandBuffer = commandBuffer,
         .renderTarget = rt,
-        .renderPass = renderPassInfo.renderPass,
+        .renderPass = renderPass,
         .params = params,
         .currentSubpass = 0,
     };
@@ -2078,8 +2084,7 @@ void VulkanDriver::endRenderPass(int) {
     rt->emitBarriersEndRenderPass(*mCurrentRenderPass.commandBuffer);
 
     mCurrentRenderPass.renderTarget = {};
-    mCurrentRenderPass.renderPass = VK_NULL_HANDLE;
-
+    mCurrentRenderPass.renderPass = {};
     mCurrentRenderPass.commandBuffer = nullptr;
 }
 
@@ -2244,7 +2249,7 @@ void VulkanDriver::resolve(
         Handle<HwTexture> src, uint8_t dstLevel, uint8_t dstLayer) {
     FVK_SYSTRACE_SCOPE();
 
-    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+    FILAMENT_CHECK_PRECONDITION(!mCurrentRenderPass.renderPass)
             << "resolve() cannot be invoked inside a render pass.";
 
     auto srcTexture = resource_ptr<VulkanTexture>::cast(&mResourceManager, src);
@@ -2287,7 +2292,7 @@ void VulkanDriver::blit(
         math::uint2 size) {
     FVK_SYSTRACE_SCOPE();
 
-    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+    FILAMENT_CHECK_PRECONDITION(!mCurrentRenderPass.renderPass)
             << "blit() cannot be invoked inside a render pass.";
 
     auto srcTexture = resource_ptr<VulkanTexture>::cast(&mResourceManager, src);
@@ -2329,7 +2334,7 @@ void VulkanDriver::blitDEPRECATED(TargetBufferFlags buffers,
 
     // Note: blitDEPRECATED is only used for Renderer::copyFrame()
 
-    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+    FILAMENT_CHECK_PRECONDITION(!mCurrentRenderPass.renderPass)
             << "blitDEPRECATED() cannot be invoked inside a render pass.";
 
     FILAMENT_CHECK_PRECONDITION(buffers == TargetBufferFlags::COLOR0)

filament/backend/src/vulkan/VulkanDriver.h

@@ -139,7 +139,7 @@ private:
 
     resource_ptr<VulkanSwapChain> mCurrentSwapChain;
     resource_ptr<VulkanRenderTarget> mDefaultRenderTarget;
-    VulkanRenderPass mCurrentRenderPass = {};
+    VulkanRenderPassContext mCurrentRenderPass = {};
     VmaAllocator mAllocator = VK_NULL_HANDLE;
     VkDebugReportCallbackEXT mDebugCallback = VK_NULL_HANDLE;
 

filament/backend/src/vulkan/VulkanExternalImageManager.cpp

@@ -94,6 +94,9 @@ void VulkanExternalImageManager::updateSetAndLayout(
     fvkmemory::resource_ptr<VulkanDescriptorSetLayout> const& layout = set->getLayout();
     set->boundLayout = mDescriptorSetLayoutCache->getVkLayout(layout->bitmask,
             actualExternalSamplers, outSamplers);
+
+    mDescriptorSetCache->cloneSet(set, actualExternalSamplers);
+
     // Update the external samplers in the set
     for (auto& [binding, sampler, image]: samplerAndBindings) {
         // We cannot call updateSamplerForExternalSamplerSet because some samplers are non NULL

filament/backend/src/vulkan/VulkanFboCache.cpp

@@ -17,6 +17,7 @@
 #include "VulkanFboCache.h"
 
 #include "VulkanConstants.h"
+#include "VulkanHandles.h"
 #include "vulkan/utils/Image.h"
 
 #include <utils/Panic.h>
@@ -69,9 +70,11 @@ VulkanFboCache::~VulkanFboCache() {
             << "Please explicitly call terminate() while the VkDevice is still alive.";
 }
 
-VkFramebuffer VulkanFboCache::getFramebuffer(FboKey const& config) noexcept {
+fvkmemory::resource_ptr<VulkanFramebuffer> VulkanFboCache::getFramebuffer(FboKey const& config,
+        fvkmemory::ResourceManager* resManager,
+        fvkmemory::resource_ptr<VulkanRenderTarget> renderTarget) noexcept {
     FboMap::iterator iter = mFramebufferCache.find(config);
-    if (UTILS_LIKELY(iter != mFramebufferCache.end() && iter->second.handle != VK_NULL_HANDLE)) {
+    if (UTILS_LIKELY(iter != mFramebufferCache.end())) {
         iter.value().timestamp = mCurrentTime;
         return iter->second.handle;
     }
@@ -117,13 +120,17 @@ VkFramebuffer VulkanFboCache::getFramebuffer(FboKey const& config) noexcept {
     VkResult error = vkCreateFramebuffer(mDevice, &info, VKALLOC, &framebuffer);
     FILAMENT_CHECK_POSTCONDITION(error == VK_SUCCESS) << "Unable to create framebuffer."
                                                      << " error=" << static_cast<int32_t>(error);
-    mFramebufferCache[config] = {framebuffer, mCurrentTime};
-    return framebuffer;
+    fvkmemory::resource_ptr<VulkanFramebuffer> fbh =
+            fvkmemory::resource_ptr<VulkanFramebuffer>::construct(resManager, mDevice, framebuffer,
+                    renderTarget);
+    mFramebufferCache[config] = { fbh, mCurrentTime };
+    return fbh;
 }
 
-VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept {
+fvkmemory::resource_ptr<VulkanRenderPass> VulkanFboCache::getRenderPass(
+        RenderPassKey const& config, fvkmemory::ResourceManager* resManager) noexcept {
     auto iter = mRenderPassCache.find(config);
-    if (UTILS_LIKELY(iter != mRenderPassCache.end() && iter->second.handle != VK_NULL_HANDLE)) {
+    if (UTILS_LIKELY(iter != mRenderPassCache.end())) {
         iter.value().timestamp = mCurrentTime;
         return iter->second.handle;
     }
@@ -326,7 +333,9 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
     VkResult error = vkCreateRenderPass(mDevice, &renderPassInfo, VKALLOC, &renderPass);
     FILAMENT_CHECK_POSTCONDITION(error == VK_SUCCESS) << "Unable to create render pass."
                                                       << " error=" << error;
-    mRenderPassCache[config] = {renderPass, mCurrentTime};
+    fvkmemory::resource_ptr<VulkanRenderPass> rph =
+        fvkmemory::resource_ptr<VulkanRenderPass>::construct(resManager, mDevice, renderPass);
+    mRenderPassCache[config] = {rph, mCurrentTime};
 
 #if FVK_ENABLED(FVK_DEBUG_FBO_CACHE)
     FVK_LOGD << "Created render pass " << renderPass << " with ";
@@ -343,13 +352,12 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
              << "colorAttachmentCount[0] = " << subpasses[0].colorAttachmentCount;
 #endif
 
-    return renderPass;
+    return rph;
 }
 
 void VulkanFboCache::resetFramebuffers() noexcept {
     for (const auto& pair: mFramebufferCache) {
         mRenderPassRefCount[pair.first.renderPass]--;
-        vkDestroyFramebuffer(mDevice, pair.second.handle, VKALLOC);
     }
     mFramebufferCache.clear();
 }
@@ -357,9 +365,6 @@ void VulkanFboCache::resetFramebuffers() noexcept {
 void VulkanFboCache::terminate() noexcept {
     resetFramebuffers();
 
-    for (const auto& pair: mRenderPassCache) {
-        vkDestroyRenderPass(mDevice, pair.second.handle, VKALLOC);
-    }
     mRenderPassRefCount.clear();
     mRenderPassCache.clear();
 }
@@ -380,8 +385,6 @@ void VulkanFboCache::gc() noexcept {
         const FboVal fbo = iter->second;
         if (fbo.timestamp < evictTime && fbo.handle) {
             mRenderPassRefCount[iter->first.renderPass]--;
-            vkDestroyFramebuffer(mDevice, fbo.handle, VKALLOC);
-            iter.value().handle = VK_NULL_HANDLE;
 
             // erase(iterator) returns the iterator to the next element.
             iter = mFramebufferCache.erase(iter);
@@ -391,11 +394,8 @@ void VulkanFboCache::gc() noexcept {
     }
 
     for (RenderPassMap::iterator iter = mRenderPassCache.begin(); iter != mRenderPassCache.end(); ) {
-        const VkRenderPass handle = iter->second.handle;
+        const VkRenderPass handle = iter->second.handle->getVkRenderPass();
         if (iter->second.timestamp < evictTime && handle && mRenderPassRefCount[handle] == 0) {
-            vkDestroyRenderPass(mDevice, handle, VKALLOC);
-            iter.value().handle = VK_NULL_HANDLE;
-
             // erase(iterator) returns the iterator to the next element.
             iter = mRenderPassCache.erase(iter);
             mRenderPassRefCount.erase(handle);

filament/backend/src/vulkan/VulkanFboCache.h

@@ -18,6 +18,9 @@
 #define TNT_FILAMENT_BACKEND_VULKANFBOCACHE_H
 
 #include "VulkanContext.h"
+#include "vulkan/memory/Resource.h"
+#include "vulkan/memory/ResourceManager.h"
+#include "vulkan/memory/ResourcePointer.h"
 
 #include <utils/Hash.h>
 
@@ -27,6 +30,9 @@
 
 namespace filament::backend {
 
+struct VulkanFramebuffer;
+struct VulkanRenderPass;
+
 // Simple manager for VkFramebuffer and VkRenderPass objects.
 //
 // Note that a VkFramebuffer is just a binding between a render pass and a set of image views. So,
@@ -57,7 +63,7 @@ public:
         uint8_t padding[2];
     };
     struct RenderPassVal {
-        VkRenderPass handle;
+        fvkmemory::resource_ptr<VulkanRenderPass> handle;
         uint32_t timestamp;
     };
     static_assert(0 == MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT % 8);
@@ -83,7 +89,7 @@ public:
         VkImageView depth; // 8 bytes
     };
     struct FboVal {
-        VkFramebuffer handle;
+        fvkmemory::resource_ptr<VulkanFramebuffer> handle;
         uint32_t timestamp;
     };
     static_assert(sizeof(VkRenderPass) == 8, "VkRenderPass has unexpected size.");
@@ -98,10 +104,13 @@ public:
     ~VulkanFboCache();
 
     // Retrieves or creates a VkFramebuffer handle.
-    VkFramebuffer getFramebuffer(FboKey const& config) noexcept;
+    fvkmemory::resource_ptr<VulkanFramebuffer> getFramebuffer(FboKey const& config,
+            fvkmemory::ResourceManager* resManager,
+            fvkmemory::resource_ptr<VulkanRenderTarget> renderTarget) noexcept;
 
     // Retrieves or creates a VkRenderPass handle.
-    VkRenderPass getRenderPass(RenderPassKey const& config) noexcept;
+    fvkmemory::resource_ptr<VulkanRenderPass> getRenderPass(
+        RenderPassKey const& config, fvkmemory::ResourceManager* resManager) noexcept;
 
     // Evicts old unused Vulkan objects. Call this once per frame.
     void gc() noexcept;

filament/backend/src/vulkan/VulkanHandles.cpp

@@ -565,7 +565,7 @@ void VulkanRenderTarget::transformViewportToPlatform(VkViewport* bounds) const {
     flipVertically(bounds, getExtent().height);
 }
 
-uint8_t VulkanRenderTarget::getColorTargetCount(const VulkanRenderPass& pass) const {
+uint8_t VulkanRenderTarget::getColorTargetCount(const VulkanRenderPassContext& pass) const {
     if (!mOffscreen) {
         return 1;
     }
@@ -715,4 +715,21 @@ VulkanRenderPrimitive::VulkanRenderPrimitive(PrimitiveType pt,
       vertexBuffer(vb),
       indexBuffer(ib) {}
 
+VulkanFramebuffer::VulkanFramebuffer(VkDevice device, VkFramebuffer framebuffer,
+        fvkmemory::resource_ptr<VulkanRenderTarget> renderTarget)
+        : mDevice(device),
+          mFramebuffer(framebuffer),
+          mRenderTarget(renderTarget) {}
+
+VulkanFramebuffer::~VulkanFramebuffer() {
+    vkDestroyFramebuffer(mDevice, mFramebuffer, VKALLOC);
+}
+
+VulkanRenderPass::VulkanRenderPass(VkDevice device, VkRenderPass renderPass)
+    : mDevice(device), mRenderPass(renderPass) {}
+
+VulkanRenderPass::~VulkanRenderPass() {
+    vkDestroyRenderPass(mDevice, mRenderPass, VKALLOC);
+}
+
 } // namespace filament::backend

filament/backend/src/vulkan/VulkanHandles.h

@@ -195,7 +195,7 @@ public:
     }
 
     // The current layout used by the descriptor set. This one will match the bindings, including
-    // external samplers data. 
+    // external samplers data.
     // This will not necessarilly be the same as `mLayout`.
     VkDescriptorSetLayout boundLayout = VK_NULL_HANDLE;
 
@@ -203,7 +203,7 @@ public:
 
     fvkutils::UniformBufferBitmask const& dynamicUboMask;
     uint8_t const uniqueDynamicUboCount;
-    
+
     // Flag to indicate if the current layout needs to be recreated or not.
     // This should only set to `true` when a external sampler image is bound to the descriptor set.
     bool isLayoutDirty = false;
@@ -419,7 +419,7 @@ struct VulkanRenderTarget : private HwRenderTarget, fvkmemory::Resource {
         return mInfo->fbkey.samples;
     }
 
-    uint8_t getColorTargetCount(VulkanRenderPass const& pass) const;
+    uint8_t getColorTargetCount(VulkanRenderPassContext const& pass) const;
 
     inline bool hasDepth() const { return mInfo->depthIndex != Auxiliary::UNDEFINED_INDEX; }
 
@@ -585,6 +585,39 @@ struct VulkanRenderPrimitive : public HwRenderPrimitive, fvkmemory::Resource {
     fvkmemory::resource_ptr<VulkanIndexBuffer> indexBuffer;
 };
 
+struct VulkanFramebuffer : public fvkmemory::Resource {
+    VulkanFramebuffer(VkDevice device,
+            VkFramebuffer framebuffer,
+            fvkmemory::resource_ptr<VulkanRenderTarget> renderTarget);
+    ~VulkanFramebuffer();
+
+    inline VkFramebuffer getVkFramebuffer() const noexcept {
+        return mFramebuffer;
+    }
+
+private:
+    VkDevice mDevice;
+    VkFramebuffer mFramebuffer;
+
+    // We need to keep a reference to the renderTarget because the key of the framebuffer in the
+    // cache has references to the image views that are derived from the textures of the render
+    // target.
+    fvkmemory::resource_ptr<VulkanRenderTarget> mRenderTarget;
+};
+
+struct VulkanRenderPass : public fvkmemory::Resource {
+    VulkanRenderPass(VkDevice device, VkRenderPass renderPass);
+    ~VulkanRenderPass();
+
+    inline VkRenderPass getVkRenderPass() const noexcept {
+        return mRenderPass;
+    }
+
+private:
+    VkDevice mDevice;
+    VkRenderPass mRenderPass;
+};
+
 } // namespace filament::backend
 
 #endif // TNT_FILAMENT_BACKEND_VULKANHANDLES_H

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -459,8 +459,10 @@ void VulkanPipelineCache::bindStencilState(StencilState const& stencilState) noe
     mPipelineRequirements.stencilState = stencilState;
 }
 
-void VulkanPipelineCache::bindRenderPass(VkRenderPass renderPass, int subpassIndex) noexcept {
-    mPipelineRequirements.renderPass = renderPass;
+void VulkanPipelineCache::bindRenderPass(
+        fvkmemory::resource_ptr<VulkanRenderPass> renderPass,
+        int subpassIndex) noexcept {
+    mPipelineRequirements.renderPass = renderPass->getVkRenderPass();
     mPipelineRequirements.subpassIndex = subpassIndex;
 }
 

filament/backend/src/vulkan/VulkanPipelineCache.h

@@ -123,7 +123,8 @@ public:
     void bindProgram(fvkmemory::resource_ptr<VulkanProgram> program) noexcept;
     void bindRasterState(RasterState const& rasterState) noexcept;
     void bindStencilState(StencilState const& stencilState) noexcept;
-    void bindRenderPass(VkRenderPass renderPass, int subpassIndex) noexcept;
+    void bindRenderPass(fvkmemory::resource_ptr<VulkanRenderPass> renderPass,
+            int subpassIndex) noexcept;
     void bindPrimitiveTopology(VkPrimitiveTopology topology) noexcept;
     void bindVertexArray(VkVertexInputAttributeDescription const* attribDesc,
             VkVertexInputBindingDescription const* bufferDesc, uint8_t count);

filament/backend/src/vulkan/memory/Resource.cpp

@@ -42,6 +42,8 @@ template ResourceType getTypeEnum<VulkanSync>() noexcept;
 template ResourceType getTypeEnum<VulkanMemoryMappedBuffer>() noexcept;
 template ResourceType getTypeEnum<VulkanSemaphore>() noexcept;
 template ResourceType getTypeEnum<VulkanStream>() noexcept;
+template ResourceType getTypeEnum<VulkanFramebuffer>() noexcept;
+template ResourceType getTypeEnum<VulkanRenderPass>() noexcept;
 
 template<typename D>
 ResourceType getTypeEnum() noexcept {
@@ -108,6 +110,12 @@ ResourceType getTypeEnum() noexcept {
     if constexpr (std::is_same_v<D, VulkanStream>) {
         return ResourceType::STREAM;
     }
+    if constexpr (std::is_same_v<D, VulkanFramebuffer>) {
+        return ResourceType::FRAMEBUFFER;
+    }
+    if constexpr (std::is_same_v<D, VulkanRenderPass>) {
+        return ResourceType::RENDER_PASS;
+    }
     return ResourceType::UNDEFINED_TYPE;
 }
 
@@ -155,6 +163,10 @@ std::string_view getTypeStr(ResourceType type) {
             return "Semaphore";
         case ResourceType::STREAM:
             return "VulkanStream";
+        case ResourceType::FRAMEBUFFER:
+            return "Framebuffer";
+        case ResourceType::RENDER_PASS:
+            return "RenderPass";
         case ResourceType::UNDEFINED_TYPE:
             return "";
     }

filament/backend/src/vulkan/memory/Resource.h

@@ -56,7 +56,9 @@ enum class ResourceType : uint8_t {
     MEMORY_MAPPED_BUFFER = 18,
     SEMAPHORE = 19,
     STREAM = 20,
-    UNDEFINED_TYPE = 21,    // Must be the last enum because we use it for iterating over the enums.
+    FRAMEBUFFER = 21,
+    RENDER_PASS = 22,
+    UNDEFINED_TYPE = 23,    // Must be the last enum because we use it for iterating over the enums.
 };
 
 template<typename D>

filament/backend/src/vulkan/memory/ResourceManager.cpp

@@ -126,6 +126,12 @@ void ResourceManager::destroyWithType(ResourceType type, HandleId id) {
         case ResourceType::STREAM:
             destruct<VulkanStream>(Handle<VulkanStream>(id));
             break;
+        case ResourceType::FRAMEBUFFER:
+            destruct<VulkanFramebuffer>(Handle<VulkanFramebuffer>(id));
+            break;
+        case ResourceType::RENDER_PASS:
+            destruct<VulkanRenderPass>(Handle<VulkanRenderPass>(id));
+            break;
         case ResourceType::UNDEFINED_TYPE:
             break;
     }

filament/backend/test/test_Autoresolve.cpp

@@ -18,6 +18,7 @@
 
 #include "Shader.h"
 #include "SharedShaders.h"
+#include "Skip.h"
 #include "TrianglePrimitive.h"
 
 #include <backend/PixelBufferDescriptor.h>
@@ -31,6 +32,9 @@ using namespace filament::backend;
 using namespace filament::math;
 
 TEST_F(BackendTest, AutoresolveDifferingSampleCounts) {
+    SKIP_IF(SkipEnvironment(OperatingSystem::CI, Backend::OPENGL), "see b/486954356");
+    SKIP_IF(SkipEnvironment(OperatingSystem::CI, Backend::VULKAN), "see b/486954356");
+
     auto& api = getDriverApi();
     constexpr int kRenderTargetSize = 512;
 

filament/include/filament/LightManager.h

@@ -372,7 +372,7 @@ public:
         } vsm;
 
         /**
-         * Light bulb radius used for soft shadows. Currently this is only used when DPCF or PCSS is
+         * Light bulb radius used for soft shadows. Currently, this is only used when DPCF or PCSS is
          * enabled. (2cm by default).
          */
         float shadowBulbRadius = 0.02f;

filament/include/filament/Options.h

@@ -735,7 +735,7 @@ struct VsmShadowOptions {
     bool highPrecision = false;
 
     /**
-     * VSM minimum variance scale, must be positive.
+     * @deprecated has no effect.
      */
     float minVarianceScale = 0.5f;
 

filament/src/LocalProgramCache.cpp

@@ -0,0 +1,265 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "LocalProgramCache.h"
+#include "MaterialParser.h"
+
+#include "details/Engine.h"
+#include "details/Material.h"
+
+#include <backend/DriverApiForward.h>
+
+namespace filament {
+
+using namespace backend;
+using namespace utils;
+
+LocalProgramCache::LocalProgramCache(LocalProgramCache const& other)
+        : mMaterial(other.mMaterial),
+          mCachedPrograms(other.mCachedPrograms.size()),
+          mSpecializationConstants((other.mMaterial != nullptr)
+                                           ? other.mMaterial->getEngine()
+                                                     .getMaterialCache()
+                                                     .getSpecializationConstantsInternPool()
+                                                     .acquire(other.mSpecializationConstants)
+                                           : SpecializationConstants()) {}
+
+LocalProgramCache& LocalProgramCache::operator=(LocalProgramCache const& other) {
+    assert_invariant(mMaterial == nullptr);
+    assert_invariant(mCachedPrograms.empty());
+    assert_invariant(mSpecializationConstants.empty());
+
+    mMaterial = other.mMaterial;
+    if (mMaterial != nullptr) {
+        mCachedPrograms = FixedCapacityVector<Handle<HwProgram>>(other.mCachedPrograms.size());
+        mSpecializationConstants = other.mMaterial->getEngine()
+                .getMaterialCache()
+                .getSpecializationConstantsInternPool()
+                .acquire(other.mSpecializationConstants);
+    }
+
+    return *this;
+}
+
+void LocalProgramCache::initializeForMaterial(FEngine& engine, FMaterial const& material,
+        utils::FixedCapacityVector<backend::Program::SpecializationConstant>
+                specializationConstants) {
+    assert_invariant(mMaterial == nullptr);
+    assert_invariant(mCachedPrograms.empty());
+    assert_invariant(mSpecializationConstants.empty());
+
+    mMaterial = &material;
+
+    mSpecializationConstants =
+            engine.getMaterialCache().getSpecializationConstantsInternPool().acquire(
+                    std::move(specializationConstants));
+
+    size_t cachedProgramsSize;
+    switch (material.getMaterialDomain()) {
+        case filament::MaterialDomain::SURFACE:
+            cachedProgramsSize = 1 << VARIANT_BITS;
+            break;
+        case filament::MaterialDomain::POST_PROCESS:
+            cachedProgramsSize = 1 << POST_PROCESS_VARIANT_BITS;
+            break;
+        case filament::MaterialDomain::COMPUTE:
+            cachedProgramsSize = 1;
+            break;
+    }
+    mCachedPrograms = FixedCapacityVector<Handle<HwProgram>>(cachedProgramsSize);
+
+    material.getDefinition().acquirePrograms(engine, mCachedPrograms.as_slice(),
+            material.getMaterialParser(), mSpecializationConstants, material.isDefaultMaterial());
+}
+
+void LocalProgramCache::initializeForMaterialInstance(FEngine& engine, FMaterial const& material) {
+    assert_invariant(mMaterial == nullptr);
+    assert_invariant(mCachedPrograms.empty());
+    assert_invariant(mSpecializationConstants.empty());
+
+    mMaterial = &material;
+    LocalProgramCache const& programs = material.getPrograms();
+
+    mSpecializationConstants =
+            engine.getMaterialCache().getSpecializationConstantsInternPool().acquire(
+                    programs.getSpecializationConstants());
+
+    mCachedPrograms =
+            FixedCapacityVector<Handle<HwProgram>>(material.getPrograms().mCachedPrograms.size());
+}
+
+Handle<HwProgram> LocalProgramCache::prepareProgramSlow(DriverApi& driver, Variant const variant,
+        CompilerPriorityQueue const priorityQueue) const noexcept {
+    assert_invariant(mMaterial != nullptr);
+
+    FEngine& engine = mMaterial->getEngine();
+    if (mMaterial->isSharedVariant(variant)) {
+        FMaterial const* defaultMaterial = engine.getDefaultMaterial();
+        assert_invariant(defaultMaterial);
+        LocalProgramCache const& defaultPrograms = defaultMaterial->getPrograms();
+        Handle<HwProgram> program = defaultPrograms.mCachedPrograms[variant.key];
+        if (program) {
+            return mCachedPrograms[variant.key] = program;
+        }
+        return mCachedPrograms[variant.key] =
+                defaultPrograms.prepareProgram(driver, variant, priorityQueue);
+    }
+    return mCachedPrograms[variant.key] = mMaterial->getDefinition().prepareProgram(engine, driver,
+                   mMaterial->getMaterialParser(), getProgramSpecialization(variant), priorityQueue);
+}
+
+ProgramSpecialization LocalProgramCache::getProgramSpecialization(Variant variant) const noexcept {
+    assert_invariant(mMaterial != nullptr);
+
+    return ProgramSpecialization {
+        .materialCrc32 = mMaterial->getMaterialParser().getCrc32(),
+        .variant = variant,
+        .specializationConstants = mSpecializationConstants,
+    };
+}
+
+void LocalProgramCache::terminate(FEngine& engine) {
+    assert_invariant(mMaterial != nullptr);
+
+    mMaterial->getDefinition().releasePrograms(engine, mCachedPrograms.as_slice(),
+            mMaterial->getMaterialParser(), mSpecializationConstants,
+            mMaterial->isDefaultMaterial());
+    engine.getMaterialCache().releaseMaterial(engine, mMaterial->getDefinition());
+    engine.getMaterialCache().getSpecializationConstantsInternPool().release(
+            mSpecializationConstants);
+}
+
+void LocalProgramCache::clear(FEngine& engine) {
+    assert_invariant(mMaterial != nullptr);
+
+    mMaterial->getDefinition().releasePrograms(engine, mCachedPrograms.as_slice(),
+            mMaterial->getMaterialParser(), mSpecializationConstants,
+            mMaterial->isDefaultMaterial());
+}
+
+Variant LocalProgramCache::filterVariantForGetProgram(Variant variant) const noexcept {
+    if (UTILS_UNLIKELY(mMaterial->getEngine().features.material.enable_fog_as_postprocess)) {
+        // if the fog as post-process feature is enabled, we need to proceed "as-if" the material
+        // didn't have the FOG variant bit.
+        if (mMaterial->getMaterialDomain() == MaterialDomain::SURFACE) {
+            BlendingMode const blendingMode = mMaterial->getBlendingMode();
+            bool const hasScreenSpaceRefraction =
+                    mMaterial->getRefractionMode() == RefractionMode::SCREEN_SPACE;
+            bool const isBlendingCommand = !hasScreenSpaceRefraction &&
+                    (blendingMode != BlendingMode::OPAQUE && blendingMode != BlendingMode::MASKED);
+            if (!isBlendingCommand) {
+                variant.setFog(false);
+            }
+        }
+    }
+    return variant;
+}
+
+Program::SpecializationConstant LocalProgramCache::getConstantImpl(uint32_t id) const noexcept {
+    return mSpecializationConstants[id];
+}
+
+Program::SpecializationConstant LocalProgramCache::getConstantImpl(
+        std::string_view name) const noexcept {
+    assert_invariant(mMaterial != nullptr);
+
+    MaterialDefinition const& definition = mMaterial->getDefinition();
+    auto it = definition.specializationConstantsNameToIndex.find(name);
+    if (it != definition.specializationConstantsNameToIndex.cend()) {
+        return getConstantImpl(it->second + CONFIG_MAX_RESERVED_SPEC_CONSTANTS);
+    }
+
+    std::string name_cstring(name);
+    PANIC_PRECONDITION("No such constant exists: %s", name_cstring.c_str());
+    return {};
+}
+
+void LocalProgramCache::setConstants(
+        std::initializer_list<std::pair<uint32_t, Program::SpecializationConstant>>
+                constants) noexcept {
+    assert_invariant(mMaterial != nullptr);
+
+    auto newSpecializationConstants =
+            FixedCapacityVector<Program::SpecializationConstant>(mSpecializationConstants);
+
+    bool hasChanged = false;
+    for (const auto& [id, value] : constants) {
+        if (newSpecializationConstants[id] != value) {
+            newSpecializationConstants[id] = value;
+            hasChanged = true;
+        }
+    }
+
+    if (hasChanged) {
+        setConstantsImpl(std::move(newSpecializationConstants));
+    }
+}
+
+void LocalProgramCache::setConstants(
+        std::initializer_list<std::pair<std::string_view, Program::SpecializationConstant>>
+                constants) noexcept {
+    assert_invariant(mMaterial != nullptr);
+
+    auto newSpecializationConstants =
+            FixedCapacityVector<Program::SpecializationConstant>(mSpecializationConstants);
+
+    bool hasChanged = false;
+    for (const auto& [name, value] : constants) {
+        MaterialDefinition const& definition = mMaterial->getDefinition();
+        auto it = definition.specializationConstantsNameToIndex.find(name);
+        if (it != definition.specializationConstantsNameToIndex.cend()) {
+            uint32_t id = it->second + CONFIG_MAX_RESERVED_SPEC_CONSTANTS;
+            if (newSpecializationConstants[id] != value) {
+                newSpecializationConstants[id] = value;
+                hasChanged = true;
+            }
+        }
+    }
+
+    if (hasChanged) {
+        setConstantsImpl(std::move(newSpecializationConstants));
+    }
+}
+
+void LocalProgramCache::setConstantsImpl(
+        FixedCapacityVector<Program::SpecializationConstant> constants) noexcept {
+    FEngine& engine = mMaterial->getEngine();
+
+    auto& internPool = engine.getMaterialCache().getSpecializationConstantsInternPool();
+    MaterialParser const& materialParser = mMaterial->getMaterialParser();
+    MaterialDefinition const& definition = mMaterial->getDefinition();
+    const bool isDefaultMaterial = mMaterial->isDefaultMaterial();
+
+    // Release old resources...
+    definition.releasePrograms(engine, mCachedPrograms.as_slice(), materialParser,
+            mSpecializationConstants, isDefaultMaterial);
+    internPool.release(mSpecializationConstants);
+
+    // Then acquire new ones.
+    mSpecializationConstants = internPool.acquire(std::move(constants));
+    definition.acquirePrograms(engine, mCachedPrograms.as_slice(), materialParser,
+            mSpecializationConstants, isDefaultMaterial);
+}
+
+template int32_t LocalProgramCache::getConstant<int32_t>(uint32_t id) const noexcept;
+template float LocalProgramCache::getConstant<float>(uint32_t id) const noexcept;
+template bool LocalProgramCache::getConstant<bool>(uint32_t id) const noexcept;
+
+template int32_t LocalProgramCache::getConstant<int32_t>(std::string_view name) const noexcept;
+template float LocalProgramCache::getConstant<float>(std::string_view name) const noexcept;
+template bool LocalProgramCache::getConstant<bool>(std::string_view name) const noexcept;
+
+} // namespace filament

filament/src/LocalProgramCache.h

@@ -0,0 +1,144 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_FILAMENT_LOCALPROGRAMCACHE_H
+#define TNT_FILAMENT_LOCALPROGRAMCACHE_H
+
+#include "MaterialDefinition.h"
+
+#include <backend/Handle.h>
+
+#include <private/filament/Variant.h>
+
+#include <backend/DriverEnums.h>
+#include <backend/DriverApiForward.h>
+#include <backend/Program.h>
+
+#include <utility>
+
+namespace filament {
+
+class FMaterial;
+
+// L0 cache for material programs. Manages recompiling them on-demand; owned by Material and
+// MaterialInstance.
+class LocalProgramCache {
+    template<typename T>
+    using is_supported_constant_parameter_t =
+            std::enable_if_t<std::is_same_v<int32_t, T> || std::is_same_v<float, T> ||
+                             std::is_same_v<bool, T>>;
+
+public:
+    using Programs = utils::Slice<const backend::Handle<backend::HwProgram>>;
+    using SpecializationConstants = utils::Slice<const backend::Program::SpecializationConstant>;
+
+    LocalProgramCache() = default;
+    LocalProgramCache(LocalProgramCache const& other);
+
+    LocalProgramCache& operator=(LocalProgramCache const& other);
+
+    // Initialize for use in a Material.
+    void initializeForMaterial(FEngine& engine, FMaterial const& material,
+            utils::FixedCapacityVector<backend::Program::SpecializationConstant>
+                    specializationConstants);
+
+    // Initialize for use in a MaterialInstance. Copies the set of spec constants currently in use
+    // from its Material.
+    void initializeForMaterialInstance(FEngine& engine, FMaterial const& material);
+
+    bool isInitialized() const noexcept { return mMaterial != nullptr; }
+
+    // prepareProgram creates the program for the material's given variant at the backend level.
+    // Must be called outside of backend render pass.
+    // Must be called before getProgram() below.
+    backend::Handle<backend::HwProgram> prepareProgram(backend::DriverApi& driver,
+            Variant const variant,
+            backend::CompilerPriorityQueue const priorityQueue) const noexcept {
+        backend::Handle<backend::HwProgram> program = mCachedPrograms[variant.key];
+        if (UTILS_LIKELY(program)) {
+            return program;
+        }
+        return prepareProgramSlow(driver, variant, priorityQueue);
+    }
+
+    // getProgram returns the backend program for the material's given variant.
+    // Must be called after prepareProgram().
+    [[nodiscard]]
+    backend::Handle<backend::HwProgram> getProgram(Variant variant) const noexcept {
+        variant = filterVariantForGetProgram(variant);
+        backend::Handle<backend::HwProgram> program = mCachedPrograms[variant.key];
+        assert_invariant(program);
+        return program;
+    }
+
+    SpecializationConstants getSpecializationConstants() const noexcept {
+        return mSpecializationConstants;
+    }
+
+    Programs getPrograms() const noexcept { return mCachedPrograms.as_slice(); }
+
+    // Free all engine resources associated with this instance.
+    void terminate(FEngine& engine);
+
+    // Clear all cached programs. Used primarily by matdbg to "sever" a Material's connection to the
+    // global material cache.
+    void clear(FEngine& engine);
+
+    // Get constant by ID.
+    template<typename T, typename = is_supported_constant_parameter_t<T>>
+    T getConstant(uint32_t id) const noexcept {
+        return std::get<T>(getConstantImpl(id));
+    }
+
+    // Get constant by name.
+    template<typename T, typename = is_supported_constant_parameter_t<T>>
+    T getConstant(std::string_view name) const noexcept {
+        return std::get<T>(getConstantImpl(name));
+    }
+
+    // Set constants by ID.
+    void setConstants(
+            std::initializer_list<std::pair<uint32_t, backend::Program::SpecializationConstant>>
+                    constants) noexcept;
+
+    // Set constants by name.
+    void setConstants(std::initializer_list<
+            std::pair<std::string_view, backend::Program::SpecializationConstant>>
+                    constants) noexcept;
+
+private:
+    backend::Handle<backend::HwProgram> prepareProgramSlow(backend::DriverApi& driver,
+            Variant const variant,
+            backend::CompilerPriorityQueue const priorityQueue) const noexcept;
+
+    ProgramSpecialization getProgramSpecialization(Variant variant) const noexcept;
+
+    Variant filterVariantForGetProgram(Variant const variant) const noexcept;
+
+    void setConstantsImpl(utils::FixedCapacityVector<backend::Program::SpecializationConstant>
+                    constants) noexcept;
+
+    backend::Program::SpecializationConstant getConstantImpl(uint32_t id) const noexcept;
+    backend::Program::SpecializationConstant getConstantImpl(std::string_view name) const noexcept;
+
+    FMaterial const* mMaterial = nullptr;
+    mutable utils::FixedCapacityVector<backend::Handle<backend::HwProgram>> mCachedPrograms;
+    SpecializationConstants mSpecializationConstants;
+};
+
+} // namespace filament
+
+#endif  // TNT_FILAMENT_LOCALPROGRAMCACHE_H

filament/src/MaterialCache.cpp

@@ -39,12 +39,25 @@ bool MaterialCache::MaterialKey::operator==(MaterialKey const& rhs) const noexce
     return parser == rhs.parser;
 }
 
+MaterialCache::MaterialCache()
+        : mDefinitions("MaterialCache::mDefinitions", 0),
+          mPrograms("MaterialCache::mPrograms", 0) {}
+
 MaterialCache::~MaterialCache() {
     assert_invariant(mDefinitions.empty());
     assert_invariant(mPrograms.empty());
     assert_invariant(mSpecializationConstantsInternPool.empty());
 }
 
+void MaterialCache::terminate(FEngine& engine) {
+    mPrograms.clearLruCache([&engine](backend::Handle<backend::HwProgram>& program) {
+        engine.getDriverApi().destroyProgram(program);
+    });
+    mDefinitions.clearLruCache([&engine](MaterialDefinition& definition) {
+        definition.terminate(engine);
+    });
+}
+
 MaterialDefinition* UTILS_NULLABLE MaterialCache::acquireMaterial(FEngine& engine,
         const void* UTILS_NONNULL data, size_t size) noexcept {
     std::unique_ptr<MaterialParser> parser = MaterialDefinition::createParser(engine.getBackend(),

filament/src/MaterialCache.h

@@ -56,8 +56,13 @@ public:
     using ProgramCache =
             utils::RefCountedMap<ProgramSpecialization, backend::Handle<backend::HwProgram>>;
 
+    MaterialCache();
     ~MaterialCache();
 
+    // All reference-counted resources should be freed by the time MaterialCache is destructed, but
+    // the LRU cache needs to be explicitly freed in addition.
+    void terminate(FEngine& engine);
+
     SpecializationConstantInternPool& getSpecializationConstantsInternPool() {
         return mSpecializationConstantsInternPool;
     }

filament/src/MaterialDefinition.cpp

@@ -271,8 +271,8 @@ std::unique_ptr<MaterialDefinition> MaterialDefinition::create(FEngine& engine,
 
 void MaterialDefinition::terminate(FEngine& engine) {
     DriverApi& driver = engine.getDriverApi();
-    perViewDescriptorSetLayout.terminate(engine.getDescriptorSetLayoutFactory(), driver);
-    perViewDescriptorSetLayoutVsm.terminate(engine.getDescriptorSetLayoutFactory(), driver);
+    perViewDescriptorSetLayoutPcf.terminate(engine.getDescriptorSetLayoutFactory(), driver);
+    perViewDescriptorSetLayoutS2d.terminate(engine.getDescriptorSetLayoutFactory(), driver);
     descriptorSetLayout.terminate(engine.getDescriptorSetLayoutFactory(), driver);
 }
 
@@ -607,23 +607,23 @@ void MaterialDefinition::processDescriptorSets(FEngine& engine) {
             refractionMode == RefractionMode::SCREEN_SPACE;
     bool const hasFog = !(variantFilterMask & UserVariantFilterMask(UserVariantFilterBit::FOG));
 
-    this->perViewDescriptorSetLayoutDescription = descriptor_sets::getPerViewDescriptorSetLayout(
+    this->perViewDescriptorSetLayoutPcfDescription = descriptor_sets::getPerViewDescriptorSetLayout(
             materialDomain, isLit, isSSR, hasFog, false);
 
-    this->perViewDescriptorSetLayoutVsmDescription = descriptor_sets::getPerViewDescriptorSetLayout(
+    this->perViewDescriptorSetLayoutS2dDescription = descriptor_sets::getPerViewDescriptorSetLayout(
             materialDomain, isLit, isSSR, hasFog, true);
 
     // set the labels
     this->descriptorSetLayoutDescription.label = CString{ name }.append("_perMat");
-    this->perViewDescriptorSetLayoutDescription.label = CString{ name }.append("_perView");
-    this->perViewDescriptorSetLayoutVsmDescription.label = CString{ name }.append("_perViewVsm");
+    this->perViewDescriptorSetLayoutPcfDescription.label = CString{ name }.append("_perView");
+    this->perViewDescriptorSetLayoutS2dDescription.label = CString{ name }.append("_perViewVsm");
 
     // get the PER_RENDERABLE and PER_VIEW descriptor binding info
     for (auto&& [bindingPoint, dsl] : {
             std::pair{ DescriptorSetBindingPoints::PER_RENDERABLE,
                     descriptor_sets::getPerRenderableLayout() },
             std::pair{ DescriptorSetBindingPoints::PER_VIEW,
-                    this->perViewDescriptorSetLayoutDescription }}) {
+                    this->perViewDescriptorSetLayoutPcfDescription }}) {
         Program::DescriptorBindingsInfo& descriptors = programDescriptorBindings[+bindingPoint];
         descriptors.reserve(dsl.descriptors.size());
         for (auto const& entry: dsl.descriptors) {
@@ -636,17 +636,17 @@ void MaterialDefinition::processDescriptorSets(FEngine& engine) {
             descriptorSetLayoutFactory, driver,
             this->descriptorSetLayoutDescription };
 
-    this->perViewDescriptorSetLayout = {
+    this->perViewDescriptorSetLayoutPcf = {
             descriptorSetLayoutFactory, driver,
-            this->perViewDescriptorSetLayoutDescription };
+            this->perViewDescriptorSetLayoutPcfDescription };
 
-    this->perViewDescriptorSetLayoutVsm = {
+    this->perViewDescriptorSetLayoutS2d = {
             descriptorSetLayoutFactory, driver,
-            this->perViewDescriptorSetLayoutVsmDescription };
+            this->perViewDescriptorSetLayoutS2dDescription };
 }
 
 backend::DescriptorSetLayout const& MaterialDefinition::getPerViewDescriptorSetLayoutDescription(
-        Variant const variant, bool const useVsmDescriptorSetLayout) const noexcept {
+        Variant const variant, bool const useS2dDescriptorSetLayout) const noexcept {
     if (materialDomain == MaterialDomain::SURFACE) {
         if (Variant::isValidDepthVariant(variant)) {
             // Use the layout description used to create the per view depth variant layout.
@@ -657,10 +657,10 @@ backend::DescriptorSetLayout const& MaterialDefinition::getPerViewDescriptorSetL
             return descriptor_sets::getSsrVariantLayout();
         }
     }
-    if (useVsmDescriptorSetLayout) {
-        return perViewDescriptorSetLayoutVsmDescription;
+    if (useS2dDescriptorSetLayout) {
+        return perViewDescriptorSetLayoutS2dDescription;
     }
-    return perViewDescriptorSetLayoutDescription;
+    return perViewDescriptorSetLayoutPcfDescription;
 }
 
 Handle<HwProgram> MaterialDefinition::compileProgram(
@@ -689,7 +689,7 @@ Handle<HwProgram> MaterialDefinition::compileProgram(
     pb.descriptorLayout(+DescriptorSetBindingPoints::PER_VIEW,
             getPerViewDescriptorSetLayoutDescription(
                     specialization.variant,
-                    Variant::isVSMVariant(specialization.variant)));
+                    Variant::isShadowSampler2DVariant(specialization.variant)));
     pb.descriptorLayout(+DescriptorSetBindingPoints::PER_RENDERABLE,
             descriptor_sets::getPerRenderableLayout());
     pb.descriptorLayout(

filament/src/MaterialDefinition.h

@@ -94,17 +94,17 @@ struct MaterialDefinition {
             backend::ShaderModel const sm, bool isStereoSupported) const noexcept;
 
     backend::DescriptorSetLayout const& getPerViewDescriptorSetLayoutDescription(
-            Variant const variant, bool useVsmDescriptorSetLayout) const noexcept;
+            Variant const variant, bool useS2dDescriptorSetLayout) const noexcept;
 
     // Keep track of the definitions of the descriptor set layouts, as these
     // may be used by some backends in parallel compilation of programs.
-    backend::DescriptorSetLayout perViewDescriptorSetLayoutDescription;
-    backend::DescriptorSetLayout perViewDescriptorSetLayoutVsmDescription;
+    backend::DescriptorSetLayout perViewDescriptorSetLayoutPcfDescription;
+    backend::DescriptorSetLayout perViewDescriptorSetLayoutS2dDescription;
     backend::DescriptorSetLayout descriptorSetLayoutDescription;
 
     // try to order by frequency of use
-    filament::DescriptorSetLayout perViewDescriptorSetLayout;
-    filament::DescriptorSetLayout perViewDescriptorSetLayoutVsm;
+    filament::DescriptorSetLayout perViewDescriptorSetLayoutPcf;
+    filament::DescriptorSetLayout perViewDescriptorSetLayoutS2d;
     filament::DescriptorSetLayout descriptorSetLayout;
     backend::Program::DescriptorSetInfo programDescriptorBindings;
 

filament/src/MaterialInstanceManager.cpp

@@ -19,90 +19,61 @@
 
 #include "details/Engine.h"
 #include "details/Material.h"
-#include "details/MaterialInstance.h"
 
-#include <utils/debug.h>
-
-#include <iterator>
-#include <utility>
-
-#include <stdint.h>
+#include <cstdint>
 
 namespace filament {
 
-using Record = MaterialInstanceManager::Record;
+using namespace utils;
 
-std::pair<FMaterialInstance*, int32_t> Record::getInstance() {
-    if (mAvailable < mInstances.size()) {
-        auto index = mAvailable++;
-        return { mInstances[index], index };
-    }
-    assert_invariant(mAvailable == mInstances.size());
-    auto& name = mMaterial->getName();
-    FMaterialInstance* inst = mMaterial->createInstance(name.c_str_safe());
-    mInstances.push_back(inst);
-    return { inst, mAvailable++ };
-}
+MaterialInstanceManager::MaterialInstanceManager() noexcept = default;
 
-FMaterialInstance* Record::getInstance(int32_t const fixedInstanceindex) const {
-    assert_invariant(fixedInstanceindex >= 0 &&  fixedInstanceindex < int32_t(mInstances.size()));
-    return mInstances[fixedInstanceindex];
-}
-
-// Defined in cpp to avoid inlining
-Record::Record(Record const& rhs) noexcept = default;
-Record& Record::operator=(Record const& rhs) noexcept = default;
-Record::Record(Record&& rhs) noexcept = default;
-Record& Record::operator=(Record&& rhs) noexcept = default;
-
-void Record::terminate(FEngine& engine) {
-    std::for_each(mInstances.begin(), mInstances.end(),
-            [&engine](auto instance) { engine.destroy(instance); });
-}
-
-MaterialInstanceManager::MaterialInstanceManager() noexcept {}
-
-MaterialInstanceManager::MaterialInstanceManager(
-        MaterialInstanceManager const& rhs) noexcept = default;
 MaterialInstanceManager::MaterialInstanceManager(MaterialInstanceManager&& rhs) noexcept = default;
-MaterialInstanceManager& MaterialInstanceManager::operator=(
-        MaterialInstanceManager const& rhs) noexcept = default;
-MaterialInstanceManager& MaterialInstanceManager::operator=(
-        MaterialInstanceManager&& rhs) noexcept = default;
-
+MaterialInstanceManager& MaterialInstanceManager::operator=(MaterialInstanceManager&& rhs) noexcept = default;
 MaterialInstanceManager::~MaterialInstanceManager() = default;
 
 void MaterialInstanceManager::terminate(FEngine& engine) {
-    std::for_each(mMaterials.begin(), mMaterials.end(), [&engine](auto& record) {
-        record.terminate(engine);
-    });
+    for (auto const& [key, instance] : mMaterialInstances) {
+        engine.destroy(instance);
+    }
+    mMaterialInstances.clear();
+
+    for (auto const& [material, pool] : mAnonymousMaterialInstances) {
+        for (auto instance : pool.instances) {
+            engine.destroy(instance);
+        }
+    }
+    mAnonymousMaterialInstances.clear();
 }
 
-Record& MaterialInstanceManager::getRecord(FMaterial const* const ma) const {
-    auto itr = std::find_if(mMaterials.begin(), mMaterials.end(), [ma](auto& record) {
-        return ma == record.mMaterial;
-    });
-    if (itr == mMaterials.end()) {
-        mMaterials.emplace_back(ma);
-        itr = std::prev(mMaterials.end());
+void MaterialInstanceManager::reset() {
+    for (auto& [material, pool] : mAnonymousMaterialInstances) {
+        pool.highWaterMark = 0;
     }
-    return *itr;
+}
+
+FMaterialInstance* MaterialInstanceManager::getMaterialInstance(FMaterial const* ma, uint32_t tag) const {
+    Key const key{ma, tag};
+    auto it = mMaterialInstances.find(key);
+    if (it != mMaterialInstances.end()) {
+        return it->second;
+    }
+
+    FMaterialInstance* const instance = ma->createInstance(ma->getName().c_str_safe());
+    mMaterialInstances.emplace(key, instance);
+    return instance;
 }
 
 FMaterialInstance* MaterialInstanceManager::getMaterialInstance(FMaterial const* ma) const {
-    auto [inst, index] = getRecord(ma).getInstance();
-    return inst;
-}
+    AnonymousPool& pool = mAnonymousMaterialInstances[ma];
+    if (pool.highWaterMark < pool.instances.size()) {
+        return pool.instances[pool.highWaterMark++];
+    }
 
-FMaterialInstance* MaterialInstanceManager::getMaterialInstance(FMaterial const* ma,
-        int32_t const fixedIndex) const {
-    return getRecord(ma).getInstance(fixedIndex);
+    FMaterialInstance* const instance = ma->createInstance(ma->getName().c_str_safe());
+    pool.instances.push_back(instance);
+    pool.highWaterMark++;
+    return instance;
 }
 
-std::pair<FMaterialInstance*, int32_t> MaterialInstanceManager::getFixedMaterialInstance(
-        FMaterial const* ma) {
-    return getRecord(ma).getInstance();
-}
-
-
 } // namespace filament

filament/src/MaterialInstanceManager.h

@@ -16,10 +16,13 @@
 
 #pragma once
 
-#include <utils/bitset.h>
-
+#include <cstddef>
+#include <cstdint>
+#include <unordered_map>
 #include <vector>
 
+#include <utils/Hash.h>
+
 namespace filament {
 
 class FMaterial;
@@ -30,37 +33,10 @@ class FEngine;
 // re-use instances across frames.
 class MaterialInstanceManager {
 public:
-    class Record {
-    public:
-        Record(FMaterial const* material)
-            : mMaterial(material),
-              mAvailable(0) {}
-        ~Record() = default;
-
-        Record(Record const& rhs) noexcept;
-        Record& operator=(Record const& rhs) noexcept;
-        Record(Record&& rhs) noexcept;
-        Record& operator=(Record&& rhs) noexcept;
-
-        void terminate(FEngine& engine);
-        void reset() { mAvailable = 0; }
-        std::pair<FMaterialInstance*, int32_t> getInstance();
-        FMaterialInstance* getInstance(int32_t fixedInstanceindex) const;
-
-    private:
-        FMaterial const* mMaterial = nullptr;
-        std::vector<FMaterialInstance*> mInstances;
-        uint32_t mAvailable;
-
-        friend class MaterialInstanceManager;
-    };
-
-    constexpr static int32_t INVALID_FIXED_INDEX = -1;
-
     MaterialInstanceManager() noexcept;
-    MaterialInstanceManager(MaterialInstanceManager const& rhs) noexcept;
+    MaterialInstanceManager(MaterialInstanceManager const& rhs) = delete;
     MaterialInstanceManager(MaterialInstanceManager&& rhs) noexcept;
-    MaterialInstanceManager& operator=(MaterialInstanceManager const& rhs) noexcept;
+    MaterialInstanceManager& operator=(MaterialInstanceManager const& rhs) = delete;
     MaterialInstanceManager& operator=(MaterialInstanceManager&& rhs) noexcept;
 
     ~MaterialInstanceManager();
@@ -71,40 +47,60 @@ public:
      */
     void terminate(FEngine& engine);
 
-    /*
-     * This returns a material instance given a material. The implementation will try to find an
-     * available instance in the cache. If one is not found, then a new instance will be created and
-     * added to the cache.
+    /**
+     * Resets the anonymous material instances cache.
+     */
+    void reset();
+
+    /**
+     * This returns a material instance given a material and a tag.
+     *
+     * If the material instance doesn't exist in the cache, it is created and cached.
+     *
+     * @param ma    FMaterial to get a MaterialInstance for
+     * @param tag   A unique tag identifying the MaterialInstance
+     * @return      A FMaterialInstance pointer
+     */
+    FMaterialInstance* getMaterialInstance(FMaterial const* ma, uint32_t tag) const;
+
+    /**
+     * This returns a material instance given a material from a cache.
+     *
+     * If the material instance doesn't exist in the cache, it is created and cached.
+     *
+     * It is permissible to call the method several times, in which case a different MaterialInstance will be returned.
+     * It is guaranteed to be different from MaterialInstances returned with a tag.
+     *
+     * @param ma    FMaterial to get a MaterialInstance for
+     * @return      A FMaterialInstance pointer
      */
     FMaterialInstance* getMaterialInstance(FMaterial const* ma) const;
 
-    /*
-     * This returns a material instance given a material and an index. The `fixedIndex` should be
-     * a value returned by getiFixedMaterialInstance.
-     */
-    FMaterialInstance* getMaterialInstance(FMaterial const* ma, int32_t const fixedIndex) const;
-
-    /*
-     * This returns a material instance and an index given a material. This is needed for the
-     * case when two framegraph passes need to refer to the same material instance.
-     * The returned index can be used with `getFixedMaterialInstance` to get a specific instance
-     * of a material (and not a random entry in the record cache).
-     */
-    std::pair<FMaterialInstance*, int32_t> getFixedMaterialInstance(FMaterial const* ma);
-
-
-    /*
-     * Marks all of the material instances as unused. Typically, you'd call this at the beginning of
-     * a frame.
-     */
-    void reset() {
-        std::for_each(mMaterials.begin(), mMaterials.end(), [](auto& record) { record.reset(); });
-    }
-
 private:
-    Record& getRecord(FMaterial const* material) const;
+    struct Key {
+        FMaterial const* material;
+        uint32_t tag;
+        bool operator==(Key const& rhs) const noexcept {
+            return material == rhs.material && tag == rhs.tag;
+        }
+    };
 
-    mutable std::vector<Record> mMaterials;
+    struct Hasher {
+        std::size_t operator()(Key const& key) const noexcept {
+            std::size_t seed = 0;
+            utils::hash::combine(seed, key.material);
+            utils::hash::combine(seed, key.tag);
+            return seed;
+        }
+    };
+
+    struct AnonymousPool {
+        std::vector<FMaterialInstance*> instances;
+        uint32_t highWaterMark = 0;
+    };
+
+    mutable std::unordered_map<Key, FMaterialInstance*, Hasher> mMaterialInstances;
+    mutable std::unordered_map<FMaterial const*, AnonymousPool> mAnonymousMaterialInstances;
 };
 
 } // namespace filament

filament/src/PostProcessManager.cpp

@@ -225,7 +225,6 @@ const PostProcessManager::JitterSequence<32>
 
 PostProcessManager::PostProcessManager(FEngine& engine) noexcept
         : mEngine(engine),
-          mFixedMaterialInstanceIndex {},
           mWorkaroundSplitEasu(false),
           mWorkaroundAllowReadOnlyAncillaryFeedbackLoop(false) {
     // don't use Engine here, it's not fully initialized yet
@@ -455,7 +454,6 @@ Handle<HwTexture> PostProcessManager::getZeroTextureArray() const {
 
 void PostProcessManager::resetForRender() {
     mMaterialInstanceManager.reset();
-    mFixedMaterialInstanceIndex = {};
 }
 
 void PostProcessManager::unbindAllDescriptorSets(DriverApi& driver) noexcept {
@@ -802,7 +800,7 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::ssr(FrameGraph& fg,
 
                 // use our special SSR variant, it can only be applied to object that have
                 // the SCREEN_SPACE ReflectionMode.
-                passBuilder.variant(Variant{ Variant::SPECIAL_SSR });
+                passBuilder.variant(Variant{ Variant::SPECIAL_SSR_VARIANT });
 
                 // generate all our drawing commands, except blended objects.
                 passBuilder.commandTypeFlags(RenderPass::CommandTypeFlags::SCREEN_SPACE_REFLECTIONS);
@@ -1000,13 +998,10 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::screenSpaceAmbientOcclusion(
                 auto& material = getPostProcessMaterial(materialName);
 
                 FMaterial* ma = material.getMaterial(mEngine, driver);
-                {
-                    FMaterial::SpecializationConstantsBuilder maConstants =
-                            ma->getSpecializationConstantsBuilder();
-                    maConstants.set("useVisibilityBitmasks", options.gtao.useVisibilityBitmasks);
-                    maConstants.set("linearThickness", options.gtao.linearThickness);
-                    ma->setSpecializationConstants(std::move(maConstants));
-                }
+                ma->getPrograms().setConstants({
+                    { "useVisibilityBitmasks", options.gtao.useVisibilityBitmasks },
+                    { "linearThickness", options.gtao.linearThickness },
+                });
 
                 ma = material.getMaterial(mEngine, driver);
                 FMaterialInstance* const mi = getMaterialInstance(ma);
@@ -2552,11 +2547,7 @@ void PostProcessManager::colorGradingSubpass(DriverApi& driver,
     auto const& material = getPostProcessMaterial("colorGradingAsSubpass");
     FMaterial const* const ma = material.getMaterial(mEngine, driver, variant);
     // the UBO has been set and committed in colorGradingPrepareSubpass()
-    int32_t const fixedIndex = colorGradingConfig.translucent
-                                       ? mFixedMaterialInstanceIndex.colorGradingTranslucent
-                                       : mFixedMaterialInstanceIndex.colorGradingOpaque;
-
-    FMaterialInstance const* mi = mMaterialInstanceManager.getMaterialInstance(ma, fixedIndex);
+    FMaterialInstance const* mi = mMaterialInstanceManager.getMaterialInstance(ma, colorGradingConfig.translucent);
     mi->use(driver);
     auto const pipeline = getPipelineState(ma, variant);
     driver.nextSubpass();
@@ -2567,8 +2558,7 @@ void PostProcessManager::colorGradingSubpass(DriverApi& driver,
 void PostProcessManager::customResolvePrepareSubpass(DriverApi& driver, CustomResolveOp const op) noexcept {
     auto const& material = getPostProcessMaterial("customResolveAsSubpass");
     auto const ma = material.getMaterial(mEngine, driver, PostProcessVariant::OPAQUE);
-    auto [mi, fixedIndex] = mMaterialInstanceManager.getFixedMaterialInstance(ma);
-    mFixedMaterialInstanceIndex.customResolve = fixedIndex;
+    auto* const mi = mMaterialInstanceManager.getMaterialInstance(ma, 0);
     mi->setParameter("direction", op == CustomResolveOp::COMPRESS ? 1.0f : -1.0f),
     mi->commit(driver, getUboManager());
 }
@@ -2580,8 +2570,7 @@ void PostProcessManager::customResolveSubpass(DriverApi& driver) noexcept {
     auto const& material = getPostProcessMaterial("customResolveAsSubpass");
     FMaterial const* const ma = material.getMaterial(mEngine, driver);
     // the UBO has been set and committed in customResolvePrepareSubpass()
-    FMaterialInstance const* mi = mMaterialInstanceManager.getMaterialInstance(ma,
-            mFixedMaterialInstanceIndex.customResolve);
+    FMaterialInstance const* mi = mMaterialInstanceManager.getMaterialInstance(ma, 0);
     mi->use(driver);
 
     auto const pipeline = getPipelineState(ma);
@@ -2620,9 +2609,8 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::customResolveUncompressPass(
 void PostProcessManager::clearAncillaryBuffersPrepare(DriverApi& driver,
         Variant::type_t variant) noexcept {
     auto const& material = getPostProcessMaterial("clearDepth");
-    auto ma = material.getMaterial(mEngine, driver, variant);
-    auto [mi, fixedIndex] = mMaterialInstanceManager.getFixedMaterialInstance(ma);
-    mFixedMaterialInstanceIndex.clearDepth = fixedIndex;
+    auto const ma = material.getMaterial(mEngine, driver, variant);
+    auto const mi = mMaterialInstanceManager.getMaterialInstance(ma, 0);
     mi->commit(driver, getUboManager());
 }
 
@@ -2640,8 +2628,7 @@ void PostProcessManager::clearAncillaryBuffers(DriverApi& driver,
     FMaterial const* const ma = material.getMaterial(mEngine, driver, variant);
 
     // the UBO has been set and committed in clearAncillaryBuffersPrepare()
-    FMaterialInstance const* const mi = mMaterialInstanceManager.getMaterialInstance(ma,
-            mFixedMaterialInstanceIndex.clearDepth);
+    FMaterialInstance const* const mi = mMaterialInstanceManager.getMaterialInstance(ma, 0);
     mi->use(driver);
 
     auto pipeline = getPipelineState(ma, variant);
@@ -2927,20 +2914,18 @@ void PostProcessManager::configureTemporalAntiAliasingMaterial(backend::DriverAp
         TemporalAntiAliasingOptions const& taaOptions) noexcept {
 
     FMaterial* const ma = getPostProcessMaterial("taa").getMaterial(mEngine, driver);
-    FMaterial::SpecializationConstantsBuilder maConstants = ma->getSpecializationConstantsBuilder();
-
-    maConstants.set("upscaling", taaOptions.upscaling > 1.0f);
-    maConstants.set("historyReprojection", taaOptions.historyReprojection);
-    maConstants.set("filterHistory", taaOptions.filterHistory);
-    maConstants.set("filterInput", taaOptions.filterInput);
-    maConstants.set("useYCoCg", taaOptions.useYCoCg);
-    maConstants.set("hdr", taaOptions.hdr);
-    maConstants.set("preventFlickering", taaOptions.preventFlickering);
-    maConstants.set("boxType", int32_t(taaOptions.boxType));
-    maConstants.set("boxClipping", int32_t(taaOptions.boxClipping));
-    maConstants.set("varianceGamma", taaOptions.varianceGamma);
-
-    ma->setSpecializationConstants(std::move(maConstants));
+    ma->getPrograms().setConstants({
+        { "upscaling", taaOptions.upscaling > 1.0f },
+        { "historyReprojection", taaOptions.historyReprojection },
+        { "filterHistory", taaOptions.filterHistory },
+        { "filterInput", taaOptions.filterInput },
+        { "useYCoCg", taaOptions.useYCoCg },
+        { "hdr", taaOptions.hdr },
+        { "preventFlickering", taaOptions.preventFlickering },
+        { "boxType", int32_t(taaOptions.boxType) },
+        { "boxClipping", int32_t(taaOptions.boxClipping) },
+        { "varianceGamma", taaOptions.varianceGamma },
+    });
 }
 
 FMaterialInstance* PostProcessManager::configureColorGradingMaterial(backend::DriverApi& driver,
@@ -2948,23 +2933,16 @@ FMaterialInstance* PostProcessManager::configureColorGradingMaterial(backend::Dr
         ColorGradingConfig const& colorGradingConfig, VignetteOptions const& vignetteOptions,
         uint32_t const width, uint32_t const height) noexcept {
     FMaterial* ma = material.getMaterial(mEngine, driver);
-    {
-        FMaterial::SpecializationConstantsBuilder maConstants =
-                ma->getSpecializationConstantsBuilder();
-        maConstants.set("isOneDimensional", colorGrading->isOneDimensional());
-        maConstants.set("isLDR", colorGrading->isLDR());
-        ma->setSpecializationConstants(std::move(maConstants));
-    }
+    ma->getPrograms().setConstants({
+        { "isOneDimensional", colorGrading->isOneDimensional() },
+        { "isLDR", colorGrading->isLDR() },
+    });
 
     PostProcessVariant const variant = colorGradingConfig.translucent
                                                ? PostProcessVariant::TRANSLUCENT
                                                : PostProcessVariant::OPAQUE;
     ma = material.getMaterial(mEngine, driver, variant);
-    FMaterialInstance* mi = nullptr;
-    int32_t& fixedIndex = colorGradingConfig.translucent
-                                  ? mFixedMaterialInstanceIndex.colorGradingTranslucent
-                                  : mFixedMaterialInstanceIndex.colorGradingOpaque;
-    std::tie(mi, fixedIndex) = mMaterialInstanceManager.getFixedMaterialInstance(ma);
+    FMaterialInstance* mi = mMaterialInstanceManager.getMaterialInstance(ma, colorGradingConfig.translucent);
 
     const SamplerParams params = SamplerParams{
             .filterMag = SamplerMagFilter::LINEAR,
@@ -3823,15 +3801,13 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::vsmMipmapPass(FrameGraph& fg
                 auto const& inDesc = resources.getDescriptor(data.in);
                 auto width = inDesc.width;
                 assert_invariant(width == inDesc.height);
-                int const dim = width >> (level + 1);
+                uint32_t const dim = std::max(1u, width >> (level + 1));
 
                 auto& material = getPostProcessMaterial("vsmMipmap");
                 FMaterial const* const ma = material.getMaterial(mEngine, driver);
 
-                // When generating shadow map mip levels, we want to preserve the 1 texel border.
-                // (note clearing never respects the scissor in Filament)
                 auto const pipeline = getPipelineState(ma);
-                backend::Viewport const scissor = { 1u, 1u, dim - 2u, dim - 2u };
+                backend::Viewport const scissor = { 0, 0, dim, dim };
 
                 FMaterialInstance* const mi = getMaterialInstance(ma);
                 mi->setParameter("color", in, SamplerParams{

filament/src/PostProcessManager.h

@@ -486,13 +486,6 @@ private:
 
     MaterialInstanceManager mMaterialInstanceManager;
 
-    struct {
-        int32_t colorGradingTranslucent = MaterialInstanceManager::INVALID_FIXED_INDEX;
-        int32_t colorGradingOpaque = MaterialInstanceManager::INVALID_FIXED_INDEX;
-        int32_t customResolve = MaterialInstanceManager::INVALID_FIXED_INDEX;
-        int32_t clearDepth = MaterialInstanceManager::INVALID_FIXED_INDEX;
-    } mFixedMaterialInstanceIndex;
-
     backend::Handle<backend::HwTexture> mStarburstTexture;
 
     std::uniform_real_distribution<float> mUniformDistribution{0.0f, 1.0f};

filament/src/RenderPass.cpp

@@ -568,7 +568,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(CommandTypeFlags extraFlag
     if constexpr (isDepthPass) {
         cmd.info.materialVariant = variant;
         cmd.info.rasterState = {};
-        cmd.info.rasterState.colorWrite = Variant::isPickingVariant(variant) || Variant::isVSMVariant(variant);
+        cmd.info.rasterState.colorWrite = Variant::isPickingVariant(variant) || Variant::isDepthMomentsVariant(variant);
         cmd.info.rasterState.depthWrite = true;
         cmd.info.rasterState.depthFunc = RasterState::DepthFunc::GE;
         cmd.info.rasterState.alphaToCoverage = false;
@@ -616,7 +616,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(CommandTypeFlags extraFlag
         bool const hasSkinningOrMorphing = hasSkinning || hasMorphing;
 
         // if we are already an SSR variant, the SRE bit is already set
-        static_assert(Variant::SPECIAL_SSR & Variant::SRE);
+        static_assert(Variant::SPECIAL_SSR_VARIANT & Variant::SRE);
         Variant renderableVariant{ variant };
 
         // we can't have SSR and shadowing together by construction

filament/src/RenderableManager.cpp

@@ -54,7 +54,7 @@ RenderableManager::getInstance(Entity const e) const noexcept {
 }
 
 void RenderableManager::destroy(Entity const e) noexcept {
-    return downcast(this)->destroy(e);
+    return downcast(this)->clientDestroy(e);
 }
 
 void RenderableManager::setAxisAlignedBoundingBox(Instance const instance, const Box& aabb) {

filament/src/ShadowMap.cpp

@@ -62,6 +62,8 @@ ShadowMap::ShadowMap(FEngine& engine) noexcept
         : mPerShadowMapUniforms(engine),
           mShadowType(ShadowType::DIRECTIONAL),
           mHasVisibleShadows(false),
+          mVsm(false),
+          mReservedBit(false),
           mFace(0) {
     Entity entities[2];
     engine.getEntityManager().create(2, entities);
@@ -85,7 +87,7 @@ void ShadowMap::terminate(FEngine& engine) {
 
 ShadowMap::~ShadowMap() = default;
 
-void ShadowMap::initialize(size_t const lightIndex, ShadowType const shadowType,
+void ShadowMap::initialize(size_t const lightIndex, ShadowType const shadowType, bool const vsm,
         uint16_t const shadowIndex, uint8_t const face,
         LightManager::ShadowOptions const* options) {
     mLightIndex = lightIndex;
@@ -93,6 +95,7 @@ void ShadowMap::initialize(size_t const lightIndex, ShadowType const shadowType,
     mOptions = options;
     mShadowType = shadowType;
     mFace = face;
+    mVsm = vsm;
 }
 
 mat4f ShadowMap::getDirectionalLightViewMatrix(float3 direction, float3 up,
@@ -213,12 +216,14 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
      * Final shadow map transform
      */
 
-    // Final shadow transform (focused warped light-space)
+    // Final shadow transform (focused warped light-space), world space to clip space
     const mat4f S = F * (W * LMpMv);
 
     // Computes St the transform to use in the shader to access the shadow map texture
     // i.e. it transforms a world-space vertex to a texture coordinate in the shadowmap
     const auto [Mt, Mn] = getTextureCoordsMapping(shadowMapInfo, getViewport());
+
+    // world space to texture atlas space
     const mat4f St = highPrecisionMultiply(Mt, S);
 
     ShaderParameters shaderParameters;
@@ -226,14 +231,12 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
 
     // note: in texelSizeWorldSpace() below, we can use Mb * Mt * F * W because
     // L * Mp * Mv is a rigid transform for directional lights, and doesn't matter.
-    // if Wp[3][1] is 0, then LISPSM was cancelled.
+    // if Wp[3][1] is 0, then LiSPSM was canceled.
     if (useLispsm && Wp[3][1] != 0.0f) {
-        shaderParameters.texelSizeAtOneMeterWs =
-                texelSizeWorldSpace(Wp, mat4f(Mt * F), shadowMapInfo.shadowDimension);
+        shaderParameters.texelSizeAtOneMeterWs = texelSizeWorldSpace(S, shadowMapInfo.shadowDimension);
     } else {
         // We know we're using an ortho projection
-        shaderParameters.texelSizeAtOneMeterWs =
-                texelSizeWorldSpace(St.upperLeft(), shadowMapInfo.shadowDimension);
+        shaderParameters.texelSizeAtOneMeterWs = texelSizeWorldSpace(S.upperLeft(), shadowMapInfo.shadowDimension);
     }
     if (!shadowMapInfo.vsm) {
         shaderParameters.lightSpace = St;
@@ -1117,90 +1120,72 @@ bool ShadowMap::intersectSegmentWithPlanarQuad(float3& UTILS_RESTRICT p,
     return hit;
 }
 
-float ShadowMap::texelSizeWorldSpace(const mat3f& worldToShadowTexture,
-        uint16_t shadowDimension) noexcept {
+float2 ShadowMap::texelSizeWorldSpace(const mat3f& clipFromWorld, uint16_t shadowDimension) noexcept {
     // The Jacobian of the transformation from texture-to-world is the matrix itself for
-    // orthographic projections. We just need to inverse worldToShadowTexture,
+    // orthographic projections. We just need to inverse shadowMapFromWorld,
     // which is guaranteed to be orthographic.
     // The two first columns give us how a texel maps in world-space.
-    const float ures = 1.0f / float(shadowDimension);
-    const float vres = 1.0f / float(shadowDimension);
-    const mat3f shadowTextureToWorld(inverse(worldToShadowTexture));
-    const float3 Jx = shadowTextureToWorld[0];
-    const float3 Jy = shadowTextureToWorld[1];
-    const float s = std::max(length(Jx) * ures, length(Jy) * vres);
+    float const oneTexel = 2.0f / float(shadowDimension);
+    mat3f const worldFromClip(inverse(clipFromWorld));
+    float3 const Jx = worldFromClip[0];
+    float3 const Jy = worldFromClip[1];
+    float2 const s = float2{ length(Jx), length(Jy) } * oneTexel;
     return s;
 }
 
-float ShadowMap::texelSizeWorldSpace(const mat4f& Wp, const mat4f& MbMtF,
-        uint16_t shadowDimension) noexcept {
-    // Here we compute the Jacobian of inverse(MbMtF * Wp).
-    // The expression below has been computed with Mathematica. However, it's not very hard,
-    // albeit error-prone, to do it by hand because MbMtF is a linear transform.
-    // So we really only need to calculate the Jacobian of inverse(Wp) at inverse(MbMtF).
-    //
-    // Because we're only interested in the length of the columns of the Jacobian, we can use
-    // Mb * Mt * F * Wp instead of the full expression Mb * Mt * F * Wp * Wv * L * Mp * Mv,
-    // because Wv * L * Mp * Mv is a rigid transform, which doesn't affect the length of
-    // the Jacobian's column vectors.
+/**
+ * Calculates the Jacobian matrix J = ∂(u,v,d)/∂(x,y,z) for a 4x4 perspective projection.
+ *
+ * Given a view-space point P = [x, y, z, 1]^T and a projection matrix M,
+ * the projected homogeneous coordinates are [X, Y, Z, W]^T = M * P.
+ * The resulting NDC coordinates are u = X/W, v = Y/W, and depth d = Z/W.
+ *
+ * To find the Jacobian on the CPU, we apply the quotient rule to each component:
+ * ∂(X/W) / ∂xi = ( (∂X/∂xi) * W - X * (∂W/∂xi) ) / W^2
+ *
+ * In matrix form, this can be expressed as:
+ * J = (1/W) * [ M_sub - (1/W) * (T ⊗ w_grad) ]
+ *
+ * Where:
+ * - W: The homogeneous w-component after projection (usually -z for standard mats).
+ * - M_sub: The top-left 3x3 submatrix of M.
+ * - T: The column vector [X, Y, Z]^T (pre-perspective divide).
+ * - w_grad: The row vector [m30, m31, m32] (the first three elements of M's last row).
+ * - ⊗: The outer product, resulting in a 3x3 matrix.
+ *
+ * This Jacobian describes the local "stretch" of the projection. For LiSPSM or
+ * shadow mapping, the inverse Jacobian J^-1 provides the world-space footprint
+ * of a shadow texel, which is essential for calculating an accurate,
+ * non-constant depth bias to eliminate shadow acne.
+ *
+ * @param M The 4x4 projection matrix.
+ * @param p The 3D point in view-space where the Jacobian is evaluated.
+ * @return A 3x3 matrix representing the partial derivatives of (u,v,d) w.r.t (x,y,z).
+ */
+static mat3f jacobian(mat4f const& M, float3 const& p) noexcept {
+    float4 const T = M * p;
+    mat3f const M_sub = M.upperLeft();
+    float3 const w_grad = { M[0].w, M[1].w, M[2].w };
+    mat3f const t_cross_w{
+        w_grad.x * T.xyz,
+        w_grad.y * T.xyz,
+        w_grad.z * T.xyz
+    };
+    return (M_sub - t_cross_w / T.w) / T.w;
+}
 
+float2 ShadowMap::texelSizeWorldSpace(mat4f const& S, uint16_t const shadowDimension) noexcept {
     // The Jacobian is not constant, so we evaluate it in the center of the shadow-map texture.
     // It might be better to do this computation in the vertex shader.
-    float3 const p = { 0.5f, 0.5f, 0.0f };
-
-    const float ures = 1.0f / float(shadowDimension);
-    const float vres = 1.0f / float(shadowDimension);
-    const float dres = 1.0f / 65536.0f;
-
-    constexpr bool JACOBIAN_ESTIMATE = false;
-    if constexpr (JACOBIAN_ESTIMATE) {
-        // This estimates the Jacobian -- this is a lot heavier. This is mostly for reference
-        // and testing.
-        const mat4f Si(inverse(MbMtF * Wp));
-        const float3 p0 = mat4f::project(Si, p);
-        const float3 p1 = mat4f::project(Si, p + float3{ 1, 0, 0 } * ures);
-        const float3 p2 = mat4f::project(Si, p + float3{ 0, 1, 0 } * vres);
-        const float3 p3 = mat4f::project(Si, p + float3{ 0, 0, 1 } * dres);
-        const float3 Jx = p1 - p0;
-        const float3 Jy = p2 - p0;
-        const float3 UTILS_UNUSED Jz = p3 - p0;
-        const float s = std::max(length(Jx), length(Jy));
-        return s;
-    }
-
-    const float n = Wp[0][0];
-    const float A = Wp[1][1];
-    const float B = Wp[3][1];
-    const float sx = MbMtF[0][0];
-    const float sy = MbMtF[1][1];
-    const float sz = MbMtF[2][2];
-    const float ox = MbMtF[3][0];
-    const float oy = MbMtF[3][1];
-    const float oz = MbMtF[3][2];
-
-    const float X = p.x - ox;
-    const float Y = p.y - oy;
-    const float Z = p.z - oz;
-
-    const float dz = A * sy - Y;
-    const float nsxsz = n * sx * sz;
-    const float j = -(B * sy) / (nsxsz * dz * dz);
-    const mat3f J(mat3f::row_major_init{
-            j * dz * sz,    j * X * sz,     0.0f,
-            0.0f,           j * nsxsz,      0.0f,
-            0.0f,           j * Z * sx,     j * dz * sx
-    });
-
-    float3 const Jx = J[0] * ures;
-    float3 const Jy = J[1] * vres;
-    UTILS_UNUSED float3 const Jz = J[2] * dres;
-    const float s = std::max(length(Jx), length(Jy));
+    float3 const p = { 0.0f, 0.0f, 0.0f }; // clip-space
+    float const oneTexel = 2.0f / float(shadowDimension);
+    mat3f const J = jacobian(inverse(S), p);
+    float2 const s = float2{ length(J[0]), length(J[1]) } * oneTexel;
     return s;
 }
 
-template<typename Casters, typename Receivers>
-void ShadowMap::visitScene(const FScene& scene, uint32_t const visibleLayers,
-        Casters casters, Receivers receivers) noexcept {
+template<typename Visitor>
+void ShadowMap::visitScene(const FScene& scene, uint32_t const visibleLayers, Visitor visitor) noexcept {
     FILAMENT_TRACING_CALL(FILAMENT_TRACING_CATEGORY_FILAMENT);
 
     using State = FRenderableManager::Visibility;
@@ -1213,14 +1198,11 @@ void ShadowMap::visitScene(const FScene& scene, uint32_t const visibleLayers,
     size_t const c = soa.size();
     for (size_t i = 0; i < c; i++) {
         if (layers[i] & visibleLayers) {
-            const Aabb aabb{ worldAABBCenter[i] - worldAABBExtent[i],
-                             worldAABBCenter[i] + worldAABBExtent[i] };
-            if (visibility[i].castShadows) {
-                casters(aabb, visibleMasks[i]);
-            }
-            if (visibility[i].receiveShadows) {
-                receivers(aabb, visibleMasks[i]);
-            }
+            Aabb const aabb{
+                worldAABBCenter[i] - worldAABBExtent[i],
+                worldAABBCenter[i] + worldAABBExtent[i]
+            };
+            visitor(aabb, visibleMasks[i], visibility[i]);
         }
     }
 }
@@ -1239,13 +1221,15 @@ ShadowMap::SceneInfo::SceneInfo(
     wsShadowCastersVolume = {};
     wsShadowReceiversVolume = {};
     visitScene(scene, visibleLayers,
-            [&](Aabb caster, Culler::result_type) {
-                wsShadowCastersVolume.min = min(wsShadowCastersVolume.min, caster.min);
-                wsShadowCastersVolume.max = max(wsShadowCastersVolume.max, caster.max);
-            },
-            [&](Aabb receiver, Culler::result_type) {
-                wsShadowReceiversVolume.min = min(wsShadowReceiversVolume.min, receiver.min);
-                wsShadowReceiversVolume.max = max(wsShadowReceiversVolume.max, receiver.max);
+            [this](Aabb const& aabb, Culler::result_type, FRenderableManager::Visibility const visibility) {
+                if (visibility.castShadows) {
+                    wsShadowCastersVolume.min = min(wsShadowCastersVolume.min, aabb.min);
+                    wsShadowCastersVolume.max = max(wsShadowCastersVolume.max, aabb.max);
+                }
+                if (visibility.receiveShadows) {
+                    wsShadowReceiversVolume.min = min(wsShadowReceiversVolume.min, aabb.min);
+                    wsShadowReceiversVolume.max = max(wsShadowReceiversVolume.max, aabb.max);
+                }
             }
     );
 }
@@ -1259,18 +1243,20 @@ void ShadowMap::updateSceneInfoDirectional(mat4f const& Mv, FScene const& scene,
     sceneInfo.lsCastersNearFar = { std::numeric_limits<float>::lowest(), std::numeric_limits<float>::max() };
     sceneInfo.lsReceiversNearFar = { std::numeric_limits<float>::lowest(), std::numeric_limits<float>::max() };
     visitScene(scene, sceneInfo.visibleLayers,
-            [&](Aabb caster, Culler::result_type) {
-                auto r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, caster);
-                sceneInfo.lsCastersNearFar.x = max(sceneInfo.lsCastersNearFar.x, r.max.z);
-                sceneInfo.lsCastersNearFar.y = min(sceneInfo.lsCastersNearFar.y, r.min.z);
-            },
-            [&](Aabb receiver, Culler::result_type const vis) {
-                // account only for objects that are visible by the camera
-                auto mask = 1u << VISIBLE_RENDERABLE_BIT;
-                if ((vis & mask) == mask) {
-                    auto r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, receiver);
-                    sceneInfo.lsReceiversNearFar.x = max(sceneInfo.lsReceiversNearFar.x, r.max.z);
-                    sceneInfo.lsReceiversNearFar.y = min(sceneInfo.lsReceiversNearFar.y, r.min.z);
+            [&](Aabb const& aabb, Culler::result_type const vis, FRenderableManager::Visibility const visibility) {
+                if (visibility.castShadows) {
+                    auto const r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, aabb);
+                    sceneInfo.lsCastersNearFar.x = max(sceneInfo.lsCastersNearFar.x, r.max.z);
+                    sceneInfo.lsCastersNearFar.y = min(sceneInfo.lsCastersNearFar.y, r.min.z);
+                }
+                if (visibility.castShadows) {
+                    // account only for objects that are visible by the camera
+                    constexpr auto mask = 1u << VISIBLE_RENDERABLE_BIT;
+                    if ((vis & mask) == mask) {
+                        auto r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, aabb);
+                        sceneInfo.lsReceiversNearFar.x = max(sceneInfo.lsReceiversNearFar.x, r.max.z);
+                        sceneInfo.lsReceiversNearFar.y = min(sceneInfo.lsReceiversNearFar.y, r.min.z);
+                    }
                 }
             }
     );
@@ -1285,15 +1271,15 @@ void ShadowMap::updateSceneInfoSpot(mat4f const& Mv, FScene const& scene,
     sceneInfo.lsCastersNearFar = { std::numeric_limits<float>::lowest(), std::numeric_limits<float>::max() };
     // account only for objects that are visible by both the camera and the light
     visitScene(scene, sceneInfo.visibleLayers,
-            [&](Aabb caster, Culler::result_type const vis) {
-                auto mask = VISIBLE_DYN_SHADOW_RENDERABLE;
-                if ((vis & mask) == mask) {
-                    auto r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, caster);
-                    sceneInfo.lsCastersNearFar.x = std::max(sceneInfo.lsCastersNearFar.x, r.max.z);  // near
-                    sceneInfo.lsCastersNearFar.y = std::min(sceneInfo.lsCastersNearFar.y, r.min.z);  // far
+            [&](Aabb const& aabb, Culler::result_type const vis, FRenderableManager::Visibility const visibility) {
+                if (visibility.castShadows) {
+                    constexpr auto mask = VISIBLE_DYN_SHADOW_RENDERABLE;
+                    if ((vis & mask) == mask) {
+                        auto const r = Aabb::transform(Mv.upperLeft(), Mv[3].xyz, aabb);
+                        sceneInfo.lsCastersNearFar.x = std::max(sceneInfo.lsCastersNearFar.x, r.max.z);  // near
+                        sceneInfo.lsCastersNearFar.y = std::min(sceneInfo.lsCastersNearFar.y, r.min.z);  // far
+                    }
                 }
-            },
-            [&](Aabb receiver, Culler::result_type) {
             }
     );
 }
@@ -1303,47 +1289,56 @@ void ShadowMap::setAllocation(uint8_t const layer, backend::Viewport viewport) n
 }
 
 backend::Viewport ShadowMap::getViewport() const noexcept {
-    // We set a viewport with a 1-texel border for when we index outside the texture.
-    // This happens only for directional lights when "focus shadow casters" is used,
-    // or when shadowFar is smaller than the camera far.
-    // For spot- and point-lights we also use a 1-texel border, so that bilinear filtering
-    // can work properly if the shadowmap is in an atlas (and we can't rely on h/w clamp).
+    // This is used for calculating the light space; in particular, if the shadowmap is in a 2D atlas, this
+    // returns the valid area of the shadowmap. By definition all values must be integer.
+
+    // We set a viewport with a 1-texel border for when we index outside the texture, which should only happen for
+    // directional lights when "focus shadow casters" is used, or when shadowFar is smaller than the camera far.
+    // For directional lights, the border is filed with "fully lit".
+    //
+    // For point-lights, we also use a 1-texel border, but for a different reason; the border is filled with data
+    // so that bilinear (PCF) filtering works properly.
+    //
+    // Spot-light a treated like point lights (the border will be filled with "fully-lit" anyways)
+
     const uint32_t dim = mOptions->mapSize;
     const uint16_t border = 1u;
     return { mOffset.x + border, mOffset.y + border, dim - 2u * border, dim - 2u * border };
 }
 
 backend::Viewport ShadowMap::getScissor() const noexcept {
-    // We set a viewport with a 1-texel border for when we index outside the texture.
-    // This happens only for directional lights when "focus shadow casters" is used,
-    // or when shadowFar is smaller than the camera far.
-    // For spot- and point-lights we also use a 1-texel border, so that bilinear filtering
-    // can work properly if the shadowmap is in an atlas (and we can't rely on h/w clamp), so we
-    // don't scissor the border, so it gets filled with correct neighboring texels.
+    // This is used while rendering the shadowmap.
+
     const uint32_t dim = mOptions->mapSize;
     const uint16_t border = 1u;
-    switch (mShadowType) {
-        case ShadowType::DIRECTIONAL:
-            return { mOffset.x + border, mOffset.y + border, dim - 2u * border, dim - 2u * border };
+    switch (mShadowType) { // NOLINT(*-multiway-paths-covered)
+        case ShadowType::DIRECTIONAL: {
+            // Don't render anything into the border; it's already filled with "fully lit".
+            return {mOffset.x + border, mOffset.y + border, dim - 2u * border, dim - 2u * border};
+        }
         case ShadowType::SPOT:
-        case ShadowType::POINT:
-            return { mOffset.x, mOffset.y, dim, dim };
+        case ShadowType::POINT: {
+            // Render into the border (which will get the adjacent faces texels)
+            return {mOffset.x, mOffset.y, dim, dim};
+        }
     }
+    return {};
 }
 
 float4 ShadowMap::getClampToEdgeCoords(ShadowMapInfo const& shadowMapInfo) const noexcept {
-    float border; // shadowmap border in texels
-    switch (mShadowType) {
+    // This is used to clamp the texture coordinates when sampling the shadowmap
+
+    float border = 0; // shadowmap border in texels
+    switch (mShadowType) { // NOLINT(*-multiway-paths-covered)
         case ShadowType::DIRECTIONAL:
-            // For directional lights, we need to allow the sampling to reach the border, it
-            // happens when "focus shadow casters" is used for instance.
+            // For directional lights, we need to allow the sampling to reach the center of border texels,
+            // but no further, so we don't read into the adjacent texture in the 2D atlas (taking bilinear filtering
+            // into account).
             border = 0.5f;
             break;
         case ShadowType::SPOT:
         case ShadowType::POINT:
-            // For spot and point light, this is equal to the viewport. i.e. the valid
-            // texels are inside the viewport (w/ 1-texel border), the border will be used
-            // for bilinear filtering.
+            // For point-light, the border is only needed for bilinear filtering (of the other faces)
             border = 1.0f;
             break;
     }
@@ -1372,8 +1367,8 @@ void ShadowMap::prepareCamera(Transaction const& transaction,
 }
 
 void ShadowMap::prepareViewport(Transaction const& transaction,
-        backend::Viewport const& viewport) noexcept {
-    ShadowMapDescriptorSet::prepareViewport(transaction, viewport);
+        backend::Viewport const& physicalViewport, backend::Viewport const& logicalViewport) noexcept {
+    ShadowMapDescriptorSet::prepareViewport(transaction, physicalViewport, logicalViewport);
 }
 
 void ShadowMap::prepareTime(Transaction const& transaction,
@@ -1387,8 +1382,8 @@ void ShadowMap::prepareMaterialGlobals(Transaction const& transaction,
 }
 
 void ShadowMap::prepareShadowMapping(Transaction const& transaction,
-        bool const highPrecision) noexcept {
-    ShadowMapDescriptorSet::prepareShadowMapping(transaction, highPrecision);
+        float const vsmExponent, float const vsmMaxMoment) noexcept {
+    ShadowMapDescriptorSet::prepareShadowMapping(transaction, vsmExponent, vsmMaxMoment);
 }
 
 ShadowMapDescriptorSet::Transaction ShadowMap::open(DriverApi& driver) noexcept {

filament/src/ShadowMap.h

@@ -128,14 +128,14 @@ public:
     static math::mat4f getPointLightViewMatrix(backend::TextureCubemapFace face,
             math::float3 position) noexcept;
 
-    void initialize(size_t lightIndex, ShadowType shadowType, uint16_t shadowIndex, uint8_t face,
+    void initialize(size_t lightIndex, ShadowType shadowType, bool vsm, uint16_t shadowIndex, uint8_t face,
             LightManager::ShadowOptions const* options);
 
     struct ShaderParameters {
         math::mat4f lightSpace{};
         math::float4 lightFromWorldZ{};
         math::float4 scissorNormalized{};
-        float texelSizeAtOneMeterWs{};
+        math::float2 texelSizeAtOneMeterWs{};
     };
 
     // Call once per frame if the light, scene (or visible layers) or camera changes.
@@ -173,7 +173,10 @@ public:
     static void updateSceneInfoSpot(const math::mat4f& Mv, FScene const& scene,
             SceneInfo& sceneInfo);
 
-    LightManager::ShadowOptions const* getShadowOptions() const noexcept { return mOptions; }
+    LightManager::ShadowOptions const& getShadowOptions() const noexcept {
+            assert_invariant(mOptions);
+            return *mOptions;
+    }
     size_t getLightIndex() const { return mLightIndex; }
     uint16_t getShadowIndex() const { return mShadowIndex; }
     void setAllocation(uint8_t layer, backend::Viewport viewport) noexcept;
@@ -193,13 +196,13 @@ public:
     static void prepareCamera(Transaction const& transaction,
             FEngine const& engine, const CameraInfo& cameraInfo) noexcept;
     static void prepareViewport(Transaction const& transaction,
-            backend::Viewport const& viewport) noexcept;
+            backend::Viewport const& physicalViewport, backend::Viewport const& logicalViewport) noexcept;
     static void prepareTime(Transaction const& transaction,
             FEngine const& engine, math::float4 const& userTime) noexcept;
     static void prepareMaterialGlobals(Transaction const& transaction,
             std::array<math::float4, 4> const& materialGlobals) noexcept;
     static void prepareShadowMapping(Transaction const& transaction,
-            bool highPrecision) noexcept;
+            float vsmExponent, float vsmMaxMoment) noexcept;
     static ShadowMapDescriptorSet::Transaction open(backend::DriverApi& driver) noexcept;
     void commit(Transaction& transaction, FEngine& engine, backend::DriverApi& driver) const noexcept;
     void bind(backend::DriverApi& driver) const noexcept;
@@ -273,9 +276,8 @@ private:
     static inline math::float4 computeBoundingSphere(
             math::float3 const* vertices, size_t count) noexcept;
 
-    template<typename Casters, typename Receivers>
-    static void visitScene(FScene const& scene, uint32_t visibleLayers,
-            Casters casters, Receivers receivers) noexcept;
+    template<typename Visitor>
+    static void visitScene(FScene const& scene, uint32_t visibleLayers, Visitor visitor) noexcept;
 
     static inline Aabb compute2DBounds(const math::mat4f& lightView,
             math::float3 const* wsVertices, size_t count) noexcept;
@@ -319,11 +321,8 @@ private:
 
     math::float4 getClampToEdgeCoords(ShadowMapInfo const& shadowMapInfo) const noexcept;
 
-    static float texelSizeWorldSpace(const math::mat3f& worldToShadowTexture,
-            uint16_t shadowDimension) noexcept;
-
-    static float texelSizeWorldSpace(const math::mat4f& W, const math::mat4f& MbMtF,
-            uint16_t shadowDimension) noexcept;
+    static math::float2 texelSizeWorldSpace(const math::mat3f& clipFromWorld, uint16_t shadowDimension) noexcept;
+    static math::float2 texelSizeWorldSpace(const math::mat4f& clipFromWorld, uint16_t shadowDimension) noexcept;
 
     static constexpr Segment sBoxSegments[12] = {
             { 0, 1 }, { 1, 3 }, { 3, 2 }, { 2, 0 },
@@ -352,9 +351,11 @@ private:
     uint8_t mLayer = 0;         // our layer in the shadowMap texture       // 1
     ShadowType mShadowType  : 2;                                            // :2
     bool mHasVisibleShadows : 1;                                            // :1
+    bool mVsm               : 1;                                            // :1
+    UTILS_UNUSED bool mReservedBit : 1;                                     // :1
     uint8_t mFace           : 3;                                            // :3
     math::ushort2 mOffset{};                                                // 4
-    UTILS_UNUSED uint8_t reserved[4];                                       // 4
+    UTILS_UNUSED uint8_t reserved[4] = {};                                  // 4
 };
 
 } // namespace filament

filament/src/ShadowMapManager.cpp

@@ -151,12 +151,14 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::update(
 
     mDirectionalShadowMapCount = builder.mDirectionalShadowMapCount;
     mSpotShadowMapCount = builder.mSpotShadowMapCount;
+    const bool vsm = view.hasVSM();
 
     for (auto const& entry : builder.mShadowMaps) {
         auto& shadowMap = getShadowMap(entry.shadowIndex);
         shadowMap.initialize(
                 entry.lightIndex,
                 entry.shadowType,
+                vsm,
                 entry.shadowIndex,
                 entry.face,
                 entry.options);
@@ -230,15 +232,12 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
         FView& view, CameraInfo const& mainCameraInfo,
         float4 const& userTime) noexcept {
 
-    const float moment2 = std::numeric_limits<half>::max();
-    const float moment1 = std::sqrt(moment2);
-    const float4 vsmClearColor{ moment1, moment2, -moment1, moment2 };
-
     FScene* scene = view.getScene();
     assert_invariant(scene);
 
     // make a copy here, because it's a very small structure
-    const TextureAtlasRequirements textureRequirements = mTextureAtlasRequirements;
+    VsmShadowOptions const& vsmShadowOptions = view.getVsmShadowOptions();
+    TextureAtlasRequirements const textureRequirements = mTextureAtlasRequirements;
     assert_invariant(textureRequirements.layers <= CONFIG_MAX_SHADOW_LAYERS);
 
     // -------------------------------------------------------------------------------------------
@@ -258,8 +257,6 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
         utils::FixedCapacityVector<ShadowPass> passList;
     };
 
-    VsmShadowOptions const& vsmShadowOptions = view.getVsmShadowOptions();
-
     auto& prepareShadowPass = fg.addPass<PrepareShadowPassData>("Prepare Shadow Pass",
             [&](FrameGraph::Builder& builder, auto& data) {
                 data.passList.reserve(getMaxShadowMapCount());
@@ -392,16 +389,18 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
 
                     auto transaction = ShadowMap::open(driver);
                     ShadowMap::prepareCamera(transaction, engine, cameraInfo);
-                    ShadowMap::prepareViewport(transaction, shadowMap.getViewport());
+                    ShadowMap::prepareViewport(transaction,
+                            { 0, 0, textureRequirements.size, textureRequirements.size },
+                            shadowMap.getViewport());
                     ShadowMap::prepareTime(transaction, engine, userTime);
                     ShadowMap::prepareMaterialGlobals(transaction, view.getMaterialGlobals());
                     ShadowMap::prepareShadowMapping(transaction,
-                            vsmShadowOptions.highPrecision);
+                            getWrapExponentEVSM(vsmShadowOptions, shadowMap.getShadowOptions()),
+                            getMaxMomentEVSM(vsmShadowOptions));
                     shadowMap.commit(transaction, engine, driver);
 
                     // updatePrimitivesLod must be run before RenderPass::appendCommands.
-                    FView::updatePrimitivesLod(scene->getRenderableData(),
-                            engine, cameraInfo, entry.range);
+                    FView::updatePrimitivesLod(scene->getRenderableData(), engine, cameraInfo, entry.range);
 
                     // generate and sort the commands for rendering the shadow map
 
@@ -430,10 +429,10 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
                     entry.executor = pass.getExecutor();
 
                     if (!view.hasVSM()) {
-                        auto const* options = shadowMap.getShadowOptions();
+                        auto const& options = shadowMap.getShadowOptions();
                         PolygonOffset const polygonOffset = { // handle reversed Z
-                                .slope    = -options->polygonOffsetSlope,
-                                .constant = -options->polygonOffsetConstant
+                                .slope    = -options.polygonOffsetSlope,
+                                .constant = -options.polygonOffsetConstant
                         };
                         entry.executor.overridePolygonOffset(&polygonOffset);
                     }
@@ -465,10 +464,10 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
         auto const& entry = *first;
 
         const uint8_t layer = entry.shadowMap->getLayer();
-        const auto* options = entry.shadowMap->getShadowOptions();
+        const auto& options = entry.shadowMap->getShadowOptions();
         const auto msaaSamples = textureRequirements.msaaSamples;
         const bool blur = entry.shadowMap->hasVisibleShadows() &&
-                view.hasVSM() && options->vsm.blurWidth > 0.0f;
+                view.hasVSM() && options.vsm.blurWidth > 0.0f;
 
         auto last = first;
         // loop over each shadow pass to find its layer range
@@ -508,10 +507,9 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
 
                         renderTargetDesc.attachments.color[0] = data.output;
                         renderTargetDesc.attachments.depth = depth;
-                        renderTargetDesc.clearFlags =
-                                TargetBufferFlags::COLOR | TargetBufferFlags::DEPTH;
+                        renderTargetDesc.clearFlags = TargetBufferFlags::COLOR | TargetBufferFlags::DEPTH;
                         // we need to clear the shadow map with the max EVSM moments
-                        renderTargetDesc.clearColor = vsmClearColor;
+                        renderTargetDesc.clearColor = textureRequirements.clearColor;
                         renderTargetDesc.samples = msaaSamples;
 
                         if (UTILS_UNLIKELY(blur)) {
@@ -530,16 +528,14 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
                                     .attachments = {
                                             .color = { data.tempBlurSrc },
                                             .depth = depth },
-                                    .clearColor = vsmClearColor,
+                                    .clearColor = textureRequirements.clearColor,
                                     .samples = msaaSamples,
-                                    .clearFlags = TargetBufferFlags::COLOR
-                                            | TargetBufferFlags::DEPTH
+                                    .clearFlags = TargetBufferFlags::COLOR | TargetBufferFlags::DEPTH
                             });
                         }
                     } else {
                         // the shadowmap layer
-                        data.output = builder.write(data.output,
-                                FrameGraphTexture::Usage::DEPTH_ATTACHMENT);
+                        data.output = builder.write(data.output, FrameGraphTexture::Usage::DEPTH_ATTACHMENT);
                         renderTargetDesc.attachments.depth = data.output;
                         renderTargetDesc.clearFlags = TargetBufferFlags::DEPTH;
                     }
@@ -594,27 +590,27 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
             //        the whole layer. Blurring should happen per shadowmap, not for the whole
             //        layer.
 
-            const float blurWidth = options->vsm.blurWidth;
+            // FIXME: this Gaussian blur is not precise enough for EVSM
+
+            const float blurWidth = options.vsm.blurWidth;
             if (blurWidth > 0.0f) {
                 const float sigma = (blurWidth + 1.0f) / 6.0f;
-                size_t kernelWidth = std::ceil((blurWidth - 5.0f) / 4.0f);
+                size_t kernelWidth = size_t(std::ceil((blurWidth - 5.0f) / 4.0f));
                 kernelWidth = kernelWidth * 4 + 5;
                 ppm.gaussianBlurPass(fg,
                         shadowPass->tempBlurSrc,
                         shadowPass->output,
                         false, kernelWidth, sigma);
             }
+        }
 
-            // FIXME: mipmapping here is broken because it'll access texels from adjacent
-            //        shadow maps.
-
-            // If the shadow texture has more than one level, mipmapping was requested, either directly
-            // or indirectly via anisotropic filtering.
-            // So generate the mipmaps for each layer
-            if (textureRequirements.levels > 1) {
-                for (size_t level = 0; level < textureRequirements.levels - 1; level++) {
-                    ppm.vsmMipmapPass(fg, prepareShadowPass->shadows, layer, level, vsmClearColor);
-                }
+        // If the shadow texture has more than one level, mipmapping was requested, either directly
+        // or indirectly via anisotropic filtering.
+        // So generate the mipmaps for each layer
+        if (UTILS_UNLIKELY(textureRequirements.levels > 1)) {
+            auto& ppm = engine.getPostProcessManager();
+            for (size_t level = 0; level < textureRequirements.levels - 1; level++) {
+                ppm.vsmMipmapPass(fg, prepareShadowPass->shadows, layer, level, textureRequirements.clearColor);
             }
         }
     }
@@ -626,7 +622,8 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
         FView& view, CameraInfo cameraInfo, FScene::RenderableSoa& renderableData,
         FScene::LightSoa const& lightData, ShadowMap::SceneInfo sceneInfo) noexcept {
 
-    FScene* scene = view.getScene();
+    FScene const* const scene = view.getScene();
+    auto const& vsmShadowOptions = view.getVsmShadowOptions();
     auto& lcm = engine.getLightManager();
 
     FLightManager::Instance const directionalLight = lightData.elementAt<FScene::LIGHT_INSTANCE>(0);
@@ -650,7 +647,7 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
     };
 
     bool hasVisibleShadows = false;
-    utils::Slice<ShadowMap> cascadedShadowMaps = getCascadedShadowMap();
+    utils::Slice<ShadowMap> const cascadedShadowMaps = getCascadedShadowMap();
     if (!cascadedShadowMaps.empty()) {
         // Even if we have more than one cascade, we cull directional shadow casters against the
         // entire camera frustum, as if we only had a single cascade.
@@ -742,17 +739,17 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
 
                 // Texel size is constant for directional light (although that's not true when LISPSM
                 // is used, but in that case we're pretending it is).
-                const float wsTexelSize = shaderParameters.texelSizeAtOneMeterWs;
+                float2 const wsTexelSize = shaderParameters.texelSizeAtOneMeterWs;
 
                 auto& s = mShadowUb.edit();
                 s.shadows[shadowIndex].layer = shadowMap.getLayer();
                 s.shadows[shadowIndex].lightFromWorldMatrix = shaderParameters.lightSpace;
                 s.shadows[shadowIndex].scissorNormalized = shaderParameters.scissorNormalized;
-                s.shadows[shadowIndex].normalBias = normalBias * wsTexelSize;
-                s.shadows[shadowIndex].texelSizeAtOneMeter = wsTexelSize;
+                s.shadows[shadowIndex].normalBias = wsTexelSize * normalBias;
                 s.shadows[shadowIndex].elvsm = options.vsm.elvsm;
+                s.shadows[shadowIndex].vsmExponent = getWrapExponentEVSM(vsmShadowOptions, options);
                 s.shadows[shadowIndex].bulbRadiusLs =
-                        mSoftShadowOptions.penumbraScale * options.shadowBulbRadius / wsTexelSize;
+                        mSoftShadowOptions.penumbraScale * options.shadowBulbRadius / length(wsTexelSize);
 
                 shadowTechnique |= ShadowTechnique::SHADOW_MAP;
                 cascadeHasVisibleShadows |= 0x1u << i;
@@ -802,10 +799,8 @@ void ShadowMapManager::updateSpotVisibilityMasks(
         const bool visSpotShadowRenderable = v.castShadows && inVisibleLayer &&
                 (!v.culling || (mask & VISIBLE_DYN_SHADOW_RENDERABLE));
 
-        using Type = Culler::result_type;
-
-        visibleMask[i] &= ~Type(VISIBLE_DYN_SHADOW_RENDERABLE);
-        visibleMask[i] |= Type(visSpotShadowRenderable << VISIBLE_DYN_SHADOW_RENDERABLE_BIT);
+        visibleMask[i] &= ~Culler::result_type(VISIBLE_DYN_SHADOW_RENDERABLE);
+        visibleMask[i] |= Culler::result_type(visSpotShadowRenderable << VISIBLE_DYN_SHADOW_RENDERABLE_BIT);
     }
 }
 
@@ -814,13 +809,14 @@ void ShadowMapManager::prepareSpotShadowMap(ShadowMap& shadowMap, FEngine& engin
         FScene::LightSoa const& lightData, ShadowMap::SceneInfo const& sceneInfo) noexcept {
 
     const size_t lightIndex = shadowMap.getLightIndex();
-    FLightManager::ShadowOptions const* const options = shadowMap.getShadowOptions();
+    FLightManager::ShadowOptions const& options = shadowMap.getShadowOptions();
+    auto const& vsmShadowOptions = view.getVsmShadowOptions();
 
     // update the shadow map frustum/camera
     const ShadowMap::ShadowMapInfo shadowMapInfo{
             .atlasDimension      = mTextureAtlasRequirements.size,
-            .textureDimension    = uint16_t(options->mapSize),
-            .shadowDimension     = uint16_t(options->mapSize - 2u),
+            .textureDimension    = uint16_t(options.mapSize),
+            .shadowDimension     = uint16_t(options.mapSize - 2u),
             .textureSpaceFlipped = engine.getBackend() == Backend::METAL ||
                                    engine.getBackend() == Backend::VULKAN ||
                                    engine.getBackend() == Backend::WEBGPU,
@@ -833,9 +829,9 @@ void ShadowMapManager::prepareSpotShadowMap(ShadowMap& shadowMap, FEngine& engin
     // and if we need to generate it, update all the UBO data
     if (shadowMap.hasVisibleShadows()) {
         const size_t shadowIndex = shadowMap.getShadowIndex();
-        const float wsTexelSizeAtOneMeter = shaderParameters.texelSizeAtOneMeterWs;
+        const float2 wsTexelSizeAtOneMeter = shaderParameters.texelSizeAtOneMeterWs;
         // note: normalBias is set to zero for VSM
-        const float normalBias = shadowMapInfo.vsm ? 0.0f : options->normalBias;
+        const float normalBias = shadowMapInfo.vsm ? 0.0f : options.normalBias;
 
         auto& s = mShadowUb.edit();
         const double n = shadowMap.getCamera().getNear();
@@ -845,12 +841,12 @@ void ShadowMapManager::prepareSpotShadowMap(ShadowMap& shadowMap, FEngine& engin
         s.shadows[shadowIndex].scissorNormalized = shaderParameters.scissorNormalized;
         s.shadows[shadowIndex].normalBias = normalBias * wsTexelSizeAtOneMeter;
         s.shadows[shadowIndex].lightFromWorldZ = shaderParameters.lightFromWorldZ;
-        s.shadows[shadowIndex].texelSizeAtOneMeter = wsTexelSizeAtOneMeter;
         s.shadows[shadowIndex].nearOverFarMinusNear = float(n / (f - n));
-        s.shadows[shadowIndex].elvsm = options->vsm.elvsm;
+        s.shadows[shadowIndex].elvsm = options.vsm.elvsm;
+        s.shadows[shadowIndex].vsmExponent = getWrapExponentEVSM(vsmShadowOptions, options);
         s.shadows[shadowIndex].bulbRadiusLs =
-                mSoftShadowOptions.penumbraScale * options->shadowBulbRadius
-                        / wsTexelSizeAtOneMeter;
+                mSoftShadowOptions.penumbraScale * options.shadowBulbRadius
+                        / length(wsTexelSizeAtOneMeter);
 
     }
 }
@@ -907,13 +903,14 @@ void ShadowMapManager::preparePointShadowMap(ShadowMap& shadowMap,
 
     const uint8_t face = shadowMap.getFace();
     const size_t lightIndex = shadowMap.getLightIndex();
-    FLightManager::ShadowOptions const* const options = shadowMap.getShadowOptions();
+    FLightManager::ShadowOptions const& options = shadowMap.getShadowOptions();
+    auto const& vsmShadowOptions = view.getVsmShadowOptions();
 
     // update the shadow map frustum/camera
     const ShadowMap::ShadowMapInfo shadowMapInfo{
             .atlasDimension      = mTextureAtlasRequirements.size,
-            .textureDimension    = uint16_t(options->mapSize),
-            .shadowDimension     = uint16_t(options->mapSize), // point-lights don't have a border
+            .textureDimension    = uint16_t(options.mapSize),
+            .shadowDimension     = uint16_t(options.mapSize), // point-lights don't have a border
             .textureSpaceFlipped = engine.getBackend() == Backend::METAL ||
                                    engine.getBackend() == Backend::VULKAN ||
                                    engine.getBackend() == Backend::WEBGPU,
@@ -926,9 +923,9 @@ void ShadowMapManager::preparePointShadowMap(ShadowMap& shadowMap,
     // and if we need to generate it, update all the UBO data
     if (shadowMap.hasVisibleShadows()) {
         const size_t shadowIndex = shadowMap.getShadowIndex();
-        const float wsTexelSizeAtOneMeter = shaderParameters.texelSizeAtOneMeterWs;
+        const float2 wsTexelSizeAtOneMeter = shaderParameters.texelSizeAtOneMeterWs;
         // note: normalBias is set to zero for VSM
-        const float normalBias = shadowMapInfo.vsm ? 0.0f : options->normalBias;
+        const float normalBias = shadowMapInfo.vsm ? 0.0f : options.normalBias;
 
         auto& s = mShadowUb.edit();
         const double n = shadowMap.getCamera().getNear();
@@ -938,12 +935,12 @@ void ShadowMapManager::preparePointShadowMap(ShadowMap& shadowMap,
         s.shadows[shadowIndex].scissorNormalized = shaderParameters.scissorNormalized;
         s.shadows[shadowIndex].normalBias = normalBias * wsTexelSizeAtOneMeter;
         s.shadows[shadowIndex].lightFromWorldZ = shaderParameters.lightFromWorldZ;
-        s.shadows[shadowIndex].texelSizeAtOneMeter = wsTexelSizeAtOneMeter;
         s.shadows[shadowIndex].nearOverFarMinusNear = float(n / (f - n));
-        s.shadows[shadowIndex].elvsm = options->vsm.elvsm;
+        s.shadows[shadowIndex].elvsm = options.vsm.elvsm;
+        s.shadows[shadowIndex].vsmExponent = getWrapExponentEVSM(vsmShadowOptions, options);
         s.shadows[shadowIndex].bulbRadiusLs =
-                mSoftShadowOptions.penumbraScale * options->shadowBulbRadius
-                        / wsTexelSizeAtOneMeter;
+                mSoftShadowOptions.penumbraScale * options.shadowBulbRadius
+                        / length(wsTexelSizeAtOneMeter);
     }
 }
 
@@ -998,7 +995,7 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateSpotShadowMaps(FEngine
             lightData.data<FScene::SHADOW_INFO>());
 
     ShadowTechnique shadowTechnique{};
-    utils::Slice<const ShadowMap> spotShadowMaps = getSpotShadowMaps();
+    utils::Slice<const ShadowMap> const spotShadowMaps = getSpotShadowMaps();
     if (!spotShadowMaps.empty()) {
         shadowTechnique |= ShadowTechnique::SHADOW_MAP;
         for (ShadowMap const& shadowMap : spotShadowMaps) {
@@ -1038,14 +1035,14 @@ void ShadowMapManager::calculateTextureRequirements(FEngine& engine, FView& view
     for (ShadowMap const& shadowMap : getCascadedShadowMap()) {
         // Shadow map size should be the same for all cascades.
         auto const& options = shadowMap.getShadowOptions();
-        maxDimension = std::max(maxDimension, options->mapSize);
-        elvsm = elvsm || options->vsm.elvsm;
+        maxDimension = std::max(maxDimension, options.mapSize);
+        elvsm = elvsm || options.vsm.elvsm;
     }
 
     for (ShadowMap const& shadowMap : getSpotShadowMaps()) {
         auto const& options = shadowMap.getShadowOptions();
-        maxDimension = std::max(maxDimension, options->mapSize);
-        elvsm = elvsm || options->vsm.elvsm;
+        maxDimension = std::max(maxDimension, options.mapSize);
+        elvsm = elvsm || options.vsm.elvsm;
     }
 
     uint8_t layersNeeded = 0;
@@ -1055,7 +1052,7 @@ void ShadowMapManager::calculateTextureRequirements(FEngine& engine, FView& view
         ShadowMap* pShadowMap) mutable {
         // Allocate shadowmap from our Atlas Allocator
         auto const& options = pShadowMap->getShadowOptions();
-        auto allocation = allocator.allocate(options->mapSize);
+        auto allocation = allocator.allocate(options.mapSize);
         assert_invariant(allocation.isValid());
         assert_invariant(!allocation.viewport.empty());
         pShadowMap->setAllocation(allocation.layer, allocation.viewport);
@@ -1091,6 +1088,7 @@ void ShadowMapManager::calculateTextureRequirements(FEngine& engine, FView& view
         msaaSamples = 1;
     }
 
+    float4 clearColor{};
     TextureFormat format = TextureFormat::DEPTH16;
     if (view.hasVSM()) {
         if (vsmShadowOptions.highPrecision) {
@@ -1098,6 +1096,9 @@ void ShadowMapManager::calculateTextureRequirements(FEngine& engine, FView& view
         } else {
             format = elvsm ? TextureFormat::RGBA16F : TextureFormat::RG16F;
         }
+        const float maxMoment2 = getMaxMomentEVSM(vsmShadowOptions);
+        const float maxMoment1 = std::sqrt(maxMoment2);
+        clearColor = { maxMoment1, maxMoment2, 0, 0 };
     }
 
     mSoftShadowOptions = view.getSoftShadowOptions();
@@ -1119,7 +1120,8 @@ void ShadowMapManager::calculateTextureRequirements(FEngine& engine, FView& view
             layersNeeded,
             mipLevels,
             msaaSamples,
-            format
+            format,
+            clearColor
     };
 }
 

filament/src/ShadowMapManager.h

@@ -47,9 +47,12 @@
 #include <utils/Slice.h>
 
 #include <math/mat4.h>
+#include <math/half.h>
 #include <math/vec4.h>
 
+#include <algorithm>
 #include <array>
+#include <limits>
 #include <memory>
 #include <new>
 #include <type_traits>
@@ -145,6 +148,28 @@ public:
     // for debugging only
     utils::FixedCapacityVector<Camera const*> getDirectionalShadowCameras() const noexcept;
 
+    static float getMaxMomentEVSM(VsmShadowOptions const& vsmShadowOptions) noexcept {
+        return vsmShadowOptions.highPrecision ?
+                std::numeric_limits<float>::max() :
+                float(std::numeric_limits<math::half>::max());
+    }
+
+    static float getMaxWrapExponentEVSM(VsmShadowOptions const& vsmShadowOptions) noexcept {
+        constexpr float low  = 5.2f;  // ~ std::log(std::numeric_limits<math::half>::max()) * 0.5f;
+        constexpr float high = 40.0f; // ~ std::log(std::numeric_limits<float>::max()) * 0.5f;
+        return vsmShadowOptions.highPrecision ? high : low;
+    }
+
+    static float getWrapExponentEVSM(
+            VsmShadowOptions const& vsmShadowOptions,
+            LightManager::ShadowOptions const& options) noexcept {
+        constexpr float ABSOLUTE_FILTER_LIMIT = 42.0f;
+        float const targetExponent = getMaxWrapExponentEVSM(vsmShadowOptions);
+        float const effectiveFilterRadius = std::max(1.0f, options.vsm.blurWidth);
+        float const filterCeiling = ABSOLUTE_FILTER_LIMIT / effectiveFilterRadius;
+        return std::min(targetExponent, filterCeiling);
+    }
+
 private:
     explicit ShadowMapManager(FEngine& engine);
 
@@ -216,6 +241,7 @@ private:
         uint8_t levels = 0;
         uint8_t msaaSamples = 1;
         backend::TextureFormat format = backend::TextureFormat::DEPTH16;
+        math::float4 clearColor{};
     } mTextureAtlasRequirements;
 
     SoftShadowOptions mSoftShadowOptions;

filament/src/components/CameraManager.cpp

@@ -85,7 +85,6 @@ void FCameraManager::destroy(FEngine& engine, Entity const e) noexcept {
         { // scope for camera -- it's invalid after this scope.
             FCamera* const camera = manager.elementAt<CAMERA>(i);
             assert_invariant(camera);
-            camera->terminate(engine);
             engine.getHeapAllocator().destroy(camera);
 
             // Remove the camera component

filament/src/components/RenderableManager.cpp

@@ -577,7 +577,7 @@ void FRenderableManager::create(
     FEngine::DriverApi& driver = engine.getDriverApi();
 
     if (UTILS_UNLIKELY(manager.hasComponent(entity))) {
-        destroy(entity);
+        destroy(entity, driver);
     }
     Instance const ci = manager.addComponent(entity);
     assert_invariant(ci);
@@ -733,41 +733,42 @@ void FRenderableManager::create(
 }
 
 // this destroys a single component from an entity
-void FRenderableManager::destroy(Entity const e) noexcept {
+void FRenderableManager::destroy(Entity const e, DriverApi& driver) noexcept {
     Instance const ci = getInstance(e);
     if (ci) {
-        destroyComponent(ci);
+        destroyComponent(ci, driver);
         mManager.removeComponent(e);
     }
 }
 
+void FRenderableManager::clientDestroy(utils::Entity e) noexcept {
+    destroy(e, mEngine.getDriverApi());
+}
+
 // this destroys all components in this manager
-void FRenderableManager::terminate() noexcept {
+void FRenderableManager::terminate(DriverApi& driver) noexcept {
     auto& manager = mManager;
     if (!manager.empty()) {
         DLOG(INFO) << "cleaning up " << manager.getComponentCount()
                    << " leaked Renderable components";
         while (!manager.empty()) {
             Instance const ci = manager.end() - 1;
-            destroyComponent(ci);
+            destroyComponent(ci, driver);
             manager.removeComponent(manager.getEntity(ci));
         }
     }
-    mHwRenderPrimitiveFactory.terminate(mEngine.getDriverApi());
+    mHwRenderPrimitiveFactory.terminate(driver);
 }
 
-void FRenderableManager::gc(EntityManager& em) noexcept {
-    mManager.gc(em, [this](Entity const e) {
-        destroy(e);
+void FRenderableManager::gc(EntityManager& em, DriverApi& driver) noexcept {
+    mManager.gc(em, [this, &driver](Entity const e) {
+        destroy(e, driver);
     });
 }
 
 // This is basically a Renderable's destructor.
-void FRenderableManager::destroyComponent(Instance const ci) noexcept {
+void FRenderableManager::destroyComponent(Instance const ci, DriverApi& driver) noexcept {
     auto& manager = mManager;
-    FEngine& engine = mEngine;
-
-    FEngine::DriverApi& driver = engine.getDriverApi();
 
     // See create(RenderableManager::Builder&, Entity)
     destroyComponentPrimitives(mHwRenderPrimitiveFactory, driver, manager[ci].primitives);

filament/src/components/RenderableManager.h

@@ -91,9 +91,9 @@ public:
     ~FRenderableManager();
 
     // free-up all resources
-    void terminate() noexcept;
+    void terminate(backend::DriverApi& driver) noexcept;
 
-    void gc(utils::EntityManager& em) noexcept;
+    void gc(utils::EntityManager& em, backend::DriverApi& driver) noexcept;
 
     /*
      * Component Manager APIs
@@ -125,7 +125,11 @@ public:
 
     void create(const Builder& builder, utils::Entity entity);
 
-    void destroy(utils::Entity e) noexcept;
+    void destroy(utils::Entity e, backend::DriverApi& driver) noexcept;
+
+    // The client API should have taken an Engine&, but it doesn't, so that's a workaround
+    // so we can keep the API as it is.
+    void clientDestroy(utils::Entity e) noexcept;
 
     inline void setAxisAlignedBoundingBox(Instance instance, const Box& aabb);
 
@@ -239,7 +243,7 @@ public:
     };
 
 private:
-    void destroyComponent(Instance ci) noexcept;
+    void destroyComponent(Instance ci, backend::DriverApi& driver) noexcept;
     static void destroyComponentPrimitives(
             HwRenderPrimitiveFactory& factory, backend::DriverApi& driver,
             utils::Slice<FRenderPrimitive> primitives) noexcept;

filament/src/details/Camera.h

@@ -46,9 +46,6 @@ public:
 
     FCamera(FEngine& engine, utils::Entity e);
 
-    void terminate(FEngine&) noexcept { }
-
-
     // Sets the projection matrices (viewing and culling). The viewing matrice has infinite far.
     void setProjection(Projection projection,
                        double left, double right, double bottom, double top,

filament/src/details/Engine.cpp

@@ -20,6 +20,11 @@
 #include "TextureCache.h"
 #include "RenderPrimitive.h"
 
+#include "components/CameraManager.h"
+#include "components/LightManager.h"
+#include "components/RenderableManager.h"
+#include "components/TransformManager.h"
+
 #include "details/BufferObject.h"
 #include "details/Camera.h"
 #include "details/Fence.h"
@@ -58,6 +63,7 @@
 #include <utils/CallStack.h>
 #include <utils/CString.h>
 #include <utils/Invocable.h>
+#include <utils/JobSystem.h>
 #include <utils/Logger.h>
 #include <utils/Panic.h>
 #include <utils/PrivateImplementation-impl.h>
@@ -538,12 +544,10 @@ void FEngine::init() {
             &debug.shadowmap.debug_directional_shadowmap, [this] {
                 mMaterials.forEach([this](FMaterial* material) {
                     if (material->getMaterialDomain() == MaterialDomain::SURFACE) {
-                        FMaterial::SpecializationConstantsBuilder constants =
-                                material->getSpecializationConstantsBuilder();
-                        constants.set(+ReservedSpecializationConstants::
-                                              CONFIG_DEBUG_DIRECTIONAL_SHADOWMAP,
-                                debug.shadowmap.debug_directional_shadowmap);
-                        material->setSpecializationConstants(std::move(constants));
+                        material->getPrograms().setConstants({
+                            { +ReservedSpecializationConstants::CONFIG_DEBUG_DIRECTIONAL_SHADOWMAP,
+                              debug.shadowmap.debug_directional_shadowmap },
+                        });
                     }
                 });
             });
@@ -552,12 +556,10 @@ void FEngine::init() {
             &debug.lighting.debug_froxel_visualization, [this] {
                 mMaterials.forEach([this](FMaterial* material) {
                     if (material->getMaterialDomain() == MaterialDomain::SURFACE) {
-                        FMaterial::SpecializationConstantsBuilder constants =
-                                material->getSpecializationConstantsBuilder();
-                        constants.set(+ReservedSpecializationConstants::
-                                              CONFIG_DEBUG_FROXEL_VISUALIZATION,
-                                debug.lighting.debug_froxel_visualization);
-                        material->setSpecializationConstants(std::move(constants));
+                        material->getPrograms().setConstants({
+                            { +ReservedSpecializationConstants::CONFIG_DEBUG_FROXEL_VISUALIZATION,
+                              debug.lighting.debug_froxel_visualization },
+                        });
                     }
                 });
             });
@@ -590,6 +592,9 @@ void FEngine::shutdown() {
     DLOG(INFO) << "CircularBuffer: High watermark " << wm / 1024 << " KiB (" << wmpct << "%)";
 #endif
 
+    /* Destroy any leftover items in the cache. */
+    mMaterialCache.terminate(*this);
+
     DriverApi& driver = getDriverApi();
 
     /*
@@ -600,7 +605,7 @@ void FEngine::shutdown() {
     mResourceAllocatorDisposer->terminate();
     mResourceAllocatorDisposer.reset();
     mDFG.terminate(*this);                  // free-up the DFG
-    mRenderableManager.terminate();         // free-up all renderables
+    mRenderableManager.terminate(driver);   // free-up all renderables
     mLightManager.terminate();              // free-up all lights
     mCameraManager.terminate(*this);        // free-up all cameras
 
@@ -764,13 +769,30 @@ void FEngine::prepare(DriverApi& driver) {
     });
 }
 
-void FEngine::gcManagers() {
-    // Note: this runs in a Job
-    auto& em = mEntityManager;
-    mRenderableManager.gc(em);
-    mLightManager.gc(em);
-    mTransformManager.gc(em);
-    mCameraManager.gc(*this, em);
+void FEngine::gc() {
+    JobSystem& js = getJobSystem();
+    auto *rootJob = js.createJob();
+
+    js.run(
+            jobs::createJob(js, rootJob, [this] {
+                // These are safe to GC *sequentially* from a worker thread.
+                // The JobSystem acts as a release/acquire operation.
+                mLightManager.gc(mEntityManager);
+                mTransformManager.gc(mEntityManager);
+                mCameraManager.gc(*this, mEntityManager);
+            }));
+
+    if (isAsynchronousModeEnabled()) {
+        // gcDeferredAsyncObjectDestruction() is thread-safe in this context because
+        // 1. JobSystem provides the release/acquire operation
+        // 2. it's only used from the main thread, which we are blocking during the gc
+        js.run(jobs::createJob(js, rootJob, &FEngine::gcDeferredAsyncObjectDestruction, this));
+    }
+
+    // RenderableManager cannot be gc'ed from a different thread, because it needs the DriverAPI
+    mRenderableManager.gc(mEntityManager, getDriverApi());
+
+    js.runAndWait(rootJob);
 }
 
 void FEngine::gcDeferredAsyncObjectDestruction() {
@@ -798,6 +820,12 @@ void FEngine::submitFrame() {
 void FEngine::flush() {
     // flush the command buffer
     flushCommandBuffer(mCommandBufferQueue);
+    
+    // In single-threaded mode, we have to call execute() to drain the command
+    // buffer to really free up space
+    if constexpr (!UTILS_HAS_THREADING) {
+        execute();
+    }
 }
 
 void FEngine::flushAndWait() {
@@ -1393,7 +1421,7 @@ bool FEngine::destroy(const FMaterialInstance* p) {
 
 UTILS_NOINLINE
 void FEngine::destroy(Entity const e) {
-    mRenderableManager.destroy(e);
+    mRenderableManager.destroy(e, getDriverApi());
     mLightManager.destroy(e);
     mTransformManager.destroy(e);
     mCameraManager.destroy(*this, e);

filament/src/details/Engine.h

@@ -456,8 +456,7 @@ public:
     }
 
     void prepare(backend::DriverApi& driver);
-    void gcManagers();
-    void gcDeferredAsyncObjectDestruction();
+    void gc();
     void submitFrame();
 
     using ShaderContent = utils::FixedCapacityVector<uint8_t>;
@@ -583,6 +582,8 @@ private:
     int loop();
     void flushCommandBuffer(backend::CommandBufferQueue& commandBufferQueue) const;
 
+    void gcDeferredAsyncObjectDestruction();
+
     template<typename T>
     bool isValid(const T* ptr, ResourceList<T> const& list) const;
 

filament/src/details/Material.cpp

@@ -176,28 +176,7 @@ FMaterial::FMaterial(FEngine& engine, const Builder& builder, MaterialDefinition
             driver.isWorkaroundNeeded(Workaround::DISABLE_DEPTH_PRECACHE_FOR_DEFAULT_MATERIAL);
     mDefaultMaterial = engine.getDefaultMaterial();
 
-    FixedCapacityVector<Program::SpecializationConstant> specializationConstants =
-            processSpecializationConstants(builder);
-    mSpecializationConstants =
-            engine.getMaterialCache().getSpecializationConstantsInternPool().acquire(
-                    std::move(specializationConstants));
-
-    size_t cachedProgramsSize;
-    switch (mDefinition.materialDomain) {
-        case filament::MaterialDomain::SURFACE:
-            cachedProgramsSize = 1 << VARIANT_BITS;
-            break;
-        case filament::MaterialDomain::POST_PROCESS:
-            cachedProgramsSize = 1 << POST_PROCESS_VARIANT_BITS;
-            break;
-        case filament::MaterialDomain::COMPUTE:
-            cachedProgramsSize = 1;
-            break;
-    }
-    mCachedPrograms = FixedCapacityVector<backend::Handle<backend::HwProgram>>(cachedProgramsSize);
-
-    mDefinition.acquirePrograms(engine, mCachedPrograms.as_slice(), getMaterialParser(),
-            mSpecializationConstants, mIsDefaultMaterial);
+    mPrograms.initializeForMaterial(engine, *this, processSpecializationConstants(builder));
 
 #if FILAMENT_ENABLE_MATDBG
     // Register the material with matdbg.
@@ -237,11 +216,7 @@ void FMaterial::terminate(FEngine& engine) {
     }
 #endif
 
-    mDefinition.releasePrograms(engine, mCachedPrograms.as_slice(),
-            getMaterialParser(), mSpecializationConstants, mIsDefaultMaterial);
-    engine.getMaterialCache().releaseMaterial(engine, mDefinition);
-    engine.getMaterialCache().getSpecializationConstantsInternPool().release(
-            mSpecializationConstants);
+    mPrograms.terminate(engine);
 }
 
 filament::DescriptorSetLayout const& FMaterial::getPerViewDescriptorSetLayout(
@@ -257,9 +232,9 @@ filament::DescriptorSetLayout const& FMaterial::getPerViewDescriptorSetLayout(
     }
     // mDefinition.perViewDescriptorSetLayout{Vsm} is already resolved for MaterialDomain
     if (useVsmDescriptorSetLayout) {
-        return mDefinition.perViewDescriptorSetLayoutVsm;
+        return mDefinition.perViewDescriptorSetLayoutS2d;
     }
-    return mDefinition.perViewDescriptorSetLayout;
+    return mDefinition.perViewDescriptorSetLayoutPcf;
 }
 
 void FMaterial::compile(CompilerPriorityQueue const priority,
@@ -306,22 +281,6 @@ void FMaterial::compile(CompilerPriorityQueue const priority,
     }
 }
 
-Handle<HwProgram> FMaterial::prepareProgramSlow(DriverApi& driver, Variant const variant,
-        CompilerPriorityQueue const priorityQueue) const noexcept {
-    if (isSharedVariant(variant)) {
-        FMaterial const* defaultMaterial = mEngine.getDefaultMaterial();
-        FILAMENT_CHECK_PRECONDITION(defaultMaterial);
-        Handle<HwProgram> program = defaultMaterial->mCachedPrograms[variant.key];
-        if (program) {
-            return mCachedPrograms[variant.key] = program;
-        }
-        return mCachedPrograms[variant.key] =
-                defaultMaterial->prepareProgram(driver, variant, priorityQueue);
-    }
-    return mCachedPrograms[variant.key] = mDefinition.prepareProgram(mEngine, driver,
-            getMaterialParser(), getProgramSpecialization(variant), priorityQueue);
-}
-
 FMaterialInstance* FMaterial::createInstance(const char* name) const noexcept {
     if (mDefaultMaterialInstance) {
         // if we have a default instance, use it to create a new one
@@ -356,14 +315,6 @@ BufferInterfaceBlock::FieldInfo const* FMaterial::reflect(
     return mDefinition.uniformInterfaceBlock.getFieldInfo(name);
 }
 
-ProgramSpecialization FMaterial::getProgramSpecialization(Variant const variant) const noexcept {
-    return ProgramSpecialization {
-        .materialCrc32 = mDefinition.getMaterialParser().getCrc32(),
-        .variant = variant,
-        .specializationConstants = mSpecializationConstants,
-    };
-}
-
 size_t FMaterial::getParameters(ParameterInfo* parameters, size_t count) const noexcept {
     count = std::min(count, getParameterCount());
 
@@ -430,8 +381,7 @@ void FMaterial::updateActiveProgramsForMatdbg(Variant const variant) const noexc
 void FMaterial::applyPendingEdits() noexcept {
     const char* name = mDefinition.name.c_str();
     DLOG(INFO) << "Applying edits to " << (name ? name : "(untitled)");
-    mDefinition.releasePrograms(mEngine, mCachedPrograms.as_slice(), getMaterialParser(),
-            mSpecializationConstants, mIsDefaultMaterial);
+    mPrograms.clear(mEngine);
     latchPendingEdits();
 }
 
@@ -480,26 +430,6 @@ void FMaterial::onQueryCallback(void* userdata, VariantList* pActiveVariants) {
 
 #endif // FILAMENT_ENABLE_MATDBG
 
-void FMaterial::setSpecializationConstants(SpecializationConstantsBuilder&& builder) noexcept {
-    if (builder.mConstants.empty()) {
-        // Nothing was changed.
-        return;
-    }
-
-    auto& internPool = mEngine.getMaterialCache().getSpecializationConstantsInternPool();
-    MaterialParser const& materialParser = getMaterialParser();
-
-    // Release old resources...
-    mDefinition.releasePrograms(mEngine, mCachedPrograms.as_slice(), materialParser,
-            mSpecializationConstants, mIsDefaultMaterial);
-    internPool.release(mSpecializationConstants);
-
-    // Then acquire new ones.
-    mSpecializationConstants = internPool.acquire(std::move(builder.mConstants));
-    mDefinition.acquirePrograms(mEngine, mCachedPrograms.as_slice(), materialParser,
-            mSpecializationConstants, mIsDefaultMaterial);
-}
-
 FixedCapacityVector<Program::SpecializationConstant> FMaterial::processSpecializationConstants(
         Builder const& builder) {
     FixedCapacityVector<Program::SpecializationConstant> specializationConstants =
@@ -560,12 +490,4 @@ const char* FMaterial::getParameterTransformName(std::string_view samplerName) c
     return info->transformName.c_str();
 }
 
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<int32_t>(uint32_t id, int32_t value) noexcept;
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<float>(uint32_t id, float value) noexcept;
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<bool>(uint32_t id, bool value) noexcept;
-
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<int32_t>(std::string_view name, int32_t value) noexcept;
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<float>(std::string_view name, float value) noexcept;
-template FMaterial::SpecializationConstantsBuilder& FMaterial::SpecializationConstantsBuilder::set<bool>(std::string_view name, bool value) noexcept;
-
 } // namespace filament

filament/src/details/Material.h

@@ -18,6 +18,7 @@
 #define TNT_FILAMENT_DETAILS_MATERIAL_H
 
 #include "downcast.h"
+#include "LocalProgramCache.h"
 
 #include "details/MaterialInstance.h"
 
@@ -45,7 +46,6 @@
 #include <utils/Invocable.h>
 #include <utils/Mutex.h>
 
-#include <optional>
 #include <string_view>
 
 #include <stddef.h>
@@ -72,62 +72,6 @@ public:
         DefaultMaterialBuilder();
     };
 
-    // Used to change specialization constants at runtime internally by Filament.
-    //
-    // Call Material::getSpecializationConstantsBuilder() to return an instance of
-    // SpecializationConstantsBuilder. The lifetime of this object must not exceed the lifetime of
-    // the corresponding Material. After spec constants are changed with calls to set(), apply the
-    // changes to the original Material via setSpecializationConstants().
-    //
-    // It would be nice to reuse Builder for this, but Builder allocates an entire map and asserts
-    // if specified constants don't exist. In constrast, SpecializationConstantsBuilder is
-    // copy-on-write and allows non-existent specialization constants to be named.
-    class SpecializationConstantsBuilder {
-        friend class FMaterial;
-
-    public:
-        SpecializationConstantsBuilder(SpecializationConstantsBuilder const& rhs) = delete;
-        SpecializationConstantsBuilder& operator=(
-                SpecializationConstantsBuilder const& rhs) = delete;
-
-        SpecializationConstantsBuilder(SpecializationConstantsBuilder&& rhs) = default;
-        SpecializationConstantsBuilder& operator=(SpecializationConstantsBuilder&& rhs) = default;
-
-        template<typename T, typename = Builder::is_supported_constant_parameter_t<T>>
-        SpecializationConstantsBuilder& set(uint32_t id, T value) noexcept {
-            // Don't allocate if we can help it.
-            if (mConstants.empty()) {
-                if (std::get<T>(mDefaultConstants[id]) == value) {
-                    return *this;
-                }
-                mConstants = utils::FixedCapacityVector<backend::Program::SpecializationConstant>(
-                        mDefaultConstants);
-            }
-            mConstants[id] = value;
-            return *this;
-        }
-
-        template<typename T, typename = Builder::is_supported_constant_parameter_t<T>>
-        SpecializationConstantsBuilder& set(std::string_view name, T value) noexcept {
-            auto it = mDefinition->specializationConstantsNameToIndex.find(name);
-            if (it != mDefinition->specializationConstantsNameToIndex.cend()) {
-                set(it->second + CONFIG_MAX_RESERVED_SPEC_CONSTANTS, value);
-            }
-            return *this;
-        }
-
-    private:
-        SpecializationConstantsBuilder(MaterialDefinition const& definition,
-                utils::Slice<const backend::Program::SpecializationConstant> defaultConstants)
-                : mDefinition(&definition),
-                  mDefaultConstants(defaultConstants) {}
-
-        MaterialDefinition const* mDefinition;
-        utils::Slice<const backend::Program::SpecializationConstant> mDefaultConstants;
-        // Copy-on-write vector.
-        utils::FixedCapacityVector<backend::Program::SpecializationConstant> mConstants;
-    };
-
     void terminate(FEngine& engine);
 
     // return the uniform interface block for this material
@@ -139,7 +83,7 @@ public:
         // This is mostly intended to be used for post-process materials; but it's also useful for
         // Surface material that behave like post-process material (i.e. that don't really have variants or for
         // which VSM is nonsensical, like for unlit materials)
-        return mDefinition.perViewDescriptorSetLayout;
+        return mDefinition.perViewDescriptorSetLayoutPcf;
     }
 
     DescriptorSetLayout const& getPerViewDescriptorSetLayout(
@@ -187,11 +131,7 @@ public:
     backend::Handle<backend::HwProgram> prepareProgram(backend::DriverApi& driver,
             Variant const variant,
             backend::CompilerPriorityQueue const priorityQueue) const noexcept {
-        backend::Handle<backend::HwProgram> program = mCachedPrograms[variant.key];
-        if (UTILS_LIKELY(program)) {
-            return program;
-        }
-        return prepareProgramSlow(driver, variant, priorityQueue);
+        return mPrograms.prepareProgram(driver, variant, priorityQueue);
     }
 
     // getProgram returns the backend program for the material's given variant.
@@ -216,9 +156,7 @@ public:
 #if FILAMENT_ENABLE_MATDBG
         updateActiveProgramsForMatdbg(variant);
 #endif
-        backend::Handle<backend::HwProgram> program = mCachedPrograms[variant.key];
-        assert_invariant(program);
-        return program;
+        return mPrograms.getProgram(variant);
     }
 
     // MaterialInstance::use() binds descriptor sets before drawing. For shared variants,
@@ -275,6 +213,8 @@ public:
     float getSpecularAntiAliasingVariance() const noexcept { return mDefinition.specularAntiAliasingVariance; }
     float getSpecularAntiAliasingThreshold() const noexcept { return mDefinition.specularAntiAliasingThreshold; }
 
+    bool isDefaultMaterial() const noexcept { return mIsDefaultMaterial; }
+
     backend::descriptor_binding_t getSamplerBinding(
             std::string_view const& name) const;
 
@@ -297,12 +237,7 @@ public:
 
     uint32_t generateMaterialInstanceId() const noexcept { return mMaterialInstanceId++; }
 
-    // Update specialization constants.
-    SpecializationConstantsBuilder getSpecializationConstantsBuilder() const noexcept {
-        return SpecializationConstantsBuilder(mDefinition, mSpecializationConstants);
-    }
-
-    void setSpecializationConstants(SpecializationConstantsBuilder&& builder) noexcept;
+    LocalProgramCache& getPrograms() noexcept { return mPrograms; }
 
     uint8_t getPerViewLayoutIndex() const noexcept {
         return mDefinition.perViewLayoutIndex;
@@ -316,6 +251,30 @@ public:
         return mDefinition.source.c_str_safe();
     }
 
+    inline bool isSharedVariant(Variant const variant) const {
+        // HACK: The default material "should" have MNT | DEP, but then we'd have to compile it as a
+        // lit material, which would increase binary size. Perhaps we could specially compile it
+        // with this variant, but with the shader program cache in active development, the days of
+        // the default material are numbered anyway.
+        constexpr Variant::type_t vsmAndDep = Variant::MNT | Variant::DEP;
+        return mDefinition.materialDomain == MaterialDomain::SURFACE && !mIsDefaultMaterial &&
+               !mDefinition.hasCustomDepthShader && Variant::isValidDepthVariant(variant) &&
+               (variant.key & vsmAndDep) != vsmAndDep;
+    }
+
+    MaterialParser const& getMaterialParser() const noexcept {
+#if FILAMENT_ENABLE_MATDBG
+        if (mEditedMaterialParser) {
+            return *mEditedMaterialParser;
+        }
+#endif
+        return mDefinition.getMaterialParser();
+    }
+
+    MaterialDefinition const& getDefinition() const noexcept { return mDefinition; }
+
+    LocalProgramCache const& getPrograms() const noexcept { return mPrograms; }
+
 #if FILAMENT_ENABLE_MATDBG
     void applyPendingEdits() noexcept;
 
@@ -349,21 +308,6 @@ public:
 #endif
 
 private:
-    MaterialParser const& getMaterialParser() const noexcept {
-#if FILAMENT_ENABLE_MATDBG
-        if (mEditedMaterialParser) {
-            return *mEditedMaterialParser;
-        }
-#endif
-        return mDefinition.getMaterialParser();
-    }
-
-    ProgramSpecialization getProgramSpecialization(Variant const variant) const noexcept;
-
-    backend::Handle<backend::HwProgram> prepareProgramSlow(backend::DriverApi& driver,
-            Variant const variant,
-            backend::CompilerPriorityQueue const priorityQueue) const noexcept;
-
     utils::FixedCapacityVector<backend::Program::SpecializationConstant>
             processSpecializationConstants(Builder const& builder);
 
@@ -371,24 +315,6 @@ private:
 
     void createAndCacheProgram(backend::DriverApi& driver, backend::Program&& p, Variant variant) const noexcept;
 
-    backend::DescriptorSetLayout const& getPerViewDescriptorSetLayoutDescription(
-            Variant variant, bool useVsmDescriptorSetLayout) const noexcept;
-
-    backend::DescriptorSetLayout const& getDescriptorSetLayoutDescription(
-            Variant variant = {}) const noexcept;
-
-    bool isSharedVariant(Variant const variant) const {
-        // HACK: The default material "should" have VSM | DEP, but then we'd have to compile it as a
-        // lit material, which would increase binary size. Perhaps we could specially compile it
-        // with this variant, but with the shader program cache in active development, the days of
-        // the default material are numbered anyway.
-        constexpr Variant::type_t vsmAndDep = Variant::VSM | Variant::DEP;
-        return mDefinition.materialDomain == MaterialDomain::SURFACE && !mIsDefaultMaterial &&
-               !mDefinition.hasCustomDepthShader && Variant::isValidDepthVariant(variant) &&
-               (variant.key & vsmAndDep) != vsmAndDep;
-    }
-
-    mutable utils::FixedCapacityVector<backend::Handle<backend::HwProgram>> mCachedPrograms;
     MaterialDefinition const& mDefinition;
 
     bool mIsDefaultMaterial = false;
@@ -403,9 +329,6 @@ private:
     // reserve some space to construct the default material instance
     mutable FMaterialInstance* mDefaultMaterialInstance = nullptr;
 
-    // current specialization constants for the HwProgram
-    utils::Slice<const backend::Program::SpecializationConstant> mSpecializationConstants;
-
 #if FILAMENT_ENABLE_MATDBG
     matdbg::MaterialKey mDebuggerId;
     mutable utils::Mutex mActiveProgramsLock;
@@ -423,6 +346,8 @@ private:
     FEngine& mEngine;
     const uint32_t mMaterialId;
     mutable uint32_t mMaterialInstanceId = 0;
+
+    LocalProgramCache mPrograms;
 };
 
 

filament/src/details/MaterialInstance.h

@@ -93,6 +93,10 @@ public:
         mHasScissor = true;
     }
 
+    void setScissor(backend::Viewport const& viewport) noexcept {
+        setScissor(viewport.left, viewport.bottom, viewport.width, viewport.height);
+    }
+
     void unsetScissor() noexcept {
         constexpr uint32_t maxvalu = std::numeric_limits<int32_t>::max();
         mScissorRect = { 0, 0, maxvalu, maxvalu };

filament/src/details/Renderer.cpp

@@ -310,13 +310,7 @@ void FRenderer::skipFrame(uint64_t vsyncSteadyClockTimeNano) {
     engine.flush();     // flush command stream
 
     // Run GC
-    JobSystem& js = engine.getJobSystem();
-    auto *rootJob = js.createJob();
-    js.run(jobs::createJob(js, rootJob, &FEngine::gcManagers, &engine)); // gc all component managers
-    if (engine.isAsynchronousModeEnabled()) {
-        js.run(jobs::createJob(js, rootJob, &FEngine::gcDeferredAsyncObjectDestruction, &engine));
-    }
-    js.runAndWait(rootJob);
+    engine.gc();
 
     mFrameSkipper.frameSkipped();
 }
@@ -518,13 +512,7 @@ void FRenderer::endFrame() {
     engine.flush();     // flush command stream
 
     // Run GC
-    JobSystem& js = engine.getJobSystem();
-    auto *rootJob = js.createJob();
-    js.run(jobs::createJob(js, rootJob, &FEngine::gcManagers, &engine)); // gc all component managers
-    if (engine.isAsynchronousModeEnabled()) {
-        js.run(jobs::createJob(js, rootJob, &FEngine::gcDeferredAsyncObjectDestruction, &engine));
-    }
-    js.runAndWait(rootJob);
+    engine.gc();
 }
 
 void FRenderer::readPixels(
@@ -969,10 +957,7 @@ void FRenderer::renderJob(DriverApi& driver, RootArenaScope& rootArenaScope, FVi
     variant.setDirectionalLighting(view.hasDirectionalLighting());
     variant.setDynamicLighting(view.hasDynamicLighting());
     variant.setFog(view.hasFog());
-    // The VSM bit has a different meaning for STANDARD_VARIANT (as opposed to DEPTH_VARIANT),
-    // In the STANDARD_VARIANT case, we are *using* the shadow-map, and the VSM only decides which
-    // type of sampler is used (samplerShadow or sampler2D).
-    variant.setVsm(view.hasShadowing() && view.getShadowType() != ShadowType::PCF);
+    variant.setShadowSampler2D(view.hasShadowing() && view.getShadowType() != ShadowType::PCF);
     variant.setStereo(view.hasStereo());
 
     /*
@@ -981,10 +966,7 @@ void FRenderer::renderJob(DriverApi& driver, RootArenaScope& rootArenaScope, FVi
 
     if (view.needsShadowMap()) {
         Variant shadowVariant(Variant::DEPTH_VARIANT);
-        // The VSM bit has a different meaning for DEPTH_VARIANT (as opposed to STANDARD_VARIANT),
-        // In the DEPTH_VARIANT case, we are *generating* the shadow-map, and some computations
-        // are handled differently. In addition, the color buffer is used.
-        shadowVariant.setVsm(view.getShadowType() == ShadowType::VSM);
+        shadowVariant.setDepthMoments(view.getShadowType() == ShadowType::VSM);
 
         auto shadows = view.renderShadowMaps(engine, fg, cameraInfo, mShaderUserTime,
                 RenderPassBuilder{ commandArena }

filament/src/details/View.cpp

@@ -76,6 +76,7 @@
 #include <cmath>
 #include <chrono>
 #include <functional>
+#include <limits>
 #include <memory>
 #include <new>
 #include <ratio>
@@ -143,7 +144,7 @@ FView::FView(FEngine& engine)
 #ifndef NDEBUG
     // This can fail if another view has already registered this data source
     mDebugState->owner = debugRegistry.registerDataSource("d.view.frame_info",
-            [weak = std::weak_ptr(mDebugState)]() -> DebugRegistry::DataSource {
+            [weak = std::weak_ptr<DebugState>(mDebugState)]() -> DebugRegistry::DataSource {
                 // the View could have been destroyed by the time we do this
                 auto const state = weak.lock();
                 if (!state) {
@@ -1131,8 +1132,6 @@ void FView::prepareShadowMapping() const noexcept {
         uniforms = mShadowMapManager->getShadowMappingUniforms();
     }
 
-    constexpr float low  = 5.54f; // ~ std::log(std::numeric_limits<math::half>::max()) * 0.5f;
-    constexpr float high = 42.0f; // ~ std::log(std::numeric_limits<float>::max()) * 0.5f;
     constexpr uint32_t SHADOW_SAMPLING_RUNTIME_PCF = 0u;
     constexpr uint32_t SHADOW_SAMPLING_RUNTIME_EVSM = 1u;
     constexpr uint32_t SHADOW_SAMPLING_RUNTIME_DPCF = 2u;
@@ -1148,8 +1147,8 @@ void FView::prepareShadowMapping() const noexcept {
             break;
         case ShadowType::VSM:
             s.shadowSamplingType = SHADOW_SAMPLING_RUNTIME_EVSM;
-            s.vsmExponent = mVsmShadowOptions.highPrecision ? high : low;
-            s.vsmDepthScale = mVsmShadowOptions.minVarianceScale * 0.01f * s.vsmExponent;
+            s.vsmExponent = 0; // this is only used when rendering the shadowmap, not when using it
+            s.vsmMaxMoment = ShadowMapManager::getMaxMomentEVSM(mVsmShadowOptions);
             s.vsmLightBleedReduction = mVsmShadowOptions.lightBleedReduction;
             break;
         case ShadowType::DPCF:

filament/src/ds/ShadowMapDescriptorSet.cpp

@@ -28,9 +28,11 @@
 
 #include <utils/debug.h>
 
+#include <math/half.h>
 #include <math/vec4.h>
 
 #include <array>
+#include <limits>
 
 namespace filament {
 
@@ -74,8 +76,8 @@ void ShadowMapDescriptorSet::prepareLodBias(Transaction const& transaction, floa
 }
 
 void ShadowMapDescriptorSet::prepareViewport(Transaction const& transaction,
-        backend::Viewport const& viewport) noexcept {
-    PerViewDescriptorSetUtils::prepareViewport(edit(transaction), viewport, viewport);
+        backend::Viewport const& physicalViewport, backend::Viewport const& logicalViewport) noexcept {
+    PerViewDescriptorSetUtils::prepareViewport(edit(transaction), physicalViewport, logicalViewport);
     // TODO: offset calculation is now different
 }
 
@@ -90,11 +92,10 @@ void ShadowMapDescriptorSet::prepareMaterialGlobals(Transaction const& transacti
 }
 
 void ShadowMapDescriptorSet::prepareShadowMapping(Transaction const& transaction,
-        bool const highPrecision) noexcept {
+        float const vsmExponent, float const vsmMaxMoment) noexcept {
     auto& s = edit(transaction);
-    constexpr float low  = 5.54f; // ~ std::log(std::numeric_limits<math::half>::max()) * 0.5f;
-    constexpr float high = 42.0f; // ~ std::log(std::numeric_limits<float>::max()) * 0.5f;
-    s.vsmExponent = highPrecision ? high : low;
+    s.vsmExponent = vsmExponent;
+    s.vsmMaxMoment = vsmMaxMoment;
 }
 
 ShadowMapDescriptorSet::Transaction ShadowMapDescriptorSet::open(DriverApi& driver) noexcept {

filament/src/ds/ShadowMapDescriptorSet.h

@@ -66,7 +66,7 @@ public:
             float bias) noexcept;
 
     static void prepareViewport(Transaction const& transaction,
-            backend::Viewport const& viewport) noexcept;
+            backend::Viewport const& physicalViewport, backend::Viewport const& logicalViewport) noexcept;
 
     static void prepareTime(Transaction const& transaction,
             FEngine const& engine, math::float4 const& userTime) noexcept;
@@ -75,7 +75,7 @@ public:
             std::array<math::float4, 4> const& materialGlobals) noexcept;
 
     static void prepareShadowMapping(Transaction const& transaction,
-            bool highPrecision) noexcept;
+            float vsmExponent, float vsmMaxMoment) noexcept;
 
     static Transaction open(backend::DriverApi& driver) noexcept;
 

filament/src/materials/vsmMipmap.mat

@@ -19,7 +19,8 @@ material {
         {
             name : color,
             target : color,
-            type : float4
+            type : float4,
+            precision : high
         }
     ],
     domain : postprocess,
@@ -30,8 +31,29 @@ material {
 
 fragment {
     void postProcess(inout PostProcessInputs postProcess) {
-        highp vec2 uv = gl_FragCoord.xy * materialParams.uvscale;
-        postProcess.color = textureLod(materialParams_color,
-                vec3(uv, materialParams.layer), 0.0);
+        // For EVSM mipmapping, we use a custom box filter (instead of the GPU's bilinear filter), because GPUs often
+        // use a lower precision for texture interpolation and EVSM moments are very sensitive to that.
+
+        highp ivec2 destCoord = ivec2(gl_FragCoord.xy);
+        highp ivec3 srcCoord = ivec3(destCoord * 2, materialParams.layer);
+
+#if defined(TARGET_WEBGPU_ENVIRONMENT)
+        // it looks like WebGPU doesn't support texelFetchOffset
+        highp vec4 m0 = texelFetch(materialParams_color, ivec3(srcCoord.xy + ivec2(0, 0), srcCoord.z), 0);
+        highp vec4 m1 = texelFetch(materialParams_color, ivec3(srcCoord.xy + ivec2(1, 0), srcCoord.z), 0);
+        highp vec4 m2 = texelFetch(materialParams_color, ivec3(srcCoord.xy + ivec2(0, 1), srcCoord.z), 0);
+        highp vec4 m3 = texelFetch(materialParams_color, ivec3(srcCoord.xy + ivec2(1, 1), srcCoord.z), 0);
+#else
+        highp vec4 m0 = texelFetchOffset(materialParams_color, srcCoord, 0, ivec2(0, 0));
+        highp vec4 m1 = texelFetchOffset(materialParams_color, srcCoord, 0, ivec2(1, 0));
+        highp vec4 m2 = texelFetchOffset(materialParams_color, srcCoord, 0, ivec2(0, 1));
+        highp vec4 m3 = texelFetchOffset(materialParams_color, srcCoord, 0, ivec2(1, 1));
+#endif
+
+        // Make sure to not overflow the moments when averaging them
+        postProcess.color = (m0 * 0.25) +
+                            (m1 * 0.25) +
+                            (m2 * 0.25) +
+                            (m3 * 0.25);
     }
 }

ios/CocoaPods/Filament.podspec

@@ -1,12 +1,12 @@
 Pod::Spec.new do |spec|
   spec.name = "Filament"
-  spec.version = "1.69.3"
+  spec.version = "1.69.5"
   spec.license = { :type => "Apache 2.0", :file => "LICENSE" }
   spec.homepage = "https://google.github.io/filament"
   spec.authors = "Google LLC."
   spec.summary = "Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WASM/WebGL."
   spec.platform = :ios, "11.0"
-  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.69.3/filament-v1.69.3-ios.tgz" }
+  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.69.5/filament-v1.69.5-ios.tgz" }
 
   spec.libraries = 'c++'
 

libs/filabridge/include/private/filament/DescriptorSets.h

@@ -36,7 +36,7 @@ backend::DescriptorSetLayout const& getPerRenderableLayout() noexcept;
 backend::DescriptorSetLayout getPerViewDescriptorSetLayout(
         MaterialDomain domain,
         bool isLit, bool isSSR, bool hasFog,
-        bool isVSM) noexcept;
+        bool isShadowSampler2D) noexcept;
 
 backend::DescriptorSetLayout getPerViewDescriptorSetLayoutWithVariant(
         Variant variant,

libs/filabridge/include/private/filament/EngineEnums.h

@@ -85,6 +85,9 @@ enum class ReservedSpecializationConstants : uint8_t {
     CONFIG_SH_BANDS_COUNT = 9,
     CONFIG_SHADOW_SAMPLING_METHOD = 10,
     CONFIG_FROXEL_RECORD_BUFFER_HEIGHT = 11,
+    CONFIG_HAS_DIRECTIONAL_LIGHTING = 12,
+    CONFIG_HAS_DYNAMIC_LIGHTING = 13,
+    CONFIG_HAS_SHADOWING = 14,
     // check CONFIG_NEXT_RESERVED_SPEC_CONSTANT and CONFIG_MAX_RESERVED_SPEC_CONSTANTS below
 };
 
@@ -107,7 +110,7 @@ constexpr size_t CONFIG_MAX_LIGHT_INDEX = CONFIG_MAX_LIGHT_COUNT - 1;
 // Updating this value necessitates a material version bump.
 constexpr size_t CONFIG_MAX_RESERVED_SPEC_CONSTANTS = 16;
 // The number of the next unassigned reserved spec constant.
-constexpr size_t CONFIG_NEXT_RESERVED_SPEC_CONSTANT = 12;
+constexpr size_t CONFIG_NEXT_RESERVED_SPEC_CONSTANT = 15;
 
 // The maximum number of shadow maps possible.
 // There is currently a maximum limit of 128 shadow maps.

libs/filabridge/include/private/filament/UibStructs.h

@@ -166,7 +166,7 @@ struct PerViewUib { // NOLINT(cppcoreguidelines-pro-type-member-init)
     // VSM shadows [variant: VSM]
     // --------------------------------------------------------------------------------------------
     float vsmExponent;
-    float vsmDepthScale;
+    float vsmMaxMoment;
     float vsmLightBleedReduction;
     uint32_t shadowSamplingType;                // 0: vsm, 1: dpcf
 
@@ -299,13 +299,12 @@ struct ShadowUib { // NOLINT(cppcoreguidelines-pro-type-member-init)
         math::mat4f lightFromWorldMatrix;       // 64
         math::float4 lightFromWorldZ;           // 16
         math::float4 scissorNormalized;         // 16
-        float texelSizeAtOneMeter;              //  4
         float bulbRadiusLs;                     //  4
         float nearOverFarMinusNear;             //  4
-        float normalBias;                       //  4
-        bool elvsm;                             //  4
-        uint32_t layer;                         //  4
-        uint32_t reserved1;                     //  4
+        math::float2 normalBias;                //  4
+        bool elvsm;                             //  4   // could be 1 bit
+        uint32_t layer;                         //  4   // could be 8 bits
+        float vsmExponent;                      //  4   // could be fp16
         uint32_t reserved2;                     //  4
     };
     ShadowData shadows[CONFIG_MAX_SHADOWMAPS];

libs/filabridge/include/private/filament/Variant.h

@@ -48,20 +48,21 @@ struct Variant {
     // SRE: Shadow Receiver
     // SKN: Skinning
     // DEP: Depth only
-    // FOG: Fog
-    // PCK: Picking (depth variant only)
-    // VSM: Variance shadow maps (depth) / sampler type (standard)
+    // FOG: Fog (standard)
+    // PCK: Picking (depth)
+    // MNT: Output depth moments (depth)
+    // S2D: Sampler type for shadows (0: samplerShadowArray, 1: sampler2DArray) (standard)
     // STE: Instanced stereo rendering
     //
     //   X: either 1 or 0
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
-    // Variant              | STE | VSM | FOG | DEP | SKN | SRE | DYN | DIR |   256
+    // Variant              | STE | S2D | FOG | DEP | SKN | SRE | DYN | DIR |   256
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
-    //                                    PCK
+    //                              MNT   PCK
     //
     // Standard variants:
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
-    //                      | STE | VSM | FOG |  0  | SKN | SRE | DYN | DIR |    128 - 44 = 84
+    //                      | STE | S2D | FOG |  0  | SKN | SRE | DYN | DIR |    128 - 44 = 84
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
     //      Vertex shader      X     0     0     0     X     X     X     X
     //    Fragment shader      0     X     X     0     0     X     X     X
@@ -72,7 +73,7 @@ struct Variant {
     //
     // Depth variants:
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
-    //                      | STE | VSM | PCK |  1  | SKN |  0  |  0  |  0  |   16 - 4 = 12
+    //                      | STE | MNT | PCK |  1  | SKN |  0  |  0  |  0  |   16 - 4 = 12
     //                      +-----+-----+-----+-----+-----+-----+-----+-----+
     //       Vertex depth      X     X     0     1     X     0     0     0
     //     Fragment depth      0     0     X     1     0     0     0     0
@@ -96,13 +97,15 @@ struct Variant {
     static constexpr type_t DEP   = 0x10; // depth only variants
     static constexpr type_t FOG   = 0x20; // fog (standard)
     static constexpr type_t PCK   = 0x20; // picking (depth)
-    static constexpr type_t VSM   = 0x40; // variance shadow maps / sampler type
+    static constexpr type_t S2D   = 0x40; // sampler type
+    static constexpr type_t MNT   = 0x40; // variance shadow maps
     static constexpr type_t STE   = 0x80; // instanced stereo
 
     static constexpr type_t NO_VARIANT         = 0u;
 
     // special variants (variants that use the reserved space)
-    static constexpr type_t SPECIAL_SSR   = VSM | SRE; // screen-space reflections variant
+    static constexpr type_t SPECIAL_SSR_VARIANT=       S2D |       SRE            ;
+    static constexpr type_t SPECIAL_SSR_MASK   = STE | S2D | DEP | SRE | DYN | DIR;
 
     static constexpr type_t STANDARD_MASK      = DEP;
     static constexpr type_t STANDARD_VARIANT   = 0u;
@@ -127,29 +130,30 @@ struct Variant {
     void setSkinning(bool v) noexcept            { set(v, SKN); }
     void setFog(bool v) noexcept                 { set(v, FOG); }
     void setPicking(bool v) noexcept             { set(v, PCK); }
-    void setVsm(bool v) noexcept                 { set(v, VSM); }
+    void setShadowSampler2D(bool v) noexcept     { set(v, S2D); }
+    void setDepthMoments(bool v) noexcept        { set(v, MNT); }
     void setStereo(bool v) noexcept              { set(v, STE); }
 
     static constexpr bool isValidDepthVariant(Variant variant) noexcept {
         // Can't have VSM and PICKING together with DEPTH variants
-        constexpr type_t RESERVED_MASK  = VSM | PCK | DEP | SRE | DYN | DIR;
-        constexpr type_t RESERVED_VALUE = VSM | PCK | DEP;
+        constexpr type_t RESERVED_MASK  = MNT | PCK | DEP | SRE | DYN | DIR;
+        constexpr type_t RESERVED_VALUE = MNT | PCK | DEP;
         return ((variant.key & DEPTH_MASK) == DEPTH_VARIANT) &&
                ((variant.key & RESERVED_MASK) != RESERVED_VALUE);
    }
 
     static constexpr bool isValidStandardVariant(Variant variant) noexcept {
         // can't have shadow receiver if we don't have any lighting
-        constexpr type_t RESERVED0_MASK  = VSM | FOG | SRE | DYN | DIR;
-        constexpr type_t RESERVED0_VALUE = VSM | FOG | SRE;
+        constexpr type_t RESERVED0_MASK  = S2D | FOG | SRE | DYN | DIR;
+        constexpr type_t RESERVED0_VALUE = S2D | FOG | SRE;
 
         // can't have shadow receiver if we don't have any lighting
-        constexpr type_t RESERVED1_MASK  = VSM | SRE | DYN | DIR;
+        constexpr type_t RESERVED1_MASK  = S2D | SRE | DYN | DIR;
         constexpr type_t RESERVED1_VALUE = SRE;
 
         // can't have VSM without shadow receiver
-        constexpr type_t RESERVED2_MASK  = VSM | SRE;
-        constexpr type_t RESERVED2_VALUE = VSM;
+        constexpr type_t RESERVED2_MASK  = S2D | SRE;
+        constexpr type_t RESERVED2_VALUE = S2D;
 
         return ((variant.key & STANDARD_MASK) == STANDARD_VARIANT) &&
                ((variant.key & RESERVED0_MASK) != RESERVED0_VALUE) &&
@@ -174,11 +178,15 @@ struct Variant {
     }
 
     static constexpr bool isSSRVariant(Variant variant) noexcept {
-        return (variant.key & (STE | VSM | DEP | SRE | DYN | DIR)) == (VSM | SRE);
+        return (variant.key & SPECIAL_SSR_MASK) == SPECIAL_SSR_VARIANT;
     }
 
-    static constexpr bool isVSMVariant(Variant variant) noexcept {
-        return !isSSRVariant(variant) && ((variant.key & VSM) == VSM);
+    static constexpr bool isShadowSampler2DVariant(Variant variant) noexcept {
+        return !isSSRVariant(variant) && ((variant.key & (S2D | DEP)) == S2D);
+    }
+
+    static constexpr bool isDepthMomentsVariant(Variant variant) noexcept {
+        return !isSSRVariant(variant) && ((variant.key & (MNT | DEP)) == (MNT | DEP));
     }
 
     static constexpr bool isShadowReceiverVariant(Variant variant) noexcept {
@@ -202,13 +210,13 @@ struct Variant {
         // vertex shader.
         if ((variant.key & STANDARD_MASK) == STANDARD_VARIANT) {
             if (isSSRVariant(variant)) {
-                variant.key &= ~(VSM | SRE);
+                variant.key &= ~SPECIAL_SSR_VARIANT;
             }
             return variant & (STE | SKN | SRE | DYN | DIR);
         }
         if ((variant.key & DEPTH_MASK) == DEPTH_VARIANT) {
-            // Only VSM, skinning, and stereo affect the vertex shader's DEPTH variant
-            return variant & (STE | VSM | SKN | DEP);
+            // Only MNT, skinning, and stereo affect the vertex shader's DEPTH variant
+            return variant & (STE | MNT | SKN | DEP);
         }
         return {};
     }
@@ -217,11 +225,11 @@ struct Variant {
         // filter out fragment variants that are not needed. For e.g. skinning doesn't
         // affect the fragment shader.
         if ((variant.key & STANDARD_MASK) == STANDARD_VARIANT) {
-            return variant & (VSM | FOG | SRE | DYN | DIR);
+            return variant & (S2D | FOG | SRE | DYN | DIR);
         }
         if ((variant.key & DEPTH_MASK) == DEPTH_VARIANT) {
             // Only VSM & PICKING affects the fragment shader's DEPTH variant
-            return variant & (VSM | PCK | DEP);
+            return variant & (MNT | PCK | DEP);
         }
         return {};
     }
@@ -230,8 +238,8 @@ struct Variant {
         // special case for depth variant
         if (isValidDepthVariant(variant)) {
             if (!isLit) {
-                // if we're unlit, we never need the VSM variant
-                return variant & ~VSM;
+                // if we're unlit, we never need the MNT variant
+                return variant & ~MNT;
             }
             return variant;
         }
@@ -242,9 +250,9 @@ struct Variant {
             // when the shading mode is unlit, remove all the lighting variants
             return variant & UNLIT_MASK;
         }
-        // if shadow receiver is disabled, turn off VSM
+        // if shadow receiver is disabled, we pick the shadow sampler
         if (!(variant.key & SRE)) {
-            return variant & ~VSM;
+            return variant & ~S2D;
         }
         return variant;
     }

libs/filabridge/src/DescriptorSets.cpp

@@ -216,7 +216,7 @@ utils::CString getDescriptorName(DescriptorSetBindingPoints const set,
 DescriptorSetLayout getPerViewDescriptorSetLayout(
         MaterialDomain const domain,
         bool const isLit, bool const isSSR, bool const hasFog,
-        bool const isVSM) noexcept {
+        bool const isShadowSampler2D) noexcept {
 
     switch (domain) {
         case MaterialDomain::SURFACE: {
@@ -255,7 +255,7 @@ DescriptorSetLayout getPerViewDescriptorSetLayout(
             }
 
             // change the SHADOW_MAP descriptor type for VSM
-            if (isVSM) {
+            if (isShadowSampler2D) {
                 auto const pos = std::find_if(layout.descriptors.begin(), layout.descriptors.end(),
                         [](auto const& v) {
                             return v.binding == PerViewBindingPoints::SHADOW_MAP;
@@ -285,8 +285,7 @@ DescriptorSetLayout getPerViewDescriptorSetLayoutWithVariant(
         return ssrVariantDescriptorSetLayout;
     }
     // We need to filter out all the descriptors not included in the "resolved" layout below
-    return getPerViewDescriptorSetLayout(domain, isLit, isSSR, hasFog,
-            Variant::isVSMVariant(variant));
+    return getPerViewDescriptorSetLayout(domain, isLit, isSSR, hasFog, Variant::isShadowSampler2DVariant(variant));
 }
 
 DescriptorType getDescriptorType(SamplerType const type, SamplerFormat const format) {

libs/filabridge/src/Variant.cpp

@@ -32,41 +32,46 @@ namespace filament {
 Variant Variant::filterUserVariant(
         Variant variant, UserVariantFilterMask filterMask) noexcept {
     // these are easy to filter by just removing the corresponding bit
-    if (filterMask & (uint32_t)UserVariantFilterBit::DIRECTIONAL_LIGHTING) {
+    if (filterMask & uint32_t(UserVariantFilterBit::DIRECTIONAL_LIGHTING)) {
         variant.key &= ~DIR;
     }
-    if (filterMask & (uint32_t)UserVariantFilterBit::DYNAMIC_LIGHTING) {
+
+    if (filterMask & uint32_t(UserVariantFilterBit::DYNAMIC_LIGHTING)) {
         variant.key &= ~DYN;
     }
-    if (filterMask & (uint32_t)UserVariantFilterBit::SKINNING) {
+
+    if (filterMask & uint32_t(UserVariantFilterBit::SKINNING)) {
         variant.key &= ~SKN;
     }
-    if (filterMask & (uint32_t)UserVariantFilterBit::STE) {
+
+    if (filterMask & uint32_t(UserVariantFilterBit::STE)) {
         variant.key &= ~(filterMask & STE);
     }
-    if (!isValidDepthVariant(variant)) {
-        // we can't remove FOG from depth variants, this would, in fact, remove picking
-        if (filterMask & (uint32_t)UserVariantFilterBit::FOG) {
-            variant.key &= ~FOG;
+
+    if (isValidDepthVariant(variant)) {
+        // depth variants can have their MNT bit filtered
+        if (filterMask & uint32_t(UserVariantFilterBit::VSM)) {
+            variant.key &= ~MNT;
         }
     } else {
-        // depth variants can have their VSM bit filtered
-        if (filterMask & (uint32_t)UserVariantFilterBit::VSM) {
-            variant.key &= ~VSM;
+        // we can't remove FOG from depth variants, this would, in fact, remove picking
+        if (filterMask & uint32_t(UserVariantFilterBit::FOG)) {
+            variant.key &= ~FOG;
         }
     }
+
     if (!isSSRVariant(variant)) {
         // SSR variant needs to be handled separately
-        if (filterMask & (uint32_t)UserVariantFilterBit::SHADOW_RECEIVER) {
+        if (filterMask & uint32_t(UserVariantFilterBit::SHADOW_RECEIVER)) {
             variant.key &= ~SRE;
         }
-        if (filterMask & (uint32_t)UserVariantFilterBit::VSM) {
-            variant.key &= ~VSM;
+        if (filterMask & uint32_t(UserVariantFilterBit::VSM)) {
+            variant.key &= ~S2D;
         }
     } else {
         // see if we need to filter out the SSR variants
-        if (filterMask & (uint32_t)UserVariantFilterBit::SSR) {
-            variant.key &= ~SPECIAL_SSR;
+        if (filterMask & uint32_t(UserVariantFilterBit::SSR)) {
+            variant.key &= ~SPECIAL_SSR_VARIANT;
         }
     }
     return variant;

libs/filamat/src/shaders/CodeGenerator.cpp

@@ -358,6 +358,21 @@ utils::io::sstream& CodeGenerator::generateCommonProlog(utils::io::sstream& out,
                 +ReservedSpecializationConstants::CONFIG_SRGB_SWAPCHAIN_EMULATION, false);
     }
 
+    // Generate specialization constants for "minor variants".
+    //
+    // HACK: Setting the default values like this is a temporary measure for switching variants to
+    // spec constants.
+    bool const litVariants = material.isLit || material.hasShadowMultiplier;
+    generateSpecializationConstant(out, "CONFIG_HAS_DIRECTIONAL_LIGHTING",
+            +ReservedSpecializationConstants::CONFIG_HAS_DIRECTIONAL_LIGHTING,
+            litVariants && v.hasDirectionalLighting());
+    generateSpecializationConstant(out, "CONFIG_HAS_DYNAMIC_LIGHTING",
+            +ReservedSpecializationConstants::CONFIG_HAS_DYNAMIC_LIGHTING,
+            litVariants && v.hasDynamicLighting());
+    generateSpecializationConstant(out, "CONFIG_HAS_SHADOWING",
+            +ReservedSpecializationConstants::CONFIG_HAS_SHADOWING,
+            litVariants && filament::Variant::isShadowReceiverVariant(v));
+
     out << '\n';
     out << SHADERS_COMMON_DEFINES_GLSL_DATA;
 
@@ -1160,10 +1175,9 @@ io::sstream& CodeGenerator::generateSurfaceLit(io::sstream& out, ShaderStage sta
         filament::Variant variant, Shading shading, bool customSurfaceShading) {
     if (stage == ShaderStage::FRAGMENT) {
         out << SHADERS_SURFACE_LIGHTING_FS_DATA;
-        if (filament::Variant::isShadowReceiverVariant(variant)) {
+        if (!filament::Variant::isSSRVariant(variant)) {
             out << SHADERS_SURFACE_SHADOWING_FS_DATA;
         }
-
         // the only reason we have this assert here is that we used to have a check,
         // which seemed unnecessary.
         assert_invariant(shading != Shading::UNLIT);
@@ -1191,14 +1205,8 @@ io::sstream& CodeGenerator::generateSurfaceLit(io::sstream& out, ShaderStage sta
 
         out << SHADERS_SURFACE_AMBIENT_OCCLUSION_FS_DATA;
         out << SHADERS_SURFACE_LIGHT_INDIRECT_FS_DATA;
-
-        if (variant.hasDirectionalLighting()) {
-            out << SHADERS_SURFACE_LIGHT_DIRECTIONAL_FS_DATA;
-        }
-        if (variant.hasDynamicLighting()) {
-            out << SHADERS_SURFACE_LIGHT_PUNCTUAL_FS_DATA;
-        }
-
+        out << SHADERS_SURFACE_LIGHT_DIRECTIONAL_FS_DATA;
+        out << SHADERS_SURFACE_LIGHT_PUNCTUAL_FS_DATA;
         out << SHADERS_SURFACE_SHADING_LIT_FS_DATA;
     }
     return out;
@@ -1207,10 +1215,8 @@ io::sstream& CodeGenerator::generateSurfaceLit(io::sstream& out, ShaderStage sta
 io::sstream& CodeGenerator::generateSurfaceUnlit(io::sstream& out, ShaderStage stage,
         filament::Variant variant, bool hasShadowMultiplier) {
     if (stage == ShaderStage::FRAGMENT) {
-        if (hasShadowMultiplier) {
-            if (filament::Variant::isShadowReceiverVariant(variant)) {
-                out << SHADERS_SURFACE_SHADOWING_FS_DATA;
-            }
+        if (hasShadowMultiplier && !filament::Variant::isSSRVariant(variant)) {
+            out << SHADERS_SURFACE_SHADOWING_FS_DATA;
         }
         out << SHADERS_SURFACE_SHADING_UNLIT_FS_DATA;
     }

libs/filamat/src/shaders/ShaderGenerator.cpp

@@ -51,16 +51,9 @@ void ShaderGenerator::generateSurfaceMaterialVariantDefines(io::sstream& out,
         ShaderStage const stage, MaterialBuilder::FeatureLevel featureLevel,
         MaterialInfo const& material, filament::Variant const variant) noexcept {
 
-    bool const litVariants = material.isLit || material.hasShadowMultiplier;
-
-    CodeGenerator::generateDefine(out, "VARIANT_HAS_DIRECTIONAL_LIGHTING",
-            litVariants && variant.hasDirectionalLighting());
-    CodeGenerator::generateDefine(out, "VARIANT_HAS_DYNAMIC_LIGHTING",
-            litVariants && variant.hasDynamicLighting());
-    CodeGenerator::generateDefine(out, "VARIANT_HAS_SHADOWING",
-            litVariants && filament::Variant::isShadowReceiverVariant(variant));
     CodeGenerator::generateDefine(out, "VARIANT_HAS_VSM",
-            filament::Variant::isVSMVariant(variant));
+            filament::Variant::isShadowSampler2DVariant(variant) ||
+            filament::Variant::isDepthMomentsVariant(variant));
     CodeGenerator::generateDefine(out, "VARIANT_HAS_STEREO",
             hasStereo(variant, featureLevel));
     CodeGenerator::generateDefine(out, "VARIANT_DEPTH",
@@ -89,6 +82,8 @@ void ShaderGenerator::generateSurfaceMaterialVariantDefines(io::sstream& out,
     CodeGenerator::generateDefine(out, "MATERIAL_HAS_SHADOW_MULTIPLIER",
             material.hasShadowMultiplier);
 
+    CodeGenerator::generateDefine(out, "MATERIAL_HAS_LIGHTING", hasLighting(material, variant));
+
     CodeGenerator::generateDefine(out, "MATERIAL_HAS_INSTANCES", material.instanced);
 
     CodeGenerator::generateDefine(out, "MATERIAL_HAS_VERTEX_DOMAIN_DEVICE_JITTERED",
@@ -464,8 +459,7 @@ std::string ShaderGenerator::createSurfaceVertexProgram(ShaderModel const shader
             +PerRenderableBindingPoints::OBJECT_UNIFORMS,
             UibGenerator::getPerRenderableUib());
 
-    const bool litVariants = material.isLit || material.hasShadowMultiplier;
-    if (litVariants && filament::Variant::isShadowReceiverVariant(variant)) {
+    if (hasLighting(material, variant)) {
         cg.generateUniforms(vs, ShaderStage::FRAGMENT,
                 DescriptorSetBindingPoints::PER_VIEW,
                 +PerViewBindingPoints::SHADOWS,
@@ -572,22 +566,17 @@ std::string ShaderGenerator::createSurfaceFragmentProgram(ShaderModel const shad
             +PerRenderableBindingPoints::OBJECT_UNIFORMS,
             UibGenerator::getPerRenderableUib());
 
-    if (variant.hasDynamicLighting()) {
+    if (hasLighting(material, variant)) {
         cg.generateUniforms(fs, ShaderStage::FRAGMENT,
                 DescriptorSetBindingPoints::PER_VIEW,
                 +PerViewBindingPoints::LIGHTS,
                 UibGenerator::getLightsUib());
-    }
 
-    bool const litVariants = material.isLit || material.hasShadowMultiplier;
-    if (litVariants && filament::Variant::isShadowReceiverVariant(variant)) {
         cg.generateUniforms(fs, ShaderStage::FRAGMENT,
                 DescriptorSetBindingPoints::PER_VIEW,
                 +PerViewBindingPoints::SHADOWS,
                 UibGenerator::getShadowUib());
-    }
 
-    if (variant.hasDynamicLighting()) {
         cg.generateUniforms(fs, ShaderStage::FRAGMENT,
                 DescriptorSetBindingPoints::PER_VIEW,
                 +PerViewBindingPoints::RECORD_BUFFER,
@@ -836,4 +825,10 @@ bool ShaderGenerator::hasStereo(
             && featureLevel > MaterialBuilder::FeatureLevel::FEATURE_LEVEL_0;
 }
 
+bool ShaderGenerator::hasLighting(
+        MaterialInfo const& material, filament::Variant const variant) noexcept {
+    return (material.isLit || material.hasShadowMultiplier)
+            && !filament::Variant::isSSRVariant(variant);
+}
+
 } // namespace filament

libs/filamat/src/shaders/ShaderGenerator.h

@@ -130,6 +130,8 @@ private:
             filament::Variant variant,
             MaterialBuilder::FeatureLevel featureLevel) noexcept;
 
+    static bool hasLighting(MaterialInfo const& material, filament::Variant variant) noexcept;
+
     MaterialBuilder::PropertyList mProperties;
     MaterialBuilder::VariableList mVariables;
     MaterialBuilder::OutputList mOutputs;

libs/filamat/src/shaders/SibGenerator.cpp

@@ -49,7 +49,7 @@ SamplerInterfaceBlock const& SibGenerator::getPerViewSib(Variant variant) noexce
     // reason we name them "unused*" to ensure we're not using them by mistake (type/format don't
     // matter).
 
-    static SamplerInterfaceBlock const sibPcf{ SamplerInterfaceBlock::Builder()
+    static SamplerInterfaceBlock const sibShadowSamplerPcf{ SamplerInterfaceBlock::Builder()
             .name("sampler0")
             .stageFlags(backend::ShaderStageFlags::FRAGMENT)
             .add(  {{ "shadowMap",   +PerViewBindingPoints::SHADOW_MAP,     Type::SAMPLER_2D_ARRAY, Format::SHADOW, Precision::MEDIUM, FILTERABLE, !MULTISAMPLE, ALL_STAGES },
@@ -62,7 +62,7 @@ SamplerInterfaceBlock const& SibGenerator::getPerViewSib(Variant variant) noexce
             )
             .build() };
 
-    static SamplerInterfaceBlock const sibVsm{ SamplerInterfaceBlock::Builder()
+    static SamplerInterfaceBlock const sibShadowSampler2D{ SamplerInterfaceBlock::Builder()
             .name("sampler0")
             .stageFlags(backend::ShaderStageFlags::FRAGMENT)
             .add(  {{ "shadowMap",   +PerViewBindingPoints::SHADOW_MAP,     Type::SAMPLER_2D_ARRAY, Format::FLOAT,  Precision::HIGH,   FILTERABLE, !MULTISAMPLE, ALL_STAGES },
@@ -85,10 +85,10 @@ SamplerInterfaceBlock const& SibGenerator::getPerViewSib(Variant variant) noexce
 
     if (Variant::isSSRVariant(variant)) {
         return sibSsr;
-    } else if (Variant::isVSMVariant(variant)) {
-        return sibVsm;
+    } else if (Variant::isShadowSampler2DVariant(variant)) {
+        return sibShadowSampler2D;
     } else {
-        return sibPcf;
+        return sibShadowSamplerPcf;
     }
 }
 

libs/filamat/src/shaders/UibGenerator.cpp

@@ -175,7 +175,7 @@ BufferInterfaceBlock const& UibGenerator::getPerViewUib() noexcept  {
             // VSM shadows [variant: VSM]
             // ------------------------------------------------------------------------------------
             { "vsmExponent",             0, Type::FLOAT                  },
-            { "vsmDepthScale",           0, Type::FLOAT                  },
+            { "vsmMaxMoment",            0, Type::FLOAT, Precision::HIGH },
             { "vsmLightBleedReduction",  0, Type::FLOAT                  },
             { "shadowSamplingType",      0, Type::UINT                   },
 

libs/gltfio/src/FFilamentAsset.h

@@ -60,11 +60,13 @@
 #define GLTFIO_WARN(msg) slog.w << msg << io::endl
 #endif
 
+#ifndef GLTFIO_USE_FILESYSTEM
 #if defined(__EMSCRIPTEN__) || defined(__ANDROID__) || defined(FILAMENT_IOS)
 #define GLTFIO_USE_FILESYSTEM 0
 #else
 #define GLTFIO_USE_FILESYSTEM 1
 #endif
+#endif
 
 namespace utils {
     class NameComponentManager;

libs/matdbg/src/CommonWriter.cpp

@@ -48,10 +48,11 @@ std::string formatVariantString(Variant variant, MaterialDomain domain) noexcept
         if (variant.key & Variant::DEP) variantString += "DEP|";
         if (variant.key & Variant::DEP) {
             if (variant.key & Variant::PCK) variantString += "PCK|";
+            if (variant.key & Variant::MNT) variantString += "MNT|";
         } else {
             if (variant.key & Variant::FOG) variantString += "FOG|";
+            if (variant.key & Variant::S2D) variantString += "S2D|";
         }
-        if (variant.key & Variant::VSM) variantString += "VSM|";
         if (variant.key & Variant::STE) variantString += "STE|";
         variantString = variantString.substr(0, variantString.length() - 1);
     }

libs/utils/CMakeLists.txt

@@ -31,6 +31,7 @@ set(DIST_HDRS
         ${PUBLIC_HDR_DIR}/${TARGET}/Invocable.h
         ${PUBLIC_HDR_DIR}/${TARGET}/Log.h
         ${PUBLIC_HDR_DIR}/${TARGET}/Logger.h
+        ${PUBLIC_HDR_DIR}/${TARGET}/LruCache.h
         ${PUBLIC_HDR_DIR}/${TARGET}/memalign.h
         ${PUBLIC_HDR_DIR}/${TARGET}/MonotonicRingMap.h
         ${PUBLIC_HDR_DIR}/${TARGET}/Mutex.h
@@ -181,6 +182,7 @@ if (FILAMENT_BUILD_TESTING)
             test/test_FixedCircularBuffer.cpp
             test/test_Hash.cpp
             test/test_InternPool.cpp
+            test/test_LruCache.cpp
             test/test_JobSystem.cpp
             test/test_MonotonicRingMap.cpp
             test/test_QuadTreeArray.cpp

libs/utils/include/utils/LruCache.h

@@ -0,0 +1,322 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_UTILS_LRUCACHE_H
+#define TNT_UTILS_LRUCACHE_H
+
+#include <utils/Allocator.h>
+#include <utils/compiler.h>
+
+#include <tsl/robin_map.h>
+
+#include <cassert>
+#include <cstddef>
+#include <functional>
+#include <optional>
+#include <utility>
+
+namespace utils {
+
+/**
+ * A fixed-capacity Least Recently Used (LRU) cache.
+ *
+ * This container allows O(1) access, insertion, and eviction. It uses an Arena with an
+ * ObjectPoolAllocator to store the nodes of a doubly-linked list representing the LRU order,
+ * and a robin_map for fast key lookups.
+ *
+ * This class is not thread-safe. Additionally, the pop() and put() methods have special concerns
+ * with regards to object lifetimes.
+ *
+ * @tparam Key The type of the keys.
+ * @tparam T The type of the values.
+ * @tparam Hash The hasher for the keys.
+ */
+template<typename Key,
+         typename T,
+         typename Hash = std::hash<Key>,
+         typename KeyEqual = std::equal_to<Key>>
+class LruCache {
+    // If Key is bigger than a pointer, robin map keys are references to Node::key. Otherwise,
+    // they're full copies.
+    using MapKey = std::conditional_t<(sizeof(Key) > sizeof(void*)),
+            std::reference_wrapper<const Key>, Key>;
+
+public:
+    using size_type = uint32_t;
+
+    /**
+     * Creates an LRU cache with the specified capacity.
+     *
+     * @param name Name to identify the backing Arena allocator.
+     * @param capacity The maximum number of elements the cache can hold.
+     */
+    LruCache(const char* UTILS_NONNULL name, size_type capacity)
+            : mCapacity(capacity),
+              // HACK: FreeList cannot handle a capacity of 0.
+              mArena(name, (capacity ? capacity : 1) * sizeof(Node)),
+              mHead(nullptr),
+              mTail(nullptr) {
+        mMap.reserve(capacity);
+    }
+
+    ~LruCache() {
+        clear();
+    }
+
+    LruCache(const LruCache&) = delete;
+    LruCache& operator=(const LruCache&) = delete;
+    LruCache(LruCache&&) = default;
+    LruCache& operator=(LruCache&&) = default;
+
+    /**
+     * Returns a reference to the value associated with the key.
+     *
+     * Additionally moves the key/value pair to the front of the most recently used (MRU) list.
+     *
+     * @param key The key to look up.
+     * @param hash The precomputed hash of the key.
+     * @return Pointer to the value, if exists; otherwise, nullptr.
+     */
+    T* UTILS_NULLABLE get(Key const& key, size_t hash) {
+        auto it = mMap.find(key, hash);
+        if (UTILS_UNLIKELY(it == mMap.end())) {
+            return nullptr;
+        }
+
+        Node* node = it->second;
+        assert(node != nullptr);
+
+        moveToFront(node);
+
+        return &node->value;
+    }
+
+    inline T* UTILS_NULLABLE get(Key const& key) {
+        return get(key, Hash{}(key));
+    }
+
+    /**
+     * Moves the value out of the cache, if it exists.
+     *
+     * Because this moves the actual value, any previous references to this object returned by a
+     * call to get() or put() is invalidated by this call.
+     *
+     * @param key The key to look up.
+     * @param hash The precomputed hash of the key.
+     */
+    std::optional<T> pop(Key const& key, size_t hash) {
+        auto it = mMap.find(key, hash);
+        if (UTILS_UNLIKELY(it == mMap.end())) {
+            return std::nullopt;
+        }
+
+        Node* node = it->second;
+        assert(node != nullptr);
+
+        if (node == mHead && node == mTail) {
+            mHead = nullptr;
+            mTail = nullptr;
+        } else if (node == mHead) {
+            assert(node->next != nullptr);
+            mHead = node->next;
+            mHead->prev = nullptr;
+        } else if (node == mTail) {
+            assert(node->prev != nullptr);
+            mTail = node->prev;
+            mTail->next = nullptr;
+        } else {
+            assert(node->prev != nullptr);
+            assert(node->next != nullptr);
+            node->prev->next = node->next;
+            node->next->prev = node->prev;
+        }
+
+        T r = std::move(node->value);
+        mMap.erase(it);
+        mArena.destroy(node);
+        return r;
+    }
+
+    inline std::optional<T> pop(Key const& key) {
+        return pop(key, Hash{}(key));
+    }
+
+    /**
+     * Inserts a new entry or updates an existing one.
+     *
+     * Prepends it to the front of the most recently used (MRU) list. Potentially evicts the
+     * least-recently used (LRU) key/value pair by calling the releaser function.
+     *
+     * Due to the evicting nature of this function, any pointers to any objects within the LRU cache
+     * that had been previously returned by a call to get() or another call to put() can be
+     * considered INVALID and any access to them will result in undefined behavior.
+     *
+     * An evicted node is removed from the map before the releaser callback is called. Calls to
+     * get() or pop() in the body of the releaser for the item in question will fail.
+     *
+     * @tparam F Callable type accepting T&&.
+     * @param key The key to insert or update.
+     * @param t The value to insert or update.
+     * @param hash The precomputed hash of the key.
+     * @param releaser Function called with the evicted value (T&&) if eviction occurs.
+     * @return Reference to the inserted or updated value.
+     */
+    template<typename F>
+    T& put(Key key, T value, size_t hash, F releaser) {
+        // Assert that we have capacity to store at least one item
+        assert(mCapacity > 0);
+
+        auto it = mMap.find(key, hash);
+        if (it != mMap.end()) {
+            Node* node = it->second;
+            assert(node != nullptr);
+
+            moveToFront(node);
+
+            node->value = std::move(value);
+            return node->value;
+        }
+
+        if (UTILS_LIKELY(mMap.size() >= mCapacity)) {
+            evict(releaser);
+        }
+
+        // Create new node at front of list.
+        Node* node = mArena.template make<Node>(std::move(key), std::move(value), mHead);
+        assert(node != nullptr);
+        attach(node);
+
+        mMap.emplace(node->key, node);
+
+        return node->value;
+    }
+
+    template<typename F>
+    inline T& put(Key key, T value, F releaser) {
+        return put(std::move(key), std::move(value), Hash{}(key), std::move(releaser));
+    }
+
+    /**
+     * Clear the cache, calling releaser on each item evicted.
+     *
+     * @param releaser Function called with the evicted value (T&&)
+     */
+    template<typename F>
+    void clear(F releaser) {
+        // Clear map first, just in case it tries to dereference any keys.
+        mMap.clear();
+        // Destroy everything in the arena.
+        Node* node = mHead;
+        while (UTILS_LIKELY(node)) {
+            Node* next = node->next;
+            releaser(std::move(node->value));
+            mArena.destroy(node);
+            node = next;
+        }
+        mHead = nullptr;
+        mTail = nullptr;
+    }
+
+    void clear() {
+        clear([](T&&){});
+    }
+
+    /** Returns the number of elements in the cache. */
+    size_type size() const noexcept { return mMap.size(); }
+
+    /** Returns the capacity of the cache. */
+    size_type capacity() const noexcept { return mCapacity; }
+
+private:
+    struct Node {
+        Key key;
+        T value;
+        Node* UTILS_NULLABLE prev;
+        Node* UTILS_NULLABLE next;
+
+        Node(Key&& k, T&& v, Node* UTILS_NULLABLE next)
+                : key(std::move(k)),
+                  value(std::move(v)),
+                  prev(nullptr),
+                  next(next) {}
+    };
+
+    void moveToFront(Node* UTILS_NONNULL node) {
+        if (node == mHead) {
+            return;
+        }
+
+        // First, detach from list.
+        if (UTILS_UNLIKELY(node == mTail)) {
+            assert(node->prev != nullptr);
+            mTail = node->prev;
+            mTail->next = nullptr;
+        } else {
+            assert(node->prev != nullptr);
+            assert(node->next != nullptr);
+            node->prev->next = node->next;
+            node->next->prev = node->prev;
+        }
+
+        // Then attach to head.
+        node->prev = nullptr;
+        node->next = mHead;
+        attach(node);
+    }
+
+    // Attach node to front.
+    void attach(Node* UTILS_NONNULL node) {
+        if (UTILS_LIKELY(mHead != nullptr)) {
+            mHead->prev = node;
+        } else {
+            assert(mTail == nullptr);
+            mTail = node;
+        }
+        mHead = node;
+    }
+
+    // Evict the least recently used node.
+    template<typename F>
+    void evict(F releaser) {
+        Node* node = mTail;
+        assert(node != nullptr);
+
+        if (UTILS_UNLIKELY(node == mHead)) {
+            mTail = nullptr;
+            mHead = nullptr;
+        } else {
+            // Move new tail node to mTail.
+            assert(node->prev != nullptr);
+            mTail = node->prev;
+            mTail->next = nullptr;
+        }
+
+        // Finally free the node.
+        mMap.erase(node->key);
+        releaser(std::move(node->value));
+        mArena.destroy(node);
+    }
+
+    size_type mCapacity;
+    utils::Arena<utils::ObjectPoolAllocator<Node>, utils::LockingPolicy::NoLock> mArena;
+    tsl::robin_map<MapKey, Node* UTILS_NONNULL, Hash, KeyEqual> mMap;
+    Node* UTILS_NULLABLE mHead;
+    Node* UTILS_NULLABLE mTail;
+};
+
+} // namespace utils
+
+#endif // TNT_UTILS_LRUCACHE_H

libs/utils/include/utils/RefCountedMap.h

@@ -19,6 +19,7 @@
 #include <utils/Panic.h>
 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/LruCache.h>
 
 #include <tsl/robin_map.h>
 
@@ -75,8 +76,6 @@ class RefCountedMap {
         T value;
     };
 
-    using Map = tsl::robin_map<Key, Entry, Hash>;
-
     static constexpr TValue& deref(T& a) {
         if constexpr (refcountedmap::IsPointer<T>) {
             return *a;
@@ -99,6 +98,9 @@ class RefCountedMap {
             "Attempted to get missing value";
 
 public:
+    explicit RefCountedMap(const char* UTILS_NONNULL name = "RefCountedMap", size_t lruCapacity = 0)
+            : mLruCache(name, lruCapacity) {}
+
     /** Acquire and return a value by key, initializing it with F if it doesn't exist.
      *
      * If F returns NullValue{}(), this indicates a failure to create the object. If T is a value
@@ -111,12 +113,16 @@ public:
             it.value().referenceCount++;
             return &deref(it.value().value);
         }
+
+        if (std::optional<T> lruValue = mLruCache.pop(key, hash)) {
+            return &insert(key, std::move(*lruValue));
+        }
+
         T r = factory();
         if (r == NullValue{}()) {
             return nullptr;
         }
-        // TODO: how to use above computed hash here?
-        return &deref(mMap.insert({ key, Entry{ 1, std::move(r) } }).first.value().value);
+        return &insert(key, std::move(r));
     }
 
     template<typename F>
@@ -138,6 +144,11 @@ public:
             it.value().referenceCount++;
             return &deref(it.value().value);
         }
+
+        if (std::optional<T> lruValue = mLruCache.pop(key, hash)) {
+            return &insert(key, std::move(*lruValue));
+        }
+
         // TODO: how to use above computed hash here?
         mMap.insert({ key, Entry{ 1, NullValue{}() } });
         return nullptr;
@@ -156,8 +167,14 @@ public:
         auto it = mMap.find(key, hash);
         FILAMENT_CHECK_PRECONDITION(it != mMap.end()) << MISSING_ENTRY_ERROR_STRING;
         if (--it.value().referenceCount == 0) {
-            if (it.value().value != NullValue{}()){
-                releaser(deref(it.value().value));
+            if (it.value().value != NullValue{}()) {
+                if (mLruCache.capacity() > 0) {
+                    mLruCache.put(key, std::move(it.value().value), hash, [&releaser](T&& v) {
+                        releaser(deref(v));
+                    });
+                } else {
+                    releaser(deref(it.value().value));
+                }
             }
             // TODO: change to erase_fast
             mMap.erase(it);
@@ -177,6 +194,9 @@ public:
         auto it = mMap.find(key, hash);
         FILAMENT_CHECK_PRECONDITION(it != mMap.end()) << MISSING_ENTRY_ERROR_STRING;
         if (--it.value().referenceCount == 0) {
+            if (mLruCache.capacity() > 0) {
+                mLruCache.put(key, std::move(it.value().value), hash, [](T&&){});
+            }
             // TODO: change to erase_fast
             mMap.erase(it);
         }
@@ -217,7 +237,7 @@ public:
      * Panics if no entry found in map.
      */
     TValue& get(KeyRef key, size_t hash) {
-        auto it = mMap.find(key);
+        auto it = mMap.find(key, hash);
         FILAMENT_CHECK_PRECONDITION(it != mMap.end()) << MISSING_ENTRY_ERROR_STRING;
         FILAMENT_CHECK_PRECONDITION(it.value().value != NullValue{}())
                 << MISSING_VALUE_ERROR_STRING;
@@ -236,13 +256,33 @@ public:
 
     inline TValue const& get(KeyRef key) const noexcept { return get(key, Hash{}(key)); }
 
+    /** Clear the LRU cache, calling releaser on each item evicted. */
+    template<typename F>
+    void clearLruCache(F releaser) {
+        mLruCache.clear([&releaser](T&& v) {
+            releaser(deref(v));
+        });
+    }
+
+    /** Clear the LRU cache without calling any releasers. */
+    void clearLruCache() {
+        mLruCache.clear();
+    }
+
     /** Returns true if the map is empty. */
     inline bool empty() const noexcept { return mMap.empty(); }
 
 private:
-    Map mMap;
+    tsl::robin_map<Key, Entry, Hash> mMap;
+    utils::LruCache<Key, T, Hash> mLruCache;
+
+    TValue& insert(KeyRef key, T value) {
+        // TODO: how to use computed hash here?
+        auto it = mMap.insert({ key, Entry{ 1, std::move(value) } });
+        return deref(it.first.value().value);
+    }
 };
 
-}
+} // utils
 
 #endif  // TNT_UTILS_REFCOUNTEDMAP_H

libs/utils/src/Allocator.cpp

@@ -87,7 +87,7 @@ FreeList::Node* FreeList::init(void* begin, void* end,
     void* const p = pointermath::align(begin, alignment, extra);
     void* const n = pointermath::align(pointermath::add(p, elementSize), alignment, extra);
     assert_invariant(p >= begin && p < end);
-    assert_invariant(n >= begin && n < end && n > p);
+    assert_invariant(n >= begin && n <= end && n > p);
 
     const size_t d = uintptr_t(n) - uintptr_t(p);
     const size_t num = (uintptr_t(end) - uintptr_t(p)) / d;
@@ -128,7 +128,7 @@ AtomicFreeList::AtomicFreeList(void* begin, void* end,
     void* const p = pointermath::align(begin, alignment, extra);
     void* const n = pointermath::align(pointermath::add(p, elementSize), alignment, extra);
     assert_invariant(p >= begin && p < end);
-    assert_invariant(n >= begin && n < end && n > p);
+    assert_invariant(n >= begin && n <= end && n > p);
 
     const size_t d = uintptr_t(n) - uintptr_t(p);
     const size_t num = (uintptr_t(end) - uintptr_t(p)) / d;

libs/utils/src/JobSystem.cpp

@@ -17,6 +17,7 @@
 // TODO: Clean-up. We shouldn't need this #ifndef here, but a client has requested that perfetto be
 // disabled due to size increase.  In their case, this flag would be defined across targets. Hence
 // we guard below with an #ifndef.
+#include <cstring>
 #ifndef FILAMENT_TRACING_ENABLED
 // Note: The overhead of TRACING is not negligible especially with parallel_for().
 #define FILAMENT_TRACING_ENABLED false
@@ -98,7 +99,11 @@ namespace utils {
 
 void JobSystem::setThreadName(const char* name) noexcept {
 #if defined(__linux__)
-    pthread_setname_np(pthread_self(), name);
+    constexpr size_t MAX_PTHREAD_NAME_LEN = 16;
+    char buf[MAX_PTHREAD_NAME_LEN];
+    strncpy(buf, name, MAX_PTHREAD_NAME_LEN - 1);
+    buf[MAX_PTHREAD_NAME_LEN - 1] = '\0';
+    pthread_setname_np(pthread_self(), buf);
 #elif defined(__APPLE__)
     pthread_setname_np(name);
 #elif defined(WIN32)

libs/utils/test/test_LruCache.cpp

@@ -0,0 +1,268 @@
+/*
+ * Copyright (C) 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <utils/LruCache.h>
+
+#include <gtest/gtest.h>
+
+#include <string>
+#include <vector>
+
+using namespace utils;
+
+TEST(LruCacheTest, BasicPutGet) {
+    LruCache<int, std::string> cache("LruCacheTest", 3);
+
+    cache.put(1, "one", [](std::string&&) {});
+    cache.put(2, "two", [](std::string&&) {});
+
+    auto* v1 = cache.get(1);
+    ASSERT_NE(v1, nullptr);
+    EXPECT_EQ(*v1, "one");
+
+    auto* v2 = cache.get(2);
+    ASSERT_NE(v2, nullptr);
+    EXPECT_EQ(*v2, "two");
+
+    EXPECT_EQ(cache.size(), 2);
+}
+
+TEST(LruCacheTest, MissingKey) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    EXPECT_EQ(cache.get(999), nullptr);
+}
+
+TEST(LruCacheTest, Eviction) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+    cache.put(3, 30, releaser);
+
+    // Cache: 3(MRU), 2, 1(LRU)
+    EXPECT_EQ(cache.size(), 3);
+    EXPECT_TRUE(evicted.empty());
+
+    cache.put(4, 40, releaser);
+    // Evicted 1. Cache: 4(MRU), 3, 2
+    EXPECT_EQ(cache.size(), 3);
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted[0], 10);
+
+    // Verify contents
+    EXPECT_NE(cache.get(2), nullptr);
+    EXPECT_NE(cache.get(3), nullptr);
+    EXPECT_NE(cache.get(4), nullptr);
+    EXPECT_EQ(cache.get(1), nullptr);
+
+    // Accessing 2 makes it MRU. Cache: 2(MRU), 4, 3(LRU)
+    cache.get(2);
+
+    cache.put(5, 50, releaser);
+    // Should evict 3.
+    ASSERT_EQ(evicted.size(), 2);
+    EXPECT_EQ(evicted[1], 30);
+}
+
+TEST(LruCacheTest, UpdatePromotesToMRU) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    auto releaser = [](int&&) {};
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+    cache.put(3, 30, releaser);
+    // Order: 3, 2, 1
+
+    cache.put(1, 11, releaser);
+    // Order: 1, 3, 2
+
+    cache.put(4, 40, releaser);
+    // Order: 4, 1, 3, 2 (evicted)
+
+    // Check if 1 exists
+    auto* v1 = cache.get(1);
+    ASSERT_NE(v1, nullptr);
+    EXPECT_EQ(*v1, 11);
+}
+
+TEST(LruCacheTest, GetPromotesToMRU) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+    cache.put(3, 30, releaser);
+    // 3, 2, 1
+
+    cache.get(1);
+    // 1, 3, 2
+
+    cache.put(4, 40, releaser);
+    // Evicts 2.
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted[0], 20);
+}
+
+TEST(LruCacheTest, MoveToFrontFromTail) {
+    // This specific test targets the potential bug where moving from tail doesn't update tail.
+    LruCache<int, int> cache("LruCacheTest", 3);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+    cache.put(3, 30, releaser);
+    // State: 3 (MRU) -> 2 -> 1 (LRU, Tail)
+
+    // Move 1 to front.
+    cache.get(1);
+    // Expected State: 1 (MRU) -> 3 -> 2 (LRU, Tail)
+
+    // Add 4. Should evict 2.
+    cache.put(4, 40, releaser);
+
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted[0], 20);
+}
+
+TEST(LruCacheTest, MoveToFrontFromMiddle) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+    cache.put(3, 30, releaser);
+    // 3, 2, 1
+
+    cache.get(2);
+    // 2, 3, 1
+
+    cache.put(4, 40, releaser);
+    // Evicts 1.
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted[0], 10);
+}
+
+TEST(LruCacheTest, CapacityOne) {
+    LruCache<int, int> cache("LruCacheTest", 1);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    EXPECT_NE(cache.get(1), nullptr);
+    EXPECT_EQ(*cache.get(1), 10);
+
+    cache.put(2, 20, releaser);
+    ASSERT_EQ(evicted.size(), 1);
+    EXPECT_EQ(evicted[0], 10);
+    EXPECT_NE(cache.get(2), nullptr);
+    EXPECT_EQ(*cache.get(2), 20);
+}
+
+#ifdef GTEST_HAS_DEATH_TEST
+TEST(LruCacheTest, CapacityZero) {
+    LruCache<int, int> cache("LruCacheTest", 0);
+    EXPECT_EQ(cache.capacity(), 0);
+    EXPECT_EQ(cache.size(), 0);
+    EXPECT_DEATH(cache.put(1, 1, [](int&&){}), "");
+}
+#endif
+
+TEST(LruCacheTest, Clear) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    std::vector<int> evicted;
+    auto releaser = [&](int&& v) { evicted.push_back(v); };
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+
+    EXPECT_EQ(cache.size(), 2);
+
+    cache.clear(releaser);
+
+    EXPECT_EQ(cache.size(), 0);
+    ASSERT_EQ(evicted.size(), 2);
+    // Implementation traverses mHead -> mTail (MRU to LRU).
+    EXPECT_EQ(evicted[0], 20); // MRU
+    EXPECT_EQ(evicted[1], 10); // LRU
+
+    // We should now be able to refill the cache.
+    cache.put(3, 30, releaser);
+    cache.put(4, 40, releaser);
+
+    EXPECT_EQ(cache.size(), 2);
+    EXPECT_NE(cache.get(3), nullptr);
+    EXPECT_NE(cache.get(4), nullptr);
+}
+
+TEST(LruCacheTest, Pop) {
+    LruCache<int, int> cache("LruCacheTest", 3);
+    auto releaser = [](int&&) {};
+
+    cache.put(1, 10, releaser);
+    cache.put(2, 20, releaser);
+
+    std::optional<int> val1 = cache.pop(1);
+    EXPECT_TRUE(val1.has_value());
+    EXPECT_EQ(*val1, 10);
+    EXPECT_EQ(cache.size(), 1);
+    EXPECT_EQ(cache.get(1), nullptr);
+    EXPECT_NE(cache.get(2), nullptr);
+
+    std::optional<int> val2 = cache.pop(2);
+    EXPECT_TRUE(val2.has_value());
+    EXPECT_EQ(*val2, 20);
+    EXPECT_EQ(cache.size(), 0);
+}
+
+/* Large key tests. */
+
+struct LargeKey {
+    long long a, b;
+    bool operator==(LargeKey const& other) const {
+        return a == other.a && b == other.b;
+    }
+};
+
+struct LargeKeyHash {
+    size_t operator()(LargeKey const& k) const {
+        return std::hash<long long>{}(k.a) ^ std::hash<long long>{}(k.b);
+    }
+};
+
+TEST(LruCacheTest, LargeKey) {
+    static_assert(sizeof(LargeKey) > sizeof(void*), "LargeKey must be larger than pointer");
+    LruCache<LargeKey, int, LargeKeyHash> cache("LruCacheTest", 2);
+
+    LargeKey k1{1, 1};
+    LargeKey k2{2, 2};
+    LargeKey k3{3, 3};
+
+    cache.put(k1, 100, [](int&&){});
+    cache.put(k2, 200, [](int&&){});
+
+    EXPECT_NE(cache.get(k1), nullptr);
+    EXPECT_EQ(*cache.get(k1), 100);
+
+    // Evict k2 (LRU because k1 was accessed)
+    cache.put(k3, 300, [](int&&){});
+
+    EXPECT_NE(cache.get(k3), nullptr); // k3 present
+}