Merge branch 'rc/1.62.2' into release

- Make sure that we don't allocate a VulkanContext on the function
   stack since this was passed erroroneously to other components
   and stored as a pointer
 - Use const& to refer to VulkanContext across components for
   consistency.
 - Remove unused VkPhysicalDeviceProtectedMemoryProperties struct.

.clang-format

@@ -57,7 +57,7 @@ SpaceBeforeInheritanceColon: true
 SpaceBeforeParens: ControlStatements
 SpaceBeforeRangeBasedForLoopColon: false
 SpaceInEmptyParentheses: false
-SpacesBeforeTrailingComments: 0
+SpacesBeforeTrailingComments: 1
 SpacesInAngles: false
 SpacesInCStyleCastParentheses: false
 SpacesInContainerLiterals: false

.github/actions/dep-versions/action.yml

@@ -3,5 +3,5 @@ runs:
   using: "composite"
   steps:
     - name: Set up dependency versions
-      shell: bash    
+      shell: bash
       run: cat ./build/common/versions >> $GITHUB_ENV

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

@@ -0,0 +1,45 @@
+name: 'Get commit message'
+outputs:
+  msg:
+    value: ${{ steps.action_output.outputs.msg }}
+runs:
+  using: "composite"
+  steps:
+    - name: Find commit message (on push)
+      if: github.event_name == 'push'
+      shell: bash
+      run: |
+        AUTHOR_NAME="${{ github.event.head_commit.author.name }}"
+        AUTHOR_EMAIL="${{ github.event.head_commit.author.email }}"
+        TSTAMP="${{ github.event.head_commit.timestamp }}"
+        echo "commit ${{ github.event.head_commit.id }}" >> /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 "${{ github.event.head_commit.message }}" >> /tmp/commit_msg.txt
+    - name: Find commit message (PR)
+      shell: bash
+      id: checkout_code
+      if: github.event_name == 'pull_request'
+      run: |
+        echo "+++++ head commit message +++++"
+        echo "$(git log -1 --no-merges)"
+        echo "+++++++++++++++++++++++++++++++"
+        echo "hash=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+        git checkout ${{ github.event.pull_request.head.sha }}
+        echo "$(git log -1 --no-merges)" >> /tmp/commit_msg.txt
+    - shell: bash
+      id: action_output
+      run: |
+        DELIMITER="EOF_FILE_CONTENT_$(date +%s)" # Using timestamp to make it more unique
+        echo "msg<<$DELIMITER" >> "$GITHUB_OUTPUT"
+        cat /tmp/commit_msg.txt >> "$GITHUB_OUTPUT"
+        echo "$DELIMITER" >> "$GITHUB_OUTPUT"
+        echo "----- got commit message ---"
+        cat /tmp/commit_msg.txt
+        echo "----------------------------"
+    - name: Cleanup Find commit message (PR)
+      shell: bash
+      if: github.event_name == 'pull_request'
+      run: |
+        git checkout ${{ steps.checkout_code.outputs.hash }}

.github/actions/web-prereq/action.yml

@@ -0,0 +1,16 @@
+name: 'Web Preqrequisites'
+runs:
+  using: "composite"
+  steps:
+    - uses: ./.github/actions/dep-versions
+    - name: Cache EMSDK
+      id: emsdk-cache
+      uses: actions/cache@v4 # Use a specific version
+      with:
+        path: emsdk
+        key: ${{ runner.os }}-emsdk-${{ env.GITHUB_EMSDK_VERSION }}
+    - name: Install Web Prerequisites
+      shell: bash
+      run: |
+        bash ./build/common/get-emscripten.sh
+        echo "EMSDK=$PWD/emsdk" >> $GITHUB_ENV

.github/workflows/mac-continuous.yml

@@ -26,4 +26,4 @@ jobs:
           path: out/filament-release-darwin.tgz
       - name: Check public headers
         run: |
-          build/common/check-headers.sh out/release/filament/include
+          test/check-headers/test.sh out/release/filament/include

.github/workflows/postsubmit.yml

@@ -0,0 +1,57 @@
+name: 'Post-submit tasks'
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  update-renderdiff-goldens:
+    name: update-renderdiff-goldens
+    runs-on: 'ubuntu-24.04-4core'
+    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: Run update script
+        env:
+          GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
+        run: |
+          GOLDEN_BRANCH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | python3 test/renderdiff/src/commit_msg.py)
+          COMMIT_HASH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | head -n 1 | sed "s/commit //g")
+          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-docs:
+    name: update-docs
+    runs-on: 'ubuntu-24.04-4core'
+    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 selenium
+      - name: Run update script
+        env:
+          GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
+        run: |
+          COMMIT_HASH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | head -n 1 | sed "s/commit //g")
+          git config --global user.email "filament.bot@gmail.com"
+          git config --global user.name "Filament Bot"
+          git config --global credential.helper cache
+          bash docs_src/build/postsubmit.sh ${COMMIT_HASH} ${GH_TOKEN}

.github/workflows/presubmit.yml

@@ -3,10 +3,10 @@ name: Presubmit
 on:
   push:
     branches:
-    - main
+      - main
   pull_request:
     branches:
-    - main
+      - main
 
 jobs:
   build-desktop-mac:
@@ -41,8 +41,7 @@ jobs:
 
   build-windows:
     name: build-windows
-    runs-on: win-2019-16core
-
+    runs-on: windows-2022-32core
     steps:
       - uses: actions/checkout@v4.1.6
         with:
@@ -55,7 +54,6 @@ jobs:
   build-android:
     name: build-android
     runs-on: 'ubuntu-24.04-16core'
-
     steps:
       - uses: actions/checkout@v4.1.6
         with:
@@ -74,7 +72,6 @@ jobs:
   build-ios:
     name: build-iOS
     runs-on: macos-14-xlarge
-
     steps:
       - uses: actions/checkout@v4.1.6
         with:
@@ -90,12 +87,12 @@ jobs:
   build-web:
     name: build-web
     runs-on: 'ubuntu-24.04-16core'
-
     steps:
       - uses: actions/checkout@v4.1.6
         with:
           fetch-depth: 0
       - uses: ./.github/actions/linux-prereq
+      - uses: ./.github/actions/web-prereq
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh presubmit
@@ -107,11 +104,12 @@ jobs:
       - uses: actions/checkout@v4.1.6
         with:
           fetch-depth: 0
+      - id: get_commit_msg
+        uses: ./.github/actions/get-commit-msg
       - name: Check for manual edits to /docs
         run: |
-           echo "${{ github.event.pull_request.head.sha }} -- ${{ github.event.pull_request.head.sha }}"
-           # disable for now
-           # bash docs_src/build/presubmit_check.sh ${{ github.event.pull_request.head.sha }}
+          COMMIT_ID=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | head -n 1 | sed "s/commit //g")
+          bash docs_src/build/presubmit_check.sh ${COMMIT_ID}
 
   test-renderdiff:
     name: test-renderdiff
@@ -120,22 +118,25 @@ jobs:
       - uses: actions/checkout@v4.1.6
         with:
           fetch-depth: 0
+      - id: get_commit_msg
+        uses: ./.github/actions/get-commit-msg
       - uses: ./.github/actions/mac-prereq
       - name: Cache Mesa and deps
-        id: mesa-cache
-        uses: actions/cache@v4 # Use a specific version
+        uses: actions/cache@v4
         with:
           path: mesa
           key: ${{ runner.os }}-mesa-deps-2-${{ vars.MESA_VERSION }}
-      - name: Get Mesa
-        id: mesa-prereq
-        run: bash test/utils/get_mesa.sh
+      - name: Prerequisites
+        run: |
+          bash build/common/get-mesa.sh
+          pip install tifffile numpy
       - name: Run Test
-        run: bash test/renderdiff/test.sh
+        run: |
+          echo "${{ steps.get_commit_msg.outputs.msg }}" | bash test/renderdiff/test.sh
       - uses: actions/upload-artifact@v4
         with:
           name: presubmit-renderdiff-result
-          path: ./out/renderdiff_tests
+          path: ./out/renderdiff
 
   validate-wgsl-webgpu:
     name: validate-wgsl-webgpu
@@ -150,8 +151,8 @@ jobs:
       - name: Run test
         run: ./out/cmake-debug/libs/filamat/test_filamat --gtest_filter=MaterialCompiler.Wgsl*
 
