Add missing VulkanDriver.h header

Keep it's original behavior of no-op

.github/workflows/postsubmit.yml

@@ -21,8 +21,9 @@ jobs:
       - name: Run update script
         env:
           GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
+          COMMIT_MESSAGE: ${{ steps.get_commit_msg.outputs.msg }}
         run: |
-          GOLDEN_BRANCH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | python3 test/renderdiff/src/commit_msg.py)
+          GOLDEN_BRANCH=$(echo "${COMMIT_MESSAGE}" | python3 test/renderdiff/src/commit_msg.py)
           COMMIT_HASH="${{ steps.get_commit_msg.outputs.hash }}"
           if [[ "${GOLDEN_BRANCH}" != "main" ]]; then
               git config --global user.email "filament.bot@gmail.com"

.github/workflows/presubmit.yml

@@ -134,18 +134,17 @@ jobs:
         env:
           COMMIT_MESSAGE: ${{ steps.get_commit_msg.outputs.msg }}
         run: |
-          ls ./gltf/Models
           TEST_DIR=test/renderdiff
           source ${TEST_DIR}/src/preamble.sh
-          start_
+          set -eux
           GOLDEN_BRANCH=$(echo "${COMMIT_MESSAGE}" | python3 ${TEST_DIR}/src/commit_msg.py)
-          bash ${TEST_DIR}/generate.sh && \
-              python3 ${TEST_DIR}/src/golden_manager.py \
+          bash ${TEST_DIR}/generate.sh
+          python3 ${TEST_DIR}/src/golden_manager.py \
                   --branch=${GOLDEN_BRANCH} \
                   --output=${GOLDEN_OUTPUT_DIR}
 
-          # Note that we need to upload the output even if comparison fails, so we undo `set -ex`
-          end_
+          # Note that we need to upload the output even if comparison fails, so we undo `set -eux`
+          set +eux
 
           python3 ${TEST_DIR}/src/compare.py \
               --src=${GOLDEN_OUTPUT_DIR} \
@@ -158,6 +157,7 @@ jobs:
              cat compare_output.txt >> "$GITHUB_OUTPUT"
              echo "$DELIMITER" >> "$GITHUB_OUTPUT"
           fi
+        shell: bash
       - uses: actions/upload-artifact@v4
         with:
           name: presubmit-renderdiff-result
@@ -179,7 +179,7 @@ jobs:
           fetch-depth: 0
       - uses: ./.github/actions/linux-prereq
       - name: Run build script
-        run: ./build.sh -W debug test_filamat filament
+        run: ./build.sh -W debug test_filamat filament gltf_viewer
       - name: Run test
         run: ./out/cmake-debug/libs/filamat/test_filamat --gtest_filter=MaterialCompiler.Wgsl*
 

BUILDING.md

@@ -62,6 +62,11 @@ force a clean build by adding the `-c` flag in that case.
 To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag.
 The script offers more features described by executing `build.sh -h`.
 
+For more specialized options, please also consider the following pages:
+ - `-d`: [`matdbg`](https://google.github.io/filament/dup/matdbg.html)
+ - `-t`: [`fgviewer`](https://google.github.io/filament/dup/fgviewer.html)
+ - `-b` and `-y`: [ASAN/UBSAN builds](https://google.github.io/filament/notes/asan_ubsan.html)
+
 ### Filament-specific CMake Options
 
 The following CMake options are boolean options specific to Filament:

CMakeLists.txt

@@ -58,6 +58,8 @@ option(FILAMENT_USE_ABSEIL_LOGGING "Use Abseil to log, may increase binary size"
 
 option(FILAMENT_ENABLE_EXPERIMENTAL_GCC_SUPPORT "Enable GCC support (unsupported)" OFF)
 
+option(FILAMENT_SUPPORTS_WEBP_TEXTURES "Enable webp texture support for Filament (builds libwebp when ON)" OFF)
+
 # This is to disable GTAO for the short-term while we investigate a way to better manage size increases.
 # On the regular filament build (where size is of less concern), we enable GTAO by default.
 option(FILAMENT_DISABLE_GTAO "Disable GTAO" OFF)
@@ -753,12 +755,61 @@ function(combine_static_libs TARGET OUTPUT DEPS)
 endfunction()
 
 # ==================================================================================================
-# Configuration for CMAKE_CROSSCOMPILING.
+# Configuration importing/exporting prebuilt "/tools" executables
 # ==================================================================================================
+
+# In certain cases, we want the ability to separate the build type/flags (release, debug) of tools
+# (matc, resgen, etc...) from filament.  Cross compilation is one such case (e.g. building material
+# with matc running on host while building filament for Android) [1]. Another example is when client
+# wants to enable ASAN for filament but not the tool [2].
+#
+# Here are the varibles that are used to determine behavior is such flows:
+#   - CMAKE_CROSSCOMPILING : Set by cmake to indicate the build's target platform is different
+#     from the host platform.
+#   - IMPORT_EXECUTABLES_DIR : This is the directory containing the /ImportExecutables-type.cmake
+#     which are then included in other CMakeLists.txt to enable finding targets that have been
+#     prebuilt. This is set by the client in their `cmake` invocation.
+#   - IMPORT_EXECUTABLES : Path to a file to for 1) exporting the prebuilt targets or 2)
+#     importing a previously exported targets. (Used internally and should not be set by client).
+#   - FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that
+#     they wish to export the tools as prebuilts, and the corresponding targets will be recorded
+#     in a cmake file (i.e IMPORT_EXECUTABLES). IMPORT_EXECUTABLES will be set relative to the the
+#     given path. This will set FILAMENT_EXPORT_PREBUILT_EXECUTABLES=ON.
+#   - FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR : A path set by the client to indicate that they wish
+#     to import the tools as prebuilts from a .cmake file. The location (IMPORT_EXECUTABLES) of the
+#     file is relative to the path given. This will set FILAMENT_IMPORT_PREBUILT_EXECUTABLES=ON.
+#   - IMPORT_PREBUILT_EXECUTABLES and EXPORT_PREBUILT_EXECUTABLES are internal booleans set to
+#     ON based on the prescence of FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR and
+#     FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR.
+#
+# In conclusion, for cases
+#   - [1] (crosscompiling), the client must set IMPORT_EXECUTABLES_DIR for both when they are building
+#     the tools and when they are building the target-platform filament.
+#   - [2] (all other instances), the client must set FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR in
+#     the prebuilt exporting step, and set FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR in the importing
+#     step.
+
+# TODO: Fold the cross compilation case into the more general FILAMENT_IMPORT/EXPORT variables.
+
+if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR)
+   set(FILAMENT_EXPORT_PREBUILT_EXECUTABLES ON)
+   set(IMPORT_EXECUTABLES_DIR ${FILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR})
+endif()
+
+if (FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR)
+   set(FILAMENT_IMPORT_PREBUILT_EXECUTABLES ON)
+   set(IMPORT_EXECUTABLES_DIR ${FILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR})
+endif()
+
 if (WEBGL)
     set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-Release.cmake)
 else()
-    set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake)
+    if (FILAMENT_EXPORT_PREBUILT_EXECUTABLES OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES)
+        set(IMPORT_EXECUTABLES_BUILD_TYPE Prebuilt)
+    else()
+        set(IMPORT_EXECUTABLES_BUILD_TYPE ${CMAKE_BUILD_TYPE})
+    endif()
+    set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${IMPORT_EXECUTABLES_BUILD_TYPE}.cmake)
 endif()
 
 # ==================================================================================================
@@ -821,7 +872,9 @@ add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${LIBRARIES}/viewer)
 add_subdirectory(${FILAMENT}/shaders)
 add_subdirectory(${EXTERNAL}/abseil/tnt)
-add_subdirectory(${EXTERNAL}/basisu/tnt)
+# Add zstd before basisu to force it to use the external zstd target,
+# preventing a duplicate symbol conflict with its bundled version.
+add_subdirectory(${EXTERNAL}/zstd/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)
 add_subdirectory(${EXTERNAL}/robin-map/tnt)
@@ -835,7 +888,8 @@ add_subdirectory(${EXTERNAL}/jsmn/tnt)
 add_subdirectory(${EXTERNAL}/stb/tnt)
 add_subdirectory(${EXTERNAL}/getopt)
 add_subdirectory(${EXTERNAL}/perfetto/tnt)
-add_subdirectory(${EXTERNAL}/zstd/tnt)
+add_subdirectory(${EXTERNAL}/basisu/tnt)
+
 
 # Note that this has to be placed after mikktspace in order for combine_static_libs to work.
 add_subdirectory(${LIBRARIES}/geometry)
@@ -859,6 +913,11 @@ if (FILAMENT_ENABLE_FGVIEWER)
     add_subdirectory(${LIBRARIES}/fgviewer)
 endif()
 
+if (FILAMENT_SUPPORTS_WEBP_TEXTURES)
+    add_subdirectory(${EXTERNAL}/libwebp/tnt)
+    add_definitions(-DFILAMENT_SUPPORTS_WEBP_TEXTURES)
+endif()
+
 if (FILAMENT_SUPPORTS_VULKAN)
     add_subdirectory(${LIBRARIES}/bluevk)
     add_subdirectory(${EXTERNAL}/vkmemalloc/tnt)
@@ -917,6 +976,6 @@ if (IS_HOST_PLATFORM)
 endif()
 
 # Generate exported executables for cross-compiled builds (Android, WebGL, and iOS)
-if (NOT CMAKE_CROSSCOMPILING)
+if ((NOT CMAKE_CROSSCOMPILING AND NOT FILAMENT_IMPORT_PREBUILT_EXECUTABLES) OR FILAMENT_EXPORT_PREBUILT_EXECUTABLES)
     export(TARGETS matc cmgen filamesh mipgen resgen uberz glslminifier FILE ${IMPORT_EXECUTABLES})
 endif()

README.md

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

RELEASE_NOTES.md

@@ -7,6 +7,22 @@ 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.68.1
+
+
+## v1.68.0
+
+- engine: add `View::getLastDynamicResolutionScale()` (b/457753622)
+- Metal: report GPU errors to the platform via `debugUpdateStat` (b/431665753).
+- materials: Make Material Instances' UBO descriptor use dynamic offsets. [⚠️ **Recompile Materials**]
+
+## v1.67.1
+
+- Metal: Add support for the `SwapChain::CONFIG_MSAA_4_SAMPLES` flag.
+- third_party: Optionally add libwebp to build
+  - controlled by cmake flag FILAMENT_SUPPORTS_WEBP_TEXTURES, defaults to OFF
+  - actual webp texture support for libs/gltfio coming in subsequent change
+
 ## v1.67.0
 
 - materials: Add a new API getParameterTransformName that will return the value of the transformName field of a sampler

android/build.gradle

@@ -100,7 +100,7 @@ buildscript {
         'kotlin': '2.0.21',
         'kotlin_coroutines': '1.9.0',
         'buildTools': '35.0.0',
-        'ndk': '27.0.11718014',
+        'ndk': '29.0.14206865',
         'androidx_core': '1.13.1',
         'androidx_annotations': '1.9.0'
     ]

android/filament-android/CMakeLists.txt

@@ -51,10 +51,6 @@ add_library(bluevk STATIC IMPORTED)
 set_target_properties(bluevk PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbluevk.a)
 
