add logging

Full commit hash is 29e91f0d3a

DOCS_ALLOW_DIRECT_EDITS

.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

@@ -6,18 +6,31 @@ on:
       - main
 
 jobs:
+  # Update the renderdiff goldens in filament-assets. This will add or merge the new goldens from
+  # 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: Prerequisites
-        run: pip install tifffile numpy
+      - 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 }}
@@ -25,16 +38,31 @@ 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} \
                   --merge-to-main --filament-tag=${COMMIT_HASH} --golden-repo-token=${GH_TOKEN}
           fi
 
+  # Update the /docs (offiicla github-hosted Filament site) if necessary
   update-docs:
     name: update-docs
     runs-on: 'ubuntu-24.04-4core'
@@ -57,3 +85,40 @@ jobs:
           git config --global user.name "Filament Bot"
           git config --global credential.helper cache
           bash docs_src/build/postsubmit.sh ${COMMIT_HASH} ${GH_TOKEN}
+
+  # Produce a json that describes the android artifact sizes, and will push that json to a folder in
+  # filament-assets
+  update-sizeguard:
+    name: update-sizeguard
+    runs-on: 'ubuntu-24.04-16core'
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/linux-prereq
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+      - id: get_commit_msg
+        uses: ./.github/actions/get-commit-msg
+      - name: Build and generate size report
+        run: |
+          cd build/android && printf "y" | ./build.sh release all
+          cd ../..
+          COMMIT_HASH="${{ steps.get_commit_msg.outputs.hash }}"
+          python3 test/sizeguard/dump_artifact_size.py out/*.tgz out/*.aar > "${COMMIT_HASH}.json"
+      - name: Push to filament-assets
+        env:
+          GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
+        run: |
+          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 clone https://x-access-token:${GH_TOKEN}@github.com/google/filament-assets.git filament-assets
+          mkdir -p filament-assets/sizeguard
+          mv "${COMMIT_HASH}.json" filament-assets/sizeguard/
+          cd filament-assets
+          git add sizeguard/"${COMMIT_HASH}.json"
+          git commit -m "Update sizeguard for filament@${COMMIT_HASH}" || echo "No changes to commit"
+          git push https://x-access-token:${GH_TOKEN}@github.com/google/filament-assets.git main

.github/workflows/presubmit.yml

@@ -67,7 +67,16 @@ jobs:
         # Only build 1 64 bit target during presubmit to cut down build times during presubmit
         # Continuous builds will build everything
         run: |
-          cd build/android && printf "y" | ./build.sh presubmit arm64-v8a
+          pushd .
+          cd build/android && printf "y" | ./build.sh presubmit-with-archive arm64-v8a
+          popd
+      - name: Check artifact sizes
+        run: |
+          python3 test/sizeguard/dump_artifact_size.py out/*.aar > current_size.json
+          python3 test/sizeguard/check_size.py current_size.json \
+              --target-branch origin/main \
+              --threshold 20480 \
+              --artifacts filament-android-release.aar/jni/arm64-v8a/libfilament-jni.so
 
   build-ios:
     name: build-iOS
@@ -117,19 +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: |
-          pip install tifffile numpy
-          # 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 }}
@@ -138,7 +152,7 @@ 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
+
           python3 ${TEST_DIR}/src/golden_manager.py \
                   --branch=${GOLDEN_BRANCH} \
                   --output=${GOLDEN_OUTPUT_DIR}
@@ -149,7 +163,9 @@ jobs:
           python3 ${TEST_DIR}/src/compare.py \
               --src=${GOLDEN_OUTPUT_DIR} \
               --dest=${RENDER_OUTPUT_DIR} \
-              --out=${DIFF_OUTPUT_DIR} 2>&1 | tee compare_output.txt
+              --out=${DIFF_OUTPUT_DIR} \
+              --diffimg="$(pwd)/out/cmake-release/tools/diffimg/diffimg" \
+              --test="${TEST_DIR}/tests/presubmit.json" 2>&1 | tee compare_output.txt
 
           if grep "Failed" compare_output.txt > /dev/null; then
              DELIMITER="EOF_FILE_CONTENT_$(date +%s)" # Using timestamp to make it more unique
@@ -159,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

@@ -163,9 +163,7 @@ jobs:
           mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
           mv out/gltfio-android-release.aar out/gltfio-${TAG}-android.aar
           mv out/filament-utils-android-release.aar out/filament-utils-${TAG}-android.aar
-          cd out/android-release/filament
-          tar -czf ../../filament-${TAG}-android-native.tgz .
-          cd ../../..
+          mv out/filament-android-release-linux.tgz out/filament-${TAG}-android-native.tgz
       - name: Sign sample-gltf-viewer
         run: |
           echo "${APK_KEYSTORE_BASE64}" > filament.jks.base64
@@ -190,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
@@ -245,7 +291,8 @@ jobs:
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
-          build\windows\build-github.bat release
+          @REMARK 'call' is required to ensure control returns to this script after the batch file finishes.
+          call build\windows\build-github.bat release
           echo on
           move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
         shell: cmd

CMakeLists.txt

@@ -65,6 +65,8 @@ option(FILAMENT_SUPPORTS_WEBP_TEXTURES "Enable webp texture support for Filament
 # On the regular filament build (where size is of less concern), we enable GTAO by default.
 option(FILAMENT_DISABLE_GTAO "Disable GTAO" OFF)
 
+option(FILAMENT_BUILD_TESTING "Build tests" ON)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
@@ -877,6 +879,7 @@ add_subdirectory(${LIBRARIES}/gltfio)
 add_subdirectory(${LIBRARIES}/ibl)
 add_subdirectory(${LIBRARIES}/iblprefilter)
 add_subdirectory(${LIBRARIES}/image)
+add_subdirectory(${LIBRARIES}/imagediff)
 add_subdirectory(${LIBRARIES}/ktxreader)
 add_subdirectory(${LIBRARIES}/math)
 add_subdirectory(${LIBRARIES}/mathio)
@@ -903,6 +906,8 @@ add_subdirectory(${EXTERNAL}/getopt)
 add_subdirectory(${EXTERNAL}/perfetto/tnt)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 
+# imageio-lite is needed for viewer
+add_subdirectory(${LIBRARIES}/imageio-lite)
 
 # Note that this has to be placed after mikktspace in order for combine_static_libs to work.
 add_subdirectory(${LIBRARIES}/geometry)
@@ -971,6 +976,7 @@ if (IS_HOST_PLATFORM)
 
     add_subdirectory(${TOOLS}/cmgen)
     add_subdirectory(${TOOLS}/cso-lut)
+    add_subdirectory(${TOOLS}/diffimg)
     add_subdirectory(${TOOLS}/filamesh)
     add_subdirectory(${TOOLS}/glslminifier)
     add_subdirectory(${TOOLS}/matc)

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.68.5'
+    implementation 'com.google.android.filament:filament-android:1.69.5'
 }
 ```
 
@@ -39,19 +39,18 @@ Here are all the libraries available in the group `com.google.android.filament`:
 
 | Artifact      | Description   |
 | ------------- | ------------- |
-| [![filament-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
-| [![filament-android-debug](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug/badge.svg?subject=filament-android-debug)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug)  | Debug version of `filament-android`. |
-| [![gltfio-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
-| [![filament-utils-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
-| [![filamat-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
-| [![filamat-android-lite](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite/badge.svg?subject=filamat-android-lite)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite) | A much smaller alternative to `filamat-android` that can only generate OpenGL shaders. It does not provide validation or optimizations. |
+| [![filament-android](https://img.shields.io/maven-central/v/com.google.android.filament/filament-android?label=filament-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
+| [![filament-android-debug](https://img.shields.io/maven-central/v/com.google.android.filament/filament-android-debug?label=filament-android-debug&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-android-debug)  | Debug version of `filament-android`. |
+| [![gltfio-android](https://img.shields.io/maven-central/v/com.google.android.filament/gltfio-android?label=gltfio-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
+| [![filament-utils-android](https://img.shields.io/maven-central/v/com.google.android.filament/filament-utils-android?label=filament-utils-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
+| [![filamat-android](https://img.shields.io/maven-central/v/com.google.android.filament/filamat-android?label=filamat-android&color=green)](https://mvnrepository.com/artifact/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
 
 ### iOS
 
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.68.5'
+pod 'Filament', '~> 1.69.5'
 ```
 
 ## Documentation
@@ -89,7 +88,8 @@ pod 'Filament', '~> 1.68.5'
 - OpenGL ES 3.0+ for Android and iOS
 - Metal for macOS and iOS
 - Vulkan 1.0 for Android, Linux, macOS, and Windows
-- WebGL 2.0 for all platforms
+- WebGPU for Android, Linux, macOS, and Windows
+- WebGL 2.0 for all browsers supporting it
 
 ### Rendering
 
@@ -124,7 +124,7 @@ pod 'Filament', '~> 1.68.5'
 
 - HDR bloom
 - Depth of field bokeh
-- Multiple tone mappers: generic (customizable), ACES, filmic, etc.
+- Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc.
 - Color and tone management: luminance scaling, gamut mapping
 - Color grading: exposure, night adaptation, white balance, channel mixer,
   shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc.
@@ -158,15 +158,16 @@ pod 'Filament', '~> 1.68.5'
   - [x] KHR_draco_mesh_compression
   - [x] KHR_lights_punctual
   - [x] KHR_materials_clearcoat
+  - [x] KHR_materials_dispersion
   - [x] KHR_materials_emissive_strength
   - [x] KHR_materials_ior
   - [x] KHR_materials_pbrSpecularGlossiness
   - [x] KHR_materials_sheen
+  - [x] KHR_materials_specular
   - [x] KHR_materials_transmission
   - [x] KHR_materials_unlit
   - [x] KHR_materials_variants
   - [x] KHR_materials_volume
-  - [x] KHR_materials_specular
   - [x] KHR_mesh_quantization
   - [x] KHR_texture_basisu
   - [x] KHR_texture_transform
@@ -331,7 +332,7 @@ and tools.
   - `filamesh`:               Mesh converter
   - `glslminifier`:           Minifies GLSL source code
   - `matc`:                   Material compiler
-  - `filament-matp`:          Material parser
+  - `matedit`:                Material editor for compiled materials
   - `matinfo`                 Displays information about materials compiled with `matc`
   - `mipgen`                  Generates a series of miplevels from a source image
   - `normal-blending`:        Tool to blend normal maps

RELEASE_NOTES.md

@@ -7,6 +7,29 @@ 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
+
+
+## v1.69.3
+
+
+## v1.69.2
+
+- engine: fix shader compilation failure in TAA material
+- engine: fix stereo & parallel shader compilation
+
+## v1.69.1
+
+
 ## v1.69.0
 
 - engine: Support custom attributes morphing, and allow for omitting position and/or normal data. [⚠️ **Recompile Materials**]

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/buildSrc/README.md

@@ -0,0 +1,120 @@
+# Filament Tools Gradle Plugin
+
+## About
+
+The **Filament Tools Gradle Plugin** helps integrate Filament into your Android project. It
+automates the use of Filament's command-line tools (`matc`, `cmgen`, and `filamesh`).
+
+This plugin handles:
+- **Material Compilation**: Compiles `.mat` material definitions into `.filamat` binaries.
+- **IBL Generation**: Generates Image-Based Lighting assets from HDR environment maps.
+- **Mesh Compilation**: Converts models into Filament's efficient `.filamesh` binary format. *Note:
+  This tool is no longer recommended; instead, use glTF and Filament's `gltfio` library for model
+  loading.*
+
+The plugin hooks directly into the Android build lifecycle (via `preBuild`) and supports incremental
+builds, so assets are only recompiled when source files change.
+
+## Usage
+
+Apply the plugin in your module's `build.gradle` file and configure the `filament` block. You can
+specify inputs and outputs for any combination of materials, IBLs, or meshes. If a path is not
+configured, the corresponding task will be disabled.
+
+### Example Configuration
+
+```groovy
+plugins {
+    id 'filament-plugin'
+}
+
+filament {
+    materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
+    materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
+
+    iblInputFile = project.layout.projectDirectory.file("path/to/environment.hdr")
+    iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
+
+    meshInputFile = project.layout.projectDirectory.file("path/to/model.obj")
+    meshOutputDir = project.layout.projectDirectory.dir("src/main/assets/models")
+}
+```
+
+### Configuration Details
+
+- **materialInputDir**: The directory containing your source material definitions (`.mat` files).
+- **materialOutputDir**: The directory where the compiled material files (`.filamat`) will be
+  generated.
+- **iblInputFile**: The source high-dynamic-range image file (e.g., `.hdr` or `.exr`) used to
+  generate Image Based Lighting assets.
+- **iblOutputDir**: The directory where the generated IBL assets (typically `.ktx` files) will be
+  placed.
+- **meshInputFile**: The source mesh file (e.g., `.obj`) to be compiled.
+- **meshOutputDir**: The directory where the compiled mesh file (`.filamesh`) will be generated.
+
+Automatically adds tasks to your Android build to compile materials, generate an IBL, and compile a
+mesh. The plugin hooks into `preBuild` to ensure assets are generated before the application is
+built.
+
+### Configuration Flags
+
+You can control specific compilation options using Gradle properties (e.g., in `gradle.properties`
+or via command line `-P`).
+
+- **`com.google.android.filament.exclude-vulkan`**  When set to `true`, the Vulkan backend is
+  excluded from the compiled materials. This can be useful to reduce the size of the generated
+  assets if your application does not target Vulkan.  *Default: `false` (Vulkan is included)*
+
+- **`com.google.android.filament.include-webgpu`**  When set to `true`, the WebGPU backend is
+  included in the compiled materials. Use this if you intend to use the materials in a context
+  supporting WebGPU.  *Default: `false`*
+
+## Tools Configuration
+
+The Filament Tools plugin requires some binary tools to be available: `matc`, `cmgen`, and
+`filamesh`.
+
+There are three ways to configure Filament tools:
+
+1. **Point to a local path directly**
+
+```groovy
+filament {
+    matc {
+        path = "/path/to/matc"
+    }
+
+    cmgen {
+        path = "/path/to/cmgen"
+    }
+
+    filamesh {
+        path = "/path/to/filamesh"
+    }
+}
+```
+
+2. **Point to a Maven artifact**
+
+```groovy
+filament {
+    matc {
+        // The minor version (the middle number) must match the Filament dependency's.
+        artifact = 'com.google.android.filament:matc:1.68.5'
+    }
+
+    cmgen {
+        artifact = 'com.google.android.filament:cmgen:1.68.5'
+    }
+}
+```
+
+*Note that the `filamesh` artifact is not hosted on Maven Central, so it must be provided locally or
+via another mechanism if needed.*
+
+Gradle will automatically handle downloading the tool appropriate for your machine (MacOS/Linux/Windows) from Maven.
+
+3. **Set the `com.google.android.filament.tools-dir` Gradle property**
+
+This will override any other configuration. Gradle will attempt to locate the tools under
+`<tools-dir>/bin` (e.g., `.../bin/matc`, `.../bin/cmgen`, `.../bin/filamesh`).

android/buildSrc/build.gradle

@@ -4,13 +4,18 @@ plugins {
 
 gradlePlugin {
     plugins {
-        create("filament-tools-plugin") {
-            id = "filament-tools-plugin"
-            implementationClass = "FilamentToolsPlugin"
+        create("filament-plugin") {
+            id = "filament-plugin"
+            implementationClass = "com.google.android.filament.gradle.FilamentPlugin"
         }
     }
 }
 
 repositories {
     mavenCentral()
+    gradlePluginPortal()
+}
+
+dependencies {
+    implementation "com.google.gradle:osdetector-gradle-plugin:1.7.3"
 }

android/buildSrc/src/main/groovy/FilamentPlugin.groovy

@@ -1,359 +0,0 @@
-// This plugin accepts the following parameters:
-//
-// com.google.android.filament.tools-dir
-//     Path to the Filament distribution/install directory for desktop.
-//     This directory must contain bin/matc.
-//
-// com.google.android.filament.exclude-vulkan
-//     When set, support for Vulkan will be excluded.
-//
-// Example:
-//     ./gradlew -Pcom.google.android.filament.tools-dir=../../dist-release assembleDebug
-
-import org.gradle.api.DefaultTask
-import org.gradle.api.GradleException
-import org.gradle.api.Plugin
-import org.gradle.api.Project
-import org.gradle.api.provider.ProviderFactory
-import org.gradle.api.file.DirectoryProperty
-import org.gradle.api.file.FileSystemOperations
-import org.gradle.api.file.FileType
-import org.gradle.api.file.RegularFileProperty
-import org.gradle.api.logging.LogLevel
-import org.gradle.api.logging.Logger
-import org.gradle.api.provider.Property
-import org.gradle.api.tasks.Input
-import org.gradle.api.tasks.InputDirectory
-import org.gradle.api.tasks.InputFile
-import org.gradle.api.tasks.Optional
-import org.gradle.api.tasks.OutputDirectory
-import org.gradle.api.tasks.TaskAction
-import org.gradle.api.tasks.incremental.InputFileDetails
-import org.gradle.api.model.ObjectFactory
-import org.gradle.internal.os.OperatingSystem
-import org.gradle.process.ExecOperations
-import org.gradle.work.ChangeType
-import org.gradle.work.Incremental
-import org.gradle.work.InputChanges
-
-import java.nio.file.Paths
-
-import javax.inject.Inject
-
-abstract class TaskWithBinary extends DefaultTask {
-    private final String binaryName
-    private Property<String> binaryPath = null
-
-    TaskWithBinary(String name) {
-        binaryName = name
-    }
-
-    @Inject abstract ObjectFactory getObjects()
-    @Inject abstract ProviderFactory getProviders()
-
-    @Input
-    Property<String> getBinary() {
-        if (binaryPath == null) {
-            def tool = ["/bin/${binaryName}.exe", "/bin/${binaryName}"]
-            def fullPath = tool.collect { path ->
-                def filamentToolsPath = providers
-                        .gradleProperty("com.google.android.filament.tools-dir")
-                        .forUseAtConfigurationTime().get()
-                def directory = objects.fileProperty()
-                        .fileValue(new File(filamentToolsPath)).getAsFile().get()
-                Paths.get(directory.absolutePath, path).toFile()
-            }
-
-            binaryPath = objects.property(String.class)
-            binaryPath.set(
-                    (OperatingSystem.current().isWindows() ? fullPath[0] : fullPath[1]).toString())
-        }
-        return binaryPath
-    }
-}
-
-class LogOutputStream extends ByteArrayOutputStream {
-    private final Logger logger
-    private final LogLevel level
-
-    LogOutputStream(Logger logger, LogLevel level) {
-        this.logger = logger
-        this.level = level
-    }
-
-    @Override
-    void flush() {
-        logger.log(level, toString())
-        reset()
-    }
-}
-
-// Custom task to compile material files using matc
-// This task handles incremental builds
-abstract class MaterialCompiler extends TaskWithBinary {
-    @Incremental
-    @InputDirectory
-    abstract DirectoryProperty getInputDir()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-    @Inject abstract ObjectFactory getObjects()
-    @Inject abstract ProviderFactory getProviders()
-
-    MaterialCompiler() {
-        super("matc")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*.filamat' })
-            })
-        }
-
-        inputs.getFileChanges(inputDir).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Compiling material " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                def matcArgs = []
-                def exclude_vulkan = providers
-                        .gradleProperty("com.google.android.filament.exclude-vulkan")
-                        .forUseAtConfigurationTime().present
-                if (!exclude_vulkan) {
-                    matcArgs += ['-a', 'vulkan']
-                }
-                def include_webgpu = providers
-                        .gradleProperty("com.google.android.filament.include-webgpu")
-                        .forUseAtConfigurationTime().present
-                if (include_webgpu) {
-                    matcArgs += ['-a', 'webgpu', '--variant-filter=stereo']
-                }
-
-                def mat_no_opt = providers
-                        .gradleProperty("com.google.android.filament.matnopt")
-                        .forUseAtConfigurationTime().present
-                if (mat_no_opt) {
-                    matcArgs += ['-g']
-                }
-
-                matcArgs += ['-a', 'opengl', '-p', 'mobile', '-o', getOutputFile(file), file]
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args matcArgs
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.')] + 'filamat').get().asFile
-    }
-}
-
-// Custom task to process IBLs using cmgen
-// This task handles incremental builds
-abstract class IblGenerator extends TaskWithBinary {
-    @Input
-    @Optional
-    abstract Property<String> getCmgenArgs()
-
-    @Incremental
-    @InputFile
-    abstract RegularFileProperty getInputFile()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-    @Inject abstract ObjectFactory getObjects()
-
-    IblGenerator() {
-        super("cmgen")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*' })
-            })
-        }
-
-        inputs.getFileChanges(inputFile).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Generating IBL " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                def outputPath = outputDir.get().asFile
-                def commandArgs = cmgenArgs.getOrNull()
-                if (commandArgs == null) {
-                    commandArgs =
-                            '-q -x ' + outputPath + ' --format=rgb32f ' +
-                                    '--extract-blur=0.08 --extract=' + outputPath.absolutePath
-                }
-                commandArgs = commandArgs + " " + file
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args(commandArgs.split())
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.') - 1]).get().asFile
-    }
-}
-
-// Custom task to compile mesh files using filamesh
-// This task handles incremental builds
-abstract class MeshCompiler extends TaskWithBinary {
-    @Incremental
-    @InputFile
-    abstract RegularFileProperty getInputFile()
-
-    @OutputDirectory
-    abstract DirectoryProperty getOutputDir()
-
-    @Inject abstract FileSystemOperations getFs()
-    @Inject abstract ExecOperations getExec()
-
-    MeshCompiler() {
-        super("filamesh")
-    }
-
-    @TaskAction
-    void execute(InputChanges inputs) {
-        if (!inputs.incremental) {
-            fs.delete({
-                delete(objects.fileTree().from(outputDir).matching { include '*.filamesh' })
-            })
-        }
-
-        inputs.getFileChanges(inputFile).each { InputFileDetails change ->
-            if (change.fileType == FileType.DIRECTORY) return
-
-            def file = change.file
-
-            if (change.changeType == ChangeType.REMOVED) {
-                getOutputFile(file).delete()
-            } else {
-                def out = new LogOutputStream(logger, LogLevel.LIFECYCLE)
-                def err = new LogOutputStream(logger, LogLevel.ERROR)
-
-                def header = ("Compiling mesh " + file + "\n").getBytes()
-                out.write(header)
-                out.flush()
-
-                if (!new File(binary.get()).exists()) {
-                    throw new GradleException("Could not find ${binary.get()}." +
-                            " Ensure Filament has been built/installed before building this app.")
-                }
-
-                exec.exec {
-                    standardOutput out
-                    errorOutput err
-                    executable "${binary.get()}"
-                    args(file, getOutputFile(file))
-                }
-            }
-        }
-    }
-
-    File getOutputFile(final File file) {
-        return outputDir.file(file.name[0..file.name.lastIndexOf('.')] + 'filamesh').get().asFile
-    }
-}
-
-class FilamentToolsPluginExtension {
-    DirectoryProperty materialInputDir
-    DirectoryProperty materialOutputDir
-
-    String cmgenArgs
-    RegularFileProperty iblInputFile
-    DirectoryProperty iblOutputDir
-
-    RegularFileProperty meshInputFile
-    DirectoryProperty meshOutputDir
-}
-
-class FilamentToolsPlugin implements Plugin<Project> {
-    void apply(Project project) {
-        def extension = project.extensions.create('filamentTools', FilamentToolsPluginExtension)
-        extension.materialInputDir = project.objects.directoryProperty()
-        extension.materialOutputDir = project.objects.directoryProperty()
-        extension.iblInputFile = project.objects.fileProperty()
-        extension.iblOutputDir = project.objects.directoryProperty()
-        extension.meshInputFile = project.objects.fileProperty()
-        extension.meshOutputDir = project.objects.directoryProperty()
-
-        project.tasks.register("filamentCompileMaterials", MaterialCompiler) {
-            enabled =
-                    extension.materialInputDir.isPresent() &&
-                    extension.materialOutputDir.isPresent()
-            inputDir.set(extension.materialInputDir.getOrNull())
-            outputDir.set(extension.materialOutputDir.getOrNull())
-        }
-
-        project.preBuild.dependsOn "filamentCompileMaterials"
-
-        project.tasks.register("filamentGenerateIbl", IblGenerator) {
-            enabled = extension.iblInputFile.isPresent() && extension.iblOutputDir.isPresent()
-            cmgenArgs = extension.cmgenArgs
-            inputFile = extension.iblInputFile.getOrNull()
-            outputDir = extension.iblOutputDir.getOrNull()
-        }
-
-        project.preBuild.dependsOn "filamentGenerateIbl"
-
-        project.tasks.register("filamentCompileMesh", MeshCompiler) {
-            enabled = extension.meshInputFile.isPresent() && extension.meshOutputDir.isPresent()
-            inputFile = extension.meshInputFile.getOrNull()
-            outputDir = extension.meshOutputDir.getOrNull()
-        }
-
-        project.preBuild.dependsOn "filamentCompileMesh"
-    }
-}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/FilamentExtension.groovy

@@ -0,0 +1,57 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Action
+import org.gradle.api.Project
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.provider.Property
+
+class FilamentExtension {
+    final ToolsLocator tools
+    final DirectoryProperty materialInputDir
+    final DirectoryProperty materialOutputDir
+    final Property<String> cmgenArgs
+    final RegularFileProperty iblInputFile
+    final DirectoryProperty iblOutputDir
+    final RegularFileProperty meshInputFile
+    final DirectoryProperty meshOutputDir
+
+    FilamentExtension(Project project) {
+        this.tools = new ToolsLocator(project)
+        this.materialInputDir = project.objects.directoryProperty()
+        this.materialOutputDir = project.objects.directoryProperty()
+        this.cmgenArgs = project.objects.property(String)
+        this.iblInputFile = project.objects.fileProperty()
+        this.iblOutputDir = project.objects.directoryProperty()
+        this.meshInputFile = project.objects.fileProperty()
+        this.meshOutputDir = project.objects.directoryProperty()
+    }
+
+    void matc(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.matc)
+    }
+
+    void cmgen(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.cmgen)
+    }
+
+    void filamesh(Action<ToolsLocator.ToolConfig> action) {
+        action.execute(tools.filamesh)
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/FilamentPlugin.groovy

@@ -0,0 +1,59 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+
+class FilamentPlugin implements Plugin<Project> {
+    @Override
+    void apply(Project project) {
+        project.pluginManager.apply("com.google.osdetector")
+
+        FilamentExtension extension = project.extensions.create("filament", FilamentExtension, project)
+
+        project.afterEvaluate {
+            extension.tools.resolve(project)
+
+            project.tasks.register("filamentCompileMaterials", MaterialCompileTask) {
+                enabled = extension.materialInputDir.isPresent() && extension.materialOutputDir.isPresent()
+                inputDir.set(extension.materialInputDir.getOrNull())
+                outputDir.set(extension.materialOutputDir.getOrNull())
+                matcTool.from(extension.tools.matcToolFiles)
+            }
+
+            project.tasks.register("filamentGenerateIbl", IblGenerateTask) {
+                enabled = extension.iblInputFile.isPresent() && extension.iblOutputDir.isPresent()
+                cmgenArgs = extension.cmgenArgs
+                inputFile.set(extension.iblInputFile.getOrNull())
+                outputDir.set(extension.iblOutputDir.getOrNull())
+                cmgenTool.from(extension.tools.cmgenToolFiles)
+            }
+
+            project.tasks.register("filamentCompileMesh", MeshCompileTask) {
+                enabled = extension.meshInputFile.isPresent() && extension.meshOutputDir.isPresent()
+                inputFile = extension.meshInputFile.getOrNull()
+                outputDir = extension.meshOutputDir.getOrNull()
+                filameshTool.from(extension.tools.filameshToolFiles)
+            }
+
+            project.preBuild.dependsOn "filamentCompileMaterials"
+            project.preBuild.dependsOn "filamentGenerateIbl"
+            project.preBuild.dependsOn "filamentCompileMesh"
+        }
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/IblGenerateTask.groovy

@@ -0,0 +1,126 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.GradleException
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.provider.Property
+import org.gradle.api.tasks.Input
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.Optional
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import org.gradle.api.tasks.incremental.InputFileDetails
+import javax.inject.Inject
+
+abstract class IblGenerateTask extends DefaultTask {
+
+    @Input
+    @Optional
+    abstract Property<String> getCmgenArgs()
+
+    @Incremental
+    @InputFile
+    abstract RegularFileProperty getInputFile()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    abstract ConfigurableFileCollection getCmgenTool()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @TaskAction
+    void execute(InputChanges inputs) {
+        if (cmgenTool.empty) {
+            throw new IllegalStateException(
+                "cmgen executable not configured. Please configure the 'cmgen' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File cmgen = getCmgenTool().singleFile
+        if (!cmgen.exists()) {
+            throw new IllegalStateException("cmgen executable does not exist: ${cmgen.absolutePath}")
+        }
+
+        if (!cmgen.canExecute()) {
+            cmgen.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching { include '*' })
+            }
+        }
+
+        inputs.getFileChanges(getInputFile()).each { InputFileDetails change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            def file = change.file
+
+            if (change.changeType == ChangeType.REMOVED) {
+                computeOutputFile(file).delete()
+            } else {
+                println "Generating IBL: ${file.name}"
+
+                def outputPath = getOutputDir().get().asFile
+                def commandArgs = getCmgenArgs().getOrNull()
+                if (commandArgs == null) {
+                    // Default args if not provided
+                    commandArgs = '-q -x ' + outputPath + ' --format=rgb32f ' +
+                                  '--extract-blur=0.08 --extract=' + outputPath.absolutePath
+                }
+
+                def argsList = commandArgs.split(' ').toList()
+                argsList.add(file.absolutePath)
+
+                getExecOperations().exec { spec ->
+                    spec.executable(cmgen)
+                    spec.args(argsList)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(final File file) {
+        String name = file.name
+        int dotIndex = name.lastIndexOf('.')
+        String baseName = dotIndex > 0 ? name.substring(0, dotIndex) : name
+        return getOutputDir().file(baseName).get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/MaterialCompileTask.groovy

@@ -0,0 +1,147 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.artifacts.component.ModuleComponentIdentifier
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.provider.ProviderFactory
+import org.gradle.api.tasks.InputDirectory
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.SkipWhenEmpty
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import javax.inject.Inject
+
+abstract class MaterialCompileTask extends DefaultTask {
+
+    @Incremental
+    @InputDirectory
+    @PathSensitive(PathSensitivity.RELATIVE)
+    abstract DirectoryProperty getInputDir()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    @PathSensitive(PathSensitivity.NONE)
+    abstract ConfigurableFileCollection getMatcTool()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @Inject
+    abstract ProviderFactory getProviderFactory()
+
+    @TaskAction
+    void compile(InputChanges inputs) {
+        if (matcTool.empty) {
+            throw new IllegalStateException(
+                "matc executable not configured. Please configure the 'matc' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File matc = matcTool.singleFile
+        if (!matc.exists()) {
+            throw new IllegalStateException("matc executable does not exist: ${matc.absolutePath}")
+        }
+
+        if (!matc.canExecute()) {
+            matc.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching {
+                    include '*.filamat'
+                })
+            }
+        }
+
+        def pf = getProviderFactory()
+        def excludeVulkanProperty = pf.gradleProperty("com.google.android.filament.exclude-vulkan")
+        def includeWebGpuProperty = pf.gradleProperty("com.google.android.filament.include-webgpu")
+        def matNoOptProperty = pf.gradleProperty("com.google.android.filament.matnopt")
+        def excludeVulkan = excludeVulkanProperty.orNull == "true"
+        def includeWebGpu = includeWebGpuProperty.orNull == "true"
+        def matNoOpt = matNoOptProperty.orNull == "true"
+
+        inputs.getFileChanges(getInputDir()).each { change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            File file = change.file
+            File outputFile = computeOutputFile(file)
+
+            if (change.changeType == ChangeType.REMOVED) {
+                outputFile.delete()
+            } else {
+                println "Compiling material: ${file.name}"
+
+                def args = []
+                if (!excludeVulkan) {
+                    args += ['-a', 'vulkan']
+                }
+
+                if (includeWebGpu) {
+                    args += ['-a', 'webgpu', '--variant-filter=stereo']
+                }
+
+                if (matNoOpt) {
+                    args += ['-g']
+                }
+
+                args += [
+                    '-a', 'opengl', '-p', 'mobile',
+                    '-o', outputFile.absolutePath,
+                    file.absolutePath
+                ]
+
+                getExecOperations().exec { spec ->
+                    spec.executable(matc)
+                    spec.args(args)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(File inputFile) {
+        String baseName = inputFile.name
+        int dotIndex = baseName.lastIndexOf('.')
+        if (dotIndex > 0) {
+            baseName = baseName.substring(0, dotIndex)
+        }
+        return getOutputDir().file("${baseName}.filamat").get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/MeshCompileTask.groovy

@@ -0,0 +1,115 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.DefaultTask
+import org.gradle.api.file.ConfigurableFileCollection
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.file.FileSystemOperations
+import org.gradle.api.file.FileType
+import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.model.ObjectFactory
+import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.InputFiles
+import org.gradle.api.tasks.OutputDirectory
+import org.gradle.api.tasks.PathSensitive
+import org.gradle.api.tasks.PathSensitivity
+import org.gradle.api.tasks.TaskAction
+import org.gradle.process.ExecOperations
+import org.gradle.work.ChangeType
+import org.gradle.work.Incremental
+import org.gradle.work.InputChanges
+import javax.inject.Inject
+
+abstract class MeshCompileTask extends DefaultTask {
+
+    @Incremental
+    @InputFile
+    @PathSensitive(PathSensitivity.RELATIVE)
+    abstract RegularFileProperty getInputFile()
+
+    @OutputDirectory
+    abstract DirectoryProperty getOutputDir()
+
+    @InputFiles
+    @PathSensitive(PathSensitivity.NONE)
+    abstract ConfigurableFileCollection getFilameshTool()
+
+    @Inject
+    abstract ExecOperations getExecOperations()
+
+    @Inject
+    abstract FileSystemOperations getFileSystemOperations()
+
+    @Inject
+    abstract ObjectFactory getObjectFactory()
+
+    @TaskAction
+    void compile(InputChanges inputs) {
+        if (filameshTool.empty) {
+            throw new IllegalStateException(
+                "filamesh executable not configured. Please configure the 'filamesh' block in the " +
+                "'filament' extension or set the 'com.google.android.filament.tools-dir' " +
+                "property."
+            )
+        }
+
+        File filamesh = filameshTool.singleFile
+        if (!filamesh.exists()) {
+            throw new IllegalStateException("filamesh executable does not exist: ${filamesh.absolutePath}")
+        }
+
+        if (!filamesh.canExecute()) {
+            filamesh.setExecutable(true)
+        }
+
+        if (!inputs.incremental) {
+            getFileSystemOperations().delete {
+                delete(getObjectFactory().fileTree().from(getOutputDir()).matching {
+                    include '*.filamesh'
+                })
+            }
+        }
+
+        inputs.getFileChanges(inputFile).each { change ->
+            if (change.fileType == FileType.DIRECTORY) return
+
+            File file = change.file
+            File outputFile = computeOutputFile(file)
+
+            if (change.changeType == ChangeType.REMOVED) {
+                outputFile.delete()
+            } else {
+                println "Compiling mesh: ${file.name}"
+
+                getExecOperations().exec { spec ->
+                    spec.executable(filamesh)
+                    spec.args(file.absolutePath, outputFile.absolutePath)
+                }
+            }
+        }
+    }
+
+    File computeOutputFile(File inputFile) {
+        String baseName = inputFile.name
+        int dotIndex = baseName.lastIndexOf('.')
+        if (dotIndex > 0) {
+            baseName = baseName.substring(0, dotIndex)
+        }
+        return getOutputDir().file("${baseName}.filamesh").get().asFile
+    }
+}

android/buildSrc/src/main/groovy/com/google/android/filament/gradle/ToolsLocator.groovy

@@ -0,0 +1,113 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.gradle
+
+import org.gradle.api.Action
+import org.gradle.api.Project
+import org.gradle.api.artifacts.Configuration
+import org.gradle.api.file.FileCollection
+import org.gradle.internal.os.OperatingSystem
+
+import java.nio.file.Paths
+
+class ToolsLocator {
+    static class ToolConfig {
+        String artifact
+        String path
+        FileCollection files
+    }
+
+    final ToolConfig matc = new ToolConfig()
+    final ToolConfig cmgen = new ToolConfig()
+    final ToolConfig filamesh = new ToolConfig()
+    private final Project project
+
+    ToolsLocator(Project project) {
+        this.project = project
+    }
+
+    void resolve(Project project) {
+        resolveTool(matc, "matc")
+        resolveTool(cmgen, "cmgen")
+        resolveTool(filamesh, "filamesh")
+    }
+
+    /**
+     * Resolves a specific tool by its name and sets the {@link ToolConfig#files} property of the
+     * provided {@link ToolConfig} object. It first attempts to locate the tool based on a Gradle
+     * property `com.google.android.filament.tools-dir` if present, otherwise it resolves the tool
+     * through a Gradle configuration.
+     *
+     * @param tool The {@link ToolConfig} object whose {@code files} property will be set.
+     * @param name The name of the tool (e.g., "matc", "cmgen").
+     */
+    private void resolveTool(ToolConfig tool, String name) {
+        // Find the OS classifier, e.g. 'osx-aarch_64'.
+        def classifier =
+                project.extensions.getByType(com.google.gradle.osdetector.OsDetector).classifier
+
+        // If com.google.android.filament.tools-dir is set, we'll use it as the tool's base path.
+        def toolsDirProp = project.providers.gradleProperty("com.google.android.filament.tools-dir")
+        if (toolsDirProp.isPresent()) {
+            def toolsDir = toolsDirProp.get()
+            def path = OperatingSystem.current().isWindows() ?
+                "${toolsDir}/bin/${name}.exe" :
+                "${toolsDir}/bin/${name}"
+            tool.files = project.files(path)
+            return
+        }
+
+        // If an explicit path for the tool is provided in ToolConfig
+        // (e.g. matc { path = 'path/to/tool' }), use it directly.
+        if (tool.path) {
+            tool.files = project.files(tool.path)
+            return
+        }
+
+        // Otherwise, if an artifact is provided
+        // (e.g. matc { artifact = 'com.google.android.filament:matc:1.68.5' }), resolve it.
+        if (tool.artifact) {
+            String depString = tool.artifact
+
+            // In Gradle, a configuration is a named, manageable group of dependencies.
+            // Resolve the tool artifact using a detached configuration. A detached configuration
+            // is a temporary, isolated configuration that is not part of the project's regular
+            // configuration hierarchy.
+            Configuration config = project.configurations.detachedConfiguration()
+            config.setTransitive(false) // We only want the tool itself, not its dependencies
+
+            def dep = project.dependencies.create("${depString}:${classifier}@exe")
+            config.dependencies.add(dep)
+
+            // A Gradle Configuration implements FileCollection. When treated as a FileCollection,
+            // it represents the resolved files of its dependencies.
+            tool.files = config
+        }
+    }
+
+    FileCollection getMatcToolFiles() {
+        return matc.files ?: project.files()
+    }
+
+    FileCollection getCmgenToolFiles() {
+        return cmgen.files ?: project.files()
+    }
+
+    FileCollection getFilameshToolFiles() {
+        return filamesh.files ?: project.files()
+    }
+}

