renderdiff: Use single lib for osmesa (#8255 )

Previously, we linked against libOSMesa through the linker and then used dlopen to link against libGL. This is not how libOSMesa is intended to be used. Instead, we use dlopen on libOSMesa (via bluegl), which then will map the correct GL methods for us, and for the OSMesa functions, we also map those functions from libOSMesa (instead of relying on compile-time linker).
vk: remove incorrect assert
2024-11-07 15:42:44 -08:00 · 2024-10-28 15:54:09 -07:00 · 2024-10-18 16:42:52 -04:00 · 2024-10-14 06:07:43 +00:00 · 2024-10-14 06:07:34 +00:00 · 2024-10-11 23:09:32 +00:00
758 changed files with 58046 additions and 34852 deletions
@@ -0,0 +1,17 @@
+name: 'Android Continuous'
+inputs:
+  build-abi:
+    description: 'The target platform ABI'
+    required: true
+    default: 'armeabi-v7a'
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-java@v3
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+    - name: Run build script
+      run: |
+        cd build/android && printf "y" | ./build.sh continuous ${{ inputs.build-abi }}
+      shell: bash
@@ -0,0 +1,9 @@
+name: 'ubuntu apt add deb-src'
+runs:
+  using: "composite"
+  steps:
+    - name: "ubuntu apt add deb-src"
+      run: |
+          echo "deb-src http://archive.ubuntu.com/ubuntu jammy main restricted universe" | sudo tee /etc/apt/sources.list.d/my.list
+          sudo apt-get update
+      shell: bash
@@ -10,30 +10,13 @@ on:
 jobs:
  build-android:
    name: build-android
-    runs-on: macos-14
+    # We intentially use a larger runner here to enable larger disk space
+    # (standard linux runner will fail on disk space and faster build time).
+    runs-on: ubuntu-22.04-32core

    steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-java@v3
+      - uses: actions/checkout@v4.1.6
+      - name: Run Android Continuous
+        uses: ./.github/actions/android-continuous
        with:
-          distribution: 'temurin'
-          java-version: '17'
-      - name: Run build script
-        run: |
-          cd build/android && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filament-android
-          path: out/filament-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filamat-android-full
-          path: out/filamat-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: gltfio-android-release
-          path: out/gltfio-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filament-utils-android-release
-          path: out/filament-utils-android-release.aar
+          build-abi: armeabi-v7a,arm64-v8a,x86_64
@@ -10,14 +10,14 @@ on:
 jobs:
  build-ios:
    name: build-ios
-    runs-on: macos-14
+    runs-on: macos-14-xlarge

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/ios && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
        with:
          name: filament-ios
          path: out/filament-release-ios.tgz
@@ -10,14 +10,14 @@ on:
 jobs:
  build-linux:
    name: build-linux
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-22.04-16core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/linux && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
        with:
          name: filament-linux
          path: out/filament-release-linux.tgz
@@ -10,14 +10,14 @@ on:
 jobs:
  build-mac:
    name: build-mac
-    runs-on: macos-14
+    runs-on: macos-14-xlarge

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/mac && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
        with:
          name: filament-mac
          path: out/filament-release-darwin.tgz
@@ -13,7 +13,7 @@ jobs:
    name: npm-deploy
    runs-on: macos-14
    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ github.event.inputs.release_tag }}
      # Setup .npmrc file to publish to npm
@@ -15,10 +15,10 @@ jobs:

    strategy:
      matrix:
-        os: [macos-14, ubuntu-22.04]
+        os: [macos-14-xlarge, ubuntu-22.04-16core]

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          WORKFLOW_OS=`echo \`uname\` | sed "s/Darwin/mac/" | tr [:upper:] [:lower:]`
@@ -29,10 +29,10 @@ jobs:

  build-windows:
    name: build-windows
-    runs-on: windows-2019
+    runs-on: win-2019-16core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          build\windows\build-github.bat presubmit
@@ -40,24 +40,26 @@ jobs:

  build-android:
    name: build-android
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
      - name: Run build script
+        # Only build 1 64 bit target during presubmit to cut down build times during presubmit
+        # Continuous builds will build everything
        run: |
-          cd build/android && printf "y" | ./build.sh presubmit
+          cd build/android && printf "y" | ./build.sh presubmit arm64-v8a

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

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/ios && printf "y" | ./build.sh presubmit
@@ -67,10 +69,25 @@ jobs:

  build-web:
    name: build-web
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/web && printf "y" | ./build.sh presubmit
+
+  test-renderdiff:
+    name: test-renderdiff
+    runs-on: ubuntu-22.04-32core
+
+    steps:
+      - uses: actions/checkout@v4.1.6
+      - uses: ./.github/actions/ubuntu-apt-add-src
+      - name: Run script
+        run: |
+          source ./build/linux/ci-common.sh && bash test/renderdiff_tests.sh
+      - uses: actions/upload-artifact@v4
+        with:
+          name: presubmit-renderdiff-result
+          path: ./out/renderdiff_tests
@@ -31,7 +31,7 @@ jobs:

    strategy:
      matrix:
-        os: [macos-14, ubuntu-22.04]
+        os: [macos-14-xlarge, ubuntu-22.04-32core]

    steps:
      - name: Decide Git ref
@@ -41,7 +41,7 @@ jobs:
          TAG=${REF##*/}
          echo "ref=${REF}" >> $GITHUB_OUTPUT
          echo "tag=${TAG}" >> $GITHUB_OUTPUT
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ steps.git_ref.outputs.ref }}
      - name: Run build script
@@ -65,7 +65,7 @@ jobs:

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

    steps:
@@ -76,7 +76,7 @@ jobs:
          TAG=${REF##*/}
          echo "ref=${REF}" >> $GITHUB_OUTPUT
          echo "tag=${TAG}" >> $GITHUB_OUTPUT
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ steps.git_ref.outputs.ref }}
      - name: Run build script
@@ -98,7 +98,7 @@ jobs:

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

    steps:
@@ -109,7 +109,7 @@ jobs:
          TAG=${REF##*/}
          echo "ref=${REF}" >> $GITHUB_OUTPUT
          echo "tag=${TAG}" >> $GITHUB_OUTPUT
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ steps.git_ref.outputs.ref }}
      - uses: actions/setup-java@v3
@@ -120,7 +120,7 @@ jobs:
        env:
          TAG: ${{ steps.git_ref.outputs.tag }}
        run: |
-          cd build/android && printf "y" | ./build.sh release
+          cd build/android && printf "y" | ./build.sh release armeabi-v7a,arm64-v8a,x86,x86_64
          cd ../..
          mv out/filament-android-release.aar out/filament-${TAG}-android.aar
          mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
@@ -152,7 +152,7 @@ jobs:

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

    steps:
@@ -163,7 +163,7 @@ jobs:
          TAG=${REF##*/}
          echo "ref=${REF}" >> $GITHUB_OUTPUT
          echo "tag=${TAG}" >> $GITHUB_OUTPUT
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ steps.git_ref.outputs.ref }}
      - name: Run build script
@@ -185,7 +185,7 @@ jobs:

  build-windows:
    name: build-windows
-    runs-on: windows-2019
+    runs-on: windows-2019-32core
    if: github.event_name == 'release' || github.event.inputs.platform == 'windows'

    steps:
@@ -197,7 +197,7 @@ jobs:
          echo "ref=${REF}" >> $GITHUB_OUTPUT
          echo "tag=${TAG}" >> $GITHUB_OUTPUT
        shell: bash
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
        with:
          ref: ${{ steps.git_ref.outputs.ref }}
      - name: Run build script
@@ -205,6 +205,7 @@ jobs:
          TAG: ${{ steps.git_ref.outputs.tag }}
        run: |
          build\windows\build-github.bat release
+          echo on
          move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
        shell: cmd
      - uses: actions/github-script@v6
@@ -10,14 +10,14 @@ on:
 jobs:
  build-web:
    name: build-web
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          cd build/web && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
        with:
          name: filament-web
          path: out/filament-release-web.tgz
@@ -10,15 +10,15 @@ on:
 jobs:
  build-windows:
    name: build-windows
-    runs-on: windows-2019
+    runs-on: windows-2019-32core

    steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
      - name: Run build script
        run: |
          build\windows\build-github.bat continuous
        shell: cmd
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
        with:
          name: filament-windows
          path: out/filament-windows.tgz
@@ -73,7 +73,6 @@ The following CMake options are boolean options specific to Filament:
 - `FILAMENT_SUPPORTS_VULKAN`:      Include the Vulkan backend
 - `FILAMENT_INSTALL_BACKEND_TEST`: Install the backend test library so it can be consumed on iOS
 - `FILAMENT_USE_EXTERNAL_GLES3`:   Experimental: Compile Filament against OpenGL ES 3
- `FILAMENT_USE_SWIFTSHADER`:      Compile Filament against SwiftShader
 - `FILAMENT_SKIP_SAMPLES`:         Don't build sample apps

 To turn an option on or off:
@@ -426,7 +425,7 @@ value is the desired roughness between 0 and 1.

 ## Generating C++ documentation

-To generate the documentation you must first install `doxygen` and `graphviz`, then run the 
+To generate the documentation you must first install `doxygen` and `graphviz`, then run the
 following commands:

 ```shell
@@ -436,32 +435,62 @@ doxygen docs/doxygen/filament.doxygen

 Finally simply open `docs/html/index.html` in your web browser.

-## SwiftShader
+## Software Rasterization

-To try out Filament's Vulkan support with SwiftShader, first build SwiftShader and set the
-`SWIFTSHADER_LD_LIBRARY_PATH` variable to the folder that contains `libvk_swiftshader.dylib`:
+We have tested swiftshader and Mesa for software rasterization on the Vulkan/GL backends.
+
+To use this for Vulkan, please first make sure that the [Vulkan SDK](https://www.lunarg.com/vulkan-sdk/) is
+installed on your machine. If you are doing a manual installation of the SDK on Linux, you will have
+to source `setup-env.sh` in the SDK's root folder to make sure the Vulkan loader is the first lib loaded.
+
+### Swiftshader (Vulkan) [tested on macOS and Linux]
+
+First, build SwiftShader

 ```shell
 git clone https://github.com/google/swiftshader.git
 cd swiftshader/build
 cmake .. &&  make -j
-export SWIFTSHADER_LD_LIBRARY_PATH=`pwd`
 ```

-Next, go to your Filament repo and use the [easy build](#easy-build) script with `-t`.
+and then set `VK_ICD_FILENAMES` to the ICD json produced in the build. For example,
+```shell
+export VK_ICD_FILENAMES=/Users/user/swiftshader/build/Darwin/vk_swiftshader_icd.json
+```

-## SwiftShader for CI
+Build and run Filament as usual and specify the Vulkan backend when creating the Engine.

-Continuous testing turnaround can be quite slow if you need to build SwiftShader from scratch, so we
-provide an Ubuntu-based Docker image that has it already built. The Docker image also includes
-everything necessary for building Filament. You can fetch and run the image as follows:
+### Mesa's LLVMPipe (GL) and Lavapipe (Vulkan) [tested on Linux]
+
+We will only cover steps that build Mesa from source. The official documentation of Mesa mentioned
+that in general precompiled libraries [are **not** made available](https://docs.mesa3d.org/precompiled.html).
+
+Download the repo and make sure you have the build depedencies. For example (assuming an Ubuntu/Debian distro),
+```shell
+git clone https://gitlab.freedesktop.org/mesa/mesa.git
+sudo apt-get build-dep mesa
+```
+
+To build both the GL and Vulkan rasterizers,

 ```shell
-docker pull ghcr.io/filament-assets/swiftshader
-docker run -it ghcr.io/filament-assets/swiftshader
+cd mesa
+mkdir -p out
+meson setup builddir/ -Dprefix=$(pwd)/out -Dglx=xlib -Dgallium-drivers=swrast -Dvulkan-drivers=swrast
+meson install -C builddir/
 ```

-To do more with the container, see the helper script at `build/swiftshader/test.sh`.
+For GL, we need to ensure that we load the GL lib from the mesa output directory.  For example, to run
+the debug `gltf_viewer`, we would execute
+```shell
+LD_LIBRARY_PATH=/Users/user/mesa/out/lib/x86_64-linux-gnu \
+    ./out/cmake-debug/samples/gltf_viewer -a opengl
+```

-If you are a team member, you can update the public image to the latest SwiftShader by
-following the instructions at the top of `build/swiftshader/Dockerfile`.
+For Vulkan, we need to set the path to the ICD json, which tells the loader where to find the driver
+library. To run `gltf_viewer`, we would execute
+```shell
+VK_ICD_FILENAMES=/Users/user/mesa/out/share/vulkan/icd.d/lvp_icd.x86_64.json \
+    ./out/cmake-debug/samples/gltf_viewer -a vulkan
+
+```
@@ -21,8 +21,6 @@ project(TNT)
 # ==================================================================================================
 option(FILAMENT_USE_EXTERNAL_GLES3 "Experimental: Compile Filament against OpenGL ES 3" OFF)

-option(FILAMENT_USE_SWIFTSHADER "Compile Filament against SwiftShader" OFF)
-
 option(FILAMENT_ENABLE_LTO "Enable link-time optimizations if supported by the compiler" OFF)

 option(FILAMENT_SKIP_SAMPLES "Don't build samples" OFF)
@@ -45,6 +43,10 @@ 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)
+
+option(FILAMENT_SUPPORTS_OSMESA "Enable OSMesa (headless GL context) for Filament" OFF)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
    "Android NDK version or version prefix to be used when building for Android."
 )
@@ -69,6 +71,14 @@ set(FILAMENT_METAL_HANDLE_ARENA_SIZE_IN_MB "8" CACHE STRING
    "Size of the Metal handle arena, default 8."
 )

+set(FILAMENT_BACKEND_DEBUG_FLAG "" CACHE STRING
+    "A debug flag meant for enabling/disabling backend debugging paths"
+)
+
+set(FILAMENT_OSMESA_PATH "" CACHE STRING
+    "Path to the OSMesa header and lib"
+)
+
 # Enable exceptions by default in spirv-cross.
 set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS OFF)

@@ -128,22 +138,27 @@ else()
 endif()

 if (LINUX)
+    if (NOT FILAMENT_OSMESA_PATH STREQUAL "")
+        if (NOT EXISTS ${FILAMENT_OSMESA_PATH}/)
+            message(FATAL_ERROR "Cannot find specified OSMesa build directory: ${FILAMENT_OSMESA_PATH}")
+        endif()
+        set(FILAMENT_SUPPORTS_OSMESA TRUE)
+    endif()
+
    if (FILAMENT_SUPPORTS_WAYLAND)
        add_definitions(-DFILAMENT_SUPPORTS_WAYLAND)
        set(FILAMENT_SUPPORTS_X11 FALSE)
    elseif (FILAMENT_SUPPORTS_EGL_ON_LINUX)
        add_definitions(-DFILAMENT_SUPPORTS_EGL_ON_LINUX)
        set(FILAMENT_SUPPORTS_X11 FALSE)
+    elseif (FILAMENT_SUPPORTS_OSMESA)
+        set(FILAMENT_SUPPORTS_X11 FALSE)
+        add_definitions(-DFILAMENT_SUPPORTS_OSMESA)
    else ()
        if (FILAMENT_SUPPORTS_XCB)
            add_definitions(-DFILAMENT_SUPPORTS_XCB)
        endif()

-        # Default Swiftshader build does not enable the xlib extension
-        if (FILAMENT_SUPPORTS_XLIB AND FILAMENT_USE_SWIFTSHADER)
-            set(FILAMENT_SUPPORTS_XLIB OFF)
-        endif()
-
        if (FILAMENT_SUPPORTS_XLIB)
            add_definitions(-DFILAMENT_SUPPORTS_XLIB)
        endif()
@@ -167,15 +182,6 @@ if (NOT ANDROID AND NOT WEBGL AND NOT IOS AND NOT FILAMENT_LINUX_IS_MOBILE)
    set(IS_HOST_PLATFORM TRUE)
 endif()

-if (IOS)
-    # Remove the headerpad_max_install_names linker flag on iOS. It causes warnings when linking
-    # executables with bitcode.
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_C_LINK_FLAGS ${CMAKE_C_LINK_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_CXX_LINK_FLAGS ${CMAKE_CXX_LINK_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS ${CMAKE_SHARED_LIBRARY_CREATE_C_FLAGS})
-    string(REPLACE "-Wl,-headerpad_max_install_names" "" CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS ${CMAKE_SHARED_LIBRARY_CREATE_CXX_FLAGS})
-endif()
-
 if (WIN32)
    # Link statically against c/c++ lib to avoid missing redistriburable such as
    # "VCRUNTIME140.dll not found. Try reinstalling the app.", but give users
@@ -330,10 +336,6 @@ if (FILAMENT_SUPPORTS_EGL_ON_LINUX)
  set(EGL TRUE)
 endif()

-if (FILAMENT_USE_SWIFTSHADER)
-    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DFILAMENT_USE_SWIFTSHADER")
-endif()
-
 if (WIN32)
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -D_USE_MATH_DEFINES=1")
 endif()
@@ -387,8 +389,9 @@ endif()
 if (NOT MSVC AND NOT IOS)
    # Omitting stack frame pointers prevents the generation of readable stack traces in crash reports on iOS
    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer")
+endif()

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

@@ -453,8 +456,13 @@ endif()
 if (NOT WEBGL)
    set(GC_SECTIONS "-Wl,--gc-sections")
 endif()
+
 set(B_SYMBOLIC_FUNCTIONS "-Wl,-Bsymbolic-functions")

+if (ANDROID)
+set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
+endif()
+
 if (APPLE)
    set(GC_SECTIONS "-Wl,-dead_strip")
    set(B_SYMBOLIC_FUNCTIONS "")
@@ -468,7 +476,7 @@ if (APPLE)
 endif()

 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
-set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS}")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS} ${BINARY_ALIGNMENT}")

 if (WEBGL_PTHREADS)
    set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -pthread")
@@ -531,6 +539,29 @@ 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", "multiview", or "none"
+set(FILAMENT_SAMPLES_STEREO_TYPE "none" 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"
+    AND NOT FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "none")
+    message(FATAL_ERROR "Invalid stereo type: \"${FILAMENT_SAMPLES_STEREO_TYPE}\" choose either \"instanced\",  \"multiview\", or \"none\" ")
+endif ()
+
+# Compiling samples for multiview implies enabling multiview feature as well.
+if (FILAMENT_SAMPLES_STEREO_TYPE STREQUAL "multiview")
+    set(FILAMENT_ENABLE_MULTIVIEW ON)
+endif ()
+
+# Define backend flag for debug only
+if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND NOT FILAMENT_BACKEND_DEBUG_FLAG STREQUAL "")
+    add_definitions(-DFILAMENT_BACKEND_DEBUG_FLAG=${FILAMENT_BACKEND_DEBUG_FLAG})
+    unset(FILAMENT_BACKEND_DEBUG_FLAG)
+endif()
+
 # ==================================================================================================
 # Material compilation flags
 # ==================================================================================================
@@ -659,21 +690,6 @@ else()
    set(IMPORT_EXECUTABLES ${FILAMENT}/${IMPORT_EXECUTABLES_DIR}/ImportExecutables-${CMAKE_BUILD_TYPE}.cmake)
 endif()

-# ==================================================================================================
-# Try to find Vulkan if the SDK is installed, otherwise fall back to the bundled version.
-# This needs to stay in our top-level CMakeLists because it sets up variables that are used by the
-# "bluevk" and "samples" targets.
-# ==================================================================================================
-
-if (FILAMENT_USE_SWIFTSHADER)
-    if (NOT FILAMENT_SUPPORTS_VULKAN)
-        message(ERROR "SwiftShader is only useful when Vulkan is enabled.")
-    endif()
-    find_library(SWIFTSHADER_VK NAMES vk_swiftshader HINTS "$ENV{SWIFTSHADER_LD_LIBRARY_PATH}")
-    message(STATUS "Found SwiftShader VK library in: ${SWIFTSHADER_VK}.")
-    add_definitions(-DFILAMENT_VKLIBRARY_PATH=\"${SWIFTSHADER_VK}\")
-endif()
-
 # ==================================================================================================
 # Common Functions
 # ==================================================================================================
@@ -735,7 +751,6 @@ add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
-add_subdirectory(${EXTERNAL}/hat-trie/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)
 add_subdirectory(${EXTERNAL}/robin-map/tnt)
 add_subdirectory(${EXTERNAL}/smol-v/tnt)
@@ -802,6 +817,9 @@ if (IS_HOST_PLATFORM)
    add_subdirectory(${TOOLS}/glslminifier)
    add_subdirectory(${TOOLS}/matc)
    add_subdirectory(${TOOLS}/matinfo)
+    if (NOT WIN32)  # matedit not yet supported on Windows
+        add_subdirectory(${TOOLS}/matedit)
+    endif()
    add_subdirectory(${TOOLS}/mipgen)
    add_subdirectory(${TOOLS}/normal-blending)
    add_subdirectory(${TOOLS}/resgen)
@@ -31,7 +31,7 @@ repositories {
 }

 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.50.6'
+    implementation 'com.google.android.filament:filament-android:1.55.1'
 }
 ```