-  code-correcteness:
-    name: code-correctness
+  test-code-correctness:
+    name: test-code-correctness
     runs-on: 'macos-14-xlarge'
     steps:
       - uses: actions/checkout@v4.1.6

.github/workflows/release.yml

@@ -65,13 +65,9 @@ jobs:
 
   build-mac:
     name: build-mac
-    runs-on: ${{ matrix.os }}
+    runs-on: macos-14-xlarge
     if: github.event_name == 'release' || github.event.inputs.platform == 'desktop'
 
-    strategy:
-      matrix:
-        os: [macos-14-xlarge, ubuntu-22.04-32core]
-
     steps:
       - name: Decide Git ref
         id: git_ref
@@ -118,6 +114,7 @@ jobs:
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - uses: ./.github/actions/linux-prereq
+      - uses: ./.github/actions/web-prereq
       - name: Run build script
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
@@ -166,6 +163,9 @@ 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 ../../..
       - name: Sign sample-gltf-viewer
         run: |
           echo "${APK_KEYSTORE_BASE64}" > filament.jks.base64
@@ -187,7 +187,7 @@ jobs:
           script: |
             const upload = require('./build/common/upload-release-assets');
             const { TAG } = process.env;
-            const globber = await glob.create(['out/*.aar', 'out/*.apk'].join('\n'));
+            const globber = await glob.create(['out/*.aar', 'out/*.apk', 'out/*.tgz'].join('\n'));
             await upload({ github, context }, await globber.glob(), TAG);
 
   build-ios:
@@ -226,7 +226,7 @@ jobs:
 
   build-windows:
     name: build-windows
-    runs-on: windows-2019-32core
+    runs-on: windows-2022-32core
     if: github.event_name == 'release' || github.event.inputs.platform == 'windows'
 
     steps:

.github/workflows/web-continuous.yml

@@ -17,6 +17,7 @@ jobs:
         with:
           fetch-depth: 0
       - uses: ./.github/actions/linux-prereq
+      - uses: ./.github/actions/web-prereq
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh continuous

.github/workflows/windows-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-windows:
     name: build-windows
-    runs-on: windows-2019-32core
+    runs-on: windows-2022-32core
 
     steps:
       - uses: actions/checkout@v4.1.6

BUILDING.md

@@ -97,6 +97,10 @@ Make sure you've installed the following dependencies:
 - `libxcomposite-dev` (`libXcomposite-devel` on Fedora)
 - `libxxf86vm-dev` (`libXxf86vm-devel` on Fedora)
 
