Revert "buffer update opt: Add a flag to guard the feature (#9322)"

This reverts commit 49c4a5d62c.

.clang-format

@@ -65,4 +65,6 @@ SpacesInParentheses: false
 SpacesInSquareBrackets: false
 TabWidth: 4
 UseTab: Never
-PackConstructorInitializers: Never
+PackConstructorInitializers: Never
+ConstructorInitializerIndentWidth: 8
+IndentWrappedFunctionNames: true

.github/actions/get-gltf-assets/action.yml

@@ -0,0 +1,23 @@
+name: 'Get and cache glTF Assets'
+description: 'Downloads and caches glTF assets by calling the get-gltf-sample-assets.sh script.'
+
+runs:
+  using: "composite"
+  steps:
+    - uses: ./.github/actions/dep-versions
+    - name: Hash models file
+      id: hash-models
+      shell: bash
+      run: echo "hash=$(cat test/renderdiff/tests/gltf_models.txt | md5sum | sed 's/ -//g')" >> $GITHUB_OUTPUT
+    - name: Cache glTF assets
+      id: cache-gltf
+      uses: actions/cache@v4
+      with:
+        path: gltf
+        key: gltf-assets-${{ env.GITHUB_GLTF_SAMPLE_ASSETS_COMMIT }}-${{ steps.hash-models.outputs.hash }}
+    - name: Download assets via script if cache not found
+      if: steps.cache-gltf.outputs.cache-hit != 'true'
+      shell: bash
+      run: |
+        echo "Cache miss for commit ${{ env.GITHUB_GLTF_SAMPLE_ASSETS_COMMIT }}. Running download script..."
+        xargs bash build/common/get-gltf-sample-assets.sh < test/renderdiff/tests/gltf_models.txt

.github/actions/get-mesa/action.yml

@@ -1,5 +1,6 @@
-name: 'Get Mesa'
-description: 'Caches and installs Mesa'
+name: 'Get and cache Mesa'
+description: 'Get and cache Mesa'
+
 runs:
   using: "composite"
   steps:

.github/actions/get-vulkan-sdk/action.yml

@@ -8,7 +8,7 @@ runs:
       uses: actions/cache@v3
       id: cache-vulkan-sdk
       with:
-        path: ${{ runner.homedir }}/VulkanSDK
+        path: ~/VulkanSDK
         key: vulkansdk-${{ env.GITHUB_VULKANSDK_VERSION }}-2-${{ runner.os }}
     - name: Download Vulkan SDK
       if: steps.cache-vulkan-sdk.outputs.cache-hit != 'true'
@@ -21,6 +21,9 @@ runs:
       run: |
         source ${{ github.workspace }}/build/common/get-vulkan-sdk.sh
         unpack_vulkan_installer
+      shell: bash
+    - name: Run Vulkan SDK setup
+      run: |
         pushd .
         cd ~/VulkanSDK/${GITHUB_VULKANSDK_VERSION}
         sudo ./install_vulkan.py

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

@@ -14,10 +14,12 @@ runs:
       id: brew-cache
       uses: actions/cache@v4 # Use a specific version
       with:
-        path: $HOME/Library/Caches/Homebrew
+        path: ~/Library/Caches/Homebrew
         key: ${{ runner.os }}-brew-20250424
     - name: Install Mac Prerequisites
       shell: bash
       run: |
+        # Install brew prereqs
+        brew install coreutils
         # Install ninja
         source ./build/common/get-ninja.sh

.github/workflows/android-continuous.yml

@@ -12,7 +12,7 @@ jobs:
     name: build-android
     # We intentially use a larger runner here to enable larger disk space
     # (standard linux runner will fail on disk space and faster build time).
-    runs-on: 'ubuntu-24.04-32core'
+    runs-on: 'ubuntu-24.04-16core'
 
     steps:
       - uses: actions/checkout@v4.1.6

.github/workflows/presubmit.yml

@@ -26,7 +26,7 @@ jobs:
 
   build-desktop-linux:
     name: build-linux
-    runs-on: ubuntu-22.04-16core
+    runs-on: 'ubuntu-24.04-16core'
     steps:
       - uses: actions/checkout@v4.1.6
         with:
@@ -118,11 +118,12 @@ 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
-      - uses: ./.github/actions/mac-prereq
-      - uses: ./.github/actions/get-mesa
-      - uses: ./.github/actions/get-vulkan-sdk
       - name: Prerequisites
         run: |
           pip install tifffile numpy
@@ -132,6 +133,7 @@ jobs:
       - name: Render and compare
         id: render_compare
         run: |
+          ls ./gltf/Models
           TEST_DIR=test/renderdiff
           source ${TEST_DIR}/src/preamble.sh
           start_
@@ -169,7 +171,7 @@ jobs:
 
   validate-wgsl-webgpu:
     name: validate-wgsl-webgpu
-    runs-on: 'ubuntu-24.04-8core'
+    runs-on: 'ubuntu-24.04-16core'
     steps:
       - uses: actions/checkout@v4.1.6
         with:

.github/workflows/release.yml

@@ -31,7 +31,7 @@ on:
 jobs:
   build-linux:
     name: build-linux
-    runs-on: ubuntu-22.04-32core
+    runs-on: 'ubuntu-24.04-16core'
     if: github.event_name == 'release' || github.event.inputs.platform == 'desktop'
 
     steps:

.gitignore

@@ -18,3 +18,9 @@ test*.json
 results
 /compile_commands.json
 /.cache
+
+# For /test/renderdiff dependencies
+/mesa
+/gltf
+/filament-assets
+/venv

BUILDING.md

@@ -391,7 +391,7 @@ Alternatively, if you have node installed you can use the
 [live-server](https://www.npmjs.com/package/live-server) package, which automatically refreshes the
 web page when it detects a change.
 
-Each sample app has its own handwritten html file. Additionally the server folder contains assets
+Each sample app has its own handwritten html file. Additionally, the server folder contains assets
 such as meshes, textures, and materials.
 
 ## Running the native samples

CMakeLists.txt

@@ -351,7 +351,7 @@ else()
 endif()
 
 if (FILAMENT_USE_EXTERNAL_GLES3)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DUSE_EXTERNAL_GLES3")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DFILAMENT_USE_EXTERNAL_GLES3")
 endif()
 
 if (FILAMENT_SUPPORTS_EGL_ON_LINUX)
@@ -532,6 +532,15 @@ if (FILAMENT_SUPPORTS_OPENGL)
     add_definitions(-DFILAMENT_SUPPORTS_OPENGL)
 endif()
 
+if (CMAKE_BUILD_TYPE STREQUAL "Release" OR CMAKE_BUILD_TYPE STREQUAL "MinSizeRel")
+    option(FILAMENT_ENABLE_PERFETTO "Enable perfetto SDK on Android" OFF)
+else()
+    option(FILAMENT_ENABLE_PERFETTO "Enable perfetto SDK on Android" ON)
+endif()
+if (FILAMENT_ENABLE_PERFETTO)
+    add_definitions(-DFILAMENT_ENABLE_PERFETTO)
+endif()
+
 # By default, build with Vulkan support on desktop platforms, although clients must request to use
 # it at run time.
 if (WIN32 OR WEBGL OR IOS)
@@ -633,7 +642,7 @@ endif()
 # With WebGPU, Tint does not support ClipDistance which is used in Stereo.  Mentioned in comment
 # https://github.com/google/dawn/blob/855d17b08abdf02f9142bf5a8f14d0ea088810a4/src/tint/lang/spirv/reader/ast_parser/function.cc#L4434
 if (FILAMENT_SUPPORTS_WEBGPU)
-    set(MATC_API_FLAGS ${MATC_API_FLAGS} -a webgpu --variant-filter=skinning,stereo)
+    set(MATC_API_FLAGS ${MATC_API_FLAGS} -a webgpu --variant-filter=stereo)
 endif()
 
 # Disable ESSL 1.0 code generation.

CODE_STYLE.md

@@ -20,7 +20,7 @@ The guiding principles of the filament code style and code formatting can be res
 - class access modifiers are not indented
 - last line of `.cpp` or `.h` file must be an empty line
 
-```
+```c++
 for (int i = 0; i < max; i++) {
 }
 
@@ -73,12 +73,24 @@ src/data.inc
 - `public` class attributes *are not* prefixed
 - class attributes and methods are lower camelcase
 
