Merge branch 'rc/1.51.3' into release

BUGS=[331610785]

.dir-locals.el

@@ -0,0 +1,7 @@
+;;; Directory Local Variables            -*- no-byte-compile: t -*-
+;;; For more information see (info "(emacs) Directory Variables")
+
+((c++-mode . ((c-file-style . "filament")
+              (apheleia-inhibit . t)))
+ (c-mode . ((c-file-style . "filament")
+            (apheleia-inhibit . t))))

.github/workflows/android-continuous.yml

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

.github/workflows/cocopods-deploy.yml

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

.github/workflows/ios-continuous.yml

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

.github/workflows/mac-continuous.yml

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

.github/workflows/npm-deploy.yml

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

.github/workflows/presubmit.yml

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

.github/workflows/release.yml

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

.github/workflows/web-continuous.yml

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

.gitignore

@@ -16,3 +16,5 @@ settings.json
 test*.png
 test*.json
 results
+/compile_commands.json
+/.cache

BUILDING.md

@@ -56,9 +56,11 @@ To trigger both incremental debug and release builds:
 ./build.sh debug release
 ```
 
+If build fails for some reasons, it may leave the `out/` directory in a broken state. You can
+force a clean build by adding the `-c` flag in that case.
+
 To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag.
-You can force a clean build by adding the `-c` flag. The script offers more features described
-by executing `build.sh -h`.
+The script offers more features described by executing `build.sh -h`.
 
 ### Filament-specific CMake Options
 
@@ -172,12 +174,12 @@ See [ios/samples/README.md](./ios/samples/README.md) for more information.
 
 ### Windows
 
-#### Building on Windows with Visual Studio 2019
+#### Building on Windows with Visual Studio 2019 or later
 
 Install the following components:
 
-- [Visual Studio 2019](https://www.visualstudio.com/downloads)
-- [Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
+- [Visual Studio 2019 or later](https://www.visualstudio.com/downloads)
+- [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)
 - [Python 3.7](https://www.python.org/ftp/python/3.7.0/python-3.7.0.exe)
 - [CMake 3.14 or later](https://github.com/Kitware/CMake/releases/download/v3.14.7/cmake-3.14.7-win64-x64.msi)
 

CMakeLists.txt

@@ -41,6 +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."
 )
@@ -65,6 +71,9 @@ set(FILAMENT_METAL_HANDLE_ARENA_SIZE_IN_MB "8" CACHE STRING
     "Size of the Metal handle arena, default 8."
 )
 
+# Enable exceptions by default in spirv-cross.
+set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS OFF)
+
 # ==================================================================================================
 # CMake policies
 # ==================================================================================================
@@ -225,6 +234,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()
 
@@ -337,6 +361,7 @@ endif()
 
 if (CYGWIN)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-exceptions -fno-rtti")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
 endif()
 
 if (MSVC)
@@ -373,6 +398,7 @@ endif()
 # saved by -fno-exception and 10 KiB saved by -fno-rtti).
 if (ANDROID OR IOS OR WEBGL)
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fno-exceptions -fno-rtti")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
 
     if (ANDROID OR WEBGL)
         # Omitting unwind info prevents the generation of readable stack traces in crash reports on iOS
@@ -384,6 +410,7 @@ endif()
 # std::visit, which is not supported on iOS 11.0 when exceptions are enabled.
 if (IOS)
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fno-exceptions")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
 endif()
 
 # With WebGL, we disable RTTI even for debug builds because we pass emscripten::val back and forth
@@ -403,7 +430,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()
@@ -500,6 +533,21 @@ 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 ()
+
 # ==================================================================================================
 # Material compilation flags
 # ==================================================================================================
@@ -523,6 +571,11 @@ if (FILAMENT_SUPPORTS_METAL)
     set(MATC_API_FLAGS ${MATC_API_FLAGS} -a metal)
 endif()
 
+# Disable ESSL 1.0 code generation.
+if (NOT FILAMENT_ENABLE_FEATURE_LEVEL_0)
+    set(MATC_API_FLAGS ${MATC_API_FLAGS} -1)
+endif()
+
 # Enable debug info (preserves names in SPIR-V)
 if (FILAMENT_ENABLE_MATDBG)
     set(MATC_OPT_FLAGS ${MATC_OPT_FLAGS} -d)
@@ -598,9 +651,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()
@@ -670,7 +723,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()
 
@@ -685,7 +738,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)
@@ -713,6 +765,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.
@@ -730,6 +785,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)

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.45.0'
+    implementation 'com.google.android.filament:filament-android:1.51.3'
 }
 ```
 