+```shell
+sudo apt install clang-14 libglu1-mesa-dev libc++-14-dev libc++abi-14-dev ninja-build libxi-dev libxcomposite-dev libxxf86vm-dev -y
+```
+
 After dependencies have been installed, we highly recommend using the [easy build](#easy-build)
 script.
 
@@ -363,6 +367,8 @@ python ./emsdk.py activate latest
 source ./emsdk_env.sh
 ```
 
+Alternatively, you can try running the script `build/common/get-emscripten.sh`.
+
 After this you can invoke the [easy build](#easy-build) script as follows:
 
 ```shell

CMakeLists.txt

@@ -49,6 +49,12 @@ option(FILAMENT_SUPPORTS_OSMESA "Enable OSMesa (headless GL context) for Filamen
 
 option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" OFF)
 
+option(FILAMENT_USE_ABSEIL_LOGGING "Use Abseil to log, may increase binary size" OFF)
+
+# This is to disable GTAO for the short-term while we investigate a way to better manage size increases.
+# On the regular filament build (where size is of less concern), we enable GTAO by default.
+option(FILAMENT_DISABLE_GTAO "Disable GTAO" OFF)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
@@ -587,6 +593,10 @@ if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND NOT FILAMENT_BACKEND_DEBUG_FLAG STREQU
     unset(FILAMENT_BACKEND_DEBUG_FLAG)
 endif()
 
+if (FILAMENT_USE_ABSEIL_LOGGING)
+    add_definitions(-DFILAMENT_USE_ABSEIL_LOGGING)
+endif()
+
 # ==================================================================================================
 # Material compilation flags
 # ==================================================================================================
@@ -776,6 +786,7 @@ add_subdirectory(${LIBRARIES}/filabridge)
 add_subdirectory(${LIBRARIES}/filaflat)
 add_subdirectory(${LIBRARIES}/filagui)
 add_subdirectory(${LIBRARIES}/filameshio)
+add_subdirectory(${LIBRARIES}/generatePrefilterMipmap)
 add_subdirectory(${LIBRARIES}/gltfio)
 add_subdirectory(${LIBRARIES}/ibl)
 add_subdirectory(${LIBRARIES}/iblprefilter)

NEW_RELEASE_NOTES.md

@@ -1,11 +1,9 @@
 # Filament Release Notes log
 
 **If you are merging a PR into main**: please add the release note below, under the *Release notes
-for next branch cut* header.
+We are chaning the way Vulkan buffers are handled. We need to switch over to a managed (or view-based) model where the data stored inside the object is a proxy to a Vulkan object that can dynamically be swapped around.
 
 **If you are cherry-picking a commit into an rc/ branch**: add the release note under the
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
-- materials: remove dependence on per-view descset layout from filamat. [⚠️ **New Material Version**]

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,43 @@ 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.62.2
+
+- Metal: fix, respect alpha to coverage rasterization
+- engine: removed `Texture::generatePrefilterMipmap`, a new `libfilament-generatePrefilterMipmap` library can be used in its stead [⚠️ **API BREAKAGE**]
+
+## v1.62.1
+
+- Add new shader define `VARIANT_DEPTH`, defined when a material is compiled for depth variants
+  (e.g., shadows) [**Requires recompiling materials**]
+
+## v1.62.0
+
+- Add new `unfilterable` field to Filament Material's `sampler` [⚠️ **New Material Version**]
+
+## v1.61.2
+
+- samples: samples now have a CLI to select backend api
+
+## v1.61.1
+
+
+## v1.61.0
+
+- materials: sampler now export their type in the material binary [⚠️ **New Material Version**]
+- samples/texturedquad.cpp now has CLI to select backend api
+- samples/hellopbr.cpp CLI now allows for selecting webgpu
+
+## v1.60.1
+
+
+## v1.60.0
+
+- materials: remove dependence on per-view descset layout from filamat. [⚠️ **New Material Version**]
+- matc non-functional change: Update GLSL postprocessor to
+  isolate calls to SPVRemap from calls to SPIRV-Cross.
+
+
 ## v1.59.5
 
 

android/filament-android/CMakeLists.txt

@@ -13,6 +13,10 @@ add_library(filament STATIC IMPORTED)
 set_target_properties(filament PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilament.a)
 
+add_library(filament-generatePrefilterMipmap STATIC IMPORTED)
+set_target_properties(filament-generatePrefilterMipmap PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilament-generatePrefilterMipmap.a)
+
 add_library(backend STATIC IMPORTED)
 set_target_properties(backend PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbackend.a)
@@ -59,6 +63,10 @@ add_library(smol-v STATIC IMPORTED)
 set_target_properties(smol-v PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libsmol-v.a)
 
+add_library(abseil STATIC IMPORTED)
+set_target_properties(abseil PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libabseil.a)
+
 if (FILAMENT_ENABLE_FGVIEWER)
     add_library(fgviewer STATIC IMPORTED)
     set_target_properties(fgviewer PROPERTIES IMPORTED_LOCATION
@@ -116,6 +124,7 @@ add_library(filament-jni SHARED
 
 # Ordering is significant in the following list. The PRIVATE qualifier prevents transitive deps.
 target_link_libraries(filament-jni
+    PRIVATE filament-generatePrefilterMipmap
     PRIVATE filament
     PRIVATE backend
     PRIVATE filaflat
@@ -128,6 +137,7 @@ target_link_libraries(filament-jni
     PRIVATE jnigraphics
     PRIVATE utils
     PRIVATE perfetto
+    PRIVATE abseil
 
     # libgeometry is PUBLIC because gltfio uses it.
     PUBLIC geometry

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

@@ -556,7 +556,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
         jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
         jboolean disableHandleUseAfterFreeCheck,
         jint preferredShaderLanguage,
-        jboolean forceGLES2Context, jboolean assertNativeWindowIsValid) {
+        jboolean forceGLES2Context, jboolean assertNativeWindowIsValid,
+        jint gpuContextPriority) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     Engine::Config config = {
             .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -574,6 +575,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .preferredShaderLanguage = (Engine::Config::ShaderLanguage) preferredShaderLanguage,
             .forceGLES2Context = (bool) forceGLES2Context,
             .assertNativeWindowIsValid = (bool) assertNativeWindowIsValid,
+            .gpuContextPriority = (Engine::GpuContextPriority) gpuContextPriority,
     };
     builder->config(&config);
 }

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

@@ -23,16 +23,20 @@
 #include <android/bitmap.h>
 #endif
 
-#include <backend/BufferDescriptor.h>
 #include <filament/Engine.h>
 #include <filament/Stream.h>
 #include <filament/Texture.h>
 
+#include <filament-generatePrefilterMipmap/generatePrefilterMipmap.h>
+
+#include <backend/BufferDescriptor.h>
+
 #include "common/CallbackUtils.h"
 #include "common/NioUtils.h"
 
 #include "private/backend/VirtualMachineEnv.h"
 
+
 using namespace filament;
 using namespace backend;
 
@@ -421,7 +425,7 @@ Java_com_google_android_filament_Texture_nGeneratePrefilterMipmap(JNIEnv *env, j
     Engine *engine = (Engine *) nativeEngine;
 
     jint *faceOffsetsInBytes = env->GetIntArrayElements(faceOffsetsInBytes_, nullptr);
-    Texture::FaceOffsets faceOffsets;
+    filament::FaceOffsets faceOffsets;
     std::copy_n(faceOffsetsInBytes, 6, faceOffsets.offsets);
     env->ReleaseIntArrayElements(faceOffsetsInBytes_, faceOffsetsInBytes, JNI_ABORT);
 
@@ -444,10 +448,11 @@ Java_com_google_android_filament_Texture_nGeneratePrefilterMipmap(JNIEnv *env, j
             (uint32_t) left, (uint32_t) top, (uint32_t) stride,
             callback->getHandler(), &JniBufferCallback::postToJavaAndDestroy, callback);
 
-    Texture::PrefilterOptions options;
+    filament::PrefilterOptions options;
     options.sampleCount = sampleCount;
     options.mirror = mirror;
-    texture->generatePrefilterMipmap(*engine, std::move(desc), faceOffsets, &options);
+
+    filament::generatePrefilterMipmap(texture, *engine, std::move(desc), faceOffsets, &options);
 
     return 0;
 }

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

@@ -175,6 +175,36 @@ public class Engine {
         MULTIVIEW,
     };
 
+    /**
+     * This controls the priority level for GPU work scheduling, which helps prioritize the
+     * submitted GPU work and enables preemption.
+     */
+    public enum GpuContextPriority {
+        /**
+         * Backend default GPU context priority (typically MEDIUM)
+         */
+        DEFAULT,
+        /**
+         * For non-interactive, deferrable workloads. This should not interfere with standard
+         * applications.
+         */
+        LOW,
+        /**
+         * The default priority level for standard applications.
+         */
+        MEDIUM,
+        /**
+         * For high-priority, latency-sensitive workloads that are more important than standard
+         * applications.
+         */
+        HIGH,
+        /**
+         * The highest priority, intended for system-critical, real-time applications where missing
+         * deadlines is unacceptable (e.g., VR/AR compositors or other system-critical tasks).
+         */
+        REALTIME,
+    };
+
     /**
      * Constructs <code>Engine</code> objects using a builder pattern.
      */
@@ -233,7 +263,8 @@ public class Engine {
                     config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
                     config.disableHandleUseAfterFreeCheck,
                     config.preferredShaderLanguage.ordinal(),
-                    config.forceGLES2Context, config.assertNativeWindowIsValid);
+                    config.forceGLES2Context, config.assertNativeWindowIsValid,
+                    config.gpuContextPriority.ordinal());
             return this;
         }
 
@@ -489,6 +520,11 @@ public class Engine {
          * @Deprecated use "backend.opengl.assert_native_window_is_valid" feature flag instead
          */
         public boolean assertNativeWindowIsValid = false;
+
+        /**
+         * GPU context priority level. Controls GPU work scheduling and preemption.
+         */
+        public GpuContextPriority gpuContextPriority = GpuContextPriority.DEFAULT;
     }
 
     private Engine(long nativeEngine, Config config) {
@@ -1492,7 +1528,8 @@ public class Engine {
             long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
             boolean disableHandleUseAfterFreeCheck,
             int preferredShaderLanguage,
-            boolean forceGLES2Context, boolean assertNativeWindowIsValid);
+            boolean forceGLES2Context, boolean assertNativeWindowIsValid,
+            int gpuContextPriority);
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
     private static native void nSetBuilderPaused(long nativeBuilder, boolean paused);

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

@@ -1390,8 +1390,8 @@ public class View {
      *
      * \note
      * Dynamic resolution is only supported on platforms where the time to render
-     * a frame can be measured accurately. Dynamic resolution is currently only
-     * supported on Android.
+     * a frame can be measured accurately. On platform where this is not supported,
+     * Dynamic Resolution can't be enabled unless minScale == maxScale.
      *
      * @see Renderer::FrameRateOptions
      *
@@ -1801,6 +1801,22 @@ public class View {
      * @see setAmbientOcclusionOptions()
      */
     public static class AmbientOcclusionOptions {
+        public enum AmbientOcclusionType {
+            /**
+             * use Scalable Ambient Occlusion
+             */
+            SAO,
+            /**
+             * use Ground Truth-Based Ambient Occlusion
+             */
+            GTAO,
+        }
+
+        /**
+         * Type of ambient occlusion algorithm.
+         */
+        @NonNull
+        public AmbientOcclusionOptions.AmbientOcclusionType aoType = AmbientOcclusionOptions.AmbientOcclusionType.SAO;
         /**
          * Ambient Occlusion radius in meters, between 0 and ~10.
          */
@@ -1810,7 +1826,8 @@ public class View {
          */
         public float power = 1.0f;
         /**
-         * Self-occlusion bias in meters. Use to avoid self-occlusion. Between 0 and a few mm.
+         * 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;
         /**
@@ -1826,12 +1843,12 @@ public class View {
          */
         public float bilateralThreshold = 0.05f;
         /**
-         * affects # of samples used for AO.
+         * affects # of samples used for AO and params for filtering
          */
         @NonNull
         public QualityLevel quality = QualityLevel.LOW;
         /**
-         * affects AO smoothness
+         * affects AO smoothness. Recommend setting to HIGH when aoType set to GTAO.
          */
         @NonNull
         public QualityLevel lowPassFilter = QualityLevel.MEDIUM;
@@ -1849,7 +1866,7 @@ public class View {
          */
         public boolean bentNormals = false;
         /**
-         * min angle in radian to consider
+         * min angle in radian to consider. No effect when aoType set to GTAO.
          */
         public float minHorizonAngleRad = 0.0f;
         /**
@@ -1904,6 +1921,19 @@ public class View {
          */
         public boolean ssctEnabled = false;
 
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public int gtaoSampleSliceCount = 4;
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public int gtaoSampleStepsPerSlice = 3;
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public float gtaoThicknessHeuristic = 0.004f;
+
     }
 
     /**

android/gradle.properties

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

android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,7 @@
-#Wed Nov 17 10:40:18 PST 2021
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 distributionUrl=https\://services.gradle.org/distributions/gradle-8.8-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/gradlew

@@ -1,7 +1,7 @@
-#!/usr/bin/env sh
+#!/bin/sh
 
 #
-# Copyright 2015 the original author or authors.
+# Copyright © 2015-2021 the original authors.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,67 +17,99 @@
 #
 
 ##############################################################################
-##
-##  Gradle start up script for UN*X
-##
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/HEAD/platforms/jvm/plugins-application/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
 ##############################################################################
 
 # Attempt to set APP_HOME
+
 # Resolve links: $0 may be a link
-PRG="$0"
-# Need this for relative symlinks.
-while [ -h "$PRG" ] ; do
-    ls=`ls -ld "$PRG"`
-    link=`expr "$ls" : '.*-> \(.*\)$'`
-    if expr "$link" : '/.*' > /dev/null; then
-        PRG="$link"
-    else
-        PRG=`dirname "$PRG"`"/$link"
-    fi
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
 done
-SAVED="`pwd`"
-cd "`dirname \"$PRG\"`/" >/dev/null
-APP_HOME="`pwd -P`"
-cd "$SAVED" >/dev/null
 
-APP_NAME="Gradle"
-APP_BASE_NAME=`basename "$0"`
-
-# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
-DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+# This is normally unused
+# shellcheck disable=SC2034
+APP_BASE_NAME=${0##*/}
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
-MAX_FD="maximum"
+MAX_FD=maximum
 
 warn () {
     echo "$*"
-}
+} >&2
 
 die () {
     echo
     echo "$*"
     echo
     exit 1
-}
+} >&2
 
 # OS specific support (must be 'true' or 'false').
 cygwin=false
 msys=false
 darwin=false
 nonstop=false
-case "`uname`" in
-  CYGWIN* )
-    cygwin=true
-    ;;
-  Darwin* )
-    darwin=true
-    ;;
-  MINGW* )
-    msys=true
-    ;;
-  NONSTOP* )
-    nonstop=true
-    ;;
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
 esac
 
 CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
