vk: record timestmps on command buffers

Timer queries are inserted into the beginning and the end of each
command buffer. Refactor vk's implementation of Filament's timer
queries so that they are now computed as a sum of the time taken
by one or more command buffers (and not direct insertion of queries
into the command stream).

This is to address a potential issue where the timestamps returned
between command buffers are not consistent.

.github/workflows/presubmit.yml

@@ -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()
 
 # ==================================================================================================
@@ -837,6 +888,7 @@ add_subdirectory(${EXTERNAL}/getopt)
 add_subdirectory(${EXTERNAL}/perfetto/tnt)
 add_subdirectory(${EXTERNAL}/zstd/tnt)
 
+
 # Note that this has to be placed after mikktspace in order for combine_static_libs to work.
 add_subdirectory(${LIBRARIES}/geometry)
 
@@ -859,6 +911,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 +974,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()

NEW_RELEASE_NOTES.md

@@ -6,3 +6,5 @@
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- engine: add `View::getLastDynamicResolutionScale()` (b/457753622)

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.67.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.67.0'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,6 +7,13 @@ 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.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/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/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/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/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/gradle.properties

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

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"
@@ -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

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.66.2'
 }
 </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.66.2'
 </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/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)
@@ -214,8 +216,6 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanPipelineCache.h
             src/vulkan/VulkanPipelineLayoutCache.cpp
             src/vulkan/VulkanPipelineLayoutCache.h
-            src/vulkan/VulkanQueryManager.cpp
-            src/vulkan/VulkanQueryManager.h
             src/vulkan/VulkanReadPixels.cpp
             src/vulkan/VulkanReadPixels.h
             src/vulkan/VulkanSamplerCache.cpp
@@ -250,10 +250,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
@@ -369,46 +380,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 +413,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 +532,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 +563,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/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,11 @@ 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;
 
 } // namespace filament::backend
 

filament/backend/include/backend/Platform.h

@@ -96,6 +96,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 +111,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 +139,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;
     };
 

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

@@ -18,6 +18,8 @@
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 
 #include "AndroidSwapChainHelper.h"
+#include "AndroidFrameCallback.h"
+#include "AndroidNdk.h"
 
 #include <backend/AcquiredImage.h>
 #include <backend/DriverEnums.h>
@@ -30,6 +32,8 @@
 
 #include <math/mat3.h>
 
+#include "AndroidNativeWindow.h"
+
 #include <chrono>
 
 #include <stddef.h>
@@ -43,7 +47,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;
@@ -185,6 +189,10 @@ private:
     [[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();
     };
@@ -202,11 +210,10 @@ private:
 
     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;
+    AndroidProducerThrottling mProducerThrottling;
     bool mAssertNativeWindowIsValid = false;
-    bool mHasProducerThrottlingControl = false;
+
+    AndroidFrameCallback mAndroidFrameCallback;
 };
 
 } // namespace filament::backend

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

@@ -48,7 +48,7 @@ struct VulkanPlatformPrivate;
 
 // Forward declare the fence status that will be maintained by the command
 // buffer manager.
