test load image

Release Filament 1.51.8
backend tests were broken by a change in TargetBufferInfo
2024-05-15 23:37:49 -07:00 · 2024-05-13 20:53:36 +00:00 · 2024-05-10 14:39:22 -07:00 · 2024-05-10 13:00:00 -07:00 · 2024-05-10 11:25:34 -07:00 · 2024-05-10 11:14:41 -07:00
602 changed files with 22781 additions and 9373 deletions
@@ -10,7 +10,7 @@ on:
 jobs:
  build-android:
    name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -13,7 +13,7 @@ on:
 jobs:
  cocoapods-deploy:
    name: cocoapods-deploy
-    runs-on: macos-latest
+    runs-on: macos-14
    steps:
      - name: Check out iOS/CocoaPods directory
        uses: Bhacaz/checkout-files@49fc3050859046bf4f4873678d46099985640e89
@@ -10,7 +10,7 @@ on:
 jobs:
  build-ios:
    name: build-ios
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -10,7 +10,7 @@ on:
 jobs:
  build-mac:
    name: build-mac
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -11,7 +11,7 @@ on:
 jobs:
  npm-deploy:
    name: npm-deploy
-    runs-on: macos-latest
+    runs-on: macos-14
    steps:
      - uses: actions/checkout@v3.3.0
        with:
@@ -15,7 +15,7 @@ jobs:

    strategy:
      matrix:
-        os: [macos-latest, ubuntu-22.04]
+        os: [macos-14, ubuntu-22.04]

    steps:
      - uses: actions/checkout@v3.3.0
@@ -40,7 +40,7 @@ jobs:

  build-android:
    name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -54,7 +54,7 @@ jobs:

  build-ios:
    name: build-iOS
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -67,7 +67,7 @@ jobs:

  build-web:
    name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -31,7 +31,7 @@ jobs:

    strategy:
      matrix:
-        os: [macos-latest, ubuntu-22.04]
+        os: [macos-14, ubuntu-22.04]

    steps:
      - name: Decide Git ref
@@ -65,7 +65,7 @@ jobs:

  build-web:
    name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14
    if: github.event_name == 'release' || github.event.inputs.platform == 'web'

    steps:
@@ -98,7 +98,7 @@ jobs:

  build-android:
    name: build-android
-    runs-on: macos-latest
+    runs-on: macos-14
    if: github.event_name == 'release' || github.event.inputs.platform == 'android'

    steps:
@@ -129,7 +129,7 @@ jobs:
      - name: Sign sample-gltf-viewer
        run: |
          echo "${APK_KEYSTORE_BASE64}" > filament.jks.base64
-          base64 --decode filament.jks.base64 > filament.jks
+          base64 --decode -i filament.jks.base64 > filament.jks
          BUILD_TOOLS_VERSION=$(ls ${ANDROID_HOME}/build-tools | sort -V | tail -n 1)
          APKSIGNER=${ANDROID_HOME}/build-tools/${BUILD_TOOLS_VERSION}/apksigner
          IN_FILE="out/sample-gltf-viewer-release.apk"
@@ -152,7 +152,7 @@ jobs:

  build-ios:
    name: build-ios
-    runs-on: macos-latest
+    runs-on: macos-14
    if: github.event_name == 'release' || github.event.inputs.platform == 'ios'

    steps:
@@ -205,7 +205,7 @@ jobs:
          TAG: ${{ steps.git_ref.outputs.tag }}
        run: |
          build\windows\build-github.bat release
-          move out\filament-windows.tgz out\filament-$Env:TAG-windows.tgz
+          move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
        shell: cmd
      - uses: actions/github-script@v6
        env:
@@ -10,7 +10,7 @@ on:
 jobs:
  build-web:
    name: build-web
-    runs-on: macos-latest
+    runs-on: macos-14

    steps:
      - uses: actions/checkout@v3.3.0
@@ -41,8 +41,12 @@ option(FILAMENT_LINUX_IS_MOBILE "Treat Linux as Mobile" OFF)

 option(FILAMENT_ENABLE_ASAN_UBSAN "Enable Address and Undefined Behavior Sanitizers" OFF)

+option(FILAMENT_ENABLE_TSAN "Enable Thread Sanitizer" OFF)
+
 option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)

+option(FILAMENT_ENABLE_MULTIVIEW "Enable multiview for Filament" OFF)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
    "Android NDK version or version prefix to be used when building for Android."
 )
@@ -67,6 +71,10 @@ set(FILAMENT_METAL_HANDLE_ARENA_SIZE_IN_MB "8" CACHE STRING
    "Size of the Metal handle arena, default 8."
 )

+set(FILAMENT_BACKEND_DEBUG_FLAG "" CACHE STRING
+    "A debug flag meant for enabling/disabling backend debugging paths"
+)
+
 # Enable exceptions by default in spirv-cross.
 set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS OFF)

@@ -165,15 +173,6 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS AND NOT FILAMENT_LINUX_IS_MOBILE)
    set(IS_HOST_PLATFORM TRUE)
 endif()

-if (IOS)
-    # Remove the headerpad_max_install_names linker flag on iOS. It causes warnings when linking
-    # executables with bitcode.
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_C_LINK_FLAGS ${CMAKE_C_LINK_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_CXX_LINK_FLAGS ${CMAKE_CXX_LINK_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS ${CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS ${CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS})
-endif()
-
 if (WIN32)
    # Link statically against c/c++ lib to avoid missing redistriburable such as
    # "VCRUNTIME140.dll not found. Try reinstalling the app.", but give users
@@ -230,6 +229,21 @@ if (WIN32)
            # we don't need them on CI.
            string(REPLACE "/INCREMENTAL" "/INCREMENTAL:NO" ${LinkerFlag} ${${LinkerFlag}})
        endforeach()
+
+        # We turn off compile-time optimizations for CI, as options that speed up the compile-time
+        # (e.g. /MP) might increase memory usage, leading to instabilities on limited CI machines.
+        option(FILAMENT_SHORTEN_MSVC_COMPILATION "Shorten compile-time in Visual Studio" OFF)
+    else()
+        option(FILAMENT_SHORTEN_MSVC_COMPILATION "Shorten compile-time in Visual Studio" ON)
+    endif()
+
+    if (MSVC)
+        if (FILAMENT_SHORTEN_MSVC_COMPILATION)
+            # enable multi-processor compilation
+            set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /MP")
+            # disable run-time STL checks to improve tools (e.g. matc) performance
+            set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} /D_ITERATOR_DEBUG_LEVEL=0")
+        endif()
    endif()
 endif()

@@ -370,8 +384,9 @@ endif()
 if (NOT MSVC AND NOT IOS)
    # Omitting stack frame pointers prevents the generation of readable stack traces in crash reports on iOS
    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer")
+endif()

-    # These aren't compatible with -fembed-bitcode (and seem to have no effect on Apple platforms anyway)
+if (NOT MSVC)
    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -ffunction-sections -fdata-sections")
 endif()

@@ -411,7 +426,13 @@ endif()
 if (FILAMENT_ENABLE_ASAN_UBSAN)
   set(EXTRA_SANITIZE_OPTIONS "-fsanitize=address -fsanitize=undefined")
 endif()
-
+if (FILAMENT_ENABLE_TSAN)
+   set(EXTRA_SANITIZE_OPTIONS "-fsanitize=thread")
+endif()
+if (ANDROID)
+    # keep STL debug infos (mimics what the NDK does)
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fno-limit-debug-info")
+endif()
 if (NOT MSVC AND NOT WEBGL)
    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fstack-protector")
 endif()
@@ -508,6 +529,27 @@ else()
    option(FILAMENT_DISABLE_MATOPT "Disable material optimizations" ON)
 endif()

+# This only affects the prebuilt shader files in gltfio and samples, not filament library.
+# The value can be either "instanced" or "multiview".
+set(FILAMENT_SAMPLES_STEREO_TYPE "instanced" CACHE STRING
+    "Stereoscopic type that shader files in gltfio and samples are built for."
+)
+string(TOLOWER "${FILAMENT_SAMPLES_STEREO_TYPE}" FILAMENT_SAMPLES_STEREO_TYPE)
+if (NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "instanced" AND NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    message(FATAL_ERROR "Invalid stereo type: \"${FILAMENT_SAMPLES_STEREO_TYPE}\" choose either \"instanced\" or \"multiview\" ")
+endif ()
+
+# Compiling samples for multiview implies enabling multiview feature as well.
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set(FILAMENT_ENABLE_MULTIVIEW ON)
+endif ()
+
+# Define backend flag for debug only
+if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND NOT FILAMENT_BACKEND_DEBUG_FLAG STREQUAL "")
+    add_definitions(-DFILAMENT_BACKEND_DEBUG_FLAG=${FILAMENT_BACKEND_DEBUG_FLAG})
+    unset(FILAMENT_BACKEND_DEBUG_FLAG)
+endif()
+
 # ==================================================================================================
 # Material compilation flags
 # ==================================================================================================
@@ -611,9 +653,9 @@ function(combine_static_libs TARGET OUTPUT DEPS)
    # Loop through the dependent libraries and query their location on disk.
    set(DEPS_FILES )
    foreach(DEPENDENCY ${DEPS})
-        if(TARGET ${DEPENDENCY})
+        if (TARGET ${DEPENDENCY})
            get_property(dep_type TARGET ${DEPENDENCY} PROPERTY TYPE)
-            if(dep_type STREQUAL "STATIC_LIBRARY")
+            if (dep_type STREQUAL "STATIC_LIBRARY")
                list(APPEND DEPS_FILES "$<TARGET_FILE:${DEPENDENCY}>")
            endif()
        endif()
@@ -683,7 +725,7 @@ function(get_resgen_vars ARCHIVE_DIR ARCHIVE_NAME)
        set(RESGEN_OUTPUTS "${OUTPUTS}" PARENT_SCOPE)
        set(RESGEN_FLAGS -qx ${ARCHIVE_DIR} -p ${ARCHIVE_NAME} PARENT_SCOPE)
        set(RESGEN_SOURCE "${ARCHIVE_DIR}/${ARCHIVE_NAME}${ASM_SUFFIX}.S" PARENT_SCOPE)
-        set(RESGEN_SOURCE_FLAGS "-I${ARCHIVE_DIR} ${ASM_ARCH_FLAG}" PARENT_SCOPE)
+        set(RESGEN_SOURCE_FLAGS "-I'${ARCHIVE_DIR}' ${ASM_ARCH_FLAG}" PARENT_SCOPE)
    endif()
 endfunction()

@@ -698,7 +740,6 @@ add_subdirectory(${LIBRARIES}/filabridge)
 add_subdirectory(${LIBRARIES}/filaflat)
 add_subdirectory(${LIBRARIES}/filagui)
 add_subdirectory(${LIBRARIES}/filameshio)
-add_subdirectory(${LIBRARIES}/geometry)
 add_subdirectory(${LIBRARIES}/gltfio)
 add_subdirectory(${LIBRARIES}/ibl)
 add_subdirectory(${LIBRARIES}/iblprefilter)
@@ -726,6 +767,9 @@ add_subdirectory(${EXTERNAL}/jsmn/tnt)
 add_subdirectory(${EXTERNAL}/stb/tnt)
 add_subdirectory(${EXTERNAL}/getopt)

+# Note that this has to be placed after mikktspace in order for combine_static_libs to work.
+add_subdirectory(${LIBRARIES}/geometry)
+
 if (FILAMENT_BUILD_FILAMAT OR IS_HOST_PLATFORM)
    # spirv-tools must come before filamat, as filamat relies on the presence of the
    # spirv-tools_SOURCE_DIR variable.
@@ -743,6 +787,8 @@ endif()
 if (FILAMENT_SUPPORTS_VULKAN)
    add_subdirectory(${LIBRARIES}/bluevk)
    add_subdirectory(${EXTERNAL}/vkmemalloc/tnt)
+    set(SPIRV_HEADERS_SKIP_EXAMPLES ON)
+    add_subdirectory(${EXTERNAL}/spirv-headers)
 endif()

 set(FILAMENT_SAMPLES_BINARY_DIR ${PROJECT_BINARY_DIR}/samples)
@@ -775,6 +821,9 @@ if (IS_HOST_PLATFORM)
    add_subdirectory(${TOOLS}/glslminifier)
    add_subdirectory(${TOOLS}/matc)
    add_subdirectory(${TOOLS}/matinfo)
+    if (NOT WIN32)  # matedit not yet supported on Windows
+        add_subdirectory(${TOOLS}/matedit)
+    endif()
    add_subdirectory(${TOOLS}/mipgen)
    add_subdirectory(${TOOLS}/normal-blending)
    add_subdirectory(${TOOLS}/resgen)
@@ -31,7 +31,7 @@ repositories {
 }

 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.47.0'
+    implementation 'com.google.android.filament:filament-android:1.51.8'
 }
 ```

@@ -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.47.0'
+pod 'Filament', '~> 1.51.8'
 ```

 ### Snapshots
@@ -7,6 +7,93 @@ 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.51.9
+
+
+## v1.51.8
+
+- filagui: Fix regression which broke WebGL
+- Add a new Engine::Config setting to control preferred shader language
+- Add `getEyeIndex` vertex API
+- ios: Remove bitcode from iOS builds
+
+## v1.51.7
+
+- Add new matedit tool
+- filagui: Support rendering `GL_TEXTURE_EXTERNAL_OES` textures.
+- `setFrameScheduledCallback` now takes a `utils::Invocable`.
+- engine: Add `isPaused()`
+
+## v1.51.6
+
+- Add new matedit tool
+- filagui: Support rendering `GL_TEXTURE_EXTERNAL_OES` textures.
+
+## v1.51.5
+
+
+## v1.51.4
+
+
+## v1.51.3
+
+
+## v1.51.2
+
+- engine: Add experimental APIs `Engine::builder::paused()` and `Engine::setPaused()`
+
+## v1.51.1
+
+
+## v1.51.0
+
+- materials: add support for post-lighting mix factor (b/328498606) [⚠️ **New Material Version**]
+
+## v1.50.6
+
+- Add new API `SwapChain::getFrameScheduledCallback`
+- vulkan: fixed validation error VUID-vkAcquireNextImageKHR-semaphore-01779
+- opengl: Add support for protected content swapchains and contexts
+
+## v1.50.5
+
+- android: NDK 26.1.10909125 is used by default
+- android: Minimum API level on Android is now API 21 instead of API 19. This allows the use of OpenGL ES 3.1
+- rendering: New PBR Neutral tone mapper, designed to preserve materials color appearance
+- android: Change default frameRateOptions.interval to 1.0
+
+## v1.50.4
+
+
+## v1.50.3
+
+
+## v1.50.2
+
+
+## v1.50.1
+
+- Metal: fix some shader artifacts by disabling fast math optimizations.
+- backend: remove `atan2` overload which had a typo and wasn't useful. Fixes b/320856413.
+- utils: remove usages of `SpinLock`. Fixes b/321101014.
+
+## v1.50.0
+- engine: TAA now supports 4x upscaling [BETA] [⚠️ **New Material Version**]
+
+## v1.49.3
+
+- matc: Generate stereo variants for FL0 materials [⚠️ **Recompile materials**]
+
+## v1.49.2
+
+
+## v1.49.1
+
+
+## v1.49.0
+
+- matc: Fix ESSL 1.0 codegen when using external samplers [⚠️ **Recompile materials**]
+
 ## v1.48.0

 - matc: New option `-1` to disable generation of ESSL 1.0 code in Feature Level 0 materials
@@ -80,15 +80,15 @@ buildscript {

    ext.versions = [
        'jdk': 17,
-        'minSdk': 19,
-        'targetSdk': 33,
-        'compileSdk': 33,
-        'kotlin': '1.9.0',
-        'kotlin_coroutines': '1.7.2',
+        'minSdk': 21,
+        'targetSdk': 34,
+        'compileSdk': 34,
+        'kotlin': '1.9.21',
+        'kotlin_coroutines': '1.7.3',
        'buildTools': '34.0.0',
-        'ndk': '25.1.8937393',
-        'androidx_core': '1.10.1',
-        'androidx_annotations': '1.6.0'
+        'ndk': '26.1.10909125',
+        'androidx_core': '1.12.0',
+        'androidx_annotations': '1.7.0'
    ]

    ext.deps = [
@@ -104,7 +104,7 @@ buildscript {
    ]

    dependencies {
-        classpath 'com.android.tools.build:gradle:8.1.0'
+        classpath 'com.android.tools.build:gradle:8.2.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
    }

@@ -342,6 +342,21 @@ Java_com_google_android_filament_Engine_nIsValidMaterial(JNIEnv*, jclass,
    return (jboolean)engine->isValid((Material*)nativeMaterial);
 }

+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidMaterialInstance(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeMaterial, jlong nativeMaterialInstance) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Material*)nativeMaterial,
+            (MaterialInstance*)nativeMaterialInstance);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+        Java_com_google_android_filament_Engine_nIsValidExpensiveMaterialInstance(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeMaterialInstance) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValidExpensive((MaterialInstance*)nativeMaterialInstance);
+}
+
 extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_Engine_nIsValidSkybox(JNIEnv*, jclass,
        jlong nativeEngine, jlong nativeSkybox) {
@@ -391,6 +406,20 @@ Java_com_google_android_filament_Engine_nFlush(JNIEnv*, jclass,
    engine->flush();
 }

+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsPaused(JNIEnv*, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jboolean)engine->isPaused();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nSetPaused(JNIEnv*, jclass,
+        jlong nativeEngine, jboolean paused) {
+    Engine* engine = (Engine*) nativeEngine;
+    engine->setPaused(paused);
+}
+
 // Managers...

 extern "C" JNIEXPORT jlong JNICALL
@@ -484,7 +513,13 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
 extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*,
        jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB,
        jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB,
-        jlong jobSystemThreadCount, jlong stereoscopicEyeCount) {
+        jlong jobSystemThreadCount,
+        jlong textureUseAfterFreePoolSize, jboolean disableParallelShaderCompile,
+        jint stereoscopicType, jlong stereoscopicEyeCount,
+        jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
+        jboolean disableHandleUseAfterFreeCheck,
+        jint preferredShaderLanguage,
+        jboolean forceGLES2Context) {
    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
    Engine::Config config = {
            .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -493,7 +528,15 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
            .minCommandBufferSizeMB = (uint32_t) minCommandBufferSizeMB,
            .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
            .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
+            .textureUseAfterFreePoolSize = (uint32_t) textureUseAfterFreePoolSize,
+            .disableParallelShaderCompile = (bool) disableParallelShaderCompile,
+            .stereoscopicType = (Engine::StereoscopicType) stereoscopicType,
            .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
+            .resourceAllocatorCacheSizeMB = (uint32_t) resourceAllocatorCacheSizeMB,
+            .resourceAllocatorCacheMaxAge = (uint8_t) resourceAllocatorCacheMaxAge,
+            .disableHandleUseAfterFreeCheck = (bool) disableHandleUseAfterFreeCheck,
+            .preferredShaderLanguage = (Engine::Config::ShaderLanguage) preferredShaderLanguage,
+            .forceGLES2Context = (bool) forceGLES2Context,
    };
    builder->config(&config);
 }
@@ -510,6 +553,12 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
    builder->sharedContext((void*) sharedContext);
 }

+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderPaused(
+        JNIEnv*, jclass, jlong nativeBuilder, jboolean paused) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->paused((bool) paused);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder) {
    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
@@ -38,7 +38,7 @@ Java_com_google_android_filament_EntityManager_nCreateArray(JNIEnv* env, jclass,
    // (which it is), but still.
    em->create((size_t) n, reinterpret_cast<Entity *>(entities));

-    env->ReleaseIntArrayElements(entities_, entities, 0);
+    env->ReleaseIntArrayElements(entities_, entities, JNI_ABORT);
 }

 extern "C" JNIEXPORT jint JNICALL
@@ -205,7 +205,7 @@ Java_com_google_android_filament_MaterialInstance_nSetIntParameterArray(JNIEnv *
            break;
    }

-    env->ReleaseIntArrayElements(v_, v, 0);
+    env->ReleaseIntArrayElements(v_, v, JNI_ABORT);

    env->ReleaseStringUTFChars(name_, name);
 }
@@ -104,6 +104,14 @@ Java_com_google_android_filament_RenderableManager_nBuilderGeometry__JIIJJIIII(J
            (size_t) count);
 }

+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderGeometryType(JNIEnv*, jclass,
+        jlong nativeBuilder, int type) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    builder->geometryType((RenderableManager::Builder::GeometryType)type);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nBuilderMaterial(JNIEnv*, jclass,
@@ -114,6 +114,6 @@ Java_com_google_android_filament_Scene_nGetEntities(JNIEnv *env, jclass ,
            out[i++] = (jint) entity.getId();
        }
    });
-    env->ReleaseIntArrayElements(outArray, (jint*) out, JNI_ABORT);
+    env->ReleaseIntArrayElements(outArray, (jint*) out, 0);
    return JNI_TRUE;
 }
@@ -34,7 +34,15 @@ Java_com_google_android_filament_SwapChain_nSetFrameCompletedCallback(JNIEnv* en
 }

 extern "C" JNIEXPORT jboolean JNICALL