@@ -87,9 +119,9 @@ CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
 if [ -n "$JAVA_HOME" ] ; then
     if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
         # IBM's JDK on AIX uses strange locations for the executables
-        JAVACMD="$JAVA_HOME/jre/sh/java"
+        JAVACMD=$JAVA_HOME/jre/sh/java
     else
-        JAVACMD="$JAVA_HOME/bin/java"
+        JAVACMD=$JAVA_HOME/bin/java
     fi
     if [ ! -x "$JAVACMD" ] ; then
         die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
@@ -98,88 +130,120 @@ Please set the JAVA_HOME variable in your environment to match the
 location of your Java installation."
     fi
 else
-    JAVACMD="java"
-    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+    JAVACMD=java
+    if ! command -v java >/dev/null 2>&1
+    then
+        die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
 
 Please set the JAVA_HOME variable in your environment to match the
 location of your Java installation."
+    fi
 fi
 
 # Increase the maximum file descriptors if we can.
-if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
-    MAX_FD_LIMIT=`ulimit -H -n`
-    if [ $? -eq 0 ] ; then
-        if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
-            MAX_FD="$MAX_FD_LIMIT"
-        fi
-        ulimit -n $MAX_FD
-        if [ $? -ne 0 ] ; then
-            warn "Could not set maximum file descriptor limit: $MAX_FD"
-        fi
-    else
-        warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
-    fi
-fi
-
-# For Darwin, add options to specify how the application appears in the dock
-if $darwin; then
-    GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
-fi
-
-# For Cygwin or MSYS, switch paths to Windows format before running java
-if [ "$cygwin" = "true" -o "$msys" = "true" ] ; then
-    APP_HOME=`cygpath --path --mixed "$APP_HOME"`
-    CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
-
-    JAVACMD=`cygpath --unix "$JAVACMD"`
-
-    # We build the pattern for arguments to be converted via cygpath
-    ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
-    SEP=""
-    for dir in $ROOTDIRSRAW ; do
-        ROOTDIRS="$ROOTDIRS$SEP$dir"
-        SEP="|"
-    done
-    OURCYGPATTERN="(^($ROOTDIRS))"
-    # Add a user-defined pattern to the cygpath arguments
-    if [ "$GRADLE_CYGPATTERN" != "" ] ; then
-        OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
-    fi
-    # Now convert the arguments - kludge to limit ourselves to /bin/sh
-    i=0
-    for arg in "$@" ; do
-        CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
-        CHECK2=`echo "$arg"|egrep -c "^-"`                                 ### Determine if an option
-
-        if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then                    ### Added a condition
-            eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
-        else
-            eval `echo args$i`="\"$arg\""
-        fi
-        i=`expr $i + 1`
-    done
-    case $i in
-        0) set -- ;;
-        1) set -- "$args0" ;;
-        2) set -- "$args0" "$args1" ;;
-        3) set -- "$args0" "$args1" "$args2" ;;
-        4) set -- "$args0" "$args1" "$args2" "$args3" ;;
-        5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
-        6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
-        7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
-        8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
-        9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        # In POSIX sh, ulimit -H is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        # In POSIX sh, ulimit -n is undefined. That's why the result is checked to see if it worked.
+        # shellcheck disable=SC2039,SC3045
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
     esac
 fi
 
-# Escape application args
-save () {
-    for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
-    echo " "
-}
-APP_ARGS=`save "$@"`
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
 
-# Collect all arguments for the java command, following the shell quoting and substitution rules
-eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='"-Xmx64m" "-Xms64m"'
+
+# Collect all arguments for the java command:
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, JAVA_OPTS, and optsEnvironmentVar are not allowed to contain shell fragments,
+#     and any embedded shellness will be escaped.
+#   * For example: A user cannot expect ${Hostname} to be expanded, as it is an environment variable and will be
+#     treated as '${Hostname}' itself on the command line.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Stop when "xargs" is not available.
+if ! command -v xargs >/dev/null 2>&1
+then
+    die "xargs is not available"
+fi
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
 
 exec "$JAVACMD" "$@"

android/gradlew.bat

@@ -14,7 +14,7 @@
 @rem limitations under the License.
 @rem
 
-@if "%DEBUG%" == "" @echo off
+@if "%DEBUG%"=="" @echo off
 @rem ##########################################################################
 @rem
 @rem  Gradle startup script for Windows
@@ -25,7 +25,8 @@
 if "%OS%"=="Windows_NT" setlocal
 
 set DIRNAME=%~dp0
-if "%DIRNAME%" == "" set DIRNAME=.
+if "%DIRNAME%"=="" set DIRNAME=.
+@rem This is normally unused
 set APP_BASE_NAME=%~n0
 set APP_HOME=%DIRNAME%
 
@@ -40,13 +41,13 @@ if defined JAVA_HOME goto findJavaFromJavaHome
 
 set JAVA_EXE=java.exe
 %JAVA_EXE% -version >NUL 2>&1
-if "%ERRORLEVEL%" == "0" goto execute
+if %ERRORLEVEL% equ 0 goto execute
 
-echo.
-echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH. 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -56,11 +57,11 @@ set JAVA_EXE=%JAVA_HOME%/bin/java.exe
 
 if exist "%JAVA_EXE%" goto execute
 
-echo.
-echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
-echo.
-echo Please set the JAVA_HOME variable in your environment to match the
-echo location of your Java installation.
+echo. 1>&2
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME% 1>&2
+echo. 1>&2
+echo Please set the JAVA_HOME variable in your environment to match the 1>&2
+echo location of your Java installation. 1>&2
 
 goto fail
 
@@ -75,13 +76,15 @@ set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
 
 :end
 @rem End local scope for the variables with windows NT shell
-if "%ERRORLEVEL%"=="0" goto mainEnd
+if %ERRORLEVEL% equ 0 goto mainEnd
 
 :fail
 rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
 rem the _cmd.exe /c_ return code!
-if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
-exit /b 1
+set EXIT_CODE=%ERRORLEVEL%
+if %EXIT_CODE% equ 0 set EXIT_CODE=1
+if not ""=="%GRADLE_EXIT_CONSOLE%" exit %EXIT_CODE%
+exit /b %EXIT_CODE%
 
 :mainEnd
 if "%OS%"=="Windows_NT" endlocal

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

@@ -18,6 +18,7 @@ package com.google.android.filament.gltf
 
 import android.annotation.SuppressLint
 import android.app.Activity
+import android.content.Intent
 import android.os.Bundle
 import android.util.Log
 import android.view.*
@@ -50,6 +51,7 @@ class MainActivity : Activity() {
         // Load the library for the utility layer, which in turn loads gltfio and the Filament core.
         init { Utils.init() }
         private const val TAG = "gltf-viewer"
+        private const val STATIC_MODEL_TAG = "use-static-model"
     }
 
     private lateinit var surfaceView: SurfaceView