-struct VulkanCmdFence;
+struct VulkanCmdBufferState;
 
 /**
  * A Platform interface that creates a Vulkan backend.
@@ -242,7 +242,7 @@ public:
      * @return              A Platform::Sync object tracking the provided fence.
      */
     virtual Platform::Sync* createSync(VkFence fence,
-            std::shared_ptr<VulkanCmdFence> fenceStatus) noexcept;
+            std::shared_ptr<VulkanCmdBufferState> fenceStatus) noexcept;
 
     /**
      * Destroys a sync. If called with a sync not created by this platform
@@ -434,25 +434,17 @@ public:
 protected:
     struct VulkanSync : public Platform::Sync {
         VkFence fence;
-        std::shared_ptr<VulkanCmdFence> fenceStatus;
+        std::shared_ptr<VulkanCmdBufferState> 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;
 
 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,6 +17,9 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORMS_VULKAN_PLATFORM_ANDROID_H
 #define TNT_FILAMENT_BACKEND_PLATFORMS_VULKAN_PLATFORM_ANDROID_H
 
+#include "AndroidFrameCallback.h"
+#include "AndroidNdk.h"
+
 #include <backend/DriverEnums.h>
 #include <backend/platforms/VulkanPlatform.h>
 
@@ -24,7 +27,7 @@
 
 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 +39,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 +60,47 @@ 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 ExternalImageVulkanAndroid : public ExternalImage {
         AHardwareBuffer* aHardwareBuffer = nullptr;
         bool sRGB = false;
 
     protected:
         ~ExternalImageVulkanAndroid() override;
     };
+
+    AndroidFrameCallback mAndroidFrameCallback;
+    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/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

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)) {
@@ -75,4 +84,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

@@ -37,7 +37,12 @@ struct NativeWindow {
         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, ...);
 
@@ -58,6 +63,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 "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/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/src/AndroidSwapChainHelper.cpp

@@ -31,31 +31,27 @@ 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) {
+        if (pos && *pos != sysFrameId) {
             // we're trying to associate the same frame id to a different frame!
             return false;
         }
-        // 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/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/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,7 @@ id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
         }
 
         if (UTILS_UNLIKELY(errorCode != MTLCommandBufferErrorNone)) {
-            LOG(ERROR) << "Filament Metal command buffer errored with code: " << errorCode << " ("
-                       << stringifyMTLCommandBufferError(errorCode) << ").";
+            logMTLCommandBufferError(errorCode);
         }
     }];
     FILAMENT_CHECK_POSTCONDITION(context->pendingCommandBuffer)

filament/backend/src/metal/MetalDriver.mm

@@ -621,7 +621,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 +637,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 +647,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 +671,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 +1039,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);
 }
 
@@ -1150,8 +1158,7 @@ bool MetalDriver::isSRGBSwapChainSupported() {
 }
 
 bool MetalDriver::isMSAASwapChainSupported(uint32_t) {
-    // TODO: support MSAA swapchain
-    return false;
+    return true;
 }
 
 bool MetalDriver::isProtectedContentSupported() {
@@ -1475,6 +1482,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 +1582,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 +1792,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 +1805,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 +1847,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 +1886,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),

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/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;

filament/backend/src/metal/MetalHandles.mm

@@ -116,7 +116,8 @@ MetalSwapChain::MetalSwapChain(
       depthStencilFormat(decideDepthStencilFormat(flags)),
       layer(nativeWindow),
       layerDrawableMutex(std::make_shared<std::mutex>()),
-      type(SwapChainType::CAMETALLAYER) {
+      type(SwapChainType::CAMETALLAYER),
+      flags(flags) {
 
     FILAMENT_CHECK_PRECONDITION([nativeWindow isKindOfClass:[CAMetalLayer class]])
             << "nativeWindow pointer of class "
@@ -147,7 +148,8 @@ MetalSwapChain::MetalSwapChain(MetalContext& context, PlatformMetal& platform, i
       depthStencilFormat(decideDepthStencilFormat(flags)),
       headlessWidth(width),
       headlessHeight(height),
-      type(SwapChainType::HEADLESS) {}
+      type(SwapChainType::HEADLESS),
+      flags(flags) {}
 
 MetalSwapChain::MetalSwapChain(MetalContext& context, PlatformMetal& platform,
         CVPixelBufferRef pixelBuffer, uint64_t flags)
@@ -155,7 +157,8 @@ MetalSwapChain::MetalSwapChain(MetalContext& context, PlatformMetal& platform,
       platform(platform),
       depthStencilFormat(decideDepthStencilFormat(flags)),
       externalImage(MetalExternalImage::createFromImage(context, pixelBuffer)),
-      type(SwapChainType::CVPIXELBUFFERREF) {
+      type(SwapChainType::CVPIXELBUFFERREF),
+      flags(flags) {
     assert_invariant(flags & SWAP_CHAIN_CONFIG_APPLE_CVPIXELBUFFER);
     MetalExternalImage::assertWritableImage(pixelBuffer);
     assert_invariant(externalImage.isValid());
@@ -167,6 +170,27 @@ MTLPixelFormat MetalSwapChain::decideDepthStencilFormat(uint64_t flags) {
                                                         : MTLPixelFormatDepth32Float;
 }
 
+id<MTLTexture> MetalSwapChain::createMultisampledTexture(MetalContext const& context,
+        MTLPixelFormat format, uint32_t width, uint32_t height, uint8_t samples) {
+    MTLTextureDescriptor* descriptor =
+            [MTLTextureDescriptor texture2DDescriptorWithPixelFormat:format
+                                                               width:width
+                                                              height:height
+                                                           mipmapped:NO];
+    descriptor.textureType = MTLTextureType2DMultisample;
+    descriptor.sampleCount = samples;
+    descriptor.usage = MTLTextureUsageRenderTarget;
+    descriptor.resourceOptions = MTLResourceStorageModePrivate;
+
+    if (context.supportsMemorylessRenderTargets) {
+        if (@available(macOS 11.0, *)) {
+            descriptor.resourceOptions = MTLResourceStorageModeMemoryless;
+        }
+    }
+
+    return [context.device newTextureWithDescriptor:descriptor];
+}
+
 MetalSwapChain::~MetalSwapChain() {
 }
 
@@ -190,63 +214,16 @@ NSUInteger MetalSwapChain::getSurfaceHeight() const {
     return (NSUInteger) layer.drawableSize.height;
 }
 
-bool MetalSwapChain::isAbandoned() const {
-    return context.currentFrame < abandonedUntilFrame;
+
+NSUInteger MetalSwapChain::getSampleCount() const {
+    if (flags & flags & SwapChain::CONFIG_MSAA_4_SAMPLES) {
+        return 4u;
+    }
+    return 1u;
 }
 
-id<MTLTexture> MetalSwapChain::acquireDrawable() {
-    if (drawable) {
-        return drawable.texture;
-    }
-
-    if (isHeadless()) {
-        if (headlessDrawable) {
-            return headlessDrawable;
-        }
-        // For headless surfaces we construct a "fake" drawable, which is simply a renderable
-        // texture.
-        MTLTextureDescriptor* textureDescriptor = [MTLTextureDescriptor new];
-        textureDescriptor.pixelFormat = MTLPixelFormatBGRA8Unorm;
-        textureDescriptor.width = headlessWidth;
-        textureDescriptor.height = headlessHeight;
-        // Specify MTLTextureUsageShaderRead so the headless surface can be blitted from.
-        textureDescriptor.usage = MTLTextureUsageRenderTarget | MTLTextureUsageShaderRead;
-#if defined(FILAMENT_IOS)
-        textureDescriptor.storageMode = MTLStorageModeShared;
-#else
-        textureDescriptor.storageMode = MTLStorageModeManaged;
-#endif
-        headlessDrawable = [context.device newTextureWithDescriptor:textureDescriptor];
-        return headlessDrawable;
-    }
-
-    if (isPixelBuffer()) {
-        return externalImage.getMtlTexture();
-    }
-
-    assert_invariant(isCaMetalLayer());
-
-    // CAMetalLayer's drawable pool is not thread safe. Use a mutex when
-    // calling -nextDrawable, or when releasing the last known reference
-    // to any CAMetalDrawable returned from a previous -nextDrawable.
-    {
-        std::lock_guard<std::mutex> lock(*layerDrawableMutex);
-        drawable = [layer nextDrawable];
-    }
-
-    if (UTILS_UNLIKELY(drawable == nil)) {
-        switch (platform.getDrawableFailureBehavior()) {
-            case PlatformMetal::DrawableFailureBehavior::PANIC:
-                FILAMENT_CHECK_POSTCONDITION(drawable != nil) << "Could not obtain drawable.";
-                break;
-
-            case PlatformMetal::DrawableFailureBehavior::ABORT_FRAME:
-                abandonedUntilFrame = context.currentFrame + 1;
-                return nil;
-        }
-    }
-
-    return drawable.texture;
+bool MetalSwapChain::isAbandoned() const {
+    return context.currentFrame < abandonedUntilFrame;
 }
 
 void MetalSwapChain::releaseDrawable() {
@@ -256,32 +233,45 @@ void MetalSwapChain::releaseDrawable() {
     }
 }
 
-id<MTLTexture> MetalSwapChain::acquireDepthTexture() {
-    ensureDepthStencilTexture();
-    assert_invariant(depthStencilTexture);
-    return depthStencilTexture;
-}
-
-id<MTLTexture> MetalSwapChain::acquireStencilTexture() {
-    if (!isMetalFormatStencil(depthStencilFormat)) {
-        return nil;
+MetalAttachment MetalSwapChain::acquireDrawable() {
+    MetalAttachment attachment = acquireBaseDrawable();
+    if (auto texture = attachment.getTexture();
+            texture && flags & SwapChain::CONFIG_MSAA_4_SAMPLES) {
+        return attachment.withMsaaTexture(
+                ensureMsaaColorTexture(texture.pixelFormat, texture.width, texture.height, 4u));
     }
-    ensureDepthStencilTexture();
-    assert_invariant(depthStencilTexture);
-    return depthStencilTexture;
+    return attachment;
 }
 
-void MetalSwapChain::ensureDepthStencilTexture() {
-    NSUInteger width = getSurfaceWidth();
-    NSUInteger height = getSurfaceHeight();
-    if (UTILS_LIKELY(depthStencilTexture)) {
-        // If the surface size has changed, we'll need to allocate a new depth/stencil texture.
-        if (UTILS_UNLIKELY(
-                    depthStencilTexture.width != width || depthStencilTexture.height != height)) {
-            depthStencilTexture = nil;
-        } else {
-            return;
-        }
+MetalAttachment MetalSwapChain::acquireDepthTexture() {
+    MetalAttachment attachment =
+            MetalAttachment(ensureDepthStencilTexture(getSurfaceWidth(), getSurfaceHeight()));
+    if (auto texture = attachment.getTexture();
+            texture && flags & SwapChain::CONFIG_MSAA_4_SAMPLES) {
+        return attachment.withMsaaTexture(ensureMsaaDepthStencilTexture(texture.pixelFormat,
+                texture.width, texture.height, 4u));
+    }
+    return attachment;
+}
+
+MetalAttachment MetalSwapChain::acquireStencilTexture() {
+    if (!(flags & SwapChain::CONFIG_HAS_STENCIL_BUFFER)) {
+        return MetalAttachment::invalidAttachment();
+    }
+    MetalAttachment attachment =
+            MetalAttachment(ensureDepthStencilTexture(getSurfaceWidth(), getSurfaceHeight()));
+    if (auto texture = attachment.getTexture();
+            texture && flags & SwapChain::CONFIG_MSAA_4_SAMPLES) {
+        return attachment.withMsaaTexture(ensureMsaaDepthStencilTexture(texture.pixelFormat,
+                texture.width, texture.height, 4u));
+    }
+    return attachment;
+}
+
+id<MTLTexture> MetalSwapChain::ensureDepthStencilTexture(uint32_t width, uint32_t height) {
+    if (UTILS_LIKELY(depthStencilTexture && depthStencilTexture.width == width &&
+                     depthStencilTexture.height == height)) {
+        return depthStencilTexture;
     }
     MTLTextureDescriptor* descriptor =
             [MTLTextureDescriptor texture2DDescriptorWithPixelFormat:depthStencilFormat
@@ -290,7 +280,26 @@ void MetalSwapChain::ensureDepthStencilTexture() {
                                                            mipmapped:NO];
     descriptor.usage = MTLTextureUsageRenderTarget;
     descriptor.resourceOptions = MTLResourceStorageModePrivate;
-    depthStencilTexture = [context.device newTextureWithDescriptor:descriptor];
+    return depthStencilTexture = [context.device newTextureWithDescriptor:descriptor];
+}
+
+id<MTLTexture> MetalSwapChain::ensureMsaaColorTexture(MTLPixelFormat format, uint32_t width, uint32_t height,
+        uint8_t samples) {
+    if (UTILS_LIKELY(msaaColor && msaaColor.pixelFormat == format && msaaColor.width == width &&
+                     msaaColor.height == height && msaaColor.sampleCount == samples)) {
+        return msaaColor;
+    }
+    return msaaColor = createMultisampledTexture(context, format, width, height, samples);
+}
+
+id<MTLTexture> MetalSwapChain::ensureMsaaDepthStencilTexture(MTLPixelFormat format, uint32_t width,
+        uint32_t height, uint8_t samples) {
+    if (UTILS_LIKELY(msaaDepthStencil && msaaDepthStencil.pixelFormat == format &&
+                     msaaDepthStencil.width == width && msaaDepthStencil.height == height &&
+                     msaaDepthStencil.sampleCount == samples)) {
+        return msaaDepthStencil;
+    }
+    return msaaDepthStencil = createMultisampledTexture(context, format, width, height, samples);
 }
 
 void MetalSwapChain::setFrameScheduledCallback(
@@ -454,6 +463,62 @@ void MetalSwapChain::scheduleFrameCompletedCallback() {
     }];
 }
 
+MetalAttachment MetalSwapChain::acquireBaseDrawable() {
+    if (drawable) {
+        return MetalAttachment(drawable.texture);
+    }
+
+    if (isHeadless()) {
+        if (headlessDrawable) {
+            return MetalAttachment(headlessDrawable);
+        }
+        // For headless surfaces we construct a "fake" drawable, which is simply a renderable
+        // texture.
+        MTLTextureDescriptor* textureDescriptor = [MTLTextureDescriptor new];
+        textureDescriptor.pixelFormat = MTLPixelFormatBGRA8Unorm;
+        textureDescriptor.width = headlessWidth;
+        textureDescriptor.height = headlessHeight;
+        // Specify MTLTextureUsageShaderRead so the headless surface can be blitted from.
+        textureDescriptor.usage = MTLTextureUsageRenderTarget | MTLTextureUsageShaderRead;
+#if defined(FILAMENT_IOS)
+        textureDescriptor.storageMode = MTLStorageModeShared;
+#else
+        textureDescriptor.storageMode = MTLStorageModeManaged;
+#endif
+        headlessDrawable = [context.device newTextureWithDescriptor:textureDescriptor];
+        return MetalAttachment(headlessDrawable);
+    }
+
+    if (isPixelBuffer()) {
+        return MetalAttachment(externalImage.getMtlTexture());
+    }
+
+    assert_invariant(isCaMetalLayer());
+
+    // CAMetalLayer's drawable pool is not thread safe. Use a mutex when
+    // calling -nextDrawable, or when releasing the last known reference
+    // to any CAMetalDrawable returned from a previous -nextDrawable.
+    {
+        std::lock_guard<std::mutex> lock(*layerDrawableMutex);
+        drawable = [layer nextDrawable];
+    }
+
+    if (UTILS_UNLIKELY(drawable == nil)) {
+        switch (platform.getDrawableFailureBehavior()) {
+            case PlatformMetal::DrawableFailureBehavior::PANIC:
+                FILAMENT_CHECK_POSTCONDITION(drawable != nil) << "Could not obtain drawable.";
+                break;
+
+            case PlatformMetal::DrawableFailureBehavior::ABORT_FRAME:
+                abandonedUntilFrame = context.currentFrame + 1;
+                return MetalAttachment::invalidAttachment();
+        }
+    }
+
+    return MetalAttachment(drawable.texture);
+}
+
+
 MetalBufferObject::MetalBufferObject(MetalContext& context, BufferObjectBinding bindingType,
         BufferUsage usage, uint32_t byteCount)
         : HwBufferObject(byteCount), buffer(context, bindingType, usage, byteCount) {}
@@ -970,90 +1035,108 @@ void MetalTexture::loadWithBlit(uint32_t level, uint32_t slice, MTLRegion region
 }
 
 MetalRenderTarget::MetalRenderTarget(MetalContext* context, uint32_t width, uint32_t height,
-        uint8_t samples, Attachment colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT],
-        Attachment depthAttachment, Attachment stencilAttachment) :
-        HwRenderTarget(width, height), context(context), samples(samples) {
-    math::uint2 tmin = {std::numeric_limits<uint32_t>::max()};
-    UTILS_UNUSED_IN_RELEASE math::uint2 tmax = {0};
+        uint8_t samples, AttachmentInfo colorAttachments[MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT],
+        AttachmentInfo depthAttachment, AttachmentInfo stencilAttachment)
+        : HwRenderTarget(width, height),
+          context(context),
+          samples(samples) {
+    math::uint2 tmin = { std::numeric_limits<uint32_t>::max() };
+    UTILS_UNUSED_IN_RELEASE math::uint2 tmax = { 0 };
     UTILS_UNUSED_IN_RELEASE size_t attachmentCount = 0;
 
     for (size_t i = 0; i < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT; i++) {
-        if (!colorAttachments[i]) {
+        MetalTexture* const texture = colorAttachments[i].texture;
+        const auto& level = colorAttachments[i].level;
+        const auto& layer = colorAttachments[i].layer;
+        if (!texture) {
             continue;
         }
-        color[i] = colorAttachments[i];
 
-        FILAMENT_CHECK_PRECONDITION(color[i].getSampleCount() <= samples)
+        FILAMENT_CHECK_PRECONDITION(texture->samples <= samples)
                 << "MetalRenderTarget was initialized with a MSAA COLOR" << i
                 << " texture, but sample count is " << samples << ".";
 
-        auto t = color[i].metalTexture;
-        const auto twidth = std::max(1u, t->width >> color[i].level);
-        const auto theight = std::max(1u, t->height >> color[i].level);
+        const auto twidth = std::max(1u, texture->width >> level);
+        const auto theight = std::max(1u, texture->height >> level);
         tmin = { std::min(tmin.x, twidth), std::min(tmin.y, theight) };
         tmax = { std::max(tmax.x, twidth), std::max(tmax.y, theight) };
         attachmentCount++;
 
+        id<MTLTexture> mtlTexture = texture->getMtlTextureForWrite();
+        color[i] = MetalAttachment(mtlTexture, level, layer);
+
         // If we were given a single-sampled texture but the samples parameter is > 1, we create
         // a multisampled sidecar texture and do a resolve automatically.
-        if (samples > 1 && color[i].getSampleCount() == 1) {
-            auto& sidecar = color[i].metalTexture->msaaSidecar;
+        if (samples > 1 && texture->samples == 1) {
+            auto& sidecar = texture->msaaSidecar;
             if (!sidecar) {
-                sidecar = createMultisampledTexture(color[i].getPixelFormat(),
-                        color[i].metalTexture->width, color[i].metalTexture->height, samples);
+                sidecar = createMultisampledTexture(mtlTexture.pixelFormat, texture->width,
+                        texture->height, samples);
             }
+            color[i] = MetalAttachment(mtlTexture, level, layer).withMsaaTexture(sidecar);
         }
     }
 
-    if (depthAttachment) {
-        depth = depthAttachment;
+    if (depthAttachment.texture) {
+        MetalTexture* const texture = depthAttachment.texture;
+        const auto& level = depthAttachment.level;
+        const auto& layer = depthAttachment.layer;
 
-        FILAMENT_CHECK_PRECONDITION(depth.getSampleCount() <= samples)
+        FILAMENT_CHECK_PRECONDITION(texture->samples <= samples)
                 << "MetalRenderTarget was initialized with a MSAA DEPTH texture, but sample count "
                    "is "
                 << samples << ".";
 
-        auto t = depth.metalTexture;
-        const auto twidth = std::max(1u, t->width >> depth.level);
-        const auto theight = std::max(1u, t->height >> depth.level);
+        const auto twidth = std::max(1u, texture->width >> level);
+        const auto theight = std::max(1u, texture->height >> level);
         tmin = { math::min(tmin.x, twidth), math::min(tmin.y, theight) };
         tmax = { math::max(tmax.x, twidth), math::max(tmax.y, theight) };
         attachmentCount++;
 
+        id<MTLTexture> mtlTexture = texture->getMtlTextureForWrite();
+        depth = MetalAttachment(mtlTexture, level, layer);
+
         // If we were given a single-sampled texture but the samples parameter is > 1, we create
         // a multisampled sidecar texture and do a resolve automatically.
-        if (samples > 1 && depth.getSampleCount() == 1) {
-            auto& sidecar = depth.metalTexture->msaaSidecar;
+        if (samples > 1 && texture->samples == 1) {
+            auto& sidecar = texture->msaaSidecar;
             if (!sidecar) {
-                sidecar = createMultisampledTexture(depth.getPixelFormat(),
-                        depth.metalTexture->width, depth.metalTexture->height, samples);
+                sidecar = createMultisampledTexture(mtlTexture.pixelFormat, texture->width,
+                        texture->height, samples);
             }
+            depth = MetalAttachment(mtlTexture, level, layer).withMsaaTexture(sidecar);
         }
     }
 
-    if (stencilAttachment) {
-        stencil = stencilAttachment;
+    if (stencilAttachment.texture) {
+        // stencil = stencilAttachment;
+        MetalTexture* const texture = stencilAttachment.texture;
+        const auto& level = stencilAttachment.level;
+        const auto& layer = stencilAttachment.layer;
 
-        FILAMENT_CHECK_PRECONDITION(stencil.getSampleCount() <= samples)
+        FILAMENT_CHECK_PRECONDITION(texture->samples <= samples)
                 << "MetalRenderTarget was initialized with a MSAA STENCIL texture, but sample "
                    "count is "
                 << samples << ".";
 
-        auto t = stencil.metalTexture;
-        const auto twidth = std::max(1u, t->width >> stencil.level);
-        const auto theight = std::max(1u, t->height >> stencil.level);
+        const auto twidth = std::max(1u, texture->width >> level);
+        const auto theight = std::max(1u, texture->height >> level);
         tmin = { math::min(tmin.x, twidth), math::min(tmin.y, theight) };
         tmax = { math::max(tmax.x, twidth), math::max(tmax.y, theight) };
         attachmentCount++;
 
+        id<MTLTexture> mtlTexture = texture->getMtlTextureForWrite();
+        stencil = MetalAttachment(mtlTexture, level, layer);
+
         // If we were given a single-sampled texture but the samples parameter is > 1, we create
         // a multisampled sidecar texture and do a resolve automatically.
-        if (samples > 1 && stencil.getSampleCount() == 1) {
-            auto& sidecar = stencil.metalTexture->msaaSidecar;
+        if (samples > 1 && texture->samples == 1) {
+            auto& sidecar = texture->msaaSidecar;
             if (!sidecar) {
-                sidecar = createMultisampledTexture(stencil.getPixelFormat(),
-                        stencil.metalTexture->width, stencil.metalTexture->height, samples);
+                sidecar = createMultisampledTexture(mtlTexture.pixelFormat, texture->width,
+                        texture->height, samples);
             }
+            stencil = MetalAttachment(mtlTexture, level, layer).withMsaaTexture(sidecar);
         }
     }
 
@@ -1076,105 +1159,105 @@ void MetalRenderTarget::setUpRenderPassAttachments(MTLRenderPassDescriptor* desc
     const auto discardFlags = params.flags.discardEnd;
 
     for (size_t i = 0; i < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT; i++) {
-        Attachment attachment = getDrawColorAttachment(i);
+        MetalAttachment attachment = getDrawColorAttachment(i);
         if (!attachment) {
             continue;
         }
 
         descriptor.colorAttachments[i].texture = attachment.getTexture();
-        descriptor.colorAttachments[i].level = attachment.level;
-        descriptor.colorAttachments[i].slice = attachment.layer;
+        descriptor.colorAttachments[i].level = attachment.getLevel();
+        descriptor.colorAttachments[i].slice = attachment.getLayer();
         descriptor.colorAttachments[i].loadAction = getLoadAction(params, getTargetBufferFlagsAt(i));
         descriptor.colorAttachments[i].storeAction = getStoreAction(params,
                 getTargetBufferFlagsAt(i));
         descriptor.colorAttachments[i].clearColor = MTLClearColorMake(
                 params.clearColor.r, params.clearColor.g, params.clearColor.b, params.clearColor.a);
 
-        const bool automaticResolve = samples > 1 && attachment.getSampleCount() == 1;
-        if (automaticResolve) {
+        if (attachment.getMsaaTexture()) {
+            // Check that the loadAction is valid for MSAA targets: either DontCare or Clear.
             // We're rendering into our temporary MSAA texture and doing an automatic resolve.
             // We should not be attempting to load anything into the MSAA texture.
-            assert_invariant(descriptor.colorAttachments[i].loadAction != MTLLoadActionLoad);
-            assert_invariant(!defaultRenderTarget);
+            // This might happen if the user is rendering multiple views into a MSAA SwapChain,
+            // which is not supported. In that case, ignore the load action.
+            if (descriptor.colorAttachments[i].loadAction == MTLLoadActionLoad) {
+                descriptor.colorAttachments[i].loadAction = MTLLoadActionDontCare;
+            }
 
-            id<MTLTexture> sidecar = attachment.getMSAASidecarTexture();
-            assert_invariant(sidecar);
-
-            descriptor.colorAttachments[i].texture = sidecar;
+            descriptor.colorAttachments[i].texture = attachment.getMsaaTexture();
             descriptor.colorAttachments[i].level = 0;
             descriptor.colorAttachments[i].slice = 0;
             const bool discard = any(discardFlags & getTargetBufferFlagsAt(i));
             if (!discard) {
-                descriptor.colorAttachments[i].resolveTexture = attachment.texture;
-                descriptor.colorAttachments[i].resolveLevel = attachment.level;
-                descriptor.colorAttachments[i].resolveSlice = attachment.layer;
+                descriptor.colorAttachments[i].resolveTexture = attachment.getTexture();
+                descriptor.colorAttachments[i].resolveLevel = attachment.getLevel();
+                descriptor.colorAttachments[i].resolveSlice = attachment.getLayer();
                 descriptor.colorAttachments[i].storeAction = MTLStoreActionMultisampleResolve;
             }
         }
     }
 
-    Attachment depthAttachment = getDepthAttachment();
+    MetalAttachment depthAttachment = getDepthAttachment();
     if (depthAttachment) {
         descriptor.depthAttachment.texture = depthAttachment.getTexture();
-        descriptor.depthAttachment.level = depthAttachment.level;
-        descriptor.depthAttachment.slice = depthAttachment.layer;
+        descriptor.depthAttachment.level = depthAttachment.getLevel();
+        descriptor.depthAttachment.slice = depthAttachment.getLayer();
         descriptor.depthAttachment.loadAction = getLoadAction(params, TargetBufferFlags::DEPTH);
         descriptor.depthAttachment.storeAction = getStoreAction(params, TargetBufferFlags::DEPTH);
         descriptor.depthAttachment.clearDepth = params.clearDepth;
     }
 
-    const bool depthAutomaticResolve = samples > 1 && depthAttachment.getSampleCount() == 1;
-    if (depthAutomaticResolve) {
+    if (depthAttachment.getMsaaTexture()) {
+        // Check that the loadAction is valid for MSAA targets: either DontCare or Clear.
         // We're rendering into our temporary MSAA texture and doing an automatic resolve.
         // We should not be attempting to load anything into the MSAA texture.
-        assert_invariant(descriptor.depthAttachment.loadAction != MTLLoadActionLoad);
-        assert_invariant(!defaultRenderTarget);
+        // This might happen if the user is rendering multiple views into a MSAA SwapChain,
+        // which is not supported. In that case, ignore the load action.
+        if (descriptor.depthAttachment.loadAction == MTLLoadActionLoad) {
+            descriptor.depthAttachment.loadAction = MTLLoadActionDontCare;
+        }
 
-        id<MTLTexture> sidecar = depthAttachment.getMSAASidecarTexture();
-        assert_invariant(sidecar);
-
-        descriptor.depthAttachment.texture = sidecar;
+        descriptor.depthAttachment.texture = depthAttachment.getMsaaTexture();
         descriptor.depthAttachment.level = 0;
         descriptor.depthAttachment.slice = 0;
         const bool discard = any(discardFlags & TargetBufferFlags::DEPTH);
         if (!discard) {
             assert_invariant(context->supportsAutoDepthResolve);
             descriptor.depthAttachment.resolveTexture = depthAttachment.getTexture();
-            descriptor.depthAttachment.resolveLevel = depthAttachment.level;
-            descriptor.depthAttachment.resolveSlice = depthAttachment.layer;
+            descriptor.depthAttachment.resolveLevel = depthAttachment.getLevel();
+            descriptor.depthAttachment.resolveSlice = depthAttachment.getLayer();
             descriptor.depthAttachment.storeAction = MTLStoreActionMultisampleResolve;
         }
     }
 
-    Attachment stencilAttachment = getStencilAttachment();
+    MetalAttachment stencilAttachment = getStencilAttachment();
     if (stencilAttachment) {
         descriptor.stencilAttachment.texture = stencilAttachment.getTexture();
-        descriptor.stencilAttachment.level = stencilAttachment.level;
-        descriptor.stencilAttachment.slice = stencilAttachment.layer;
+        descriptor.stencilAttachment.level = stencilAttachment.getLevel();
+        descriptor.stencilAttachment.slice = stencilAttachment.getLayer();
         descriptor.stencilAttachment.loadAction = getLoadAction(params, TargetBufferFlags::STENCIL);
         descriptor.stencilAttachment.storeAction = getStoreAction(params, TargetBufferFlags::STENCIL);
         descriptor.stencilAttachment.clearStencil = params.clearStencil;
     }
 
-    const bool stencilAutomaticResolve = samples > 1 && stencilAttachment.getSampleCount() == 1;
-    if (stencilAutomaticResolve) {
+    if (stencilAttachment.getMsaaTexture()) {
+        // Check that the loadAction is valid for MSAA targets: either DontCare or Clear.
         // We're rendering into our temporary MSAA texture and doing an automatic resolve.
         // We should not be attempting to load anything into the MSAA texture.
-        assert_invariant(descriptor.stencilAttachment.loadAction != MTLLoadActionLoad);
-        assert_invariant(!defaultRenderTarget);
+        // This might happen if the user is rendering multiple views into a MSAA SwapChain,
+        // which is not supported. In that case, ignore the load action.
+        if (descriptor.stencilAttachment.loadAction == MTLLoadActionLoad) {
+            descriptor.stencilAttachment.loadAction = MTLLoadActionDontCare;
+        }
 
-        id<MTLTexture> sidecar = stencilAttachment.getMSAASidecarTexture();
-        assert_invariant(sidecar);
-
-        descriptor.stencilAttachment.texture = sidecar;
+        descriptor.stencilAttachment.texture = stencilAttachment.getMsaaTexture();
         descriptor.stencilAttachment.level = 0;
         descriptor.stencilAttachment.slice = 0;
         const bool discard = any(discardFlags & TargetBufferFlags::STENCIL);
         if (!discard) {
             assert_invariant(context->supportsAutoDepthResolve);
             descriptor.stencilAttachment.resolveTexture = stencilAttachment.getTexture();
-            descriptor.stencilAttachment.resolveLevel = stencilAttachment.level;
-            descriptor.stencilAttachment.resolveSlice = stencilAttachment.layer;
+            descriptor.stencilAttachment.resolveLevel = stencilAttachment.getLevel();
+            descriptor.stencilAttachment.resolveSlice = stencilAttachment.getLayer();
             descriptor.stencilAttachment.storeAction = MTLStoreActionMultisampleResolve;
             if (@available(iOS 12.0, *)) {
                 descriptor.stencilAttachment.stencilResolveFilter = MTLMultisampleStencilResolveFilterSample0;
@@ -1189,44 +1272,46 @@ bool MetalRenderTarget::involvesAbandonedSwapChain() const noexcept {
     return (draw && draw->isAbandoned()) || (read && read->isAbandoned());
 }
 
-MetalRenderTarget::Attachment MetalRenderTarget::getDrawColorAttachment(size_t index) {
+MetalAttachment MetalRenderTarget::getDrawColorAttachment(size_t index) {
     assert_invariant(index < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT);
-    Attachment result = color[index];
     if (index == 0 && defaultRenderTarget) {
         assert_invariant(context->currentDrawSwapChain);
-        result.texture = context->currentDrawSwapChain->acquireDrawable();
-        // acquireDrawable may fail to acquire the drawable, in which case result.texture will be
-        // nil, and an invalid attachment
+        return context->currentDrawSwapChain->acquireDrawable();
     }
-    return result;
+    return color[index];
 }
 
-MetalRenderTarget::Attachment MetalRenderTarget::getReadColorAttachment(size_t index) {
+MetalAttachment MetalRenderTarget::getReadColorAttachment(size_t index) {
     assert_invariant(index < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT);
-    Attachment result = color[index];
     if (index == 0 && defaultRenderTarget) {
         assert_invariant(context->currentReadSwapChain);
-        result.texture = context->currentReadSwapChain->acquireDrawable();
-        // acquireDrawable may fail to acquire the drawable, in which case result.texture will be
-        // nil, and an invalid attachment
+        return context->currentReadSwapChain->acquireDrawable();
     }
-    return result;
+    return color[index];
 }
 
-MetalRenderTarget::Attachment MetalRenderTarget::getDepthAttachment() {
-    Attachment result = depth;
+MetalAttachment MetalRenderTarget::getDepthAttachment() {
     if (defaultRenderTarget) {
-        result.texture = context->currentDrawSwapChain->acquireDepthTexture();
+        assert_invariant(context->currentDrawSwapChain);
+        return context->currentDrawSwapChain->acquireDepthTexture();
     }
-    return result;
+    return depth;
 }
 
-MetalRenderTarget::Attachment MetalRenderTarget::getStencilAttachment() {
-    Attachment result = stencil;
+MetalAttachment MetalRenderTarget::getStencilAttachment() {
     if (defaultRenderTarget) {
-        result.texture = context->currentDrawSwapChain->acquireStencilTexture();
+        assert_invariant(context->currentDrawSwapChain);
+        return context->currentDrawSwapChain->acquireStencilTexture();
     }
-    return result;
+    return stencil;
+}
+
+NSUInteger MetalRenderTarget::getSampleCount() const {
+    if (defaultRenderTarget) {
+        assert_invariant(context->currentDrawSwapChain);
+        return context->currentDrawSwapChain->getSampleCount();
+    }
+    return samples;
 }
 
 MTLLoadAction MetalRenderTarget::getLoadAction(const RenderPassParams& params,
@@ -1316,14 +1401,20 @@ FenceStatus MetalFence::wait(uint64_t timeoutNs) {
                 state->cv.wait(guard);
             } else if (timeoutNs == 0 ||
                     state->cv.wait_for(guard, ns(timeoutNs)) == std::cv_status::timeout) {
-                return FenceStatus::TIMEOUT_EXPIRED;
+                return state->status;
             }
         }
-        return FenceStatus::CONDITION_SATISFIED;
+        return state->status;
     }
     return FenceStatus::ERROR;
 }
 
+void MetalFence::cancel() {
+    std::unique_lock guard(state->mutex);
+    state->status = FenceStatus::ERROR;
+    state->cv.notify_all();
+}
+
 MetalDescriptorSetLayout::MetalDescriptorSetLayout(DescriptorSetLayout&& l) noexcept
     : mLayout(std::move(l)) {
     size_t dynamicBindings = 0;

filament/backend/src/noop/NoopDriver.cpp

@@ -166,6 +166,9 @@ void NoopDriver::getPlatformSync(Handle<HwSync> sh, CallbackHandler* handler,
 void NoopDriver::destroyFence(Handle<HwFence> fh) {
 }
 
+void NoopDriver::fenceCancel(FenceHandle fh) {
+}
+
 FenceStatus NoopDriver::getFenceStatus(Handle<HwFence> fh) {
     return FenceStatus::CONDITION_SATISFIED;
 }
@@ -450,4 +453,18 @@ void NoopDriver::copyToMemoryMappedBuffer(MemoryMappedBufferHandle mmbh, size_t
         BufferDescriptor&& data) {
 }
 
+bool NoopDriver::isCompositorTimingSupported() {
+    return false;
+}
+
+bool NoopDriver::queryCompositorTiming(backend::SwapChainHandle swapChain,
+        backend::CompositorTiming* outCompositorTiming) {
+    return false;
+}
+
+bool NoopDriver::queryFrameTimestamps(SwapChainHandle swapChain, uint64_t frameId,
+        FrameTimestamps* outFrameTimestamps) {
+    return false;
+}
+
 } // namespace filament

filament/backend/src/opengl/GLDescriptorSet.cpp

@@ -303,13 +303,10 @@ void GLDescriptorSet::bind(
                     offset += offsets[dynamicOffsetIndex++];
                 }
                 if (arg.bo) {
-                    auto buffer = static_cast<char const*>(arg.bo->gl.buffer) + offset;
-                    p.updateUniforms(bindingPoint, arg.bo->gl.id, buffer, arg.bo->age);
+                    p.updateUniforms(bindingPoint, arg.bo->gl.id, arg.bo->gl.buffer, arg.bo->age, offset);
                 }
             } else if constexpr (std::is_same_v<T, Sampler>) {
                 GLuint const unit = p.getTextureUnit(set, binding);
-
-
                 if (arg.handle) {
                     GLTexture const* const t = handleAllocator.handle_cast<GLTexture*>(arg.handle);
                     gl.bindTexture(unit, t->gl.target, t->gl.id, t->gl.external);

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -807,8 +807,9 @@ void OpenGLDriver::textureStorage(GLTexture* t,
                         for (GLint face = 0 ; face < 6 ; face++) {
                             glTexImage2D(GL_TEXTURE_CUBE_MAP_POSITIVE_X + face,
                                     level, GLint(t->gl.internalFormat),
-                                    GLsizei(width), GLsizei(height), 0,
-                                    format, type, nullptr);
+                                    std::max(GLsizei(1), GLsizei(width >> level)),
+                                    std::max(GLsizei(1), GLsizei(height >> level)),
+                                    0, format, type, nullptr);
                         }
                     } else {
                         glTexImage2D(t->gl.target, level, GLint(t->gl.internalFormat),
@@ -1787,7 +1788,7 @@ void OpenGLDriver::createFenceR(Handle<HwFence> fh, ImmutableCString&& tag) {
 
     mHandleAllocator.associateTagToHandle(fh.getId(), std::move(tag));
 
-    GLFence* f = handle_cast<GLFence*>(fh);
+    GLFence* const f = handle_cast<GLFence*>(fh);
     assert_invariant(f->state);
 
     bool const platformCanCreateFence = mPlatform.canCreateFence();
@@ -1803,8 +1804,9 @@ void OpenGLDriver::createFenceR(Handle<HwFence> fh, ImmutableCString&& tag) {
         return;
     }
 
-    // This is the case where we need to use OpenGL fences
 #ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
+    // This is the case where we need to use OpenGL fences, as soon as we return, the user
+    // is allowed to destroy the fence, so we need to keep a reference to the internal state.
     std::weak_ptr<GLFence::State> const weak = f->state;
     whenGpuCommandsComplete([weak] {
         if (auto const state = weak.lock()) {
@@ -2287,74 +2289,84 @@ mat3f OpenGLDriver::getStreamTransformMatrix(Handle<HwStream> sh) {
 
 void OpenGLDriver::destroyFence(Handle<HwFence> fh) {
     if (fh) {
-        GLFence const* f = handle_cast<GLFence*>(fh);
+        GLFence const* const f = handle_cast<GLFence*>(fh);
         if (mPlatform.canCreateFence() || mContext.isES2()) {
             mPlatform.destroyFence(f->fence);
         }
+        // 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(fh, f);
     }
 }
 
+void OpenGLDriver::fenceCancel(FenceHandle fh) {
+    // Even though this is a synchronous call, the fence handle must be (and stay) valid
+    assert_invariant(fh);
+    GLFence const* const f = handle_cast<GLFence*>(fh);
+    assert_invariant(f->state);
+
+    std::lock_guard const lock(f->state->lock);
+    f->state->status = FenceStatus::ERROR;
+    f->state->cond.notify_all();
+}
+
 FenceStatus OpenGLDriver::getFenceStatus(Handle<HwFence> fh) {
     return fenceWait(fh, 0);
 }
 
 FenceStatus OpenGLDriver::fenceWait(FenceHandle fh, uint64_t const timeout) {
-    if (fh) {
-        // we have to take into account that the STL's wait_for() actually works with
-        // time_points relative to steady_clock::now() internally.
-        using namespace std::chrono;
-        auto const now = steady_clock::now();
-        steady_clock::time_point until = steady_clock::time_point::max();
-        if (now <= steady_clock::time_point::max() - nanoseconds(timeout)) {
-            until = now + nanoseconds(timeout);
-        }
+    // Even though this is a synchronous call, the fence handle must be (and stay) valid
+    assert_invariant(fh);
+    GLFence const* const f = handle_cast<GLFence*>(fh);
+    assert_invariant(f->state);
 
-        GLFence const* f = handle_cast<GLFence*>(fh);
-        assert_invariant(f->state);
-
-        bool const platformCanCreateFence = mPlatform.canCreateFence();
-
-        // immediately acquire a reference on our state, so that things don't go south if
-        // the HwFence gets destroyed (on the main thread) while we wait.
-        std::shared_ptr const state{ f->state };
-
-        if (mContext.isES2() || platformCanCreateFence) {
-            if (platformCanCreateFence) {
-                std::unique_lock lock(state->lock);
-                if (f->fence == nullptr) {
-                    // we've been called before the fence was created asynchronously,
-                    // so we need to wait for that, before using the real fence.
-                    // By construction, "f" can't be destroyed while we wait, because its
-                    // construction call is in the queue and a destroy call will have to come later.
-                    state->cond.wait_until(lock, until, [f] {
-                        return f->fence != nullptr;
-                    });
-                    if (f->fence == nullptr) {
-                        // the only possible choice here is that we timed out
-                        assert_invariant(state->status == FenceStatus::TIMEOUT_EXPIRED);
-                        return FenceStatus::TIMEOUT_EXPIRED;
-                    }
-                }
-                lock.unlock();
-                // here we know that we have the platform fence
-                assert_invariant(f->fence);
-                return mPlatform.waitFence(f->fence, timeout);
-            }
-            // platform doesn't support fences -- nothing we can do.
-            return FenceStatus::ERROR;
-        }
-
-        // This is the case where we need to use OpenGL fences
-#ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
-        std::unique_lock lock(state->lock);
-        state->cond.wait_until(lock, until, [&state] {
-            return state->status != FenceStatus::TIMEOUT_EXPIRED;
-        });
-        return state->status;
-#endif
+    // we have to take into account that the STL's wait_for() actually works with
+    // time_points relative to steady_clock::now() internally.
+    using namespace std::chrono;
+    auto const now = steady_clock::now();
+    steady_clock::time_point until = steady_clock::time_point::max();
+    if (now <= steady_clock::time_point::max() - nanoseconds(timeout)) {
+        until = now + nanoseconds(timeout);
     }
-    return FenceStatus::ERROR;
+
+    // we don't need to acquire a reference to f->state here because `f` already has one, and
+    // `f` is not supposed to become invalid while we wait.
+
+    bool const platformCanCreateFence = mPlatform.canCreateFence();
+    if (mContext.isES2() || platformCanCreateFence) {
+        if (platformCanCreateFence) {
+            std::unique_lock lock(f->state->lock);
+            if (f->fence == nullptr) {
+                // we've been called before the fence was created asynchronously,
+                // so we need to wait for that, before using the real fence.
+                // By construction, "f" can't be destroyed while we wait, because its
+                // construction call is in the queue and a destroy call will have to come later.
+                f->state->cond.wait_until(lock, until, [f] {
+                    return f->fence != nullptr;
+                });
+                if (f->fence == nullptr) {
+                    // the only possible choice here is that we timed out
+                    assert_invariant(f->state->status == FenceStatus::TIMEOUT_EXPIRED);
+                    return FenceStatus::TIMEOUT_EXPIRED;
+                }
+            }
+            lock.unlock();
+            // here we know that we have the platform fence
+            assert_invariant(f->fence);
+            return mPlatform.waitFence(f->fence, timeout);
+        }
+        // platform doesn't support fences -- nothing we can do.
+        return FenceStatus::ERROR;
+    }
+
+    // This is the case where we need to use OpenGL fences
+#ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
+    std::unique_lock lock(f->state->lock);
+    f->state->cond.wait_until(lock, until, [f] {
+        return f->state->status != FenceStatus::TIMEOUT_EXPIRED;
+    });
+    return f->state->status;
+#endif
 }
 
 void OpenGLDriver::getPlatformSync(Handle<HwSync> sh, CallbackHandler* handler,
@@ -2698,6 +2710,39 @@ void OpenGLDriver::commit(Handle<HwSwapChain> sch) {
 #endif
 }
 
+bool OpenGLDriver::isCompositorTimingSupported() {
+    // this is a synchronous call
+    return mPlatform.isCompositorTimingSupported();
+}
+
+bool OpenGLDriver::queryCompositorTiming(SwapChainHandle swapChain,
+        CompositorTiming* outCompositorTiming) {
+    // this is a synchronous call
+    if (!swapChain) {
+        return false;
+    }
+    GLSwapChain const* const sc = handle_cast<GLSwapChain*>(swapChain);
+    if (!sc) {
+        // can happen if the SwapChainHandle is not initialized yet (still in CommandStream)
+        return false;
+    }
+    return mPlatform.queryCompositorTiming(sc->swapChain, outCompositorTiming);
+}
+
+bool OpenGLDriver::queryFrameTimestamps(SwapChainHandle swapChain, uint64_t const frameId,
+        FrameTimestamps* outFrameTimestamps) {
+    // this is a synchronous call
+    if (!swapChain) {
+        return false;
+    }
+    GLSwapChain const* const sc = handle_cast<GLSwapChain*>(swapChain);
+    if (!sc) {
+        // can happen if the SwapChainHandle is not initialized yet (still in CommandStream)
+        return false;
+    }
+    return mPlatform.queryFrameTimestamps(sc->swapChain, frameId, outFrameTimestamps);
+}
+
 void OpenGLDriver::makeCurrent(Handle<HwSwapChain> schDraw, Handle<HwSwapChain> schRead) {
     DEBUG_MARKER()
 

filament/backend/src/opengl/OpenGLProgram.cpp

@@ -262,20 +262,25 @@ void OpenGLProgram::initializeProgramState(OpenGLContext& context, GLuint progra
 }
 
 void OpenGLProgram::updateUniforms(
-        uint32_t index, GLuint id, void const* buffer, uint16_t age) const noexcept {
+        uint32_t const index, GLuint const id, void const* buffer,
+        uint16_t const age, uint32_t const offset) const noexcept {
     assert_invariant(mUniformsRecords);
     assert_invariant(buffer);
 
     // only update the uniforms if the UBO has changed since last time we updated
     UniformsRecord const& records = mUniformsRecords[index];
-    if (records.id == id && records.age == age) {
+    if (records.id == id && records.age == age && records.offset == offset) {
         return;
     }
     records.id = id;
     records.age = age;
+    records.offset = offset;
 
     assert_invariant(records.uniforms.size() == records.locations.size());
 
+    // apply the offset to the buffer
+    buffer = static_cast<char const*>(buffer) + offset;
+
     for (size_t i = 0, c = records.uniforms.size(); i < c; i++) {
         Program::Uniform const& u = records.uniforms[i];
         GLint const loc = records.locations[i];

filament/backend/src/opengl/OpenGLProgram.h

@@ -88,7 +88,7 @@ public:
     }
 
     // For ES2 only
-    void updateUniforms(uint32_t index, GLuint id, void const* buffer, uint16_t age) const noexcept;
+    void updateUniforms(uint32_t index, GLuint id, void const* buffer, uint16_t age, uint32_t offset) const noexcept;
     void setRec709ColorSpace(bool rec709) const noexcept;
 
     PushConstantBundle getPushConstants() {
@@ -123,6 +123,7 @@ private:
         LocationInfo locations;
         mutable GLuint id = 0;
         mutable uint16_t age = std::numeric_limits<uint16_t>::max();
+        mutable uint32_t offset = 0;
     };
     UniformsRecord const* mUniformsRecords = nullptr;
     GLint mRec709Location : 24;     // 4 bytes

filament/backend/src/opengl/platforms/PlatformEGLAndroid.cpp

@@ -34,6 +34,8 @@
 #include <android/api-level.h>
 #include <android/native_window.h>
 #include <android/hardware_buffer.h>
+#include <android/choreographer.h>
+#include <android/looper.h>
 
 #include <utils/android/PerformanceHintManager.h>
 #include <utils/compiler.h>
@@ -58,7 +60,6 @@
 #include <new>
 #include <string_view>
 
-#include <dlfcn.h>
 #include <unistd.h>
 #include <stddef.h>
 #include <stdint.h>
@@ -116,33 +117,12 @@ PlatformEGLAndroid::PlatformEGLAndroid() noexcept
     if (mOSVersion < 0) {
         mOSVersion = __ANDROID_API_FUTURE__;
     }
-
-    // TODO: remove this code one the new NDK is available
-    void* nativeWindowLibHandle = dlopen("libnativewindow.so", RTLD_LOCAL | RTLD_NOW);
-    if (nativeWindowLibHandle) {
-        ANativeWindow_setProducerThrottlingEnabled =
-                (int32_t(*)(ANativeWindow*, bool))dlsym(nativeWindowLibHandle,
-                        "ANativeWindow_setProducerThrottlingEnabled");
-
-        ANativeWindow_isProducerThrottlingEnabled =
-                (int32_t(*)(ANativeWindow*, bool*))dlsym(nativeWindowLibHandle,
-                        "ANativeWindow_isProducerThrottlingEnabled");
-
-        if (ANativeWindow_setProducerThrottlingEnabled &&
-                ANativeWindow_isProducerThrottlingEnabled) {
-            mHasProducerThrottlingControl = true;
-            LOG(INFO) << "Producer Throttling API available";
-        }
-    }
 }
 
-PlatformEGLAndroid::~PlatformEGLAndroid() noexcept {
-    // 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().
-}
+PlatformEGLAndroid::~PlatformEGLAndroid() noexcept = default;
 
 void PlatformEGLAndroid::terminate() noexcept {
+    mAndroidFrameCallback.terminate();
     ExternalStreamManagerAndroid::destroy(&mExternalStreamManager);
     PlatformEGL::terminate();
 }
@@ -260,6 +240,8 @@ Driver* PlatformEGLAndroid::createDriver(void* sharedContext,
 
     mAssertNativeWindowIsValid = driverConfig.assertNativeWindowIsValid;
 
+    mAndroidFrameCallback.init();
+
     return driver;
 }
 
@@ -281,8 +263,14 @@ bool PlatformEGLAndroid::queryCompositorTiming(SwapChain const* swapchain,
         return false;
     }
 
+    AndroidFrameCallback::Timeline const preferredTimeline{
+            mAndroidFrameCallback.getPreferredTimeline() };
+    outCompositorTiming->frameTime = preferredTimeline.frameTime;
+    outCompositorTiming->expectedPresentTime = preferredTimeline.expectedPresentTime;
+    outCompositorTiming->frameTimelineDeadline = preferredTimeline.frameTimelineDeadline;
+
     if (UTILS_LIKELY(ext.egl.ANDROID_get_frame_timestamps)) {
-        EGLSurface sur = static_cast<SwapChainEGL const *>(swapchain)->sur;
+        EGLSurface const sur = static_cast<SwapChainEGL const *>(swapchain)->sur;
         if (sur == EGL_NO_SURFACE) {
             return false;
         }
@@ -365,8 +353,8 @@ bool PlatformEGLAndroid::queryFrameTimestamps(SwapChain const* swapchain, uint64
         outFrameTimestamps->requestedPresentTime = values[0];
         outFrameTimestamps->acquireTime = values[1];
         outFrameTimestamps->latchTime = values[2];
-        outFrameTimestamps->firstRefreshStartTime = values[3];
-        outFrameTimestamps->lastRefreshStartTime = values[4];
+        outFrameTimestamps->firstCompositionStartTime = values[3];
+        outFrameTimestamps->lastCompositionStartTime = values[4];
         outFrameTimestamps->gpuCompositionDoneTime = values[5];
         outFrameTimestamps->displayPresentTime = values[6];
         outFrameTimestamps->dequeueReadyTime = values[7];
@@ -380,8 +368,8 @@ bool PlatformEGLAndroid::queryFrameTimestamps(SwapChain const* swapchain, uint64
             &outFrameTimestamps->requestedPresentTime,
             &outFrameTimestamps->acquireTime,
             &outFrameTimestamps->latchTime,
-            &outFrameTimestamps->firstRefreshStartTime,
-            &outFrameTimestamps->lastRefreshStartTime,
+            &outFrameTimestamps->firstCompositionStartTime,
+            &outFrameTimestamps->lastCompositionStartTime,
             &outFrameTimestamps->gpuCompositionDoneTime,
             &outFrameTimestamps->displayPresentTime,
             &outFrameTimestamps->dequeueReadyTime,
@@ -419,12 +407,13 @@ Platform::ExternalImageHandle PlatformEGLAndroid::createExternalImage(
         auto const hardwareBuffer = const_cast<AHardwareBuffer*>(buffer);
         AHardwareBuffer_acquire(hardwareBuffer);
         p->aHardwareBuffer = hardwareBuffer;
-        p->sRGB = sRGB;
         AHardwareBuffer_Desc hardwareBufferDescription = {};
         AHardwareBuffer_describe(hardwareBuffer, &hardwareBufferDescription);
         p->height = hardwareBufferDescription.height;
         p->width = hardwareBufferDescription.width;
         auto const textureFormat = mapToFilamentFormat(hardwareBufferDescription.format, sRGB);
+        // Only set sRGB as true if the filament format requires it, otherwise the eglCreateImage might fail.
+        p->sRGB = textureFormat == TextureFormat::SRGB8 || textureFormat == TextureFormat::SRGB8_A8;
         p->format = textureFormat;
         p->usage = mapToFilamentUsage(hardwareBufferDescription.usage, textureFormat);
         return ExternalImageHandle{ p };
@@ -567,7 +556,15 @@ void PlatformEGLAndroid::destroyStream(Stream* stream) noexcept {
 }
 
 Platform::Sync* PlatformEGLAndroid::createSync() noexcept {
-    auto const sync = eglCreateSyncKHR(getEglDisplay(), EGL_SYNC_NATIVE_FENCE_ANDROID, nullptr);
+    EGLSyncKHR sync = EGL_NO_SYNC_KHR;
+    if (UTILS_LIKELY(ext.egl.ANDROID_native_fence_sync)) {
+        sync = eglCreateSyncKHR(getEglDisplay(), EGL_SYNC_NATIVE_FENCE_ANDROID, nullptr);
+        if (sync == EGL_NO_SYNC_KHR) {
+            LOG(ERROR) << "Failed to create sync: " << eglGetError();
+        }
+    } else {
+        LOG(WARNING) << "Native fences not supported on this device.";
+    }
     return new(std::nothrow) SyncEGLAndroid{ .sync = sync };
 }
 
@@ -575,10 +572,16 @@ bool PlatformEGLAndroid::convertSyncToFd(Sync* sync, int* fd) noexcept {
     assert_invariant(sync && fd);
 
     if (UTILS_UNLIKELY(!ext.egl.ANDROID_native_fence_sync)) {
+        LOG(WARNING) << "Native fences not supported, cannot convert to fd.";
         return false;
     }
 
     SyncEGLAndroid const& eglSync = static_cast<SyncEGLAndroid&>(*sync);
+    if (eglSync.sync == EGL_NO_SYNC_KHR) {
+        LOG(ERROR) << "Invalid fence, cannot convert to fd.";
+        return false;
+    }
+
     *fd = eglDupNativeFenceFDANDROID(getEglDisplay(), eglSync.sync);
     // In the case where there was no native FD, -1 is returned. Return false
     // to indicate there was an error in this case.
@@ -591,8 +594,12 @@ bool PlatformEGLAndroid::convertSyncToFd(Sync* sync, int* fd) noexcept {
 
 void PlatformEGLAndroid::destroySync(Sync* sync) noexcept {
     assert_invariant(sync);
-    SyncEGLAndroid const& eglSync = static_cast<SyncEGLAndroid&>(*sync);
-    eglDestroySyncKHR(getEglDisplay(), eglSync.sync);
+    if (UTILS_LIKELY(ext.egl.ANDROID_native_fence_sync)) {
+        SyncEGLAndroid const& eglSync = static_cast<SyncEGLAndroid&>(*sync);
+        if (eglSync.sync != EGL_NO_SYNC_KHR) {
+            eglDestroySyncKHR(getEglDisplay(), eglSync.sync);
+        }
+    }
     delete sync;
 }
 
@@ -666,6 +673,16 @@ AcquiredImage PlatformEGLAndroid::transformAcquiredImage(AcquiredImage const sou
     return { eglImage, patchedCallback, closure, source.handler };
 }
 
+
+bool PlatformEGLAndroid::isProducerThrottlingControlSupported() const {
+    return mProducerThrottling.isSupported();
+}
+
+int32_t PlatformEGLAndroid::setProducerThrottlingEnabled(
+    EGLNativeWindowType const nativeWindow, bool const enabled) const {
+    return mProducerThrottling.setProducerThrottlingEnabled(nativeWindow, enabled);
+}
+
 // ---------------------------------------------------------------------------------------------
 // PlatformEGLAndroid::SwapChainEGLAndroid
 
@@ -673,9 +690,9 @@ PlatformEGLAndroid::SwapChainEGLAndroid::SwapChainEGLAndroid(PlatformEGLAndroid
         void* nativeWindow, uint64_t const flags)
     : SwapChainEGL(platform, nativeWindow, flags) {
 
-    if (nativeWindow && platform.mHasProducerThrottlingControl) {
+    if (nativeWindow && platform.isProducerThrottlingControlSupported()) {
         // Disable Producer Throttling when supported. This allows eglSwapBuffers() to not stall
-        int32_t const result = platform.ANativeWindow_setProducerThrottlingEnabled(
+        int32_t const result = platform.setProducerThrottlingEnabled(
                 EGLNativeWindowType(nativeWindow), false);
         if (UTILS_UNLIKELY(result < 0)) {
             LOG(WARNING) << "ANativeWindow_setProducerThrottlingEnabled(false) failed: " << result;
@@ -702,6 +719,10 @@ void PlatformEGLAndroid::SwapChainEGLAndroid::terminate(PlatformEGLAndroid& plat
 }
 
 bool PlatformEGLAndroid::SwapChainEGLAndroid::setPresentFrameId(uint64_t frameId) const noexcept {
+    if (!nativeWindow) {
+        // nativeWindow is null in the headless case
+        return false;
+    }
     return mImpl.setPresentFrameId(nativeWindow, frameId);
 }
 

filament/backend/src/opengl/platforms/PlatformGLX.cpp

@@ -26,6 +26,8 @@
 
 #include <dlfcn.h>
 
+#include <mutex>
+
 #define LIBRARY_GLX "libGL.so.1"
 #define LIBRARY_X11 "libX11.so.6"
 

filament/backend/src/vulkan/BlitDepth.fs

@@ -1,19 +0,0 @@
-#version 320 es
-precision mediump float;
-
-precision lowp sampler2DMS;
-
-layout(set = 0, binding = 0, std140) uniform ParamsBlock {
-    int sampleCount;
-    float inverseSampleCount;
-} params;
-
-layout(set = 1, binding = 0) uniform sampler2DMS tex;
-
-void main() {
-    float depth = 0.0;
-    for (int sampleIndex = 0; sampleIndex < params.sampleCount; sampleIndex++) {
-        depth += texelFetch(tex, ivec2(gl_FragCoord.xy), sampleIndex).r;
-    }
-    gl_FragDepth = depth * params.inverseSampleCount;
-}

filament/backend/src/vulkan/BlitDepth.vs

@@ -1,7 +0,0 @@
-#version 320 es
-
-layout(location = 0) in vec4 pos;
-
-void main() {
-    gl_Position = pos;
-}

filament/backend/src/vulkan/VulkanAsyncHandles.cpp

@@ -29,30 +29,33 @@ using namespace bluevk;
 
 namespace filament::backend {
 
-FenceStatus VulkanCmdFence::wait(VkDevice device, uint64_t const timeout,
-    std::chrono::steady_clock::time_point const until) {
+FenceStatus VulkanCmdBufferState::waitOnFence(VkDevice device, uint64_t const timeout,
+        std::chrono::steady_clock::time_point const until) {
+    // this lock MUST be held for READ when calling vkWaitForFences()
+    std::shared_lock rl(mLock);
 
-    {
-        std::shared_lock l(mLock);
-
-        // If the vulkan fence has not been submitted yet, we need to wait for that before we
-        // can use vkWaitForFences()
-        if (mStatus == VK_INCOMPLETE) {
-            bool const success = mCond.wait_until(l, until, [this] {
-                // Internally we use the VK_INCOMPLETE status to mean "not yet submitted".
-                // When this fence gets submitted, its status changes to VK_NOT_READY.
-                return mStatus != VK_INCOMPLETE;
-            });
-            if (!success) {
-                // !success indicates a timeout
-                return FenceStatus::TIMEOUT_EXPIRED;
-            }
+    // If the vulkan fence has not been submitted yet, we need to wait for that before we
+    // can use vkWaitForFences()
+    if (mStatus == VK_INCOMPLETE) {
+        bool const success = mCond.wait_until(rl, until, [this] {
+            // Internally we use the VK_INCOMPLETE status to mean "not yet submitted".
+            // When this fence gets submitted, its status changes to VK_NOT_READY.
+            return mStatus != VK_INCOMPLETE || mCanceled;
+        });
+        if (!success) {
+            // !success indicates a timeout or cancel
+            return mCanceled ? FenceStatus::ERROR : FenceStatus::TIMEOUT_EXPIRED;
         }
+    }
 
-        // The fence could have already signaled, avoid calling into vkWaitForFences()
-        if (mStatus == VK_SUCCESS) {
-            return FenceStatus::CONDITION_SATISFIED;
-        }
+    // The fence could have already signaled, avoid calling into vkWaitForFences()
+    if (mStatus == VK_SUCCESS) {
+        return FenceStatus::CONDITION_SATISFIED;
+    }
+
+    // Or it could have been canceled, return immediately
+    if (mCanceled) {
+        return FenceStatus::ERROR;
     }
 
     // If we're here, we know that vkQueueSubmit has been called (because it sets the status
@@ -62,13 +65,14 @@ FenceStatus VulkanCmdFence::wait(VkDevice device, uint64_t const timeout,
     // place simultaneously. vkResetFence is only called once it knows the fence has signaled,
     // which guaranties that vkResetFence won't have to wait too long, just enough for
     // all the vkWaitForFences() to return.
-    VkResult status = vkWaitForFences(device, 1, &mFence, VK_TRUE, timeout);
+    VkResult const status = vkWaitForFences(device, 1, &mFence, VK_TRUE, timeout);
     if (status == VK_TIMEOUT) {
         return FenceStatus::TIMEOUT_EXPIRED;
     }
 
     if (status == VK_SUCCESS) {
-        std::lock_guard const l(mLock);
+        rl.unlock();
+        std::lock_guard const wl(mLock);
         mStatus = status;
         return FenceStatus::CONDITION_SATISFIED;
     }
@@ -76,7 +80,7 @@ FenceStatus VulkanCmdFence::wait(VkDevice device, uint64_t const timeout,
     return FenceStatus::ERROR; // not supported
 }
 
-void VulkanCmdFence::resetFence(VkDevice device) {
+void VulkanCmdBufferState::resetFence(VkDevice device) {
     // This lock prevents vkResetFences() from being called simultaneously with vkWaitForFences(),
     // but by construction, when we're here, we know that the fence has signaled and
     // vkWaitForFences() will return shortly.
@@ -85,4 +89,35 @@ void VulkanCmdFence::resetFence(VkDevice device) {
     vkResetFences(device, 1, &mFence);
 }
 
+uint64_t VulkanTimerQuery::getResult() {
+    {
+        std::lock_guard<std::mutex> lock(mDurationLock);
+        if (mDuration != UNKNOWN_QUERY_RESULT) {
+            return mDuration;
+        }
+    }
+
+    VulkanCmdBufferState* startState = nullptr;
+    VulkanCmdBufferState* endState = nullptr;
+    {
+        std::shared_lock const l(mMutex);
+        startState = mBeginState.get();
+        endState = mEndState.get();
+    }
+    // Here we sum up the time taken by each command buffer that were marked by this timer query.
+    uint64_t duration = 0;
+    do {
+        uint64_t const stDuration = startState->getBufferDuration();
+        assert_invariant(stDuration != VulkanCmdBufferState::UNKNOWN_BUFFER_DURATION);
+        duration += stDuration;
+        startState = startState->getNextState().get();
+    } while (startState != endState);
+
+    {
+        std::lock_guard<std::mutex> lock(mDurationLock);
+        mDuration = duration;
+    }
+    return duration;
+}
+
 } // namespace filament::backend

filament/backend/src/vulkan/VulkanAsyncHandles.h

@@ -27,6 +27,7 @@
 
 #include <chrono>
 #include <cstdint>
+#include <limits>
 #include <memory>
 #include <mutex>
 #include <shared_mutex>
@@ -35,69 +36,113 @@
 
 namespace filament::backend {
 
-// Wrapper to enable use of shared_ptr for implementing shared ownership of low-level Vulkan fences.
-struct VulkanCmdFence {
-    explicit VulkanCmdFence(VkFence fence) : mFence(fence) { }
-    ~VulkanCmdFence() = default;
+// Wrapper to enable use of shared_ptr for implementing shared ownership of Vulkan fences
+// and timer query results.
+struct VulkanCmdBufferState {
+    static uint64_t const UNKNOWN_BUFFER_DURATION = std::numeric_limits<uint64_t>::max();
 
-    void setStatus(VkResult const value) {
+    explicit VulkanCmdBufferState(VkFence fence)
+            : mFence(fence) {
+    }
+    ~VulkanCmdBufferState() = default;
+
+    void setStatus(VkResult const value, uint64_t duration) {
         std::lock_guard const l(mLock);
         mStatus = value;
+        mDuration = duration;
         mCond.notify_all();
     }
 
-    VkResult getStatus() {
+    uint64_t getBufferDuration() {
+        std::shared_lock const l(mLock);
+        return mDuration;
+    }
+
+    VkResult getFenceStatus() {
         std::shared_lock const l(mLock);
         return mStatus;
     }
 
     void resetFence(VkDevice device);
 
-    FenceStatus wait(VkDevice device, uint64_t timeout,
+    FenceStatus waitOnFence(VkDevice device, uint64_t timeout,
         std::chrono::steady_clock::time_point until);
 
+    void cancel() {
+        std::lock_guard const l(mLock);
+        mCanceled = true;
+        mCond.notify_all();
+    }
+
+    void setNextState(std::shared_ptr<VulkanCmdBufferState> next) {
+        mNextState = std::move(next);
+    }
+
+    std::shared_ptr<VulkanCmdBufferState>& getNextState() {
+        return mNextState;
+    }
+
+    VkFence getVkFence() const {
+        return mFence;
+    }
+
 private:
     std::shared_mutex mLock; // NOLINT(*-include-cleaner)
     std::condition_variable_any mCond;
+    bool mCanceled = false;
     // Internally we use the VK_INCOMPLETE status to mean "not yet submitted". When this fence
     // gets submitted, its status changes to VK_NOT_READY. Finally, when the GPU actually
     // finishes executing the command buffer, the status changes to VK_SUCCESS.
     VkResult mStatus{ VK_INCOMPLETE };
-    VkFence mFence;
+    VkFence const mFence;
+
+    uint64_t mDuration = UNKNOWN_BUFFER_DURATION;
+
+    // We assume that command buffers are serialized.  This will point to the state of the next
+    // buffer. This is necessary so that we can return total duration of multiple command buffers
+    // when a TimerQuery is requested by the front-end.
+    std::shared_ptr<VulkanCmdBufferState> mNextState;
 };
 
 struct VulkanFence : public HwFence, fvkmemory::ThreadSafeResource {
     VulkanFence() {}
 
-    void setFence(std::shared_ptr<VulkanCmdFence> fence) {
-        std::lock_guard lock(mState->lock);
-        mState->sharedFence = std::move(fence);
-        mState->cond.notify_all();
+    void setCmdBufferState(std::shared_ptr<VulkanCmdBufferState> state) {
+        std::lock_guard l(lock);
+        cmdbufState = std::move(state);
+        cond.notify_all();
     }
 
-    std::shared_ptr<VulkanCmdFence>& getSharedFence() {
-        std::lock_guard lock(mState->lock);
-        return mState->sharedFence;
+    std::shared_ptr<VulkanCmdBufferState>& getCmdBufferState() {
+        std::lock_guard l(lock);
+        return cmdbufState;
     }
 
-    std::shared_ptr<VulkanCmdFence> wait(std::chrono::steady_clock::time_point const until) {
-        // hold a reference so that our state doesn't disappear while we wait
-        std::shared_ptr state{ mState };
-        std::unique_lock lock(state->lock);
-        state->cond.wait_until(lock, until, [&state] { return bool(state->sharedFence); });
-        // here mSharedFence will be null if we timed out
-        return state->sharedFence;
+    std::pair<std::shared_ptr<VulkanCmdBufferState>, bool> wait(
+            std::chrono::steady_clock::time_point const until) {
+        std::unique_lock l(lock);
+        cond.wait_until(l, until, [&] { return bool(cmdbufState) || canceled; });
+        // here cmdbufState will be null if we timed out
+        return { cmdbufState, canceled };
     }
+
+    void cancel() const {
+        std::lock_guard const l(lock);
+        if (cmdbufState) {
+            cmdbufState->cancel();
+        }
+        canceled = true;
+        cond.notify_all();
+    }
+
 private:
-    struct State {
-        std::mutex lock;
-        std::condition_variable cond;
-        std::shared_ptr<VulkanCmdFence> sharedFence;
-    };
-    std::shared_ptr<State> mState{ std::make_shared<State>() };
+    mutable std::mutex lock;
+    mutable std::condition_variable cond;
+    mutable bool canceled = false;
+    std::shared_ptr<VulkanCmdBufferState> cmdbufState;
 };
 
-struct VulkanSync : fvkmemory::ThreadSafeResource, public HwSync {
+struct VulkanSync : public HwSync, fvkmemory::ThreadSafeResource {
     struct CallbackData {
         CallbackHandler* handler;
         Platform::SyncCallback cb;
@@ -111,38 +156,50 @@ struct VulkanSync : fvkmemory::ThreadSafeResource, public HwSync {
 };
 
 struct VulkanTimerQuery : public HwTimerQuery, fvkmemory::ThreadSafeResource {
-    VulkanTimerQuery(uint32_t startingIndex, uint32_t stoppingIndex)
-        : mStartingQueryIndex(startingIndex),
-          mStoppingQueryIndex(stoppingIndex) {}
 
-    void setFence(std::shared_ptr<VulkanCmdFence> fence) noexcept {
-        std::unique_lock const lock(mFenceMutex);
-        mFence = std::move(fence);
+    static decltype(VulkanCmdBufferState::UNKNOWN_BUFFER_DURATION) const
+            UNKNOWN_QUERY_RESULT = VulkanCmdBufferState::UNKNOWN_BUFFER_DURATION;
+
+    VulkanTimerQuery() {}
+
+    void setBeginState(std::shared_ptr<VulkanCmdBufferState> state) {
+        {
+            std::lock_guard const lock(mMutex);
+            mBeginState = std::move(state);
+        }
+        {
+            std::lock_guard<std::mutex> lock(mDurationLock);
+            mDuration = UNKNOWN_QUERY_RESULT;
+        }
+
     }
 
-    bool isCompleted() noexcept {
-        std::unique_lock const lock(mFenceMutex);
-        // QueryValue is a synchronous call and might occur before beginTimerQuery has written
-        // anything into the command buffer, which is an error according to the validation layer
-        // that ships in the Android NDK.  Even when AVAILABILITY_BIT is set, validation seems to
-        // require that the timestamp has at least been written into a processed command buffer.
-
-        // This fence indicates that the corresponding buffer has been completed.
-        return mFence && mFence->getStatus() == VK_SUCCESS;
+    void setEndState(std::shared_ptr<VulkanCmdBufferState> state) {
+        {
+            std::lock_guard const lock(mMutex);
+            mEndState = std::move(state);
+        }
+        {
+            std::lock_guard<std::mutex> lock(mDurationLock);
+            mDuration = UNKNOWN_QUERY_RESULT;
+        }
     }
 
-    uint32_t getStartingQueryIndex() const { return mStartingQueryIndex; }
-
-    uint32_t getStoppingQueryIndex() const {
-        return mStoppingQueryIndex;
+    bool isComplete() {
+        std::shared_lock const lock(mMutex);
+        return mBeginState && mEndState &&
+                mBeginState->getBufferDuration() != UNKNOWN_QUERY_RESULT &&
+                mEndState->getBufferDuration() != UNKNOWN_QUERY_RESULT;
     }
 
+    uint64_t getResult();
+
 private:
-    uint32_t mStartingQueryIndex;
-    uint32_t mStoppingQueryIndex;
-
-    std::shared_ptr<VulkanCmdFence> mFence;
-    utils::Mutex mFenceMutex;
+    std::shared_mutex mMutex; // NOLINT(*-include-cleaner)
+    std::mutex mDurationLock;
+    std::shared_ptr<VulkanCmdBufferState> mBeginState;
+    std::shared_ptr<VulkanCmdBufferState> mEndState;
+    uint64_t mDuration = UNKNOWN_QUERY_RESULT;
 };
 
 } // namespace filament::backend

filament/backend/src/vulkan/VulkanCommands.cpp

@@ -55,6 +55,22 @@ VkCommandBuffer createCommandBuffer(VkDevice device, VkCommandPool pool) {
     return cmdbuffer;
 }
 
+VkFence createFence(VkDevice device, VulkanContext const& context, VkCommandPool pool) {
+    VkFenceCreateInfo fenceCreateInfo{ .sType = VK_STRUCTURE_TYPE_FENCE_CREATE_INFO };
+    VkExportFenceCreateInfo exportFenceCreateInfo{
+        .sType = VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO,
+    };
+
+    // Necessary to guard this. Otherwise, swiftshader would throw an error.
+    if (context.getFenceExportFlags()) {
+        exportFenceCreateInfo.handleTypes = context.getFenceExportFlags(),
+        fenceCreateInfo.pNext = &exportFenceCreateInfo;
+    }
+    VkFence fence;
+    vkCreateFence(device, &fenceCreateInfo, VKALLOC, &fence);
+    return fence;
+}
+
 } // anonymous namespace
 
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS)
@@ -91,30 +107,21 @@ uint32_t VulkanCommandBuffer::sAgeCounter = 0;
 
 VulkanCommandBuffer::VulkanCommandBuffer(VulkanContext const& context, VkDevice device,
         VkQueue queue, VkCommandPool pool, VulkanSemaphoreManager* semaphoreManager,
-        bool isProtected)
-    : mContext(context),
-      mMarkerCount(0),
-      isProtected(isProtected),
-      mDevice(device),
-      mQueue(queue),
-      mSemaphoreManager(semaphoreManager),
-      mBuffer(createCommandBuffer(device, pool)),
-      mSubmission(semaphoreManager->acquire()),
-      mAge(++sAgeCounter) {
-    VkFenceCreateInfo fenceCreateInfo{.sType = VK_STRUCTURE_TYPE_FENCE_CREATE_INFO};
-    VkExportFenceCreateInfo exportFenceCreateInfo{
-        .sType = VK_STRUCTURE_TYPE_EXPORT_FENCE_CREATE_INFO,
-        .handleTypes = context.getFenceExportFlags()
-    };
-
-    // Necessary to guard this. Otherwise, swiftshader would throw an error.
-    if (context.getFenceExportFlags()) {
-        fenceCreateInfo.pNext = &exportFenceCreateInfo;
-    }
-    vkCreateFence(device, &fenceCreateInfo, VKALLOC, &mFence);
-
-    mFenceStatus = std::make_shared<VulkanCmdFence>(mFence);
-}
+        bool isProtected, uint32_t timerQueryIndex, VkQueryPool queryPool)
+        : mContext(context),
+          mMarkerCount(0),
+          isProtected(isProtected),
+          mDevice(device),
+          mQueue(queue),
+          mSemaphoreManager(semaphoreManager),
+          mBuffer(createCommandBuffer(device, pool)),
+          mSubmission(semaphoreManager->acquire()),
+          mFence(createFence(device, context, pool)),
+          mCmdbufState(std::make_shared<VulkanCmdBufferState>(mFence)),
+          mAge(++sAgeCounter),
+          mQueryBeginIndex(timerQueryIndex),
+          mQueryEndIndex(timerQueryIndex + 1),
+          mQueryPool(queryPool) {}
 
 VulkanCommandBuffer::~VulkanCommandBuffer() {
     vkDestroyFence(mDevice, mFence, VKALLOC);
@@ -129,12 +136,12 @@ void VulkanCommandBuffer::reset() noexcept {
     mSubmission = mSemaphoreManager->acquire();
 
     // reset the fence with proper host synchronization
-    mFenceStatus->resetFence(mDevice);
+    mCmdbufState->resetFence(mDevice);
 
     // Internally we use the VK_INCOMPLETE status to mean "not yet submitted". When this fence
     // gets, gets submitted, its status changes to VK_NOT_READY. Finally, when the GPU actually
     // finishes executing the command buffer, the status changes to VK_SUCCESS.
-    mFenceStatus = std::make_shared<VulkanCmdFence>(mFence);
+    mCmdbufState = std::make_shared<VulkanCmdBufferState>(mFence);
 }
 
 void VulkanCommandBuffer::pushMarker(char const* marker) noexcept {
@@ -191,6 +198,12 @@ void VulkanCommandBuffer::begin() noexcept {
         .flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT,
     };
     vkBeginCommandBuffer(mBuffer, &binfo);
+
+    // We need to reset the queries before writing to it. (This must happen within a command buffer,
+    // but not before the queries have occurred).
+    vkCmdResetQueryPool(mBuffer, mQueryPool, mQueryBeginIndex, 2);
+    vkCmdWriteTimestamp(mBuffer, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, mQueryPool,
+            mQueryBeginIndex);
 }
 
 fvkmemory::resource_ptr<VulkanSemaphore> VulkanCommandBuffer::submit() {
@@ -198,6 +211,9 @@ fvkmemory::resource_ptr<VulkanSemaphore> VulkanCommandBuffer::submit() {
         popMarker();
     }
 
+    vkCmdWriteTimestamp(mBuffer, VK_PIPELINE_STAGE_ALL_COMMANDS_BIT, mQueryPool,
+            mQueryEndIndex);
+
     vkEndCommandBuffer(mBuffer);
 
     VkSemaphore submissionSemaphore = mSubmission->getVkSemaphore();
@@ -236,7 +252,7 @@ fvkmemory::resource_ptr<VulkanSemaphore> VulkanCommandBuffer::submit() {
 
     UTILS_UNUSED_IN_RELEASE VkResult result =
         vkQueueSubmit(mQueue, 1, &submitInfo, mFence);
-    mFenceStatus->setStatus(VK_NOT_READY);
+    mCmdbufState->setStatus(VK_NOT_READY, VulkanCmdBufferState::UNKNOWN_BUFFER_DURATION);
 
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
     if (result != VK_SUCCESS) {
@@ -248,6 +264,45 @@ fvkmemory::resource_ptr<VulkanSemaphore> VulkanCommandBuffer::submit() {
     return mSubmission;
 }
 
+void VulkanCommandBuffer::setComplete() {
+    if (mCmdbufState->getBufferDuration() != VulkanCmdBufferState::UNKNOWN_BUFFER_DURATION) {
+        return;
+    }
+    // We always query the duration of this buffer on the GPU.  This is then used to inform timer
+    // queries from the Filament-side.  The reason for doing it this way is because the timestamp is
+    // consistent within a command buffer, but not guarranteed to be consistent outside of a command
+    // buffer. So we can only infer duration by looking at execution duration with respect to a
+    // buffer.
+    struct QueryResult {
+        uint64_t beginTime = 0;
+        uint64_t beginAvailable = 0;
+        uint64_t endTime = 0;
+        uint64_t endAvailable = 0;
+    } result;
+
+    constexpr size_t dataSize = sizeof(result);
+    constexpr VkDeviceSize stride = sizeof(uint64_t) * 2;
+    VkResult const vkresult =
+            vkGetQueryPoolResults(mDevice, mQueryPool, mQueryBeginIndex, 2, dataSize,
+                    (void*) &result, stride,
+                    VK_QUERY_RESULT_64_BIT | VK_QUERY_RESULT_WITH_AVAILABILITY_BIT);
+    FILAMENT_CHECK_POSTCONDITION(vkresult == VK_SUCCESS || vkresult == VK_NOT_READY)
+            << "vkGetQueryPoolResults error=" << static_cast<int32_t>(vkresult);
+
+    uint64_t const begin = result.beginTime;
+    uint64_t const end = result.endTime;
+    uint64_t duration = end - begin;
+
+    assert_invariant(result.beginAvailable != 0 && result.endAvailable != 0);
+    if (begin > end) {
+        FVK_LOGW << "Timestamps are not monotonically increasing. begin=" << begin <<
+                " end=" << end;
+        duration = begin - end;
+    }
+
+    mCmdbufState->setStatus(VK_SUCCESS, duration);
+}
+
 CommandBufferPool::CommandBufferPool(VulkanContext const& context, VkDevice device, VkQueue queue,
         uint8_t queueFamilyIndex, VulkanSemaphoreManager* semaphoreManager, bool isProtected)
     : mDevice(device),
@@ -259,11 +314,24 @@ CommandBufferPool::CommandBufferPool(VulkanContext const& context, VkDevice devi
                 (isProtected ? VK_COMMAND_POOL_CREATE_PROTECTED_BIT : 0u),
         .queueFamilyIndex = queueFamilyIndex,
     };
-    vkCreateCommandPool(device, &createInfo, VKALLOC, &mPool);
+    VkResult result = vkCreateCommandPool(device, &createInfo, VKALLOC, &mPool);
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateCommandPool failed."
+                                                       << " error=" << static_cast<int32_t>(result);
+
+    // Create a timestamp pool large enough to hold a pair of queries for each command buffer.
+    VkQueryPoolCreateInfo tqpCreateInfo = {
+        .sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
+        .queryType = VK_QUERY_TYPE_TIMESTAMP,
+        .queryCount = CAPACITY *2,
+    };
+    result = vkCreateQueryPool(mDevice, &tqpCreateInfo, VKALLOC, &mQueryPool);
+
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateQueryPool failed."
+                                                       << " error=" << static_cast<int32_t>(result);
 
     for (size_t i = 0; i < CAPACITY; ++i) {
-        mBuffers.emplace_back(std::make_unique<VulkanCommandBuffer>(
-                context, device, queue, mPool, semaphoreManager, isProtected));
+        mBuffers.emplace_back(std::make_unique<VulkanCommandBuffer>(context, device, queue, mPool,
+                semaphoreManager, isProtected, i * 2, mQueryPool));
     }
 }
 
@@ -271,6 +339,7 @@ CommandBufferPool::~CommandBufferPool() {
     wait();
     gc();
     vkDestroyCommandPool(mDevice, mPool, VKALLOC);
+    vkDestroyQueryPool(mDevice, mQueryPool, VKALLOC);
 }
 
 VulkanCommandBuffer& CommandBufferPool::getRecording() {
@@ -414,7 +483,7 @@ void VulkanCommands::terminate() {
     mPool.reset();
     mProtectedPool.reset();
     mLastSubmit = {};
-    mLastFenceStatus = {};
+    mLastBufferState = {};
 }
 
 VulkanCommandBuffer& VulkanCommands::get() {
@@ -443,8 +512,7 @@ bool VulkanCommands::flush() {
     fvkmemory::resource_ptr<VulkanSemaphore> dependency;
     bool hasFlushed = false;
 
-    VkFence flushedFence = VK_NULL_HANDLE;
-    std::shared_ptr<VulkanCmdFence> flushedFenceStatus;
+    std::shared_ptr<VulkanCmdBufferState> flushedBufferState;
 
     // Note that we've ordered it so that the non-protected commands are followed by the protected
     // commands.  This assumes that the protected commands will be that one doing the rendering into
@@ -467,8 +535,7 @@ bool VulkanCommands::flush() {
                     VK_PIPELINE_STAGE_FRAGMENT_SHADER_BIT | VK_PIPELINE_STAGE_TRANSFER_BIT);
             mLastSubmit = {};
         }
-        flushedFence = pool->getRecording().getVkFence();
-        flushedFenceStatus = pool->getRecording().getFenceStatus();
+        flushedBufferState = pool->getRecording().getState();
         dependency = pool->flush();
         hasFlushed = true;
     }
@@ -476,8 +543,11 @@ bool VulkanCommands::flush() {
     if (hasFlushed) {
         mInjectedDependency = VK_NULL_HANDLE;
         mLastSubmit = dependency;
-        mLastFence = flushedFence;
-        mLastFenceStatus = flushedFenceStatus;
+
+        if (mLastBufferState) {
+            mLastBufferState->setNextState(flushedBufferState);
+        }
+        mLastBufferState = flushedBufferState;
     }
 
     return true;

filament/backend/src/vulkan/VulkanCommands.h

@@ -42,6 +42,7 @@
 namespace filament::backend {
 
 using namespace fvkmemory;
+struct CommandBufferPool;
 
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS)
 class VulkanGroupMarkers {
@@ -65,7 +66,8 @@ private:
 // we're done waiting on the most recent submission of the given command buffer.
 struct VulkanCommandBuffer {
     VulkanCommandBuffer(VulkanContext const& mContext, VkDevice device, VkQueue queue,
-            VkCommandPool pool, VulkanSemaphoreManager* semaphoreManager, bool isProtected);
+            VkCommandPool pool, VulkanSemaphoreManager* semaphoreManager, bool isProtected,
+            uint32_t timerQueryIndex, VkQueryPool queryPool);
 
     VulkanCommandBuffer(VulkanCommandBuffer const&) = delete;
     VulkanCommandBuffer& operator=(VulkanCommandBuffer const&) = delete;
@@ -90,20 +92,14 @@ struct VulkanCommandBuffer {
     void begin() noexcept;
     fvkmemory::resource_ptr<VulkanSemaphore> submit();
 
-    inline void setComplete() {
-        mFenceStatus->setStatus(VK_SUCCESS);
-    }
+    void setComplete();
 
     VkResult getStatus() {
-        return mFenceStatus->getStatus();
+        return mCmdbufState->getFenceStatus();
     }
 
-    std::shared_ptr<VulkanCmdFence> getFenceStatus() const {
-        return mFenceStatus;
-    }
-
-    VkFence getVkFence() const {
-        return mFence;
+    std::shared_ptr<VulkanCmdBufferState> getState() const {
+        return mCmdbufState;
     }
 
     VkCommandBuffer buffer() const {
@@ -115,22 +111,31 @@ struct VulkanCommandBuffer {
     }
 
 private:
+    VkFence getVkFence() const {
+        return mFence;
+    }
+
     static uint32_t sAgeCounter;
 
     VulkanContext const& mContext;
     uint8_t mMarkerCount;
     bool const isProtected;
-    VkDevice mDevice;
-    VkQueue mQueue;
+    VkDevice const mDevice;
+    VkQueue const mQueue;
     VulkanSemaphoreManager* mSemaphoreManager;
     fvkutils::StaticVector<VkSemaphore, 2> mWaitSemaphores;
     fvkutils::StaticVector<VkPipelineStageFlags, 2> mWaitSemaphoreStages;
-    VkCommandBuffer mBuffer;
+    VkCommandBuffer const mBuffer;
     fvkmemory::resource_ptr<VulkanSemaphore> mSubmission;
-    VkFence mFence;
-    std::shared_ptr<VulkanCmdFence> mFenceStatus;
+    VkFence const mFence;
+    std::shared_ptr<VulkanCmdBufferState> mCmdbufState;
     std::vector<fvkmemory::resource_ptr<Resource>> mResources;
     uint32_t mAge;
+    uint32_t const mQueryBeginIndex;
+    uint32_t const mQueryEndIndex;
+    VkQueryPool const mQueryPool;
+
+    friend struct CommandBufferPool;
 };
 
 struct CommandBufferPool {
@@ -174,6 +179,8 @@ private:
     std::vector<std::unique_ptr<VulkanCommandBuffer>> mBuffers;
     int8_t mRecording;
 
+    VkQueryPool mQueryPool;
+
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS)
     std::unique_ptr<VulkanGroupMarkers> mGroupMarkers;
 #endif
@@ -199,7 +206,7 @@ private:
 //
 // - Allows off-thread queries of command buffer status.
 //    - Exposes an "updateFences" method that transfers current fence status into atomics.
-//    - Users can examine these atomic variables (see VulkanCmdFence) to determine status.
+//    - Users can examine these atomic variables (see VulkanCmdBufferState) to determine status.
 //    - We do this because vkGetFenceStatus must be called from the rendering thread.
 //
 class VulkanCommands {
@@ -230,12 +237,8 @@ public:
         return sem;
     }
 
-    VkFence getMostRecentFence() {
-        return mLastFence;
-    }
-
-    std::shared_ptr<VulkanCmdFence> getMostRecentFenceStatus() {
-        return mLastFenceStatus;
+    std::shared_ptr<VulkanCmdBufferState> getMostRecentBufferState() {
+        return mLastBufferState;
     }
 
     // Takes a semaphore that signals when the next flush can occur. Only one injected
@@ -276,8 +279,7 @@ private:
     VkSemaphore mInjectedDependency = VK_NULL_HANDLE;
     fvkmemory::resource_ptr<VulkanSemaphore> mLastSubmit;
 
-    VkFence mLastFence = VK_NULL_HANDLE;
-    std::shared_ptr<VulkanCmdFence> mLastFenceStatus;
+    std::shared_ptr<VulkanCmdBufferState> mLastBufferState;
 
     VkPipelineStageFlags mInjectedDependencyWaitStage = 0;
 };

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -45,6 +45,7 @@
 #endif
 
 #include <chrono>
+#include <mutex>
 
 using namespace bluevk;
 
@@ -240,7 +241,6 @@ VulkanDriver::VulkanDriver(VulkanPlatform* platform, VulkanContext& context,
       mReadPixels(mPlatform->getDevice()),
       mDescriptorSetLayoutCache(mPlatform->getDevice(), &mResourceManager),
       mDescriptorSetCache(mPlatform->getDevice(), &mResourceManager),
-      mQueryManager(mPlatform->getDevice()),
       mExternalImageManager(platform, &mSamplerCache, &mYcbcrConversionCache, &mDescriptorSetCache,
               &mDescriptorSetLayoutCache),
       mIsSRGBSwapChainSupported(mPlatform->getCustomization().isSRGBSwapChainSupported),
@@ -337,8 +337,6 @@ void VulkanDriver::terminate() {
     mDefaultRenderTarget = {};
     mPipelineState = {};
 
-    mQueryManager.terminate();
-
     mBlitter.terminate();
     mReadPixels.terminate();
 
@@ -419,6 +417,10 @@ void VulkanDriver::beginFrame(int64_t monotonic_clock_ns,
         int64_t refreshIntervalNs, uint32_t frameId) {
     FVK_PROFILE_MARKER(PROFILE_NAME_BEGINFRAME);
 
+    if (mCurrentSwapChain) { // This should be guaranteed
+        mPlatform->setPresentFrameId(mCurrentSwapChain->swapChain, frameId);
+    }
+
     // Check if any command have finished and reset all its used resources. The resources
     // wont be destroyed but their reference count will decreased if the command is already
     // completed.
@@ -855,32 +857,33 @@ void VulkanDriver::createFenceR(Handle<HwFence> fh, utils::ImmutableCString&& ta
         cmdbuf = &mCommands.get();
     }
     // Note at this point, the fence has already been constructed via createFenceS, so we just tag
-    // it with appropriate VulkanCmdFence, which is associated with the current, recording command
+    // it with appropriate VulkanCmdBufferState, which is associated with the current, recording command
     // buffer.
     auto fence = resource_ptr<VulkanFence>::cast(&mResourceManager, fh);
-    fence->setFence(cmdbuf->getFenceStatus());
+    fence->setCmdBufferState(cmdbuf->getState());
     mResourceManager.associateHandle(fh.getId(), std::move(tag));
 }
 
 void VulkanDriver::createSyncR(Handle<HwSync> sh, utils::ImmutableCString&& tag) {
     auto sync = resource_ptr<VulkanSync>::cast(&mResourceManager, sh);
     VkFence fence = VK_NULL_HANDLE;
-    std::shared_ptr<VulkanCmdFence> fenceStatus;
+    std::shared_ptr<VulkanCmdBufferState> cmdbufState;
     if (mCurrentRenderPass.commandBuffer) {
         VulkanCommandBuffer* cmdBuff = mCurrentRenderPass.commandBuffer;
-        fence = cmdBuff->getVkFence();
-        fenceStatus = cmdBuff->getFenceStatus();
+        cmdbufState = cmdBuff->getState();
+        fence = cmdbufState->getVkFence();
+
         // If we're currently recording, flush so that the fence only applies
         // to commands already issued.
         mCommands.flush();
     } else {
-        fence = mCommands.getMostRecentFence();
-        fenceStatus = mCommands.getMostRecentFenceStatus();
+        cmdbufState = mCommands.getMostRecentBufferState();
+        fence = cmdbufState->getVkFence();
     }
 
     {
         std::lock_guard<std::mutex> guard(sync->lock);
-        sync->sync = mPlatform->createSync(fence, fenceStatus);
+        sync->sync = mPlatform->createSync(fence, cmdbufState);
     }
 
     for (auto& cbData : sync->conversionCallbacks) {
@@ -915,10 +918,22 @@ void VulkanDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow,
             FVK_LOGW << "protected swapchain requested, but Platform does not support it";
         }
     }
+
+#if defined(__ANDROID__)
+    // on Android, disable producer throttling
+    if (mProducerThrottling.isSupported()) {
+        mProducerThrottling.setProducerThrottlingEnabled(
+                static_cast<ANativeWindow*>(nativeWindow), false);
+    }
+#endif
+
     auto swapChain = resource_ptr<VulkanSwapChain>::make(&mResourceManager, sch, mPlatform,
             mContext, &mResourceManager, mAllocator, &mCommands, mStagePool, nativeWindow, flags);
     swapChain.inc();
     mResourceManager.associateHandle(sch.getId(), std::move(tag));
+
+    std::unique_lock<std::mutex> lock(mTiming.lock);
+    mTiming.nativeSwapchains.emplace(sch.getId(), swapChain->swapChain);
 }
 
 void VulkanDriver::createSwapChainHeadlessR(Handle<HwSwapChain> sch, uint32_t width,
@@ -1058,9 +1073,10 @@ Handle<HwSwapChain> VulkanDriver::createSwapChainHeadlessS() noexcept {
 Handle<HwTimerQuery> VulkanDriver::createTimerQueryS() noexcept {
     // The handle must be constructed here, as a synchronous call to getTimerQueryValue might happen
     // before createTimerQueryR is executed.
-    auto query = mQueryManager.getNextQuery(&mResourceManager);
+    auto handle = mResourceManager.allocHandle<VulkanTimerQuery>();
+    auto query = resource_ptr<VulkanTimerQuery>::make(&mResourceManager, handle);
     query.inc();
-    return Handle<VulkanTimerQuery>(query.id());
+    return handle;
 }
 
 Handle<HwDescriptorSetLayout> VulkanDriver::createDescriptorSetLayoutS() noexcept {
@@ -1093,6 +1109,9 @@ void VulkanDriver::destroySwapChain(Handle<HwSwapChain> sch) {
         mCurrentSwapChain = {};
     }
     swapChain.dec();
+
+    std::unique_lock<std::mutex> lock(mTiming.lock);
+    mTiming.nativeSwapchains.erase(sch.getId());
 }
 
 void VulkanDriver::destroyStream(Handle<HwStream> sh) {
@@ -1114,7 +1133,6 @@ void VulkanDriver::destroyTimerQuery(Handle<HwTimerQuery> tqh) {
         return;
     }
     auto vtq = resource_ptr<VulkanTimerQuery>::cast(&mResourceManager, tqh);
-    mQueryManager.clearQuery(vtq);
     vtq.dec();
 }
 
@@ -1155,8 +1173,19 @@ void VulkanDriver::updateStreams(CommandStream* driver) {
 }
 
 void VulkanDriver::destroyFence(Handle<HwFence> fh) {
+    if (fh) {
+        auto fence = resource_ptr<VulkanFence>::cast(&mResourceManager, 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.
+        fence.dec();
+    }
+}
+
+void VulkanDriver::fenceCancel(FenceHandle const fh) {
+    // Even though this is a synchronous call, the fence handle must be (and stay) valid
+    assert_invariant(fh);
     auto fence = resource_ptr<VulkanFence>::cast(&mResourceManager, fh);
-    fence.dec();
+    fence->cancel();
 }
 
 FenceStatus VulkanDriver::getFenceStatus(Handle<HwFence> const fh) {
@@ -1164,6 +1193,8 @@ FenceStatus VulkanDriver::getFenceStatus(Handle<HwFence> const fh) {
 }
 
 FenceStatus VulkanDriver::fenceWait(FenceHandle const 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 = resource_ptr<VulkanFence>::cast(&mResourceManager, fh);
 
     // we have to take into account that the STL's wait_for() actually works with
@@ -1180,14 +1211,14 @@ FenceStatus VulkanDriver::fenceWait(FenceHandle const fh, uint64_t const timeout
         until = now + nanoseconds(timeout);
     }
 
-    std::shared_ptr const cmdfence = fence->wait(until);
-    if (!cmdfence) {
-        return FenceStatus::TIMEOUT_EXPIRED;
+    auto const [cmdbufState, canceled] = fence->wait(until);
+    if (!cmdbufState || canceled) {
+        return canceled ? FenceStatus::ERROR : FenceStatus::TIMEOUT_EXPIRED;
     }
 
-    // now we are holding a reference to our VulkanCmdFence, so we know it can't
+    // now we are holding a reference to our VulkanCmdBufferState, so we know it can't
     // disappear while we wait
-    return cmdfence->wait(mPlatform->getDevice(), timeout, until);
+    return cmdbufState->waitOnFence(mPlatform->getDevice(), timeout, until);
 }
 
 void VulkanDriver::getPlatformSync(Handle<HwSync> sh, CallbackHandler* handler,
@@ -1484,29 +1515,17 @@ void VulkanDriver::setupExternalImage(void* image) {
 
 TimerQueryResult VulkanDriver::getTimerQueryValue(Handle<HwTimerQuery> tqh, uint64_t* elapsedTime) {
     auto vtq = resource_ptr<VulkanTimerQuery>::cast(&mResourceManager, tqh);
-    if (!vtq->isCompleted()) {
+    if (!vtq->isComplete()) {
         return TimerQueryResult::NOT_READY;
     }
-
-    auto results = mQueryManager.getResult(vtq);
-    if (results.beginAvailable == 0 || results.endAvailable == 0) {
-        return TimerQueryResult::NOT_READY;
-    }
-
-    uint64_t const begin = results.beginTime;
-    uint64_t const end = results.endTime;
-    if (begin >= end) {
-        // TODO: queries might have ran on different command buffers.
-        FVK_LOGW << "Timestamps are not monotonically increasing. ";
-        *elapsedTime = 0;
-        return TimerQueryResult::ERROR;
-    }
+    uint64_t result = vtq->getResult();
+    assert_invariant(result != VulkanTimerQuery::UNKNOWN_QUERY_RESULT);
 
     // NOTE: MoltenVK currently writes system time so the following delta will always be zero.
     // However there are plans for implementing this properly. See the following GitHub ticket.
     // https://github.com/KhronosGroup/MoltenVK/issues/773
     float const period = mContext.getPhysicalDeviceLimits().timestampPeriod;
-    *elapsedTime = uint64_t(float(end - begin) * period);
+    *elapsedTime = uint64_t(float(result) * period);
     return TimerQueryResult::AVAILABLE;
 }
 
@@ -1759,6 +1778,43 @@ void VulkanDriver::nextSubpass(int) {
     }
 }
 
+bool VulkanDriver::isCompositorTimingSupported() {
+    return mPlatform->isCompositorTimingSupported();
+}
+
+bool VulkanDriver::queryCompositorTiming(Handle<HwSwapChain> const swapChain,
+        CompositorTiming* outCompositorTiming) {
+    // this is a synchronous call
+    if (!swapChain) {
+        return false;
+    }
+
+    HandleId const id = swapChain.getId();
+    std::unique_lock<std::mutex> lock(mTiming.lock);
+    auto& swapchains = mTiming.nativeSwapchains;
+    if (auto itr = swapchains.find(id); itr != swapchains.end()) {
+        lock.unlock();
+        return mPlatform->queryCompositorTiming(itr->second, outCompositorTiming);
+    }
+    return false;
+}
+
+bool VulkanDriver::queryFrameTimestamps(Handle<HwSwapChain> const swapChain, uint64_t const frameId,
+        FrameTimestamps* outFrameTimestamps) {
+    // this is a synchronous call
+    if (!swapChain) {
+        return false;
+    }
+    HandleId const id = swapChain.getId();
+    std::unique_lock<std::mutex> lock(mTiming.lock);
+    auto& swapchains = mTiming.nativeSwapchains;
+    if (auto itr = swapchains.find(id); itr != swapchains.end()) {
+        lock.unlock();
+        return mPlatform->queryFrameTimestamps(itr->second, frameId, outFrameTimestamps);
+    }
+    return false;
+}
+
 void VulkanDriver::makeCurrent(Handle<HwSwapChain> drawSch, Handle<HwSwapChain> readSch) {
     FVK_SYSTRACE_SCOPE();
 
@@ -2228,12 +2284,14 @@ void VulkanDriver::scissor(Viewport scissorBox) {
 
 void VulkanDriver::beginTimerQuery(Handle<HwTimerQuery> tqh) {
     auto vtq = resource_ptr<VulkanTimerQuery>::cast(&mResourceManager, tqh);
-    mQueryManager.beginQuery(&(mCommands.get()), vtq);
+    auto cmdbuf = &mCommands.get();
+    vtq->setBeginState(cmdbuf->getState());
 }
 
 void VulkanDriver::endTimerQuery(Handle<HwTimerQuery> tqh) {
     auto vtq = resource_ptr<VulkanTimerQuery>::cast(&mResourceManager, tqh);
-    mQueryManager.endQuery(&(mCommands.get()), vtq);
+    auto cmdbuf = &mCommands.get();
+    vtq->setEndState(cmdbuf->getState());
 }
 
 void VulkanDriver::debugCommandBegin(CommandStream* cmds, bool synchronous, const char* methodName) noexcept {

filament/backend/src/vulkan/VulkanDriver.h

@@ -25,7 +25,6 @@
 #include "VulkanHandles.h"
 #include "VulkanMemory.h"
 #include "VulkanPipelineCache.h"
-#include "VulkanQueryManager.h"
 #include "VulkanReadPixels.h"
 #include "VulkanSamplerCache.h"
 #include "VulkanSemaphoreManager.h"
@@ -48,6 +47,10 @@
 #include <utils/Allocator.h>
 #include <utils/compiler.h>
 
+#if defined(__ANDROID__)
+#include "AndroidNativeWindow.h"
+#endif
+
 namespace filament::backend {
 
 class VulkanPlatform;
@@ -155,9 +158,17 @@ private:
     VulkanReadPixels mReadPixels;
     VulkanDescriptorSetLayoutCache mDescriptorSetLayoutCache;
     VulkanDescriptorSetCache mDescriptorSetCache;
-    VulkanQueryManager mQueryManager;
     VulkanExternalImageManager mExternalImageManager;
 
+    // This maps a VulkanSwapchain to a native swapchain. VulkanSwapchain should have a copy of the
+    // Platform::Swapchain pointer, but queryFrameTimestamps() and queryCompositorTiming() are
+    // synchronous calls, making access to VulkanSwapchain unsafe (this difference vs other backends
+    // is due to the ref-counting of vulkan resources).
+    struct {
+        std::mutex lock;
+        std::unordered_map<HandleId, Platform::SwapChain*> nativeSwapchains;
+    } mTiming;
+
     // This is necessary for us to write to push constants after binding a pipeline.
     using DescriptorSetLayoutHandleList = std::array<resource_ptr<VulkanDescriptorSetLayout>,
             VulkanDescriptorSetLayout::UNIQUE_DESCRIPTOR_SET_COUNT>;
@@ -193,6 +204,9 @@ private:
     bool const mIsSRGBSwapChainSupported;
     bool const mIsMSAASwapChainSupported;
     backend::StereoscopicType const mStereoscopicType;
+#if defined(__ANDROID__)
+    AndroidProducerThrottling mProducerThrottling;
+#endif
 };
 
 } // namespace filament::backend

filament/backend/src/vulkan/VulkanQueryManager.cpp

@@ -1,106 +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.
- */
-
-#include "VulkanQueryManager.h"
-
-#include "VulkanAsyncHandles.h"
-#include "VulkanCommands.h"
-#include "VulkanConstants.h"
-
-#include <bluevk/BlueVK.h>
-
-namespace filament::backend {
-
-using namespace bluevk;
-
-VulkanQueryManager::VulkanQueryManager(VkDevice device) : mDevice(device) {
-    // Create a timestamp pool large enough to hold a pair of queries for each timer.
-    VkQueryPoolCreateInfo tqpCreateInfo = {
-        .sType = VK_STRUCTURE_TYPE_QUERY_POOL_CREATE_INFO,
-        .queryType = VK_QUERY_TYPE_TIMESTAMP,
-        .queryCount = (uint32_t) mUsed.size() * 2,
-    };
-    VkResult result = vkCreateQueryPool(mDevice, &tqpCreateInfo, VKALLOC, &mPool);
-    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateQueryPool failed."
-                                                       << " error=" << static_cast<int32_t>(result);
-}
-
-fvkmemory::resource_ptr<VulkanTimerQuery> VulkanQueryManager::getNextQuery(
-        fvkmemory::ResourceManager* resourceManager) {
-    auto unused = ~mUsed;
-    if (unused.empty()) {
-        FVK_LOGE << "More than " << mUsed.size() << " timers are not supported.";
-        return {};
-    }
-
-    std::pair<uint32_t, uint32_t> queryIndices;
-    size_t const firstUnused = unused.firstSetBit();
-    {
-        std::unique_lock<utils::Mutex> lock(mMutex);
-        mUsed.set(firstUnused);
-        queryIndices = { firstUnused * 2, firstUnused * 2 + 1 };
-    }
-    return fvkmemory::resource_ptr<VulkanTimerQuery>::construct(resourceManager, queryIndices.first,
-            queryIndices.second);
-}
-
-void VulkanQueryManager::clearQuery(fvkmemory::resource_ptr<VulkanTimerQuery> query) {
-    std::unique_lock<utils::Mutex> lock(mMutex);
-    uint32_t const startingIndex = query->getStartingQueryIndex();
-    mUsed.unset(startingIndex / 2);
-}
-
-void VulkanQueryManager::beginQuery(VulkanCommandBuffer const* commands,
-        fvkmemory::resource_ptr<VulkanTimerQuery> query) {
-    uint32_t const index = query->getStartingQueryIndex();
-
-    auto const cmdbuffer = commands->buffer();
-    vkCmdResetQueryPool(cmdbuffer, mPool, index, 2);
-    vkCmdWriteTimestamp(cmdbuffer, VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, mPool, index);
-
-    // We stash this because getResult might come before the query is actually processed.
-    query->setFence(commands->getFenceStatus());
-}
-
-void VulkanQueryManager::endQuery(VulkanCommandBuffer const* commands,
-        fvkmemory::resource_ptr<VulkanTimerQuery> query) {
-    uint32_t const index = query->getStoppingQueryIndex();
-    vkCmdWriteTimestamp(commands->buffer(), VK_PIPELINE_STAGE_BOTTOM_OF_PIPE_BIT, mPool, index);
-}
-
-VulkanQueryManager::QueryResult VulkanQueryManager::getResult(
-        fvkmemory::resource_ptr<VulkanTimerQuery> query) {
-    uint32_t const index = query->getStartingQueryIndex();
-    QueryResult result;
-    size_t const dataSize = sizeof(result);
-    VkDeviceSize const stride = sizeof(uint64_t) * 2;
-    VkResult vkresult =
-            vkGetQueryPoolResults(mDevice, mPool, index, 2, dataSize, (void*) &result, stride,
-                    VK_QUERY_RESULT_64_BIT | VK_QUERY_RESULT_WITH_AVAILABILITY_BIT);
-    FILAMENT_CHECK_POSTCONDITION(vkresult == VK_SUCCESS || vkresult == VK_NOT_READY)
-            << "vkGetQueryPoolResults error=" << static_cast<int32_t>(vkresult);
-    if (vkresult == VK_NOT_READY) {
-        return {};
-    }
-    return result;
-}
-
-void VulkanQueryManager::terminate() noexcept {
-    vkDestroyQueryPool(mDevice, mPool, VKALLOC);
-    mPool = VK_NULL_HANDLE;
-}
-
-} // filament::backend