-Java_com_google_android_filament_SwapChain_nIsSRGBSwapChainSupported(JNIEnv *, jclass, jlong nativeEngine) {
+Java_com_google_android_filament_SwapChain_nIsSRGBSwapChainSupported(
+        JNIEnv *, jclass, jlong nativeEngine) {
    Engine* engine = (Engine*) nativeEngine;
-    return (bool)SwapChain::isSRGBSwapChainSupported(*engine);
+    return (jboolean)SwapChain::isSRGBSwapChainSupported(*engine);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_SwapChain_nIsProtectedContentSupported(
+        JNIEnv *, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jboolean)SwapChain::isProtectedContentSupported(*engine);
 }
@@ -47,6 +47,11 @@ Java_com_google_android_filament_ToneMapper_nCreateFilmicToneMapper(JNIEnv*, jcl
    return (jlong) new FilmicToneMapper();
 }

+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_ToneMapper_nCreatePBRNeutralToneMapper(JNIEnv*, jclass) {
+    return (jlong) new PBRNeutralToneMapper();
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_ToneMapper_nCreateAgxToneMapper(JNIEnv*, jclass, jint look) {
    return (jlong) new AgxToneMapper(AgxToneMapper::AgxLook(look));
@@ -49,6 +49,12 @@ Java_com_google_android_filament_View_nSetCamera(JNIEnv*, jclass,
    view->setCamera(camera);
 }

+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nHasCamera(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return (jboolean)view->hasCamera();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetColorGrading(JNIEnv*, jclass,
        jlong nativeView, jlong nativeColorGrading) {
@@ -158,6 +158,16 @@ public class Engine {
        FEATURE_LEVEL_3,
    };

+    /**
+     * The type of technique for stereoscopic rendering
+     */
+    public enum StereoscopicType {
+        /** Stereoscopic rendering is performed using instanced rendering technique. */
+        INSTANCED,
+        /** Stereoscopic rendering is performed using the multiview feature from the graphics backend. */
+        MULTIVIEW,
+    };
+
    /**
     * Constructs <code>Engine</code> objects using a builder pattern.
     */
@@ -211,7 +221,13 @@ public class Engine {
            nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
                    config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
                    config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
-                    config.jobSystemThreadCount, config.stereoscopicEyeCount);
+                    config.jobSystemThreadCount,
+                    config.textureUseAfterFreePoolSize, config.disableParallelShaderCompile,
+                    config.stereoscopicType.ordinal(), config.stereoscopicEyeCount,
+                    config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
+                    config.disableHandleUseAfterFreeCheck,
+                    config.preferredShaderLanguage.ordinal(),
+                    config.forceGLES2Context);
            return this;
        }

@@ -226,6 +242,20 @@ public class Engine {
            return this;
        }

+        /**
+         * Sets the initial paused state of the rendering thread.
+         *
+         * <p>Warning: This is an experimental API. See {@link Engine#setPaused(boolean)} for
+         * caveats.
+         *
+         * @param paused Whether to start the rendering thread paused.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder paused(boolean paused) {
+            nSetBuilderPaused(mNativeBuilder, paused);
+            return this;
+        }
+
        /**
         * Creates an instance of Engine
         *
@@ -348,6 +378,35 @@ public class Engine {
         */
        public long jobSystemThreadCount = 0;

+        /**
+         * Number of most-recently destroyed textures to track for use-after-free.
+         *
+         * This will cause the backend to throw an exception when a texture is freed but still bound
+         * to a SamplerGroup and used in a draw call. 0 disables completely.
+         *
+         * Currently only respected by the Metal backend.
+         */
+        public long textureUseAfterFreePoolSize = 0;
+
+        /**
+         * Set to `true` to forcibly disable parallel shader compilation in the backend.
+         * Currently only honored by the GL backend.
+         */
+        public boolean disableParallelShaderCompile = false;
+
+        /**
+         * The type of technique for stereoscopic rendering.
+         *
+         * This setting determines the algorithm used when stereoscopic rendering is enabled. This
+         * decision applies to the entire Engine for the lifetime of the Engine. E.g., multiple
+         * Views created from the Engine must use the same stereoscopic type.
+         *
+         * Each view can enable stereoscopic rendering via the StereoscopicOptions::enable flag.
+         *
+         * @see View#setStereoscopicOptions
+         */
+        public StereoscopicType stereoscopicType = StereoscopicType.INSTANCED;
+
        /**
         * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
         * between 1 and Engine#getMaxStereoscopicEyes() (inclusive).
@@ -356,6 +415,50 @@ public class Engine {
         * @see Engine#getMaxStereoscopicEyes
         */
        public long stereoscopicEyeCount = 2;
+
+        /*
+         * @Deprecated This value is no longer used.
+         */
+        public long resourceAllocatorCacheSizeMB = 64;
+
+        /*
+         * This value determines for how many frames are texture entries kept in the cache.
+         */
+        public long resourceAllocatorCacheMaxAge = 2;
+
+        /*
+         * Disable backend handles use-after-free checks.
+         */
+        public boolean disableHandleUseAfterFreeCheck = false;
+
+        /*
+         * Sets a preferred shader language for Filament to use.
+         *
+         * The Metal backend supports two shader languages: MSL (Metal Shading Language) and
+         * METAL_LIBRARY (precompiled .metallib). This option controls which shader language is
+         * used when materials contain both.
+         *
+         * By default, when preferredShaderLanguage is unset, Filament will prefer METAL_LIBRARY
+         * shaders if present within a material, falling back to MSL. Setting
+         * preferredShaderLanguage to ShaderLanguage::MSL will instead instruct Filament to check
+         * for the presence of MSL in a material first, falling back to METAL_LIBRARY if MSL is not
+         * present.
+         *
+         * When using a non-Metal backend, setting this has no effect.
+         */
+        public enum ShaderLanguage {
+            DEFAULT,
+            MSL,
+            METAL_LIBRARY,
+        };
+        public ShaderLanguage preferredShaderLanguage = ShaderLanguage.DEFAULT;
+
+        /*
+         * When the OpenGL ES backend is used, setting this value to true will force a GLES2.0
+         * context if supported by the Platform, or if not, will have the backend pretend
+         * it's a GLES2 context. Ignored on other backends.
+         */
+        public boolean forceGLES2Context = false;
    }

    private Engine(long nativeEngine, Config config) {
@@ -602,7 +705,7 @@ public class Engine {
     */
    @NonNull
    public SwapChain createSwapChain(@NonNull Object surface) {
-        return createSwapChain(surface, SwapChain.CONFIG_DEFAULT);
+        return createSwapChain(surface, SwapChainFlags.CONFIG_DEFAULT);
    }

    /**
@@ -610,15 +713,15 @@ public class Engine {
     *
     * @param surface on Android, <b>must be</b> an instance of {@link android.view.Surface}
     *
-     * @param flags configuration flags, see {@link SwapChain}
+     * @param flags configuration flags, see {@link SwapChainFlags}
     *
     * @return a newly created {@link SwapChain} object
     *
     * @exception IllegalStateException can be thrown if the SwapChain couldn't be created
     *
-     * @see SwapChain#CONFIG_DEFAULT
-     * @see SwapChain#CONFIG_TRANSPARENT
-     * @see SwapChain#CONFIG_READABLE
+     * @see SwapChainFlags#CONFIG_DEFAULT
+     * @see SwapChainFlags#CONFIG_TRANSPARENT
+     * @see SwapChainFlags#CONFIG_READABLE
     *
     */
    @NonNull
@@ -636,21 +739,22 @@ public class Engine {
     *
     * @param width  width of the rendering buffer
     * @param height height of the rendering buffer
-     * @param flags  configuration flags, see {@link SwapChain}
+     * @param flags  configuration flags, see {@link SwapChainFlags}
     *
     * @return a newly created {@link SwapChain} object
     *
     * @exception IllegalStateException can be thrown if the SwapChain couldn't be created
     *
-     * @see SwapChain#CONFIG_DEFAULT
-     * @see SwapChain#CONFIG_TRANSPARENT
-     * @see SwapChain#CONFIG_READABLE
+     * @see SwapChainFlags#CONFIG_DEFAULT
+     * @see SwapChainFlags#CONFIG_TRANSPARENT
+     * @see SwapChainFlags#CONFIG_READABLE
     *
     */
    @NonNull
    public SwapChain createSwapChain(int width, int height, long flags) {
        if (width >= 0 && height >= 0) {
-            long nativeSwapChain = nCreateSwapChainHeadless(getNativeObject(), width, height, flags);
+            long nativeSwapChain =
+                nCreateSwapChainHeadless(getNativeObject(), width, height, flags);
            if (nativeSwapChain == 0) throw new IllegalStateException("Couldn't create SwapChain");
            return new SwapChain(nativeSwapChain, null);
        }
@@ -662,11 +766,12 @@ public class Engine {
     *
     * @param surface a properly initialized {@link NativeSurface}
     *
-     * @param flags configuration flags, see {@link SwapChain}
+     * @param flags configuration flags, see {@link SwapChainFlags}
     *
     * @return a newly created {@link SwapChain} object
     *
-     * @exception IllegalStateException can be thrown if the {@link SwapChain} couldn't be created
+     * @exception IllegalStateException can be thrown if the {@link SwapChainFlags} couldn't be
+     *            created
     */
    @NonNull
    public SwapChain createSwapChainFromNativeSurface(@NonNull NativeSurface surface, long flags) {
@@ -775,6 +880,24 @@ public class Engine {
        return nIsValidMaterial(getNativeObject(), object.getNativeObject());
    }

+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidMaterialInstance(@NonNull Material ma, MaterialInstance mi) {
+        return nIsValidMaterialInstance(getNativeObject(), ma.getNativeObject(), mi.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidExpensiveMaterialInstance(@NonNull MaterialInstance object) {
+        return nIsValidExpensiveMaterialInstance(getNativeObject(), object.getNativeObject());
+    }
+
    /**
     * Returns whether the object is valid.
     * @param object Object to check for validity
@@ -1135,6 +1258,33 @@ public class Engine {
        nFlush(getNativeObject());
    }

+    /**
+     * Get paused state of rendering thread.
+     *
+     * <p>Warning: This is an experimental API.
+     *
+     * @see #setPaused
+     */
+    public boolean isPaused() {
+        return nIsPaused(getNativeObject());
+    }
+
+    /**
+     * Pause or resume the rendering thread.
+     *
+     * <p>Warning: This is an experimental API. In particular, note the following caveats.
+     *
+     * <ul><li>
+     * Buffer callbacks will never be called as long as the rendering thread is paused.
+     * Do not rely on a buffer callback to unpause the thread.
+     * </li><li>
+     * While the rendering thread is paused, rendering commands will continue to be queued until the
+     * buffer limit is reached. When the limit is reached, the program will abort.
+     * </li></ul>
+     */
+    public void setPaused(boolean paused) {
+        nSetPaused(getNativeObject(), paused);
+    }

    @UsedByReflection("TextureHelper.java")
    public long getNativeObject() {
@@ -1201,6 +1351,8 @@ public class Engine {
    private static native boolean nIsValidSkinningBuffer(long nativeEngine, long nativeSkinningBuffer);
    private static native boolean nIsValidIndirectLight(long nativeEngine, long nativeIndirectLight);
    private static native boolean nIsValidMaterial(long nativeEngine, long nativeMaterial);
+    private static native boolean nIsValidMaterialInstance(long nativeEngine, long nativeMaterial, long nativeMaterialInstance);
+    private static native boolean nIsValidExpensiveMaterialInstance(long nativeEngine, long nativeMaterialInstance);
    private static native boolean nIsValidSkybox(long nativeEngine, long nativeSkybox);
    private static native boolean nIsValidColorGrading(long nativeEngine, long nativeColorGrading);
    private static native boolean nIsValidTexture(long nativeEngine, long nativeTexture);
@@ -1209,6 +1361,8 @@ public class Engine {
    private static native void nDestroyEntity(long nativeEngine, int entity);
    private static native void nFlushAndWait(long nativeEngine);
    private static native void nFlush(long nativeEngine);
+    private static native boolean nIsPaused(long nativeEngine);
+    private static native void nSetPaused(long nativeEngine, boolean paused);
    private static native long nGetTransformManager(long nativeEngine);
    private static native long nGetLightManager(long nativeEngine);
    private static native long nGetRenderableManager(long nativeEngine);
@@ -1227,8 +1381,14 @@ public class Engine {
    private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
            long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
            long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
-            long stereoscopicEyeCount);
+            long textureUseAfterFreePoolSize, boolean disableParallelShaderCompile,
+            int stereoscopicType, long stereoscopicEyeCount,
+            long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
+            boolean disableHandleUseAfterFreeCheck,
+            int preferredShaderLanguage,
+            boolean forceGLES2Context);
    private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
    private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
+    private static native void nSetBuilderPaused(long nativeBuilder, boolean paused);
    private static native long nBuilderBuild(long nativeBuilder);
 }
@@ -175,6 +175,32 @@ public class RenderableManager {
            return this;
        }

+        /**
+         * Type of geometry for a Renderable
+         */
+        public enum GeometryType {
+            /** dynamic gemoetry has no restriction */
+            DYNAMIC,
+            /** bounds and world space transform are immutable */
+            STATIC_BOUNDS,
+            /** skinning/morphing not allowed and Vertex/IndexBuffer immutables */
+            STATIC
+        }
+
+        /**
+         * Specify whether this renderable has static bounds. In this context his means that
+         * the renderable's bounding box cannot change and that the renderable's transform is
+         * assumed immutable. Changing the renderable's transform via the TransformManager
+         * can lead to corrupted graphics. Note that skinning and morphing are not forbidden.
+         * Disabled by default.
+         * @param enable whether this renderable has static bounds. false by default.
+         */
+        @NonNull
+        public Builder geometryType(GeometryType type) {
+            nBuilderGeometryType(mNativeBuilder, type.ordinal());
+            return this;
+        }
+
        /**
         * Binds a material instance to the specified primitive.
         *
@@ -964,6 +990,7 @@ public class RenderableManager {
    private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer);
    private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
    private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int minIndex, int maxIndex, int count);
+    private static native void nBuilderGeometryType(long nativeBuilder, int type);
    private static native void nBuilderMaterial(long nativeBuilder, int index, long nativeMaterialInstance);
    private static native void nBuilderBlendOrder(long nativeBuilder, int index, int blendOrder);
    private static native void nBuilderGlobalBlendOrderEnabled(long nativeBuilder, int index, boolean enabled);
@@ -101,7 +101,7 @@ public class Renderer {
        /**
         * Desired frame interval in unit of 1 / DisplayInfo.refreshRate.
         */
-        public float interval = 1.0f / 60.0f;
+        public float interval = 1.0f;

        /**
         * Additional headroom for the GPU as a ratio of the targetFrameTime.
@@ -68,77 +68,30 @@ public class SwapChain {
    private final Object mSurface;
    private long mNativeObject;

-    public static final long CONFIG_DEFAULT = 0x0;
-
-    /**
-     * This flag indicates that the <code>SwapChain</code> must be allocated with an
-     * alpha-channel.
-     */
-    public static final long CONFIG_TRANSPARENT = 0x1;
-
-    /**
-     * This flag indicates that the <code>SwapChain</code> may be used as a source surface
-     * for reading back render results.  This config must be set when creating
-     * any <code>SwapChain</code>  that will be used as the source for a blit operation.
-     *
-     * @see Renderer#copyFrame
-     */
-    public static final long CONFIG_READABLE = 0x2;
-
-    /**
-     * Indicates that the native X11 window is an XCB window rather than an XLIB window.
-     * This is ignored on non-Linux platforms and in builds that support only one X11 API.
-     */
-    public static final long CONFIG_ENABLE_XCB = 0x4;
-
-    /**
-     * Indicates that the SwapChain must automatically perform linear to sRGB encoding.
-     *
-     * This flag is ignored if isSRGBSwapChainSupported() is false.
-     *
-     * When using this flag, post-processing should be disabled.
-     *
-     * @see SwapChain#isSRGBSwapChainSupported
-     * @see View#setPostProcessingEnabled
-     */
-    public static final long CONFIG_SRGB_COLORSPACE = 0x10;
-
-    /**
-     * Indicates that this SwapChain should allocate a stencil buffer in addition to a depth buffer.
-     *
-     * This flag is necessary when using View::setStencilBufferEnabled and rendering directly into
-     * the SwapChain (when post-processing is disabled).
-     *
-     * The specific format of the stencil buffer depends on platform support. The following pixel
-     * formats are tried, in order of preference:
-     *
-     * Depth only (without CONFIG_HAS_STENCIL_BUFFER):
-     * - DEPTH32F
-     * - DEPTH24
-     *
-     * Depth + stencil (with CONFIG_HAS_STENCIL_BUFFER):
-     * - DEPTH32F_STENCIL8
-     * - DEPTH24F_STENCIL8
-     *
-     * Note that enabling the stencil buffer may hinder depth precision and should only be used if
-     * necessary.
-     *
-     * @see View#setStencilBufferEnabled
-     * @see View#setPostProcessingEnabled
-     */
-    public static final long CONFIG_HAS_STENCIL_BUFFER = 0x20;
-
    SwapChain(long nativeSwapChain, Object surface) {
        mNativeObject = nativeSwapChain;
        mSurface = surface;
    }

    /**
-     * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
+     * Return whether createSwapChain supports the CONFIG_PROTECTED_CONTENT flag.
     * The default implementation returns false.
     *
     * @param engine A reference to the filament Engine
-     * @return true if SWAP_CHAIN_CONFIG_SRGB_COLORSPACE is supported, false otherwise.
+     * @return true if CONFIG_PROTECTED_CONTENT is supported, false otherwise.
+     * @see SwapChainFlags#CONFIG_PROTECTED_CONTENT
+     */
+    public static boolean isProtectedContentSupported(@NonNull Engine engine) {
+        return nIsProtectedContentSupported(engine.getNativeObject());
+    }
+
+    /**
+     * Return whether createSwapChain supports the CONFIG_SRGB_COLORSPACE flag.
+     * The default implementation returns false.
+     *
+     * @param engine A reference to the filament Engine
+     * @return true if CONFIG_SRGB_COLORSPACE is supported, false otherwise.
+     * @see SwapChainFlags#CONFIG_SRGB_COLORSPACE
     */
    public static boolean isSRGBSwapChainSupported(@NonNull Engine engine) {
        return nIsSRGBSwapChainSupported(engine.getNativeObject());
@@ -186,4 +139,5 @@ public class SwapChain {

    private static native void nSetFrameCompletedCallback(long nativeSwapChain, Object handler, Runnable callback);
    private static native boolean nIsSRGBSwapChainSupported(long nativeEngine);
+    private static native boolean nIsProtectedContentSupported(long nativeEngine);
 }
@@ -0,0 +1,97 @@
+/*
+ * Copyright (C) 2024 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;
+
+// Note: SwapChainFlags is kept separate from SwapChain so that UiHelper does not need to depend
+// on SwapChain. This allows clients to use UiHelper without requiring all of Filament's Java
+// classes.
+
+/**
+ * Flags that a <code>SwapChain</code> can be created with to control behavior.
+ *
+ * @see Engine#createSwapChain
+ * @see Engine#createSwapChainFromNativeSurface
+ */
+public final class SwapChainFlags {
+
+    public static final long CONFIG_DEFAULT = 0x0;
+
+    /**
+     * This flag indicates that the <code>SwapChain</code> must be allocated with an
+     * alpha-channel.
+     */
+    public static final long CONFIG_TRANSPARENT = 0x1;
+
+    /**
+     * This flag indicates that the <code>SwapChain</code> may be used as a source surface
+     * for reading back render results.  This config must be set when creating
+     * any <code>SwapChain</code>  that will be used as the source for a blit operation.
+     *
+     * @see Renderer#copyFrame
+     */
+    public static final long CONFIG_READABLE = 0x2;
+
+    /**
+     * Indicates that the native X11 window is an XCB window rather than an XLIB window.
+     * This is ignored on non-Linux platforms and in builds that support only one X11 API.
+     */
+    public static final long CONFIG_ENABLE_XCB = 0x4;
+
+    /**
+     * Indicates that the SwapChain must automatically perform linear to sRGB encoding.
+     *
+     * This flag is ignored if isSRGBSwapChainSupported() is false.
+     *
+     * When using this flag, post-processing should be disabled.
+     *
+     * @see SwapChain#isSRGBSwapChainSupported
+     * @see View#setPostProcessingEnabled
+     */
+    public static final long CONFIG_SRGB_COLORSPACE = 0x10;
+
+    /**
+     * Indicates that this SwapChain should allocate a stencil buffer in addition to a depth buffer.
+     *
+     * This flag is necessary when using View::setStencilBufferEnabled and rendering directly into
+     * the SwapChain (when post-processing is disabled).
+     *
+     * The specific format of the stencil buffer depends on platform support. The following pixel
+     * formats are tried, in order of preference:
+     *
+     * Depth only (without CONFIG_HAS_STENCIL_BUFFER):
+     * - DEPTH32F
+     * - DEPTH24
+     *
+     * Depth + stencil (with CONFIG_HAS_STENCIL_BUFFER):
+     * - DEPTH32F_STENCIL8
+     * - DEPTH24F_STENCIL8
+     *
+     * Note that enabling the stencil buffer may hinder depth precision and should only be used if
+     * necessary.
+     *
+     * @see View#setStencilBufferEnabled
+     * @see View#setPostProcessingEnabled
+     */
+    public static final long CONFIG_HAS_STENCIL_BUFFER = 0x20;
+
+    /**
+     * The SwapChain contains protected content. Only supported when isProtectedContentSupported()
+     * is true.
+     */
+    public static final long CONFIG_PROTECTED_CONTENT   = 0x40;
+}
+
@@ -849,6 +849,10 @@ public class Texture {
        public static final int SAMPLEABLE = 0x10;
        /** Texture can be used as a subpass input */
        public static final int SUBPASS_INPUT = 0x20;
+        /** Texture can be used the source of a blit() */
+        public static final int BLIT_SRC = 0x40;
+        /** Texture can be used the destination of a blit() */
+        public static final int BLIT_DST = 0x80;
        /** by default textures are <code>UPLOADABLE</code> and <code>SAMPLEABLE</code>*/
        public static final int DEFAULT = UPLOADABLE | SAMPLEABLE;
    }
@@ -16,12 +16,14 @@ package com.google.android.filament;
 * <li>Configurable tone mapping operators</li>
 * <ul>
 *   <li>GenericToneMapper</li>
+ *   <li>AgXToneMapper</li>
 * </ul>
 * <li>Fixed-aesthetic tone mapping operators</li>
 * <ul>
 *   <li>ACESToneMapper</li>
 *   <li>ACESLegacyToneMapper</li>
 *   <li>FilmicToneMapper</li>
+ *   <li>PBRNeutralToneMapper</li>
 * </ul>
 * <li>Debug/validation tone mapping operators</li>
 * <ul>
@@ -100,11 +102,21 @@ public class ToneMapper {
        }
    }

+    /**
+     * Khronos PBR Neutral tone mapping operator. This tone mapper was designed
+     * to preserve the appearance of materials across lighting conditions while
+     * avoiding artifacts in the highlights in high dynamic range conditions.
+     */
+    public static class PBRNeutralToneMapper extends ToneMapper {
+        public PBRNeutralToneMapper() {
+            super(nCreatePBRNeutralToneMapper());
+        }
+    }
+
    /**
     * AgX tone mapping operator.
     */
    public static class Agx extends ToneMapper {
-
        public enum AgxLook {
            /**
             * Base contrast with no look applied
@@ -233,6 +245,7 @@ public class ToneMapper {
    private static native long nCreateACESToneMapper();
    private static native long nCreateACESLegacyToneMapper();
    private static native long nCreateFilmicToneMapper();
+    private static native long nCreatePBRNeutralToneMapper();
    private static native long nCreateAgxToneMapper(int look);
    private static native long nCreateGenericToneMapper(
            float contrast, float midGrayIn, float midGrayOut, float hdrMax);
@@ -241,6 +241,15 @@ public class View {
        nSetCamera(getNativeObject(), camera == null ? 0 : camera.getNativeObject());
    }

+    /**
+     * Query whether a camera is set.
+     * @return true if a camera is set, false otherwise
+     * @see #setCamera
+     */
+    public boolean hasCamera() {
+        return nHasCamera(getNativeObject());
+    }
+
    /**
     * Gets this View's associated Camera, or null if none has been assigned.
     *
@@ -1093,7 +1102,7 @@ public class View {
     * @see #setStereoscopicOptions
     */
    @NonNull
-    public StereoscopicOptions getStereoscoopicOptions() {
+    public StereoscopicOptions getStereoscopicOptions() {
        if (mStereoscopicOptions == null) {
            mStereoscopicOptions = new StereoscopicOptions();
        }
@@ -1238,6 +1247,7 @@ public class View {
    private static native void nSetName(long nativeView, String name);
    private static native void nSetScene(long nativeView, long nativeScene);
    private static native void nSetCamera(long nativeView, long nativeCamera);
+    private static native boolean nHasCamera(long nativeView);
    private static native void nSetViewport(long nativeView, int left, int bottom, int width, int height);
    private static native void nSetVisibleLayers(long nativeView, int select, int value);
    private static native void nSetShadowingEnabled(long nativeView, boolean enabled);
@@ -1637,6 +1647,10 @@ public class View {
         * circle of confusion scale factor (amount of blur)
         */
        public float cocScale = 1.0f;
+        /**
+         * width/height aspect ratio of the circle of confusion (simulate anamorphic lenses)
+         */
+        public float cocAspectRatio = 1.0f;
        /**
         * maximum aperture diameter in meters (zero to disable rotation)
         */
@@ -1852,7 +1866,7 @@ public class View {
    }

    /**
-     * Options for Temporal Multi-Sample Anti-aliasing (MSAA)
+     * Options for Multi-Sample Anti-aliasing (MSAA)
     * @see setMultiSampleAntiAliasingOptions()
     */
    public static class MultiSampleAntiAliasingOptions {
@@ -1876,21 +1890,111 @@ public class View {

    /**
     * Options for Temporal Anti-aliasing (TAA)
+     * Most TAA parameters are extremely costly to change, as they will trigger the TAA post-process
+     * shaders to be recompiled. These options should be changed or set during initialization.
+     * `filterWidth`, `feedback` and `jitterPattern`, however, can be changed at any time.
+     *
+     * `feedback` of 0.1 effectively accumulates a maximum of 19 samples in steady state.
+     * see "A Survey of Temporal Antialiasing Techniques" by Lei Yang and all for more information.
+     *
     * @see setTemporalAntiAliasingOptions()
     */
    public static class TemporalAntiAliasingOptions {
+        public enum BoxType {
+            /**
+             * use an AABB neighborhood
+             */
+            AABB,
+            /**
+             * use the variance of the neighborhood (not recommended)
+             */
+            VARIANCE,
+            /**
+             * use both AABB and variance
+             */
+            AABB_VARIANCE,
+        }
+
+        public enum BoxClipping {
+            /**
+             * Accurate box clipping
+             */
+            ACCURATE,
+            /**
+             * clamping
+             */
+            CLAMP,
+            /**
+             * no rejections (use for debugging)
+             */
+            NONE,
+        }
+
+        public enum JitterPattern {
+            RGSS_X4,
+            UNIFORM_HELIX_X4,
+            HALTON_23_X8,
+            HALTON_23_X16,
+            HALTON_23_X32,
+        }
+
        /**
-         * reconstruction filter width typically between 0 (sharper, aliased) and 1 (smoother)
+         * reconstruction filter width typically between 0.2 (sharper, aliased) and 1.5 (smoother)
         */
        public float filterWidth = 1.0f;
        /**
         * history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
         */
-        public float feedback = 0.04f;
+        public float feedback = 0.12f;
+        /**
+         * texturing lod bias (typically -1 or -2)
+         */
+        public float lodBias = -1.0f;
+        /**
+         * post-TAA sharpen, especially useful when upscaling is true.
+         */
+        public float sharpness = 0.0f;
        /**
         * enables or disables temporal anti-aliasing
         */
        public boolean enabled = false;
+        /**
+         * 4x TAA upscaling. Disables Dynamic Resolution. [BETA]
+         */
+        public boolean upscaling = false;
+        /**
+         * whether to filter the history buffer
+         */
+        public boolean filterHistory = true;
+        /**
+         * whether to apply the reconstruction filter to the input
+         */
+        public boolean filterInput = true;
+        /**
+         * whether to use the YcoCg color-space for history rejection
+         */
+        public boolean useYCoCg = false;
+        /**
+         * type of color gamut box
+         */
+        @NonNull
+        public TemporalAntiAliasingOptions.BoxType boxType = TemporalAntiAliasingOptions.BoxType.AABB;
+        /**
+         * clipping algorithm
+         */
+        @NonNull
+        public TemporalAntiAliasingOptions.BoxClipping boxClipping = TemporalAntiAliasingOptions.BoxClipping.ACCURATE;
+        @NonNull
+        public TemporalAntiAliasingOptions.JitterPattern jitterPattern = TemporalAntiAliasingOptions.JitterPattern.HALTON_23_X16;
+        public float varianceGamma = 1.0f;
+        /**
+         * adjust the feedback dynamically to reduce flickering
+         */
+        public boolean preventFlickering = false;
+        /**
+         * whether to apply history reprojection (debug option)
+         */
+        public boolean historyReprojection = true;
    }

    /**
@@ -27,7 +27,7 @@ import android.view.SurfaceHolder;
 import android.view.SurfaceView;
 import android.view.TextureView;

-import com.google.android.filament.SwapChain;
+import com.google.android.filament.SwapChainFlags;

 /**
 * UiHelper is a simple class that can manage either a SurfaceView, TextureView, or a SurfaceHolder
@@ -182,28 +182,85 @@ public class UiHelper {
        void detach();
    }

-    private static class SurfaceViewHandler implements RenderSurface {
-        private final SurfaceView mSurfaceView;
+    private class SurfaceViewHandler implements RenderSurface, SurfaceHolder.Callback {
+        @NonNull private final SurfaceView mSurfaceView;

-        SurfaceViewHandler(SurfaceView surface) {
-            mSurfaceView = surface;
+        SurfaceViewHandler(@NonNull SurfaceView surfaceView) {
+            mSurfaceView = surfaceView;
+
+            @NonNull SurfaceHolder holder = surfaceView.getHolder();
+            holder.addCallback(this);
+
+            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
+            }
+
+            // in case the SurfaceView's surface already existed
+            final Surface surface = holder.getSurface();
+            if (surface != null && surface.isValid()) {
+                surfaceCreated(holder);
+                // there is no way to retrieve the actual PixelFormat, since it is not used
+                // in the callback, we can use whatever we want.
+                surfaceChanged(holder, PixelFormat.RGBA_8888,
+                    holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
+            }
        }

        @Override
        public void resize(int width, int height) {
-            mSurfaceView.getHolder().setFixedSize(width, height);
+            @NonNull SurfaceHolder holder = mSurfaceView.getHolder();
+            holder.setFixedSize(width, height);
        }

        @Override
        public void detach() {
+            @NonNull SurfaceHolder holder = mSurfaceView.getHolder();
+            holder.removeCallback(this);
+        }
+
+        @Override
+        public void surfaceCreated(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
+            createSwapChain(holder.getSurface());
+        }
+
+        @Override
+        public void surfaceChanged(
+            @NonNull SurfaceHolder holder, int format, int width, int height) {
+            // Note: this is always called at least once after surfaceCreated()
+            if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
+            if (mRenderCallback != null) {
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void surfaceDestroyed(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
+            destroySwapChain();
        }
    }

-    private static class SurfaceHolderHandler implements RenderSurface {
+    private class SurfaceHolderHandler implements RenderSurface, SurfaceHolder.Callback {
        private final SurfaceHolder mSurfaceHolder;

-        SurfaceHolderHandler(SurfaceHolder surface) {
-            mSurfaceHolder = surface;
+        SurfaceHolderHandler(@NonNull SurfaceHolder holder) {
+            mSurfaceHolder = holder;
+            holder.addCallback(this);
+
+            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
+            }
+
+            // in case the SurfaceHolder's surface already existed
+            final Surface surface = holder.getSurface();
+            if (surface != null && surface.isValid()) {
+                surfaceCreated(holder);
+                // there is no way to retrieve the actual PixelFormat, since it is not used
+                // in the callback, we can use whatever we want.
+                surfaceChanged(holder, PixelFormat.RGBA_8888,
+                    holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
+            }
        }

        @Override
@@ -213,19 +270,55 @@ public class UiHelper {

        @Override
        public void detach() {
+            mSurfaceHolder.removeCallback(this);
+        }
+
+        @Override
+        public void surfaceCreated(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
+            createSwapChain(holder.getSurface());
+        }
+
+        @Override
+        public void surfaceChanged(@NonNull SurfaceHolder holder, int format, int width, int height) {
+            // Note: this is always called at least once after surfaceCreated()
+            if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
+            if (mRenderCallback != null) {
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void surfaceDestroyed(@NonNull SurfaceHolder surfaceHolder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
+            destroySwapChain();
        }
    }

-    private class TextureViewHandler implements RenderSurface {
+    private class TextureViewHandler implements RenderSurface, TextureView.SurfaceTextureListener {
        private final TextureView mTextureView;
        private Surface mSurface;

-        TextureViewHandler(TextureView surface) { mTextureView = surface; }
+        TextureViewHandler(@NonNull TextureView view) {
+            mTextureView = view;
+            mTextureView.setSurfaceTextureListener(this);
+            // in case the View's SurfaceTexture already existed
+            if (view.isAvailable()) {
+                SurfaceTexture surfaceTexture = view.getSurfaceTexture();
+                if (surfaceTexture != null) {
+                    this.onSurfaceTextureAvailable(surfaceTexture,
+                        mDesiredWidth, mDesiredHeight);
+                }
+            }
+        }

        @Override
        public void resize(int width, int height) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
-                mTextureView.getSurfaceTexture().setDefaultBufferSize(width, height);
+                final SurfaceTexture surfaceTexture = mTextureView.getSurfaceTexture();
+                if (surfaceTexture != null) {
+                    surfaceTexture.setDefaultBufferSize(width, height);
+                }
            }
            if (mRenderCallback != null) {
                // the call above won't cause TextureView.onSurfaceTextureSizeChanged()
@@ -235,10 +328,69 @@ public class UiHelper {

        @Override
        public void detach() {
-            setSurface(null);
+            mTextureView.setSurfaceTextureListener(null);
        }

-        void setSurface(Surface surface) {
+
+        @Override
+        public void onSurfaceTextureAvailable(
+            @NonNull SurfaceTexture surfaceTexture, int width, int height) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureAvailable()");
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
+                if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                    surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
+                }
+            }
+
+            final Surface surface = new Surface(surfaceTexture);
+            setSurface(surface);
+            createSwapChain(surface);
+
+            if (mRenderCallback != null) {
+                // Call this the first time because onSurfaceTextureSizeChanged()
+                // isn't called at initialization time
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void onSurfaceTextureSizeChanged(
+            @NonNull SurfaceTexture surfaceTexture, int width, int height) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureSizeChanged()");
+            if (mRenderCallback != null) {
+                if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                    surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
+                    mRenderCallback.onResized(mDesiredWidth, mDesiredHeight);
+                } else {
+                    mRenderCallback.onResized(width, height);
+                }
+                // We must recreate the SwapChain to guarantee that it sees the new size.
+                // More precisely, for an EGL client, the EGLSurface must be recreated. For
+                // a Vulkan client, the SwapChain must be recreated. Calling
+                // onNativeWindowChanged() will accomplish that.
+                // This requirement comes from SurfaceTexture.setDefaultBufferSize()
+                // documentation.
+                final Surface surface = getSurface();
+                if (surface != null) {
+                    mRenderCallback.onNativeWindowChanged(surface);
+                }
+            }
+        }
+
+        @Override
+        public boolean onSurfaceTextureDestroyed(@NonNull SurfaceTexture surfaceTexture) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureDestroyed()");
+            setSurface(null);
+            destroySwapChain();
+            return true;
+        }
+
+        @Override
+        public void onSurfaceTextureUpdated(@NonNull SurfaceTexture surface) { }
+
+
+        private void setSurface(@Nullable Surface surface) {
            if (surface == null) {
                if (mSurface != null) {
                    mSurface.release();
@@ -247,7 +399,7 @@ public class UiHelper {
            mSurface = surface;
        }

-        public Surface getSurface() {
+        private Surface getSurface() {
            return mSurface;
        }
    }
@@ -293,6 +445,9 @@ public class UiHelper {
     * {@link #attachTo(TextureView)}, or {@link #attachTo(SurfaceHolder)}.
     */
    public void detach() {
+        if (mRenderSurface != null) {
+            mRenderSurface.detach();
+        }
        destroySwapChain();
        mNativeWindow = null;
        mRenderSurface = null;
@@ -383,7 +538,7 @@ public class UiHelper {
     * the options set on this UiHelper.
     */
    public long getSwapChainFlags() {
-        return isOpaque() ? SwapChain.CONFIG_DEFAULT : SwapChain.CONFIG_TRANSPARENT;
+        return isOpaque() ? SwapChainFlags.CONFIG_DEFAULT : SwapChainFlags.CONFIG_TRANSPARENT;
    }

    /**
@@ -402,48 +557,8 @@ public class UiHelper {
                view.setZOrderOnTop(translucent);
            }

-            int format = isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT;
-            view.getHolder().setFormat(format);
-
+            view.getHolder().setFormat(isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT);
            mRenderSurface = new SurfaceViewHandler(view);
-
-            final SurfaceHolder.Callback callback = new SurfaceHolder.Callback() {
-                @Override
-                public void surfaceCreated(@NonNull SurfaceHolder holder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(
-                    @NonNull SurfaceHolder holder, int format, int width, int height) {
-                    // Note: this is always called at least once after surfaceCreated()
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
-                    if (mRenderCallback != null) {
-                        mRenderCallback.onResized(width, height);
-                    }
-                }
-
-                @Override
-                public void surfaceDestroyed(@NonNull SurfaceHolder holder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
-                    destroySwapChain();
-                }
-            };
-
-            SurfaceHolder holder = view.getHolder();
-            holder.addCallback(callback);
-            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
-            }
-
-            // in case the SurfaceView's surface already existed
-            final Surface surface = holder.getSurface();
-            if (surface != null && surface.isValid()) {
-                callback.surfaceCreated(holder);
-                callback.surfaceChanged(holder, format,
-                        holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
-            }
        }
    }

@@ -455,76 +570,7 @@ public class UiHelper {
    public void attachTo(@NonNull TextureView view) {
        if (attach(view)) {
            view.setOpaque(isOpaque());
-
            mRenderSurface = new TextureViewHandler(view);
-
-            TextureView.SurfaceTextureListener listener = new TextureView.SurfaceTextureListener() {
-                @Override
-                public void onSurfaceTextureAvailable(
-                    @NonNull SurfaceTexture surfaceTexture, int width, int height) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureAvailable()");
-
-                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
-                        if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                            surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
-                        }
-                    }
-
-                    Surface surface = new Surface(surfaceTexture);
-                    TextureViewHandler textureViewHandler = (TextureViewHandler) mRenderSurface;
-                    textureViewHandler.setSurface(surface);
-
-                    createSwapChain(surface);
-
-                    if (mRenderCallback != null) {
-                        // Call this the first time because onSurfaceTextureSizeChanged()
-                        // isn't called at initialization time
-                        mRenderCallback.onResized(width, height);
-                    }
-                }
-
-                @Override
-                public void onSurfaceTextureSizeChanged(
-                    @NonNull SurfaceTexture surfaceTexture, int width, int height) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureSizeChanged()");
-                    if (mRenderCallback != null) {
-                        if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                            surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
-                            mRenderCallback.onResized(mDesiredWidth, mDesiredHeight);
-                        } else {
-                            mRenderCallback.onResized(width, height);
-                        }
-                        // We must recreate the SwapChain to guarantee that it sees the new size.
-                        // More precisely, for an EGL client, the EGLSurface must be recreated. For
-                        // a Vulkan client, the SwapChain must be recreated. Calling
-                        // onNativeWindowChanged() will accomplish that.
-                        // This requirement comes from SurfaceTexture.setDefaultBufferSize()
-                        // documentation.
-                        TextureViewHandler textureViewHandler = (TextureViewHandler) mRenderSurface;
-                        mRenderCallback.onNativeWindowChanged(textureViewHandler.getSurface());
-                    }
-                }
-
-                @Override
-                public boolean onSurfaceTextureDestroyed(@NonNull SurfaceTexture surfaceTexture) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureDestroyed()");
-                    destroySwapChain();
-                    return true;
-                }
-
-                @Override
-                public void onSurfaceTextureUpdated(@NonNull SurfaceTexture surface) { }
-            };
-
-            view.setSurfaceTextureListener(listener);
-
-            // in case the View's SurfaceTexture already existed
-            if (view.isAvailable()) {
-                SurfaceTexture surfaceTexture = view.getSurfaceTexture();
-                if (surfaceTexture != null) {
-                    listener.onSurfaceTextureAvailable(surfaceTexture, mDesiredWidth, mDesiredHeight);
-                }
-            }
        }
    }

@@ -535,46 +581,8 @@ public class UiHelper {
     */
    public void attachTo(@NonNull SurfaceHolder holder) {
        if (attach(holder)) {
-            int format = isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT;
-            holder.setFormat(format);
-
+            holder.setFormat(isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT);
            mRenderSurface = new SurfaceHolderHandler(holder);
-
-            final SurfaceHolder.Callback callback = new SurfaceHolder.Callback() {
-                @Override
-                public void surfaceCreated(@NonNull SurfaceHolder surfaceHolder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(@NonNull SurfaceHolder holder, int format, int width, int height) {
-                    // Note: this is always called at least once after surfaceCreated()
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
-                    if (mRenderCallback != null) {
-                        mRenderCallback.onResized(width, height);
-                    }
-                }
-
-                @Override
-                public void surfaceDestroyed(@NonNull SurfaceHolder surfaceHolder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
-                    destroySwapChain();
-                }
-            };
-
-            holder.addCallback(callback);
-            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
-            }
-
-            // in case the SurfaceHolder's surface already existed
-            final Surface surface = holder.getSurface();
-            if (surface != null && surface.isValid()) {
-                callback.surfaceCreated(holder);
-                callback.surfaceChanged(holder, format,
-                        holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
-            }
        }
    }

@@ -585,6 +593,10 @@ public class UiHelper {
                // nothing to do
                return false;
            }
+            if (mRenderSurface != null) {
+                mRenderSurface.detach();
+                mRenderSurface = null;
+            }
            destroySwapChain();
        }
        mNativeWindow = nativeWindow;
@@ -599,9 +611,6 @@ public class UiHelper {
    }

    private void destroySwapChain() {
-        if (mRenderSurface != null) {
-            mRenderSurface.detach();
-        }
        if (mRenderCallback != null) {
            mRenderCallback.onDetachedFromSurface();
        }
@@ -81,9 +81,20 @@ set(GLTFIO_SRCS
        ${GLTFIO_DIR}/src/TangentsJob.cpp
        ${GLTFIO_DIR}/src/TangentsJob.h
        ${GLTFIO_DIR}/src/UbershaderProvider.cpp
+        ${GLTFIO_DIR}/src/Utility.cpp
+        ${GLTFIO_DIR}/src/Utility.h
        ${GLTFIO_DIR}/src/Wireframe.cpp
        ${GLTFIO_DIR}/src/Wireframe.h
        ${GLTFIO_DIR}/src/downcast.h
+        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.cpp
+        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.h
+        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.cpp
+        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.h
+        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.cpp
+        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.h
+        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.cpp
+        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.h
+

        src/main/cpp/Animator.cpp
        src/main/cpp/AssetLoader.cpp
@@ -144,7 +144,7 @@ public class FilamentInstance {
     *
     * Ignored if variantIndex is out of bounds.
     */
-    void applyMaterialVariant(@IntRange(from = 0) int variantIndex) {
+    public void applyMaterialVariant(@IntRange(from = 0) int variantIndex) {
        nApplyMaterialVariant(mNativeObject, variantIndex);
    }

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.47.0
+VERSION_NAME=1.51.8

 POM_DESCRIPTION=Real-time physically based rendering engine for Android.

@@ -1,6 +1,6 @@
 #Wed Nov 17 10:40:18 PST 2021
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
@@ -30,7 +30,7 @@ android {
    compileSdkVersion versions.compileSdk
    defaultConfig {
        applicationId "com.google.android.filament.gltf"
-        minSdkVersion 19
+        minSdkVersion versions.minSdk
        targetSdkVersion versions.targetSdk
    }

@@ -321,7 +321,7 @@ class MainActivity : Activity() {
            var flags = uiHelper.swapChainFlags
            if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
                if (SwapChain.isSRGBSwapChainSupported(engine)) {
-                    flags = flags or SwapChain.CONFIG_SRGB_COLORSPACE
+                    flags = flags or SwapChainFlags.CONFIG_SRGB_COLORSPACE
                }
            }

@@ -61,6 +61,11 @@ function print_help {
    echo "    -b"
    echo "        Enable Address and Undefined Behavior Sanitizers (asan/ubsan) for debugging."
    echo "        This is only for the desktop build."
+    echo "    -x value"
+    echo "        Define a preprocessor flag FILAMENT_BACKEND_DEBUG_FLAG with [value]. This is useful for"
+    echo "        enabling debug paths in the backend from the build script. For example, make a"
+    echo "        systrace-enabled build without directly changing #defines. Remember to add -f when"
+    echo "        changing this option."
    echo ""
    echo "Build types:"
    echo "    release"
@@ -172,6 +177,8 @@ MATOPT_GRADLE_OPTION=""

 ASAN_UBSAN_OPTION=""

+BACKEND_DEBUG_FLAG_OPTION=""
+
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false

@@ -231,6 +238,7 @@ function build_desktop_target {
            ${MATDBG_OPTION} \
            ${MATOPT_OPTION} \
            ${ASAN_UBSAN_OPTION} \
+            ${BACKEND_DEBUG_FLAG_OPTION} \
            ${architectures} \
            ../..
        ln -sf "out/cmake-${lc_target}/compile_commands.json" \
@@ -289,6 +297,7 @@ function build_webgl_with_target {
            -DCMAKE_BUILD_TYPE="$1" \
            -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \
            -DWEBGL=1 \
+            ${BACKEND_DEBUG_FLAG_OPTION} \
            ../..
        ln -sf "out/cmake-webgl-${lc_target}/compile_commands.json" \
           ../../compile_commands.json
@@ -363,6 +372,7 @@ function build_android_target {
            ${MATDBG_OPTION} \
            ${MATOPT_OPTION} \
            ${VULKAN_ANDROID_OPTION} \
+            ${BACKEND_DEBUG_FLAG_OPTION} \
            ../..
        ln -sf "out/cmake-android-${lc_target}-${arch}/compile_commands.json" \
           ../../compile_commands.json
@@ -516,7 +526,7 @@ function build_android {
            if [[ "${BUILD_ANDROID_SAMPLES}" == "true" ]]; then
                for sample in ${ANDROID_SAMPLES}; do
                    echo "Installing out/${sample}-debug.apk"
-                    cp samples/${sample}/build/outputs/apk/debug/${sample}-debug-unsigned.apk \
+                    cp samples/${sample}/build/outputs/apk/debug/${sample}-debug.apk \
                        ../out/${sample}-debug.apk
                done
            fi
@@ -597,6 +607,7 @@ function build_ios_target {
            -DCMAKE_TOOLCHAIN_FILE=../../third_party/clang/iOS.cmake \
            ${MATDBG_OPTION} \
            ${MATOPT_OPTION} \
+            ${BACKEND_DEBUG_FLAG_OPTION} \
            ../..
        ln -sf "out/cmake-ios-${lc_target}-${arch}/compile_commands.json" \
           ../../compile_commands.json
@@ -730,6 +741,13 @@ function validate_build_command {
            exit 1
        fi
    fi
+
+    # Make sure FILAMENT_BACKEND_DEBUG_FLAG is only meant for debug builds
+    if [[ "${ISSUE_DEBUG_BUILD}" != "true" ]] && [[ ! -z "${BACKEND_DEBUG_FLAG_OPTION}" ]]; then
+        echo "Error: cannot specify FILAMENT_BACKEND_DEBUG_FLAG in non-debug build"
+        exit 1
+    fi
+
    set -e
 }

@@ -776,7 +794,7 @@ function check_debug_release_build {

 pushd "$(dirname "$0")" > /dev/null

-while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
+while getopts ":hacCfgijmp:q:uvslwtedk:bx:" opt; do
    case ${opt} in
        h)
            print_help
@@ -840,7 +858,7 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
                        echo "Platform must be one of [desktop|android|ios|webgl|all]"
                        echo ""
                        exit 1
-                    ;;    
+                    ;;
                esac
            done
            ;;
@@ -918,6 +936,8 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
        b)  ASAN_UBSAN_OPTION="-DFILAMENT_ENABLE_ASAN_UBSAN=ON"
            echo "Enabled ASAN/UBSAN"
            ;;
+        x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
+            ;;
        \?)
            echo "Invalid option: -${OPTARG}" >&2
            echo ""
@@ -1 +1 @@
-25.1.8937393
+26.1.10909125
@@ -50,7 +50,7 @@ function replace {
    FIND_STR="${1//\{\{VERSION\}\}/${VERSION_REGEX}}"
    REPLACE_STR="${1//\{\{VERSION\}\}/${NEW_VERSION}}"
    local FILE_NAME="$2"
-    if [ IS_DARWIN ]; then
+    if [ $IS_DARWIN == 1 ]; then
        sed -i '' -E "s/${FIND_STR}/${REPLACE_STR}/" "${FILE_NAME}"
    else
        sed -i -E "s/${FIND_STR}/${REPLACE_STR}/" "${FILE_NAME}"
@@ -125,7 +125,13 @@ if [[ "${has_universal}" == "true" ]]; then

        arch_output="${OUTPUT_PATH%.a}_${arch}.a"
        arch_outputs+=("$arch_output")
-        combine_static_libs "$arch_output" $(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a')
+
+        archives=()
+        while IFS=  read -r -d $'\0'; do
+            archives+=("$REPLY")
+        done < <(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a' -print0)
+
+        combine_static_libs "$arch_output" "$archives"
    done

    # Finally, combine the single-architecture archives into a universal binary.
@@ -21,7 +21,7 @@ set(CMAKE_SYSTEM_NAME Linux)
 set(CMAKE_SYSTEM_VERSION 1)

 # android
-set(API_LEVEL 19)
+set(API_LEVEL 21)

 # architecture
 set(ARCH armv7a-linux-androideabi)
@@ -21,7 +21,7 @@ set(CMAKE_SYSTEM_NAME Linux)
 set(CMAKE_SYSTEM_VERSION 1)

 # android
-set(API_LEVEL 19)
+set(API_LEVEL 21)

 # architecture
 set(ARCH i686-linux-android)
@@ -476,7 +476,7 @@ Energy conservation is one of the key components of a good BRDF for physically b
 <p>


-For the specular term, \(f_m\) is a mirror BRDF that can be modeled with the Fresnel law, noted \(F\) in the Cook-Torrance approximation of the microfacet model integration:
+For the specular term, \(f_r\) is a mirror BRDF that can be modeled with the Fresnel law, noted \(F\) in the Cook-Torrance approximation of the microfacet model integration:

 </p><p>

@@ -857,7 +857,7 @@ The full GLSL implementation of the standard model is shown in <a href="#listing
 <span class="line">    <span class="hljs-comment">// perceptually linear roughness to roughness (see parameterization)</span></span>
 <span class="line">    <span class="hljs-type">float</span> roughness = perceptualRoughness * perceptualRoughness;</span>
 <span class="line"></span>
-<span class="line">    <span class="hljs-type">float</span> D = D_GGX(NoH, a);</span>
+<span class="line">    <span class="hljs-type">float</span> D = D_GGX(NoH, roughness);</span>
 <span class="line">    <span class="hljs-type">vec3</span>  F = F_Schlick(LoH, f0);</span>
 <span class="line">    <span class="hljs-type">float</span> V = V_SmithGGXCorrelated(NoV, NoL, roughness);</span>
 <span class="line"></span>
@@ -1397,7 +1397,7 @@ Type
 :    `string`

 Value
-:     Any of `opaque`, `transparent`, `fade`, `add`, `masked`, `multiply`, `screen`. Defaults to `opaque`.
+:     Any of `opaque`, `transparent`, `fade`, `add`, `masked`, `multiply`, `screen`, `custom`. Defaults to `opaque`.

 Description
 :     Defines how/if the rendered object is blended with the content of the render target.
@@ -1420,6 +1420,7 @@ Description
      of the material's output defines whether a fragment is discarded or not. Additionally,
      ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
      information.
+    - **Custom**: blending is enabled. But the blending function is user specified. See `blendFunction`.

 !!! Note
    When `blending` is set to `masked`, alpha to coverage is automatically enabled for the material.
@@ -1432,6 +1433,36 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+### Blending and transparency: blendFunction
+
+Type
+:    `object`
+
+Fields
+:     `srcRGB`, `srcA`, `dstRGB`, `dstA`
+
+Description
+:       - *srcRGB*: source function applied to the RGB channels
+        - *srcA*: source function applied to the alpha channel
+        - *srcRGB*: destination function applied to the RGB channels
+        - *srcRGB*: destination function applied to the alpha channel
+        The values possible for each functions are one of `zero`, `one`, `srcColor`, `oneMinusSrcColor`,
+               `dstColor`, `oneMinusDstColor`, `srcAlpha`, `oneMinusSrcAlpha`, `dstAlpha`,
+               `oneMinusDstAlpha`, `srcAlphaSaturate`
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    blending : custom,
+    blendFunction :
+    {
+        srcRGB: one,
+        srcA: one,
+        dstRGB: oneMinusSrcColor,
+        dstA: oneMinusSrcAlpha
+    }
+ }
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Blending and transparency: postLightingBlending

 Type
@@ -2394,6 +2425,7 @@ The following APIs are only available from the vertex block:
 **getWorldFromModelMatrix()**        | float4x4 |  Matrix that converts from model (object) space to world space
 **getWorldFromModelNormalMatrix()**  | float3x3 |  Matrix that converts normals from model (object) space to world space
 **getVertexIndex()**                 | int      |  Index of the current vertex
+**getEyeIndex()**                    | int      |  Index of the eye being rendered, starting at 0

 ### Fragment only

@@ -43,7 +43,7 @@ filament-viewer::part(canvas) {
 </p>

 </main>
-<script src="https://unpkg.com/filament@1.44.0/filament.js"></script>
+<script src="https://unpkg.com/filament@1.51.6/filament.js"></script>
 <script src="https://unpkg.com/gltumble"></script>
 <script src="filament-viewer.js" type="module"></script>
 </body>
@@ -587,6 +587,7 @@
 <li><em>overrides</em> Dictionary with one or more of the following properties: mapSize, shadowCascades, constantBias, normalBias, shadowFar, shadowNearHint, shadowFarHint, stable, polygonOffsetConstant, polygonOffsetSlope, \</li>
 </ul>
 </li>
+<li><strong>engine.setStereoscopicOptions()</strong></li>
 <li><strong>engine.setTemporalAntiAliasingOptions()</strong></li>
 <li><strong>engine.setVignetteOptions()</strong></li>
 </ul>
@@ -1462,6 +1463,8 @@ This defines the following functions:</p>
 <li>STENCIL_ATTACHMENT</li>
 <li>UPLOADABLE</li>
 <li>SAMPLEABLE</li>
+<li>BLIT_SRC</li>
+<li>BLIT_DST</li>
 <li>SUBPASS_INPUT</li>
 </ul>
 </div>
@@ -66,6 +66,7 @@ set(SRCS
        src/Froxelizer.cpp
        src/Frustum.cpp
        src/HwRenderPrimitiveFactory.cpp
+        src/HwVertexBufferInfoFactory.cpp
        src/IndexBuffer.cpp
        src/IndirectLight.cpp
        src/InstanceBuffer.cpp
@@ -137,6 +138,7 @@ set(SRCS

 set(PRIVATE_HDRS
        src/Allocators.h
+        src/Bimap.h
        src/BufferPoolAllocator.h
        src/ColorSpaceUtils.h
        src/Culler.h
@@ -147,6 +149,7 @@ set(PRIVATE_HDRS
        src/FrameSkipper.h
        src/Froxelizer.h
        src/HwRenderPrimitiveFactory.h
+        src/HwVertexBufferInfoFactory.h
        src/Intersections.h
        src/MaterialParser.h
        src/PerViewUniforms.h
@@ -160,6 +163,7 @@ set(PRIVATE_HDRS
        src/ResourceList.h
        src/ShadowMap.h
        src/ShadowMapManager.h
+        src/SharedHandle.h
        src/TypedUniformBuffer.h
        src/UniformBuffer.h
        src/components/CameraManager.h
@@ -209,10 +213,15 @@ set(PRIVATE_HDRS
 )

 set(MATERIAL_SRCS
-        src/materials/fsr/fsr_easu.mat
-        src/materials/fsr/fsr_easu_mobile.mat
-        src/materials/fsr/fsr_easu_mobileF.mat
-        src/materials/fsr/fsr_rcas.mat
+        src/materials/antiAliasing/fxaa.mat
+        src/materials/antiAliasing/taa.mat
+        src/materials/blitDepth.mat
+        src/materials/blitLow.mat
+        src/materials/blitArray.mat
+        src/materials/bloom/bloomDownsample.mat
+        src/materials/bloom/bloomDownsample2x.mat
+        src/materials/bloom/bloomDownsample9.mat
+        src/materials/bloom/bloomUpsample.mat
        src/materials/colorGrading/colorGrading.mat
        src/materials/colorGrading/colorGradingAsSubpass.mat
        src/materials/colorGrading/customResolveAsSubpass.mat
@@ -220,34 +229,38 @@ set(MATERIAL_SRCS
        src/materials/defaultMaterial.mat
        src/materials/dof/dof.mat
        src/materials/dof/dofCoc.mat
-        src/materials/dof/dofDownsample.mat
        src/materials/dof/dofCombine.mat
+        src/materials/dof/dofDilate.mat
+        src/materials/dof/dofDownsample.mat
+        src/materials/dof/dofMedian.mat
+        src/materials/dof/dofMipmap.mat
        src/materials/dof/dofTiles.mat
        src/materials/dof/dofTilesSwizzle.mat
-        src/materials/dof/dofDilate.mat
-        src/materials/dof/dofMipmap.mat
-        src/materials/dof/dofMedian.mat
        src/materials/flare/flare.mat
-        src/materials/bloom/bloomDownsample.mat
-        src/materials/bloom/bloomDownsample2x.mat
-        src/materials/bloom/bloomDownsample9.mat
-        src/materials/bloom/bloomUpsample.mat
+        src/materials/fsr/fsr_easu.mat
+        src/materials/fsr/fsr_easu_mobile.mat
+        src/materials/fsr/fsr_easu_mobileF.mat
+        src/materials/fsr/fsr_rcas.mat
+        src/materials/resolveDepth.mat
+        src/materials/separableGaussianBlur.mat
+        src/materials/skybox.mat
+        src/materials/shadowmap.mat
        src/materials/ssao/bilateralBlur.mat
        src/materials/ssao/bilateralBlurBentNormals.mat
        src/materials/ssao/mipmapDepth.mat
-        src/materials/skybox.mat
        src/materials/ssao/sao.mat
        src/materials/ssao/saoBentNormals.mat
-        src/materials/separableGaussianBlur.mat
-        src/materials/antiAliasing/fxaa.mat
-        src/materials/antiAliasing/taa.mat
        src/materials/vsmMipmap.mat
-        src/materials/blitLow.mat
 )

 set(MATERIAL_FL0_SRCS
-        src/materials/defaultMaterial0.mat
-        src/materials/skybox0.mat
+        src/materials/defaultMaterial.mat
+        src/materials/skybox.mat
+)
+
+set(MATERIAL_MULTIVIEW_SRCS
+        src/materials/defaultMaterial.mat
+        src/materials/skybox.mat
 )

 # Embed the binary resource blob for materials.
@@ -279,6 +292,11 @@ if (FILAMENT_ENABLE_FEATURE_LEVEL_0)
    add_definitions(-DFILAMENT_ENABLE_FEATURE_LEVEL_0)
 endif()

+# Whether to include MULTIVIEW materials.
+if (FILAMENT_ENABLE_MULTIVIEW)
+    add_definitions(-DFILAMENT_ENABLE_MULTIVIEW)
+endif()
+
 # ==================================================================================================
 # Definitions
 # ==================================================================================================
@@ -309,33 +327,42 @@ foreach (mat_src ${MATERIAL_SRCS})
    get_filename_component(localname "${mat_src}" NAME_WE)
    get_filename_component(fullname "${mat_src}" ABSOLUTE)
    set(output_path "${MATERIAL_DIR}/${localname}.filamat")
-
    add_custom_command(
            OUTPUT ${output_path}
            COMMAND matc ${MATC_BASE_FLAGS} -o ${output_path} ${fullname}
            MAIN_DEPENDENCY ${fullname}
            DEPENDS matc
-            COMMENT "Compiling material ${mat_src} to ${output_path}"
+            COMMENT "Compiling material ${fullname} to ${output_path}"
    )
    list(APPEND MATERIAL_BINS ${output_path})
-endforeach()
-
-if (FILAMENT_ENABLE_FEATURE_LEVEL_0 AND FILAMENT_SUPPORTS_OPENGL)
-    foreach (mat_src ${MATERIAL_FL0_SRCS})
-        get_filename_component(localname "${mat_src}" NAME_WE)
-        get_filename_component(fullname "${mat_src}" ABSOLUTE)
-        set(output_path "${MATERIAL_DIR}/${localname}.filamat")

+    list(FIND MATERIAL_FL0_SRCS ${mat_src} index)
+    if (${index} GREATER -1 AND FILAMENT_ENABLE_FEATURE_LEVEL_0)
+        string(REGEX REPLACE "[.]filamat$" "_fl0.filamat" output_path_fl0 ${output_path})
        add_custom_command(
-                OUTPUT ${output_path}
-                COMMAND matc -a opengl -p ${MATC_TARGET} ${MATC_OPT_FLAGS} -o ${output_path} ${fullname}
+                OUTPUT ${output_path_fl0}
+                COMMAND matc ${MATC_BASE_FLAGS} -PfeatureLevel=0 -o ${output_path_fl0} ${fullname}
                MAIN_DEPENDENCY ${fullname}
                DEPENDS matc
-                COMMENT "Compiling material ${mat_src} to ${output_path}"
+                COMMENT "Compiling material ${fullname} to ${output_path_fl0}"
        )
-        list(APPEND MATERIAL_BINS ${output_path})
-    endforeach ()
-endif ()
+        list(APPEND MATERIAL_BINS ${output_path_fl0})
+    endif ()
+
+    list(FIND MATERIAL_MULTIVIEW_SRCS ${mat_src} index)
+    if (${index} GREATER -1 AND FILAMENT_ENABLE_MULTIVIEW)
+        string(REGEX REPLACE "[.]filamat$" "_multiview.filamat" output_path_multiview ${output_path})
+        add_custom_command(
+                OUTPUT ${output_path_multiview}
+                COMMAND matc ${MATC_BASE_FLAGS} -PstereoscopicType=multiview -o ${output_path_multiview} ${fullname}
+                MAIN_DEPENDENCY ${fullname}
+                DEPENDS matc
+                COMMENT "Compiling material ${fullname} to ${output_path_multiview}"
+        )
+        list(APPEND MATERIAL_BINS ${output_path_multiview})
+    endif ()
+
+endforeach()

 # Additional dependencies on included files for materials

@@ -71,6 +71,8 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
            include/backend/platforms/OpenGLPlatform.h
            src/opengl/gl_headers.cpp
            src/opengl/gl_headers.h
+            src/opengl/GLBufferObject.h
+            src/opengl/GLTexture.h
            src/opengl/GLUtils.cpp
            src/opengl/GLUtils.h
            src/opengl/OpenGLBlobCache.cpp
@@ -166,9 +168,15 @@ endif()
 if (FILAMENT_SUPPORTS_VULKAN)
    list(APPEND SRCS
            include/backend/platforms/VulkanPlatform.h
+            src/vulkan/caching/VulkanDescriptorSetManager.cpp
+            src/vulkan/caching/VulkanDescriptorSetManager.h
+            src/vulkan/caching/VulkanPipelineLayoutCache.cpp
+            src/vulkan/caching/VulkanPipelineLayoutCache.h
            src/vulkan/platform/VulkanPlatform.cpp
            src/vulkan/platform/VulkanPlatformSwapChainImpl.cpp
            src/vulkan/platform/VulkanPlatformSwapChainImpl.h
+            src/vulkan/spirv/VulkanSpirvUtils.cpp
+            src/vulkan/spirv/VulkanSpirvUtils.h
            src/vulkan/VulkanBlitter.cpp
            src/vulkan/VulkanBlitter.h
            src/vulkan/VulkanBuffer.cpp
@@ -313,6 +321,7 @@ endif()

 if (FILAMENT_SUPPORTS_VULKAN)
    target_link_libraries(${TARGET} PUBLIC bluevk vkmemalloc vkshaders smol-v)
+    target_link_libraries(${TARGET} PRIVATE SPIRV-Headers)
 endif()

 if (FILAMENT_SUPPORTS_METAL)
@@ -397,8 +406,8 @@ install(DIRECTORY ${PUBLIC_HDR_DIR}/backend DESTINATION include)
 # ==================================================================================================
 option(INSTALL_BACKEND_TEST "Install the backend test library so it can be consumed on iOS" OFF)

-if (APPLE)
-    add_library(backend_test STATIC
+if (APPLE OR LINUX)
+    set(BACKEND_TEST_SRC
        test/BackendTest.cpp
        test/ShaderGenerator.cpp
        test/TrianglePrimitive.cpp
@@ -410,19 +419,26 @@ if (APPLE)
        test/test_BufferUpdates.cpp
        test/test_MRT.cpp
        test/test_LoadImage.cpp
-        test/test_RenderExternalImage.cpp
        test/test_StencilBuffer.cpp
        test/test_Scissor.cpp
        test/test_MipLevels.cpp
-        )
-
-    target_link_libraries(backend_test PRIVATE
+    )
+    set(BACKEND_TEST_LIBS
        backend
        getopt
        gtest
+        imageio
        filamat
        SPIRV
        spirv-cross-glsl)
+endif()
+
+if (APPLE)
+    # TODO: we should expand this test to Linux and other platforms.
+    list(APPEND BACKEND_TEST_SRC
+         test/test_RenderExternalImage.cpp)
+    add_library(backend_test STATIC ${BACKEND_TEST_SRC})
+    target_link_libraries(backend_test PRIVATE ${BACKEND_TEST_LIBS})

    set(BACKEND_TEST_DEPS
            OGLCompiler
@@ -436,12 +452,11 @@ if (APPLE)
            glslang
            spirv-cross-core
            spirv-cross-glsl
-            spirv-cross-msl
-            )
+            spirv-cross-msl)

    if (NOT IOS)
        target_link_libraries(backend_test PRIVATE image imageio)
-        list(APPEND BACKEND_TEST_DEPS image imageio)
+        list(APPEND BACKEND_TEST_DEPS image)
    endif()

    set(BACKEND_TEST_COMBINED_OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/libbackendtest_combined.a")
@@ -455,15 +470,25 @@ if (APPLE)
    endif()

    set_target_properties(backend_test PROPERTIES FOLDER Tests)
+
+    if (APPLE AND NOT IOS)
+       add_executable(backend_test_mac test/mac_runner.mm)
+       target_link_libraries(backend_test_mac PRIVATE "-framework Metal -framework AppKit -framework QuartzCore")
+       # Because each test case is a separate file, the -force_load flag is necessary to prevent the
+       # linker from removing "unused" symbols.
+       target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
+       set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+
+       # This is needed after XCode 15.3
+       set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
+       set_target_properties(backend_test_mac PROPERTIES INSTALL_RPATH /usr/local/lib)
+    endif()
 endif()

-if (APPLE AND NOT IOS)
-    add_executable(backend_test_mac test/mac_runner.mm)
-    target_link_libraries(backend_test_mac PRIVATE "-framework Metal -framework AppKit -framework QuartzCore")
-    # Because each test case is a separate file, the -force_load flag is necessary to prevent the
-    # linker from removing "unused" symbols.
-    target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
-    set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+if (LINUX)
+    add_executable(backend_test_linux test/linux_runner.cpp ${BACKEND_TEST_SRC})
+    target_link_libraries(backend_test_linux PRIVATE ${BACKEND_TEST_LIBS})
+    set_target_properties(backend_test_linux PROPERTIES FOLDER Tests)
 endif()

 # ==================================================================================================
@@ -23,7 +23,6 @@
 #include <utils/ostream.h>

 #include <stddef.h>
-#include <stdint.h>

 namespace filament::backend {

@@ -17,8 +17,6 @@
 #ifndef TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H
 #define TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H

-#include <utils/compiler.h>
-
 namespace filament::backend {

 /**
@@ -24,11 +24,14 @@

 #include <backend/PresentCallable.h>

+#include <utils/Invocable.h>
 #include <utils/ostream.h>

 #include <math/vec4.h>

-#include <array>    // FIXME: STL headers are not allowed in public headers
+#include <array>        // FIXME: STL headers are not allowed in public headers
+#include <type_traits>  // FIXME: STL headers are not allowed in public headers
+#include <variant>      // FIXME: STL headers are not allowed in public headers

 #include <stddef.h>
 #include <stdint.h>
@@ -80,14 +83,24 @@ static constexpr uint64_t SWAP_CHAIN_CONFIG_SRGB_COLORSPACE     = 0x10;
 /**
 * Indicates that the SwapChain should also contain a stencil component.
 */
-static constexpr uint64_t SWAP_CHAIN_HAS_STENCIL_BUFFER         = 0x20;
+static constexpr uint64_t SWAP_CHAIN_CONFIG_HAS_STENCIL_BUFFER  = 0x20;
+static constexpr uint64_t SWAP_CHAIN_HAS_STENCIL_BUFFER         = SWAP_CHAIN_CONFIG_HAS_STENCIL_BUFFER;

+/**
+ * The SwapChain contains protected content. Currently only supported by OpenGLPlatform and
+ * only when OpenGLPlatform::isProtectedContextSupported() is true.
+ */
+static constexpr uint64_t SWAP_CHAIN_CONFIG_PROTECTED_CONTENT   = 0x40;

 static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT  = 16;   // This is guaranteed by OpenGL ES.
 static constexpr size_t MAX_SAMPLER_COUNT           = 62;   // Maximum needed at feature level 3.
 static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
 static constexpr size_t MAX_SSBO_COUNT              = 4;    // This is guaranteed by OpenGL ES.

+static constexpr size_t MAX_PUSH_CONSTANT_COUNT     = 32;   // Vulkan 1.1 spec allows for 128-byte
+                                                            // of push constant (we assume 4-byte
+                                                            // types).
+
 // Per feature level caps
 // Use (int)FeatureLevel to index this array
 static constexpr struct {
@@ -128,6 +141,12 @@ enum class Backend : uint8_t {
    NOOP = 4,     //!< Selects the no-op driver for testing purposes.
 };

+enum class TimerQueryResult : int8_t {
+    ERROR = -1,     // an error occurred, result won't be available
+    NOT_READY = 0,  // result to ready yet
+    AVAILABLE = 1,  // result is available
+};
+
 static constexpr const char* backendToString(Backend backend) {
    switch (backend) {
        case Backend::NOOP:
@@ -144,14 +163,16 @@ static constexpr const char* backendToString(Backend backend) {
 }

 /**
- * Defines the shader language. Similar to the above backend enum, but the OpenGL backend can select
- * between two shader languages: ESSL 1.0 and ESSL 3.0.
+ * Defines the shader language. Similar to the above backend enum, with some differences:
+ * - The OpenGL backend can select between two shader languages: ESSL 1.0 and ESSL 3.0.
+ * - The Metal backend can prefer precompiled Metal libraries, while falling back to MSL.
 */
 enum class ShaderLanguage {
    ESSL1 = 0,
    ESSL3 = 1,
    SPIRV = 2,
    MSL = 3,
+    METAL_LIBRARY = 4,
 };

 static constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguage) {
@@ -164,6 +185,8 @@ static constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguag
            return "SPIR-V";
        case ShaderLanguage::MSL:
            return "MSL";
+        case ShaderLanguage::METAL_LIBRARY:
+            return "Metal precompiled library";
    }
 }

@@ -227,6 +250,7 @@ struct Viewport {
    int32_t top() const noexcept { return bottom + int32_t(height); }
 };

+
 /**
 * Specifies the mapping of the near and far clipping plane to window coordinates.
 */
@@ -312,7 +336,7 @@ enum class UniformType : uint8_t {
 /**
 * Supported constant parameter types
 */
- enum class ConstantType : uint8_t {
+enum class ConstantType : uint8_t {
  INT,
  FLOAT,
  BOOL
@@ -657,14 +681,17 @@ enum class TextureFormat : uint16_t {
 };

 //! Bitmask describing the intended Texture Usage
-enum class TextureUsage : uint8_t {
-    NONE                = 0x0,
-    COLOR_ATTACHMENT    = 0x1,                      //!< Texture can be used as a color attachment
-    DEPTH_ATTACHMENT    = 0x2,                      //!< Texture can be used as a depth attachment
-    STENCIL_ATTACHMENT  = 0x4,                      //!< Texture can be used as a stencil attachment
-    UPLOADABLE          = 0x8,                      //!< Data can be uploaded into this texture (default)
-    SAMPLEABLE          = 0x10,                     //!< Texture can be sampled (default)
-    SUBPASS_INPUT       = 0x20,                     //!< Texture can be used as a subpass input
+enum class TextureUsage : uint16_t {
+    NONE                = 0x0000,
+    COLOR_ATTACHMENT    = 0x0001,            //!< Texture can be used as a color attachment
+    DEPTH_ATTACHMENT    = 0x0002,            //!< Texture can be used as a depth attachment
+    STENCIL_ATTACHMENT  = 0x0004,            //!< Texture can be used as a stencil attachment
+    UPLOADABLE          = 0x0008,            //!< Data can be uploaded into this texture (default)
+    SAMPLEABLE          = 0x0010,            //!< Texture can be sampled (default)
+    SUBPASS_INPUT       = 0x0020,            //!< Texture can be used as a subpass input
+    BLIT_SRC            = 0x0040,            //!< Texture can be used the source of a blit()
+    BLIT_DST            = 0x0080,            //!< Texture can be used the destination of a blit()
+    PROTECTED           = 0x0100,            //!< Texture can be used for protected content
    DEFAULT             = UPLOADABLE | SAMPLEABLE   //!< Default texture usage
 };

@@ -692,6 +719,17 @@ static constexpr bool isDepthFormat(TextureFormat format) noexcept {
    }
 }

+static constexpr bool isStencilFormat(TextureFormat format) noexcept {
+    switch (format) {
+        case TextureFormat::STENCIL8:
+        case TextureFormat::DEPTH24_STENCIL8:
+        case TextureFormat::DEPTH32F_STENCIL8:
+            return true;
+        default:
+            return false;
+    }
+}
+
 static constexpr bool isUnsignedIntFormat(TextureFormat format) {
    switch (format) {
        case TextureFormat::R8UI:
@@ -1157,11 +1195,27 @@ struct StencilState {

    //! Stencil operations for front-facing polygons
    StencilOperations front = {
-            .stencilFunc = StencilFunction::A, .ref = 0, .readMask = 0xff, .writeMask = 0xff };
+            .stencilFunc = StencilFunction::A,
+            .stencilOpStencilFail = StencilOperation::KEEP,
+            .padding0 = 0,
+            .stencilOpDepthFail = StencilOperation::KEEP,
+            .stencilOpDepthStencilPass = StencilOperation::KEEP,
+            .padding1 = 0,
+            .ref = 0,
+            .readMask = 0xff,
+            .writeMask = 0xff };

    //! Stencil operations for back-facing polygons
    StencilOperations back  = {
-            .stencilFunc = StencilFunction::A, .ref = 0, .readMask = 0xff, .writeMask = 0xff };
+            .stencilFunc = StencilFunction::A,
+            .stencilOpStencilFail = StencilOperation::KEEP,
+            .padding0 = 0,
+            .stencilOpDepthFail = StencilOperation::KEEP,
+            .stencilOpDepthStencilPass = StencilOperation::KEEP,
+            .padding1 = 0,
+            .ref = 0,
+            .readMask = 0xff,
+            .writeMask = 0xff };

    //! Whether stencil-buffer writes are enabled
    bool stencilWrite = false;
@@ -1169,19 +1223,21 @@ struct StencilState {
    uint8_t padding = 0;
 };

+using PushConstantVariant = std::variant<int32_t, float, bool>;
+
 static_assert(sizeof(StencilState::StencilOperations) == 5u,
        "StencilOperations size not what was intended");

 static_assert(sizeof(StencilState) == 12u,
        "StencilState size not what was intended");

-using FrameScheduledCallback = void(*)(PresentCallable callable, void* user);
+using FrameScheduledCallback = utils::Invocable<void(backend::PresentCallable)>;

 enum class Workaround : uint16_t {
    // The EASU pass must split because shader compiler flattens early-exit branch
    SPLIT_EASU,
-    // Backend allows feedback loop with ancillary buffers (depth/stencil) as long as they're read-only for
-    // the whole render pass.
+    // Backend allows feedback loop with ancillary buffers (depth/stencil) as long as they're
+    // read-only for the whole render pass.
    ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP,
    // for some uniform arrays, it's needed to do an initialization to avoid crash on adreno gpu
    ADRENO_UNIFORM_ARRAY_CRASH,
@@ -1192,9 +1248,14 @@ enum class Workaround : uint16_t {
    DISABLE_BLIT_INTO_TEXTURE_ARRAY,
    // Multiple workarounds needed for PowerVR GPUs
    POWER_VR_SHADER_WORKAROUNDS,
-    // The driver has some threads pinned, and we can't easily know on which core, it can hurt
-    // performance more if we end-up pinned on the same one.
-    DISABLE_THREAD_AFFINITY
+};
+
+//! The type of technique for stereoscopic rendering
+enum class StereoscopicType : uint8_t {
+    // Stereoscopic rendering is performed using instanced rendering technique.
+    INSTANCED,
+    // Stereoscopic rendering is performed using the multiview feature from the graphics backend.
+    MULTIVIEW,
 };

 } // namespace filament::backend
@@ -17,16 +17,14 @@
 #ifndef TNT_FILAMENT_BACKEND_HANDLE_H
 #define TNT_FILAMENT_BACKEND_HANDLE_H

-#include <utils/compiler.h>
 #if !defined(NDEBUG)
-#include <utils/Log.h>
+#include <utils/ostream.h>
 #endif
 #include <utils/debug.h>

-#include <stdint.h>
+#include <type_traits> // FIXME: STL headers are not allowed in public headers

-#include <limits>
-#include <type_traits>
+#include <stdint.h>

 namespace filament::backend {

@@ -41,6 +39,7 @@ struct HwStream;
 struct HwSwapChain;
 struct HwTexture;
 struct HwTimerQuery;
+struct HwVertexBufferInfo;
 struct HwVertexBuffer;

 /*
@@ -54,7 +53,7 @@ struct HwVertexBuffer;
 class HandleBase {
 public:
    using HandleId = uint32_t;
-    static constexpr const HandleId nullid = HandleId{ std::numeric_limits<HandleId>::max() };
+    static constexpr const HandleId nullid = HandleId{ UINT32_MAX };

    constexpr HandleBase() noexcept: object(nullid) {}

@@ -64,14 +63,6 @@ public:
    // clear the handle, this doesn't free associated resources
    void clear() noexcept { object = nullid; }

-    // compare handles
-    bool operator==(const HandleBase& rhs) const noexcept { return object == rhs.object; }
-    bool operator!=(const HandleBase& rhs) const noexcept { return object != rhs.object; }
-    bool operator<(const HandleBase& rhs) const noexcept { return object < rhs.object; }
-    bool operator<=(const HandleBase& rhs) const noexcept { return object <= rhs.object; }
-    bool operator>(const HandleBase& rhs) const noexcept { return object > rhs.object; }
-    bool operator>=(const HandleBase& rhs) const noexcept { return object >= rhs.object; }
-
    // get this handle's handleId
    HandleId getId() const noexcept { return object; }

@@ -84,6 +75,19 @@ protected:
    HandleBase(HandleBase const& rhs) noexcept = default;
    HandleBase& operator=(HandleBase const& rhs) noexcept = default;

+    HandleBase(HandleBase&& rhs) noexcept
+            : object(rhs.object) {
+        rhs.object = nullid;
+    }
+
+    HandleBase& operator=(HandleBase&& rhs) noexcept {
+        if (this != &rhs) {
+            object = rhs.object;
+            rhs.object = nullid;
+        }
+        return *this;
+    }
+
 private:
    HandleId object;
 };
@@ -98,11 +102,21 @@ struct Handle : public HandleBase {
    Handle() noexcept = default;

    Handle(Handle const& rhs) noexcept = default;
+    Handle(Handle&& rhs) noexcept = default;

    Handle& operator=(Handle const& rhs) noexcept = default;
+    Handle& operator=(Handle&& rhs) noexcept = default;

    explicit Handle(HandleId id) noexcept : HandleBase(id) { }

+    // compare handles of the same type
+    bool operator==(const Handle& rhs) const noexcept { return getId() == rhs.getId(); }
+    bool operator!=(const Handle& rhs) const noexcept { return getId() != rhs.getId(); }
+    bool operator<(const Handle& rhs) const noexcept { return getId() < rhs.getId(); }
+    bool operator<=(const Handle& rhs) const noexcept { return getId() <= rhs.getId(); }
+    bool operator>(const Handle& rhs) const noexcept { return getId() > rhs.getId(); }
+    bool operator>=(const Handle& rhs) const noexcept { return getId() >= rhs.getId(); }
+
    // type-safe Handle cast
    template<typename B, typename = std::enable_if_t<std::is_base_of<T, B>::value> >
    Handle(Handle<B> const& base) noexcept : HandleBase(base) { } // NOLINT(hicpp-explicit-conversions,google-explicit-constructor)
@@ -116,18 +130,19 @@ private:

 // Types used by the command stream
 // (we use this renaming because the macro-system doesn't deal well with "<" and ">")
-using BufferObjectHandle    = Handle<HwBufferObject>;
-using FenceHandle           = Handle<HwFence>;
-using IndexBufferHandle     = Handle<HwIndexBuffer>;
-using ProgramHandle         = Handle<HwProgram>;
-using RenderPrimitiveHandle = Handle<HwRenderPrimitive>;
-using RenderTargetHandle    = Handle<HwRenderTarget>;
-using SamplerGroupHandle    = Handle<HwSamplerGroup>;
-using StreamHandle          = Handle<HwStream>;
-using SwapChainHandle       = Handle<HwSwapChain>;
-using TextureHandle         = Handle<HwTexture>;
-using TimerQueryHandle      = Handle<HwTimerQuery>;
-using VertexBufferHandle    = Handle<HwVertexBuffer>;
+using BufferObjectHandle     = Handle<HwBufferObject>;
+using FenceHandle            = Handle<HwFence>;
+using IndexBufferHandle      = Handle<HwIndexBuffer>;
+using ProgramHandle          = Handle<HwProgram>;
+using RenderPrimitiveHandle  = Handle<HwRenderPrimitive>;
+using RenderTargetHandle     = Handle<HwRenderTarget>;
+using SamplerGroupHandle     = Handle<HwSamplerGroup>;
+using StreamHandle           = Handle<HwStream>;
+using SwapChainHandle        = Handle<HwSwapChain>;
+using TextureHandle          = Handle<HwTexture>;
+using TimerQueryHandle       = Handle<HwTimerQuery>;
+using VertexBufferHandle     = Handle<HwVertexBuffer>;
+using VertexBufferInfoHandle = Handle<HwVertexBufferInfo>;

 } // namespace filament::backend

@@ -20,7 +20,7 @@
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>

-#include <limits>
+#include <utils/ostream.h>

 #include <stdint.h>

@@ -29,14 +29,13 @@ namespace filament::backend {
 //! \privatesection

 struct PipelineState {
-    Handle<HwProgram> program;
-    RasterState rasterState;
-    StencilState stencilState;
-    PolygonOffset polygonOffset;
-    Viewport scissor{ 0, 0,
-                      (uint32_t)std::numeric_limits<int32_t>::max(),
-                      (uint32_t)std::numeric_limits<int32_t>::max()
-    };
+    Handle<HwProgram> program;                                              //  4
+    Handle<HwVertexBufferInfo> vertexBufferInfo;                            //  4
+    RasterState rasterState;                                                //  4
+    StencilState stencilState;                                              // 12
+    PolygonOffset polygonOffset;                                            //  8
+    PrimitiveType primitiveType = PrimitiveType::TRIANGLES;                 //  1
+    uint8_t padding[3] = {};                                                //  3
 };

 } // namespace filament::backend
@@ -24,6 +24,7 @@

 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/ostream.h>

 #include <stddef.h>
 #include <stdint.h>
@@ -19,11 +19,12 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORM_H
 #define TNT_FILAMENT_BACKEND_PLATFORM_H

-#include <backend/DriverEnums.h>
-
 #include <utils/compiler.h>
 #include <utils/Invocable.h>

+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 class Driver;
@@ -41,18 +42,35 @@ public:
    struct Stream {};

    struct DriverConfig {
-        /*
-         * size of handle arena in bytes. Setting to 0 indicates default value is to be used.
+        /**
+         * Size of handle arena in bytes. Setting to 0 indicates default value is to be used.
         * Driver clamps to valid values.
         */
        size_t handleArenaSize = 0;

-        /*
-         * this number of most-recently destroyed textures will be tracked for use-after-free.
+        /**
+         * This number of most-recently destroyed textures will be tracked for use-after-free.
         * Throws an exception when a texture is freed but still bound to a SamplerGroup and used in
         * a draw call. 0 disables completely. Currently only respected by the Metal backend.
         */
        size_t textureUseAfterFreePoolSize = 0;
+
+        /**
+         * Set to `true` to forcibly disable parallel shader compilation in the backend.
+         * Currently only honored by the GL and Metal backends.
+         */
+        bool disableParallelShaderCompile = false;
+
+        /**
+         * Disable backend handles use-after-free checks.
+         */
+        bool disableHandleUseAfterFreeCheck = false;
+
+        /**
+         * Force GLES2 context if supported, or pretend the context is ES2. Only meaningful on
+         * GLES 3.x backends.
+         */
+        bool forceGLES2Context = false;
    };

    Platform() noexcept;
@@ -78,7 +96,7 @@ public:
     *
     * @return nullptr on failure, or a pointer to the newly created driver.
     */
-    virtual backend::Driver* createDriver(void* sharedContext,
+    virtual backend::Driver* UTILS_NULLABLE createDriver(void* UTILS_NULLABLE sharedContext,
            const DriverConfig& driverConfig) noexcept = 0;

    /**
@@ -96,7 +114,8 @@ public:
     * cache.
     */
    using InsertBlobFunc = utils::Invocable<
-            void(const void* key, size_t keySize, const void* value, size_t valueSize)>;
+            void(const void* UTILS_NONNULL key, size_t keySize,
+                    const void* UTILS_NONNULL value, size_t valueSize)>;

    /*
     * RetrieveBlobFunc is an Invocable to an application-provided function that a
@@ -104,7 +123,8 @@ public:
     * cache.
     */
    using RetrieveBlobFunc = utils::Invocable<
-            size_t(const void* key, size_t keySize, void* value, size_t valueSize)>;
+            size_t(const void* UTILS_NONNULL key, size_t keySize,
+                    void* UTILS_NONNULL value, size_t valueSize)>;

    /**
     * Sets the callback functions that the backend can use to interact with caching functionality
@@ -157,7 +177,8 @@ public:
     * @param value         pointer to the beginning of the value data that is to be inserted
     * @param valueSize     specifies the size in byte of the data pointed to by <value>
     */
-    void insertBlob(const void* key, size_t keySize, const void* value, size_t valueSize);
+    void insertBlob(const void* UTILS_NONNULL key, size_t keySize,
+            const void* UTILS_NONNULL value, size_t valueSize);

    /**
     * To retrieve the binary value associated with a given key from the cache, a
@@ -176,11 +197,43 @@ public:
     * @return             If the cache contains a value associated with the given key then the
     *                     size of that binary value in bytes is returned. Otherwise 0 is returned.
     */
-    size_t retrieveBlob(const void* key, size_t keySize, void* value, size_t valueSize);
+    size_t retrieveBlob(const void* UTILS_NONNULL key, size_t keySize,
+            void* UTILS_NONNULL value, size_t valueSize);
+
+    using DebugUpdateStatFunc = utils::Invocable<void(const char* UTILS_NONNULL key, uint64_t value)>;
+
+    /**
+     * Sets the callback function that the backend can use to update backend-specific statistics
+     * to aid with debugging. This callback is guaranteed to be called on the Filament driver
+     * thread.
+     *
+     * @param debugUpdateStat   an Invocable that updates debug statistics
+     */
+    void setDebugUpdateStatFunc(DebugUpdateStatFunc&& debugUpdateStat) noexcept;
+
+    /**
+     * @return true if debugUpdateStat is valid.
+     */
+    bool hasDebugUpdateStatFunc() const noexcept;
+
+    /**
+     * To track backend-specific statistics, the backend implementation can call the
+     * application-provided callback function debugUpdateStatFunc to associate or update a value
+     * with a given key. It is possible for this function to be called multiple times with the
+     * same key, in which case newer values should overwrite older values.
+     *
+     * This function is guaranteed to be called only on a single thread, the Filament driver
+     * thread.
+     *
+     * @param key          a null-terminated C-string with the key of the debug statistic
+     * @param value        the updated value of key
+     */
+    void debugUpdateStat(const char* UTILS_NONNULL key, uint64_t value);

 private:
    InsertBlobFunc mInsertBlob;
    RetrieveBlobFunc mRetrieveBlob;
+    DebugUpdateStatFunc mDebugUpdateStat;
 };

 } // namespace filament
@@ -21,8 +21,7 @@

 #include <utils/compiler.h>

-namespace filament {
-namespace backend {
+namespace filament::backend {

 /**
 * A PresentCallable is a callable object that, when called, schedules a frame for presentation on
@@ -49,7 +48,7 @@ namespace backend {
 * and optional user data:
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * swapChain->setFrameScheduledCallback(myFrameScheduledCallback, nullptr);
+ * swapChain->setFrameScheduledCallback(nullptr, myFrameScheduledCallback);
 * if (renderer->beginFrame(swapChain)) {
 *     renderer->render(view);
 *     renderer->endFrame();
@@ -59,8 +58,6 @@ namespace backend {
 * @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
 * backends ignore the callback (which will never be called) and proceed normally.
 *
- * @remark The SwapChain::FrameScheduledCallback is called on an arbitrary thread.
- *
 * Applications *must* call each PresentCallable they receive. Each PresentCallable represents a
 * frame that is waiting to be presented. If an application fails to call a PresentCallable, a
 * memory leak could occur. To "cancel" the presentation of a frame, pass false to the
@@ -98,7 +95,6 @@ private:
 */
 using FrameFinishedCallback UTILS_DEPRECATED = void(*)(PresentCallable callable, void* user);

-} // namespace backend
-} // namespace filament
+} // namespace filament::backend

 #endif // TNT_FILAMENT_BACKEND_PRESENTCALLABLE
@@ -17,17 +17,19 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_PROGRAM_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_PROGRAM_H

-#include <utils/compiler.h>
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
 #include <utils/Invocable.h>
-#include <utils/Log.h>
 #include <utils/ostream.h>

 #include <backend/DriverEnums.h>

-#include <array>
-#include <variant>
+#include <array>    // FIXME: STL headers are not allowed in public headers
+#include <utility>  // FIXME: STL headers are not allowed in public headers
+#include <variant>  // FIXME: STL headers are not allowed in public headers
+
+#include <stddef.h>
+#include <stdint.h>

 namespace filament::backend {

@@ -82,6 +84,9 @@ public:
    // null terminating character.
    Program& shader(ShaderStage shader, void const* data, size_t size);

+    // sets the language of the shader sources provided with shader() (defaults to ESSL3)
+    Program& shaderLanguage(ShaderLanguage shaderLanguage);
+
    // Note: This is only needed for GLES3.0 backends, because the layout(binding=) syntax is
    //       not permitted in glsl. The backend needs a way to associate a uniform block
    //       to a binding point.
@@ -112,8 +117,18 @@ public:
    Program& specializationConstants(
            utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;

+    struct PushConstant {
+        utils::CString name;
+        ConstantType type;
+    };
+
+    Program& pushConstants(ShaderStage stage,
+            utils::FixedCapacityVector<PushConstant> constants) noexcept;
+
    Program& cacheId(uint64_t cacheId) noexcept;

+    Program& multiview(bool multiview) noexcept;
+
    ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
    ShaderSource& getShadersSource() noexcept { return mShadersSource; }

@@ -132,6 +147,8 @@ public:
    utils::CString const& getName() const noexcept { return mName; }
    utils::CString& getName() noexcept { return mName; }

+    auto const& getShaderLanguage() const { return mShaderLanguage; }
+
    utils::FixedCapacityVector<SpecializationConstant> const& getSpecializationConstants() const noexcept {
        return mSpecializationConstants;
    }
@@ -139,8 +156,19 @@ public:
        return mSpecializationConstants;
    }

+    utils::FixedCapacityVector<PushConstant> const& getPushConstants(
+            ShaderStage stage) const noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
+    utils::FixedCapacityVector<PushConstant>& getPushConstants(ShaderStage stage) noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
    uint64_t getCacheId() const noexcept { return mCacheId; }

+    bool isMultiview() const noexcept { return mMultiview; }
+
    CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }

 private:
@@ -149,13 +177,20 @@ private:
    UniformBlockInfo mUniformBlocks = {};
    SamplerGroupInfo mSamplerGroups = {};
    ShaderSource mShadersSource;
+    ShaderLanguage mShaderLanguage = ShaderLanguage::ESSL3;
    utils::CString mName;
    uint64_t mCacheId{};
    utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
    utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
+    std::array<utils::FixedCapacityVector<PushConstant>, SHADER_TYPE_COUNT> mPushConstants;
    utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;
    std::array<UniformInfo, Program::UNIFORM_BINDING_COUNT> mBindingUniformInfo;
    CompilerPriorityQueue mPriorityQueue = CompilerPriorityQueue::HIGH;
+    // Indicates the current engine was initialized with multiview stereo, and the variant for this
+    // program contains STE flag. This will be referred later for the OpenGL shader compiler to
+    // determine whether shader code replacement for the num_views should be performed.
+    // This variable could be promoted as a more generic variable later if other similar needs occur.
+    bool mMultiview = false;
 };

 } // namespace filament::backend
@@ -24,9 +24,6 @@

 #include <utils/compiler.h>

-#include <stddef.h>
-#include <stdint.h>
-
 namespace filament::backend {

 struct UTILS_PUBLIC SamplerDescriptor {
@@ -17,9 +17,11 @@
 #ifndef TNT_FILAMENT_BACKEND_TARGETBUFFERINFO_H
 #define TNT_FILAMENT_BACKEND_TARGETBUFFERINFO_H

-#include <backend/DriverEnums.h>
 #include <backend/Handle.h>

+#include <utils/ostream.h>
+
+#include <stddef.h>
 #include <stdint.h>

 namespace filament::backend {
@@ -27,13 +29,36 @@ namespace filament::backend {
 //! \privatesection

 struct TargetBufferInfo {
+    // note: the parameters of this constructor are not in the order of this structure's fields
+    TargetBufferInfo(Handle<HwTexture> handle, uint8_t level, uint16_t layer, uint8_t baseViewIndex) noexcept
+        : handle(handle), baseViewIndex(baseViewIndex), level(level), layer(layer) {
+    }
+
+    TargetBufferInfo(Handle<HwTexture> handle, uint8_t level, uint16_t layer) noexcept
+            : handle(handle), level(level), layer(layer) {
+    }
+
+    TargetBufferInfo(Handle<HwTexture> handle, uint8_t level) noexcept
+            : handle(handle), level(level) {
+    }
+
+    TargetBufferInfo(Handle<HwTexture> handle) noexcept // NOLINT(*-explicit-constructor)
+            : handle(handle) {
+    }
+
+    TargetBufferInfo() noexcept = default;
+
    // texture to be used as render target
    Handle<HwTexture> handle;

+    // Starting layer index for multiview. This value is only used when the `layerCount` for the
+    // render target is greater than 1.
+    uint8_t baseViewIndex = 0;
+
    // level to be used
    uint8_t level = 0;

-    // for cubemaps and 3D textures. See TextureCubemapFace for the face->layer mapping
+    // For cubemaps and 3D textures. See TextureCubemapFace for the face->layer mapping
    uint16_t layer = 0;
 };

@@ -58,7 +83,7 @@ public:

    MRT() noexcept = default;

-    MRT(TargetBufferInfo const& color) noexcept // NOLINT(hicpp-explicit-conversions)
+    MRT(TargetBufferInfo const& color) noexcept // NOLINT(hicpp-explicit-conversions, *-explicit-constructor)
            : mInfos{ color } {
    }

@@ -78,7 +103,7 @@ public:

    // this is here for backward compatibility
    MRT(Handle<HwTexture> handle, uint8_t level, uint16_t layer) noexcept
-            : mInfos{{ handle, level, layer }} {
+            : mInfos{{ handle, level, layer, 0 }} {
    }
 };

@@ -18,8 +18,15 @@
 #define TNT_FILAMENT_BACKEND_PRIVATE_OPENGLPLATFORM_H

 #include <backend/AcquiredImage.h>
+#include <backend/DriverEnums.h>
 #include <backend/Platform.h>

+#include <utils/compiler.h>
+#include <utils/Invocable.h>
+
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 class Driver;
@@ -38,8 +45,8 @@ protected:
     * Derived classes can use this to instantiate the default OpenGLDriver backend.
     * This is typically called from your implementation of createDriver()
     */
-    static Driver* createDefaultDriver(OpenGLPlatform* platform,
-            void* sharedContext, const DriverConfig& driverConfig);
+    static Driver* UTILS_NULLABLE createDefaultDriver(OpenGLPlatform* UTILS_NONNULL platform,
+            void* UTILS_NULLABLE sharedContext, const DriverConfig& driverConfig);

    ~OpenGLPlatform() noexcept override;

@@ -57,6 +64,22 @@ public:
     */
    virtual void terminate() noexcept = 0;

+    /**
+     * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
+     * The default implementation returns false.
+     *
+     * @return true if SWAP_CHAIN_CONFIG_SRGB_COLORSPACE is supported, false otherwise.
+     */
+    virtual bool isSRGBSwapChainSupported() const noexcept;
+
+    /**
+     * Return whether protected contexts are supported by this backend.
+     * If protected context are supported, the SWAP_CHAIN_CONFIG_PROTECTED_CONTENT flag can be
+     * used when creating a SwapChain.
+     * The default implementation returns false.
+     */
+    virtual bool isProtectedContextSupported() const noexcept;
+
    /**
     * Called by the driver to create a SwapChain for this driver.
     *
@@ -66,15 +89,8 @@ public:
     * @return              The driver's SwapChain object.
     *
     */
-    virtual SwapChain* createSwapChain(void* nativeWindow, uint64_t flags) noexcept = 0;
-
-    /**
-     * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
-     * The default implementation returns false.
-     *
-     * @return true if SWAP_CHAIN_CONFIG_SRGB_COLORSPACE is supported, false otherwise.
-     */
-    virtual bool isSRGBSwapChainSupported() const noexcept;
+    virtual SwapChain* UTILS_NULLABLE createSwapChain(
+            void* UTILS_NULLABLE nativeWindow, uint64_t flags) noexcept = 0;

    /**
     * Called by the driver create a headless SwapChain.
@@ -87,13 +103,14 @@ public:
     * TODO: we need a more generic way of passing construction parameters
     *       A void* might be enough.
     */
-    virtual SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept = 0;
+    virtual SwapChain* UTILS_NULLABLE createSwapChain(
+            uint32_t width, uint32_t height, uint64_t flags) noexcept = 0;

    /**
     * Called by the driver to destroys the SwapChain
     * @param swapChain SwapChain to be destroyed.
     */
-    virtual void destroySwapChain(SwapChain* swapChain) noexcept = 0;
+    virtual void destroySwapChain(SwapChain* UTILS_NONNULL swapChain) noexcept = 0;

    /**
     * Returns the set of buffers that must be preserved up to the call to commit().
@@ -106,28 +123,103 @@ public:
     * @return buffer that must be preserved
     * @see commit()
     */
-    virtual TargetBufferFlags getPreservedFlags(SwapChain* swapChain) noexcept;
+    virtual TargetBufferFlags getPreservedFlags(SwapChain* UTILS_NONNULL swapChain) noexcept;
+
+    /**
+     * Returns true if the swapchain is protected
+     */
+    virtual bool isSwapChainProtected(Platform::SwapChain* UTILS_NONNULL swapChain) noexcept;

    /**
     * Called by the driver to establish the default FBO. The default implementation returns 0.
-      * @return a GLuint casted to a uint32_t that is an OpenGL framebuffer object.
+     *
+     * This method can be called either on the regular or protected OpenGL contexts and can return
+     * a different or identical name, since these names exist in different namespaces.
+     *
+     * @return a GLuint casted to a uint32_t that is an OpenGL framebuffer object.
     */
-    virtual uint32_t createDefaultRenderTarget() noexcept;
+    virtual uint32_t getDefaultFramebufferObject() noexcept;
+
+    /**
+     * Called by the backend when a frame starts.
+     * @param steady_clock_ns vsync time point on the monotonic clock
+     * @param refreshIntervalNs refresh interval in nanosecond
+     * @param frameId a frame id
+     */
+    virtual void beginFrame(
+            int64_t monotonic_clock_ns,
+            int64_t refreshIntervalNs,
+            uint32_t frameId) noexcept;
+
+    /**
+     * Called by the backend when a frame ends.
+     * @param frameId the frame id used in beginFrame
+     */
+    virtual void endFrame(
+            uint32_t frameId) noexcept;
+
+    /**
+     * Type of contexts available
+     */
+    enum class ContextType {
+        NONE,           //!< No current context
+        UNPROTECTED,    //!< current context is unprotected
+        PROTECTED       //!< current context supports protected content
+    };
+
+    /**
+     * Returns the type of the context currently in use. This value is updated by makeCurrent()
+     * and therefore can be cached between calls. ContextType::PROTECTED can only be returned
+     * if isProtectedContextSupported() is true.
+     * @return ContextType
+     */
+    virtual ContextType getCurrentContextType() const noexcept;
+
+    /**
+     * Binds the requested context to the current thread and drawSwapChain to the default FBO
+     * returned by getDefaultFramebufferObject().
+     *
+     * @param type type of context to bind to the current thread.
+     * @param drawSwapChain SwapChain to draw to. It must be bound to the default FBO.
+     * @param readSwapChain SwapChain to read from (for operation like `glBlitFramebuffer`)
+     * @return true on success, false on error.
+     */
+    virtual bool makeCurrent(ContextType type,
+            SwapChain* UTILS_NONNULL drawSwapChain,
+            SwapChain* UTILS_NONNULL readSwapChain) noexcept = 0;

    /**
     * Called by the driver to make the OpenGL context active on the calling thread and bind
-     * the drawSwapChain to the default render target (FBO) created with createDefaultRenderTarget.
+     * the drawSwapChain to the default FBO returned by getDefaultFramebufferObject().
+     * The context used is either the default context or the protected context. When a context
+     * change is necessary, the preContextChange and postContextChange callbacks are called,
+     * before and after the context change respectively. postContextChange is given the index
+     * of the new context (0 for default and 1 for protected).
+     * The default implementation just calls makeCurrent(getCurrentContextType(), SwapChain*, SwapChain*).
+     *
     * @param drawSwapChain SwapChain to draw to. It must be bound to the default FBO.
     * @param readSwapChain SwapChain to read from (for operation like `glBlitFramebuffer`)
+     * @param preContextChange called before the context changes
+     * @param postContextChange called after the context changes
     */
-    virtual void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept = 0;
+    virtual void makeCurrent(
+            SwapChain* UTILS_NONNULL drawSwapChain,
+            SwapChain* UTILS_NONNULL readSwapChain,
+            utils::Invocable<void()> preContextChange,
+            utils::Invocable<void(size_t index)> postContextChange) noexcept;
+
+    /**
+     * Called by the backend just before calling commit()
+     * @see commit()
+     */
+    virtual void preCommit() noexcept;

    /**
     * Called by the driver once the current frame finishes drawing. Typically, this should present
     * the drawSwapChain. This is for example where `eglMakeCurrent()` would be called.
     * @param swapChain the SwapChain to present.
     */
-    virtual void commit(SwapChain* swapChain) noexcept = 0;
+    virtual void commit(SwapChain* UTILS_NONNULL swapChain) noexcept = 0;

    /**
     * Set the time the next committed buffer should be presented to the user at.
@@ -152,14 +244,14 @@ public:
     *
     * @return A Fence object. The default implementation returns nullptr.
     */
-    virtual Fence* createFence() noexcept;
+    virtual Fence* UTILS_NULLABLE createFence() noexcept;

    /**
     * Destroys a Fence object. The default implementation does nothing.
     *
     * @param fence Fence to destroy.
     */
-    virtual void destroyFence(Fence* fence) noexcept;
+    virtual void destroyFence(Fence* UTILS_NONNULL fence) noexcept;

    /**
     * Waits on a Fence.
@@ -169,7 +261,7 @@ public:
     * @return Whether the fence signaled or timed out. See backend::FenceStatus.
     *         The default implementation always return backend::FenceStatus::ERROR.
     */
-    virtual backend::FenceStatus waitFence(Fence* fence, uint64_t timeout) noexcept;
+    virtual backend::FenceStatus waitFence(Fence* UTILS_NONNULL fence, uint64_t timeout) noexcept;


    // --------------------------------------------------------------------------------------------
@@ -183,13 +275,13 @@ public:
     * @param nativeStream The native stream, this parameter depends on the concrete implementation.
     * @return A new Stream object.
     */
-    virtual Stream* createStream(void* nativeStream) noexcept;
+    virtual Stream* UTILS_NULLABLE createStream(void* UTILS_NULLABLE nativeStream) noexcept;

    /**
     * Destroys a Stream.
     * @param stream Stream to destroy.
     */
-    virtual void destroyStream(Stream* stream) noexcept;
+    virtual void destroyStream(Stream* UTILS_NONNULL stream) noexcept;

    /**
     * The specified stream takes ownership of the texture (tname) object
@@ -199,20 +291,21 @@ public:
     * @param stream Stream to take ownership of the texture
     * @param tname  GL texture id to "bind" to the Stream.
     */
-    virtual void attach(Stream* stream, intptr_t tname) noexcept;
+    virtual void attach(Stream* UTILS_NONNULL stream, intptr_t tname) noexcept;

    /**
     * Destroys the texture associated to the stream
     * @param stream Stream to detach from its texture
     */
-    virtual void detach(Stream* stream) noexcept;
+    virtual void detach(Stream* UTILS_NONNULL stream) noexcept;

    /**
     * Updates the content of the texture attached to the stream.
     * @param stream Stream to update
     * @param timestamp Output parameter: Timestamp of the image bound to the texture.
     */
-    virtual void updateTexImage(Stream* stream, int64_t* timestamp) noexcept;
+    virtual void updateTexImage(Stream* UTILS_NONNULL stream,
+            int64_t* UTILS_NONNULL timestamp) noexcept;


    // --------------------------------------------------------------------------------------------
@@ -225,13 +318,13 @@ public:
     *         implementation could just return { 0, GL_TEXTURE_2D } at this point. The actual
     *         values can be delayed until setExternalImage.
     */
-    virtual ExternalTexture *createExternalImageTexture() noexcept;
+    virtual ExternalTexture* UTILS_NULLABLE createExternalImageTexture() noexcept;

    /**
     * Destroys an external texture handle and associated data.
     * @param texture a pointer to the handle to destroy.
     */
-    virtual void destroyExternalImage(ExternalTexture* texture) noexcept;
+    virtual void destroyExternalImage(ExternalTexture* UTILS_NONNULL texture) noexcept;

    // called on the application thread to allow Filament to take ownership of the image

@@ -244,7 +337,7 @@ public:
     * @param externalImage A token representing the platform's external image.
     * @see destroyExternalImage
     */
-    virtual void retainExternalImage(void* externalImage) noexcept;
+    virtual void retainExternalImage(void* UTILS_NONNULL externalImage) noexcept;

    /**
     * Called to bind the platform-specific externalImage to an ExternalTexture.
@@ -258,7 +351,8 @@ public:
     * @param texture an in/out pointer to ExternalTexture, id and target can be updated if necessary.
     * @return true on success, false on error.
     */
-    virtual bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept;
+    virtual bool setExternalImage(void* UTILS_NONNULL externalImage,
+            ExternalTexture* UTILS_NONNULL texture) noexcept;

    /**
     * The method allows platforms to convert a user-supplied external image object into a new type
@@ -17,11 +17,10 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_COCOA_GL_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_COCOA_GL_H

-#include <stdint.h>
-
+#include <backend/DriverEnums.h>
 #include <backend/platforms/OpenGLPlatform.h>

-#include <backend/DriverEnums.h>
+#include <stdint.h>

 namespace filament::backend {

@@ -58,7 +57,7 @@ protected:
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
    void commit(SwapChain* swapChain) noexcept override;
    OpenGLPlatform::ExternalTexture* createExternalImageTexture() noexcept override;
    void destroyExternalImage(ExternalTexture* texture) noexcept override;
@@ -30,7 +30,7 @@ struct PlatformCocoaTouchGLImpl;
 class PlatformCocoaTouchGL : public OpenGLPlatform {
 public:
    PlatformCocoaTouchGL();
-    ~PlatformCocoaTouchGL() noexcept;
+    ~PlatformCocoaTouchGL() noexcept override;

    // --------------------------------------------------------------------------------------------
    // Platform Interface
@@ -45,7 +45,7 @@ public:

    void terminate() noexcept override;

-    uint32_t createDefaultRenderTarget() noexcept override;
+    uint32_t getDefaultFramebufferObject() noexcept override;

    bool isExtraContextSupported() const noexcept override;
    void createContext(bool shared) override;
@@ -53,7 +53,7 @@ public:
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
    void commit(SwapChain* swapChain) noexcept override;

    OpenGLPlatform::ExternalTexture* createExternalImageTexture() noexcept override;
@@ -17,18 +17,23 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_H

-#include <stdint.h>
+#include <backend/DriverEnums.h>
+#include <backend/Platform.h>
+#include <backend/platforms/OpenGLPlatform.h>

 #include <EGL/egl.h>
 #include <EGL/eglext.h>
+#include <EGL/eglplatform.h>

-#include <backend/platforms/OpenGLPlatform.h>
-
-#include <backend/DriverEnums.h>
+#include <utils/Invocable.h>

+#include <initializer_list>
 #include <utility>
 #include <vector>

+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 /**
@@ -38,15 +43,11 @@ class PlatformEGL : public OpenGLPlatform {
 public:

    PlatformEGL() noexcept;
-    bool isExtraContextSupported() const noexcept override;
-    void createContext(bool shared) override;
-    void releaseContext() noexcept override;

    // Return true if we're on an OpenGL platform (as opposed to OpenGL ES). false by default.
    virtual bool isOpenGL() const noexcept;

 protected:
-
    // --------------------------------------------------------------------------------------------
    // Helper for EGL configs and attributes parameters

@@ -86,13 +87,30 @@ protected:
    // --------------------------------------------------------------------------------------------
    // OpenGLPlatform Interface

+    bool isExtraContextSupported() const noexcept override;
+    void createContext(bool shared) override;
+    void releaseContext() noexcept override;
+
    void terminate() noexcept override;

+    bool isProtectedContextSupported() const noexcept override;
+
    bool isSRGBSwapChainSupported() const noexcept override;
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool isSwapChainProtected(SwapChain* swapChain) noexcept override;
+
+    ContextType getCurrentContextType() const noexcept override;
+
+    bool makeCurrent(ContextType type,
+            SwapChain* drawSwapChain,
+            SwapChain* readSwapChain) noexcept override;
+
+    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain,
+            utils::Invocable<void()> preContextChange,
+            utils::Invocable<void(size_t index)> postContextChange) noexcept override;
+
    void commit(SwapChain* swapChain) noexcept override;

    bool canCreateFence() noexcept override;
@@ -119,16 +137,27 @@ protected:
    static void clearGlError() noexcept;

    /**
-     * Always use this instead of eglMakeCurrent().
+     * Always use this instead of eglMakeCurrent(), as it tracks some state.
     */
-    EGLBoolean makeCurrent(EGLSurface drawSurface, EGLSurface readSurface) noexcept;
+
+    EGLContext getContextForType(ContextType type) const noexcept;
+
+    // makes the draw and read surface current without changing the current context
+    EGLBoolean makeCurrent(EGLSurface drawSurface, EGLSurface readSurface) noexcept {
+        return egl.makeCurrent(drawSurface, readSurface);
+    }
+
+    // makes context current and set draw and read surfaces to EGL_NO_SURFACE
+    EGLBoolean makeCurrent(EGLContext context) noexcept {
+        return egl.makeCurrent(context, mEGLDummySurface, mEGLDummySurface);
+    }

    // TODO: this should probably use getters instead.
    EGLDisplay mEGLDisplay = EGL_NO_DISPLAY;
    EGLContext mEGLContext = EGL_NO_CONTEXT;
-    EGLSurface mCurrentDrawSurface = EGL_NO_SURFACE;
-    EGLSurface mCurrentReadSurface = EGL_NO_SURFACE;
+    EGLContext mEGLContextProtected = EGL_NO_CONTEXT;
    EGLSurface mEGLDummySurface = EGL_NO_SURFACE;
+    ContextType mCurrentContextType = ContextType::NONE;
    // mEGLConfig is valid only if ext.egl.KHR_no_config_context is false
    EGLConfig mEGLConfig = EGL_NO_CONFIG_KHR;
    Config mContextAttribs;
@@ -145,13 +174,38 @@ protected:
            bool KHR_gl_colorspace = false;
            bool KHR_no_config_context = false;
            bool KHR_surfaceless_context = false;
+            bool EXT_protected_content = false;
        } egl;
    } ext;

+    struct SwapChainEGL : public Platform::SwapChain {
+        EGLSurface sur = EGL_NO_SURFACE;
+        Config attribs{};
+        EGLNativeWindowType nativeWindow{};
+        EGLConfig config{};
+        uint64_t flags{};
+    };
+
    void initializeGlExtensions() noexcept;

 protected:
    EGLConfig findSwapChainConfig(uint64_t flags, bool window, bool pbuffer) const;
+
+private:
+    class EGL {
+        EGLDisplay& mEGLDisplay;
+        EGLSurface mCurrentDrawSurface = EGL_NO_SURFACE;
+        EGLSurface mCurrentReadSurface = EGL_NO_SURFACE;
+        EGLContext mCurrentContext = EGL_NO_CONTEXT;
+    public:
+        explicit EGL(EGLDisplay& dpy) : mEGLDisplay(dpy) {}
+        EGLBoolean makeCurrent(EGLContext context,
+                EGLSurface drawSurface, EGLSurface readSurface) noexcept;
+
+        EGLBoolean makeCurrent(EGLSurface drawSurface, EGLSurface readSurface) noexcept {
+            return makeCurrent(mCurrentContext, drawSurface, readSurface);
+        }
+    } egl{ mEGLDisplay };
 };

 } // namespace filament::backend
@@ -17,8 +17,18 @@
 #ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H
 #define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_EGL_ANDROID_H

+#include <backend/AcquiredImage.h>
+#include <backend/Platform.h>
+#include <backend/platforms/OpenGLPlatform.h>
 #include <backend/platforms/PlatformEGL.h>

+#include <utils/android/PerformanceHintManager.h>
+
+#include <chrono>
+
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 class ExternalStreamManagerAndroid;
@@ -52,6 +62,13 @@ protected:

    void terminate() noexcept override;

+    void beginFrame(
+            int64_t monotonic_clock_ns,
+            int64_t refreshIntervalNs,
+            uint32_t frameId) noexcept override;
+
+    void preCommit() noexcept override;
+
    /**
     * Set the presentation time using `eglPresentationTimeANDROID`
     * @param presentationTimeInNanosecond
@@ -75,6 +92,11 @@ protected:
 private:
    int mOSVersion;
    ExternalStreamManagerAndroid& mExternalStreamManager;
+    utils::PerformanceHintManager mPerformanceHintManager;
+    utils::PerformanceHintManager::Session mPerformanceHintSession;
+
+    using clock = std::chrono::high_resolution_clock;
+    clock::time_point mStartTimeOfActualWork;
 };

 } // namespace filament::backend
@@ -51,7 +51,7 @@ protected:
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
    void commit(SwapChain* swapChain) noexcept override;

 private:
@@ -53,7 +53,7 @@ protected:
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
    void commit(SwapChain* swapChain) noexcept override;

 protected:
@@ -46,7 +46,7 @@ protected:
    SwapChain* createSwapChain(void* nativewindow, uint64_t flags) noexcept override;
    SwapChain* createSwapChain(uint32_t width, uint32_t height, uint64_t flags) noexcept override;
    void destroySwapChain(SwapChain* swapChain) noexcept override;
-    void makeCurrent(SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain, SwapChain* readSwapChain) noexcept override;
    void commit(SwapChain* swapChain) noexcept override;
 };

@@ -20,13 +20,18 @@
 #include <backend/Platform.h>

 #include <bluevk/BlueVK.h>
+
 #include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
 #include <utils/PrivateImplementation.h>

+#include <string_view>
 #include <tuple>
 #include <unordered_set>

+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 using SwapChain = Platform::SwapChain;
@@ -17,7 +17,7 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H

-#include <utils/compiler.h>
+#include <utils/debug.h>

 #include <stddef.h>
 #include <stdint.h>
@@ -40,28 +40,36 @@ public:

    ~CircularBuffer() noexcept;

-    // allocates 'size' bytes in the circular buffer and returns a pointer to the memory
-    // return the current head and moves it forward by size bytes
-    inline void* allocate(size_t size) noexcept {
+    static size_t getBlockSize() noexcept { return sPageSize; }
+
+    // Total size of circular buffer. This is a constant.
+    size_t size() const noexcept { return mSize; }
+
+    // Allocates `s` bytes in the circular buffer and returns a pointer to the memory. All
+    // allocations must not exceed size() bytes.
+    inline void* allocate(size_t s) noexcept {
+        // We can never allocate more that size().
+        assert_invariant(getUsed() + s <= size());
        char* const cur = static_cast<char*>(mHead);
-        mHead = cur + size;
+        mHead = cur + s;
        return cur;
    }

-    // Total size of circular buffer
-    size_t size() const noexcept { return mSize; }
-
-    // returns true if the buffer is empty (e.g. after calling flush)
+    // Returns true if the buffer is empty, i.e.: no allocations were made since
+    // calling getBuffer();
    bool empty() const noexcept { return mTail == mHead; }

-    void* getHead() const noexcept { return mHead; }
+    // Returns the size used since the last call to getBuffer()
+    size_t getUsed() const noexcept { return intptr_t(mHead) - intptr_t(mTail); }

-    void* getTail() const noexcept { return mTail; }
-
-    // call at least once every getRequiredSize() bytes allocated from the buffer
-    void circularize() noexcept;
-
-    static size_t getBlockSize() noexcept { return sPageSize; }
+    // Retrieves the current allocated range and frees it. It is the responsibility of the caller
+    // to make sure the returned range is no longer in use by the time allocate() allocates
+    // (size() - getUsed()) bytes.
+    struct Range {
+        void* tail;
+        void* head;
+    };
+    Range getBuffer() noexcept;

 private:
    void* alloc(size_t size) noexcept;
@@ -69,10 +77,10 @@ private:

    // pointer to the beginning of the circular buffer (constant)
    void* mData = nullptr;
-    int mUsesAshmem = -1;
+    int mAshmemFd = -1;

    // size of the circular buffer (constant)
-    size_t mSize = 0;
+    size_t const mSize;

    // pointer to the beginning of recorded data
    void* mTail = nullptr;
@@ -19,19 +19,21 @@

 #include "private/backend/CircularBuffer.h"

-#include <utils/compiler.h>
 #include <utils/Condition.h>
 #include <utils/Mutex.h>

 #include <vector>

+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {

 /*
 * A producer-consumer command queue that uses a CircularBuffer as main storage
 */
 class CommandBufferQueue {
-    struct Slice {
+    struct Range {
        void* begin;
        void* end;
    };
@@ -44,29 +46,33 @@ class CommandBufferQueue {

    mutable utils::Mutex mLock;
    mutable utils::Condition mCondition;
-    mutable std::vector<Slice> mCommandBuffersToExecute;
+    mutable std::vector<Range> mCommandBuffersToExecute;
    size_t mFreeSpace = 0;
    size_t mHighWatermark = 0;
    uint32_t mExitRequested = 0;
+    bool mPaused = false;

    static constexpr uint32_t EXIT_REQUESTED = 0x31415926;

 public:
    // requiredSize: guaranteed available space after flush()
-    CommandBufferQueue(size_t requiredSize, size_t bufferSize);
+    CommandBufferQueue(size_t requiredSize, size_t bufferSize, bool paused);
    ~CommandBufferQueue();

-    CircularBuffer& getCircularBuffer() { return mCircularBuffer; }
+    CircularBuffer& getCircularBuffer() noexcept { return mCircularBuffer; }
+    CircularBuffer const& getCircularBuffer() const noexcept { return mCircularBuffer; }
+
+    size_t getCapacity() const noexcept { return mRequiredSize; }

    size_t getHighWatermark() const noexcept { return mHighWatermark; }

    // wait for commands to be available and returns an array containing these commands
-    std::vector<Slice> waitForCommands() const;
+    std::vector<Range> waitForCommands() const;

    // return the memory used by this command buffer to the circular buffer
    // WARNING: releaseBuffer() must be called in sequence of the Slices returned by
    // waitForCommands()
-    void releaseBuffer(Slice const& buffer);
+    void releaseBuffer(Range const& buffer);

    // all commands buffers (Slices) written to this point are returned by waitForCommand(). This
    // call blocks until the CircularBuffer has at least mRequiredSize bytes available.
@@ -75,6 +81,10 @@ public:
    // returns from waitForCommands() immediately.
    void requestExit();

+    // suspend or unsuspend the queue.
+    bool isPaused() const noexcept;
+    void setPaused(bool paused);
+
    bool isExitRequested() const;
 };

@@ -32,11 +32,13 @@
 #include <backend/TargetBufferInfo.h>

 #include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/ThreadUtils.h>

 #include <cstddef>
 #include <functional>
 #include <tuple>
+#include <type_traits>
 #include <utility>

 #ifndef NDEBUG
@@ -132,7 +134,7 @@ struct CommandType<void (Driver::*)(ARGS...)> {

    public:
        template<typename M, typename D>
-        static inline void execute(M&& method, D&& driver, CommandBase* base, intptr_t* next) noexcept {
+        static inline void execute(M&& method, D&& driver, CommandBase* base, intptr_t* next) {
            Command* self = static_cast<Command*>(base);
            *next = align(sizeof(Command));
 #if DEBUG_COMMAND_STREAM
@@ -152,21 +154,21 @@ struct CommandType<void (Driver::*)(ARGS...)> {
        }

        // placement new declared as "throw" to avoid the compiler's null-check
-        inline void* operator new(std::size_t size, void* ptr) {
+        inline void* operator new(std::size_t, void* ptr) {
            assert_invariant(ptr);
            return ptr;
        }
    };
 };

-// convert an method of "class Driver" into a Command<> type
+// convert a method of "class Driver" into a Command<> type
 #define COMMAND_TYPE(method) CommandType<decltype(&Driver::method)>::Command<&Driver::method>

 // ------------------------------------------------------------------------------------------------

 class CustomCommand : public CommandBase {
    std::function<void()> mCommand;
-    static void execute(Driver&, CommandBase* base, intptr_t* next) noexcept;
+    static void execute(Driver&, CommandBase* base, intptr_t* next);
 public:
    inline CustomCommand(CustomCommand&& rhs) = default;
    inline explicit CustomCommand(std::function<void()> cmd)
@@ -211,6 +213,8 @@ public:
    CommandStream(CommandStream const& rhs) noexcept = delete;
    CommandStream& operator=(CommandStream const& rhs) noexcept = delete;

+    CircularBuffer const& getCircularBuffer() const noexcept { return mCurrentBuffer; }
+
 public:
 #define DECL_DRIVER_API(methodName, paramsDecl, params)                                         \
    inline void methodName(paramsDecl) {                                                        \
@@ -29,6 +29,7 @@

 #include <functional>

+#include <stddef.h>
 #include <stdint.h>

 // Command debugging off. debugging virtuals are not called.
@@ -75,7 +76,7 @@ public:
    // the fn function will execute a batch of driver commands
    // this gives the driver a chance to wrap their execution in a meaningful manner
    // the default implementation simply calls fn
-    virtual void execute(std::function<void(void)> const& fn) noexcept;
+    virtual void execute(std::function<void(void)> const& fn);

    // This is called on debug build, or when enabled manually on the backend thread side.
    virtual void debugCommandBegin(CommandStream* cmds,
@@ -133,12 +133,13 @@ DECL_DRIVER_API_0(tick)

 DECL_DRIVER_API_N(beginFrame,
        int64_t, monotonic_clock_ns,
+        int64_t, refreshIntervalNs,
        uint32_t, frameId)

 DECL_DRIVER_API_N(setFrameScheduledCallback,
        backend::SwapChainHandle, sch,
-        backend::FrameScheduledCallback, callback,
-        void*, user)
+        backend::CallbackHandler*, handler,
+        backend::FrameScheduledCallback&&, callback)

 DECL_DRIVER_API_N(setFrameCompletedCallback,
        backend::SwapChainHandle, sch,
@@ -167,12 +168,15 @@ DECL_DRIVER_API_0(resetState)
 * -----------------------
 */

-DECL_DRIVER_API_R_N(backend::VertexBufferHandle, createVertexBuffer,
+DECL_DRIVER_API_R_N(backend::VertexBufferInfoHandle, createVertexBufferInfo,
        uint8_t, bufferCount,
        uint8_t, attributeCount,
-        uint32_t, vertexCount,
        backend::AttributeArray, attributes)

+DECL_DRIVER_API_R_N(backend::VertexBufferHandle, createVertexBuffer,
+        uint32_t, vertexCount,
+        backend::VertexBufferInfoHandle, vbih)
+
 DECL_DRIVER_API_R_N(backend::IndexBufferHandle, createIndexBuffer,
        backend::ElementType, elementType,
        uint32_t, indexCount,
@@ -224,11 +228,7 @@ DECL_DRIVER_API_R_N(backend::SamplerGroupHandle, createSamplerGroup,
 DECL_DRIVER_API_R_N(backend::RenderPrimitiveHandle, createRenderPrimitive,
        backend::VertexBufferHandle, vbh,
        backend::IndexBufferHandle, ibh,
-        backend::PrimitiveType, pt,
-        uint32_t, offset,
-        uint32_t, minIndex,
-        uint32_t, maxIndex,
-        uint32_t, count)
+        backend::PrimitiveType, pt)

 DECL_DRIVER_API_R_N(backend::ProgramHandle, createProgram,
        backend::Program&&, program)
@@ -240,6 +240,7 @@ DECL_DRIVER_API_R_N(backend::RenderTargetHandle, createRenderTarget,
        uint32_t, width,
        uint32_t, height,
        uint8_t, samples,
+        uint8_t, layerCount,
        backend::MRT, color,
        backend::TargetBufferInfo, depth,
        backend::TargetBufferInfo, stencil)
@@ -264,6 +265,7 @@ DECL_DRIVER_API_R_0(backend::TimerQueryHandle, createTimerQuery)
 */

 DECL_DRIVER_API_N(destroyVertexBuffer,    backend::VertexBufferHandle, vbh)
+DECL_DRIVER_API_N(destroyVertexBufferInfo,backend::VertexBufferInfoHandle, vbih)
 DECL_DRIVER_API_N(destroyIndexBuffer,     backend::IndexBufferHandle, ibh)
 DECL_DRIVER_API_N(destroyBufferObject,    backend::BufferObjectHandle, ibh)
 DECL_DRIVER_API_N(destroyRenderPrimitive, backend::RenderPrimitiveHandle, rph)
@@ -298,14 +300,17 @@ DECL_DRIVER_API_SYNCHRONOUS_0(bool, isFrameBufferFetchMultiSampleSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isFrameTimeSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isAutoDepthResolveSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isSRGBSwapChainSupported)
-DECL_DRIVER_API_SYNCHRONOUS_0(bool, isStereoSupported)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isProtectedContentSupported)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, isStereoSupported, backend::StereoscopicType, stereoscopicType)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isParallelShaderCompileSupported)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isDepthStencilResolveSupported)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, isDepthStencilBlitSupported, backend::TextureFormat, format)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isProtectedTexturesSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(uint8_t, getMaxDrawBuffers)
 DECL_DRIVER_API_SYNCHRONOUS_0(size_t, getMaxUniformBufferSize)
 DECL_DRIVER_API_SYNCHRONOUS_0(math::float2, getClipSpaceParams)
-DECL_DRIVER_API_SYNCHRONOUS_0(bool, canGenerateMipmaps)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setupExternalImage, void*, image)
-DECL_DRIVER_API_SYNCHRONOUS_N(bool, getTimerQueryValue, backend::TimerQueryHandle, query, uint64_t*, elapsedTime)
+DECL_DRIVER_API_SYNCHRONOUS_N(backend::TimerQueryResult, getTimerQueryValue, backend::TimerQueryHandle, query, uint64_t*, elapsedTime)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isWorkaroundNeeded, backend::Workaround, workaround)
 DECL_DRIVER_API_SYNCHRONOUS_0(backend::FeatureLevel, getFeatureLevel)

@@ -429,6 +434,11 @@ DECL_DRIVER_API_N(bindSamplers,
        uint32_t, index,
        backend::SamplerGroupHandle, sbh)

+DECL_DRIVER_API_N(setPushConstant,
+        backend::ShaderStage, stage,
+        uint8_t, index,
+        backend::PushConstantVariant, value)
+
 DECL_DRIVER_API_N(insertEventMarker,
        const char*, string,
        uint32_t, len = 0)
@@ -468,7 +478,7 @@ DECL_DRIVER_API_N(readBufferSubData,
 * --------------------
 */

-DECL_DRIVER_API_N(blit,
+DECL_DRIVER_API_N(blitDEPRECATED,
        backend::TargetBufferFlags, buffers,
        backend::RenderTargetHandle, dst,
        backend::Viewport, dstRect,
@@ -476,15 +486,47 @@ DECL_DRIVER_API_N(blit,
        backend::Viewport, srcRect,
        backend::SamplerMagFilter, filter)

+DECL_DRIVER_API_N(resolve,
+        backend::TextureHandle, dst,
+        uint8_t, dstLevel, uint8_t, dstLayer,
+        backend::TextureHandle, src,
+        uint8_t, srcLevel, uint8_t, srcLayer)
+
+DECL_DRIVER_API_N(blit,
+        backend::TextureHandle, dst,
+        uint8_t, dstLevel, uint8_t, dstLayer,
+        math::uint2, dstOrigin,
+        backend::TextureHandle, src,
+        uint8_t, srcLevel, uint8_t, srcLayer,
+        math::uint2, srcOrigin,
+        math::uint2, size)
+
+DECL_DRIVER_API_N(bindPipeline,
+        backend::PipelineState, state)
+
+DECL_DRIVER_API_N(bindRenderPrimitive,
+        backend::RenderPrimitiveHandle, rph)
+
+DECL_DRIVER_API_N(draw2,
+        uint32_t, indexOffset,
+        uint32_t, indexCount,
+        uint32_t, instanceCount)
+
 DECL_DRIVER_API_N(draw,
        backend::PipelineState, state,
        backend::RenderPrimitiveHandle, rph,
+        uint32_t, indexOffset,
+        uint32_t, indexCount,
        uint32_t, instanceCount)

+
 DECL_DRIVER_API_N(dispatchCompute,
        backend::ProgramHandle, program,
        math::uint3, workGroupCount)

+DECL_DRIVER_API_N(scissor,
+        Viewport, scissor)
+

 #pragma clang diagnostic pop

@@ -22,29 +22,34 @@
 #include <utils/Allocator.h>
 #include <utils/Log.h>
 #include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/ostream.h>
+#include <utils/Panic.h>
+
 #include <tsl/robin_map.h>
+
+#include <cstddef>
+#include <exception>
+#include <type_traits>
 #include <unordered_map>
+#include <utility>

-#if !defined(NDEBUG) && UTILS_HAS_RTTI
-#   define HANDLE_TYPE_SAFETY 1
-#else
-#   define HANDLE_TYPE_SAFETY 0
-#endif
+#include <stddef.h>
+#include <stdint.h>

-#define HandleAllocatorGL  HandleAllocator<16, 64, 208>
-#define HandleAllocatorVK  HandleAllocator<16, 64, 880>
-#define HandleAllocatorMTL HandleAllocator<16, 64, 584>
+#define HandleAllocatorGL  HandleAllocator<32,  64, 136>    // ~4520 / pool / MiB
+#define HandleAllocatorVK  HandleAllocator<64, 160, 312>    // ~1820 / pool / MiB
+#define HandleAllocatorMTL HandleAllocator<32,  48, 552>    // ~1660 / pool / MiB

 namespace filament::backend {

 /*
 * A utility class to efficiently allocate and manage Handle<>
 */
-template <size_t P0, size_t P1, size_t P2>
+template<size_t P0, size_t P1, size_t P2>
 class HandleAllocator {
 public:
-
-    HandleAllocator(const char* name, size_t size) noexcept;
+    HandleAllocator(const char* name, size_t size, bool disableUseAfterFreeCheck) noexcept;
    HandleAllocator(HandleAllocator const& rhs) = delete;
    HandleAllocator& operator=(HandleAllocator const& rhs) = delete;
    ~HandleAllocator();
@@ -60,15 +65,10 @@ public:
     *
     */
    template<typename D, typename ... ARGS>
-    Handle<D> allocateAndConstruct(ARGS&& ... args) noexcept {
-        Handle<D> h{ allocateHandle<sizeof(D)>() };
+    Handle<D> allocateAndConstruct(ARGS&& ... args) {
+        Handle<D> h{ allocateHandle<D>() };
        D* addr = handle_cast<D*>(h);
        new(addr) D(std::forward<ARGS>(args)...);
-#if HANDLE_TYPE_SAFETY
-        mLock.lock();
-        mHandleTypeId[addr] = typeid(D).name();
-        mLock.unlock();
-#endif
        return h;
    }

@@ -84,13 +84,7 @@ public:
     */
    template<typename D>
    Handle<D> allocate() noexcept {
-        Handle<D> h{ allocateHandle<sizeof(D)>() };
-#if HANDLE_TYPE_SAFETY
-        D* addr = handle_cast<D*>(h);
-        mLock.lock();
-        mHandleTypeId[addr] = typeid(D).name();
-        mLock.unlock();
-#endif
+        Handle<D> h{ allocateHandle<D>() };
        return h;
    }

@@ -103,21 +97,14 @@ public:
     */
    template<typename D, typename B, typename ... ARGS>
    typename std::enable_if_t<std::is_base_of_v<B, D>, D>*
-    destroyAndConstruct(Handle<B> const& handle, ARGS&& ... args) noexcept {
+    destroyAndConstruct(Handle<B> const& handle, ARGS&& ... args) {
        assert_invariant(handle);
        D* addr = handle_cast<D*>(const_cast<Handle<B>&>(handle));
        assert_invariant(addr);
-
        // currently we implement construct<> with dtor+ctor, we could use operator= also
        // but all our dtors are trivial, ~D() is actually a noop.
        addr->~D();
        new(addr) D(std::forward<ARGS>(args)...);
-
-#if HANDLE_TYPE_SAFETY
-        mLock.lock();
-        mHandleTypeId[addr] = typeid(D).name();
-        mLock.unlock();
-#endif
        return addr;
    }

@@ -134,12 +121,6 @@ public:
        D* addr = handle_cast<D*>(const_cast<Handle<B>&>(handle));
        assert_invariant(addr);
        new(addr) D(std::forward<ARGS>(args)...);
-
-#if HANDLE_TYPE_SAFETY
-        mLock.lock();
-        mHandleTypeId[addr] = typeid(D).name();
-        mLock.unlock();
-#endif
        return addr;
    }

@@ -155,19 +136,8 @@ public:
    void deallocate(Handle<B>& handle, D const* p) noexcept {
        // allow to destroy the nullptr, similarly to operator delete
        if (p) {
-#if HANDLE_TYPE_SAFETY
-            mLock.lock();
-            auto typeId = mHandleTypeId[p];
-            mHandleTypeId.erase(p);
-            mLock.unlock();
-            if (UTILS_UNLIKELY(typeId != typeid(D).name())) {
-                utils::slog.e << "Destroying handle " << handle.getId() << ", type " << typeid(D).name()
-                       << ", but handle's actual type is " << typeId << utils::io::endl;
-                std::terminate();
-            }
-#endif
            p->~D();
-            deallocateHandle<sizeof(D)>(handle.getId());
+            deallocateHandle<D>(handle.getId());
        }
    }

@@ -193,9 +163,21 @@ public:
    inline typename std::enable_if_t<
            std::is_pointer_v<Dp> &&
            std::is_base_of_v<B, typename std::remove_pointer_t<Dp>>, Dp>
-    handle_cast(Handle<B>& handle) noexcept {
+    handle_cast(Handle<B>& handle) {
        assert_invariant(handle);
-        void* const p = handleToPointer(handle.getId());
+        auto [p, tag] = handleToPointer(handle.getId());
+
+        if (isPoolHandle(handle.getId())) {
+            // check for use after free
+            if (UTILS_UNLIKELY(!mUseAfterFreeCheckDisabled)) {
+                uint8_t const age = (tag & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
+                auto const pNode = static_cast<typename Allocator::Node*>(p);
+                uint8_t const expectedAge = pNode[-1].age;
+                ASSERT_POSTCONDITION(expectedAge == age,
+                        "use-after-free of Handle with id=%d", handle.getId());
+            }
+        }
+
        return static_cast<Dp>(p);
    }

@@ -203,36 +185,66 @@ public:
    inline typename std::enable_if_t<
            std::is_pointer_v<Dp> &&
            std::is_base_of_v<B, typename std::remove_pointer_t<Dp>>, Dp>
-    handle_cast(Handle<B> const& handle) noexcept {
+    handle_cast(Handle<B> const& handle) {
        return handle_cast<Dp>(const_cast<Handle<B>&>(handle));
    }

-
 private:

-    // template <int P0, int P1, int P2>
+    template<typename D>
+    static constexpr size_t getBucketSize() noexcept {
+        if constexpr (sizeof(D) <= P0) { return P0; }
+        if constexpr (sizeof(D) <= P1) { return P1; }
+        static_assert(sizeof(D) <= P2);
+        return P2;
+    }
+
    class Allocator {
        friend class HandleAllocator;
-        utils::PoolAllocator<P0, 16>   mPool0;
-        utils::PoolAllocator<P1, 16>   mPool1;
-        utils::PoolAllocator<P2, 16>   mPool2;
+        static constexpr size_t MIN_ALIGNMENT = alignof(std::max_align_t);
+        struct Node { uint8_t age; };
+        // Note: using the `extra` parameter of PoolAllocator<>, even with a 1-byte structure,
+        // generally increases all pool allocations by 8-bytes because of alignment restrictions.
+        template<size_t SIZE>
+        using Pool = utils::PoolAllocator<SIZE, MIN_ALIGNMENT, sizeof(Node)>;
+        Pool<P0> mPool0;
+        Pool<P1> mPool1;
+        Pool<P2> mPool2;
        UTILS_UNUSED_IN_RELEASE const utils::AreaPolicy::HeapArea& mArea;
+        bool mUseAfterFreeCheckDisabled;
    public:
-        static constexpr size_t MIN_ALIGNMENT_SHIFT = 4;
-        explicit Allocator(const utils::AreaPolicy::HeapArea& area);
+        explicit Allocator(const utils::AreaPolicy::HeapArea& area, bool disableUseAfterFreeCheck);
+
+        static constexpr size_t getAlignment() noexcept { return MIN_ALIGNMENT; }

        // this is in fact always called with a constexpr size argument
-        [[nodiscard]] inline void* alloc(size_t size, size_t alignment, size_t extra) noexcept {
+        [[nodiscard]] inline void* alloc(size_t size, size_t, size_t, uint8_t* outAge) noexcept {
            void* p = nullptr;
-                 if (size <= mPool0.getSize()) p = mPool0.alloc(size, 16, extra);
-            else if (size <= mPool1.getSize()) p = mPool1.alloc(size, 16, extra);
-            else if (size <= mPool2.getSize()) p = mPool2.alloc(size, 16, extra);
+            if      (size <= mPool0.getSize()) p = mPool0.alloc(size);
+            else if (size <= mPool1.getSize()) p = mPool1.alloc(size);
+            else if (size <= mPool2.getSize()) p = mPool2.alloc(size);
+            if (UTILS_LIKELY(p)) {
+                Node const* const pNode = static_cast<Node const*>(p);
+                // we are guaranteed to have at least sizeof<Node> bytes of extra storage before
+                // the allocation address.
+                *outAge = pNode[-1].age;
+            }
            return p;
        }

        // this is in fact always called with a constexpr size argument
-        inline void free(void* p, size_t size) noexcept {
+        inline void free(void* p, size_t size, uint8_t age) noexcept {
            assert_invariant(p >= mArea.begin() && (char*)p + size <= (char*)mArea.end());
+
+            // check for double-free
+            Node* const pNode = static_cast<Node*>(p);
+            uint8_t& expectedAge = pNode[-1].age;
+            if (UTILS_UNLIKELY(!mUseAfterFreeCheckDisabled)) {
+                ASSERT_POSTCONDITION(expectedAge == age,
+                        "double-free of Handle of size %d at %p", size, p);
+            }
+            expectedAge = (expectedAge + 1) & 0xF; // fixme
+
            if (size <= mPool0.getSize()) { mPool0.free(p); return; }
            if (size <= mPool1.getSize()) { mPool1.free(p); return; }
            if (size <= mPool2.getSize()) { mPool2.free(p); return; }
@@ -254,24 +266,16 @@ private:
    // allocateHandle()/deallocateHandle() selects the pool to use at compile-time based on the
    // allocation size this is always inlined, because all these do is to call
    // allocateHandleInPool()/deallocateHandleFromPool() with the right pool size.
-    template<size_t SIZE>
+    template<typename D>
    HandleBase::HandleId allocateHandle() noexcept {
-        if constexpr (SIZE <= P0) { return allocateHandleInPool<P0>(); }
-        if constexpr (SIZE <= P1) { return allocateHandleInPool<P1>(); }
-        static_assert(SIZE <= P2);
-        return allocateHandleInPool<P2>();
+        constexpr size_t BUCKET_SIZE = getBucketSize<D>();
+        return allocateHandleInPool<BUCKET_SIZE>();
    }

-    template<size_t SIZE>
+    template<typename D>
    void deallocateHandle(HandleBase::HandleId id) noexcept {
-        if constexpr (SIZE <= P0) {
-            deallocateHandleFromPool<P0>(id);
-        } else if constexpr (SIZE <= P1) {
-            deallocateHandleFromPool<P1>(id);
-        } else {
-            static_assert(SIZE <= P2);
-            deallocateHandleFromPool<P2>(id);
-        }
+        constexpr size_t BUCKET_SIZE = getBucketSize<D>();
+        deallocateHandleFromPool<BUCKET_SIZE>(id);
    }

    // allocateHandleInPool()/deallocateHandleFromPool() is NOT inlined, which will cause three
@@ -280,9 +284,11 @@ private:
    template<size_t SIZE>
    UTILS_NOINLINE
    HandleBase::HandleId allocateHandleInPool() noexcept {
-        void* p = mHandleArena.alloc(SIZE);
+        uint8_t age;
+        void* p = mHandleArena.alloc(SIZE, alignof(std::max_align_t), 0, &age);
        if (UTILS_LIKELY(p)) {
-            return pointerToHandle(p);
+            uint32_t const tag = (uint32_t(age) << HANDLE_AGE_SHIFT) & HANDLE_AGE_MASK;
+            return arenaPointerToHandle(p, tag);
        } else {
            return allocateHandleSlow(SIZE);
        }
@@ -292,42 +298,51 @@ private:
    UTILS_NOINLINE
    void deallocateHandleFromPool(HandleBase::HandleId id) noexcept {
        if (UTILS_LIKELY(isPoolHandle(id))) {
-            void* p = handleToPointer(id);
-            mHandleArena.free(p, SIZE);
+            auto [p, tag] = handleToPointer(id);
+            uint8_t const age = (tag & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
+            mHandleArena.free(p, SIZE, age);
        } else {
            deallocateHandleSlow(id, SIZE);
        }
    }

-    static constexpr uint32_t HEAP_HANDLE_FLAG = 0x80000000u;
+    // we handle a 4 bits age per address
+    static constexpr uint32_t HANDLE_HEAP_FLAG      = 0x80000000u;      // pool vs heap handle
+    static constexpr uint32_t HANDLE_AGE_MASK       = 0x78000000u;      // handle's age
+    static constexpr uint32_t HANDLE_INDEX_MASK     = 0x07FFFFFFu;      // handle index
+    static constexpr uint32_t HANDLE_TAG_MASK       = HANDLE_AGE_MASK;
+    static constexpr uint32_t HANDLE_AGE_SHIFT      = 27;

    static bool isPoolHandle(HandleBase::HandleId id) noexcept {
-        return (id & HEAP_HANDLE_FLAG) == 0u;
+        return (id & HANDLE_HEAP_FLAG) == 0u;
    }

-    HandleBase::HandleId allocateHandleSlow(size_t size) noexcept;
+    HandleBase::HandleId allocateHandleSlow(size_t size);
    void deallocateHandleSlow(HandleBase::HandleId id, size_t size) noexcept;

    // We inline this because it's just 4 instructions in the fast case
-    inline void* handleToPointer(HandleBase::HandleId id) const noexcept {
+    inline std::pair<void*, uint32_t> handleToPointer(HandleBase::HandleId id) const noexcept {
        // note: the null handle will end-up returning nullptr b/c it'll be handled as
        // a non-pool handle.
        if (UTILS_LIKELY(isPoolHandle(id))) {
            char* const base = (char*)mHandleArena.getArea().begin();
-            size_t offset = id << Allocator::MIN_ALIGNMENT_SHIFT;
-            return static_cast<void*>(base + offset);
+            uint32_t const tag = id & HANDLE_TAG_MASK;
+            size_t const offset = (id & HANDLE_INDEX_MASK) * Allocator::getAlignment();
+            return { static_cast<void*>(base + offset), tag };
        }
-        return handleToPointerSlow(id);
+        return { handleToPointerSlow(id), 0 };
    }

    void* handleToPointerSlow(HandleBase::HandleId id) const noexcept;

    // We inline this because it's just 3 instructions
-    inline HandleBase::HandleId pointerToHandle(void* p) const noexcept {
+    inline HandleBase::HandleId arenaPointerToHandle(void* p, uint32_t tag) const noexcept {
        char* const base = (char*)mHandleArena.getArea().begin();
-        size_t offset = (char*)p - base;
-        auto id = HandleBase::HandleId(offset >> Allocator::MIN_ALIGNMENT_SHIFT);
-        assert_invariant((id & HEAP_HANDLE_FLAG) == 0);
+        size_t const offset = (char*)p - base;
+        assert_invariant((offset % Allocator::getAlignment()) == 0);
+        auto id = HandleBase::HandleId(offset / Allocator::getAlignment());
+        id |= tag & HANDLE_TAG_MASK;
+        assert_invariant((id & HANDLE_HEAP_FLAG) == 0);
        return id;
    }

@@ -337,9 +352,7 @@ private:
    mutable utils::Mutex mLock;
    tsl::robin_map<HandleBase::HandleId, void*> mOverflowMap;
    HandleBase::HandleId mId = 0;
-#if HANDLE_TYPE_SAFETY
-    mutable std::unordered_map<const void*, const char*> mHandleTypeId;
-#endif
+    bool mUseAfterFreeCheckDisabled = false;
 };

 } // namespace filament::backend
@@ -19,9 +19,9 @@
 #ifndef TNT_FILAMENT_BACKEND_PLATFORM_FACTORY_H
 #define TNT_FILAMENT_BACKEND_PLATFORM_FACTORY_H

-#include "backend/DriverEnums.h"
+#include <backend/DriverEnums.h>

-#include "utils/compiler.h"
+#include <utils/compiler.h>

 namespace filament::backend {

@@ -17,15 +17,13 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H

-#include "backend/DriverApiForward.h"
-
-#include <utils/compiler.h>
-#include <utils/FixedCapacityVector.h>
-
+#include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
-#include <backend/Handle.h>
 #include <backend/SamplerDescriptor.h>

+#include <utils/FixedCapacityVector.h>
+#include <utils/ostream.h>
+
 #include <stddef.h>

 namespace filament::backend {
@@ -16,6 +16,14 @@

 #include "private/backend/CircularBuffer.h"

+#include <utils/Log.h>
+#include <utils/Panic.h>
+#include <utils/architecture.h>
+#include <utils/ashmem.h>
+#include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/ostream.h>
+
 #if !defined(WIN32) && !defined(__EMSCRIPTEN__) && !defined(IOS)
 #    include <sys/mman.h>
 #    include <unistd.h>
@@ -24,23 +32,20 @@
 #    define HAS_MMAP 0
 #endif

+#include <stdint.h>
+#include <stddef.h>
+#include <stdlib.h>
 #include <stdio.h>

-#include <utils/architecture.h>
-#include <utils/ashmem.h>
-#include <utils/debug.h>
-#include <utils/Log.h>
-#include <utils/Panic.h>
-
 using namespace utils;

 namespace filament::backend {

 size_t CircularBuffer::sPageSize = arch::getPageSize();

-CircularBuffer::CircularBuffer(size_t size) {
+CircularBuffer::CircularBuffer(size_t size)
+    : mSize(size) {
    mData = alloc(size);
-    mSize = size;
    mTail = mData;
    mHead = mData;
 }
@@ -85,7 +90,7 @@ void* CircularBuffer::alloc(size_t size) noexcept {
                            MAP_PRIVATE, fd, (off_t)size);
                    if (vaddr_guard != MAP_FAILED && (vaddr_guard == (char*)vaddr_shadow + size)) {
                        // woo-hoo success!
-                        mUsesAshmem = fd;
+                        mAshmemFd = fd;
                        data = vaddr;
                    }
                }
@@ -93,7 +98,7 @@ void* CircularBuffer::alloc(size_t size) noexcept {
        }
    }

-    if (UTILS_UNLIKELY(mUsesAshmem < 0)) {
+    if (UTILS_UNLIKELY(mAshmemFd < 0)) {
        // ashmem failed
        if (vaddr_guard != MAP_FAILED) {
            munmap(vaddr_guard, size);
@@ -137,9 +142,9 @@ void CircularBuffer::dealloc() noexcept {
    if (mData) {
        size_t const BLOCK_SIZE = getBlockSize();
        munmap(mData, mSize * 2 + BLOCK_SIZE);
-        if (mUsesAshmem >= 0) {
-            close(mUsesAshmem);
-            mUsesAshmem = -1;
+        if (mAshmemFd >= 0) {
+            close(mAshmemFd);
+            mAshmemFd = -1;
        }
    }
 #else
@@ -149,23 +154,37 @@ void CircularBuffer::dealloc() noexcept {
 }


-void CircularBuffer::circularize() noexcept {
-    if (mUsesAshmem > 0) {
-        intptr_t const overflow = intptr_t(mHead) - (intptr_t(mData) + ssize_t(mSize));
-        if (overflow >= 0) {
-            assert_invariant(size_t(overflow) <= mSize);
-            mHead = (void *) (intptr_t(mData) + overflow);
-            #ifndef NDEBUG
-            memset(mData, 0xA5, size_t(overflow));
-            #endif
-        }
-    } else {
-        // Only circularize if mHead if in the second buffer.
-        if (intptr_t(mHead) - intptr_t(mData) > ssize_t(mSize)) {
+CircularBuffer::Range CircularBuffer::getBuffer() noexcept {
+    Range const range{ .tail = mTail, .head = mHead };
+
+    char* const pData = static_cast<char*>(mData);
+    char const* const pEnd = pData + mSize;
+    char const* const pHead = static_cast<char const*>(mHead);
+    if (UTILS_UNLIKELY(pHead >= pEnd)) {
+        size_t const overflow = pHead - pEnd;
+        if (UTILS_LIKELY(mAshmemFd > 0)) {
+            assert_invariant(overflow <= mSize);
+            mHead = static_cast<void*>(pData + overflow);
+            // Data         Tail  End   Head              [virtual]
+            //  v             v    v     v
+            //  +-------------:----+-----:--------------+
+            //  |             :    |     :              |
+            //  +-----:------------+--------------------+
+            //       Head          |<------ copy ------>| [physical]
+        } else {
+            // Data         Tail  End   Head
+            //  v             v    v     v
+            //  +-------------:----+-----:--------------+
+            //  |             :    |     :              |
+            //  +-----|------------+-----|--------------+
+            //        |<---------------->|
+            //           sliding window
            mHead = mData;
        }
    }
    mTail = mHead;
+
+    return range;
 }

 } // namespace filament::backend
@@ -15,23 +15,35 @@
 */

 #include "private/backend/CommandBufferQueue.h"
+#include "private/backend/CircularBuffer.h"
+#include "private/backend/CommandStream.h"

+#include <utils/compiler.h>
 #include <utils/Log.h>
-#include <utils/Systrace.h>
+#include <utils/Mutex.h>
+#include <utils/ostream.h>
 #include <utils/Panic.h>
+#include <utils/Systrace.h>
 #include <utils/debug.h>

-#include "private/backend/BackendUtils.h"
-#include "private/backend/CommandStream.h"
+#include <algorithm>
+#include <mutex>
+#include <iterator>
+#include <utility>
+#include <vector>
+
+#include <stddef.h>
+#include <stdint.h>

 using namespace utils;

 namespace filament::backend {

-CommandBufferQueue::CommandBufferQueue(size_t requiredSize, size_t bufferSize)
+CommandBufferQueue::CommandBufferQueue(size_t requiredSize, size_t bufferSize, bool paused)
        : mRequiredSize((requiredSize + (CircularBuffer::getBlockSize() - 1u)) & ~(CircularBuffer::getBlockSize() -1u)),
          mCircularBuffer(bufferSize),
-          mFreeSpace(mCircularBuffer.size()) {
+          mFreeSpace(mCircularBuffer.size()),
+          mPaused(paused) {
    assert_invariant(mCircularBuffer.size() > requiredSize);
 }

@@ -45,6 +57,21 @@ void CommandBufferQueue::requestExit() {
    mCondition.notify_one();
 }

+bool CommandBufferQueue::isPaused() const noexcept {
+    std::lock_guard<utils::Mutex> const lock(mLock);
+    return mPaused;
+}
+
+void CommandBufferQueue::setPaused(bool paused) {
+    std::lock_guard<utils::Mutex> const lock(mLock);
+    if (paused) {
+        mPaused = true;
+    } else {
+        mPaused = false;
+        mCondition.notify_one();
+    }
+}
+
 bool CommandBufferQueue::isExitRequested() const {
    std::lock_guard<utils::Mutex> const lock(mLock);
    ASSERT_PRECONDITION( mExitRequested == 0 || mExitRequested == EXIT_REQUESTED,
@@ -65,55 +92,61 @@ void CommandBufferQueue::flush() noexcept {
    // always guaranteed to have enough space for the NoopCommand
    new(circularBuffer.allocate(sizeof(NoopCommand))) NoopCommand(nullptr);

-    // end of this slice
-    void* const head = circularBuffer.getHead();
+    const size_t requiredSize = mRequiredSize;

-    // beginning of this slice
-    void* const tail = circularBuffer.getTail();
+    // get the current buffer
+    auto const [begin, end] = circularBuffer.getBuffer();

-    // size of this slice
-    uint32_t const used = uint32_t(intptr_t(head) - intptr_t(tail));
+    assert_invariant(circularBuffer.empty());

-    circularBuffer.circularize();
+    // size of the current buffer
+    size_t const used = std::distance(
+            static_cast<char const*>(begin), static_cast<char const*>(end));

    std::unique_lock<utils::Mutex> lock(mLock);
-    mCommandBuffersToExecute.push_back({ tail, head });
+    mCommandBuffersToExecute.push_back({ begin, end });
+    mCondition.notify_one();

    // circular buffer is too small, we corrupted the stream
    ASSERT_POSTCONDITION(used <= mFreeSpace,
            "Backend CommandStream overflow. Commands are corrupted and unrecoverable.\n"
            "Please increase minCommandBufferSizeMB inside the Config passed to Engine::create.\n"
-            "Space used at this time: %u bytes",
-            (unsigned)used);
+            "Space used at this time: %u bytes, overflow: %u bytes",
+            (unsigned)used, unsigned(used - mFreeSpace));

    // wait until there is enough space in the buffer
    mFreeSpace -= used;
-    const size_t requiredSize = mRequiredSize;
+    if (UTILS_UNLIKELY(mFreeSpace < requiredSize)) {
+

 #ifndef NDEBUG
-    size_t totalUsed = circularBuffer.size() - mFreeSpace;
-    mHighWatermark = std::max(mHighWatermark, totalUsed);
-    if (UTILS_UNLIKELY(totalUsed > requiredSize)) {
-        slog.d << "CommandStream used too much space: " << totalUsed
-            << ", out of " << requiredSize << " (will block)" << io::endl;
-    }
+        size_t const totalUsed = circularBuffer.size() - mFreeSpace;
+        slog.d << "CommandStream used too much space (will block): "
+                << "needed space " << requiredSize << " out of " << mFreeSpace
+                << ", totalUsed=" << totalUsed << ", current=" << used
+                << ", queue size=" << mCommandBuffersToExecute.size() << " buffers"
+                << io::endl;
+
+        mHighWatermark = std::max(mHighWatermark, totalUsed);
 #endif

-    mCondition.notify_one();
-    if (UTILS_LIKELY(mFreeSpace < requiredSize)) {
        SYSTRACE_NAME("waiting: CircularBuffer::flush()");
+        ASSERT_POSTCONDITION(!mPaused,
+                "CommandStream is full, but since the rendering thread is paused, "
+                "the buffer cannot flush and we will deadlock. Instead, abort.");
        mCondition.wait(lock, [this, requiredSize]() -> bool {
+            // TODO: on macOS, we need to call pumpEvents from time to time
            return mFreeSpace >= requiredSize;
        });
    }
 }

-std::vector<CommandBufferQueue::Slice> CommandBufferQueue::waitForCommands() const {
+std::vector<CommandBufferQueue::Range> CommandBufferQueue::waitForCommands() const {
    if (!UTILS_HAS_THREADING) {
        return std::move(mCommandBuffersToExecute);
    }
    std::unique_lock<utils::Mutex> lock(mLock);
-    while (mCommandBuffersToExecute.empty() && !mExitRequested) {
+    while ((mCommandBuffersToExecute.empty() || mPaused) && !mExitRequested) {
        mCondition.wait(lock);
    }

@@ -123,7 +156,7 @@ std::vector<CommandBufferQueue::Slice> CommandBufferQueue::waitForCommands() con
    return std::move(mCommandBuffersToExecute);
 }

-void CommandBufferQueue::releaseBuffer(CommandBufferQueue::Slice const& buffer) {
+void CommandBufferQueue::releaseBuffer(CommandBufferQueue::Range const& buffer) {
    std::lock_guard<utils::Mutex> const lock(mLock);
    mFreeSpace += uintptr_t(buffer.end) - uintptr_t(buffer.begin);
    mCondition.notify_one();
@@ -149,7 +149,7 @@ void CommandType<void (Driver::*)(ARGS...)>::Command<METHOD>::log() noexcept  {

 // ------------------------------------------------------------------------------------------------

-void CustomCommand::execute(Driver&, CommandBase* base, intptr_t* next) noexcept {
+void CustomCommand::execute(Driver&, CommandBase* base, intptr_t* next) {
    *next = CustomCommand::align(sizeof(CustomCommand));
    static_cast<CustomCommand*>(base)->mCommand();
    static_cast<CustomCommand*>(base)->~CustomCommand();
@@ -19,6 +19,7 @@

 #include <backend/PixelBufferDescriptor.h>

+#include <cstring>
 #include <stddef.h>
 #include <stdint.h>

@@ -21,7 +21,12 @@

 #include <backend/AcquiredImage.h>
 #include <backend/BufferDescriptor.h>
+#include <backend/DriverEnums.h>

+#include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/Log.h>
+#include <utils/ostream.h>
 #include <utils/Systrace.h>

 #include <math/half.h>
@@ -29,6 +34,13 @@
 #include <math/vec3.h>
 #include <math/vec4.h>

+#include <functional>
+#include <mutex>
+#include <utility>
+
+#include <stddef.h>
+#include <stdint.h>
+
 using namespace utils;
 using namespace filament::math;

@@ -119,7 +131,8 @@ void DriverBase::purge() noexcept {
 // ------------------------------------------------------------------------------------------------

 void DriverBase::scheduleDestroySlow(BufferDescriptor&& buffer) noexcept {
-    scheduleCallback(buffer.getHandler(), [buffer = std::move(buffer)]() {
+    auto const handler = buffer.getHandler();
+    scheduleCallback(handler, [buffer = std::move(buffer)]() {
        // user callback is called when BufferDescriptor gets destroyed
    });
 }
@@ -201,7 +214,7 @@ size_t Driver::getElementTypeSize(ElementType type) noexcept {

 Driver::~Driver() noexcept = default;

-void Driver::execute(std::function<void(void)> const& fn) noexcept {
+void Driver::execute(std::function<void(void)> const& fn) {
    fn();
 }

@@ -49,24 +49,28 @@ struct AcquiredImage;
 struct HwBase {
 };

-struct HwVertexBuffer : public HwBase {
-    AttributeArray attributes{};          // 8 * MAX_VERTEX_ATTRIBUTE_COUNT
-    uint32_t vertexCount{};               //   4
+
+struct HwVertexBufferInfo : public HwBase {
    uint8_t bufferCount{};                //   1
    uint8_t attributeCount{};             //   1
-    bool padding{};                       //   1
-    uint8_t bufferObjectsVersion{};       //   1 -> total struct is 136 bytes
-
-    HwVertexBuffer() noexcept = default;
-    HwVertexBuffer(uint8_t bufferCount, uint8_t attributeCount, uint32_t elementCount,
-            AttributeArray const& attributes) noexcept
-            : attributes(attributes),
-              vertexCount(elementCount),
-              bufferCount(bufferCount),
+    bool padding[2]{};                    //   2
+    HwVertexBufferInfo() noexcept = default;
+    HwVertexBufferInfo(uint8_t bufferCount, uint8_t attributeCount) noexcept
+            : bufferCount(bufferCount),
              attributeCount(attributeCount) {
    }
 };

+struct HwVertexBuffer : public HwBase {
+    uint32_t vertexCount{};               //   4
+    uint8_t bufferObjectsVersion{0xff};   //   1
+    bool padding[3]{};                    //   2
+    HwVertexBuffer() noexcept = default;
+    explicit HwVertexBuffer(uint32_t vertextCount) noexcept
+            : vertexCount(vertextCount) {
+    }
+};
+
 struct HwBufferObject : public HwBase {
    uint32_t byteCount{};

@@ -88,11 +92,6 @@ struct HwIndexBuffer : public HwBase {
 };

 struct HwRenderPrimitive : public HwBase {
-    uint32_t offset{};
-    uint32_t minIndex{};
-    uint32_t maxIndex{};
-    uint32_t count{};
-    uint32_t maxVertexCount{};
    PrimitiveType type = PrimitiveType::TRIANGLES;
 };

@@ -114,7 +113,9 @@ struct HwTexture : public HwBase {
    uint8_t levels : 4;  // This allows up to 15 levels (max texture size of 32768 x 32768)
    uint8_t samples : 4; // Sample count per pixel (should always be a power of 2)
    TextureFormat format{};
+    uint8_t reserved0 = 0;
    TextureUsage usage{};
+    uint16_t reserved1 = 0;
    HwStream* hwStream = nullptr;

    HwTexture() noexcept : levels{}, samples{} {}
@@ -16,9 +16,22 @@

 #include "private/backend/HandleAllocator.h"

+#include <backend/Handle.h>
+
+#include <utils/Allocator.h>
+#include <utils/Log.h>
 #include <utils/Panic.h>
+#include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/ostream.h>
+
+#include <algorithm>
+#include <exception>
+#include <limits>
+#include <mutex>

 #include <stdlib.h>
+#include <string.h>

 namespace filament::backend {

@@ -26,23 +39,47 @@ using namespace utils;

 template <size_t P0, size_t P1, size_t P2>
 UTILS_NOINLINE
-HandleAllocator<P0, P1, P2>::Allocator::Allocator(AreaPolicy::HeapArea const& area)
-        : mArea(area) {
-    // TODO: we probably need a better way to set the size of these pools
-    const size_t unit = area.size() / 32;
-    const size_t offsetPool1 =      unit;
-    const size_t offsetPool2 = 16 * unit;
-    char* const p = (char*)area.begin();
-    mPool0 = PoolAllocator< P0, 16>(p, p + offsetPool1);
-    mPool1 = PoolAllocator< P1, 16>(p + offsetPool1, p + offsetPool2);
-    mPool2 = PoolAllocator< P2, 16>(p + offsetPool2, area.end());
+HandleAllocator<P0, P1, P2>::Allocator::Allocator(AreaPolicy::HeapArea const& area,
+        bool disableUseAfterFreeCheck)
+        : mArea(area),
+          mUseAfterFreeCheckDisabled(disableUseAfterFreeCheck) {
+
+    // The largest handle this allocator can generate currently depends on the architecture's
+    // min alignment, typically 8 or 16 bytes.
+    // e.g. On Android armv8, the alignment is 16 bytes, so for a 1 MiB heap, the largest handle
+    //      index will be 65536. Note that this is not the same as the number of handles (which
+    //      will always be less).
+    // Because our maximum representable handle currently is 0x07FFFFFF, the maximum no-nonsensical
+    // heap size is 2 GiB, which amounts to 7.6 millions handles per pool (in the GL case).
+    size_t const maxHeapSize = std::min(area.size(), HANDLE_INDEX_MASK * getAlignment());
+
+    if (UTILS_UNLIKELY(maxHeapSize != area.size())) {
+        slog.w << "HandleAllocator heap size reduced to "
+               << maxHeapSize << " from " << area.size() << io::endl;
+    }
+
+    // make sure we start with a clean arena. This is needed to ensure that all blocks start
+    // with an age of 0.
+    memset(area.data(), 0, maxHeapSize);
+
+    // size the different pools so that they can all contain the same number of handles
+    size_t const count = maxHeapSize / (P0 + P1 + P2);
+    char* const p0 = static_cast<char*>(area.begin());
+    char* const p1 = p0 + count * P0;
+    char* const p2 = p1 + count * P1;
+
+    mPool0 = Pool<P0>(p0, count * P0);
+    mPool1 = Pool<P1>(p1, count * P1);
+    mPool2 = Pool<P2>(p2, count * P2);
 }

 // ------------------------------------------------------------------------------------------------

 template <size_t P0, size_t P1, size_t P2>
-HandleAllocator<P0, P1, P2>::HandleAllocator(const char* name, size_t size) noexcept
-    : mHandleArena(name, size) {
+HandleAllocator<P0, P1, P2>::HandleAllocator(const char* name, size_t size,
+        bool disableUseAfterFreeCheck) noexcept
+    : mHandleArena(name, size, disableUseAfterFreeCheck),
+      mUseAfterFreeCheckDisabled(disableUseAfterFreeCheck) {
 }

 template <size_t P0, size_t P1, size_t P2>
@@ -70,14 +107,20 @@ 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) noexcept {
+HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size) {
    void* p = ::malloc(size);
    std::unique_lock lock(mLock);
-    HandleBase::HandleId id = (++mId) | HEAP_HANDLE_FLAG;
+
+    HandleBase::HandleId id = (++mId) | HANDLE_HEAP_FLAG;
+
+    ASSERT_POSTCONDITION(mId < 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");
+
    mOverflowMap.emplace(id, p);
    lock.unlock();

-    if (UTILS_UNLIKELY(id == (HEAP_HANDLE_FLAG|1u))) { // meaning id was zero
+    if (UTILS_UNLIKELY(id == (HANDLE_HEAP_FLAG | 1u))) { // meaning id was zero
        PANIC_LOG("HandleAllocator arena is full, using slower system heap. Please increase "
                  "the appropriate constant (e.g. FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB).");
    }
@@ -86,7 +129,7 @@ HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size

 template <size_t P0, size_t P1, size_t P2>
 void HandleAllocator<P0, P1, P2>::deallocateHandleSlow(HandleBase::HandleId id, size_t) noexcept {
-    assert_invariant(id & HEAP_HANDLE_FLAG);
+    assert_invariant(id & HANDLE_HEAP_FLAG);
    void* p = nullptr;
    auto& overflowMap = mOverflowMap;

@@ -53,4 +53,18 @@ size_t Platform::retrieveBlob(void const* key, size_t keySize, void* value, size
    return 0;
 }

+void Platform::setDebugUpdateStatFunc(DebugUpdateStatFunc&& debugUpdateStat) noexcept {
+    mDebugUpdateStat = std::move(debugUpdateStat);
+}
+
+bool Platform::hasDebugUpdateStatFunc() const noexcept {
+    return bool(mDebugUpdateStat);
+}
+
+void Platform::debugUpdateStat(const char* key, uint64_t value) {
+    if (mDebugUpdateStat) {
+        mDebugUpdateStat(key, value);
+    }
+}
+
 } // namespace filament::backend
@@ -21,7 +21,7 @@ namespace filament::backend {
 using namespace utils;

 // We want these in the .cpp file, so they're not inlined (not worth it)
-Program::Program() noexcept { // NOLINT(modernize-use-equals-default)
+Program::Program() noexcept {  // NOLINT(modernize-use-equals-default)
 }

 Program::Program(Program&& rhs) noexcept = default;
@@ -47,6 +47,11 @@ Program& Program::shader(ShaderStage shader, void const* data, size_t size) {
    return *this;
 }

+Program& Program::shaderLanguage(ShaderLanguage shaderLanguage) {
+    mShaderLanguage = shaderLanguage;
+    return *this;
+}
+
 Program& Program::uniformBlockBindings(
        FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept {
    for (auto const& item : uniformBlockBindings) {
@@ -86,11 +91,22 @@ Program& Program::specializationConstants(
    return *this;
 }

+Program& Program::pushConstants(ShaderStage stage,
+        utils::FixedCapacityVector<PushConstant> constants) noexcept {
+    mPushConstants[static_cast<uint8_t>(stage)] = std::move(constants);
+    return *this;
+}
+
 Program& Program::cacheId(uint64_t cacheId) noexcept {
    mCacheId = cacheId;
    return *this;
 }

+Program& Program::multiview(bool multiview) noexcept {
+    mMultiview = multiview;
+    return *this;
+}
+
 io::ostream& operator<<(io::ostream& out, const Program& builder) {
    out << "Program{";
    builder.mLogger(out);
@@ -24,8 +24,7 @@
 #include <tsl/robin_map.h>
 #include <utils/Hash.h>

-namespace filament {
-namespace backend {
+namespace filament::backend {

 struct MetalContext;

@@ -37,8 +36,7 @@ public:

    struct BlitArgs {
        struct Attachment {
-            id<MTLTexture> color = nil;
-            id<MTLTexture> depth = nil;
+            id<MTLTexture> texture = nil;
            MTLRegion region = {};
            uint8_t level = 0;
            uint32_t slice = 0;      // must be 0 on source attachment
@@ -46,25 +44,13 @@ public:

        // Valid source formats:       2D, 2DArray, 2DMultisample, 3D
        // Valid destination formats:  2D, 2DArray, 3D, Cube
-        Attachment source, destination;
+        Attachment source;
+        Attachment destination;
        SamplerMagFilter filter;

-        bool blitColor() const {
-            return source.color != nil && destination.color != nil;
-        }
-
-        bool blitDepth() const {
-            return source.depth != nil && destination.depth != nil;
-        }
-
-        bool colorDestinationIsFullAttachment() const {
-            return destination.color.width == destination.region.size.width &&
-                   destination.color.height == destination.region.size.height;
-        }
-
-        bool depthDestinationIsFullAttachment() const {
-            return destination.depth.width == destination.region.size.width &&
-                   destination.depth.height == destination.region.size.height;
+        bool destinationIsFullAttachment() const {
+            return destination.texture.width == destination.region.size.width &&
+                   destination.texture.height == destination.region.size.height;
        }
    };

@@ -78,48 +64,36 @@ public:

 private:

-    static void setupColorAttachment(const BlitArgs& args, MTLRenderPassDescriptor* descriptor,
-            uint32_t depthPlane);
-    static void setupDepthAttachment(const BlitArgs& args, MTLRenderPassDescriptor* descriptor,
-            uint32_t depthPlane);
+    static void setupAttachment(MTLRenderPassAttachmentDescriptor* descriptor,
+            const BlitArgs& args, uint32_t depthPlane);

    struct BlitFunctionKey {
-        bool blitColor;
-        bool blitDepth;
-        bool msaaColorSource;
-        bool msaaDepthSource;
-        bool sources3D;
-
-        char padding[3];
+        bool msaaColorSource{};
+        bool sources3D{};
+        char padding[2]{};

        bool isValid() const noexcept {
            // MSAA 3D textures do not exist.
-            bool hasMsaa = msaaColorSource || msaaDepthSource;
+            bool const hasMsaa = msaaColorSource;
            return !(hasMsaa && sources3D);
        }

        bool operator==(const BlitFunctionKey& rhs) const noexcept {
-            return blitColor == rhs.blitColor &&
-                   blitDepth == rhs.blitDepth &&
-                   msaaColorSource == rhs.msaaColorSource &&
-                   msaaDepthSource == rhs.msaaDepthSource &&
+            return msaaColorSource == rhs.msaaColorSource &&
                   sources3D == rhs.sources3D;
        }
-
-        BlitFunctionKey() {
-            std::memset(this, 0, sizeof(BlitFunctionKey));
-        }
    };

-    void blitFastPath(id<MTLCommandBuffer> cmdBuffer, bool& blitColor, bool& blitDepth,
+    static bool blitFastPath(id<MTLCommandBuffer> cmdBuffer,
            const BlitArgs& args, const char* label);
-    void blitSlowPath(id<MTLCommandBuffer> cmdBuffer, bool& blitColor, bool& blitDepth,
+
+    void blitSlowPath(id<MTLCommandBuffer> cmdBuffer,
            const BlitArgs& args, const char* label);
-    void blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor, bool blitDepth,
-            const BlitArgs& args, uint32_t depthPlaneSource, uint32_t depthPlaneDest,
-            const char* label);
-    id<MTLTexture> createIntermediateTexture(id<MTLTexture> t, MTLSize size);
-    id<MTLFunction> compileFragmentFunction(BlitFunctionKey key);
+
+    void blitDepthPlane(id <MTLCommandBuffer> cmdBuffer, const BlitArgs& args,
+            uint32_t depthPlaneSource, uint32_t depthPlaneDest, const char* label);
+
+    id<MTLFunction> compileFragmentFunction(BlitFunctionKey key) const;
    id<MTLFunction> getBlitVertexFunction();
    id<MTLFunction> getBlitFragmentFunction(BlitFunctionKey key);

@@ -130,10 +104,9 @@ private:
    tsl::robin_map<BlitFunctionKey, Function, HashFn> mBlitFunctions;

    id<MTLFunction> mVertexFunction = nil;
-
 };

-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
+

 #endif //TNT_METALBLITTER_H
@@ -20,9 +20,9 @@
 #include "MetalUtils.h"

 #include <utils/Panic.h>
+#include <utils/Log.h>

-namespace filament {
-namespace backend {
+namespace filament::backend {

 static const char* functionLibrary = R"(
 #include <metal_stdlib>
@@ -37,13 +37,7 @@ struct VertexOut

 struct FragmentOut
 {
-#ifdef BLIT_COLOR
    float4 color [[color(0)]];
-#endif
-
-#ifdef BLIT_DEPTH
-    float depth [[depth(any)]];
-#endif
 };

 vertex VertexOut
@@ -67,7 +61,6 @@ fragment FragmentOut
 blitterFrag(VertexOut in [[stage_in]],
            sampler sourceSampler [[sampler(0)]],

-#ifdef BLIT_COLOR
 #ifdef MSAA_COLOR_SOURCE
            texture2d_ms<float, access::read> sourceColor [[texture(0)]],
 #elif SOURCES_3D
@@ -75,32 +68,18 @@ blitterFrag(VertexOut in [[stage_in]],
 #else
            texture2d<float, access::sample> sourceColor [[texture(0)]],
 #endif  // MSAA_COLOR_SOURCE
-#endif  // BLIT_COLOR
-
-#ifdef BLIT_DEPTH
-#ifdef MSAA_DEPTH_SOURCE
-            texture2d_ms<float, access::read> sourceDepth [[texture(1)]],
-#elif SOURCES_3D
-            texture3d<float, access::sample> sourceDepth [[texture(1)]],
-#else
-            texture2d<float, access::sample> sourceDepth [[texture(1)]],
-#endif  // MSAA_DEPTH_SOURCE
-#endif  // BLIT_DEPTH

            constant FragmentArgs* args [[buffer(0)]])
 {
    FragmentOut out = {};

-#if defined(BLIT_COLOR) || defined(BLIT_DEPTH)
    // These coordinates match the Vulkan vkCmdBlitImage spec:
    // https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkCmdBlitImage.html
    float2 uvbase = in.position.xy; // unnormalized coordinates at center of texel: (1.5, 2.5, etc)
    float2 uvoffset = uvbase - args->dstOffset;
    float2 uvscaled = uvoffset * args->scale;
    float2 uv = uvscaled + args->srcOffset;
-#endif

-#ifdef BLIT_COLOR
 #ifdef MSAA_COLOR_SOURCE
    out.color = float4(0.0);
    for (uint s = 0; s < sourceColor.get_num_samples(); s++) {
@@ -116,201 +95,106 @@ blitterFrag(VertexOut in [[stage_in]],
    float2 uvnorm = uv / float2(sourceColor.get_width(args->lod), sourceColor.get_height(args->lod));
    out.color += sourceColor.sample(sourceSampler, uvnorm, level(args->lod));
 #endif  // MSAA_COLOR_SOURCE
-#endif  // BLIT_COLOR

-#ifdef BLIT_DEPTH
-#ifdef MSAA_DEPTH_SOURCE
-    out.depth = 0.0;
-    for (uint s = 0; s < sourceDepth.get_num_samples(); s++) {
-        out.depth += sourceDepth.read(static_cast<uint2>(uv), s).r;
-    }
-    out.depth /= sourceDepth.get_num_samples();
-#elif SOURCES_3D
-    float2 uvnormd = uv / float2(sourceDepth.get_width(args->lod), sourceDepth.get_height(args->lod));
-    float3 coords = float3(uvnormd, (static_cast<float>(args->depthPlane) + 0.5) /
-            sourceDepth.get_depth(args->lod));
-    out.depth = sourceDepth.sample(sourceSampler, coords, level(args->lod)).r;
-#else
-    float2 uvnormd = uv / float2(sourceDepth.get_width(args->lod), sourceDepth.get_height(args->lod));
-    out.depth = sourceDepth.sample(sourceSampler, uvnormd, level(args->lod)).r;
-#endif  // MSAA_DEPTH_SOURCE
-#endif  // BLIT_DEPTH
    return out;
 }
 )";

+
+template<typename T>
+inline bool MTLSizeEqual(T a, T b) noexcept {
+    return (a.width == b.width && a.height == b.height && a.depth == b.depth);
+}
+
 MetalBlitter::MetalBlitter(MetalContext& context) noexcept : mContext(context) { }

-#define MTLSizeEqual(a, b) (a.width == b.width && a.height == b.height && a.depth == b.depth)
-
 void MetalBlitter::blit(id<MTLCommandBuffer> cmdBuffer, const BlitArgs& args, const char* label) {
-    bool blitColor = args.blitColor();
-    bool blitDepth = args.blitDepth();

    ASSERT_PRECONDITION(args.source.region.size.depth == args.destination.region.size.depth,
            "Blitting requires the source and destination regions to have the same depth.");

-    if (args.source.color && args.source.depth) {
-        MTLTextureType colorType = args.source.color.textureType;
-        MTLTextureType depthType = args.source.depth.textureType;
-
-        if (colorType == MTLTextureType2DMultisample) colorType = MTLTextureType2D;
-        if (depthType == MTLTextureType2DMultisample) depthType = MTLTextureType2D;
-
-        ASSERT_PRECONDITION(colorType == depthType,
-                "Blitting requires color and depth sources to be the same texture type.");
-    }
-
    // Determine if the blit for color or depth are eligible to use a MTLBlitCommandEncoder.
-    // blitColor and / or blitDepth are set to false upon success, to indicate that no more work is
-    // necessary for that attachment.
-    blitFastPath(cmdBuffer, blitColor, blitDepth, args, label);
-
-    if (!blitColor && !blitDepth) {
+    // blitFastPath returns true upon success.
+    // blitFastPath fails if either the format or sampleCount don't match (i.e. resolve)
+    if (blitFastPath(cmdBuffer, args, label)) {
        return;
    }

-    // If the destination is MSAA and we weren't able to use the fast path, report an error, as
-    // blitting to a MSAA texture isn't supported through the "slow path" yet.
-    const bool colorDestinationIsMultisample =
-            blitColor && args.destination.color.textureType == MTLTextureType2DMultisample;
-    const bool depthDestinationIsMultisample =
-            blitDepth && args.destination.depth.textureType == MTLTextureType2DMultisample;
-    ASSERT_PRECONDITION(!colorDestinationIsMultisample && !depthDestinationIsMultisample,
-        "Blitting between MSAA render targets with differing pixel formats and/or regions is not supported.");
+    // If we end-up here, it means that either:
+    // - we're resolving a color texture
+    // - src/dest formats didn't match, or we're scaling -- this can only happen with the legacy
+    //   blit() path and implies that the format is not depth.
+    // note: in the future we will support a fast-path resolve

-    // If the destination texture doesn't have the MTLTextureUsageRenderTarget flag, we have to blit
-    // to an intermediate texture first to perform the format conversion. Then, we can perform a
-    // "fast blit" to the final destination texture.
+    UTILS_UNUSED_IN_RELEASE
+    const bool destinationIsMultisample =
+            args.destination.texture.textureType == MTLTextureType2DMultisample;

-    id<MTLTexture> intermediateColor = nil;
-    id<MTLTexture> intermediateDepth = nil;
-    BlitArgs slowBlit = args;
-    BlitArgs finalBlit = args;
-
-    MTLRegion sourceRegionNoOffset = MTLRegionMake3D(0, 0, 0,
-            args.source.region.size.width, args.source.region.size.height,
-            args.source.region.size.depth);
-
-    if (blitColor && !(args.destination.color.usage & MTLTextureUsageRenderTarget)) {
-        intermediateColor = createIntermediateTexture(args.destination.color, args.source.region.size);
-        slowBlit.destination.color = finalBlit.source.color = intermediateColor;
-        slowBlit.destination.level = finalBlit.source.level = 0;
-        slowBlit.destination.slice = finalBlit.source.slice = 0;
-        slowBlit.destination.region = finalBlit.source.region = sourceRegionNoOffset;
-    }
-    if (blitDepth && !(args.destination.depth.usage & MTLTextureUsageRenderTarget)) {
-        intermediateDepth = createIntermediateTexture(args.destination.depth, args.source.region.size);
-        slowBlit.destination.depth = finalBlit.source.depth = intermediateDepth;
-        slowBlit.destination.level = finalBlit.source.level = 0;
-        slowBlit.destination.slice = finalBlit.source.slice = 0;
-        slowBlit.destination.region = finalBlit.source.region = sourceRegionNoOffset;
-    }
-
-    blitSlowPath(cmdBuffer, blitColor, blitDepth, slowBlit, label);
-
-    bool finalBlitColor = intermediateColor != nil;
-    bool finalBlitDepth = intermediateDepth != nil;
-    blitFastPath(cmdBuffer, finalBlitColor, finalBlitDepth, finalBlit, label);
+    assert_invariant(!destinationIsMultisample);
+    assert_invariant((args.destination.texture.usage & MTLTextureUsageRenderTarget));
+    blitSlowPath(cmdBuffer, args, label);
 }

-void MetalBlitter::blitFastPath(id<MTLCommandBuffer> cmdBuffer, bool& blitColor, bool& blitDepth,
+bool MetalBlitter::blitFastPath(id<MTLCommandBuffer> cmdBuffer,
        const BlitArgs& args, const char* label) {
-    if (blitColor) {
-        if (args.source.color.sampleCount == args.destination.color.sampleCount &&
-            args.source.color.pixelFormat == args.destination.color.pixelFormat &&
-            MTLSizeEqual(args.source.region.size, args.destination.region.size)) {

-            id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
-            blitEncoder.label = @(label);
-            [blitEncoder copyFromTexture:args.source.color
-                             sourceSlice:args.source.slice
-                             sourceLevel:args.source.level
-                            sourceOrigin:args.source.region.origin
-                              sourceSize:args.source.region.size
-                               toTexture:args.destination.color
-                        destinationSlice:args.destination.slice
-                        destinationLevel:args.destination.level
-                       destinationOrigin:args.destination.region.origin];
-            [blitEncoder endEncoding];
+    if (args.source.texture.sampleCount == args.destination.texture.sampleCount &&
+        args.source.texture.pixelFormat == args.destination.texture.pixelFormat &&
+        MTLSizeEqual(args.source.region.size, args.destination.region.size)) {

-            blitColor = false;
-        }
-    }
+        id<MTLBlitCommandEncoder> const blitEncoder = [cmdBuffer blitCommandEncoder];
+        blitEncoder.label = @(label);
+        [blitEncoder copyFromTexture:args.source.texture
+                         sourceSlice:args.source.slice
+                         sourceLevel:args.source.level
+                        sourceOrigin:args.source.region.origin
+                          sourceSize:args.source.region.size
+                           toTexture:args.destination.texture
+                    destinationSlice:args.destination.slice
+                    destinationLevel:args.destination.level
+                   destinationOrigin:args.destination.region.origin];
+        [blitEncoder endEncoding];

-    if (blitDepth) {
-        if (args.source.depth.sampleCount == args.destination.depth.sampleCount &&
-            args.source.depth.pixelFormat == args.destination.depth.pixelFormat &&
-            MTLSizeEqual(args.source.region.size, args.destination.region.size)) {
-
-            id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
-            blitEncoder.label = @(label);
-            [blitEncoder copyFromTexture:args.source.depth
-                             sourceSlice:args.source.slice
-                             sourceLevel:args.source.level
-                            sourceOrigin:args.source.region.origin
-                              sourceSize:args.source.region.size
-                               toTexture:args.destination.depth
-                        destinationSlice:args.destination.slice
-                        destinationLevel:args.destination.level
-                       destinationOrigin:args.destination.region.origin];
-            [blitEncoder endEncoding];
-
-            blitDepth = false;
-        }
+        return true;
    }
+    return false;
 }

-void MetalBlitter::blitSlowPath(id<MTLCommandBuffer> cmdBuffer, bool& blitColor, bool& blitDepth,
+void MetalBlitter::blitSlowPath(id<MTLCommandBuffer> cmdBuffer,
        const BlitArgs& args, const char* label) {
-
+    // scaling in any dimension is not allowed
+    assert_invariant(args.source.region.size.depth == args.destination.region.size.depth);
+    // we're always blitting a single plane
    uint32_t depthPlaneSource = args.source.region.origin.z;
    uint32_t depthPlaneDest = args.destination.region.origin.z;
-
-    assert_invariant(args.source.region.size.depth == args.destination.region.size.depth);
-    uint32_t depthPlaneCount = args.source.region.size.depth;
-    for (NSUInteger d = 0; d < depthPlaneCount; d++) {
-        blitDepthPlane(cmdBuffer, blitColor, blitDepth, args, depthPlaneSource++, depthPlaneDest++,
-                label);
+    for (NSUInteger d = 0; d < args.source.region.size.depth; d++) {
+        blitDepthPlane(cmdBuffer, args,
+                depthPlaneSource++, depthPlaneDest++, label);
    }
-
-    blitColor = false;
-    blitDepth = false;
 }

-void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor, bool blitDepth,
-        const BlitArgs& args, uint32_t depthPlaneSource, uint32_t depthPlaneDest,
-        const char* label) {
-    MTLRenderPassDescriptor* descriptor = [MTLRenderPassDescriptor renderPassDescriptor];
+void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, const BlitArgs& args,
+        uint32_t depthPlaneSource, uint32_t depthPlaneDest, const char* label) {

-    if (blitColor) {
-        setupColorAttachment(args, descriptor, depthPlaneDest);
-    }
+    MTLRenderPassDescriptor* const descriptor = [MTLRenderPassDescriptor renderPassDescriptor];

-    if (blitDepth) {
-        setupDepthAttachment(args, descriptor, depthPlaneDest);
-    }
+    setupAttachment(descriptor.colorAttachments[0], args, depthPlaneDest);

-    id<MTLRenderCommandEncoder> encoder = [cmdBuffer renderCommandEncoderWithDescriptor:descriptor];
+    id<MTLRenderCommandEncoder> const encoder =
+            [cmdBuffer renderCommandEncoderWithDescriptor:descriptor];
    encoder.label = @(label);

    BlitFunctionKey key;
-    key.blitColor = blitColor;
-    key.blitDepth = blitDepth;
-    key.msaaColorSource = blitColor && args.source.color.textureType == MTLTextureType2DMultisample;
-    key.msaaDepthSource = blitDepth && args.source.depth.textureType == MTLTextureType2DMultisample;
-    key.sources3D       = blitColor && args.source.color.textureType == MTLTextureType3D;
-    if (key.sources3D && blitDepth) {
-        assert_invariant(args.source.depth.textureType == MTLTextureType3D);
-    }
-    id<MTLFunction> fragmentFunction = getBlitFragmentFunction(key);
+    key.msaaColorSource = args.source.texture.textureType == MTLTextureType2DMultisample;
+    key.sources3D       = args.source.texture.textureType == MTLTextureType3D;
+    id<MTLFunction> const fragmentFunction = getBlitFragmentFunction(key);

-    MetalPipelineState pipelineState {
+    MetalPipelineState const pipelineState {
        .vertexFunction = getBlitVertexFunction(),
        .fragmentFunction = fragmentFunction,
        .vertexDescription = {},
        .colorAttachmentPixelFormat = {
-            blitColor ? args.destination.color.pixelFormat : MTLPixelFormatInvalid,
+            args.destination.texture.pixelFormat,
            MTLPixelFormatInvalid,
            MTLPixelFormatInvalid,
            MTLPixelFormatInvalid,
@@ -319,31 +203,21 @@ void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor
            MTLPixelFormatInvalid,
            MTLPixelFormatInvalid
        },
-        .depthAttachmentPixelFormat =
-                blitDepth ? args.destination.depth.pixelFormat : MTLPixelFormatInvalid,
+        .depthAttachmentPixelFormat = MTLPixelFormatInvalid,
        .sampleCount = 1,
        .blendState = {}
    };
-    id<MTLRenderPipelineState> pipeline = mContext.pipelineStateCache.getOrCreateState(pipelineState);
+    id<MTLRenderPipelineState> const pipeline =
+            mContext.pipelineStateCache.getOrCreateState(pipelineState);
    [encoder setRenderPipelineState:pipeline];

    // For texture arrays, create a view of the texture at the given slice (layer).
-    id<MTLTexture> srcTextureColor = args.source.color;
+
+    id<MTLTexture> srcTextureColor = args.source.texture;
    if (srcTextureColor && srcTextureColor.textureType == MTLTextureType2DArray) {
        srcTextureColor = createTextureViewWithSingleSlice(srcTextureColor, args.source.slice);
    }
-    id<MTLTexture> srcTextureDepth = args.source.depth;
-    if (srcTextureDepth && srcTextureDepth.textureType == MTLTextureType2DArray) {
-        srcTextureDepth = createTextureViewWithSingleSlice(srcTextureDepth, args.source.slice);
-    }
-
-    if (blitColor) {
-        [encoder setFragmentTexture:srcTextureColor atIndex:0];
-    }
-
-    if (blitDepth) {
-        [encoder setFragmentTexture:srcTextureDepth atIndex:1];
-    }
+    [encoder setFragmentTexture:srcTextureColor atIndex:0];

    SamplerMinFilter filterMin = SamplerMinFilter::NEAREST_MIPMAP_NEAREST;
    if (args.filter == SamplerMagFilter::NEAREST) {
@@ -352,13 +226,13 @@ void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor
        filterMin = SamplerMinFilter::LINEAR_MIPMAP_NEAREST;
    }

-    SamplerState s {
+    SamplerState const s {
        .samplerParams = {
            .filterMag = args.filter,
            .filterMin = filterMin
        }
    };
-    id<MTLSamplerState> sampler = mContext.samplerStateCache.getOrCreateState(s);
+    id<MTLSamplerState> const sampler = mContext.samplerStateCache.getOrCreateState(s);
    [encoder setFragmentSamplerState:sampler atIndex:0];

    MTLViewport viewport;
@@ -370,11 +244,11 @@ void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor
    viewport.zfar = 1.0;
    [encoder setViewport:viewport];

-    DepthStencilState depthStencilState {
+    DepthStencilState const depthStencilState {
        .depthCompare = MTLCompareFunctionAlways,
-        .depthWriteEnabled = blitDepth
+        .depthWriteEnabled = false
    };
-    id<MTLDepthStencilState> depthStencil =
+    id<MTLDepthStencilState> const depthStencil =
            mContext.depthStencilStateCache.getOrCreateState(depthStencilState);
    [encoder setDepthStencilState:depthStencil];

@@ -410,80 +284,42 @@ void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor
    [encoder endEncoding];
 }

-id<MTLTexture> MetalBlitter::createIntermediateTexture(id<MTLTexture> t, MTLSize size) {
-    MTLTextureDescriptor* descriptor = [MTLTextureDescriptor new];
-    descriptor.textureType = size.depth == 1 ? MTLTextureType2D : MTLTextureType3D;
-    descriptor.pixelFormat = t.pixelFormat;
-    descriptor.width = size.width;
-    descriptor.height = size.height;
-    descriptor.depth = size.depth;
-    descriptor.usage = t.usage & MTLTextureUsageRenderTarget;
-    return [mContext.device newTextureWithDescriptor:descriptor];
-}
-
 void MetalBlitter::shutdown() noexcept {
    mBlitFunctions.clear();
    mVertexFunction = nil;
 }

-void MetalBlitter::setupColorAttachment(const BlitArgs& args,
-        MTLRenderPassDescriptor* descriptor, uint32_t depthPlane) {
-    descriptor.colorAttachments[0].texture = args.destination.color;
-    descriptor.colorAttachments[0].level = args.destination.level;
-    descriptor.colorAttachments[0].slice = args.destination.slice;
-    descriptor.colorAttachments[0].depthPlane = depthPlane;
-
-    descriptor.colorAttachments[0].loadAction = MTLLoadActionLoad;
+void MetalBlitter::setupAttachment(MTLRenderPassAttachmentDescriptor* descriptor,
+        const BlitArgs& args, uint32_t depthPlane) {
+    descriptor.texture = args.destination.texture;
+    descriptor.level = args.destination.level;
+    descriptor.slice = args.destination.slice;
+    descriptor.depthPlane = depthPlane;
+    descriptor.loadAction = MTLLoadActionLoad;
    // We don't need to load the contents of the attachment if we're blitting over all of it.
-    if (args.colorDestinationIsFullAttachment()) {
-        descriptor.colorAttachments[0].loadAction = MTLLoadActionDontCare;
+    if (args.destinationIsFullAttachment()) {
+        descriptor.loadAction = MTLLoadActionDontCare;
    }
-
-    descriptor.colorAttachments[0].storeAction = MTLStoreActionStore;
+    descriptor.storeAction = MTLStoreActionStore;
 }

-void MetalBlitter::setupDepthAttachment(const BlitArgs& args, MTLRenderPassDescriptor* descriptor,
-        uint32_t depthPlane) {
-    descriptor.depthAttachment.texture = args.destination.depth;
-    descriptor.depthAttachment.level = args.destination.level;
-    descriptor.depthAttachment.slice = args.destination.slice;
-    descriptor.depthAttachment.depthPlane = depthPlane;
-
-    descriptor.depthAttachment.loadAction = MTLLoadActionLoad;
-    // We don't need to load the contents of the attachment if we're blitting over all of it.
-    if (args.depthDestinationIsFullAttachment()) {
-        descriptor.depthAttachment.loadAction = MTLLoadActionDontCare;
-    }
-
-    descriptor.depthAttachment.storeAction = MTLStoreActionStore;
-}
-
-id<MTLFunction> MetalBlitter::compileFragmentFunction(BlitFunctionKey key) {
-    MTLCompileOptions* options = [MTLCompileOptions new];
-    NSMutableDictionary* macros = [NSMutableDictionary dictionary];
-    if (key.blitColor) {
-        macros[@"BLIT_COLOR"] = @"1";
-    }
-    if (key.blitDepth) {
-        macros[@"BLIT_DEPTH"] = @"1";
-    }
+id<MTLFunction> MetalBlitter::compileFragmentFunction(BlitFunctionKey key) const {
+    MTLCompileOptions* const options = [MTLCompileOptions new];
+    NSMutableDictionary* const macros = [NSMutableDictionary dictionary];
    if (key.msaaColorSource) {
        macros[@"MSAA_COLOR_SOURCE"] = @"1";
    }
-    if (key.msaaDepthSource) {
-        macros[@"MSAA_DEPTH_SOURCE"] = @"1";
-    }
    if (key.sources3D) {
        macros[@"SOURCES_3D"] = @"1";
    }
    options.preprocessorMacros = macros;
-    NSString* objcSource = [NSString stringWithCString:functionLibrary
-                                              encoding:NSUTF8StringEncoding];
+    NSString* const objcSource = [NSString stringWithCString:functionLibrary
+                                                    encoding:NSUTF8StringEncoding];
    NSError* error = nil;
-    id<MTLLibrary> library = [mContext.device newLibraryWithSource:objcSource
-                                                            options:options
-                                                              error:&error];
-    id<MTLFunction> function = [library newFunctionWithName:@"blitterFrag"];
+    id <MTLLibrary> const library = [mContext.device newLibraryWithSource:objcSource
+                                                                  options:options
+                                                                    error:&error];
+    id <MTLFunction> const function = [library newFunctionWithName:@"blitterFrag"];

    if (!library || !function) {
        if (error) {
@@ -501,13 +337,14 @@ id<MTLFunction> MetalBlitter::getBlitVertexFunction() {
        return mVertexFunction;
    }

-    NSString* objcSource = [NSString stringWithCString:functionLibrary
-                                              encoding:NSUTF8StringEncoding];
+    NSString* const objcSource = [NSString stringWithCString:functionLibrary
+                                                    encoding:NSUTF8StringEncoding];
    NSError* error = nil;
-    id<MTLLibrary> library = [mContext.device newLibraryWithSource:objcSource
-                                                           options:nil
-                                                             error:&error];
-    id<MTLFunction> function = [library newFunctionWithName:@"blitterVertex"];
+    id <MTLLibrary> const library = [mContext.device newLibraryWithSource:objcSource
+                                                                  options:nil
+                                                                    error:&error];
+
+    id<MTLFunction> const function = [library newFunctionWithName:@"blitterVertex"];

    if (!library || !function) {
        if (error) {
@@ -535,5 +372,5 @@ id<MTLFunction> MetalBlitter::getBlitFragmentFunction(BlitFunctionKey key) {
    return function;
 }

-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
+
@@ -18,7 +18,7 @@
 #define TNT_FILAMENT_DRIVER_METALBUFFER_H

 #include "MetalContext.h"
-#include "MetalBufferPool.h"
+#include "MetalPlatform.h"

 #include <backend/DriverEnums.h>

@@ -28,9 +28,125 @@

 #include <utility>
 #include <memory>
+#include <atomic>
+#include <chrono>

 namespace filament::backend {

+class ScopedAllocationTimer {
+public:
+    ScopedAllocationTimer(const char* name) : mBeginning(clock_t::now()), mName(name) {}
+    ~ScopedAllocationTimer() {
+        using namespace std::literals::chrono_literals;
+        static constexpr std::chrono::seconds LONG_TIME_THRESHOLD = 10s;
+
+        auto end = clock_t::now();
+        std::chrono::duration<double, std::micro> allocationTimeMicroseconds = end - mBeginning;
+
+        if (UTILS_UNLIKELY(allocationTimeMicroseconds > LONG_TIME_THRESHOLD)) {
+            if (platform && platform->hasDebugUpdateStatFunc()) {
+                char buffer[64];
+                snprintf(buffer, sizeof(buffer), "filament.metal.long_buffer_allocation_time.%s",
+                        mName);
+                platform->debugUpdateStat(
+                        buffer, static_cast<uint64_t>(allocationTimeMicroseconds.count()));
+            }
+        }
+    }
+
+    static void setPlatform(MetalPlatform* p) { platform = p; }
+
+private:
+    typedef std::chrono::steady_clock clock_t;
+
+    static MetalPlatform* platform;
+
+    std::chrono::time_point<clock_t> mBeginning;
+    const char* mName;
+};
+
+#ifndef FILAMENT_METAL_BUFFER_TRACKING
+#define FILAMENT_METAL_BUFFER_TRACKING 0
+#endif
+
+class MetalBufferTracking {
+public:
+    static constexpr size_t EXCESS_BUFFER_COUNT = 30000;
+
+    enum class Type {
+        NONE = 0,
+        GENERIC = 1,
+        RING = 2,
+        STAGING = 3,
+    };
+    static constexpr size_t TypeCount = 3;
+
+    static constexpr auto toIndex(Type t) {
+        assert_invariant(t != Type::NONE);
+        switch (t) {
+            case Type::NONE:
+            case Type::GENERIC:
+                return 0;
+            case Type::RING:
+                return 1;
+            case Type::STAGING:
+                return 2;
+        }
+    }
+
+#if FILAMENT_METAL_BUFFER_TRACKING
+    static void initialize() {
+        static dispatch_once_t onceToken;
+        dispatch_once(&onceToken, ^{
+            for (size_t i = 0; i < TypeCount; i++) {
+                aliveBuffers[i] = [NSHashTable weakObjectsHashTable];
+            }
+        });
+    }
+
+    static void setPlatform(MetalPlatform* p) { platform = p; }
+
+    static void track(id<MTLBuffer> buffer, Type type) {
+        assert_invariant(type != Type::NONE);
+        if (UTILS_UNLIKELY(getAliveBuffers() >= EXCESS_BUFFER_COUNT)) {
+            if (platform && platform->hasDebugUpdateStatFunc()) {
+                platform->debugUpdateStat("filament.metal.excess_buffers_allocated",
+                        MetalBufferTracking::getAliveBuffers());
+            }
+        }
+        [aliveBuffers[toIndex(type)] addObject:buffer];
+    }
+
+    static uint64_t getAliveBuffers() {
+        uint64_t sum = 0;
+        for (size_t i = 1; i < TypeCount; i++) {
+            sum += getAliveBuffers(static_cast<Type>(i));
+        }
+        return sum;
+    }
+
+    static uint64_t getAliveBuffers(Type type) {
+        assert_invariant(type != Type::NONE);
+        NSHashTable* hashTable = aliveBuffers[toIndex(type)];
+        // Caution! We can't simply use hashTable.count here, which is inaccurate.
+        // See http://cocoamine.net/blog/2013/12/13/nsmaptable-and-zeroing-weak-references/
+        return hashTable.objectEnumerator.allObjects.count;
+    }
+#else
+    static void initialize() {}
+    static void setPlatform(MetalPlatform* p) {}
+    static id<MTLBuffer> track(id<MTLBuffer> buffer, Type type) { return buffer; }
+    static uint64_t getAliveBuffers() { return 0; }
+    static uint64_t getAliveBuffers(Type type) { return 0; }
+#endif
+
+private:
+#if FILAMENT_METAL_BUFFER_TRACKING
+    static std::array<NSHashTable<id<MTLBuffer>>*, TypeCount> aliveBuffers;
+    static MetalPlatform* platform;
+#endif
+};
+
 class MetalBuffer {
 public:

@@ -82,7 +198,7 @@ public:

 private:

-    id<MTLBuffer> mBuffer = nil;
+    id<MTLBuffer> mBuffer;
    size_t mBufferSize = 0;
    void* mCpuBuffer = nullptr;
    MetalContext& mContext;
@@ -131,7 +247,11 @@ public:
          mBufferOptions(options),
          mSlotSizeBytes(computeSlotSize(layout)),
          mSlotCount(slotCount) {
-        mBuffer = [device newBufferWithLength:mSlotSizeBytes * mSlotCount options:mBufferOptions];
+        {
+            ScopedAllocationTimer timer("ring");
+            mBuffer = [device newBufferWithLength:mSlotSizeBytes * mSlotCount options:mBufferOptions];
+        }
+        MetalBufferTracking::track(mBuffer, MetalBufferTracking::Type::RING);
        assert_invariant(mBuffer);
    }

@@ -149,9 +269,13 @@ public:
            // If we already have an aux buffer, it will get freed here, unless it has been retained
            // by a MTLCommandBuffer. In that case, it will be freed when the command buffer
            // finishes executing.
-            mAuxBuffer = [mDevice newBufferWithLength:mSlotSizeBytes options:mBufferOptions];
+            {
+                ScopedAllocationTimer timer("ring");
+                mAuxBuffer = [mDevice newBufferWithLength:mSlotSizeBytes options:mBufferOptions];
+            }
+            MetalBufferTracking::track(mAuxBuffer, MetalBufferTracking::Type::RING);
            assert_invariant(mAuxBuffer);
-            return {mAuxBuffer, 0};
+            return { mAuxBuffer, 0 };
        }
        mCurrentSlot = (mCurrentSlot + 1) % mSlotCount;
        mOccupiedSlots->fetch_add(1, std::memory_order_relaxed);
@@ -15,12 +15,21 @@
 */

 #include "MetalBuffer.h"
+#include "MetalBufferPool.h"

 #include "MetalContext.h"

 namespace filament {
 namespace backend {

+MetalPlatform* ScopedAllocationTimer::platform = nullptr;
+
+#if FILAMENT_METAL_BUFFER_TRACKING
+std::array<NSHashTable<id<MTLBuffer>>*, MetalBufferTracking::TypeCount>
+        MetalBufferTracking::aliveBuffers;
+MetalPlatform* MetalBufferTracking::platform = nullptr;
+#endif
+
 MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType, BufferUsage usage,
        size_t size, bool forceGpuBuffer) : mBufferSize(size), mContext(context) {
    // If the buffer is less than 4K in size and is updated frequently, we don't use an explicit
@@ -34,7 +43,11 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType,
    }

    // Otherwise, we allocate a private GPU buffer.
-    mBuffer = [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate];
+    {
+        ScopedAllocationTimer timer("generic");
+        mBuffer = [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate];
+    }
+    MetalBufferTracking::track(mBuffer, MetalBufferTracking::Type::GENERIC);
    ASSERT_POSTCONDITION(mBuffer, "Could not allocate Metal buffer of size %zu.", size);
 }

@@ -19,6 +19,8 @@

 #include <Metal/Metal.h>

+#include "MetalBuffer.h"
+
 #include <map>
 #include <mutex>
 #include <unordered_set>
@@ -73,7 +75,10 @@ private:
    std::unordered_set<MetalBufferPoolEntry const*> mUsedStages;

    // Store the current "time" (really just a frame count) and LRU eviction parameters.
-    uint64_t mCurrentFrame = 0;
+    // An atomic is necessary as mCurrentFrame is incremented in gc() (called on
+    // the driver thread) and read from acquireBuffer() and releaseBuffer(),
+    // which may be called on non-driver threads.
+    std::atomic<uint64_t> mCurrentFrame = 0;
    static constexpr uint32_t TIME_BEFORE_EVICTION = 10;
 };

@@ -19,6 +19,7 @@
 #include "MetalContext.h"

 #include <utils/Panic.h>
+#include <utils/Log.h>
 #include <utils/trap.h>

 #include <thread>
@@ -41,15 +42,20 @@ MetalBufferPoolEntry const* MetalBufferPool::acquireBuffer(size_t numBytes) {
    }

    // We were not able to find a sufficiently large stage, so create a new one.
-    id<MTLBuffer> buffer = [mContext.device newBufferWithLength:numBytes
-                                                        options:MTLResourceStorageModeShared];
+    id<MTLBuffer> buffer = nil;
+    {
+        ScopedAllocationTimer timer("staging");
+        buffer = [mContext.device newBufferWithLength:numBytes
+                                              options:MTLResourceStorageModeShared];
+    }
+    MetalBufferTracking::track(buffer, MetalBufferTracking::Type::STAGING);
    ASSERT_POSTCONDITION(buffer, "Could not allocate Metal staging buffer of size %zu.", numBytes);
-    MetalBufferPoolEntry* stage = new MetalBufferPoolEntry({
+    MetalBufferPoolEntry* stage = new MetalBufferPoolEntry {
        .buffer = buffer,
        .capacity = numBytes,
        .lastAccessed = mCurrentFrame,
        .referenceCount = 1
-    });
+    };
    mUsedStages.insert(stage);

    return stage;
@@ -99,6 +99,7 @@ struct MetalContext {
    std::array<BufferState, MAX_SSBO_COUNT> ssboState;
    CullModeStateTracker cullModeState;
    WindingStateTracker windingState;
+    Handle<HwRenderPrimitive> currentRenderPrimitive;

    // State caches.
    DepthStencilStateCache depthStencilStateCache;
@@ -142,7 +143,10 @@ struct MetalContext {
    // Fences, only supported on macOS 10.14 and iOS 12 and above.
    API_AVAILABLE(macos(10.14), ios(12.0))
    MTLSharedEventListener* eventListener = nil;
-    uint64_t signalId = 1;
+    // signalId is incremented in the MetalFence constructor, which is called on
+    // both the driver (MetalTimerQueryFence::beginTimeElapsedQuery) and main
+    // threads (in createFenceS), so an atomic is necessary.
+    std::atomic<uint64_t> signalId = 1;

    MetalTimerQueryInterface* timerQueryImpl;

--- a/Show More
+++ b/Show More