@@ -69,6 +71,7 @@ class MainActivity : Activity() {
     private var loadStartTime = 0L
     private var loadStartFence: Fence? = null
     private val viewerContent = AutomationEngine.ViewerContent()
+    private var useStaticModel = false
 
     @SuppressLint("ClickableViewAccessibility")
     override fun onCreate(savedInstanceState: Bundle?) {
@@ -83,6 +86,12 @@ class MainActivity : Activity() {
         doubleTapDetector = GestureDetector(applicationContext, doubleTapListener)
         singleTapDetector = GestureDetector(applicationContext, singleTapListener)
 
+        val intent: Intent = intent
+        val bundle: Bundle? = intent.extras
+        bundle?.let {
+            useStaticModel = it.getBoolean(STATIC_MODEL_TAG, false)
+        }
+
         modelViewer = ModelViewer(surfaceView)
         viewerContent.view = modelViewer.view
         viewerContent.sunlight = modelViewer.light
@@ -141,7 +150,16 @@ class MainActivity : Activity() {
     }
 
     private fun createDefaultRenderables() {
-        val buffer = assets.open("models/scene.gltf").use { input ->
+        // Sometimes it's useful to set to the default model to something static. You can enable
+        // the static model by launching the app from adb, as in
+        // `adb shell am start -n com.google.android.filament.gltf/.MainActivity --ez "use-static-model" true`
+        val modelPath = if (useStaticModel) {
+            "models/helmet.glb"
+        } else {
+            "models/scene.gltf"
+        }
+
+        val buffer = assets.open(modelPath).use { input ->
             val bytes = ByteArray(input.available())
             input.read(bytes)
             ByteBuffer.wrap(bytes)

build.sh

@@ -151,7 +151,7 @@ function print_fgviewer_help {
 }
 
 # Unless explicitly specified, NDK version will be selected as highest available version within same major release chain
-FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/build/android/ndk.version | cut -f 1 -d ".")}
+FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/build/common/versions | grep GITHUB_NDK_VERSION | sed s/GITHUB_NDK_VERSION=//g | cut -f 1 -d ".")}
 
 # Requirements
 CMAKE_MAJOR=3
@@ -463,16 +463,6 @@ function ensure_android_build {
         echo "Error: Android NDK side-by-side version ${FILAMENT_NDK_VERSION} or compatible must be installed, exiting"
         exit 1
     fi
-
-    local cmake_version=$(cmake --version)
-    if [[ "${cmake_version}" =~ ([0-9]+)\.([0-9]+)\.[0-9]+ ]]; then
-        if [[ "${BASH_REMATCH[1]}" -lt "${CMAKE_MAJOR}" ]] || \
-           [[ "${BASH_REMATCH[2]}" -lt "${CMAKE_MINOR}" ]]; then
-            echo "Error: cmake version ${CMAKE_MAJOR}.${CMAKE_MINOR}+ is required," \
-                 "${BASH_REMATCH[1]}.${BASH_REMATCH[2]} installed, exiting"
-            exit 1
-        fi
-    fi
 }
 
 function build_android {

build/android/build.sh

@@ -1,28 +1,6 @@
 #!/bin/bash
 
-# Usage: the first argument selects the build type:
-# - release, to build release only
-# - debug, to build debug only
-# - continuous, to build release and debug
-# - presubmit, for presubmit builds
-#
-# The default is release
-
-echo "This script is intended to run in a CI environment and may modify your current environment."
-echo "Please refer to BUILDING.md for more information."
-
-read -r -p "Do you wish to proceed (y/n)? " choice
-case "${choice}" in
-    y|Y)
-              echo "Build will proceed..."
-              ;;
-    n|N)
-          exit 0
-          ;;
-          *)
-        exit 0
-        ;;
-esac
+source `dirname $0`/../common/ci-check.sh
 
 set -e
 set -x
@@ -30,11 +8,6 @@ set -x
 UNAME=`echo $(uname)`
 LC_UNAME=`echo $UNAME | tr '[:upper:]' '[:lower:]'`
 
-# build-common.sh will generate the following variables:
-#     $GENERATE_ARCHIVES
-#     $BUILD_DEBUG
-#     $BUILD_RELEASE
-source `dirname $0`/../common/ci-common.sh
 source `dirname $0`/../common/build-common.sh
 
 if [[ "$GITHUB_WORKFLOW" ]]; then

build/common/build-common.sh

@@ -1,5 +1,20 @@
 #!/bin/bash
 
+# build-common.sh will generate the following variables:
+#     $GENERATE_ARCHIVES
+#     $BUILD_DEBUG
+#     $BUILD_RELEASE
+
+# Typically a build script (build.sh) would source this script. For example,
+#   source `dirname $0`/../common/build-common.sh
+
+# Usage: the first argument selects the build type:
+# - release, to build release only
+# - debug, to build debug only
+# - continuous, to build release and debug
+# - presubmit, for presubmit builds
+#
+# The default is release
 if [[ ! "$TARGET" ]]; then
     if [[ "$1" ]]; then
         TARGET=$1

build/common/ci-check.sh

@@ -0,0 +1,19 @@
+echo "This script is intended to run in a CI environment and may modify your current environment."
+echo "Please refer to BUILDING.md for more information."
+
+read -r -p "Do you wish to proceed (y/n)? " choice
+case "${choice}" in
+    y|Y)
+	      echo "Build will proceed..."
+	      ;;
+    n|N)
+    	  exit 0
+    	  ;;
+	  *)
+        exit 0
+        ;;
+esac
+
+if [[ "$GITHUB_WORKFLOW" ]]; then
+    echo "Running workflow $GITHUB_WORKFLOW (event: $GITHUB_EVENT_NAME, action: $GITHUB_ACTION)"
+fi

build/common/ci-common.sh

@@ -1,5 +0,0 @@
-#!/bin/bash
-
-if [[ "$GITHUB_WORKFLOW" ]]; then
-    echo "Running workflow $GITHUB_WORKFLOW (event: $GITHUB_EVENT_NAME, action: $GITHUB_ACTION)"
-fi

build/common/get-emscripten.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+if [ -d "./emsdk" ]; then
+    echo "emsdk folder found. Assume emsdk has been installed."
+    cd emsdk
+    ./emsdk activate latest
+    source ./emsdk_env.sh
+    export EMSDK="$PWD"
+    cd ..
+    exit 0
+fi
+
+# Install emscripten.
+EMSDK_VERSION=${GITHUB_EMSDK_VERSION-3.1.60}
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/${EMSDK_VERSION}.zip > emsdk.zip
+unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
+./emsdk install latest
+./emsdk activate latest
+source ./emsdk_env.sh
+
+export EMSDK="$PWD"
+cd ..

build/common/get-mesa.sh

@@ -14,9 +14,9 @@
 
 #!/usr/bin/bash
 
-set -x
+set -e
 if [[ "$GITHUB_WORKFLOW" ]]; then
-    set -e
+    set -x
 fi
 
 OS_NAME=$(uname -s)
@@ -35,12 +35,14 @@ source ${ORIG_DIR}/venv/bin/activate
 
 NEEDED_PYTHON_DEPS=("mako" "setuptools" "pyyaml")
 for cmd in "${NEEDED_PYTHON_DEPS[@]}"; do
-    if ! python3 -m pip show "${cmd}" >/dev/null 2>&1; then
+    if ! python3 -m pip show -q "${cmd}" >/dev/null 2>&1; then
         python3 -m pip install ${cmd}
     fi
 done
 deactivate
 
+LOCAL_PKG_CONFIG_PATH=
+
 # Install system deps
 if [[ "$OS_NAME" == "Linux" ]]; then
     if [[ "$GITHUB_WORKFLOW" ]]; then
@@ -75,13 +77,20 @@ if [[ "$OS_NAME" == "Linux" ]]; then
             sudo ln -s /usr/bin/clang++-${CLANG_VERSION} /usr/bin/clang++
     fi # [[ "$GITHUB_WORKFLOW" ]]
 elif [[ "$OS_NAME" == "Darwin" ]]; then
-    if [[ ! "$GITHUB_WORKFLOW" ]]; then
-        if [ ! command -v brew > /dev/null 2>&1 ]; then
-            echo "Error: need to install homebrew to continue"
-            exit 1
-        fi
+    if command -v brew > /dev/null 2>&1; then
+        HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=true brew install autoconf automake libx11 libxext libxrandr \
+                                                        llvm@${LLVM_VERSION} ninja meson pkg-config libxshmfence
+        # For reasons unknown, this is necessary for pkg-config to find homebrew's packages
+        LOCAL_PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"
+    elif command -v port > /dev/null 2>&1; then
+        sudo port install autoconf automake libx11 libXext libXrandr llvm-${LLVM_VERSION} \
+             ninja meson pkgconfig libxshmfence
+        # For reasons unknown, this is necessary for pkg-config to find macport's packages
+        LOCAL_PKG_CONFIG_PATH="/opt/local/lib/pkgconfig:$PKG_CONFIG_PATH"
+    else
+        echo "Error: need to install homebrew or macports to continue"
+        exit 1
     fi