@@ -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.45.0'
+pod 'Filament', '~> 1.51.3'
 ```
 
 ### Snapshots

RELEASE_GUIDE.md

@@ -128,3 +128,15 @@ Navigate to [Filament's release
 workflow](https://github.com/google/filament/actions/workflows/release.yml). Hit the _Run workflow_
 dropdown. Modify _Platform to build_ and _Release tag to build_, then hit _Run workflow_. This will
 initiate a new release run.
+
+## 11. Kick off the npm and CocoaPods release jobs
+
+Navigate to [Filament's npm deploy
+workflow](https://github.com/google/filament/actions/workflows/npm-deploy.yml).
+Hit the _Run workflow_ dropdown. Modify _Release tag to deploy_ to the tag corresponding to this
+release (for example, v1.42.2).
+
+Navigate to [Filament's CocoaPods deploy
+workflow](https://github.com/google/filament/actions/workflows/cocopods-deploy.yml).
+Hit the _Run workflow_ dropdown. Modify _Release tag to deploy_ to the tag corresponding to this
+release (for example, v1.42.2).

RELEASE_NOTES.md

@@ -7,12 +7,104 @@ 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.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
+- matc: Support optimizations for ESSL 1.0 code [⚠️ **Recompile materials**]
+
+## v1.47.0
+
+- engine: Support up to 4 side-by-side stereoscopic eyes, configurable at Engine creation time. See
+  `Engine::Config::stereoscopicEyeCount`. [⚠️ **Recompile Materials**]
+
+## v1.46.0
+
+- engine: Allow instantiating Engine at a given feature level via `Engine::Builder::featureLevel`
+- matc: Enable `GL_OES_standard_derivatives` extension in ESSL 1.0 shaders
+- matc: Fix code generation of double sided and masked materials in ESSL 1.0 shaders
+- filagui: Add support for feature level 0
+- matc: Add support for post-process materials in feature level 0
+- engine: Add `Material::getFeatureLevel()`
+- engine: Add missing `Material::getReflectionMode()` method in Java
+- engine: Support basic usage of post-processing materials on feature level 0
+- engine: Fix critical GLES 2.0 bugs
+- engine: Add `FILAMENT_ENABLE_FEATURE_LEVEL_0` build-time option optionally allow building Filament
+  without FL0 support.
+
+## v1.45.1
+
+- engine: Added parameter for configuring JobSystem thread count
+- engine: In Java, introduce Engine.Builder
+- gltfio: fix ubershader index for transmission&volume material
+- engine: New tone mapper: `AgXTonemapper`.
+- matinfo: Add support for viewing ESSL 1.0 shaders
+- engine: Add `Renderer::getClearOptions()` [b/243846268]
+- engine: Fix stable shadows (again) when an IBL rotation is used
+
 ## v1.45.0
 
 - materials: fix alpha masked materials when MSAA is turned on [⚠️ **Recompile materials**]
 - materials: better support materials with custom depth [**Recompile Materials**]
 - engine: fade shadows at shadowFar distance instead of hard cutoff [⚠️ **New Material Version**]
-- engine: Add support for stencil buffer when post-processing is disabled (Metal backend only).
 
 ## v1.44.0
 

android/build.gradle

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

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

@@ -25,15 +25,8 @@
 using namespace filament;
 using namespace utils;
 
-extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_Engine_nCreateEngine(JNIEnv*, jclass, jlong backend,
-        jlong sharedContext) {
-    return (jlong) Engine::create((Engine::Backend) backend, nullptr, (void*) sharedContext);
-}
-
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_Engine_nDestroyEngine(JNIEnv*, jclass,
-        jlong nativeEngine) {
+Java_com_google_android_filament_Engine_nDestroyEngine(JNIEnv*, jclass, jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
     Engine::destroy(&engine);
 }
@@ -391,6 +384,20 @@ Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
     engine->flushAndWait();
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nFlush(JNIEnv*, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    engine->flush();
+}
+
+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
@@ -435,6 +442,13 @@ Java_com_google_android_filament_Engine_nIsAutomaticInstancingEnabled(JNIEnv*, j
     return (jboolean)engine->isAutomaticInstancingEnabled();
 }
 
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_nGetMaxStereoscopicEyes(JNIEnv*, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jlong) engine->getMaxStereoscopicEyes();
+}
+
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Engine_nGetSupportedFeatureLevel(JNIEnv *, jclass,
         jlong nativeEngine) {
@@ -454,4 +468,73 @@ Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
         jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
     return (jint)engine->getActiveFeatureLevel();
-}
+}
+
+extern "C" JNIEXPORT jlong JNICALL Java_com_google_android_filament_Engine_nCreateBuilder(JNIEnv*,
+        jclass) {
+    Engine::Builder* builder = new Engine::Builder{};
+    return (jlong) builder;
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nDestroyBuilder(JNIEnv*,
+        jclass, jlong nativeBuilder) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    delete builder;
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderBackend(
+        JNIEnv*, jclass, jlong nativeBuilder, jlong backend) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->backend((Engine::Backend) backend);
+}
+
+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 textureUseAfterFreePoolSize, jboolean disableParallelShaderCompile,
+        jint stereoscopicType, jlong stereoscopicEyeCount,
+        jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
+        jboolean disableHandleUseAfterFreeCheck) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    Engine::Config config = {
+            .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
+            .perRenderPassArenaSizeMB = (uint32_t) perRenderPassArenaSizeMB,
+            .driverHandleArenaSizeMB = (uint32_t) driverHandleArenaSizeMB,
+            .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,
+    };
+    builder->config(&config);
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderFeatureLevel(
+        JNIEnv*, jclass, jlong nativeBuilder, jint ordinal) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->featureLevel((Engine::FeatureLevel)ordinal);
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderSharedContext(
+        JNIEnv*, jclass, jlong nativeBuilder, jlong sharedContext) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    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;
+    return (jlong) builder->build();
+}

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

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

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

@@ -19,6 +19,7 @@
 #include <filament/Material.h>
 
 #include "common/NioUtils.h"
+#include "common/CallbackUtils.h"
 
 using namespace filament;
 
@@ -105,6 +106,22 @@ Java_com_google_android_filament_Material_nGetRefractionType(JNIEnv*, jclass,
     return (jint) material->getRefractionType();
 }
 
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetReflectionMode(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getReflectionMode();
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetFeatureLevel(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getFeatureLevel();
+}
+
 extern "C"
 JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Material_nGetVertexDomain(JNIEnv*, jclass,
@@ -255,3 +272,17 @@ Java_com_google_android_filament_Material_nHasParameter(JNIEnv* env, jclass,
     env->ReleaseStringUTFChars(name_, name);
     return (jboolean) hasParameter;
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Material_nCompile(JNIEnv *env, jclass clazz,
+        jlong nativeMaterial, jint priority, jint variants, jobject handler, jobject runnable) {
+    Material* material = (Material*) nativeMaterial;
+    JniCallback* jniCallback = JniCallback::make(env, handler, runnable);
+    material->compile(
+            (Material::CompilerPriorityQueue) priority,
+            (UserVariantFilterBit) variants,
+            jniCallback->getHandler(), [jniCallback](Material*){
+                JniCallback::postToJavaAndDestroy(jniCallback);
+            });
+}

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

@@ -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);
 }

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

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

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

@@ -71,6 +71,13 @@ Java_com_google_android_filament_Scene_nRemoveEntities(JNIEnv *env, jclass type,
     env->ReleaseIntArrayElements(entities, (jint*) nativeEntities, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Scene_nGetEntityCount(JNIEnv *env, jclass type,
+        jlong nativeScene) {
+    Scene* scene = (Scene*) nativeScene;
+    return (jint) scene->getEntityCount();
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Scene_nGetRenderableCount(JNIEnv *env, jclass type,
         jlong nativeScene) {
@@ -91,3 +98,22 @@ Java_com_google_android_filament_Scene_nHasEntity(JNIEnv *env, jclass type, jlon
     Entity entity = Entity::import(entityId);
     return (jboolean) scene->hasEntity(entity);
 }
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Scene_nGetEntities(JNIEnv *env, jclass ,
+        jlong nativeScene, jintArray outArray, jint length) {
+    Scene const* const scene = (Scene*) nativeScene;
+    if (length < scene->getEntityCount()) {
+        // should not happen because we already checked on the java side
+        return JNI_FALSE;
+    }
+    jint *out = (jint *) env->GetIntArrayElements(outArray, nullptr);
+    scene->forEach([out, length, i = 0](Entity entity)mutable {
+        if (i < length) { // this is just paranoia here
+            out[i++] = (jint) entity.getId();
+        }
+    });
+    env->ReleaseIntArrayElements(outArray, (jint*) out, 0);
+    return JNI_TRUE;
+}

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

@@ -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);
 }

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

@@ -47,6 +47,16 @@ 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));
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_ToneMapper_nCreateGenericToneMapper(JNIEnv*, jclass,
         jfloat contrast, jfloat midGrayIn, jfloat midGrayOut, jfloat hdrMax) {

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

@@ -480,6 +480,17 @@ Java_com_google_android_filament_View_nIsStencilBufferEnabled(JNIEnv *, jclass,
     return view->isStencilBufferEnabled();
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetStereoscopicOptions(JNIEnv *, jclass, jlong nativeView,
+        jboolean enabled) {
+    View* view = (View*) nativeView;
+    View::StereoscopicOptions options {
+        .enabled = (bool) enabled
+    };
+    view->setStereoscopicOptions(options);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,

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

@@ -111,6 +111,8 @@ public class Engine {
 
     private long mNativeObject;
 
+    private Config mConfig;
+
     @NonNull private final TransformManager mTransformManager;
     @NonNull private final LightManager mLightManager;
     @NonNull private final RenderableManager mRenderableManager;
@@ -150,16 +152,291 @@ public class Engine {
         FEATURE_LEVEL_0,
         /** OpenGL ES 3.0 features (default) */
         FEATURE_LEVEL_1,
+        /** OpenGL ES 3.1 features + 16 textures units + cubemap arrays */
+        FEATURE_LEVEL_2,
         /** OpenGL ES 3.1 features + 31 textures units + cubemap arrays */
-        FEATURE_LEVEL_2
+        FEATURE_LEVEL_3,
     };
 
-    private Engine(long nativeEngine) {
+    /**
+     * 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.
+     */
+    public static class Builder {
+        @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
+        private final BuilderFinalizer mFinalizer;
+        private final long mNativeBuilder;
+        private Config mConfig;
+
+        public Builder() {
+            mNativeBuilder = nCreateBuilder();
+            mFinalizer = new BuilderFinalizer(mNativeBuilder);
+        }
+
+        /**
+         * Sets the {@link Backend} for the Engine.
+         *
+         * @param backend Driver backend to use
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder backend(Backend backend) {
+            nSetBuilderBackend(mNativeBuilder, backend.ordinal());
+            return this;
+        }
+
+        /**
+         * Sets a sharedContext for the Engine.
+         *
+         * @param sharedContext  A platform-dependant OpenGL context used as a shared context
+         *                       when creating filament's internal context. On Android this parameter
+         *                       <b>must be</b> an instance of {@link android.opengl.EGLContext}.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder sharedContext(Object sharedContext) {
+            if (Platform.get().validateSharedContext(sharedContext)) {
+                nSetBuilderSharedContext(mNativeBuilder,
+                        Platform.get().getSharedContextNativeHandle(sharedContext));
+                return this;
+            }
+            throw new IllegalArgumentException("Invalid shared context " + sharedContext);
+        }
+
+        /**
+         * Configure the Engine with custom parameters.
+         *
+         * @param config A {@link Config} object
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder config(Config config) {
+            mConfig = config;
+            nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
+                    config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
+                    config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
+                    config.jobSystemThreadCount,
+                    config.textureUseAfterFreePoolSize, config.disableParallelShaderCompile,
+                    config.stereoscopicType.ordinal(), config.stereoscopicEyeCount,
+                    config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
+                    config.disableHandleUseAfterFreeCheck);
+            return this;
+        }
+
+        /**
+         * Sets the initial featureLevel for the Engine.
+         *
+         * @param featureLevel The feature level at which initialize Filament.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder featureLevel(FeatureLevel featureLevel) {
+            nSetBuilderFeatureLevel(mNativeBuilder, featureLevel.ordinal());
+            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
+         *
+         * @return A newly created <code>Engine</code>, or <code>null</code> if the GPU driver couldn't
+         *         be initialized, for instance if it doesn't support the right version of OpenGL or
+         *         OpenGL ES.
+         *
+         * @exception IllegalStateException can be thrown if there isn't enough memory to
+         * allocate the command buffer.
+         */
+        public Engine build() {
+            long nativeEngine = nBuilderBuild(mNativeBuilder);
+            if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
+            return new Engine(nativeEngine, mConfig);
+        }
+
+        private static class BuilderFinalizer {
+            private final long mNativeObject;
+
+            BuilderFinalizer(long nativeObject) {
+                mNativeObject = nativeObject;
+            }
+
+            @Override
+            public void finalize() {
+                try {
+                    super.finalize();
+                } catch (Throwable t) { // Ignore
+                } finally {
+                    nDestroyBuilder(mNativeObject);
+                }
+            }
+        }
+    }
+
+    /**
+     * Parameters for customizing the initialization of {@link Engine}.
+     */
+    public static class Config {
+
+        // #defines in Engine.h
+        private static final long FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB = 3;
+        private static final long FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB = 2;
+        private static final long FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB = 1;
+        private static final long FILAMENT_COMMAND_BUFFER_SIZE_IN_MB =
+                FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB * 3;
+
+        /**
+         * Size in MiB of the low-level command buffer arena.
+         *
+         * Each new command buffer is allocated from here. If this buffer is too small the program
+         * might terminate or rendering errors might occur.
+         *
+         * This is typically set to minCommandBufferSizeMB * 3, so that up to 3 frames can be
+         * batched-up at once.
+         *
+         * This value affects the application's memory usage.
+         */
+        public long commandBufferSizeMB = FILAMENT_COMMAND_BUFFER_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the per-frame data arena.
+         *
+         * This is the main arena used for allocations when preparing a frame.
+         * e.g.: Froxel data and high-level commands are allocated from this arena.
+         *
+         * If this size is too small, the program will abort on debug builds and have undefined
+         * behavior otherwise.
+         *
+         * This value affects the application's memory usage.
+         */
+        public long perRenderPassArenaSizeMB = FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the backend's handle arena.
+         *
+         * Backends will fallback to slower heap-based allocations when running out of space and
+         * log this condition.
+         *
+         * If 0, then the default value for the given platform is used
+         *
+         * This value affects the application's memory usage.
+         */
+        public long driverHandleArenaSizeMB = 0;
+
+        /**
+         * Minimum size in MiB of a low-level command buffer.
+         *
+         * This is how much space is guaranteed to be available for low-level commands when a new
+         * buffer is allocated. If this is too small, the engine might have to stall to wait for
+         * more space to become available, this situation is logged.
+         *
+         * This value does not affect the application's memory usage.
+         */
+        public long minCommandBufferSizeMB = FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the per-frame high level command buffer.
+         *
+         * This buffer is related to the number of draw calls achievable within a frame, if it is
+         * too small, the program will abort on debug builds and have undefined behavior otherwise.
+         *
+         * It is allocated from the 'per-render-pass arena' above. Make sure that at least 1 MiB is
+         * left in the per-render-pass arena when deciding the size of this buffer.
+         *
+         * This value does not affect the application's memory usage.
+         */
+        public long perFrameCommandsSizeMB = FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB;
+
+        /**
+         * Number of threads to use in Engine's JobSystem.
+         *
+         * Engine uses a utils::JobSystem to carry out paralleization of Engine workloads. This
+         * value sets the number of threads allocated for JobSystem. Configuring this value can be
+         * helpful in CPU-constrained environments where too many threads can cause contention of
+         * CPU and reduce performance.
+         *
+         * The default value is 0, which implies that the Engine will use a heuristic to determine
+         * the number of threads to use.
+         */
+        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).
+         *
+         * @see View#setStereoscopicOptions
+         * @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;
+    }
+
+    private Engine(long nativeEngine, Config config) {
         mNativeObject = nativeEngine;
         mTransformManager = new TransformManager(nGetTransformManager(nativeEngine));
         mLightManager = new LightManager(nGetLightManager(nativeEngine));
         mRenderableManager = new RenderableManager(nGetRenderableManager(nativeEngine));
         mEntityManager = new EntityManager(nGetEntityManager(nativeEngine));
+        mConfig = config;
     }
 
     /**
@@ -177,9 +454,7 @@ public class Engine {
      */
     @NonNull
     public static Engine create() {
-        long nativeEngine = nCreateEngine(0, 0);
-        if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-        return new Engine(nativeEngine);
+        return new Builder().build();
     }
 
     /**
@@ -199,9 +474,9 @@ public class Engine {
      */
     @NonNull
     public static Engine create(@NonNull Backend backend) {
-        long nativeEngine = nCreateEngine(backend.ordinal(), 0);
-        if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-        return new Engine(nativeEngine);
+        return new Builder()
+            .backend(backend)
+            .build();
     }
 
     /**
@@ -223,13 +498,9 @@ public class Engine {
      */
     @NonNull
     public static Engine create(@NonNull Object sharedContext) {
-        if (Platform.get().validateSharedContext(sharedContext)) {
-            long nativeEngine = nCreateEngine(0,
-                    Platform.get().getSharedContextNativeHandle(sharedContext));
-            if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-            return new Engine(nativeEngine);
-        }
-        throw new IllegalArgumentException("Invalid shared context " + sharedContext);
+        return new Builder()
+            .sharedContext(sharedContext)
+            .build();
     }
 
     /**
@@ -296,17 +567,23 @@ public class Engine {
     }
 
     /**
-     * Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
-     * active. The selected feature level must not be higher than the value returned by
-     * getActiveFeatureLevel() and it's not possible lower the active feature level.
+     * Activate all features of a given feature level. If an explicit feature level is not specified
+     * at Engine initialization time via {@link Builder#featureLevel}, the default feature level is
+     * {@link FeatureLevel#FEATURE_LEVEL_0} on devices not compatible with GLES 3.0; otherwise, the
+     * default is {@link FeatureLevel::FEATURE_LEVEL_1}. The selected feature level must not be
+     * higher than the value returned by {@link #getActiveFeatureLevel} and it's not possible lower
+     * the active feature level. Additionally, it is not possible to modify the feature level at all
+     * if the Engine was initialized at {@link FeatureLevel#FEATURE_LEVEL_0}.
      *
-     * @param featureLevel the feature level to activate. If featureLevel is lower than
-     *                     getActiveFeatureLevel(), the current (higher) feature level is kept.
-     *                     If featureLevel is higher than getSupportedFeatureLevel(), an exception
-     *                     is thrown, or the program is terminated if exceptions are disabled.
+     * @param featureLevel the feature level to activate. If featureLevel is lower than {@link
+     *                     #getActiveFeatureLevel}, the current (higher) feature level is kept. If
+     *                     featureLevel is higher than {@link #getSupportedFeatureLevel}, or if the
+     *                     engine was initialized at feature level 0, an exception is thrown, or the
+     *                     program is terminated if exceptions are disabled.
      *
      * @return the active feature level.
      *
+     * @see Builder#featureLevel
      * @see #getSupportedFeatureLevel
      * @see #getActiveFeatureLevel
      */
@@ -352,6 +629,37 @@ public class Engine {
         return nIsAutomaticInstancingEnabled(getNativeObject());
     }
 
+    /**
+     * Retrieves the configuration settings of this {@link Engine}.
+     *
+     * This method returns the configuration object that was supplied to the Engine's {@link
+     * Builder#config} method during the creation of this Engine. If the {@link Builder::config}
+     * method was not explicitly called (or called with null), this method returns the default
+     * configuration settings.
+     *
+     * @return a {@link Config} object with this Engine's configuration
+     * @see Builder#config
+     */
+    @NonNull
+    public Config getConfig() {
+        if (mConfig == null) {
+            mConfig = new Config();
+        }
+        return mConfig;
+    }
+
+    /**
+     * Returns the maximum number of stereoscopic eyes supported by Filament. The actual number of
+     * eyes rendered is set at Engine creation time with the {@link
+     * Engine#Config#stereoscopicEyeCount} setting.
+     *
+     * @return the max number of stereoscopic eyes supported
+     * @see Engine#Config#stereoscopicEyeCount
+     */
+    public long getMaxStereoscopicEyes() {
+        return nGetMaxStereoscopicEyes(getNativeObject());
+    }
+
 
     // SwapChain
 
@@ -366,7 +674,7 @@ public class Engine {
      */
     @NonNull
     public SwapChain createSwapChain(@NonNull Object surface) {
-        return createSwapChain(surface, SwapChain.CONFIG_DEFAULT);
+        return createSwapChain(surface, SwapChainFlags.CONFIG_DEFAULT);
     }
 
     /**
@@ -374,15 +682,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
@@ -400,21 +708,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);
         }
@@ -426,11 +735,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) {
@@ -888,6 +1198,34 @@ public class Engine {
         nFlushAndWait(getNativeObject());
     }
 
+    /**
+     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) but does not wait
+     * for commands to be either executed or the hardware finished.
+     *
+     * <p>This is typically used after creating a lot of objects to start draining the command
+     * queue which has a limited size.</p>
+     */
+    public void flush() {
+        nFlush(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() {
         if (mNativeObject == 0) {
@@ -914,7 +1252,6 @@ public class Engine {
         }
     }
 
-    private static native long nCreateEngine(long backend, long sharedContext);
     private static native void nDestroyEngine(long nativeEngine);
     private static native long nGetBackend(long nativeEngine);
     private static native long nCreateSwapChain(long nativeEngine, Object nativeWindow, long flags);
@@ -961,6 +1298,8 @@ public class Engine {
     private static native boolean nIsValidSwapChain(long nativeEngine, long nativeSwapChain);
     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 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);
@@ -968,7 +1307,23 @@ public class Engine {
     private static native long nGetEntityManager(long nativeEngine);
     private static native void nSetAutomaticInstancingEnabled(long nativeEngine, boolean enable);
     private static native boolean nIsAutomaticInstancingEnabled(long nativeEngine);
+    private static native long nGetMaxStereoscopicEyes(long nativeEngine);
     private static native int nGetSupportedFeatureLevel(long nativeEngine);
     private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
     private static native int nGetActiveFeatureLevel(long nativeEngine);
+
+    private static native long nCreateBuilder();
+    private static native void nDestroyBuilder(long nativeBuilder);
+    private static native void nSetBuilderBackend(long nativeBuilder, long backend);
+    private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
+            long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
+            long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
+            long textureUseAfterFreePoolSize, boolean disableParallelShaderCompile,
+            int stereoscopicType, long stereoscopicEyeCount,
+            long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
+            boolean disableHandleUseAfterFreeCheck);
+    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);
 }

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

@@ -18,9 +18,11 @@ package com.google.android.filament;
 
 import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.annotation.Size;
 
 import com.google.android.filament.proguard.UsedByNative;
+import com.google.android.filament.Engine.FeatureLevel;
 
 import java.nio.Buffer;
 import java.util.ArrayList;
@@ -46,6 +48,8 @@ public class Material {
         static final BlendingMode[] sBlendingModeValues = BlendingMode.values();
         static final RefractionMode[] sRefractionModeValues = RefractionMode.values();
         static final RefractionType[] sRefractionTypeValues = RefractionType.values();
+        static final ReflectionMode[] sReflectionModeValues = ReflectionMode.values();
+        static final FeatureLevel[] sFeatureLevelValues = FeatureLevel.values();
         static final VertexDomain[] sVertexDomainValues = VertexDomain.values();
         static final CullingMode[] sCullingModeValues = CullingMode.values();
         static final VertexBuffer.VertexAttribute[] sVertexAttributeValues =
@@ -181,6 +185,18 @@ public class Material {
         THIN
     }
 
+    /**
+     * Supported reflection modes
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/lighting:reflections">
+     * Lighting: reflections</a>
+     */
+    public enum ReflectionMode {
+        DEFAULT,
+        SCREEN_SPACE
+    }
+
     /**
      * Supported types of vertex domains
      *
@@ -223,6 +239,31 @@ public class Material {
         FRONT_AND_BACK
     }
 
+    public enum CompilerPriorityQueue {
+        HIGH,
+        LOW
+    }
+
+    public static class UserVariantFilterBit {
+        /** Directional lighting */
+        public static int DIRECTIONAL_LIGHTING = 0x01;
+        /** Dynamic lighting */
+        public static int DYNAMIC_LIGHTING = 0x02;
+        /** Shadow receiver */
+        public static int SHADOW_RECEIVER = 0x04;
+        /** Skinning */
+        public static int SKINNING = 0x08;
+        /** Fog */
+        public static int FOG = 0x10;
+        /** Variance shadow maps */
+        public static int VSM = 0x20;
+        /** Screen-space reflections */
+        public static int SSR = 0x40;
+        /** Instanced stereo rendering */
+        public static int STE = 0x80;
+        public static int ALL = 0xFF;
+    }
+
     @UsedByNative("Material.cpp")
     public static class Parameter {
         private static final Type[] sTypeValues = Type.values();
@@ -337,6 +378,55 @@ public class Material {
         }
     }
 
+
+    /**
+     * Asynchronously ensures that a subset of this Material's variants are compiled. After issuing
+     * several compile() calls in a row, it is recommended to call {@link Engine#flush}
+     * such that the backend can start the compilation work as soon as possible.
+     * The provided callback is guaranteed to be called on the main thread after all specified
+     * variants of the material are compiled. This can take hundreds of milliseconds.
+     *<p>
+     * If all the material's variants are already compiled, the callback will be scheduled as
+     * soon as possible, but this might take a few dozen millisecond, corresponding to how
+     * many previous frames are enqueued in the backend. This also varies by backend. Therefore,
+     * it is recommended to only call this method once per material shortly after creation.
+     *</p>
+     *<p>
+     * If the same variant is scheduled for compilation multiple times, the first scheduling
+     * takes precedence; later scheduling are ignored.
+     *</p>
+     *<p>
+     * caveat: A consequence is that if a variant is scheduled on the low priority queue and later
+     * scheduled again on the high priority queue, the later scheduling is ignored.
+     * Therefore, the second callback could be called before the variant is compiled.
+     * However, the first callback, if specified, will trigger as expected.
+     *</p>
+     *<p>
+     * The callback is guaranteed to be called. If the engine is destroyed while some material
+     * variants are still compiling or in the queue, these will be discarded and the corresponding
+     * callback will be called. In that case however the Material pointer passed to the callback
+     * is guaranteed to be invalid (either because it's been destroyed by the user already, or,
+     * because it's been cleaned-up by the Engine).
+     *</p>
+     *<p>
+     * {@link UserVariantFilterBit#ALL} should be used with caution. Only variants that an application
+     * needs should be included in the variants argument. For example, the STE variant is only used
+     * for stereoscopic rendering. If an application is not planning to render in stereo, this bit
+     * should be turned off to avoid unnecessary material compilations.
+     *</p>
+     * @param priority      Which priority queue to use, LOW or HIGH.
+     * @param variants      Variants to include to the compile command.
+     * @param handler       An {@link java.util.concurrent.Executor Executor}. On Android this can also be a {@link android.os.Handler Handler}.
+     * @param callback      callback called on the main thread when the compilation is done on
+     *                      by backend.
+     */
+    public void compile(@NonNull CompilerPriorityQueue priority,
+                        int variants,
+                        @Nullable Object handler,
+                        @Nullable Runnable callback) {
+        nCompile(getNativeObject(), priority.ordinal(), variants, handler, callback);
+    }
+
     /**
      * Creates a new instance of this material. Material instances should be freed using
      * {@link Engine#destroyMaterialInstance(MaterialInstance)}.
@@ -437,6 +527,28 @@ public class Material {
         return EnumCache.sRefractionTypeValues[nGetRefractionType(getNativeObject())];
     }
 
+    /**
+     * Returns the reflection mode of this material.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/lighting:reflections">
+     * Lighting: reflections</a>
+     */
+    public ReflectionMode getReflectionMode() {
+        return EnumCache.sReflectionModeValues[nGetReflectionMode(getNativeObject())];
+    }
+
+    /**
+     * Returns the minimum required feature level for this material.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/general:featurelevel">
+     * General: featureLevel</a>
+     */
+    public FeatureLevel getFeatureLevel() {
+        return EnumCache.sFeatureLevelValues[nGetFeatureLevel(getNativeObject())];
+    }
+
     /**
      * Returns the vertex domain of this material.
      *
@@ -916,6 +1028,7 @@ public class Material {
     private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
     private static native long nGetDefaultInstance(long nativeMaterial);
 
+    private static native void nCompile(long nativeMaterial, int priority, int variants, Object handler, Runnable runnable);
     private static native String nGetName(long nativeMaterial);
     private static native int nGetShading(long nativeMaterial);
     private static native int nGetInterpolation(long nativeMaterial);
@@ -932,6 +1045,8 @@ public class Material {
     private static native float nGetSpecularAntiAliasingThreshold(long nativeMaterial);
     private static native int nGetRefractionMode(long nativeMaterial);
     private static native int nGetRefractionType(long nativeMaterial);
+    private static native int nGetReflectionMode(long nativeMaterial);
+    private static native int nGetFeatureLevel(long nativeMaterial);
 
 
     private static native int nGetParameterCount(long nativeMaterial);

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

@@ -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);

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

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

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

@@ -16,6 +16,7 @@
 
 package com.google.android.filament;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
 /**
@@ -146,18 +147,29 @@ public class Scene {
     }
 
     /**
-     * Returns the number of {@link RenderableManager} components in the <code>Scene</code>.
+     * Returns the total number of Entities in the <code>Scene</code>, whether alive or not.
      *
-     * @return number of {@link RenderableManager} components in the <code>Scene</code>..
+     * @return the total number of Entities in the <code>Scene</code>.
+     */
+    public int getEntityCount() {
+        return nGetEntityCount(getNativeObject());
+    }
+
+    /**
+     * Returns the number of active (alive) {@link RenderableManager} components in the
+     * <code>Scene</code>.
+     *
+     * @return number of {@link RenderableManager} components in the <code>Scene</code>.
      */
     public int getRenderableCount() {
         return nGetRenderableCount(getNativeObject());
     }
 
     /**
-     * Returns the number of {@link LightManager} components in the <code>Scene</code>.
+     * Returns the number of active (alive) {@link LightManager} components in the
+     * <code>Scene</code>.
      *
-     * @return number of {@link LightManager} components in the <code>Scene</code>..
+     * @return number of {@link LightManager} components in the <code>Scene</code>.
      */
     public int getLightCount() {
         return nGetLightCount(getNativeObject());
@@ -179,6 +191,52 @@ public class Scene {
         return mNativeObject;
     }
 
+    /**
+     * Returns the list of all entities in the Scene. If outArray is provided and large enough,
+     * it is used to store the list and returned, otherwise a new array is allocated and returned.
+     * @param outArray an array to store the list of entities in the scene.
+     * @return outArray if it was used or a newly allocated array.
+     * @see #getEntityCount
+     */
+    public int[] getEntities(@Nullable int[] outArray) {
+        int c = getEntityCount();
+        if (outArray == null || outArray.length < c) {
+            outArray = new int[c];
+        }
+        boolean success = nGetEntities(getNativeObject(), outArray, outArray.length);
+        if (!success) {
+            throw new IllegalStateException("Error retriving Scene's entities");
+        }
+        return outArray;
+    }
+
+    /**
+     * Returns the list of all entities in the Scene in a newly allocated array.
+     * @return an array containing the list of all entities in the scene.
+     * @see #getEntityCount
+     */
+    public int[] getEntities() {
+        return getEntities(null);
+    }
+
+    public interface EntityProcessor {
+        void process(@Entity int entity);
+    }
+
+    /**
+     * Invokes user functor on each entity in the scene.
+     *
+     * It is not allowed to add or remove an entity from the scene within the functor.
+     *
+     * @param entityProcessor User provided functor called for each entity in the scene
+     */
+    public void forEach(@NonNull EntityProcessor entityProcessor) {
+        int[] entities = getEntities(null);
+        for (int entity : entities) {
+            entityProcessor.process(entity);
+        }
+    }
+
     void clearNativeObject() {
         mNativeObject = 0;
     }
@@ -189,7 +247,9 @@ public class Scene {
     private static native void nAddEntities(long nativeScene, int[] entities);
     private static native void nRemove(long nativeScene, int entity);
     private static native void nRemoveEntities(long nativeScene, int[] entities);
+    private static native int nGetEntityCount(long nativeScene);
     private static native int nGetRenderableCount(long nativeScene);
     private static native int nGetLightCount(long nativeScene);
     private static native boolean nHasEntity(long nativeScene, int entity);
+    private static native boolean nGetEntities(long nativeScene, int[] outArray, int length);
 }

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

@@ -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);
 }

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

@@ -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;
+}
+

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

@@ -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;
     }

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

@@ -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,6 +102,55 @@ 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
+             */
+            NONE,
+
+            /**
+             * A punchy and more chroma laden look for sRGB displays
+             */
+            PUNCHY,
+
+            /**
+             * A golden tinted, slightly washed look for BT.1886 displays
+             */
+            GOLDEN
+        }
+
+        /**
+         * Builds a new AgX tone mapper with no look applied.
+         */
+        public Agx() {
+            this(AgxLook.NONE);
+        }
+
+        /**
+         * Builds a new AgX tone mapper.
+         *
+         * @param look: an optional creative adjustment to contrast and saturation
+         */
+        public Agx(AgxLook look) {
+            super(nCreateAgxToneMapper(look.ordinal()));
+        }
+    }
+
     /**
      * Generic tone mapping operator that gives control over the tone mapping
      * curve. This operator can be used to control the aesthetics of the final
@@ -194,6 +245,8 @@ 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);
 

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

@@ -75,6 +75,7 @@ public class View {
     private AmbientOcclusionOptions mAmbientOcclusionOptions;
     private BloomOptions mBloomOptions;
     private FogOptions mFogOptions;
+    private StereoscopicOptions mStereoscopicOptions;
     private RenderTarget mRenderTarget;
     private BlendMode mBlendMode;
     private DepthOfFieldOptions mDepthOfFieldOptions;
@@ -1055,6 +1056,51 @@ public class View {
         return nIsStencilBufferEnabled(getNativeObject());
     }
 
+    /**
+     * Sets the stereoscopic rendering options for this view.
+     *
+     * <p>
+     * Currently, only one type of stereoscopic rendering is supported: side-by-side.
+     * Side-by-side stereo rendering splits the viewport into two halves: a left and right half.
+     * Eye 0 will render to the left half, while Eye 1 will render into the right half.
+     * </p>
+     *
+     * <p>
+     * Currently, the following features are not supported with stereoscopic rendering:
+     * - post-processing
+     * - shadowing
+     * - punctual lights
+     * </p>
+     *
+     * <p>
+     * Stereo rendering depends on device and platform support. To check if stereo rendering is
+     * supported, use {@link Engine#isStereoSupported()}. If stereo rendering is not supported, then
+     * the stereoscopic options have no effect.
+     * </p>
+     *
+     * @param options The stereoscopic options to use on this view
+     * @see #getStereoscopicOptions
+     */
+    public void setStereoscopicOptions(@NonNull StereoscopicOptions options) {
+        mStereoscopicOptions = options;
+        nSetStereoscopicOptions(getNativeObject(), options.enabled);
+    }
+
+    /**
+     * Gets the stereoscopic options.
+     *
+     * @return options Stereoscopic options currently set.
+     * @see #setStereoscopicOptions
+     */
+    @NonNull
+    public StereoscopicOptions getStereoscopicOptions() {
+        if (mStereoscopicOptions == null) {
+            mStereoscopicOptions = new StereoscopicOptions();
+        }
+        return mStereoscopicOptions;
+    }
+
+
     /**
      * A class containing the result of a picking query
      */
@@ -1220,6 +1266,7 @@ public class View {
     private static native void nSetBloomOptions(long nativeView, long dirtNativeObject, float dirtStrength, float strength, int resolution, int levels, int blendMode, boolean threshold, boolean enabled, float highlight,
             boolean lensFlare, boolean starburst, float chromaticAberration, int ghostCount, float ghostSpacing, float ghostThreshold, float haloThickness, float haloRadius, float haloThreshold);
     private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, long skyColorNativeObject, boolean enabled);
+    private static native void nSetStereoscopicOptions(long nativeView, boolean enabled);
     private static native void nSetBlendMode(long nativeView, int blendMode);
     private static native void nSetDepthOfFieldOptions(long nativeView, float cocScale, float maxApertureDiameter, boolean enabled, int filter,
             boolean nativeResolution, int foregroundRingCount, int backgroundRingCount, int fastGatherRingCount, int maxForegroundCOC, int maxBackgroundCOC);
@@ -1590,6 +1637,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)
          */
@@ -1805,7 +1856,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 {
@@ -1829,21 +1880,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;
     }
 
     /**
@@ -1930,6 +2071,7 @@ public class View {
          * PCF with soft shadows and contact hardening
          */
         PCSS,
+        PCFd,
     }
 
     /**

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

@@ -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,30 +270,127 @@ 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()
+                mRenderCallback.onResized(width, height);
             }
-            // the call above won't cause TextureView.onSurfaceTextureSizeChanged()
-            mRenderCallback.onResized(width, height);
         }
 
         @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();
@@ -245,7 +399,7 @@ public class UiHelper {
             mSurface = surface;
         }
 
-        public Surface getSurface() {
+        private Surface getSurface() {
             return mSurface;
         }
     }
@@ -291,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;
@@ -298,7 +455,6 @@ public class UiHelper {
 
     /**
      * Checks whether we are ready to render into the attached surface.
-     *
      * Using OpenGL ES when this returns true, will result in drawing commands being lost,
      * HOWEVER, GLES state will be preserved. This is useful to initialize the engine.
      *
@@ -343,7 +499,6 @@ public class UiHelper {
     /**
      * Controls whether the render target (SurfaceView or TextureView) is opaque or not.
      * The render target is considered opaque by default.
-     *
      * Must be called before calling {@link #attachTo(SurfaceView)}, {@link #attachTo(TextureView)},
      * or {@link #attachTo(SurfaceHolder)}.
      *
@@ -366,10 +521,8 @@ public class UiHelper {
      * positioned above other surfaces but below the activity's surface. This property
      * only has an effect when used in combination with {@link #setOpaque(boolean) setOpaque(false)}
      * and does not affect TextureView targets.
-     *
      * Must be called before calling {@link #attachTo(SurfaceView)}
      * or {@link #attachTo(TextureView)}.
-     *
      * Has no effect when using {@link #attachTo(SurfaceHolder)}.
      *
      * @param overlay Indicates whether the render target should be rendered below the activity's
@@ -385,12 +538,11 @@ 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;
     }
 
     /**
      * Associate UiHelper with a SurfaceView.
-     *
      * As soon as SurfaceView is ready (i.e. has a Surface), we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
@@ -405,171 +557,32 @@ 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(SurfaceHolder holder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(
-                        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 + ")");
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void surfaceDestroyed(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());
-            }
         }
     }
 
     /**
      * Associate UiHelper with a TextureView.
-     *
      * As soon as TextureView is ready (i.e. has a buffer), we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
     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(
-                        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);
-
-                    // Call this the first time because onSurfaceTextureSizeChanged()
-                    // isn't called at initialization time
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void onSurfaceTextureSizeChanged(
-                        SurfaceTexture surfaceTexture, int width, int height) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureSizeChanged()");
-                    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(SurfaceTexture surfaceTexture) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureDestroyed()");
-                    destroySwapChain();
-                    return true;
-                }
-
-                @Override
-                public void onSurfaceTextureUpdated(SurfaceTexture surface) { }
-            };
-
-            view.setSurfaceTextureListener(listener);
-
-            // in case the View's SurfaceTexture already existed
-            if (view.isAvailable()) {
-                SurfaceTexture surfaceTexture = view.getSurfaceTexture();
-                listener.onSurfaceTextureAvailable(surfaceTexture, mDesiredWidth, mDesiredHeight);
-            }
         }
     }
 
     /**
      * Associate UiHelper with a SurfaceHolder.
-     *
      * As soon as a Surface is created, we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
     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(SurfaceHolder surfaceHolder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(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 + ")");
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void surfaceDestroyed(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());
-            }
         }
     }
 
@@ -580,6 +593,10 @@ public class UiHelper {
                 // nothing to do
                 return false;
             }
+            if (mRenderSurface != null) {
+                mRenderSurface.detach();
+                mRenderSurface = null;
+            }
             destroySwapChain();
         }
         mNativeWindow = nativeWindow;
@@ -587,15 +604,16 @@ public class UiHelper {
     }
 
     private void createSwapChain(@NonNull Surface surface) {
-        mRenderCallback.onNativeWindowChanged(surface);
+        if (mRenderCallback != null) {
+            mRenderCallback.onNativeWindowChanged(surface);
+        }
         mHasSwapChain = true;
     }
 
     private void destroySwapChain() {
-        if (mRenderSurface != null) {
-            mRenderSurface.detach();
+        if (mRenderCallback != null) {
+            mRenderCallback.onDetachedFromSurface();
         }
-        mRenderCallback.onDetachedFromSurface();
         mHasSwapChain = false;
     }
 }

android/gltfio-android/CMakeLists.txt

@@ -81,9 +81,17 @@ 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.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

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java

@@ -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);
     }
 

android/gradle.properties

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

android/gradle/wrapper/gradle-wrapper.properties

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

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

@@ -30,7 +30,7 @@ android {
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.gltf"
-        minSdkVersion 19
+        minSdkVersion versions.minSdk
         targetSdkVersion versions.targetSdk
     }
 

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

@@ -26,6 +26,7 @@ import android.widget.TextView
 import android.widget.Toast
 import com.google.android.filament.Fence
 import com.google.android.filament.IndirectLight
+import com.google.android.filament.Material
 import com.google.android.filament.Skybox
 import com.google.android.filament.View
 import com.google.android.filament.View.OnPickCallback
@@ -392,6 +393,36 @@ class MainActivity : Activity() {
                     Log.i(TAG, "The Filament backend took $total ms to load the model geometry.")
                     modelViewer.engine.destroyFence(it)
                     loadStartFence = null
+
+                    val materials = mutableSetOf<Material>()
+                    val rcm = modelViewer.engine.renderableManager
+                    modelViewer.scene.forEach {
+                        val entity = it
+                        if (rcm.hasComponent(entity)) {
+                            val ri = rcm.getInstance(entity)
+                            val c = rcm.getPrimitiveCount(ri)
+                            for (i in 0 until c) {
+                                val mi = rcm.getMaterialInstanceAt(ri, i)
+                                val ma = mi.material
+                                materials.add(ma)
+                            }
+                        }
+                    }
+                    materials.forEach {
+                        it.compile(
+                            Material.CompilerPriorityQueue.HIGH,
+                            Material.UserVariantFilterBit.DIRECTIONAL_LIGHTING or
+                            Material.UserVariantFilterBit.DYNAMIC_LIGHTING or
+                            Material.UserVariantFilterBit.SHADOW_RECEIVER,
+                            null, null)
+                        it.compile(
+                            Material.CompilerPriorityQueue.LOW,
+                            Material.UserVariantFilterBit.FOG or
+                            Material.UserVariantFilterBit.SKINNING or
+                            Material.UserVariantFilterBit.SSR or
+                            Material.UserVariantFilterBit.VSM,
+                            null, null)
+                    }
                 }
             }
 

android/samples/sample-hello-triangle/src/main/java/com/google/android/filament/hellotriangle/MainActivity.kt

@@ -20,6 +20,8 @@ import android.animation.ValueAnimator
 import android.app.Activity
 import android.opengl.Matrix
 import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
 import android.view.Choreographer
 import android.view.Surface
 import android.view.SurfaceView
@@ -110,7 +112,7 @@ class MainActivity : Activity() {
     }
 
     private fun setupFilament() {
-        engine = Engine.create()
+        engine = Engine.Builder().featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0).build()
         renderer = engine.createRenderer()
         scene = engine.createScene()
         view = engine.createView()
@@ -120,13 +122,8 @@ class MainActivity : Activity() {
     private fun setupView() {
         scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
 
-        if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
-            // post-processing is not supported at feature level 0
-            view.isPostProcessingEnabled = false
-        } else {
-            // NOTE: Try to disable post-processing (tone-mapping, etc.) to see the difference
-            // view.isPostProcessingEnabled = false
-        }
+        // post-processing is not supported at feature level 0
+        view.isPostProcessingEnabled = false
 
         // Tell the view which camera we want to use
         view.camera = camera
@@ -162,6 +159,14 @@ class MainActivity : Activity() {
     private fun loadMaterial() {
         readUncompressedAsset("materials/baked_color.filamat").let {
             material = Material.Builder().payload(it, it.remaining()).build(engine)
+            material.compile(
+                Material.CompilerPriorityQueue.HIGH,
+                Material.UserVariantFilterBit.ALL,
+                Handler(Looper.getMainLooper())) {
+                        android.util.Log.i("hellotriangle",
+                            "Material " + material.name + " compiled.")
+            }
+            engine.flush()
         }
     }
 

build.sh

@@ -191,6 +191,7 @@ function build_clean {
     rm -Rf android/filamat-android/build android/filamat-android/.externalNativeBuild android/filamat-android/.cxx
     rm -Rf android/gltfio-android/build android/gltfio-android/.externalNativeBuild android/gltfio-android/.cxx
     rm -Rf android/filament-utils-android/build android/filament-utils-android/.externalNativeBuild android/filament-utils-android/.cxx
+    rm -f compile_commands.json
 }
 
 function build_clean_aggressive {
@@ -232,6 +233,8 @@ function build_desktop_target {
             ${ASAN_UBSAN_OPTION} \
             ${architectures} \
             ../..
+        ln -sf "out/cmake-${lc_target}/compile_commands.json" \
+           ../../compile_commands.json
     fi
     ${BUILD_COMMAND} ${build_targets}
 
@@ -287,6 +290,8 @@ function build_webgl_with_target {
             -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \
             -DWEBGL=1 \
             ../..
+        ln -sf "out/cmake-webgl-${lc_target}/compile_commands.json" \
+           ../../compile_commands.json
         ${BUILD_COMMAND} ${BUILD_TARGETS}
         )
     fi
@@ -359,6 +364,8 @@ function build_android_target {
             ${MATOPT_OPTION} \
             ${VULKAN_ANDROID_OPTION} \
             ../..
+        ln -sf "out/cmake-android-${lc_target}-${arch}/compile_commands.json" \
+           ../../compile_commands.json
     fi
 
     # We must always install Android libraries to build the AAR
@@ -509,7 +516,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
@@ -591,6 +598,8 @@ function build_ios_target {
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ../..
+        ln -sf "out/cmake-ios-${lc_target}-${arch}/compile_commands.json" \
+           ../../compile_commands.json
     fi
 
     ${BUILD_COMMAND}

build/android/ndk.version

@@ -1 +1 @@
-25.1.8937393
+26.1.10909125

build/common/bump-version.sh

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

build/linux/combine-static-libs.sh

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

build/toolchain-arm7-linux-android.cmake

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

build/toolchain-x86-linux-android.cmake

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

docs/Materials.md.html

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

docs/viewer/filament-viewer.js

@@ -15,7 +15,7 @@
 */
 
 // If you are bundling this with rollup, webpack, or esbuild, the following URL should be trimmed.
-import { LitElement, html, css } from "https://unpkg.com/lit?module";
+import { LitElement, html, css } from "https://unpkg.com/lit@2.8.0?module";
 
 // This little utility checks if the Filament module is ready for action.
 // If so, it immediately calls the given function. If not, it asks the Filament
@@ -287,12 +287,12 @@ class FilamentViewer extends LitElement {
         // Dropping a glb file is simple because there are no external resources.
         if (this.srcBlob && this.srcBlob.name.endsWith(".glb")) {
             this.srcBlob.arrayBuffer().then(buffer => {
-                this.asset = this.loader.createAssetFromBinary(new Uint8Array(buffer));
+                this.asset = this.loader.createAsset(new Uint8Array(buffer));
                 const aabb = this.asset.getBoundingBox();
                 this.assetRoot = this.asset.getRoot();
                 this.unitCubeTransform = Filament.fitIntoUnitCube(aabb, zoffset);
                 this.asset.loadResources();
-                this.animator = this.asset.getAnimator();
+                this.animator = this.asset.getInstance().getAnimator();
                 this.animationStartTime = Date.now();
                 this._updateOverlay();
             });
@@ -304,8 +304,6 @@ class FilamentViewer extends LitElement {
 
             const config = {
                 normalizeSkinningWeights: true,
-                recomputeBoundingBoxes: false,
-                ignoreBindTransform: false,
                 asyncInterval: 30
             };
 
@@ -320,22 +318,20 @@ class FilamentViewer extends LitElement {
                         resourceLoader.delete();
                         stbProvider.delete();
                         ktx2Provider.delete();
-                        this.animator = this.asset.getAnimator();
+                        this.animator = this.asset.getInstance().getAnimator();
                         this.animationStartTime = Date.now();
                     }
                 }, config.asyncInterval);
             };
 
             this.srcBlob.arrayBuffer().then(buffer => {
-                this.asset = this.loader.createAssetFromJson(new Uint8Array(buffer));
+                this.asset = this.loader.createAsset(new Uint8Array(buffer));
                 const aabb = this.asset.getBoundingBox();
                 this.assetRoot = this.asset.getRoot();
                 this.unitCubeTransform = Filament.fitIntoUnitCube(aabb, zoffset);
 
                 const resourceLoader = new Filament.gltfio$ResourceLoader(this.engine,
-                    config.normalizeSkinningWeights,
-                    config.recomputeBoundingBoxes,
-                    config.ignoreBindTransform);
+                    config.normalizeSkinningWeights);
 
                 const stbProvider = new Filament.gltfio$StbProvider(this.engine);
                 const ktx2Provider = new Filament.gltfio$Ktx2Provider(this.engine);
@@ -367,12 +363,7 @@ class FilamentViewer extends LitElement {
             return response.arrayBuffer();
         }).then(arrayBuffer => {
             const modelData = new Uint8Array(arrayBuffer);
-            if (this.src.endsWith(".glb")) {
-                this.asset = this.loader.createAssetFromBinary(modelData);
-            } else {
-                this.asset = this.loader.createAssetFromJson(modelData);
-            }
-
+            this.asset = this.loader.createAsset(modelData);
             const aabb = this.asset.getBoundingBox();
             this.assetRoot = this.asset.getRoot();
             this.unitCubeTransform = Filament.fitIntoUnitCube(aabb, zoffset);
@@ -380,7 +371,7 @@ class FilamentViewer extends LitElement {
             const basePath = '' + new URL(this.src, document.location);
 
             this.asset.loadResources(() => {
-                this.animator = this.asset.getAnimator();
+                this.animator = this.asset.getInstance().getAnimator();
                 this.animationStartTime = Date.now();
                 this._applyMaterialVariant();
             }, null, basePath);
@@ -441,14 +432,15 @@ class FilamentViewer extends LitElement {
         if (!this.hasAttribute("materialVariant")) {
             return;
         }
-        const names = this.asset.getMaterialVariantNames();
+        const instance = this.asset.getInstance();
+        const names = instance.getMaterialVariantNames();
         const index = this.materialVariant;
         if (index < 0 || index >= names.length) {
             console.error(`Material variant ${index} does not exist in this asset.`);
             return;
         }
         console.info(this.src, `Applying material variant: ${names[index]}`);
-        this.asset.applyMaterialVariant(index);
+        instance.applyMaterialVariant(index);
     }
 }
 

docs/viewer/index.html

@@ -43,7 +43,7 @@ filament-viewer::part(canvas) {
 </p>
 
 </main>
-<script src="https://unpkg.com/filament@1.25.3/filament.js"></script>
+<script src="https://unpkg.com/filament@1.44.0/filament.js"></script>
 <script src="https://unpkg.com/gltumble"></script>
 <script src="filament-viewer.js" type="module"></script>
 </body>

docs/webgl/reference.html

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

filament/CMakeLists.txt

@@ -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
@@ -209,10 +212,14 @@ 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/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 +227,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/blitLow.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
 )
 
-set(MATERIAL_ES2_SRCS
-        src/materials/defaultMaterial0.mat
-        src/materials/skybox0.mat
+set(MATERIAL_FL0_SRCS
+        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.
@@ -274,6 +285,16 @@ if (NOT DFG_LUT_SIZE)
 endif()
 message(STATUS "DFG LUT size set to ${DFG_LUT_SIZE}x${DFG_LUT_SIZE}")
 
+# Whether to include FL0 materials.
+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
 # ==================================================================================================
@@ -304,33 +325,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 (IS_MOBILE_TARGET AND FILAMENT_SUPPORTS_OPENGL)
-    foreach (mat_src ${MATERIAL_ES2_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
 

filament/backend/CMakeLists.txt

@@ -133,6 +133,7 @@ if (FILAMENT_SUPPORTS_METAL)
             src/metal/MetalExternalImage.mm
             src/metal/MetalHandles.mm
             src/metal/MetalPlatform.mm
+            src/metal/MetalShaderCompiler.mm
             src/metal/MetalState.mm
             src/metal/MetalTimerQuery.mm
             src/metal/MetalUtils.mm
@@ -165,9 +166,13 @@ endif()
 if (FILAMENT_SUPPORTS_VULKAN)
     list(APPEND SRCS
             include/backend/platforms/VulkanPlatform.h
+            src/vulkan/caching/VulkanDescriptorSet.cpp
+            src/vulkan/caching/VulkanDescriptorSet.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
@@ -312,6 +317,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)
@@ -396,8 +402,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
@@ -409,19 +415,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
@@ -435,12 +448,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")
@@ -454,15 +466,21 @@ 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)
+    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()
 
 # ==================================================================================================

filament/backend/include/backend/BufferDescriptor.h

@@ -23,7 +23,6 @@
 #include <utils/ostream.h>
 
 #include <stddef.h>
-#include <stdint.h>
 
 namespace filament::backend {
 
@@ -113,7 +112,7 @@ public:
     /**
      * Helper to create a BufferDescriptor that uses a KNOWN method pointer w/ object passed
      * by pointer as the callback. e.g.:
-     *     auto bd = BufferDescriptor::make(buffer, size, &Foo::method, foo);
+     *     auto bd = BufferDescriptor::make<Foo, &Foo::method>(buffer, size, foo);
      *
      * @param buffer    Memory address of the CPU buffer to reference
      * @param size      Size of the CPU buffer in bytes
@@ -121,12 +120,12 @@ public:
      * @return          a new BufferDescriptor
      */
     template<typename T, void(T::*method)(void const*, size_t)>
-    static BufferDescriptor make(
-            void const* buffer, size_t size, T* data, CallbackHandler* handler = nullptr) noexcept {
+    static BufferDescriptor make(void const* buffer, size_t size, T* data,
+            CallbackHandler* handler = nullptr) noexcept {
         return {
                 buffer, size,
                 handler, [](void* b, size_t s, void* u) {
-                    (*static_cast<T**>(u)->*method)(b, s);
+                    (static_cast<T*>(u)->*method)(b, s);
                 }, data
         };
     }
@@ -145,14 +144,14 @@ public:
      * @return          a new BufferDescriptor
      */
     template<typename T>
-    static BufferDescriptor make(
-            void const* buffer, size_t size, T&& functor, CallbackHandler* handler = nullptr) noexcept {
+    static BufferDescriptor make(void const* buffer, size_t size, T&& functor,
+            CallbackHandler* handler = nullptr) noexcept {
         return {
                 buffer, size,
                 handler, [](void* b, size_t s, void* u) {
-                    T& that = *static_cast<T*>(u);
-                    that(b, s);
-                    delete &that;
+                    T* const that = static_cast<T*>(u);
+                    that->operator()(b, s);
+                    delete that;
                 },
                 new T(std::forward<T>(functor))
         };
@@ -201,7 +200,7 @@ public:
         return mUser;
     }
 
-    //! CPU mempry-buffer virtual address
+    //! CPU memory-buffer virtual address
     void* buffer = nullptr;
 
     //! CPU memory-buffer size in bytes

filament/backend/include/backend/CallbackHandler.h

@@ -17,8 +17,6 @@
 #ifndef TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H
 #define TNT_FILAMENT_BACKEND_CALLBACKHANDLER_H
 
-#include <utils/compiler.h>
-
 namespace filament::backend {
 
 /**

filament/backend/include/backend/DriverEnums.h

@@ -28,7 +28,8 @@
 
 #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 <stddef.h>
 #include <stdint.h>
@@ -80,7 +81,14 @@ 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.
@@ -128,6 +136,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:
@@ -154,6 +168,19 @@ enum class ShaderLanguage {
     MSL = 3,
 };
 
+static constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguage) {
+    switch (shaderLanguage) {
+        case ShaderLanguage::ESSL1:
+            return "ESSL 1.0";
+        case ShaderLanguage::ESSL3:
+            return "ESSL 3.0";
+        case ShaderLanguage::SPIRV:
+            return "SPIR-V";
+        case ShaderLanguage::MSL:
+            return "MSL";
+    }
+}
+
 /**
  * Bitmask for selecting render buffers
  */
@@ -214,6 +241,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.
  */
@@ -644,14 +672,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 the destination of a blit()
     DEFAULT             = UPLOADABLE | SAMPLEABLE   //!< Default texture usage
 };
 
@@ -679,6 +710,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:
@@ -1144,11 +1186,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;
@@ -1167,8 +1225,8 @@ using FrameScheduledCallback = void(*)(PresentCallable callable, void* user);
 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,
@@ -1184,6 +1242,14 @@ enum class Workaround : uint16_t {
     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
 
 template<> struct utils::EnableBitMaskOperators<filament::backend::ShaderStageFlags>

filament/backend/include/backend/Handle.h

@@ -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; }
 
@@ -103,6 +94,14 @@ struct Handle : public HandleBase {
 
     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 +115,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
 

filament/backend/include/backend/PipelineState.h

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

filament/backend/include/backend/PixelBufferDescriptor.h

@@ -24,6 +24,7 @@
 
 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/ostream.h>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -141,7 +142,7 @@ public:
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, type, alignment, left, top, stride,
                 handler, [](void* b, size_t s, void* u) {
-                    (*static_cast<T**>(u)->*method)(b, s); }, data };
+                    (static_cast<T*>(u)->*method)(b, s); }, data };
     }
 
     template<typename T, void(T::*method)(void const*, size_t)>
@@ -149,7 +150,7 @@ public:
             PixelDataFormat format, PixelDataType type, T* data,
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, type, handler, [](void* b, size_t s, void* u) {
-                    (*static_cast<T**>(u)->*method)(b, s); }, data };
+                    (static_cast<T*>(u)->*method)(b, s); }, data };
     }
 
     template<typename T, void(T::*method)(void const*, size_t)>
@@ -157,7 +158,7 @@ public:
             backend::CompressedPixelDataType format, uint32_t imageSize, T* data,
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, imageSize, handler, [](void* b, size_t s, void* u) {
-                    (*static_cast<T**>(u)->*method)(b, s); }, data
+                    (static_cast<T*>(u)->*method)(b, s); }, data
         };
     }
 
@@ -168,9 +169,9 @@ public:
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, type, alignment, left, top, stride,
                 handler, [](void* b, size_t s, void* u) {
-                    T& that = *static_cast<T*>(u);
-                    that(b, s);
-                    delete &that;
+                    T* const that = static_cast<T*>(u);
+                    that->operator()(b, s);
+                    delete that;
                 }, new T(std::forward<T>(functor))
         };
     }
@@ -181,9 +182,9 @@ public:
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, type,
                  handler, [](void* b, size_t s, void* u) {
-                    T& that = *static_cast<T*>(u);
-                    that(b, s);
-                    delete &that;
+                    T* const that = static_cast<T*>(u);
+                    that->operator()(b, s);
+                    delete that;
                 }, new T(std::forward<T>(functor))
         };
     }
@@ -194,9 +195,9 @@ public:
             CallbackHandler* handler = nullptr) noexcept {
         return { buffer, size, format, imageSize,
                  handler, [](void* b, size_t s, void* u) {
-                    T& that = *static_cast<T*>(u);
-                    that(b, s);
-                    delete &that;
+                    T* const that = static_cast<T*>(u);
+                    that->operator()(b, s);
+                    delete that;
                 }, new T(std::forward<T>(functor))
         };
     }

filament/backend/include/backend/Platform.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,29 @@ 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;
     };
 
     Platform() noexcept;
@@ -78,7 +90,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 +108,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 +117,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
@@ -114,6 +128,7 @@ public:
      * Platform.  The <insert> and <retrieve> Invocables may be called at any time and
      * from any thread from the time at which setBlobFunc is called until the time that Platform
      * is destroyed. Concurrent calls to these functions from different threads is also allowed.
+     * Either function can be null.
      *
      * @param insertBlob    an Invocable that inserts a new value into the cache and associates
      *                      it with the given key
@@ -123,9 +138,21 @@ public:
     void setBlobFunc(InsertBlobFunc&& insertBlob, RetrieveBlobFunc&& retrieveBlob) noexcept;
 
     /**
-     * @return true if setBlobFunc was called.
+     * @return true if insertBlob is valid.
      */
-    bool hasBlobFunc() const noexcept;
+    bool hasInsertBlobFunc() const noexcept;
+
+    /**
+     * @return true if retrieveBlob is valid.
+     */
+    bool hasRetrieveBlobFunc() const noexcept;
+
+    /**
+     * @return true if either of insertBlob or retrieveBlob are valid.
+     */
+    bool hasBlobFunc() const noexcept {
+        return hasInsertBlobFunc() || hasRetrieveBlobFunc();
+    }
 
     /**
      * To insert a new binary value into the cache and associate it with a given
@@ -144,7 +171,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
@@ -163,11 +191,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

filament/backend/include/backend/PresentCallable.h

@@ -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
@@ -98,7 +97,6 @@ private:
  */
 using FrameFinishedCallback UTILS_DEPRECATED = void(*)(PresentCallable callable, void* user);
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
 
 #endif // TNT_FILAMENT_BACKEND_PRESENTCALLABLE

filament/backend/include/backend/Program.h

@@ -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 {
 
@@ -114,6 +116,8 @@ public:
 
     Program& cacheId(uint64_t cacheId) noexcept;
 
+    Program& multiview(bool multiview) noexcept;
+
     ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
     ShaderSource& getShadersSource() noexcept { return mShadersSource; }
 
@@ -141,6 +145,8 @@ public:
 
     uint64_t getCacheId() const noexcept { return mCacheId; }
 
+    bool isMultiview() const noexcept { return mMultiview; }
+
     CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }
 
 private:
@@ -156,6 +162,11 @@ private:
     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

filament/backend/include/backend/SamplerDescriptor.h

@@ -24,9 +24,6 @@
 
 #include <utils/compiler.h>
 
-#include <stddef.h>
-#include <stdint.h>
-
 namespace filament::backend {
 
 struct UTILS_PUBLIC SamplerDescriptor {

filament/backend/include/backend/TargetBufferInfo.h

@@ -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 {
@@ -30,6 +32,10 @@ struct TargetBufferInfo {
     // 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;
 
@@ -78,7 +84,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, 0, level, layer }} {
     }
 };
 

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

@@ -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,80 @@ 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;
+
+
+    /**
+     * 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 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 +221,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 +238,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 +252,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 +268,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 +295,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 +314,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 +328,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

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

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

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

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

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

@@ -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,12 +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
 
@@ -83,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;
@@ -116,16 +137,28 @@ 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;
     std::vector<EGLContext> mAdditionalContexts;
@@ -141,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:
-    EGLConfig findSwapChainConfig(uint64_t flags) const;
+    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

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

@@ -17,8 +17,14 @@
 #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 <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
 class ExternalStreamManagerAndroid;

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

@@ -30,6 +30,9 @@ public:
 
     Driver* createDriver(void* sharedContext,
             const Platform::DriverConfig& driverConfig) noexcept override;
+
+protected:
+    bool isOpenGL() const noexcept override;
 };
 
 } // namespace filament

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

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

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

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

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

@@ -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;
 };
 

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

@@ -20,12 +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;
@@ -89,36 +95,44 @@ public:
 
     // ----------------------------------------------------
     // ---------- Platform Customization options ----------
-    /**
-     * The client preference can be stored within the struct.  We allow for two specification of
-     * preference:
-     *     1) A substring to match against `VkPhysicalDeviceProperties.deviceName`.
-     *     2) Index of the device in the list as returned by vkEnumeratePhysicalDevices.
-     */
-    struct GPUPreference {
-        std::string deviceName;
-        int8_t index = -1;
+    struct Customization {
+        /**
+         * The client can specify the GPU (i.e. VkDevice) for the platform. We allow the
+         * following preferences:
+         *     1) A substring to match against `VkPhysicalDeviceProperties.deviceName`. Empty string
+         *        by default.
+         *     2) Index of the device in the list as returned by
+         *        `vkEnumeratePhysicalDevices`. -1 by default to indicate no preference.
+         */
+        struct GPUPreference {
+            utils::CString deviceName;
+            int8_t index = -1;
+        } gpu;
+
+        /**
+         * Whether the platform supports sRGB swapchain. Default is true.
+         */
+        bool isSRGBSwapChainSupported = true;
+
+        /**
+         * When the platform window is resized, we will flush and wait on the command queues
+         * before recreating the swapchain. Default is true.
+         */
+        bool flushAndWaitOnWindowResize = true;
     };
 
     /**
-     * Client can provide a preference over the GPU to use in the vulkan instance
-     * @return            `GPUPreference` struct that indicates the client's preference
+     * Client can override to indicate customized behavior or parameter for their platform.
+     * @return            `Customization` struct that indicates the client's platform
+     *                    customizations.
      */
-    virtual GPUPreference getPreferredGPU() noexcept {
+    virtual Customization getCustomization() const noexcept {
         return {};
     }
+
     // -------- End platform customization options --------
     // ----------------------------------------------------
 
-    /**
-     * Returns whether the platform supports sRGB swapchain. This is true by default, and the client
-     * needs to override this method to specify otherwise.
-     * @return            Whether the platform supports sRGB swapchain.
-     */
-    virtual bool isSRGBSwapChainSupported() const {
-        return true;
-    }
-
     /**
      * Get the images handles and format of the memory backing the swapchain. This should be called
      * after createSwapChain() or after recreateIfResized().

filament/backend/include/private/backend/CircularBuffer.h

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

filament/backend/include/private/backend/CommandBufferQueue.h

@@ -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,9 @@ public:
     // returns from waitForCommands() immediately.
     void requestExit();
 
+    // suspend or unsuspend the queue.
+    void setPaused(bool paused);
+
     bool isExitRequested() const;
 };
 

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

@@ -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) {                                                        \

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

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

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

@@ -167,12 +167,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 +227,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 +239,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 +264,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 +299,16 @@ 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_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)
 
@@ -468,7 +471,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 +479,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
 

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

@@ -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, 576>
+#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,71 +185,97 @@ 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; }
         }
     };
 
-
+// FIXME: We should be using a Spinlock here, at least on platforms where mutexes are not
+//        efficient (i.e. non-Linux). However, we've seen some hangs on that spinlock, which
+//        we don't understand well (b/308029108).
 #ifndef NDEBUG
     using HandleArena = utils::Arena<Allocator,
-            utils::LockingPolicy::SpinLock,
+            utils::LockingPolicy::Mutex,
             utils::TrackingPolicy::DebugAndHighWatermark>;
 #else
     using HandleArena = utils::Arena<Allocator,
-            utils::LockingPolicy::SpinLock>;
+            utils::LockingPolicy::Mutex>;
 #endif
 
     // 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>(); }
-        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 {
-            deallocateHandleFromPool<P2>(id);
-        }
+        constexpr size_t BUCKET_SIZE = getBucketSize<D>();
+        deallocateHandleFromPool<BUCKET_SIZE>(id);
     }
 
     // allocateHandleInPool()/deallocateHandleFromPool() is NOT inlined, which will cause three
@@ -276,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);
         }
@@ -288,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;
     }
 
@@ -333,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

filament/backend/include/private/backend/PlatformFactory.h

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

filament/backend/include/private/backend/SamplerGroup.h

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

filament/backend/src/CircularBuffer.cpp

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

filament/backend/src/CommandBufferQueue.cpp

@@ -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,16 @@ void CommandBufferQueue::requestExit() {
     mCondition.notify_one();
 }
 
+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 +87,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 +151,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();

filament/backend/src/CommandStream.cpp

@@ -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();

filament/backend/src/DataReshaper.h

@@ -19,6 +19,7 @@
 
 #include <backend/PixelBufferDescriptor.h>
 
+#include <cstring>
 #include <stddef.h>
 #include <stdint.h>
 

filament/backend/src/Driver.cpp

@@ -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();
 }
 

filament/backend/src/DriverBase.h

@@ -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{} {}

filament/backend/src/HandleAllocator.cpp

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

filament/backend/src/Platform.cpp

@@ -28,14 +28,16 @@ bool Platform::pumpEvents() noexcept {
 }
 
 void Platform::setBlobFunc(InsertBlobFunc&& insertBlob, RetrieveBlobFunc&& retrieveBlob) noexcept {
-    if (!mInsertBlob && !mRetrieveBlob) {
-        mInsertBlob = std::move(insertBlob);
-        mRetrieveBlob = std::move(retrieveBlob);
-    }
+    mInsertBlob = std::move(insertBlob);
+    mRetrieveBlob = std::move(retrieveBlob);
 }
 
-bool Platform::hasBlobFunc() const noexcept {
-    return mInsertBlob && mRetrieveBlob;
+bool Platform::hasInsertBlobFunc() const noexcept {
+    return bool(mInsertBlob);
+}
+
+bool Platform::hasRetrieveBlobFunc() const noexcept {
+    return bool(mRetrieveBlob);
 }
 
 void Platform::insertBlob(void const* key, size_t keySize, void const* value, size_t valueSize) {
@@ -51,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