@@ -51,19 +51,9 @@ 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.50.6'
+pod 'Filament', '~> 1.55.1'
 ```

-### Snapshots
-
-If you prefer to live on the edge, you can download a continuous build by following the following
-steps:
-
-1. Find the [commit](https://github.com/google/filament/commits/main) you're interested in.
-2. Click the green check mark under the commit message.
-3. Click on the _Details_ link for the platform you're interested in.
-4. On the top left click _Summary_, then in the _Artifacts_ section choose the desired artifact.
-
 ## Documentation

 - [Filament](https://google.github.io/filament/Filament.html), an in-depth explanation of
@@ -176,6 +166,7 @@ steps:
  - [x] KHR_materials_unlit
  - [x] KHR_materials_variants
  - [x] KHR_materials_volume
+  - [x] KHR_materials_specular
  - [x] KHR_mesh_quantization
  - [x] KHR_texture_basisu
  - [x] KHR_texture_transform
@@ -7,6 +7,108 @@ 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.55.1
+
+
+## v1.55.0
+- Add descriptor sets to describe shader resources. [⚠️ **New Material Version**]
+
+## v1.54.5
+
+
+## v1.54.4
+
+- Add support for multi-layered render target with array textures.
+
+## v1.54.3
+
+
+## v1.54.2
+
+- Add a `name` API to Filament objects for debugging handle use-after-free assertions
+
+## v1.54.1
+
+
+## v1.54.0
+
+- materials: add a new `stereoscopicType` material parameter. [⚠️ **New Material Version**]
+- Fix a crash when compiling shaders on IMG devices
+
+## v1.53.5
+
+- engine: Fix bug causing certain sampler parameters to not be applied correctly in GLES 2.0 and on
+  certain GLES 3.0 drivers.
+
+## v1.53.4
+
+
+## v1.53.3
+
+- Add drag and drop support for IBL files for desktop gltf_viewer.
+
+## v1.53.2
+
+
+## v1.53.1
+
+
+## v1.53.0
+
+- engine: fix skinning normals with large transforms (b/342459864) [⚠️ **New Material Version**]
+
+## v1.52.3
+
+
+## v1.52.2
+
+
+## v1.52.1
+
+- Add instructions for using Mesa for software rasterization
+
+## v1.51.9
+
+
+## v1.51.8
+
+- filagui: Fix regression which broke WebGL
+- Add a new Engine::Config setting to control preferred shader language
+- Add `getEyeIndex` vertex API
+- ios: Remove bitcode from iOS builds
+
+## v1.51.7
+
+- Add new matedit tool
+- filagui: Support rendering `GL_TEXTURE_EXTERNAL_OES` textures.
+- `setFrameScheduledCallback` now takes a `utils::Invocable`.
+- engine: Add `isPaused()`
+
+## v1.51.6
+
+- Add new matedit tool
+- filagui: Support rendering `GL_TEXTURE_EXTERNAL_OES` textures.
+
+## v1.51.5
+
+
+## v1.51.4
+
+
+## v1.51.3
+
+
+## v1.51.2
+
+- engine: Add experimental APIs `Engine::builder::paused()` and `Engine::setPaused()`
+
+## v1.51.1
+
+
+## v1.51.0
+
+- materials: add support for post-lighting mix factor (b/328498606) [⚠️ **New Material Version**]
+
 ## v1.50.6

 - Add new API `SwapChain::getFrameScheduledCallback`
@@ -83,12 +83,12 @@ buildscript {
        'minSdk': 21,
        'targetSdk': 34,
        'compileSdk': 34,
-        'kotlin': '1.9.21',
-        'kotlin_coroutines': '1.7.3',
+        'kotlin': '2.0.0',
+        'kotlin_coroutines': '1.9.0-RC',
        'buildTools': '34.0.0',
-        'ndk': '26.1.10909125',
-        'androidx_core': '1.12.0',
-        'androidx_annotations': '1.7.0'
+        'ndk': '27.0.11718014',
+        'androidx_core': '1.13.1',
+        'androidx_annotations': '1.8.0'
    ]

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

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

@@ -38,6 +38,7 @@ set(FILAMAT_INCLUDE_DIRS
 include_directories(${FILAMENT_DIR}/include)

 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_SOURCE_DIR}/libfilamat-jni.map")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")

 add_library(filamat-jni SHARED src/main/cpp/MaterialBuilder.cpp)
 target_include_directories(filamat-jni PRIVATE ${FILAMAT_INCLUDE_DIRS})
@@ -59,6 +59,7 @@ endif()

 set(VERSION_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/libfilament-jni.map")
 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${VERSION_SCRIPT}")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")

 add_library(filament-jni SHARED
    src/main/cpp/BufferObject.cpp
@@ -342,6 +342,21 @@ Java_com_google_android_filament_Engine_nIsValidMaterial(JNIEnv*, jclass,
    return (jboolean)engine->isValid((Material*)nativeMaterial);
 }

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

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

 extern "C" JNIEXPORT jlong JNICALL
@@ -484,10 +520,12 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
 extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*,
        jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB,
        jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB,
-        jlong jobSystemThreadCount,
-        jlong textureUseAfterFreePoolSize, jboolean disableParallelShaderCompile,
+        jlong jobSystemThreadCount, jboolean disableParallelShaderCompile,
        jint stereoscopicType, jlong stereoscopicEyeCount,
-        jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge) {
+        jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
+        jboolean disableHandleUseAfterFreeCheck,
+        jint preferredShaderLanguage,
+        jboolean forceGLES2Context, jboolean assertNativeWindowIsValid) {
    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
    Engine::Config config = {
            .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -496,12 +534,15 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
            .minCommandBufferSizeMB = (uint32_t) minCommandBufferSizeMB,
            .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
            .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
-            .textureUseAfterFreePoolSize = (uint32_t) textureUseAfterFreePoolSize,
            .disableParallelShaderCompile = (bool) disableParallelShaderCompile,
            .stereoscopicType = (Engine::StereoscopicType) stereoscopicType,
            .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
            .resourceAllocatorCacheSizeMB = (uint32_t) resourceAllocatorCacheSizeMB,
            .resourceAllocatorCacheMaxAge = (uint8_t) resourceAllocatorCacheMaxAge,
+            .disableHandleUseAfterFreeCheck = (bool) disableHandleUseAfterFreeCheck,
+            .preferredShaderLanguage = (Engine::Config::ShaderLanguage) preferredShaderLanguage,
+            .forceGLES2Context = (bool) forceGLES2Context,
+            .assertNativeWindowIsValid = (bool) assertNativeWindowIsValid,
    };
    builder->config(&config);
 }
@@ -518,8 +559,20 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
    builder->sharedContext((void*) sharedContext);
 }

+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderPaused(
+        JNIEnv*, jclass, jlong nativeBuilder, jboolean paused) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->paused((bool) paused);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder) {
    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
    return (jlong) builder->build();
 }
+
+extern "C"
+JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_getSteadyClockTimeNano(JNIEnv *env, jclass clazz) {
+    return (jlong)Engine::getSteadyClockTimeNano();
+}
@@ -25,12 +25,17 @@ using namespace filament;

 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Material_nBuilderBuild(JNIEnv *env, jclass,
-        jlong nativeEngine, jobject buffer_, jint size) {
+        jlong nativeEngine, jobject buffer_, jint size, jint shBandCount) {
    Engine* engine = (Engine*) nativeEngine;
    AutoBuffer buffer(env, buffer_, size);
-    Material* material = Material::Builder()
+    auto builder = Material::Builder();
+    if (shBandCount) {
+        builder.sphericalHarmonicsBandCount(shBandCount);
+    }
+    Material* material = builder
            .package(buffer.getData(), buffer.getSize())
            .build(*engine);
+
    return (jlong) material;
 }

@@ -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,
@@ -237,12 +245,18 @@ Java_com_google_android_filament_RenderableManager_nBuilderMorphing(JNIEnv*, jcl
 }

 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_RenderableManager_nBuilderSetMorphTargetBufferAt(JNIEnv*, jclass,
-        jlong nativeBuilder, int level, int primitiveIndex, jlong nativeMorphTargetBuffer,
-        int offset, int count) {
+Java_com_google_android_filament_RenderableManager_nBuilderMorphingStandard(JNIEnv*, jclass,
+        jlong nativeBuilder, jlong nativeMorphTargetBuffer) {
    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
    MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
-    builder->morphing(level, primitiveIndex, morphTargetBuffer, offset, count);
+    builder->morphing(morphTargetBuffer);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderSetMorphTargetBufferOffsetAt(JNIEnv*, jclass,
+        jlong nativeBuilder, int level, int primitiveIndex, int offset) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    builder->morphing(level, primitiveIndex, offset);
 }

 extern "C" JNIEXPORT void JNICALL
@@ -314,13 +328,12 @@ Java_com_google_android_filament_RenderableManager_nSetMorphWeights(JNIEnv* env,
 }

 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_RenderableManager_nSetMorphTargetBufferAt(JNIEnv*,
+Java_com_google_android_filament_RenderableManager_nSetMorphTargetBufferOffsetAt(JNIEnv*,
        jclass, jlong nativeRenderableManager, jint i, int level, jint primitiveIndex,
-        jlong nativeMorphTargetBuffer, jint offset, jint count) {
+        jlong, jint offset) {
    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
-    MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
-    rm->setMorphTargetBufferAt((RenderableManager::Instance) i, (uint8_t) level,
-            (size_t) primitiveIndex, morphTargetBuffer, (size_t) offset, (size_t) count);
+    rm->setMorphTargetBufferOffsetAt((RenderableManager::Instance) i, (uint8_t) level,
+            (size_t) primitiveIndex, (size_t) offset);
 }

 extern "C" JNIEXPORT jint JNICALL
@@ -28,6 +28,14 @@
 using namespace filament;
 using namespace backend;

+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Renderer_nSkipFrame(JNIEnv *, jclass, jlong nativeRenderer,
+        jlong vsyncSteadyClockTimeNano) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    renderer->skipFrame(uint64_t(vsyncSteadyClockTimeNano));
+}
+
 extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_Renderer_nBeginFrame(JNIEnv *, jclass, jlong nativeRenderer,
        jlong nativeSwapChain, jlong frameTimeNanos) {
@@ -187,3 +195,10 @@ Java_com_google_android_filament_Renderer_nSetPresentationTime(JNIEnv *, jclass
    Renderer *renderer = (Renderer *) nativeRenderer;
    renderer->setPresentationTime(monotonicClockNanos);
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Renderer_nSetVsyncTime(JNIEnv *, jclass,
+    jlong nativeRenderer, jlong steadyClockTimeNano) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    renderer->setVsyncTime(steadyClockTimeNano);
+}
@@ -49,6 +49,12 @@ Java_com_google_android_filament_View_nSetCamera(JNIEnv*, jclass,
    view->setCamera(camera);
 }

+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nHasCamera(JNIEnv*, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return (jboolean)view->hasCamera();
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetColorGrading(JNIEnv*, jclass,
        jlong nativeView, jlong nativeColorGrading) {
@@ -525,3 +531,12 @@ Java_com_google_android_filament_View_nGetFogEntity(JNIEnv *env, jclass clazz,
    View *view = (View *) nativeView;
    return (jint)view->getFogEntity().getId();
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nClearFrameHistory(JNIEnv *env, jclass clazz,
+        jlong nativeView, jlong nativeEngine) {
+    View *view = (View *) nativeView;
+    Engine *engine = (Engine *) nativeEngine;
+    view->clearFrameHistory(*engine);
+}
@@ -159,9 +159,12 @@ public class Engine {
    };

    /**
-     * The type of technique for stereoscopic rendering
+     * The type of technique for stereoscopic rendering. (Note that the materials used will need to be
+     * compatible with the chosen technique.)
     */
    public enum StereoscopicType {
+        /** No stereoscopic rendering. */
+        NONE,
        /** Stereoscopic rendering is performed using instanced rendering technique. */
        INSTANCED,
        /** Stereoscopic rendering is performed using the multiview feature from the graphics backend. */
@@ -221,10 +224,12 @@ public class Engine {
            nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
                    config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
                    config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
-                    config.jobSystemThreadCount,
-                    config.textureUseAfterFreePoolSize, config.disableParallelShaderCompile,
+                    config.jobSystemThreadCount, config.disableParallelShaderCompile,
                    config.stereoscopicType.ordinal(), config.stereoscopicEyeCount,
-                    config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge);
+                    config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
+                    config.disableHandleUseAfterFreeCheck,
+                    config.preferredShaderLanguage.ordinal(),
+                    config.forceGLES2Context, config.assertNativeWindowIsValid);
            return this;
        }

@@ -239,6 +244,20 @@ public class Engine {
            return this;
        }

+        /**
+         * Sets the initial paused state of the rendering thread.
+         *
+         * <p>Warning: This is an experimental API. See {@link Engine#setPaused(boolean)} for
+         * caveats.
+         *
+         * @param paused Whether to start the rendering thread paused.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder paused(boolean paused) {
+            nSetBuilderPaused(mNativeBuilder, paused);
+            return this;
+        }
+
        /**
         * Creates an instance of Engine
         *
@@ -388,7 +407,7 @@ public class Engine {
         *
         * @see View#setStereoscopicOptions
         */
-        public StereoscopicType stereoscopicType = StereoscopicType.INSTANCED;
+        public StereoscopicType stereoscopicType = StereoscopicType.NONE;

        /**
         * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
@@ -399,15 +418,59 @@ public class Engine {
         */
        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.
+        /**
+         * This value determines how many frames texture entries are kept for in the cache. This
+         * is a soft limit, meaning some texture older than this are allowed to stay in the cache.
+         * Typically only one texture is evicted per frame.
+         * The default is 1.
         */
-        public long resourceAllocatorCacheMaxAge = 2;
+        public long resourceAllocatorCacheMaxAge = 1;
+
+        /**
+         * Disable backend handles use-after-free checks.
+         */
+        public boolean disableHandleUseAfterFreeCheck = false;
+
+        /**
+         * Sets a preferred shader language for Filament to use.
+         *
+         * The Metal backend supports two shader languages: MSL (Metal Shading Language) and
+         * METAL_LIBRARY (precompiled .metallib). This option controls which shader language is
+         * used when materials contain both.
+         *
+         * By default, when preferredShaderLanguage is unset, Filament will prefer METAL_LIBRARY
+         * shaders if present within a material, falling back to MSL. Setting
+         * preferredShaderLanguage to ShaderLanguage::MSL will instead instruct Filament to check
+         * for the presence of MSL in a material first, falling back to METAL_LIBRARY if MSL is not
+         * present.
+         *
+         * When using a non-Metal backend, setting this has no effect.
+         */
+        public enum ShaderLanguage {
+            DEFAULT,
+            MSL,
+            METAL_LIBRARY,
+        };
+        public ShaderLanguage preferredShaderLanguage = ShaderLanguage.DEFAULT;
+
+        /**
+         * When the OpenGL ES backend is used, setting this value to true will force a GLES2.0
+         * context if supported by the Platform, or if not, will have the backend pretend
+         * it's a GLES2 context. Ignored on other backends.
+         */
+        public boolean forceGLES2Context = false;
+
+        /**
+         * Assert the native window associated to a SwapChain is valid when calling makeCurrent().
+         * This is only supported for:
+         *      - PlatformEGLAndroid
+         */
+        public boolean assertNativeWindowIsValid = false;
    }

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

    /**
@@ -662,15 +725,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
@@ -688,21 +751,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);
        }
@@ -714,11 +778,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) {
@@ -827,6 +892,24 @@ public class Engine {
        return nIsValidMaterial(getNativeObject(), object.getNativeObject());
    }

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

+    /**
+     * Get paused state of rendering thread.
+     *
+     * <p>Warning: This is an experimental API.
+     *
+     * @see #setPaused
+     */
+    public boolean isPaused() {
+        return nIsPaused(getNativeObject());
+    }
+
+    /**
+     * Pause or resume the rendering thread.
+     *
+     * <p>Warning: This is an experimental API. In particular, note the following caveats.
+     *
+     * <ul><li>
+     * Buffer callbacks will never be called as long as the rendering thread is paused.
+     * Do not rely on a buffer callback to unpause the thread.
+     * </li><li>
+     * While the rendering thread is paused, rendering commands will continue to be queued until the
+     * buffer limit is reached. When the limit is reached, the program will abort.
+     * </li></ul>
+     */
+    public void setPaused(boolean paused) {
+        nSetPaused(getNativeObject(), paused);
+    }
+
+    /**
+     * Switch the command queue to unprotected mode. Protected mode can be activated via
+     * Renderer::beginFrame() using a protected SwapChain.
+     * @see Renderer
+     * @see SwapChain
+     */
+    public void unprotected() {
+        nUnprotected(getNativeObject());
+    }
+
+    /**
+     * Get the current time. This is a convenience function that simply returns the
+     * time in nanosecond since epoch of std::chrono::steady_clock.
+     * @return current time in nanosecond since epoch of std::chrono::steady_clock.
+     * @see Renderer#beginFrame
+     */
+    public static native long getSteadyClockTimeNano();

    @UsedByReflection("TextureHelper.java")
    public long getNativeObject() {
@@ -1253,6 +1381,8 @@ public class Engine {
    private static native boolean nIsValidSkinningBuffer(long nativeEngine, long nativeSkinningBuffer);
    private static native boolean nIsValidIndirectLight(long nativeEngine, long nativeIndirectLight);
    private static native boolean nIsValidMaterial(long nativeEngine, long nativeMaterial);
+    private static native boolean nIsValidMaterialInstance(long nativeEngine, long nativeMaterial, long nativeMaterialInstance);
+    private static native boolean nIsValidExpensiveMaterialInstance(long nativeEngine, long nativeMaterialInstance);
    private static native boolean nIsValidSkybox(long nativeEngine, long nativeSkybox);
    private static native boolean nIsValidColorGrading(long nativeEngine, long nativeColorGrading);
    private static native boolean nIsValidTexture(long nativeEngine, long nativeTexture);
@@ -1261,6 +1391,9 @@ public class Engine {
    private static native void nDestroyEntity(long nativeEngine, int entity);
    private static native void nFlushAndWait(long nativeEngine);
    private static native void nFlush(long nativeEngine);
+    private static native boolean nIsPaused(long nativeEngine);
+    private static native void nSetPaused(long nativeEngine, boolean paused);
+    private static native void nUnprotected(long nativeEngine);
    private static native long nGetTransformManager(long nativeEngine);
    private static native long nGetLightManager(long nativeEngine);
    private static native long nGetRenderableManager(long nativeEngine);
@@ -1279,10 +1412,13 @@ public class Engine {
    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 disableParallelShaderCompile, int stereoscopicType, long stereoscopicEyeCount,
+            long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
+            boolean disableHandleUseAfterFreeCheck,
+            int preferredShaderLanguage,
+            boolean forceGLES2Context, boolean assertNativeWindowIsValid);
    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);
 }
@@ -346,6 +346,7 @@ public class Material {
    public static class Builder {
        private Buffer mBuffer;
        private int mSize;
+        private int mShBandCount = 0;

        /**
         * Specifies the material data. The material data is a binary blob produced by
@@ -361,6 +362,22 @@ public class Material {
            return this;
        }

+        /**
+         * Sets the quality of the indirect lights computations. This is only taken into account
+         * if this material is lit and in the surface domain. This setting will affect the
+         * IndirectLight computation if one is specified on the Scene and Spherical Harmonics
+         * are used for the irradiance.
+         *
+         * @param shBandCount Number of spherical harmonic bands. Must be 1, 2 or 3 (default).
+         * @return Reference to this Builder for chaining calls.
+         * @see IndirectLight
+         */
+        @NonNull
+        public Builder sphericalHarmonicsBandCount(@IntRange(from = 0) int shBandCount) {
+            mShBandCount = shBandCount;
+            return this;
+        }
+
        /**
         * Creates and returns the Material object.
         *
@@ -372,7 +389,8 @@ public class Material {
         */
        @NonNull
        public Material build(@NonNull Engine engine) {
-            long nativeMaterial = nBuilderBuild(engine.getNativeObject(), mBuffer, mSize);
+            long nativeMaterial = nBuilderBuild(engine.getNativeObject(),
+                mBuffer, mSize, mShBandCount);
            if (nativeMaterial == 0) throw new IllegalStateException("Couldn't create Material");
            return new Material(nativeMaterial);
        }
@@ -1023,7 +1041,7 @@ public class Material {
        mNativeObject = 0;
    }

-    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size);
+    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount);
    private static native long nCreateInstance(long nativeMaterial);
    private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
    private static native long nGetDefaultInstance(long nativeMaterial);
@@ -74,7 +74,7 @@ public class MorphTargetBuffer {
         *
         * @exception IllegalStateException if the MorphTargetBuffer could not be created
         *
-         * @see #setMorphTargetBufferAt
+         * @see #setMorphTargetBufferOffsetAt
         */
        @NonNull
        public MorphTargetBuffer build(@NonNull Engine engine) {
@@ -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.
         *
@@ -498,14 +524,7 @@ public class RenderableManager {
        }

        /**
-         * Controls if the renderable has vertex morphing targets, zero by default. This is
-         * required to enable GPU morphing.
-         *
-         * <p>Filament supports two morphing modes: standard (default) and legacy.</p>
-         *
-         * <p>For standard morphing, A {@link MorphTargetBuffer} must be created and provided via
-         * {@link RenderableManager#setMorphTargetBufferAt}. Standard morphing supports up to
-         * <code>CONFIG_MAX_MORPH_TARGET_COUNT</code> morph targets.</p>
+         * Controls if the renderable has legacy vertex morphing targets, zero by default.
         *
         * For legacy morphing, the attached {@link VertexBuffer} must provide data in the
         * appropriate {@link VertexBuffer.VertexAttribute} slots (<code>MORPH_POSITION_0</code> etc).
@@ -523,6 +542,22 @@ public class RenderableManager {
            return this;
        }

+        /**
+         * Controls if the renderable has vertex morphing targets, zero by default.
+         *
+         * <p>For standard morphing, A {@link MorphTargetBuffer} must be provided.
+         * Standard morphing supports up to
+         * <code>CONFIG_MAX_MORPH_TARGET_COUNT</code> morph targets.</p>
+         *
+         * <p>See also {@link RenderableManager#setMorphWeights}, which can be called on a per-frame basis
+         * to advance the animation.</p>
+         */
+        @NonNull
+        public Builder morphing(@NonNull MorphTargetBuffer morphTargetBuffer) {
+            nBuilderMorphingStandard(mNativeBuilder, morphTargetBuffer.getNativeObject());
+            return this;
+        }
+
        /**
         * Specifies the morph target buffer for a primitive.
         *
@@ -534,31 +569,13 @@ public class RenderableManager {
         *
         * @param level the level of detail (lod), only 0 can be specified
         * @param primitiveIndex zero-based index of the primitive, must be less than the count passed to Builder constructor
-         * @param morphTargetBuffer specifies the morph target buffer
         * @param offset specifies where in the morph target buffer to start reading (expressed as a number of vertices)
-         * @param count number of vertices in the morph target buffer to read, must equal the geometry's count (for triangles, this should be a multiple of 3)
         */
        @NonNull
        public Builder morphing(@IntRange(from = 0) int level,
                                @IntRange(from = 0) int primitiveIndex,
-                                @NonNull MorphTargetBuffer morphTargetBuffer,
-                                @IntRange(from = 0) int offset,
-                                @IntRange(from = 0) int count) {
-            nBuilderSetMorphTargetBufferAt(mNativeBuilder, level, primitiveIndex,
-                    morphTargetBuffer.getNativeObject(), offset, count);
-            return this;
-        }
-
-        /**
-         * Utility method to specify morph target buffer for a primitive.
-         * For details, see the {@link RenderableManager.Builder#morphing}.
-         */
-        @NonNull
-        public Builder morphing(@IntRange(from = 0) int level,
-                                @IntRange(from = 0) int primitiveIndex,
-                                @NonNull MorphTargetBuffer morphTargetBuffer) {
-            nBuilderSetMorphTargetBufferAt(mNativeBuilder, level, primitiveIndex,
-                    morphTargetBuffer.getNativeObject(), 0, morphTargetBuffer.getVertexCount());
+                                @IntRange(from = 0) int offset) {
+            nBuilderSetMorphTargetBufferOffsetAt(mNativeBuilder, level, primitiveIndex, offset);
            return this;
        }

@@ -661,26 +678,11 @@ public class RenderableManager {
     *
     * @see Builder#morphing
     */
-    public void setMorphTargetBufferAt(@EntityInstance int i,
+    public void setMorphTargetBufferOffsetAt(@EntityInstance int i,
                                       @IntRange(from = 0) int level,
                                       @IntRange(from = 0) int primitiveIndex,
-                                       @NonNull MorphTargetBuffer morphTargetBuffer,
-                                       @IntRange(from = 0) int offset,
-                                       @IntRange(from = 0) int count) {
-        nSetMorphTargetBufferAt(mNativeObject, i, level, primitiveIndex,
-                morphTargetBuffer.getNativeObject(), offset, count);
-    }
-
-    /**
-     * Utility method to change morph target buffer for the given primitive.
-     * For details, see the {@link RenderableManager#setMorphTargetBufferAt}.
-     */
-    public void setMorphTargetBufferAt(@EntityInstance int i,
-                                       @IntRange(from = 0) int level,
-                                       @IntRange(from = 0) int primitiveIndex,
-                                       @NonNull MorphTargetBuffer morphTargetBuffer) {
-        nSetMorphTargetBufferAt(mNativeObject, i, level, primitiveIndex,
-                morphTargetBuffer.getNativeObject(), 0, morphTargetBuffer.getVertexCount());
+                                       @IntRange(from = 0) int offset) {
+        nSetMorphTargetBufferOffsetAt(mNativeObject, i, level, primitiveIndex, 0, offset);
    }

    /**
@@ -964,6 +966,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);
@@ -979,7 +982,8 @@ public class RenderableManager {
    private static native int nBuilderSkinningBones(long nativeBuilder, int boneCount, Buffer bones, int remaining);
    private static native void nBuilderSkinningBuffer(long nativeBuilder, long nativeSkinningBuffer, int boneCount, int offset);
    private static native void nBuilderMorphing(long nativeBuilder, int targetCount);
-    private static native void nBuilderSetMorphTargetBufferAt(long nativeBuilder, int level, int primitiveIndex, long nativeMorphTargetBuffer, int offset, int count);
+    private static native void nBuilderMorphingStandard(long nativeBuilder, long nativeMorphTargetBuffer);
+    private static native void nBuilderSetMorphTargetBufferOffsetAt(long nativeBuilder, int level, int primitiveIndex, int offset);
    private static native void nBuilderEnableSkinningBuffers(long nativeBuilder, boolean enabled);
    private static native void nBuilderFog(long nativeBuilder, boolean enabled);
    private static native void nBuilderLightChannel(long nativeRenderableManager, int channel, boolean enable);
@@ -989,7 +993,7 @@ public class RenderableManager {
    private static native int nSetBonesAsMatrices(long nativeObject, int i, Buffer matrices, int remaining, int boneCount, int offset);
    private static native int nSetBonesAsQuaternions(long nativeObject, int i, Buffer quaternions, int remaining, int boneCount, int offset);
    private static native void nSetMorphWeights(long nativeObject, int instance, float[] weights, int offset);
-    private static native void nSetMorphTargetBufferAt(long nativeObject, int i, int level, int primitiveIndex, long nativeMorphTargetBuffer, int offset, int count);
+    private static native void nSetMorphTargetBufferOffsetAt(long nativeObject, int i, int level, int primitiveIndex, long nativeMorphTargetBuffer, int offset);
    private static native int nGetMorphTargetCount(long nativeObject, int i);
    private static native void nSetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float cx, float cy, float cz, float ex, float ey, float ez);
    private static native void nSetLayerMask(long nativeRenderableManager, int i, int select, int value);
@@ -284,6 +284,33 @@ public class Renderer {
        nSetPresentationTime(getNativeObject(), monotonicClockNanos);
    }

+    /**
+     * The use of this method is optional. It sets the VSYNC time expressed as the duration in
+     * nanosecond since epoch of std::chrono::steady_clock.
+     * If called, passing 0 to frameTimeNanos in Renderer.BeginFrame will use this
+     * time instead.
+     * @param steadyClockTimeNano duration in nanosecond since epoch of std::chrono::steady_clock
+     * @see Engine#getSteadyClockTimeNano
+     * @see Renderer#beginFrame
+     */
+    public void setVsyncTime(long steadyClockTimeNano) {
+        nSetVsyncTime(getNativeObject(), steadyClockTimeNano);
+    }
+
+    /**
+     * Call skipFrame when momentarily skipping frames, for instance if the content of the
+     * scene doesn't change.
+     *
+     * @param vsyncSteadyClockTimeNano The time in nanoseconds when the frame started being rendered,
+     *                       in the {@link System#nanoTime()} timebase. Divide this value by 1000000 to
+     *                       convert it to the {@link android.os.SystemClock#uptimeMillis()}
+     *                       time base. This typically comes from
+     *                       {@link android.view.Choreographer.FrameCallback}.
+     */
+    public void skipFrame(long vsyncSteadyClockTimeNano) {
+        nSkipFrame(getNativeObject(), vsyncSteadyClockTimeNano);
+    }
+
    /**
     * Sets up a frame for this <code>Renderer</code>.
     * <p><code>beginFrame</code> manages frame pacing, and returns whether or not a frame should be
@@ -702,6 +729,8 @@ public class Renderer {
    }

    private static native void nSetPresentationTime(long nativeObject, long monotonicClockNanos);
+    private static native void nSetVsyncTime(long nativeObject, long steadyClockTimeNano);
+    private static native void nSkipFrame(long nativeObject, long vsyncSteadyClockTimeNano);
    private static native boolean nBeginFrame(long nativeRenderer, long nativeSwapChain, long frameTimeNanos);
    private static native void nEndFrame(long nativeRenderer);
    private static native void nRender(long nativeRenderer, long nativeView);
@@ -68,72 +68,6 @@ 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;
-
-    /**
-     * The SwapChain contains protected content. Only supported when isProtectedContentSupported()
-     * is true.
-     */
-    public static final long CONFIG_PROTECTED_CONTENT   = 0x40;
-
    SwapChain(long nativeSwapChain, Object surface) {
        mNativeObject = nativeSwapChain;
        mSurface = surface;
@@ -145,17 +79,19 @@ public class SwapChain {
     *
     * @param engine A reference to the filament Engine
     * @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 SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
+     * 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 SWAP_CHAIN_CONFIG_SRGB_COLORSPACE is supported, false otherwise.
+     * @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());
@@ -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;
+}
+
@@ -241,6 +241,15 @@ public class View {
        nSetCamera(getNativeObject(), camera == null ? 0 : camera.getNativeObject());
    }

+    /**
+     * Query whether a camera is set.
+     * @return true if a camera is set, false otherwise
+     * @see #setCamera
+     */
+    public boolean hasCamera() {
+        return nHasCamera(getNativeObject());
+    }
+
    /**
     * Gets this View's associated Camera, or null if none has been assigned.
     *
@@ -1224,6 +1233,18 @@ public class View {
        return nGetFogEntity(getNativeObject());
    }

+    /**
+     * When certain temporal features are used (e.g.: TAA or Screen-space reflections), the view
+     * keeps a history of previous frame renders associated with the Renderer the view was last
+     * used with. When switching Renderer, it may be necessary to clear that history by calling
+     * this method. Similarly, if the whole content of the screen change, like when a cut-scene
+     * starts, clearing the history might be needed to avoid artifacts due to the previous frame
+     * being very different.
+     */
+    public void clearFrameHistory(Engine engine) {
+        nClearFrameHistory(getNativeObject(), engine.getNativeObject());
+    }
+
    public long getNativeObject() {
        if (mNativeObject == 0) {
            throw new IllegalStateException("Calling method on destroyed View");
@@ -1238,6 +1259,7 @@ public class View {
    private static native void nSetName(long nativeView, String name);
    private static native void nSetScene(long nativeView, long nativeScene);
    private static native void nSetCamera(long nativeView, long nativeCamera);
+    private static native boolean nHasCamera(long nativeView);
    private static native void nSetViewport(long nativeView, int left, int bottom, int width, int height);
    private static native void nSetVisibleLayers(long nativeView, int select, int value);
    private static native void nSetShadowingEnabled(long nativeView, boolean enabled);
@@ -1284,7 +1306,7 @@ public class View {
    private static native void nSetMaterialGlobal(long nativeView, int index, float x, float y, float z, float w);
    private static native void nGetMaterialGlobal(long nativeView, int index, float[] out);
    private static native int nGetFogEntity(long nativeView);
-
+    private static native void nClearFrameHistory(long nativeView, long nativeEngine);

    /**
     * List of available ambient occlusion techniques.
@@ -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
@@ -538,7 +538,7 @@ public class UiHelper {
     * the options set on this UiHelper.
     */
    public long getSwapChainFlags() {
-        return isOpaque() ? SwapChain.CONFIG_DEFAULT : SwapChain.CONFIG_TRANSPARENT;
+        return isOpaque() ? SwapChainFlags.CONFIG_DEFAULT : SwapChainFlags.CONFIG_TRANSPARENT;
    }

    /**
@@ -31,6 +31,7 @@ set_target_properties(iblprefilter PROPERTIES IMPORTED_LOCATION
        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfilament-iblprefilter.a)

 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libfilament-utils-jni.map")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")

 add_library(filament-utils-jni SHARED
        src/main/cpp/AutomationEngine.cpp
@@ -125,6 +125,11 @@ extern "C" JNIEXPORT void Java_com_google_android_filament_utils_Manipulator_nBu
    builder->groundPlane(a, b, c, d);
 }

+extern "C" JNIEXPORT void Java_com_google_android_filament_utils_Manipulator_nBuilderPanning(JNIEnv*, jclass, jlong nativeBuilder, jboolean enabled) {
+    Builder* builder = (Builder*) nativeBuilder;
+    builder->panning(enabled);
+}
+
 extern "C" JNIEXPORT long Java_com_google_android_filament_utils_Manipulator_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder, jint mode) {
    Builder* builder = (Builder*) nativeBuilder;
    return (jlong) builder->build((Mode) mode);
@@ -274,6 +274,17 @@ public class Manipulator {
            return this;
        }

+        /**
+         * Sets whether panning is enabled in the manipulator.
+         *
+         * @return this <code>Builder</code> object for chaining calls
+         */
+        @NonNull
+        public Builder panning(Boolean enabled) {
+            nBuilderPanning(mNativeBuilder, enabled);
+            return this;
+        }
+
        /**
         * Creates and returns the <code>Manipulator</code> object.
         *
@@ -483,6 +494,7 @@ public class Manipulator {
    private static native void nBuilderFlightPanSpeed(long nativeBuilder, float x, float y);
    private static native void nBuilderFlightMoveDamping(long nativeBuilder, float damping);
    private static native void nBuilderGroundPlane(long nativeBuilder, float a, float b, float c, float d);
+    private static native void nBuilderPanning(long nativeBuilder, Boolean enabled);
    private static native long nBuilderBuild(long nativeBuilder, int mode);

    private static native void nDestroyManipulator(long nativeManip);
@@ -44,6 +44,7 @@ set_target_properties(uberarchive PROPERTIES IMPORTED_LOCATION
        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberarchive.a)

 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map")
+set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,max-page-size=16384")

 set(GLTFIO_SRCS
        ${GLTFIO_DIR}/include/gltfio/Animator.h
@@ -81,9 +82,20 @@ set(GLTFIO_SRCS
        ${GLTFIO_DIR}/src/TangentsJob.cpp
        ${GLTFIO_DIR}/src/TangentsJob.h
        ${GLTFIO_DIR}/src/UbershaderProvider.cpp
+        ${GLTFIO_DIR}/src/Utility.cpp
+        ${GLTFIO_DIR}/src/Utility.h
        ${GLTFIO_DIR}/src/Wireframe.cpp
        ${GLTFIO_DIR}/src/Wireframe.h
        ${GLTFIO_DIR}/src/downcast.h
+        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.cpp
+        ${GLTFIO_DIR}/src/extended/AssetLoaderExtended.h
+        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.cpp
+        ${GLTFIO_DIR}/src/extended/ResourceLoaderExtended.h
+        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.cpp
+        ${GLTFIO_DIR}/src/extended/TangentsJobExtended.h
+        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.cpp
+        ${GLTFIO_DIR}/src/extended/TangentSpaceMeshWrapper.h
+

        src/main/cpp/Animator.cpp
        src/main/cpp/AssetLoader.cpp
@@ -108,7 +120,6 @@ set(GLTFIO_INCLUDE_DIRS
        ../../third_party/cgltf
        ../../third_party/meshoptimizer/src
        ../../third_party/robin-map
-        ../../third_party/hat-trie
        ../../third_party/stb
        ../../libs/utils/include
        ../../libs/ktxreader/include
@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.50.6
+VERSION_NAME=1.55.1

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

@@ -1,6 +1,6 @@
 #Wed Nov 17 10:40:18 PST 2021
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
@@ -321,7 +321,7 @@ class MainActivity : Activity() {
            var flags = uiHelper.swapChainFlags
            if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
                if (SwapChain.isSRGBSwapChainSupported(engine)) {
-                    flags = flags or SwapChain.CONFIG_SRGB_COLORSPACE
+                    flags = flags or SwapChainFlags.CONFIG_SRGB_COLORSPACE
                }
            }

@@ -44,8 +44,6 @@ function print_help {
    echo "        Exclude Vulkan support from the Android build."
    echo "    -s"
    echo "        Add iOS simulator support to the iOS build."
-    echo "    -t"
-    echo "        Enable SwiftShader support for Vulkan in desktop builds."
    echo "    -e"
    echo "        Enable EGL on Linux support for desktop builds."
    echo "    -l"
@@ -61,6 +59,17 @@ function print_help {
    echo "    -b"
    echo "        Enable Address and Undefined Behavior Sanitizers (asan/ubsan) for debugging."
    echo "        This is only for the desktop build."
+    echo "    -x value"
+    echo "        Define a preprocessor flag FILAMENT_BACKEND_DEBUG_FLAG with [value]. This is useful for"
+    echo "        enabling debug paths in the backend from the build script. For example, make a"
+    echo "        systrace-enabled build without directly changing #defines. Remember to add -f when"
+    echo "        changing this option."
+    echo "    -X osmesa_path"
+    echo "        Indicates a path to a completed OSMesa build. OSMesa is used to create an offscreen GL"
+    echo "        context for software rasterization"
+    echo "    -S type"
+    echo "        Enable stereoscopic rendering where type is one of [instanced|multiview]. This is only"
+    echo "        meant for building the samples."
    echo ""
    echo "Build types:"
    echo "    release"
@@ -160,8 +169,6 @@ INSTALL_COMMAND=
 VULKAN_ANDROID_OPTION="-DFILAMENT_SUPPORTS_VULKAN=ON"
 VULKAN_ANDROID_GRADLE_OPTION=""

-SWIFTSHADER_OPTION="-DFILAMENT_USE_SWIFTSHADER=OFF"
-
 EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=OFF"

 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
@@ -172,6 +179,12 @@ MATOPT_GRADLE_OPTION=""

 ASAN_UBSAN_OPTION=""

+BACKEND_DEBUG_FLAG_OPTION=""
+
+STEREOSCOPIC_OPTION=""
+
+OSMESA_OPTION=""
+
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false

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

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

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

-while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
+while getopts ":hacCfgijmp:q:uvslwedk:bx:S:X:" opt; do
    case ${opt} in
        h)
            print_help
@@ -840,7 +866,7 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
                        echo "Platform must be one of [desktop|android|ios|webgl|all]"
                        echo ""
                        exit 1
-                    ;;    
+                    ;;
                esac
            done
            ;;
@@ -895,10 +921,6 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
            IOS_BUILD_SIMULATOR=true
            echo "iOS simulator support enabled."
            ;;
-        t)
-            SWIFTSHADER_OPTION="-DFILAMENT_USE_SWIFTSHADER=ON"
-            echo "SwiftShader support enabled."
-            ;;
        e)
            EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=ON -DFILAMENT_SKIP_SDL2=ON -DFILAMENT_SKIP_SAMPLES=ON"
            echo "EGL on Linux support enabled; skipping SDL2."
@@ -918,6 +940,24 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
        b)  ASAN_UBSAN_OPTION="-DFILAMENT_ENABLE_ASAN_UBSAN=ON"
            echo "Enabled ASAN/UBSAN"
            ;;
+        x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
+            ;;
+        S)  case $(echo "${OPTARG}" | tr '[:upper:]' '[:lower:]') in
+                instanced)
+                    STEREOSCOPIC_OPTION="-DFILAMENT_SAMPLES_STEREO_TYPE=instanced"
+                    ;;
+                multiview)
+                    STEREOSCOPIC_OPTION="-DFILAMENT_SAMPLES_STEREO_TYPE=multiview"
+                    ;;
+                *)
+                    echo "Unknown stereoscopic type ${OPTARG}"
+                    echo "Type must be one of [instanced|multiview]"
+                    echo ""
+                    exit 1
+            esac
+            ;;
+        X)  OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}"
+            ;;
        \?)
            echo "Invalid option: -${OPTARG}" >&2
            echo ""
@@ -57,15 +57,10 @@ FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/ndk.version)}

 # Install the required NDK version specifically (if not present)
 if [[ ! -d "${ANDROID_HOME}/ndk/$FILAMENT_NDK_VERSION" ]]; then
-    ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION" > /dev/null
+    yes | ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager --licenses
+    ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION"
 fi
-
-# Only build 1 64 bit target during presubmit to cut down build times during presubmit
-# Continuous builds will build everything
 ANDROID_ABIS=
-if [[ "$TARGET" == "presubmit" ]]; then
-  ANDROID_ABIS="-q arm64-v8a"
-fi

 # Build the Android sample-gltf-viewer APK during release.
 BUILD_SAMPLES=
@@ -73,5 +68,19 @@ if [[ "$TARGET" == "release" ]]; then
    BUILD_SAMPLES="-k sample-gltf-viewer"
 fi

+function build_android() {
+    local ABI=$1
+
+    # Do the following in two steps so that we do not run out of space
+    if [[ -n "${BUILD_DEBUG}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_DEBUG}
+        rm -rf out/cmake-android-debug-*
+    fi
+    if [[ -n "${BUILD_RELEASE}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_RELEASE}
+        rm -rf out/cmake-android-release-*
+    fi
+}
+
 pushd `dirname $0`/../.. > /dev/null
-FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android $ANDROID_ABIS -c $BUILD_SAMPLES $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+build_android $2
@@ -1 +1 @@
-26.1.10909125
+27.0.11718014
@@ -1,53 +0,0 @@
-# Build the image:
-#   docker build --no-cache --tag ssfilament -f build/swiftshader/Dockerfile .
-#   docker tag ssfilament ghcr.io/filament-assets/swiftshader
-#
-# Publish the image:
-#   docker login ghcr.io --username <user> --password <token>
-#   docker push ghcr.io/filament-assets/swiftshader
-#
-# Run the image and mount the current directory:
-#   docker run -it -v `pwd`:/trees/filament -t ssfilament
-
-FROM ubuntu:focal
-WORKDIR /trees
-ARG DEBIAN_FRONTEND=noninteractive
-ENV SWIFTSHADER_LD_LIBRARY_PATH=/trees/swiftshader/build
-ENV CXXFLAGS='-fno-builtin -Wno-pass-failed'
-
-RUN apt-get update && \
-    apt-get --no-install-recommends install -y \
-	apt-transport-https \
-	apt-utils \
-	build-essential \
-	cmake \
-	ca-certificates \
-	git \
-	ninja-build \
-	python \
-	python3 \
-	xorg-dev \
-	clang-7 \
-	libc++-7-dev \
-	libc++abi-7-dev \
-	lldb
-
-# Ensure that clang is used instead of gcc.
-RUN set -eux ;\
-    update-alternatives --install /usr/bin/clang clang /usr/bin/clang-7 100 ;\
-    update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-7 100 ;\
-    update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100 ;\
-    update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
-
-# Get patch files from the local Filament tree.
-COPY build/swiftshader/*.diff .
-
-# Clone SwiftShader, apply patches, and build it.
-RUN set -eux ;\
-	git clone https://swiftshader.googlesource.com/SwiftShader swiftshader ;\
-    cd swiftshader ;\
-	git checkout 139f5c3 ;\
-	git apply /trees/*.diff ;\
-    cd build ;\
-    cmake .. -GNinja -DCMAKE_BUILD_TYPE=Release ;\
-    ninja
@@ -1,56 +0,0 @@
-#!/usr/bin/env python3
-
-from pathlib import Path
-import os
-
-spath = os.path.dirname(os.path.realpath(__file__))
-
-path = Path(spath)
-
-folder = "../../results/"
-
-images = list(path.glob(folder + '*.png'))
-
-images.sort()
-
-gallery = open(path.absolute().joinpath(folder + 'index.html'), 'w')
-
-gallery.write("""<html>
-<head>
-<script type="module" src="https://unpkg.com/img-comparison-slider@latest/dist/component/component.esm.js"></script>
-<script nomodule="" src="https://unpkg.com/img-comparison-slider@latest/dist/component/component.js"></script>
-<link rel="stylesheet" href="https://unpkg.com/img-comparison-slider@latest/dist/collection/styles/initial.css"/>
-<style>
-    h2 {
-        font-weight: normal;
-        margin-top: 150px;
-        margin-bottom: 20px;
-    }
-    a {
-        text-decoration: none;
-        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
-        color: blue;
-    }
-    a:hover {
-        font-weight: bold;
-    }
-</style>
-</head>
-<body>
-""")
-
-tag = ''
-
-for image in images:
-    group = image.stem.rstrip('0123456789')
-    before = f'https://filament-assets.github.io/golden/{group}/{image.name}'
-    after = image.name
-    gallery.write('\n')
-    gallery.write(f'<h2><a href="{image.stem}.json">{image.stem}.json</a></h2>\n')
-    gallery.write('<img-comparison-slider>\n')
-    gallery.write(f'<img slot="before" src="{before}" /> <img slot="after" src="{after}" />\n')
-    gallery.write('</img-comparison-slider>\n')
-
-gallery.write("""</body>
-</html>
-""")
@@ -1,62 +0,0 @@
-diff --git a/src/Vulkan/VkPipeline.cpp b/src/Vulkan/VkPipeline.cpp
-index 86913ec72..3b35345af 100644
--- a/src/Vulkan/VkPipeline.cpp
-+++ b/src/Vulkan/VkPipeline.cpp
-@@ -71,7 +71,56 @@ std::vector<uint32_t> preprocessSpirv(
- 	if(optimize)
- 	{
- 		// Full optimization list taken from spirv-opt.
-		opt.RegisterPerformancePasses();
-+
-+		// We have removed CreateRedundancyEliminationPass because it segfaults when encountering:
-+		//     %389 = OpCompositeConstruct %7 %386 %387 %388 %86
-+		// When inserting an entry into instruction_to_value_ (which is an unordered_map)
-+		// This could perhaps be investigated further with help from asan.
-+
-+		using namespace spvtools;
-+		opt.RegisterPass(CreateWrapOpKillPass())
-+			.RegisterPass(CreateDeadBranchElimPass())
-+			.RegisterPass(CreateMergeReturnPass())
-+			.RegisterPass(CreateInlineExhaustivePass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreatePrivateToLocalPass())
-+			.RegisterPass(CreateLocalSingleBlockLoadStoreElimPass())
-+			.RegisterPass(CreateLocalSingleStoreElimPass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateScalarReplacementPass())
-+			.RegisterPass(CreateLocalAccessChainConvertPass())
-+			.RegisterPass(CreateLocalSingleBlockLoadStoreElimPass())
-+			.RegisterPass(CreateLocalSingleStoreElimPass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateLocalMultiStoreElimPass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateCCPPass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateLoopUnrollPass(true))
-+			.RegisterPass(CreateDeadBranchElimPass())
-+			.RegisterPass(CreateRedundancyEliminationPass()) // workaround for SEGFAULT
-+			.RegisterPass(CreateCombineAccessChainsPass())
-+			.RegisterPass(CreateSimplificationPass())
-+			.RegisterPass(CreateScalarReplacementPass())
-+			.RegisterPass(CreateLocalAccessChainConvertPass())
-+			.RegisterPass(CreateLocalSingleBlockLoadStoreElimPass())
-+			.RegisterPass(CreateLocalSingleStoreElimPass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateSSARewritePass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateVectorDCEPass())
-+			.RegisterPass(CreateDeadInsertElimPass())
-+			.RegisterPass(CreateDeadBranchElimPass())
-+			.RegisterPass(CreateSimplificationPass())
-+			.RegisterPass(CreateIfConversionPass())
-+			.RegisterPass(CreateCopyPropagateArraysPass())
-+			.RegisterPass(CreateReduceLoadSizePass())
-+			.RegisterPass(CreateAggressiveDCEPass())
-+			.RegisterPass(CreateBlockMergePass())
-+			.RegisterPass(CreateRedundancyEliminationPass()) // workaround for SEGFAULT
-+			.RegisterPass(CreateDeadBranchElimPass())
-+			.RegisterPass(CreateBlockMergePass())
-+			.RegisterPass(CreateSimplificationPass());
- 	}
- 
- 	std::vector<uint32_t> optimized;
@@ -1,127 +0,0 @@
-#!/bin/bash
-set -e
-
-function print_help {
-    local self_name=$(basename "$0")
-    echo "This script issues docker commands for testing Filament with SwiftShader."
-    echo "The usual sequence of commands is: fetch, start, build filament release, and run."
-    echo ""
-    echo "Usage:"
-    echo "    $self_name [command]"
-    echo ""
-    echo "Commands:"
-    echo "    build filament [debug | release]"
-    echo "        Use the container to build Filament."
-    echo "    build swiftshader [debug | release]"
-    echo "        Use the container to do a clean rebuild of SwiftShader."
-    echo "        (Note that the container already has SwiftShader built.)"
-    echo "    fetch"
-    echo "        Download the docker image from the central repository."
-    echo "    help"
-    echo "        Print this help message."
-    echo "    logs"
-    echo "        Print messages from the container's kernel ring buffer."
-    echo "        This is useful for diagnosing OOM issues."
-    echo "    run [lldb]"
-    echo "        Launch a test inside the container, optionally via lldb."
-    echo "    shell"
-    echo "        Interact with a bash prompt in the container."
-    echo "    start"
-    echo "        Start a container from the image."
-    echo "    stop"
-    echo "        Stop the container."
-    echo ""
-}
-
-# Change the current working directory to the Filament root.
-pushd "$(dirname "$0")/../.." > /dev/null
-
-if [[ "$1" == "build" ]] && [[ "$2" == "filament" ]]; then
-    docker exec runner filament/build.sh -t $3 gltf_viewer
-    exit $?
-fi
-
-if [[ "$1" == "build" ]] && [[ "$2" == "swiftshader" ]]; then
-    BUILD_TYPE="$3"
-    BUILD_TYPE="$(tr '[:lower:]' '[:upper:]' <<< ${BUILD_TYPE:0:1})${BUILD_TYPE:1}"
-    docker exec --workdir /trees/swiftshader runner rm -rf build
-    docker exec --workdir /trees/swiftshader runner mkdir build
-    docker exec --workdir /trees/swiftshader/build runner cmake -GNinja -DCMAKE_BUILD_TYPE="$BUILD_TYPE" ..
-    docker exec --workdir /trees/swiftshader/build runner ninja
-    exit $?
-fi
-
-if [[ "$1" == "fetch" ]]; then
-    docker pull ghcr.io/filament-assets/swiftshader:latest
-    docker tag ghcr.io/filament-assets/swiftshader:latest ssfilament
-    exit $?
-fi
-
-if [[ "$1" == "help" ]]; then
-    print_help
-    exit 0
-fi
-
-if [[ "$1" == "logs" ]]; then
-    docker exec runner dmesg --human --read-clear
-    exit $?
-fi
-
-if [[ "$1" == "run" ]] && [[ "$2" == "lldb" ]]; then
-    docker exec -i --workdir /trees/filament/results runner \
-          lldb --batch -o run -o bt -- \
-          ../out/cmake-release/samples/gltf_viewer \
-          --headless \
-          --batch ../libs/viewer/tests/basic.json \
-          --api vulkan
-    docker exec runner /trees/filament/build/swiftshader/gallery.py
-    exit $?
-fi
-
-if [[ "$1" == "run" ]]; then
-    docker exec --tty  --workdir /trees/filament/results runner \
-          /usr/bin/catchsegv \
-          ../out/cmake-release/samples/gltf_viewer \
-          --headless \
-          --batch ../libs/viewer/tests/basic.json \
-          --api vulkan
-    docker exec runner /trees/filament/build/swiftshader/gallery.py
-    exit $?
-fi
-
-if [[ "$1" == "shell" ]]; then
-    docker exec --interactive --tty runner /bin/bash
-    exit $?
-fi
-
-# Notes on options being passed to docker's run command:
-#
-# - The memory constraint seems to prevent an OOM signal in GitHub Actions.
-# - The cap / security args allow use of lldb and creation of core dumps.
-# - The privileged arg allows use of dmesg for examining OOM logs.
-#
-# Currently, a GitHub Actions VM has 2 CPUs, 7 GB RAM, and 14 GB of SSD disk space.
-#
-# Please be aware that Docker Desktop might impose additional resource constraints, and that those
-# settings can only be controlled with its GUI. We recommend at least 7 GB of memory and 2 GB swap.
-if [[ "$1" == "start" ]]; then
-    mkdir -p results
-    docker run --tty --rm --detach --privileged \
-          --memory 6.5g \
-          --name runner \
-          --cap-add=SYS_PTRACE \
-          --security-opt seccomp=unconfined \
-          --security-opt apparmor=unconfined \
-          --volume `pwd`:/trees/filament \
-          --workdir /trees \
-          ssfilament
-    exit $?
-fi
-
-if [[ "$1" == "stop" ]]; then
-    docker container rm runner --force
-    exit $?
-fi
-
-print_help
-exit 1
@@ -1,7 +1,6 @@
 #!/bin/bash
 if [ `uname` == "Linux" ];then
-    curl -OL https://github.com/ninja-build/ninja/releases/download/v1.10.2/ninja-linux.zip
-    unzip -q ninja-linux.zip
+    source `dirname $0`/../linux/ci-common.sh
 elif [ `uname` == "Darwin" ];then
    curl -OL https://github.com/ninja-build/ninja/releases/download/v1.10.2/ninja-mac.zip
    unzip -q ninja-mac.zip
@@ -13,9 +12,6 @@ fi
 chmod +x ninja
 export PATH="$PWD:$PATH"

-# FIXME: kokoro machines have node and npm but currently they are symlinked to non-existent files
-# npm install -g typescript
-
 # Install emscripten.
 curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
@@ -115,17 +115,23 @@ cmake ..\.. ^
    -DFILAMENT_SUPPORTS_VULKAN=ON ^
    || exit /b

+set build_flags=-j %NUMBER_OF_PROCESSORS%
+
+@echo on
+
+:: we've upgraded the windows machines, so the following are no longer accurate as of 09/19/24, but
+:: keeping around the comment for record.
+
 :: Attempt to fix "error C1060: compiler is out of heap space" seen on CI.
 :: Some resource libraries require significant heap space to compile, so first compile them serially.
-@echo on
-cmake --build . --target filagui --config %config% || exit /b
-cmake --build . --target uberarchive --config %config% || exit /b
-cmake --build . --target gltf-demo-resources --config %config% || exit /b
-cmake --build . --target filamentapp-resources --config %config% || exit /b
-cmake --build . --target sample-resources --config %config% || exit /b
-cmake --build . --target suzanne-resources --config %config% || exit /b
+:: cmake --build . --target filagui --config %config% %build_flags% || exit /b
+:: cmake --build . --target uberarchive --config %config% %build_flags% || exit /b
+:: cmake --build . --target gltf-demo-resources --config %config% %build_flags% || exit /b
+:: cmake --build . --target filamentapp-resources --config %config% %build_flags% || exit /b
+:: cmake --build . --target sample-resources --config %config% %build_flags% || exit /b
+:: cmake --build . --target suzanne-resources --config %config% %build_flags% || exit /b

-cmake --build . %INSTALL% --config %config% -- /m || exit /b
+cmake --build . %INSTALL% --config %config% %build_flags% -- /m || exit /b
@echo off

 echo Disk info after building variant: %variant%
@@ -476,7 +476,7 @@ Energy conservation is one of the key components of a good BRDF for physically b
 <p>


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

 </p><p>

@@ -857,7 +857,7 @@ The full GLSL implementation of the standard model is shown in <a href="#listing
 <span class="line">    <span class="hljs-comment">// perceptually linear roughness to roughness (see parameterization)</span></span>
 <span class="line">    <span class="hljs-type">float</span> roughness = perceptualRoughness * perceptualRoughness;</span>
 <span class="line"></span>
-<span class="line">    <span class="hljs-type">float</span> D = D_GGX(NoH, a);</span>
+<span class="line">    <span class="hljs-type">float</span> D = D_GGX(NoH, roughness);</span>
 <span class="line">    <span class="hljs-type">vec3</span>  F = F_Schlick(LoH, f0);</span>
 <span class="line">    <span class="hljs-type">float</span> V = V_SmithGGXCorrelated(NoV, NoL, roughness);</span>
 <span class="line"></span>
@@ -1308,7 +1308,12 @@ Description
      declare a variable called `eyeDirection` you can access it in the fragment shader using
      `variable_eyeDirection`. In the vertex shader, the interpolant name is simply a member of
      the `MaterialVertexInputs` structure (`material.eyeDirection` in your example). Each
-      interpolant is of type `float4` (`vec4`) in the shaders.
+      interpolant is of type `float4` (`vec4`) in the shaders. By default the precision of the
+      interpolant is `highp` in *both* the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if `default` is specified the default precision is used is the fragment shader
+      (`mediump`) and in the vertex shader (`highp`).

 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
@@ -1320,7 +1325,11 @@ material {
        }
    ],
    variables : [
-         eyeDirection
+         eyeDirection,
+         {
+            name : eyeColor,
+            precision : medium
+         }
    ],
    vertexDomain : device,
    depthWrite : false,
@@ -1397,7 +1406,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 +1429,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 +1442,36 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

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

 ### Fragment only

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

 </main>
-<script src="https://unpkg.com/filament@1.44.0/filament.js"></script>
+<script src="https://unpkg.com/filament@1.51.6/filament.js"></script>
 <script src="https://unpkg.com/gltumble"></script>
 <script src="filament-viewer.js" type="module"></script>
 </body>
@@ -61,10 +61,12 @@ set(SRCS
        src/Engine.cpp
        src/Exposure.cpp
        src/Fence.cpp
+        src/FilamentBuilder.cpp
        src/FrameInfo.cpp
        src/FrameSkipper.cpp
        src/Froxelizer.cpp
        src/Frustum.cpp
+        src/HwDescriptorSetLayoutFactory.cpp
        src/HwRenderPrimitiveFactory.cpp
        src/HwVertexBufferInfoFactory.cpp
        src/IndexBuffer.cpp
@@ -75,8 +77,6 @@ set(SRCS
        src/MaterialInstance.cpp
        src/MaterialParser.cpp
        src/MorphTargetBuffer.cpp
-        src/PerViewUniforms.cpp
-        src/PerShadowMapUniforms.cpp
        src/PostProcessManager.cpp
        src/RenderPass.cpp
        src/RenderPrimitive.cpp
@@ -125,6 +125,12 @@ set(SRCS
        src/details/Texture.cpp
        src/details/VertexBuffer.cpp
        src/details/View.cpp
+        src/ds/ColorPassDescriptorSet.cpp
+        src/ds/DescriptorSet.cpp
+        src/ds/DescriptorSetLayout.cpp
+        src/ds/PostProcessDescriptorSet.cpp
+        src/ds/ShadowMapDescriptorSet.cpp
+        src/ds/SsrPassDescriptorSet.cpp
        src/fg/Blackboard.cpp
        src/fg/DependencyGraph.cpp
        src/fg/FrameGraph.cpp
@@ -148,22 +154,21 @@ set(PRIVATE_HDRS
        src/FrameInfo.h
        src/FrameSkipper.h
        src/Froxelizer.h
+        src/HwDescriptorSetLayoutFactory.h
        src/HwRenderPrimitiveFactory.h
        src/HwVertexBufferInfoFactory.h
        src/Intersections.h
        src/MaterialParser.h
-        src/PerViewUniforms.h
-        src/PerShadowMapUniforms.h
        src/PIDController.h
        src/PostProcessManager.h
-        src/RendererUtils.h
        src/RenderPass.h
        src/RenderPrimitive.h
+        src/RendererUtils.h
        src/ResourceAllocator.h
        src/ResourceList.h
        src/ShadowMap.h
        src/ShadowMapManager.h
-        src/TypedUniformBuffer.h
+        src/SharedHandle.h
        src/UniformBuffer.h
        src/components/CameraManager.h
        src/components/LightManager.h
@@ -191,6 +196,14 @@ set(PRIVATE_HDRS
        src/details/Texture.h
        src/details/VertexBuffer.h
        src/details/View.h
+        src/downcast.h
+        src/ds/ColorPassDescriptorSet.h
+        src/ds/DescriptorSetLayout.h
+        src/ds/PostProcessDescriptorSet.h
+        src/ds/ShadowMapDescriptorSet.h
+        src/ds/SsrPassDescriptorSet.h
+        src/ds/TypedBuffer.h
+        src/ds/TypedUniformBuffer.h
        src/fg/Blackboard.h
        src/fg/FrameGraph.h
        src/fg/FrameGraphId.h
@@ -208,12 +221,12 @@ set(PRIVATE_HDRS
        src/materials/fsr/ffx_a.h
        src/materials/fsr/ffx_fsr1.h
        src/materials/fsr/ffx_fsr1_mobile.fs
-        src/downcast.h
 )

 set(MATERIAL_SRCS
        src/materials/antiAliasing/fxaa.mat
        src/materials/antiAliasing/taa.mat
+        src/materials/blitDepth.mat
        src/materials/blitLow.mat
        src/materials/blitArray.mat
        src/materials/bloom/bloomDownsample.mat
@@ -252,8 +265,13 @@ set(MATERIAL_SRCS
 )

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

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

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

+    list(FIND MATERIAL_FL0_SRCS ${mat_src} index)
+    if (${index} GREATER -1 AND FILAMENT_ENABLE_FEATURE_LEVEL_0)
+        string(REGEX REPLACE "[.]filamat$" "_fl0.filamat" output_path_fl0 ${output_path})
        add_custom_command(
-                OUTPUT ${output_path}
-                COMMAND matc ${MATC_BASE_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

@@ -12,6 +12,7 @@ set(PUBLIC_HDRS
        include/backend/AcquiredImage.h
        include/backend/BufferDescriptor.h
        include/backend/CallbackHandler.h
+        include/backend/DescriptorSetOffsetArray.h
        include/backend/DriverApiForward.h
        include/backend/DriverEnums.h
        include/backend/Handle.h
@@ -66,11 +67,17 @@ set(PRIVATE_HDRS
 # OpenGL / OpenGL ES Sources
 # ==================================================================================================

-if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMENT_USE_SWIFTSHADER)
+if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3)
    list(APPEND SRCS
            include/backend/platforms/OpenGLPlatform.h
+            src/opengl/BindingMap.h
            src/opengl/gl_headers.cpp
            src/opengl/gl_headers.h
+            src/opengl/GLBufferObject.h
+            src/opengl/GLDescriptorSet.cpp
+            src/opengl/GLDescriptorSet.h
+            src/opengl/GLDescriptorSetLayout.h
+            src/opengl/GLTexture.h
            src/opengl/GLUtils.cpp
            src/opengl/GLUtils.h
            src/opengl/OpenGLBlobCache.cpp
@@ -112,6 +119,8 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
            list(APPEND SRCS src/opengl/platforms/PlatformGLX.cpp)
        elseif (FILAMENT_SUPPORTS_EGL_ON_LINUX)
            list(APPEND SRCS src/opengl/platforms/PlatformEGLHeadless.cpp)
+        elseif (FILAMENT_SUPPORTS_OSMESA)
+            list(APPEND SRCS src/opengl/platforms/PlatformOSMesa.cpp)
        endif()
    elseif (WIN32)
        list(APPEND SRCS src/opengl/platforms/PlatformWGL.cpp)
@@ -166,8 +175,10 @@ 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/caching/VulkanDescriptorSetManager.cpp
+            src/vulkan/caching/VulkanDescriptorSetManager.h
+            src/vulkan/caching/VulkanPipelineLayoutCache.cpp
+            src/vulkan/caching/VulkanPipelineLayoutCache.h
            src/vulkan/platform/VulkanPlatform.cpp
            src/vulkan/platform/VulkanPlatformSwapChainImpl.cpp
            src/vulkan/platform/VulkanPlatformSwapChainImpl.h
@@ -357,6 +368,11 @@ set(LINUX_LINKER_OPTIMIZATION_FLAGS
        -Wl,--exclude-libs,bluegl
 )

+if (LINUX AND FILAMENT_SUPPORTS_OSMESA)
+    set(OSMESA_COMPILE_FLAGS
+        -I${FILAMENT_OSMESA_PATH}/include/GL)
+endif()
+
 if (MSVC)
    set(FILAMENT_WARNINGS /W3)
 else()
@@ -377,6 +393,7 @@ endif()

 target_compile_options(${TARGET} PRIVATE
        ${FILAMENT_WARNINGS}
+        ${OSMESA_COMPILE_FLAGS}
        $<$<CONFIG:Release>:${OPTIMIZATION_FLAGS}>
        $<$<AND:$<PLATFORM_ID:Darwin>,$<CONFIG:Release>>:${DARWIN_OPTIMIZATION_FLAGS}>
 )
@@ -386,6 +403,7 @@ if (FILAMENT_SUPPORTS_METAL)
 endif()

 target_link_libraries(${TARGET} PRIVATE
+        ${OSMESA_LINKER_FLAGS}
        $<$<AND:$<PLATFORM_ID:Linux>,$<CONFIG:Release>>:${LINUX_LINKER_OPTIMIZATION_FLAGS}>
 )

@@ -413,11 +431,14 @@ if (APPLE OR LINUX)
        test/test_MissingRequiredAttributes.cpp
        test/test_ReadPixels.cpp
        test/test_BufferUpdates.cpp
+        test/test_Callbacks.cpp
        test/test_MRT.cpp
+        test/test_PushConstants.cpp
        test/test_LoadImage.cpp
        test/test_StencilBuffer.cpp
        test/test_Scissor.cpp
        test/test_MipLevels.cpp
+        test/test_Handles.cpp
    )
    set(BACKEND_TEST_LIBS
        backend
@@ -474,6 +495,10 @@ if (APPLE)
       # linker from removing "unused" symbols.
       target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
       set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+
+       # This is needed after XCode 15.3
+       set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
+       set_target_properties(backend_test_mac PROPERTIES INSTALL_RPATH /usr/local/lib)
    endif()
 endif()

@@ -485,21 +510,40 @@ endif()

 # ==================================================================================================
 # Compute tests
+#
+#if (NOT IOS AND NOT WEBGL)
+#
+#add_executable(compute_test
+#        test/ComputeTest.cpp
+#        test/Arguments.cpp
+#        test/test_ComputeBasic.cpp
+#        )
+#
+#target_link_libraries(compute_test PRIVATE
+#        backend
+#        getopt
+#        gtest
+#        )
+#
+#set_target_properties(compute_test PROPERTIES FOLDER Tests)
+#
+#endif()

-if (NOT IOS AND NOT WEBGL)
+# ==================================================================================================
+# Metal utils tests

-add_executable(compute_test
-        test/ComputeTest.cpp
-        test/Arguments.cpp
-        test/test_ComputeBasic.cpp
-        )
+if (APPLE AND NOT IOS)

-target_link_libraries(compute_test PRIVATE
+add_executable(metal_utils_test test/MetalTest.mm)
+
+target_compile_options(metal_utils_test PRIVATE "-fobjc-arc")
+
+target_link_libraries(metal_utils_test PRIVATE
        backend
        getopt
        gtest
        )

-set_target_properties(compute_test PROPERTIES FOLDER Tests)
+set_target_properties(metal_utils_test PROPERTIES FOLDER Tests)

 endif()
@@ -0,0 +1,101 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_COMMANDSTREAMVECTOR_H
+#define TNT_FILAMENT_BACKEND_COMMANDSTREAMVECTOR_H
+
+#include <backend/DriverApiForward.h>
+
+#include <initializer_list>
+#include <memory>
+
+#include <stddef.h>
+#include <stdint.h>
+
+
+namespace filament::backend {
+
+void* allocateFromCommandStream(DriverApi& driver, size_t size, size_t alignment) noexcept;
+
+class DescriptorSetOffsetArray {
+public:
+    using value_type = uint32_t;
+    using reference = value_type&;
+    using const_reference = value_type const&;
+    using size_type = uint32_t;
+    using difference_type = int32_t;
+    using pointer = value_type*;
+    using const_pointer = value_type const*;
+    using iterator = pointer;
+    using const_iterator = const_pointer;
+
+    DescriptorSetOffsetArray() noexcept = default;
+
+    ~DescriptorSetOffsetArray() noexcept = default;
+
+    DescriptorSetOffsetArray(size_type size, DriverApi& driver) noexcept {
+        mOffsets = (value_type *)allocateFromCommandStream(driver,
+                size * sizeof(value_type), alignof(value_type));
+        std::uninitialized_fill_n(mOffsets, size, 0);
+    }
+
+    DescriptorSetOffsetArray(std::initializer_list<uint32_t> list, DriverApi& driver) noexcept {
+        mOffsets = (value_type *)allocateFromCommandStream(driver,
+                list.size() * sizeof(value_type), alignof(value_type));
+        std::uninitialized_copy(list.begin(), list.end(), mOffsets);
+    }
+
+    DescriptorSetOffsetArray(DescriptorSetOffsetArray const&) = delete;
+    DescriptorSetOffsetArray& operator=(DescriptorSetOffsetArray const&) = delete;
+
+    DescriptorSetOffsetArray(DescriptorSetOffsetArray&& rhs) noexcept
+            : mOffsets(rhs.mOffsets) {
+        rhs.mOffsets = nullptr;
+    }
+
+    DescriptorSetOffsetArray& operator=(DescriptorSetOffsetArray&& rhs) noexcept {
+        if (this != &rhs) {
+            mOffsets = rhs.mOffsets;
+            rhs.mOffsets = nullptr;
+        }
+        return *this;
+    }
+
+    bool empty() const noexcept { return mOffsets == nullptr; }
+
+    value_type* data() noexcept { return mOffsets; }
+    const value_type* data() const noexcept { return mOffsets; }
+
+
+    reference operator[](size_type n) noexcept {
+        return *(data() + n);
+    }
+
+    const_reference operator[](size_type n) const noexcept {
+        return *(data() + n);
+    }
+
+    void clear() noexcept {
+        mOffsets = nullptr;
+    }
+
+private:
+    value_type *mOffsets = nullptr;
+};
+
+} // namespace filament::backend
+
+#endif //TNT_FILAMENT_BACKEND_COMMANDSTREAMVECTOR_H
@@ -19,17 +19,23 @@
 #ifndef TNT_FILAMENT_BACKEND_DRIVERENUMS_H
 #define TNT_FILAMENT_BACKEND_DRIVERENUMS_H

-#include <utils/BitmaskEnum.h>
 #include <utils/unwindows.h> // Because we define ERROR in the FenceStatus enum.

+#include <backend/Platform.h>
 #include <backend/PresentCallable.h>

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

 #include <math/vec4.h>

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

 #include <stddef.h>
 #include <stdint.h>
@@ -90,11 +96,16 @@ static constexpr uint64_t SWAP_CHAIN_HAS_STENCIL_BUFFER         = SWAP_CHAIN_CON
 */
 static constexpr uint64_t SWAP_CHAIN_CONFIG_PROTECTED_CONTENT   = 0x40;

-
 static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT  = 16;   // This is guaranteed by OpenGL ES.
 static constexpr size_t MAX_SAMPLER_COUNT           = 62;   // Maximum needed at feature level 3.
 static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
 static constexpr size_t MAX_SSBO_COUNT              = 4;    // This is guaranteed by OpenGL ES.
+static constexpr size_t MAX_DESCRIPTOR_SET_COUNT    = 4;    // This is guaranteed by Vulkan.
+static constexpr size_t MAX_DESCRIPTOR_COUNT        = 64;   // per set
+
+static constexpr size_t MAX_PUSH_CONSTANT_COUNT     = 32;   // Vulkan 1.1 spec allows for 128-byte
+                                                            // of push constant (we assume 4-byte
+                                                            // types).

 // Per feature level caps
 // Use (int)FeatureLevel to index this array
@@ -112,7 +123,7 @@ static_assert(MAX_VERTEX_BUFFER_COUNT <= MAX_VERTEX_ATTRIBUTE_COUNT,
        "The number of buffer objects that can be attached to a VertexBuffer must be "
        "less than or equal to the maximum number of vertex attributes.");

-static constexpr size_t CONFIG_UNIFORM_BINDING_COUNT = 10;  // This is guaranteed by OpenGL ES.
+static constexpr size_t CONFIG_UNIFORM_BINDING_COUNT = 9;   // This is guaranteed by OpenGL ES.
 static constexpr size_t CONFIG_SAMPLER_BINDING_COUNT = 4;   // This is guaranteed by OpenGL ES.

 /**
@@ -158,14 +169,16 @@ static constexpr const char* backendToString(Backend backend) {
 }

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

 static constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguage) {
@@ -178,9 +191,75 @@ static constexpr const char* shaderLanguageToString(ShaderLanguage shaderLanguag
            return "SPIR-V";
        case ShaderLanguage::MSL:
            return "MSL";
+        case ShaderLanguage::METAL_LIBRARY:
+            return "Metal precompiled library";
    }
 }

+enum class ShaderStage : uint8_t {
+    VERTEX = 0,
+    FRAGMENT = 1,
+    COMPUTE = 2
+};
+
+static constexpr size_t PIPELINE_STAGE_COUNT = 2;
+enum class ShaderStageFlags : uint8_t {
+    NONE        =    0,
+    VERTEX      =    0x1,
+    FRAGMENT    =    0x2,
+    COMPUTE     =    0x4,
+    ALL_SHADER_STAGE_FLAGS = VERTEX | FRAGMENT | COMPUTE
+};
+
+static inline constexpr bool hasShaderType(ShaderStageFlags flags, ShaderStage type) noexcept {
+    switch (type) {
+        case ShaderStage::VERTEX:
+            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::VERTEX));
+        case ShaderStage::FRAGMENT:
+            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::FRAGMENT));
+        case ShaderStage::COMPUTE:
+            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::COMPUTE));
+    }
+}
+
+enum class DescriptorType : uint8_t {
+    UNIFORM_BUFFER,
+    SHADER_STORAGE_BUFFER,
+    SAMPLER,
+    INPUT_ATTACHMENT,
+};
+
+enum class DescriptorFlags : uint8_t {
+    NONE = 0x00,
+    DYNAMIC_OFFSET = 0x01
+};
+
+using descriptor_set_t = uint8_t;
+
+using descriptor_binding_t = uint8_t;
+
+struct DescriptorSetLayoutBinding {
+    DescriptorType type;
+    ShaderStageFlags stageFlags;
+    descriptor_binding_t binding;
+    DescriptorFlags flags = DescriptorFlags::NONE;
+    uint16_t count = 0;
+
+    friend inline bool operator==(
+            DescriptorSetLayoutBinding const& lhs,
+            DescriptorSetLayoutBinding const& rhs) noexcept {
+        return lhs.type == rhs.type &&
+               lhs.flags == rhs.flags &&
+               lhs.count == rhs.count &&
+               lhs.stageFlags == rhs.stageFlags;
+    }
+};
+
+struct DescriptorSetLayout {
+    utils::FixedCapacityVector<DescriptorSetLayoutBinding> bindings;
+};
+
+
 /**
 * Bitmask for selecting render buffers
 */
@@ -260,15 +339,6 @@ enum class FenceStatus : int8_t {
    TIMEOUT_EXPIRED = 1,        //!< wait()'s timeout expired. The Fence condition is not satisfied.
 };

-/**
- * Status codes for sync objects
- */
-enum class SyncStatus : int8_t {
-    ERROR = -1,          //!< An error occurred. The Sync is not signaled.
-    SIGNALED = 0,        //!< The Sync is signaled.
-    NOT_SIGNALED = 1,    //!< The Sync is not signaled yet
-};
-
 static constexpr uint64_t FENCE_WAIT_FOR_EVER = uint64_t(-1);

 /**
@@ -327,7 +397,7 @@ enum class UniformType : uint8_t {
 /**
 * Supported constant parameter types
 */
- enum class ConstantType : uint8_t {
+enum class ConstantType : uint8_t {
  INT,
  FLOAT,
  BOOL
@@ -358,6 +428,18 @@ enum class SamplerType : uint8_t {
    SAMPLER_CUBEMAP_ARRAY,  //!< Cube map array texture (feature level 2)
 };

+inline const char* stringify(SamplerType samplerType) {
+    switch (samplerType) {
+        case SamplerType::SAMPLER_2D: return "SAMPLER_2D";
+        case SamplerType::SAMPLER_2D_ARRAY: return "SAMPLER_2D_ARRAY";
+        case SamplerType::SAMPLER_CUBEMAP: return "SAMPLER_CUBEMAP";
+        case SamplerType::SAMPLER_EXTERNAL: return "SAMPLER_EXTERNAL";
+        case SamplerType::SAMPLER_3D: return "SAMPLER_3D";
+        case SamplerType::SAMPLER_CUBEMAP_ARRAY: return "SAMPLER_CUBEMAP_ARRAY";
+    }
+    return "UNKNOWN";
+}
+
 //! Subpass type
 enum class SubpassType : uint8_t {
    SUBPASS_INPUT
@@ -682,10 +764,28 @@ enum class TextureUsage : uint16_t {
    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
+    PROTECTED           = 0x0100,            //!< Texture can be used for protected content
+    DEFAULT             = UPLOADABLE | SAMPLEABLE,   //!< Default texture usage
+    ALL_ATTACHMENTS     = COLOR_ATTACHMENT | DEPTH_ATTACHMENT | STENCIL_ATTACHMENT | SUBPASS_INPUT,   //!< Mask of all attachments
 };

+inline const char* stringify(TextureUsage usage) {
+    switch (usage) {
+        case TextureUsage::NONE: return "NONE";
+        case TextureUsage::COLOR_ATTACHMENT: return "COLOR_ATTACHMENT";
+        case TextureUsage::DEPTH_ATTACHMENT: return "DEPTH_ATTACHMENT";
+        case TextureUsage::STENCIL_ATTACHMENT: return "STENCIL_ATTACHMENT";
+        case TextureUsage::UPLOADABLE: return "UPLOADABLE";
+        case TextureUsage::SAMPLEABLE: return "SAMPLEABLE";
+        case TextureUsage::SUBPASS_INPUT: return "SUBPASS_INPUT";
+        case TextureUsage::BLIT_SRC: return "BLIT_SRC";
+        case TextureUsage::BLIT_DST: return "BLIT_DST";
+        case TextureUsage::PROTECTED: return "PROTECTED";
+        case TextureUsage::DEFAULT: return "DEFAULT";
+        default: return "UNKNOWN";
+    }
+}
+
 //! Texture swizzle
 enum class TextureSwizzle : uint8_t {
    SUBSTITUTE_ZERO,
@@ -877,6 +977,9 @@ struct SamplerParams { // NOLINT

    struct EqualTo {
        bool operator()(SamplerParams lhs, SamplerParams rhs) const noexcept {
+            assert_invariant(lhs.padding0 == 0);
+            assert_invariant(lhs.padding1 == 0);
+            assert_invariant(lhs.padding2 == 0);
            auto* pLhs = reinterpret_cast<uint32_t const*>(reinterpret_cast<char const*>(&lhs));
            auto* pRhs = reinterpret_cast<uint32_t const*>(reinterpret_cast<char const*>(&rhs));
            return *pLhs == *pRhs;
@@ -885,6 +988,9 @@ struct SamplerParams { // NOLINT

    struct LessThan {
        bool operator()(SamplerParams lhs, SamplerParams rhs) const noexcept {
+            assert_invariant(lhs.padding0 == 0);
+            assert_invariant(lhs.padding1 == 0);
+            assert_invariant(lhs.padding2 == 0);
            auto* pLhs = reinterpret_cast<uint32_t const*>(reinterpret_cast<char const*>(&lhs));
            auto* pRhs = reinterpret_cast<uint32_t const*>(reinterpret_cast<char const*>(&rhs));
            return *pLhs == *pRhs;
@@ -892,6 +998,12 @@ struct SamplerParams { // NOLINT
    };

 private:
+    friend inline bool operator == (SamplerParams lhs, SamplerParams rhs) noexcept {
+        return SamplerParams::EqualTo{}(lhs, rhs);
+    }
+    friend inline bool operator != (SamplerParams lhs, SamplerParams rhs) noexcept {
+        return  !SamplerParams::EqualTo{}(lhs, rhs);
+    }
    friend inline bool operator < (SamplerParams lhs, SamplerParams rhs) noexcept {
        return SamplerParams::LessThan{}(lhs, rhs);
    }
@@ -1048,7 +1160,7 @@ struct RasterState {
            bool inverseFrontFaces                      : 1;        // 31

            //! padding, must be 0
-            uint8_t padding                             : 1;        // 32
+            bool depthClamp                             : 1;        // 32
        };
        uint32_t u = 0;
    };
@@ -1059,32 +1171,6 @@ struct RasterState {
 * \privatesection
 */

-enum class ShaderStage : uint8_t {
-    VERTEX = 0,
-    FRAGMENT = 1,
-    COMPUTE = 2
-};
-
-static constexpr size_t PIPELINE_STAGE_COUNT = 2;
-enum class ShaderStageFlags : uint8_t {
-    NONE        =    0,
-    VERTEX      =    0x1,
-    FRAGMENT    =    0x2,
-    COMPUTE     =    0x4,
-    ALL_SHADER_STAGE_FLAGS = VERTEX | FRAGMENT | COMPUTE
-};
-
-static inline constexpr bool hasShaderType(ShaderStageFlags flags, ShaderStage type) noexcept {
-    switch (type) {
-        case ShaderStage::VERTEX:
-            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::VERTEX));
-        case ShaderStage::FRAGMENT:
-            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::FRAGMENT));
-        case ShaderStage::COMPUTE:
-            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::COMPUTE));
-    }
-}
-
 /**
 * Selects which buffers to clear at the beginning of the render pass, as well as which buffers
 * can be discarded at the beginning and end of the render pass.
@@ -1186,11 +1272,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;
@@ -1198,13 +1300,15 @@ struct StencilState {
    uint8_t padding = 0;
 };

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

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

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

 enum class Workaround : uint16_t {
    // The EASU pass must split because shader compiler flattens early-exit branch
@@ -1216,23 +1320,14 @@ enum class Workaround : uint16_t {
    ADRENO_UNIFORM_ARRAY_CRASH,
    // Workaround a Metal pipeline compilation error with the message:
    // "Could not statically determine the target of a texture". See light_indirect.fs
-    A8X_STATIC_TEXTURE_TARGET_ERROR,
+    METAL_STATIC_TEXTURE_TARGET_ERROR,
    // Adreno drivers sometimes aren't able to blit into a layer of a texture array.
    DISABLE_BLIT_INTO_TEXTURE_ARRAY,
    // Multiple workarounds needed for PowerVR GPUs
    POWER_VR_SHADER_WORKAROUNDS,
-    // The driver has some threads pinned, and we can't easily know on which core, it can hurt
-    // performance more if we end-up pinned on the same one.
-    DISABLE_THREAD_AFFINITY
 };

-//! The type of technique for stereoscopic rendering
-enum class StereoscopicType : uint8_t {
-    // Stereoscopic rendering is performed using instanced rendering technique.
-    INSTANCED,
-    // Stereoscopic rendering is performed using the multiview feature from the graphics backend.
-    MULTIVIEW,
-};
+using StereoscopicType = backend::Platform::StereoscopicType;

 } // namespace filament::backend

@@ -1240,6 +1335,8 @@ template<> struct utils::EnableBitMaskOperators<filament::backend::ShaderStageFl
        : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::TargetBufferFlags>
        : public std::true_type {};
+template<> struct utils::EnableBitMaskOperators<filament::backend::DescriptorFlags>
+        : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::TextureUsage>
        : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::StencilFace>
@@ -23,6 +23,7 @@
 #include <utils/debug.h>

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

 #include <stdint.h>

@@ -41,6 +42,8 @@ struct HwTexture;
 struct HwTimerQuery;
 struct HwVertexBufferInfo;
 struct HwVertexBuffer;
+struct HwDescriptorSetLayout;
+struct HwDescriptorSet;

 /*
 * A handle to a backend resource. HandleBase is for internal use only.
@@ -75,6 +78,19 @@ protected:
    HandleBase(HandleBase const& rhs) noexcept = default;
    HandleBase& operator=(HandleBase const& rhs) noexcept = default;

+    HandleBase(HandleBase&& rhs) noexcept
+            : object(rhs.object) {
+        rhs.object = nullid;
+    }
+
+    HandleBase& operator=(HandleBase&& rhs) noexcept {
+        if (this != &rhs) {
+            object = rhs.object;
+            rhs.object = nullid;
+        }
+        return *this;
+    }
+
 private:
    HandleId object;
 };
@@ -89,8 +105,20 @@ struct Handle : public HandleBase {
    Handle() noexcept = default;

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

-    Handle& operator=(Handle const& rhs) noexcept = default;
+    // Explicitly redefine copy/move assignment operators rather than just using default here.
+    // Because it doesn't make a call to the parent's method automatically during the std::move
+    // function call(https://en.cppreference.com/w/cpp/algorithm/move) in certain compilers like
+    // NDK 25.1.8937393 and below (see b/371980551)
+    Handle& operator=(Handle const& rhs) noexcept {
+        HandleBase::operator=(rhs);
+        return *this;
+    }
+    Handle& operator=(Handle&& rhs) noexcept {
+        HandleBase::operator=(std::move(rhs));
+        return *this;
+    }

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

@@ -115,19 +143,21 @@ 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 VertexBufferInfoHandle = Handle<HwVertexBufferInfo>;
+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>;
+using DescriptorSetLayoutHandle = Handle<HwDescriptorSetLayout>;
+using DescriptorSetHandle       = Handle<HwDescriptorSet>;

 } // namespace filament::backend

@@ -22,17 +22,28 @@

 #include <utils/ostream.h>

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

 namespace filament::backend {

 //! \privatesection

+struct PipelineLayout {
+    using SetLayout = std::array<Handle<HwDescriptorSetLayout>, MAX_DESCRIPTOR_SET_COUNT>;
+    SetLayout setLayout;      // 16
+};
+
 struct PipelineState {
-    Handle<HwProgram> program;
-    RasterState rasterState;
-    StencilState stencilState;
-    PolygonOffset polygonOffset;
+    Handle<HwProgram> program;                                              //  4
+    Handle<HwVertexBufferInfo> vertexBufferInfo;                            //  4
+    PipelineLayout pipelineLayout;                                          // 16
+    RasterState rasterState;                                                //  4
+    StencilState stencilState;                                              // 12
+    PolygonOffset polygonOffset;                                            //  8
+    PrimitiveType primitiveType = PrimitiveType::TRIANGLES;                 //  1
+    uint8_t padding[3] = {};                                                //  3
 };

 } // namespace filament::backend
@@ -23,6 +23,7 @@
 #include <utils/Invocable.h>

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

 namespace filament::backend {

@@ -40,6 +41,26 @@ public:
    struct Fence {};
    struct Stream {};

+    /**
+     * The type of technique for stereoscopic rendering. (Note that the materials used will need to
+     * be compatible with the chosen technique.)
+     */
+    enum class StereoscopicType : uint8_t {
+        /**
+         * No stereoscopic rendering
+         */
+        NONE,
+        /**
+         * Stereoscopic rendering is performed using instanced rendering technique.
+         */
+        INSTANCED,
+        /**
+         * Stereoscopic rendering is performed using the multiview feature from the graphics
+         * backend.
+         */
+        MULTIVIEW,
+    };
+
    struct DriverConfig {
        /**
         * Size of handle arena in bytes. Setting to 0 indicates default value is to be used.
@@ -47,18 +68,36 @@ public:
         */
        size_t handleArenaSize = 0;

-        /**
-         * 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;
+        size_t metalUploadBufferSizeBytes = 512 * 1024;

        /**
         * Set to `true` to forcibly disable parallel shader compilation in the backend.
-         * Currently only honored by the GL backend.
+         * Currently only honored by the GL and Metal backends.
         */
        bool disableParallelShaderCompile = false;
+
+        /**
+         * Disable backend handles use-after-free checks.
+         */
+        bool disableHandleUseAfterFreeCheck = false;
+
+        /**
+         * Force GLES2 context if supported, or pretend the context is ES2. Only meaningful on
+         * GLES 3.x backends.
+         */
+        bool forceGLES2Context = false;
+
+        /**
+         * Sets the technique for stereoscopic rendering.
+         */
+        StereoscopicType stereoscopicType = StereoscopicType::NONE;
+
+        /**
+         * Assert the native window associated to a SwapChain is valid when calling makeCurrent().
+         * This is only supported for:
+         *      - PlatformEGLAndroid
+         */
+        bool assertNativeWindowIsValid = false;
    };

    Platform() noexcept;
@@ -188,9 +227,40 @@ public:
    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
@@ -48,7 +48,7 @@ namespace filament::backend {
 * and optional user data:
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * swapChain->setFrameScheduledCallback(myFrameScheduledCallback, nullptr);
+ * swapChain->setFrameScheduledCallback(nullptr, myFrameScheduledCallback);
 * if (renderer->beginFrame(swapChain)) {
 *     renderer->render(view);
 *     renderer->endFrame();
@@ -58,8 +58,6 @@ namespace filament::backend {
 * @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
 * backends ignore the callback (which will never be called) and proceed normally.
 *
- * @remark The SwapChain::FrameScheduledCallback is called on an arbitrary thread.
- *
 * Applications *must* call each PresentCallable they receive. Each PresentCallable represents a
 * frame that is waiting to be presented. If an application fails to call a PresentCallable, a
 * memory leak could occur. To "cancel" the presentation of a frame, pass false to the
@@ -24,9 +24,11 @@

 #include <backend/DriverEnums.h>

-#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 <array>
+#include <unordered_map>
+#include <tuple>
+#include <utility>
+#include <variant>

 #include <stddef.h>
 #include <stdint.h>
@@ -40,29 +42,36 @@ public:
    static constexpr size_t UNIFORM_BINDING_COUNT = CONFIG_UNIFORM_BINDING_COUNT;
    static constexpr size_t SAMPLER_BINDING_COUNT = CONFIG_SAMPLER_BINDING_COUNT;

-    struct Sampler {
-        utils::CString name = {};   // name of the sampler in the shader
-        uint32_t binding = 0;       // binding point of the sampler in the shader
+    struct Descriptor {
+        utils::CString name;
+        backend::DescriptorType type;
+        backend::descriptor_binding_t binding;
    };

-    struct SamplerGroupData {
-        utils::FixedCapacityVector<Sampler> samplers;
-        ShaderStageFlags stageFlags = ShaderStageFlags::ALL_SHADER_STAGE_FLAGS;
+    struct SpecializationConstant {
+        using Type = std::variant<int32_t, float, bool>;
+        uint32_t id;    // id set in glsl
+        Type value;     // value and type
    };

-    struct Uniform {
+    struct Uniform { // For ES2 support
        utils::CString name;    // full qualified name of the uniform field
        uint16_t offset;        // offset in 'uint32_t' into the uniform buffer
        uint8_t size;           // >1 for arrays
        UniformType type;       // uniform type
    };

-    using UniformBlockInfo = std::array<utils::CString, UNIFORM_BINDING_COUNT>;
-    using UniformInfo = utils::FixedCapacityVector<Uniform>;
-    using SamplerGroupInfo = std::array<SamplerGroupData, SAMPLER_BINDING_COUNT>;
+    using DescriptorBindingsInfo = utils::FixedCapacityVector<Descriptor>;
+    using DescriptorSetInfo = std::array<DescriptorBindingsInfo, MAX_DESCRIPTOR_SET_COUNT>;
+    using SpecializationConstantsInfo = utils::FixedCapacityVector<SpecializationConstant>;
    using ShaderBlob = utils::FixedCapacityVector<uint8_t>;
    using ShaderSource = std::array<ShaderBlob, SHADER_TYPE_COUNT>;

+    using AttributesInfo = utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>>;
+    using UniformInfo = utils::FixedCapacityVector<Uniform>;
+    using BindingUniformsInfo = utils::FixedCapacityVector<
+            std::tuple<uint8_t, utils::CString, Program::UniformInfo>>;
+
    Program() noexcept;

    Program(const Program& rhs) = delete;
@@ -79,85 +88,103 @@ public:
    Program& diagnostics(utils::CString const& name,
            utils::Invocable<utils::io::ostream&(utils::io::ostream& out)>&& logger);

-    // sets one of the program's shader (e.g. vertex, fragment)
+    // Sets one of the program's shader (e.g. vertex, fragment)
    // string-based shaders are null terminated, consequently the size parameter must include the
    // null terminating character.
    Program& shader(ShaderStage shader, void const* data, size_t size);

-    // Note: This is only needed for GLES3.0 backends, because the layout(binding=) syntax is
-    //       not permitted in glsl. The backend needs a way to associate a uniform block
-    //       to a binding point.
-    Program& uniformBlockBindings(
-            utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept;
+    // Sets the language of the shader sources provided with shader() (defaults to ESSL3)
+    Program& shaderLanguage(ShaderLanguage shaderLanguage);

-    // Note: This is only needed for GLES2.0, this is used to emulate UBO. This function tells
-    // the program everything it needs to know about the uniforms at a given binding
-    Program& uniforms(uint32_t index, UniformInfo const& uniforms) noexcept;
+    // Descriptor binding (set, binding, type -> shader name) info
+    Program& descriptorBindings(backend::descriptor_set_t set,
+            DescriptorBindingsInfo descriptorBindings) noexcept;

-    // Note: This is only needed for GLES2.0.
-    Program& attributes(
-            utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> attributes) noexcept;
+    Program& specializationConstants(SpecializationConstantsInfo specConstants) noexcept;

-    // sets the 'bindingPoint' sampler group descriptor for this program.
-    // 'samplers' can be destroyed after this call.
-    // This effectively associates a set of (BindingPoints, index) to a texture unit in the shader.
-    // Or more precisely, what layout(binding=) is set to in GLSL.
-    Program& setSamplerGroup(size_t bindingPoint, ShaderStageFlags stageFlags,
-            Sampler const* samplers, size_t count) noexcept;
-
-    struct SpecializationConstant {
-        using Type = std::variant<int32_t, float, bool>;
-        uint32_t id;                                // id set in glsl
-        Type value;                                 // value and type
+    struct PushConstant {
+        utils::CString name;
+        ConstantType type;
    };

-    Program& specializationConstants(
-            utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;
+    Program& pushConstants(ShaderStage stage,
+            utils::FixedCapacityVector<PushConstant> constants) noexcept;

    Program& cacheId(uint64_t cacheId) noexcept;

+    Program& multiview(bool multiview) noexcept;
+
+    // For ES2 support only...
+    Program& uniforms(uint32_t index, utils::CString name, UniformInfo uniforms) noexcept;
+    Program& attributes(AttributesInfo attributes) noexcept;
+
+    //
+    // Getters for program construction...
+    //
+
    ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
    ShaderSource& getShadersSource() noexcept { return mShadersSource; }

-    UniformBlockInfo const& getUniformBlockBindings() const noexcept { return mUniformBlocks; }
-    UniformBlockInfo& getUniformBlockBindings() noexcept { return mUniformBlocks; }
+    utils::CString const& getName() const noexcept { return mName; }
+    utils::CString& getName() noexcept { return mName; }

-    SamplerGroupInfo const& getSamplerGroupInfo() const { return mSamplerGroups; }
-    SamplerGroupInfo& getSamplerGroupInfo() { return mSamplerGroups; }
+    auto const& getShaderLanguage() const { return mShaderLanguage; }

-    auto const& getBindingUniformInfo() const { return mBindingUniformInfo; }
-    auto& getBindingUniformInfo() { return mBindingUniformInfo; }
+    uint64_t getCacheId() const noexcept { return mCacheId; }
+
+    bool isMultiview() const noexcept { return mMultiview; }
+
+    CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }
+
+    SpecializationConstantsInfo const& getSpecializationConstants() const noexcept {
+        return mSpecializationConstants;
+    }
+
+    SpecializationConstantsInfo& getSpecializationConstants() noexcept {
+        return mSpecializationConstants;
+    }
+
+    DescriptorSetInfo& getDescriptorBindings() noexcept {
+        return mDescriptorBindings;
+    }
+
+    utils::FixedCapacityVector<PushConstant> const& getPushConstants(
+            ShaderStage stage) const noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
+    utils::FixedCapacityVector<PushConstant>& getPushConstants(ShaderStage stage) noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
+    auto const& getBindingUniformInfo() const { return mBindingUniformsInfo; }
+    auto& getBindingUniformInfo() { return mBindingUniformsInfo; }

    auto const& getAttributes() const { return mAttributes; }
    auto& getAttributes() { return mAttributes; }

-    utils::CString const& getName() const noexcept { return mName; }
-    utils::CString& getName() noexcept { return mName; }
-
-    utils::FixedCapacityVector<SpecializationConstant> const& getSpecializationConstants() const noexcept {
-        return mSpecializationConstants;
-    }
-    utils::FixedCapacityVector<SpecializationConstant>& getSpecializationConstants() noexcept {
-        return mSpecializationConstants;
-    }
-
-    uint64_t getCacheId() const noexcept { return mCacheId; }
-
-    CompilerPriorityQueue getPriorityQueue() const noexcept { return mPriorityQueue; }
-
 private:
    friend utils::io::ostream& operator<<(utils::io::ostream& out, const Program& builder);

-    UniformBlockInfo mUniformBlocks = {};
-    SamplerGroupInfo mSamplerGroups = {};
    ShaderSource mShadersSource;
+    ShaderLanguage mShaderLanguage = ShaderLanguage::ESSL3;
    utils::CString mName;
    uint64_t mCacheId{};
-    utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
-    utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
-    utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;
-    std::array<UniformInfo, Program::UNIFORM_BINDING_COUNT> mBindingUniformInfo;
    CompilerPriorityQueue mPriorityQueue = CompilerPriorityQueue::HIGH;
+    utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
+    SpecializationConstantsInfo mSpecializationConstants;
+    std::array<utils::FixedCapacityVector<PushConstant>, SHADER_TYPE_COUNT> mPushConstants;
+    DescriptorSetInfo mDescriptorBindings;
+
+    // For ES2 support only
+    AttributesInfo mAttributes;
+    BindingUniformsInfo mBindingUniformsInfo;
+
+    // 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
@@ -29,13 +29,33 @@ namespace filament::backend {
 //! \privatesection

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

    // level to be used
    uint8_t level = 0;

-    // for cubemaps and 3D textures. See TextureCubemapFace for the face->layer mapping
+    // - For cubemap textures, this indicates the face of the cubemap. See TextureCubemapFace for
+    //   the face->layer mapping)
+    // - For 2d array, cubemap array, and 3d textures, this indicates an index of a single layer of
+    //   them.
+    // - For multiview textures (i.e., layerCount for the RenderTarget is greater than 1), this
+    //   indicates a starting layer index of the current 2d array texture for multiview.
    uint16_t layer = 0;
 };

@@ -60,7 +80,7 @@ public:

    MRT() noexcept = default;

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

@@ -89,7 +89,7 @@ public:
     * @return              The driver's SwapChain object.
     *
     */
-    virtual SwapChain* UTILS_NONNULL createSwapChain(
+    virtual SwapChain* UTILS_NULLABLE createSwapChain(
            void* UTILS_NULLABLE nativeWindow, uint64_t flags) noexcept = 0;

    /**
@@ -126,29 +126,76 @@ public:
    virtual TargetBufferFlags getPreservedFlags(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.
+     * Returns true if the swapchain is protected
     */
-    virtual uint32_t createDefaultRenderTarget() noexcept;
+    virtual bool isSwapChainProtected(Platform::SwapChain* UTILS_NONNULL swapChain) noexcept;

    /**
-     * 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.
+     * Called by the driver to establish the default FBO. The default implementation returns 0.
+     *
+     * 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 getDefaultFramebufferObject() noexcept;
+
+    /**
+     * Called by the backend when a frame starts.
+     * @param steady_clock_ns vsync time point on the monotonic clock
+     * @param refreshIntervalNs refresh interval in nanosecond
+     * @param frameId a frame id
+     */
+    virtual void beginFrame(
+            int64_t monotonic_clock_ns,
+            int64_t refreshIntervalNs,
+            uint32_t frameId) noexcept;
+
+    /**
+     * Called by the backend when a frame ends.
+     * @param frameId the frame id used in beginFrame
+     */
+    virtual void endFrame(
+            uint32_t frameId) noexcept;
+
+    /**
+     * Type of contexts available
+     */
+    enum class ContextType {
+        NONE,           //!< No current context
+        UNPROTECTED,    //!< current context is unprotected
+        PROTECTED       //!< current context supports protected content
+    };
+
+    /**
+     * Returns the type of the context currently in use. This value is updated by makeCurrent()
+     * and therefore can be cached between calls. ContextType::PROTECTED can only be returned
+     * if isProtectedContextSupported() is true.
+     * @return ContextType
+     */
+    virtual ContextType getCurrentContextType() const noexcept;
+
+    /**
+     * Binds the requested context to the current thread and drawSwapChain to the default FBO
+     * returned by getDefaultFramebufferObject().
+     *
+     * @param type type of context to bind to the current thread.
     * @param drawSwapChain SwapChain to draw to. It must be bound to the default FBO.
     * @param readSwapChain SwapChain to read from (for operation like `glBlitFramebuffer`)
+     * @return true on success, false on error.
     */
-    virtual void makeCurrent(
+    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(SwapChain*, SwapChain*).
+     * 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`)
@@ -161,6 +208,12 @@ public:
            utils::Invocable<void()> preContextChange,
            utils::Invocable<void(size_t index)> postContextChange) noexcept;