-add_library(vkshaders STATIC IMPORTED)
-set_target_properties(vkshaders PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libvkshaders.a)
-
 if (FILAMENT_SUPPORTS_WEBGPU)
         add_library(webgpu_dawn STATIC IMPORTED)
         set_target_properties(webgpu_dawn PROPERTIES IMPORTED_LOCATION
@@ -165,7 +161,6 @@ target_link_libraries(filament-jni
     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>
 )

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

@@ -25,7 +25,7 @@ using namespace filament;
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Material_nBuilderBuild(JNIEnv *env, jclass,
-        jlong nativeEngine, jobject buffer_, jint size, jint shBandCount, jint shadowQuality) {
+        jlong nativeEngine, jobject buffer_, jint size, jint shBandCount, jint shadowQuality, jint uboBatchingMode) {
     Engine* engine = (Engine*) nativeEngine;
     AutoBuffer buffer(env, buffer_, size);
     auto builder = Material::Builder();
@@ -33,6 +33,7 @@ Java_com_google_android_filament_Material_nBuilderBuild(JNIEnv *env, jclass,
         builder.sphericalHarmonicsBandCount(shBandCount);
     }
     builder.shadowSamplingQuality((Material::Builder::ShadowSamplingQuality)shadowQuality);
+    builder.uboBatching((Material::UboBatchingMode)uboBatchingMode);
     Material* material = builder
             .package(buffer.getData(), buffer.getSize())
             .build(*engine);

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

@@ -147,6 +147,15 @@ Java_com_google_android_filament_View_nSetDynamicResolutionOptions(JNIEnv*, jcla
     view->setDynamicResolutionOptions(options);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nGetLastDynamicResolutionScale(JNIEnv *env, jclass, jlong nativeView, jfloatArray out_) {
+    jfloat* out = env->GetFloatArrayElements(out_, nullptr);
+    View *view = (View *) nativeView;
+    math::float2 result = view->getLastDynamicResolutionScale();
+    std::copy_n(result.v, 2, out);
+    env->ReleaseFloatArrayElements(out_, out, 0);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetShadowType(JNIEnv*, jclass, jlong nativeView, jint type) {
     View* view = (View*) nativeView;

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

@@ -99,6 +99,15 @@ final class Asserts {
         }
     }
 
+    @NonNull @Size(min = 2)
+    static float[] assertFloat2(@Nullable float[] out) {
+        if (out == null) out = new float[2];
+        else if (out.length < 2) {
+            throw new ArrayIndexOutOfBoundsException("Array length must be at least 2");
+        }
+        return out;
+    }
+
     @NonNull @Size(min = 4)
     static float[] assertFloat4(@Nullable float[] out) {
         if (out == null) out = new float[4];

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

@@ -261,6 +261,20 @@ public class Material {
         LOW
     }
 
+    /**
+     * Defines whether a material instance should use UBO batching or not.
+     */
+    public enum UboBatchingMode {
+        /**
+         * For default, it follows the engine settings.
+         * If UBO batching is enabled on the engine and the material domain is SURFACE, it
+         * turns on the UBO batching. Otherwise, it turns off the UBO batching.
+        */
+        DEFAULT,
+        /** Disable the Ubo Batching for this material */
+        DISABLED
+    }
+
     public static class UserVariantFilterBit {
         /** Directional lighting */
         public static int DIRECTIONAL_LIGHTING = 0x01;
@@ -372,6 +386,7 @@ public class Material {
         private int mSize;
         private int mShBandCount = 0;
         private ShadowSamplingQuality mShadowSamplingQuality = ShadowSamplingQuality.LOW;
+        private UboBatchingMode mUboBatchingMode = UboBatchingMode.DEFAULT;
 
 
         /**
@@ -416,6 +431,17 @@ public class Material {
             return this;
         }
 
+        /**
+         * Set the batching mode of the instances created from this material.
+         * @param uboBatchingMode
+         * @return Reference to this Builder for chaining calls.
+         */
+        @NonNull
+        public Builder uboBatching(UboBatchingMode mode) {
+            mUboBatchingMode = mode;
+            return this;
+        }
+
         /**
          * Creates and returns the Material object.
          *
@@ -428,7 +454,7 @@ public class Material {
         @NonNull
         public Material build(@NonNull Engine engine) {
             long nativeMaterial = nBuilderBuild(engine.getNativeObject(),
-                mBuffer, mSize, mShBandCount, mShadowSamplingQuality.ordinal());
+                mBuffer, mSize, mShBandCount, mShadowSamplingQuality.ordinal(), mUboBatchingMode.ordinal());
             if (nativeMaterial == 0) throw new IllegalStateException("Couldn't create Material");
             return new Material(nativeMaterial);
         }
@@ -1094,7 +1120,7 @@ public class Material {
         mNativeObject = 0;
     }
 
-    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount, int shadowQuality);
+    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount, int shadowQuality, int uboBatchingMode);
     private static native long nCreateInstance(long nativeMaterial);
     private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
     private static native long nGetDefaultInstance(long nativeMaterial);

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

@@ -25,7 +25,6 @@ import java.util.EnumSet;
 
 import static com.google.android.filament.Asserts.assertFloat3In;
 import static com.google.android.filament.Asserts.assertFloat4In;
-import static com.google.android.filament.Colors.LinearColor;
 
 import com.google.android.filament.proguard.UsedByNative;
 
@@ -674,6 +673,21 @@ public class View {
         return mDynamicResolution;
     }
 
+    /**
+     * Returns the last dynamic resolution scale factor used by this view. This value is updated
+     * when Renderer::render(View*) is called
+     * @param out A 2-float array where the value will be stored, or null in which case the array is
+     *            allocated.
+     * @return A 2-float array containing the horizontal and the vertical scale factors
+     * @see Renderer#render(View)
+     */
+    @NonNull @Size(min = 2)
+    public float[] getLastDynamicResolutionScale(@Nullable @Size(min = 2) float[] out) {
+        out = Asserts.assertFloat2(out);
+        nGetLastDynamicResolutionScale(getNativeObject(), out);
+        return out;
+    }
+
     /**
      * Sets the rendering quality for this view (e.g. color precision).
      *
@@ -1317,6 +1331,7 @@ public class View {
     private static native void nSetDithering(long nativeView, int dithering);
     private static native int nGetDithering(long nativeView);
     private static native void nSetDynamicResolutionOptions(long nativeView, boolean enabled, boolean homogeneousScaling, float minScale, float maxScale, float sharpness, int quality);
+    private static native void nGetLastDynamicResolutionScale(long nativeView, float[] out);
     private static native void nSetRenderQuality(long nativeView, int hdrColorBufferQuality);
     private static native void nSetDynamicLightingOptions(long nativeView, float zLightNear, float zLightFar);
     private static native void nSetShadowType(long nativeView, int type);

android/filament-utils-android/src/main/java/com/google/android/filament/utils/ModelViewer.kt

@@ -16,6 +16,9 @@
 
 package com.google.android.filament.utils
 
+import android.graphics.Bitmap
+import android.os.Handler
+import android.os.Looper
 import android.view.MotionEvent
 import android.view.Surface
 import android.view.SurfaceView
@@ -26,6 +29,7 @@ import com.google.android.filament.android.UiHelper
 import com.google.android.filament.gltfio.*
 import kotlinx.coroutines.*
 import java.nio.Buffer
+import java.nio.ByteBuffer
 
 private const val kNearPlane = 0.05f     // 5 cm
 private const val kFarPlane = 1000.0f    // 1 km
@@ -119,6 +123,8 @@ class ModelViewer(
     private val target = DoubleArray(3)
     private val upward = DoubleArray(3)
 
+    private var debugFrameCallback: ((Bitmap) -> Unit)? = null
+
     init {
         renderer = engine.createRenderer()
         scene = engine.createScene()
@@ -305,10 +311,39 @@ class ModelViewer(
         // Render the scene, unless the renderer wants to skip the frame.
         if (renderer.beginFrame(swapChain!!, frameTimeNanos)) {
             renderer.render(view)
+
+            debugFrameCallback?.let {
+                val viewport = view.viewport
+                val bitmap = Bitmap.createBitmap(viewport.width, viewport.height,
+                        Bitmap.Config.ARGB_8888)
+                val buffer = ByteBuffer.allocateDirect(viewport.width * viewport.height * 4)
+
+                val handler = Handler(Looper.getMainLooper())
+                val pixelBufferDescriptor = Texture.PixelBufferDescriptor(buffer,
+                        Texture.Format.RGBA, Texture.Type.UBYTE, 1, 0, 0, 0, handler) {
+                    buffer.rewind()
+                    bitmap.copyPixelsFromBuffer(buffer)
+                    it(bitmap)
+                }
+                renderer.readPixels(viewport.left, viewport.bottom, viewport.width,
+                                    viewport.height, pixelBufferDescriptor)
+                debugFrameCallback = null
+            }
+
             renderer.endFrame()
         }
     }
 
+    /*
+     * Sets a callback that will be invoked with the next rendered frame as a Bitmap. Note that this
+     * is a one-time callback.
+     *
+     *  @param callback   callback to be invoked with a rendered frame as [Bitmap]
+     */
+    fun debugGetNextFrameCallback(callback: (Bitmap) -> Unit) {
+        debugFrameCallback = callback
+    }
+
     private fun populateScene(asset: FilamentAsset) {
         val rcm = engine.renderableManager
         var count = 0

android/filament-utils-android/src/main/java/com/google/android/filament/utils/TextureLoader.kt

@@ -40,7 +40,21 @@ fun loadTexture(engine: Engine, resources: Resources, resourceId: Int, type: Tex
     options.inPremultiplied = type == TextureType.COLOR
 
     val bitmap = BitmapFactory.decodeResource(resources, resourceId, options)
+    return buildTexture(engine, bitmap, type)
+}
 
+fun loadTexture(engine: Engine, bytes: ByteArray, type: TextureType, offset: Int = 0, length: Int = bytes.size): Texture {
+    val options = BitmapFactory.Options()
+    // Color is the only type of texture we want to pre-multiply with the alpha channel
+    // Pre-multiplication is the default behavior, so we need to turn it off here
+    options.inPremultiplied = type == TextureType.COLOR
+
+    val bitmap = BitmapFactory.decodeByteArray(bytes, offset, length, options)
+    return buildTexture(engine, bitmap, type)
+}
+
+
+private fun buildTexture(engine: Engine, bitmap: Bitmap, type: TextureType): Texture {
     val texture = Texture.Builder()
             .width(bitmap.width)
             .height(bitmap.height)

android/filament-utils-android/src/main/java/com/google/android/filament/utils/Utils.kt

@@ -22,6 +22,7 @@ object Utils {
     /**
      * Initializes the utils JNI layer. Must be called before using any utils functionality.
      */
+    @JvmStatic
     fun init() {
         // Load Filament first to ensure that the NioUtils Java class is available in the JNIEnv.
         Filament.init()

android/gradle.properties

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

android/samples/sample-gltf-viewer/build.gradle

@@ -17,12 +17,20 @@ filamentTools {
 }
 
 // don't forget to update MainACtivity.kt when/if changing this.
-tasks.register('copyMesh', Copy) {
+tasks.register('copyDamagedHelmetGltf', Copy) {
+    from file("../../../third_party/models/DamagedHelmet/DamagedHelmet.glb")
+    into file("src/main/assets/models")
+    rename {String fileName -> "helmet.glb"}
+}
+
+// don't forget to update MainACtivity.kt when/if changing this.
+tasks.register('copyBusterGltf', Copy) {
     from "../../../third_party/models/BusterDrone"
     into "src/main/assets/models"
 }
 
-preBuild.dependsOn copyMesh
+preBuild.dependsOn copyDamagedHelmetGltf
+preBuild.dependsOn copyBusterGltf
 
 clean.doFirst {
     delete "src/main/assets"

android/samples/sample-material-instance-stress/.gitignore

@@ -0,0 +1,12 @@
+*.iml
+.gradle
+/local.properties
+/.idea/workspace.xml
+/.idea/libraries
+/.idea/caches
+/.idea/gradle.xml
+.DS_Store
+/build
+/captures
+/src/main/assets
+.externalNativeBuild

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

@@ -0,0 +1,52 @@
+plugins {
+    id 'com.android.application'
+    id 'kotlin-android'
+    id 'filament-tools-plugin'
+}
+
+project.ext.isSample = true
+
+kotlin {
+    jvmToolchain(versions.jdk)
+}
+
+filamentTools {
+    materialInputDir = project.layout.projectDirectory.dir("src/main/materials")
+    materialOutputDir = project.layout.projectDirectory.dir("src/main/assets/materials")
+}
+
+clean.doFirst {
+    delete "src/main/assets"
+}
+android {
+    namespace 'com.google.android.filament.materialinstancestress'
+
+    compileSdkVersion versions.compileSdk
+    defaultConfig {
+        applicationId "com.google.android.filament.materialinstancestress"
+        minSdkVersion versions.minSdk
+        targetSdkVersion versions.targetSdk
+    }
+
+    // NOTE: This is a workaround required because the AGP task collectReleaseDependencies
+    //       is not configuration-cache friendly yet; this is only useful for Play publication
+    dependenciesInfo {
+        includeInApk = false
+    }
+
+    // We use the .filamat extension for materials compiled with matc
+    // Telling aapt to not compress them allows to load them efficiently
+    aaptOptions {
+        noCompress 'filamat', 'ktx'
+    }
+
+    compileOptions {
+        sourceCompatibility versions.jdk
+        targetCompatibility versions.jdk
+    }
+}
+
+dependencies {
+    implementation deps.kotlin
+    implementation project(':filament-android')
+}

android/samples/sample-material-instance-stress/src/main/AndroidManifest.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+  <application
+      android:allowBackup="true"
+      android:icon="@mipmap/ic_launcher"
+      android:label="@string/app_name"
+      android:roundIcon="@mipmap/ic_launcher_round"
+      android:supportsRtl="true"
+      android:theme="@style/AppTheme">
+    <activity
+        android:exported="true"
+        android:name=".MainActivity">
+      <intent-filter>
+        <action android:name="android.intent.action.MAIN"/>
+
+        <category android:name="android.intent.category.LAUNCHER"/>
+      </intent-filter>
+    </activity>
+  </application>
+
+</manifest>

android/samples/sample-material-instance-stress/src/main/java/com/google/android/filament/materialinstancestress/MainActivity.kt

@@ -0,0 +1,532 @@
+/*
+ * 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.
+ */
+
+package com.google.android.filament.materialinstancestress
+
+import android.animation.ValueAnimator
+import android.app.Activity
+import android.opengl.Matrix
+import android.os.Bundle
+import android.view.Choreographer
+import android.view.Surface
+import android.view.SurfaceView
+import android.view.animation.LinearInterpolator
+
+import com.google.android.filament.*
+import com.google.android.filament.RenderableManager.*
+import com.google.android.filament.VertexBuffer.*
+import com.google.android.filament.android.DisplayHelper
+import com.google.android.filament.android.FilamentHelper
+import com.google.android.filament.android.UiHelper
+
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import java.nio.channels.Channels
+import kotlin.math.cos
+import kotlin.math.sin
+
+class MainActivity : Activity() {
+    // Make sure to initialize Filament first
+    // This loads the JNI library needed by most API calls
+    companion object {
+        init {
+            Filament.init()
+        }
+
+        private const val NUM_CUBES = 1000
+        private const val GRID_SIZE = 10
+        private const val SPACING = 2.5f
+    }
+
+    // The View we want to render into
+    private lateinit var surfaceView: SurfaceView
+    // UiHelper is provided by Filament to manage SurfaceView and SurfaceTexture
+    private lateinit var uiHelper: UiHelper
+    // DisplayHelper is provided by Filament to manage the display
+    private lateinit var displayHelper: DisplayHelper
+    // Choreographer is used to schedule new frames
+    private lateinit var choreographer: Choreographer
+
+    // Engine creates and destroys Filament resources
+    // Each engine must be accessed from a single thread of your choosing
+    // Resources cannot be shared across engines
+    private lateinit var engine: Engine
+    // A renderer instance is tied to a single surface (SurfaceView, TextureView, etc.)
+    private lateinit var renderer: Renderer
+    // A scene holds all the renderable, lights, etc. to be drawn
+    private lateinit var scene: Scene
+    // A view defines a viewport, a scene and a camera for rendering
+    private lateinit var view: View
+    // Should be pretty obvious :)
+    private lateinit var camera: Camera
+
+    private lateinit var material: Material
+    private lateinit var vertexBuffer: VertexBuffer
+    private lateinit var indexBuffer: IndexBuffer
+
+    // Filament entity representing a renderable object
+    @Entity private val renderables = IntArray(NUM_CUBES)
+    private val materialInstances = arrayOfNulls<MaterialInstance>(NUM_CUBES)
+    private val translationMatrices = Array(NUM_CUBES) { FloatArray(16) }
+
+    @Entity private var light = 0
+
+    // A swap chain is Filament's representation of a surface
+    private var swapChain: SwapChain? = null
+
+    private var cameraRadius = 42.7f // Initial distance (calculated from original 15Y, 40Z)
+    private var cameraTheta = 0.0f  // Azimuth (horizontal) in radians
+    private var cameraPhi = 0.358f  // Elevation (vertical) in radians (from original 15Y, 40Z)
+
+    private var mLastX = 0.0f
+    private var mLastY = 0.0f
+    private val DRAG_SPEED = 0.005f
+
+    // Performs the rendering and schedules new frames
+    private val frameScheduler = FrameCallback()
+
+    private val animator = ValueAnimator.ofFloat(0.0f, 360.0f)
+
+    private val animatorListener = object : ValueAnimator.AnimatorUpdateListener {
+        // Pre-allocate matrix to avoid GC churn
+        private val transformMatrix = FloatArray(16)
+
+        override fun onAnimationUpdate(a: ValueAnimator) {
+            val tcm = engine.transformManager
+            val time = a.animatedFraction // 0.0 to 1.0
+
+            // Calculate the sine wave scale factor.
+            // sin(time * 2 * PI) oscillates between -1.0 and 1.0.
+            // We multiply by 0.5f (so it's -0.5 to 0.5) and add 1.0f.
+            // This makes the final 'scale' oscillate between 0.5 and 1.5.
+            val scale = 1.0f + sin(time * 2.0 * Math.PI).toFloat() * 0.5f
+
+            val localScale = (scale - 0.5f) * 0.5f + 0.5f
+
+            for (i in 0 until NUM_CUBES) {
+                val inst = tcm.getInstance(renderables[i])
+                val materialInst = materialInstances[i] ?: continue
+
+                // Get the cube's base position from its stored matrix
+                // The translation is in elements 12 (x), 13 (y), and 14 (z)
+                val baseX = translationMatrices[i][12]
+                val baseY = translationMatrices[i][13]
+                val baseZ = translationMatrices[i][14]
+
+                // Set the transformMatrix to a new translation matrix,
+                // scaled from the center (0,0,0)
+                Matrix.setIdentityM(transformMatrix, 0)
+                Matrix.translateM(transformMatrix, 0,
+                        baseX * scale,
+                        baseY * scale,
+                        baseZ * scale)
+                Matrix.scaleM(transformMatrix, 0, localScale, localScale, localScale)
+
+                tcm.setTransform(inst, transformMatrix)
+
+                // Vary roughness
+                val roughness = 0.5f + 0.5f * sin(time * 2.0 * Math.PI + i * 0.1).toFloat()
+                materialInst.setParameter("roughness", roughness)
+
+                // Vary color (using linear RGB)
+                val r = 0.5f + 0.5f * cos(time * 2.0 * Math.PI + i * 0.5).toFloat()
+                val g = 0.5f + 0.5f * sin(time * 2.0 * Math.PI + i * 0.3).toFloat()
+                val b = 0.5f + 0.5f * cos(time * 2.0 * Math.PI + i * 0.1).toFloat()
+                materialInst.setParameter("baseColor", Colors.RgbType.LINEAR, r, g, b)
+            }
+        }
+    }
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        surfaceView = SurfaceView(this)
+        setContentView(surfaceView)
+
+        surfaceView.setOnTouchListener(touchListener)
+        choreographer = Choreographer.getInstance()
+
+        displayHelper = DisplayHelper(this)
+
+        setupSurfaceView()
+        setupFilament()
+        setupView()
+        setupScene()
+    }
+
+    private fun setupSurfaceView() {
+        uiHelper = UiHelper(UiHelper.ContextErrorPolicy.DONT_CHECK)
+        uiHelper.renderCallback = SurfaceCallback()
+        uiHelper.attachTo(surfaceView)
+    }
+
+    private fun setupFilament() {
+        engine = Engine.create()
+        renderer = engine.createRenderer()
+        scene = engine.createScene()
+        view = engine.createView()
+        camera = engine.createCamera(engine.entityManager.create())
+    }
+
+    private fun setupView() {
+        scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
+        view.camera = camera
+        view.scene = scene
+    }
+
+    private fun setupScene() {
+        loadMaterial()
+        createMesh()
+
+        val tcm = engine.transformManager
+        val center = (GRID_SIZE - 1) * 0.5f
+
+        for (i in 0 until NUM_CUBES) {
+            // Calculate grid position
+            val x = (i % GRID_SIZE) - center
+            val y = ((i / GRID_SIZE) % GRID_SIZE) - center
+            val z = (i / (GRID_SIZE * GRID_SIZE)) - center
+
+            val posX = x * SPACING
+            val posY = y * SPACING
+            val posZ = z * SPACING
+
+            // Create material instance for this cube
+            materialInstances[i] = material.createInstance()
+
+            // Set initial parameters (will be overwritten by animator, but good practice)
+            materialInstances[i]?.setParameter("baseColor", Colors.RgbType.SRGB, 1.0f, 0.85f, 0.57f)
+            materialInstances[i]?.setParameter("metallic", 0.0f)
+            materialInstances[i]?.setParameter("roughness", 0.3f)
+
+            // Create the renderable entity
+            renderables[i] = EntityManager.get().create()
+
+            // Create the renderable component
+            RenderableManager.Builder(1)
+                .boundingBox(Box(0.0f, 0.0f, 0.0f, 1.0f, 1.0f, 1.0f))
+                .geometry(0, PrimitiveType.TRIANGLES, vertexBuffer, indexBuffer, 0, 6 * 6)
+                .material(0, materialInstances[i]!!)
+                .build(engine, renderables[i])
+
+            // Add to scene
+            scene.addEntity(renderables[i])
+
+            // Set its initial transform
+            // Store the base translation matrix
+            Matrix.setIdentityM(translationMatrices[i], 0)
+            Matrix.translateM(translationMatrices[i], 0, posX, posY, posZ)
+
+            // Get the transform component instance
+            val inst = tcm.getInstance(renderables[i])
+            tcm.setTransform(inst, translationMatrices[i])
+        }
+
+        // We now need a light, let's create a directional light
+        light = EntityManager.get().create()
+
+        val (r, g, b) = Colors.cct(5_500.0f)
+        LightManager.Builder(LightManager.Type.DIRECTIONAL)
+                .color(r, g, b)
+                .intensity(110_000.0f)
+                .direction(0.0f, -0.5f, -1.0f)
+                .castShadows(true)
+                .build(engine, light)
+
+        scene.addEntity(light)
+
+        camera.setExposure(16.0f, 1.0f / 125.0f, 100.0f)
+
+        updateCamera()
+
+        startAnimation()
+    }
+
+    private fun loadMaterial() {
+        readUncompressedAsset("materials/lit.filamat").let {
+            material = Material.Builder().payload(it, it.remaining()).build(engine)
+        }
+    }
+
+    private fun createMesh() {
+        val floatSize = 4
+        val shortSize = 2
+        val vertexSize = 3 * floatSize + 4 * floatSize
+
+        // A vertex is a position + a tangent frame:
+        // 3 floats for XYZ position, 4 floats for normal+tangents (quaternion)
+        @Suppress("ArrayInDataClass")
+        data class Vertex(val x: Float, val y: Float, val z: Float, val tangents: FloatArray)
+        fun ByteBuffer.put(v: Vertex): ByteBuffer {
+            putFloat(v.x)
+            putFloat(v.y)
+            putFloat(v.z)
+            v.tangents.forEach { putFloat(it) }
+            return this
+        }
+
+        // 6 faces, 4 vertices per face
+        val vertexCount = 6 * 4
+
+        // Create tangent frames, one per face
+        val tfPX = FloatArray(4)
+        val tfNX = FloatArray(4)
+        val tfPY = FloatArray(4)
+        val tfNY = FloatArray(4)
+        val tfPZ = FloatArray(4)
+        val tfNZ = FloatArray(4)
+
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f,  1.0f,  0.0f,  0.0f, tfPX)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 0.0f, 0.0f, -1.0f, -1.0f,  0.0f,  0.0f, tfNX)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f, -1.0f,  0.0f,  1.0f,  0.0f, tfPY)
+        MathUtils.packTangentFrame(-1.0f,  0.0f, 0.0f, 0.0f, 0.0f,  1.0f,  0.0f, -1.0f,  0.0f, tfNY)
+        MathUtils.packTangentFrame( 0.0f,  1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f,  1.0f, tfPZ)
+        MathUtils.packTangentFrame( 0.0f, -1.0f, 0.0f, 1.0f, 0.0f,  0.0f,  0.0f,  0.0f, -1.0f, tfNZ)
+
+        val vertexData = ByteBuffer.allocate(vertexCount * vertexSize)
+                // It is important to respect the native byte order
+                .order(ByteOrder.nativeOrder())
+                // Face -Z
+                .put(Vertex(-1.0f, -1.0f, -1.0f, tfNZ))
+                .put(Vertex(-1.0f,  1.0f, -1.0f, tfNZ))
+                .put(Vertex( 1.0f,  1.0f, -1.0f, tfNZ))
+                .put(Vertex( 1.0f, -1.0f, -1.0f, tfNZ))
+                // Face +X
+                .put(Vertex( 1.0f, -1.0f, -1.0f, tfPX))
+                .put(Vertex( 1.0f,  1.0f, -1.0f, tfPX))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPX))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPX))
+                // Face +Z
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfPZ))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPZ))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPZ))
+                // Face -X
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfNX))
+                .put(Vertex(-1.0f,  1.0f, -1.0f, tfNX))
+                .put(Vertex(-1.0f, -1.0f, -1.0f, tfNX))
+                // Face -Y
+                .put(Vertex(-1.0f, -1.0f,  1.0f, tfNY))
+                .put(Vertex(-1.0f, -1.0f, -1.0f, tfNY))
+                .put(Vertex( 1.0f, -1.0f, -1.0f, tfNY))
+                .put(Vertex( 1.0f, -1.0f,  1.0f, tfNY))
+                // Face +Y
+                .put(Vertex(-1.0f,  1.0f, -1.0f, tfPY))
+                .put(Vertex(-1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.0f,  1.0f,  1.0f, tfPY))
+                .put(Vertex( 1.0f,  1.0f, -1.0f, tfPY))
+                // Make sure the cursor is pointing in the right place in the byte buffer
+                .flip()
+
+        // Declare the layout of our mesh
+        vertexBuffer = VertexBuffer.Builder()
+                .bufferCount(1)
+                .vertexCount(vertexCount)
+                // Because we interleave position and color data we must specify offset and stride
+                // We could use de-interleaved data by declaring two buffers and giving each
+                // attribute a different buffer index
+                .attribute(VertexAttribute.POSITION, 0, AttributeType.FLOAT3, 0,             vertexSize)
+                .attribute(VertexAttribute.TANGENTS, 0, AttributeType.FLOAT4, 3 * floatSize, vertexSize)
+                .build(engine)
+
+        // Feed the vertex data to the mesh
+        // We only set 1 buffer because the data is interleaved
+        vertexBuffer.setBufferAt(engine, 0, vertexData)
+
+        // Create the indices
+        val indexData = ByteBuffer.allocate(6 * 2 * 3 * shortSize)
+                .order(ByteOrder.nativeOrder())
+        repeat(6) {
+            val i = (it * 4).toShort()
+            indexData
+                    .putShort(i).putShort((i + 1).toShort()).putShort((i + 2).toShort())
+                    .putShort(i).putShort((i + 2).toShort()).putShort((i + 3).toShort())
+        }
+        indexData.flip()
+
+        // 6 faces, 2 triangles per face,
+        indexBuffer = IndexBuffer.Builder()
+                .indexCount(vertexCount * 2)
+                .bufferType(IndexBuffer.Builder.IndexType.USHORT)
+                .build(engine)
+        indexBuffer.setBuffer(engine, indexData)
+    }
+
+    private fun updateCamera() {
+        // Calculate eye position from spherical coordinates
+        val eyeY = cameraRadius * sin(cameraPhi)
+        val horizontalRadius = cameraRadius * cos(cameraPhi)
+        val eyeX = horizontalRadius * sin(cameraTheta)
+        val eyeZ = horizontalRadius * cos(cameraTheta)
+
+        // Point the camera at the center (0,0,0)
+        camera.lookAt(eyeX.toDouble(), eyeY.toDouble(), eyeZ.toDouble(), // eye
+                0.0, 0.0, 0.0, // center
+                0.0, 1.0, 0.0) // up
+    }
+
+    private val touchListener = object : android.view.View.OnTouchListener {
+        override fun onTouch(v: android.view.View?, event: android.view.MotionEvent?): Boolean {
+            if (event == null) return false
+            when (event.action) {
+                android.view.MotionEvent.ACTION_DOWN -> {
+                    mLastX = event.x
+                    mLastY = event.y
+                    return true
+                }
+                android.view.MotionEvent.ACTION_MOVE -> {
+                    val dx = event.x - mLastX
+                    val dy = event.y - mLastY
+
+                    cameraTheta -= dx * DRAG_SPEED
+                    cameraPhi += dy * DRAG_SPEED
+
+                    // Clamp vertical angle to avoid flipping over
+                    cameraPhi = cameraPhi.coerceIn(-1.5f, 1.5f)
+
+                    updateCamera()
+
+                    mLastX = event.x
+                    mLastY = event.y
+                    return true
+                }
+            }
+            return v?.onTouchEvent(event) ?: false
+        }
+    }
+
+    private fun startAnimation() {
+        animator.interpolator = LinearInterpolator()
+        animator.duration = 6000
+        animator.repeatMode = ValueAnimator.RESTART
+        animator.repeatCount = ValueAnimator.INFINITE
+        animator.addUpdateListener(animatorListener)
+        animator.start()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        choreographer.postFrameCallback(frameScheduler)
+        animator.start()
+    }
+
+    override fun onPause() {
+        super.onPause()
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel()
+    }
+
+    override fun onDestroy() {
+        super.onDestroy()
+
+        // Stop the animation and any pending frame
+        choreographer.removeFrameCallback(frameScheduler)
+        animator.cancel();
+
+        // Always detach the surface before destroying the engine
+        uiHelper.detach()
+
+        // Cleanup all resources
+        engine.destroyEntity(light)
+
+        // Destroy all 1000 entities and material instances
+        for (i in 0 until NUM_CUBES) {
+            engine.destroyEntity(renderables[i])
+            materialInstances[i]?.let { engine.destroyMaterialInstance(it) }
+        }
+
+        engine.destroyRenderer(renderer)
+        engine.destroyVertexBuffer(vertexBuffer)
+        engine.destroyIndexBuffer(indexBuffer)
+        engine.destroyMaterial(material)
+        engine.destroyView(view)
+        engine.destroyScene(scene)
+        engine.destroyCameraComponent(camera.entity)
+
+        // Engine.destroyEntity() destroys Filament related resources only
+        // (components), not the entity itself
+        val entityManager = EntityManager.get()
+        entityManager.destroy(light)
+        for (entity in renderables) {
+            entityManager.destroy(entity)
+        }
+        entityManager.destroy(camera.entity)
+
+        // Destroying the engine will free up any resource you may have forgotten
+        // to destroy, but it's recommended to do the cleanup properly
+        engine.destroy()
+    }
+
+    inner class FrameCallback : Choreographer.FrameCallback {
+        override fun doFrame(frameTimeNanos: Long) {
+            // Schedule the next frame
+            choreographer.postFrameCallback(this)
+
+            // This check guarantees that we have a swap chain
+            if (uiHelper.isReadyToRender) {
+                // If beginFrame() returns false you should skip the frame
+                // This means you are sending frames too quickly to the GPU
+                if (renderer.beginFrame(swapChain!!, frameTimeNanos)) {
+                    renderer.render(view)
+                    renderer.endFrame()
+                }
+            }
+        }
+    }
+
+    inner class SurfaceCallback : UiHelper.RendererCallback {
+        override fun onNativeWindowChanged(surface: Surface) {
+            swapChain?.let { engine.destroySwapChain(it) }
+            swapChain = engine.createSwapChain(surface)
+            displayHelper.attach(renderer, surfaceView.display)
+        }
+
+        override fun onDetachedFromSurface() {
+            displayHelper.detach()
+            swapChain?.let {
+                engine.destroySwapChain(it)
+                // Required to ensure we don't return before Filament is done executing the
+                // destroySwapChain command, otherwise Android might destroy the Surface
+                // too early
+                engine.flushAndWait()
+                swapChain = null
+            }
+        }
+
+        override fun onResized(width: Int, height: Int) {
+            val aspect = width.toDouble() / height.toDouble()
+            camera.setProjection(45.0, aspect, 0.1, 100.0, Camera.Fov.VERTICAL)
+
+            view.viewport = Viewport(0, 0, width, height)
+
+            FilamentHelper.synchronizePendingFrames(engine)
+        }
+    }
+
+    private fun readUncompressedAsset(assetName: String): ByteBuffer {
+        assets.openFd(assetName).use { fd ->
+            val input = fd.createInputStream()
+            val dst = ByteBuffer.allocate(fd.length.toInt())
+
+            val src = Channels.newChannel(input)
+            src.read(dst)
+            src.close()
+
+            return dst.apply { rewind() }
+        }
+    }
+}