filament/backend/src/vulkan/VulkanQueryManager.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_VULKANQUERYMANAGER_H
-#define TNT_FILAMENT_BACKEND_VULKANQUERYMANAGER_H
-
-#include "vulkan/memory/ResourcePointer.h"
-
-namespace filament::backend {
-
-struct VulkanCommandBuffer;
-struct VulkanTimerQuery;
-
-class VulkanQueryManager {
-public:
-    struct QueryResult {
-        uint64_t beginTime = 0;
-        uint64_t beginAvailable = 0;
-        uint64_t endTime = 0;
-        uint64_t endAvailable = 0;
-    };
-
-    VulkanQueryManager(VkDevice device);
-    ~VulkanQueryManager() = default;
-
-    // Not copy-able.
-    VulkanQueryManager(VulkanQueryManager const&) = delete;
-    VulkanQueryManager& operator=(VulkanQueryManager const&) = delete;
-
-    fvkmemory::resource_ptr<VulkanTimerQuery>
-            getNextQuery(fvkmemory::ResourceManager* mResourceManager);
-    void clearQuery(fvkmemory::resource_ptr<VulkanTimerQuery> query);
-    void beginQuery(VulkanCommandBuffer const* commands,
-            fvkmemory::resource_ptr<VulkanTimerQuery> query);
-    void endQuery(VulkanCommandBuffer const* commands,
-            fvkmemory::resource_ptr<VulkanTimerQuery> query);
-    QueryResult getResult(fvkmemory::resource_ptr<VulkanTimerQuery> query);
-
-    void terminate() noexcept;
-
-private:
-    VkDevice mDevice;
-    VkQueryPool mPool;
-    utils::bitset32 mUsed;
-    utils::Mutex mMutex;
-};
-
-} // filament::backend
-
-#endif // TNT_FILAMENT_BACKEND_VULKANQUERYMANAGER_H