+    /**
+     * Called by the backend just before calling commit()
+     * @see commit()
+     */
+    virtual void preCommit() noexcept;
+
    /**
     * Called by the driver once the current frame finishes drawing. Typically, this should present
     * the drawSwapChain. This is for example where `eglMakeCurrent()` would be called.
@@ -57,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;
@@ -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;
@@ -99,11 +99,18 @@ 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;
+    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) 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;
@@ -132,21 +139,25 @@ protected:
    /**
     * Always use this instead of eglMakeCurrent(), as it tracks some state.
     */
-    EGLBoolean makeCurrent(EGLSurface drawSurface, EGLSurface readSurface) noexcept;

-    /**
-     * Returns true if the swapchain is protected
-     */
-    static bool isSwapChainProtected(Platform::SwapChain const* swapChain) 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;
    EGLContext mEGLContextProtected = EGL_NO_CONTEXT;
-    EGLSurface mCurrentDrawSurface = EGL_NO_SURFACE;
-    EGLSurface mCurrentReadSurface = EGL_NO_SURFACE;
-    EGLContext mCurrentContext = 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;
@@ -181,8 +192,20 @@ protected:
    EGLConfig findSwapChainConfig(uint64_t flags, bool window, bool pbuffer) const;

 private:
-    EGLBoolean makeCurrent(EGLContext context,
-            EGLSurface drawSurface, EGLSurface readSurface) noexcept;
+    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
@@ -22,6 +22,10 @@
 #include <backend/platforms/OpenGLPlatform.h>
 #include <backend/platforms/PlatformEGL.h>