android/samples/sample-material-instance-stress/src/main/materials/lit.mat

@@ -0,0 +1,53 @@
+// Simple lit material that defines 3 parameters:
+// - baseColor
+// - roughness
+// - metallic
+//
+// These parameters can be used by the application to change the appearance of the material.
+//
+// This source material must be compiled to a binary material using the matc tool.
+// The command used to compile this material is:
+// matc -p mobile -a opengl -o app/src/main/assets/lit.filamat app/src/materials/lit.mat
+//
+// See build.gradle for an example of how to compile materials automatically
+// Please refer to the documentation for more information about matc and the materials system.
+
+material {
+    name : lit,
+
+    // Dynamic lighting is enabled on this material
+    shadingModel : lit,
+
+    // We don't need to declare a "requires" array, lit materials
+    // always requires the "tangents" vertex attribute (the normal
+    // is required for lighting, tangent/bitangent for normal mapping
+    // and anisotropy)
+
+    // List of parameters exposed by this material
+    parameters : [
+        // The color must be passed in linear space, not sRGB
+        {
+            type : float3,
+            name : baseColor
+        },
+        {
+            type : float,
+            name : roughness
+        },
+        {
+            type : float,
+            name : metallic
+        }
+    ],
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+
+        // Nothing fancy here, we simply copy the parameters
+        material.baseColor.rgb = materialParams.baseColor;
+        material.roughness = materialParams.roughness;
+        material.metallic = materialParams.metallic;
+    }
+}

android/samples/sample-material-instance-stress/src/main/res/drawable-v24/ic_launcher_foreground.xml

@@ -0,0 +1,34 @@
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:aapt="http://schemas.android.com/aapt"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+  <path
+      android:fillType="evenOdd"
+      android:pathData="M32,64C32,64 38.39,52.99 44.13,50.95C51.37,48.37 70.14,49.57 70.14,49.57L108.26,87.69L108,109.01L75.97,107.97L32,64Z"
+      android:strokeColor="#00000000"
+      android:strokeWidth="1">
+    <aapt:attr name="android:fillColor">
+      <gradient
+          android:endX="78.5885"
+          android:endY="90.9159"
+          android:startX="48.7653"
+          android:startY="61.0927"
+          android:type="linear">
+        <item
+            android:color="#44000000"
+            android:offset="0.0"/>
+        <item
+            android:color="#00000000"
+            android:offset="1.0"/>
+      </gradient>
+    </aapt:attr>
+  </path>
+  <path
+      android:fillColor="#FFFFFF"
+      android:fillType="nonZero"
+      android:pathData="M66.94,46.02L66.94,46.02C72.44,50.07 76,56.61 76,64L32,64C32,56.61 35.56,50.11 40.98,46.06L36.18,41.19C35.45,40.45 35.45,39.3 36.18,38.56C36.91,37.81 38.05,37.81 38.78,38.56L44.25,44.05C47.18,42.57 50.48,41.71 54,41.71C57.48,41.71 60.78,42.57 63.68,44.05L69.11,38.56C69.84,37.81 70.98,37.81 71.71,38.56C72.44,39.3 72.44,40.45 71.71,41.19L66.94,46.02ZM62.94,56.92C64.08,56.92 65,56.01 65,54.88C65,53.76 64.08,52.85 62.94,52.85C61.8,52.85 60.88,53.76 60.88,54.88C60.88,56.01 61.8,56.92 62.94,56.92ZM45.06,56.92C46.2,56.92 47.13,56.01 47.13,54.88C47.13,53.76 46.2,52.85 45.06,52.85C43.92,52.85 43,53.76 43,54.88C43,56.01 43.92,56.92 45.06,56.92Z"
+      android:strokeColor="#00000000"
+      android:strokeWidth="1"/>
+</vector>

android/samples/sample-material-instance-stress/src/main/res/drawable/ic_launcher_background.xml

@@ -0,0 +1,171 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="108dp"
+    android:height="108dp"
+    android:viewportHeight="108"
+    android:viewportWidth="108">
+  <path
+      android:fillColor="#26A69A"
+      android:pathData="M0,0h108v108h-108z"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M9,0L9,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,0L19,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,0L29,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,0L39,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,0L49,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,0L59,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,0L69,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,0L79,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M89,0L89,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M99,0L99,108"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,9L108,9"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,19L108,19"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,29L108,29"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,39L108,39"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,49L108,49"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,59L108,59"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,69L108,69"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,79L108,79"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,89L108,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M0,99L108,99"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,29L89,29"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,39L89,39"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,49L89,49"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,59L89,59"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,69L89,69"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M19,79L89,79"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M29,19L29,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M39,19L39,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M49,19L49,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M59,19L59,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M69,19L69,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+  <path
+      android:fillColor="#00000000"
+      android:pathData="M79,19L79,89"
+      android:strokeColor="#33FFFFFF"
+      android:strokeWidth="0.8"/>
+</vector>

android/samples/sample-material-instance-stress/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background"/>
+  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+</adaptive-icon>

android/samples/sample-material-instance-stress/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+  <background android:drawable="@drawable/ic_launcher_background"/>
+  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
+</adaptive-icon>

android/samples/sample-material-instance-stress/src/main/res/values/colors.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <color name="colorPrimary">#3F51B5</color>
+  <color name="colorPrimaryDark">#303F9F</color>
+  <color name="colorAccent">#FF4081</color>
+</resources>

android/samples/sample-material-instance-stress/src/main/res/values/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+  <string name="app_name">Material Instance Stress</string>
+</resources>

android/samples/sample-material-instance-stress/src/main/res/values/styles.xml

@@ -0,0 +1,8 @@
+<resources>
+
+  <!-- Base application theme. -->
+  <style name="AppTheme" parent="android:Theme.Material.Light.DarkActionBar">
+    <!-- Customize your theme here. -->
+  </style>
+
+</resources>

android/settings.gradle

@@ -12,6 +12,7 @@ include ':samples:sample-image-based-lighting'
 include ':samples:sample-lit-cube'
 include ':samples:sample-live-wallpaper'
 include ':samples:sample-material-builder'
+include ':samples:sample-material-instance-stress'
 include ':samples:sample-multi-view'
 include ':samples:sample-page-curl'
 include ':samples:sample-stream-test'

build.sh

@@ -77,6 +77,10 @@ function print_help {
     echo "        meant for building the samples."
     echo "    -P"
     echo "        Enable perfetto traces on Android. Disabled by default on the Release build, enabled otherwise."
+    echo "    -y build_type"
+    echo "        Build the filament dependent tools (matc, resgen) separately from the project. This will set"
+    echo "        the tools as prebuilts that filament target will then use to build. The built_type option"
+    echo "        (debug|release) is meant to indicate the type of build of the resulting prebuilts."
     echo ""
     echo "Build types:"
     echo "    release"
@@ -154,7 +158,7 @@ function print_fgviewer_help {
 }
 
 # Unless explicitly specified, NDK version will be selected as highest available version within same major release chain
-FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/build/common/versions | grep GITHUB_NDK_VERSION | sed s/GITHUB_NDK_VERSION=//g | cut -f 1 -d ".")}
+FILAMENT_NDK_VERSION=$(cat `dirname $0`/build/common/versions | grep GITHUB_NDK_VERSION | sed s/GITHUB_NDK_VERSION=//g | cut -f 1 -d ".")
 
 # Internal variables
 ISSUE_CLEAN=false
@@ -217,6 +221,11 @@ OSMESA_OPTION=""
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false
 
+ISSUE_SPLIT_BUILD=false
+SPLIT_BUILD_TYPE=""
+PREBUILT_TOOLS_DIR=""
+IMPORT_EXECUTABLES_DIR_OPTION="-DIMPORT_EXECUTABLES_DIR=out"
+
 BUILD_GENERATOR=Ninja
 BUILD_COMMAND=ninja
 BUILD_CUSTOM_TARGETS=
@@ -242,6 +251,37 @@ function build_clean_aggressive {
     git clean -qfX android
 }
 
+function build_tools_for_split_build {
+    local build_type_arg=$1
+    local lc_build_type=$(echo "${build_type_arg}" | tr '[:upper:]' '[:lower:]')
+    PREBUILT_TOOLS_DIR="out/prebuilt-tools-${lc_build_type}"
+
+    echo "Building tools for split build (${lc_build_type}) in ${PREBUILT_TOOLS_DIR}..."
+    mkdir -p "${PREBUILT_TOOLS_DIR}"
+
+    pushd "${PREBUILT_TOOLS_DIR}" > /dev/null
+
+    local lc_name=$(echo "${UNAME}" | tr '[:upper:]' '[:lower:]')
+    local architectures=""
+    if [[ "${lc_name}" == "darwin" ]]; then
+        if [[ "${BUILD_UNIVERSAL_LIBRARIES}" == "true" ]]; then
+            architectures="-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64"
+        fi
+    fi
+
+    cmake \
+        -G "${BUILD_GENERATOR}" \
+        -DFILAMENT_EXPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR} \
+        -DCMAKE_BUILD_TYPE="${build_type_arg}" \
+        ${WEBGPU_OPTION} \
+        ${architectures} \
+        ../..
+
+    ${BUILD_COMMAND} ${WEB_HOST_TOOLS}
+
+    popd > /dev/null
+}
+
 function build_desktop_target {
     local lc_target=$(echo "$1" | tr '[:upper:]' '[:lower:]')
     local build_targets=$2
@@ -265,7 +305,7 @@ function build_desktop_target {
     if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then
         cmake \
             -G "${BUILD_GENERATOR}" \
-            -DIMPORT_EXECUTABLES_DIR=out \
+            ${IMPORT_EXECUTABLES_DIR_OPTION} \
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \
             ${EGL_ON_LINUX_OPTION} \
@@ -331,7 +371,7 @@ function build_webgl_with_target {
         source "${EMSDK}/emsdk_env.sh"
         cmake \
             -G "${BUILD_GENERATOR}" \
-            -DIMPORT_EXECUTABLES_DIR=out \
+            ${IMPORT_EXECUTABLES_DIR_OPTION} \
             -DCMAKE_TOOLCHAIN_FILE="${EMSDK}/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake" \
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \
@@ -404,7 +444,7 @@ function build_android_target {
     if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then
         cmake \
             -G "${BUILD_GENERATOR}" \
-            -DIMPORT_EXECUTABLES_DIR=out \
+            ${IMPORT_EXECUTABLES_DIR_OPTION} \
             -DCMAKE_BUILD_TYPE="$1" \
             -DFILAMENT_NDK_VERSION="${FILAMENT_NDK_VERSION}" \
             -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \
@@ -638,7 +678,7 @@ function build_ios_target {
     if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then
         cmake \
             -G "${BUILD_GENERATOR}" \
-            -DIMPORT_EXECUTABLES_DIR=out \
+            ${IMPORT_EXECUTABLES_DIR_OPTION} \
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../ios-${lc_target}/filament" \
             -DIOS_ARCH="${arch}" \
@@ -810,7 +850,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do
+while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:Py:" opt; do
     case ${opt} in
         h)
             print_help
@@ -979,6 +1019,20 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:P" opt; do
             ;;
         X)  OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}"
             ;;
+        y)
+            ISSUE_SPLIT_BUILD=true
+            SPLIT_BUILD_TYPE=${OPTARG}
+            case $(echo "${SPLIT_BUILD_TYPE}" | tr '[:upper:]' '[:lower:]') in
+                debug|release)
+                    ;;
+                *)
+                    echo "Unknown build type for -y: ${SPLIT_BUILD_TYPE}"
+                    echo "Build type must be one of [debug|release]"
+                    echo ""
+                    exit 1
+                    ;;
+            esac
+            ;;
         \?)
             echo "Invalid option: -${OPTARG}" >&2
             echo ""
@@ -1013,6 +1067,13 @@ done
 
 validate_build_command
 
+if [[ "${ISSUE_SPLIT_BUILD}" == "true" ]]; then
+    # Capitalize first letter of SPLIT_BUILD_TYPE
+    SPLIT_BUILD_TYPE_CAPITALIZED="$(echo ${SPLIT_BUILD_TYPE:0:1} | tr '[:lower:]' '[:upper:]')${SPLIT_BUILD_TYPE:1}"
+    build_tools_for_split_build "${SPLIT_BUILD_TYPE_CAPITALIZED}"
+    IMPORT_EXECUTABLES_DIR_OPTION="-DFILAMENT_IMPORT_PREBUILT_EXECUTABLES_DIR=${PREBUILT_TOOLS_DIR}"
+fi
+
 if [[ "${ISSUE_CLEAN}" == "true" ]]; then
     build_clean
 fi

build/android/build.sh

@@ -18,8 +18,8 @@ if [[ "$GITHUB_WORKFLOW" ]]; then
     fi
 fi
 
-# Unless explicitly specified, NDK version will be set to match exactly the required one
-FILAMENT_NDK_VERSION=${GITHUB_NDK_VERSION:-27.0.11718014}
+# Unless explicitly specified, NDK version will be selected as highest available version within same major release chain
+FILAMENT_NDK_VERSION=$(cat `dirname $0`/../common/versions | grep GITHUB_NDK_VERSION | sed s/GITHUB_NDK_VERSION=//g)
 
 (! grep "${FILAMENT_NDK_VERSION}" `dirname $0`/../../android/build.gradle > /dev/null) &&
     echo "Mismatch of NDK versions: want ${FILAMENT_NDK_VERSION} and not found in android/build.gradle" &&

build/common/versions

@@ -3,7 +3,7 @@ GITHUB_CMAKE_VERSION=3.22.1
 GITHUB_NINJA_VERSION=1.10.2
 GITHUB_MESA_VERSION=24.2.1
 GITHUB_LLVM_VERSION=16
-GITHUB_NDK_VERSION=27.0.11718014
+GITHUB_NDK_VERSION=29.0.14206865
 GITHUB_EMSDK_VERSION=3.1.60
 GITHUB_VULKANSDK_VERSION=1.4.321.0
-GITHUB_GLTF_SAMPLE_ASSETS_COMMIT=d441dfdb87413ff412c620849a649d61789a470f
+GITHUB_GLTF_SAMPLE_ASSETS_COMMIT=d441dfdb87413ff412c620849a649d61789a470f

build/toolchain-aarch64-linux-android.cmake

@@ -75,7 +75,7 @@ set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
 #   C_FLAGS += -Wl,-pie
 #   CXX_FLAGS += -lstdc++
 
-set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIE -mcpu=cortex-a57" CACHE STRING "Toolchain CFLAGS")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fPIE -march=armv8-a -mtune=cortex-a78" CACHE STRING "Toolchain CFLAGS")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CMAKE_C_FLAGS}" CACHE STRING "Toolchain CXXFLAGS")
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -fPIE -pie -static-libstdc++" CACHE STRING "Toolchain LDFLAGS")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -static-libstdc++" CACHE STRING "Toolchain LDFLAGS")

build/toolchain-arm7-linux-android.cmake

@@ -87,7 +87,7 @@ set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
 # for hardfp: CFLAGS must have -mhard-float
 #             LDFLAGS must have -Wl,--no-warn-mismatch
 #
-set(CMAKE_C_FLAGS   "${CMAKE_C_FLAGS} -mthumb -march=armv7-a -mcpu=cortex-a15 -mfloat-abi=softfp -mfpu=neon-vfpv4 -fPIE" CACHE STRING "Toolchain CFLAGS")
+set(CMAKE_C_FLAGS   "${CMAKE_C_FLAGS} -mthumb -march=armv7-a -mfloat-abi=softfp -mfpu=neon-vfpv4 -fPIE" CACHE STRING "Toolchain CFLAGS")
 set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${CMAKE_C_FLAGS}" CACHE STRING "Toolchain CXXFLAGS")
 set(CMAKE_EXE_LINKER_FLAGS    "${CMAKE_EXE_LINKER_FLAGS}    -march=armv7-a -Wl,--no-warn-mismatch -L${TOOLCHAIN}/arm-linux-androideabi/lib/armv7-a -static-libstdc++ -fPIE -pie" CACHE STRING "Toolchain LDFLAGS")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -march=armv7-a -Wl,--no-warn-mismatch -L${TOOLCHAIN}/arm-linux-androideabi/lib/armv7-a -static-libstdc++" CACHE STRING "Toolchain LDFLAGS")

docs/dup/bluevk.html

@@ -180,7 +180,7 @@ rm -r Vulkan-Headers-1.3.232 v1.3.232.zip
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
-                            <a rel="next prefetch" href="../dup/filamat.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                            <a rel="next prefetch" href="../dup/fgviewer.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>
 
@@ -194,7 +194,7 @@ rm -r Vulkan-Headers-1.3.232 v1.3.232.zip
                         <i class="fa fa-angle-left"></i>
                     </a>
 
-                    <a rel="next prefetch" href="../dup/filamat.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                    <a rel="next prefetch" href="../dup/fgviewer.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

@@ -200,6 +200,12 @@ inside the Filament source tree.</p>
 force a clean build by adding the <code>-c</code> flag in that case.</p>
 <p>To install the libraries and executables in <code>out/debug/</code> and <code>out/release/</code>, add the <code>-i</code> flag.
 The script offers more features described by executing <code>build.sh -h</code>.</p>
+<p>For more specialized options, please also consider the following pages:</p>
+<ul>
+<li><code>-d</code>: <a href="https://google.github.io/filament/dup/matdbg.html"><code>matdbg</code></a></li>
+<li><code>-t</code>: <a href="https://google.github.io/filament/dup/fgviewer.html"><code>fgviewer</code></a></li>
+<li><code>-b</code> and <code>-y</code>: <a href="https://google.github.io/filament/notes/asan_ubsan.html">ASAN/UBSAN builds</a></li>
+</ul>
 <h3 id="filament-specific-cmake-options"><a class="header" href="#filament-specific-cmake-options">Filament-specific CMake Options</a></h3>
 <p>The following CMake options are boolean options specific to Filament:</p>
 <ul>

docs/dup/fgviewer.html