filament/backend/src/vulkan/VulkanSwapChain.h

@@ -35,8 +35,6 @@ using namespace bluevk;
 
 namespace filament::backend {
 
-struct VulkanHeadlessSwapChain;
-struct VulkanSurfaceSwapChain;
 class VulkanCommands;
 
 // A wrapper around the platform implementation of swapchain.

filament/backend/src/vulkan/platform/VulkanPlatform.cpp

@@ -966,12 +966,12 @@ SwapChainPtr VulkanPlatform::createSwapChain(void* nativeWindow, uint64_t flags,
     // The VulkanPlatformSurfaceSwapChain now `owns` the surface.
     VulkanPlatformSurfaceSwapChain* swapchain = new VulkanPlatformSurfaceSwapChain(mImpl->mContext,
             mImpl->mPhysicalDevice, mImpl->mDevice, mImpl->mGraphicsQueue, mImpl->mInstance,
-            surface, fallbackExtent, flags);
+            surface, fallbackExtent, nativeWindow, flags);
     return swapchain;
 }
 
 Platform::Sync* VulkanPlatform::createSync(VkFence fence,
-        std::shared_ptr<VulkanCmdFence> fenceStatus) noexcept {
+        std::shared_ptr<VulkanCmdBufferState> fenceStatus) noexcept {
     return new VulkanSync{.fence = fence, .fenceStatus = fenceStatus};
 }
 