-    HOMEBREW_NO_INSTALLED_DEPENDENTS_CHECK=true brew install autoconf automake libx11 libxext libxrandr llvm@${LLVM_VERSION} ninja meson pkg-config libxshmfence
 fi # [[ "$OS_NAME" == x ]]
 
 LOCAL_LDFLAGS=${LDFLAGS}
@@ -134,9 +143,11 @@ fi
 # -Dgallium-drivers=swrast  => builds GL software rasterizer
 # -Dvulkan-drivers=swrast   => builds VK software rasterizer
 # -Dgallium-drivers=llvmpipe is needed for GL >= 4.1 pipe-screen (see src/gallium/auxiliary/target-helpers/inline_sw_helper.h)
-CXX=${LOCAL_CXX} CC=${LOCAL_CC} PATH=${LOCAL_PATH} LDFLAGS=${LOCAL_LDFLAGS} CPPFLAGS=${LOCAL_CPPFLAGS} \
+PKG_CONFIG_PATH=${LOCAL_PKG_CONFIG_PATH} PATH=${LOCAL_PATH} \
+CXX=${LOCAL_CXX} CC=${LOCAL_CC} LDFLAGS=${LOCAL_LDFLAGS} CPPFLAGS=${LOCAL_CPPFLAGS} \
    meson setup --wipe builddir/ -Dprefix="${MESA_DIR}/out" -Dglx=xlib -Dosmesa=true -Dgallium-drivers=llvmpipe,swrast -Dvulkan-drivers=swrast
-CXX=${LOCAL_CXX} CC=${LOCAL_CC} PATH=${LOCAL_PATH} LDFLAGS=${LOCAL_LDFLAGS} CPPFLAGS=${LOCAL_CPPFLAGS} \
+PKG_CONFIG_PATH=${LOCAL_PKG_CONFIG_PATH} PATH=${LOCAL_PATH} \
+CXX=${LOCAL_CXX} CC=${LOCAL_CC} LDFLAGS=${LOCAL_LDFLAGS} CPPFLAGS=${LOCAL_CPPFLAGS} \
    meson install -C builddir/
 
 # Disable python venv
@@ -145,6 +156,6 @@ deactivate
 popd
 
 if [[ "$GITHUB_WORKFLOW" ]]; then
-    set +e
+    set +x
 fi
-set +x
+set +e

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

@@ -204,9 +204,10 @@
       "license": "Apache-2.0"
     },
     "node_modules/brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "license": "MIT",
       "dependencies": {
         "balanced-match": "^1.0.0",
         "concat-map": "0.0.1"
@@ -409,9 +410,9 @@
       "integrity": "sha512-Nik3Sc0ncrMK4UUdXQmAnRtzmNQTAAXmXIopizwZ1W1t8QmfJj+zL4OA2I7XPTPW5z5TDqv4hRo/JzouDJnX3A=="
     },
     "brace-expansion": {
-      "version": "1.1.11",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
-      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
       "requires": {
         "balanced-match": "^1.0.0",
         "concat-map": "0.0.1"

build/common/versions

@@ -3,4 +3,5 @@ GITHUB_CMAKE_VERSION=3.19.5
 GITHUB_NINJA_VERSION=1.10.2
 GITHUB_MESA_VERSION=24.2.1
 GITHUB_LLVM_VERSION=16
-GITHUB_NDK_VERSION=27.0.11718014
+GITHUB_NDK_VERSION=27.0.11718014
+GITHUB_EMSDK_VERSION=3.1.60

build/ios/build.sh

@@ -1,35 +1,11 @@
 #!/bin/bash
 
-# Usage: the first argument selects the build type:
-# - release, to build release only
-# - debug, to build debug only
-# - continuous, to build release and debug
-# - presubmit, for presubmit builds
-#
-# The default is release
-
-echo "This script is intended to run in a CI environment and may modify your current environment."
-echo "Please refer to BUILDING.md for more information."
-
-read -r -p "Do you wish to proceed (y/n)? " choice
-case "${choice}" in
-    y|Y)
-	      echo "Build will proceed..."
-	      ;;
-    n|N)
-    	  exit 0
-    	  ;;
-	  *)
-        exit 0
-        ;;
-esac
+source `dirname $0`/../common/ci-check.sh
 
 set -e
 set -x
 
-source `dirname $0`/../common/ci-common.sh
 source `dirname $0`/../common/build-common.sh
-
 pushd `dirname $0`/../.. > /dev/null
 
 # If we're generating an archive for release or continuous builds, then we'll also build for the

build/linux/build.sh

@@ -1,38 +1,11 @@
 #!/bin/bash
 
-# Usage: the first argument selects the build type:
-# - release, to build release only
-# - debug, to build debug only
-# - continuous, to build release and debug
-# - presubmit, for presubmit builds
-#
-# The default is release
-
-echo "This script is intended to run in a CI environment and may modify your current environment."
-echo "Please refer to BUILDING.md for more information."
-
-read -r -p "Do you wish to proceed (y/n)? " choice
-case "${choice}" in
-    y|Y)
-	      echo "Build will proceed..."
-	      ;;
-    n|N)
-    	  exit 0
-    	  ;;
-	  *)
-        exit 0
-        ;;
-esac
+source `dirname $0`/../common/ci-check.sh
 
 set -e
 set -x
 
-# build-common.sh will generate the following variables:
-#     $GENERATE_ARCHIVES
-#     $BUILD_DEBUG
-#     $BUILD_RELEASE
-source `dirname $0`/../common/ci-common.sh
 source `dirname $0`/../common/build-common.sh
-
 pushd `dirname $0`/../.. > /dev/null
+
 ./build.sh -c $RUN_TESTS $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE

build/mac/build.sh

@@ -1,34 +1,11 @@
 #!/bin/bash
 
-# Usage: the first argument selects the build type:
-# - release, to build release only
-# - debug, to build debug only
-# - continuous, to build release and debug
-# - presubmit, for presubmit builds
-#
-# The default is release
-
-echo "This script is intended to run in a CI environment and may modify your current environment."
-echo "Please refer to BUILDING.md for more information."
-
-read -r -p "Do you wish to proceed (y/n)? " choice
-case "${choice}" in
-    y|Y)
-	      echo "Build will proceed..."
-	      ;;
-    n|N)
-    	  exit 0
-    	  ;;
-	  *)
-        exit 0
-        ;;
-esac
+source `dirname $0`/../common/ci-check.sh
 
 set -e
 set -x
 
-source `dirname $0`/../common/ci-common.sh
 source `dirname $0`/../common/build-common.sh
-
 pushd `dirname $0`/../.. > /dev/null
+
 ./build.sh -c $RUN_TESTS $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE

build/web/build.sh

@@ -1,34 +1,10 @@
 #!/bin/bash
 
-# Usage: the first argument selects the build type:
-# - release, to build release only
-# - debug, to build debug only
-# - continuous, to build release and debug
-# - presubmit, for presubmit builds
-#
-# The default is release
-
-echo "This script is intended to run in a CI environment and may modify your current environment."
-echo "Please refer to BUILDING.md for more information."
-
-read -r -p "Do you wish to proceed (y/n)? " choice
-case "${choice}" in
-    y|Y)
-	      echo "Build will proceed..."
-	      ;;
-    n|N)
-    	  exit 0
-    	  ;;
-	  *)
-        exit 0
-        ;;
-esac
+source `dirname $0`/../common/ci-check.sh
 
 set -e
 set -x
 
-source `dirname $0`/../common/ci-common.sh
-source `dirname $0`/ci-common.sh
 source `dirname $0`/../common/build-common.sh
 pushd `dirname $0`/../.. > /dev/null
 

build/web/ci-common.sh

@@ -1,11 +0,0 @@
-#!/bin/bash
-
-# Install emscripten.
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
-unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
-./emsdk install latest
-./emsdk activate latest
-source ./emsdk_env.sh
-
-export EMSDK="$PWD"
-cd ..