+#include <utils/android/PerformanceHintManager.h>
+
+#include <chrono>
+
 #include <stddef.h>
 #include <stdint.h>

@@ -58,6 +62,13 @@ protected:

    void terminate() noexcept override;

+    void beginFrame(
+            int64_t monotonic_clock_ns,
+            int64_t refreshIntervalNs,
+            uint32_t frameId) noexcept override;
+
+    void preCommit() noexcept override;
+
    /**
     * Set the presentation time using `eglPresentationTimeANDROID`
     * @param presentationTimeInNanosecond
@@ -78,9 +89,28 @@ protected:
     */
    AcquiredImage transformAcquiredImage(AcquiredImage source) noexcept override;

+protected:
+    bool makeCurrent(ContextType type,
+            SwapChain* drawSwapChain,
+            SwapChain* readSwapChain) noexcept override;
+
 private:
+    struct InitializeJvmForPerformanceManagerIfNeeded {
+        InitializeJvmForPerformanceManagerIfNeeded();
+    };
+
    int mOSVersion;
    ExternalStreamManagerAndroid& mExternalStreamManager;
+    InitializeJvmForPerformanceManagerIfNeeded const mInitializeJvmForPerformanceManagerIfNeeded;
+    utils::PerformanceHintManager mPerformanceHintManager;
+    utils::PerformanceHintManager::Session mPerformanceHintSession;
+
+    using clock = std::chrono::high_resolution_clock;
+    clock::time_point mStartTimeOfActualWork;
+
+    void* mNativeWindowLib = nullptr;
+    int32_t (*ANativeWindow_getBuffersDefaultDataSpace)(ANativeWindow* window) = nullptr;
+    bool mAssertNativeWindowIsValid = false;
 };

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

 private:
@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+
+#ifndef TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_OSMESA_H
+#define TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_OSMESA_H
+
+#include <stdint.h>
+
+#include "bluegl/BlueGL.h"
+
+#include <osmesa.h>
+
+#include <backend/platforms/OpenGLPlatform.h>
+#include <backend/DriverEnums.h>
+
+namespace filament::backend {
+
+/**
+ * A concrete implementation of OpenGLPlatform that uses OSMesa, which is an offscreen
+ * context that can be used in conjunction with Mesa for software rasterization.
+ * See https://docs.mesa3d.org/osmesa.html for more information.
+ */
+class PlatformOSMesa : public OpenGLPlatform {
+protected:
+    // --------------------------------------------------------------------------------------------
+    // Platform Interface
+
+    Driver* createDriver(void* sharedGLContext, const DriverConfig& driverConfig) noexcept override;
+
+    int getOSVersion() const noexcept final override { return 0; }
+
+    // --------------------------------------------------------------------------------------------
+    // OpenGLPlatform Interface
+
+    void terminate() 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;
+    bool makeCurrent(ContextType type, SwapChain* drawSwapChain,
+            SwapChain* readSwapChain) noexcept override;
+    void commit(SwapChain* swapChain) noexcept override;
+
+private:
+    OSMesaContext mContext;
+    void* mOsMesaApi = nullptr;
+};
+
+} // namespace filament::backend
+
+#endif // TNT_FILAMENT_BACKEND_OPENGL_OPENGL_PLATFORM_OSMESA_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:
@@ -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;
 };