@@ -1022,13 +1022,4 @@ VkExternalFenceHandleTypeFlagBits VulkanPlatform::getFenceExportFlags() const no
     return static_cast<VkExternalFenceHandleTypeFlagBits>(0);
 }
 
-ExtensionSet VulkanPlatform::getSwapchainInstanceExtensions() const {
-    return getSwapchainInstanceExtensionsImpl();
-}
-
-VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWindow,
-        VkInstance instance, uint64_t flags) const noexcept {
-    return createVkSurfaceKHRImpl(nativeWindow, instance, flags);
-}
-
-}// namespace filament::backend
+} // namespace filament::backend

filament/backend/src/vulkan/platform/VulkanPlatformAndroid.cpp

@@ -17,15 +17,18 @@
 
 #include "vulkan/VulkanConstants.h"
 #include "vulkan/VulkanContext.h"
+#include "vulkan/platform/VulkanPlatformSwapChainImpl.h"
+#include "vulkan/utils/Image.h"
 
-#include <backend/DriverEnums.h>
 #include <private/backend/BackendUtilsAndroid.h>
 
+#include <backend/DriverEnums.h>
+
 #include <utils/Panic.h>
-#include "vulkan/utils/Image.h"
 
 #include <bluevk/BlueVK.h>
 
+#include <android/api-level.h>
 #include <android/hardware_buffer.h>
 #include <android/native_window.h>
 