build/windows/build-github.bat

@@ -47,7 +47,11 @@ if "%RUNNING_LOCALLY%" == "1" (
     set "PATH=%PATH%;C:\Program Files\7-Zip"
 )
 
-call "C:\Program Files (x86)\Microsoft Visual Studio\2019\%VISUAL_STUDIO_VERSION%\VC\Auxiliary\Build\vcvars64.bat"
+:: Outdated windows-2019 pattern
+:: call "C:\Program Files (x86)\Microsoft Visual Studio\2019\%VISUAL_STUDIO_VERSION%\VC\Auxiliary\Build\vcvars64.bat"
+
+call "C:\Program Files\Microsoft Visual Studio\2022\%VISUAL_STUDIO_VERSION%\VC\Auxiliary\Build\vcvars64.bat"
+echo Passed vcvars64.bat
 if errorlevel 1 exit /b %errorlevel%
 
 msbuild /version
@@ -107,7 +111,7 @@ cd out\cmake-%variant%
 if errorlevel 1 exit /b %errorlevel%
 
 cmake ..\.. ^
-    -G "Visual Studio 16 2019" ^
+    -G "Visual Studio 17 2022" ^
     -A x64 ^
     %flag% ^
     -DCMAKE_INSTALL_PREFIX=..\%variant% ^

docs/Materials.md.html

@@ -1027,8 +1027,11 @@ samplerCubemap         | Cubemap texture
 [Table [materialParamsTypes]: Material parameter types]
 
 Samplers
-:     Sampler types can also specify a `format` which can be either `int` or `float` (defaults to
-      `float`).
+:     Sampler types can have the following fields:
+       - `format` : which can be either `int` or `float` (defaults to `float`).
+       - `multisample` : a boolean to indicate whether the sampler is meant for multisampling (defaults to `false`)
+       - `unfilterable` : a boolean to indicate whether the sampling is not filtered (defaults to `false`)
+
 
 Arrays
 :     A parameter can define an array of values by appending `[size]` after the type name, where

docs_src/.gitignore