@@ -23,9 +23,9 @@

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

-#include <string_view>
 #include <tuple>
 #include <unordered_set>

@@ -47,6 +47,14 @@ struct VulkanPlatformPrivate;
 class VulkanPlatform : public Platform, utils::PrivateImplementation<VulkanPlatformPrivate> {
 public:

+    struct ExtensionHashFn {
+        std::size_t operator()(utils::CString const& s) const noexcept {
+            return std::hash<std::string>{}(s.data());
+        }
+    };
+    // Utility for managing device or instance extensions during initialization.
+    using ExtensionSet = std::unordered_set<utils::CString, ExtensionHashFn>;
+
    /**
     * A collection of handles to objects and metadata that comprises a Vulkan context. The client
     * can instantiate this struct and pass to Engine::Builder::sharedContext if they wishes to
@@ -82,6 +90,20 @@ public:
        VkExtent2D extent = {0, 0};
    };

+    struct ImageSyncData {
+        static constexpr uint32_t INVALID_IMAGE_INDEX = UINT32_MAX;
+
+        // The index of the next image as returned by vkAcquireNextImage or equivalent.
+        uint32_t imageIndex = INVALID_IMAGE_INDEX;
+
+        // Semaphore to be signaled once the image is available.
+        VkSemaphore imageReadySemaphore = VK_NULL_HANDLE;
+
+        // A function called right before vkQueueSubmit. After this call, the image must be 
+        // available. This pointer can be null if imageReadySemaphore is not VK_NULL_HANDLE.
+        std::function<void(SwapChainPtr handle)> explicitImageReadyWait = nullptr;
+    };
+
    VulkanPlatform();

    ~VulkanPlatform() override;
@@ -119,6 +141,12 @@ public:
         * before recreating the swapchain. Default is true.
         */
        bool flushAndWaitOnWindowResize = true;
+
+        /**
+         * Whether the swapchain image should be transitioned to a layout suitable for
+         * presentation. Default is true.
+         */
+        bool transitionSwapChainImageLayoutForPresent = true;
    };

    /**
@@ -147,13 +175,10 @@ public:
     * corresponding VkImage will be used as the output color attachment. The client should signal
     * the `clientSignal` semaphore when the image is ready to be used by the backend.
     * @param handle         The handle returned by createSwapChain()
-     * @param clientSignal   The semaphore that the client will signal to indicate that the backend
-     *                       may render into the image.
-     * @param index          Pointer to memory that will be filled with the index that corresponding
-     *                       to an image in the `SwapChainBundle.colors` array.
+     * @param outImageSyncData The synchronization data used for image readiness
     * @return               Result of acquire
     */
-    virtual VkResult acquire(SwapChainPtr handle, VkSemaphore clientSignal, uint32_t* index);
+    virtual VkResult acquire(SwapChainPtr handle, ImageSyncData* outImageSyncData);

    /**
     * Present the image corresponding to `index` to the display. The client should wait on
@@ -192,6 +217,13 @@ public:
    virtual SwapChainPtr createSwapChain(void* nativeWindow, uint64_t flags = 0,
            VkExtent2D extent = {0, 0});

+    /**
+     * Allows implementers to provide instance extensions that they'd like to include in the
+     * instance creation.
+     * @return          A set of extensions to enable for the instance.
+     */
+    virtual ExtensionSet getRequiredInstanceExtensions() { return {}; }
+
    /**
     * Destroy the swapchain.
     * @param handle    The handle returned by createSwapChain()
@@ -236,10 +268,9 @@ public:
    VkQueue getGraphicsQueue() const noexcept;

 private:
-    // Platform dependent helper methods
-    using ExtensionSet = std::unordered_set<std::string_view>;
-    static ExtensionSet getRequiredInstanceExtensions();
+    static ExtensionSet getSwapchainInstanceExtensions();

+    // Platform dependent helper methods
    using SurfaceBundle = std::tuple<VkSurfaceKHR, VkExtent2D>;
    static SurfaceBundle createVkSurfaceKHR(void* nativeWindow, VkInstance instance,
            uint64_t flags) noexcept;
@@ -50,12 +50,13 @@ class CommandBufferQueue {
    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() noexcept { return mCircularBuffer; }
@@ -80,6 +81,10 @@ public:
    // returns from waitForCommands() immediately.
    void requestExit();

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

@@ -134,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
@@ -168,7 +168,7 @@ struct CommandType<void (Driver::*)(ARGS...)> {

 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)
@@ -18,6 +18,7 @@
 #define TNT_FILAMENT_BACKEND_PRIVATE_DRIVER_H

 #include <backend/CallbackHandler.h>
+#include <backend/DescriptorSetOffsetArray.h>
 #include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
@@ -76,7 +77,7 @@ public:
    // the fn function will execute a batch of driver commands
    // this gives the driver a chance to wrap their execution in a meaningful manner
    // the default implementation simply calls fn
-    virtual void execute(std::function<void(void)> const& fn) noexcept;
+    virtual void execute(std::function<void(void)> const& fn);

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

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

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

 DECL_DRIVER_API_N(setFrameCompletedCallback,
        backend::SwapChainHandle, sch,
        backend::CallbackHandler*, handler,
-        backend::CallbackHandler::Callback, callback,
-        void*, user)
+        utils::Invocable<void(void)>&&, callback)

 DECL_DRIVER_API_N(setPresentationTime,
        int64_t, monotonic_clock_ns)
@@ -162,6 +163,10 @@ DECL_DRIVER_API_0(finish)
 // reset state tracking, if the driver does any state tracking (e.g. GL)
 DECL_DRIVER_API_0(resetState)

+DECL_DRIVER_API_N(setDebugTag,
+        backend::HandleBase::HandleId, handleId,
+        utils::CString, tag)
+
 /*
 * Creating driver objects
 * -----------------------
@@ -196,20 +201,33 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTexture,
        uint32_t, depth,
        backend::TextureUsage, usage)

-DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureSwizzled,
-        backend::SamplerType, target,
-        uint8_t, levels,
-        backend::TextureFormat, format,
-        uint8_t, samples,
-        uint32_t, width,
-        uint32_t, height,
-        uint32_t, depth,
-        backend::TextureUsage, usage,
+DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureView,
+        backend::TextureHandle, texture,
+        uint8_t, baseLevel,
+        uint8_t, levelCount)
+
+DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureViewSwizzle,
+        backend::TextureHandle, texture,
        backend::TextureSwizzle, r,
        backend::TextureSwizzle, g,
        backend::TextureSwizzle, b,
        backend::TextureSwizzle, a)

+DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage,
+        backend::TextureFormat, format,
+        uint32_t, width,
+        uint32_t, height,
+        backend::TextureUsage, usage,
+        void*, image)
+
+DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImagePlane,
+        backend::TextureFormat, format,
+        uint32_t, width,
+        uint32_t, height,
+        backend::TextureUsage, usage,
+        void*, image,
+        uint32_t, plane)
+
 DECL_DRIVER_API_R_N(backend::TextureHandle, importTexture,
        intptr_t, id,
        backend::SamplerType, target,
@@ -221,9 +239,6 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, importTexture,
        uint32_t, depth,
        backend::TextureUsage, usage)

-DECL_DRIVER_API_R_N(backend::SamplerGroupHandle, createSamplerGroup,
-        uint32_t, size, utils::FixedSizeString<32>, debugName)
-
 DECL_DRIVER_API_R_N(backend::RenderPrimitiveHandle, createRenderPrimitive,
        backend::VertexBufferHandle, vbh,
        backend::IndexBufferHandle, ibh,
@@ -239,6 +254,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)
@@ -256,25 +272,53 @@ DECL_DRIVER_API_R_N(backend::SwapChainHandle, createSwapChainHeadless,

 DECL_DRIVER_API_R_0(backend::TimerQueryHandle, createTimerQuery)

+DECL_DRIVER_API_R_N(backend::DescriptorSetLayoutHandle, createDescriptorSetLayout,
+        backend::DescriptorSetLayout&&, info)
+
+DECL_DRIVER_API_R_N(backend::DescriptorSetHandle, createDescriptorSet,
+        backend::DescriptorSetLayoutHandle, dslh)
+
+DECL_DRIVER_API_N(updateDescriptorSetBuffer,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_binding_t, binding,
+        backend::BufferObjectHandle, boh,
+        uint32_t, offset,
+        uint32_t, size
+)
+
+DECL_DRIVER_API_N(updateDescriptorSetTexture,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_binding_t, binding,
+        backend::TextureHandle, th,
+        SamplerParams, params
+)
+
+DECL_DRIVER_API_N(bindDescriptorSet,
+        backend::DescriptorSetHandle, dsh,
+        backend::descriptor_set_t, set,
+        backend::DescriptorSetOffsetArray&&, offsets
+)
+

 /*
 * Destroying driver objects
 * -------------------------
 */

-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)
-DECL_DRIVER_API_N(destroyProgram,         backend::ProgramHandle, ph)
-DECL_DRIVER_API_N(destroySamplerGroup,    backend::SamplerGroupHandle, sbh)
-DECL_DRIVER_API_N(destroyTexture,         backend::TextureHandle, th)
-DECL_DRIVER_API_N(destroyRenderTarget,    backend::RenderTargetHandle, rth)
-DECL_DRIVER_API_N(destroySwapChain,       backend::SwapChainHandle, sch)
-DECL_DRIVER_API_N(destroyStream,          backend::StreamHandle, sh)
-DECL_DRIVER_API_N(destroyTimerQuery,      backend::TimerQueryHandle, sh)
-DECL_DRIVER_API_N(destroyFence,           backend::FenceHandle, fh)
+DECL_DRIVER_API_N(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)
+DECL_DRIVER_API_N(destroyProgram,               backend::ProgramHandle, ph)
+DECL_DRIVER_API_N(destroyTexture,               backend::TextureHandle, th)
+DECL_DRIVER_API_N(destroyRenderTarget,          backend::RenderTargetHandle, rth)
+DECL_DRIVER_API_N(destroySwapChain,             backend::SwapChainHandle, sch)
+DECL_DRIVER_API_N(destroyStream,                backend::StreamHandle, sh)
+DECL_DRIVER_API_N(destroyTimerQuery,            backend::TimerQueryHandle, sh)
+DECL_DRIVER_API_N(destroyFence,                 backend::FenceHandle, fh)
+DECL_DRIVER_API_N(destroyDescriptorSetLayout,   backend::DescriptorSetLayoutHandle, dslh)
+DECL_DRIVER_API_N(destroyDescriptorSet,         backend::DescriptorSetHandle, dsh)

 /*
 * Synchronous APIs
@@ -299,10 +343,12 @@ 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, isProtectedContentSupported)
-DECL_DRIVER_API_SYNCHRONOUS_N(bool, isStereoSupported, backend::StereoscopicType, stereoscopicType)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isStereoSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isParallelShaderCompileSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isDepthStencilResolveSupported)
+DECL_DRIVER_API_SYNCHRONOUS_N(bool, isDepthStencilBlitSupported, backend::TextureFormat, format)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isProtectedTexturesSupported)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isDepthClampSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(uint8_t, getMaxDrawBuffers)
 DECL_DRIVER_API_SYNCHRONOUS_0(size_t, getMaxUniformBufferSize)
 DECL_DRIVER_API_SYNCHRONOUS_0(math::float2, getClipSpaceParams)
@@ -339,15 +385,6 @@ DECL_DRIVER_API_N(updateBufferObjectUnsynchronized,
 DECL_DRIVER_API_N(resetBufferObject,
        backend::BufferObjectHandle, ibh)

-DECL_DRIVER_API_N(updateSamplerGroup,
-        backend::SamplerGroupHandle, ubh,
-        backend::BufferDescriptor&&, data)
-
-DECL_DRIVER_API_N(setMinMaxLevels,
-        backend::TextureHandle, th,
-        uint32_t, minLevel,
-        uint32_t, maxLevel)
-
 DECL_DRIVER_API_N(update3DImage,
        backend::TextureHandle, th,
        uint32_t, level,
@@ -362,10 +399,12 @@ DECL_DRIVER_API_N(update3DImage,
 DECL_DRIVER_API_N(generateMipmaps,
        backend::TextureHandle, th)

+// Deprecated
 DECL_DRIVER_API_N(setExternalImage,
        backend::TextureHandle, th,
        void*, image)

+// Deprecated
 DECL_DRIVER_API_N(setExternalImagePlane,
        backend::TextureHandle, th,
        void*, image,
@@ -412,32 +451,16 @@ DECL_DRIVER_API_N(commit,
 * -----------------------
 */

-DECL_DRIVER_API_N(bindUniformBuffer,
-        uint32_t, index,
-        backend::BufferObjectHandle, ubh)
-
-DECL_DRIVER_API_N(bindBufferRange,
-        BufferObjectBinding, bindingType,
-        uint32_t, index,
-        backend::BufferObjectHandle, ubh,
-        uint32_t, offset,
-        uint32_t, size)
-
-DECL_DRIVER_API_N(unbindBuffer,
-        BufferObjectBinding, bindingType,
-        uint32_t, index)
-
-DECL_DRIVER_API_N(bindSamplers,
-        uint32_t, index,
-        backend::SamplerGroupHandle, sbh)
+DECL_DRIVER_API_N(setPushConstant,
+        backend::ShaderStage, stage,
+        uint8_t, index,
+        backend::PushConstantVariant, value)

 DECL_DRIVER_API_N(insertEventMarker,
-        const char*, string,
-        uint32_t, len = 0)
+        const char*, string)

 DECL_DRIVER_API_N(pushGroupMarker,
-        const char*, string,
-        uint32_t, len = 0)
+        const char*, string)

 DECL_DRIVER_API_0(popGroupMarker)

@@ -493,6 +516,17 @@ DECL_DRIVER_API_N(blit,
        math::uint2, srcOrigin,
        math::uint2, size)

+DECL_DRIVER_API_N(bindPipeline,
+        backend::PipelineState const&, state)
+
+DECL_DRIVER_API_N(bindRenderPrimitive,
+        backend::RenderPrimitiveHandle, rph)
+
+DECL_DRIVER_API_N(draw2,
+        uint32_t, indexOffset,
+        uint32_t, indexCount,
+        uint32_t, instanceCount)
+
 DECL_DRIVER_API_N(draw,
        backend::PipelineState, state,
        backend::RenderPrimitiveHandle, rph,
@@ -500,6 +534,7 @@ DECL_DRIVER_API_N(draw,
        uint32_t, indexCount,
        uint32_t, instanceCount)

+
 DECL_DRIVER_API_N(dispatchCompute,
        backend::ProgramHandle, program,
        math::uint3, workGroupCount)
@@ -18,6 +18,17 @@
 #define TNT_FILAMENT_BACKEND_PRIVATE_DRIVERAPI_H

 #include "backend/DriverApiForward.h"
+
 #include "private/backend/CommandStream.h"

+#include <stddef.h>
+
+namespace filament::backend {
+
+inline void* allocateFromCommandStream(DriverApi& driver, size_t size, size_t alignment) noexcept {
+    return driver.allocate(size, alignment);
+}
+
+} // namespace filament::backend
+
 #endif // TNT_FILAMENT_BACKEND_PRIVATE_DRIVERAPI_H
@@ -20,11 +20,12 @@
 #include <backend/Handle.h>

 #include <utils/Allocator.h>
+#include <utils/CString.h>
 #include <utils/Log.h>
+#include <utils/Panic.h>
 #include <utils/compiler.h>
 #include <utils/debug.h>
 #include <utils/ostream.h>
-#include <utils/Panic.h>

 #include <tsl/robin_map.h>

@@ -37,9 +38,9 @@
 #include <stddef.h>
 #include <stdint.h>

-#define HandleAllocatorGL  HandleAllocator<24,  64, 136>    // ~3640 / pool / MiB
-#define HandleAllocatorVK  HandleAllocator<80, 176, 320>    // ~1820 / pool / MiB
-#define HandleAllocatorMTL HandleAllocator<48, 160, 592>    // ~1310 / pool / MiB
+#define HandleAllocatorGL  HandleAllocator<32,  96, 136>    // ~4520 / pool / MiB
+#define HandleAllocatorVK  HandleAllocator<64, 160, 312>    // ~1820 / pool / MiB
+#define HandleAllocatorMTL HandleAllocator<32,  64, 552>    // ~1660 / pool / MiB

 namespace filament::backend {

@@ -49,7 +50,7 @@ namespace filament::backend {
 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();
@@ -65,7 +66,7 @@ public:
     *
     */
    template<typename D, typename ... ARGS>
-    Handle<D> allocateAndConstruct(ARGS&& ... args) noexcept {
+    Handle<D> allocateAndConstruct(ARGS&& ... args) {
        Handle<D> h{ allocateHandle<D>() };
        D* addr = handle_cast<D*>(h);
        new(addr) D(std::forward<ARGS>(args)...);
@@ -97,7 +98,7 @@ 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);
@@ -163,30 +164,88 @@ 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);
        auto [p, tag] = handleToPointer(handle.getId());

        if (isPoolHandle(handle.getId())) {
-            // check for use after free
-            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());
+            // check for pool handle 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;
+                // getHandleTag() is only called if the check fails.
+                FILAMENT_CHECK_POSTCONDITION(expectedAge == age)
+                        << "use-after-free of Handle with id=" << handle.getId()
+                        << ", tag=" << getHandleTag(handle.getId()).c_str_safe();
+            }
+        } else {
+            // check for heap handle use-after-free
+            if (UTILS_UNLIKELY(!mUseAfterFreeCheckDisabled)) {
+                uint8_t const index = (handle.getId() & HANDLE_INDEX_MASK);
+                // if we've already handed out this handle index before, it's definitely a
+                // use-after-free, otherwise it's probably just a corrupted handle
+                if (index < mId) {
+                    FILAMENT_CHECK_POSTCONDITION(p != nullptr)
+                            << "use-after-free of heap Handle with id=" << handle.getId()
+                            << ", tag=" << getHandleTag(handle.getId()).c_str_safe();
+                } else {
+                    FILAMENT_CHECK_POSTCONDITION(p != nullptr)
+                            << "corrupted heap Handle with id=" << handle.getId()
+                            << ", tag=" << getHandleTag(handle.getId()).c_str_safe();
+                }
+            }
        }

        return static_cast<Dp>(p);
    }

+    template<typename B>
+    bool is_valid(Handle<B>& handle) {
+        if (!handle) {
+            // null handles are invalid
+            return false;
+        }
+        auto [p, tag] = handleToPointer(handle.getId());
+        if (isPoolHandle(handle.getId())) {
+            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;
+            return expectedAge == age;
+        }
+        return p != nullptr;
+    }
+
    template<typename Dp, typename B>
    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));
    }

+    void associateTagToHandle(HandleBase::HandleId id, utils::CString&& tag) noexcept {
+        // TODO: for now, only pool handles check for use-after-free, so we only keep tags for
+        // those
+        if (isPoolHandle(id)) {
+            // Truncate the age to get the debug tag
+            uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+            // This line is the costly part. In the future, we could potentially use a custom
+            // allocator.
+            mDebugTags[key] = std::move(tag);
+        }
+    }
+
+    utils::CString getHandleTag(HandleBase::HandleId id) const noexcept {
+        if (!isPoolHandle(id)) {
+            return "(no tag)";
+        }
+        uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+        if (auto pos = mDebugTags.find(key); pos != mDebugTags.end()) {
+            return pos->second;
+        }
+        return "(no tag)";
+    }

 private:

@@ -210,8 +269,9 @@ private:
        Pool<P1> mPool1;
        Pool<P2> mPool2;
        UTILS_UNUSED_IN_RELEASE const utils::AreaPolicy::HeapArea& mArea;
+        bool mUseAfterFreeCheckDisabled;
    public:
-        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; }

@@ -237,8 +297,10 @@ private:
            // check for double-free
            Node* const pNode = static_cast<Node*>(p);
            uint8_t& expectedAge = pNode[-1].age;
-            ASSERT_POSTCONDITION(expectedAge == age,
-                    "double-free of Handle of size %d at %p", size, p);
+            if (UTILS_UNLIKELY(!mUseAfterFreeCheckDisabled)) {
+                FILAMENT_CHECK_POSTCONDITION(expectedAge == age) <<
+                        "double-free of Handle of size " << size << " at " << p;
+            }
            expectedAge = (expectedAge + 1) & 0xF; // fixme

            if (size <= mPool0.getSize()) { mPool0.free(p); return; }
@@ -302,18 +364,30 @@ private:
        }
    }