@@ -0,0 +1,345 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>fgviewer - 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="fgviewer"><a class="header" href="#fgviewer">fgviewer</a></h1>
+<ol>
+<li><a href="#capabilities">Capabilities</a></li>
+<li><a href="#setup-for-desktop">Setup for Desktop</a></li>
+<li><a href="#setup-for-android">Setup for Android</a></li>
+<li><a href="#debugger-usage">Debugger Usage</a></li>
+<li><a href="#architecture-overview">Architecture Overview</a></li>
+<li><a href="#c-server">C++ Server</a></li>
+<li><a href="#javascript-client">JavaScript Client</a></li>
+<li><a href="#http-requests">HTTP Requests</a></li>
+<li><a href="#wish-list">Wish List</a></li>
+</ol>
+<h2 id="capabilities"><a class="header" href="#capabilities">Capabilities</a></h2>
+<p>fgviewer is a library and web application for real-time visualization of the frame graph in Filament.
+It displays active passes and resource usage, providing insights into the rendering pipeline.</p>
+<h2 id="setup-for-desktop"><a class="header" href="#setup-for-desktop">Setup for Desktop</a></h2>
+<p>When using the easy build script, include the <code>-t</code> argument. For example:</p>
+<pre><code>./build.sh -ft debug gltf_viewer
+</code></pre>
+<p>The <code>t</code> enables a CMake option called <code>FILAMENT_ENABLE_FGVIEWER</code> and the <code>f</code> ensures that CMake gets
+re-run so that the option is honored.</p>
+<p>Next, set an environment variable as follows. In Windows, use <code>set</code> instead of <code>export</code>.</p>
+<pre><code>export FILAMENT_FGVIEWER_PORT=8050
+</code></pre>
+<p>Next, launch any app that links against a debug build of a Filament and point your web browser to
+http://localhost:8050. Skip ahead to <strong>Debugger Usage</strong>.</p>
+<h2 id="setup-for-android"><a class="header" href="#setup-for-android">Setup for Android</a></h2>
+<p>Rebuild Filament for Android after enabling a CMake option called <code>FILAMENT_ENABLE_FGVIEWER</code>. Note that
+CMake is invoked from several places for Android (both gradle and our easy build script), so one
+pragmatic and reliable way of doing this is to simply hack <code>CMakeLists.txt</code> and
+<code>filament-android/CMakeLists.txt</code> by unconditionally setting <code>FILAMENT_ENABLE_FGVIEWER</code> to <code>ON</code>.</p>
+<p>After rebuilding Filament with the option enabled, ensure that internet permissions are enabled in
+your app by adding the following into your manifest as a child of the <code>&lt;manifest&gt;</code> element.</p>
+<pre><code>&lt;uses-permission android:name="android.permission.INTERNET" /&gt;
+</code></pre>
+<p>Now launch your app as usual. The Filament Engine sets up a server that is hardcoded to listen to
+port <code>8085</code>. Next, you will need to forward your device's TCP port <code>8085</code> to your host port of choice.
+For example, to forward the fgviewer server on your device to port <code>8085</code> on your host machine, do the
+following:</p>
+<pre><code>adb forward tcp:8085 tcp:8085
+</code></pre>
+<p>This lets you go to http://localhost:8085 in Chrome on your host machine.</p>
+<h2 id="debugger-usage"><a class="header" href="#debugger-usage">Debugger Usage</a></h2>
+<p>After opening the fgviewer page in your browser, you can see the active views are on the left panel.
+Then you can select any of them to see the active passes and resources for that view.</p>
+<p align="center">
+  <img width="600px" src=https://github.com/user-attachments/assets/2d31767f-fc25-4f17-8c14-528fe5c6b698>
+</p>
+<h2 id="architecture-overview"><a class="header" href="#architecture-overview">Architecture Overview</a></h2>
+<p align="center">
+  <img width="450" src=https://github.com/user-attachments/assets/537ebb89-6ad0-4b93-bbeb-207d4fe9ec5a>
+</p>
+<p>The fgviewer library has two parts: a C++ server and a JavaScript client. The C++ server is
+responsible for instancing a <a href="https://github.com/civetweb/civetweb">civetweb</a> context that handles HTTP requests. The
+JavaScript client is a small web app that contains a view into an in-browser database of framegraphs.</p>
+<p>When a new connection is established, the client asks the server for a list of framegraphs
+in order to populate its in-browser database. If the connection is lost (e.g. if the app crashes),
+then the database stays intact and the web app is still functional.</p>
+<h2 id="c-server"><a class="header" href="#c-server">C++ Server</a></h2>
+<p>The civetweb server is wrapped by our <code>DebugServer</code> class, which provides a public interface consisting of
+a few methods invoked by the Filament engine.</p>
+<p>Since each view corresponds to a frame graph, the engine should notify <code>DebugServer</code> of any changes to the views
+on the engine side.</p>
+<ul>
+<li><strong>createView</strong> Notifies the debugger that a new view has been created.</li>
+<li><strong>updateView</strong> Notifies the debugger of updates to an existing view.</li>
+<li><strong>destroyView</strong> Notifies the debugger that a view is being removed.</li>
+</ul>
+<h2 id="javascript-client"><a class="header" href="#javascript-client">JavaScript Client</a></h2>
+<p>The web app is built using LitElement, a lightweight library for creating Web Components. Our goal is to keep the code simple and modern, avoiding frameworks like React or Angular.</p>
+<p>The app presents a view over a pseudo-database, which is essentially a global variable holding a dictionary that maps frame graph ids to objects following the JSON structure described below.</p>
+<h2 id="http-requests"><a class="header" href="#http-requests">HTTP requests</a></h2>
+<p>The server responds to the following GET requests by returning a JSON blob. The <code>{id}</code> in these
+requests is a concept specific to fgviewer (not Filament) which is an 8-digit hex string for identifying frame graphs.</p>
+<hr />
+<p><code>/api/framegraphs</code></p>
+<p>Returns an array containing all framegraphs in an app. Example:</p>
+<pre><code class="language-json">[{
+    "fgid": "00000000",
+    "viewName": "Main View",
+    "passes": [{
+        "name": "shadow pass",
+        "reads": [],
+        "writes": ["0"]
+    }],
+    "resources": [{
+        "id": "0",
+        "name": "shadowmap",
+        "properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
+    }]
+},
+{
+    "fgid": "00000001",
+    "viewName": "UI view",
+    ...
+}]
+</code></pre>
+<hr />
+<p><code>/api/framegraph?fg={id}</code></p>
+<p>Returns a specific framegraph info. Example:</p>
+<pre><code class="language-json">{
+  "fgid": "00000000",
+  "viewName": "Main View",
+  "passes": [{
+    "name": "shadow pass",
+    "reads": [],
+    "writes": ["0"]
+  }],
+  "resources": [{
+    "id": "0",
+    "name": "shadowmap",
+    "properties": [{"resolution": "256x256"}, {"is_subresource": "false"}]
+  }]
+}
+</code></pre>
+<hr />
+<p><code>/api/status</code></p>
+<p>Returns one of the below:</p>
+<ul>
+<li><code>0</code>: first time connected</li>
+<li><code>1</code>: no-op</li>
+<li><code>{fgid}</code>: the corresponding frame graph has an update
+<ul>
+<li>Then the web view can request for the actual info using the previous api</li>
+</ul>
+</li>
+</ul>
+<p>If the request gets timeout, the web page show disconnected to the user.</p>
+<hr />
+<h2 id="wish-list"><a class="header" href="#wish-list">Wish List</a></h2>
+<ul>
+<li>Display the texture contents on the webview</li>
+</ul>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="../dup/bluevk.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/filamat.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="../dup/bluevk.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/filamat.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/filamat.html