@@ -1,2 +1,5 @@
-book
-src/dup/*.md
+build/__pycache__
+src_mdbook/book
+src_mdbook/src/dup/*.md
+src_mdbook/src/main/filament.md
+src_mdbook/src/main/materials.md

docs_src/build/checks.py

@@ -30,21 +30,23 @@ from utils import execute, ArgParseImpl
 CUR_DIR = os.path.dirname(os.path.abspath(__file__))
 ROOT_DIR = os.path.join(CUR_DIR, '../../')
 
-def get_last_commit_hash():
-  res, ret = execute('git rev-parse HEAD', cwd=ROOT_DIR)
-  assert res == 0, 'Failed to get the last commit hash'
-  return ret.strip()
+DOCS_SRC_DIR = os.path.abspath(os.path.join(CUR_DIR, '../'))
+MARKDEEP_SRC_DIR = os.path.join(DOCS_SRC_DIR, 'src_markdeep')
+MDBOOK_SRC_DIR = os.path.join(DOCS_SRC_DIR, 'src_mdbook')
+RAW_SRC_DIR = os.path.join(DOCS_SRC_DIR, 'src_raw')
+
+SRC_SRC_DIRS = [MARKDEEP_SRC_DIR, MDBOOK_SRC_DIR, RAW_SRC_DIR]
 
 def get_edited_files(commit_hash):
   INSERT = '#####?????'
   res, ret = execute(f'git show --name-only --pretty=%b{INSERT} {commit_hash}')
-  assert res == 0, 'Failed to get edited filed'
+  assert res == 0, f'Failed to get edited filed {res}: ' + ret
   files = []
   _, after = ret.split(INSERT)
   for r in filter(lambda a: len(a) > 0, after.split('\n')):
     if r.startswith('commit'):
       break
-    files.append(r)
+    files.append(os.path.abspath(os.path.join(ROOT_DIR, r)))
   return files
 
 # Returns True if there were no direct edits to '/docs'
@@ -59,12 +61,19 @@ def check_has_source_edits(commit_hash, printing=True):
   config = {}
   with open(f'{CUR_DIR}/duplicates.json') as config_txt:
     config = json.loads(config_txt.read())
-  source_files = set(config.keys())
+  source_files = set(os.path.abspath(os.path.join(ROOT_DIR, k)) for k in config.keys())
   edited_files = set(get_edited_files(commit_hash))
-  overlap = [f'\t{f}' for f in list(source_files & edited_files)]
-  if printing and len(overlap) > 0:
-    print(f'Found edited source files:\n' + '\n'.join(overlap))
-  return len(overlap) > 0
+
+  # find any changes to docs_src sources
+  is_docs_src_edit = lambda f: any(f.startswith(prefix) for prefix in SRC_SRC_DIRS)
+
+  final_edited = [f'\t{f}' for f in \
+                  list(source_files & edited_files) + \
+                  list(filter(is_docs_src_edit, edited_files))]
+
+  if printing and len(final_edited) > 0:
+    print(f'Found edited source files:\n' + '\n'.join(final_edited))
+  return len(final_edited) > 0
 
 # Returns true in a given TAG is found in the commit msg
 def commit_msg_has_tag(commit_hash, tag, printing=True):

docs_src/build/install_mdbook.sh

@@ -39,13 +39,13 @@ function download_mdbook() {
     fi
 
     local CHECK_UNAME="
-import sys;
-parts=[a.lower() for a in sys.stdin.read().strip().split(' ')];
+import sys
+parts=[a.lower() for a in sys.stdin.read().strip().split(' ')]
 def get_type():
   if 'darwin' in parts:
     if 'x86_64' in parts:
       return ${DARWIN_X86}
-    elif 'aarch' in parts:
+    elif 'aarch' in parts or 'arm64' in parts:
       return ${DARWIN_ARM}
   elif 'linux' in parts:
     if 'x86_64' in parts:
@@ -63,11 +63,12 @@ print(get_type())
             echo "*** Need to install Rust ***"
             curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
         fi
+        source "${HOME}/.cargo/env"
         if ! (command -v cargo >/dev/null 2>&1); then
-            echo "*** Still cannot find `cargo` ***"
+            echo "*** Still cannot find cargo ***"
             exit 1
         fi
-        cargo install mdbook
+        cargo install --force mdbook
     else
         # Download prebuilts from github
         mkdir -p ${HOME}/.cargo/bin

docs_src/build/postsubmit.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/bash
+
+# Copyright (C) 2025 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.
+
+FILAMENT_BOT_TOKEN=$2
+
+function update_to_main() {
+    python3 docs_src/build/run.py
+    mkdir -p tmp
+    pushd .
+    cd tmp
+    git clone https://x-access-token:${FILAMENT_BOT_TOKEN}@github.com/google/filament.git
+    cd filament
+    rm -rf docs/*
+    cp -r ../../docs_src/src_mdbook/book/* docs
+    git add -A docs/*
+    git commit -a \
+        -m "[automated] Updating /docs due to commit ${COMMIT_HASH:0:7}" \
+        -m "" \
+        -m "Full commit hash is ${COMMIT_HASH}" \
+        -m "" \
+        -m "DOCS_ALLOW_DIRECT_EDITS"
+
+    git push origin main
+    popd
+}
+
+COMMIT_HASH=$1
+HAS_EDITS=$((python3 docs_src/build/checks.py --do-or="source_edits,commit_docs_force" $COMMIT_HASH > /dev/null && echo "true") || echo "false")
+DO_BYPASS=$((python3 docs_src/build/checks.py --do-and="commit_docs_bypass" $COMMIT_HASH && echo "true") || echo "false")
+
+if [[ "${HAS_EDITS}" == "true" && "${DO_BYPASS}" == "false" ]]; then
+    # Run again to output the edited files:
+    python3 docs_src/build/checks.py --do-or="source_edits,commit_docs_force" $COMMIT_HASH
+    update_to_main
+else
+    echo "has edits (to /docs_src): ${HAS_EDITS}"
+    echo "bypass: ${DO_BYPASS}"
+fi

docs_src/build/run.py

@@ -16,12 +16,18 @@ import json
 import os
 import re
 from utils import execute, ArgParseImpl
+import shutil
 
 CUR_DIR = os.path.dirname(os.path.abspath(__file__))
 DOCS_SRC_DIR = os.path.join(CUR_DIR, '../')
 ROOT_DIR = os.path.join(CUR_DIR, '../../')
-SRC_DIR = os.path.join(CUR_DIR, '../src')
-MARKDEEP_DIR = os.path.join(CUR_DIR, '../markdeep')
+
+MDBOOK_DIR = os.path.join(CUR_DIR, '../src_mdbook')
+BOOK_OUPUT_DIR = os.path.join(MDBOOK_DIR, 'book')
+SRC_DIR = os.path.join(MDBOOK_DIR, 'src')
+
+MARKDEEP_DIR = os.path.join(CUR_DIR, '../src_markdeep')
+RAW_COPIES_DIR = os.path.join(CUR_DIR, '../src_raw')
 DUP_DIR = os.path.join(SRC_DIR, 'dup')
 MAIN_DIR = os.path.join(SRC_DIR, 'main')
 
@@ -124,5 +130,7 @@ if __name__ == "__main__":
   pull_duplicates()
   pull_markdeep_docs()
 
-  res, err = execute('mdbook build', cwd=DOCS_SRC_DIR)
+  res, err = execute('mdbook build', cwd=MDBOOK_DIR)
   assert res == 0, f"failed to execute `mdbook`. return-code={res} err=\"{err}\""
+
+  shutil.copytree(RAW_COPIES_DIR, BOOK_OUPUT_DIR, dirs_exist_ok=True)

docs_src/src_markdeep/Materials.md.html

@@ -13,7 +13,7 @@ This document is part of the [Filament project](https://github.com/google/filame
 ## Authors
 
 - [Romain Guy](https://github.com/romainguy), [@romainguy](https://twitter.com/romainguy)
-- [Mathias Agopian](https://github.com/pixelflinger), [@darthmoosious](https://twitter.com/darthmoosious)
+- [Mathias Agopian](https://github.com/pixelflinger), [@pixelflinger](https://bsky.app/profile/pixelflinger.bsky.social)
 
 # Overview
 
@@ -78,26 +78,27 @@ in table [standardProperties].
         Property        |      Definition
 -----------------------:|:---------------------
 **baseColor**           | Diffuse albedo for non-metallic surfaces, and specular color for metallic surfaces
-**metallic**            | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
 **roughness**           | Perceived smoothness (1.0) or roughness (0.0) of a surface. Smooth surfaces exhibit sharp reflections
+**metallic**            | Whether a surface appears to be dielectric (0.0) or conductor (1.0). Often used as a binary value (0 or 1)
 **reflectance**         | Fresnel reflectance at normal incidence for dielectric surfaces. This directly controls the strength of the reflections
-**sheenColor**          | Strength of the sheen layer
-**sheenRoughness**      | Perceived smoothness or roughness of the sheen layer
+**ambientOcclusion**    | Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0
 **clearCoat**           | Strength of the clear coat layer
 **clearCoatRoughness**  | Perceived smoothness or roughness of the clear coat layer
+**clearCoatNormal**     | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
 **anisotropy**          | Amount of anisotropy in either the tangent or bitangent direction
 **anisotropyDirection** | Local surface direction in tangent space
-**ambientOcclusion**    | Defines how much of the ambient light is accessible to a surface point. It is a per-pixel shadowing factor between 0.0 and 1.0
-**normal**              | A detail normal used to perturb the surface using _bump mapping_ (_normal mapping_)
-**bentNormal**          | A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality
-**clearCoatNormal**     | A detail normal used to perturb the clear coat layer using _bump mapping_ (_normal mapping_)
-**emissive**            | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
-**postLightingColor**   | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
-**ior**                 | Index of refraction, either for refractive objects or as an alternative to reflectance
-**transmission**        | Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is
-**absorption**          | Absorption factor for refractive objects
-**microThickness**      | Thickness of the thin layer of refractive objects
 **thickness**           | Thickness of the solid volume of refractive objects
+**sheenColor**          | Strength of the sheen layer
+**sheenRoughness**      | Perceived smoothness or roughness of the sheen layer
+**emissive**            | Additional diffuse albedo to simulate emissive surfaces (such as neons, etc.) This property is mostly useful in an HDR pipeline with a bloom pass
+**normal**              | A detail normal used to perturb the surface using _bump mapping_ (_normal mapping_)
+**postLightingColor**   | Additional color that can be blended with the result of the lighting computations. See `postLightingBlending`
+**absorption**          | Absorption factor for refractive objects
+**transmission**        | Defines how much of the diffuse light of a dielectric is transmitted through the object, in other words this defines how transparent an object is
+**ior**                 | Index of refraction, either for refractive objects or as an alternative to reflectance
+**microThickness**      | Thickness of the thin layer of refractive objects
+**bentNormal**          | A normal pointing in the average unoccluded direction. Can be used to improve indirect lighting quality
+**shadowStrength**      | Strength factor between 0 and 1 for all shadows received by this material
 [Table [standardProperties]: Properties of the standard model]
 
 The type and range of each property is described in table [standardPropertiesTypes].
@@ -991,10 +992,13 @@ Type
 
 Value
 :     Each entry is an object with the properties `name` and `type`, both of `string` type. The
-      name must be a valid GLSL identifier. Entries also have an optional `precision`, which can be
+      name must be a valid GLSL identifier. Entries have an optional `precision`, which can be
       one of `default` (best precision for the platform, typically `high` on desktop, `medium` on
       mobile), `low`, `medium`, `high`. The type must be one of the types described in
-      table [materialParamsTypes].
+      table [materialParamsTypes]. For Android external textures, entries also have an optional 
+      transformName parameter to specify the name of the material parameter that will be 
+      used to expose the transform matrix associated with the external sampler. In iOS and Vulkan,
+      this will always be identity. 
 
          Type          |            Description
 :----------------------|:---------------------------------
@@ -1023,8 +1027,11 @@ samplerCubemap         | Cubemap texture
 [Table [materialParamsTypes]: Material parameter types]
 
 Samplers
-:     Sampler types can also specify a `format` which can be either `int` or `float` (defaults to
-      `float`).
+:     Sampler types can have the following fields:
+       - `format` : which can be either `int` or `float` (defaults to `float`).
+       - `multisample` : a boolean to indicate whether the sampler is meant for multisampling (defaults to `false`)
+       - `unfilterable` : a boolean to indicate whether the sampling is not filtered (defaults to `false`)
+
 
 Arrays
 :     A parameter can define an array of values by appending `[size]` after the type name, where
@@ -1269,6 +1276,9 @@ Description
       when selecting any shading model that is not `unlit`. See the shader sections of this document
       for more information on how to access these attributes from the shaders.
 
+!!! Note: Interaction with custom variables
+    When the `color` attribute is specified, only four custom variables are available instead of five.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
     parameters : [
@@ -1299,7 +1309,7 @@ Type
 :    array of `string`
 
 Value
-:     Up to 4 strings, each must be a valid GLSL identifier.
+:     Up to 5 strings, each must be a valid GLSL identifier.
 
 Description
 :     Defines custom interpolants (or variables) that are output by the material's vertex shader.
@@ -1315,6 +1325,10 @@ Description
       particular if `default` is specified the default precision is used is the fragment shader
       (`mediump`) and in the vertex shader (`highp`).
 
+!!! Warning: Interaction with required attributes
+    If the `color` attribute is specified in the `required` list, then only four variables can be used
+    instead of five.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
     name : Skybox,

docs_src/src_mdbook/book.toml

@@ -10,8 +10,8 @@ create-missing = false
 
 [output.html]
 mathjax-support = true
-default-theme = "light"
-preferred-dark-theme = "light"
+default-theme = "ayu"
+preferred-dark-theme = "ayu"
 
 [output.html.print]
 enable = false

docs_src/src_mdbook/src/SUMMARY.md

@@ -18,6 +18,8 @@
     - [Metal](./notes/metal_debugging.md)
     - [Vulkan](./notes/vulkan_debugging.md)
     - [SPIR-V](./notes/spirv_debugging.md)
+    - [Running with ASAN and UBSAN](./notes/asan_ubsan.md)
+    - [Using Instruments on macOS](./notes/instruments.md)
   - [Libraries](./notes/libs.md)
     - [bluegl](./dup/bluegl.md)
     - [bluevk](./dup/bluevk.md)