-    // 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;
+    // number if bits allotted to the handle's age (currently 4 max)
+    static constexpr uint32_t HANDLE_AGE_BIT_COUNT = 4;
+    // number if bits allotted to the handle's debug tag (HANDLE_AGE_BIT_COUNT max)
+    static constexpr uint32_t HANDLE_DEBUG_TAG_BIT_COUNT = 2;
+    // bit shift for both the age and debug tag
+    static constexpr uint32_t HANDLE_AGE_SHIFT = 27;
+    // mask for the heap (vs pool) flag
+    static constexpr uint32_t HANDLE_HEAP_FLAG = 0x80000000u;
+    // mask for the age
+    static constexpr uint32_t HANDLE_AGE_MASK =
+            ((1 << HANDLE_AGE_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the debug tag
+    static constexpr uint32_t HANDLE_DEBUG_TAG_MASK =
+            ((1 << HANDLE_DEBUG_TAG_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the index
+    static constexpr uint32_t HANDLE_INDEX_MASK = 0x07FFFFFFu;
+
+    static_assert(HANDLE_DEBUG_TAG_BIT_COUNT <= HANDLE_AGE_BIT_COUNT);

    static bool isPoolHandle(HandleBase::HandleId id) noexcept {
        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
@@ -322,7 +396,7 @@ private:
        // a non-pool handle.
        if (UTILS_LIKELY(isPoolHandle(id))) {
            char* const base = (char*)mHandleArena.getArea().begin();
-            uint32_t const tag = id & HANDLE_TAG_MASK;
+            uint32_t const tag = id & HANDLE_AGE_MASK;
            size_t const offset = (id & HANDLE_INDEX_MASK) * Allocator::getAlignment();
            return { static_cast<void*>(base + offset), tag };
        }
@@ -337,7 +411,7 @@ private:
        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;
+        id |= tag & HANDLE_AGE_MASK;
        assert_invariant((id & HANDLE_HEAP_FLAG) == 0);
        return id;
    }
@@ -347,7 +421,9 @@ private:
    // Below is only used when running out of space in the HandleArena
    mutable utils::Mutex mLock;
    tsl::robin_map<HandleBase::HandleId, void*> mOverflowMap;
+    tsl::robin_map<HandleBase::HandleId, utils::CString> mDebugTags;
    HandleBase::HandleId mId = 0;
+    bool mUseAfterFreeCheckDisabled = false;
 };

 } // namespace filament::backend
@@ -27,8 +27,8 @@ PresentCallable::PresentCallable(PresentFn fn, void* user) noexcept
 }

 void PresentCallable::operator()(bool presentFrame) noexcept {
-    ASSERT_PRECONDITION(mPresentFn, "This PresentCallable was already called. " \
-            "PresentCallables should be called exactly once.");
+    FILAMENT_CHECK_PRECONDITION(mPresentFn) << "This PresentCallable was already called. "
+                                               "PresentCallables should be called exactly once.";
    mPresentFn(presentFrame, mUser);
    // Set mPresentFn to nullptr to denote that the callable has been called.
    mPresentFn = nullptr;
@@ -24,7 +24,7 @@
 #include <utils/debug.h>
 #include <utils/ostream.h>

-#if !defined(WIN32) && !defined(__EMSCRIPTEN__) && !defined(IOS)
+#if !defined(WIN32) && !defined(__EMSCRIPTEN__)
 #    include <sys/mman.h>
 #    include <unistd.h>
 #    define HAS_MMAP 1
@@ -32,10 +32,11 @@
 #    define HAS_MMAP 0
 #endif

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

 using namespace utils;

@@ -81,6 +82,9 @@ void* CircularBuffer::alloc(size_t size) noexcept {
            // map the circular buffer once...
            vaddr = mmap(reserve_vaddr, size, PROT_READ | PROT_WRITE, MAP_PRIVATE, fd, 0);
            if (vaddr != MAP_FAILED) {
+                // populate the address space with pages (because this is a circular buffer,
+                // all the pages will be allocated eventually, might as well do it now)
+                memset(vaddr, 0, size);
                // and map the circular buffer again, behind the previous copy...
                vaddr_shadow = mmap((char*)vaddr + size, size,
                        PROT_READ | PROT_WRITE, MAP_PRIVATE, fd, 0);
@@ -101,7 +105,7 @@ void* CircularBuffer::alloc(size_t size) noexcept {
    if (UTILS_UNLIKELY(mAshmemFd < 0)) {
        // ashmem failed
        if (vaddr_guard != MAP_FAILED) {
-            munmap(vaddr_guard, size);
+            munmap(vaddr_guard, BLOCK_SIZE);
        }

        if (vaddr_shadow != MAP_FAILED) {
@@ -119,12 +123,11 @@ void* CircularBuffer::alloc(size_t size) noexcept {
        data = mmap(nullptr, size * 2 + BLOCK_SIZE,
                PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);

-        ASSERT_POSTCONDITION(data,
-                "couldn't allocate %u KiB of virtual address space for the command buffer",
-                (size * 2 / 1024));
+        FILAMENT_CHECK_POSTCONDITION(data != MAP_FAILED) <<
+                "couldn't allocate " << (size * 2 / 1024) <<
+                " KiB of virtual address space for the command buffer";

-        slog.d << "WARNING: Using soft CircularBuffer (" << (size * 2 / 1024) << " KiB)"
-               << io::endl;
+        slog.w << "Using 'soft' CircularBuffer (" << (size * 2 / 1024) << " KiB)" << io::endl;

        // guard page at the end
        void* guard = (void*)(uintptr_t(data) + size * 2);
@@ -39,10 +39,11 @@ 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);
 }

@@ -56,10 +57,23 @@ void CommandBufferQueue::requestExit() {
    mCondition.notify_one();
 }

+bool CommandBufferQueue::isPaused() const noexcept {
+    std::lock_guard<utils::Mutex> const lock(mLock);
+    return mPaused;
+}
+
+void CommandBufferQueue::setPaused(bool paused) {
+    std::lock_guard<utils::Mutex> const lock(mLock);
+    if (paused) {
+        mPaused = true;
+    } else {
+        mPaused = false;
+        mCondition.notify_one();
+    }
+}
+
 bool CommandBufferQueue::isExitRequested() const {
    std::lock_guard<utils::Mutex> const lock(mLock);
-    ASSERT_PRECONDITION( mExitRequested == 0 || mExitRequested == EXIT_REQUESTED,
-            "mExitRequested is corrupted (value = 0x%08x)!", mExitRequested);
    return (bool)mExitRequested;
 }

@@ -87,22 +101,23 @@ void CommandBufferQueue::flush() noexcept {
    size_t const used = std::distance(
            static_cast<char const*>(begin), static_cast<char const*>(end));

+
    std::unique_lock<utils::Mutex> lock(mLock);
+
+    // circular buffer is too small, we corrupted the stream
+    FILAMENT_CHECK_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: " << used <<
+            " bytes, overflow: " << used - mFreeSpace << " bytes";
+
+    mFreeSpace -= used;
    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, overflow: %u bytes",
-            (unsigned)used, unsigned(used - mFreeSpace));
-
    // wait until there is enough space in the buffer
-    mFreeSpace -= used;
    if (UTILS_UNLIKELY(mFreeSpace < requiredSize)) {

-
 #ifndef NDEBUG
        size_t const totalUsed = circularBuffer.size() - mFreeSpace;
        slog.d << "CommandStream used too much space (will block): "
@@ -115,6 +130,11 @@ void CommandBufferQueue::flush() noexcept {
 #endif

        SYSTRACE_NAME("waiting: CircularBuffer::flush()");
+
+        FILAMENT_CHECK_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;
@@ -127,19 +147,17 @@ std::vector<CommandBufferQueue::Range> CommandBufferQueue::waitForCommands() con
        return std::move(mCommandBuffersToExecute);
    }
    std::unique_lock<utils::Mutex> lock(mLock);
-    while (mCommandBuffersToExecute.empty() && !mExitRequested) {
+    while ((mCommandBuffersToExecute.empty() || mPaused) && !mExitRequested) {
        mCondition.wait(lock);
    }
-
-    ASSERT_PRECONDITION( mExitRequested == 0 || mExitRequested == EXIT_REQUESTED,
-            "mExitRequested is corrupted (value = 0x%08x)!", mExitRequested);
-
    return std::move(mCommandBuffersToExecute);
 }

 void CommandBufferQueue::releaseBuffer(CommandBufferQueue::Range const& buffer) {
+    size_t const used = std::distance(
+            static_cast<char const*>(buffer.begin), static_cast<char const*>(buffer.end));
    std::lock_guard<utils::Mutex> const lock(mLock);
-    mFreeSpace += uintptr_t(buffer.end) - uintptr_t(buffer.begin);
+    mFreeSpace += used;
    mCondition.notify_one();
 }

@@ -20,11 +20,16 @@
 #include <utils/CallStack.h>
 #endif

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

+#include <cstddef>
 #include <functional>
+#include <string>
+#include <utility>

 #ifdef __ANDROID__
 #include <sys/system_properties.h>
@@ -74,8 +79,8 @@ CommandStream::CommandStream(Driver& driver, CircularBuffer& buffer) noexcept
 }

 void CommandStream::execute(void* buffer) {
-    SYSTRACE_CALL();
-    SYSTRACE_CONTEXT();
+    // NOTE: we can't use SYSTRACE_CALL() or similar here because, execute() below, also
+    // uses systrace BEGIN/END and the END is not guaranteed to be happening in this scope.

    Profiler profiler;

@@ -100,6 +105,7 @@ void CommandStream::execute(void* buffer) {
            // we want to remove all this when tracing is completely disabled
            profiler.stop();
            UTILS_UNUSED Profiler::Counters const counters = profiler.readCounters();
+            SYSTRACE_CONTEXT();
            SYSTRACE_VALUE32("GLThread (I)", counters.getInstructions());
            SYSTRACE_VALUE32("GLThread (C)", counters.getCpuCycles());
            SYSTRACE_VALUE32("GLThread (CPI x10)", counters.getCPI() * 10);
@@ -149,7 +155,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();
@@ -214,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();
 }

@@ -101,6 +101,14 @@ struct HwProgram : public HwBase {
    HwProgram() noexcept = default;
 };

+struct HwDescriptorSetLayout : public HwBase {
+    HwDescriptorSetLayout() noexcept = default;
+};
+
+struct HwDescriptorSet : public HwBase {
+    HwDescriptorSet() noexcept = default;
+};
+
 struct HwSamplerGroup : public HwBase {
    HwSamplerGroup() noexcept = default;
 };
@@ -39,8 +39,10 @@ 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) {
+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.
@@ -74,8 +76,13 @@ HandleAllocator<P0, P1, P2>::Allocator::Allocator(AreaPolicy::HeapArea const& ar
 // ------------------------------------------------------------------------------------------------

 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) {
+    // Reserve initial space for debug tags. This prevents excessive calls to malloc when the first
+    // few tags are set.
+    mDebugTags.reserve(512);
 }

 template <size_t P0, size_t P1, size_t P2>
@@ -103,15 +110,15 @@ void* HandleAllocator<P0, P1, P2>::handleToPointerSlow(HandleBase::HandleId id)
 }

 template <size_t P0, size_t P1, size_t P2>
-HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size) noexcept {
+HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size) {
    void* p = ::malloc(size);
    std::unique_lock lock(mLock);

    HandleBase::HandleId id = (++mId) | HANDLE_HEAP_FLAG;

-    ASSERT_POSTCONDITION(mId < HANDLE_HEAP_FLAG,
+    FILAMENT_CHECK_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");
+            " for a while. Please increase FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB";

    mOverflowMap.emplace(id, p);
    lock.unlock();
@@ -53,4 +53,18 @@ size_t Platform::retrieveBlob(void const* key, size_t keySize, void* value, size
    return 0;
 }

+void Platform::setDebugUpdateStatFunc(DebugUpdateStatFunc&& debugUpdateStat) noexcept {
+    mDebugUpdateStat = std::move(debugUpdateStat);
+}
+
+bool Platform::hasDebugUpdateStatFunc() const noexcept {
+    return bool(mDebugUpdateStat);
+}
+
+void Platform::debugUpdateStat(const char* key, uint64_t value) {
+    if (mDebugUpdateStat) {
+        mDebugUpdateStat(key, value);
+    }
+}
+
 } // namespace filament::backend
@@ -29,21 +29,25 @@
        #include "backend/platforms/PlatformCocoaTouchGL.h"
    #endif
 #elif defined(__APPLE__)
-    #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
+    #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
        #include <backend/platforms/PlatformCocoaGL.h>
    #endif
 #elif defined(__linux__)
    #if defined(FILAMENT_SUPPORTS_X11)
-        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
+        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
            #include "backend/platforms/PlatformGLX.h"
        #endif
    #elif defined(FILAMENT_SUPPORTS_EGL_ON_LINUX)
-        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
+        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
            #include "backend/platforms/PlatformEGLHeadless.h"
        #endif
+    #elif defined(FILAMENT_SUPPORTS_OSMESA)
+        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
+            #include "backend/platforms/PlatformOSMesa.h"
+        #endif
    #endif
 #elif defined(WIN32)
-    #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
+    #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
        #include "backend/platforms/PlatformWGL.h"
    #endif
 #elif defined(__EMSCRIPTEN__)
@@ -111,8 +115,7 @@ Platform* PlatformFactory::create(Backend* backend) noexcept {
    }
    assert_invariant(*backend == Backend::OPENGL);
    #if defined(FILAMENT_SUPPORTS_OPENGL)
-        #if defined(FILAMENT_USE_EXTERNAL_GLES3) || defined(FILAMENT_USE_SWIFTSHADER)
-            // Swiftshader OpenGLES support is deprecated and incomplete
+        #if defined(FILAMENT_USE_EXTERNAL_GLES3)
            return nullptr;
        #elif defined(__ANDROID__)
            return new PlatformEGLAndroid();
@@ -125,6 +128,8 @@ Platform* PlatformFactory::create(Backend* backend) noexcept {
                return new PlatformGLX();
            #elif defined(FILAMENT_SUPPORTS_EGL_ON_LINUX)
                return new PlatformEGLHeadless();
+            #elif defined(FILAMENT_SUPPORTS_OSMESA)
+                return new PlatformOSMesa();
            #else
                return nullptr;
            #endif
@@ -14,14 +14,25 @@
 * limitations under the License.
 */

-#include "backend/Program.h"
+#include <backend/Program.h>
+#include <backend/DriverEnums.h>
+
+#include <utils/debug.h>
+#include <utils/CString.h>
+#include <utils/ostream.h>
+#include <utils/Invocable.h>
+
+#include <utility>
+
+#include <stddef.h>
+#include <stdint.h>

 namespace filament::backend {

 using namespace utils;

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

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

-Program& Program::uniformBlockBindings(
-        FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept {
-    for (auto const& item : uniformBlockBindings) {
-        assert_invariant(item.second < UNIFORM_BINDING_COUNT);
-        mUniformBlocks[item.second] = item.first;
-    }
+Program& Program::shaderLanguage(ShaderLanguage shaderLanguage) {
+    mShaderLanguage = shaderLanguage;
    return *this;
 }

-Program& Program::uniforms(uint32_t index, UniformInfo const& uniforms) noexcept {
-    assert_invariant(index < UNIFORM_BINDING_COUNT);
-    mBindingUniformInfo[index] = uniforms;
+Program& Program::descriptorBindings(backend::descriptor_set_t set,
+        DescriptorBindingsInfo descriptorBindings) noexcept {
+    mDescriptorBindings[set] = std::move(descriptorBindings);
    return *this;
 }

+Program& Program::uniforms(uint32_t index, utils::CString name, UniformInfo uniforms) noexcept {
+    mBindingUniformsInfo.reserve(mBindingUniformsInfo.capacity() + 1);
+    mBindingUniformsInfo.emplace_back(index, std::move(name), std::move(uniforms));
+    return *this;
+}

-Program& Program::attributes(
-        utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> attributes) noexcept {
+Program& Program::attributes(AttributesInfo attributes) noexcept {
    mAttributes = std::move(attributes);
    return *this;
 }

-Program& Program::setSamplerGroup(size_t bindingPoint, ShaderStageFlags stageFlags,
-        const Program::Sampler* samplers, size_t count) noexcept {
-    auto& groupData = mSamplerGroups[bindingPoint];
-    groupData.stageFlags = stageFlags;
-    auto& samplerList = groupData.samplers;
-    samplerList.reserve(count);
-    samplerList.resize(count);
-    std::copy_n(samplers, count, samplerList.data());
+Program& Program::specializationConstants(SpecializationConstantsInfo specConstants) noexcept {
+    mSpecializationConstants = std::move(specConstants);
    return *this;
 }

-Program& Program::specializationConstants(
-        FixedCapacityVector<SpecializationConstant> specConstants) noexcept {
-    mSpecializationConstants = std::move(specConstants);
+Program& Program::pushConstants(ShaderStage stage,
+        utils::FixedCapacityVector<PushConstant> constants) noexcept {
+    mPushConstants[static_cast<uint8_t>(stage)] = std::move(constants);
    return *this;
 }

@@ -91,6 +96,11 @@ Program& Program::cacheId(uint64_t cacheId) noexcept {
    return *this;
 }

+Program& Program::multiview(bool multiview) noexcept {
+    mMultiview = multiview;
+    return *this;
+}
+
 io::ostream& operator<<(io::ostream& out, const Program& builder) {
    out << "Program{";
    builder.mLogger(out);
@@ -16,13 +16,23 @@

 #include "private/backend/VirtualMachineEnv.h"

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

+#include <jni.h>
+
 namespace filament {

 JavaVM* VirtualMachineEnv::sVirtualMachine = nullptr;

-// This is called when the library is loaded. We need this to get a reference to the global VM
+/*
+ * This is typically called by filament_jni.so when it is loaded. If filament_jni.so is not used,
+ * then this must be called manually -- however, this is a problem because VirtualMachineEnv.h
+ * is currently private and part of backend.
+ * For now, we authorize this usage, but we will need to fix it; by making a proper public
+ * API for this.
+ */
+UTILS_PUBLIC
 UTILS_NOINLINE
 jint VirtualMachineEnv::JNI_OnLoad(JavaVM* vm) noexcept {
    JNIEnv* env = nullptr;
@@ -109,9 +109,8 @@ inline bool MTLSizeEqual(T a, T b) noexcept {
 MetalBlitter::MetalBlitter(MetalContext& context) noexcept : mContext(context) { }

 void MetalBlitter::blit(id<MTLCommandBuffer> cmdBuffer, const BlitArgs& args, const char* label) {
-
-    ASSERT_PRECONDITION(args.source.region.size.depth == args.destination.region.size.depth,
-            "Blitting requires the source and destination regions to have the same depth.");
+    FILAMENT_CHECK_PRECONDITION(args.source.region.size.depth == args.destination.region.size.depth)
+            << "Blitting requires the source and destination regions to have the same depth.";

    // Determine if the blit for color or depth are eligible to use a MTLBlitCommandEncoder.
    // blitFastPath returns true upon success.
@@ -327,7 +326,8 @@ id<MTLFunction> MetalBlitter::compileFragmentFunction(BlitFunctionKey key) const
            utils::slog.e << description << utils::io::endl;
        }
    }
-    ASSERT_POSTCONDITION(library && function, "Unable to compile fragment shader for MetalBlitter.");
+    FILAMENT_CHECK_POSTCONDITION(library && function)
+            << "Unable to compile fragment shader for MetalBlitter.";

    return function;
 }
@@ -352,7 +352,8 @@ id<MTLFunction> MetalBlitter::getBlitVertexFunction() {
            utils::slog.e << description << utils::io::endl;
        }
    }
-    ASSERT_POSTCONDITION(library && function, "Unable to compile vertex shader for MetalBlitter.");
+    FILAMENT_CHECK_POSTCONDITION(library && function)
+            << "Unable to compile vertex shader for MetalBlitter.";

    mVertexFunction = function;

@@ -18,7 +18,7 @@
 #define TNT_FILAMENT_DRIVER_METALBUFFER_H

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

 #include <backend/DriverEnums.h>

@@ -28,9 +28,134 @@

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

 namespace filament::backend {

+class ScopedAllocationTimer {
+public:
+    ScopedAllocationTimer(const char* name) : mBeginning(clock_t::now()), mName(name) {}
+    ~ScopedAllocationTimer() {
+        using namespace std::literals::chrono_literals;
+        static constexpr std::chrono::seconds LONG_TIME_THRESHOLD = 10s;
+
+        auto end = clock_t::now();
+        std::chrono::duration<double, std::micro> allocationTimeMicroseconds = end - mBeginning;
+
+        if (UTILS_UNLIKELY(allocationTimeMicroseconds > LONG_TIME_THRESHOLD)) {
+            if (platform && platform->hasDebugUpdateStatFunc()) {
+                char buffer[64];
+                snprintf(buffer, sizeof(buffer), "filament.metal.long_buffer_allocation_time.%s",
+                        mName);
+                platform->debugUpdateStat(
+                        buffer, static_cast<uint64_t>(allocationTimeMicroseconds.count()));
+            }
+        }
+    }
+
+    static void setPlatform(MetalPlatform* p) { platform = p; }
+
+private:
+    typedef std::chrono::steady_clock clock_t;
+
+    static MetalPlatform* platform;
+
+    std::chrono::time_point<clock_t> mBeginning;
+    const char* mName;
+};
+
+class TrackedMetalBuffer {
+public:
+
+    static constexpr size_t EXCESS_BUFFER_COUNT = 30000;
+
+    enum class Type {
+        NONE = 0,
+        GENERIC = 1,
+        RING = 2,       // deprecated
+        STAGING = 3,
+        DESCRIPTOR_SET = 4,
+    };
+    static constexpr size_t TypeCount = 4;
+
+    static constexpr auto toIndex(Type t) {
+        assert_invariant(t != Type::NONE);
+        switch (t) {
+            case Type::NONE:
+            case Type::GENERIC:
+                return 0;
+            case Type::RING:
+                return 1;
+            case Type::STAGING:
+                return 2;
+            case Type::DESCRIPTOR_SET:
+                return 3;
+        }
+    }
+
+    TrackedMetalBuffer() noexcept : mBuffer(nil) {}
+    TrackedMetalBuffer(nullptr_t) noexcept : mBuffer(nil) {}
+    TrackedMetalBuffer(id<MTLBuffer> buffer, Type type) : mBuffer(buffer), mType(type) {
+        assert_invariant(type != Type::NONE);
+        if (buffer) {
+            aliveBuffers[toIndex(type)]++;
+            mType = type;
+            if (getAliveBuffers() >= EXCESS_BUFFER_COUNT) {
+                if (platform && platform->hasDebugUpdateStatFunc()) {
+                    platform->debugUpdateStat("filament.metal.excess_buffers_allocated",
+                            TrackedMetalBuffer::getAliveBuffers());
+                }
+            }
+        }
+    }
+
+    ~TrackedMetalBuffer() {
+        if (mBuffer) {
+            assert_invariant(mType != Type::NONE);
+            aliveBuffers[toIndex(mType)]--;
+        }
+    }
+
+    TrackedMetalBuffer(TrackedMetalBuffer&&) = delete;
+    TrackedMetalBuffer(TrackedMetalBuffer const&) = delete;
+    TrackedMetalBuffer& operator=(TrackedMetalBuffer const&) = delete;
+
+    TrackedMetalBuffer& operator=(TrackedMetalBuffer&& rhs) noexcept {
+        swap(rhs);
+        return *this;
+    }
+
+    id<MTLBuffer> get() const noexcept { return mBuffer; }
+    operator bool() const noexcept { return bool(mBuffer); }
+
+    static uint64_t getAliveBuffers() {
+        uint64_t sum = 0;
+        for (const auto& v : aliveBuffers) {
+            sum += v;
+        }
+        return sum;
+    }
+
+    static uint64_t getAliveBuffers(Type type) {
+        assert_invariant(type != Type::NONE);
+        return aliveBuffers[toIndex(type)];
+    }
+    static void setPlatform(MetalPlatform* p) { platform = p; }
+
+private:
+    void swap(TrackedMetalBuffer& other) noexcept {
+        std::swap(mBuffer, other.mBuffer);
+        std::swap(mType, other.mType);
+    }
+
+    id<MTLBuffer> mBuffer;
+    Type mType = Type::NONE;
+
+    static MetalPlatform* platform;
+    static std::array<uint64_t, TypeCount> aliveBuffers;
+};
+
 class MetalBuffer {
 public:

@@ -38,6 +163,8 @@ public:
         size_t size, bool forceGpuBuffer = false);
    ~MetalBuffer();

+    [[nodiscard]] bool wasAllocationSuccessful() const noexcept { return mBuffer || mCpuBuffer; }
+
    MetalBuffer(const MetalBuffer& rhs) = delete;
    MetalBuffer& operator=(const MetalBuffer& rhs) = delete;

@@ -47,8 +174,10 @@ public:
     * Update the buffer with data inside src. Potentially allocates a new buffer allocation to hold
     * the bytes which will be released when the current frame is finished.
     */
-    void copyIntoBuffer(void* src, size_t size, size_t byteOffset);
-    void copyIntoBufferUnsynchronized(void* src, size_t size, size_t byteOffset);
+    using TagResolver = utils::Invocable<const char*(void)>;
+    void copyIntoBuffer(void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag);
+    void copyIntoBufferUnsynchronized(
+            void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag);

    /**
     * Denotes that this buffer is used for a draw call ensuring that its allocation remains valid
@@ -58,7 +187,7 @@ public:
     * is no device allocation.
     *
     */
-    id<MTLBuffer> getGpuBufferForDraw(id<MTLCommandBuffer> cmdBuffer) noexcept;
+    id<MTLBuffer> getGpuBufferForDraw() noexcept;

    void* getCpuBuffer() const noexcept { return mCpuBuffer; }

@@ -82,7 +211,18 @@ public:

 private:

-    id<MTLBuffer> mBuffer = nil;
+    enum class UploadStrategy {
+        POOL,
+        BUMP_ALLOCATOR,
+    };
+
+    void uploadWithPoolBuffer(
+            void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) const;
+    void uploadWithBumpAllocator(
+            void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) const;
+
+    UploadStrategy mUploadStrategy;
+    TrackedMetalBuffer mBuffer;
    size_t mBufferSize = 0;
    void* mCpuBuffer = nullptr;
    MetalContext& mContext;
@@ -131,7 +271,9 @@ public:
          mBufferOptions(options),
          mSlotSizeBytes(computeSlotSize(layout)),
          mSlotCount(slotCount) {
-        mBuffer = [device newBufferWithLength:mSlotSizeBytes * mSlotCount options:mBufferOptions];
+        ScopedAllocationTimer timer("ring");
+        mBuffer = { [device newBufferWithLength:mSlotSizeBytes * mSlotCount options:mBufferOptions],
+            TrackedMetalBuffer::Type::RING };
        assert_invariant(mBuffer);
    }

@@ -149,9 +291,13 @@ public:
            // If we already have an aux buffer, it will get freed here, unless it has been retained
            // by a MTLCommandBuffer. In that case, it will be freed when the command buffer
            // finishes executing.
-            mAuxBuffer = [mDevice newBufferWithLength:mSlotSizeBytes options:mBufferOptions];
+            {
+                ScopedAllocationTimer timer("ring");
+                mAuxBuffer = { [mDevice newBufferWithLength:mSlotSizeBytes options:mBufferOptions],
+                    TrackedMetalBuffer::Type::RING };
+            }
            assert_invariant(mAuxBuffer);
-            return {mAuxBuffer, 0};
+            return { mAuxBuffer.get(), 0 };
        }
        mCurrentSlot = (mCurrentSlot + 1) % mSlotCount;
        mOccupiedSlots->fetch_add(1, std::memory_order_relaxed);
@@ -180,9 +326,9 @@ public:
     */
    std::pair<id<MTLBuffer>, NSUInteger> getCurrentAllocation() const {
        if (UTILS_UNLIKELY(mAuxBuffer)) {
-            return { mAuxBuffer, 0 };
+            return { mAuxBuffer.get(), 0 };
        }
-        return { mBuffer, mCurrentSlot * mSlotSizeBytes };
+        return { mBuffer.get(), mCurrentSlot * mSlotSizeBytes };
    }

    bool canAccomodateLayout(MTLSizeAndAlign layout) const {
@@ -191,8 +337,8 @@ public:

 private:
    id<MTLDevice> mDevice;
-    id<MTLBuffer> mBuffer;
-    id<MTLBuffer> mAuxBuffer;
+    TrackedMetalBuffer mBuffer;
+    TrackedMetalBuffer mAuxBuffer;

    MTLResourceOptions mBufferOptions;

@@ -15,27 +15,49 @@
 */

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

 #include "MetalContext.h"

 namespace filament {
 namespace backend {

+std::array<uint64_t, TrackedMetalBuffer::TypeCount> TrackedMetalBuffer::aliveBuffers = { 0 };
+MetalPlatform* TrackedMetalBuffer::platform = nullptr;
+MetalPlatform* ScopedAllocationTimer::platform = nullptr;
+
 MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType, BufferUsage usage,
-        size_t size, bool forceGpuBuffer) : mBufferSize(size), mContext(context) {
+        size_t size, bool forceGpuBuffer)
+    : mBufferSize(size), mContext(context) {
+    const MetalBumpAllocator& allocator = *mContext.bumpAllocator;
+    // VERTEX is also used for index buffers
+    if (allocator.getCapacity() > 0 && bindingType == BufferObjectBinding::VERTEX) {
+        mUploadStrategy = UploadStrategy::BUMP_ALLOCATOR;
+    } else {
+        mUploadStrategy = UploadStrategy::POOL;
+    }
+
    // If the buffer is less than 4K in size and is updated frequently, we don't use an explicit
    // buffer. Instead, we use immediate command encoder methods like setVertexBytes:length:atIndex:.
    // This won't work for SSBOs, since they are read/write.
+
+    /*
    if (size <= 4 * 1024 && bindingType != BufferObjectBinding::SHADER_STORAGE &&
            usage == BufferUsage::DYNAMIC && !forceGpuBuffer) {
        mBuffer = nil;
        mCpuBuffer = malloc(size);
        return;
    }
+    */

    // Otherwise, we allocate a private GPU buffer.
-    mBuffer = [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate];
-    ASSERT_POSTCONDITION(mBuffer, "Could not allocate Metal buffer of size %zu.", size);
+    {
+        ScopedAllocationTimer timer("generic");
+        mBuffer = { [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate],
+            TrackedMetalBuffer::Type::GENERIC };
+    }
+    // mBuffer might fail to be allocated. Clients can check for this by calling
+    // wasAllocationSuccessful().
 }

 MetalBuffer::~MetalBuffer() {
@@ -44,56 +66,51 @@ MetalBuffer::~MetalBuffer() {
    }
 }

-void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
+void MetalBuffer::copyIntoBuffer(
+        void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) {
    if (size <= 0) {
        return;
    }
-    ASSERT_PRECONDITION(size + byteOffset <= mBufferSize,
-            "Attempting to copy %zu bytes into a buffer of size %zu at offset %zu",
-            size, mBufferSize, byteOffset);

-    // Either copy into the Metal buffer or into our cpu buffer.
+    FILAMENT_CHECK_PRECONDITION(src)
+            << "copyIntoBuffer called with a null src, tag=" << getHandleTag();
+    FILAMENT_CHECK_PRECONDITION(size + byteOffset <= mBufferSize)
+            << "Attempting to copy " << size << " bytes into a buffer of size " << mBufferSize
+            << " at offset " << byteOffset << ", tag=" << getHandleTag();
+    // The copy blit requires that byteOffset be a multiple of 4.
+    FILAMENT_CHECK_PRECONDITION(!(byteOffset & 0x3))
+            << "byteOffset must be a multiple of 4, tag=" << getHandleTag();
+
+    // If we have a cpu buffer, we can directly copy into it.
    if (mCpuBuffer) {
        memcpy(static_cast<uint8_t*>(mCpuBuffer) + byteOffset, src, size);
        return;
    }

-    // Acquire a staging buffer to hold the contents of this update.
-    MetalBufferPool* bufferPool = mContext.bufferPool;
-    const MetalBufferPoolEntry* const staging = bufferPool->acquireBuffer(size);
-    memcpy(staging->buffer.contents, src, size);
-
-    // The blit below requires that byteOffset be a multiple of 4.
-    ASSERT_PRECONDITION(!(byteOffset & 0x3u), "byteOffset must be a multiple of 4");
-
-    // Encode a blit from the staging buffer into the private GPU buffer.
-    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
-    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
-    blitEncoder.label = @"Buffer upload blit";
-    [blitEncoder copyFromBuffer:staging->buffer
-                   sourceOffset:0
-                       toBuffer:mBuffer
-              destinationOffset:byteOffset
-                           size:size];
-    [blitEncoder endEncoding];
-    [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> cb) {
-        bufferPool->releaseBuffer(staging);
-    }];
+    switch (mUploadStrategy) {
+        case UploadStrategy::BUMP_ALLOCATOR:
+            uploadWithBumpAllocator(src, size, byteOffset, std::move(getHandleTag));
+            break;
+        case UploadStrategy::POOL:
+            uploadWithPoolBuffer(src, size, byteOffset, std::move(getHandleTag));
+            break;
+    }
 }

-void MetalBuffer::copyIntoBufferUnsynchronized(void* src, size_t size, size_t byteOffset) {
+void MetalBuffer::copyIntoBufferUnsynchronized(
+        void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) {
    // TODO: implement the unsynchronized version
-    copyIntoBuffer(src, size, byteOffset);
+    copyIntoBuffer(src, size, byteOffset, std::move(getHandleTag));
 }

-id<MTLBuffer> MetalBuffer::getGpuBufferForDraw(id<MTLCommandBuffer> cmdBuffer) noexcept {
+id<MTLBuffer> MetalBuffer::getGpuBufferForDraw() noexcept {
    // If there's a CPU buffer, then we return nil here, as the CPU-side buffer will be bound
    // separately.
    if (mCpuBuffer) {
        return nil;
    }
    assert_invariant(mBuffer);
-    return mBuffer;
+    return mBuffer.get();
 }

 void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLCommandEncoder> encoder,
@@ -129,7 +146,7 @@ void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLCommandEncod
        }
        // getGpuBufferForDraw() might return nil, which means there isn't a device allocation for
        // this buffer. In this case, we'll bind the buffer below with the CPU-side memory.
-        id<MTLBuffer> gpuBuffer = buffer->getGpuBufferForDraw(cmdBuffer);
+        id<MTLBuffer> gpuBuffer = buffer->getGpuBufferForDraw();
        if (!gpuBuffer) {
            continue;
        }
@@ -189,5 +206,54 @@ void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLCommandEncod
    }
 }

+void MetalBuffer::uploadWithPoolBuffer(
+        void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) const {
+    MetalBufferPool* bufferPool = mContext.bufferPool;
+    const MetalBufferPoolEntry* const staging = bufferPool->acquireBuffer(size);
+    FILAMENT_CHECK_POSTCONDITION(staging)
+            << "uploadWithPoolbuffer unable to acquire staging buffer of size " << size
+            << ", tag=" << getHandleTag();
+    memcpy(staging->buffer.get().contents, src, size);
+
+    // Encode a blit from the staging buffer into the private GPU buffer.
+    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
+    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
+    blitEncoder.label = @"Buffer upload blit - pool buffer";
+    [blitEncoder copyFromBuffer:staging->buffer.get()
+                   sourceOffset:0
+                       toBuffer:mBuffer.get()
+              destinationOffset:byteOffset
+                           size:size];
+    [blitEncoder endEncoding];
+    [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> cb) {
+        bufferPool->releaseBuffer(staging);
+    }];
+}
+
+void MetalBuffer::uploadWithBumpAllocator(
+        void* src, size_t size, size_t byteOffset, TagResolver&& getHandleTag) const {
+    MetalBumpAllocator& allocator = *mContext.bumpAllocator;
+    auto [buffer, offset] = allocator.allocateStagingArea(size);
+    FILAMENT_CHECK_POSTCONDITION(buffer)
+            << "uploadWithBumpAllocator unable to acquire staging area of size " << size
+            << ", tag=" << getHandleTag();
+    void* const contents = buffer.contents;
+    FILAMENT_CHECK_POSTCONDITION(contents)
+            << "uploadWithBumpAllocator unable to acquire pointer to staging area, size " << size
+            << ", tag=" << getHandleTag();
+    memcpy(static_cast<char*>(contents) + offset, src, size);
+
+    // Encode a blit from the staging buffer into the private GPU buffer.
+    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
+    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
+    blitEncoder.label = @"Buffer upload blit - bump allocator";
+    [blitEncoder copyFromBuffer:buffer
+                   sourceOffset:offset
+                       toBuffer:mBuffer.get()
+              destinationOffset:byteOffset
+                           size:size];
+    [blitEncoder endEncoding];
+}
+
 } // namespace backend
 } // namespace filament
@@ -19,6 +19,8 @@

 #include <Metal/Metal.h>

+#include "MetalBuffer.h"
+
 #include <map>
 #include <mutex>
 #include <unordered_set>
@@ -30,12 +32,34 @@ struct MetalContext;

 // Immutable POD representing a shared CPU-GPU buffer.
 struct MetalBufferPoolEntry {
-    id<MTLBuffer> buffer;
+    TrackedMetalBuffer buffer;
    size_t capacity;
    mutable uint64_t lastAccessed;
    mutable uint32_t referenceCount;
 };

+class MetalBumpAllocator {
+public:
+    MetalBumpAllocator(id<MTLDevice> device, size_t capacity);
+
+    /**
+     * Allocates a staging area of the given size. Returns a pair of the buffer and the offset
+     * within the buffer. The buffer is guaranteed to be at least the given size, but may be larger.
+     * Clients must not write to the buffer beyond the returned offset + size.
+     * Clients are responsible for holding a reference to the returned buffer.
+     * Allocations are guaranteed to be aligned to 4 bytes.
+     */
+    std::pair<id<MTLBuffer>, size_t> allocateStagingArea(size_t size);
+
+    size_t getCapacity() const noexcept { return mCapacity; }
+
+private:
+    id<MTLDevice> mDevice;
+    TrackedMetalBuffer mCurrentUploadBuffer = nil;
+    size_t mHead = 0;
+    size_t mCapacity;
+};
+
 // Manages a pool of Metal buffers, periodically releasing ones that have been unused for awhile.
 class MetalBufferPool {
 public:
@@ -42,15 +42,20 @@ MetalBufferPoolEntry const* MetalBufferPool::acquireBuffer(size_t numBytes) {
    }

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

    return stage;
@@ -111,5 +116,39 @@ void MetalBufferPool::reset() noexcept {
    mFreeStages.clear();
 }

+MetalBumpAllocator::MetalBumpAllocator(id<MTLDevice> device, size_t capacity)
+    : mDevice(device), mCapacity(capacity) {
+    if (mCapacity > 0) {
+        mCurrentUploadBuffer = { [device newBufferWithLength:capacity options:MTLStorageModeShared],
+            TrackedMetalBuffer::Type::STAGING };
+    }
+}
+
+std::pair<id<MTLBuffer>, size_t> MetalBumpAllocator::allocateStagingArea(size_t size) {
+    if (size == 0) {
+        return { nil, 0 };
+    }
+    if (size > mCapacity) {
+        return { [mDevice newBufferWithLength:size options:MTLStorageModeShared], 0 };
+    }
+    assert_invariant(mCurrentUploadBuffer);
+
+    // Align the head to a 4-byte boundary.
+    mHead = (mHead + 3) & ~3;
+
+    if (UTILS_LIKELY(mHead + size <= mCapacity)) {
+        const size_t oldHead = mHead;
+        mHead += size;
+        return { mCurrentUploadBuffer.get(), oldHead };
+    }
+
+    // We're finished with the current allocation.
+    mCurrentUploadBuffer = { [mDevice newBufferWithLength:mCapacity options:MTLStorageModeShared],
+        TrackedMetalBuffer::Type::STAGING };
+    mHead = size;
+
+    return { mCurrentUploadBuffer.get(), 0 };
+}
+
 } // namespace backend
 } // namespace filament
@@ -21,6 +21,8 @@
 #include "MetalShaderCompiler.h"
 #include "MetalState.h"

+#include <backend/DriverEnums.h>
+
 #include <CoreVideo/CVMetalTextureCache.h>
 #include <Metal/Metal.h>
 #include <QuartzCore/QuartzCore.h>
@@ -44,27 +46,88 @@ namespace backend {
 class MetalDriver;
 class MetalBlitter;
 class MetalBufferPool;
+class MetalBumpAllocator;
 class MetalRenderTarget;
-class MetalSamplerGroup;
 class MetalSwapChain;
 class MetalTexture;
 class MetalTimerQueryInterface;
 struct MetalUniformBuffer;
 struct MetalIndexBuffer;
 struct MetalVertexBuffer;
+struct MetalDescriptorSet;

 constexpr static uint8_t MAX_SAMPLE_COUNT = 8;  // Metal devices support at most 8 MSAA samples

-struct MetalContext {
-    explicit MetalContext(size_t metalFreedTextureListSize)
-        : texturesToDestroy(metalFreedTextureListSize) {}
+class MetalPushConstantBuffer {
+public:
+    void setPushConstant(PushConstantVariant value, uint8_t index);
+    bool isDirty() const { return mDirty; }
+    void setBytes(id<MTLCommandEncoder> encoder, ShaderStage stage);
+    void clear();

+private:
+    std::vector<PushConstantVariant> mPushConstants;
+    bool mDirty = false;
+};
+
+class MetalDynamicOffsets {
+public:
+    void setOffsets(uint32_t set, const uint32_t* offsets, uint32_t count) {
+        assert(set < MAX_DESCRIPTOR_SET_COUNT);
+
+        auto getStartIndexForSet = [&](uint32_t s) {
+            uint32_t startIndex = 0;
+            for (uint32_t i = 0; i < s; i++) {
+                startIndex += mCounts[i];
+            }
+            return startIndex;
+        };
+
+        const bool resizeNecessary = mCounts[set] != count;
+        if (UTILS_UNLIKELY(resizeNecessary)) {
+            int delta = count - mCounts[set];
+
+            auto thisSetStart = mOffsets.begin() + getStartIndexForSet(set);
+            if (delta > 0) {
+                mOffsets.insert(thisSetStart, delta, 0);
+            } else {
+                mOffsets.erase(thisSetStart, thisSetStart - delta);
+            }
+
+            mCounts[set] = count;
+        }
+
+        if (resizeNecessary ||
+                !std::equal(
+                        offsets, offsets + count, mOffsets.begin() + getStartIndexForSet(set))) {
+            std::copy(offsets, offsets + count, mOffsets.begin() + getStartIndexForSet(set));
+            mDirty = true;
+        }
+    }
+    bool isDirty() const { return mDirty; }
+    void setDirty(bool dirty) { mDirty = dirty; }
+
+    std::pair<uint32_t, const uint32_t*> getOffsets() const {
+        return { mOffsets.size(), mOffsets.data() };
+    }
+
+private:
+    std::array<uint32_t, MAX_DESCRIPTOR_SET_COUNT> mCounts = { 0 };
+    std::vector<uint32_t> mOffsets;
+    bool mDirty = false;
+};
+
+struct MetalContext {
    MetalDriver* driver;
    id<MTLDevice> device = nullptr;
    id<MTLCommandQueue> commandQueue = nullptr;

-    id<MTLCommandBuffer> pendingCommandBuffer = nullptr;
-    id<MTLRenderCommandEncoder> currentRenderPassEncoder = nullptr;
+    // The ID of pendingCommandBuffer (or the next command buffer, if pendingCommandBuffer is nil).
+    uint64_t pendingCommandBufferId = 1;
+    // read from driver thread, set from completion handlers
+    std::atomic<uint64_t> latestCompletedCommandBufferId = 0;
+    id<MTLCommandBuffer> pendingCommandBuffer = nil;
+    id<MTLRenderCommandEncoder> currentRenderPassEncoder = nil;

    std::atomic<bool> memorylessLimitsReached = false;

@@ -80,7 +143,7 @@ struct MetalContext {
    } highestSupportedGpuFamily;

    struct {
-        bool a8xStaticTextureTargetError;
+        bool staticTextureTargetError;
    } bugs;

    // sampleCountLookup[requestedSamples] gives a <= sample count supported by the device.
@@ -95,10 +158,10 @@ struct MetalContext {
    // State trackers.
    PipelineStateTracker pipelineState;
    DepthStencilStateTracker depthStencilState;
-    std::array<BufferState, Program::UNIFORM_BINDING_COUNT> uniformState;
-    std::array<BufferState, MAX_SSBO_COUNT> ssboState;
    CullModeStateTracker cullModeState;
    WindingStateTracker windingState;
+    DepthClampStateTracker depthClampState;
+    Handle<HwRenderPrimitive> currentRenderPrimitive;

    // State caches.
    DepthStencilStateCache depthStencilStateCache;
@@ -108,24 +171,21 @@ struct MetalContext {

    PolygonOffset currentPolygonOffset = {0.0f, 0.0f};

-    MetalSamplerGroup* samplerBindings[Program::SAMPLER_BINDING_COUNT] = {};
+    std::array<MetalPushConstantBuffer, Program::SHADER_TYPE_COUNT> currentPushConstants;

-    // Keeps track of sampler groups we've finalized for the current render pass.
-    tsl::robin_set<MetalSamplerGroup*> finalizedSamplerGroups;
+    // Keeps track of descriptor sets we've finalized for the current render pass.
+    tsl::robin_set<MetalDescriptorSet*> finalizedDescriptorSets;
+    std::array<MetalDescriptorSet*, MAX_DESCRIPTOR_SET_COUNT> currentDescriptorSets = {};
+    MetalBufferBindings<MAX_DESCRIPTOR_SET_COUNT, ShaderStage::VERTEX> vertexDescriptorBindings;
+    MetalBufferBindings<MAX_DESCRIPTOR_SET_COUNT, ShaderStage::FRAGMENT> fragmentDescriptorBindings;
+    MetalBufferBindings<MAX_DESCRIPTOR_SET_COUNT, ShaderStage::COMPUTE> computeDescriptorBindings;
+    MetalDynamicOffsets dynamicOffsets;

-    // Keeps track of all alive sampler groups, textures.
-    tsl::robin_set<MetalSamplerGroup*> samplerGroups;
+    // Keeps track of all alive textures.
    tsl::robin_set<MetalTexture*> textures;

-    // This circular buffer implements delayed destruction for Metal texture handles. It keeps a
-    // handle to a fixed number of the most recently destroyed texture handles. When we're asked to
-    // destroy a texture handle, we free its texture memory, but keep the MetalTexture object alive,
-    // marking it as "terminated". If we later are asked to use that texture, we can check its
-    // terminated status and throw an Objective-C error instead of crashing, which is helpful for
-    // debugging use-after-free issues in release builds.
-    utils::FixedCircularBuffer<Handle<HwTexture>> texturesToDestroy;
-
    MetalBufferPool* bufferPool;
+    MetalBumpAllocator* bumpAllocator;

    MetalSwapChain* currentDrawSwapChain = nil;
    MetalSwapChain* currentReadSwapChain = nil;
@@ -136,6 +196,7 @@ struct MetalContext {

    // Empty texture used to prevent GPU errors when a sampler has been bound without a texture.
    id<MTLTexture> emptyTexture = nil;
+    id<MTLBuffer> emptyBuffer = nil;

    MetalBlitter* blitter = nullptr;

@@ -101,9 +101,14 @@ id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
    context->pendingCommandBuffer = [context->commandQueue commandBuffer];
    // It's safe for this block to capture the context variable. MetalDriver::terminate will ensure
    // all frames and their completion handlers finish before context is deallocated.
+    uint64_t thisCommandBufferId = context->pendingCommandBufferId;
    [context->pendingCommandBuffer addCompletedHandler:^(id <MTLCommandBuffer> buffer) {
        context->resourceTracker.clearResources((__bridge void*) buffer);
-        
+
+        // Command buffers should complete in order, so latestCompletedCommandBufferId will only
+        // ever increase.
+        context->latestCompletedCommandBufferId = thisCommandBufferId;
+
        auto errorCode = (MTLCommandBufferError)buffer.error.code;
        if (@available(macOS 11.0, *)) {
            if (errorCode == MTLCommandBufferErrorMemoryless) {
@@ -113,7 +118,8 @@ id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
            }
        }
    }];
-    ASSERT_POSTCONDITION(context->pendingCommandBuffer, "Could not obtain command buffer.");
+    FILAMENT_CHECK_POSTCONDITION(context->pendingCommandBuffer)
+            << "Could not obtain command buffer.";
    return context->pendingCommandBuffer;
 }

@@ -124,6 +130,7 @@ void submitPendingCommands(MetalContext* context) {
    assert_invariant(context->pendingCommandBuffer.status != MTLCommandBufferStatusCommitted);
    [context->pendingCommandBuffer commit];
    context->pendingCommandBuffer = nil;
+    context->pendingCommandBufferId++;
 }

 id<MTLTexture> getOrCreateEmptyTexture(MetalContext* context) {
@@ -153,5 +160,67 @@ bool isInRenderPass(MetalContext* context) {
    return context->currentRenderPassEncoder != nil;
 }

+void MetalPushConstantBuffer::setPushConstant(PushConstantVariant value, uint8_t index) {
+    if (mPushConstants.size() <= index) {
+        mPushConstants.resize(index + 1);
+        mDirty = true;
+    }
+    if (UTILS_LIKELY(mPushConstants[index] != value)) {
+        mDirty = true;
+        mPushConstants[index] = value;
+    }
+}
+
+void MetalPushConstantBuffer::setBytes(id<MTLCommandEncoder> encoder, ShaderStage stage) {
+    constexpr size_t PUSH_CONSTANT_SIZE_BYTES = 4;
+
+    static char buffer[MAX_PUSH_CONSTANT_COUNT * PUSH_CONSTANT_SIZE_BYTES];
+    assert_invariant(mPushConstants.size() <= MAX_PUSH_CONSTANT_COUNT);
+
+    size_t bufferSize = PUSH_CONSTANT_SIZE_BYTES * mPushConstants.size();
+    for (size_t i = 0; i < mPushConstants.size(); i++) {
+        const auto& constant = mPushConstants[i];
+        std::visit(
+                [i](auto arg) {
+                    if constexpr (std::is_same_v<decltype(arg), bool>) {
+                        // bool push constants are converted to uints in MSL.
+                        // We must ensure we write all the bytes for boolean values to work
+                        // correctly.
+                        uint32_t boolAsUint = arg ? 0x00000001 : 0x00000000;
+                        *(reinterpret_cast<uint32_t*>(buffer + PUSH_CONSTANT_SIZE_BYTES * i)) =
+                                boolAsUint;
+                    } else {
+                        *(decltype(arg)*)(buffer + PUSH_CONSTANT_SIZE_BYTES * i) = arg;
+                    }
+                },
+                constant);
+    }
+
+    switch (stage) {
+        case ShaderStage::VERTEX:
+            [(id<MTLRenderCommandEncoder>)encoder setVertexBytes:buffer
+                                                          length:bufferSize
+                                                         atIndex:PUSH_CONSTANT_BUFFER_INDEX];
+            break;
+        case ShaderStage::FRAGMENT:
+            [(id<MTLRenderCommandEncoder>)encoder setFragmentBytes:buffer
+                                                            length:bufferSize
+                                                           atIndex:PUSH_CONSTANT_BUFFER_INDEX];
+            break;
+        case ShaderStage::COMPUTE:
+            [(id<MTLComputeCommandEncoder>)encoder setBytes:buffer
+                                                     length:bufferSize
+                                                    atIndex:PUSH_CONSTANT_BUFFER_INDEX];
+            break;
+    }
+
+    mDirty = false;
+}
+
+void MetalPushConstantBuffer::clear() {
+    mPushConstants.clear();
+    mDirty = false;
+}
+
 } // namespace backend
 } // namespace filament
@@ -17,6 +17,7 @@
 #ifndef TNT_FILAMENT_DRIVER_METALDRIVER_H
 #define TNT_FILAMENT_DRIVER_METALDRIVER_H

+#include <backend/DriverEnums.h>
 #include "private/backend/Driver.h"
 #include "DriverBase.h"

@@ -31,6 +32,7 @@
 #include <functional>
 #include <mutex>
 #include <vector>
+#include <deque>

 namespace filament {
 namespace backend {
@@ -56,11 +58,11 @@ class MetalDriver final : public DriverBase {

 public:
    static Driver* create(MetalPlatform* platform, const Platform::DriverConfig& driverConfig);
-    void runAtNextTick(const std::function<void()>& fn) noexcept;

 private:

    friend class MetalSwapChain;
+    friend struct MetalDescriptorSet;

    MetalPlatform& mPlatform;
    MetalContext* mContext;
@@ -72,10 +74,23 @@ private:

    /*
     * Tasks run regularly on the driver thread.
+     * Not thread-safe; tasks are run from the driver thead and must be enqueued from the driver
+     * thread.
     */
+    void runAtNextTick(const std::function<void()>& fn) noexcept;
    void executeTickOps() noexcept;
    std::vector<std::function<void()>> mTickOps;
-    std::mutex mTickOpsLock;
+
+    // Tasks regularly executed on the driver thread after a command buffer has completed
+    struct DeferredTask {
+        DeferredTask(uint64_t commandBufferId, utils::Invocable<void()>&& fn) noexcept
+            : commandBufferId(commandBufferId), fn(std::move(fn)) {}
+        uint64_t commandBufferId;     // after this command buffer completes
+        utils::Invocable<void()> fn;  // execute this task
+    };
+    void executeAfterCurrentCommandBufferCompletes(utils::Invocable<void()>&& fn) noexcept;
+    void executeDeferredOps() noexcept;
+    std::deque<DeferredTask> mDeferredTasks;

    /*
     * Driver interface
@@ -136,10 +151,10 @@ private:
    inline void setRenderPrimitiveBuffer(Handle<HwRenderPrimitive> rph, PrimitiveType pt,
            Handle<HwVertexBuffer> vbh, Handle<HwIndexBuffer> ibh);

-    void finalizeSamplerGroup(MetalSamplerGroup* sg);
    void enumerateBoundBuffers(BufferObjectBinding bindingType,
            const std::function<void(const BufferState&, MetalBuffer*, uint32_t)>& f);

+    backend::StereoscopicType const mStereoscopicType;
 };

 } // namespace backend
--- a/Show More
+++ b/Show More