-```
+```c++
 extern int gGlobalWarming;
 
 class FooBar {
 public:
-    void methodName();
+    FooBar(int attributeName, int sizeInBytes)
+            : mAttributeName(attributeName),
+              sizeInBytes(sizeInBytes) {}
+
+    void reallyLongMethodNameWithLotsOfArguments(bool argument1,
+            int someSecondArgument, int bestArgument) {
+        std::pair<bool, int> pair = {
+            argument1,
+            argument2,
+        };
+        // etc
+    }
+
     int sizeInBytes;
 private:
     int mAttributeName;
@@ -97,7 +109,7 @@ private:
 - always include the copyright notice at the top of every file
 - make sure the date is correct
 
-```
+```c++
 /*
  * Copyright (C) 2018 The Android Open Source Project
  *
@@ -139,7 +151,7 @@ conversely containers and algorithms are not allowed. There are exceptions such
 
 *Sorting the headers is important to help catching missing `#include` directives.*
 
-```
+```c++
 /*
  * Copyright (C) 2018 The Android Open Source Project
  *
@@ -183,7 +195,7 @@ conversely containers and algorithms are not allowed. There are exceptions such
 ### Misc
 
 - Use `auto` only when the type appears on the same line or with iterators and lambdas.
-```
+```c++
 auto foo = new Foo();
 for (auto& i : collection) { }
 ```

NEW_RELEASE_NOTES.md

@@ -1,7 +1,6 @@
 # Filament Release Notes log
 
 **If you are merging a PR into main**: please add the release note below, under the *Release notes
-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).

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.64.1'
+    implementation 'com.google.android.filament:filament-android:1.66.0'
 }
 ```
 
@@ -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.64.1'
+pod 'Filament', '~> 1.66.0'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,6 +7,37 @@ 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.66.1
+
+- filamat: Removed a dependency on Glslang's deprecated SPIR-V remapper.
+  The functionality is already implemented by calling the CanonicalizeIds pass
+  in the SPIRV-Tools, and should be a non-functional change.
+
+## v1.66.0
+
+- materials: include default values of spec constants in material metadata [⚠️ **Recompile Materials**]
+
+## v1.65.4
+
+
+## v1.65.3
+
+
+## v1.65.2
+
+
+## v1.65.1
+
+- `setFrameScheduledCallback` now works on all backends (frame presentation scheduling is still only
+  available on Metal). Non-Metal backends can use the callback to be notified when Filament has
+  finished processing a frame on the CPU.
+- materials: added `getEyeFromViewMatrix()` for vertex shader [⚠️ **Recompile Materials**]
+- matc: make `--workarounds=none` the default [**Recompile Materials to take effect**]
+
+## v1.65.0
+
+lighting: the intermediate froxel record buffer is now dynamically sized [⚠️ **New Material Version**]
+
 ## v1.64.1
 
 - Update CMake minimum version to 3.22.1

android/build.gradle

@@ -178,6 +178,8 @@ nexusPublishing {
     repositories {
         sonatype {
             stagingProfileId = '9a75a224a4f17b'
+            nexusUrl.set(uri("https://ossrh-staging-api.central.sonatype.com/service/local/"))
+            snapshotRepositoryUrl.set(uri("https://central.sonatype.com/repository/maven-snapshots/"))
         }
     }
 }

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

@@ -146,7 +146,7 @@ abstract class MaterialCompiler extends TaskWithBinary {
                         .gradleProperty("com.google.android.filament.include-webgpu")
                         .forUseAtConfigurationTime().present
                 if (include_webgpu) {
-                    matcArgs += ['-a', 'webgpu', '--variant-filter=skinning,stereo']
+                    matcArgs += ['-a', 'webgpu', '--variant-filter=stereo']
                 }
 
                 def mat_no_opt = providers

android/filamat-android/CMakeLists.txt

@@ -1,6 +1,8 @@
 cmake_minimum_required(VERSION 3.19)
 project(filamat-android)
 
+set(CMAKE_CXX_STANDARD 20)
+
 option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
 
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})

android/filament-android/CMakeLists.txt

@@ -7,6 +7,8 @@ option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
 option(FILAMENT_DISABLE_MATOPT "Disables material optimizations" OFF)
 option(FILAMENT_SUPPORTS_WEBGPU "Enables WebGPU on Android" OFF)
 
+set(CMAKE_CXX_STANDARD 20)
+
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})
 
 add_library(filament STATIC IMPORTED)
@@ -130,6 +132,14 @@ add_library(filament-jni SHARED
     ../common/NioUtils.cpp
 )
 
+target_include_directories(filament-jni PRIVATE
+        ..
+        ${FILAMENT_DIR}/include
+        ../../filament/backend/include
+        ../../third_party/robin-map
+        ../../third_party/perfetto
+        ../../libs/utils/include)
+
 # Ordering is significant in the following list. The PRIVATE qualifier prevents transitive deps.
 target_link_libraries(filament-jni
     PRIVATE filament-generatePrefilterMipmap
@@ -144,29 +154,21 @@ target_link_libraries(filament-jni
     PRIVATE android
     PRIVATE jnigraphics
     PRIVATE utils
-    PRIVATE perfetto
-    PRIVATE abseil
+    PRIVATE perfetto    # needed only when FILAMENT_ENABLE_PERFETTO is defined
+    PRIVATE abseil      # needed only when FILAMENT_USE_ABSEIL_LOGGING is defined
     PRIVATE zstd
 
     # libgeometry is PUBLIC because gltfio uses it.
     PUBLIC geometry
 
-    $<$<STREQUAL:${FILAMENT_ENABLE_FGVIEWER},ON>:fgviewer>
-    $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:matdbg>
-    $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:filamat>
-    $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:bluevk>
-    $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:vkshaders>
-    $<$<STREQUAL:${FILAMENT_SUPPORTS_WEBGPU},ON>:webgpu_dawn>
-    $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:smol-v>
+    PRIVATE $<$<STREQUAL:${FILAMENT_ENABLE_FGVIEWER},ON>:fgviewer>
+    PRIVATE $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:matdbg>
+    PRIVATE $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:filamat>
+    PRIVATE $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:bluevk>
+    PRIVATE $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:vkshaders>
+    PRIVATE $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:smol-v>
+    PRIVATE $<$<STREQUAL:${FILAMENT_SUPPORTS_WEBGPU},ON>:webgpu_dawn>
 )
 
-target_include_directories(filament-jni PRIVATE
-        ..
-        ${FILAMENT_DIR}/include
-        ../../filament/backend/include
-        ../../third_party/robin-map
-        ../../third_party/perfetto
-        ../../libs/utils/include)
-
 # Force a relink when the version script is changed:
 set_target_properties(filament-jni PROPERTIES LINK_DEPENDS ${VERSION_SCRIPT})

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

@@ -450,6 +450,13 @@ Java_com_google_android_filament_RenderableManager_nGetPrimitiveCount(JNIEnv*, j
     return (jint) rm->getPrimitiveCount((RenderableManager::Instance) i);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_RenderableManager_nGetInstanceCount(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    return (jint) rm->getInstanceCount((RenderableManager::Instance) i);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetMaterialInstanceAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex, jlong nativeMaterialInstance) {

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

@@ -208,3 +208,19 @@ Java_com_google_android_filament_Renderer_nSetVsyncTime(JNIEnv *, jclass,
     Renderer *renderer = (Renderer *) nativeRenderer;
     renderer->setVsyncTime(steadyClockTimeNano);
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Renderer_nSkipNextFrames(JNIEnv *, jclass ,
+    jlong nativeRenderer, jint frameCount) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    renderer->skipNextFrames(frameCount);
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Renderer_nGetFrameToSkipCount(JNIEnv *, jclass ,
+    jlong nativeRenderer) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    return renderer->getFrameToSkipCount();
+}

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

@@ -28,9 +28,8 @@ Java_com_google_android_filament_SwapChain_nSetFrameCompletedCallback(JNIEnv* en
         jlong nativeSwapChain, jobject handler, jobject runnable) {
     SwapChain* swapChain = (SwapChain*) nativeSwapChain;
     auto* callback = JniCallback::make(env, handler, runnable);
-    swapChain->setFrameCompletedCallback(nullptr, [callback](SwapChain* swapChain) {
-        JniCallback::postToJavaAndDestroy(callback);
-    });
+    swapChain->setFrameCompletedCallback(callback->getHandler(),
+            [callback](SwapChain* swapChain) { JniCallback::postToJavaAndDestroy(callback); });
 }
 
 extern "C" JNIEXPORT jboolean JNICALL
@@ -40,9 +39,35 @@ Java_com_google_android_filament_SwapChain_nIsSRGBSwapChainSupported(
     return (jboolean)SwapChain::isSRGBSwapChainSupported(*engine);
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_SwapChain_nIsMSAASwapChainSupported(
+        JNIEnv *, jclass, jlong nativeEngine, jint samples) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jboolean)SwapChain::isMSAASwapChainSupported(*engine, samples);
+}
+
 extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_SwapChain_nIsProtectedContentSupported(
         JNIEnv *, jclass, jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
     return (jboolean)SwapChain::isProtectedContentSupported(*engine);
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_SwapChain_nSetFrameScheduledCallback(JNIEnv* env, jclass,
+        jlong nativeSwapChain, jobject handler, jobject runnable) {
+    SwapChain* swapChain = (SwapChain*) nativeSwapChain;
+    auto* callback = JniCallback::make(env, handler, runnable);
+    swapChain->setFrameScheduledCallback(callback->getHandler(),
+            [callback](backend::PresentCallable) {
+                // Ignore PresentCallable, which is only meaningful with the Metal backend.
+                JniCallback::postToJavaAndDestroy(callback);
+            });
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_SwapChain_nIsFrameScheduledCallbackSet(
+        JNIEnv *, jclass, jlong nativeSwapChain) {
+    SwapChain* swapChain = (SwapChain*) nativeSwapChain;
+    return (jboolean)swapChain->isFrameScheduledCallbackSet();
+}

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

@@ -356,6 +356,7 @@ Java_com_google_android_filament_View_nSetFogOptions(JNIEnv *, jclass , jlong na
     view->setFogOptions(options);
 }
 
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetBlendMode(JNIEnv *, jclass , jlong nativeView, jint blendMode) {
     View* view = (View*) nativeView;
@@ -554,3 +555,20 @@ Java_com_google_android_filament_View_nClearFrameHistory(JNIEnv *env, jclass cla
     Engine *engine = (Engine *) nativeEngine;
     view->clearFrameHistory(*engine);
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetChannelDepthClearEnabled(JNIEnv *, jclass ,
+        jlong nativeView, jint channel, jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setChannelDepthClearEnabled((uint8_t) channel, (bool) enabled);
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsChannelDepthClearEnabled(JNIEnv *env, jclass clazz,
+        jlong nativeView, jint channel) {
+    // TODO: implement nIsChannelDepthClearEnabled()
+    View* view = (View*) nativeView;
+    return (jboolean)view->isChannelDepthClearEnabled((uint8_t) channel);
+}

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

@@ -332,7 +332,7 @@ public class RenderableManager {
         }
 
         /**
-         * Set the channel this renderable is associated to. There can be 4 channels.
+         * Set the channel this renderable is associated to. There can be 8 channels.
          *
          * <p>All renderables in a given channel are rendered together, regardless of anything else.
          * They are sorted as usual within a channel.</p>
@@ -342,7 +342,7 @@ public class RenderableManager {
          * <p>Channels 0 and 1 may not have render primitives using a material with `refractionType`
          * set to `screenspace`.</p>
          *
-         * @param channel clamped to the range [0..3], defaults to 2.
+         * @param channel clamped to the range [0..7], defaults to 2.
          *
          * @return Builder reference for chaining calls.
          *
@@ -351,7 +351,7 @@ public class RenderableManager {
          * @see RenderableManager::setBlendOrderAt()
          */
         @NonNull
-        public Builder channel(@IntRange(from = 0, to = 3) int channel) {
+        public Builder channel(@IntRange(from = 0, to = 7) int channel) {
             nBuilderChannel(mNativeBuilder, channel);
             return this;
         }
@@ -730,7 +730,7 @@ public class RenderableManager {
      *
      * @see Builder#channel
      */
-    public void setChannel(@EntityInstance int i, @IntRange(from = 0, to = 3) int channel) {
+    public void setChannel(@EntityInstance int i, @IntRange(from = 0, to = 7) int channel) {
         nSetChannel(mNativeObject, i, channel);
     }
 
@@ -851,6 +851,14 @@ public class RenderableManager {
         return nGetPrimitiveCount(mNativeObject, i);
     }
 
+    /**
+     * Gets the immutable number of instances in the given renderable.
+     */
+    @IntRange(from = 0)
+    public int getInstanceCount(@EntityInstance int i) {
+        return nGetInstanceCount(mNativeObject, i);
+    }
+
     /**
      * Changes the material instance binding for the given primitive.
      *
@@ -1018,6 +1026,7 @@ public class RenderableManager {
     private static native boolean nIsShadowReceiver(long nativeRenderableManager, int i);
     private static native void nGetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float[] center, float[] halfExtent);
     private static native int nGetPrimitiveCount(long nativeRenderableManager, int i);
+    private static native int nGetInstanceCount(long nativeRenderableManager, int i);
     private static native void nSetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex, long nativeMaterialInstance);
     private static native void nClearMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);

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

@@ -732,6 +732,22 @@ public class Renderer {
         nResetUserTime(getNativeObject());
     }
 
+    /**
+     * Requests the next frameCount frames to be skipped. For Debugging.
+     * @param frameCount number of frames to skip.
+     */
+    public void skipNextFrames(int frameCount) {
+        nSkipNextFrames(getNativeObject(), frameCount);
+    }
+
+    /**
+     * Remainder count of frame to be skipped
+     * @return remaining frames to be skipped
+     */
+    public int getFrameToSkipCount() {
+        return nGetFrameToSkipCount(getNativeObject());
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Renderer");
@@ -773,4 +789,7 @@ public class Renderer {
             float interval, float headRoomRatio, float scaleRate, int history);
     private static native void nSetClearOptions(long nativeRenderer,
             float r, float g, float b, float a, boolean clear, boolean discard);
+
+    private static native void nSkipNextFrames(long nativeObject, int frameCount);
+    private static native int nGetFrameToSkipCount(long nativeObject);
 }

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

@@ -97,6 +97,19 @@ public class SwapChain {
         return nIsSRGBSwapChainSupported(engine.getNativeObject());
     }
 
+    /**
+     * Return whether createSwapChain supports the CONFIG_MSAA_*_SAMPLES flag.
+     * The default implementation returns false.
+     *
+     * @param engine A reference to the filament Engine
+     * @param samples The number of samples
+     * @return true if CONFIG_MSAA_*_SAMPLES is supported, false otherwise.
+     * @see SwapChainFlags#CONFIG_MSAA_*_SAMPLES
+     */
+    public static boolean isMSAASwapChainSupported(@NonNull Engine engine, int samples) {
+        return nIsMSAASwapChainSupported(engine.getNativeObject(), samples);
+    }
+
     /**
      * @return the native <code>Object</code> this <code>SwapChain</code> was created from or null
      *         for a headless SwapChain.
@@ -126,6 +139,78 @@ public class SwapChain {
         nSetFrameCompletedCallback(getNativeObject(), handler, callback);
     }
 
+    /**
+     * FrameScheduledCallback is a callback function that notifies an application about the status
+     * of a frame after Filament has finished its processing.
+     *
+     * <p>
+     * The exact timing and semantics of this callback differ depending on the graphics backend in
+     * use.
+     * </p>
+     *
+     * <h3>Metal Backend</h3>
+     * <p>
+     * With the Metal backend, this callback signifies that Filament has completed all CPU-side
+     * processing for a frame and the frame is ready to be scheduled for presentation.
+     * </p>
+     *
+     * <p>
+     * Typically, Filament is responsible for scheduling the frame's presentation to the SwapChain.
+     * If a FrameScheduledCallback is set, however, the application bears the responsibility of
+     * scheduling the frame for presentation by calling the PresentCallable passed to the callback
+     * function. In this mode, Filament will not automatically schedule the frame for presentation.
+     * </p>
+     *
+     * <p>
+     * When using the Metal backend, if your application delays the call to the PresentCallable
+     * (e.g., by invoking it on a separate thread), you must ensure all PresentCallables have been
+     * called before shutting down the Filament Engine. You can guarantee this by calling
+     * Engine.flushAndWait() before Engine.shutdown(). This is necessary to ensure the Engine has
+     * a chance to clean up all memory related to frame presentation.
+     * </p>
+     *
+     * <h3>Other Backends (OpenGL, Vulkan, WebGPU)</h3>
+     * <p>
+     * On other backends, this callback serves as a notification that Filament has completed all
+     * CPU-side processing for a frame. Filament proceeds with its normal presentation logic
+     * automatically, and the PresentCallable passed to the callback is a no-op that can be safely
+     * ignored.
+     * </p>
+     *
+     * <h3>General Behavior</h3>
+     * <p>
+     * A FrameScheduledCallback can be set on an individual SwapChain through
+     * setFrameScheduledCallback. Each SwapChain can have only one callback set per frame. If
+     * setFrameScheduledCallback is called multiple times on the same SwapChain before
+     * Renderer.endFrame(), the most recent call effectively overwrites any previously set callback.
+     * </p>
+     *
+     * <p>
+     * The callback set by setFrameScheduledCallback is "latched" when Renderer.endFrame() is
+     * executed. At this point, the callback is fixed for the frame that was just encoded.
+     * Subsequent calls to setFrameScheduledCallback after endFrame() will apply to the next frame.
+     * </p>
+     *
+     * <p>
+     * Use setFrameScheduledCallback() (with default arguments) to unset the callback.
+     * </p>
+     *
+     * @param handler     A {@link java.util.concurrent.Executor Executor}.
+     * @param callback    The Runnable callback to invoke when frame processing is complete.
+     */
+    public void setFrameScheduledCallback(@NonNull Object handler, @NonNull Runnable callback) {
+        nSetFrameScheduledCallback(getNativeObject(), handler, callback);
+    }
+
+    /**
+     * Returns whether this SwapChain currently has a FrameScheduledCallback set.
+     *
+     * @return true, if the last call to setFrameScheduledCallback set a callback
+     */
+    public boolean isFrameScheduledCallbackSet() {
+        return nIsFrameScheduledCallbackSet(getNativeObject());
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed SwapChain");
@@ -138,6 +223,9 @@ public class SwapChain {
     }
 
     private static native void nSetFrameCompletedCallback(long nativeSwapChain, Object handler, Runnable callback);
+    private static native void nSetFrameScheduledCallback(long nativeSwapChain, Object handler, Runnable callback);
+    private static native boolean nIsFrameScheduledCallbackSet(long nativeSwapChain);
     private static native boolean nIsSRGBSwapChainSupported(long nativeEngine);
+    private static native boolean nIsMSAASwapChainSupported(long nativeEngine, int samples);
     private static native boolean nIsProtectedContentSupported(long nativeEngine);
 }

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

@@ -92,6 +92,15 @@ public final class SwapChainFlags {
      * The SwapChain contains protected content. Only supported when isProtectedContentSupported()
      * is true.
      */
-    public static final long CONFIG_PROTECTED_CONTENT   = 0x40;
-}
+    public static final long CONFIG_PROTECTED_CONTENT = 0x40;
 
+    /**
+     * Indicates that the SwapChain is configured to use Multi-Sample Anti-Aliasing (MSAA) with the
+     * given sample points within each pixel. Only supported when isMSAASwapChainSupported(4) is
+     * true.
+     *
+     * This is only supported by EGL(Android). Other GL platforms (GLX, WGL, etc) don't support it
+     * because the swapchain MSAA settings must be configured before window creation.
+     */
+    public static final long CONFIG_MSAA_4_SAMPLES = 0x80;
+}

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

@@ -231,7 +231,7 @@ public class View {
      *
      * <p>
      * The View does not take ownership of the Scene pointer. Before destroying a Camera, be sure
-     * to remove it from all assoicated Views.
+     * to remove it from all associated Views. If the camera isn't set, Renderer::render() will result in a no-op.
      * </p>
      *
      * @see #getCamera
@@ -291,6 +291,25 @@ public class View {
         return mViewport;
     }
 
+    /**
+     * Sets whether a channel must clear the depth buffer before all primitives are rendered.
+     * Channel depth clear is off by default for all channels.
+     * This is orthogonal to Renderer::setClearOptions().
+     * @param channel between 0 and 7
+     * @param enabled true to enable clear, false to disable
+     */
+    void setChannelDepthClearEnabled(@IntRange(from = 0, to = 7) int channel, boolean enabled) {
+        nSetChannelDepthClearEnabled(getNativeObject(), channel, enabled);
+    }
+
+    /**
+     * @param channel between 0 and 7
+     * @return true if this channel has depth clear enabled.
+     */
+    boolean isChannelDepthClearEnabled(@IntRange(from = 0, to = 7) int channel) {
+        return nIsChannelDepthClearEnabled(getNativeObject(), channel);
+    }
+
     /**
      * Sets the blending mode used to draw the view into the SwapChain.
      *
@@ -1318,6 +1337,8 @@ public class View {
             boolean lensFlare, boolean starburst, float chromaticAberration, int ghostCount, float ghostSpacing, float ghostThreshold, float haloThickness, float haloRadius, float haloThreshold);
     private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, long skyColorNativeObject, boolean enabled);
     private static native void nSetStereoscopicOptions(long nativeView, boolean enabled);
+    private static native void nSetChannelDepthClearEnabled(long nativeView, int channel, boolean enabled);
+    private static native boolean nIsChannelDepthClearEnabled(long nativeView, int channel);
     private static native void nSetBlendMode(long nativeView, int blendMode);
     private static native void nSetDepthOfFieldOptions(long nativeView, float cocScale, float maxApertureDiameter, boolean enabled, int filter,
             boolean nativeResolution, int foregroundRingCount, int backgroundRingCount, int fastGatherRingCount, int maxForegroundCOC, int maxBackgroundCOC);
@@ -1615,7 +1636,7 @@ public class View {
          *
          *  This value is used as a tint instead, when fogColorFromIbl is enabled.
          *
-         *  @see fogColorFromIbl
+         *  @see #fogColorFromIbl
          */
         @NonNull @Size(min = 3)
         public float[] color = {1.0f, 1.0f, 1.0f};
@@ -1656,7 +1677,7 @@ public class View {
          *
          * `fogColorFromIbl` is ignored when skyTexture is specified.
          *
-         * @see skyColor
+         * @see #skyColor
          */
         public boolean fogColorFromIbl = false;
         /**
@@ -1674,7 +1695,7 @@ public class View {
          * In `linearFog` mode mipmap level 0 is always used.
          *
          * @see Texture
-         * @see fogColorFromIbl
+         * @see #fogColorFromIbl
          */
         @Nullable
         public Texture skyColor = null;
@@ -1796,7 +1817,8 @@ public class View {
     /**
      * Structure used to set the precision of the color buffer and related quality settings.
      *
-     * @see setRenderQuality, getRenderQuality
+     * @see #setRenderQuality
+     * @see #getRenderQuality
      */
     public static class RenderQuality {
         /**
@@ -1814,7 +1836,7 @@ public class View {
 
     /**
      * Options for screen space Ambient Occlusion (SSAO) and Screen Space Cone Tracing (SSCT)
-     * @see setAmbientOcclusionOptions()
+     * @see #setAmbientOcclusionOptions
      */
     public static class AmbientOcclusionOptions {
         public enum AmbientOcclusionType {
@@ -1949,12 +1971,24 @@ public class View {
          * Ground Truth-base Ambient Occlusion (GTAO) options
          */
         public float gtaoThicknessHeuristic = 0.004f;
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public boolean gtaoUseVisibilityBitmasks = false;
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public float gtaoConstThickness = 0.5f;
+        /**
+         * Ground Truth-base Ambient Occlusion (GTAO) options
+         */
+        public boolean gtaoLinearThickness = false;
 
     }
 
     /**
      * Options for Multi-Sample Anti-aliasing (MSAA)
-     * @see setMultiSampleAntiAliasingOptions()
+     * @see #setMultiSampleAntiAliasingOptions
      */
     public static class MultiSampleAntiAliasingOptions {
         /**
@@ -1984,7 +2018,7 @@ public class View {
      * `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.
      *
-     * @see setTemporalAntiAliasingOptions()
+     * @see #setTemporalAntiAliasingOptions
      */
     public static class TemporalAntiAliasingOptions {
         public enum BoxType {
@@ -2086,7 +2120,7 @@ public class View {
 
     /**
      * Options for Screen-space Reflections.
-     * @see setScreenSpaceReflectionsOptions()
+     * @see #setScreenSpaceReflectionsOptions
      */
     public static class ScreenSpaceReflectionsOptions {
         /**
@@ -2120,7 +2154,9 @@ public class View {
 
     /**
      * List of available post-processing anti-aliasing techniques.
-     * @see setAntiAliasing, getAntiAliasing, setSampleCount
+     * @see #setAntiAliasing
+     * @see #getAntiAliasing
+     * @see #setSampleCount
      */
     public enum AntiAliasing {
         /**
@@ -2149,7 +2185,7 @@ public class View {
 
     /**
      * List of available shadow mapping techniques.
-     * @see setShadowType
+     * @see #setShadowType
      */
     public enum ShadowType {
         /**
@@ -2173,7 +2209,7 @@ public class View {
 
     /**
      * View-level options for VSM Shadowing.
-     * @see setVsmShadowOptions()
+     * @see #setVsmShadowOptions
      * @warning This API is still experimental and subject to change.
      */
     public static class VsmShadowOptions {
@@ -2214,7 +2250,7 @@ public class View {
 
     /**
      * View-level options for DPCF and PCSS Shadowing.
-     * @see setSoftShadowOptions()
+     * @see #setSoftShadowOptions
      * @warning This API is still experimental and subject to change.
      */
     public static class SoftShadowOptions {

android/filament-utils-android/CMakeLists.txt

@@ -1,6 +1,14 @@
 cmake_minimum_required(VERSION 3.19)
 project(filament-utils-android)
 
+option(FILAMENT_SUPPORTS_VULKAN "Enables Vulkan on Android" OFF)
+option(FILAMENT_ENABLE_FGVIEWER "Enables Frame Graph Viewer" OFF)
+option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
+option(FILAMENT_DISABLE_MATOPT "Disables material optimizations" OFF)
+option(FILAMENT_SUPPORTS_WEBGPU "Enables WebGPU on Android" OFF)
+
+set(CMAKE_CXX_STANDARD 20)
+
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})
 set(IMAGEIO_DIR ../../libs/imageio)
 
@@ -30,7 +38,16 @@ add_library(iblprefilter STATIC IMPORTED)
 set_target_properties(iblprefilter PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilament-iblprefilter.a)
 
-set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.map")
+add_library(utils STATIC IMPORTED)
+set_target_properties(utils PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
+
+add_library(perfetto STATIC IMPORTED)
+set_target_properties(perfetto PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libperfetto.a)
+
+set(VERSION_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.map")
+set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${VERSION_SCRIPT}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 
 add_library(filament-utils-jni SHARED
@@ -53,22 +70,25 @@ add_library(filament-utils-jni SHARED
 target_compile_definitions(filament-utils-jni PUBLIC IMAGEIO_LITE=1)
 
 target_include_directories(filament-utils-jni PRIVATE
-        ${FILAMENT_DIR}/include
         ..
+        ${FILAMENT_DIR}/include
         ../../filament/backend/include
         ${IMAGEIO_DIR}/include
         ../../libs/utils/include)
 
-set_target_properties(filament-utils-jni PROPERTIES LINK_DEPENDS
-        ${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.symbols)
+set_target_properties(filament-utils-jni PROPERTIES LINK_DEPENDS ${VERSION_SCRIPT})
 
 # The ordering in the following list is important because CMake does not have dependency information.
 target_link_libraries(filament-utils-jni
-        gltfio-jni
-        civetweb
-        camutils
-        iblprefilter
-        image
-        ktxreader
-        viewer
+        PRIVATE gltfio-jni
+        PRIVATE civetweb
+        PRIVATE camutils
+        PRIVATE iblprefilter
+        PRIVATE image
+        PRIVATE filament-jni
+        PRIVATE ktxreader
+        PRIVATE viewer
+        PRIVATE log
+        PRIVATE utils
+        PRIVATE perfetto        # needed only when FILAMENT_ENABLE_PERFETTO is defined
 )

android/gltfio-android/CMakeLists.txt

@@ -1,20 +1,27 @@
 cmake_minimum_required(VERSION 3.19)
 project(gltfio-android)
 
+option(FILAMENT_SUPPORTS_VULKAN "Enables Vulkan on Android" OFF)
+option(FILAMENT_ENABLE_FGVIEWER "Enables Frame Graph Viewer" OFF)
+option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
+option(FILAMENT_DISABLE_MATOPT "Disables material optimizations" OFF)
+option(FILAMENT_SUPPORTS_WEBGPU "Enables WebGPU on Android" OFF)
+
+set(CMAKE_CXX_STANDARD 20)
+
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})
-set(GLTFIO_DIR ../../libs/gltfio)
 set(DRACO_DIR ../../third_party/draco)
 
 add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../filament-android ${CMAKE_CURRENT_BINARY_DIR}/filament-android)
 
+add_library(gltfio_core STATIC IMPORTED)
+set_target_properties(gltfio_core PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libgltfio_core.a)
+
 add_library(dracodec STATIC IMPORTED)
 set_target_properties(dracodec PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libdracodec.a)
 
-add_library(meshoptimizer STATIC IMPORTED)
-set_target_properties(meshoptimizer PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libmeshoptimizer.a)
-
 add_library(ktxreader STATIC IMPORTED)
 set_target_properties(ktxreader PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libktxreader.a)
@@ -27,10 +34,6 @@ add_library(basis_transcoder STATIC IMPORTED)
 set_target_properties(basis_transcoder PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbasis_transcoder.a)
 
-add_library(zstd STATIC IMPORTED)
-set_target_properties(zstd PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libzstd.a)
-
 add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
@@ -47,60 +50,11 @@ add_library(uberarchive STATIC IMPORTED)
 set_target_properties(uberarchive PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberarchive.a)
 
-set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map")
+set(VERSION_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map")
+set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${VERSION_SCRIPT}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")
 
 set(GLTFIO_SRCS
-        ${GLTFIO_DIR}/include/gltfio/Animator.h
-        ${GLTFIO_DIR}/include/gltfio/AssetLoader.h
-        ${GLTFIO_DIR}/include/gltfio/FilamentAsset.h
-        ${GLTFIO_DIR}/include/gltfio/FilamentInstance.h
-        ${GLTFIO_DIR}/include/gltfio/MaterialProvider.h
-        ${GLTFIO_DIR}/include/gltfio/NodeManager.h
-        ${GLTFIO_DIR}/include/gltfio/TrsTransformManager.h
-        ${GLTFIO_DIR}/include/gltfio/ResourceLoader.h
-        ${GLTFIO_DIR}/include/gltfio/TextureProvider.h
-        ${GLTFIO_DIR}/include/gltfio/math.h
-
-        ${GLTFIO_DIR}/src/ArchiveCache.cpp
-        ${GLTFIO_DIR}/src/ArchiveCache.h
-        ${GLTFIO_DIR}/src/Animator.cpp
-        ${GLTFIO_DIR}/src/AssetLoader.cpp
-        ${GLTFIO_DIR}/src/DependencyGraph.cpp
-        ${GLTFIO_DIR}/src/DependencyGraph.h
-        ${GLTFIO_DIR}/src/DracoCache.cpp
-        ${GLTFIO_DIR}/src/DracoCache.h
-        ${GLTFIO_DIR}/src/FFilamentAsset.h
-        ${GLTFIO_DIR}/src/FFilamentInstance.h
-        ${GLTFIO_DIR}/src/FilamentAsset.cpp
-        ${GLTFIO_DIR}/src/FilamentInstance.cpp
-        ${GLTFIO_DIR}/src/FNodeManager.h
-        ${GLTFIO_DIR}/src/FTrsTransformManager.h
-        ${GLTFIO_DIR}/src/GltfEnums.h
-        ${GLTFIO_DIR}/src/Ktx2Provider.cpp
-        ${GLTFIO_DIR}/src/MaterialProvider.cpp
-        ${GLTFIO_DIR}/src/NodeManager.cpp
-        ${GLTFIO_DIR}/src/TrsTransformManager.cpp
-        ${GLTFIO_DIR}/src/ResourceLoader.cpp
-        ${GLTFIO_DIR}/src/StbProvider.cpp
-        ${GLTFIO_DIR}/src/TangentsJob.cpp
-        ${GLTFIO_DIR}/src/TangentsJob.h
-        ${GLTFIO_DIR}/src/UbershaderProvider.cpp
-        ${GLTFIO_DIR}/src/Utility.cpp
-        ${GLTFIO_DIR}/src/Utility.h
-        ${GLTFIO_DIR}/src/Wireframe.cpp
-        ${GLTFIO_DIR}/src/Wireframe.h
-        ${GLTFIO_DIR}/src/downcast.h
-        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.cpp
-        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.h
-        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.cpp
-        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.h
-        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.cpp
-        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.h
-        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.cpp
-        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.h
-
-
         src/main/cpp/Animator.cpp
         src/main/cpp/AssetLoader.cpp
         src/main/cpp/FilamentAsset.cpp
@@ -118,24 +72,38 @@ set(GLTFIO_SRCS
 set(GLTFIO_INCLUDE_DIRS
         ..
         ${FILAMENT_DIR}/include
-        ../../filament/backend/include
+        ${FILAMENT_DIR}/backend/include
         ../../libs/gltfio/include
-        ../../third_party/zstd/lib
         ../../third_party/cgltf
-        ../../third_party/meshoptimizer/src
         ../../third_party/robin-map
         ../../third_party/stb
-        ../../third_party/perfetto
         ../../libs/utils/include
         ../../libs/ktxreader/include
 )
 
 add_library(gltfio-jni SHARED ${GLTFIO_SRCS})
-target_include_directories(gltfio-jni PRIVATE ${GLTFIO_INCLUDE_DIRS})
-set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.symbols)
-set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map)
-target_link_libraries(gltfio-jni filament-jni utils perfetto uberzlib log stb ktxreader basis_transcoder zstd uberarchive)
-target_link_libraries(gltfio-jni dracodec meshoptimizer)
+
 target_compile_definitions(gltfio-jni PUBLIC GLTFIO_DRACO_SUPPORTED=1)
+
+target_include_directories(gltfio-jni PRIVATE ${GLTFIO_INCLUDE_DIRS})
 target_include_directories(gltfio-jni PRIVATE ${DRACO_DIR}/src)
 target_include_directories(gltfio-jni PRIVATE ${DRACO_DIR}/tnt)
+
+# Force a relink when the version script is changed:
+set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS
+        "${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.symbols;${VERSION_SCRIPT}")
+
+# The ordering in the following list is important because CMake does not have dependency information.
+target_link_libraries(gltfio-jni
+        PRIVATE gltfio_core
+        PRIVATE ktxreader
+        PUBLIC filament-jni
+        PRIVATE stb
+        PRIVATE basis_transcoder
+        PRIVATE uberarchive
+        PRIVATE dracodec
+        PRIVATE utils
+        PRIVATE uberzlib
+        PRIVATE perfetto        # needed only when FILAMENT_ENABLE_PERFETTO is defined
+        PRIVATE log             # needed only when perfetto above is used
+)

android/gradle.properties

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

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

@@ -24,7 +24,7 @@ android {
 
     compileSdkVersion versions.compileSdk
     defaultConfig {
-        applicationId "com.google.android.filament.hellocamera"
+        applicationId "com.google.android.filament.hellocam"
         minSdkVersion 23
         targetSdkVersion versions.targetSdk
     }

build.sh

@@ -75,6 +75,8 @@ function print_help {
     echo "    -S type"
     echo "        Enable stereoscopic rendering where type is one of [instanced|multiview]. This is only"
     echo "        meant for building the samples."
+    echo "    -P"
+    echo "        Enable perfetto traces on Android. Disabled by default on the Release build, enabled otherwise."
     echo ""
     echo "Build types:"
     echo "    release"
@@ -204,6 +206,7 @@ MATOPT_GRADLE_OPTION=""
 
 ASAN_UBSAN_OPTION=""
 COVERAGE_OPTION=""
+ENABLE_PERFETTO=""
 
 BACKEND_DEBUG_FLAG_OPTION=""
 
@@ -413,6 +416,7 @@ function build_android_target {
             ${WEBGPU_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
             ${STEREOSCOPIC_OPTION} \
+            ${ENABLE_PERFETTO} \
             ../..
         ln -sf "out/cmake-android-${lc_target}-${arch}/compile_commands.json" \
            ../../compile_commands.json
@@ -806,7 +810,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:" opt; do
+while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do
     case ${opt} in
         h)
             print_help
@@ -954,6 +958,9 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:" opt; do
         V)  COVERAGE_OPTION="-DFILAMENT_ENABLE_COVERAGE=ON"
             echo "Enabled coverage"
             ;;
+        P)  ENABLE_PERFETTO="-DFILAMENT_ENABLE_PERFETTO=ON"
+            echo "Enabled perfetto"
+            ;;
         x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
             ;;
         S)  case $(echo "${OPTARG}" | tr '[:upper:]' '[:lower:]') in

build/common/close-sonatype-staging-repository.py

@@ -0,0 +1,349 @@
+#!/usr/bin/env python3
+
+# 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.
+
+"""
+This script automates the process of closing a Sonatype OSSRH staging repository.
+
+To run the script:
+    python3 ./close-sonatype-staging-repository.py
+
+To run the embedded unit tests:
+    python3 ./close-sonatype-staging-repository.py test
+"""
+
+import sys
+import os
+import base64
+import json
+import pathlib
+import unittest
+import io
+from unittest import mock
+import urllib.request
+import urllib.error
+
+PROPERTIES_PATH = pathlib.Path.home() / ".gradle" / "gradle.properties"
+API_BASE_URL = "https://ossrh-staging-api.central.sonatype.com/manual"
+
+def get_gradle_credentials(file_path: pathlib.Path) -> (str, str):
+    """
+    Reads sonatypeUsername and sonatypePassword from the properties file.
+    """
+    if not file_path.exists():
+        print(f"Error: Properties file not found at {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    username = None
+    password = None
+
+    try:
+        with open(file_path, 'r') as f:
+            for line in f:
+                line = line.strip()
+
+                # Ignore blank lines and comments
+                if not line or line.startswith("#"):
+                    continue
+
+                if line.startswith("sonatypeUsername="):
+                    username = line.split("=", 1)[1].strip()
+                elif line.startswith("sonatypePassword="):
+                    password = line.split("=", 1)[1].strip()
+
+        if not username or not password:
+            print(f"Error: 'sonatypeUsername' or 'sonatypePassword' not found in {file_path}", file=sys.stderr)
+            sys.exit(1)
+
+        return username, password
+
+    except Exception as e:
+        print(f"Error reading properties file: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+def generate_auth_token(username: str, password: str) -> str:
+    """
+    Generates a Base64 encoded auth token from username and password.
+    """
+    auth_string = f"{username}:{password}"
+    auth_bytes = auth_string.encode('utf-8')
+    token_bytes = base64.b64encode(auth_bytes)
+    return token_bytes.decode('utf-8')
+
+
+def find_staging_repository(token: str) -> str:
+    """
+    Finds the 'open' staging repository key from the Sonatype API.
+    """
+    print("Searching for staging repository...")
+
+    url = f"{API_BASE_URL}/search/repositories"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json"
+    }
+
+    req = urllib.request.Request(url, headers=headers, method="GET")
+
+    try:
+        with urllib.request.urlopen(req) as response:
+            response_body = response.read().decode('utf-8')
+            data = json.loads(response_body)
+
+        repositories = data.get("repositories", [])
+
+        open_repositories = list(filter(lambda repo: repo.get("state") == "open", repositories))
+
+        if len(open_repositories) == 0:
+            print("Error: No 'open' staging repositories found.", file=sys.stderr)
+            sys.exit(1)
+
+        if len(open_repositories) > 1:
+            print(f"Error: Expected 1 'open' repository, but found {len(repositories)}.", file=sys.stderr)
+            sys.exit(1)
+
+        repo_key = open_repositories[0].get("key")
+        if not repo_key:
+            print("Error: Repository found, but it has no 'key'.", file=sys.stderr)
+            sys.exit(1)
+
+        return repo_key
+
+    except urllib.error.HTTPError as e:
+        # Handle HTTP errors (e.g., 401 Unauthorized, 404 Not Found, 500 Server Error)
+        print(f"Error during repository search: HTTP {e.code} {e.reason}", file=sys.stderr)
+        try:
+            # Try to read the error response body for more context
+            error_body = e.read().decode('utf-8')
+            print(f"Response body: {error_body}", file=sys.stderr)
+        except Exception:
+            pass  # Ignore if we can't read the body
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        # Handle network errors (e.g., connection refused)
+        print(f"Error during repository search: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+    except json.JSONDecodeError:
+        print("Error: Failed to decode JSON response from server.", file=sys.stderr)
+        sys.exit(1)
+
+
+def close_staging_repository(token: str, repo_key: str):
+    """
+    Closes (promotes) the staging repository with the given key.
+    """
+    print(f"Attempting to close staging repository: {repo_key}")
+
+    url = f"{API_BASE_URL}/upload/repository/{repo_key}"
+    headers = {"Authorization": f"Bearer {token}"}
+
+    req = urllib.request.Request(url, headers=headers, method="POST")
+
+    try:
+        with urllib.request.urlopen(req) as response:
+            print(f"Successfully submitted request. Server responded with: {response.status} {response.reason}")
+            print("It may take a few moments to process.")
+
+    except urllib.error.HTTPError as e:
+        print(f"Error closing repository: HTTP {e.code} {e.reason}", file=sys.stderr)
+        try:
+            error_body = e.read().decode('utf-8')
+            print(f"Response body: {error_body}", file=sys.stderr)
+        except Exception:
+            pass
+        sys.exit(1)
+    except urllib.error.URLError as e:
+        print(f"Error closing repository: {e.reason}", file=sys.stderr)
+        sys.exit(1)
+
+
+def main():
+    username, password = get_gradle_credentials(PROPERTIES_PATH)
+    token = generate_auth_token(username, password)
+    print("Successfully generated auth token.")
+
+    repo_key = find_staging_repository(token)
+    print(f"Found staging repository: {repo_key}")
+
+    close_staging_repository(token, repo_key)
+
+    print("\nScript completed successfully.")
+
+
+# --- Unit Tests ---
+
+class TestSonatypeScript(unittest.TestCase):
+
+    @mock.patch('pathlib.Path.exists', return_value=True)
+    @mock.patch('builtins.open', new_callable=mock.mock_open,
+              read_data="# This is a comment\nsonatypeUsername=testuser\n\nsonatypePassword=testpass\nother=data")
+    def test_get_gradle_credentials_success(self, mock_file, mock_exists):
+        """Tests successful credential parsing, ignoring comments."""
+        user, pw = get_gradle_credentials(pathlib.Path("/fake/path"))
+        self.assertEqual(user, "testuser")
+        self.assertEqual(pw, "testpass")
+
+    @mock.patch('pathlib.Path.exists', return_value=False)
+    def test_get_gradle_credentials_no_file(self, mock_exists):
+        """Tests error exit when file is missing."""
+        with self.assertRaises(SystemExit) as cm:
+            get_gradle_credentials(pathlib.Path("/fake/path"))
+
+    @mock.patch('pathlib.Path.exists', return_value=True)
+    @mock.patch('builtins.open', new_callable=mock.mock_open, read_data="# Only comments\nsonatypeUsername=testuser")
+    def test_get_gradle_credentials_missing_key(self, mock_file, mock_exists):
+        """Tests error exit when a key is missing."""
+        with self.assertRaises(SystemExit) as cm:
+            get_gradle_credentials(pathlib.Path("/fake/path"))
+
+    def test_generate_auth_token(self):
+        """Tests the Base64 token encoding."""
+        token = generate_auth_token("foobar", "abc123")
+        # echo -n "foobar:abc123" | base64
+        self.assertEqual(token, "Zm9vYmFyOmFiYzEyMw==")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_success(self, mock_urlopen):
+        """Tests finding exactly one open repository."""
+        mock_response = mock.Mock()
+        mock_response.status = 200
+        mock_response.reason = "OK"
+        mock_response.read.return_value = json.dumps({
+            "repositories": [{"key": "test-repo-key-123", "state": "open"}]
+        }).encode('utf-8')
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        key = find_staging_repository("fake-token")
+        self.assertEqual(key, "test-repo-key-123")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_success(self, mock_urlopen):
+        """Tests finding exactly one open repository."""
+        mock_response = mock.Mock()
+        mock_response.status = 200
+        mock_response.reason = "OK"
+        mock_response.read.return_value = json.dumps({
+            "repositories": [{"key": "test-repo-key-123", "state": "open"}, {"key": "test-repo-key-456", "state": "closed"}]
+        }).encode('utf-8')
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        key = find_staging_repository("fake-token")
+        self.assertEqual(key, "test-repo-key-123")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_success(self, mock_urlopen):
+        """Tests error exit when only a closed repository is found."""
+        mock_response = mock.Mock()
+        mock_response.status = 200
+        mock_response.reason = "OK"
+        mock_response.read.return_value = json.dumps({
+            "repositories": [{"key": "test-repo-key-123", "state": "closed"}]
+        }).encode('utf-8')
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        with self.assertRaises(SystemExit) as cm:
+            key = find_staging_repository("fake-token")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_not_found(self, mock_urlopen):
+        """Tests error exit when zero repositories are found."""
+        mock_response = mock.Mock()
+        mock_response.status = 200
+        mock_response.read.return_value = json.dumps({"repositories": []}).encode('utf-8')
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        with self.assertRaises(SystemExit) as cm:
+            find_staging_repository("fake-token")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_too_many(self, mock_urlopen):
+        """Tests error exit when multiple open repositories are found."""
+        mock_response = mock.Mock()
+        mock_response.status = 200
+        mock_response.read.return_value = json.dumps({
+            "repositories": [{"key": "key1", "state": "open"}, {"key": "key2", "state": "open"}]
+        }).encode('utf-8')
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        with self.assertRaises(SystemExit) as cm:
+            find_staging_repository("fake-token")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_find_repository_http_error(self, mock_urlopen):
+        """Tests error exit on a network HTTP error."""
+        # Mock an HTTPError
+        mock_urlopen.side_effect = urllib.error.HTTPError(
+            url='http://fake.com',
+            code=401,
+            msg="Unauthorized",
+            hdrs={},
+            fp=io.BytesIO(b'{"error":"bad token"}')
+        )
+
+        with self.assertRaises(SystemExit) as cm:
+            find_staging_repository("fake-token")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_close_repository_success(self, mock_urlopen):
+        """Tests successful repository close."""
+        mock_response = mock.Mock()
+        mock_response.status = 202  # 202 Accepted is a common response for POST
+        mock_response.reason = "Accepted"
+        mock_urlopen.return_value.__enter__.return_value = mock_response
+
+        close_staging_repository("fake-token", "test-repo-key")
+
+        # Check that the request object was created correctly
+        called_request = mock_urlopen.call_args[0][0]
+        self.assertEqual(called_request.full_url, f"{API_BASE_URL}/upload/repository/test-repo-key")
+        self.assertEqual(called_request.method, "POST")
+        self.assertEqual(called_request.headers["Authorization"], "Bearer fake-token")
+
+    @mock.patch('urllib.request.urlopen')
+    def test_close_repository_http_error(self, mock_urlopen):
+        """Tests error exit on close network failure."""
+        mock_urlopen.side_effect = urllib.error.HTTPError(
+            url='http://fake.com',
+            code=500,
+            msg="Server Error",
+            hdrs={},
+            fp=io.BytesIO(b'{"error":"failed to close"}')
+        )
+
+        with self.assertRaises(SystemExit) as cm:
+            close_staging_repository("fake-token", "test-repo-key")
+
+
+def run_unit_tests():
+    """
+    Configures and runs the unit tests.
+    """
+    print("Running unit tests...")
+    # We replace sys.argv to prevent unittest.main from
+    # trying to parse the 'test' argument.
+    original_argv = sys.argv
+    sys.argv = [original_argv[0]]  # Keep only the script name
+    unittest.main()
+    sys.argv = original_argv # Restore original args
+
+
+if __name__ == '__main__':
+    # Check if the user wants to run tests
+    if len(sys.argv) > 1 and sys.argv[1].lower() == 'test':
+        run_unit_tests()
+    else:
+        # Run the main script logic
+        main()

build/common/get-gltf-sample-assets.sh

@@ -0,0 +1,60 @@
+# 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.
+
+#!/usr/bin/bash
+set -e
+
+GLTF_SAMPLE_ASSETS_COMMIT=${GITHUB_GLTF_SAMPLE_ASSETS_COMMIT:-d441dfdb87413ff412c620849a649d61789a470f}
+COMMIT_HASH="${GLTF_SAMPLE_ASSETS_COMMIT}"
+REPO_URL="https://github.com/KhronosGroup/glTF-Sample-Assets.git"
+TARGET_DIR="gltf"
+
+# The default directories to check out if none are specified
+DEFAULT_SPARSE_PATHS=(
+    "Models/Box/"
+    "Models/Triangle/"
+    "Models/AnimatedCube/"
+)
+
+# Check if command-line arguments are provided
+if [ "$#" -gt 0 ]; then
+    # If arguments are provided, use them as the paths
+    SPARSE_PATHS=()
+    for model_name in "$@"; do
+        SPARSE_PATHS+=("Models/${model_name}/")
+    done
+    echo "Downloading specified models: $@"
+else
+    # Otherwise, use the default list
+    SPARSE_PATHS=("${DEFAULT_SPARSE_PATHS[@]}")
+    echo "No models specified, downloading default set."
+fi
+
+echo "Removing old directory..."
+rm -rf "${TARGET_DIR}"
+
+# Clone the repository using a "treeless" clone, which is highly efficient.
+# --filter=tree:0: Clones only the repository structure without file content (no historical directory listings), making the initial clone very small.
+# --no-checkout:   Prevents automatically checking out the main branch. We will check out a specific commit later.
+# --sparse:        Initializes the repository for sparse checkout, allowing us to fetch only specific directories.
+git clone --filter=tree:0 --no-checkout --sparse "${REPO_URL}" "${TARGET_DIR}"
+
+cd "${TARGET_DIR}"
+
+git sparse-checkout set "${SPARSE_PATHS[@]}"
+
+echo "Checking out commit ${COMMIT_HASH}..."
+git checkout "${COMMIT_HASH}"
+
+echo "Successfully checked out the specified models into the '${TARGET_DIR}' directory."

build/common/versions

@@ -5,4 +5,5 @@ GITHUB_MESA_VERSION=24.2.1
 GITHUB_LLVM_VERSION=16
 GITHUB_NDK_VERSION=27.0.11718014
 GITHUB_EMSDK_VERSION=3.1.60
-GITHUB_VULKANSDK_VERSION=1.4.321.0
+GITHUB_VULKANSDK_VERSION=1.4.321.0
+GITHUB_GLTF_SAMPLE_ASSETS_COMMIT=d441dfdb87413ff412c620849a649d61789a470f

docs/Materials.md.html

@@ -212,7 +212,7 @@ when using textures.
 This property can dramatically change the appearance of a surface. Non-metallic surfaces have
 chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
 color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
-(reflected light takes on the color of the surfaced as defined by `baseColor`). 
+(reflected light takes on the color of the surfaced as defined by `baseColor`).
 
 The effect of `metallic` is shown in figure [metallicProperty] (click on the image to see a
 larger version).
@@ -248,7 +248,7 @@ The effect of `roughness` on metallic surfaces is shown in figure [roughnessCond
 When refraction through an object is enabled (using a `refractonType` of `thin` or `solid`), the
 `roughness` property will also affect the refractions, as shown in figure
 [roughnessRefractionProperty] (click on the image to see a larger version).
-                             
+
 ![Figure [roughnessRefractionProperty]: Refractive sphere with `roughness` varying from 0.0
  (left) to 1.0 (right)](images/materials/refraction_roughness.png)
 
@@ -307,7 +307,7 @@ The sheen color controls the color appearance and strength of an optional sheen
 base layer described by the properties above. The sheen layer always sits below the clear coat layer
 if such a layer is present.
 
-The sheen layer can be used to represent cloth and fabric materials. Please refer to 
+The sheen layer can be used to represent cloth and fabric materials. Please refer to
 section [Cloth model] for more information about cloth and fabric materials.
 
 The effect of `sheenColor` is shown in figure [materialSheenColor]
@@ -520,14 +520,14 @@ light to bend further away from the initial path.
 
 Table [commonMatIOR] describes acceptable refractive indices for various types of materials.
 
-Material                   |        IOR       
+Material                   |        IOR
 --------------------------:|:-----------------
 Air                        | 1.0
-Water                      | 1.33             
-Common liquids             | 1.33 to 1.5      
-Common gemstones           | 1.58 to 2.33     
-Plastics, glass            | 1.5 to 1.58      
-Other dielectric materials | 1.33 to 1.58     
+Water                      | 1.33
+Common liquids             | 1.33 to 1.5
+Common gemstones           | 1.58 to 2.33
+Plastics, glass            | 1.5 to 1.58
+Other dielectric materials | 1.33 to 1.58
 [Table [commonMatIOR]: Index of refraction of common materials]
 
 The appearance of a refractive material will greatly depend on the `refractionType` and
@@ -995,10 +995,10 @@ Value
       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]. For Android external textures, entries also have an optional 
-      transformName parameter to specify the name of the material parameter that will be 
+      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. 
+      this will always be identity.
 
          Type          |            Description
 :----------------------|:---------------------------------
@@ -2476,14 +2476,17 @@ type aliases:
 
 ### Matrices
 
-                 Name               |   Type   |            Description
-:-----------------------------------|:--------:|:------------------------------------
-**getViewFromWorldMatrix()**        | float4x4 |  Matrix that converts from world space to view/eye space
-**getWorldFromViewMatrix()**        | float4x4 |  Matrix that converts from view/eye space to world space
-**getClipFromViewMatrix()**         | float4x4 |  Matrix that converts from view/eye space to clip (NDC) space
-**getViewFromClipMatrix()**         | float4x4 |  Matrix that converts from clip (NDC) space to view/eye space
-**getClipFromWorldMatrix()**        | float4x4 |  Matrix that converts from world to clip (NDC) space
-**getWorldFromClipMatrix()**        | float4x4 |  Matrix that converts from clip (NDC) space to world space
+                 Name                     |   Type   |            Description
+:-----------------------------------------|:--------:|:------------------------------------
+**getViewFromWorldMatrix()**              | float4x4 |  Matrix that converts from world space to view/eye space
+**getWorldFromViewMatrix()**              | float4x4 |  Matrix that converts from view/eye space to world space
+**getClipFromViewMatrix()**               | float4x4 |  Matrix that converts from view/eye space to clip (NDC) space
+**getViewFromClipMatrix()**               | float4x4 |  Matrix that converts from clip (NDC) space to view/eye space
+**getEyeFromViewMatrix()**                | float4x4 |  Matrix that converts from view space to eye space
+**getEyeFromViewMatrix(int eyeIndex)**    | float4x4 |  Matrix that converts from view space to eye space for the eye referred to by eyeIndex
+**getClipFromWorldMatrix()**              | float4x4 |  Matrix that converts from world to clip (NDC) space
+**getClipFromWorldMatrix(int eyeIndex)**  | float4x4 |  Matrix that converts from world to clip (NDC) space for the eye referred to by eyeIndex
+**getWorldFromClipMatrix()**              | float4x4 |  Matrix that converts from clip (NDC) space to world space
 
 ### Frame constants
 
@@ -2639,7 +2642,7 @@ standard skybox material. It produces a list of 2 parameters, named `showSun` an
 respectively a boolean and a cubemap texture.
 
 ```text
-$ matc --reflect parameters filament/src/materials/skybox.mat 
+$ matc --reflect parameters filament/src/materials/skybox.mat
 {
   "parameters": [
     {
@@ -2655,7 +2658,7 @@ $ matc --reflect parameters filament/src/materials/skybox.mat
     }
   ]
 }
-``` 
+```
 
 ### --variant-filter
 

docs/build/maven_release.html

@@ -0,0 +1,267 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Maven Release - 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="maven-release"><a class="header" href="#maven-release">Maven Release</a></h1>
+<h2 id="register-for-a-sonatype-account"><a class="header" href="#register-for-a-sonatype-account">Register for a Sonatype Account</a></h2>
+<p>First, you'll need to register for a Sonatype account at the <a href="https://central.sonatype.org/register/central-portal/">Central
+Portal</a>.</p>
+<p>To publish under the <code>com.google.android</code> namespace, you'll also need to email
+<code>central-support@sonatype.com</code> with your account information to request access.</p>
+<p>Then, generate a user token through the Sonatype website. Navigate to
+<a href="https://central.sonatype.com/account">https://central.sonatype.com/account</a> and select <strong>Generate
+User Token</strong>.</p>
+<p>Finally, add the generated token credentials to <code>~/.gradle/gradle.properties</code>. (Note: these are
+different from the credentials used to log into your Sonatype account):</p>
+<pre><code class="language-gradle"># Generated Sonatype token
+sonatypeUsername=&lt;username&gt;
+sonatypePassword=&lt;password&gt;
+</code></pre>
+<hr />
+<h2 id="signing-key"><a class="header" href="#signing-key">Signing Key</a></h2>
+<p>All release artifacts must be signed. You'll need to create an OpenPGP key pair. See Gradle's
+documentation on <a href="https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials">Signatory
+credentials</a>
+for instructions.</p>
+<p>Update <code>~/.gradle/gradle.properties</code> with your new key's credentials:</p>
+<pre><code class="language-gradle">signing.keyId=&lt;key id&gt;
+signing.password=&lt;key password&gt;
+signing.secretKeyRingFile=&lt;secret key ring file&gt;
+</code></pre>
+<hr />
+<h2 id="build-the-android-release"><a class="header" href="#build-the-android-release">Build the Android Release</a></h2>
+<p>Make sure <code>JAVA_HOME</code> is set correctly. For example:</p>
+<pre><code class="language-bash">export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
+./build.sh -C -i -p android release
+</code></pre>
+<hr />
+<h2 id="publish-to-sonatype"><a class="header" href="#publish-to-sonatype">Publish to Sonatype</a></h2>
+<h3 id="a-note-on-the-legacy-staging-service"><a class="header" href="#a-note-on-the-legacy-staging-service">A Note on the Legacy Staging Service</a></h3>
+<p>Previously, Filament was published to Maven via OSSRH (Open Source Software Repository Hosting). In
+2025, this service was <a href="https://central.sonatype.org/pages/ossrh-eol/">sunsetted</a>. Now, we use
+Sonatype's <a href="https://central.sonatype.org/">Central Publisher Portal</a>.</p>
+<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>
+<pre><code class="language-bash">cd android
+./gradlew publishToSonatype
+</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>
+<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>
+<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>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../build/windows_android.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/contributing.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="../build/windows_android.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/contributing.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/build/windows_android.html

@@ -273,7 +273,7 @@ copy filament-android\build\outputs\aar\filament-android-release.aar ..\..\out\
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
-                            <a rel="next prefetch" href="../dup/contributing.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next prefetch" href="../build/maven_release.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -287,7 +287,7 @@ copy filament-android\build\outputs\aar\filament-android-release.aar ..\..\out\
                         <i class="fa fa-angle-left"></i>
                     </a>
 
-                    <a rel="next prefetch" href="../dup/contributing.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next prefetch" href="../build/maven_release.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/building.html

@@ -434,7 +434,7 @@ to create a quick localhost server:</p>
 <p>Alternatively, if you have node installed you can use the
 <a href="https://www.npmjs.com/package/live-server">live-server</a> package, which automatically refreshes the
 web page when it detects a change.</p>
-<p>Each sample app has its own handwritten html file. Additionally the server folder contains assets
+<p>Each sample app has its own handwritten html file. Additionally, the server folder contains assets
 such as meshes, textures, and materials.</p>
 <h2 id="running-the-native-samples"><a class="header" href="#running-the-native-samples">Running the native samples</a></h2>
 <p>The <code>samples/</code> directory contains several examples of how to use Filament with SDL2.</p>

docs/dup/code_style.html

@@ -179,7 +179,7 @@ Google code style and is derived from the Java code style, but not quite.</p>
 <li>class access modifiers are not indented</li>
 <li>last line of <code>.cpp</code> or <code>.h</code> file must be an empty line</li>
 </ul>
-<pre><code>for (int i = 0; i &lt; max; i++) {
+<pre><code class="language-c++">for (int i = 0; i &lt; max; i++) {
 }
 
 class Foo {
@@ -227,11 +227,23 @@ src/data.inc
 <li><code>public</code> class attributes <em>are not</em> prefixed</li>
 <li>class attributes and methods are lower camelcase</li>
 </ul>
-<pre><code>extern int gGlobalWarming;
+<pre><code class="language-c++">extern int gGlobalWarming;
 
 class FooBar {
 public:
-    void methodName();
+    FooBar(int attributeName, int sizeInBytes)
+            : mAttributeName(attributeName),
+              sizeInBytes(sizeInBytes) {}
+
+    void reallyLongMethodNameWithLotsOfArguments(bool argument1,
+            int someSecondArgument, int bestArgument) {
+        std::pair&lt;bool, int&gt; pair = {
+            argument1,
+            argument2,
+        };
+        // etc
+    }
+
     int sizeInBytes;
 private:
     int mAttributeName;
@@ -248,7 +260,7 @@ private:
 <li>always include the copyright notice at the top of every file</li>
 <li>make sure the date is correct</li>
 </ul>
-<pre><code>/*
+<pre><code class="language-c++">/*
  * Copyright (C) 2018 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -293,7 +305,7 @@ conversely containers and algorithms are not allowed. There are exceptions such
 </li>
 </ul>
 <p><em>Sorting the headers is important to help catching missing <code>#include</code> directives.</em></p>
-<pre><code>/*
+<pre><code class="language-c++">/*
  * Copyright (C) 2018 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -336,7 +348,7 @@ from other string types.</li>
 <ul>
 <li>Use <code>auto</code> only when the type appears on the same line or with iterators and lambdas.</li>
 </ul>
-<pre><code>auto foo = new Foo();
+<pre><code class="language-c++">auto foo = new Foo();
 for (auto&amp; i : collection) { }
 </code></pre>
 

docs/dup/contributing.html

@@ -209,7 +209,7 @@ as possible. The current external dependencies of the runtime library include:</
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="../build/windows_android.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="../build/maven_release.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
@@ -223,7 +223,7 @@ as possible. The current external dependencies of the runtime library include:</
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="../build/windows_android.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="../build/maven_release.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/intro.html

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

docs/dup/renderdiff.html

@@ -0,0 +1,341 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>renderdiff - 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="rendering-difference-test"><a class="header" href="#rendering-difference-test">Rendering Difference Test</a></h1>
+<p>We created a few scripts to run <code>gltf_viewer</code> and produce headless renderings.</p>
+<p>This is mainly useful for continuous integration where GPUs are generally not available on cloud
+machines. To perform software rasterization, these scripts are centered around <a href="https://docs.mesa3d.org">Mesa</a>'s
+software rasterizers, but nothing bars us from using another rasterizer like <a href="https://github.com/google/swiftshader">SwiftShader</a>.
+Additionally, we should be able to use GPUs where available (though this is more of a future
+work).</p>
+<p>The script <code>render.py</code> contains the core logic for taking input parameters (such as the test
+description file) and then running gltf_viewer to produce the renderings.</p>
+<p>In the <code>test</code> directory is a list of test descriptions that are specified in json. Please see
+<code>sample.json</code> to parse the structure.</p>
+<h2 id="setting-up-python"><a class="header" href="#setting-up-python">Setting up python</a></h2>
+<p>The <code>renderdiff</code> project uses <code>python</code> extensively. To install the dependencies for producing
+renderings, do the following step</p>
+<ul>
+<li>Set up a virtual environment (from the root directory)
+<pre><code>python3 -m venv venv
+. ./venv/bin/activate
+</code></pre>
+</li>
+<li>Install the rendering dependencies
+<pre><code>pip install -r test/renderdiff/src/rendering_requirements.txt
+</code></pre>
+</li>
+<li>Install the viewer depdencies
+<pre><code>pip install -r test/renderdiff/src/viewer_requirements.txt
+</code></pre>
+</li>
+<li>For the commands in the following section, do not exit the virtual environment. Once you've
+completed all your work, you can exit with
+<pre><code>deactivate
+</code></pre>
+</li>
+</ul>
+<h2 id="running-the-test-locally"><a class="header" href="#running-the-test-locally">Running the test locally</a></h2>
+<ul>
+<li>To run the same presbumit as <a href="presubmit-renderdiff"><code>test-renderdiff</code></a>, you can do
+<pre><code>bash test/renderdiff/local_test.sh
+</code></pre>
+</li>
+<li>This script will generate the renderings based on the current state of your repo.
+Additionally, it will also compare the generated images with corresponding images in the
+golden repo.</li>
+<li>To just render without running the test, you could use the following script
+<pre><code>bash test/renderdiff/generate.sh
+</code></pre>
+</li>
+</ul>
+<h2 id="command-line-options"><a class="header" href="#command-line-options">Command-line Options</a></h2>
+<p>You can control the behavior of the test scripts with the following flags passed to <code>local_test.sh</code>:</p>
+<ul>
+<li><code>--test_filter=&lt;filter&gt;</code>: Run a subset of tests. The filter supports wildcards (<code>*</code>) to match test names.</li>
+<li><code>--no_rebuild</code>: Skip rebuilding the <code>gltf_viewer</code> executable.</li>
+<li><code>--num_threads=&lt;number&gt;</code>: Set the number of threads for rendering. If not set, the system's default is used.</li>
+</ul>
+<p>For example, to run all <code>MSAA</code> tests without rebuilding and using 8 threads:</p>
+<pre><code>bash test/renderdiff/local_test.sh --test_filter='MSAA.*.*' --no_rebuild --num_threads=8
+</code></pre>
+<h2 id="update-the-golden-images"><a class="header" href="#update-the-golden-images">Update the golden images</a></h2>
+<p>The golden images are stored in a github repository:
+https://github.com/google/filament-assets. Filament team members should have access to write
+to the repository. A typical flow for updating the goldens is to upload your changed images
+into <strong>branch</strong> of <code>filament-assets</code>. This branch is paired with a PR or commit on the
+<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>
+<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>Run interactive mode in the <code>update_golden.py</code> script.
+<pre><code>python3 test/renderdiff/src/update_golden.py
+</code></pre>
+</li>
+<li>This will guide you through a series of steps to push the changes to a remote branch on
+<code>filament-assets</code>.</li>
+</ul>
+<h3 id="manually-updating-the-golden-repo"><a class="header" href="#manually-updating-the-golden-repo">Manually updating the golden repo</a></h3>
+<ul>
+<li>Check out the golden repo
+<pre><code>git clone git@github.com:google/filament-assets.git
+</code></pre>
+</li>
+<li>Create a branch on the golden repo
+<pre><code>cd filament-assets
+git switch -c my-pr-branch-golden
+</code></pre>
+</li>
+<li>Copy the new images to their appropriate place in <code>filament-assets</code></li>
+<li>Push the <code>filament-assets</code> working branch to remote
+<pre><code>git push origin my-pr-branch-golden
+</code></pre>
+</li>
+<li>In the commit message of your working branch on <code>filament</code>, add the following line
+<pre><code>RDIFF_BBRANCH=my-pr-branch-golden
+</code></pre>
+</li>
+</ul>
+<p>Doing the above has multiple effects:</p>
+<ul>
+<li>The presubmit test <a href="https://github.com/google/filament/blob/e85dfe75c86106a05019e13ccdbef67e030af675/.github/workflows/presubmit.yml#L118"><code>test-renderdiff</code></a> will test against the provided
+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>
+<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
+directory, it will parse the test result and show the results and the rendered and/or golden
+images.</p>
+<p><img src="../images/renderdiff_example.png" alt="Viewer" /></p>
+<p>To run the viewer of a test output directory that has been generated locally, you would run
+the following</p>
+<pre><code>python3 test/renderdiff/src/viewer.py --diff=[test output]
+</code></pre>
+<p>where <code>[test output]</code> is a directory containing the <code>compare_results.json</code> of the test run.
+For example, it could be <code>out/renderdiff/diffs/presubmit</code> for the standard path to the
+<code>presubmit</code> test output.</p>
+<p>To see the results of a Pull Request initiated test run, you would do the following</p>
+<pre><code>python3 test/renderdiff/src/viewer.py --pr_number=[PR #] --github_token=[github token]
+</code></pre>
+<p>where <code>[PR #]</code> is the numeric ID of your pull request, and the <code>[github token]</code> is an acess
+token that you (as a github user) needs to generate (<a href="https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens">reference</a>).</p>
+<p>To see the results of a specific run, you would do the following</p>
+<pre><code>python3 test/renderdiff/src/viewer.py --run_number=[RUN #] --github_token=[github token]
+</code></pre>
+<p>where <code>[RUN #]</code> is the numeric ID of the run. You can find the run number in the URL of the
+GitHub Actions page. For example, in the URL
+<code>https://github.com/google/filament/actions/runs/18023632663/job/51286323708?pr=9264</code>,
+the run number is <code>18023632663</code>.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../notes/tests.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="../notes/libs.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="../notes/tests.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="../notes/libs.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/dup/zbloat.html

@@ -162,7 +162,7 @@
 <p>This tool makes it easy to analyze the composition of Android applications that use Filament.</p>
 <ul>
 <li>Filament materials are shown in the treemap if <code>resgen --json</code> was used in the build.</li>
-<li>The input path can be a so file, folder, or zip archive (apk or aar).</li>
+<li>The input path can be a <code>.so</code> or <code>.a</code> file, a folder, or a zip archive (apk or aar).</li>
 <li>If the path is a zip or folder, interactively finds the file to analyze.</li>
 <li>The generated web report is a self-contained HTML file.</li>
 <li>Reports the gzipped size of all Filament materials.</li>

docs/main/filament.html

@@ -178,9 +178,9 @@ content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5)
 counter-increment: h6;margin-right:10px}
 </style><style>.hljs{display:block;overflow-x:auto;padding:0.5em;background:#fff;color:#000;-webkit-text-size-adjust:none}.hljs-comment{color:#006a00}.hljs-keyword{color:#02E}.hljs-literal,.nginx .hljs-title{color:#aa0d91}.method,.hljs-list .hljs-title,.hljs-tag .hljs-title,.setting .hljs-value,.hljs-winutils,.tex .hljs-command,.http .hljs-title,.hljs-request,.hljs-status,.hljs-name{color:#008}.hljs-envvar,.tex .hljs-special{color:#660}.hljs-string{color:#c41a16}.hljs-tag .hljs-value,.hljs-cdata,.hljs-filter .hljs-argument,.hljs-attr_selector,.apache .hljs-cbracket,.hljs-date,.hljs-regexp{color:#080}.hljs-sub .hljs-identifier,.hljs-pi,.hljs-tag,.hljs-tag .hljs-keyword,.hljs-decorator,.ini .hljs-title,.hljs-shebang,.hljs-prompt,.hljs-hexcolor,.hljs-rule .hljs-value,.hljs-symbol,.hljs-symbol .hljs-string,.hljs-number,.css .hljs-function,.hljs-function .hljs-title,.coffeescript .hljs-attribute{color:#A0C}.hljs-function .hljs-title{font-weight:bold;color:#000}.hljs-class .hljs-title,.smalltalk .hljs-class,.hljs-type,.hljs-typename,.hljs-tag .hljs-attribute,.hljs-doctype,.hljs-class .hljs-id,.hljs-built_in,.setting,.hljs-params,.clojure .hljs-attribute{color:#5c2699}.hljs-variable{color:#3f6e74}.css .hljs-tag,.hljs-rule .hljs-property,.hljs-pseudo,.hljs-subst{color:#000}.css .hljs-class,.css .hljs-id{color:#9b703f}.hljs-value .hljs-important{color:#ff7700;font-weight:bold}.hljs-rule .hljs-keyword{color:#c5af75}.hljs-annotation,.apache .hljs-sqbracket,.nginx .hljs-built_in{color:#9b859d}.hljs-preprocessor,.hljs-preprocessor *,.hljs-pragma{color:#643820}.tex .hljs-formula{background-color:#eee;font-style:italic}.diff .hljs-header,.hljs-chunk{color:#808080;font-weight:bold}.diff .hljs-change{background-color:#bccff9}.hljs-addition{background-color:#baeeba}.hljs-deletion{background-color:#ffc8bd}.hljs-comment .hljs-doctag{font-weight:bold}.method .hljs-id{color:#000}</style><style>div.title { padding-top: 40px; } div.afterTitles { height: 15px; }</style><meta charset="utf-8"></p>
 <style>img { max-width: 100%; }</style>
-<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
+<p><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{,\mathrm{#1}}$$
 </span>
-<span class="md"><p><title>Physically Based Rendering in Filament</title><div class="title"> Physically Based Rendering in Filament </div>
+<span class="md"><p><title>Physically Based Rendering in Filament</title><div class="title"> Physically Based Rendering in Filament </div></p>
 <div class="afterTitles"></div>
 </p><p>
 </p>
@@ -2060,7 +2060,7 @@ In practice only 4 or 9 coefficients (i.e.: 2 or 3 bands) are enough for \(\cosT
 In practice we pre-convolve \(\Lt\) with \(\cosTheta\) and pre-scale these coefficients by the basis scaling factors \(K_l^m\) so that the reconstruction code is as simple as possible in the shader:
 </p><a class="target" name="listing_irradiancesh">&nbsp;</a><pre class="listing tilde"><code><span class="line"></span>vec3 irradianceSH(vec3 n) {
 <span class="line"></span>    // uniform vec3 sphericalHarmonics<span class="hljs-selector-attr">[9]</span>
-<span class="line"></span>    // We can use only the first <span class="hljs-number">2</span> bands for better performance
+<span class="line"></span>    // We can <span class="hljs-selector-tag">use</span> only the first <span class="hljs-number">2</span> bands for better performance
 <span class="line"></span>    return
 <span class="line"></span>          sphericalHarmonics<span class="hljs-selector-attr">[0]</span>
 <span class="line"></span>        + sphericalHarmonics<span class="hljs-selector-attr">[1]</span> * (n<span class="hljs-selector-class">.y</span>)
@@ -4395,7 +4395,7 @@ For Fast Realistic Image Display. <em class="asterisk">SIGGRAPH '00 Proceedings
 </div><div class="bib">[<a class="target" name="citation-schlick94">&nbsp;</a><b>Schlick94</b>] Christophe Schlick. 1994. An Inexpensive BRDF Model for Physically-Based Rendering. <em class="asterisk">Computer Graphics Forum</em>, 13 (3), 233–246.
 </div><div class="bib">[<a class="target" name="citation-walter07">&nbsp;</a><b>Walter07</b>] Bruce Walter et al. 2007. Microfacet Models for Refraction through Rough Surfaces. <em class="asterisk">Proceedings of the Eurographics Symposium on Rendering</em>.
 </div>
-</sample></float></sample></float></float></p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.18&nbsp;&nbsp;</a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">&#x2712;</div></div><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+</sample></float></sample></float></float></p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.18&nbsp;&nbsp;</a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">&#x2712;</div></div><script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
                     </main>
 
                     <nav class="nav-wrapper" aria-label="Page navigation">

docs/main/materials.html

@@ -178,9 +178,9 @@ content:counter(h1) "."counter(h2) "."counter(h3) "."counter(h4) "."counter(h5)
 counter-increment: h6;margin-right:10px}
 </style><style>.hljs{display:block;overflow-x:auto;padding:0.5em;background:#fff;color:#000;-webkit-text-size-adjust:none}.hljs-comment{color:#006a00}.hljs-keyword{color:#02E}.hljs-literal,.nginx .hljs-title{color:#aa0d91}.method,.hljs-list .hljs-title,.hljs-tag .hljs-title,.setting .hljs-value,.hljs-winutils,.tex .hljs-command,.http .hljs-title,.hljs-request,.hljs-status,.hljs-name{color:#008}.hljs-envvar,.tex .hljs-special{color:#660}.hljs-string{color:#c41a16}.hljs-tag .hljs-value,.hljs-cdata,.hljs-filter .hljs-argument,.hljs-attr_selector,.apache .hljs-cbracket,.hljs-date,.hljs-regexp{color:#080}.hljs-sub .hljs-identifier,.hljs-pi,.hljs-tag,.hljs-tag .hljs-keyword,.hljs-decorator,.ini .hljs-title,.hljs-shebang,.hljs-prompt,.hljs-hexcolor,.hljs-rule .hljs-value,.hljs-symbol,.hljs-symbol .hljs-string,.hljs-number,.css .hljs-function,.hljs-function .hljs-title,.coffeescript .hljs-attribute{color:#A0C}.hljs-function .hljs-title{font-weight:bold;color:#000}.hljs-class .hljs-title,.smalltalk .hljs-class,.hljs-type,.hljs-typename,.hljs-tag .hljs-attribute,.hljs-doctype,.hljs-class .hljs-id,.hljs-built_in,.setting,.hljs-params,.clojure .hljs-attribute{color:#5c2699}.hljs-variable{color:#3f6e74}.css .hljs-tag,.hljs-rule .hljs-property,.hljs-pseudo,.hljs-subst{color:#000}.css .hljs-class,.css .hljs-id{color:#9b703f}.hljs-value .hljs-important{color:#ff7700;font-weight:bold}.hljs-rule .hljs-keyword{color:#c5af75}.hljs-annotation,.apache .hljs-sqbracket,.nginx .hljs-built_in{color:#9b859d}.hljs-preprocessor,.hljs-preprocessor *,.hljs-pragma{color:#643820}.tex .hljs-formula{background-color:#eee;font-style:italic}.diff .hljs-header,.hljs-chunk{color:#808080;font-weight:bold}.diff .hljs-change{background-color:#bccff9}.hljs-addition{background-color:#baeeba}.hljs-deletion{background-color:#ffc8bd}.hljs-comment .hljs-doctag{font-weight:bold}.method .hljs-id{color:#000}</style><style>div.title { padding-top: 40px; } div.afterTitles { height: 15px; }</style><meta charset="utf-8"></p>
 <style>img { max-width: 100%; }</style>
-<script type="text/x-mathjax-config">MathJax.Hub.Config({ TeX: { equationNumbers: {autoNumber: "AMS"} } });</script><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{\,\mathrm{#1}}$$
+<p><span style="display:none">$$\newcommand{\n}{\hat{n}}\newcommand{\thetai}{\theta_\mathrm{i}}\newcommand{\thetao}{\theta_\mathrm{o}}\newcommand{\d}[1]{\mathrm{d}#1}\newcommand{\w}{\hat{\omega}}\newcommand{\wi}{\w_\mathrm{i}}\newcommand{\wo}{\w_\mathrm{o}}\newcommand{\wh}{\w_\mathrm{h}}\newcommand{\Li}{L_\mathrm{i}}\newcommand{\Lo}{L_\mathrm{o}}\newcommand{\Le}{L_\mathrm{e}}\newcommand{\Lr}{L_\mathrm{r}}\newcommand{\Lt}{L_\mathrm{t}}\newcommand{\O}{\mathrm{O}}\newcommand{\degrees}{{^{\large\circ}}}\newcommand{\T}{\mathsf{T}}\newcommand{\mathset}[1]{\mathbb{#1}}\newcommand{\Real}{\mathset{R}}\newcommand{\Integer}{\mathset{Z}}\newcommand{\Boolean}{\mathset{B}}\newcommand{\Complex}{\mathset{C}}\newcommand{\un}[1]{,\mathrm{#1}}$$
 </span>
-<span class="md"><p><title>Filament Materials Guide</title><div class="title"> Filament Materials Guide </div>
+<span class="md"><p><title>Filament Materials Guide</title><div class="title"> Filament Materials Guide </div></p>
 <div class="afterTitles"></div>
 </p><p>
 </p>
@@ -504,7 +504,7 @@ when using textures.</p>
 This property can dramatically change the appearance of a surface. Non-metallic surfaces have
 chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
 color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
-(reflected light takes on the color of the surfaced as defined by <code>baseColor</code>). 
+(reflected light takes on the color of the surfaced as defined by <code>baseColor</code>).
 </p><p>
 The effect of <code>metallic</code> is shown in <a href="#figure_metallicproperty" target="_self">figure&nbsp;1</a> (click on the image to see a
 larger version).
@@ -597,7 +597,7 @@ indices.
 base layer described by the properties above. The sheen layer always sits below the clear coat layer
 if such a layer is present.</p>
 </p><p>
-The sheen layer can be used to represent cloth and fabric materials. Please refer to 
+The sheen layer can be used to represent cloth and fabric materials. Please refer to
 section <a href="#toc3.3" target="_self">3.3</a> for more information about cloth and fabric materials.
 </p><p>
 The effect of <code>sheenColor</code> is shown in <a href="#figure_materialsheencolor" target="_self">figure&nbsp;7</a>
@@ -1220,10 +1220,10 @@ non-shader data.</p>
       name must be a valid GLSL identifier. Entries have an optional <code>precision</code>, which can be
       one of <code>default</code> (best precision for the platform, typically <code>high</code> on desktop, <code>medium</code> on
       mobile), <code>low</code>, <code>medium</code>, <code>high</code>. The type must be one of the types described in
-      <a href="#table_materialparamstypes" target="_self">table&nbsp;14</a>. For Android external textures, entries also have an optional 
-      transformName parameter to specify the name of the material parameter that will be 
+      <a href="#table_materialparamstypes" target="_self">table&nbsp;14</a>. 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. 
+      this will always be identity.
 </p></dd></dl><div class='table'>
 <a class="target" name="table_materialparamstypes">&nbsp;</a><table class="table longtable"><tr><th  style="text-align:left"> Type </th><th  style="text-align:left"> Description </th></tr>
 <tr><td  style="text-align:left"> bool </td><td  style="text-align:left"> Single boolean </td></tr>
@@ -2361,7 +2361,10 @@ type aliases:</p>
 <tr><td  style="text-align:left"> <strong class="asterisk">getWorldFromViewMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from view/eye space to world space </td></tr>
 <tr><td  style="text-align:left"> <strong class="asterisk">getClipFromViewMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from view/eye space to clip (NDC) space </td></tr>
 <tr><td  style="text-align:left"> <strong class="asterisk">getViewFromClipMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from clip (NDC) space to view/eye space </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">getEyeFromViewMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from view space to eye space </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">getEyeFromViewMatrix(int eyeIndex)</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from view space to eye space for the eye referred to by eyeIndex </td></tr>
 <tr><td  style="text-align:left"> <strong class="asterisk">getClipFromWorldMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from world to clip (NDC) space </td></tr>
+<tr><td  style="text-align:left"> <strong class="asterisk">getClipFromWorldMatrix(int eyeIndex)</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from world to clip (NDC) space for the eye referred to by eyeIndex </td></tr>
 <tr><td  style="text-align:left"> <strong class="asterisk">getWorldFromClipMatrix()</strong> </td><td  style="text-align:center"> float4&times;4 </td><td  style="text-align:left"> Matrix that converts from clip (NDC) space to world space </td></tr>
 </table></div>
 </p>
@@ -2501,7 +2504,7 @@ a good compromise between runtime performance and size.</p>
 metadata in JSON format. The example below prints out the list of parameters defined in Filament's
 standard skybox material. It produces a list of 2 parameters, named <code>showSun</code> and <code>skybox</code>,
 respectively a boolean and a cubemap texture.</p>
-</p><pre class="listing backtick"><code><span class="line"></span>$ matc --reflect parameters filament/src/materials/skybox.mat 
+</p><pre class="listing backtick"><code><span class="line"></span>$ matc --reflect parameters filament/src/materials/skybox.mat
 <span class="line"></span>{
 <span class="line"></span>  &quot;parameters&quot;: [
 <span class="line"></span>    {
@@ -2600,7 +2603,7 @@ Finally if <code>variantFilter</code> contains the <code>fog</code> filter, an e
 </p><p>
                Be aware that <code>external</code> samplers account for 2 regular samplers.</div>
 </p><p>
-</p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.18&nbsp;&nbsp;</a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">&#x2712;</div></div><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.6/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+</p></span><div id="mdContextMenu" style="visibility:hidden"></div><div class="markdeepFooter"><i>formatted by <a href="https://casual-effects.com/markdeep" style="color:#999">Markdeep&nbsp;1.18&nbsp;&nbsp;</a></i><div style="display:inline-block;font-size:13px;font-family:'Times New Roman',serif;vertical-align:middle;transform:translate(-3px,-1px)rotate(135deg);">&#x2712;</div></div><script src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js"></script>
                     </main>
 
                     <nav class="nav-wrapper" aria-label="Page navigation">

docs/notes/coverage.html

@@ -250,7 +250,7 @@ execution profile data.</p>
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
-                            <a rel="next prefetch" href="../notes/framegraph.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next prefetch" href="../notes/performance_analysis.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -264,7 +264,7 @@ execution profile data.</p>
                         <i class="fa fa-angle-left"></i>
                     </a>
 
-                    <a rel="next prefetch" href="../notes/framegraph.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next prefetch" href="../notes/performance_analysis.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/notes/framegraph.html

@@ -331,11 +331,11 @@ nodes</li>
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="../notes/coverage.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="../notes/performance_analysis.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="../notes/libs.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next prefetch" href="../notes/tests.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -345,11 +345,11 @@ nodes</li>
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="../notes/coverage.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="../notes/performance_analysis.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="../notes/libs.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next prefetch" href="../notes/tests.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/notes/libs.html

@@ -165,7 +165,7 @@
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="../notes/framegraph.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="../dup/renderdiff.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
@@ -179,7 +179,7 @@
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="../notes/framegraph.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="../dup/renderdiff.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>
 

docs/notes/performance_analysis.html

@@ -0,0 +1,352 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Performance analysis - 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="performance-analysis"><a class="header" href="#performance-analysis">Performance Analysis</a></h1>
+<h2 id="android"><a class="header" href="#android">Android</a></h2>
+<h3 id="prerequisites"><a class="header" href="#prerequisites">Prerequisites</a></h3>
+<ul>
+<li>Download and install Android GPU Inspector (AGI). See https://developer.android.com/agi.</li>
+</ul>
+<hr />
+<h4 id="profiling"><a class="header" href="#profiling">Profiling</a></h4>
+<ol>
+<li>
+<p>Before profiling the application or analyzing the performance in a consistent way, ideally
+the <strong>GPU frequency on the target hardware should get locked</strong>. In order to do this, you need to do the following:</p>
+<ol>
+<li>Ensure your device is OEM unlocked. If your phone is carrier-locked, you may need
+to wait a period, such as 60 or 90 days after activation to be eligible for unlocking.
+Some phones don't support this at all. You will need to enable developer options
+(e.g. Settings &gt; About Phone and tap the Build number 7 times). You need to go to
+Settings &gt; System &gt; Developer options and toggle on "OEM unlocking".</li>
+<li>Next, you need to unlock the phone. You will need to install Android SDK Platform
+Tools on you computer, enable "USB debugging" in your phone's Settings &gt; System &gt; Developer options.</li>
+<li>Connect the phone to the computer via a USB cable and run from the command line:
+<pre><code class="language-shell">adb reboot bootloader
+# once the phone is in bootloader mode, run the following to begin the unlocking
+# process:
+fastboot flashing unlock
+</code></pre>
+A warning will appear on your phone's screen. Use the volume buttons to navigate and
+the power button to select the "Unlock the bootloader" option. The phone will perform
+a factory data reset and reboot with an unlocked bootloader.</li>
+<li>You would need to flash an image to the phone with root permissions, such as a *-userdebug or *-eng
+build. One way to do this is with the <a href="https://flash.android.com/">Android Flash Tool</a>. Connect the
+tool to your device and find a build to flash ending in <code>-userdebug</code> or <code>-eng</code>. Once you have that
+selected run <code>Install build</code>.</li>
+<li>Shell into your device as root and configure the gpu frequency to be locked, e.g.:
+<pre><code class="language-shell">adb shell
+su
+# navigate to the system GPU directory. this varies on different phones. One phone might have
+# it at /sys/class/kgsl/kgsl-3d0 and another might be in something similar, maybe with "mali" instead
+# of "kgsl". At the time of writing this for the device at hand it was /sys/devices/platform/1f000000.mali
+cd /sys/devices/platform/1f000000.mali
+# get the current available GPU governors and frequencies.
+# note that some systems may have these at gpu_available_governors and gpu_available_frequencies, but
+# the system at the time of writing this had available_governors and available_frequences
+cat available_governors
+cat available_frequencies
+# depending on the governors, you may want to set it prioritize performance over other things like
+# battery. Some systems allow you to do this with something like (although, for the device used at the
+# time of writing this did not have an equivalent option):
+echo performance &gt; gpu_governor
+# finally, lock your frequency in, usually to something high like 897 MHz. Some systems may have you
+# pipe the value to gpu_min_freq and gpu_max_freq, but the system used at the time of writing this had:
+echo 940000 &gt; hint_min_freq
+echo 940000 &gt; hint_max_freq
+# you can typically verify the GPU is running at that frequency consistently by running something like
+# the following a few times over time, which should show the frequency you want to lock the device to:
+cat cur_freq
+</code></pre>
+</li>
+<li>You may need to re-apply the <code>hint_min_freq</code> just before starting the profiling trace and check before and after
+that the frequency remained at the value expected. Some systems may adjust the frequency on you, but you
+may want to ensure the frequency remains the same through the analysis.</li>
+<li>The GPU frequency settings should be undone after restarting the device, but after you have done your app profiling,
+you can revert the state of the device, such as the OS build image, back to the way you had it
+initially, as needed.</li>
+</ol>
+</li>
+<li>
+<p>Build a release build of Filament with the applicable backend(s) enabled
+<em>(+ any special flags for enabling sys strace. Nothing special is needed for Vulkan or WebGPU aside from
+building a release build with no flags)</em> <em>(debug builds for this are useless)</em></p>
+<pre><code class="language-shell"># the following command assumes you are in the root filament directory
+# and ANDROID_HOME is exported (and possibly also CC and CXX on linux as needed)
+#
+# NOTE: to build with WebGPU support you need to explicitly include the -W flag
+# (it doesn't get compiled in by default), e.g.:
+# ./build.sh -W -p android,desktop -i release
+#
+# Note that you can speed this up a bit (and reduce disk space usage) by limiting the target to just 
+# the ABI you plan on testing with the -q flag, e.g. -q arm64-v8a. If you do this, you
+# will need to update the android/gradle.properties file to specify the ABI(s) you are targeting
+# with the com.google.android.filament.abis property.
+# Thus, a build command that would target BOTH Vulkan AND WebGPU AND only target the ARM64 ABI would look something
+# like:
+# ./build.sh -W -q arm64-v8a -p android,desktop -i release
+./build.sh -p android,desktop -i release
+</code></pre>
+</li>
+<li>
+<p>Connect your Android device to your computer via a USB cord with USB debugging enabled and configure
+the system property to default to the desired backend, e.g.
+<em>(to determine how these numbers map to the backends, see the <code>enum class Backend</code>
+definition in <a href="../../../../filament/backend/include/backend/DriverEnums.h">filament/filament/backend/include/backend/DriverEnums.h</a>)</em>:</p>
+<pre><code class="language-shell"># to set the backend to Vulkan: 
+adb shell setprop debug.filament.backend 2
+# to set the backend to WebGPU:
+adb shell setprop debug.filament.backend 4
+# to view the current property:
+adb shell getprop debug.filament.backend
+</code></pre>
+</li>
+<li>
+<p>Build and run a sample, e.g. sample-gltf-viewer, on your Android device
+<em>(<a href="https://developer.android.com/studio">Android Studio</a> recommended)</em>.</p>
+</li>
+<li>
+<p>Run <a href="https://developer.android.com/agi">AGI</a> and follow instructions to profile the app/system
+with trace capture(s). See https://developer.android.com/agi/start for more details to
+get started.</p>
+<ul>
+<li>We typically only run "Capture System Profiler trace" <em>(not necessarily "Capture Frame Profiler trace")</em></li>
+<li>When configuring the trace:
+<ul>
+<li>For both the WebGPU and Vulkan backends configure the profiler for the Vulkan API
+<em>(since WebGPU should be using Vulkan under the hood as well)</em></li>
+<li>Running for ~1 seconds should suffice</li>
+<li>Hit the "Configure" button in Trace objects, select "Switch to advanced mode" and add:
+<pre><code>data_sources {
+  config {
+    name: "track_event"
+    track_event_config {
+      disabled_categories: "*"
+      enabled_categories: "filament/filament"
+      enabled_categories: "filament/jobsystem"
+      enabled_categories: "filament/gltfio"
+    }
+  }
+}
+</code></pre>
+</li>
+</ul>
+</li>
+<li>One you open the trace, zoom into a series of frames to get a sense of generally how long they typically take
+<em>(use <code>W</code>, <code>S</code>, <code>A</code> and <code>D</code> keys and mouse wheel for navigation)</em> and find a representative one.
+We are most interested in the performance of the
+<code>FEngine::loop</code> thread, how long it takes, overlap in activities/processes/commands, reduction in queue submissions,
+etc. Similarly, we can view GPU timeline as it relates to that. We want to see overlapping
+shader invocations and non-interrupted fragment shader runs.</li>
+</ul>
+</li>
+</ol>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../notes/coverage.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="../notes/framegraph.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="../notes/coverage.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="../notes/framegraph.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/notes/tests.html

@@ -0,0 +1,215 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Tests - 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="tests"><a class="header" href="#tests">Tests</a></h1>
+<p>Filament has a collection of tests that can be run locally. Many of them are used
+for in our Continuation Integration flow <a href="https://https://github.com/google/filament/tree/main/.github/workflows">on github</a>.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../notes/framegraph.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/renderdiff.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="../notes/framegraph.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/renderdiff.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_src/build/duplicates.json

@@ -78,5 +78,11 @@
     },
     "docs_src/README.md": {
         "dest": "dup/docs.md"
+    },
+    "test/renderdiff/README.md": {
+        "dest": "dup/renderdiff.md",
+        "link_transforms": {
+            "docs/images/": "../images/"
+        }
     }
 }

docs_src/src_markdeep/Materials.md.html

@@ -212,7 +212,7 @@ when using textures.
 This property can dramatically change the appearance of a surface. Non-metallic surfaces have
 chromatic diffuse reflection and achromatic specular reflection (reflected light does not change
 color). Metallic surfaces do not have any diffuse reflection and chromatic specular reflection
-(reflected light takes on the color of the surfaced as defined by `baseColor`). 
+(reflected light takes on the color of the surfaced as defined by `baseColor`).
 
 The effect of `metallic` is shown in figure [metallicProperty] (click on the image to see a
 larger version).
@@ -248,7 +248,7 @@ The effect of `roughness` on metallic surfaces is shown in figure [roughnessCond
 When refraction through an object is enabled (using a `refractonType` of `thin` or `solid`), the
 `roughness` property will also affect the refractions, as shown in figure
 [roughnessRefractionProperty] (click on the image to see a larger version).
-                             
+
 ![Figure [roughnessRefractionProperty]: Refractive sphere with `roughness` varying from 0.0
  (left) to 1.0 (right)](images/materials/refraction_roughness.png)
 
@@ -307,7 +307,7 @@ The sheen color controls the color appearance and strength of an optional sheen
 base layer described by the properties above. The sheen layer always sits below the clear coat layer
 if such a layer is present.
 
-The sheen layer can be used to represent cloth and fabric materials. Please refer to 
+The sheen layer can be used to represent cloth and fabric materials. Please refer to
 section [Cloth model] for more information about cloth and fabric materials.
 
 The effect of `sheenColor` is shown in figure [materialSheenColor]
@@ -520,14 +520,14 @@ light to bend further away from the initial path.
 
 Table [commonMatIOR] describes acceptable refractive indices for various types of materials.
 
-Material                   |        IOR       
+Material                   |        IOR
 --------------------------:|:-----------------
 Air                        | 1.0
-Water                      | 1.33             
-Common liquids             | 1.33 to 1.5      
-Common gemstones           | 1.58 to 2.33     
-Plastics, glass            | 1.5 to 1.58      
-Other dielectric materials | 1.33 to 1.58     
+Water                      | 1.33
+Common liquids             | 1.33 to 1.5
+Common gemstones           | 1.58 to 2.33
+Plastics, glass            | 1.5 to 1.58
+Other dielectric materials | 1.33 to 1.58
 [Table [commonMatIOR]: Index of refraction of common materials]
 
 The appearance of a refractive material will greatly depend on the `refractionType` and
@@ -995,10 +995,10 @@ Value
       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]. For Android external textures, entries also have an optional 
-      transformName parameter to specify the name of the material parameter that will be 
+      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. 
+      this will always be identity.
 
          Type          |            Description
 :----------------------|:---------------------------------
@@ -2476,14 +2476,17 @@ type aliases:
 
 ### Matrices
 
-                 Name               |   Type   |            Description
-:-----------------------------------|:--------:|:------------------------------------
-**getViewFromWorldMatrix()**        | float4x4 |  Matrix that converts from world space to view/eye space
-**getWorldFromViewMatrix()**        | float4x4 |  Matrix that converts from view/eye space to world space
-**getClipFromViewMatrix()**         | float4x4 |  Matrix that converts from view/eye space to clip (NDC) space
-**getViewFromClipMatrix()**         | float4x4 |  Matrix that converts from clip (NDC) space to view/eye space
-**getClipFromWorldMatrix()**        | float4x4 |  Matrix that converts from world to clip (NDC) space
-**getWorldFromClipMatrix()**        | float4x4 |  Matrix that converts from clip (NDC) space to world space
+                 Name                     |   Type   |            Description
+:-----------------------------------------|:--------:|:------------------------------------
+**getViewFromWorldMatrix()**              | float4x4 |  Matrix that converts from world space to view/eye space
+**getWorldFromViewMatrix()**              | float4x4 |  Matrix that converts from view/eye space to world space
+**getClipFromViewMatrix()**               | float4x4 |  Matrix that converts from view/eye space to clip (NDC) space
+**getViewFromClipMatrix()**               | float4x4 |  Matrix that converts from clip (NDC) space to view/eye space
+**getEyeFromViewMatrix()**                | float4x4 |  Matrix that converts from view space to eye space
+**getEyeFromViewMatrix(int eyeIndex)**    | float4x4 |  Matrix that converts from view space to eye space for the eye referred to by eyeIndex
+**getClipFromWorldMatrix()**              | float4x4 |  Matrix that converts from world to clip (NDC) space
+**getClipFromWorldMatrix(int eyeIndex)**  | float4x4 |  Matrix that converts from world to clip (NDC) space for the eye referred to by eyeIndex
+**getWorldFromClipMatrix()**              | float4x4 |  Matrix that converts from clip (NDC) space to world space
 
 ### Frame constants
 
@@ -2639,7 +2642,7 @@ standard skybox material. It produces a list of 2 parameters, named `showSun` an
 respectively a boolean and a cubemap texture.
 
 ```text
-$ matc --reflect parameters filament/src/materials/skybox.mat 
+$ matc --reflect parameters filament/src/materials/skybox.mat
 {
   "parameters": [
     {
@@ -2655,7 +2658,7 @@ $ matc --reflect parameters filament/src/materials/skybox.mat
     }
   ]
 }
-``` 
+```
 
 ### --variant-filter
 

docs_src/src_mdbook/src/SUMMARY.md

@@ -3,6 +3,7 @@
 - [Introduction](./dup/intro.md)
   - [Build](./dup/building.md)
     - [Build for Android on Windows](./build/windows_android.md)
+    - [Maven Release](./build/maven_release.md)
   - [Contribute](./dup/contributing.md)
   - [Coding Style](./dup/code_style.md)
 - [Core Concepts](./main/README.md)
@@ -24,7 +25,10 @@
     - [Running with ASAN and UBSAN](./notes/asan_ubsan.md)
     - [Using Instruments on macOS](./notes/instruments.md)
     - [Code coverage analysis](./notes/coverage.md)
+    - [Performance analysis](./notes/performance_analysis.md)
   - [Framegraph](./notes/framegraph.md)
+  - [Tests](./notes/tests.md)
+    - [renderdiff](./dup/renderdiff.md)
   - [Libraries](./notes/libs.md)
     - [bluegl](./dup/bluegl.md)
     - [bluevk](./dup/bluevk.md)

docs_src/src_mdbook/src/build/maven_release.md

@@ -0,0 +1,89 @@
+# Maven Release
+
+## Register for a Sonatype Account
+
+First, you'll need to register for a Sonatype account at the [Central
+Portal](https://central.sonatype.org/register/central-portal/).
+
+To publish under the `com.google.android` namespace, you'll also need to email
+`central-support@sonatype.com` with your account information to request access.
+
+Then, generate a user token through the Sonatype website. Navigate to
+[https://central.sonatype.com/account](https://central.sonatype.com/account) and select **Generate
+User Token**.
+
+Finally, add the generated token credentials to `~/.gradle/gradle.properties`. (Note: these are
+different from the credentials used to log into your Sonatype account):
+
+```gradle
+# Generated Sonatype token
+sonatypeUsername=<username>
+sonatypePassword=<password>
+```
+
+-----
+
+## Signing Key
+
+All release artifacts must be signed. You'll need to create an OpenPGP key pair. See Gradle's
+documentation on [Signatory
+credentials](https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials)
+for instructions.
+
+Update `~/.gradle/gradle.properties` with your new key's credentials:
+
+```gradle
+signing.keyId=<key id>
+signing.password=<key password>
+signing.secretKeyRingFile=<secret key ring file>
+```
+
+-----
+
+## Build the Android Release
+
+Make sure `JAVA_HOME` is set correctly. For example:
+
+```bash
+export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
+./build.sh -C -i -p android release
+```
+
+-----
+
+## Publish to Sonatype
+
+### A Note on the Legacy Staging Service
+
+Previously, Filament was published to Maven via OSSRH (Open Source Software Repository Hosting). In
+2025, this service was [sunsetted](https://central.sonatype.org/pages/ossrh-eol/). Now, we use
+Sonatype's [Central Publisher Portal](https://central.sonatype.org/).
+
+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.
+
+-----
+
+### 1\. Upload to the Staging API Compatibility Service
+
+```bash
+cd android
+./gradlew publishToSonatype
+```
+
+### 2\. Move the Repository to the Central Publisher Portal
+
+We have a script to automate this. It reads the `sonatypeUsername` and `sonatypePassword` from your
+`~/.gradle/gradle.properties` file.
+
+```bash
+python3 build/common/close-sonatype-staging-repository.py
+```
+
+### 3\. Publish the Release on Sonatype
+
+Navigate to [Maven Central Repository Deployments](https://central.sonatype.com/publishing/deployments).
+
+Here, you should see a new deployment with a **Validated** status and all your artifacts listed. Click
+the **Publish** button to publish the artifacts. It typically takes around 5 minutes after clicking
+**Publish** for the artifacts to go live.

docs_src/src_mdbook/src/notes/performance_analysis.md

@@ -0,0 +1,129 @@
+# Performance Analysis
+
+## Android
+
+### Prerequisites
+
+- Download and install Android GPU Inspector (AGI). See https://developer.android.com/agi.
+
+---
+
+#### Profiling
+
+1. Before profiling the application or analyzing the performance in a consistent way, ideally
+   the **GPU frequency on the target hardware should get locked**. In order to do this, you need to do the following:
+   1. Ensure your device is OEM unlocked. If your phone is carrier-locked, you may need
+      to wait a period, such as 60 or 90 days after activation to be eligible for unlocking.
+      Some phones don't support this at all. You will need to enable developer options
+      (e.g. Settings > About Phone and tap the Build number 7 times). You need to go to
+      Settings > System > Developer options and toggle on "OEM unlocking".
+   1. Next, you need to unlock the phone. You will need to install Android SDK Platform
+      Tools on you computer, enable "USB debugging" in your phone's Settings > System > Developer options.
+   1. Connect the phone to the computer via a USB cable and run from the command line:
+      ```shell
+      adb reboot bootloader
+      # once the phone is in bootloader mode, run the following to begin the unlocking
+      # process:
+      fastboot flashing unlock
+      ```
+      A warning will appear on your phone's screen. Use the volume buttons to navigate and
+      the power button to select the "Unlock the bootloader" option. The phone will perform
+      a factory data reset and reboot with an unlocked bootloader.
+   1. You would need to flash an image to the phone with root permissions, such as a *-userdebug or *-eng
+      build. One way to do this is with the [Android Flash Tool](https://flash.android.com/). Connect the
+      tool to your device and find a build to flash ending in `-userdebug` or `-eng`. Once you have that
+      selected run `Install build`.
+   1. Shell into your device as root and configure the gpu frequency to be locked, e.g.:
+      ```shell
+      adb shell
+      su
+      # navigate to the system GPU directory. this varies on different phones. One phone might have
+      # it at /sys/class/kgsl/kgsl-3d0 and another might be in something similar, maybe with "mali" instead
+      # of "kgsl". At the time of writing this for the device at hand it was /sys/devices/platform/1f000000.mali
+      cd /sys/devices/platform/1f000000.mali
+      # get the current available GPU governors and frequencies.
+      # note that some systems may have these at gpu_available_governors and gpu_available_frequencies, but
+      # the system at the time of writing this had available_governors and available_frequences
+      cat available_governors
+      cat available_frequencies
+      # depending on the governors, you may want to set it prioritize performance over other things like
+      # battery. Some systems allow you to do this with something like (although, for the device used at the
+      # time of writing this did not have an equivalent option):
+      echo performance > gpu_governor
+      # finally, lock your frequency in, usually to something high like 897 MHz. Some systems may have you
+      # pipe the value to gpu_min_freq and gpu_max_freq, but the system used at the time of writing this had:
+      echo 940000 > hint_min_freq
+      echo 940000 > hint_max_freq
+      # you can typically verify the GPU is running at that frequency consistently by running something like
+      # the following a few times over time, which should show the frequency you want to lock the device to:
+      cat cur_freq
+      ```
+   1. You may need to re-apply the `hint_min_freq` just before starting the profiling trace and check before and after
+      that the frequency remained at the value expected. Some systems may adjust the frequency on you, but you
+      may want to ensure the frequency remains the same through the analysis.
+   1. The GPU frequency settings should be undone after restarting the device, but after you have done your app profiling,
+      you can revert the state of the device, such as the OS build image, back to the way you had it
+      initially, as needed.
+1. Build a release build of Filament with the applicable backend(s) enabled
+   _(+ any special flags for enabling sys strace. Nothing special is needed for Vulkan or WebGPU aside from
+   building a release build with no flags)_ _(debug builds for this are useless)_
+
+    ```shell
+    # the following command assumes you are in the root filament directory
+    # and ANDROID_HOME is exported (and possibly also CC and CXX on linux as needed)
+    #
+    # NOTE: to build with WebGPU support you need to explicitly include the -W flag
+    # (it doesn't get compiled in by default), e.g.:
+    # ./build.sh -W -p android,desktop -i release
+    #
+    # Note that you can speed this up a bit (and reduce disk space usage) by limiting the target to just 
+    # the ABI you plan on testing with the -q flag, e.g. -q arm64-v8a. If you do this, you
+    # will need to update the android/gradle.properties file to specify the ABI(s) you are targeting
+    # with the com.google.android.filament.abis property.
+    # Thus, a build command that would target BOTH Vulkan AND WebGPU AND only target the ARM64 ABI would look something
+    # like:
+    # ./build.sh -W -q arm64-v8a -p android,desktop -i release
+    ./build.sh -p android,desktop -i release
+    ```
+1. Connect your Android device to your computer via a USB cord with USB debugging enabled and configure
+   the system property to default to the desired backend, e.g.
+   _(to determine how these numbers map to the backends, see the `enum class Backend`
+   definition in [filament/filament/backend/include/backend/DriverEnums.h](../../../../filament/backend/include/backend/DriverEnums.h))_:
+    ```shell
+    # to set the backend to Vulkan: 
+    adb shell setprop debug.filament.backend 2
+    # to set the backend to WebGPU:
+    adb shell setprop debug.filament.backend 4
+    # to view the current property:
+    adb shell getprop debug.filament.backend
+    ```
+1. Build and run a sample, e.g. sample-gltf-viewer, on your Android device
+   _([Android Studio](https://developer.android.com/studio) recommended)_.
+1. Run [AGI](https://developer.android.com/agi) and follow instructions to profile the app/system
+   with trace capture(s). See https://developer.android.com/agi/start for more details to
+   get started.
+   - We typically only run "Capture System Profiler trace" _(not necessarily "Capture Frame Profiler trace")_
+   - When configuring the trace:
+     - For both the WebGPU and Vulkan backends configure the profiler for the Vulkan API
+       _(since WebGPU should be using Vulkan under the hood as well)_
+     - Running for ~1 seconds should suffice
+     - Hit the "Configure" button in Trace objects, select "Switch to advanced mode" and add:
+       ```
+       data_sources {
+         config {
+           name: "track_event"
+           track_event_config {
+             disabled_categories: "*"
+             enabled_categories: "filament/filament"
+             enabled_categories: "filament/jobsystem"
+             enabled_categories: "filament/gltfio"
+           }
+         }
+       }
+       ```
+   - One you open the trace, zoom into a series of frames to get a sense of generally how long they typically take
+    _(use `W`, `S`, `A` and `D` keys and mouse wheel for navigation)_ and find a representative one.
+     We are most interested in the performance of the
+     `FEngine::loop` thread, how long it takes, overlap in activities/processes/commands, reduction in queue submissions,
+     etc. Similarly, we can view GPU timeline as it relates to that. We want to see overlapping
+     shader invocations and non-interrupted fragment shader runs.

docs_src/src_mdbook/src/notes/tests.md

@@ -0,0 +1,4 @@
+# Tests
+
+Filament has a collection of tests that can be run locally. Many of them are used
+for in our Continuation Integration flow [on github](https://https://github.com/google/filament/tree/main/.github/workflows).

filament/CMakeLists.txt

@@ -40,6 +40,7 @@ set(PUBLIC_HDRS
         include/filament/Skybox.h
         include/filament/Stream.h
         include/filament/SwapChain.h
+        include/filament/Sync.h
         include/filament/Texture.h
         include/filament/TextureSampler.h
         include/filament/ToneMapper.h
@@ -83,6 +84,8 @@ set(SRCS
         src/InstanceBuffer.cpp
         src/LightManager.cpp
         src/Material.cpp
+        src/MaterialCache.cpp
+        src/MaterialDefinition.cpp
         src/MaterialInstance.cpp
         src/MaterialInstanceManager.cpp
         src/MaterialParser.cpp
@@ -103,6 +106,7 @@ set(SRCS
         src/Skybox.cpp
         src/Stream.cpp
         src/SwapChain.cpp
+        src/Sync.cpp
         src/Texture.cpp
         src/ToneMapper.cpp
         src/TransformManager.cpp
@@ -113,6 +117,7 @@ set(SRCS
         src/components/LightManager.cpp
         src/components/RenderableManager.cpp
         src/components/TransformManager.cpp
+        src/details/BufferAllocator.cpp
         src/details/BufferObject.cpp
         src/details/Camera.cpp
         src/details/ColorGrading.cpp
@@ -132,6 +137,7 @@ set(SRCS
         src/details/Skybox.cpp
         src/details/Stream.cpp
         src/details/SwapChain.cpp
+        src/details/Sync.cpp
         src/details/Texture.cpp
         src/details/VertexBuffer.cpp
         src/details/View.cpp
@@ -172,6 +178,8 @@ set(PRIVATE_HDRS
         src/HwRenderPrimitiveFactory.h
         src/HwVertexBufferInfoFactory.h
         src/Intersections.h
+        src/MaterialCache.h
+        src/MaterialDefinition.h
         src/MaterialParser.h
         src/MaterialInstanceManager.h
         src/PIDController.h
@@ -189,6 +197,7 @@ set(PRIVATE_HDRS
         src/components/LightManager.h
         src/components/RenderableManager.h
         src/components/TransformManager.h
+        src/details/BufferAllocator.h
         src/details/BufferObject.h
         src/details/Camera.h
         src/details/ColorGrading.h
@@ -242,9 +251,10 @@ set(PRIVATE_HDRS
 set(MATERIAL_SRCS
         src/materials/antiAliasing/fxaa/fxaa.mat
         src/materials/antiAliasing/taa/taa.mat
+        src/materials/blitArray.mat
         src/materials/blitDepth.mat
         src/materials/blitLow.mat
-        src/materials/blitArray.mat
+        src/materials/clearDepth.mat
         src/materials/bloom/bloomDownsample.mat
         src/materials/bloom/bloomDownsample2x.mat
         src/materials/bloom/bloomDownsample9.mat

filament/backend/CMakeLists.txt

@@ -78,6 +78,8 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3)
             src/opengl/GLTexture.h
             src/opengl/GLUtils.cpp
             src/opengl/GLUtils.h
+            src/opengl/GLMemoryMappedBuffer.cpp
+            src/opengl/GLMemoryMappedBuffer.h
             src/opengl/OpenGLBlobCache.cpp
             src/opengl/OpenGLBlobCache.h
             src/opengl/OpenGLContext.cpp
@@ -177,6 +179,7 @@ endif()
 if (FILAMENT_SUPPORTS_VULKAN)
     list(APPEND SRCS
             include/backend/platforms/VulkanPlatform.h
+            src/vulkan/VulkanAsyncHandles.cpp
             src/vulkan/VulkanAsyncHandles.h
             src/vulkan/VulkanBlitter.cpp
             src/vulkan/VulkanBlitter.h
@@ -215,6 +218,10 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanReadPixels.h
             src/vulkan/VulkanSamplerCache.cpp
             src/vulkan/VulkanSamplerCache.h
+            src/vulkan/VulkanSemaphore.cpp
+            src/vulkan/VulkanSemaphore.h
+            src/vulkan/VulkanSemaphoreManager.cpp
+            src/vulkan/VulkanSemaphoreManager.h
             src/vulkan/VulkanStagePool.cpp
             src/vulkan/VulkanStagePool.h
             src/vulkan/VulkanSwapChain.cpp
@@ -287,6 +294,8 @@ if (FILAMENT_SUPPORTS_WEBGPU)
             src/webgpu/WebGPUPipelineLayoutCache.h
             src/webgpu/WebGPUProgram.cpp
             src/webgpu/WebGPUProgram.h
+            src/webgpu/WebGPUQueueManager.cpp
+            src/webgpu/WebGPUQueueManager.h
             src/webgpu/WebGPURenderPassMipmapGenerator.cpp
             src/webgpu/WebGPURenderPassMipmapGenerator.h
             src/webgpu/WebGPURenderPrimitive.h
@@ -295,6 +304,7 @@ if (FILAMENT_SUPPORTS_WEBGPU)
             src/webgpu/WebGPUStrings.h
             src/webgpu/WebGPUSwapChain.cpp
             src/webgpu/WebGPUSwapChain.h
+            src/webgpu/WebGPUSync.h
             src/webgpu/WebGPUTexture.cpp
             src/webgpu/WebGPUTexture.h
             src/webgpu/WebGPUTextureHelpers.h
@@ -494,9 +504,6 @@ else()
             -Wover-aligned -Wreorder-init-list
             -Werror
     )
-    if (CMAKE_CXX_STANDARD EQUAL 20)
-        list(APPEND FILAMENT_WARNINGS -Wno-deprecated-this-capture)
-    endif()
 endif()
 
 if (APPLE)
@@ -530,7 +537,7 @@ target_link_libraries(${TARGET} PRIVATE
 if (LINUX AND FILAMENT_SUPPORTS_WEBGPU)
     # Unclear why this needs to be explicit while other linux libs do not, but it is necessary for
     # WebGPU to build on linux.
-    target_link_libraries(${TARGET} PRIVATE -lxcb)
+    target_link_libraries(${TARGET} PRIVATE -lxcb -lX11)
 endif()
 
 # ==================================================================================================
@@ -568,6 +575,7 @@ if (APPLE OR LINUX)
         test/test_ReadPixels.cpp
         test/test_BufferUpdates.cpp
         test/test_Callbacks.cpp
+        test/test_MemoryMappedBuffer.cpp
         test/test_MRT.cpp
         test/test_PushConstants.cpp
         test/test_LoadImage.cpp
@@ -580,7 +588,9 @@ if (APPLE OR LINUX)
         test/test_Template.cpp
     )
     if (FILAMENT_SUPPORTS_WEBGPU)
-        list(APPEND BACKEND_TEST_SRC test/test_WebGPUAsyncTaskCounter.cpp)
+        list(APPEND BACKEND_TEST_SRC
+                test/test_WebGPUAsyncTaskCounter.cpp
+                test/test_WebGPUComposeSwizzle.cpp)
     endif()
     if (APPLE)
         # Metal-specific tests
@@ -629,6 +639,10 @@ if (APPLE AND NOT IOS)
         target_link_libraries(backend_test PRIVATE image imageio)
         list(APPEND BACKEND_TEST_DEPS image)
     endif()
+    if (FILAMENT_SUPPORTS_WEBGPU)
+        target_link_libraries(backend_test PRIVATE webgpu_dawn dawncpp_headers)
+        list(APPEND BACKEND_TEST_DEPS webgpu_dawn dawncpp_headers)
+    endif()
 
     set(BACKEND_TEST_COMBINED_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/libbackendtest_combined.a")
     combine_static_libs(backend_test "${BACKEND_TEST_COMBINED_OUTPUT}" "${BACKEND_TEST_DEPS}")
@@ -660,6 +674,9 @@ if (LINUX)
     add_executable(backend_test_linux test/linux_runner.cpp ${BACKEND_TEST_SRC})
     target_link_libraries(backend_test_linux PRIVATE ${BACKEND_TEST_LIBS})
     set_target_properties(backend_test_linux PROPERTIES FOLDER Tests)
+    if (FILAMENT_SUPPORTS_WEBGPU)
+        target_link_libraries(backend_test_linux PRIVATE webgpu_dawn dawncpp_headers)
+    endif()
 endif()
 
 # ==================================================================================================

filament/backend/include/backend/DriverEnums.h

@@ -101,6 +101,16 @@ static constexpr uint64_t SWAP_CHAIN_HAS_STENCIL_BUFFER         = SWAP_CHAIN_CON
  */
 static constexpr uint64_t SWAP_CHAIN_CONFIG_PROTECTED_CONTENT   = 0x40;
 
+/**
+ * Indicates that the SwapChain is configured to use Multi-Sample Anti-Aliasing (MSAA) with the
+ * given sample points within each pixel. Only supported when isMSAASwapChainSupported(4) is
+ * true.
+ *
+ * This is only supported by EGL(Android). Other GL platforms (GLX, WGL, etc) don't support it
+ * because the swapchain MSAA settings must be configured before window creation.
+ */
+static constexpr uint64_t SWAP_CHAIN_CONFIG_MSAA_4_SAMPLES      = 0x80;
+
 static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT  = 16;   // This is guaranteed by OpenGL ES.
 static constexpr size_t MAX_SAMPLER_COUNT           = 62;   // Maximum needed at feature level 3.
 static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
@@ -187,6 +197,7 @@ constexpr std::string_view to_string(Backend const backend) noexcept {
  * - The Metal backend can prefer precompiled Metal libraries, while falling back to MSL.
  */
 enum class ShaderLanguage {
+    UNSPECIFIED = -1,
     ESSL1 = 0,
     ESSL3 = 1,
     SPIRV = 2,
@@ -209,6 +220,8 @@ constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguage) noex
             return "Metal precompiled library";
         case ShaderLanguage::WGSL:
             return "WGSL";
+        case ShaderLanguage::UNSPECIFIED:
+            return "Unspecified";
     }
     return "UNKNOWN";
 }
@@ -546,12 +559,21 @@ constexpr TargetBufferFlags getTargetBufferFlagsAt(size_t index) noexcept {
 }
 
 /**
- * Frequency at which a buffer is expected to be modified and used. This is used as an hint
- * for the driver to make better decisions about managing memory internally.
+ * How the buffer will be used.
  */
 enum class BufferUsage : uint8_t {
-    STATIC,      //!< content modified once, used many times
-    DYNAMIC,     //!< content modified frequently, used many times
+    STATIC              = 0,    //!< (legacy) content modified once, used many times
+    DYNAMIC             = 1,    //!< (legacy) content modified frequently, used many times
+    DYNAMIC_BIT         = 0x1,  //!< buffer can be modified frequently, used many times
+    SHARED_WRITE_BIT    = 0x04, //!< buffer can be memory mapped for write operations
+};
+
+/**
+ * How the buffer will be mapped.
+ */
+enum class MapBufferAccessFlags : uint8_t {
+    WRITE_BIT               = 0x2,  //!< buffer is mapped from writing
+    INVALIDATE_RANGE_BIT    = 0x4,  //!< the mapped range content is lost
 };
 
 /**
@@ -617,6 +639,15 @@ enum class ShaderModel : uint8_t {
 };
 static constexpr size_t SHADER_MODEL_COUNT = 2;
 
+constexpr std::string_view to_string(ShaderModel model) noexcept {
+    switch (model) {
+        case ShaderModel::MOBILE:
+            return "mobile";
+        case ShaderModel::DESKTOP:
+            return "desktop";
+    }
+}
+
 /**
  * Primitive types
  */
@@ -629,6 +660,18 @@ enum class PrimitiveType : uint8_t {
     TRIANGLE_STRIP = 5     //!< triangle strip
 };
 
+[[nodiscard]] constexpr bool isStripPrimitiveType(const PrimitiveType type) {
+    switch (type) {
+        case PrimitiveType::POINTS:
+        case PrimitiveType::LINES:
+        case PrimitiveType::TRIANGLES:
+            return false;
+        case PrimitiveType::LINE_STRIP:
+        case PrimitiveType::TRIANGLE_STRIP:
+            return true;
+    }
+}
+
 /**
  * Supported uniform types
  */
@@ -670,6 +713,12 @@ enum class Precision : uint8_t {
     DEFAULT
 };
 
+union ConstantValue {
+    int32_t i;
+    float f;
+    bool b;
+};
+
 /**
  * Shader compiler priority queue
  *
@@ -1654,6 +1703,8 @@ enum class Workaround : uint16_t {
     // prevents these stutters by not precaching depth variants of the default material for those
     // particular browsers.
     DISABLE_DEPTH_PRECACHE_FOR_DEFAULT_MATERIAL,
+    // Emulate an sRGB swapchain in shader code.
+    EMULATE_SRGB_SWAPCHAIN,
 };
 
 using StereoscopicType = backend::Platform::StereoscopicType;
@@ -1670,6 +1721,11 @@ template<> struct utils::EnableBitMaskOperators<filament::backend::TextureUsage>
         : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::StencilFace>
         : public std::true_type {};
+template<> struct utils::EnableBitMaskOperators<filament::backend::BufferUsage>
+        : public std::true_type {};
+template<> struct utils::EnableBitMaskOperators<filament::backend::MapBufferAccessFlags>
+        : public std::true_type {};
+
 template<> struct utils::EnableIntegerOperators<filament::backend::TextureCubemapFace>
         : public std::true_type {};
 template<> struct utils::EnableIntegerOperators<filament::backend::FeatureLevel>

filament/backend/include/backend/Handle.h

@@ -38,12 +38,14 @@ struct HwRenderPrimitive;
 struct HwRenderTarget;
 struct HwStream;
 struct HwSwapChain;
+struct HwSync;
 struct HwTexture;
 struct HwTimerQuery;
 struct HwVertexBufferInfo;
 struct HwVertexBuffer;
 struct HwDescriptorSetLayout;
 struct HwDescriptorSet;
+struct HwMemoryMappedBuffer;
 
 /*
  * A handle to a backend resource. HandleBase is for internal use only.
@@ -151,12 +153,14 @@ using RenderPrimitiveHandle     = Handle<HwRenderPrimitive>;
 using RenderTargetHandle        = Handle<HwRenderTarget>;
 using StreamHandle              = Handle<HwStream>;
 using SwapChainHandle           = Handle<HwSwapChain>;
+using SyncHandle                = Handle<HwSync>;
 using TextureHandle             = Handle<HwTexture>;
 using TimerQueryHandle          = Handle<HwTimerQuery>;
 using VertexBufferHandle        = Handle<HwVertexBuffer>;
 using VertexBufferInfoHandle    = Handle<HwVertexBufferInfo>;
 using DescriptorSetLayoutHandle = Handle<HwDescriptorSetLayout>;
 using DescriptorSetHandle       = Handle<HwDescriptorSet>;
+using MemoryMappedBufferHandle  = Handle<HwMemoryMappedBuffer>;
 
 } // namespace filament::backend
 

filament/backend/include/backend/Platform.h

@@ -29,6 +29,7 @@
 
 namespace filament::backend {
 
+class CallbackHandler;
 class Driver;
 
 /**
@@ -42,6 +43,9 @@ public:
     struct SwapChain {};
     struct Fence {};
     struct Stream {};
+    struct Sync {};
+
+    using SyncCallback = void(*)(Sync* UTILS_NONNULL sync, void* UTILS_NULLABLE userData);
 
     class ExternalImageHandle;
 
@@ -232,7 +236,7 @@ public:
      * @return nullptr on failure, or a pointer to the newly created driver.
      */
     virtual Driver* UTILS_NULLABLE createDriver(void* UTILS_NULLABLE sharedContext,
-            const DriverConfig& driverConfig) noexcept = 0;
+            const DriverConfig& driverConfig) = 0;
 
     /**
      * Processes the platform's event queue when called from its primary event-handling thread.

filament/backend/include/backend/PresentCallable.h

@@ -27,12 +27,12 @@ namespace filament::backend {
  * A PresentCallable is a callable object that, when called, schedules a frame for presentation on
  * a SwapChain.
  *
- * Typically, Filament's backend is responsible scheduling a frame's presentation. However, there
- * are certain cases where the application might want to control when a frame is scheduled for
+ * Typically, Filament's backend is responsible for scheduling a frame's presentation. However,
+ * there are certain cases where the application might want to control when a frame is scheduled for
  * presentation.
  *
  * For example, on iOS, UIKit elements can be synchronized to 3D content by scheduling a present
- * within a CATransation:
+ * within a CATransaction:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  * void myFrameScheduledCallback(PresentCallable presentCallable, void* user) {
@@ -55,12 +55,13 @@ namespace filament::backend {
  * }
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
- * backends ignore the callback (which will never be called) and proceed normally.
+ * @remark The PresentCallable mechanism for user-controlled presentation is only supported by
+ * Filament's Metal backend. On other backends, the FrameScheduledCallback is still invoked, but the
+ * PresentCallable passed to it is a no-op and calling it has no effect.
  *
- * Applications *must* call each PresentCallable they receive. Each PresentCallable represents a
- * frame that is waiting to be presented. If an application fails to call a PresentCallable, a
- * memory leak could occur. To "cancel" the presentation of a frame, pass false to the
+ * When using the Metal backend, applications *must* call each PresentCallable they receive. Each
+ * PresentCallable represents a frame that is waiting to be presented, and failing to call it
+ * will result in a memory leak. To "cancel" the presentation of a frame, pass false to the
  * PresentCallable, which will cancel the presentation of the frame and release associated memory.
  *
  * @see Renderer, SwapChain::setFrameScheduledCallback
@@ -69,6 +70,7 @@ class UTILS_PUBLIC PresentCallable {
 public:
 
     using PresentFn = void(*)(bool presentFrame, void* user);
+    static void noopPresent(bool, void*) {}
 
     PresentCallable(PresentFn fn, void* user) noexcept;
     ~PresentCallable() noexcept = default;

filament/backend/include/backend/Program.h

@@ -50,11 +50,7 @@ public:
         descriptor_binding_t binding;
     };
 
-    struct SpecializationConstant {
-        using Type = std::variant<int32_t, float, bool>;
-        uint32_t id;    // id set in glsl
-        Type value;     // value and type
-    };
+    using SpecializationConstant = std::variant<int32_t, float, bool>;
 
     struct Uniform { // For ES2 support
         utils::CString name;    // full qualified name of the uniform field
@@ -118,7 +114,7 @@ public:
     Program& multiview(bool multiview) noexcept;
 
     // For ES2 support only...
-    Program& uniforms(uint32_t index, utils::CString name, UniformInfo uniforms) noexcept;
+    Program& uniforms(uint32_t index, utils::CString name, UniformInfo uniforms);
     Program& attributes(AttributesInfo attributes) noexcept;
 
     //

filament/backend/include/backend/platforms/OpenGLPlatform.h

@@ -85,6 +85,15 @@ public:
      */
     virtual bool isSRGBSwapChainSupported() const noexcept;
 
+    /**
+     * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_MSAA_*_SAMPLES flag.
+     * The default implementation returns false.
+     *
+     * @param samples The number of samples
+     * @return true if SWAP_CHAIN_CONFIG_MSAA_*_SAMPLES is supported, false otherwise.
+     */
+    virtual bool isMSAASwapChainSupported(uint32_t samples) const noexcept;
+
     /**
      * Return whether protected contexts are supported by this backend.
      * If protected context are supported, the SWAP_CHAIN_CONFIG_PROTECTED_CONTENT flag can be
@@ -103,7 +112,7 @@ public:
      *
      */
     virtual SwapChain* UTILS_NULLABLE createSwapChain(
-            void* UTILS_NULLABLE nativeWindow, uint64_t flags) noexcept = 0;
+            void* UTILS_NULLABLE nativeWindow, uint64_t flags) = 0;
 
     /**
      * Called by the driver create a headless SwapChain.
@@ -117,7 +126,7 @@ public:
      *       A void* might be enough.
      */
     virtual SwapChain* UTILS_NULLABLE createSwapChain(
-            uint32_t width, uint32_t height, uint64_t flags) noexcept = 0;
+            uint32_t width, uint32_t height, uint64_t flags) = 0;
 
     /**
      * Called by the driver to destroys the SwapChain
@@ -276,6 +285,26 @@ public:
      */
     virtual backend::FenceStatus waitFence(Fence* UTILS_NONNULL fence, uint64_t timeout) noexcept;
 
+    // --------------------------------------------------------------------------------------------
+    // Sync support
+
+    /**
+     * Creates a Sync. These can be used for frame synchronization externally
+     * (certain platform implementations can be exported to handles that can
+     * be used in other processes).
+     *
+     * @return A Sync object.
+     */
+    virtual Platform::Sync* UTILS_NONNULL createSync() noexcept;
+
+    /**
+     * Destroys a sync. If called with a sync not created by this platform
+     * object, this will lead to undefined behavior.
+     *
+     * @param sync The sync to destroy, that was created by this platform
+     *             instance.
+     */
+    virtual void destroySync(Platform::Sync* UTILS_NONNULL sync) noexcept;
 
     // --------------------------------------------------------------------------------------------
     // Streaming support

filament/backend/include/backend/platforms/PlatformCocoaGL.h

@@ -40,7 +40,7 @@ protected:
     // Platform Interface
 
     Driver* createDriver(void* sharedContext,
-            const DriverConfig& driverConfig) noexcept override;
+            const DriverConfig& driverConfig) override;
 
     // Currently returns 0
     int getOSVersion() const noexcept override;

filament/backend/include/backend/platforms/PlatformCocoaTouchGL.h

@@ -38,7 +38,7 @@ public:
     // Platform Interface
 
     Driver* createDriver(void* sharedGLContext,
-            const DriverConfig& driverConfig) noexcept override;
+            const DriverConfig& driverConfig) override;
 
     int getOSVersion() const noexcept final { return 0; }
 

filament/backend/include/backend/platforms/PlatformEGL.h

@@ -80,7 +80,7 @@ protected:
      * Initializes EGL, creates the OpenGL context and returns a concrete Driver implementation
      * that supports OpenGL/OpenGL ES.
      */
-    Driver* createDriver(void* sharedContext, const DriverConfig& driverConfig) noexcept override;
+    Driver* createDriver(void* sharedContext, const DriverConfig& driverConfig) override;
 
     /**
      * This returns zero. This method can be overridden to return something more useful.
@@ -98,10 +98,11 @@ protected:
     void terminate() noexcept override;
 
     bool isProtectedContextSupported() const noexcept override;
-
     bool isSRGBSwapChainSupported() const noexcept override;
-    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
-    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
+    bool isMSAASwapChainSupported(uint32_t samples) const noexcept override;
+
+    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) override;
+    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) override;
     void destroySwapChain(SwapChain* swapChain) noexcept override;
     bool isSwapChainProtected(SwapChain* swapChain) noexcept override;
 
@@ -167,6 +168,7 @@ protected:
     EGLConfig mEGLConfig = EGL_NO_CONFIG_KHR;
     Config mContextAttribs;
     std::vector<EGLContext> mAdditionalContexts;
+    bool mMSAA4XSupport = false;
 
     // supported extensions detected at runtime
     struct {
@@ -217,6 +219,8 @@ private:
             return makeCurrent(mCurrentContext, drawSurface, readSurface);
         }
     } egl{ mEGLDisplay };
+
+    bool checkIfMSAASwapChainSupported(uint32_t samples) const noexcept;
 };
 
 } // namespace filament::backend

filament/backend/include/backend/platforms/PlatformEGLAndroid.h

@@ -58,6 +58,17 @@ public:
 
     ExternalImageDescAndroid UTILS_PUBLIC getExternalImageDesc(ExternalImageHandle externalImage) noexcept;
 
+    /**
+     * Converts a sync to an external file descriptor, if possible. Accepts an
+     * opaque handle to a sync, as well as a pointer to where the fd should be
+     * stored.
+     * @param sync The sync to be converted to a file descriptor.
+     * @param fd   A pointer to where the file descriptor should be stored.
+     * @return `true` on success, `false` on failure. The default implementation
+     *         returns `false`.
+     */
+    bool convertSyncToFd(Platform::Sync* sync, int* fd) noexcept;
+
 protected:
     // --------------------------------------------------------------------------------------------
     // Platform Interface
@@ -69,11 +80,15 @@ protected:
     int getOSVersion() const noexcept override;
 
     Driver* createDriver(void* sharedContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const Platform::DriverConfig& driverConfig) override;
 
     // --------------------------------------------------------------------------------------------
     // OpenGLPlatform Interface
 
+    struct SyncEGLAndroid : public Platform::Sync {
+        EGLSyncKHR sync;
+    };
+
     void terminate() noexcept override;
 
     void beginFrame(
@@ -89,9 +104,10 @@ protected:
      */
     void setPresentationTime(int64_t presentationTimeInNanosecond) noexcept override;
 
-
     Stream* createStream(void* nativeStream) noexcept override;
     void destroyStream(Stream* stream) noexcept override;
+    Platform::Sync* createSync() noexcept override;
+    void destroySync(Platform::Sync* sync) noexcept override;
     void attach(Stream* stream, intptr_t tname) noexcept override;
     void detach(Stream* stream) noexcept override;
     void updateTexImage(Stream* stream, int64_t* timestamp) noexcept override;

filament/backend/include/backend/platforms/PlatformEGLHeadless.h

@@ -29,7 +29,7 @@ public:
     PlatformEGLHeadless() noexcept;
 
     Driver* createDriver(void* sharedContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const Platform::DriverConfig& driverConfig) override;
 
 protected:
     bool isOpenGL() const noexcept override;

filament/backend/include/backend/platforms/PlatformGLX.h

@@ -39,7 +39,7 @@ protected:
     // Platform Interface
 
     Driver* createDriver(void* sharedGLContext,
-            const DriverConfig& driverConfig) noexcept override;
+            const DriverConfig& driverConfig) override;
 
     int getOSVersion() const noexcept final override { return 0; }
 
@@ -55,9 +55,9 @@ protected:
     void commit(SwapChain* swapChain) noexcept override;
 
 private:
-    Display *mGLXDisplay;
-    GLXContext mGLXContext;
-    GLXFBConfig* mGLXConfig;
+    Display* mGLXDisplay;
+    GLXContext mGLXContext{};
+    GLXFBConfig mGLXConfig{};
     GLXPbuffer mDummySurface;
     std::vector<GLXPbuffer> mPBuffers;
 };

filament/backend/include/backend/platforms/PlatformMetal.h

@@ -36,7 +36,7 @@ public:
     PlatformMetal();
     ~PlatformMetal() noexcept override;
 
-    Driver* createDriver(void* sharedContext, const Platform::DriverConfig& driverConfig) noexcept override;
+    Driver* createDriver(void* sharedContext, const Platform::DriverConfig& driverConfig) override;
     int getOSVersion() const noexcept override { return 0; }
 
     /**

filament/backend/include/backend/platforms/PlatformOSMesa.h

@@ -43,7 +43,7 @@ protected:
     // --------------------------------------------------------------------------------------------
     // Platform Interface
 
-    Driver* createDriver(void* sharedGLContext, const DriverConfig& driverConfig) noexcept override;
+    Driver* createDriver(void* sharedGLContext, const DriverConfig& driverConfig) override;
 
     int getOSVersion() const noexcept final override { return 0; }
 

filament/backend/include/backend/platforms/PlatformWGL.h

@@ -38,7 +38,7 @@ protected:
     // Platform Interface
 
     Driver* createDriver(void* sharedGLContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const Platform::DriverConfig& driverConfig) override;
 
     int getOSVersion() const noexcept final override { return 0; }
 
@@ -61,8 +61,12 @@ protected:
     HWND mHWnd = NULL;
     HDC mWhdc = NULL;
     PIXELFORMATDESCRIPTOR mPfd = {};
-    std::vector<HGLRC> mAdditionalContexts;
     std::vector<int> mAttribs;
+
+    // For shared contexts
+    static constexpr int SHARED_CONTEXT_NUM = 1;
+    std::vector<HGLRC> mAdditionalContexts;
+    std::atomic<int> mNextFreeSharedContextIndex{0};
 };
 
 } // namespace filament::backend

filament/backend/include/backend/platforms/PlatformWebGL.h

@@ -34,7 +34,7 @@ protected:
     // Platform Interface
 
     Driver* createDriver(void* sharedGLContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const Platform::DriverConfig& driverConfig) override;
 
     int getOSVersion() const noexcept override;
 

filament/backend/include/backend/platforms/VulkanPlatform.h

@@ -17,8 +17,9 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORM_H
 #define TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORM_H
 
-#include <backend/Platform.h>
+#include <backend/CallbackHandler.h>
 #include <backend/DriverEnums.h>
+#include <backend/Platform.h>
 
 #include <bluevk/BlueVK.h>
 
@@ -29,9 +30,9 @@
 
 #include <cstddef>
 #include <functional>
+#include <string>
 #include <tuple>
 #include <unordered_set>
-#include <string>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -45,6 +46,10 @@ using SwapChain = Platform::SwapChain;
  */
 struct VulkanPlatformPrivate;
 
+// Forward declare the fence status that will be maintained by the command
+// buffer manager.
+struct VulkanCmdFence;
+
 /**
  * A Platform interface that creates a Vulkan backend.
  */
@@ -114,7 +119,7 @@ public:
     ~VulkanPlatform() override;
 
     Driver* createDriver(void* sharedContext,
-            Platform::DriverConfig const& driverConfig) noexcept override;
+            Platform::DriverConfig const& driverConfig) override;
 
     int getOSVersion() const noexcept override {
         return 0;
@@ -229,6 +234,25 @@ public:
     virtual SwapChainPtr createSwapChain(void* nativeWindow, uint64_t flags = 0,
             VkExtent2D extent = {0, 0});
 
+    /**
+     * Creates a Platform::Sync object, which tracks a fence and its status,
+     * and allows conversion to an external sync.
+     * @param fence         The underlying VkFence to use for synchronization.
+     * @param fenceStatus   An object tracking the fence's state
+     * @return              A Platform::Sync object tracking the provided fence.
+     */
+    virtual Platform::Sync* createSync(VkFence fence,
+            std::shared_ptr<VulkanCmdFence> fenceStatus) noexcept;
+
+    /**
+     * Destroys a sync. If called with a sync not created by this platform
+     * object, this will lead to undefined behavior.
+     *
+     * @param sync The sync to destroy, which was created by this platform
+     *             instance.
+     */
+    virtual void destroySync(Platform::Sync* sync) noexcept;
+
     /**
      * Allows implementers to provide instance extensions that they'd like to include in the
      * instance creation.
@@ -408,12 +432,19 @@ public:
     }
 
 protected:
+    struct VulkanSync : public Platform::Sync {
+        VkFence fence;
+        std::shared_ptr<VulkanCmdFence> fenceStatus;
+    };
+
     virtual ExtensionSet getSwapchainInstanceExtensions() const;
 
     using SurfaceBundle = std::tuple<VkSurfaceKHR, VkExtent2D>;
     virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
             uint64_t flags) const noexcept;
 
+    virtual VkExternalFenceHandleTypeFlagBits getFenceExportFlags() const noexcept;
+
 private:
     // Platform dependent helper methods
     static ExtensionSet getSwapchainInstanceExtensionsImpl();

filament/backend/include/backend/platforms/VulkanPlatformAndroid.h

@@ -44,6 +44,17 @@ public:
 
     virtual ImageData createVkImageFromExternal(ExternalImageHandleRef image) const override;
 
+    /**
+     * Converts a sync to an external file descriptor, if possible. Accepts an
+     * opaque handle to a sync, as well as a pointer to where the fd should be
+     * stored.
+     * @param sync The sync to be converted to a file descriptor.
+     * @param fd   A pointer to where the file descriptor should be stored.
+     * @return `true` on success, `false` on failure. The default implementation
+     *         returns `false`.
+     */
+    bool convertSyncToFd(Platform::Sync* sync, int* fd) const noexcept;
+
 protected:
     virtual ExtensionSet getSwapchainInstanceExtensions() const override;
 
@@ -51,6 +62,8 @@ protected:
     virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
             uint64_t flags) const noexcept override;
 
+    virtual VkExternalFenceHandleTypeFlagBits getFenceExportFlags() const noexcept override;
+
 private:
     struct ExternalImageVulkanAndroid : public Platform::ExternalImage {
         AHardwareBuffer* aHardwareBuffer = nullptr;

filament/backend/include/backend/platforms/WebGPUPlatform.h

@@ -19,6 +19,16 @@
 
 #include <backend/Platform.h>
 
+#if defined(__linux__) && defined(FILAMENT_SUPPORTS_X11)
+// Resolve the conflicts between webgpu_cpp.h and X11 defines
+#undef Always
+#undef Success
+#undef None
+#undef True
+#undef False
+#undef Status
+#undef Bool
+#endif
 #include <webgpu/webgpu_cpp.h>
 
 #include <cstdint>
@@ -62,7 +72,7 @@ public:
 
 protected:
     [[nodiscard]] Driver* createDriver(void* sharedContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const Platform::DriverConfig& driverConfig) override;
 
 private:
     // returns adapter request option variations applicable for the particular

filament/backend/include/private/backend/CommandStream.h

@@ -61,7 +61,7 @@ class CommandBase {
 protected:
     using Execute = Dispatcher::Execute;
 
-    constexpr explicit CommandBase(Execute execute) noexcept : mExecute(execute) {}
+    constexpr explicit CommandBase(Execute const execute) noexcept : mExecute(execute) {}
 
 public:
     // alignment of all Commands in the CommandStream
@@ -70,7 +70,7 @@ public:
     }
 
     // executes this command and returns the next one
-    inline CommandBase* execute(Driver& driver) {
+    CommandBase* execute(Driver& driver) {
         // returning the next command by output parameter allows the compiler to perform the
         // tail-call optimization in the function called by mExecute, however that comes at
         // a cost here (writing and reading the stack at each iteration), in the end it's
@@ -80,7 +80,7 @@ public:
         return reinterpret_cast<CommandBase*>(reinterpret_cast<intptr_t>(this) + next);
     }
 
-    inline ~CommandBase() noexcept = default;
+    ~CommandBase() noexcept = default;
 
 private:
     Execute mExecute;
@@ -135,7 +135,7 @@ struct CommandType<void (Driver::*)(ARGS...)> {
 
     public:
         template<typename M, typename D>
-        static inline void execute(M&& method, D&& driver, CommandBase* base, intptr_t* next) {
+        static void execute(M&& method, D&& driver, CommandBase* base, intptr_t* next) {
             Command* self = static_cast<Command*>(base);
             *next = align(sizeof(Command));
 #if DEBUG_COMMAND_STREAM
@@ -147,15 +147,15 @@ struct CommandType<void (Driver::*)(ARGS...)> {
         }
 
         // A command can be moved
-        inline Command(Command&& rhs) noexcept = default;
+        Command(Command&& rhs) noexcept = default;
 
         template<typename... A>
-        inline explicit constexpr Command(Execute execute, A&& ... args)
+        explicit constexpr Command(Execute const execute, A&& ... args) noexcept
                 : CommandBase(execute), mArgs(std::forward<A>(args)...) {
         }
 
         // placement new declared as "throw" to avoid the compiler's null-check
-        inline void* operator new(std::size_t, void* ptr) {
+        void* operator new(std::size_t, void* ptr) noexcept {
             assert_invariant(ptr);
             return ptr;
         }
@@ -171,8 +171,9 @@ class CustomCommand : public CommandBase {
     std::function<void()> mCommand;
     static void execute(Driver&, CommandBase* base, intptr_t* next);
 public:
-    inline CustomCommand(CustomCommand&& rhs) = default;
-    inline explicit CustomCommand(std::function<void()> cmd)
+    CustomCommand(CustomCommand&& rhs) = default;
+
+    explicit CustomCommand(std::function<void()> cmd)
             : CommandBase(execute), mCommand(std::move(cmd)) { }
 };
 
@@ -184,7 +185,7 @@ class NoopCommand : public CommandBase {
         *next = static_cast<NoopCommand*>(self)->mNext;
     }
 public:
-    inline constexpr explicit NoopCommand(void* next) noexcept
+    constexpr explicit NoopCommand(void* next) noexcept
             : CommandBase(execute), mNext(intptr_t((char *)next - (char *)this)) { }
 };
 
@@ -207,8 +208,8 @@ class CommandStream {
     template<typename T>
     struct AutoExecute {
         T closure;
-        inline explicit AutoExecute(T&& closure) : closure(std::forward<T>(closure)) {}
-        inline ~AutoExecute() { closure(); }
+        explicit AutoExecute(T&& closure) : closure(std::forward<T>(closure)) {}
+        ~AutoExecute() { closure(); }
     };
 
 public:
@@ -221,7 +222,7 @@ public:
 
 public:
 #define DECL_DRIVER_API(methodName, paramsDecl, params)                                         \
-    inline void methodName(paramsDecl) {                                                        \
+    inline void methodName(paramsDecl) noexcept {                                               \
         DEBUG_COMMAND_BEGIN(methodName, false, params);                                         \
         using Cmd = COMMAND_TYPE(methodName);                                                   \
         void* const p = allocateCommand(CommandBase::align(sizeof(Cmd)));                       \
@@ -230,7 +231,7 @@ public:
     }
 
 #define DECL_DRIVER_API_SYNCHRONOUS(RetType, methodName, paramsDecl, params)                    \
-    inline RetType methodName(paramsDecl) {                                                     \
+    inline RetType methodName(paramsDecl) noexcept {                                            \
         DEBUG_COMMAND_BEGIN(methodName, true, params);                                          \
         AutoExecute callOnExit([=, this](){                                                     \
             DEBUG_COMMAND_END(methodName, true);                                                \
@@ -239,7 +240,7 @@ public:
     }
 
 #define DECL_DRIVER_API_RETURN(RetType, methodName, paramsDecl, params)                         \
-    inline RetType methodName(paramsDecl) {                                                     \
+    inline RetType methodName(paramsDecl) noexcept {                                            \
         DEBUG_COMMAND_BEGIN(methodName, false, params);                                         \
         RetType result = mDriver.methodName##S();                                               \
         using Cmd = COMMAND_TYPE(methodName##R);                                                \
@@ -255,7 +256,7 @@ public:
     // This is for debugging only. Currently, CircularBuffer can only be written from a
     // single thread. In debug builds we assert this condition.
     // Call this first in the render loop.
-    inline void debugThreading() noexcept {
+    void debugThreading() noexcept {
 #ifndef NDEBUG
         mThreadId = utils::ThreadUtils::getThreadId();
 #endif
@@ -281,11 +282,11 @@ public:
      */
     template<typename PodType,
             typename = typename std::enable_if<std::is_trivially_destructible<PodType>::value>::type>
-    inline PodType* allocatePod(
+    PodType* allocatePod(
             size_t count = 1, size_t alignment = alignof(PodType)) noexcept;
 
 private:
-    inline void* allocateCommand(size_t size) {
+    void* allocateCommand(size_t const size) noexcept {
         assert_invariant(utils::ThreadUtils::isThisThread(mThreadId));
         return mCurrentBuffer.allocate(size);
     }

filament/backend/include/private/backend/Driver.h

@@ -27,6 +27,8 @@
 #include <backend/AcquiredImage.h>
 
 #include <utils/CString.h>
+#include <utils/ImmutableCString.h>
+#include <utils/FixedCapacityVector.h>
 #include <utils/compiler.h>
 
 #include <functional>
@@ -71,7 +73,11 @@ public:
 
     virtual ShaderModel getShaderModel() const noexcept = 0;
 
-    // The shader language used for shaders for this driver, used to inform matdbg.
+    // The shader languages used for shaders for this driver in order of preference, used to inform
+    // matdbg.
+    //
+    // The `preferredLanguage` is only a hint. If the backend supports it, it will appear first in
+    // the list.
     //
     // For OpenGL, this distinguishes whether the driver's shaders are powered by ESSL1 or ESSL3.
     // This information is used by matdbg to display the correct shader code to the web UI and patch
@@ -79,7 +85,8 @@ public:
     //
     // Metal shaders can either be MSL or Metal libraries, but at time of writing, matdbg can only
     // interface with MSL.
-    virtual ShaderLanguage getShaderLanguage() const noexcept = 0;
+    virtual utils::FixedCapacityVector<ShaderLanguage> getShaderLanguages(
+            ShaderLanguage preferredLanguage) const noexcept = 0;
 
     // Returns the dispatcher. This is only called once during initialization of the CommandStream,
     // so it doesn't matter that it's virtual.

filament/backend/include/private/backend/DriverAPI.inc

@@ -107,9 +107,17 @@
 #define DECL_DRIVER_API_R_N(R, N, ...) \
     DECL_DRIVER_API_RETURN(R, N, PAIR_ARGS_N(ARG, ##__VA_ARGS__), PAIR_ARGS_N(PARAM, ##__VA_ARGS__))
 
+#define DECL_DRIVER_API_TAGGED_R_N(R, N, ...) \
+    DECL_DRIVER_API_RETURN(R, N, PAIR_ARGS_N(ARG, ##__VA_ARGS__, utils::ImmutableCString&&, tag = {}), \
+            PAIR_ARGS_N(PARAM, ##__VA_ARGS__, utils::ImmutableCString&&, tag))
+
 #define DECL_DRIVER_API_SYNCHRONOUS_N(R, N, ...) \
     DECL_DRIVER_API_SYNCHRONOUS(R, N, PAIR_ARGS_N(ARG, ##__VA_ARGS__), PAIR_ARGS_N(PARAM, ##__VA_ARGS__))
 
+#define DECL_DRIVER_API_SYNCHRONOUS_TAGGED_N(R, N, ...) \
+    DECL_DRIVER_API_SYNCHRONOUS(R, N, PAIR_ARGS_N(ARG, ##__VA_ARGS__, utils::ImmutableCString, tag = {}), \
+            PAIR_ARGS_N(PARAM, ##__VA_ARGS__, utils::ImmutableCString, tag))
+
 // on some compilers the ##__VA_ARGS__ hack is not supported, so we can't handle 0-parameter APIs
 // with DECL_DRIVER_API_SYNCHRONOUS_N
 #define DECL_DRIVER_API_SYNCHRONOUS_0(R, N) \
@@ -165,35 +173,31 @@ DECL_DRIVER_API_0(finish)
 // reset state tracking, if the driver does any state tracking (e.g. GL)
 DECL_DRIVER_API_0(resetState)
 
-DECL_DRIVER_API_N(setDebugTag,
-        backend::HandleBase::HandleId, handleId,
-        utils::CString, tag)
-
 /*
  * Creating driver objects
  * -----------------------
  */
 
-DECL_DRIVER_API_R_N(backend::VertexBufferInfoHandle, createVertexBufferInfo,
+DECL_DRIVER_API_TAGGED_R_N(backend::VertexBufferInfoHandle, createVertexBufferInfo,
         uint8_t, bufferCount,
         uint8_t, attributeCount,
         backend::AttributeArray, attributes)
 
-DECL_DRIVER_API_R_N(backend::VertexBufferHandle, createVertexBuffer,
+DECL_DRIVER_API_TAGGED_R_N(backend::VertexBufferHandle, createVertexBuffer,
         uint32_t, vertexCount,
         backend::VertexBufferInfoHandle, vbih)
 
-DECL_DRIVER_API_R_N(backend::IndexBufferHandle, createIndexBuffer,
+DECL_DRIVER_API_TAGGED_R_N(backend::IndexBufferHandle, createIndexBuffer,
         backend::ElementType, elementType,
         uint32_t, indexCount,
         backend::BufferUsage, usage)
 
-DECL_DRIVER_API_R_N(backend::BufferObjectHandle, createBufferObject,
+DECL_DRIVER_API_TAGGED_R_N(backend::BufferObjectHandle, createBufferObject,
         uint32_t, byteCount,
         backend::BufferObjectBinding, bindingType,
         backend::BufferUsage, usage)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTexture,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTexture,
         backend::SamplerType, target,
         uint8_t, levels,
         backend::TextureFormat, format,
@@ -203,19 +207,19 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTexture,
         uint32_t, depth,
         backend::TextureUsage, usage)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureView,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTextureView,
         backend::TextureHandle, texture,
         uint8_t, baseLevel,
         uint8_t, levelCount)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureViewSwizzle,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTextureViewSwizzle,
         backend::TextureHandle, texture,
         backend::TextureSwizzle, r,
         backend::TextureSwizzle, g,
         backend::TextureSwizzle, b,
         backend::TextureSwizzle, a)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage2,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTextureExternalImage2,
         backend::SamplerType, target,
         backend::TextureFormat, format,
         uint32_t, width,
@@ -223,7 +227,7 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage2,
         backend::TextureUsage, usage,
         backend::Platform::ExternalImageHandleRef, image)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTextureExternalImage,
         backend::SamplerType, target,
         backend::TextureFormat, format,
         uint32_t, width,
@@ -231,7 +235,7 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage,
         backend::TextureUsage, usage,
         void*, image)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImagePlane,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, createTextureExternalImagePlane,
         backend::TextureFormat, format,
         uint32_t, width,
         uint32_t, height,
@@ -239,7 +243,7 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImagePlane,
         void*, image,
         uint32_t, plane)
 
-DECL_DRIVER_API_R_N(backend::TextureHandle, importTexture,
+DECL_DRIVER_API_TAGGED_R_N(backend::TextureHandle, importTexture,
         intptr_t, id,
         backend::SamplerType, target,
         uint8_t, levels,
@@ -250,17 +254,17 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, importTexture,
         uint32_t, depth,
         backend::TextureUsage, usage)
 
-DECL_DRIVER_API_R_N(backend::RenderPrimitiveHandle, createRenderPrimitive,
+DECL_DRIVER_API_TAGGED_R_N(backend::RenderPrimitiveHandle, createRenderPrimitive,
         backend::VertexBufferHandle, vbh,
         backend::IndexBufferHandle, ibh,
         backend::PrimitiveType, pt)
 
-DECL_DRIVER_API_R_N(backend::ProgramHandle, createProgram,
+DECL_DRIVER_API_TAGGED_R_N(backend::ProgramHandle, createProgram,
         backend::Program&&, program)
 
-DECL_DRIVER_API_R_0(backend::RenderTargetHandle, createDefaultRenderTarget)
+DECL_DRIVER_API_TAGGED_R_N(backend::RenderTargetHandle, createDefaultRenderTarget)
 
-DECL_DRIVER_API_R_N(backend::RenderTargetHandle, createRenderTarget,
+DECL_DRIVER_API_TAGGED_R_N(backend::RenderTargetHandle, createRenderTarget,
         backend::TargetBufferFlags, targetBufferFlags,
         uint32_t, width,
         uint32_t, height,
@@ -270,46 +274,32 @@ DECL_DRIVER_API_R_N(backend::RenderTargetHandle, createRenderTarget,
         backend::TargetBufferInfo, depth,
         backend::TargetBufferInfo, stencil)
 
-DECL_DRIVER_API_R_0(backend::FenceHandle, createFence)
+DECL_DRIVER_API_TAGGED_R_N(backend::FenceHandle, createFence)
 
-DECL_DRIVER_API_R_N(backend::SwapChainHandle, createSwapChain,
+DECL_DRIVER_API_TAGGED_R_N(backend::SyncHandle, createSync)
+
+DECL_DRIVER_API_TAGGED_R_N(backend::SwapChainHandle, createSwapChain,
         void*, nativeWindow,
         uint64_t, flags)
 
-DECL_DRIVER_API_R_N(backend::SwapChainHandle, createSwapChainHeadless,
+DECL_DRIVER_API_TAGGED_R_N(backend::SwapChainHandle, createSwapChainHeadless,
         uint32_t, width,
         uint32_t, height,
         uint64_t, flags)
 
-DECL_DRIVER_API_R_0(backend::TimerQueryHandle, createTimerQuery)
+DECL_DRIVER_API_TAGGED_R_N(backend::TimerQueryHandle, createTimerQuery)
 
-DECL_DRIVER_API_R_N(backend::DescriptorSetLayoutHandle, createDescriptorSetLayout,
+DECL_DRIVER_API_TAGGED_R_N(backend::DescriptorSetLayoutHandle, createDescriptorSetLayout,
         backend::DescriptorSetLayout&&, info)
 
-DECL_DRIVER_API_R_N(backend::DescriptorSetHandle, createDescriptorSet,
+DECL_DRIVER_API_TAGGED_R_N(backend::DescriptorSetHandle, createDescriptorSet,
         backend::DescriptorSetLayoutHandle, dslh)
 
-DECL_DRIVER_API_N(updateDescriptorSetBuffer,
-        backend::DescriptorSetHandle, dsh,
-        backend::descriptor_binding_t, binding,
+DECL_DRIVER_API_TAGGED_R_N(backend::MemoryMappedBufferHandle, mapBuffer,
         backend::BufferObjectHandle, boh,
-        uint32_t, offset,
-        uint32_t, size
-)
-
-DECL_DRIVER_API_N(updateDescriptorSetTexture,
-        backend::DescriptorSetHandle, dsh,
-        backend::descriptor_binding_t, binding,
-        backend::TextureHandle, th,
-        SamplerParams, params
-)
-
-DECL_DRIVER_API_N(bindDescriptorSet,
-        backend::DescriptorSetHandle, dsh,
-        backend::descriptor_set_t, set,
-        backend::DescriptorSetOffsetArray&&, offsets
-)
-
+        size_t, offset,
+        size_t, size,
+        backend::MapBufferAccessFlags, access)
 
 /*
  * Destroying driver objects
@@ -319,7 +309,7 @@ DECL_DRIVER_API_N(bindDescriptorSet,
 DECL_DRIVER_API_N(destroyVertexBuffer,          backend::VertexBufferHandle, vbh)
 DECL_DRIVER_API_N(destroyVertexBufferInfo,      backend::VertexBufferInfoHandle, vbih)
 DECL_DRIVER_API_N(destroyIndexBuffer,           backend::IndexBufferHandle, ibh)
-DECL_DRIVER_API_N(destroyBufferObject,          backend::BufferObjectHandle, ibh)
+DECL_DRIVER_API_N(destroyBufferObject,          backend::BufferObjectHandle, boh)
 DECL_DRIVER_API_N(destroyRenderPrimitive,       backend::RenderPrimitiveHandle, rph)
 DECL_DRIVER_API_N(destroyProgram,               backend::ProgramHandle, ph)
 DECL_DRIVER_API_N(destroyTexture,               backend::TextureHandle, th)
@@ -328,8 +318,10 @@ DECL_DRIVER_API_N(destroySwapChain,             backend::SwapChainHandle, sch)
 DECL_DRIVER_API_N(destroyStream,                backend::StreamHandle, sh)
 DECL_DRIVER_API_N(destroyTimerQuery,            backend::TimerQueryHandle, sh)
 DECL_DRIVER_API_N(destroyFence,                 backend::FenceHandle, fh)
+DECL_DRIVER_API_N(destroySync,                  backend::SyncHandle, sh)
 DECL_DRIVER_API_N(destroyDescriptorSetLayout,   backend::DescriptorSetLayoutHandle, dslh)
 DECL_DRIVER_API_N(destroyDescriptorSet,         backend::DescriptorSetHandle, dsh)
+DECL_DRIVER_API_N(unmapBuffer,                  backend::MemoryMappedBufferHandle, mmbh)
 
 /*
  * Synchronous APIs
@@ -337,13 +329,16 @@ DECL_DRIVER_API_N(destroyDescriptorSet,         backend::DescriptorSetHandle, ds
  */
 
 DECL_DRIVER_API_SYNCHRONOUS_0(void, terminate)
-DECL_DRIVER_API_SYNCHRONOUS_N(backend::StreamHandle, createStreamNative, void*, stream)
-DECL_DRIVER_API_SYNCHRONOUS_0(backend::StreamHandle, createStreamAcquired)
+DECL_DRIVER_API_SYNCHRONOUS_TAGGED_N(backend::StreamHandle, createStreamNative, void*, stream)
+DECL_DRIVER_API_SYNCHRONOUS_TAGGED_N(backend::StreamHandle, createStreamAcquired)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setAcquiredImage, backend::StreamHandle, stream, void*, image, const math::mat3f&, transform, backend::CallbackHandler*, handler, backend::StreamCallback, cb, void*, userData)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setStreamDimensions, backend::StreamHandle, stream, uint32_t, width, uint32_t, height)
 DECL_DRIVER_API_SYNCHRONOUS_N(int64_t, getStreamTimestamp, backend::StreamHandle, stream)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, updateStreams, backend::DriverApi*, driver)
 DECL_DRIVER_API_SYNCHRONOUS_N(backend::FenceStatus, getFenceStatus, backend::FenceHandle, fh)
+DECL_DRIVER_API_SYNCHRONOUS_N(backend::FenceStatus, fenceWait, backend::FenceHandle, fh, uint64_t, timeout)
+DECL_DRIVER_API_SYNCHRONOUS_N(void, getPlatformSync, backend::SyncHandle, sh,
+        backend::CallbackHandler*, handler, backend::Platform::SyncCallback, cb, void*, userData)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isTextureFormatSupported, backend::TextureFormat, format)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isTextureSwizzleSupported)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isTextureFormatMipmappable, backend::TextureFormat, format)
@@ -353,6 +348,7 @@ DECL_DRIVER_API_SYNCHRONOUS_0(bool, isFrameBufferFetchMultiSampleSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isFrameTimeSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isAutoDepthResolveSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isSRGBSwapChainSupported)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, isMSAASwapChainSupported, uint32_t, samples)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isProtectedContentSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isStereoSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isParallelShaderCompileSupported)
@@ -367,7 +363,7 @@ DECL_DRIVER_API_SYNCHRONOUS_0(size_t, getMaxArrayTextureLayers)
 DECL_DRIVER_API_SYNCHRONOUS_0(math::float2, getClipSpaceParams)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setupExternalImage2, backend::Platform::ExternalImageHandleRef, image)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setupExternalImage, void*, image)
-DECL_DRIVER_API_SYNCHRONOUS_N(backend::TimerQueryResult, getTimerQueryValue, backend::TimerQueryHandle, query, uint64_t*, elapsedTime)
+DECL_DRIVER_API_SYNCHRONOUS_N(backend::TimerQueryResult, getTimerQueryValue, backend::TimerQueryHandle, tqh, uint64_t*, elapsedTime)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isWorkaroundNeeded, backend::Workaround, workaround)
 DECL_DRIVER_API_SYNCHRONOUS_0(backend::FeatureLevel, getFeatureLevel)
 
@@ -392,16 +388,16 @@ DECL_DRIVER_API_N(updateBufferObject,
         uint32_t, byteOffset)
 
 DECL_DRIVER_API_N(registerBufferObjectStreams,
-        backend::BufferObjectHandle, ibh,
+        backend::BufferObjectHandle, boh,
         backend::BufferObjectStreamDescriptor&&, streams)
 
 DECL_DRIVER_API_N(updateBufferObjectUnsynchronized,
-        backend::BufferObjectHandle, ibh,
+        backend::BufferObjectHandle, boh,
         backend::BufferDescriptor&&, data,
         uint32_t, byteOffset)
 
 DECL_DRIVER_API_N(resetBufferObject,
-        backend::BufferObjectHandle, ibh)
+        backend::BufferObjectHandle, boh)
 
 DECL_DRIVER_API_N(update3DImage,
         backend::TextureHandle, th,
@@ -421,6 +417,48 @@ DECL_DRIVER_API_N(setExternalStream,
         backend::TextureHandle, th,
         backend::StreamHandle, sh)
 
+DECL_DRIVER_API_N(beginTimerQuery,
+        backend::TimerQueryHandle, tqh)
+
+DECL_DRIVER_API_N(endTimerQuery,
+        backend::TimerQueryHandle, tqh)
+
+DECL_DRIVER_API_N(compilePrograms,
+        backend::CompilerPriorityQueue, priority,
+        backend::CallbackHandler*, handler,
+        backend::CallbackHandler::Callback, callback,
+        void*, user)
+
+DECL_DRIVER_API_N(updateDescriptorSetBuffer,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_binding_t, binding,
+        backend::BufferObjectHandle, boh,
+        uint32_t, offset,
+        uint32_t, size
+)
+
+DECL_DRIVER_API_N(updateDescriptorSetTexture,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_binding_t, binding,
+        backend::TextureHandle, th,
+        SamplerParams, params
+)
+
+DECL_DRIVER_API_N(copyToMemoryMappedBuffer,
+        backend::MemoryMappedBufferHandle, mmbh,
+        size_t, offset,
+        backend::BufferDescriptor&&, data)
+
+DECL_DRIVER_API_N(setPushConstant,
+        backend::ShaderStage, stage,
+        uint8_t, index,
+        backend::PushConstantVariant, value)
+
+/*
+ * Setting rendering state
+ * -----------------------
+ */
+
 DECL_DRIVER_API_N(beginRenderPass,
         backend::RenderTargetHandle, rth,
         const backend::RenderPassParams&, params)
@@ -429,17 +467,17 @@ DECL_DRIVER_API_0(endRenderPass)
 
 DECL_DRIVER_API_0(nextSubpass)
 
-DECL_DRIVER_API_N(beginTimerQuery,
-        backend::TimerQueryHandle, query)
+DECL_DRIVER_API_N(bindPipeline,
+        backend::PipelineState const&, state)
 
-DECL_DRIVER_API_N(endTimerQuery,
-        backend::TimerQueryHandle, query)
+DECL_DRIVER_API_N(bindRenderPrimitive,
+        backend::RenderPrimitiveHandle, rph)
 
-DECL_DRIVER_API_N(compilePrograms,
-        backend::CompilerPriorityQueue, priority,
-        backend::CallbackHandler*, handler,
-        backend::CallbackHandler::Callback, callback,
-        void*, user)
+DECL_DRIVER_API_N(bindDescriptorSet,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_set_t, set,
+        backend::DescriptorSetOffsetArray&&, offsets
+)
 
 /*
  * Swap chain
@@ -458,11 +496,6 @@ DECL_DRIVER_API_N(commit,
  * -----------------------
  */
 
-DECL_DRIVER_API_N(setPushConstant,
-        backend::ShaderStage, stage,
-        uint8_t, index,
-        backend::PushConstantVariant, value)
-
 DECL_DRIVER_API_N(insertEventMarker,
         const char*, string)
 
@@ -523,12 +556,6 @@ DECL_DRIVER_API_N(blit,
         math::uint2, srcOrigin,
         math::uint2, size)
 
-DECL_DRIVER_API_N(bindPipeline,
-        backend::PipelineState const&, state)
-
-DECL_DRIVER_API_N(bindRenderPrimitive,
-        backend::RenderPrimitiveHandle, rph)
-
 DECL_DRIVER_API_N(draw2,
         uint32_t, indexOffset,
         uint32_t, indexCount,

filament/backend/include/private/backend/HandleAllocator.h

@@ -21,6 +21,7 @@
 
 #include <utils/Allocator.h>
 #include <utils/CString.h>
+#include <utils/ImmutableCString.h>
 #include <utils/Log.h>
 #include <utils/Panic.h>
 #include <utils/compiler.h>
@@ -52,16 +53,16 @@ namespace filament::backend {
 class DebugTag {
 public:
     DebugTag();
-    void writePoolHandleTag(HandleBase::HandleId key, utils::CString&& tag) noexcept;
-    void writeHeapHandleTag(HandleBase::HandleId key, utils::CString&& tag) noexcept;
-    utils::CString findHandleTag(HandleBase::HandleId key) const noexcept;
+    void writePoolHandleTag(HandleBase::HandleId key, utils::ImmutableCString&& tag) noexcept;
+    void writeHeapHandleTag(HandleBase::HandleId key, utils::ImmutableCString&& tag) noexcept;
+    utils::ImmutableCString findHandleTag(HandleBase::HandleId key) const noexcept;
 
 private:
     // This is used to associate a tag to a handle. mDebugTags is only written the in the main
     // driver thread, but it can be accessed from any thread, because it's called from handle_cast<>
     // which is used by synchronous calls.
     mutable utils::Mutex mDebugTagLock;
-    tsl::robin_map<HandleBase::HandleId, utils::CString> mDebugTags;
+    tsl::robin_map<HandleBase::HandleId, utils::ImmutableCString> mDebugTags;
 };
 
 /*
@@ -70,12 +71,12 @@ private:
 template<size_t P0, size_t P1, size_t P2>
 class HandleAllocator : public DebugTag {
 public:
-    HandleAllocator(const char* name, size_t size) noexcept;
+    HandleAllocator(const char* name, size_t size);
     HandleAllocator(const char* name, size_t size,
-            bool disableUseAfterFreeCheck, bool disableHeapHandleTags) noexcept;
+            bool disableUseAfterFreeCheck, bool disableHeapHandleTags);
     HandleAllocator(HandleAllocator const& rhs) = delete;
     HandleAllocator& operator=(HandleAllocator const& rhs) = delete;
-    ~HandleAllocator();
+    ~HandleAllocator() noexcept;
 
     /*
      * Constructs a D object and returns a Handle<D>
@@ -106,7 +107,7 @@ public:
      *
      */
     template<typename D>
-    Handle<D> allocate() noexcept {
+    Handle<D> allocate() {
         Handle<D> h{ allocateHandle<D>() };
         return h;
     }
@@ -222,7 +223,7 @@ public:
         return static_cast<Dp>(p);
     }
 
-    utils::CString getHandleTag(HandleBase::HandleId key) const noexcept;
+    utils::ImmutableCString getHandleTag(HandleBase::HandleId key) const noexcept;
 
     template<typename B>
     bool is_valid(Handle<B>& handle) {
@@ -248,9 +249,10 @@ public:
         return handle_cast<Dp>(const_cast<Handle<B>&>(handle));
     }
 
-    void associateTagToHandle(HandleBase::HandleId id, utils::CString&& tag) noexcept {
-        // TODO: for now, only pool handles check for use-after-free, so we only keep tags for
-        // those
+    void associateTagToHandle(HandleBase::HandleId id, utils::ImmutableCString&& tag) noexcept {
+        if (tag.empty()) {
+            return;
+        }
         uint32_t key = id;
         if (UTILS_LIKELY(isPoolHandle(id))) {
             // Truncate the age to get the debug tag
@@ -341,7 +343,7 @@ private:
     // allocation size this is always inlined, because all these do is to call
     // allocateHandleInPool()/deallocateHandleFromPool() with the right pool size.
     template<typename D>
-    HandleBase::HandleId allocateHandle() noexcept {
+    HandleBase::HandleId allocateHandle() {
         constexpr size_t BUCKET_SIZE = getBucketSize<D>();
         return allocateHandleInPool<BUCKET_SIZE>();
     }
@@ -357,7 +359,7 @@ private:
     // the code generated is not trivial (even if it's not insane either).
     template<size_t SIZE>
     UTILS_NOINLINE
-    HandleBase::HandleId allocateHandleInPool() noexcept {
+    HandleBase::HandleId allocateHandleInPool() {
         uint8_t age;
         void* p = mHandleArena.alloc(SIZE, alignof(std::max_align_t), 0, &age);
         if (UTILS_LIKELY(p)) {

filament/backend/src/BackendUtils.cpp

@@ -18,10 +18,16 @@
 
 #include "DataReshaper.h"
 
+#include <backend/PixelBufferDescriptor.h>
 #include <backend/DriverEnums.h>
 
+#include <utils/BitmaskEnum.h>
+#include <utils/compiler.h>
 #include <utils/CString.h>
 
+#include <cstddef>
+#include <cstdint>
+#include <utility>
 #include <string_view>
 
 namespace filament::backend {
@@ -636,7 +642,7 @@ bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped)
     switch (data.type) {
         case PixelDataType::BYTE:
         case PixelDataType::UBYTE: {
-            uint8_t* bytes = (uint8_t*) malloc(reshapedSize);
+            uint8_t* bytes = static_cast<uint8_t*>(malloc(reshapedSize));
             DataReshaper::reshape<uint8_t, 3, 4>(bytes, data.buffer, data.size);
             PixelBufferDescriptor pbd(bytes, reshapedSize, reshapedFormat, data.type,
                     data.alignment, data.left, data.top, data.stride, freeFunc);
@@ -646,7 +652,7 @@ bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped)
         case PixelDataType::SHORT:
         case PixelDataType::USHORT:
         case PixelDataType::HALF: {
-            uint8_t* bytes = (uint8_t*) malloc(reshapedSize);
+            uint8_t* bytes = static_cast<uint8_t*>(malloc(reshapedSize));
             DataReshaper::reshape<uint16_t, 3, 4>(bytes, data.buffer, data.size);
             PixelBufferDescriptor pbd(bytes, reshapedSize, reshapedFormat, data.type,
                     data.alignment, data.left, data.top, data.stride, freeFunc);
@@ -655,7 +661,7 @@ bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped)
         }
         case PixelDataType::INT:
         case PixelDataType::UINT: {
-            uint8_t* bytes = (uint8_t*) malloc(reshapedSize);
+            uint8_t* bytes = static_cast<uint8_t*>(malloc(reshapedSize));
             DataReshaper::reshape<uint32_t, 3, 4>(bytes, data.buffer, data.size);
             PixelBufferDescriptor pbd(bytes, reshapedSize, reshapedFormat, data.type,
                     data.alignment, data.left, data.top, data.stride, freeFunc);
@@ -663,7 +669,7 @@ bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped)
             return true;
         }
         case PixelDataType::FLOAT: {
-            uint8_t* bytes = (uint8_t*) malloc(reshapedSize);
+            uint8_t* bytes = static_cast<uint8_t*>(malloc(reshapedSize));
             DataReshaper::reshape<float, 3, 4>(bytes, data.buffer, data.size);
             PixelBufferDescriptor pbd(bytes, reshapedSize, reshapedFormat, data.type,
                     data.alignment, data.left, data.top, data.stride, freeFunc);

filament/backend/src/CallbackManager.cpp

@@ -20,7 +20,7 @@
 
 namespace filament::backend {
 
-CallbackManager::CallbackManager(DriverBase& driver) noexcept
+CallbackManager::CallbackManager(DriverBase& driver)
     : mDriver(driver), mCallbacks(1) {
 }
 

filament/backend/src/CallbackManager.h

@@ -51,7 +51,7 @@ class CallbackManager {
 public:
     using Handle = Container::const_iterator;
 
-    explicit CallbackManager(DriverBase& driver) noexcept;
+    explicit CallbackManager(DriverBase& driver);
 
     ~CallbackManager() noexcept;
 
@@ -78,7 +78,7 @@ private:
         return --mCallbacks.end();
     }
 
-    Container::iterator allocateNewSlot() noexcept {
+    Container::iterator allocateNewSlot() {
         std::lock_guard const lock(mLock);
         auto curr = --mCallbacks.end();
         mCallbacks.emplace_back();

filament/backend/src/CircularBuffer.cpp

@@ -38,6 +38,11 @@
 #include <stdlib.h>
 #include <string.h>
 
+#if defined(WIN32)
+#    include <windows.h> // for VirtualAlloc, VirtualProtect, VirtualFree
+#    include <utils/unwindows.h>
+#endif
+
 using namespace utils;
 
 namespace filament::backend {
@@ -134,6 +139,21 @@ void* CircularBuffer::alloc(size_t size) {
         mprotect(guard, BLOCK_SIZE, PROT_NONE);
     }
     return data;
+#elif defined(WIN32)
+    size_t const BLOCK_SIZE = getBlockSize();
+    // On Windows, use VirtualAlloc instead of malloc to allocate virtual memory.
+    // This allows us to set page protection by VirtualProtect.
+    void* data = VirtualAlloc(nullptr, size * 2 + BLOCK_SIZE, MEM_RESERVE | MEM_COMMIT, PAGE_READWRITE);
+    FILAMENT_CHECK_POSTCONDITION(data != nullptr)
+            << "couldn't allocate " << (size * 2 / 1024)
+            << " KiB of virtual address space for the command buffer";
+
+    // guard page at the end
+    void* guard = (void*)(uintptr_t(data) + size * 2);
+    DWORD oldProtect = 0;
+    BOOL ok = VirtualProtect(guard, BLOCK_SIZE, PAGE_NOACCESS, &oldProtect);
+    FILAMENT_CHECK_POSTCONDITION(ok) << "VirtualProtect failed to set guard page";
+    return data;
 #else
     return ::malloc(2 * size);
 #endif
@@ -150,6 +170,10 @@ void CircularBuffer::dealloc() noexcept {
             mAshmemFd = -1;
         }
     }
+#elif defined(WIN32)
+    if (mData) {
+        VirtualFree(mData, 0, MEM_RELEASE);
+    }
 #else
     ::free(mData);
 #endif

filament/backend/src/CommandStream.cpp

@@ -57,12 +57,15 @@ static void printParameterPack(io::ostream& out, const FIRST& first, const REMAI
     printParameterPack(out, rest...);
 }
 
-static UTILS_NOINLINE UTILS_UNUSED std::string extractMethodName(std::string& command) noexcept {
-    constexpr const char startPattern[] = "::Command<&filament::backend::Driver::";
+static UTILS_NOINLINE UTILS_UNUSED std::string_view extractMethodName(std::string_view command) noexcept { // NOLINT(*-exception-escape)
+    constexpr char startPattern[] = "::Command<&filament::backend::Driver::";
     auto pos = command.rfind(startPattern);
     auto end = command.rfind('(');
     pos += sizeof(startPattern) - 1;
-    return command.substr(pos, end-pos);
+    if (pos > command.size()) {
+        return { command.data(), command.size() };
+    }
+    return command.substr(pos, end-pos); // this can't throw by construction
 }
 
 // ------------------------------------------------------------------------------------------------
@@ -133,9 +136,9 @@ template<std::size_t... I>
 void CommandType<void (Driver::*)(ARGS...)>::Command<METHOD>::log(std::index_sequence<I...>) noexcept  {
 #if DEBUG_COMMAND_STREAM
     static_assert(UTILS_HAS_RTTI, "DEBUG_COMMAND_STREAM can only be used with RTTI");
-    std::string command = utils::CallStack::demangleTypeName(typeid(Command).name()).c_str();
-    DLOG(INFO) << extractMethodName(command) << " : size=" << sizeof(Command);
-    utils::io::sstream parameterPack;
+    CString command = CallStack::demangleTypeName(typeid(Command).name());
+    DLOG(INFO) << extractMethodName({command.data(), command.size()}) << " : size=" << sizeof(Command);
+    io::sstream parameterPack;
     printParameterPack(parameterPack, std::get<I>(mArgs)...);
     DLOG(INFO) << "\t" << parameterPack.c_str();
 #endif
@@ -164,7 +167,7 @@ void CommandType<void (Driver::*)(ARGS...)>::Command<METHOD>::log() noexcept  {
 // ------------------------------------------------------------------------------------------------
 
 void CustomCommand::execute(Driver&, CommandBase* base, intptr_t* next) {
-    *next = CustomCommand::align(sizeof(CustomCommand));
+    *next = align(sizeof(CustomCommand));
     static_cast<CustomCommand*>(base)->mCommand();
     static_cast<CustomCommand*>(base)->~CustomCommand();
 }

filament/backend/src/CompilerThreadPool.cpp

@@ -18,7 +18,14 @@
 
 #include <private/utils/Tracing.h>
 
+#include <utils/compiler.h>
+#include <utils/debug.h>
+
+#include <algorithm>
+#include <iterator>
 #include <memory>
+#include <mutex>
+#include <utility>
 
 namespace filament::backend {
 
@@ -36,7 +43,7 @@ CompilerThreadPool::~CompilerThreadPool() noexcept {
 }
 
 void CompilerThreadPool::init(uint32_t threadCount,
-        ThreadSetup&& threadSetup, ThreadCleanup&& threadCleanup) noexcept {
+        ThreadSetup&& threadSetup, ThreadCleanup&& threadCleanup) {
     auto setup = std::make_shared<ThreadSetup>(std::move(threadSetup));
     auto cleanup = std::make_shared<ThreadCleanup>(std::move(threadCleanup));
 

filament/backend/src/CompilerThreadPool.h

@@ -47,8 +47,7 @@ public:
     using Job = utils::Invocable<void()>;
     using ThreadSetup = utils::Invocable<void()>;
     using ThreadCleanup = utils::Invocable<void()>;
-    void init(uint32_t threadCount,
-            ThreadSetup&& threadSetup, ThreadCleanup&& threadCleanup) noexcept;
+    void init(uint32_t threadCount, ThreadSetup&& threadSetup, ThreadCleanup&& threadCleanup);
     void terminate() noexcept;
     void queue(CompilerPriorityQueue priorityQueue, program_token_t const& token, Job&& job);
     Job dequeue(program_token_t const& token);