android/filament-android/src/main/cpp/Camera.cpp

@@ -18,6 +18,7 @@
 
 #include <filament/Camera.h>
 
+
 #include <utils/Entity.h>
 
 #include <math/mat4.h>
@@ -40,6 +41,13 @@ Java_com_google_android_filament_Camera_nSetProjectionFov(JNIEnv*, jclass ,
     camera->setProjection(fovInDegrees, aspect, near, far, (Camera::Fov) fov);
 }
 
+extern "C" JNIEXPORT jdouble JNICALL
+Java_com_google_android_filament_Camera_nGetFieldOfViewInDegrees(JNIEnv*, jclass,
+        jlong nativeCamera, jint direction) {
+    Camera *camera = (Camera *) nativeCamera;
+    return camera->getFieldOfViewInDegrees((Camera::Fov) direction);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nSetLensProjection(JNIEnv*, jclass,
         jlong nativeCamera, jdouble focalLength, jdouble aspect, jdouble near, jdouble far) {
@@ -62,6 +70,21 @@ Java_com_google_android_filament_Camera_nSetCustomProjection(JNIEnv *env, jclass
     env->ReleaseDoubleArrayElements(inProjectionForCulling_, inProjectionForCulling, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nSetCustomEyeProjection(JNIEnv *env, jclass,
+        jlong nativeCamera, jdoubleArray inProjection_, jint count, jdoubleArray inProjectionForCulling_,
+        jdouble near, jdouble far) {
+    Camera *camera = (Camera *) nativeCamera;
+    jdouble *inProjection = env->GetDoubleArrayElements(inProjection_, NULL);
+    jdouble *inProjectionForCulling = env->GetDoubleArrayElements(inProjectionForCulling_, NULL);
+    camera->setCustomEyeProjection(
+            reinterpret_cast<const filament::math::mat4 *>(inProjection), (size_t) count,
+            *reinterpret_cast<const filament::math::mat4 *>(inProjectionForCulling),
+            near, far);
+    env->ReleaseDoubleArrayElements(inProjection_, inProjection, JNI_ABORT);
+    env->ReleaseDoubleArrayElements(inProjectionForCulling_, inProjectionForCulling, JNI_ABORT);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nSetScaling(JNIEnv* env, jclass,
         jlong nativeCamera, jdouble x, jdouble y) {
@@ -76,6 +99,17 @@ Java_com_google_android_filament_Camera_nSetShift(JNIEnv* env, jclass,
     camera->setShift({(double)x, (double)y});
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nGetShift(JNIEnv* env, jclass,
+        jlong nativeCamera, jdoubleArray out_) {
+    Camera *camera = (Camera *) nativeCamera;
+    jdouble *out = env->GetDoubleArrayElements(out_, NULL);
+    filament::math::double2 s = camera->getShift();
+    out[0] = s.x;
+    out[1] = s.y;
+    env->ReleaseDoubleArrayElements(out_, out, 0);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nLookAt(JNIEnv*, jclass, jlong nativeCamera,
         jdouble eye_x, jdouble eye_y, jdouble eye_z, jdouble center_x, jdouble center_y,
@@ -115,6 +149,15 @@ Java_com_google_android_filament_Camera_nSetModelMatrixFp64(JNIEnv *env, jclass,
     env->ReleaseDoubleArrayElements(in_, in, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Camera_nSetEyeModelMatrix(JNIEnv *env, jclass,
+        jlong nativeCamera, jint eyeId, jdoubleArray model_) {
+    Camera* camera = (Camera *) nativeCamera;
+    jdouble *model = env->GetDoubleArrayElements(model_, NULL);
+    camera->setEyeModelMatrix((uint8_t)eyeId, *reinterpret_cast<const filament::math::mat4*>(model));
+    env->ReleaseDoubleArrayElements(model_, model, JNI_ABORT);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Camera_nGetProjectionMatrix(JNIEnv *env, jclass,
         jlong nativeCamera, jdoubleArray out_) {
@@ -280,3 +323,5 @@ Java_com_google_android_filament_Camera_nComputeEffectiveFov(JNIEnv*, jclass,
         jdouble fovInDegrees, jdouble focusDistance) {
     return Camera::computeEffectiveFov(fovInDegrees, focusDistance);
 }
+
+

android/filament-android/src/main/cpp/Material.cpp

@@ -96,6 +96,14 @@ Java_com_google_android_filament_Material_nGetBlendingMode(JNIEnv*, jclass,
     return (jint) material->getBlendingMode();
 }
 
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getTransparencyMode();
+}
+
 
 extern "C"
 JNIEXPORT jint JNICALL

android/filament-android/src/main/cpp/MaterialInstance.cpp

@@ -564,3 +564,19 @@ Java_com_google_android_filament_MaterialInstance_nGetDepthFunc(JNIEnv* env, jcl
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return (jint)instance->getDepthFunc();
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint mode) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setTransparencyMode((MaterialInstance::TransparencyMode) mode);
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetTransparencyMode(JNIEnv*, jclass,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    return (jint) instance->getTransparencyMode();
+}

android/filament-android/src/main/cpp/RenderableManager.cpp

@@ -366,6 +366,13 @@ Java_com_google_android_filament_RenderableManager_nSetPriority(JNIEnv*, jclass,
     rm->setPriority((RenderableManager::Instance) i, (uint8_t) priority);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetPriority(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getPriority((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetChannel(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint channel) {
@@ -373,6 +380,13 @@ Java_com_google_android_filament_RenderableManager_nSetChannel(JNIEnv*, jclass,
     rm->setChannel((RenderableManager::Instance) i, (uint8_t) channel);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetChannel(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getChannel((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetCulling(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jboolean enabled) {
@@ -380,6 +394,13 @@ Java_com_google_android_filament_RenderableManager_nSetCulling(JNIEnv*, jclass,
     rm->setCulling((RenderableManager::Instance) i, enabled);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsCullingEnabled(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isCullingEnabled((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetFogEnabled(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jboolean enabled) {
@@ -429,6 +450,13 @@ Java_com_google_android_filament_RenderableManager_nIsShadowReceiver(JNIEnv*, jc
     return (jboolean) rm->isShadowReceiver((RenderableManager::Instance) i);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsScreenSpaceContactShadowsEnabled(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isScreenSpaceContactShadowsEnabled((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nGetAxisAlignedBoundingBox(JNIEnv* env,
         jclass, jlong nativeRenderableManager, jint i, jfloatArray center_,
@@ -500,6 +528,13 @@ Java_com_google_android_filament_RenderableManager_nSetBlendOrderAt(JNIEnv*, jcl
             (uint16_t) blendOrder);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetBlendOrderAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getBlendOrderAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetGlobalBlendOrderEnabledAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex, jboolean enabled) {
@@ -508,6 +543,13 @@ Java_com_google_android_filament_RenderableManager_nSetGlobalBlendOrderEnabledAt
             (bool) enabled);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_RenderableManager_nIsGlobalBlendOrderEnabledAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jboolean) rm->isGlobalBlendOrderEnabledAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_RenderableManager_nGetEnabledAttributesAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex) {

android/filament-android/src/main/cpp/Texture.cpp

@@ -173,6 +173,13 @@ Java_com_google_android_filament_Texture_nBuilderSwizzle(JNIEnv *, jclass ,
             (Texture::Swizzle)r, (Texture::Swizzle)g, (Texture::Swizzle)b, (Texture::Swizzle)a);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Texture_nBuilderSamples(JNIEnv*, jclass,
+        jlong nativeBuilder, jint samples) {
+    Texture::Builder *builder = (Texture::Builder *) nativeBuilder;
+    builder->samples((uint8_t) samples);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_Texture_nBuilderImportTexture(JNIEnv*, jclass, jlong nativeBuilder, jlong id) {

android/filament-android/src/main/cpp/View.cpp

@@ -76,6 +76,12 @@ Java_com_google_android_filament_View_nSetVisibleLayers(JNIEnv*, jclass, jlong n
     view->setVisibleLayers((uint8_t) select, (uint8_t) value);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_View_nGetVisibleLayers(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return view->getVisibleLayers();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetShadowingEnabled(JNIEnv*, jclass, jlong nativeView, jboolean enabled) {
     View* view = (View*) nativeView;
@@ -440,6 +446,18 @@ Java_com_google_android_filament_View_nIsShadowingEnabled(JNIEnv *, jclass, jlon
     return (jboolean)view->isShadowingEnabled();
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetFrustumCullingEnabled(JNIEnv*, jclass, jlong nativeView, jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setFrustumCullingEnabled(enabled);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsFrustumCullingEnabled(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return (jboolean)view->isFrustumCullingEnabled();
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetScreenSpaceRefractionEnabled(JNIEnv *, jclass,

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

@@ -136,4 +136,13 @@ final class Asserts {
             throw new ArrayIndexOutOfBoundsException("Array length must be at least 4");
         }
     }
+
+    @NonNull @Size(min = 2)
+    static double[] assertDouble2(@Nullable double[] out) {
+        if (out == null) out = new double[2];
+        else if (out.length < 2) {
+            throw new ArrayIndexOutOfBoundsException("Array length must be at least 2");
+        }
+        return out;
+    }
 }

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

@@ -343,6 +343,27 @@ public class Camera {
         nSetScaling(getNativeObject(), xscaling, yscaling);
     }
 
+    /**
+     * Sets a custom projection matrix for each eye.
+     *
+     * @param inProjection              An array of projection matrices, one for each eye.
+     *                                  Must have at least 16 * count elements.
+     * @param count                     Number of eyes to set.
+     * @param inProjectionForCulling    Custom projection matrix for culling, must encompass all eyes.
+     * @param near                      Distance to the near plane.
+     * @param far                       Distance to the far plane.
+     */
+    public void setCustomEyeProjection(
+            @NonNull double[] inProjection, int count,
+            @NonNull @Size(min = 16) double[] inProjectionForCulling,
+            double near, double far) {
+        Asserts.assertMat4dIn(inProjectionForCulling);
+        if (inProjection.length < 16 * count) {
+            throw new IllegalArgumentException("inProjection array too small for the given count");
+        }
+        nSetCustomEyeProjection(getNativeObject(), inProjection, count, inProjectionForCulling, near, far);
+    }
+
     /**
      * Sets an additional matrix that scales the projection matrix.
      *
@@ -399,6 +420,31 @@ public class Camera {
         nSetShift(getNativeObject(), xshift, yshift);
     }
 
+    /**
+     * Returns the shift amount used to translate the projection matrix.
+     *
+     * @param out A 2-double array where the shift will be stored, or null.
+     * @return A 2-double array containing the x and y shift.
+     */
+    @NonNull @Size(min = 2)
+    public double[] getShift(@Nullable @Size(min = 2) double[] out) {
+        out = Asserts.assertDouble2(out);
+        nGetShift(getNativeObject(), out);
+        return out;
+    }
+
+    /**
+     * Returns the camera's field of view in degrees.
+     *
+     * @param direction The direction of the FOV (VERTICAL or HORIZONTAL).
+     * @return The field of view in degrees.
+     */
+    public double getFieldOfViewInDegrees(@NonNull Fov direction) {
+        return nGetFieldOfViewInDegrees(getNativeObject(), direction.ordinal());
+    }
+
+
+
     /**
      * Sets the camera's model matrix.
      * <p>
@@ -745,6 +791,17 @@ public class Camera {
         return mEntity;
     }
 
+    /**
+     * Sets the model matrix for a specific eye.
+     *
+     * @param eyeId The index of the eye.
+     * @param model The model matrix for the eye.
+     */
+    public void setEyeModelMatrix(int eyeId, @NonNull @Size(min = 16) double[] model) {
+        Asserts.assertMat4dIn(model);
+        nSetEyeModelMatrix(getNativeObject(), eyeId, model);
+    }
+
     /**
      * Helper to compute the effective focal length taking into account the focus distance
      *
@@ -784,8 +841,13 @@ public class Camera {
     private static native void nSetCustomProjection(long nativeCamera, double[] inProjection, double[] inProjectionForCulling, double near, double far);
     private static native void nSetScaling(long nativeCamera, double x, double y);
     private static native void nSetShift(long nativeCamera, double x, double y);
+    private static native void nGetShift(long nativeCamera, double[] out);
     private static native void nSetModelMatrix(long nativeCamera, float[] in);
     private static native void nSetModelMatrixFp64(long nativeCamera, double[] in);
+    private static native void nSetEyeModelMatrix(long nativeCamera, int eyeId, double[] model);
+    private static native void nSetCustomEyeProjection(long nativeCamera, double[] inProjection, int count, double[] inProjectionForCulling, double near, double far);
+    private static native double nGetFieldOfViewInDegrees(long nativeCamera, int direction);
+
     private static native void nLookAt(long nativeCamera, double eyeX, double eyeY, double eyeZ, double centerX, double centerY, double centerZ, double upX, double upY, double upZ);
     private static native double nGetNear(long nativeCamera);
     private static native double nGetCullingFar(long nativeCamera);

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

@@ -54,6 +54,7 @@ public class Material {
         static final CullingMode[] sCullingModeValues = CullingMode.values();
         static final VertexBuffer.VertexAttribute[] sVertexAttributeValues =
                 VertexBuffer.VertexAttribute.values();
+        static final TransparencyMode[] sTransparencyModeValues = TransparencyMode.values();
     }
 
     private long mNativeObject;
@@ -160,6 +161,31 @@ public class Material {
         SCREEN,
     }
 
+    /**
+     * How transparent objects are handled
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/blendingandtransparency:transparencymode">
+     * Blending and transparency: transparencyMode</a>
+     */
+    public enum TransparencyMode {
+        /** The transparent object is drawn honoring the raster state. */
+        DEFAULT,
+
+        /**
+         * The transparent object is first drawn in the depth buffer,
+         * then in the color buffer, honoring the culling mode, but ignoring the depth test function.
+         */
+        TWO_PASSES_ONE_SIDE,
+
+        /**
+         * The transparent object is drawn twice in the color buffer,
+         * first with back faces only, then with front faces; the culling
+         * mode is ignored. Can be combined with two-sided lighting.
+         */
+        TWO_PASSES_TWO_SIDES
+    }
+
     /**
      * Supported refraction modes
      *
@@ -587,6 +613,18 @@ public class Material {
         return EnumCache.sBlendingModeValues[nGetBlendingMode(getNativeObject())];
     }
 
+    /**
+     * Returns the transparency mode of this material.
+     * This value only makes sense when the blending mode is transparent or fade.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/blendingandtransparency:transparencymode">
+     * Blending and transparency: transparencyMode</a>
+     */
+    public TransparencyMode getTransparencyMode() {
+        return EnumCache.sTransparencyModeValues[nGetTransparencyMode(getNativeObject())];
+    }
+
     /**
      * Returns the refraction mode of this material.
      *
@@ -1130,6 +1168,7 @@ public class Material {
     private static native int nGetShading(long nativeMaterial);
     private static native int nGetInterpolation(long nativeMaterial);
     private static native int nGetBlendingMode(long nativeMaterial);
+    private static native int nGetTransparencyMode(long nativeMaterial);
     private static native int nGetVertexDomain(long nativeMaterial);
     private static native int nGetCullingMode(long nativeMaterial);
     private static native boolean nIsColorWriteEnabled(long nativeMaterial);

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

@@ -537,6 +537,14 @@ public class MaterialInstance {
         nSetDoubleSided(getNativeObject(), doubleSided);
     }
 
+    /**
+     * Sets the transparency mode for this material instance.
+     * @see Material.TransparencyMode
+     */
+    public void setTransparencyMode(@NonNull Material.TransparencyMode mode) {
+        nSetTransparencyMode(getNativeObject(), mode.ordinal());
+    }
+
     /**
      * Returns whether double-sided lighting is enabled when the parent Material has double-sided
      * capability.
@@ -545,6 +553,14 @@ public class MaterialInstance {
         return nIsDoubleSided(getNativeObject());
     }
 
+    /**
+     * Returns the transparency mode.
+     */
+    @NonNull
+    public Material.TransparencyMode getTransparencyMode() {
+        return Material.EnumCache.sTransparencyModeValues[nGetTransparencyMode(getNativeObject())];
+    }
+
     /**
      * Overrides the default triangle culling state that was set on the material.
      *
@@ -982,4 +998,6 @@ public class MaterialInstance {
     private static native boolean nIsStencilWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsDepthCullingEnabled(long nativeMaterialInstance);
     private static native int nGetDepthFunc(long nativeMaterialInstance);
+    private static native void nSetTransparencyMode(long nativeMaterialInstance, int mode);
+    private static native int nGetTransparencyMode(long nativeMaterialInstance);
 }

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

@@ -346,8 +346,8 @@ public class RenderableManager {
          *
          * @return Builder reference for chaining calls.
          *
-         * @see Builder::blendOrder()
-         * @see Builder::priority()
+         * @see Builder#blendOrder()
+         * @see Builder#priority()
          * @see RenderableManager::setBlendOrderAt()
          */
         @NonNull
@@ -725,6 +725,10 @@ public class RenderableManager {
         nSetPriority(mNativeObject, i, priority);
     }
 
+    public int getPriority(@EntityInstance int i) {
+        return nGetPriority(mNativeObject, i);
+    }
+
     /**
      * Changes the channel of a renderable
      *
@@ -734,6 +738,10 @@ public class RenderableManager {
         nSetChannel(mNativeObject, i, channel);
     }
 
+    public int getChannel(@EntityInstance int i) {
+        return nGetChannel(mNativeObject, i);
+    }
+
     /**
      * Changes whether or not frustum culling is on.
      *
@@ -743,6 +751,10 @@ public class RenderableManager {
         nSetCulling(mNativeObject, i, enabled);
     }
 
+    public boolean isCullingEnabled(@EntityInstance int i) {
+        return nIsCullingEnabled(mNativeObject, i);
+    }
+
     /**
      * Changes whether or not the large-scale fog is applied to this renderable
      * @see Builder#fog
@@ -812,6 +824,10 @@ public class RenderableManager {
         nSetScreenSpaceContactShadows(mNativeObject, i, enabled);
     }
 
+    public boolean isScreenSpaceContactShadowsEnabled(@EntityInstance int i) {
+        return nIsScreenSpaceContactShadowsEnabled(mNativeObject, i);
+    }
+
     /**
      * Checks if the renderable can cast shadows.
      *
@@ -932,6 +948,10 @@ public class RenderableManager {
         nSetBlendOrderAt(mNativeObject, instance, primitiveIndex, blendOrder);
     }
 
+    public int getBlendOrderAt(@EntityInstance int instance, @IntRange(from = 0) int primitiveIndex) {
+        return nGetBlendOrderAt(mNativeObject, instance, primitiveIndex);
+    }
+
     /**
      * Changes whether the blend order is global or local to this Renderable (by default).
      *
@@ -946,6 +966,10 @@ public class RenderableManager {
         nSetGlobalBlendOrderEnabledAt(mNativeObject, instance, primitiveIndex, enabled);
     }
 
+    public boolean isGlobalBlendOrderEnabledAt(@EntityInstance int instance, @IntRange(from = 0) int primitiveIndex) {
+        return nIsGlobalBlendOrderEnabledAt(mNativeObject, instance, primitiveIndex);
+    }
+
     /**
      * Retrieves the set of enabled attribute slots in the given primitive's VertexBuffer.
      */
@@ -1013,8 +1037,11 @@ public class RenderableManager {
     private static native void nSetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float cx, float cy, float cz, float ex, float ey, float ez);
     private static native void nSetLayerMask(long nativeRenderableManager, int i, int select, int value);
     private static native void nSetPriority(long nativeRenderableManager, int i, int priority);
+    private static native int nGetPriority(long nativeRenderableManager, int i);
     private static native void nSetChannel(long nativeRenderableManager, int i, int channel);
+    private static native int nGetChannel(long nativeRenderableManager, int i);
     private static native void nSetCulling(long nativeRenderableManager, int i, boolean enabled);
+    private static native boolean nIsCullingEnabled(long nativeRenderableManager, int i);
     private static native void nSetFogEnabled(long nativeRenderableManager, int i, boolean enabled);
     private static native boolean nGetFogEnabled(long nativeRenderableManager, int i);
     private static native void nSetLightChannel(long nativeRenderableManager, int i, int channel, boolean enable);
@@ -1022,6 +1049,7 @@ public class RenderableManager {
     private static native void nSetCastShadows(long nativeRenderableManager, int i, boolean enabled);
     private static native void nSetReceiveShadows(long nativeRenderableManager, int i, boolean enabled);
     private static native void nSetScreenSpaceContactShadows(long nativeRenderableManager, int i, boolean enabled);
+    private static native boolean nIsScreenSpaceContactShadowsEnabled(long nativeRenderableManager, int i);
     private static native boolean nIsShadowCaster(long nativeRenderableManager, int i);
     private static native boolean nIsShadowReceiver(long nativeRenderableManager, int i);
     private static native void nGetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float[] center, float[] halfExtent);
@@ -1032,6 +1060,8 @@ public class RenderableManager {
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
     private static native void nSetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex, int blendOrder);
+    private static native int nGetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGlobalBlendOrderEnabledAt(long nativeRenderableManager, int i, int primitiveIndex, boolean enabled);
+    private static native boolean nIsGlobalBlendOrderEnabledAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native int nGetEnabledAttributesAt(long nativeRenderableManager, int i, int primitiveIndex);
 }

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

@@ -795,6 +795,17 @@ public class Texture {
             return this;
         }
 
+        /**
+         * Specifies the number of samples for multisample anti-aliasing.
+         * @param samples number of samples, must be at least 1. Default is 1.
+         * @return This Builder, for chaining calls.
+         */
+        @NonNull
+        public Builder samples(@IntRange(from = 1) int samples) {
+            nBuilderSamples(mNativeBuilder, samples);
+            return this;
+        }
+
         /**
          * Specifies the texture's internal format.
          * <p>The internal format specifies how texels are stored (which may be different from how
@@ -1370,6 +1381,7 @@ public class Texture {
     private static native void nBuilderFormat(long nativeBuilder, int format);
     private static native void nBuilderUsage(long nativeBuilder, int flags);
     private static native void nBuilderSwizzle(long nativeBuilder, int r, int g, int b, int a);
+    private static native void nBuilderSamples(long nativeBuilder, int samples);
     private static native void nBuilderImportTexture(long nativeBuilder, long id);
     private static native void nBuilderExternal(long nativeBuilder);
     private static native long nBuilderBuild(long nativeBuilder, long nativeEngine);

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

@@ -350,6 +350,26 @@ public class View {
         nSetVisibleLayers(getNativeObject(), select & 0xFF, values & 0xFF);
     }
 
+    /**
+     * Returns the visible layers.
+     *
+     * @return a bitmask specifying which layer is visible.
+     */
+    public int getVisibleLayers() {
+        return nGetVisibleLayers(getNativeObject());
+    }
+
+    /**
+     * Enables or disables a specific layer.
+     *
+     * @param layer     Index of the layer to enable or disable, must be between 0 and 7.
+     * @param enabled   True to enable the layer, false to disable it.
+     */
+    public void setLayerEnabled(@IntRange(from = 0, to = 7) int layer, boolean enabled) {
+        int mask = 1 << layer;
+        setVisibleLayers(mask, enabled ? mask : 0);
+    }
+
     /**
      * Enables or disables shadow mapping. Enabled by default.
      *
@@ -368,6 +388,22 @@ public class View {
         return nIsShadowingEnabled(getNativeObject());
     }
 
+    /**
+     * Enables or disables frustum culling. Enabled by default.
+     *
+     * @param enabled true enables frustum culling, false disables it.
+     */
+    public void setFrustumCullingEnabled(boolean enabled) {
+        nSetFrustumCullingEnabled(getNativeObject(), enabled);
+    }
+
+    /**
+     * @return whether frustum culling is enabled
+     */
+    public boolean isFrustumCullingEnabled() {
+        return nIsFrustumCullingEnabled(getNativeObject());
+    }
+
     /**
      * Enables or disables screen space refraction. Enabled by default.
      *
@@ -1322,6 +1358,9 @@ public class View {
     private static native boolean nHasCamera(long nativeView);
     private static native void nSetViewport(long nativeView, int left, int bottom, int width, int height);
     private static native void nSetVisibleLayers(long nativeView, int select, int value);
+    private static native int nGetVisibleLayers(long nativeView);
+    private static native void nSetFrustumCullingEnabled(long nativeView, boolean enabled);
+    private static native boolean nIsFrustumCullingEnabled(long nativeView);
     private static native void nSetShadowingEnabled(long nativeView, boolean enabled);
     private static native void nSetRenderTarget(long nativeView, long nativeRenderTarget);
     private static native void nSetSampleCount(long nativeView, int count);
@@ -1406,65 +1445,59 @@ public class View {
      * by lowering the resolution of a View, or to increase the quality when the
      * rendering is faster than the target frame rate.
      *
-     * This structure can be used to specify the minimum scale factor used when
+     * <p>This structure can be used to specify the minimum scale factor used when
      * lowering the resolution of a View, and the maximum scale factor used when
      * increasing the resolution for higher quality rendering. The scale factors
      * can be controlled on each X and Y axis independently. By default, all scale
-     * factors are set to 1.0.
+     * factors are set to 1.0.</p>
      *
-     * enabled:   enable or disables dynamic resolution on a View
+     * <ul>
+     * <li>enabled:   enable or disables dynamic resolution on a View</li>
      *
-     * homogeneousScaling: by default the system scales the major axis first. Set this to true
-     *                     to force homogeneous scaling.
+     * <li>homogeneousScaling: by default the system scales the major axis first. Set this to true
+     *                     to force homogeneous scaling.</li>
      *
-     * minScale:  the minimum scale in X and Y this View should use
+     * <li>minScale:  the minimum scale in X and Y this View should use</li>
      *
-     * maxScale:  the maximum scale in X and Y this View should use
+     * <li>maxScale:  the maximum scale in X and Y this View should use</li>
      *
-     * quality:   upscaling quality.
-     *            LOW: 1 bilinear tap, Medium: 4 bilinear taps, High: 9 bilinear taps (tent)
+     * <li>quality:   upscaling quality.
+     *            LOW: 1 bilinear tap, Medium: 4 bilinear taps, High: 9 bilinear taps (tent)</li>
+     * </ul>
      *
-     * \note
+     * <p>Note:
      * Dynamic resolution is only supported on platforms where the time to render
      * a frame can be measured accurately. On platforms where this is not supported,
-     * Dynamic Resolution can't be enabled unless minScale == maxScale.
+     * Dynamic Resolution can't be enabled unless <code>minScale == maxScale</code>.</p>
      *
-     * @see Renderer::FrameRateOptions
+     * @see Renderer.FrameRateOptions
      *
      */
     public static class DynamicResolutionOptions {
-        /**
-         * minimum scale factors in x and y
-         */
+        /** minimum scale factors in x and y */
         public float minScale = 0.5f;
-        /**
-         * maximum scale factors in x and y
-         */
+        /** maximum scale factors in x and y */
         public float maxScale = 1.0f;
-        /**
-         * sharpness when QualityLevel::MEDIUM or higher is used [0 (disabled), 1 (sharpest)]
-         */
+        /** sharpness when QualityLevel::MEDIUM or higher is used [0 (disabled), 1 (sharpest)] */
         public float sharpness = 0.9f;
-        /**
-         * enable or disable dynamic resolution
-         */
+        /** enable or disable dynamic resolution */
         public boolean enabled = false;
-        /**
-         * set to true to force homogeneous scaling
-         */
+        /** set to true to force homogeneous scaling */
         public boolean homogeneousScaling = false;
         /**
          * Upscaling quality
-         * LOW:    bilinear filtered blit. Fastest, poor quality
-         * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
-         * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
-         * ULTRA:  AMD FidelityFX FSR1
+         * <ul>
+         * <li>LOW:    bilinear filtered blit. Fastest, poor quality</li>
+         * <li>MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0</li>
+         * <li>HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations</li>
+         * <li>ULTRA:  AMD FidelityFX FSR1</li>
+         * </ul>
          *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene.
          *      Avoid FXAA and dithering.
          *
-         * The default upscaling quality is set to LOW.
+         * <p>The default upscaling quality is set to LOW.</p>
          *
-         * caveat: currently, 'quality' is always set to LOW if the View is TRANSLUCENT.
+         * <p>caveat: currently, <code>quality</code> is always set to LOW if the View is TRANSLUCENT.</p>
          */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
@@ -1473,134 +1506,98 @@ public class View {
     /**
      * Options to control the bloom effect
      *
-     * enabled:     Enable or disable the bloom post-processing effect. Disabled by default.
+     * <ul>
+     * <li>enabled:     Enable or disable the bloom post-processing effect. Disabled by default.</li>
      *
-     * levels:      Number of successive blurs to achieve the blur effect, the minimum is 3 and the
+     * <li>levels:      Number of successive blurs to achieve the blur effect, the minimum is 3 and the
      *              maximum is 12. This value together with resolution influences the spread of the
      *              blur effect. This value can be silently reduced to accommodate the original
-     *              image size.
+     *              image size.</li>
      *
-     * resolution:  Resolution of bloom's minor axis. The minimum value is 2^levels and the
+     * <li>resolution:  Resolution of bloom's minor axis. The minimum value is 2^levels and the
      *              the maximum is lower of the original resolution and 4096. This parameter is
      *              silently clamped to the minimum and maximum.
      *              It is highly recommended that this value be smaller than the target resolution
-     *              after dynamic resolution is applied (horizontally and vertically).
+     *              after dynamic resolution is applied (horizontally and vertically).</li>
      *
-     * strength:    how much of the bloom is added to the original image. Between 0 and 1.
+     * <li>strength:    how much of the bloom is added to the original image. Between 0 and 1.</li>
      *
-     * blendMode:   Whether the bloom effect is purely additive (false) or mixed with the original
-     *              image (true).
+     * <li>blendMode:   Whether the bloom effect is purely additive (false) or mixed with the original
+     *              image (true).</li>
      *
-     * threshold:   When enabled, a threshold at 1.0 is applied on the source image, this is
-     *              useful for artistic reasons and is usually needed when a dirt texture is used.
+     * <li>threshold:   When enabled, a threshold at 1.0 is applied on the source image, this is
+     *              useful for artistic reasons and is usually needed when a dirt texture is used.</li>
      *
-     * dirt:        A dirt/scratch/smudges texture (that can be RGB), which gets added to the
+     * <li>dirt:        A dirt/scratch/smudges texture (that can be RGB), which gets added to the
      *              bloom effect. Smudges are visible where bloom occurs. Threshold must be
-     *              enabled for the dirt effect to work properly.
+     *              enabled for the dirt effect to work properly.</li>
      *
-     * dirtStrength: Strength of the dirt texture.
+     * <li>dirtStrength: Strength of the dirt texture.</li>
+     * </ul>
      */
     public static class BloomOptions {
         public enum BlendMode {
-            /**
-             * Bloom is modulated by the strength parameter and added to the scene
-             */
+            /** Bloom is modulated by the strength parameter and added to the scene */
             ADD,
-            /**
-             * Bloom is interpolated with the scene using the strength parameter
-             */
+            /** Bloom is interpolated with the scene using the strength parameter */
             INTERPOLATE,
         }
 
-        /**
-         * user provided dirt texture
-         */
+        /** user provided dirt texture */
         @Nullable
         public Texture dirt = null;
-        /**
-         * strength of the dirt texture
-         */
+        /** strength of the dirt texture */
         public float dirtStrength = 0.2f;
-        /**
-         * bloom's strength between 0.0 and 1.0
-         */
+        /** bloom's strength between 0.0 and 1.0 */
         public float strength = 0.10f;
-        /**
-         * resolution of vertical axis (2^levels to 2048)
-         */
+        /** resolution of vertical axis (2^levels to 2048) */
         public int resolution = 384;
-        /**
-         * number of blur levels (1 to 11)
-         */
+        /** number of blur levels (1 to 11) */
         public int levels = 6;
-        /**
-         * how the bloom effect is applied
-         */
+        /** how the bloom effect is applied */
         @NonNull
         public BloomOptions.BlendMode blendMode = BloomOptions.BlendMode.ADD;
-        /**
-         * whether to threshold the source
-         */
+        /** whether to threshold the source */
         public boolean threshold = true;
-        /**
-         * enable or disable bloom
-         */
+        /** enable or disable bloom */
         public boolean enabled = false;
-        /**
-         * limit highlights to this value before bloom [10, +inf]
-         */
+        /** limit highlights to this value before bloom [10, +inf] */
         public float highlight = 1000.0f;
         /**
          * Bloom quality level.
-         * LOW (default): use a more optimized down-sampling filter, however there can be artifacts
-         *      with dynamic resolution, this can be alleviated by using the homogenous mode.
-         * MEDIUM: Good balance between quality and performance.
-         * HIGH: In this mode the bloom resolution is automatically increased to avoid artifacts.
+         * <ul>
+         * <li>LOW (default): use a more optimized down-sampling filter, however there can be artifacts
+         *      with dynamic resolution, this can be alleviated by using the homogenous mode.</li>
+         * <li>MEDIUM: Good balance between quality and performance.</li>
+         * <li>HIGH: In this mode the bloom resolution is automatically increased to avoid artifacts.
          *      This mode can be significantly slower on mobile, especially at high resolution.
-         *      This mode greatly improves the anamorphic bloom.
+         *      This mode greatly improves the anamorphic bloom.</li>
+         * </ul>
          */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
-        /**
-         * enable screen-space lens flare
-         */
+        /** enable screen-space lens flare */
         public boolean lensFlare = false;
-        /**
-         * enable starburst effect on lens flare
-         */
+        /** enable starburst effect on lens flare */
         public boolean starburst = true;
-        /**
-         * amount of chromatic aberration
-         */
+        /** amount of chromatic aberration */
         public float chromaticAberration = 0.005f;
-        /**
-         * number of flare "ghosts"
-         */
+        /** number of flare "ghosts" */
         public int ghostCount = 4;
-        /**
-         * spacing of the ghost in screen units [0, 1[
-         */
+        /** spacing of the ghost in screen units [0, 1[ */
         public float ghostSpacing = 0.6f;
-        /**
-         * hdr threshold for the ghosts
-         */
+        /** hdr threshold for the ghosts */
         public float ghostThreshold = 10.0f;
-        /**
-         * thickness of halo in vertical screen units, 0 to disable
-         */
+        /** thickness of halo in vertical screen units, 0 to disable */
         public float haloThickness = 0.1f;
-        /**
-         * radius of halo in vertical screen units [0, 0.5]
-         */
+        /** radius of halo in vertical screen units [0, 0.5] */
         public float haloRadius = 0.4f;
-        /**
-         * hdr threshold for the halo
-         */
+        /** hdr threshold for the halo */
         public float haloThreshold = 10.0f;
     }
 
     /**
-     * Options to control large-scale fog in the scene. Materials can enable the `linearFog` property,
+     * Options to control large-scale fog in the scene. Materials can enable the <code>linearFog</code> property,
      * which uses a simplified, linear equation for fog calculation; in this mode, the heightFalloff
      * is ignored as well as the mipmap selection in IBL or skyColor mode.
      */
@@ -1614,12 +1611,12 @@ public class View {
          * This can be used to exclude the skybox, which is desirable if it already contains clouds or
          * fog. The default value is +infinity which applies the fog to everything.
          *
-         * Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
-         * plane distance and projection used though).
+         * <p>Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
+         * plane distance and projection used though).</p>
          */
         public float cutOffDistance = Float.POSITIVE_INFINITY;
         /**
-         * fog's maximum opacity between 0 and 1. Ignored in `linearFog` mode.
+         * fog's maximum opacity between 0 and 1. Ignored in <code>linearFog</code> mode.
          */
         public float maximumOpacity = 1.0f;
         /**
@@ -1631,11 +1628,11 @@ public class View {
          * It can be expressed as 1/H, where H is the altitude change in world units [m] that causes a
          * factor 2.78 (e) change in fog density.
          *
-         * A falloff of 0 means the fog density is constant everywhere and may result is slightly
-         * faster computations.
+         * <p>A falloff of 0 means the fog density is constant everywhere and may result is slightly
+         * faster computations.</p>
          *
-         * In `linearFog` mode, only use to compute the slope of the linear equation. Completely
-         * ignored if set to 0.
+         * <p>In <code>linearFog</code> mode, only use to compute the slope of the linear equation. Completely
+         * ignored if set to 0.</p>
          */
         public float heightFalloff = 1.0f;
         /**
@@ -1645,11 +1642,11 @@ public class View {
          *  above one are allowed but could create a non energy-conservative fog (this is dependant
          *  on the IBL's intensity as well).
          *
-         *  We assume that our fog has no absorption and therefore all the light it scatters out
+         *  <p>We assume that our fog has no absorption and therefore all the light it scatters out
          *  becomes ambient light in-scattering and has lost all directionality, i.e.: scattering is
-         *  isotropic. This somewhat simulates Rayleigh scattering.
+         *  isotropic. This somewhat simulates Rayleigh scattering.</p>
          *
-         *  This value is used as a tint instead, when fogColorFromIbl is enabled.
+         *  <p>This value is used as a tint instead, when fogColorFromIbl is enabled.</p>
          *
          *  @see #fogColorFromIbl
          */
@@ -1660,20 +1657,20 @@ public class View {
          * light is absorbed and out-scattered per unit of distance. Each unit of extinction reduces
          * the incoming light to 37% of its original value.
          *
-         * Note: The extinction factor is related to the fog density, it's usually some constant K times
+         * <p>Note: The extinction factor is related to the fog density, it's usually some constant K times
          * the density at sea level (more specifically at fog height). The constant K depends on
-         * the composition of the fog/atmosphere.
+         * the composition of the fog/atmosphere.</p>
          *
-         * For historical reason this parameter is called `density`.
+         * <p>For historical reason this parameter is called <code>density</code>.</p>
          *
-         * In `linearFog` mode this is the slope of the linear equation if heightFalloff is set to 0.
+         * <p>In <code>linearFog</code> mode this is the slope of the linear equation if heightFalloff is set to 0.
          * Otherwise, heightFalloff affects the slope calculation such that it matches the slope of
-         * the standard equation at the camera height.
+         * the standard equation at the camera height.</p>
          */
         public float density = 0.1f;
         /**
          * Distance in world units [m] from the camera where the Sun in-scattering starts.
-         * Ignored in `linearFog` mode.
+         * Ignored in <code>linearFog</code> mode.
          */
         public float inScatteringStart = 0.0f;
         /**
@@ -1681,16 +1678,16 @@ public class View {
          * is scattered (by the fog) towards the camera.
          * Size of the Sun in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
          * Smaller values result is a larger scattering size.
-         * Ignored in `linearFog` mode.
+         * Ignored in <code>linearFog</code> mode.
          */
         public float inScatteringSize = -1.0f;
         /**
-         * The fog color will be sampled from the IBL in the view direction and tinted by `color`.
+         * The fog color will be sampled from the IBL in the view direction and tinted by <code>color</code>.
          * Depending on the scene this can produce very convincing results.
          *
-         * This simulates a more anisotropic phase-function.
+         * <p>This simulates a more anisotropic phase-function.</p>
          *
-         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         * <p><code>fogColorFromIbl</code> is ignored when skyTexture is specified.</p>
          *
          * @see #skyColor
          */
@@ -1703,11 +1700,11 @@ public class View {
          * level with a strong gaussian filter or even an irradiance filter and then generate mip
          * levels as usual. How blurred the base level is somewhat of an artistic decision.
          *
-         * This simulates a more anisotropic phase-function.
+         * <p>This simulates a more anisotropic phase-function.</p>
          *
-         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         * <p><code>fogColorFromIbl</code> is ignored when skyTexture is specified.</p>
          *
-         * In `linearFog` mode mipmap level 0 is always used.
+         * <p>In <code>linearFog</code> mode mipmap level 0 is always used.</p>
          *
          * @see Texture
          * @see #fogColorFromIbl
@@ -1723,9 +1720,9 @@ public class View {
     /**
      * Options to control Depth of Field (DoF) effect in the scene.
      *
-     * cocScale can be used to set the depth of field blur independently of the camera
+     * <p>cocScale can be used to set the depth of field blur independently of the camera
      * aperture, e.g. for artistic reasons. This can be achieved by setting:
-     *      cocScale = cameraAperture / desiredDoFAperture
+     *      cocScale = cameraAperture / desiredDoFAperture</p>
      *
      * @see Camera
      */
@@ -1736,59 +1733,24 @@ public class View {
             MEDIAN,
         }
 
-        /**
-         * circle of confusion scale factor (amount of blur)
-         */
+        /** circle of confusion scale factor (amount of blur) */
         public float cocScale = 1.0f;
-        /**
-         * width/height aspect ratio of the circle of confusion (simulate anamorphic lenses)
-         */
+        /** width/height aspect ratio of the circle of confusion (simulate anamorphic lenses) */
         public float cocAspectRatio = 1.0f;
-        /**
-         * maximum aperture diameter in meters (zero to disable rotation)
-         */
+        /** maximum aperture diameter in meters (zero to disable rotation) */
         public float maxApertureDiameter = 0.01f;
-        /**
-         * enable or disable depth of field effect
-         */
+        /** enable or disable depth of field effect */
         public boolean enabled = false;
-        /**
-         * filter to use for filling gaps in the kernel
-         */
+        /** filter to use for filling gaps in the kernel */
         @NonNull
         public DepthOfFieldOptions.Filter filter = DepthOfFieldOptions.Filter.MEDIAN;
-        /**
-         * perform DoF processing at native resolution
-         */
+        /** perform DoF processing at native resolution */
         public boolean nativeResolution = false;
-        /**
-         * Number of of rings used by the gather kernels. The number of rings affects quality
-         * and performance. The actual number of sample per pixel is defined
-         * as (ringCount * 2 - 1)^2. Here are a few commonly used values:
-         *       3 rings :   25 ( 5x 5 grid)
-         *       4 rings :   49 ( 7x 7 grid)
-         *       5 rings :   81 ( 9x 9 grid)
-         *      17 rings : 1089 (33x33 grid)
-         *
-         * With a maximum circle-of-confusion of 32, it is never necessary to use more than 17 rings.
-         *
-         * Usually all three settings below are set to the same value, however, it is often
-         * acceptable to use a lower ring count for the "fast tiles", which improves performance.
-         * Fast tiles are regions of the screen where every pixels have a similar
-         * circle-of-confusion radius.
-         *
-         * A value of 0 means default, which is 5 on desktop and 3 on mobile.
-         *
-         * @{
-         */
+        /** number of kernel rings for foreground tiles */
         public int foregroundRingCount = 0;
-        /**
-         * number of kernel rings for background tiles
-         */
+        /** number of kernel rings for background tiles */
         public int backgroundRingCount = 0;
-        /**
-         * number of kernel rings for fast tiles
-         */
+        /** number of kernel rings for fast tiles */
         public int fastGatherRingCount = 0;
         /**
          * maximum circle-of-confusion in pixels for the foreground, must be in [0, 32] range.
@@ -1806,26 +1768,16 @@ public class View {
      * Options to control the vignetting effect.
      */
     public static class VignetteOptions {
-        /**
-         * high values restrict the vignette closer to the corners, between 0 and 1
-         */
+        /** high values restrict the vignette closer to the corners, between 0 and 1 */
         public float midPoint = 0.5f;
-        /**
-         * controls the shape of the vignette, from a rounded rectangle (0.0), to an oval (0.5), to a circle (1.0)
-         */
+        /** controls the shape of the vignette, from a rounded rectangle (0.0), to an oval (0.5), to a circle (1.0) */
         public float roundness = 0.5f;
-        /**
-         * softening amount of the vignette effect, between 0 and 1
-         */
+        /** softening amount of the vignette effect, between 0 and 1 */
         public float feather = 0.5f;
-        /**
-         * color of the vignette effect, alpha is currently ignored
-         */
+        /** color of the vignette effect, alpha is currently ignored */
         @NonNull @Size(min = 4)
         public float[] color = {0.0f, 0.0f, 0.0f, 1.0f};
-        /**
-         * enables or disables the vignette effect
-         */
+        /** enables or disables the vignette effect */
         public boolean enabled = false;
     }
 
@@ -1839,11 +1791,11 @@ public class View {
         /**
          * Sets the quality of the HDR color buffer.
          *
-         * A quality of HIGH or ULTRA means using an RGB16F or RGBA16F color buffer. This means
+         * <p>A quality of HIGH or ULTRA means using an RGB16F or RGBA16F color buffer. This means
          * colors in the LDR range (0..1) have a 10 bit precision. A quality of LOW or MEDIUM means
          * using an R11G11B10F opaque color buffer or an RGBA16F transparent color buffer. With
          * R11G11B10F colors in the LDR range have a precision of either 6 bits (red and green
-         * channels) or 5 bits (blue channel).
+         * channels) or 5 bits (blue channel).</p>
          */
         @NonNull
         public QualityLevel hdrColorBuffer = QualityLevel.HIGH;
@@ -1855,72 +1807,44 @@ public class View {
      */
     public static class AmbientOcclusionOptions {
         public enum AmbientOcclusionType {
-            /**
-             * use Scalable Ambient Occlusion
-             */
+            /** use Scalable Ambient Occlusion */
             SAO,
-            /**
-             * use Ground Truth-Based Ambient Occlusion
-             */
+            /** use Ground Truth-Based Ambient Occlusion */
             GTAO,
         }
 
-        /**
-         * Type of ambient occlusion algorithm.
-         */
+        /** Type of ambient occlusion algorithm. */
         @NonNull
         public AmbientOcclusionOptions.AmbientOcclusionType aoType = AmbientOcclusionOptions.AmbientOcclusionType.SAO;
-        /**
-         * Ambient Occlusion radius in meters, between 0 and ~10.
-         */
+        /** Ambient Occlusion radius in meters, between 0 and ~10. */
         public float radius = 0.3f;
-        /**
-         * Controls ambient occlusion's contrast. Must be positive.
-         */
+        /** Controls ambient occlusion's contrast. Must be positive. */
         public float power = 1.0f;
         /**
          * Self-occlusion bias in meters. Use to avoid self-occlusion.
          * Between 0 and a few mm. No effect when aoType set to GTAO
          */
         public float bias = 0.0005f;
-        /**
-         * How each dimension of the AO buffer is scaled. Must be either 0.5 or 1.0.
-         */
+        /** How each dimension of the AO buffer is scaled. Must be either 0.5 or 1.0. */
         public float resolution = 0.5f;
-        /**
-         * Strength of the Ambient Occlusion effect.
-         */
+        /** Strength of the Ambient Occlusion effect. */
         public float intensity = 1.0f;
-        /**
-         * depth distance that constitute an edge for filtering
-         */
+        /** depth distance that constitute an edge for filtering */
         public float bilateralThreshold = 0.05f;
-        /**
-         * affects # of samples used for AO and params for filtering
-         */
+        /** affects # of samples used for AO and params for filtering */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
-        /**
-         * affects AO smoothness. Recommend setting to HIGH when aoType set to GTAO.
-         */
+        /** affects AO smoothness. Recommend setting to HIGH when aoType set to GTAO. */
         @NonNull
         public QualityLevel lowPassFilter = QualityLevel.MEDIUM;
-        /**
-         * affects AO buffer upsampling quality
-         */
+        /** affects AO buffer upsampling quality */
         @NonNull
         public QualityLevel upsampling = QualityLevel.LOW;
-        /**
-         * enables or disables screen-space ambient occlusion
-         */
+        /** enables or disables screen-space ambient occlusion */
         public boolean enabled = false;
-        /**
-         * enables bent normals computation from AO, and specular AO
-         */
+        /** enables bent normals computation from AO, and specular AO */
         public boolean bentNormals = false;
-        /**
-         * min angle in radian to consider. No effect when aoType set to GTAO.
-         */
+        /** min angle in radian to consider. No effect when aoType set to GTAO. */
         public float minHorizonAngleRad = 0.0f;
         /**
          * Screen Space Cone Tracing (SSCT) options
@@ -2006,12 +1930,10 @@ public class View {
      * @see #setMultiSampleAntiAliasingOptions
      */
     public static class MultiSampleAntiAliasingOptions {
-        /**
-         * enables or disables msaa
-         */
+        /** enables or disables msaa */
         public boolean enabled = false;
         /**
-         * sampleCount number of samples to use for multi-sampled anti-aliasing.\n
+         * sampleCount number of samples to use for multi-sampled anti-aliasing.<br>
          *              0: treated as 1
          *              1: no anti-aliasing
          *              n: sample count. Effective sample could be different depending on the
@@ -2030,106 +1952,75 @@ public class View {
      * shaders to be recompiled. These options should be changed or set during initialization.
      * `filterWidth`, `feedback` and `jitterPattern`, however, can be changed at any time.
      *
-     * `feedback` of 0.1 effectively accumulates a maximum of 19 samples in steady state.
-     * see "A Survey of Temporal Antialiasing Techniques" by Lei Yang and all for more information.
+     * <p><code>feedback</code> of 0.1 effectively accumulates a maximum of 19 samples in steady state.
+     * see "A Survey of Temporal Antialiasing Techniques" by Lei Yang and all for more information.</p>
      *
      * @see #setTemporalAntiAliasingOptions
      */
     public static class TemporalAntiAliasingOptions {
         public enum BoxType {
-            /**
-             * use an AABB neighborhood
-             */
+            /** use an AABB neighborhood */
             AABB,
-            /**
-             * use both AABB and variance
-             */
+            /** use both AABB and variance */
             AABB_VARIANCE,
         }
 
         public enum BoxClipping {
-            /**
-             * Accurate box clipping
-             */
+            /** Accurate box clipping */
             ACCURATE,
-            /**
-             * clamping
-             */
+            /** clamping */
             CLAMP,
-            /**
-             * no rejections (use for debugging)
-             */
+            /** no rejections (use for debugging) */
             NONE,
         }
 
         public enum JitterPattern {
+            /** 4-samples, rotated grid sampling */
             RGSS_X4,
+            /** 4-samples, uniform grid in helix sequence */
             UNIFORM_HELIX_X4,
+            /** 8-samples of halton 2,3 */
             HALTON_23_X8,
+            /** 16-samples of halton 2,3 */
             HALTON_23_X16,
+            /** 32-samples of halton 2,3 */
             HALTON_23_X32,
         }
 
-        /**
-         * @deprecated has no effect.
-         */
+        /** @deprecated has no effect. */
         public float filterWidth = 1.0f;
-        /**
-         * history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
-         */
+        /** history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA). */
         public float feedback = 0.12f;
-        /**
-         * texturing lod bias (typically -1 or -2)
-         */
+        /** texturing lod bias (typically -1 or -2) */
         public float lodBias = -1.0f;
-        /**
-         * post-TAA sharpen, especially useful when upscaling is true.
-         */
+        /** post-TAA sharpen, especially useful when upscaling is true. */
         public float sharpness = 0.0f;
-        /**
-         * enables or disables temporal anti-aliasing
-         */
+        /** enables or disables temporal anti-aliasing */
         public boolean enabled = false;
-        /**
-         * Upscaling factor. Disables Dynamic Resolution. [BETA]
-         */
+        /** Upscaling factor. Disables Dynamic Resolution. [BETA] */
         public float upscaling = 1.0f;
-        /**
-         * whether to filter the history buffer
-         */
+        /** whether to filter the history buffer */
         public boolean filterHistory = true;
-        /**
-         * whether to apply the reconstruction filter to the input
-         */
+        /** whether to apply the reconstruction filter to the input */
         public boolean filterInput = true;
-        /**
-         * whether to use the YcoCg color-space for history rejection
-         */
+        /** whether to use the YcoCg color-space for history rejection */
         public boolean useYCoCg = false;
-        /**
-         * set to true for HDR content
-         */
+        /** set to true for HDR content */
         public boolean hdr = true;
-        /**
-         * type of color gamut box
-         */
+        /** type of color gamut box */
         @NonNull
         public TemporalAntiAliasingOptions.BoxType boxType = TemporalAntiAliasingOptions.BoxType.AABB;
-        /**
-         * clipping algorithm
-         */
+        /** clipping algorithm */
         @NonNull
         public TemporalAntiAliasingOptions.BoxClipping boxClipping = TemporalAntiAliasingOptions.BoxClipping.ACCURATE;
+        /** Jitter Pattern */
         @NonNull
         public TemporalAntiAliasingOptions.JitterPattern jitterPattern = TemporalAntiAliasingOptions.JitterPattern.HALTON_23_X16;
+        /** High values increases ghosting artefact, lower values increases jittering, range [0.75, 1.25] */
         public float varianceGamma = 1.0f;
-        /**
-         * adjust the feedback dynamically to reduce flickering
-         */
+        /** adjust the feedback dynamically to reduce flickering */
         public boolean preventFlickering = false;
-        /**
-         * whether to apply history reprojection (debug option)
-         */
+        /** whether to apply history reprojection (debug option) */
         public boolean historyReprojection = true;
     }
 
@@ -2138,30 +2029,22 @@ public class View {
      * @see #setScreenSpaceReflectionsOptions
      */
     public static class ScreenSpaceReflectionsOptions {
-        /**
-         * ray thickness, in world units
-         */
+        /** ray thickness, in world units */
         public float thickness = 0.1f;
-        /**
-         * bias, in world units, to prevent self-intersections
-         */
+        /** bias, in world units, to prevent self-intersections */
         public float bias = 0.01f;
-        /**
-         * maximum distance, in world units, to raycast
-         */
+        /** maximum distance, in world units, to raycast */
         public float maxDistance = 3.0f;
-        /**
-         * stride, in texels, for samples along the ray.
-         */
+        /** stride, in texels, for samples along the ray. */
         public float stride = 2.0f;
         public boolean enabled = false;
     }
 
     /**
      * Options for the  screen-space guard band.
-     * A guard band can be enabled to avoid some artifacts towards the edge of the screen when
+     * <p>A guard band can be enabled to avoid some artifacts towards the edge of the screen when
      * using screen-space effects such as SSAO. Enabling the guard band reduces performance slightly.
-     * Currently the guard band can only be enabled or disabled.
+     * Currently the guard band can only be enabled or disabled.</p>
      */
     public static class GuardBandOptions {
         public boolean enabled = false;
@@ -2174,13 +2057,9 @@ public class View {
      * @see #setSampleCount
      */
     public enum AntiAliasing {
-        /**
-         * no anti aliasing performed as part of post-processing
-         */
+        /** no anti aliasing performed as part of post-processing */
         NONE,
-        /**
-         * FXAA is a low-quality but very efficient type of anti-aliasing. (default).
-         */
+        /** FXAA is a low-quality but very efficient type of anti-aliasing. (default). */
         FXAA,
     }
 
@@ -2188,13 +2067,9 @@ public class View {
      * List of available post-processing dithering techniques.
      */
     public enum Dithering {
-        /**
-         * No dithering
-         */
+        /** No dithering */
         NONE,
-        /**
-         * Temporal dithering (default)
-         */
+        /** Temporal dithering (default) */
         TEMPORAL,
     }
 
@@ -2203,21 +2078,13 @@ public class View {
      * @see #setShadowType
      */
     public enum ShadowType {
-        /**
-         * percentage-closer filtered shadows (default)
-         */
+        /** percentage-closer filtered shadows (default) */
         PCF,
-        /**
-         * variance shadows
-         */
+        /** variance shadows */
         VSM,
-        /**
-         * PCF with contact hardening simulation
-         */
+        /** PCF with contact hardening simulation */
         DPCF,
-        /**
-         * PCF with soft shadows and contact hardening
-         */
+        /** PCF with soft shadows and contact hardening */
         PCSS,
         PCFd,
     }
@@ -2225,14 +2092,14 @@ public class View {
     /**
      * View-level options for VSM Shadowing.
      * @see #setVsmShadowOptions
-     * @warning This API is still experimental and subject to change.
+     * <b>Warning:</b> This API is still experimental and subject to change.
      */
     public static class VsmShadowOptions {
         /**
          * Sets the number of anisotropic samples to use when sampling a VSM shadow map. If greater
          * than 0, mipmaps will automatically be generated each frame for all lights.
          *
-         * The number of anisotropic samples = 2 ^ vsmAnisotropy.
+         * <p>The number of anisotropic samples = 2 ^ vsmAnisotropy.</p>
          */
         public int anisotropy = 0;
         /**
@@ -2254,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;
         /**
@@ -2266,7 +2133,7 @@ public class View {
     /**
      * View-level options for DPCF and PCSS Shadowing.
      * @see #setSoftShadowOptions
-     * @warning This API is still experimental and subject to change.
+     * <b>Warning:</b> This API is still experimental and subject to change.
      */
     public static class SoftShadowOptions {
         /**

android/filament-tools/build.gradle

@@ -7,7 +7,7 @@ apply from: rootProject.file('gradle/gradle-mvn-push.gradle')
 def tools = ['matc', 'cmgen']
 
 def platforms = [
-    'mac':     [classifier: 'osx-aarch64',    archive: "filament-v${VERSION_NAME}-mac.tgz",     path: { t -> "filament/bin/${t}" }],
+    'mac':     [classifier: 'osx-aarch_64',    archive: "filament-v${VERSION_NAME}-mac.tgz",     path: { t -> "filament/bin/${t}" }],
     'linux':   [classifier: 'linux-x86_64',   archive: "filament-v${VERSION_NAME}-linux.tgz",   path: { t -> "filament/bin/${t}" }],
     'windows': [classifier: 'windows-x86_64', archive: "filament-v${VERSION_NAME}-windows.tgz", path: { t -> "bin/${t}.exe" }]
 ]

android/filament-utils-android/CMakeLists.txt

@@ -22,6 +22,10 @@ add_library(image STATIC IMPORTED)
 set_target_properties(image PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimage.a)
 
+add_library(imageio-lite STATIC IMPORTED)
+set_target_properties(imageio-lite PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimageio-lite.a)
+
 add_library(ktxreader STATIC IMPORTED)
 set_target_properties(ktxreader PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libktxreader.a)
@@ -30,6 +34,10 @@ add_library(viewer STATIC IMPORTED)
 set_target_properties(viewer PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libviewer.a)
 
+add_library(imagediff STATIC IMPORTED)
+set_target_properties(imagediff PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libimagediff.a)
+
 add_library(civetweb STATIC IMPORTED)
 set_target_properties(civetweb PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libcivetweb.a)
@@ -57,6 +65,7 @@ add_library(filament-utils-jni SHARED
         src/main/cpp/IBLPrefilterContext.cpp
         src/main/cpp/Utils.cpp
         src/main/cpp/Manipulator.cpp
+        src/main/cpp/ImageDiff.cpp
         src/main/cpp/RemoteServer.cpp
 
         ${IMAGEIO_DIR}/include/imageio/ImageDecoder.h
@@ -74,6 +83,7 @@ target_include_directories(filament-utils-jni PRIVATE
         ${FILAMENT_DIR}/include
         ../../filament/backend/include
         ${IMAGEIO_DIR}/include
+        ../../libs/imagediff/include
         ../../libs/utils/include)
 
 set_target_properties(filament-utils-jni PROPERTIES LINK_DEPENDS ${VERSION_SCRIPT})
@@ -85,10 +95,13 @@ target_link_libraries(filament-utils-jni
         PRIVATE camutils
         PRIVATE iblprefilter
         PRIVATE image
+        PRIVATE imageio-lite
         PRIVATE filament-jni
         PRIVATE ktxreader
         PRIVATE viewer
+        PRIVATE imagediff
         PRIVATE log
         PRIVATE utils
         PRIVATE perfetto        # needed only when FILAMENT_ENABLE_PERFETTO is defined
+        PRIVATE jnigraphics     # needed for AndroidBitmap_* functions in ImageDiff
 )

android/filament-utils-android/src/main/cpp/AutomationEngine.cpp

@@ -71,8 +71,10 @@ Java_com_google_android_filament_utils_AutomationEngine_nStartBatchMode(JNIEnv*
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclass klass,
         jlong nativeAutomation, jlong nativeEngine,
-        jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
+        jlong view, jlongArray materials, jlong renderer, jlong nativeIbl, jint sunlightEntity,
+        jintArray assetLights, jlong nativeLm, jlong scene, jfloat deltaTime) {
     using MaterialPointer = MaterialInstance*;
+
     jsize materialCount = 0;
     jlong* longMaterials = nullptr;
     MaterialPointer* ptrMaterials = nullptr;
@@ -84,12 +86,28 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
             ptrMaterials[i] = (MaterialPointer) longMaterials[i];
         }
     }
+
+    jsize lightCount = 0;
+    jint* intLights = nullptr;
+    if (assetLights) {
+        lightCount = env->GetArrayLength(assetLights);
+        intLights = env->GetIntArrayElements(assetLights, nullptr);
+    }
+
+    static_assert(sizeof(jint) == sizeof(Entity));
+
     AutomationEngine* automation = (AutomationEngine*) nativeAutomation;
     AutomationEngine::ViewerContent content = {
         .view = (View*) view,
         .renderer = (Renderer*) renderer,
         .materials = ptrMaterials,
         .materialCount = (size_t) materialCount,
+        .lightManager = (LightManager*) nativeLm,
+        .scene = (Scene*) scene,
+        .indirectLight = (IndirectLight*) nativeIbl,
+        .sunlight = (Entity&) sunlightEntity,
+        .assetLights = (Entity*) intLights,
+        .assetLightCount = (size_t) lightCount,
     };
     Engine* engine = (Engine*)nativeEngine;
     automation->tick(engine, content, deltaTime);
@@ -97,6 +115,9 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
         delete[] ptrMaterials;
     }
+    if (intLights) {
+        env->ReleaseIntArrayElements(assetLights, intLights, 0);
+    }
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -159,37 +180,50 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nGetViewerOptions(JNIEnv* env, jclass,
         jlong nativeObject, jobject result) {
     AutomationEngine* automation = (AutomationEngine*) nativeObject;
-    auto options = automation->getViewerOptions();
+    const auto& settings = automation->getSettings();
+    const auto& options = settings.viewer;
 
     const jclass klass = env->GetObjectClass(result);
 
-    const jfieldID cameraAperture = env->GetFieldID(klass, "cameraAperture", "F");
-    const jfieldID cameraSpeed = env->GetFieldID(klass, "cameraSpeed", "F");
-    const jfieldID cameraISO = env->GetFieldID(klass, "cameraISO", "F");
-    const jfieldID cameraNear = env->GetFieldID(klass, "cameraNear", "F");
-    const jfieldID cameraFar = env->GetFieldID(klass, "cameraFar", "F");
     const jfieldID groundShadowStrength = env->GetFieldID(klass, "groundShadowStrength", "F");
     const jfieldID groundPlaneEnabled = env->GetFieldID(klass, "groundPlaneEnabled", "Z");
     const jfieldID skyboxEnabled = env->GetFieldID(klass, "skyboxEnabled", "Z");
-    const jfieldID cameraFocalLength = env->GetFieldID(klass, "cameraFocalLength", "F");
-    const jfieldID cameraFocusDistance = env->GetFieldID(klass, "cameraFocusDistance", "F");
     const jfieldID autoScaleEnabled = env->GetFieldID(klass, "autoScaleEnabled", "Z");
     const jfieldID autoInstancingEnabled = env->GetFieldID(klass, "autoInstancingEnabled", "Z");
 
-    env->SetFloatField(result, cameraAperture, options.cameraAperture);
-    env->SetFloatField(result, cameraSpeed, options.cameraSpeed);
-    env->SetFloatField(result, cameraISO, options.cameraISO);
-    env->SetFloatField(result, cameraNear, options.cameraNear);
-    env->SetFloatField(result, cameraFar, options.cameraFar);
     env->SetFloatField(result, groundShadowStrength, options.groundShadowStrength);
     env->SetBooleanField(result, groundPlaneEnabled, options.groundPlaneEnabled);
     env->SetBooleanField(result, skyboxEnabled, options.skyboxEnabled);
-    env->SetFloatField(result, cameraFocalLength, options.cameraFocalLength);
-    env->SetFloatField(result, cameraFocusDistance, options.cameraFocusDistance);
     env->SetBooleanField(result, autoScaleEnabled, options.autoScaleEnabled);
     env->SetBooleanField(result, autoInstancingEnabled, options.autoInstancingEnabled);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_utils_AutomationEngine_nGetCameraSettings(JNIEnv* env, jclass,
+        jlong nativeObject, jobject result) {
+    AutomationEngine* automation = (AutomationEngine*) nativeObject;
+    const auto& settings = automation->getSettings();
+    const auto& camera = settings.camera;
+
+    const jclass klass = env->GetObjectClass(result);
+
+    const jfieldID aperture = env->GetFieldID(klass, "aperture", "F");
+    const jfieldID shutterSpeed = env->GetFieldID(klass, "shutterSpeed", "F");
+    const jfieldID sensitivity = env->GetFieldID(klass, "sensitivity", "F");
+    const jfieldID near = env->GetFieldID(klass, "near", "F");
+    const jfieldID far = env->GetFieldID(klass, "far", "F");
+    const jfieldID focalLength = env->GetFieldID(klass, "focalLength", "F");
+    const jfieldID focusDistance = env->GetFieldID(klass, "focusDistance", "F");
+
+    env->SetFloatField(result, aperture, camera.aperture);
+    env->SetFloatField(result, shutterSpeed, camera.shutterSpeed);
+    env->SetFloatField(result, sensitivity, camera.sensitivity);
+    env->SetFloatField(result, near, camera.near);
+    env->SetFloatField(result, far, camera.far);
+    env->SetFloatField(result, focalLength, camera.focalLength);
+    env->SetFloatField(result, focusDistance, camera.focusDistance);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nGetColorGrading(JNIEnv*, jclass,
         jlong nativeObject, jlong nativeEngine) {
@@ -215,6 +249,18 @@ Java_com_google_android_filament_utils_AutomationEngine_nShouldClose(JNIEnv*, jc
     return automation->shouldClose();
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_utils_AutomationEngine_nGetTestCount(JNIEnv*, jclass, jlong native) {
+    AutomationEngine* automation = (AutomationEngine*) native;
+    return (jint) automation->testCount();
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_utils_AutomationEngine_nGetCurrentTest(JNIEnv*, jclass, jlong native) {
+    AutomationEngine* automation = (AutomationEngine*) native;
+    return (jint) automation->currentTest();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nDestroy(JNIEnv*, jclass, jlong native) {
     AutomationEngine* automation = (AutomationEngine*) native;

android/filament-utils-android/src/main/cpp/ImageDiff.cpp

@@ -0,0 +1,217 @@
+/*
+ * 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 <jni.h>
+#include <android/bitmap.h>
+
+#include <imagediff/ImageDiff.h>
+#include <utils/Log.h>
+
+#include <vector>
+
+using namespace imagediff;
+using namespace utils;
+
+namespace {
+
+struct BitmapLock {
+    JNIEnv* env;
+    jobject bitmap;
+    void* pixels;
+    AndroidBitmapInfo info;
+
+    BitmapLock(JNIEnv* env, jobject bitmap) : env(env), bitmap(bitmap), pixels(nullptr) {
+        if (!bitmap) return;
+        if (AndroidBitmap_getInfo(env, bitmap, &info) < 0) {
+            return;
+        }
+        if (AndroidBitmap_lockPixels(env, bitmap, &pixels) < 0) {
+            pixels = nullptr;
+        }
+    }
+
+    ~BitmapLock() {
+        if (pixels) {
+            AndroidBitmap_unlockPixels(env, bitmap);
+        }
+    }
+
+    bool isValid() const { return pixels != nullptr; }
+
+    imagediff::Bitmap toBitmap() const {
+        return {
+            .width = (uint32_t) info.width,
+            .height = (uint32_t) info.height,
+            .stride = (size_t) info.stride,
+            .data = pixels
+        };
+    }
+};
+
+} // namespace
+
+
+
+// Helper to convert C++ ImageDiffResult to Java Result
+jobject createResult(JNIEnv* env, ImageDiffResult const& result, bool generateDiff) {
+    // Create Result class/objects
+    jclass resultClass = env->FindClass("com/google/android/filament/utils/ImageDiff$Result");
+    jmethodID resultCtor = env->GetMethodID(resultClass, "<init>", "()V");
+    jobject resultObj = env->NewObject(resultClass, resultCtor);
+    jfieldID statusField = env->GetFieldID(resultClass, "status", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+    jfieldID failingCountField = env->GetFieldID(resultClass, "failingPixelCount", "J");
+    jfieldID maxDiffField = env->GetFieldID(resultClass, "maxDiffFound", "[F");
+    jfieldID diffImageField = env->GetFieldID(resultClass, "diffImage", "Landroid/graphics/Bitmap;");
+
+    // Map Status enum
+    jclass statusEnum = env->FindClass("com/google/android/filament/utils/ImageDiff$Result$Status");
+    jobject statusObj = nullptr;
+    jfieldID enumField = nullptr;
+    switch (result.status) {
+        case ImageDiffResult::Status::PASSED:
+            enumField = env->GetStaticFieldID(statusEnum, "PASSED", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+        case ImageDiffResult::Status::SIZE_MISMATCH:
+             enumField = env->GetStaticFieldID(statusEnum, "SIZE_MISMATCH", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+        case ImageDiffResult::Status::PIXEL_DIFFERENCE:
+             enumField = env->GetStaticFieldID(statusEnum, "PIXEL_DIFFERENCE", "Lcom/google/android/filament/utils/ImageDiff$Result$Status;");
+            break;
+    }
+    statusObj = env->GetStaticObjectField(statusEnum, enumField);
+    env->SetObjectField(resultObj, statusField, statusObj);
+
+    env->SetLongField(resultObj, failingCountField, (jlong) result.failingPixelCount);
+
+    jfloatArray maxDiffArray = env->NewFloatArray(4);
+    env->SetFloatArrayRegion(maxDiffArray, 0, 4, result.maxDiffFound);
+    env->SetObjectField(resultObj, maxDiffField, maxDiffArray);
+
+    if (generateDiff && result.diffImage.getWidth() > 0) {
+        jclass bitmapClass = env->FindClass("android/graphics/Bitmap");
+        jmethodID createBitmap = env->GetStaticMethodID(bitmapClass, "createBitmap", 
+            "(IILandroid/graphics/Bitmap$Config;)Landroid/graphics/Bitmap;");
+        
+        jclass configClass = env->FindClass("android/graphics/Bitmap$Config");
+        jfieldID argb8888 = env->GetStaticFieldID(configClass, "ARGB_8888", "Landroid/graphics/Bitmap$Config;");
+        jobject configObj = env->GetStaticObjectField(configClass, argb8888);
+
+        uint32_t width = result.diffImage.getWidth();
+        uint32_t height = result.diffImage.getHeight();
+        jobject diffBitmap = env->CallStaticObjectMethod(bitmapClass, createBitmap, (jint)width, (jint)height, configObj);
+        
+        if (diffBitmap) {
+            void* diffPixels;
+            if (AndroidBitmap_lockPixels(env, diffBitmap, &diffPixels) == 0) {
+                float const* src = result.diffImage.getPixelRef();
+                uint8_t* dst = (uint8_t*) diffPixels;
+                uint32_t channels = result.diffImage.getChannels(); // usually 4
+                
+                for (size_t i = 0; i < width * height; ++i) {
+                    for (int c = 0; c < 4; ++c) {
+                        float v = 0.0f;
+                        if (c < channels) v = src[i * channels + c];
+                        if (c == 3 && channels < 4) v = 1.0f; // Alpha 1.0 if missing
+                        dst[i * 4 + c] = (uint8_t) std::min(255.0f, std::max(0.0f, v * 255.0f));
+                    }
+                }
+                AndroidBitmap_unlockPixels(env, diffBitmap);
+                env->SetObjectField(resultObj, diffImageField, diffBitmap);
+            }
+        }
+    }
+    
+    return resultObj;
+}
+
+extern "C" JNIEXPORT jobject JNICALL
+Java_com_google_android_filament_utils_ImageDiff_nCompareBasic(JNIEnv* env, jclass,
+        jobject refBitmap, jobject candBitmap, jint mode, jint swizzle, jint channelMask,
+        jfloat maxAbsDiff, jfloat maxFailingPixelsFraction, jobject maskBitmap) {
+
+    BitmapLock refArg(env, refBitmap);
+    BitmapLock candArg(env, candBitmap);
+    BitmapLock maskArg(env, maskBitmap);
+
+    if (!refArg.isValid() || !candArg.isValid()) {
+         ImageDiffResult emptyResult; 
+         emptyResult.status = ImageDiffResult::Status::SIZE_MISMATCH; // or ERROR
+         return createResult(env, emptyResult, false);
+    }
+
+    ImageDiffConfig config;
+    config.mode = (ImageDiffConfig::Mode) mode;
+    config.swizzle = (ImageDiffConfig::Swizzle) swizzle;
+    config.channelMask = (uint8_t) channelMask;
+    config.maxAbsDiff = maxAbsDiff;
+    config.maxFailingPixelsFraction = maxFailingPixelsFraction;
+
+    imagediff::Bitmap const* maskPtr = nullptr;
+    imagediff::Bitmap maskVal;
+    if (maskBitmap && maskArg.isValid()) {
+         maskVal = maskArg.toBitmap();
+         maskPtr = &maskVal;
+    }
+
+    bool generateDiff = true;
+    ImageDiffResult result = compare(refArg.toBitmap(), candArg.toBitmap(), config, maskPtr, generateDiff);
+
+    return createResult(env, result, generateDiff);
+}
+
+extern "C" JNIEXPORT jobject JNICALL
+Java_com_google_android_filament_utils_ImageDiff_nCompareJson(JNIEnv* env, jclass,
+        jobject refBitmap, jobject candBitmap, jstring jsonConfig, jobject maskBitmap) {
+        
+    BitmapLock refArg(env, refBitmap);
+    BitmapLock candArg(env, candBitmap);
+    BitmapLock maskArg(env, maskBitmap);
+
+    if (!refArg.isValid() || !candArg.isValid()) {
+         ImageDiffResult emptyResult; 
+         emptyResult.status = ImageDiffResult::Status::SIZE_MISMATCH; // or ERROR
+         return createResult(env, emptyResult, false);
+    }
+
+    ImageDiffConfig config;
+    const char* nativeJson = env->GetStringUTFChars(jsonConfig, 0);
+    size_t length = env->GetStringUTFLength(jsonConfig);
+    
+    bool parsed = parseConfig(nativeJson, length, &config);
+    env->ReleaseStringUTFChars(jsonConfig, nativeJson);
+
+    if (!parsed) {
+        // Fallback to default or error?
+        // We could log error.
+        utils::slog.e << "ImageDiff JNI: Failed to parse JSON config" << utils::io::endl;
+        ImageDiffResult errResult;
+        errResult.status = ImageDiffResult::Status::PIXEL_DIFFERENCE; // assume fail
+        return createResult(env, errResult, false);
+    }
+
+    imagediff::Bitmap const* maskPtr = nullptr;
+    imagediff::Bitmap maskVal;
+    if (maskBitmap && maskArg.isValid()) {
+         maskVal = maskArg.toBitmap();
+         maskPtr = &maskVal;
+    }
+
+    bool generateDiff = true;
+    ImageDiffResult result = compare(refArg.toBitmap(), candArg.toBitmap(), config, maskPtr, generateDiff);
+
+    return createResult(env, result, generateDiff);
+}
+

android/filament-utils-android/src/main/java/com/google/android/filament/utils/AutomationEngine.java

@@ -94,20 +94,23 @@ public class AutomationEngine {
      * Allows remote control for the viewer.
      */
     public static class ViewerOptions {
-        public float cameraAperture = 16.0f;
-        public float cameraSpeed = 125.0f;
-        public float cameraISO = 100.0f;
-        public float cameraNear = 0.1f;
-        public float cameraFar = 100.0f;
         public float groundShadowStrength = 0.75f;
         public boolean groundPlaneEnabled = false;
         public boolean skyboxEnabled = true;
-        public float cameraFocalLength = 28.0f;
-        public float cameraFocusDistance = 0.0f;
         public boolean autoScaleEnabled = true;
         public boolean autoInstancingEnabled = false;
     }
 
+    public static class CameraSettings {
+        public float aperture = 16.0f;
+        public float shutterSpeed = 125.0f;
+        public float sensitivity = 100.0f;
+        public float near = 0.1f;
+        public float far = 100.0f;
+        public float focalLength = 28.0f;
+        public float focusDistance = 10.0f;
+    }
+
     /**
      * Creates an automation engine from a JSON specification.
      *
@@ -175,7 +178,12 @@ public class AutomationEngine {
         }
         long nativeView = content.view.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
+        long nativeIbl = content.indirectLight == null ? 0 : content.indirectLight.getNativeObject();
+        long nativeLm = content.lightManager == null ? 0 : content.lightManager.getNativeObject();
+        long nativeScene = content.scene == null ? 0 : content.scene.getNativeObject();
+        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances,
+                nativeRenderer, nativeIbl, content.sunlight, content.assetLights, nativeLm,
+                nativeScene, deltaTime);
     }
 
     /**
@@ -229,6 +237,13 @@ public class AutomationEngine {
         return result;
     }
 
+    @NonNull
+    public CameraSettings getCameraSettings() {
+        CameraSettings result = new CameraSettings();
+        nGetCameraSettings(mNativeObject, result);
+        return result;
+    }
+
     /**
      * Gets a color grading object that corresponds to the latest settings.
      *
@@ -261,6 +276,9 @@ public class AutomationEngine {
      */
     public boolean shouldClose() { return nShouldClose(mNativeObject); }
 
+    public int getTestCount() { return nGetTestCount(mNativeObject); }
+    public int getCurrentTest() { return nGetCurrentTest(mNativeObject); }
+
     @Override
     protected void finalize() throws Throwable {
         nDestroy(mNativeObject);
@@ -274,15 +292,19 @@ public class AutomationEngine {
     private static native void nStartRunning(long nativeObject);
     private static native void nStartBatchMode(long nativeObject);
     private static native void nTick(long nativeObject, long nativeEngine,
-            long view, long[] materials, long renderer, float deltaTime);
+            long view, long[] materials, long renderer, long ibl, int sunlight, int[] assetLights,
+            long lightManager, long scene, float deltaTime);
     private static native void nApplySettings(long nativeObject, long nativeEngine,
             String jsonSettings, long view,
             long[] materials, long ibl, int sunlight, int[] assetLights, long lightManager,
             long scene, long renderer);
     private static native void nGetViewerOptions(long nativeObject, Object result);
+    private static native void nGetCameraSettings(long nativeObject, Object result);
     private static native long nGetColorGrading(long nativeObject, long nativeEngine);
     private static native void nSignalBatchMode(long nativeObject);
     private static native void nStopRunning(long nativeObject);
     private static native boolean nShouldClose(long nativeObject);
+    private static native int nGetTestCount(long nativeObject);
+    private static native int nGetCurrentTest(long nativeObject);
     private static native void nDestroy(long nativeObject);
 }

android/filament-utils-android/src/main/java/com/google/android/filament/utils/ImageDiff.java

@@ -0,0 +1,91 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.utils;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import android.graphics.Bitmap;
+
+public class ImageDiff {
+    public enum Mode {
+        LEAF, AND, OR
+    }
+
+    public enum Swizzle {
+        RGBA, BGRA
+    }
+
+    public static class Config {
+        @NonNull
+        public Mode mode = Mode.LEAF;
+        @NonNull
+        public Swizzle swizzle = Swizzle.RGBA;
+        public int channelMask = 0xF;
+        public float maxAbsDiff = 0.0f;
+        public float maxFailingPixelsFraction = 0.0f;
+        // Children not supported in this simple wrapper for now, can be added if needed
+    }
+
+    public static class Result {
+        public enum Status {
+            PASSED,
+            SIZE_MISMATCH,
+            PIXEL_DIFFERENCE
+        }
+
+        public Status status;
+        public long failingPixelCount;
+        public float[] maxDiffFound; // [R, G, B, A]
+        public Bitmap diffImage; // Null if not generated
+    }
+
+    /**
+     * Compares two bitmaps using a configuration object.
+     *
+     * @param reference Golden image
+     * @param candidate Actual image
+     * @param config    Comparison configuration
+     * @param mask      Optional mask (grayscale)
+     * @return Result of comparison
+     */
+    @NonNull
+    public static Result compareBasic(@NonNull Bitmap reference, @NonNull Bitmap candidate,
+            @NonNull Config config, @Nullable Bitmap mask) {
+        return nCompareBasic(reference, candidate, config.mode.ordinal(), config.swizzle.ordinal(),
+                config.channelMask, config.maxAbsDiff, config.maxFailingPixelsFraction, mask);
+    }
+
+    /**
+     * Compares two bitmaps using a JSON configuration string.
+     *
+     * @param reference Golden image
+     * @param candidate Actual image
+     * @param jsonConfig Comparison configuration in JSON format
+     * @param mask      Optional mask (grayscale)
+     * @return Result of comparison
+     */
+    @NonNull
+    public static Result compare(@NonNull Bitmap reference, @NonNull Bitmap candidate,
+            @NonNull String jsonConfig, @Nullable Bitmap mask) {
+        return nCompareJson(reference, candidate, jsonConfig, mask);
+    }
+
+    private static native Result nCompareBasic(Bitmap reference, Bitmap candidate, int mode, int swizzle,
+            int channelMask, float maxAbsDiff, float maxFailingPixelsFraction, Bitmap mask);
+
+    private static native Result nCompareJson(Bitmap reference, Bitmap candidate, String jsonConfig, Bitmap mask);
+}

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.68.5
+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-gltf-viewer/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     cmgenArgs = "-q --format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs/default_env"
     iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/lightroom_14b.hdr")
     iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")

android/samples/sample-gltf-viewer/src/main/java/com/google/android/filament/gltf/MainActivity.kt

@@ -389,9 +389,9 @@ class MainActivity : Activity() {
         viewerContent.assetLights = modelViewer.asset?.lightEntities
         automation.applySettings(modelViewer.engine, json, viewerContent)
         modelViewer.view.colorGrading = automation.getColorGrading(modelViewer.engine)
-        modelViewer.cameraFocalLength = automation.viewerOptions.cameraFocalLength
-        modelViewer.cameraNear = automation.viewerOptions.cameraNear
-        modelViewer.cameraFar = automation.viewerOptions.cameraFar
+        modelViewer.cameraFocalLength = automation.cameraSettings.focalLength
+        modelViewer.cameraNear = automation.cameraSettings.near
+        modelViewer.cameraFar = automation.cameraSettings.far
         updateRootTransform()
     }
 

android/samples/sample-hello-camera/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-hello-triangle/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-image-based-lighting/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 

android/samples/sample-lit-cube/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-material-builder/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     meshInputFile = project.layout.projectDirectory.file("../../../third_party/models/shader_ball/shader_ball.obj")
     meshOutputDir = project.layout.projectDirectory.dir("src/main/assets/models")
 

android/samples/sample-material-instance-stress/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-multi-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-page-curl/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/studio_small_02_2k.hdr")
     iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")

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

@@ -0,0 +1,57 @@
+plugins {
+    id 'com.android.application'
+    id 'kotlin-android'
+    id 'filament-plugin'
+}
+
+project.ext.isSample = true
+
+kotlin {
+    jvmToolchain(versions.jdk)
+}
+
+filament {
+    cmgenArgs = "-q --format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs/default_env"
+    iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/lightroom_14b.hdr")
+    iblOutputDir = project.layout.projectDirectory.dir("src/main/assets/envs")
+}
+
+// don't forget to update MainACtivity.kt when/if changing this.
+tasks.register('copyDamagedHelmetGltf', Copy) {
+    from file("../../../third_party/models/DamagedHelmet/DamagedHelmet.glb")
+    into file("src/main/assets/models")
+    rename {String fileName -> "helmet.glb"}
+}
+
+preBuild.dependsOn copyDamagedHelmetGltf
+
+clean.doFirst {
+    delete "src/main/assets/envs"
+    delete "src/main/assets/models"
+}
+
+android {
+    namespace 'com.google.android.filament.validation'
+
+    compileSdkVersion versions.compileSdk
+    defaultConfig {
+        applicationId "com.google.android.filament.validation"
+        minSdkVersion versions.minSdk
+        targetSdkVersion versions.targetSdk
+    }
+
+    compileOptions {
+        sourceCompatibility versions.jdk
+        targetCompatibility versions.jdk
+    }
+}
+
+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')
+    implementation project(':filament-utils-android')
+}

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

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE" />
+
+    <application
+        android:allowBackup="true"
+        android:label="Filament Validation"
+        android:supportsRtl="true"
+        android:largeHeap="true"
+        android:requestLegacyExternalStorage="true"
+        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>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

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

@@ -0,0 +1,529 @@
+/*
+ * 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.
+ */
+
+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.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 java.io.File
+import java.nio.ByteBuffer
+import java.text.SimpleDateFormat
+import java.util.Date
+import java.util.Locale
+
+class MainActivity : Activity(), ValidationRunner.Callback {
+
+    companion object {
+        init {
+            Utils.init()
+            System.loadLibrary("filament-utils-jni")
+        }
+        private const val TAG = "FilamentValidation"
+    }
+
+    private lateinit var surfaceView: SurfaceView
+    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
+
+    // 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
+    private val frameScheduler = object : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            choreographer.postFrameCallback(this)
+            modelViewer.render(frameTimeNanos)
+            validationRunner?.onFrame(frameTimeNanos)
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_main)
+
+        // SurfaceView container
+        surfaceView = findViewById(R.id.surface_view)
+        surfaceView.holder.setFixedSize(512, 512)
+
+        statusTextView = findViewById(R.id.status_text)
+        testResultsHeader = findViewById(R.id.test_results_header)
+        resultsContainer = findViewById(R.id.results_container)
+
+        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 ->
+                // 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()
+        modelViewer = ModelViewer(surfaceView)
+        inputManager = ValidationInputManager(this)
+
+        // Initialize IBL
+        createIndirectLight()
+
+        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
+            val scene = modelViewer.scene
+            val iblName = "default_env"
+
+            fun readAsset(path: String): ByteBuffer {
+                val input = assets.open(path)
+                val bytes = input.readBytes()
+                return ByteBuffer.wrap(bytes)
+            }
+
+            readAsset("envs/$iblName/${iblName}_ibl.ktx").let {
+                val bundle = KTX1Loader.createIndirectLight(engine, it)
+                scene.indirectLight = bundle.indirectLight
+                modelViewer.indirectLightCubemap = bundle.cubemap
+                scene.indirectLight!!.intensity = 30_000.0f
+            }
+
+            readAsset("envs/$iblName/${iblName}_skybox.ktx").let {
+                val bundle = KTX1Loader.createSkybox(engine, it)
+                scene.skybox = bundle.skybox
+                modelViewer.skyboxCubemap = bundle.cubemap
+            }
+            Log.i(TAG, "IBL loaded successfully")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to load IBL", e)
+            statusTextView.text = "Warning: Failed to load IBL"
+        }
+    }
+
+    private fun handleIntent() {
+        statusTextView.text = "Resolving configuration..."
+        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
+
+                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}"
+            }
+        }
+    }
+
+    private fun startValidation(input: ValidationInputManager.ValidationInput) {
+        try {
+            resultsContainer.removeAllViews()
+            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!!)
+            validationRunner?.callback = this
+            validationRunner?.generateGoldens = input.generateGoldens
+            validationRunner?.start()
+
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to start validation", e)
+            statusTextView.text = "Error: ${e.message}"
+        }
+    }
+
+    override fun onResume() {
+        super.onResume()
+        choreographer.postFrameCallback(frameScheduler)
+    }
+
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        setIntent(intent)
+        handleIntent()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        choreographer.removeFrameCallback(frameScheduler)
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+        choreographer.removeFrameCallback(frameScheduler)
+    }
+
+    private var currentRenderedBitmap: Bitmap? = null
+    private var currentGoldenBitmap: Bitmap? = null
+    private var currentDiffBitmap: Bitmap? = null
+
+    override fun onTestFinished(result: ValidationResult) {
+        runOnUiThread {
+            val status = "Test ${result.testName} finished: ${if(result.passed) "PASS" else "FAIL"}"
+            statusTextView.text = status
+            Log.i(TAG, status)
+
+            // Container for this result
+            val resultContainer = LinearLayout(this)
+            resultContainer.orientation = LinearLayout.VERTICAL
+            resultContainer.setPadding(0, 10, 0, 20)
+
+            // 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)
+            imagesRow.orientation = LinearLayout.HORIZONTAL
+
+            fun addImage(label: String, bitmap: Bitmap?) {
+                if (bitmap != null) {
+                    val container = LinearLayout(this)
+                    container.orientation = LinearLayout.VERTICAL
+                    container.setPadding(0, 0, 10, 0)
+
+                    val labelView = TextView(this)
+                    labelView.text = label
+                    labelView.textSize = 9f
+                    container.addView(labelView)
+
+                    val iv = ImageView(this)
+                    iv.setImageBitmap(bitmap) // Use the same bitmap (or copy if needed, but same is usually fine for UI)
+                    iv.layoutParams = LinearLayout.LayoutParams(250, 250) // Smaller thumbnails
+                    iv.scaleType = ImageView.ScaleType.FIT_CENTER
+                    iv.setBackgroundColor(0xFF404040.toInt())
+                    container.addView(iv)
+
+                    imagesRow.addView(container)
+                }
+            }
+
+            addImage("Rendered", currentRenderedBitmap)
+            addImage("Golden", currentGoldenBitmap)
+            if (!result.passed) {
+                addImage("Diff", currentDiffBitmap)
+            }
+
+            resultContainer.addView(imagesRow)
+            resultsContainer.addView(resultContainer)
+
+            // Clear current images for next test
+            currentRenderedBitmap = null
+            currentGoldenBitmap = null
+            currentDiffBitmap = null
+        }
+    }
+
+    override fun onAllTestsFinished() {
+        runOnUiThread {
+            statusTextView.text = "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")
+            }
+        }
+    }
+
+    override fun onStatusChanged(status: String) {
+        runOnUiThread {
+            statusTextView.text = status
+        }
+    }
+
+    override fun onImageResult(type: String, bitmap: Bitmap) {
+        runOnUiThread {
+            // Update the "live" views
+            when (type) {
+                "Rendered" -> {
+                    currentRenderedBitmap = bitmap
+                }
+                "Golden" -> {
+                    currentGoldenBitmap = bitmap
+                }
+                "Diff" -> {
+                    currentDiffBitmap = bitmap
+                }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,186 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.validation
+
+import org.json.JSONArray
+import org.json.JSONObject
+import java.io.File
+import java.io.IOException
+
+data class RenderTestConfig(
+    val name: String,
+    val backends: List<String>,
+    val models: Map<String, String>, // name -> path
+    val tests: List<TestConfig>
+)
+
+data class TestConfig(
+    val name: String,
+    val description: String?,
+    val backends: List<String>,
+    val models: Set<String>,
+    val rendering: JSONObject,
+    val tolerance: JSONObject?
+)
+
+
+// See test/renderdiff/FORMAT.md for the full specification matched by this parser.
+class ConfigParser {
+    companion object {
+        fun parseFromPath(path: String): RenderTestConfig {
+            val file = File(path)
+            val jsonTxt = removeComments(file.readText())
+            val json = JSONObject(jsonTxt)
+            return parseRenderTestConfig(json, file.parentFile)
+        }
+
+        private fun removeComments(json: String): String {
+            return json.lines().joinToString("\n") { it.substringBefore("//") }
+        }
+
+        private fun parseRenderTestConfig(json: JSONObject, baseDir: File?): RenderTestConfig {
+            val name = json.getString("name")
+            val backends = json.getJSONArray("backends").toList<String>()
+            
+            val modelSearchPaths = json.optJSONArray("model_search_paths")?.toList<String>() ?: emptyList()
+            val models = mutableMapOf<String, String>()
+            
+            baseDir?.let { dir ->
+                modelSearchPaths.forEach { searchPath ->
+                    val searchDir = File(dir, searchPath)
+                    if (searchDir.exists()) {
+                        searchDir.walkTopDown().filter { it.isFile && (it.extension == "glb" || it.extension == "gltf") }.forEach { file ->
+                            models[file.nameWithoutExtension] = file.absolutePath
+                        }
+                    }
+                }
+            }
+
+            // Explicit models map override
+            val modelsJson = json.optJSONObject("models")
+            if (modelsJson != null) {
+                val keys = modelsJson.keys()
+                while (keys.hasNext()) {
+                    val name = keys.next()
+                    val path = modelsJson.getString(name)
+                    // Resolve path relative to baseDir if not absolute
+                    val file = File(path)
+                    if (file.isAbsolute) {
+                        models[name] = path
+                    } else if (baseDir != null) {
+                        models[name] = File(baseDir, path).absolutePath
+                    } else {
+                        models[name] = path
+                    }
+                }
+            }
+
+
+            val presetsJson = json.optJSONArray("presets")
+            val presets = mutableMapOf<String, PresetConfig>()
+            if (presetsJson != null) {
+                for (i in 0 until presetsJson.length()) {
+                    val p = parsePreset(presetsJson.getJSONObject(i), models.keys)
+                    presets[p.name] = p
+                }
+            }
+
+            val testsJson = json.getJSONArray("tests")
+            val tests = mutableListOf<TestConfig>()
+            for (i in 0 until testsJson.length()) {
+                tests.add(parseTestConfig(testsJson.getJSONObject(i), models.keys, presets, backends))
+            }
+
+            return RenderTestConfig(name, backends, models, tests)
+        }
+
+        private fun parsePreset(json: JSONObject, existingModels: Set<String>): PresetConfig {
+            val name = json.getString("name")
+            val rendering = json.getJSONObject("rendering")
+            val models = json.optJSONArray("models")?.toList<String>() ?: emptyList()
+            
+            // Validate models
+            models.forEach { if (!existingModels.contains(it)) throw IllegalArgumentException("Model $it not found") }
+
+            val tolerance = json.optJSONObject("tolerance")
+            return PresetConfig(name, rendering, models, tolerance)
+        }
+
+        private fun parseTestConfig(
+            json: JSONObject, 
+            existingModels: Set<String>, 
+            presets: Map<String, PresetConfig>, 
+            defaultBackends: List<String>
+        ): TestConfig {
+            val name = json.getString("name")
+            val description = json.optString("description")
+            val backends = json.optJSONArray("backends")?.toList<String>() ?: defaultBackends
+            
+            val applyPresets = json.optJSONArray("apply_presets")?.toList<String>() ?: emptyList()
+            
+            val rendering = JSONObject()
+            val combinedModels = mutableSetOf<String>()
+            var lastTolerance: JSONObject? = null
+
+            applyPresets.forEach { presetName ->
+                val preset = presets[presetName] ?: throw IllegalArgumentException("Unknown preset $presetName")
+                // Merge rendering (flat copy)
+                val keys = preset.rendering.keys()
+                while(keys.hasNext()) {
+                    val k = keys.next()
+                    rendering.put(k, preset.rendering.get(k))
+                }
+                combinedModels.addAll(preset.models)
+                if (preset.tolerance != null) lastTolerance = preset.tolerance
+            }
+
+            val testRendering = json.optJSONObject("rendering")
+            if (testRendering != null) {
+                val keys = testRendering.keys()
+                while(keys.hasNext()) {
+                    val k = keys.next()
+                    rendering.put(k, testRendering.get(k))
+                }
+            }
+
+            val testModels = json.optJSONArray("models")?.toList<String>() ?: emptyList()
+            combinedModels.addAll(testModels)
+            
+             // Validate models
+            combinedModels.forEach { if (!existingModels.contains(it)) throw IllegalArgumentException("Model $it not found") }
+
+            val tolerance = json.optJSONObject("tolerance") ?: lastTolerance
+
+            return TestConfig(name, description, backends, combinedModels, rendering, tolerance)
+        }
+    }
+}
+
+data class PresetConfig(
+    val name: String,
+    val rendering: JSONObject,
+    val models: List<String>,
+    val tolerance: JSONObject?
+)
+
+private inline fun <reified T> JSONArray.toList(): List<T> {
+    val list = mutableListOf<T>()
+    for (i in 0 until length()) {
+        list.add(get(i) as T)
+    }
+    return list
+}

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

@@ -0,0 +1,264 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.validation
+
+import android.content.Context
+import android.content.Intent
+import android.util.Log
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import org.json.JSONObject
+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.
+ * Supports loading from:
+ * 1. Intent extras (local path or URL)
+ * 2. Default embedded assets (fallback)
+ */
+class ValidationInputManager(private val context: Context) {
+
+    companion object {
+        private const val TAG = "ValidationInputManager"
+    }
+
+    data class ValidationInput(
+        val config: RenderTestConfig,
+        val outputDir: File,
+        val generateGoldens: Boolean,
+        val autoRun: Boolean = false,
+        val autoExport: Boolean = false,
+        val autoExportResults: Boolean = false,
+        val sourceZip: File? = null
+    )
+
+    /**
+     * Resolves the test configuration based on the provided intent extras.
+     * This may involve extracting assets or downloading files.
+     */
+    suspend fun resolveConfig(intent: Intent): ValidationInput = withContext(Dispatchers.IO) {
+        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")
+
+        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(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, 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 {
+        Log.i(TAG, "Extracting default assets...")
+        val filesDir = context.getExternalFilesDir(null) ?: context.filesDir
+        val assetManager = context.assets
+
+        // Copy default_test.json
+        val configDir = File(filesDir, "config")
+        configDir.mkdirs()
+        val configOut = File(configDir, "default_test.json")
+
+        assetManager.open("default_test.json").use { input ->
+            FileOutputStream(configOut).use { output ->
+                input.copyTo(output)
+            }
+        }
+
+        // Copy DamagedHelmet.glb
+        val modelsDir = File(filesDir, "models")
+        modelsDir.mkdirs()
+        val modelOut = File(modelsDir, "helmet.glb")
+
+        assetManager.open("models/helmet.glb").use { input ->
+            FileOutputStream(modelOut).use { output ->
+                input.copyTo(output)
+            }
+        }
+
+        // Update config to point to relative path (standardizing on relative for portability where possible)
+        // or absolute. Here we use relative as per previous logic.
+        val configJson = JSONObject(configOut.readText())
+        val models = configJson.getJSONObject("models")
+
+        // Ensure the default model points to the extracted file
+        // We can use absolute path to be safe since we know where it is now.
+        models.put("DamagedHelmet", modelOut.absolutePath)
+
+        configOut.writeText(configJson.toString(2))
+
+        return ConfigParser.parseFromPath(configOut.absolutePath)
+    }
+
+    private suspend fun downloadConfig(urlConfig: String, urlModelsBase: String?): RenderTestConfig {
+        Log.i(TAG, "Downloading config from $urlConfig")
+        val filesDir = context.getExternalFilesDir(null) ?: context.filesDir
+        val configDir = File(filesDir, "config")
+        configDir.mkdirs()
+
+        val modelsDir = File(filesDir, "models")
+        modelsDir.mkdirs()
+
+        val configName = "downloaded_config.json"
+        val configFile = File(configDir, configName)
+
+        downloadFile(urlConfig, configFile)
+
+        if (urlModelsBase != null) {
+            val configJson = JSONObject(configFile.readText())
+            val models = configJson.optJSONObject("models")
+            if (models != null) {
+                val keys = models.keys()
+                while (keys.hasNext()) {
+                    val key = keys.next()
+                    val modelPath = models.getString(key)
+                    val fileName = File(modelPath).name
+                    val modelFile = File(modelsDir, fileName)
+                    val modelUrl = "$urlModelsBase/$fileName"
+
+                    Log.i(TAG, "Downloading model: $fileName from $modelUrl")
+                    downloadFile(modelUrl, modelFile)
+
+                    // Update config to point to absolute path
+                    models.put(key, modelFile.absolutePath)
+                }
+                configFile.writeText(configJson.toString())
+            }
+        }
+
+        return ConfigParser.parseFromPath(configFile.absolutePath)
+    }
+
+    private fun downloadFile(urlStr: String, destFile: File) {
+        val url = URL(urlStr)
+        val connection = url.openConnection() as HttpURLConnection
+        connection.connect()
+
+        if (connection.responseCode != HttpURLConnection.HTTP_OK) {
+             throw Exception("Server returned HTTP ${connection.responseCode} for $urlStr")
+        }
+
+        destFile.parentFile?.mkdirs()
+        connection.inputStream.use { input ->
+            FileOutputStream(destFile).use { output ->
+                input.copyTo(output)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,288 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.validation
+
+import android.graphics.Bitmap
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.util.zip.ZipEntry
+import java.util.zip.ZipOutputStream
+import org.json.JSONArray
+import org.json.JSONObject
+
+data class ValidationResult(
+    val testName: String,
+    val passed: Boolean,
+    val diffMetric: Float = 0f
+)
+
+class ValidationResultManager(private val outputDir: File) {
+
+    companion object {
+        private const val TAG = "ValidationResultManager"
+    }
+
+    private val results = mutableListOf<ValidationResult>()
+
+    init {
+        if (!outputDir.exists()) {
+            outputDir.mkdirs()
+        }
+    }
+
+    fun addResult(result: ValidationResult) {
+        results.add(result)
+    }
+
+    fun saveImage(name: String, bitmap: Bitmap) {
+        val file = File(outputDir, "$name.png")
+        try {
+            FileOutputStream(file).use { out ->
+                bitmap.compress(Bitmap.CompressFormat.PNG, 100, out)
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to save image $name", e)
+        }
+    }
+
+    fun getOutputDir(): File {
+        return outputDir
+    }
+
+    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}")
+
+        try {
+            ZipOutputStream(FileOutputStream(zipFile)).use { 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, "Exported results to ${zipFile.absolutePath}")
+            return zipFile
+        } catch (e: Exception) {
+            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
+        }
+    }
+
+    private fun writeResultsJson() {
+        val jsonArray = JSONArray()
+        for (result in results) {
+            val jsonObject = JSONObject()
+            jsonObject.put("test_name", result.testName)
+            jsonObject.put("passed", result.passed)
+            jsonObject.put("diff_metric", result.diffMetric)
+            jsonArray.put(jsonObject)
+        }
+
+        val jsonFile = File(outputDir, "results.json")
+        try {
+            FileOutputStream(jsonFile).use { out ->
+                out.write(jsonArray.toString(4).toByteArray())
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to write results.json", e)
+        }
+    }
+}

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

@@ -0,0 +1,313 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.validation
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.util.Log
+import com.google.android.filament.utils.AutomationEngine
+import com.google.android.filament.utils.ImageDiff
+import com.google.android.filament.utils.ModelViewer
+import org.json.JSONObject
+import java.io.File
+import java.io.FileOutputStream
+import java.nio.ByteBuffer
+
+class ValidationRunner(
+    private val context: Context,
+    private val modelViewer: ModelViewer,
+    private val config: RenderTestConfig,
+    private val resultManager: ValidationResultManager
+) {
+
+    private var currentState = State.IDLE
+    private var currentTestIndex = 0
+    private var currentModelIndex = 0
+    private var currentEngine: AutomationEngine? = null
+    private var currentTestConfig: TestConfig? = null
+    private var currentModelName: String? = null
+
+    private var frameCounter = 0
+
+    enum class State {
+        IDLE,
+        WAITING_FOR_RESOURCES,
+        WARMUP,
+        RUNNING_TEST
+    }
+
+    interface Callback {
+        fun onTestFinished(result: ValidationResult)
+        fun onAllTestsFinished()
+        fun onStatusChanged(status: String)
+        fun onImageResult(type: String, bitmap: Bitmap)
+    }
+
+    var callback: Callback? = null
+    var generateGoldens: Boolean = false
+
+    fun start() {
+        if (config.tests.isEmpty()) {
+            callback?.onAllTestsFinished()
+            return
+        }
+        currentTestIndex = 0
+        currentModelIndex = 0
+        startTest(config.tests[0])
+    }
+
+    private fun startTest(test: TestConfig) {
+        currentTestConfig = test
+        if (test.models.isEmpty()) {
+            nextTest()
+            return
+        }
+        currentModelIndex = 0
+        startModel(test.models.elementAt(0))
+    }
+
+    private fun startModel(modelName: String) {
+        currentModelName = modelName
+        val modelPath = config.models[modelName]
+        if (modelPath == null) {
+            Log.e("ValidationRunner", "Model $modelName not found")
+            nextModel()
+            return
+        }
+        callback?.onStatusChanged("Loading $modelName for ${currentTestConfig?.name}")
+
+        // Load model on main thread (required by ModelViewer)
+        loadModel(modelPath)
+    }
+
+    private fun loadModel(path: String) {
+        // Assume called on Main Thread
+        modelViewer.destroyModel()
+        try {
+            Log.i("ValidationRunner", "Reading model file: $path")
+            val bytes = File(path).readBytes()
+            Log.i("ValidationRunner", "Loading GLB buffer... (${bytes.size} bytes)")
+            val buffer = ByteBuffer.wrap(bytes)
+            modelViewer.loadModelGlb(buffer)
+            Log.i("ValidationRunner", "Model loaded.")
+            modelViewer.transformToUnitCube()
+            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()
+        }
+    }
+
+    fun onFrame(frameTimeNanos: Long) {
+        if (frameCounter % 60 == 0) {
+            Log.i("ValidationRunner", "onFrame: $currentState (frame: $frameCounter)")
+        }
+
+        when (currentState) {
+            State.IDLE -> {}
+            State.WAITING_FOR_RESOURCES -> {
+                 val progress = modelViewer.progress
+                 if (progress >= 1.0f) {
+                     Log.i("ValidationRunner", "Resources loaded. Starting warmup.")
+                     frameCounter = 0
+                     currentState = State.WARMUP
+                 }
+            }
+            State.WARMUP -> {
+                frameCounter++
+                if (frameCounter > 5) { // 5 frames warmup
+                    startAutomation()
+                }
+            }
+            State.RUNNING_TEST -> {
+                // Log.i("ValidationRunner", "Running test...")
+                currentEngine?.let { engine ->
+                    val content = AutomationEngine.ViewerContent()
+                    content.view = modelViewer.view
+                    content.renderer = modelViewer.renderer
+                    content.scene = modelViewer.scene
+                    content.lightManager = modelViewer.engine.lightManager
+
+                    // Tick
+                    val deltaTime = 1.0f / 60.0f
+                    engine.tick(modelViewer.engine, content, deltaTime)
+
+                    frameCounter++
+                    if (engine.shouldClose()) {
+                        Log.i("ValidationRunner", "Finishing test (frames: $frameCounter)")
+                        // Test finished (for this spec)
+                        currentState = State.IDLE
+                        captureAndCompare()
+                    }
+                }
+            }
+        }
+    }
+
+    private fun startAutomation() {
+        val test = currentTestConfig!!
+        val specJson = JSONObject()
+        specJson.put("name", test.name)
+        specJson.put("base", test.rendering)
+        val fullSpec = "[${specJson.toString()}]"
+
+        currentEngine = AutomationEngine(fullSpec)
+        val options = AutomationEngine.Options()
+        options.sleepDuration = 0.0f // Minimal sleep, let frames drive it
+        options.minFrameCount = 5 // Ensure some frames pass
+        currentEngine?.setOptions(options)
+
+        // Use batch mode to ensure shouldClose() works reliably
+        currentEngine?.startBatchMode()
+        currentEngine?.signalBatchMode() // Start immediately
+
+        frameCounter = 0
+        currentState = State.RUNNING_TEST
+    }
+
+
+    private fun captureAndCompare() {
+        callback?.onStatusChanged("Comparing ${currentTestConfig?.name}...")
+        modelViewer.debugGetNextFrameCallback { bitmap ->
+            compareCapturedImage(bitmap)
+        }
+    }
+
+    private fun compareCapturedImage(bitmap: Bitmap) {
+         val testName = currentTestConfig!!.name
+         val modelName = currentModelName!!
+         val backend = currentTestConfig?.backends?.firstOrNull() ?: "opengl"
+         val testFullName = "${testName}.${backend}.${modelName}"
+
+         // Golden path
+         val modelFile = File(config.models.get(modelName)!!)
+         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 {
+                val flipped = bitmap
+
+                callback?.onImageResult("Rendered", flipped)
+
+                var passed = false
+                var diffMetric = 0f
+
+                if (generateGoldens) {
+                    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 != null && goldenFile.exists()) {
+                        val golden = android.graphics.BitmapFactory.decodeFile(goldenFile.absolutePath)
+                        if (golden != null) {
+                            callback?.onImageResult("Golden", golden)
+
+                            val tol = currentTestConfig?.tolerance ?: org.json.JSONObject()
+                            val tolJson = tol.toString()
+                            val result = ImageDiff.compare(golden, flipped, tolJson, null)
+                            passed = (result.status == ImageDiff.Result.Status.PASSED)
+                            diffMetric = result.failingPixelCount.toFloat()
+
+                             if (!passed) {
+                                if (result.diffImage != null) {
+                                    callback?.onImageResult("Diff", result.diffImage!!)
+                                    resultManager.saveImage("${testFullName}_diff", result.diffImage!!)
+                                }
+                             }
+                        } else {
+                            callback?.onStatusChanged("Failed to load golden")
+                        }
+                    } else {
+                        Log.w("ValidationRunner", "Golden not found: ${goldenFile?.absolutePath}")
+                        callback?.onStatusChanged("Golden not found")
+                    }
+                }
+
+                // Save output
+                resultManager.saveImage(testFullName, flipped)
+
+                val result = ValidationResult(testFullName, passed, diffMetric)
+                resultManager.addResult(result)
+                callback?.onTestFinished(result)
+
+                android.os.Handler(android.os.Looper.getMainLooper()).post {
+                    nextModel()
+                }
+
+             } catch (e: Exception) {
+                 Log.e("ValidationRunner", "Comparison failed", e)
+                 android.os.Handler(android.os.Looper.getMainLooper()).post { nextModel() }
+             }
+         }.start()
+    }
+
+    private fun nextModel() {
+        currentModelIndex++
+        if (currentTestConfig != null && currentModelIndex < currentTestConfig!!.models.size) {
+            startModel(currentTestConfig!!.models.elementAt(currentModelIndex))
+        } else {
+            nextTest()
+        }
+    }
+
+
+    private fun nextTest() {
+        currentTestIndex++
+        if (currentTestIndex < config.tests.size) {
+            startTest(config.tests[currentTestIndex])
+        } else {
+            currentState = State.IDLE
+            resultManager.finalizeResults()
+            callback?.onAllTestsFinished()
+        }
+    }
+}

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

@@ -0,0 +1,123 @@
+<?xml version="1.0" encoding="utf-8"?>
+<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"
+    android:layout_height="match_parent">
+
+    <FrameLayout
+        android:id="@+id/surface_container"
+        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">
+
+        <SurfaceView
+            android:id="@+id/surface_view"
+            android:layout_width="match_parent"
+            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/controls_container"
+        app:layout_constraintBottom_toBottomOf="parent"
+        app:layout_constraintStart_toStartOf="parent"
+        app:layout_constraintEnd_toEndOf="parent">
+
+        <LinearLayout
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:orientation="vertical"
+            android:paddingStart="20dp"
+            android:paddingEnd="20dp"
+            android:paddingBottom="20dp">
+
+            <LinearLayout
+                android:id="@+id/results_container"
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="vertical" />
+
+        </LinearLayout>
+    </ScrollView>
+
+</androidx.constraintlayout.widget.ConstraintLayout>

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

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:orientation="vertical"
+    android:padding="5dp">
+
+    <TextView
+        android:id="@+id/image_label"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:text="Label" />
+
+    <ImageView
+        android:id="@+id/image_view"
+        android:layout_width="300px"
+        android:layout_height="300px"
+        android:scaleType="fitCenter"
+        android:background="#404040" />
+</LinearLayout>

android/samples/sample-stream-test/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-texture-target/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-texture-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/samples/sample-textured-object/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 

android/samples/sample-transparent-view/build.gradle

@@ -1,7 +1,7 @@
 plugins {
     id 'com.android.application'
     id 'kotlin-android'
-    id 'filament-tools-plugin'
+    id 'filament-plugin'
 }
 
 project.ext.isSample = true
@@ -10,7 +10,7 @@ kotlin {
     jvmToolchain(versions.jdk)
 }
 
-filamentTools {
+filament {
     materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
     materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
 }

android/settings.gradle

@@ -21,5 +21,6 @@ include ':samples:sample-texture-view'
 include ':samples:sample-texture-target'
 include ':samples:sample-textured-object'
 include ':samples:sample-transparent-view'
+include ':samples:sample-render-validation'
 
 rootProject.name = 'filament'

build/common/build-common.sh

@@ -39,6 +39,11 @@ if [[ "$TARGET" == "presubmit-with-test" ]]; then
     RUN_TESTS=-u
 fi
 
+if [[ "$TARGET" == "presubmit-with-archive" ]]; then
+    BUILD_RELEASE=release
+    GENERATE_ARCHIVES=-a
+fi
+
 if [[ "$TARGET" == "debug" ]]; then
     BUILD_DEBUG=debug
     GENERATE_ARCHIVES=-a

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,22 +181,21 @@ important for <code>matc</code> (material compiler).</p>
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.68.5'
+    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>
 <div class="table-wrapper"><table><thead><tr><th>Artifact</th><th>Description</th></tr></thead><tbody>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android" alt="filament-android" /></a></td><td>The Filament rendering engine itself.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug/badge.svg?subject=filament-android-debug" alt="filament-android-debug" /></a></td><td>Debug version of <code>filament-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android" alt="gltfio-android" /></a></td><td>A glTF 2.0 loader for Filament, depends on <code>filament-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android" alt="filament-utils-android" /></a></td><td>KTX loading, Kotlin math, and camera utilities, depends on <code>gltfio-android</code>.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android" alt="filamat-android" /></a></td><td>A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.</td></tr>
-<tr><td><a href="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite"><img src="https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite/badge.svg?subject=filamat-android-lite" alt="filamat-android-lite" /></a></td><td>A much smaller alternative to <code>filamat-android</code> that can only generate OpenGL shaders. It does not provide validation or optimizations.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-android?label=filament-android&amp;color=green" alt="filament-android" /></a></td><td>The Filament rendering engine itself.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-android-debug"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-android-debug?label=filament-android-debug&amp;color=green" alt="filament-android-debug" /></a></td><td>Debug version of <code>filament-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/gltfio-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/gltfio-android?label=gltfio-android&amp;color=green" alt="gltfio-android" /></a></td><td>A glTF 2.0 loader for Filament, depends on <code>filament-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filament-utils-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filament-utils-android?label=filament-utils-android&amp;color=green" alt="filament-utils-android" /></a></td><td>KTX loading, Kotlin math, and camera utilities, depends on <code>gltfio-android</code>.</td></tr>
+<tr><td><a href="https://mvnrepository.com/artifact/com.google.android.filament/filamat-android"><img src="https://img.shields.io/maven-central/v/com.google.android.filament/filamat-android?label=filamat-android&amp;color=green" alt="filamat-android" /></a></td><td>A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan.</td></tr>
 </tbody></table>
 </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.68.5'
+<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>
@@ -230,7 +229,8 @@ sheet for the standard material model.</li>
 <li>OpenGL ES 3.0+ for Android and iOS</li>
 <li>Metal for macOS and iOS</li>
 <li>Vulkan 1.0 for Android, Linux, macOS, and Windows</li>
-<li>WebGL 2.0 for all platforms</li>
+<li>WebGPU for Android, Linux, macOS, and Windows</li>
+<li>WebGL 2.0 for all browsers supporting it</li>
 </ul>
 <h3 id="rendering"><a class="header" href="#rendering">Rendering</a></h3>
 <ul>
@@ -265,7 +265,7 @@ sheet for the standard material model.</li>
 <ul>
 <li>HDR bloom</li>
 <li>Depth of field bokeh</li>
-<li>Multiple tone mappers: generic (customizable), ACES, filmic, etc.</li>
+<li>Multiple tone mappers: PBR Neutral, AgX, generic (customizable), ACES, filmic, etc.</li>
 <li>Color and tone management: luminance scaling, gamut mapping</li>
 <li>Color grading: exposure, night adaptation, white balance, channel mixer,
 shadows/mid-tones/highlights, ASC CDL, contrast, saturation, etc.</li>
@@ -332,6 +332,8 @@ KHR_lights_punctual</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_clearcoat</li>
 <li><input disabled="" type="checkbox" checked=""/>
+KHR_materials_dispersion</li>
+<li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_emissive_strength</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_ior</li>
@@ -340,6 +342,8 @@ KHR_materials_pbrSpecularGlossiness</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_sheen</li>
 <li><input disabled="" type="checkbox" checked=""/>
+KHR_materials_specular</li>
+<li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_transmission</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_unlit</li>
@@ -348,8 +352,6 @@ KHR_materials_variants</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_materials_volume</li>
 <li><input disabled="" type="checkbox" checked=""/>
-KHR_materials_specular</li>
-<li><input disabled="" type="checkbox" checked=""/>
 KHR_mesh_quantization</li>
 <li><input disabled="" type="checkbox" checked=""/>
 KHR_texture_basisu</li>
@@ -501,7 +503,7 @@ and tools.</p>
 <li><code>filamesh</code>:               Mesh converter</li>
 <li><code>glslminifier</code>:           Minifies GLSL source code</li>
 <li><code>matc</code>:                   Material compiler</li>
-<li><code>filament-matp</code>:          Material parser</li>
+<li><code>matedit</code>:                Material editor for compiled materials</li>
 <li><code>matinfo</code>                 Displays information about materials compiled with <code>matc</code></li>
 <li><code>mipgen</code>                  Generates a series of miplevels from a source image</li>
 <li><code>normal-blending</code>:        Tool to blend normal maps</li>

docs/dup/matdbg.html

@@ -352,7 +352,7 @@ used to create the SPIR-V is not available.</p>
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
-                            <a rel="next prefetch" href="../dup/uberz.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next prefetch" href="../dup/viewer.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -366,7 +366,7 @@ used to create the SPIR-V is not available.</p>
                         <i class="fa fa-angle-left"></i>
                     </a>
 
-                    <a rel="next prefetch" href="../dup/uberz.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next prefetch" href="../dup/viewer.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

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

docs/dup/uberz.html

@@ -236,7 +236,7 @@ mapping should be specified as an <code>optional</code> feature of the ubershade
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="../dup/matdbg.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="../dup/viewer.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
@@ -250,7 +250,7 @@ mapping should be specified as an <code>optional</code> feature of the ubershade
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="../dup/matdbg.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="../dup/viewer.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>
 

docs/dup/viewer.html

@@ -0,0 +1,333 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>viewer - Filament</title>
+
+
+        <!-- Custom HTML head -->
+
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="shortcut icon" href="../favicon.png">
+        <link rel="stylesheet" href="../css/variables.css">
+        <link rel="stylesheet" href="../css/general.css">
+        <link rel="stylesheet" href="../css/chrome.css">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="../fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="../highlight.css">
+        <link rel="stylesheet" href="../tomorrow-night.css">
+        <link rel="stylesheet" href="../ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "../";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "light" : "light";
+        </script>
+        <!-- Start loading toc.js asap -->
+        <script src="../toc.js"></script>
+    </head>
+    <body>
+    <div id="body-container">
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            const html = document.documentElement;
+            html.classList.remove('light')
+            html.classList.add(theme);
+            html.classList.add("js");
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            html.classList.remove('sidebar-visible');
+            html.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div style="display:flex;align-items:center;justify-content:center">
+                <img class="flogo" src="../images/filament_logo_small.png"></img>
+            </div>
+            <!-- populated by js -->
+            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
+            <noscript>
+                <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
+            </noscript>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <!-- Filament: disable themes because the markdeep part does not look good for dark themes -->
+                        <!--
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        -->
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="https://github.com/google/filament" title="Git repository" aria-label="Git repository">
+                            <i id="git-repository-button" class="fa fa-github"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="viewer-library"><a class="header" href="#viewer-library">Viewer Library</a></h1>
+<p>The <strong>Viewer Library</strong> (<code>libs/viewer</code>) provides a high-level abstraction for configuring and rendering Filament scenes. It is used by tools like <code>gltf_viewer</code> to load assets, manage settings, and drive the rendering loop.</p>
+<h2 id="features"><a class="header" href="#features">Features</a></h2>
+<ul>
+<li><strong>Settings Management</strong>: Centralized configuration for View, Camera, Lights, and Materials via the <code>Settings</code> struct.</li>
+<li><strong>JSON Serialization</strong>: Full support for loading and saving settings via JSON.</li>
+<li><strong>Automation</strong>: <code>AutomationEngine</code> allows scripting the viewer with a sequence of JSON-based test cases (batch mode).</li>
+<li><strong>GUI Integration</strong>: Built-in support for <code>imgui</code> via <code>ViewerGui</code> and <code>Settings</code> binding.</li>
+</ul>
+<h2 id="json-settings-schema"><a class="header" href="#json-settings-schema">JSON Settings Schema</a></h2>
+<p>The viewer settings can be configured using a JSON object. This is used for <code>gltf_viewer --settings</code> or in automation specs.</p>
+<h3 id="root-object"><a class="header" href="#root-object">Root Object</a></h3>
+<p>The root object contains the following categories:</p>
+<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Type</th><th style="text-align: left">Description</th></tr></thead><tbody>
+<tr><td style="text-align: left"><code>view</code></td><td style="text-align: left">Object</td><td style="text-align: left">Post-processing and rendering quality settings.</td></tr>
+<tr><td style="text-align: left"><code>camera</code></td><td style="text-align: left">Object</td><td style="text-align: left"><strong>[NEW]</strong> Explicit camera control (pose, projection, exposure).</td></tr>
+<tr><td style="text-align: left"><code>lighting</code></td><td style="text-align: left">Object</td><td style="text-align: left"><strong>[NEW]</strong> Environment and dynamic light settings.</td></tr>
+<tr><td style="text-align: left"><code>viewer</code></td><td style="text-align: left">Object</td><td style="text-align: left">Global viewer options (skybox, background, scaling).</td></tr>
+<tr><td style="text-align: left"><code>animation</code></td><td style="text-align: left">Object</td><td style="text-align: left"><strong>[NEW]</strong> Animation playback control.</td></tr>
+<tr><td style="text-align: left"><code>material</code></td><td style="text-align: left">Object</td><td style="text-align: left">Material overrides.</td></tr>
+</tbody></table>
+</div>
+<hr />
+<h3 id="camera-settings-camera"><a class="header" href="#camera-settings-camera">Camera Settings (<code>camera</code>)</a></h3>
+<p>Allows explicit control over the camera. If <code>enabled</code> is false, the viewer uses its default orbit camera logic (auto-scaling/centering).</p>
+<pre><code class="language-json">"camera": {
+    "enabled": true,                  // Must be true to use these explicit settings
+    "projection": "PERSPECTIVE",      // "PERSPECTIVE" or "ORTHO"
+    "center": [0, 0, 0],              // World-space look-at point
+    "lookAt": [0, 0, -1],             // World-space eye position (confusingly named 'lookAt' in internal legacy, often 'eye')
+    "up": [0, 1, 0],                  // Up vector
+    "near": 0.1,                      // Near plane
+    "far": 100.0,                     // Far plane
+    "focalLength": 28.0,              // Focal length in mm (Perspective only)
+    "fov": 0.0,                       // Field of view in degrees (overrides focalLength if &gt; 0)
+    "aperture": 16.0,                 // f-stop
+    "shutterSpeed": 125.0,            // 1/seconds
+    "sensitivity": 100.0,             // ISO
+    "focusDistance": 10.0,            // Focus distance in world units
+    "scaling": [1.0, 1.0],            // Custom projection matrix scaling (mostly for Ortho)
+    "shift": [0.0, 0.0]               // Custom projection matrix shift
+}
+</code></pre>
+<h3 id="lighting-settings-lighting"><a class="header" href="#lighting-settings-lighting">Lighting Settings (<code>lighting</code>)</a></h3>
+<p>Controls the Image Based Lighting (IBL), the Sun, and additional dynamic lights.</p>
+<pre><code class="language-json">"lighting": {
+    "iblIntensity": 30000.0,
+    "iblRotation": 0.0,               // Rotation in degrees
+    "enableSunlight": true,
+    "enableShadows": true,
+    "sunlight": {                     // **[NEW]** Nested sunlight properties
+        "intensity": 100000.0,
+        "color": [0.98, 0.92, 0.89],
+        "direction": [0.6, -1.0, -0.8],
+        "sunHaloSize": 10.0,
+        "sunHaloFalloff": 80.0,
+        "sunAngularRadius": 1.9,
+        "castShadows": true,
+        "shadowOptions": {            // Per-light shadow options
+             "mapSize": 1024,
+             "shadowCascades": 1,
+             "stable": false
+        }
+    },
+    "lights": [                       // **[NEW]** Array of custom lights
+        {
+            "type": "POINT",          // "POINT", "SPOT", "FOCUSED_SPOT", "DIRECTIONAL", "SUN"
+            "position": [0, 2, 0],
+            "color": [1, 0, 0],
+            "intensity": 5000.0,
+            "falloff": 10.0,
+            "castShadows": true,
+            "shadowOptions": { "mapSize": 512 }
+        },
+        {
+            "type": "SPOT",
+            "position": [2, 5, 2],
+            "direction": [0, -1, 0],
+            "spotInner": 0.5,         // Inner cone angle (radians)
+            "spotOuter": 0.8          // Outer cone angle (radians)
+        }
+    ]
+}
+</code></pre>
+<h3 id="view-settings-view"><a class="header" href="#view-settings-view">View Settings (<code>view</code>)</a></h3>
+<p>Standard Filament view settings.</p>
+<pre><code class="language-json">"view": {
+    "postProcessingEnabled": true,
+    "antiAliasing": "FXAA",           // "NONE", "FXAA"
+    "msaa": {
+        "enabled": true,
+        "sampleCount": 4
+    },
+    "ssao": { "enabled": true, ... },
+    "bloom": { "enabled": true, ... },
+    "dof": { "enabled": false, ... },
+    "vignette": { "enabled": false, ... },
+    "colorGrading": {
+        "toneMapping": "ACES_LEGACY", // "LINEAR", "ACES", "FILMIC", "PBR_NEUTRAL", etc.
+        "exposure": 0.0,
+        "gamma": [1.0, 1.0, 1.0]
+    }
+}
+</code></pre>
+<h3 id="viewer-options-viewer"><a class="header" href="#viewer-options-viewer">Viewer Options (<code>viewer</code>)</a></h3>
+<p>General app-level settings.</p>
+<pre><code class="language-json">"viewer": {
+    "skyboxEnabled": true,
+    "backgroundColor": [0, 0, 0],     // Used if skybox is disabled
+    "autoScaleEnabled": true,         // Fit model to unit cube
+    "groundPlaneEnabled": false
+}
+</code></pre>
+<h3 id="animation-settings-animation"><a class="header" href="#animation-settings-animation">Animation Settings (<code>animation</code>)</a></h3>
+<p>Control glTF animation playback.</p>
+<pre><code class="language-json">"animation": {
+    "enabled": true,
+    "speed": 1.0,
+    "time": -1.0                      // If &gt;= 0, forces animation to this specific time (seconds)
+}
+</code></pre>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../dup/matdbg.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="../dup/uberz.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../dup/matdbg.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="../dup/uberz.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="../elasticlunr.min.js"></script>
+        <script src="../mark.min.js"></script>
+        <script src="../searcher.js"></script>
+
+        <script src="../clipboard.min.js"></script>
+        <script src="../highlight.js"></script>
+        <script src="../book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
+</html>

docs/release/cocoapods.html

@@ -195,6 +195,30 @@ for inspection.</li>
 <p><strong>Tip:</strong> To view all defined subspecs, grep the podspec file:
 <code>grep "spec.subspec" ios/CocoaPods/Filament.podspec</code></p>
 </blockquote>
+<h2 id="testing-a-podspec-locally"><a class="header" href="#testing-a-podspec-locally">Testing a Podspec Locally</a></h2>
+<p>Before pushing a new version to the CocoaPods trunk, you should verify the podspec in a sample project.</p>
+<h3 id="using-the-sample-project"><a class="header" href="#using-the-sample-project">Using the Sample Project</a></h3>
+<p>Filament includes a dedicated sample project located in <code>ios/samples/HelloCocoaPods</code>. To test your
+local changes:</p>
+<ol>
+<li><strong>Modify the Podfile</strong>: Add a <code>:podspec</code> directive pointing to your local <code>.podspec</code> file.</li>
+</ol>
+<pre><code class="language-ruby">platform :ios, '13.0'
+
+target 'HelloCocoaPods' do
+    # Use the local development podspec
+    pod 'Filament', :podspec =&gt; '../../CocoaPods/Filament.podspec'
+end
+</code></pre>
+<ol start="2">
+<li><strong>Sync Dependencies</strong>: Run the installation command from the sample directory:</li>
+</ol>
+<pre><code class="language-bash">pod install
+</code></pre>
+<ol start="3">
+<li><strong>Verify the Build</strong>: Open the generated <code>HelloCocoaPods.xcworkspace</code> in Xcode. Build and run the
+target to ensure the headers are found and the binaries link correctly.</li>
+</ol>
 
                     </main>
 

docs/release/maven.html

@@ -199,17 +199,21 @@ Sonatype's <a href="https://central.sonatype.org/">Central Publisher Portal</a>.
 <p>The new Central Publisher Portal does not officially support Gradle. However, Sonatype provides a
 staging API compatibility service, which works with Filament's Gradle setup.</p>
 <hr />
-<h3 id="1-upload-to-the-staging-api-compatibility-service"><a class="header" href="#1-upload-to-the-staging-api-compatibility-service">1. Upload to the Staging API Compatibility Service</a></h3>
+<h3 id="1-upload-to-the-central-publisher-portal"><a class="header" href="#1-upload-to-the-central-publisher-portal">1. Upload to the Central Publisher Portal</a></h3>
+<p>To upload the artifacts, it is important to run both of these Gradle tasks together in a single
+command. This ensures the staging repository is created and closed automatically.</p>
 <pre><code class="language-bash">cd android
-./gradlew publishToSonatype
+./gradlew publishToSonatype closeSonatypeStagingRepository
 </code></pre>
-<h3 id="2-move-the-repository-to-the-central-publisher-portal"><a class="header" href="#2-move-the-repository-to-the-central-publisher-portal">2. Move the Repository to the Central Publisher Portal</a></h3>
-<p>We have a script to automate this. It reads the <code>sonatypeUsername</code> and <code>sonatypePassword</code> from your
-<code>~/.gradle/gradle.properties</code> file.</p>
+<h4 id="troubleshooting-manual-staging"><a class="header" href="#troubleshooting-manual-staging">Troubleshooting: Manual Staging</a></h4>
+<p>If you ran <code>publishToSonatype</code> by itself, the repository will remain open and won't appear in the
+portal correctly. You can fix this by running our automation script, which uses the
+<code>sonatypeUsername</code> and <code>sonatypePassword</code> from your ~/.gradle/gradle.properties file:</p>
 <pre><code class="language-bash">python3 build/common/close-sonatype-staging-repository.py
 </code></pre>
-<h3 id="3-publish-the-release-on-sonatype"><a class="header" href="#3-publish-the-release-on-sonatype">3. Publish the Release on Sonatype</a></h3>
-<p>Navigate to <a href="https://central.sonatype.com/publishing/deployments">Maven Central Repository Deployments</a>.</p>
+<h3 id="2-publish-the-release-on-sonatype"><a class="header" href="#2-publish-the-release-on-sonatype">2. Publish the Release on Sonatype</a></h3>
+<p>Once the upload is successful, you must manually trigger the final release. Navigate to <a href="https://central.sonatype.com/publishing/deployments">Maven
+Central Repository Deployments</a>.</p>
 <p>Here, you should see a new deployment with a <strong>Validated</strong> status and all your artifacts listed. Click
 the <strong>Publish</strong> button to publish the artifacts. It typically takes around 5 minutes after clicking
 <strong>Publish</strong> for the artifacts to go live.</p>

docs/wip/sky/BUILDING.md

@@ -0,0 +1,40 @@
+# Building Skybox Assets
+
+This directory contains the source code for the Simulated Skybox sample. The assets (material and textures) are pre-built in the `assets/` directory.
+
+If you need to modify the material or regenerate the moon textures, you can use the scripts provided in the `tools/` directory.
+
+## Prerequisites
+
+- **Filament**: You must have a built version of Filament. The scripts assume a standard CMake build output structure (e.g., `out/cmake-release`).
+- **Python 3**: Required for texture generation.
+- **Python Dependencies**: `numpy`, `Pillow` (automatically installed if missing, via pip).
+
+## Rebuilding the Material
+
+If you modify `simulated_skybox.mat`, you must recompile it into a `.filamat` file.
+
+```bash
+# Run from the sample root or tools directory
+./tools/build_material.sh
+```
+
+This will update `assets/simulated_skybox.filamat`.
+
+## Regenerating Moon Textures
+
+If you want to change the moon's resolution, bump scale, or blur, you can regenerate the textures.
+
+```bash
+# Run from the sample root or tools directory
+./tools/generate_moon_assets.sh [size]
+```
+
+Example:
+```bash
+./tools/generate_moon_assets.sh 512
+```
+
+This will download raw NASA data (if not present) and generate:
+- `assets/moon_disk.png`
+- `assets/moon_normal.png`

docs/wip/sky/README.md

@@ -0,0 +1,76 @@
+# Analytic Skybox Sample
+
+This sample demonstrates a **fully procedural, single-pass skybox shader** capable of simulating a dynamic day-night cycle, atmospheric scattering, volumetric clouds, and water reflections. 
+
+It is designed for graphics engineers and technical artists who need a lightweight yet physically plausible environment background without relying on static HDRI textures.
+
+## Features & Performance
+
+The shader uses a "Uber-Shader" approach where all features are computed per-pixel. Features can be toggled or tuned via uniforms to balance quality vs performance.
+
+| Feature | Cost | Control | Description |
+| :--- | :---: | :--- | :--- |
+| **Atmosphere** | 🟡 **Medium** | `turbidity`, `rayleigh`, `mie` | Analytic Rayleigh & Mie scattering. Physically based colors. |
+| **Sun Disk** | 🟢 **Low** | `sunHalo` (Radius, Limb) | Analytic sphere intersection with limb darkening. Conservation of energy (Lux). |
+| **Moon & Earthshine** | 🟢 **Low** | `sunHalo2`, `moonIntensity` | Resolved moon disk with geometric phases and dynamic Earthshine. |
+| **Stars** | 🟢 **Low** | `starControl` (Density) | High-frequency procedural noise. Occluded by clouds/moon. |
+| **Clouds** | 🔴 **High** | `cloudControl` (Coverage, Density) | 4-Octave 3D Fractal Brownian Motion (FBM). Dominates the cost when enabled. |
+| **Heat Shimmer** | 🟡 **Medium** | `shimmerControl` | UV perturbation near the horizon to simulate mirages. |
+| **Water Reflection** | 🟣 **Very High** | `waterControl` | **Renders the sky twice**. Includes procedural waves (FBM) and fresnel. |
+
+> **Note**: Rendering water (`V.y < 0`) is significantly more expensive (~2.5x) than the sky because it requires re-evaluating the atmospheric scattering and cloud noise for the reflection vector.
+
+## Shader Techniques
+
+### 1. Analytic Atmospheric Scattering
+Based on the **Hoffman & Preetham** model. It solves the single-scattering integral analytically for air molecules (Rayleigh) and aerosols (Mie).
+- **Rayleigh**: Produces the deep blue sky and red sunset colors.
+- **Mie**: Produces the white halo around the sun and general haziness.
+- **Optimization**: Uses a simplified optical depth approximation ("Air Mass") to avoid expensive ray-marching.
+
+### 2. Procedural Clouds (3D Noise)
+Clouds are rendered as a spherical shell at a specific altitude.
+- **Technique**: Ray-sphere intersection finds the entry point, then **3D FBM Noise** determines density.
+- **Lighting**: Uses a "Silver Lining" approximation (strong forward scattering) and Beers-Lambert attenuation for dark underbellies.
+- **Animation**: The noise coordinate logic helps simulate wind drift and shape evolution over time.
+
+### 3. Infinite Water Ocean
+When looking below the horizon, the shader switches to "Water Mode".
+- **Geometry**: A flat plane at $y=0$.
+- **Waves**: Generated using **Derivative-Based Noise** (or Finite Difference). This creates slope vectors that perturb the normal without needing actual geometry.
+- **Reflection**: A ray is cast from the water surface back into the sky ($R = \text{reflect}(V, N)$). The sky function is called again with $R$ to get the reflected color.
+
+### 4. Dynamic Tone Mapping
+Applies a custom tone mapping curve that varies with Sun Elevation.
+- **Noon**: Linear/Gamma (Standard).
+- **Sunset**: Higher contrast curve to compress the dynamic range and enhance the rich sunset oranges/purples.
+
+## Integration
+
+To use this in your own Filament application:
+
+1.  **Compile the Material**:
+    Use `matc` to compile `simulated_skybox.mat` into a `.filamat` file.
+    ```bash
+    matc -p mobile -a opengl -o assets/simulated_skybox.filamat simulated_skybox.mat
+    ```
+
+2.  **Load in JavaScript/C++**:
+    Create a Skybox entity and assign the material.
+
+    ```javascript
+    // JavaScript Example
+    const material = engine.createMaterial('assets/simulated_skybox.filamat');
+    const skybox = engine.createSkybox(material);
+    scene.setSkybox(skybox);
+    ```
+
+3.  **Update Uniforms**:
+    The shader requires specific uniforms (Sun Direction, Time, etc.) to be updated every frame. See `SimulatedSkybox.js` for a reference implementation of the uniform buffer management.
+
+## References
+
+*   **Hoffman & Preetham (2002)**: *"Real-time Light-Atmosphere Interactions"*
+*   **Henyey & Greenstein (1941)**: *"Diffuse radiation in the galaxy"* (Mie Phase Function)
+*   **Kasten & Young (1989)**: *"Revised optical air mass tables"*
+*   **Three.js / Sky.js**: Empirical adjustments for "Golden Hour" aesthetics.

docs/wip/sky/SimulatedSkybox.js

@@ -16,18 +16,37 @@ class SimulatedSkybox {
     this.ozone = 0.0;
     this.msFactors = [0.1, 0.5, 0.0];
     this.contrast = 1.0;
-    this.nightColor = [0.0, 0.0003, 0.00075];
+    this.nightColor = [0.0, 3.0e-9, 7.5e-9];
     this.shimmerControl = [0.0, 20.0, 0.1];
     this.cloudControl = [0.0, 0.1, 8000.0, 0.0];
     this.cloudControl2 = [0.0, 0.0, 0.0, 0.0];
     this.waterControl = [50.0, 1.0, 1.0, 4.0]; // x=Strength, y=Speed, z=DerivativeTrick, w=Octaves
-    this.starControl = [1.0, 1.0]; // x=Density (0-1), y=Enabled (0-1)
+    this.starControl = [0.001, 1.0, 350.0, 0.01]; // x=Density, y=Enabled, z=Frequency, w=PixelScale
+    this.starIntensity = 1.0;
+    this.focalLength = 24.0;
+    this.height = 1000.0;
     this.planetRadius = 6360.0;
 
     // Sun Halo
     // x=cos(rad), y=limbDarkening, z=intensity, w=enabled
+    // Sun Halo
     this.sunHalo = [Math.cos(0.5 * Math.PI / 180.0), 0.5, 1.0, 1.0];
 
+    // Moon Parameters (Mapped to Secondary Sun)
+    this.moonDirection = [-0.2, 0.8, -0.2]; // Default Moon Pos
+    this.moonIntensity = 1.0; // Scale Factor (1.0 = Physical Peak)
+    // x=cos(rad), y=sin(rad) [Precision Fix], z=intensity, w=enabled
+    this.moonHalo = [Math.cos(0.5 * Math.PI / 180.0), Math.sin(0.5 * Math.PI / 180.0), 1.0, 0.0]; // Disabled by default
+
+    this.moonTextureObj = null;
+    this.moonNormalObj = null;
+    this.milkyWayTextureObj = null;
+
+    // Milky Way Parameters
+    // x=Intensity, y=Saturation, z=Unused
+    this.milkyWayControl = [1.0, 1.2, 0.05];
+    this.milkyWayEnabled = true;
+    this.milkyWayRotation = [1, 0, 0, 0, 1, 0, 0, 0, 1]; // Identity by default
     this.initEntity();
   }
 
@@ -44,6 +63,184 @@ class SimulatedSkybox {
     rcm.setMaterialInstanceAt(instance, 0, this.materialInstance);
 
     console.log("Material loaded and bound.");
+
+    // Load Moon Texture
+    try {
+      const texUrl = 'assets/moon_disk.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly (Uint8ClampedArray)
+      // Filament supports RGBA upload for RGB/SRGB internal formats (drops alpha).
+      // This matches Canvas layout (Top-Down, RGBA) and is 4-byte aligned.
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer), // Wrap buffer to ensure Uint8Array
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonTextureObj.setImage(this.engine, 0, pbd);
+      this.moonTextureObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonTexture', this.moonTextureObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon texture:", e);
+    }
+
+    // Load Moon Normal
+    try {
+      const texUrl = 'assets/moon_normal.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.moonNormalObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.RGBA8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, width, height);
+
+      // Use RGBA data directly
+      const pbd = Filament.PixelBuffer(
+        new Uint8Array(imageData.data.buffer),
+        PixelDataFormat.RGBA,
+        PixelDataType.UBYTE
+      );
+
+      this.moonNormalObj.setImage(this.engine, 0, pbd);
+      this.moonNormalObj.generateMipmaps(this.engine);
+
+      const sampler = new TextureSampler(
+        MinFilter.LINEAR_MIPMAP_LINEAR,
+        MagFilter.LINEAR,
+        WrapMode.CLAMP_TO_EDGE
+      );
+
+      this.materialInstance.setTextureParameter('moonNormal', this.moonNormalObj, sampler);
+
+    } catch (e) {
+      console.error("Failed to load moon normal:", e);
+    }
+
+    // Load Milky Way Texture
+    try {
+      const texUrl = 'assets/milkyway.png';
+      const Texture = Filament.Texture;
+      const TextureSampler = Filament.TextureSampler;
+      const PixelDataFormat = Filament.PixelDataFormat;
+      const PixelDataType = Filament.PixelDataType;
+      const TextureUsage = Filament.Texture$Usage;
+      const TextureFormat = Filament.Texture$InternalFormat;
+      const MinFilter = Filament.MinFilter;
+      const MagFilter = Filament.MagFilter;
+      const WrapMode = Filament.WrapMode;
+      const texResponse = await fetch(texUrl);
+      const texBlob = await texResponse.blob();
+      const bitmap = await createImageBitmap(texBlob);
+
+      const width = bitmap.width;
+      const height = bitmap.height;
+
+      this.milkyWayTextureObj = Texture.Builder()
+        .width(width)
+        .height(height)
+        .levels(0xff)
+        .format(TextureFormat.SRGB8_A8)
+        .usage(TextureUsage.SAMPLEABLE.value | TextureUsage.UPLOADABLE.value | TextureUsage.GEN_MIPMAPPABLE.value)
+        .build(this.engine);
+
+      // Extract Data using a Canvas
+      const canvas = document.createElement('canvas');
+      canvas.width = width;
+      canvas.height = height;
+      const ctx = canvas.getContext('2d');
+      ctx.drawImage(bitmap, 0, 0);
+      try {
+        const imageData = ctx.getImageData(0, 0, width, height);
+
+        // Use RGBA data directly
+        const pbd = Filament.PixelBuffer(
+          new Uint8Array(imageData.data.buffer),
+          PixelDataFormat.RGBA,
+          PixelDataType.UBYTE
+        );
+
+        this.milkyWayTextureObj.setImage(this.engine, 0, pbd);
+        this.milkyWayTextureObj.generateMipmaps(this.engine);
+
+        const sampler = new TextureSampler(
+          MinFilter.LINEAR_MIPMAP_LINEAR,
+          MagFilter.LINEAR,
+          WrapMode.REPEAT // Equirectangular wraps horizontally
+        );
+
+        this.materialInstance.setTextureParameter('milkyWayTexture', this.milkyWayTextureObj, sampler);
+      } catch (err) {
+        console.warn("Milky Way texture data access failed (CORS?):", err);
+      }
+
+    } catch (e) {
+      console.error("Failed to load milky way texture:", e);
+    }
+
     this.updateCoefficients();
   }
 
@@ -84,16 +281,16 @@ class SimulatedSkybox {
 
     this.ib.setBuffer(this.engine, TRIANGLE_INDICES);
 
-    // We create a dummy material first or wait? 
-    // In JS we usually can't block. We'll rely on loadMaterial being called.
-    // For now, we build the Renderable without material, then set it later.
+    // Build the Renderable without material; it will be set later by loadMaterial.
+
 
     RenderableManager.Builder(1)
       .geometry(0, PrimitiveType.TRIANGLES, this.vb, this.ib)
       .culling(false)
       .castShadows(false)
       .receiveShadows(false)
-      .priority(7) // Render behind translucent objects? 7 is skybox priority typically.
+      .priority(7) // Skybox priority
+
       .build(this.engine, this.entity);
   }
 
@@ -215,11 +412,107 @@ class SimulatedSkybox {
   }
 
   setStarControl(density, enabled) {
-    this.starControl[0] = Math.max(0.0, Math.min(1.0, density));
+    // Compensate for grid frequency reduction (350 -> 100)
+    // Fewer cells = fewer stars, so we increase density threshold.
+    // Factor ~ (350/100)^2 = 12.25
+    const compensatedDensity = density * 12.0;
+    this.starControl[0] = Math.max(0.0, Math.min(1.0, compensatedDensity));
     this.starControl[1] = enabled ? 1.0 : 0.0;
     this.updateCoefficients();
   }
 
+  setFocalLength(mm) {
+    this.focalLength = Math.max(1.0, mm);
+    this.updateStarFrequency();
+  }
+
+  setResolution(height) {
+    this.height = Math.max(1.0, height);
+    this.updateStarFrequency();
+  }
+
+  updateStarFrequency() {
+    // World-Anchored Stars
+    // z = Fixed Frequency (World Space Grid)
+    // w = Pixel Scale (Screen Space Radius)
+
+    // Fixed Frequency: Defines the "Universe" coordinate system. 
+    // Reduced to 100.0 to allow larger stars without clipping (square artifacts).
+    this.starControl[2] = 100.0;
+
+    // Pixel Scale in Radians
+    // We use linear scaling (24/f) instead of atan(fov) to ensure star size remains
+    // constant in pixels across all focal lengths (Perspective Projection).
+    const fovFactor = 24.0 / this.focalLength;
+    const pixelScale = (1.0 / this.height) * fovFactor;
+
+    // Pass to shader (w component)
+    // Target radius: 1.3 pixels (Diameter 2.6 pixels)
+    // Visible but sharp.
+    this.starControl[3] = pixelScale * 1.3;
+
+    this.updateCoefficients();
+  }
+
+  setStarIntensity(intensity) {
+    this.starIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonPosition(direction) {
+    // normalize
+    const len = Math.hypot(direction[0], direction[1], direction[2]);
+    if (len > 0) {
+      this.moonDirection = [direction[0] / len, direction[1] / len, direction[2] / len];
+    }
+    this.updateCoefficients();
+  }
+
+  setMoonIntensity(intensity) {
+    this.moonIntensity = Math.max(0.0, intensity);
+    this.updateCoefficients();
+  }
+
+  setMoonRadius(degrees) {
+    const rad = degrees * (Math.PI / 180.0);
+    this.moonHalo[0] = Math.cos(rad);
+    this.moonHalo[1] = Math.sin(rad);
+    this.updateCoefficients();
+  }
+
+  setMoonEnabled(enabled) {
+    this.moonHalo[3] = enabled ? 1.0 : 0.0;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayControl(intensity, saturation, blackPoint) {
+    this.milkyWayControl[0] = Math.max(0.0, intensity);
+    this.milkyWayControl[1] = Math.max(0.0, saturation);
+    if (blackPoint !== undefined) {
+      this.milkyWayControl[2] = Math.max(0.0, blackPoint);
+    }
+    this.updateCoefficients();
+  }
+
+  setMilkyWayEnabled(enabled) {
+    this.milkyWayEnabled = !!enabled;
+    this.updateCoefficients();
+  }
+
+  setMilkyWayRotation(rotationMatrix) {
+    if (rotationMatrix && rotationMatrix.length === 9) {
+      this.milkyWayRotation = rotationMatrix;
+      this.updateCoefficients();
+    }
+  }
+
+
+
+  setExposure(exposure) {
+    this.exposure = exposure;
+    this.updateCoefficients();
+  }
+
   updateCoefficients() {
     if (!this.materialInstance) {
       console.warn("updateCoefficients called before material loaded");
@@ -297,15 +590,133 @@ class SimulatedSkybox {
 
     this.materialInstance.setFloatParameter('contrast', this.contrast);
 
-    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity);
+    const nightColorScaled = this.nightColor.map(v => v * this.sunIntensity); // Lux scaling
     this.materialInstance.setFloat3Parameter('nightColor', new Float32Array(nightColorScaled));
 
     this.materialInstance.setFloat4Parameter('shimmerControl', new Float32Array(shimmerUniform));
     this.materialInstance.setFloat4Parameter('cloudControl', new Float32Array(cloudUniform));
     this.materialInstance.setFloat4Parameter('cloudControl2', new Float32Array(this.cloudControl2));
     this.materialInstance.setFloat4Parameter('waterControl', new Float32Array(this.waterControl));
-    this.materialInstance.setFloat2Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloat4Parameter('starControl', new Float32Array(this.starControl));
+    this.materialInstance.setFloatParameter('starIntensity', this.starIntensity);
 
     this.materialInstance.setFloatParameter('sunIntensity', physicalSunIntensity);
+
+    // Moon Upload (Secondary Sun)
+    this.materialInstance.setFloat3Parameter('sunDirection2', new Float32Array(this.moonDirection));
+
+    // Calculate Moon Phase Factor (Lambertian Sphere)
+    // We model the moon as a Lambertian sphere to calculate its integrated brightness (illuminance)
+    // based on the phase angle (angle between Sun-Moon and Observer-Moon vectors).
+    //
+    // Phase Angle (alpha):
+    // For a distant observer (Earth), the phase angle can be approximated as the angle between
+    // the vector to the Sun and the vector to the Earth (from the Moon).
+    // cos(alpha) = -dot(L_moon, L_sun)
+    //
+    // Lambertian Phase Law:
+    // The integrated flux of a lit sphere varies as:
+    // Phi(alpha) = (1/PI) * (sin(alpha) + (PI - alpha) * cos(alpha))
+    // This gives 1.0 at Full Moon (alpha=0) and 0.0 at New Moon (alpha=PI).
+
+    const dotSM = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+
+    // Final Intensity = Peak * Scale (No Phase Factor - Phase is handled in Shader via N.L)
+    const MOON_PEAK_LUX = 1.0;
+    const finalMoonIntensity = MOON_PEAK_LUX * this.moonIntensity;
+
+    this.materialInstance.setFloatParameter('sunIntensity2', finalMoonIntensity);
+
+    // Scale Milky Way by Sun Intensity
+    // Calibration: 1.0 User Intensity = 1.5e-3 cd/m^2 (Nits) approx.
+    // Target: 1.5e-3 Nits. SunIntensity = 100,000.
+    // Scale = 1.5e-3 / 1.0e5 = 1.5e-8.
+    const mwIntensity = this.milkyWayEnabled ? this.milkyWayControl[0] : 0.0;
+    const mwUniform = [
+      mwIntensity * this.sunIntensity * 1.5e-8,
+      this.milkyWayControl[1],
+      this.milkyWayControl[2]
+    ];
+    this.materialInstance.setFloat3Parameter('milkyWayControl', new Float32Array(mwUniform));
+    this.materialInstance.setMat3Parameter('milkyWayRotation', new Float32Array(this.milkyWayRotation));
+
+    // Moon Halo Upload (Disk Visualization)
+    // Multiplier = 1.0 / SolidAngle
+    const moonSolidAngle = 2.0 * F_PI * (1.0 - this.moonHalo[0]);
+    const moonRadConv = 1.0 / Math.max(1e-9, moonSolidAngle);
+    const moonHaloUpload = [...this.moonHalo];
+    moonHaloUpload[2] *= moonRadConv;
+    this.materialInstance.setFloat4Parameter('sunHalo2', new Float32Array(moonHaloUpload));
+    this.materialInstance.setFloatParameter('exposure', this.exposure !== undefined ? this.exposure : 1.0);
+
+    // Solar Eclipse (CPU Calculation)
+    const sunRadius = Math.acos(this.sunHalo[0]);
+    const moonRadius = Math.acos(this.moonHalo[0]);
+    // Dot product of Sun and Moon directions
+    const dot = this.sunDirection[0] * this.moonDirection[0] +
+      this.sunDirection[1] * this.moonDirection[1] +
+      this.sunDirection[2] * this.moonDirection[2];
+    const separation = Math.acos(Math.max(-1.0, Math.min(1.0, dot)));
+
+    let eclipseFactor = 1.0;
+    // Only calculate if moon is enabled
+    if (this.moonHalo[3] > 0.5) {
+      const overlap = this.areaIntersection(sunRadius, moonRadius, separation);
+      const sunArea = Math.PI * sunRadius * sunRadius;
+      // Ensure we don't divide by zero and clamp result
+      const ratio = overlap / Math.max(1e-9, sunArea);
+      eclipseFactor = 1.0 - Math.max(0.0, Math.min(1.0, ratio));
+
+    }
+
+    // Safety check for NaN
+    if (isNaN(eclipseFactor)) {
+      console.warn("SimulatedSkybox: eclipseFactor is NaN, resetting to 1.0");
+      eclipseFactor = 1.0;
+    }
+
+
+
+    this.materialInstance.setFloatParameter('eclipseFactor', eclipseFactor);
+  }
+
+  areaIntersection(r1, r2, d) {
+    // Circle intersection area
+    // r1, r2: radii
+    // d: distance between centers
+
+    // Case 1: Too far apart
+    if (d >= r1 + r2) {
+      return 0.0;
+    }
+    // Case 2: One inside another
+    if (d <= Math.abs(r1 - r2)) {
+      return Math.PI * Math.min(r1, r2) * Math.min(r1, r2);
+    }
+
+    const r1sq = r1 * r1;
+    const r2sq = r2 * r2;
+
+    // Law of Cosines for sector angles
+    // c1 = (d^2 + r1^2 - r2^2) / (2 * d * r1)
+    // c2 = (d^2 + r2^2 - r1^2) / (2 * d * r2)
+    // We clamp to [-1, 1] to avoid NaN from floating point errors
+    const c1 = Math.max(-1.0, Math.min(1.0, (d * d + r1sq - r2sq) / (2.0 * d * r1)));
+    const c2 = Math.max(-1.0, Math.min(1.0, (d * d + r2sq - r1sq) / (2.0 * d * r2)));
+
+    const part1 = r1sq * Math.acos(c1);
+    const part2 = r2sq * Math.acos(c2);
+
+    // Heron's formula for the triangle area * 2
+    // The sqrt term represents the area of the two triangles formed by the chord and centers.
+
+
+    // Robust sqrt
+    const val = (-d + r1 + r2) * (d + r1 - r2) * (d - r1 + r2) * (d + r1 + r2);
+    const part3 = 0.5 * Math.sqrt(Math.max(0.0, val));
+
+    return part1 + part2 - part3;
   }
 }

docs/wip/sky/assets/suncalc_global.js

@@ -0,0 +1,332 @@
+/*
+ (c) 2011-2015, Vladimir Agafonkin
+ SunCalc is a JavaScript library for calculating sun/moon position and light phases.
+ https://github.com/mourner/suncalc
+*/
+
+(function () { 'use strict';
+
+// shortcuts for easier to read formulas
+
+var PI   = Math.PI,
+    sin  = Math.sin,
+    cos  = Math.cos,
+    tan  = Math.tan,
+    asin = Math.asin,
+    atan = Math.atan2,
+    acos = Math.acos,
+    rad  = PI / 180;
+
+// sun calculations are based on https://aa.quae.nl/en/reken/zonpositie.html formulas
+
+
+// date/time constants and conversions
+
+var dayMs = 1000 * 60 * 60 * 24,
+    J1970 = 2440588,
+    J2000 = 2451545;
+
+function toJulian(date) { return date.valueOf() / dayMs - 0.5 + J1970; }
+function fromJulian(j)  { return new Date((j + 0.5 - J1970) * dayMs); }
+function toDays(date)   { return toJulian(date) - J2000; }
+
+
+// general calculations for position
+
+var e = rad * 23.4397; // obliquity of the Earth
+
+function rightAscension(l, b) { return atan(sin(l) * cos(e) - tan(b) * sin(e), cos(l)); }
+function declination(l, b)    { return asin(sin(b) * cos(e) + cos(b) * sin(e) * sin(l)); }
+
+function azimuth(H, phi, dec)  { return atan(sin(H), cos(H) * sin(phi) - tan(dec) * cos(phi)); }
+function altitude(H, phi, dec) { return asin(sin(phi) * sin(dec) + cos(phi) * cos(dec) * cos(H)); }
+
+function siderealTime(d, lw) { return rad * (280.16 + 360.9856235 * d) - lw; }
+
+function astroRefraction(h) {
+    if (h < 0) // the following formula works for positive altitudes only.
+        h = 0; // if h = -0.08901179 a div/0 would occur.
+
+    // formula 16.4 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+    // 1.02 / tan(h + 10.26 / (h + 5.10)) h in degrees, result in arc minutes -> converted to rad:
+    return 0.0002967 / Math.tan(h + 0.00312536 / (h + 0.08901179));
+}
+
+// general sun calculations
+
+function solarMeanAnomaly(d) { return rad * (357.5291 + 0.98560028 * d); }
+
+function eclipticLongitude(M) {
+
+    var C = rad * (1.9148 * sin(M) + 0.02 * sin(2 * M) + 0.0003 * sin(3 * M)), // equation of center
+        P = rad * 102.9372; // perihelion of the Earth
+
+    return M + C + P + PI;
+}
+
+function sunCoords(d) {
+
+    var M = solarMeanAnomaly(d),
+        L = eclipticLongitude(M);
+
+    return {
+        dec: declination(L, 0),
+        ra: rightAscension(L, 0)
+    };
+}
+
+
+var SunCalc = {};
+
+
+// calculates sun position for a given date and latitude/longitude
+
+SunCalc.getPosition = function (date, lat, lng) {
+
+    var lw  = rad * -lng,
+        phi = rad * lat,
+        d   = toDays(date),
+
+        c  = sunCoords(d),
+        H  = siderealTime(d, lw) - c.ra;
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: altitude(H, phi, c.dec)
+    };
+};
+
+
+// sun times configuration (angle, morning name, evening name)
+
+var times = SunCalc.times = [
+    [-0.833, 'sunrise',       'sunset'      ],
+    [-0.3,   'sunriseEnd',    'sunsetStart' ],
+    [-6,     'dawn',          'dusk'        ],
+    [-12,    'nauticalDawn',  'nauticalDusk'],
+    [-18,    'nightEnd',      'night'       ],
+    [6,      'goldenHourEnd', 'goldenHour'  ]
+];
+
+// adds a custom time to the times config
+
+SunCalc.addTime = function (angle, riseName, setName) {
+    times.push([angle, riseName, setName]);
+};
+
+
+// calculations for sun times
+
+var J0 = 0.0009;
+
+function julianCycle(d, lw) { return Math.round(d - J0 - lw / (2 * PI)); }
+
+function approxTransit(Ht, lw, n) { return J0 + (Ht + lw) / (2 * PI) + n; }
+function solarTransitJ(ds, M, L)  { return J2000 + ds + 0.0053 * sin(M) - 0.0069 * sin(2 * L); }
+
+function hourAngle(h, phi, d) { return acos((sin(h) - sin(phi) * sin(d)) / (cos(phi) * cos(d))); }
+
+// returns set time for the given sun altitude
+function getSetJ(h, lw, phi, dec, n, M, L) {
+
+    var w = hourAngle(h, phi, dec),
+        a = approxTransit(w, lw, n);
+    return solarTransitJ(a, M, L);
+}
+
+
+// calculates sun times for a given date, latitude/longitude, and, optionally,
+// the observer height (in meters) relative to the horizon
+
+SunCalc.getTimes = function (date, lat, lng, height) {
+
+    height = height || 0;
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+
+        dh = observerAngle(height),
+
+        d = toDays(date),
+        n = julianCycle(d, lw),
+        ds = approxTransit(0, lw, n),
+
+        M = solarMeanAnomaly(ds),
+        L = eclipticLongitude(M),
+        dec = declination(L, 0),
+
+        Jnoon = solarTransitJ(ds, M, L);
+
+    var result = {
+        solarNoon: fromJulian(Jnoon),
+        nadir: fromJulian(Jnoon - 0.5)
+    };
+
+    var i, len, time, h0, Jset, Jrise;
+
+    for (i = 0, len = times.length; i < len; i += 1) {
+        time = times[i];
+
+        h0 = (time[0] + dh) * rad;
+
+        Jset = getSetJ(h0, lw, phi, dec, n, M, L);
+        Jrise = Jnoon - (Jset - Jnoon);
+
+        result[time[1]] = fromJulian(Jrise);
+        result[time[2]] = fromJulian(Jset);
+    }
+
+    return result;
+};
+
+// moon calculations, based on http://aa.quae.nl/en/reken/hemelpositie.html formulas
+
+function moonCoords(d) { // geocentric ecliptic coordinates of the moon
+
+    var L = rad * (218.316 + 13.176396 * d), // ecliptic longitude
+        M = rad * (134.963 + 13.064993 * d), // mean anomaly
+        F = rad * (93.272 + 13.229350 * d),  // mean distance
+
+        l  = L + rad * 6.289 * sin(M), // longitude
+        b  = rad * 5.128 * sin(F),     // latitude
+        dt = 385001 - 20905 * cos(M);  // distance to the moon in km
+
+    return {
+        ra: rightAscension(l, b),
+        dec: declination(l, b),
+        dist: dt
+    };
+}
+
+SunCalc.getMoonPosition = function (date, lat, lng) {
+
+    var lw = rad * -lng,
+        phi = rad * lat,
+        d = toDays(date),
+
+        c = moonCoords(d),
+        H = siderealTime(d, lw) - c.ra,
+        h = altitude(H, phi, c.dec),
+        // formula 14.1 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+        pa = atan(sin(H), tan(phi) * cos(c.dec) - sin(c.dec) * cos(H));
+
+    return {
+        azimuth: azimuth(H, phi, c.dec),
+        altitude: h + astroRefraction(h), // altitude correction for refraction,
+        distance: c.dist,
+        parallacticAngle: pa
+    };
+};
+
+
+// calculations for illumination parameters of the moon,
+// based on http://idlastro.gsfc.nasa.gov/ftp/pro/astro/mphase.pro formulas and
+// Chapter 48 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
+
+SunCalc.getMoonIllumination = function (date) {
+
+    var d = toDays(date || new Date()),
+        s = sunCoords(d),
+        m = moonCoords(d),
+
+        sdist = 149598000, // distance from Earth to Sun in km
+
+        phi = acos(sin(s.dec) * sin(m.dec) + cos(s.dec) * cos(m.dec) * cos(s.ra - m.ra)),
+        inc = atan(sdist * sin(phi), m.dist - sdist * cos(phi)),
+        angle = atan(cos(s.dec) * sin(s.ra - m.ra), sin(s.dec) * cos(m.dec) -
+                cos(s.dec) * sin(m.dec) * cos(s.ra - m.ra));
+
+    return {
+        fraction: (1 + cos(inc)) / 2,
+        phase: 0.5 + 0.5 * inc * (angle < 0 ? -1 : 1) / Math.PI,
+        angle: angle
+    };
+};
+
+
+function hoursLater(date, h) {
+    return new Date(date.valueOf() + h * dayMs / 24);
+}
+
+// calculations for moon rise/set times are based on http://www.stargazing.net/kepler/moonrise.html article
+
+SunCalc.getMoonTimes = function (date, lat, lng, inUTC) {
+    var t = new Date(date);
+    if (inUTC) t.setUTCHours(0, 0, 0, 0);
+    else t.setHours(0, 0, 0, 0);
+
+    var hc = 0.133 * rad,
+        h0 = SunCalc.getMoonPosition(t, lat, lng).altitude - hc,
+        h1, h2, rise, set, a, b, xe, ye, d, roots, x1, x2, dx;
+
+    // go in 2-hour chunks, each time seeing if a 3-point quadratic curve crosses zero (which means rise or set)
+    for (var i = 1; i <= 24; i += 2) {
+        h1 = SunCalc.getMoonPosition(hoursLater(t, i), lat, lng).altitude - hc;
+        h2 = SunCalc.getMoonPosition(hoursLater(t, i + 1), lat, lng).altitude - hc;
+
+        a = (h0 + h2) / 2 - h1;
+        b = (h2 - h0) / 2;
+        xe = -b / (2 * a);
+        ye = (a * xe + b) * xe + h1;
+        d = b * b - 4 * a * h1;
+        roots = 0;
+
+        if (d >= 0) {
+            dx = Math.sqrt(d) / (Math.abs(a) * 2);
+            x1 = xe - dx;
+            x2 = xe + dx;
+            if (Math.abs(x1) <= 1) roots++;
+            if (Math.abs(x2) <= 1) roots++;
+            if (x1 < -1) x1 = x2;
+        }
+
+        if (roots === 1) {
+            if (h0 < 0) rise = i + x1;
+            else set = i + x1;
+
+        } else if (roots === 2) {
+            rise = i + (ye < 0 ? x2 : x1);
+            set = i + (ye < 0 ? x1 : x2);
+        }
+
+        if (rise && set) break;
+
+        h0 = h2;
+    }
+
+    var result = {};
+
+    if (rise) result.rise = hoursLater(t, rise);
+    if (set) result.set = hoursLater(t, set);
+
+    if (!rise && !set) result[ye > 0 ? 'alwaysUp' : 'alwaysDown'] = true;
+
+    return result;
+};
+
+// observerAngle helper was missing in my copy-paste?
+// Ah, it was in the chunks. Let me check the chunks again.
+// Function `observerAngle` was in chunk 0.
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// I included it.
+
+// Note: I replaced var with const/let or kept var?
+// The original used const/let but I used var in my head above?
+// I will just use the original code but adapted.
+// Actually, to be safe, I'll use the code I wrote in this block which is adapted to use 'var' (ES5 safe) or just ES6 is fine.
+// The user Environment is modern (Chrome/ES6 likely).
+// But for safety:
+// I'll stick to 'var' definitions I wrote above which seem complete?
+// Wait, I might have missed `observerAngle` definition in my manual reconstruction above?
+// No, `observerAngle` is called in `getTimes`.
+// I MUST define it.
+// I added it in the loop above? No.
+// Let me double check the `write_to_file` content I prepared.
+// I see:
+// `function observerAngle(height) { return -2.076 * Math.sqrt(height) / 60; }`
+// Yes, it is there.
+
+// export
+window.SunCalc = SunCalc;
+
+}());

docs/wip/sky/index.html

@@ -24,6 +24,7 @@
 
 <body>
   <canvas></canvas>
+
   <!-- Filament -->
   <script src="filament.js"></script>
   <script src="gl-matrix-min.js"></script>
@@ -31,9 +32,13 @@
   <!-- UI -->
   <script src="lil-gui.js"></script>
 
+  <!-- Utils -->
+  <script src="assets/suncalc_global.js"></script>
+
   <!-- App -->
-  <script src="SimulatedSkybox.js?v=26"></script>
-  <script src="main.js?v=26"></script>
+
+  <script src="SimulatedSkybox.js?v=9999"></script>
+  <script src="main.js?v=9999"></script>
 </body>
 
 </html>

docs/wip/sky/main.js

@@ -1,10 +1,123 @@
 
 // main.js
 
-Filament.init(['assets/simulated_skybox.filamat'], () => {
+Filament.init(['assets/simulated_skybox.filamat?v=' + Date.now()], () => {
   window.app = new App(document.getElementsByTagName('canvas')[0]);
 });
 
+// Helper: Julian Date
+function getJD(date) {
+  return date.getTime() / 86400000.0 + 2440587.5;
+}
+
+// Helper: GMST from Date
+function getGMST(date) {
+  const JD = getJD(date);
+  const D = JD - 2451545.0;
+  // GMST = 18.697... + 24.0657... * D
+  let gmst = 18.697374558 + 24.06570982441908 * D;
+  gmst = gmst % 24.0;
+  if (gmst < 0) gmst += 24.0;
+  return gmst;
+}
+
+// Helper: Matrix Rotation
+function rotateX(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m1 = m[1], m2 = m[2];
+  const m4 = m[4], m5 = m[5];
+  const m7 = m[7], m8 = m[8];
+  m[1] = m1 * c - m2 * s;
+  m[2] = m1 * s + m2 * c;
+  m[4] = m4 * c - m5 * s;
+  m[5] = m4 * s + m5 * c;
+  m[7] = m7 * c - m8 * s;
+  m[8] = m7 * s + m8 * c;
+}
+function rotateY(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m2 = m[2];
+  const m3 = m[3], m5 = m[5];
+  const m6 = m[6], m8 = m[8];
+  m[0] = m0 * c + m2 * s;
+  m[2] = -m0 * s + m2 * c;
+  m[3] = m3 * c + m5 * s;
+  m[5] = -m3 * s + m5 * c;
+  m[6] = m6 * c + m8 * s;
+  m[8] = -m6 * s + m8 * c;
+}
+function rotateZ(m, angle) {
+  const c = Math.cos(angle);
+  const s = Math.sin(angle);
+  const m0 = m[0], m1 = m[1];
+  const m3 = m[3], m4 = m[4];
+  const m6 = m[6], m7 = m[7];
+  m[0] = m0 * c - m1 * s;
+  m[1] = m0 * s + m1 * c;
+  m[3] = m3 * c - m4 * s;
+  m[4] = m3 * s + m4 * c;
+  m[6] = m6 * c - m7 * s;
+  m[7] = m6 * s + m7 * c;
+}
+
+// Galactic to Equatorial (J2000)
+// This matrix converts Galactic vectors to Equatorial vectors.
+// Or effectively, if we want to render Galactic texture from Equatorial View vector V_eq:
+// V_gal = Inv(Rot_Gal_to_Eq) * V_eq = Rot_Eq_to_Gal * V_eq.
+// The shader does: V_gal = Rotation * V_world.
+// So Rotation = Rot_Eq_to_Gal * Rot_World_to_Eq.
+//
+// Galactic North Pole (J2000): RA = 192.85948, Dec = 27.12825
+// Ascending Node: RA = 282.85
+// 
+// Pre-computed Rotation Matrix (Equatorial -> Galactic)
+// Based on standard transformation matrices.
+// 
+// R_eq_gal = 
+// [ -0.054876  -0.873437  -0.483835 ]
+// [  0.494109  -0.444830   0.746982 ]
+// [ -0.867666  -0.198076   0.455984 ]
+//
+// Let's use this static definition.
+const MAT_EQ_TO_GAL = [
+  -0.054876, 0.494109, -0.867666,
+  -0.873437, -0.444830, -0.198076,
+  -0.483835, 0.746982, 0.455984
+];
+
+// Matrix multiplication 3x3
+function multiplyMat3(a, b) {
+  const out = new Float32Array(9);
+  // Row-major or Column-major? Filament is Column-major usually.
+  // GLSL is Column-major.
+  // Mat3 in array: [col0.x, col0.y, col0.z, col1.x, ...]
+  // So a[0] is (0,0), a[1] is (1,0), a[3] is (0,1).
+  //
+  // out = a * b
+  const a00 = a[0], a10 = a[1], a20 = a[2];
+  const a01 = a[3], a11 = a[4], a21 = a[5];
+  const a02 = a[6], a12 = a[7], a22 = a[8];
+
+  const b00 = b[0], b10 = b[1], b20 = b[2];
+  const b01 = b[3], b11 = b[4], b21 = b[5];
+  const b02 = b[6], b12 = b[7], b22 = b[8];
+
+  out[0] = a00 * b00 + a01 * b10 + a02 * b20;
+  out[1] = a10 * b00 + a11 * b10 + a12 * b20;
+  out[2] = a20 * b00 + a21 * b10 + a22 * b20;
+
+  out[3] = a00 * b01 + a01 * b11 + a02 * b21;
+  out[4] = a10 * b01 + a11 * b11 + a12 * b21;
+  out[5] = a20 * b01 + a21 * b11 + a22 * b21;
+
+  out[6] = a00 * b02 + a01 * b12 + a02 * b22;
+  out[7] = a10 * b02 + a11 * b12 + a12 * b22;
+  out[8] = a20 * b02 + a21 * b12 + a22 * b22;
+  return out;
+}
+
 class App {
   constructor(canvas) {
     this.canvas = canvas;
@@ -15,13 +128,10 @@ class App {
     this.skybox.entity = this.skybox.entity; // Ensuring access if needed
     this.scene.addEntity(this.skybox.entity);
 
-    // Load the material explicitly since we passed it to init but SimulatedSkybox needs to bind it
-    // Actually SimulatedSkybox.loadMaterial fetches it. 
-    // Since we already loaded it in Filament.init, we can arguably just use it if we had a way to access the asset.
-    // But Filament.init assets are for internal or easy access via assets object if configured?
-    // Let's just let SimulatedSkybox fetch it again or use a blob if we wanted.
-    // Simpler: Just let SimulatedSkybox fetch it.
-    this.skybox.loadMaterial('assets/simulated_skybox.filamat').then(() => {
+    // Load the material explicitly. SimulatedSkybox.loadMaterial fetches it.
+
+    const matUrl = 'assets/simulated_skybox.filamat?v=' + Date.now();
+    this.skybox.loadMaterial(matUrl).then(() => {
       this.initGUI();
     });
 
@@ -71,6 +181,15 @@ class App {
 
     this.initControls(); // Initialize controls immediately
 
+    this.mwParams = {
+      enabled: true,
+      intensity: 1.0,
+      saturation: 1.0,
+      blackPoint: 0.07,
+      siderealTime: 0.0, // Hours [0-24]
+      latitude: 34.0, // Default Lat
+    };
+
     this.resize();
     window.addEventListener('resize', this.resize.bind(this));
 
@@ -99,6 +218,13 @@ class App {
     const exposure = this.getExposure();
     const preExposedIntensity = this.params.sunIntensity * exposure;
     this.skybox.setSunIntensity(preExposedIntensity);
+    this.skybox.setExposure(exposure); // Update Skybox Exposure Uniform
+
+    // Moon Exposure
+    if (this.mParams) {
+      const preExposedMoon = this.mParams.intensity * exposure;
+      this.skybox.setMoonIntensity(preExposedMoon);
+    }
   }
 
   updateCameraProjection() {
@@ -106,6 +232,7 @@ class App {
     const height = this.canvas.height;
     const aspect = width / height;
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setFocalLength(this.params.focalLength);
   }
 
   initGUI() {
@@ -114,10 +241,7 @@ class App {
     const sky = this.skybox;
 
     // Initialize local params from skybox defaults
-    // Initialize local params from skybox defaults
-    // REMOVED: Do not overwrite this.params from sky.sunDirection (Zenith)
-    // const currentDir = sky.sunDirection;
-    // this.params.sunTheta = ...
+
 
     const updateSun = () => {
       const theta = this.params.sunTheta;
@@ -128,29 +252,165 @@ class App {
       sky.setSunPosition([x, y, z]);
     };
 
+    // Sun UI Proxy
+    this.sunUI = {
+      azimuth: (this.params.sunPhi * 180.0 / Math.PI) % 360.0,
+      height: Math.cos(this.params.sunTheta)
+    };
+    if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+
     const sunFolder = gui.addFolder('Sun');
-    // Helper for "Sun Height" cosine slider like C++
-    const sunHeightParam = { height: Math.cos(this.params.sunTheta) };
-    sunFolder.add(sunHeightParam, 'height', -0.2, 1.0).name('Height (Cos)').onChange(v => {
+
+    sunFolder.add(this.sunUI, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(v => {
+      this.params.sunPhi = v * (Math.PI / 180.0);
+      updateSun();
+    });
+
+    sunFolder.add(this.sunUI, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(v => {
       this.params.sunTheta = Math.acos(v);
       updateSun();
     });
-    sunFolder.add(this.params, 'sunPhi', 0.0, Math.PI * 2).name('Azimuth').onChange(updateSun);
-    // Updated: Controls params.sunIntensity and triggers updateSunIntensity
-    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).onChange(v => this.updateSunIntensity());
 
-    const sunDisk = sunFolder.addFolder('Disk');
-    // We need local proxy for sunRadius due to conversion
-    const diskParams = {
+    sunFolder.add(this.params, 'sunIntensity', 0.0, 500000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+
+
+
+
+    const moonFolder = gui.addFolder('Moon');
+    this.mParams = {
+      enabled: true,
+      azimuth: 180.0,
+      height: Math.cos(45.0 * Math.PI / 180.0), // Default 45 degrees elevation -> cos(45) ~ 0.707
       radius: 1.2,
-      enabled: true // Enable sun disk
+      intensity: 6.0
+    };
+
+    const updateMoon = () => {
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+    };
+
+    // Initial Moon Sync
+    updateMoon();
+    sky.setMoonEnabled(this.mParams.enabled);
+    sky.setMoonRadius(this.mParams.radius);
+    sky.setMoonIntensity(this.mParams.intensity);
+
+    moonFolder.add(this.mParams, 'enabled').name('Enabled').onChange(v => sky.setMoonEnabled(v));
+    moonFolder.add(this.mParams, 'azimuth', 0.0, 360.0, 0.1).name('Azimuth').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'height', -0.2, 1.0).name('Height (Cos)').listen().onChange(updateMoon);
+    moonFolder.add(this.mParams, 'intensity', 0.0, 1000.0).name('Intensity').onChange(v => this.updateSunIntensity());
+    moonFolder.add(this.mParams, 'radius', 0.1, 5.0).name('Radius').onChange(v => sky.setMoonRadius(v));
+    moonFolder.close();
+
+    const mwFolder = gui.addFolder('Milky Way');
+
+    const updateMW = () => {
+      sky.setMilkyWayEnabled(this.mwParams.enabled);
+      sky.setMilkyWayControl(this.mwParams.intensity, this.mwParams.saturation, this.mwParams.blackPoint);
+
+      // Calculate Rotation
+      // V_gal = Rot_Eq_to_Gal * Rot_World_to_Eq * V_world
+
+      // World: Y=Up, X=East, Z=South (Filament Camera Convention is different!)
+      // In Filament Camera: -Z is Forward.
+      // Skybox V direction is World Space direction.
+      // Let's assume standard Horizontal Coordinates:
+      // Y = Zenith.
+      // Z = North? Or South?
+      // Usually Z is South in RH Y-up.
+
+      // LST (Local Sidereal Time) converts Hour Angle to RA.
+      // LST in Radians.
+      const LST = this.mwParams.siderealTime * (Math.PI / 12.0); // Hours to Rad
+      const Lat = this.mwParams.latitude * (Math.PI / 180.0);
+
+      // Rotation World (Horizontal) -> Equatorial
+      // 1. Rotate around X by -(90 - Lat) to align Equatorial Plane.
+      // 2. Rotate around Y (Polar Axis) by -LST.
+
+      // Mat3 Identity
+      const rot = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // Rotate Z by LST (Earth Rotation).
+      // Actually, transformation from Horizontal (Az, Alt) to Equatorial (HA, Dec):
+      // sin(Dec) = sin(Alt)sin(Lat) - cos(Alt)cos(Lat)cos(Az)
+      // ...
+      // Let's construct matrix directly.
+      // WorldToEq:
+      // Rotate X by (Lat - 90 deg) -> brings Pole to Zenith.
+      // Rotate Y by -LST (or Z?)
+
+      // Filament Space:
+      // +Y = Up
+      // Let's match typical skybox conventions.
+
+      // Rot_World_to_Eq = Rot_Z_LST * Rot_X_Lat
+      // But we need to use Filament matrix ops which are column major.
+
+      // Let's use simple rotations:
+      // 1. Tilt Pole: Rotate X by (Lat - 90).
+      // 2. Spin Earth: Rotate Y by LST.
+
+      // Let's iterate until it looks right visually or trust the math.
+      // Rot_World_To_Equatorial:
+      // R_z(-LST) * R_x(Lat - 90)?
+
+      // Let's build it from scratch in JS using helper.
+      // Start Identity.
+      // Rotate X (Latitude Tilt).
+      // Rotate Y (Sidereal Spin).
+      // Note: rotate functions modify in place.
+
+      const mWorldToEq = [1, 0, 0, 0, 1, 0, 0, 0, 1];
+
+      // 1. Tilt for Latitude (Align Celestial Pole)
+      // At Lat 90 (North Pole), Zenith is Pole. No tilt needed if Y is Pole?
+      // No, Y is Zenith. Pole is Y.
+      // At Lat 0 (Equator), Pole is at Horizon (Z?).
+      // So we rotate X by (Lat - 90).
+      rotateX(mWorldToEq, Lat - Math.PI / 2);
+
+      // 2. Spin for Time (LST)
+      // Rotate around new Pole (Y) by LST.
+      rotateY(mWorldToEq, LST);
+
+      // Combine with Gal Transform
+      // Rot = MAT_EQ_TO_GAL * mWorldToEq
+      const finalRot = multiplyMat3(MAT_EQ_TO_GAL, mWorldToEq);
+
+      sky.setMilkyWayRotation(finalRot);
+    };
+
+    mwFolder.add(this.mwParams, 'enabled').name('Enabled').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'intensity', 0.0, 100.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'saturation', 0.0, 2.0).onChange(updateMW);
+    mwFolder.add(this.mwParams, 'blackPoint', 0.0, 0.5).name('Black Point').onChange(updateMW);
+    mwFolder.add(this.mwParams, 'siderealTime', 0.0, 24.0).name('Sidereal Time').listen().onChange(updateMW);
+    mwFolder.add(this.mwParams, 'latitude', -90.0, 90.0).name('Latitude').onChange(updateMW);
+    mwFolder.close();
+
+    // Initial MW Update
+    updateMW();
+
+    this.updateMW = updateMW; // Export for sync
+
+    // We need local proxy for sunRadius due to conversion
+    this.diskParams = {
+      radius: 1.2
     };
     sky.setSunDiskEnabled(true);
     sky.setSunRadius(1.2);
-    sunDisk.add(diskParams, 'enabled').onChange(v => sky.setSunDiskEnabled(v));
-    sunDisk.add(diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
-    sunDisk.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
-    sunDisk.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
+    sunFolder.add(this.diskParams, 'radius', 0.0, 5.0).onChange(v => sky.setSunRadius(v));
+    sunFolder.add(sky.sunHalo, 1, 0.0, 2.0).name('Limb Darkening').onChange(v => sky.setSunLimbDarkening(v));
+    sunFolder.add(sky.sunHalo, 2, 0.0, 100.0).name('Intensity Boost').onChange(v => sky.setSunDiskIntensity(v));
 
     const atmFolder = gui.addFolder('Atmosphere');
     atmFolder.add(sky, 'turbidity', 1.0, 10.0).onChange(v => sky.setTurbidity(v));
@@ -161,30 +421,8 @@ class App {
     atmFolder.add(sky, 'ozone', 0.0, 1.0).onChange(v => sky.setOzone(v));
     atmFolder.add(sky, 'mieG', 0.0, 0.999).onChange(v => sky.setMieG(v));
 
-    const artFolder = gui.addFolder('Artistic');
-    // Set Horizon Glow default to 1.0
-    sky.setHorizonGlow(1.0);
-    sky.msFactors[2] = 1.0;
-    // Set Contrast default to 0.85
-    sky.setContrast(0.85);
-
-    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
-    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
-    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
-    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
-
-    artFolder.addColor(sky, 'nightColor').onChange(v => sky.setNightColor(v));
-
-    const shmFolder = artFolder.addFolder('Shimmer');
-    // Set Shimmer Strength default to 0.0
-    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
-
-    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
-    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
-
     const cloudFolder = gui.addFolder('Clouds');
-    const cParams = {
+    this.cParams = {
       volumetrics: sky.cloudControl2[1] > 0.5,
       coverage: 0.4,
       density: 0.02,
@@ -193,19 +431,19 @@ class App {
       evolution: 0.02
     };
     // Apply Cloud Defaults
-    sky.setCloudControl(0.4, 0.02, cParams.height, 50.0);
+    sky.setCloudControl(0.4, 0.02, this.cParams.height, 50.0);
     sky.setCloudShapeEvolution(0.02);
 
-    cloudFolder.add(cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
-    cloudFolder.add(cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, cParams.density, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(cParams.coverage, v, cParams.height, cParams.speed));
-    cloudFolder.add(cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, v, cParams.speed));
+    cloudFolder.add(this.cParams, 'volumetrics').onChange(v => sky.setCloudVolumetricLighting(v));
+    cloudFolder.add(this.cParams, 'coverage', 0.0, 1.0).onChange(v => sky.setCloudControl(v, this.cParams.density, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'density', 0.0, 1.0).onChange(v => sky.setCloudControl(this.cParams.coverage, v, this.cParams.height, this.cParams.speed));
+    cloudFolder.add(this.cParams, 'height', 2000.0, 20000.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, v, this.cParams.speed));
     // Reverse speed calc: w = speed * (0.05 / 72.0)
-    cloudFolder.add(cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(cParams.coverage, cParams.density, cParams.height, v));
-    cloudFolder.add(cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
+    cloudFolder.add(this.cParams, 'speed', 0.0, 200.0).onChange(v => sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, v));
+    cloudFolder.add(this.cParams, 'evolution', 0.0, 2.0).onChange(v => sky.setCloudShapeEvolution(v));
 
     const waterFolder = gui.addFolder('Water');
-    const wParams = {
+    this.wParams = {
       derivativeTrick: true,
       strength: 50.0,
       speed: 1.0,
@@ -215,67 +453,436 @@ class App {
     sky.setWaterControl(50.0, 1.0, 1.0, 4.0); // 1.0 = Derivative Trick On, 4 octaves
 
     const updateWater = () => {
-      sky.setWaterControl(wParams.strength, wParams.speed, wParams.derivativeTrick ? 1.0 : 0.0, wParams.octaves);
+      sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
     };
 
-    waterFolder.add(wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
-    waterFolder.add(wParams, 'strength', 10.0, 100.0).onChange(updateWater);
-    waterFolder.add(wParams, 'speed', 0.0, 5.0).onChange(updateWater);
-    waterFolder.add(wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
+    waterFolder.add(this.wParams, 'derivativeTrick').name('Derivative Trick').onChange(updateWater);
+    waterFolder.add(this.wParams, 'strength', 10.0, 100.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'speed', 0.0, 5.0).onChange(updateWater);
+    waterFolder.add(this.wParams, 'octaves', 1, 8, 1).name('Octaves').onChange(updateWater);
     waterFolder.close();
 
     const starFolder = gui.addFolder('Stars');
-    const sParams = {
+    this.sParams = {
       enabled: true,
-      density: 1.0
+      density: 0.001,
+      intensity: 0.0 // 2^0 = 1.0
     };
-    // Initialize defaults (Density 1.0, Enabled True)
-    sky.setStarControl(1.0, true);
+    // Initialize defaults (Density 0.001, Enabled True)
+    sky.setStarControl(0.001, true);
+    sky.setStarIntensity(Math.pow(2.0, 0.0));
 
     const updateStars = () => {
-      sky.setStarControl(sParams.density, sParams.enabled);
+      sky.setStarControl(this.sParams.density, this.sParams.enabled);
+      sky.setStarIntensity(Math.pow(2.0, this.sParams.intensity));
     };
 
-    starFolder.add(sParams, 'enabled').name('Enabled').onChange(updateStars);
-    starFolder.add(sParams, 'density', 0.0, 1.0).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'enabled').name('Enabled').onChange(updateStars);
+    starFolder.add(this.sParams, 'density', 0.0, 0.01, 0.0001).name('Density').onChange(updateStars);
+    starFolder.add(this.sParams, 'intensity', 0.0, 24.0).name('Intensity (Exp)').onChange(updateStars);
     starFolder.close();
+    this.updateStars = updateStars;
+
+    const artFolder = gui.addFolder('Artistic');
+    // Set Horizon Glow default to 0.0
+    sky.setHorizonGlow(0.0);
+    sky.msFactors[2] = 0.0;
+    // Set Contrast default to 1.0
+    sky.setContrast(1.0);
+
+    artFolder.add(sky.msFactors, 0, 0.0, 2.0).name('MS Rayleigh').onChange(v => sky.setMultiScattering(v, sky.msFactors[1]));
+    artFolder.add(sky.msFactors, 1, 0.0, 2.0).name('MS Mie').onChange(v => sky.setMultiScattering(sky.msFactors[0], v));
+    artFolder.add(sky.msFactors, 2, 0.0, 1.0).name('Horizon Glow').onChange(v => sky.setHorizonGlow(v));
+    artFolder.add(sky, 'contrast', 0.1, 2.0).onChange(v => sky.setContrast(v));
+
+
+
+    const shmFolder = artFolder.addFolder('Shimmer');
+    // Set Shimmer Strength default to 0.0
+    sky.setShimmerControl(0.0, sky.shimmerControl[1], sky.shimmerControl[2]);
+
+    shmFolder.add(sky.shimmerControl, 0, 0.0, 0.1).name('Strength').onChange(v => sky.setShimmerControl(v, sky.shimmerControl[1], sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 1, 1.0, 100.0).name('Frequency').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], v, sky.shimmerControl[2]));
+    shmFolder.add(sky.shimmerControl, 2, 0.01, 0.5).name('Mask Height').onChange(v => sky.setShimmerControl(sky.shimmerControl[0], sky.shimmerControl[1], v));
 
     const camFolder = gui.addFolder('Camera');
     camFolder.add(this.params, 'focalLength', 8.0, 300.0).name('Focal Length').onChange(() => this.updateCameraProjection());
     camFolder.add(this.params, 'aperture', 1.4, 32.0).onChange(() => this.updateCameraExposure());
-    camFolder.add(this.params, 'shutterSpeed', 1.0, 1000.0).onChange(() => this.updateCameraExposure());
+    camFolder.add(this.params, 'shutterSpeed', 0.05, 1000.0).onChange(() => this.updateCameraExposure());
     camFolder.add(this.params, 'iso', 50.0, 3200.0).onChange(() => this.updateCameraExposure());
 
     const bloomFolder = camFolder.addFolder('Bloom');
-    const bParams = {
-      enabled: false,
+    this.bParams = {
+      enabled: true,
       lensFlare: false
     };
 
     const updateBloom = () => {
       this.view.setBloomOptions({
-        enabled: bParams.enabled,
-        lensFlare: bParams.lensFlare
+        enabled: this.bParams.enabled,
+        lensFlare: this.bParams.lensFlare
       });
     };
 
-    bloomFolder.add(bParams, 'enabled').onChange(updateBloom);
-    bloomFolder.add(bParams, 'lensFlare').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'enabled').onChange(updateBloom);
+    bloomFolder.add(this.bParams, 'lensFlare').onChange(updateBloom);
     bloomFolder.close();
 
     // Collapse folders by default
-    sunDisk.close();
+
     atmFolder.close();
     artFolder.close();
     // shmFolder is inside artFolder, so it's hidden, but we can close it too if we want
     shmFolder.close();
     cloudFolder.close();
-    // camFolder left open? User didn't specify, but "Artistic, shimmer and clouds" + "Disk, Atmosphere" were requested.
-    // So Camera might stay open or close. Let's keep Camera open for now as it wasn't listed.
+    // camFolder left open by default for convenience.
+
 
     // Initial sync
     updateSun();
     this.updateCameraExposure(); // This will trigger updateSunIntensity too
+    updateBloom();
+
+    // Check URL for config
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.has('config')) {
+      try {
+        const state = JSON.parse(atob(urlParams.get('config')));
+        this.applyURLState(state);
+        // Update GUI
+        gui.controllers.forEach(c => c.updateDisplay());
+        // Recursive update for folders
+        gui.folders.forEach(f => {
+          f.controllers.forEach(c => c.updateDisplay());
+          // And sub-folders if any (Shimmer/Bloom)
+          f.folders.forEach(sf => sf.controllers.forEach(sc => sc.updateDisplay()));
+        });
+      } catch (e) {
+        console.error("Failed to load config:", e);
+      }
+    }
+
+    const syncFolder = gui.addFolder('Real-Time Sync');
+    this.syncParams = {
+      enabled: false,
+      lat: 0.0,
+      lng: 0.0,
+      status: 'Disabled'
+    };
+
+    const updateSync = () => {
+      if (this.syncParams.enabled) {
+        if (navigator.geolocation) {
+          this.syncParams.status = "Locating...";
+          navigator.geolocation.getCurrentPosition(
+            (pos) => {
+              this.syncParams.lat = pos.coords.latitude;
+              this.syncParams.lng = pos.coords.longitude;
+              this.syncParams.status = "Active";
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            },
+            (err) => {
+              console.error(err);
+              this.syncParams.status = "Error (See Console)";
+              this.syncParams.enabled = false;
+              syncFolder.controllers.forEach(c => c.updateDisplay());
+            }
+          );
+        } else {
+          this.syncParams.status = "Not Supported";
+        }
+      } else {
+        this.syncParams.status = "Disabled";
+      }
+      syncFolder.controllers.forEach(c => c.updateDisplay());
+    };
+
+    syncFolder.add(this.syncParams, 'enabled').name('Enable Sync').onChange(updateSync);
+    syncFolder.add(this.syncParams, 'status').name('Status').disable().listen();
+
+    this.syncFolder = syncFolder;
+
+    const shareParams = {
+      copyUrl: () => {
+        const state = this.getURLState();
+        const str = btoa(JSON.stringify(state));
+        const url = `${window.location.origin}${window.location.pathname}?config=${str}`;
+        navigator.clipboard.writeText(url).then(() => {
+          alert("Configuration URL copied to clipboard!");
+        }).catch(err => {
+          console.error('Could not copy text: ', err);
+          prompt("Copy this URL:", url);
+        });
+      }
+    };
+    gui.add(shareParams, 'copyUrl').name('Share Configuration');
+
+  }
+
+  updateRealTimeSync() {
+    if (!this.syncParams || !this.syncParams.enabled || !window.SunCalc) return;
+
+    const now = new Date();
+    const lat = this.syncParams.lat;
+    const lng = this.syncParams.lng;
+
+    // Sun
+    const sunPos = window.SunCalc.getPosition(now, lat, lng);
+    // Azimuth: South=0, West=PI/2.
+    // Skybox Phi: +X=0, +Z=PI/2.
+    // If +Z is South:
+    // SunAz 0 (South) -> Skybox PI/2 (+Z).
+    // SunAz PI/2 (West) -> Skybox PI (-X).
+    // So Phi = Az + PI/2.
+    const sunPhi = sunPos.azimuth + Math.PI / 2;
+    // Altitude: 0=Horizon, PI/2=Zenith.
+    // Skybox Theta: 0=Zenith, PI/2=Horizon.
+    const sunTheta = Math.PI / 2 - sunPos.altitude;
+
+    this.params.sunPhi = sunPhi;
+    this.params.sunTheta = sunTheta;
+
+    // Moon
+    const moonPos = window.SunCalc.getMoonPosition(now, lat, lng);
+    const moonPhi = moonPos.azimuth + Math.PI / 2;
+    const moonTheta = Math.PI / 2 - moonPos.altitude;
+
+    this.mParams.azimuth = (moonPhi * 180.0 / Math.PI) % 360.0;
+    this.mParams.height = Math.cos(moonTheta);
+
+    // Milky Way Sync
+    const gmst = getGMST(now);
+    const lst = (gmst + lng / 15.0 + 24.0) % 24.0;
+    this.mwParams.siderealTime = lst;
+    this.mwParams.latitude = lat;
+    if (this.updateMW) this.updateMW();
+
+    // Update Skybox
+    const sky = this.skybox;
+
+    // Update Sun Vector
+    const sx = Math.sin(sunTheta) * Math.cos(sunPhi);
+    const sy = Math.cos(sunTheta);
+    const sz = Math.sin(sunTheta) * Math.sin(sunPhi);
+    sky.setSunPosition([sx, sy, sz]);
+
+    // Update Moon Vector
+    const mx = Math.sin(moonTheta) * Math.cos(moonPhi);
+    const my = Math.cos(moonTheta);
+    const mz = Math.sin(moonTheta) * Math.sin(moonPhi);
+    sky.setMoonPosition([mx, my, mz]);
+
+    // Update UI Proxies
+    if (this.sunUI) {
+      this.sunUI.azimuth = (sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+      this.sunUI.height = Math.cos(sunTheta);
+    }
+  }
+
+  getURLState() {
+
+    // Update Camera LookAt
+    // Serialize current state (Minified)
+    // Mapping:
+    // p: params (Camera) -> a:aperture, ss:shutterSpeed, i:iso, st:sunTheta, sp:sunPhi, fl:focalLength, si:sunIntensity
+    // c: cParams (Clouds) -> v:volumetrics, co:coverage, d:density, h:height, s:speed, e:evolution
+    // w: wParams (Water) -> dt:derivativeTrick, st:strength, s:speed, o:octaves
+    // s: sParams (Stars) -> e:enabled, d:density
+    // b: bParams (Bloom) -> e:enabled, lf:lensFlare
+    // k: sky (Skybox) -> t:turbidity, r:rayleigh, mc:mieCoefficient, mg:mieG, o:ozone, ms:msFactors, co:contrast, nc:nightColor, sh:shimmerControl, hl:sunHalo
+
+    const p = this.params;
+    const c = this.cParams;
+    const w = this.wParams;
+    const s = this.sParams;
+    const b = this.bParams;
+    const m = this.mParams;
+    const mw = this.mwParams;
+    const sk = this.skybox;
+
+    return {
+      p: { a: p.aperture, ss: p.shutterSpeed, i: p.iso, st: p.sunTheta, sp: p.sunPhi, fl: p.focalLength, si: p.sunIntensity },
+      c: { v: c.volumetrics, co: c.coverage, d: c.density, h: c.height, s: c.speed, e: c.evolution },
+      w: { dt: w.derivativeTrick, st: w.strength, s: w.speed, o: w.octaves },
+      s: { e: s.enabled, d: s.density, i: s.intensity },
+      mw: { e: mw.enabled, i: mw.intensity, s: mw.saturation, bp: mw.blackPoint, st: mw.siderealTime, l: mw.latitude },
+      b: { e: b.enabled, lf: b.lensFlare },
+      m: { e: m.enabled, az: m.azimuth, h: m.height, r: m.radius, i: m.intensity },
+      cm: { t: this.camState.theta, p: this.camState.phi },
+      k: {
+        t: sk.turbidity,
+        r: sk.rayleigh,
+        mc: sk.mieCoefficient,
+        mg: sk.mieG,
+        o: sk.ozone,
+        ms: [...sk.msFactors],
+        co: sk.contrast,
+        nc: [...sk.nightColor],
+        sh: [...sk.shimmerControl],
+        hl: [...sk.sunHalo]
+      }
+    };
+
+  }
+
+  applyURLState(state) {
+    const p = state.p;
+    const c = state.c;
+    const w = state.w;
+    const s = state.s;
+    const mw = state.mw;
+    const b = state.b;
+    const m = state.m;
+    const k = state.k;
+    const cm = state.cm;
+
+    if (p) {
+      if (p.a !== undefined) this.params.aperture = p.a;
+      if (p.ss !== undefined) this.params.shutterSpeed = p.ss;
+      if (p.i !== undefined) this.params.iso = p.i;
+      if (p.st !== undefined) this.params.sunTheta = p.st;
+      if (p.sp !== undefined) this.params.sunPhi = p.sp;
+      if (p.fl !== undefined) this.params.focalLength = p.fl;
+      if (p.si !== undefined) this.params.sunIntensity = p.si;
+    }
+
+    if (c) {
+      if (c.v !== undefined) this.cParams.volumetrics = c.v;
+      if (c.co !== undefined) this.cParams.coverage = c.co;
+      if (c.d !== undefined) this.cParams.density = c.d;
+      if (c.h !== undefined) this.cParams.height = c.h;
+      if (c.s !== undefined) this.cParams.speed = c.s;
+      if (c.e !== undefined) this.cParams.evolution = c.e;
+    }
+
+    if (w) {
+      if (w.dt !== undefined) this.wParams.derivativeTrick = w.dt;
+      if (w.st !== undefined) this.wParams.strength = w.st;
+      if (w.s !== undefined) this.wParams.speed = w.s;
+      if (w.o !== undefined) this.wParams.octaves = w.o;
+    }
+
+    if (s) {
+      if (s.e !== undefined) this.sParams.enabled = s.e;
+      if (s.d !== undefined) this.sParams.density = s.d;
+      if (s.i !== undefined) this.sParams.intensity = s.i;
+      if (this.updateStars) this.updateStars();
+    }
+
+    if (mw) {
+      if (mw.e !== undefined) this.mwParams.enabled = mw.e;
+      if (mw.i !== undefined) this.mwParams.intensity = mw.i;
+      if (mw.s !== undefined) this.mwParams.saturation = mw.s;
+      if (mw.bp !== undefined) this.mwParams.blackPoint = mw.bp;
+      if (mw.st !== undefined) this.mwParams.siderealTime = mw.st;
+      if (mw.l !== undefined) this.mwParams.latitude = mw.l;
+      if (this.updateMW) this.updateMW();
+    }
+
+    if (b) {
+      if (b.e !== undefined) this.bParams.enabled = b.e;
+      if (b.lf !== undefined) this.bParams.lensFlare = b.lf;
+    }
+
+    const sky = this.skybox;
+    if (k) {
+      if (k.t !== undefined) sky.setTurbidity(k.t);
+      if (k.r !== undefined) sky.setRayleigh(k.r);
+      if (k.mc !== undefined) sky.setMieCoefficient(k.mc);
+      if (k.mg !== undefined) sky.setMieG(k.mg);
+      if (k.o !== undefined) sky.setOzone(k.o);
+
+      if (k.ms) { sky.setMultiScattering(k.ms[0], k.ms[1]); sky.setHorizonGlow(k.ms[2]); }
+      if (k.co !== undefined) sky.setContrast(k.co);
+      if (k.nc) sky.setNightColor(k.nc);
+      if (k.sh) sky.setShimmerControl(k.sh[0], k.sh[1], k.sh[2]);
+
+      // Sun Halo
+      const savedHalo = k.hl;
+      if (savedHalo && savedHalo.length === 4) {
+        sky.sunHalo[0] = savedHalo[0];
+        sky.sunHalo[1] = savedHalo[1];
+        sky.sunHalo[2] = savedHalo[2];
+        sky.sunHalo[3] = savedHalo[3];
+
+        // Update derived UI params for Sun Disk
+        const rad = Math.acos(Math.max(-1.0, Math.min(1.0, savedHalo[0])));
+        this.diskParams.radius = rad * (180.0 / Math.PI);
+        this.diskParams.enabled = savedHalo[3] > 0.5;
+      }
+
+      sky.updateCoefficients();
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    // Update derived Sun UI
+    if (this.sunUI) {
+      this.sunUI.height = Math.cos(this.params.sunTheta);
+      this.sunUI.azimuth = (this.params.sunPhi * 180.0 / Math.PI) % 360.0;
+      if (this.sunUI.azimuth < 0) this.sunUI.azimuth += 360.0;
+    }
+
+    // Apply Local Params via Setters
+    sky.setCloudControl(this.cParams.coverage, this.cParams.density, this.cParams.height, this.cParams.speed);
+    sky.setCloudVolumetricLighting(this.cParams.volumetrics);
+    sky.setCloudShapeEvolution(this.cParams.evolution);
+
+    sky.setWaterControl(this.wParams.strength, this.wParams.speed, this.wParams.derivativeTrick ? 1.0 : 0.0, this.wParams.octaves);
+    sky.setStarControl(this.sParams.density, this.sParams.enabled);
+
+    if (m) {
+      if (m.e !== undefined) this.mParams.enabled = m.e;
+      if (m.az !== undefined) this.mParams.azimuth = m.az;
+      // Compat: if 'el' exists (old link) convert to 'h'
+      if (m.h !== undefined) {
+        this.mParams.height = m.h;
+      } else if (m.el !== undefined) {
+        // Convert elevation degrees to height cos
+        this.mParams.height = Math.cos(m.el * Math.PI / 180.0);
+      }
+      if (m.r !== undefined) this.mParams.radius = m.r;
+      if (m.i !== undefined) this.mParams.intensity = m.i;
+
+      // Sync Moon
+      const az = this.mParams.azimuth * (Math.PI / 180.0);
+      const theta = Math.acos(this.mParams.height);
+      const phi = az;
+      const x = Math.sin(theta) * Math.cos(phi);
+      const y = Math.cos(theta);
+      const z = Math.sin(theta) * Math.sin(phi);
+
+      sky.setMoonPosition([x, y, z]);
+      sky.setMoonEnabled(this.mParams.enabled);
+      sky.setMoonRadius(this.mParams.radius);
+      sky.setMoonIntensity(this.mParams.intensity);
+    }
+
+    if (cm) {
+      if (cm.t !== undefined) this.camState.theta = cm.t;
+      if (cm.p !== undefined) this.camState.phi = cm.p;
+    }
+
+    this.view.setBloomOptions({
+      enabled: this.bParams.enabled,
+      lensFlare: this.bParams.lensFlare
+    });
+
+    // Update Sun Position from Params
+    const theta = this.params.sunTheta;
+    const phi = this.params.sunPhi;
+    const x = Math.sin(theta) * Math.cos(phi);
+    const y = Math.cos(theta);
+    const z = Math.sin(theta) * Math.sin(phi);
+    sky.setSunPosition([x, y, z]);
+
+    // Update Camera Projection (Focal Length) and Exposure (Aperture/Shutter/ISO)
+    this.updateCameraProjection();
+    this.updateCameraExposure();
   }
 
   initControls() {
@@ -305,10 +912,41 @@ class App {
       this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
     });
 
+    // Touch support
+    this.canvas.addEventListener('touchstart', e => {
+      if (e.touches.length > 0) {
+        e.preventDefault(); // Prevent scroll/long-press
+        this.camState.dragging = true;
+        this.camState.lastX = e.touches[0].clientX;
+        this.camState.lastY = e.touches[0].clientY;
+      }
+    }, { passive: false });
+
+    window.addEventListener('touchend', () => {
+      this.camState.dragging = false;
+    });
+
+    window.addEventListener('touchmove', e => {
+      if (!this.camState.dragging || e.touches.length === 0) return;
+      e.preventDefault(); // Prevent scrolling
+      const x = e.touches[0].clientX;
+      const y = e.touches[0].clientY;
+      const dx = x - this.camState.lastX;
+      const dy = y - this.camState.lastY;
+      this.camState.lastX = x;
+      this.camState.lastY = y;
+
+      const sensitivity = 0.005;
+      this.camState.theta -= dx * sensitivity;
+      this.camState.phi += dy * sensitivity;
+      this.camState.phi = Math.max(-Math.PI / 2 + 0.01, Math.min(Math.PI / 2 - 0.01, this.camState.phi));
+    }, { passive: false });
+
 
   }
 
   render() {
+    this.updateRealTimeSync();
     // Update Camera LookAt
     const r = 1.0;
     const theta = this.camState.theta;
@@ -341,5 +979,6 @@ class App {
     const aspect = width / height;
     // near=0.1, far=5000.0
     this.camera.setLensProjection(this.params.focalLength, aspect, 0.1, 5000.0);
+    if (this.skybox) this.skybox.setResolution(height);
   }
 }

docs/wip/sky/process_milkyway.py

@@ -0,0 +1,61 @@
+
+import os
+import urllib.request
+import ssl
+from PIL import Image
+import argparse
+
+# URL of the Milky Way texture (Gaia EDR3) from ESA
+# Low Res PNG (2.71 MB) is sufficient for our 1024x512 target
+URL = "https://www.esa.int/var/esa/storage/images/esa_multimedia/images/2020/12/the_colour_of_the_sky_from_gaia_s_early_data_release_3/22358049-1-eng-GB/The_colour_of_the_sky_from_Gaia_s_Early_Data_Release_3.png"
+OUTPUT_DIR = "assets"
+OUTPUT_FILENAME = "milkyway.png"
+TARGET_WIDTH = 1024
+TARGET_HEIGHT = 512
+
+def main():
+    if not os.path.exists(OUTPUT_DIR):
+        os.makedirs(OUTPUT_DIR)
+
+    output_path = os.path.join(OUTPUT_DIR, OUTPUT_FILENAME)
+    temp_path = os.path.join(OUTPUT_DIR, "temp_milkyway.png")
+
+    print(f"Downloading Milky Way texture from {URL}...")
+    
+    # Bypass SSL verification globally
+    if hasattr(ssl, '_create_unverified_context'):
+        ssl._create_default_https_context = ssl._create_unverified_context
+
+    try:
+        req = urllib.request.Request(URL, headers={'User-Agent': 'Mozilla/5.0'})
+        with urllib.request.urlopen(req) as response, open(temp_path, 'wb') as out_file:
+            out_file.write(response.read())
+    except Exception as e:
+        print(f"Failed to download: {e}")
+        return
+
+    if not os.path.exists(temp_path):
+        print("Error: Download failed.")
+        return
+
+    print("Processing image...")
+    with Image.open(temp_path) as img:
+        # Convert to RGB (remove alpha if present, though this is likely opaque)
+        img = img.convert("RGB")
+        
+        # Resize to user requested dimensions
+        print(f"Resizing to {TARGET_WIDTH}x{TARGET_HEIGHT}...")
+        img = img.resize((TARGET_WIDTH, TARGET_HEIGHT), Image.Resampling.LANCZOS)
+        
+        # Save
+        print(f"Saving to {output_path}...")
+        img.save(output_path, "PNG")
+
+    # Cleanup
+    if os.path.exists(temp_path):
+        os.remove(temp_path)
+
+    print("Done!")
+
+if __name__ == "__main__":
+    main()

docs/wip/sky/tools/build_material.sh

@@ -1,10 +1,10 @@
 # Result: /Users/mathias/sources/git/filament/out/cmake-release/tools/matc/matc
-MATC="../../../../out/cmake-release/tools/matc/matc"
+MATC="../../../../../out/cmake-release/tools/matc/matc"
 
 # Navigate to script directory to ensure relative paths work
 cd "$(dirname "$0")"
 
 set -e
 
-$MATC -a opengl -p mobile -o assets/simulated_skybox.filamat simulated_skybox.mat
+$MATC -a opengl -p mobile -o ../assets/simulated_skybox.filamat ../simulated_skybox.mat
 echo "Material recompiled to assets/simulated_skybox.filamat"

docs/wip/sky/tools/generate_moon_assets.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -e
+
+# Default size
+SIZE=${1:-256}
+OUTPUT_COLOR="../assets/moon_disk.png"
+OUTPUT_NORMAL="../assets/moon_normal.png"
+
+# Navigate to script directory
+cd "$(dirname "$0")"
+
+# Check dependencies
+if ! python3 -c "import numpy, PIL" 2>/dev/null; then
+    echo "Installing dependencies (numpy, Pillow)..."
+    pip3 install numpy Pillow
+fi
+
+echo "Generating Moon Asset (Size: ${SIZE}x${SIZE})..."
+python3 process_moon.py --size $SIZE --supersample 4 --blur 1.0 --output-color $OUTPUT_COLOR --output-normal $OUTPUT_NORMAL
+
+echo "Generated $OUTPUT_COLOR and $OUTPUT_NORMAL"

docs/wip/sky/tools/process_moon.py

@@ -0,0 +1,249 @@
+import argparse
+import urllib.request
+import os
+import sys
+import math
+import ssl
+from PIL import Image
+
+# Ensure numpy is available
+try:
+    import numpy as np
+except ImportError:
+    print("Error: numpy is required. Please install it with: pip install numpy")
+    sys.exit(1)
+
+# Default URLs
+COLOR_URL = "https://svs.gsfc.nasa.gov/vis/a000000/a004700/a004720/lroc_color_2k.jpg"
+DISP_URL = "https://svs.gsfc.nasa.gov/vis/a000000/a004700/a004720/ldem_4.tif"
+
+SRC_COLOR_FILENAME = "lroc_color_2k.jpg"
+SRC_DISP_FILENAME = "ldem_4.tif"
+
+def download_file(url, filename):
+    if os.path.exists(filename):
+        print(f"File {filename} already exists. Skipping download.")
+        return
+
+    print(f"Downloading {url} to {filename}...")
+    # Create unverified context to avoid potential SSL cert issues
+    context = ssl._create_unverified_context()
+    try:
+        with urllib.request.urlopen(url, context=context) as response, open(filename, 'wb') as out_file:
+            data = response.read()
+            out_file.write(data)
+        print(f"Download of {filename} complete.")
+    except Exception as e:
+        print(f"Error downloading file {filename}: {e}")
+        # Don't exit hard if it's just one file, maybe?
+        # But for this script, we likely need it.
+        sys.exit(1)
+
+def equirectangular_to_orthographic(src_img, size, mode=None):
+    """
+    Reprojects an equirectangular image to an orthographic projection (sphere view).
+    src_img: PIL Image (Equirectangular)
+    size: Output size (width, height) - usually square
+    """
+    print(f"Reprojecting to {size}x{size} Orthographic Disk...")
+    
+    width, height = size, size
+    src_w, src_h = src_img.size
+    
+    # Create coordinate grid centered at 0,0 (-1 to 1)
+    y, x = np.mgrid[size/2:-size/2:-1, -size/2:size/2] # Note: y goes high to low
+    
+    # Normalize to -1..1
+    x = x / (size / 2)
+    y = y / (size / 2)
+    
+    # Mask for points outside the circle
+    r2 = x*x + y*y
+    mask = r2 <= 1.0
+    
+    # Calculate sphere coordinates (z > 0 for front face)
+    z = np.zeros_like(r2)
+    z[mask] = np.sqrt(1.0 - r2[mask])
+    
+    # Vector P = (x, y, z) on unit sphere
+    # Lat = asin(y)
+    # Lon = atan2(x, z) 
+    
+    # Apply mask to avoid invalid calculations
+    lat = np.arcsin(y * mask)
+    lon = np.arctan2(x * mask, z * mask)
+    
+    # Map to UV [0, 1]
+    u = (lon / (2 * math.pi)) + 0.5
+    v = (lat / math.pi) + 0.5
+    
+    # Map to Source Pixels
+    u = np.clip(u, 0, 1)
+    v = np.clip(v, 0, 1)
+    
+    src_x = (u * (src_w - 1)).astype(np.int32)
+    src_y = ((1.0 - v) * (src_h - 1)).astype(np.int32) # Flip V for image coords
+    
+    # Sample pixels
+    src_array = np.array(src_img)
+    
+    # Handle dimensions
+    if len(src_array.shape) == 2:
+        # Grayscale / Single channel
+        out_channels = 1
+        src_array = src_array[:, :, np.newaxis] # Expand for consistent indexing
+    else:
+        out_channels = src_array.shape[2]
+        
+    out_array = np.zeros((height, width, out_channels), dtype=src_array.dtype)
+    
+    # Advanced indexing
+    valid_y, valid_x = np.where(mask)
+    
+    # Extract coordinates for valid pixels
+    sx = src_x[valid_y, valid_x]
+    sy = src_y[valid_y, valid_x]
+    
+    out_array[valid_y, valid_x] = src_array[sy, sx]
+    
+    # Squeeze if single channel
+    if out_channels == 1:
+        out_array = out_array.squeeze(axis=2)
+        
+    return Image.fromarray(out_array, mode or src_img.mode)
+
+def compute_normal_map(height_img, scale=1.0, blur_radius=0.0):
+    print("Computing Normal Map from Height Map...")
+    # Convert to float array
+    h = np.array(height_img).astype(np.float32)
+
+    # Apply Blur if requested
+    if blur_radius > 0:
+        try:
+            from scipy.ndimage import gaussian_filter
+            print(f"Applying Gaussian Blur (Radius: {blur_radius})...")
+            h = gaussian_filter(h, sigma=blur_radius)
+        except ImportError:
+            print("Warning: scipy not found. Skipping Gaussian Blur.")
+    
+    # Normalize height to 0..1 for consistent gradient scale regardless of input depth
+    h_min, h_max = h.min(), h.max()
+    print(f"Height Map Range: {h_min} to {h_max}")
+    if h_max > h_min:
+        h_norm = (h - h_min) / (h_max - h_min)
+    else:
+        h_norm = h
+    
+    # Gradients
+    dy, dx = np.gradient(h_norm)
+    
+    # Pre-emphasis scale
+    bump_scale = scale 
+    
+    # Normal vector components
+    # Map is Top-Down Y.
+    nx = -dx * bump_scale
+    ny = -dy * bump_scale
+    nz = np.ones_like(nx) 
+    
+    # Mask out normals where r > 0.96 (avoid edge cliff artifacts)
+    rows, cols = h.shape
+    y, x = np.ogrid[:rows, :cols]
+    center_y, center_x = rows/2.0, cols/2.0
+    # max radius is size/2
+    radius_sq = (min(rows, cols) / 2.0)**2
+    dist_sq = (x - center_x)**2 + (y - center_y)**2
+    mask = dist_sq < (radius_sq * 0.96 * 0.96)
+
+    nx[~mask] = 0
+    ny[~mask] = 0
+    nz[~mask] = 1
+    
+    # Normalize
+    len_n = np.sqrt(nx*nx + ny*ny + nz*nz)
+    # Avoid divide by zero
+    len_n[len_n == 0] = 1.0
+    
+    nx /= len_n
+    ny /= len_n
+    nz /= len_n
+    
+    # Pack to 0..255
+    # [-1, 1] -> [0, 255]
+    out_x = ((nx + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    out_y = ((ny + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    out_z = ((nz + 1.0) * 0.5 * 255.0).astype(np.uint8)
+    
+    out_rgb = np.dstack((out_x, out_y, out_z))
+    return Image.fromarray(out_rgb, 'RGB')
+
+def main():
+    parser = argparse.ArgumentParser(description='Process Moon Texture')
+    parser.add_argument('--size', type=int, default=256, help='Output resolution (square)')
+    parser.add_argument('--supersample', type=int, default=2, help='Internal processing resolution multiplier')
+    parser.add_argument('--blur', type=float, default=1.0, help='Gaussian blur radius for height map')
+    parser.add_argument('--bump-scale', type=float, default=60.0, help='Normal map bump scale')
+    parser.add_argument('--output-color', type=str, default='assets/moon_disk.png', help='Output color filename')
+    parser.add_argument('--output-normal', type=str, default='assets/moon_normal.png', help='Output normal filename')
+    parser.add_argument('--skip-download', action='store_true', help='Skip downloading files')
+    
+    args = parser.parse_args()
+    
+    internal_size = args.size * args.supersample
+    
+    # Ensure assets dir exists
+    os.makedirs(os.path.dirname(args.output_color) or '.', exist_ok=True)
+    
+    # 1. Download
+    if not args.skip_download:
+        download_file(COLOR_URL, SRC_COLOR_FILENAME)
+        download_file(DISP_URL, SRC_DISP_FILENAME)
+    
+    # 2. Process Color
+    print(f"Processing Color Map (Internal Size: {internal_size}x{internal_size})...")
+    try:
+        img_color = Image.open(SRC_COLOR_FILENAME).convert('RGB')
+        out_color = equirectangular_to_orthographic(img_color, internal_size)
+        
+        if args.supersample > 1:
+            print(f"Downsampling Color to {args.size}x{args.size}...")
+            out_color = out_color.resize((args.size, args.size), Image.LANCZOS)
+            
+        out_color.save(args.output_color)
+        print(f"Saved {args.output_color}")
+    except Exception as e:
+        print(f"Error processing color: {e}")
+
+    # 3. Process Normal
+    print(f"Processing Displacement Map (Internal Size: {internal_size}x{internal_size})...")
+    try:
+        from PIL import ImageFile
+        ImageFile.LOAD_TRUNCATED_IMAGES = True
+        
+        # Check if file exists
+        if not os.path.exists(SRC_DISP_FILENAME):
+            print(f"Displacement map {SRC_DISP_FILENAME} not found!")
+            return
+
+        img_disp = Image.open(SRC_DISP_FILENAME) 
+        out_disp = equirectangular_to_orthographic(img_disp, internal_size)
+        
+        # Compute Normals
+        out_normal = compute_normal_map(out_disp, scale=args.bump_scale, blur_radius=args.blur)
+        
+        if args.supersample > 1:
+            print(f"Downsampling Normal to {args.size}x{args.size}...")
+            out_normal = out_normal.resize((args.size, args.size), Image.LANCZOS)
+
+        out_normal.save(args.output_normal)
+        print(f"Saved {args.output_normal}")
+        
+    except Exception as e:
+        print(f"Error processing normal: {e}")
+        import traceback
+        traceback.print_exc()
+
+    print("Done.")
+
+if __name__ == "__main__":
+    main()

docs_src/build/duplicates.json

@@ -49,6 +49,9 @@
     "libs/fgviewer/README.md": {
         "dest": "dup/fgviewer.md"
     },
+    "libs/viewer/README.md": {
+        "dest": "dup/viewer.md"
+    },
     "ios/CocoaPods/README.md": {
         "dest": "release/cocoapods.md"
     },