@@ -336,7 +336,7 @@ void material(inout MaterialInputs material) {
 
                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
-                            <a rel="prev" href="../dup/bluevk.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                            <a rel="prev" href="../dup/fgviewer.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>
 
@@ -350,7 +350,7 @@ void material(inout MaterialInputs material) {
             </div>
 
             <nav class="nav-wide-wrapper" aria-label="Page navigation">
-                    <a rel="prev" href="../dup/bluevk.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                    <a rel="prev" href="../dup/fgviewer.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.66.1'
+    implementation 'com.google.android.filament:filament-android:1.68.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.66.1'
+<pre><code class="language-shell">pod 'Filament', '~&gt; 1.68.0'
 </code></pre>
 <h2 id="documentation"><a class="header" href="#documentation">Documentation</a></h2>
 <ul>

docs/notes/asan_ubsan.html

@@ -160,10 +160,15 @@
                     <main>
                         <h1 id="running-with-asanubsan"><a class="header" href="#running-with-asanubsan">Running with ASAN/UBSAN</a></h1>
 <h2 id="enabling"><a class="header" href="#enabling">Enabling</a></h2>
-<p>When building though build.sh, pass the <code>-b</code> flag. This sets the cmake variable
+<p>When building though <code>build.sh</code>, pass the <code>-b</code> flag. This sets the cmake variable
 <code>FILAMENT_ENABLE_ASAN_UBSAN=ON</code> which eventually passes <code>"-fsanitize=address -fsanitize=undefined"</code>
 to all compile and link operations.</p>
-<p>If building through CMake directly, or an IDE like CLion that doesn't use build.sh, instead pass
+<p>It might be desirable to pair the <code>-b</code> with <code>-y release</code>. The <code>-y</code> flag indicates that targets
+in <code>/tools</code> will be built separately from the filament target, and the filament build depends on
+the <code>/tools</code> targets as prebuilt binaries. This separation reduces ASAN/UBSAN build time
+considerably. This option assumes that the user is trying to catch sanitization issues for
+filament and not the tools that are used to build filament.</p>
+<p>If building through CMake directly, or an IDE like CLion that doesn't use <code>build.sh</code>, instead pass
 <code>-DFILAMENT_ENABLE_ASAN_UBSAN=ON</code> to cmake in order to get the same result.</p>
 <h2 id="getting-memory-leak-detection-on-mac"><a class="header" href="#getting-memory-leak-detection-on-mac">Getting memory leak detection on Mac</a></h2>
 <p>Memory leak detection isn't enabled by default on MacOS. There are two issues to address, first is

docs_src/build/duplicates.json

@@ -46,6 +46,9 @@
     "libs/matdbg/README.md": {
         "dest": "dup/matdbg.md"
     },
+    "libs/fgviewer/README.md": {
+        "dest": "dup/fgviewer.md"
+    },
     "tools/normal-blending/README.md": {
         "dest": "dup/normal_blending.md"
     },

docs_src/build/requirements.txt

@@ -10,6 +10,6 @@ sortedcontainers==2.4.0
 trio==0.31.0
 trio-websocket==0.12.2
 typing_extensions==4.15.0
-urllib3==2.5.0
+urllib3==2.6.0
 websocket-client==1.9.0
 wsproto==1.2.0

docs_src/src_mdbook/src/SUMMARY.md

@@ -32,6 +32,7 @@
   - [Libraries](./notes/libs.md)
     - [bluegl](./dup/bluegl.md)
     - [bluevk](./dup/bluevk.md)
+    - [fgviewer](./dup/fgviewer.md)
     - [filamat](./dup/filamat.md)
     - [gltfio](./dup/gltfio.md)
     - [iblprefilter](./dup/iblprefilter.md)

docs_src/src_mdbook/src/notes/asan_ubsan.md

@@ -2,11 +2,17 @@
 
 ## Enabling
 
-When building though build.sh, pass the `-b` flag. This sets the cmake variable
+When building though `build.sh`, pass the `-b` flag. This sets the cmake variable
 `FILAMENT_ENABLE_ASAN_UBSAN=ON` which eventually passes `"-fsanitize=address -fsanitize=undefined"`
 to all compile and link operations.
 
-If building through CMake directly, or an IDE like CLion that doesn't use build.sh, instead pass
+It might be desirable to pair the `-b` with `-y release`. The `-y` flag indicates that targets
+in `/tools` will be built separately from the filament target, and the filament build depends on
+the `/tools` targets as prebuilt binaries. This separation reduces ASAN/UBSAN build time
+considerably. This option assumes that the user is trying to catch sanitization issues for
+filament and not the tools that are used to build filament.
+
+If building through CMake directly, or an IDE like CLion that doesn't use `build.sh`, instead pass
 `-DFILAMENT_ENABLE_ASAN_UBSAN=ON` to cmake in order to get the same result.
 
 ## Getting memory leak detection on Mac

filament/CMakeLists.txt

@@ -139,6 +139,7 @@ set(SRCS
         src/details/SwapChain.cpp
         src/details/Sync.cpp
         src/details/Texture.cpp
+        src/details/UboManager.cpp
         src/details/VertexBuffer.cpp
         src/details/View.cpp
         src/ds/PerViewDescriptorSetUtils.cpp
@@ -218,6 +219,7 @@ set(PRIVATE_HDRS
         src/details/Stream.h
         src/details/SwapChain.h
         src/details/Texture.h
+        src/details/UboManager.h
         src/details/VertexBuffer.h
         src/details/View.h
         src/downcast.h
@@ -363,7 +365,7 @@ add_definitions(
 # Generate all .filamat: default material, skyboxes, and post-process
 # ==================================================================================================
 
-if (CMAKE_CROSSCOMPILING)
+if (CMAKE_CROSSCOMPILING OR FILAMENT_IMPORT_PREBUILT_EXECUTABLES)
     include(${IMPORT_EXECUTABLES})
 endif()
 

filament/README.md

@@ -92,7 +92,7 @@ Copy your platform's Makefile below into a `Makefile` inside the same directory.
 ### Linux
 
 ```make
-FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl -labseil
+FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -libl -labseil
 CC=clang++
 
 main: main.o
@@ -110,7 +110,7 @@ clean:
 ### macOS
 
 ```make
-FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -lvkshaders -libl -labseil
+FILAMENT_LIBS=-lfilament -lbackend -lbluegl -lbluevk -lfilabridge -lfilaflat -lutils -lgeometry -lsmol-v -libl -labseil
 FRAMEWORKS=-framework Cocoa -framework Metal -framework CoreVideo
 CC=clang++
 ARCH ?= $(shell uname -m)
@@ -140,7 +140,7 @@ used to change the run-time library version.
 
 ```make
 FILAMENT_LIBS=filament.lib backend.lib bluegl.lib bluevk.lib filabridge.lib filaflat.lib \
-              utils.lib geometry.lib smol-v.lib ibl.lib vkshaders.lib abseil.lib
+              utils.lib geometry.lib smol-v.lib ibl.lib abseil.lib
 CC=cl.exe
 
 main.exe: main.obj

filament/backend/CMakeLists.txt

@@ -104,8 +104,10 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3)
         list(APPEND SRCS src/VirtualMachineEnv.cpp)
     endif ()
     if (ANDROID)
+        list(APPEND SRCS src/AndroidNdk.cpp)
         list(APPEND SRCS src/AndroidNativeWindow.cpp)
         list(APPEND SRCS src/AndroidSwapChainHelper.cpp)
+        list(APPEND SRCS src/AndroidFrameCallback.cpp)
         list(APPEND SRCS src/opengl/platforms/ExternalStreamManagerAndroid.cpp)
         list(APPEND SRCS src/opengl/platforms/PlatformEGLAndroid.cpp)
     elseif (IOS)
@@ -204,6 +206,8 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanDriverFactory.h
             src/vulkan/VulkanExternalImageManager.cpp
             src/vulkan/VulkanExternalImageManager.h
+            src/vulkan/VulkanStreamedImageManager.cpp
+            src/vulkan/VulkanStreamedImageManager.h
             src/vulkan/VulkanFboCache.cpp
             src/vulkan/VulkanFboCache.h
             src/vulkan/VulkanHandles.cpp
@@ -250,10 +254,21 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/utils/Spirv.h
             src/vulkan/utils/StaticVector.h
     )
-    if (LINUX OR WIN32)
-        list(APPEND SRCS src/vulkan/platform/VulkanPlatformLinuxWindows.cpp)
+    if (LINUX)
+        list(APPEND SRCS
+            src/vulkan/platform/VulkanPlatformLinux.cpp
+            include/backend/platforms/VulkanPlatformLinux.h
+        )
+    elseif (WIN32)
+        list(APPEND SRCS
+            include/backend/platforms/VulkanPlatformWindows.h
+            src/vulkan/platform/VulkanPlatformWindows.cpp
+        )
     elseif (APPLE OR IOS)
-        list(APPEND SRCS src/vulkan/platform/VulkanPlatformApple.mm)
+        list(APPEND SRCS
+            include/backend/platforms/VulkanPlatformApple.h
+            src/vulkan/platform/VulkanPlatformApple.mm
+        )
     elseif (ANDROID)
         list(APPEND SRCS
             include/backend/platforms/VulkanPlatformAndroid.h
@@ -303,6 +318,8 @@ if (FILAMENT_SUPPORTS_WEBGPU)
             src/webgpu/WebGPURenderPrimitive.h
             src/webgpu/WebGPURenderTarget.cpp
             src/webgpu/WebGPURenderTarget.h
+            src/webgpu/WebGPUStagePool.cpp
+            src/webgpu/WebGPUStagePool.h
             src/webgpu/WebGPUStrings.h
             src/webgpu/WebGPUSwapChain.cpp
             src/webgpu/WebGPUSwapChain.h
@@ -369,46 +386,6 @@ endif()
 add_library(${TARGET}_headers INTERFACE)
 target_include_directories(${TARGET}_headers INTERFACE ${PUBLIC_HDR_DIR})
 
-# ==================================================================================================
-# Build SPIRV snippets used by the Vulkan backend.
-# ==================================================================================================
-
-set(VKSHADERS_DIR  "${CMAKE_CURRENT_BINARY_DIR}/generated/vkshaders")
-
-file(MAKE_DIRECTORY ${VKSHADERS_DIR})
-
-get_resgen_vars(${VKSHADERS_DIR} vkshaders)
-
-set(VKSHADER_BINS)
-function(build_vkshader SOURCE TARGET_PATH)
-    set(SOURCE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/src/vulkan/${SOURCE}")
-    set(VKSHADER_BINS ${VKSHADER_BINS} ${TARGET_PATH} PARENT_SCOPE)
-    add_custom_command(
-            OUTPUT ${TARGET_PATH}
-            COMMAND matc --raw -o ${TARGET_PATH} ${SOURCE_PATH}
-            MAIN_DEPENDENCY ${SOURCE_PATH}
-            DEPENDS matc ${SOURCE_PATH}
-            COMMENT "Building SPIR-V")
-endfunction()
-build_vkshader("BlitDepth.vs" "BlitDepthVs.spv")
-build_vkshader("BlitDepth.fs" "BlitDepthFs.spv")
-
-add_custom_command(
-        OUTPUT ${RESGEN_OUTPUTS}
-        COMMAND resgen ${RESGEN_FLAGS} ${VKSHADER_BINS}
-        DEPENDS resgen ${VKSHADER_BINS}
-        COMMENT "Aggregating compiled VK shaders")
-
-if (DEFINED RESGEN_SOURCE_FLAGS)
-    set_source_files_properties(${RESGEN_SOURCE} PROPERTIES COMPILE_FLAGS ${RESGEN_SOURCE_FLAGS})
-endif()
-
-set(DUMMY_SRC "${VKSHADERS_DIR}/dummy.c")
-add_custom_command(OUTPUT ${DUMMY_SRC} COMMAND echo "//" > ${DUMMY_SRC})
-
-add_library(vkshaders STATIC ${DUMMY_SRC} ${RESGEN_SOURCE})
-set_target_properties(vkshaders PROPERTIES FOLDER Filament/Generated)
-
 # ==================================================================================================
 # Dependencies
 # ==================================================================================================
@@ -442,7 +419,7 @@ if(FILAMENT_SUPPORTS_OPENGL AND NOT IOS AND NOT ANDROID AND NOT WEBGL)
 endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)
-    target_link_libraries(${TARGET} PUBLIC bluevk vkmemalloc vkshaders smol-v)
+    target_link_libraries(${TARGET} PUBLIC bluevk vkmemalloc smol-v)
     target_link_libraries(${TARGET} PRIVATE SPIRV-Headers)
 endif()
 
@@ -561,7 +538,7 @@ endif()
 # ==================================================================================================
 set(INSTALL_TYPE ARCHIVE)
 install(TARGETS ${TARGET} ${INSTALL_TYPE} DESTINATION lib/${DIST_DIR})
-install(TARGETS vkshaders ${INSTALL_TYPE} DESTINATION lib/${DIST_DIR})
+install(TARGETS ${INSTALL_TYPE} DESTINATION lib/${DIST_DIR})
 install(DIRECTORY ${PUBLIC_HDR_DIR}/backend DESTINATION include)
 
 if (FILAMENT_SUPPORTS_WEBGPU)
@@ -592,6 +569,7 @@ if (APPLE OR LINUX)
         test/test_BufferUpdates.cpp
         test/test_Callbacks.cpp
         test/test_MemoryMappedBuffer.cpp
+        test/test_MsaaSwapChain.cpp
         test/test_MRT.cpp
         test/test_PushConstants.cpp
         test/test_LoadImage.cpp

filament/backend/include/backend/BufferObjectStreamDescriptor.h

@@ -1,63 +0,0 @@
-/*
- * 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.
- */
-
-#ifndef TNT_FILAMENT_BACKEND_BUFFEROBJECTSTREAMDESCRIPTOR_H
-#define TNT_FILAMENT_BACKEND_BUFFEROBJECTSTREAMDESCRIPTOR_H
-
-#include <backend/Handle.h>
-
-#include <vector>
-
-namespace filament::backend {
-
-/**
- * The type of association between a buffer object and a stream.
- */
- enum class BufferObjectStreamAssociationType { TRANSFORM_MATRIX };
-
-/**
- * A descriptor for a buffer object to stream association.
- */
-class UTILS_PUBLIC BufferObjectStreamDescriptor {
-public:
-    //! creates an empty descriptor
-    BufferObjectStreamDescriptor() noexcept = default;
-
-    BufferObjectStreamDescriptor(const BufferObjectStreamDescriptor& rhs) = delete;
-    BufferObjectStreamDescriptor& operator=(const BufferObjectStreamDescriptor& rhs) = delete;
-
-    BufferObjectStreamDescriptor(BufferObjectStreamDescriptor&& rhs) = default;
-    BufferObjectStreamDescriptor& operator=(BufferObjectStreamDescriptor&& rhs) = default;
-
-    // --------------------------------------------------------------------------------------------
-
-    struct StreamDataDescriptor {
-        uint32_t offset;
-        Handle<HwStream> stream;
-        BufferObjectStreamAssociationType associationType;
-    };
-
-    std::vector<StreamDataDescriptor> mStreams;
-};
-
-} // namespace filament::backend
-
-#if !defined(NDEBUG)
-utils::io::ostream& operator<<(utils::io::ostream& out,
-        const filament::backend::BufferObjectStreamDescriptor& b);
-#endif
-
-#endif // TNT_FILAMENT_BACKEND_BUFFEROBJECTSTREAMDESCRIPTOR_H

filament/backend/include/backend/DriverEnums.h

@@ -1681,7 +1681,7 @@ static_assert(sizeof(StencilState::StencilOperations) == 5u,
 static_assert(sizeof(StencilState) == 12u,
         "StencilState size not what was intended");
 
-using FrameScheduledCallback = utils::Invocable<void(backend::PresentCallable)>;
+using FrameScheduledCallback = utils::Invocable<void(PresentCallable)>;
 
 enum class Workaround : uint16_t {
     // The EASU pass must split because shader compiler flattens early-exit branch
@@ -1707,7 +1707,13 @@ enum class Workaround : uint16_t {
     EMULATE_SRGB_SWAPCHAIN,
 };
 
-using StereoscopicType = backend::Platform::StereoscopicType;
+using StereoscopicType = Platform::StereoscopicType;
+
+using FrameTimestamps = Platform::FrameTimestamps;
+
+using CompositorTiming = Platform::CompositorTiming;
+
+using AsynchronousMode = Platform::AsynchronousMode;
 
 } // namespace filament::backend
 

filament/backend/include/backend/Platform.h

@@ -19,13 +19,17 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORM_H
 #define TNT_FILAMENT_BACKEND_PLATFORM_H
 
+#include <utils/CString.h>
 #include <utils/compiler.h>
 #include <utils/Invocable.h>
+#include <utils/Mutex.h>
 
 #include <stddef.h>
 #include <stdint.h>
 
 #include <atomic>
+#include <memory>
+#include <mutex>
 
 namespace filament::backend {
 
@@ -70,6 +74,9 @@ public:
         ExternalImageHandle& operator=(ExternalImageHandle const& rhs) noexcept;
         ExternalImageHandle& operator=(ExternalImageHandle&& rhs) noexcept;
 
+        bool operator==(const ExternalImageHandle& rhs) const noexcept {
+            return mTarget == rhs.mTarget;
+        }
         explicit operator bool() const noexcept { return mTarget != nullptr; }
 
         ExternalImage* UTILS_NULLABLE get() noexcept { return mTarget; }
@@ -96,6 +103,7 @@ public:
         using time_point_ns = int64_t;
         /** duration in nanosecond on the std::steady_clock */
         using duration_ns = int64_t;
+        static constexpr time_point_ns INVALID = -1;    //!< value not supported
         /**
          * The timestamp [ns] since epoch of the next time the compositor will begin composition.
          * This is effectively the deadline for when the compositor must receive a newly queued
@@ -110,9 +118,27 @@ public:
 
         /**
          * The time delta [ns] between the start of composition and the expected present time of
-         *  that composition. This can be used to estimate the latency of the actual present time.
+         * that composition. This can be used to estimate the latency of the actual present time.
          */
         duration_ns compositeToPresentLatency;
+
+        /**
+         * The timestamp [ns] since epoch of the system's expected presentation time.
+         * INVALID if not supported.
+         */
+        time_point_ns expectedPresentTime;
+
+        /**
+         * The timestamp [ns] since epoch of the current frame's start (i.e. vsync)
+         * INVALID if not supported.
+         */
+        time_point_ns frameTime;
+
+        /**
+         * The timestamp [ns] since epoch of the current frame's deadline
+         * INVALID if not supported.
+         */
+        time_point_ns frameTimelineDeadline;
     };
 
     struct FrameTimestamps {
@@ -120,14 +146,62 @@ public:
         using time_point_ns = int64_t;
         static constexpr time_point_ns INVALID = -1;    //!< value not supported
         static constexpr time_point_ns PENDING = -2;    //!< value not yet available
+
+        /**
+         * The time the application requested this frame be presented.
+         * If the application does not request a presentation time explicitly,
+         * this will correspond to buffer's queue time.
+         */
         time_point_ns requestedPresentTime;
+
+        /**
+         * The time when all the application's rendering to the surface was completed.
+         */
         time_point_ns acquireTime;
+
+        /**
+         * The time when the compositor selected this frame as the one to use for the next
+         * composition. This is the earliest indication that the frame was submitted in time.
+         */
         time_point_ns latchTime;
-        time_point_ns firstRefreshStartTime;
-        time_point_ns lastRefreshStartTime;
+
+        /**
+         * The first time at which the compositor began preparing composition for this frame.
+         * Zero if composition was handled by the display and the compositor didn't do any
+         * rendering.
+         */
+        time_point_ns firstCompositionStartTime;
+
+        /**
+         * The last time at which the compositor began preparing composition for this frame, for
+         * frames composited more than once. Zero if composition was handled by the display and the
+         * compositor didn't do any rendering.
+         */
+        time_point_ns lastCompositionStartTime;
+
+        /**
+         * The time at which the compositor's rendering work for this frame finished. This will be
+         * INVALID if composition was handled by the display and the compositor didn't do any
+         * rendering.
+         */
         time_point_ns gpuCompositionDoneTime;
+
+        /**
+         * The time at which this frame started to scan out to the physical display.
+         */
         time_point_ns displayPresentTime;
+
+        /**
+         * The time when the buffer became available for reuse as a buffer the client can target
+         * without blocking. This is generally the point when all read commands of the buffer have
+         * been submitted, but not necessarily completed.
+         */
         time_point_ns dequeueReadyTime;
+
+        /**
+         * The time at which all reads for the purpose of display/composition were completed for
+         * this frame.
+         */
         time_point_ns releaseTime;
     };
 
@@ -181,6 +255,28 @@ public:
         REALTIME,
     };
 
+    /**
+     * Defines how asynchronous operations are handled by the engine.
+     */
+    enum class AsynchronousMode : uint8_t {
+        /**
+         * Asynchronous operations are disabled. This is the default.
+         */
+        NONE,
+
+        /**
+         * Attempts to use a dedicated worker thread for asynchronous tasks. If threading is not
+         * supported by the platform, it automatically falls back to using an amortization strategy.
+         */
+        THREAD_PREFERRED,
+
+        /**
+         * Uses an amortization strategy, processing a small number of asynchronous tasks during
+         * each engine update cycle.
+         */
+        AMORTIZATION,
+    };
+
     struct DriverConfig {
         /**
          * Size of handle arena in bytes. Setting to 0 indicates default value is to be used.
@@ -250,6 +346,11 @@ public:
          *      - VulkanPlatform
          */
         bool vulkanEnableStagingBufferBypass = false;
+
+        /**
+         * Asynchronous mode for the engine. Defines how asynchronous operations are handled.
+         */
+        AsynchronousMode asynchronousMode = AsynchronousMode::NONE;
     };
 
     Platform() noexcept;
@@ -441,13 +542,22 @@ public:
     // --------------------------------------------------------------------------------------------
     // Debugging APIs
 
-    using DebugUpdateStatFunc = utils::Invocable<void(const char* UTILS_NONNULL key, uint64_t value)>;
+    using DebugUpdateStatFunc = utils::Invocable<void(const char* UTILS_NONNULL key,
+            uint64_t intValue, utils::CString stringValue)>;
 
     /**
      * Sets the callback function that the backend can use to update backend-specific statistics
      * to aid with debugging. This callback is guaranteed to be called on the Filament driver
      * thread.
      *
+     * The callback signature is (key, intValue, stringValue). Note that for any given call,
+     * only one of the value parameters (intValue or stringValue) will be meaningful, depending on
+     * the specific key.
+     *
+     * IMPORTANT_NOTE: because the callback is called on the driver thread, only quick, non-blocking
+     * work should be done inside it. Furthermore, no graphics API calls (such as GL calls) should
+     * be made, which could interfere with Filament's driver state.
+     *
      * @param debugUpdateStat   an Invocable that updates debug statistics
      */
     void setDebugUpdateStatFunc(DebugUpdateStatFunc&& debugUpdateStat) noexcept;
@@ -466,15 +576,32 @@ public:
      * This function is guaranteed to be called only on a single thread, the Filament driver
      * thread.
      *
-     * @param key          a null-terminated C-string with the key of the debug statistic
-     * @param value        the updated value of key
+     * @param key           a null-terminated C-string with the key of the debug statistic
+     * @param intValue      the updated integer value of key (the string value passed to the
+     *                      callback will be empty)
      */
-    void debugUpdateStat(const char* UTILS_NONNULL key, uint64_t value);
+    void debugUpdateStat(const char* UTILS_NONNULL key, uint64_t intValue);
+
+    /**
+     * To track backend-specific statistics, the backend implementation can call the
+     * application-provided callback function debugUpdateStatFunc to associate or update a value
+     * with a given key. It is possible for this function to be called multiple times with the
+     * same key, in which case newer values should overwrite older values.
+     *
+     * This function is guaranteed to be called only on a single thread, the Filament driver
+     * thread.
+     *
+     * @param key           a null-terminated C-string with the key of the debug statistic
+     * @param stringValue   the updated string value of key (the integer value passed to the
+     *                      callback will be 0)
+     */
+    void debugUpdateStat(const char* UTILS_NONNULL key, utils::CString stringValue);
 
 private:
-    InsertBlobFunc mInsertBlob;
-    RetrieveBlobFunc mRetrieveBlob;
-    DebugUpdateStatFunc mDebugUpdateStat;
+    std::shared_ptr<InsertBlobFunc> mInsertBlob;
+    std::shared_ptr<RetrieveBlobFunc> mRetrieveBlob;
+    std::shared_ptr<DebugUpdateStatFunc> mDebugUpdateStat;
+    mutable utils::Mutex mMutex;
 };
 
 } // namespace filament

filament/backend/include/backend/platforms/AndroidNdk.h

@@ -0,0 +1,79 @@
+/*
+ * 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.
+ */
+
+#ifndef FILAMENT_BACKEND_ANDROIDNDK_H
+#define FILAMENT_BACKEND_ANDROIDNDK_H
+
+#include <android/native_window.h>
+#include <android/hardware_buffer.h>
+
+#define FILAMENT_REQUIRES_API(x) __attribute__((__availability__(android,introduced=x)))
+
+#define FILAMENT_USE_DLSYM(api) (__ANDROID_API__ < (api))
+
+namespace filament::backend {
+
+class AndroidNdk {
+public:
+    AndroidNdk();
+
+#if FILAMENT_USE_DLSYM(26)
+
+    static void AHardwareBuffer_acquire(
+            AHardwareBuffer* buffer) FILAMENT_REQUIRES_API(26) {
+        ndk.AHardwareBuffer_acquire(buffer);
+    }
+
+    static void AHardwareBuffer_release(
+            AHardwareBuffer* buffer) FILAMENT_REQUIRES_API(26) {
+        ndk.AHardwareBuffer_release(buffer);
+    }
+
+    static void AHardwareBuffer_describe(
+            AHardwareBuffer const* buffer, AHardwareBuffer_Desc* desc) FILAMENT_REQUIRES_API(26) {
+        ndk.AHardwareBuffer_describe(buffer, desc);
+    }
+
+#else
+
+    static void AHardwareBuffer_acquire(
+            AHardwareBuffer* buffer) FILAMENT_REQUIRES_API(26) {
+        ::AHardwareBuffer_acquire(buffer);
+    }
+    static void AHardwareBuffer_release(
+            AHardwareBuffer* buffer) FILAMENT_REQUIRES_API(26) {
+        ::AHardwareBuffer_release(buffer);
+    }
+    static void AHardwareBuffer_describe(
+            AHardwareBuffer const* buffer, AHardwareBuffer_Desc* desc) FILAMENT_REQUIRES_API(26) {
+        ::AHardwareBuffer_describe(buffer, desc);
+    }
+
+#endif
+
+private:
+#if FILAMENT_USE_DLSYM(26)
+    static struct Ndk {
+        void (*AHardwareBuffer_acquire)(AHardwareBuffer*);
+        void (*AHardwareBuffer_release)(AHardwareBuffer*);
+        void (*AHardwareBuffer_describe)(AHardwareBuffer const*, AHardwareBuffer_Desc*);
+    } ndk;
+#endif
+};
+
+} // filament::backend
+
+#endif //FILAMENT_BACKEND_ANDROIDNDK_H

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

@@ -17,7 +17,7 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 
-#include "AndroidSwapChainHelper.h"
+#include "AndroidNdk.h"
 
 #include <backend/AcquiredImage.h>
 #include <backend/DriverEnums.h>
@@ -43,7 +43,7 @@ class ExternalStreamManagerAndroid;
  * A concrete implementation of OpenGLPlatform and subclass of PlatformEGL that supports
  * EGL on Android. It adds Android streaming functionality to PlatformEGL.
  */
-class PlatformEGLAndroid : public PlatformEGL {
+class PlatformEGLAndroid : public PlatformEGL, public AndroidNdk {
 public:
 
     PlatformEGLAndroid() noexcept;
@@ -167,24 +167,19 @@ protected:
             SwapChain* drawSwapChain,
             SwapChain* readSwapChain) override;
 
-    struct SwapChainEGLAndroid : public SwapChainEGL {
-        SwapChainEGLAndroid(PlatformEGLAndroid const& platform,
-                void* nativeWindow, uint64_t flags);
-        SwapChainEGLAndroid(PlatformEGLAndroid const& platform,
-                uint32_t width, uint32_t height, uint64_t flags);
-        void terminate(PlatformEGLAndroid& platform);
-        bool setPresentFrameId(uint64_t frameId) const noexcept;
-        uint64_t getFrameId(uint64_t frameId) const noexcept;
-    private:
-        AndroidSwapChainHelper mImpl{};
-    };
-
 private:
+    struct SwapChainEGLAndroid;
+    struct AndroidDetails;
+
     // prevent derived classes' implementations to call through
     [[nodiscard]] SwapChain* createSwapChain(void* nativeWindow, uint64_t flags) override;
     [[nodiscard]] SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) override;
     void destroySwapChain(SwapChain* swapChain) noexcept override;
 
+    bool isProducerThrottlingControlSupported() const;
+
+    int32_t setProducerThrottlingEnabled(EGLNativeWindowType nativeWindow, bool enabled) const;
+
     struct InitializeJvmForPerformanceManagerIfNeeded {
         InitializeJvmForPerformanceManagerIfNeeded();
     };
@@ -195,18 +190,14 @@ private:
 
     int mOSVersion;
     ExternalStreamManagerAndroid& mExternalStreamManager;
+    AndroidDetails& mAndroidDetails;
     InitializeJvmForPerformanceManagerIfNeeded const mInitializeJvmForPerformanceManagerIfNeeded;
     utils::PerformanceHintManager mPerformanceHintManager;
     utils::PerformanceHintManager::Session mPerformanceHintSession;
-    SwapChainEGLAndroid* mCurrentDrawSwapChain{};
-
     using clock = std::chrono::high_resolution_clock;
     clock::time_point mStartTimeOfActualWork;
-
-    int32_t (*ANativeWindow_setProducerThrottlingEnabled)(ANativeWindow* window, bool enabled) = nullptr;
-    int32_t (*ANativeWindow_isProducerThrottlingEnabled)(ANativeWindow* window, bool* outEnabled) = nullptr;
+    SwapChainEGLAndroid* mCurrentDrawSwapChain{};
     bool mAssertNativeWindowIsValid = false;
-    bool mHasProducerThrottlingControl = false;
 };
 
 } // namespace filament::backend

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

@@ -437,22 +437,19 @@ protected:
         std::shared_ptr<VulkanCmdFence> fenceStatus;
     };
 
-    virtual ExtensionSet getSwapchainInstanceExtensions() const;
-
     using SurfaceBundle = std::tuple<VkSurfaceKHR, VkExtent2D>;
+    virtual ExtensionSet getSwapchainInstanceExtensions() const = 0;
     virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
-            uint64_t flags) const noexcept;
+            uint64_t flags) const noexcept = 0;
 
     virtual VkExternalFenceHandleTypeFlagBits getFenceExportFlags() const noexcept;
 
+    /**
+     * Query if transient attachments are supported by the backend.
+     */
+    bool isTransientAttachmentSupported() const noexcept;
+
 private:
-    // Platform dependent helper methods
-    static ExtensionSet getSwapchainInstanceExtensionsImpl();
-
-    // Platform dependent helper methods
-    static SurfaceBundle createVkSurfaceKHRImpl(void* nativeWindow, VkInstance instance,
-            uint64_t flags) noexcept;
-
     friend struct VulkanPlatformPrivate;
 };
 

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

@@ -17,14 +17,18 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKAN_PLATFORM_ANDROID_H
 #define TNT_FILAMENT_BACKEND_PLATFORMS_VULKAN_PLATFORM_ANDROID_H
 
+#include "AndroidNdk.h"
+
 #include <backend/DriverEnums.h>
 #include <backend/platforms/VulkanPlatform.h>
 
+#include <utils/compiler.h>
+
 #include <android/hardware_buffer.h>
 
 namespace filament::backend {
 
-class VulkanPlatformAndroid : public VulkanPlatform {
+class VulkanPlatformAndroid : public VulkanPlatform, public AndroidNdk {
 public:
     ExternalImageHandle UTILS_PUBLIC createExternalImage(AHardwareBuffer const* buffer,
             bool sRGB) noexcept;
@@ -36,13 +40,17 @@ public:
         TextureUsage usage;  // Texture usage flags
     };
 
+    VulkanPlatformAndroid();
+
+    ~VulkanPlatformAndroid() noexcept override;
+
     ExternalImageDescAndroid UTILS_PUBLIC getExternalImageDesc(
             ExternalImageHandleRef externalImage) const noexcept;
 
-    virtual ExternalImageMetadata extractExternalImageMetadata(
+    ExternalImageMetadata extractExternalImageMetadata(
             ExternalImageHandleRef image) const override;
 
-    virtual ImageData createVkImageFromExternal(ExternalImageHandleRef image) const override;
+    ImageData createVkImageFromExternal(ExternalImageHandleRef image) const override;
 
     /**
      * Converts a sync to an external file descriptor, if possible. Accepts an
@@ -53,25 +61,49 @@ public:
      * @return `true` on success, `false` on failure. The default implementation
      *         returns `false`.
      */
-    bool convertSyncToFd(Platform::Sync* sync, int* fd) const noexcept;
+    bool convertSyncToFd(Sync* sync, int* fd) const noexcept;
+
+    int getOSVersion() const noexcept override;
+
+    void terminate() override;
+
+    Driver* createDriver(void* sharedContext,
+        DriverConfig const& driverConfig) override;
+
+
+    bool isCompositorTimingSupported() const noexcept override;
+
+    bool queryCompositorTiming(SwapChain const* swapchain,
+            CompositorTiming* outCompositorTiming) const noexcept override;
+
+    bool setPresentFrameId(SwapChain const* swapchain, uint64_t frameId) noexcept override;
+
+    bool queryFrameTimestamps(SwapChain const* swapchain, uint64_t frameId,
+            FrameTimestamps* outFrameTimestamps) const noexcept override;
+
 
 protected:
-    virtual ExtensionSet getSwapchainInstanceExtensions() const override;
+    ExtensionSet getSwapchainInstanceExtensions() const override;
 
-    using SurfaceBundle = VulkanPlatform::SurfaceBundle;
-    virtual SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
+    using SurfaceBundle = SurfaceBundle;
+    SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
             uint64_t flags) const noexcept override;
 
-    virtual VkExternalFenceHandleTypeFlagBits getFenceExportFlags() const noexcept override;
+    VkExternalFenceHandleTypeFlagBits getFenceExportFlags() const noexcept override;
 
 private:
-    struct ExternalImageVulkanAndroid : public Platform::ExternalImage {
+    struct AndroidDetails;
+
+    struct ExternalImageVulkanAndroid : public ExternalImage {
         AHardwareBuffer* aHardwareBuffer = nullptr;
         bool sRGB = false;
 
     protected:
         ~ExternalImageVulkanAndroid() override;
     };
+
+    AndroidDetails& mAndroidDetails;
+    int mOSVersion{};
 };
 
 }// namespace filament::backend

filament/backend/include/backend/platforms/VulkanPlatformApple.h

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMAPPLE_H
+#define TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMAPPLE_H
+
+#include <backend/platforms/VulkanPlatform.h>
+
+namespace filament::backend {
+
+class VulkanPlatformApple : public VulkanPlatform {
+protected:
+    ExtensionSet getSwapchainInstanceExtensions() const override;
+    SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
+            uint64_t flags) const noexcept override;
+};
+
+} // namespace filament::backend
+
+#endif // TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMAPPLE_H

filament/backend/include/backend/platforms/VulkanPlatformLinux.h

@@ -0,0 +1,33 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMLINUX_H
+#define TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMLINUX_H
+
+#include <backend/platforms/VulkanPlatform.h>
+
+namespace filament::backend {
+
+class VulkanPlatformLinux : public VulkanPlatform {
+protected:
+    ExtensionSet getSwapchainInstanceExtensions() const override;
+    SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
+            uint64_t flags) const noexcept override;
+};
+
+} // namespace filament::backend
+
+#endif // TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMLINUX_H

filament/backend/include/backend/platforms/VulkanPlatformWindows.h

@@ -0,0 +1,33 @@
+/*
+ * Copyright (C) 2023 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMWINDOWS_H
+#define TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMWINDOWS_H
+
+#include <backend/platforms/VulkanPlatform.h>
+
+namespace filament::backend {
+
+class VulkanPlatformWindows : public VulkanPlatform {
+protected:
+    ExtensionSet getSwapchainInstanceExtensions() const override;
+    SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
+            uint64_t flags) const noexcept override;
+};
+
+} // namespace filament::backend
+
+#endif // TNT_FILAMENT_BACKEND_PLATFORMS_VULKANPLATFORMWINDOWS_H

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

@@ -22,7 +22,6 @@
 #include "private/backend/Driver.h"
 
 #include <backend/BufferDescriptor.h>
-#include <backend/BufferObjectStreamDescriptor.h>
 #include <backend/CallbackHandler.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>

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

@@ -51,7 +51,6 @@
 namespace filament::backend {
 
 class BufferDescriptor;
-class BufferObjectStreamDescriptor;
 class CallbackHandler;
 class PixelBufferDescriptor;
 class Program;

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

@@ -337,6 +337,7 @@ DECL_DRIVER_API_SYNCHRONOUS_N(int64_t, getStreamTimestamp, backend::StreamHandle
 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, fenceCancel, backend::FenceHandle, fh)
 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)
@@ -367,6 +368,9 @@ DECL_DRIVER_API_SYNCHRONOUS_N(backend::TimerQueryResult, getTimerQueryValue, bac
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isWorkaroundNeeded, backend::Workaround, workaround)
 DECL_DRIVER_API_SYNCHRONOUS_0(backend::FeatureLevel, getFeatureLevel)
 DECL_DRIVER_API_SYNCHRONOUS_0(size_t, getUniformBufferOffsetAlignment)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isCompositorTimingSupported)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, queryFrameTimestamps, backend::SwapChainHandle, swapChain, uint64_t, frameId, backend::FrameTimestamps*, outFrameTimestamps)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, queryCompositorTiming, backend::SwapChainHandle, swapChain, backend::CompositorTiming*, outCompositorTiming)
 
 /*
  * Updating driver objects
@@ -388,10 +392,6 @@ DECL_DRIVER_API_N(updateBufferObject,
         backend::BufferDescriptor&&, data,
         uint32_t, byteOffset)
 
-DECL_DRIVER_API_N(registerBufferObjectStreams,
-        backend::BufferObjectHandle, boh,
-        backend::BufferObjectStreamDescriptor&&, streams)
-
 DECL_DRIVER_API_N(updateBufferObjectUnsynchronized,
         backend::BufferObjectHandle, boh,
         backend::BufferDescriptor&&, data,

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

@@ -169,10 +169,11 @@ public:
      * Destroy the object D at Handle<B> and frees Handle<B>
      * e.g.:
      *      Handle<HwTexture> h = ...;
-     *      deallocate(h);
+     *      deallocate<GLTexture>(h);
      */
-    template<typename D>
-    void deallocate(Handle<D>& handle) noexcept {
+    template<typename D, typename B,
+            typename = std::enable_if_t<std::is_base_of_v<B, D>, D>>
+    void deallocate(Handle<B>& handle) noexcept {
         D const* d = handle_cast<const D*>(handle);
         deallocate(handle, d);
     }
@@ -208,7 +209,7 @@ public:
                 HandleBase::HandleId const index = (handle.getId() & HANDLE_INDEX_MASK);
                 // if we've already handed out this handle index before, it's definitely a
                 // use-after-free, otherwise it's probably just a corrupted handle
-                if (index < mId) {
+                if (index < mId.load(std::memory_order_relaxed)) {
                     FILAMENT_CHECK_POSTCONDITION(p != nullptr)
                             << "use-after-free of heap Handle with id=" << handle.getId()
                             << ", tag=" << getHandleTag(handle.getId()).c_str_safe();

filament/backend/src/AndroidFrameCallback.cpp

@@ -0,0 +1,139 @@
+/*
+ * 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.
+ */
+
+#include "AndroidFrameCallback.h"
+
+#include <android/choreographer.h>
+#include <android/looper.h>
+
+#include <private/utils/Tracing.h>
+
+#include <utils/Panic.h>
+#include <utils/debug.h>
+#include <utils/JobSystem.h>
+
+#include <atomic>
+#include <cstddef>
+#include <cstdint>
+#include <mutex>
+
+namespace filament::backend {
+
+using namespace utils;
+
+AndroidFrameCallback::AndroidFrameCallback() = default;
+
+AndroidFrameCallback::~AndroidFrameCallback() noexcept {
+    assert_invariant(!mLooperThread.joinable());
+    assert_invariant(mLooper == nullptr);
+}
+
+void AndroidFrameCallback::init() {
+    if (__builtin_available(android 33, *)) {
+        FILAMENT_CHECK_PRECONDITION(!mLooperThread.joinable()) << "init() already called";
+
+        // start the looper thread for our choreographer callbacks
+        mLooperThread = std::thread([this] {
+            // create the looper for this thread
+            mLooper = ALooper_prepare(0);
+            // acquire a reference, so we can use it from our main thread
+            ALooper_acquire(mLooper);
+            // set thread name
+            JobSystem::setThreadName("Filament Choreographer");
+            // set priority
+            JobSystem::setThreadPriority(JobSystem::Priority::DISPLAY);
+            // start the choreographer callbacks
+            if (__builtin_available(android 33, *)) {
+                mChoreographer = AChoreographer_getInstance();
+                // request our first callback for the next frame
+                AChoreographer_postVsyncCallback(mChoreographer, &vsyncCallback, this);
+            }
+            // signal we're ready to run and choreographer and looper are initialized
+            mInitBarrier.latch();
+            // our main loop just sits there to handle events
+            while (true) {
+                int const result = ALooper_pollOnce(-1, nullptr, nullptr, nullptr);
+                if (result == ALOOPER_POLL_ERROR || mExitRequested.
+                    load(std::memory_order_relaxed)) {
+                    return; // exit the loop
+                }
+            }
+        });
+
+        // wait for the thread and looper to be created and ready to run
+        mInitBarrier.await();
+    }
+}
+
+void AndroidFrameCallback::terminate() {
+    if (__builtin_available(android 33, *)) {
+        // the thread wouldn't be joinable if terminate() is called twice, or init() is not called.
+        if (mLooperThread.joinable()) {
+            // request exit
+            mExitRequested.store(true, std::memory_order_relaxed);
+            // wake the looper right away
+            ALooper_wake(mLooper);
+            // release our reference to the looper
+            ALooper_release(mLooper);
+            mLooper = nullptr;
+            // and make sure to wait for the thread to terminate
+            mLooperThread.join();
+        }
+    }
+}
+
+bool AndroidFrameCallback::isSupported() noexcept {
+    if (__builtin_available(android 33, *)) {
+        return true;
+    }
+    return false;
+}
+
+AndroidFrameCallback::Timeline AndroidFrameCallback::getPreferredTimeline() const noexcept {
+    std::lock_guard const l(mLock);
+    return mPreferredTimeline;
+}
+
+void AndroidFrameCallback::vsyncCallback(const AChoreographerFrameCallbackData* callbackData) {
+    if (__builtin_available(android 33, *)) {
+        FILAMENT_TRACING_CALL(FILAMENT_TRACING_CATEGORY_FILAMENT);
+
+        // request the next frame callback
+        AChoreographer_postVsyncCallback(mChoreographer, &vsyncCallback, this);
+
+        int64_t const frameTime = AChoreographerFrameCallbackData_getFrameTimeNanos(callbackData);
+
+        size_t const preferredIndex =
+                AChoreographerFrameCallbackData_getPreferredFrameTimelineIndex(callbackData);
+
+        int64_t const expectedPresentTime =
+                AChoreographerFrameCallbackData_getFrameTimelineExpectedPresentationTimeNanos(
+                        callbackData, preferredIndex);
+
+        int64_t const frameTimelineDeadline =
+                AChoreographerFrameCallbackData_getFrameTimelineDeadlineNanos(
+                        callbackData, preferredIndex);
+
+        std::lock_guard const l(mLock);
+        mPreferredTimeline = {
+            .frameTime = frameTime,
+            .expectedPresentTime = expectedPresentTime,
+            .frameTimelineDeadline = frameTimelineDeadline
+        };
+    }
+}
+
+}

filament/backend/src/AndroidFrameCallback.h

@@ -0,0 +1,82 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_ANDROIDFRAMECALLBACK_H
+#define TNT_FILAMENT_BACKEND_ANDROIDFRAMECALLBACK_H
+
+#include <android/choreographer.h>
+#include <android/looper.h>
+
+#include <utils/CountDownLatch.h>
+
+#include <atomic>
+#include <cstdint>
+#include <mutex>
+#include <thread>
+
+namespace filament::backend {
+
+/*
+ * AndroidFrameCallback uses a dedicated thread running a Looper and uses
+ * Choreographer to receive the FrameCallbackData.
+ *
+ */
+class AndroidFrameCallback {
+public:
+    struct Timeline {
+        using timepoint_ns = int64_t;
+        static constexpr timepoint_ns INVALID = -1;
+        timepoint_ns frameTime{ INVALID };
+        timepoint_ns expectedPresentTime{ INVALID };
+        timepoint_ns frameTimelineDeadline{ INVALID };
+    };
+
+    AndroidFrameCallback();
+
+    ~AndroidFrameCallback() noexcept;
+
+    AndroidFrameCallback(AndroidFrameCallback const&) = delete;
+    AndroidFrameCallback& operator=(AndroidFrameCallback const&) = delete;
+
+    void init();
+    void terminate();
+
+    static  bool isSupported() noexcept;
+
+    Timeline getPreferredTimeline() const noexcept;
+
+private:
+    // looper
+    std::thread mLooperThread;
+    mutable utils::CountDownLatch mInitBarrier{ 1 };
+    ALooper* mLooper = nullptr;
+    std::atomic_bool mExitRequested{ false };
+
+    // choreographer
+    AChoreographer* mChoreographer{};
+
+    void vsyncCallback(const AChoreographerFrameCallbackData* callbackData);
+    static void vsyncCallback(const AChoreographerFrameCallbackData* callbackData, void* data) {
+        static_cast<AndroidFrameCallback*>(data)->vsyncCallback(callbackData);
+    }
+
+    mutable std::mutex mLock;
+    Timeline mPreferredTimeline{};
+};
+
+} // namespace filament::backend
+
+#endif //TNT_FILAMENT_BACKEND_ANDROIDFRAMECALLBACK_H

filament/backend/src/AndroidNativeWindow.cpp

@@ -16,22 +16,31 @@
 
 #include "AndroidNativeWindow.h"
 
+#include <android/api-level.h>
 #include <android/native_window.h>
 
 #include <utils/compiler.h>
+#include <utils/Logger.h>
 
 #include <cstdint>
 #include <cerrno>
 #include <utility>
 
+#include <dlfcn.h>
+
 namespace filament::backend {
 
 std::pair<int, bool> NativeWindow::isValid(ANativeWindow* const anw) noexcept {
+#if __ANDROID_API__ >= 26
+    // libnativewindow.so is not available before API level 26, this means we can't call
+    // any method above 25 (even protected by __builtin_available()).
     if (__builtin_available(android 28, *)) {
         // this a proxy for is_valid()
         auto const result = ANativeWindow_getBuffersDataSpace(anw);
         return { result, result >= 0 };
     }
+#endif
+
     // fallback on using private APIs
     NativeWindow const* pWindow = reinterpret_cast<NativeWindow const*>(anw);
     if (UTILS_LIKELY(pWindow->query)) {
@@ -52,6 +61,16 @@ int NativeWindow::enableFrameTimestamps(ANativeWindow* anw, bool enable) {
     return pWindow->perform(anw, ENABLE_FRAME_TIMESTAMPS, enable);
 }
 
+int NativeWindow::frameTimestampsSupportsPresent(ANativeWindow* anw, bool* outSupportsPresent) {
+    NativeWindow const* pWindow = reinterpret_cast<NativeWindow const*>(anw);
+    int value = 0;
+    bool const success = pWindow->perform(anw, FRAME_TIMESTAMPS_SUPPORTS_PRESENT, &value);
+    if (success) {
+        *outSupportsPresent = bool(value);
+    }
+    return success;
+}
+
 int NativeWindow::getCompositorTiming(ANativeWindow* anw,
         int64_t* compositeDeadline, int64_t* compositeInterval,
         int64_t* compositeToPresentLatency) {
@@ -75,4 +94,48 @@ int NativeWindow::getFrameTimestamps(ANativeWindow* anw,
             outDequeueReadyTime, outReleaseTime);
 }
 
+AndroidProducerThrottling::AndroidProducerThrottling() {
+    // note: we don't need to dlclose() mNativeWindowLib here, because the library will be cleaned
+    // when the process ends and dlopen() are ref-counted. dlclose() NDK documentation documents
+    // not to call dlclose().
+
+    // libnativewindow.so is not available before API level 26, this means we can't call
+    // any method above 25 (even protected by __builtin_available()).
+
+    void* nativeWindowLibHandle = dlopen("libnativewindow.so", RTLD_LOCAL | RTLD_NOW);
+    if (nativeWindowLibHandle) {
+        mSetProducerThrottlingEnabled =
+                (int32_t(*)(ANativeWindow*, bool)) dlsym(nativeWindowLibHandle,
+                        "ANativeWindow_setProducerThrottlingEnabled");
+
+        mIsProducerThrottlingEnabled =
+                (int32_t(*)(ANativeWindow*, bool*)) dlsym(nativeWindowLibHandle,
+                        "ANativeWindow_isProducerThrottlingEnabled");
+
+        if (mSetProducerThrottlingEnabled && mIsProducerThrottlingEnabled) {
+            LOG(INFO) << "Producer Throttling API available";
+        }
+    }
+}
+
+int32_t AndroidProducerThrottling::setProducerThrottlingEnabled(
+        ANativeWindow* window, bool enabled) const {
+    if (mSetProducerThrottlingEnabled) {
+        return mSetProducerThrottlingEnabled(window, enabled);
+    }
+    return -1;
+}
+
+int32_t AndroidProducerThrottling::isProducerThrottlingEnabled(
+        ANativeWindow* window, bool* outEnabled) const {
+    if (mIsProducerThrottlingEnabled) {
+        return mIsProducerThrottlingEnabled(window, outEnabled);
+    }
+    return -1;
+}
+
+bool AndroidProducerThrottling::isSupported() const noexcept {
+    return mSetProducerThrottlingEnabled && mIsProducerThrottlingEnabled;
+}
+
 } // namespace filament::backend

filament/backend/src/AndroidNativeWindow.h

@@ -32,12 +32,18 @@ struct NativeWindow {
     // is valid query enum value
     enum {
         IS_VALID                = 17,
+        FRAME_TIMESTAMPS_SUPPORTS_PRESENT = 18,
         GET_NEXT_FRAME_ID       = 24,
         ENABLE_FRAME_TIMESTAMPS = 25,
         GET_COMPOSITOR_TIMING   = 26,
         GET_FRAME_TIMESTAMPS    = 27,
     };
+
+#if defined(__LP64__)
     uint64_t pad[18];
+#else
+    uint32_t pad[21];
+#endif
     int (*query)(ANativeWindow const*, int, int*);
     int (*perform)(ANativeWindow*, int, ...);
 
@@ -46,6 +52,7 @@ struct NativeWindow {
 
     static int getNextFrameId(ANativeWindow* anw, uint64_t* frameId);
     static int enableFrameTimestamps(ANativeWindow* anw, bool enable);
+    static int frameTimestampsSupportsPresent(ANativeWindow* anw, bool* outSupportsPresent);
     static int getCompositorTiming(ANativeWindow* anw,
             int64_t* compositeDeadline, int64_t* compositeInterval,
             int64_t* compositeToPresentLatency);
@@ -58,6 +65,17 @@ struct NativeWindow {
             int64_t* outReleaseTime);
 };
 
+struct AndroidProducerThrottling {
+    AndroidProducerThrottling();
+    int32_t setProducerThrottlingEnabled(ANativeWindow* window, bool enabled) const;
+    int32_t isProducerThrottlingEnabled(ANativeWindow* window, bool* outEnabled) const;
+    bool isSupported() const noexcept;
+private:
+    int32_t (*mSetProducerThrottlingEnabled)(ANativeWindow* window, bool enabled) = nullptr;
+    int32_t (*mIsProducerThrottlingEnabled)(ANativeWindow* window, bool* outEnabled) = nullptr;
+};
+
+
 } // namespace filament::backend
 
 #endif //FILAMENT_BACKEND_ANDROIDNATIVEWINDOW_H

filament/backend/src/AndroidNdk.cpp

@@ -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.
+ */
+
+#include <backend/platforms/AndroidNdk.h>
+
+#include <android/hardware_buffer.h>
+
+#include <utils/compiler.h>
+
+#include <mutex>
+
+#include <dlfcn.h>
+
+namespace filament::backend {
+
+UTILS_UNUSED
+static std::once_flag sInitOnce{};
+
+template <typename T>
+UTILS_UNUSED
+static void loadSymbol(void* handle, const char* symbol, T& pfn) {
+    pfn = T(dlsym(handle, symbol));
+}
+
+#if FILAMENT_USE_DLSYM(26)
+AndroidNdk::Ndk AndroidNdk::ndk{};
+#endif
+
+AndroidNdk::AndroidNdk() {
+#if FILAMENT_USE_DLSYM(26)
+    std::call_once(sInitOnce, [] {
+        // note: we don't need to dlclose() mNativeWindowLib here, because the library will be cleaned
+        // when the process ends and dlopen() are ref-counted. dlclose() NDK documentation documents
+        // not to call dlclose().
+        if (__builtin_available(android 26, *)) {
+            void* h = dlopen("libnativewindow.so", RTLD_LOCAL | RTLD_NOW);
+            if (h) {
+                loadSymbol(h, "AHardwareBuffer_acquire", ndk.AHardwareBuffer_acquire);
+                loadSymbol(h, "AHardwareBuffer_release", ndk.AHardwareBuffer_release);
+                loadSymbol(h, "AHardwareBuffer_describe", ndk.AHardwareBuffer_describe);
+            }
+        }
+    });
+#endif
+}
+
+} // filament::backend

filament/backend/src/AndroidSwapChainHelper.cpp

@@ -19,6 +19,9 @@
 
 #include <android/native_window.h>
 
+#include <utils/compiler.h>
+#include <utils/Logger.h>
+
 #include <cstddef>
 #include <cstdint>
 #include <limits>
@@ -31,31 +34,39 @@ AndroidSwapChainHelper::AndroidSwapChainHelper() = default;
 AndroidSwapChainHelper::~AndroidSwapChainHelper() noexcept = default;
 
 bool AndroidSwapChainHelper::setPresentFrameId(
-        ANativeWindow* anw, uint64_t frameId) const noexcept {
+        ANativeWindow* anw, uint64_t const frameId) const noexcept {
     uint64_t sysFrameId{};
     int const status = NativeWindow::getNextFrameId(anw, &sysFrameId);
     if (status == 0) {
         std::lock_guard const lock(mLock);
-        auto const pos = mFrameIdToSystemFrameId.find(frameId);
-        if (pos != mFrameIdToSystemFrameId.end() && pos->second != sysFrameId) {
-            // we're trying to associate the same frame id to a different frame!
-            return false;
+        // frameIds must be strictly monotonic, if that's not the case (i.e. the new frameId is
+        // less or equal to the last one in the map), we have to clear the map, because the
+        // map's find() assume sorted keys.
+        // This case can happen if two different filament::Renderer are used with the same
+        // ANativeWindow (the Renderer would have different frameIds). This is expected to
+        // be a rare case.
+        if (UTILS_UNLIKELY(!mFrameIdToSystemFrameId.empty() &&
+                frameId <= mFrameIdToSystemFrameId.back().first)) {
+            // this log is expected to happen very rarely
+            DLOG(INFO) << "clearing frame history anw=" << anw
+                    << ", frameId=" << frameId
+                    << ", previous=" << mFrameIdToSystemFrameId.back().first
+                    << ", sysFrameId=" << sysFrameId;
+            // clear the frame history
+            mFrameIdToSystemFrameId.clear();
         }
-        // make space by destroying the oldest entry
-        if (mFrameIdToSystemFrameId.size() >= MAX_HISTORY_SIZE) {
-            mFrameIdToSystemFrameId.erase(mFrameIdToSystemFrameId.begin());
-        }
-        mFrameIdToSystemFrameId.insert(mFrameIdToSystemFrameId.end(), { frameId, sysFrameId });
+
+        // oldest entry is removed
+        mFrameIdToSystemFrameId.insert(frameId, sysFrameId);
         return true;
     }
     return false;
 }
 
-uint64_t AndroidSwapChainHelper::getFrameId(uint64_t frameId) const noexcept {
+uint64_t AndroidSwapChainHelper::getFrameId(uint64_t const frameId) const noexcept {
     std::lock_guard const lock(mLock);
-    auto pos = mFrameIdToSystemFrameId.find(frameId);
-    if (pos != mFrameIdToSystemFrameId.end()) {
-        return pos->second;
+    if (auto const* const pos = mFrameIdToSystemFrameId.find(frameId)) {
+        return *pos;
     }
     return std::numeric_limits<uint64_t>::max();
 }

filament/backend/src/AndroidSwapChainHelper.h

@@ -18,6 +18,7 @@
 #define TNT_FILAMENT_BACKEND_ANDROIDSWAPCHAINHELPER_H
 
 #include <utils/Mutex.h>
+#include <utils/MonotonicRingMap.h>
 
 #include <android/native_window.h>
 
@@ -39,7 +40,7 @@ struct AndroidSwapChainHelper {
 private:
     static constexpr size_t MAX_HISTORY_SIZE = 32;
     mutable utils::Mutex mLock; // very low-contention lock
-    mutable std::map<uint64_t, uint64_t> mFrameIdToSystemFrameId{};
+    mutable utils::MonotonicRingMap<MAX_HISTORY_SIZE, uint64_t, uint64_t> mFrameIdToSystemFrameId{};
 };
 
 }

filament/backend/src/BackendUtilsAndroid.cpp

@@ -25,8 +25,11 @@ TextureFormat mapToFilamentFormat(unsigned int format, bool isSrgbTransfer) noex
         switch (format) {
             case AHARDWAREBUFFER_FORMAT_R8G8B8_UNORM:
                 return TextureFormat::SRGB8;
-            default:
+            case AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM:
+            case AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM:
                 return TextureFormat::SRGB8_A8;
+            default:
+                break;
         }
     }
     switch (format) {

filament/backend/src/HandleAllocator.cpp

@@ -108,7 +108,7 @@ template <size_t P0, size_t P1, size_t P2>
 UTILS_NOINLINE
 void* HandleAllocator<P0, P1, P2>::handleToPointerSlow(HandleBase::HandleId id) const noexcept {
     auto& overflowMap = mOverflowMap;
-    std::lock_guard lock(mLock);
+    std::lock_guard const lock(mLock);
     auto pos = overflowMap.find(id);
     if (pos != overflowMap.end()) {
         return pos.value();
@@ -119,14 +119,15 @@ void* HandleAllocator<P0, P1, P2>::handleToPointerSlow(HandleBase::HandleId id)
 template <size_t P0, size_t P1, size_t P2>
 HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size) {
     void* p = ::malloc(size);
-    std::unique_lock lock(mLock);
 
-    HandleBase::HandleId id = (++mId) | HANDLE_HEAP_FLAG;
-
-    FILAMENT_CHECK_POSTCONDITION(mId < HANDLE_HEAP_FLAG) <<
+    auto const nextId = mId.fetch_add(1, std::memory_order_relaxed) + 1;
+    FILAMENT_CHECK_POSTCONDITION(nextId < HANDLE_HEAP_FLAG) <<
             "No more Handle ids available! This can happen if HandleAllocator arena has been full"
             " for a while. Please increase FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB";
 
+    HandleBase::HandleId id = nextId | HANDLE_HEAP_FLAG;
+
+    std::unique_lock lock(mLock);
     mOverflowMap.emplace(id, p);
     lock.unlock();
 

filament/backend/src/Platform.cpp

@@ -139,42 +139,73 @@ bool Platform::queryFrameTimestamps(SwapChain const*, uint64_t, FrameTimestamps*
 }
 
 void Platform::setBlobFunc(InsertBlobFunc&& insertBlob, RetrieveBlobFunc&& retrieveBlob) noexcept {
-    mInsertBlob = std::move(insertBlob);
-    mRetrieveBlob = std::move(retrieveBlob);
+    std::lock_guard<decltype(mMutex)> lock(mMutex);
+    mInsertBlob = std::make_shared<InsertBlobFunc>(std::move(insertBlob));
+    mRetrieveBlob = std::make_shared<RetrieveBlobFunc>(std::move(retrieveBlob));
 }
 
 bool Platform::hasInsertBlobFunc() const noexcept {
-    return bool(mInsertBlob);
+    std::lock_guard<decltype(mMutex)> lock(mMutex);
+    return mInsertBlob && bool(*mInsertBlob);
 }
 
 bool Platform::hasRetrieveBlobFunc() const noexcept {
-    return bool(mRetrieveBlob);
+    std::lock_guard<decltype(mMutex)> lock(mMutex);
+    return mRetrieveBlob && bool(*mRetrieveBlob);
 }
 
 void Platform::insertBlob(void const* key, size_t keySize, void const* value, size_t valueSize) {
-    if (mInsertBlob) {
-        mInsertBlob(key, keySize, value, valueSize);
+    std::shared_ptr<InsertBlobFunc> callback;
+    {
+        std::unique_lock<decltype(mMutex)> lock(mMutex);
+        callback = mInsertBlob;
+    }
+    if (callback) {
+        (*callback)(key, keySize, value, valueSize);
     }
 }
 
 size_t Platform::retrieveBlob(void const* key, size_t keySize, void* value, size_t valueSize) {
-    if (mRetrieveBlob) {
-        return mRetrieveBlob(key, keySize, value, valueSize);
+    std::shared_ptr<RetrieveBlobFunc> callback;
+    {
+        std::unique_lock<decltype(mMutex)> lock(mMutex);
+        callback = mRetrieveBlob;
+    }
+    if (callback) {
+        return (*callback)(key, keySize, value, valueSize);
     }
     return 0;
 }
 
 void Platform::setDebugUpdateStatFunc(DebugUpdateStatFunc&& debugUpdateStat) noexcept {
-    mDebugUpdateStat = std::move(debugUpdateStat);
+    std::lock_guard<decltype(mMutex)> lock(mMutex);
+    mDebugUpdateStat = std::make_shared<DebugUpdateStatFunc>(std::move(debugUpdateStat));
 }
 
 bool Platform::hasDebugUpdateStatFunc() const noexcept {
-    return bool(mDebugUpdateStat);
+    std::lock_guard<decltype(mMutex)> lock(mMutex);
+    return mDebugUpdateStat && bool(*mDebugUpdateStat);
 }
 
-void Platform::debugUpdateStat(const char* key, uint64_t value) {
-    if (mDebugUpdateStat) {
-        mDebugUpdateStat(key, value);
+void Platform::debugUpdateStat(const char* key, uint64_t intValue) {
+    std::shared_ptr<DebugUpdateStatFunc> callback;
+    {
+        std::unique_lock<decltype(mMutex)> lock(mMutex);
+        callback = mDebugUpdateStat;
+    }
+    if (callback) {
+        (*callback)(key, intValue, "");
+    }
+}
+
+void Platform::debugUpdateStat(const char* key, utils::CString stringValue) {
+    std::shared_ptr<DebugUpdateStatFunc> callback;
+    {
+        std::unique_lock<decltype(mMutex)> lock(mMutex);
+        callback = mDebugUpdateStat;
+    }
+    if (callback) {
+        (*callback)(key, 0, stringValue);
     }
 }
 

filament/backend/src/PlatformFactory.cpp

@@ -67,8 +67,12 @@
 #if defined(FILAMENT_DRIVER_SUPPORTS_VULKAN)
     #if defined(__ANDROID__)
         #include "backend/platforms/VulkanPlatformAndroid.h"
-    #else
-        #include "backend/platforms/VulkanPlatform.h"
+    #elif defined(__APPLE__)
+        #include "backend/platforms/VulkanPlatformApple.h"
+    #elif defined(__linux__)
+        #include "backend/platforms/VulkanPlatformLinux.h"
+    #elif defined(WIN32)
+        #include "backend/platforms/VulkanPlatformWindows.h"
     #endif
 #endif
 
@@ -117,8 +121,14 @@ Platform* PlatformFactory::create(Backend* backend) noexcept {
         #if defined(FILAMENT_DRIVER_SUPPORTS_VULKAN)
             #if defined(__ANDROID__)
                 return new VulkanPlatformAndroid();
+            #elif defined(__APPLE__)
+                return new VulkanPlatformApple();
+            #elif defined(__linux__)
+                return new VulkanPlatformLinux();
+            #elif defined(WIN32)
+                return new VulkanPlatformWindows();
             #else
-                return new VulkanPlatform();
+                return nullptr;
             #endif
         #else
             return nullptr;

filament/backend/src/metal/MetalBuffer.h

@@ -165,7 +165,7 @@ public:
          size_t size, bool forceGpuBuffer = false);
     ~MetalBuffer();
 
-    [[nodiscard]] bool wasAllocationSuccessful() const noexcept { return mBuffer || mCpuBuffer; }
+    [[nodiscard]] bool wasAllocationSuccessful() const noexcept { return mBuffer; }
 
     MetalBuffer(const MetalBuffer& rhs) = delete;
     MetalBuffer& operator=(const MetalBuffer& rhs) = delete;
@@ -185,14 +185,12 @@ public:
      * Denotes that this buffer is used for a draw call ensuring that its allocation remains valid
      * until the end of the current frame.
      *
-     * @return The MTLBuffer representing the current state of the buffer to bind, or nil if there
-     * is no device allocation.
+     * @return The MTLBuffer representing the current state of the buffer to bind, it never returns
+     * nil.
      *
      */
     id<MTLBuffer> getGpuBufferForDraw() noexcept;
 
-    void* getCpuBuffer() const noexcept { return mCpuBuffer; }
-
     void setLabel(const utils::ImmutableCString& label) {
 #if FILAMENT_METAL_DEBUG_LABELS
         if (label.empty()) {
@@ -235,7 +233,6 @@ private:
     UploadStrategy mUploadStrategy;
     TrackedMetalBuffer mBuffer;
     size_t mBufferSize = 0;
-    void* mCpuBuffer = nullptr;
     MetalContext& mContext;
 };
 

filament/backend/src/metal/MetalBuffer.mm

@@ -39,34 +39,30 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType,
         mUploadStrategy = UploadStrategy::POOL;
     }
 
-    // If the buffer is less than 4K in size and is updated frequently, we don't use an explicit
-    // buffer. Instead, we use immediate command encoder methods like setVertexBytes:length:atIndex:.
-    // This won't work for SSBOs, since they are read/write.
+    MTLResourceOptions options = MTLResourceStorageModePrivate;
 
-    /*
-    if (size <= 4 * 1024 && bindingType != BufferObjectBinding::SHADER_STORAGE &&
-            usage == BufferUsage::DYNAMIC && !forceGpuBuffer) {
-        mBuffer = nil;
-        mCpuBuffer = malloc(size);
-        return;
+    // The buffer will be memory mapped for write operations.
+    if (any(usage & BufferUsage::SHARED_WRITE_BIT)) {
+#if defined(FILAMENT_IOS) || defined(__arm64__) || defined(__aarch64__)
+        // iOS and Apple Silicon devices use UMA (Unified Memory Architecture), so we use Shared memory.
+        options = MTLResourceStorageModeShared;
+#else
+        // Intel Macs require Managed memory for CPU/GPU synchronization.
+        options = MTLResourceStorageModeManaged;
+#endif
     }
-    */
 
-    // Otherwise, we allocate a private GPU buffer.
     {
         ScopedAllocationTimer timer("generic");
-        mBuffer = { [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate],
+        mBuffer = { [context.device newBufferWithLength:size options:options],
             TrackedMetalBuffer::Type::GENERIC };
     }
+
     // mBuffer might fail to be allocated. Clients can check for this by calling
     // wasAllocationSuccessful().
 }
 
-MetalBuffer::~MetalBuffer() {
-    if (mCpuBuffer) {
-        free(mCpuBuffer);
-    }
-}
+MetalBuffer::~MetalBuffer() = default;
 
 void MetalBuffer::copyIntoBuffer(
         void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) {
@@ -83,12 +79,6 @@ void MetalBuffer::copyIntoBuffer(
     FILAMENT_CHECK_PRECONDITION(!(byteOffset & 0x3))
             << "byteOffset must be a multiple of 4, tag=" << getHandleTag();
 
-    // If we have a cpu buffer, we can directly copy into it.
-    if (mCpuBuffer) {
-        memcpy(static_cast<uint8_t*>(mCpuBuffer) + byteOffset, src, size);
-        return;
-    }
-
     switch (mUploadStrategy) {
         case UploadStrategy::BUMP_ALLOCATOR:
             uploadWithBumpAllocator(src, size, byteOffset, std::move(getHandleTag));
@@ -106,11 +96,6 @@ void MetalBuffer::copyIntoBufferUnsynchronized(
 }
 
 id<MTLBuffer> MetalBuffer::getGpuBufferForDraw() noexcept {
-    // If there's a CPU buffer, then we return nil here, as the CPU-side buffer will be bound
-    // separately.
-    if (mCpuBuffer) {
-        return nil;
-    }
     assert_invariant(mBuffer);
     return mBuffer.get();
 }
@@ -171,41 +156,6 @@ void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLCommandEncod
                                                    offsets:metalOffsets.data()
                                                  withRange:bufferRange];
     }
-
-    for (size_t b = 0; b < count; b++) {
-        MetalBuffer* const buffer = buffers[b];
-        if (!buffer) {
-            continue;
-        }
-
-        const void* cpuBuffer = buffer->getCpuBuffer();
-        if (!cpuBuffer) {
-            continue;
-        }
-
-        const size_t bufferIndex = bufferStart + b;
-        const size_t offset = offsets[b];
-        auto* bytes = static_cast<const uint8_t*>(cpuBuffer);
-
-        if (stages & Stage::VERTEX) {
-            [(id<MTLRenderCommandEncoder>) encoder setVertexBytes:(bytes + offset)
-                                                           length:(buffer->getSize() - offset)
-                                                          atIndex:bufferIndex];
-        }
-        if (stages & Stage::FRAGMENT) {
-            [(id<MTLRenderCommandEncoder>) encoder setFragmentBytes:(bytes + offset)
-                                                             length:(buffer->getSize() - offset)
-                                                            atIndex:bufferIndex];
-        }
-        if (stages & Stage::COMPUTE) {
-            // TODO: using setBytes means the data is read-only, which currently isn't enforced.
-            // In practice this won't be an issue since MetalBuffer ensures all SSBOs are realized
-            // through actual id<MTLBuffer> allocations.
-            [(id<MTLComputeCommandEncoder>) encoder setBytes:(bytes + offset)
-                                                      length:(buffer->getSize() - offset)
-                                                     atIndex:bufferIndex];
-        }
-    }
 }
 
 void MetalBuffer::uploadWithPoolBuffer(

filament/backend/src/metal/MetalContext.h

@@ -17,6 +17,7 @@
 #ifndef TNT_METALCONTEXT_H
 #define TNT_METALCONTEXT_H
 
+#include "MetalErrorQueue.h"
 #include "MetalResourceTracker.h"
 #include "MetalShaderCompiler.h"
 #include "MetalState.h"
@@ -129,6 +130,7 @@ struct MetalContext {
     id<MTLCommandBuffer> pendingCommandBuffer = nil;
     id<MTLRenderCommandEncoder> currentRenderPassEncoder = nil;
     uint32_t currentFrame = 0;
+    MetalErrorQueue commandBufferErrors;
 
     std::atomic<bool> memorylessLimitsReached = false;
 

filament/backend/src/metal/MetalContext.mm

@@ -95,6 +95,38 @@ void initializeSupportedGpuFamilies(MetalContext* context) {
     }
 }
 
+void logMTLCommandBufferError(MTLCommandBufferError error) {
+#define MTL_COMMAND_ERROR_CASE(ERR)                                                                \
+    if (error == (ERR)) {                                                                          \
+        LOG(ERROR) << "Filament Metal error: " #ERR ".";                                           \
+        return;                                                                                    \
+    }
+
+#if !defined(FILAMENT_IOS)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorDeviceRemoved)
+#endif
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorNone)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorInternal)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorTimeout)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorPageFault)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorAccessRevoked)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorNotPermitted)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorOutOfMemory)
+    MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorInvalidResource)
+
+    if (@available(macOS 11.0, *)) {
+        MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorMemoryless)
+    }
+
+    if (@available(iOS 15.0, macOS 12.0, *)) {
+        MTL_COMMAND_ERROR_CASE(MTLCommandBufferErrorStackOverflow)
+    }
+
+    LOG(ERROR) << "Filament Metal unknown error.";
+
+#undef MTL_COMMAND_ERROR_CASE
+}
+
 id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
     if (context->pendingCommandBuffer) {
         return context->pendingCommandBuffer;
@@ -120,8 +152,8 @@ id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
         }
 
         if (UTILS_UNLIKELY(errorCode != MTLCommandBufferErrorNone)) {
-            LOG(ERROR) << "Filament Metal command buffer errored with code: " << errorCode << " ("
-                       << stringifyMTLCommandBufferError(errorCode) << ").";
+            logMTLCommandBufferError(errorCode);
+            context->commandBufferErrors.push(buffer.error);
         }
     }];
     FILAMENT_CHECK_POSTCONDITION(context->pendingCommandBuffer)

filament/backend/src/metal/MetalDriver.h

@@ -61,6 +61,8 @@ public:
 
     MetalContext* getContext() { return mContext; }
 
+    using DriverBase::scheduleDestroy;
+
 private:
 
     friend class MetalSwapChain;

filament/backend/src/metal/MetalDriver.mm

@@ -254,6 +254,18 @@ MetalDriver::~MetalDriver() noexcept {
 void MetalDriver::tick(int) {
     executeTickOps();
     executeDeferredOps();
+
+    // Notify platform of GPU errors.
+    auto& platform = mPlatform;
+    if (UTILS_UNLIKELY(!mContext->commandBufferErrors.isEmpty())) {
+        mContext->commandBufferErrors.flush([&platform](NSError* error) {
+            if (UTILS_VERY_UNLIKELY(!error)) {
+                return;
+            }
+            const utils::CString errorString(error.localizedDescription.UTF8String);
+            platform.debugUpdateStat("filament.metal.command_buffer_error", errorString);
+        });
+    }
 }
 
 void MetalDriver::beginFrame(int64_t monotonic_clock_ns,
@@ -621,7 +633,9 @@ void MetalDriver::createRenderTargetR(Handle<HwRenderTarget> rth,
     auto& sc = mContext->sampleCountLookup;
     samples = sc[std::min(MAX_SAMPLE_COUNT, samples)];
 
-    MetalRenderTarget::Attachment colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT] = {{}};
+    using AttachmentInfo = MetalRenderTarget::AttachmentInfo;
+
+    AttachmentInfo colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT] = { {} };
     for (size_t i = 0; i < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT; i++) {
         if (none(targetBufferFlags & getTargetBufferFlagsAt(i))) {
             continue;
@@ -635,7 +649,7 @@ void MetalDriver::createRenderTargetR(Handle<HwRenderTarget> rth,
         colorAttachments[i] = { colorTexture, color[i].level, color[i].layer };
     }
 
-    MetalRenderTarget::Attachment depthAttachment = {};
+    AttachmentInfo depthAttachment = {};
     if (any(targetBufferFlags & TargetBufferFlags::DEPTH)) {
         FILAMENT_CHECK_PRECONDITION(depth.handle)
                 << "The DEPTH flag was specified, but invalid depth handle provided.";
@@ -645,7 +659,7 @@ void MetalDriver::createRenderTargetR(Handle<HwRenderTarget> rth,
         depthAttachment = { depthTexture, depth.level, depth.layer };
     }
 
-    MetalRenderTarget::Attachment stencilAttachment = {};
+    AttachmentInfo stencilAttachment = {};
     if (any(targetBufferFlags & TargetBufferFlags::STENCIL)) {
         FILAMENT_CHECK_PRECONDITION(stencil.handle)
                 << "The STENCIL flag was specified, but invalid stencil handle provided.";
@@ -669,8 +683,6 @@ void MetalDriver::createFenceR(Handle<HwFence> fh, utils::ImmutableCString&& tag
 
 void MetalDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow, uint64_t flags,
         utils::ImmutableCString&& tag) {
-    // TODO: support MSAA swapchain
-
     if (UTILS_UNLIKELY(flags & SWAP_CHAIN_CONFIG_APPLE_CVPIXELBUFFER)) {
         CVPixelBufferRef pixelBuffer = (CVPixelBufferRef) nativeWindow;
         construct_handle<MetalSwapChain>(sch, *mContext, mPlatform, pixelBuffer, flags);
@@ -1039,19 +1051,27 @@ void MetalDriver::updateStreams(DriverApi* driver) {
 
 void MetalDriver::destroyFence(Handle<HwFence> fh) {
     if (fh) {
+        // note: it's invalid to call this during a fenceWait(fh) on another thread. For this
+        // reason there is no point signaling the waiters. There should be no waiters.
         destruct_handle<MetalFence>(fh);
     }
 }
 
+void MetalDriver::fenceCancel(FenceHandle const fh) {
+    // Even though this is a synchronous call, the fence handle must be (and stay) valid
+    assert_invariant(fh);
+    auto* fence = handle_cast<MetalFence>(fh);
+    fence->cancel();
+}
+
 FenceStatus MetalDriver::getFenceStatus(Handle<HwFence> fh) {
     return fenceWait(fh, 0);
 }
 
 FenceStatus MetalDriver::fenceWait(FenceHandle fh, uint64_t const timeout) {
+    // Even though this is a synchronous call, the fence handle must be (and stay) valid
+    assert_invariant(fh);
     auto* fence = handle_cast<MetalFence>(fh);
-    if (!fence) {
-        return FenceStatus::ERROR;
-    }
     return fence->wait(timeout);
 }
 
@@ -1124,8 +1144,12 @@ bool MetalDriver::isRenderTargetFormatSupported(TextureFormat format) {
 bool MetalDriver::isFrameBufferFetchSupported() {
     // FrameBuffer fetch is achievable via "programmable blending" in Metal, and only supported on
     // Apple GPUs with readWriteTextureSupport.
-    return mContext->highestSupportedGpuFamily.apple >= 1 &&
-            mContext->device.readWriteTextureSupport;
+    // On macOS, framebuffer fetch requires MSL 2.3, which is only available with macOS 11.0.
+    if (@available(macOS 11.0, *)) {
+        return mContext->highestSupportedGpuFamily.apple >= 1 &&
+               mContext->device.readWriteTextureSupport;
+    }
+    return false;
 }
 
 bool MetalDriver::isFrameBufferFetchMultiSampleSupported() {
@@ -1150,8 +1174,7 @@ bool MetalDriver::isSRGBSwapChainSupported() {
 }
 
 bool MetalDriver::isMSAASwapChainSupported(uint32_t) {
-    // TODO: support MSAA swapchain
-    return false;
+    return true;
 }
 
 bool MetalDriver::isProtectedContentSupported() {
@@ -1267,10 +1290,6 @@ void MetalDriver::updateIndexBuffer(Handle<HwIndexBuffer> ibh, BufferDescriptor&
     scheduleDestroy(std::move(data));
 }
 
-void MetalDriver::registerBufferObjectStreams(Handle<HwBufferObject> boh, BufferObjectStreamDescriptor&& streams) {
-    // Noop
-}
-
 void MetalDriver::updateBufferObject(Handle<HwBufferObject> boh, BufferDescriptor&& data,
         uint32_t byteOffset) {
     FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
@@ -1475,6 +1494,20 @@ void MetalDriver::setRenderPrimitiveBuffer(Handle<HwRenderPrimitive> rph, Primit
     primitive->type = pt;
 }
 
+bool MetalDriver::isCompositorTimingSupported() {
+    return false;
+}
+
+bool MetalDriver::queryCompositorTiming(backend::SwapChainHandle swapChain,
+        CompositorTiming* outCompositorTiming) {
+    return false;
+}
+
+bool MetalDriver::queryFrameTimestamps(SwapChainHandle swapChain, uint64_t frameId,
+        FrameTimestamps* outFrameTimestamps) {
+    return false;
+}
+
 void MetalDriver::makeCurrent(Handle<HwSwapChain> schDraw, Handle<HwSwapChain> schRead) {
     ASSERT_PRECONDITION_NON_FATAL(schDraw, "A draw SwapChain must be set.");
     auto* drawSwapChain = handle_cast<MetalSwapChain>(schDraw);
@@ -1561,9 +1594,9 @@ void MetalDriver::readPixels(Handle<HwRenderTarget> src, uint32_t x, uint32_t y,
 
     auto srcTarget = handle_cast<MetalRenderTarget>(src);
     // We always readPixels from the COLOR0 attachment.
-    MetalRenderTarget::Attachment color = srcTarget->getDrawColorAttachment(0);
+    MetalAttachment color = srcTarget->getDrawColorAttachment(0);
     id<MTLTexture> srcTexture = color.getTexture();
-    size_t miplevel = color.level;
+    size_t miplevel = color.getLevel();
 
     // Clamp height and width to actual texture's height and width
     MTLSize srcTextureSize = MTLSizeMake(srcTexture.width >> miplevel, srcTexture.height >> miplevel, 1);
@@ -1771,8 +1804,8 @@ void MetalDriver::blitDEPRECATED(TargetBufferFlags buffers,
     };
 
     // We always blit from/to the COLOR0 attachment.
-    MetalRenderTarget::Attachment const srcColorAttachment = srcTarget->getReadColorAttachment(0);
-    MetalRenderTarget::Attachment const dstColorAttachment = dstTarget->getDrawColorAttachment(0);
+    MetalAttachment const srcColorAttachment = srcTarget->getReadColorAttachment(0);
+    MetalAttachment const dstColorAttachment = dstTarget->getDrawColorAttachment(0);
 
     if (srcColorAttachment && dstColorAttachment) {
         FILAMENT_CHECK_PRECONDITION(
@@ -1784,13 +1817,13 @@ void MetalDriver::blitDEPRECATED(TargetBufferFlags buffers,
         args.filter = filter;
         args.source.region = srcTarget->getRegionFromClientRect(srcRect);
         args.source.texture = srcColorAttachment.getTexture();
-        args.source.level = srcColorAttachment.level;
-        args.source.slice = srcColorAttachment.layer;
+        args.source.level = srcColorAttachment.getLevel();
+        args.source.slice = srcColorAttachment.getLayer();
 
         args.destination.region = dstTarget->getRegionFromClientRect(dstRect);
         args.destination.texture = dstColorAttachment.getTexture();
-        args.destination.level = dstColorAttachment.level;
-        args.destination.slice = dstColorAttachment.layer;
+        args.destination.level = dstColorAttachment.getLevel();
+        args.destination.slice = dstColorAttachment.getLayer();
 
         mContext->blitter->blit(getPendingCommandBuffer(mContext), args, "blitDEPRECATED");
     }
@@ -1826,24 +1859,28 @@ void MetalDriver::bindPipeline(PipelineState const& ps) {
     auto [fragment, vertex] = functions.getRasterFunctions();
 
     // Pipeline state
+    MetalRenderTarget* const rt = mContext->currentRenderTarget;
     MTLPixelFormat colorPixelFormat[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT] = { MTLPixelFormatInvalid };
     for (size_t i = 0; i < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT; i++) {
-        const auto& attachment = mContext->currentRenderTarget->getDrawColorAttachment(i);
+        const auto& attachment = rt->getDrawColorAttachment(i);
         if (!attachment) {
             continue;
         }
         colorPixelFormat[i] = attachment.getPixelFormat();
+        assert_invariant(attachment.getSampleCount() == rt->getSampleCount());
     }
     MTLPixelFormat depthPixelFormat = MTLPixelFormatInvalid;
-    const auto& depthAttachment = mContext->currentRenderTarget->getDepthAttachment();
+    const auto& depthAttachment = rt->getDepthAttachment();
     if (depthAttachment) {
         depthPixelFormat = depthAttachment.getPixelFormat();
+        assert_invariant(depthAttachment.getSampleCount() == rt->getSampleCount());
     }
     MTLPixelFormat stencilPixelFormat = MTLPixelFormatInvalid;
-    const auto& stencilAttachment = mContext->currentRenderTarget->getStencilAttachment();
+    const auto& stencilAttachment = rt->getStencilAttachment();
     if (stencilAttachment) {
         stencilPixelFormat = stencilAttachment.getPixelFormat();
         assert_invariant(isMetalFormatStencil(stencilPixelFormat));
+        assert_invariant(stencilAttachment.getSampleCount() == rt->getSampleCount());
     }
     MetalPipelineState const pipelineState {
         .vertexFunction = vertex,
@@ -1861,7 +1898,7 @@ void MetalDriver::bindPipeline(PipelineState const& ps) {
         },
         .depthAttachmentPixelFormat = depthPixelFormat,
         .stencilAttachmentPixelFormat = stencilPixelFormat,
-        .sampleCount = mContext->currentRenderTarget->getSamples(),
+        .sampleCount = rt->getSampleCount(),
         .blendState = BlendState {
             .alphaBlendOperation = getMetalBlendOperation(rs.blendEquationAlpha),
             .rgbBlendOperation = getMetalBlendOperation(rs.blendEquationRGB),
@@ -2238,7 +2275,10 @@ MemoryMappedBufferHandle MetalDriver::mapBufferS() noexcept {
 void MetalDriver::mapBufferR(MemoryMappedBufferHandle mmbh,
         BufferObjectHandle boh, size_t offset,
         size_t size, MapBufferAccessFlags access, utils::ImmutableCString&& tag) {
-    construct_handle<MetalMemoryMappedBuffer>(mmbh, boh, offset, size, access);
+    assert_invariant(boh);
+    MetalBufferObject* bo = mHandleAllocator.handle_cast<MetalBufferObject*>(boh);
+    assert_invariant(bo);
+    construct_handle<MetalMemoryMappedBuffer>(mmbh, bo, offset, size, access);
     mHandleAllocator.associateTagToHandle(mmbh.getId(), std::move(tag));
 }
 
@@ -2246,21 +2286,16 @@ void MetalDriver::unmapBuffer(MemoryMappedBufferHandle mmbh) {
     if (UTILS_UNLIKELY(!mmbh)) {
         return;
     }
+
+    auto* mmb = handle_cast<MetalMemoryMappedBuffer>(mmbh);
+    mmb->unmap();
     destruct_handle<MetalMemoryMappedBuffer>(mmbh);
 }
 
 void MetalDriver::copyToMemoryMappedBuffer(MemoryMappedBufferHandle mmbh, size_t offset,
         BufferDescriptor&& data) {
-    auto mmb = handle_cast<MetalMemoryMappedBuffer>(mmbh);
-
-    assert_invariant(any(mmb->access & MapBufferAccessFlags::WRITE_BIT));
-    assert_invariant(offset + data.size <= mmb->size);
-
-    // TODO: this isa zero-effort implementation of copyToMemoryMappedBuffer(), where we just
-    //       call updateBufferObject(). This could be a fallback implementation for when
-    //       shared memory is not available.
-    //       On UMA systems, this should just be a memcpy into the memory-mapped buffer.
-    updateBufferObject(mmb->boh, std::move(data), mmb->offset + offset);
+    auto* mmb = handle_cast<MetalMemoryMappedBuffer>(mmbh);
+    mmb->copy(*this, offset, std::move(data));
 }
 
 // explicit instantiation of the Dispatcher

filament/backend/src/metal/MetalEnums.h

@@ -451,38 +451,6 @@ inline MTLTextureSwizzleChannels getSwizzleChannels(TextureSwizzle r, TextureSwi
             getSwizzle(a));
 }
 
-inline const char* stringifyMTLCommandBufferError(MTLCommandBufferError error) {
-#if !defined(FILAMENT_IOS)
-    if (error == MTLCommandBufferErrorDeviceRemoved) {
-        return "MTLCommandBufferErrorDeviceRemoved";
-    }
-#endif
-    switch (error) {
-        case MTLCommandBufferErrorNone:
-            return "MTLCommandBufferErrorNone";
-        case MTLCommandBufferErrorInternal:
-            return "MTLCommandBufferErrorInternal";
-        case MTLCommandBufferErrorTimeout:
-            return "MTLCommandBufferErrorTimeout";
-        case MTLCommandBufferErrorPageFault:
-            return "MTLCommandBufferErrorPageFault";
-        case MTLCommandBufferErrorAccessRevoked:
-            return "MTLCommandBufferErrorAccessRevoked";
-        case MTLCommandBufferErrorNotPermitted:
-            return "MTLCommandBufferErrorNotPermitted";
-        case MTLCommandBufferErrorOutOfMemory:
-            return "MTLCommandBufferErrorOutOfMemory";
-        case MTLCommandBufferErrorInvalidResource:
-            return "MTLCommandBufferErrorInvalidResource";
-        case MTLCommandBufferErrorMemoryless:
-            return "MTLCommandBufferErrorMemoryless";
-        case MTLCommandBufferErrorStackOverflow:
-            return "MTLCommandBufferErrorStackOverflow";
-        default:
-            return "Unknown";
-    }
-}
-
 } // namespace backend
 } // namespace filament
 

filament/backend/src/metal/MetalErrorQueue.h

@@ -0,0 +1,66 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_DRIVER_METALERRORQUEUE_H
+#define TNT_FILAMENT_DRIVER_METALERRORQUEUE_H
+
+#import <Foundation/Foundation.h>
+
+#include <utils/compiler.h>
+
+#include <atomic>
+#include <functional>
+#include <mutex>
+#include <vector>
+
+class MetalErrorQueue {
+public:
+    bool isEmpty() const {
+        return !mHasErrors.load(std::memory_order_relaxed);
+    }
+
+    void push(NSError* error) {
+        std::lock_guard<std::mutex> lock(mMutex);
+        mErrors.push_back(error);
+        mHasErrors.store(true, std::memory_order_relaxed);
+    }
+
+    void flush(const std::function<void(NSError*)>& callback) {
+        if (UTILS_LIKELY(isEmpty())) {
+            return;
+        }
+        std::vector<NSError*> errors;
+        {
+            std::lock_guard<std::mutex> lock(mMutex);
+            std::swap(mErrors, errors);
+            mHasErrors.store(false, std::memory_order_relaxed);
+        }
+
+        for (const auto& error: errors) {
+            callback(error);
+        }
+    }
+
+private:
+    std::vector<NSError*> mErrors;
+    std::mutex mMutex;
+
+    // Optimization to avoid locking the mutex at each call to flush.
+    std::atomic<bool> mHasErrors;
+};
+
+
+#endif // TNT_FILAMENT_DRIVER_METALERRORQUEUE_H

filament/backend/src/metal/MetalHandles.h

@@ -49,6 +49,61 @@
 namespace filament {
 namespace backend {
 
+class MetalAttachment {
+public:
+    MetalAttachment() = default;
+    MetalAttachment(id<MTLTexture> texture, uint8_t level = 0, uint16_t layer = 0)
+            : mLevel(level),
+              mLayer(layer),
+              mTexture(texture) {
+        assert_invariant(texture);
+    }
+
+    explicit operator bool() const { return mTexture != nil; }
+
+    id<MTLTexture> getTexture() const { return mTexture; }
+
+    id<MTLTexture> getMsaaTexture() const { return mMsaaTexture; }
+
+    MTLPixelFormat getPixelFormat() const {
+        return mTexture ? mTexture.pixelFormat : MTLPixelFormatInvalid;
+    }
+
+    NSUInteger getSampleCount() const {
+        if (mMsaaTexture) {
+            return mMsaaTexture.sampleCount;
+        }
+        if (mTexture) {
+            return mTexture.sampleCount;
+        }
+        return 1u;
+    }
+
+    uint8_t getLevel() const { return mLevel; }
+    uint16_t getLayer() const { return mLayer; }
+
+    MetalAttachment withMsaaTexture(id<MTLTexture> msaa) const {
+        assert_invariant(mTexture != nil);
+        assert_invariant(mTexture.sampleCount == 1u);
+        MetalAttachment result = *this;
+        result.mMsaaTexture = msaa;
+        return result;
+    }
+
+    static MetalAttachment invalidAttachment() { return MetalAttachment(); }
+
+private:
+    uint8_t mLevel = 0;
+    uint16_t mLayer = 0;
+
+    // The main texture for this Attachment. May be single-sampled or MSAA.
+    id<MTLTexture> mTexture = nil;
+
+    // The MSAA "sidecar" texture that will resolve into mTexture.
+    // If this is non-nil, mTexture must be single-sampled.
+    id<MTLTexture> mMsaaTexture = nil;
+};
+
 class MetalSwapChain : public HwSwapChain {
 public:
 
@@ -66,14 +121,14 @@ public:
 
     ~MetalSwapChain();
 
-    // Acquires a texture that can be used to render into this SwapChain.
-    // The texture source depends on the type of SwapChain:
+    // Acquires a texture that can be used to render into this SwapChain and returns a
+    // MetalAttachment. The texture source depends on the type of SwapChain:
     //   - CAMetalLayer-backed: acquires the CAMetalDrawable and returns its texture.
     //   - Headless: lazily creates and returns a headless texture.
-    id<MTLTexture> acquireDrawable();
-
-    id<MTLTexture> acquireDepthTexture();
-    id<MTLTexture> acquireStencilTexture();
+    // May return an invalid attachemnt if a drawable cannot be acquired.
+    MetalAttachment acquireDrawable();
+    MetalAttachment acquireDepthTexture();
+    MetalAttachment acquireStencilTexture();
 
     void releaseDrawable();
 
@@ -88,6 +143,7 @@ public:
 
     NSUInteger getSurfaceWidth() const;
     NSUInteger getSurfaceHeight() const;
+    NSUInteger getSampleCount() const;
 
     bool isPixelBuffer() const { return type == SwapChainType::CVPIXELBUFFERREF; }
 
@@ -106,13 +162,24 @@ private:
     void scheduleFrameScheduledCallback();
     void scheduleFrameCompletedCallback();
 
+    MetalAttachment acquireBaseDrawable();
+
+    id<MTLTexture> ensureDepthStencilTexture(uint32_t width, uint32_t height);
+    id<MTLTexture> ensureMsaaColorTexture(MTLPixelFormat format, uint32_t width, uint32_t height,
+            uint8_t samples);
+    id<MTLTexture> ensureMsaaDepthStencilTexture(MTLPixelFormat format, uint32_t width,
+            uint32_t height, uint8_t samples);
+
     static MTLPixelFormat decideDepthStencilFormat(uint64_t flags);
-    void ensureDepthStencilTexture();
+    static id<MTLTexture> createMultisampledTexture(MetalContext const& context,
+            MTLPixelFormat format, uint32_t width, uint32_t height, uint8_t samples);
 
     MetalContext& context;
     PlatformMetal& platform;
     id<CAMetalDrawable> drawable = nil;
     id<MTLTexture> depthStencilTexture = nil;
+    id<MTLTexture> msaaColor = nil;
+    id<MTLTexture> msaaDepthStencil = nil;
     id<MTLTexture> headlessDrawable = nil;
     MTLPixelFormat depthStencilFormat = MTLPixelFormatInvalid;
     NSUInteger headlessWidth = 0;
@@ -121,6 +188,7 @@ private:
     std::shared_ptr<std::mutex> layerDrawableMutex;
     MetalExternalImage externalImage;
     SwapChainType type;
+    uint64_t flags;
 
     int64_t abandonedUntilFrame = -1;
 
@@ -307,51 +375,15 @@ private:
 class MetalRenderTarget : public HwRenderTarget {
 public:
 
-    class Attachment {
-    public:
-
-        friend class MetalRenderTarget;
-
-        Attachment() = default;
-        Attachment(MetalTexture* metalTexture, uint8_t level = 0, uint16_t layer = 0) :
-                level(level), layer(layer),
-                texture(metalTexture->getMtlTextureForWrite()),
-                metalTexture(metalTexture) { }
-
-        id<MTLTexture> getTexture() const {
-            return texture;
-        }
-
-        NSUInteger getSampleCount() const {
-            return texture ? texture.sampleCount : 0u;
-        }
-
-        MTLPixelFormat getPixelFormat() const {
-            return texture ? texture.pixelFormat : MTLPixelFormatInvalid;
-        }
-
-        explicit operator bool() const {
-            return texture != nil;
-        }
-
+    struct AttachmentInfo {
+        MetalTexture* texture = nullptr;
         uint8_t level = 0;
         uint16_t layer = 0;
-
-    private:
-
-        id<MTLTexture> getMSAASidecarTexture() const {
-            // This should only be called from render targets associated with a MetalTexture.
-            assert_invariant(metalTexture);
-            return metalTexture->msaaSidecar;
-        }
-
-        id<MTLTexture> texture = nil;
-        MetalTexture* metalTexture = nullptr;
     };
 
     MetalRenderTarget(MetalContext* context, uint32_t width, uint32_t height, uint8_t samples,
-            Attachment colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT],
-            Attachment depthAttachment, Attachment stencilAttachment);
+            AttachmentInfo colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT],
+            AttachmentInfo depthAttachment, AttachmentInfo stencilAttachment);
     explicit MetalRenderTarget(MetalContext* context)
             : HwRenderTarget(0, 0), context(context), defaultRenderTarget(true) {}
 
@@ -387,12 +419,14 @@ public:
 
     math::uint2 getAttachmentSize() noexcept;
 
-    uint8_t getSamples() const { return samples; }
+    MetalAttachment getDrawColorAttachment(size_t index);
+    MetalAttachment getReadColorAttachment(size_t index);
+    MetalAttachment getDepthAttachment();
+    MetalAttachment getStencilAttachment();
 
-    Attachment getDrawColorAttachment(size_t index);
-    Attachment getReadColorAttachment(size_t index);
-    Attachment getDepthAttachment();
-    Attachment getStencilAttachment();
+    // Returns the number of samples that should be used in the pipeline state that renders to this
+    // render target. Takes into account "automagic" resolve and MSAA SwapChains.
+    NSUInteger getSampleCount() const;
 
 private:
 
@@ -402,12 +436,12 @@ private:
 
     MetalContext* context;
     bool defaultRenderTarget = false;
-    uint8_t samples = 1;
 
-    Attachment color[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT] = {};
-    Attachment depth = {};
-    Attachment stencil = {};
+    MetalAttachment color[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT] = {};
+    MetalAttachment depth = {};
+    MetalAttachment stencil = {};
     math::uint2 attachmentSize = {};
+    uint8_t samples = 1;
 };
 
 // MetalFence is used to implement both Fences and Syncs.
@@ -429,6 +463,8 @@ public:
     API_AVAILABLE(ios(12.0))
     void onSignal(MetalFenceSignalBlock block);
 
+    void cancel();
+
 private:
 
     MetalContext& context;
@@ -533,14 +569,22 @@ struct MetalDescriptorSet : public HwDescriptorSet {
 
 
 struct MetalMemoryMappedBuffer : public HwMemoryMappedBuffer {
-    MetalMemoryMappedBuffer(BufferObjectHandle boh, size_t const offset,
-            size_t const size, MapBufferAccessFlags const access)
-        : boh(boh), access(access), size(size), offset(offset) {
-    }
-    BufferObjectHandle boh{};
     MapBufferAccessFlags access{};
-    uint32_t size = 0;
-    uint32_t offset = 0;
+    struct {
+        MetalBufferObject* bo;
+        void* vaddr = nullptr;
+        uint32_t size = 0;
+        uint32_t offset = 0;
+    } mtl;
+
+    MetalMemoryMappedBuffer(MetalBufferObject* bo, size_t offset, size_t size,
+            MapBufferAccessFlags access) noexcept;
+
+    ~MetalMemoryMappedBuffer();
+
+    void unmap();
+
+    void copy(MetalDriver& mtld, size_t offset, BufferDescriptor&& data) const;
 };
 
 } // namespace backend