@@ -165,6 +168,15 @@ VulkanPlatformAndroid::ExternalImageVulkanAndroid::~ExternalImageVulkanAndroid()
     }
 }
 
+VulkanPlatformAndroid::VulkanPlatformAndroid() {
+    mOSVersion = android_get_device_api_level();
+    if (mOSVersion < 0) {
+        mOSVersion = __ANDROID_API_FUTURE__;
+    }
+}
+
+VulkanPlatformAndroid::~VulkanPlatformAndroid() noexcept = default;
+
 Platform::ExternalImageHandle VulkanPlatformAndroid::createExternalImage(
         AHardwareBuffer const* buffer, bool sRGB) noexcept {
     if (__builtin_available(android 26, *)) {
@@ -395,7 +407,7 @@ bool VulkanPlatformAndroid::convertSyncToFd(Platform::Sync* sync, int* fd) const
     VulkanSync& vulkanSync = static_cast<VulkanSync&>(*sync);
     assert_invariant(vulkanSync.fenceStatus);
 
-    if (vulkanSync.fenceStatus->getStatus() == VK_SUCCESS) {
+    if (vulkanSync.fenceStatus->getFenceStatus() == VK_SUCCESS) {
         // We've already signaled; return -1 so that operations will proceed
         // immediately. Also, signal that fence conversion was successful.
         *fd = -1;
@@ -442,12 +454,52 @@ VulkanPlatform::SurfaceBundle VulkanPlatformAndroid::createVkSurfaceKHR(void* na
     return { surface, extent };
 }
 
-// Deprecated platform dependent helper methods
-VulkanPlatform::ExtensionSet VulkanPlatform::getSwapchainInstanceExtensionsImpl() { return {}; }
+int VulkanPlatformAndroid::getOSVersion() const noexcept {
+    return mOSVersion;
+}
 
-VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHRImpl(void* nativeWindow,
-        VkInstance instance, uint64_t flags) noexcept {
-    return SurfaceBundle{};
+void VulkanPlatformAndroid::terminate() {
+    mAndroidFrameCallback.terminate();
+    VulkanPlatform::terminate();
+}
+
+Driver* VulkanPlatformAndroid::createDriver(void* sharedContext, DriverConfig const& driverConfig) {
+    Driver* driver = VulkanPlatform::createDriver(sharedContext, driverConfig);
+    if (driver) {
+        mAndroidFrameCallback.init();
+    }
+    return driver;
+}
+
+bool VulkanPlatformAndroid::isCompositorTimingSupported() const noexcept {
+    return true;
+}
+
+bool VulkanPlatformAndroid::queryCompositorTiming(SwapChain const* swapchain,
+        CompositorTiming* outCompositorTiming) const noexcept {
+    if (!swapchain) {
+        return false;
+    }
+
+    AndroidFrameCallback::Timeline const preferredTimeline{
+        mAndroidFrameCallback.getPreferredTimeline() };
+    outCompositorTiming->frameTime = preferredTimeline.frameTime;
+    outCompositorTiming->expectedPresentTime = preferredTimeline.expectedPresentTime;
+    outCompositorTiming->frameTimelineDeadline = preferredTimeline.frameTimelineDeadline;
+
+    auto vulkanSwapchain = static_cast<VulkanPlatformSwapChainBase const *>(swapchain);
+    return vulkanSwapchain->queryCompositorTiming(outCompositorTiming);
+}
+
+bool VulkanPlatformAndroid::setPresentFrameId(SwapChain const* swapchain, uint64_t frameId) noexcept {
+    auto vulkanSwapchain = static_cast<VulkanPlatformSwapChainBase const *>(swapchain);
+    return vulkanSwapchain->setPresentFrameId(frameId);
+}
+
+bool VulkanPlatformAndroid::queryFrameTimestamps(SwapChain const* swapchain, uint64_t frameId,
+        FrameTimestamps* outFrameTimestamps) const noexcept {
+    auto vulkanSwapchain = static_cast<VulkanPlatformSwapChainBase const *>(swapchain);
+    return vulkanSwapchain->queryFrameTimestamps(frameId, outFrameTimestamps);
 }
 
 } // namespace filament::backend

filament/backend/src/vulkan/platform/VulkanPlatformApple.mm

@@ -14,10 +14,9 @@
  * limitations under the License.
  */
 
-#include <backend/platforms/VulkanPlatform.h>
+#include <backend/platforms/VulkanPlatformApple.h>
 
 #include "vulkan/VulkanConstants.h"
-#include "vulkan/VulkanDriverFactory.h"
 
 #include <utils/Panic.h>
 
@@ -36,15 +35,15 @@ using namespace bluevk;
 
 namespace filament::backend {
 
-VulkanPlatform::ExtensionSet VulkanPlatform::getSwapchainInstanceExtensionsImpl() {
+VulkanPlatform::ExtensionSet VulkanPlatformApple::getSwapchainInstanceExtensions() const {
     ExtensionSet const ret = {
         VK_EXT_METAL_SURFACE_EXTENSION_NAME,
     };
     return ret;
 }
 
-VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHRImpl(void* nativeWindow,
-        VkInstance instance, uint64_t flags) noexcept {
+VulkanPlatform::SurfaceBundle VulkanPlatformApple::createVkSurfaceKHR(void* nativeWindow,
+        VkInstance instance, uint64_t flags) const noexcept {
     VkSurfaceKHR surface;
     CAMetalLayer* mlayer = (__bridge CAMetalLayer*) nativeWindow;
     FILAMENT_CHECK_POSTCONDITION(mlayer) << "Unable to obtain Metal-backed layer.";

filament/backend/src/vulkan/platform/VulkanPlatformLinux.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023 The Android Open Source Project
+ * 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.
@@ -14,11 +14,10 @@
  * limitations under the License.
  */
 
-#include <backend/platforms/VulkanPlatform.h>
+#include <backend/platforms/VulkanPlatformLinux.h>
 #include <backend/DriverEnums.h>
 
 #include "vulkan/VulkanConstants.h"
-#include "vulkan/VulkanDriverFactory.h"
 
 #include <utils/Panic.h>
 
@@ -74,17 +73,13 @@
             void* library = nullptr;
         } g_x11_vk;
     }// anonymous namespace
-#elif defined(WIN32)
-    // No platform specific includes
-#else
-    // Not a supported Vulkan platform
 #endif
 
 using namespace bluevk;
 
 namespace filament::backend {
 
-VulkanPlatform::ExtensionSet VulkanPlatform::getSwapchainInstanceExtensionsImpl() {
+VulkanPlatform::ExtensionSet VulkanPlatformLinux::getSwapchainInstanceExtensions() const {
     VulkanPlatform::ExtensionSet const ret = {
 #if defined(__linux__) && defined(FILAMENT_SUPPORTS_WAYLAND)
         VK_KHR_WAYLAND_SURFACE_EXTENSION_NAME,
@@ -95,15 +90,13 @@ VulkanPlatform::ExtensionSet VulkanPlatform::getSwapchainInstanceExtensionsImpl(
     #if defined(FILAMENT_SUPPORTS_XLIB)
         VK_KHR_XLIB_SURFACE_EXTENSION_NAME,
     #endif
-#elif defined(WIN32)
-        VK_KHR_WIN32_SURFACE_EXTENSION_NAME,
 #endif
     };
     return ret;
 }
 
-VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHRImpl(void* nativeWindow,
-        VkInstance instance, uint64_t flags) noexcept {
+VulkanPlatform::SurfaceBundle VulkanPlatformLinux::createVkSurfaceKHR(void* nativeWindow,
+        VkInstance instance, uint64_t flags) const noexcept {
     VkSurfaceKHR surface;
 
     // On certain platforms, the extent of the surface cannot be queried from Vulkan. In those
@@ -182,26 +175,6 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHRImpl(void* nativ
                         << "vkCreateXlibSurfaceKHR error=" << static_cast<int32_t>(result);
             }
         #endif
-    #elif defined(WIN32)
-        // On (at least) NVIDIA drivers, the Vulkan implementation (specifically the call to
-        // vkGetPhysicalDeviceSurfaceCapabilitiesKHR()) does not correctly handle the fact that
-        // each native window has its own DPI_AWARENESS_CONTEXT, and erroneously uses the context
-        // of the calling thread. As a workaround, we set the current thread's DPI_AWARENESS_CONTEXT
-        // to that of the native window we've been given. This isn't a perfect solution, because an
-        // application could create swap chains on multiple native windows with varying DPI-awareness,
-        // but even then, at least one of the windows would be guaranteed to work correctly.
-        SetThreadDpiAwarenessContext(GetWindowDpiAwarenessContext((HWND) nativeWindow));
-
-        VkWin32SurfaceCreateInfoKHR const createInfo = {
-            .sType = VK_STRUCTURE_TYPE_WIN32_SURFACE_CREATE_INFO_KHR,
-            .hinstance = GetModuleHandle(nullptr),
-            .hwnd = (HWND) nativeWindow,
-        };
-        VkResult const result = vkCreateWin32SurfaceKHR(instance, &createInfo, nullptr,
-                (VkSurfaceKHR*) &surface);
-        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
-                << "vkCreateWin32SurfaceKHR failed."
-                << " error=" << static_cast<int32_t>(result);
 #endif
         return std::make_tuple(surface, extent);
 }