OpenGL: handle glFenceSync returning null

The current API used a void* in Texture::setExternalImage to pass
the platform specific image. This was a problem because on some
platform like Android, there could be several types (EGLImageKHR and
AHardwareBuffer), and with the void* there was no way to distinguish
them on the backend / platform side.

We now have a new Texture API which takes a
Platform::ExternalImageHandle, which is a reference-counted handle
to a Platform::ExternalImage. Platform::ExternalImage is an opaque
type only known by the platform.

This type must be created using a concrete Platform specific API, such
as:

PlatformEGL::createExternalImage
PlatformEGLAndroid::createExternalImage
PlatformCocoaGL::createExternalImage
PlatformCocoaTouchGL::createExternalImage

New types can easily be added in the future.

There is no "destroy" call because the Platform::ExternalImageHandle is
reference-counted and the client can let go of it as soon as it
doesn't need it any longer (typically after calling
Texture::setExternalImage). Platform::ExternalImage is a small
structure that just anonymously wraps the concrete types.

New internal driver APIs have been added to handle this functionality.

.github/workflows/presubmit.yml

@@ -77,9 +77,22 @@ jobs:
         run: |
           cd build/web && printf "y" | ./build.sh presubmit
 
+  validate-docs:
+    name: validate-docs
+    runs-on: ubuntu-22.04-4core
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - name: Check for manual edits to /docs
+        run: |
+           echo "${{ github.event.pull_request.head.sha }} -- ${{ github.event.pull_request.head.sha }}"
+           # disable for now
+           # bash docs_src/build/presubmit_check.sh ${{ github.event.pull_request.head.sha }}
+
   test-renderdiff:
     name: test-renderdiff
-    runs-on: ubuntu-22.04-32core
+    runs-on: ubuntu-22.04-16core
 
     steps:
       - uses: actions/checkout@v4.1.6

CMakeLists.txt

@@ -457,10 +457,19 @@ if (NOT WEBGL)
     set(GC_SECTIONS "-Wl,--gc-sections")
 endif()
 
+# Prevents stacks from being made for executable by explicitly adding this linker flag. Otherwise,
+# it generates warnings newly introduced as of GNU LD 2.39. Modern security practices strongly
+# recommend marking the stack as non-executable using the -z noexecstack linker flag to prevent
+# stack-based buffer overflow exploits.
+# See: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ffcf9c5700e49c0aee42dcba9a12ba21338e8136
+if (LINUX)
+    set(NO_EXEC_STACK "-Wl,-z,noexecstack")
+endif()
+
 set(B_SYMBOLIC_FUNCTIONS "-Wl,-Bsymbolic-functions")
 
 if (ANDROID)
-set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
+    set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
 endif()
 
 if (APPLE)
@@ -475,7 +484,7 @@ if (APPLE)
     set(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> qc -S <TARGET> <LINK_FLAGS> <OBJECTS>")
 endif()
 
-set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS} ${NO_EXEC_STACK}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS} ${BINARY_ALIGNMENT}")
 
 if (WEBGL_PTHREADS)
@@ -658,10 +667,6 @@ function(list_licenses OUTPUT MODULES)
 endfunction()
 
 set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/linux/combine-static-libs.sh")
-if (WIN32)
-    set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/windows/combine-static-libs.bat")
-    set(CMAKE_AR "lib.exe")
-endif()
 
 # Add a custom command to TARGET that combines the static libraries in DEPS into a single archive.
 function(combine_static_libs TARGET OUTPUT DEPS)
@@ -676,12 +681,22 @@ function(combine_static_libs TARGET OUTPUT DEPS)
         endif()
     endforeach()
 
-    add_custom_command(
-        TARGET ${TARGET} POST_BUILD
-        COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
-        COMMENT "Combining ${target} dependencies into single shared library"
-        VERBATIM
-    )
+    if (WIN32)
+        add_custom_command(
+            TARGET ${TARGET} POST_BUILD
+            COMMAND lib.exe /nologo /out:temp.lib ${DEPS_FILES}
+            COMMAND "${CMAKE_COMMAND}" -E rename temp.lib ${OUTPUT}
+            COMMENT "Combining ${target} dependencies into single shared library"
+            VERBATIM
+        )
+    else()
+        add_custom_command(
+            TARGET ${TARGET} POST_BUILD
+            COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
+            COMMENT "Combining ${target} dependencies into single shared library"
+            VERBATIM
+        )
+    endif()
 endfunction()
 
 # ==================================================================================================
@@ -752,6 +767,7 @@ add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${LIBRARIES}/viewer)
 add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
+add_subdirectory(${EXTERNAL}/abseil/tnt)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)

CODE_STYLE.md

@@ -121,9 +121,21 @@ private:
 - other headers are sorted in reverse order of their layering, that is, lower layer headers last
 - within a layer, headers are sorted alphabetically
 - strive for implementing one class per file
-- `STL` limited in public headers to:
-    - `type_traits`
+- `STL` limited in **filament** public headers to:
+    - `array`
+    - `initializer_list`
+    - `iterator`
     - `limits`
+    - `optional`
+    - `type_traits`
+    - `utility`
+    - `variant`
+
+For **libfilament** the rule of thumb is that STL headers that don't generate code are allowed (e.g. `type_traits`),
+conversely containers and algorithms are not allowed. There are exceptions such as `array`. See above for the full list.
+- The following `STL` headers are banned entirely, from public and private headers as well as implementation files:
+  - `iostream`
+
 
 *Sorting the headers is important to help catching missing `#include` directives.*
 

NEW_RELEASE_NOTES.md

@@ -7,3 +7,6 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- matdbg: Add support for debugging ESSL 1.0 shaders
+- backend: New platform API to better handle external textures [⚠️ **New Material Version**]

RELEASE_NOTES.md

@@ -7,6 +7,9 @@ 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.56.8
+
+
 ## v1.56.7
 
 

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

@@ -392,11 +392,11 @@ Java_com_google_android_filament_Engine_nIsValidSwapChain(JNIEnv*, jclass,
     return (jboolean)engine->isValid((SwapChain*)nativeSwapChain);
 }
 
-extern "C" JNIEXPORT void JNICALL
+extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
-        jlong nativeEngine) {
+        jlong nativeEngine, jlong timeout) {
     Engine* engine = (Engine*) nativeEngine;
-    engine->flushAndWait();
+    return engine->flushAndWait((uint64_t)timeout);
 }
 
 extern "C" JNIEXPORT void JNICALL

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

@@ -459,6 +459,13 @@ Java_com_google_android_filament_RenderableManager_nSetMaterialInstanceAt(JNIEnv
             materialInstance);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nClearMaterialInstanceAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    rm->clearMaterialInstanceAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_RenderableManager_nGetMaterialInstanceAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex) {

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

@@ -1271,7 +1271,28 @@ public class Engine {
      * {@link  android.view.SurfaceHolder.Callback#surfaceDestroyed surfaceDestroyed}.</p>
      */
     public void flushAndWait() {
-        nFlushAndWait(getNativeObject());
+        boolean unused = flushAndWait(Fence.WAIT_FOR_EVER);
+    }
+
+    /**
+     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
+     * all commands to this point are executed. Note that does guarantee that the
+     * hardware is actually finished.
+     *
+     * A timeout can be specified, if for some reason this flushAndWait doesn't complete before the timeout, it will
+     * return false, true otherwise.
+     *
+     * <p>This is typically used right after destroying the <code>SwapChain</code>,
+     * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
+     * timely fashion, such as when responding to Android's
+     * <code>android.view.SurfaceHolder.Callback.surfaceDestroyed</code></p>
+     *
+     * @param timeout A timeout in nanoseconds
+     * @return true if successful, false if flushAndWait timed out, in which case it wasn't successful and commands
+     * might still be executing on both the CPU and GPU sides.
+     */
+    public boolean flushAndWait(long timeout) {
+        return nFlushAndWait(getNativeObject(), timeout);
     }
 
     /**
@@ -1437,7 +1458,7 @@ public class Engine {
     private static native boolean nIsValidRenderTarget(long nativeEngine, long nativeTarget);
     private static native boolean nIsValidSwapChain(long nativeEngine, long nativeSwapChain);
     private static native void nDestroyEntity(long nativeEngine, int entity);
-    private static native void nFlushAndWait(long nativeEngine);
+    private static native boolean nFlushAndWait(long nativeEngine, long timeout);
     private static native void nFlush(long nativeEngine);
     private static native boolean nIsPaused(long nativeEngine);
     private static native void nSetPaused(long nativeEngine, boolean paused);

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

@@ -869,6 +869,13 @@ public class RenderableManager {
         nSetMaterialInstanceAt(mNativeObject, i, primitiveIndex, materialInstance.getNativeObject());
     }
 
+    /**
+     * Clears the material instance for the given primitive.
+     */
+    public void clearMaterialInstanceAt(@EntityInstance int i, @IntRange(from = 0) int primitiveIndex) {
+        nClearMaterialInstanceAt(mNativeObject, i, primitiveIndex);
+    }
+
     /**
      * Creates a MaterialInstance Java wrapper object for a particular material instance.
      */
@@ -1012,6 +1019,7 @@ public class RenderableManager {
     private static native void nGetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float[] center, float[] halfExtent);
     private static native int nGetPrimitiveCount(long nativeRenderableManager, int i);
     private static native void nSetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex, long nativeMaterialInstance);
+    private static native void nClearMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
     private static native void nSetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex, int blendOrder);

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

@@ -1420,10 +1420,10 @@ public class View {
         /**
          * Upscaling quality
          * LOW:    bilinear filtered blit. Fastest, poor quality
-         * MEDIUM: AMD FidelityFX FSR1 w/ mobile optimizations
+         * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
          * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
          * ULTRA:  AMD FidelityFX FSR1
-         *      FSR1 require a well anti-aliased (MSAA or TAA), noise free scene.
+         *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene. Avoid FXAA and dithering.
          *
          * The default upscaling quality is set to LOW.
          */

build/linux/ci-common.sh

@@ -1,16 +1,16 @@
 #!/bin/bash
 
 # version of clang we want to use
-GITHUB_CLANG_VERSION=14
+export GITHUB_CLANG_VERSION=14
 # version of CMake to use instead of the default one
-CMAKE_VERSION=3.19.5
+export GITHUB_CMAKE_VERSION=3.19.5
 # version of ninja to use
-NINJA_VERSION=1.10.2
+export GITHUB_NINJA_VERSION=1.10.2
 
 # Steps for GitHub Workflows
 if [[ "$GITHUB_WORKFLOW" ]]; then
     # Install ninja
-    wget -q https://github.com/ninja-build/ninja/releases/download/v$NINJA_VERSION/ninja-linux.zip
+    wget -q https://github.com/ninja-build/ninja/releases/download/v$GITHUB_NINJA_VERSION/ninja-linux.zip
     unzip -q ninja-linux.zip
     export PATH="$PWD:$PATH"
 
@@ -18,9 +18,9 @@ if [[ "$GITHUB_WORKFLOW" ]]; then
     mkdir -p cmake
     cd cmake
 
-    sudo wget https://github.com/Kitware/CMake/releases/download/v$CMAKE_VERSION/cmake-$CMAKE_VERSION-Linux-x86_64.sh
-    sudo chmod +x ./cmake-$CMAKE_VERSION-Linux-x86_64.sh
-    sudo ./cmake-$CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
+    sudo wget https://github.com/Kitware/CMake/releases/download/v$GITHUB_CMAKE_VERSION/cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh
+    sudo chmod +x ./cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh
+    sudo ./cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
     sudo update-alternatives --install /usr/bin/cmake cmake $(pwd)/bin/cmake 1000 --force
 
     cd ..

build/windows/combine-static-libs.bat

@@ -1,39 +0,0 @@
-@echo off
-set selfName=%0
-
-:: Check that we have at least 3 arguments.
-set argC=0
-for %%x in (%*) do Set /A argC+=1
-if %argC% LSS 3 goto :print_help
-
-set AR_TOOL=%1
-shift
-set OUTPUT_PATH=%1
-shift
-
-set ARCHIVES=
-:loop
-if [%1]==[] goto :finished
-set ARCHIVES=%ARCHIVES% %1
-shift
-goto :loop
-
-:finished
-
-%AR_TOOL% /nologo /out:%OUTPUT_PATH% %ARCHIVES% || goto :error
-
-exit /B %ERRORLEVEL%
-
-:print_help
-echo %selfName%. Combine multiple static libraries using an archiver tool.
-echo;
-echo Usage:
-echo     %selfName% ^<path-to-ar^> ^<output-archive^> ^<archives^>...
-echo;
-echo Notes:
-echo     ^<archives^> must be a list of absolute paths to static library archives.
-echo     This script creates a temporary working directory inside the current directory.
-exit /B 1
-
-:error
-exit /B %ERRORLEVEL%

docs_src/build/checks.py

@@ -0,0 +1,140 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This script contains several checks on the current commit, each corresponds to `possible_conditions`
+# in the main function below
+#   - Direct (non-filamentbot) edits of /docs
+#   - Edits to sources of READMEs that are duplicated to /docs
+#       or edits to /docs_src sources
+#   - Commit message has DOCS_BYPASS
+#   - Commit message has DOCS_FORCE
+#   - Commit message has DOCS_ALLOW_DIRECT_EDITS
+
+import json
+import sys
+import os
+
+from utils import execute, ArgParseImpl
+
+CUR_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.join(CUR_DIR, '../../')
+
+def get_last_commit_hash():
+  res, ret = execute('git rev-parse HEAD', cwd=ROOT_DIR)
+  assert res == 0, 'Failed to get the last commit hash'
+  return ret.strip()
+
+def get_edited_files(commit_hash):
+  INSERT = '#####?????'
+  res, ret = execute(f'git show --name-only --pretty=%b{INSERT} {commit_hash}')
+  assert res == 0, 'Failed to get edited filed'
+  files = []
+  _, after = ret.split(INSERT)
+  for r in filter(lambda a: len(a) > 0, after.split('\n')):
+    if r.startswith('commit'):
+      break
+    files.append(r)
+  return files
+
+# Returns True if there were no direct edits to '/docs'
+def check_no_direct_edits(commit_hash, printing=True):
+  bad = [f'\t{f}' for f in get_edited_files(commit_hash) if f.startswith('docs/')]
+  if printing and len(bad) > 0:
+    print(f'Found edits to /docs:\n' + '\n'.join(bad))
+  return len(bad) == 0
+
+# Returns True if docs sources have been modified
+def check_has_source_edits(commit_hash, printing=True):
+  config = {}
+  with open(f'{CUR_DIR}/duplicates.json') as config_txt:
+    config = json.loads(config_txt.read())
+  source_files = set(config.keys())
+  edited_files = set(get_edited_files(commit_hash))
+  overlap = [f'\t{f}' for f in list(source_files & edited_files)]
+  if printing and len(overlap) > 0:
+    print(f'Found edited source files:\n' + '\n'.join(overlap))
+  return len(overlap) > 0
+
+# Returns true in a given TAG is found in the commit msg
+def commit_msg_has_tag(commit_hash, tag, printing=True):
+  res, ret = execute(f'git log --pretty=%B {commit_hash}', cwd=ROOT_DIR)
+  for l in ret.split('\n'):
+    if tag == l.strip():
+      if printing:
+        print(f'Found tag={tag} in commit message')
+      return True
+  return False
+
+if __name__ == "__main__":
+  parser = ArgParseImpl()
+
+  TAG_DOCS_BYPASS = 'DOCS_BYPASS'
+  TAG_DOCS_FORCE = 'DOCS_FORCE'
+  TAG_DOCS_ALLOW_DIRECT_EDITS = 'DOCS_ALLOW_DIRECT_EDITS'
+
+  possible_conditions = {
+      'no_direct_edits':
+          check_no_direct_edits,
+      'source_edits':
+          check_has_source_edits,
+      'commit_docs_bypass':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_BYPASS),
+      'commit_docs_force':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_FORCE),
+      'commit_docs_allow_direct_edits':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_ALLOW_DIRECT_EDITS),
+  }
+
+  possible_str = ', '.join(list(possible_conditions.keys()))
+  parser.add_argument(
+      '--do-and',
+      type=str,
+      help=(
+          f'A conjunction of boolean conditions. Possible values are={possible_str}. '
+          'Negation is done with `-`'
+      )
+  )
+  parser.add_argument(
+      '--do-or',
+      type=str,
+      help=(
+          f'A disjunction of boolean conditions. Possible values are={possible_str}. '
+          'Negation is done with `-`'
+      )
+  )
+
+  args, _ = parser.parse_known_args(sys.argv[1:len(sys.argv) - 1])
+  commit_hash = sys.argv[-1]
+
+  assert not (args.do_and and args.do_or), "Must not supply both '--do-and' and '--do-or'"
+  assert args.do_and or args.do_or, "Must supply argument '--do-and' or '--do-or'"
+  conds = args.do_and.split(',') if args.do_and else args.do_or.split(',')
+  conds = [c.strip() for c in conds]
+  assert all(
+    [c in possible_conditions.keys() for c in
+     [(c.replace('-', '') if c.startswith('-') else c) for c in conds]]),\
+     f"Not all conditions are valid names. Only {possible_str} are accepted"
+
+  res = []
+  for cond in conds:
+    if cond.startswith('-'):
+      f = lambda: not possible_conditions[cond.replace('-', '')]()
+    else:
+      f = possible_conditions[cond]
+    res.append(f(commit_hash))
+
+  if args.do_and:
+    exit(0 if all(res) else 1)
+  else:
+    exit(0 if any(res) else 1)

docs_src/build/presubmit_check.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/bash
+
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+COMMIT_HASH=$1
+python3 docs_src/build/checks.py --do-or="no_direct_edits,commit_docs_allow_direct_edits" $COMMIT_HASH ||\
+    (echo "Direct edits to /docs are not allowed. Please see /docs_src/README.md if you need to bypass this check." && exit 1)

filament/CMakeLists.txt

@@ -252,6 +252,7 @@ set(MATERIAL_SRCS
         src/materials/fsr/fsr_easu_mobile.mat
         src/materials/fsr/fsr_easu_mobileF.mat
         src/materials/fsr/fsr_rcas.mat
+        src/materials/sgsr/sgsr1.mat
         src/materials/resolveDepth.mat
         src/materials/separableGaussianBlur.mat
         src/materials/skybox.mat
@@ -384,16 +385,16 @@ endforeach()
 
 add_custom_command(
         OUTPUT "${MATERIAL_DIR}/colorGrading.filamat"
-        DEPENDS ../shaders/src/dithering.fs
-        DEPENDS ../shaders/src/vignette.fs
+        DEPENDS ../shaders/src/inline_dithering.fs
+        DEPENDS ../shaders/src/inline_vignette.fs
         DEPENDS src/materials/colorGrading/colorGrading.fs
         APPEND
 )
 
 add_custom_command(
         OUTPUT "${MATERIAL_DIR}/colorGradingAsSubpass.filamat"
-        DEPENDS ../shaders/src/dithering.fs
-        DEPENDS ../shaders/src/vignette.fs
+        DEPENDS ../shaders/src/inline_dithering.fs
+        DEPENDS ../shaders/src/inline_vignette.fs
         DEPENDS src/materials/colorGrading/colorGrading.fs
         APPEND
 )
@@ -504,6 +505,12 @@ add_custom_command(
         APPEND
 )
 
+add_custom_command(
+        OUTPUT "${MATERIAL_DIR}/sgsr1.filamat"
+        DEPENDS src/materials/sgsr/sgsr1_shader_mobile.fs
+        APPEND
+)
+
 add_custom_command(
         OUTPUT "${MATERIAL_DIR}/separableGaussianBlur.filamat"
         DEPENDS src/materials/separableGaussianBlur.vs

filament/backend/CMakeLists.txt

@@ -139,11 +139,11 @@ if (FILAMENT_SUPPORTS_METAL)
             src/metal/MetalEnums.mm
             src/metal/MetalExternalImage.mm
             src/metal/MetalHandles.mm
-            src/metal/MetalPlatform.mm
             src/metal/MetalShaderCompiler.mm
             src/metal/MetalState.mm
             src/metal/MetalTimerQuery.mm
             src/metal/MetalUtils.mm
+            src/metal/PlatformMetal.mm
     )
 
     set(METAL_CPP_SRCS
@@ -185,8 +185,15 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/platform/VulkanPlatform.cpp
             src/vulkan/platform/VulkanPlatformSwapChainImpl.cpp
             src/vulkan/platform/VulkanPlatformSwapChainImpl.h
-            src/vulkan/spirv/VulkanSpirvUtils.cpp
-            src/vulkan/spirv/VulkanSpirvUtils.h
+            src/vulkan/utils/Conversion.cpp
+            src/vulkan/utils/Conversion.h
+            src/vulkan/utils/Definitions.h
+            src/vulkan/utils/Helper.h
+            src/vulkan/utils/Image.h
+            src/vulkan/utils/Image.cpp
+            src/vulkan/utils/Spirv.h
+            src/vulkan/utils/Spirv.cpp
+            src/vulkan/utils/StaticVector.h
             src/vulkan/VulkanAsyncHandles.cpp
             src/vulkan/VulkanAsyncHandles.h
             src/vulkan/VulkanBlitter.cpp
@@ -205,8 +212,6 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanFboCache.h
             src/vulkan/VulkanHandles.cpp
             src/vulkan/VulkanHandles.h
-            src/vulkan/VulkanImageUtility.cpp
-            src/vulkan/VulkanImageUtility.h
             src/vulkan/VulkanMemory.h
             src/vulkan/VulkanMemory.cpp
             src/vulkan/VulkanPipelineCache.cpp
@@ -221,8 +226,6 @@ if (FILAMENT_SUPPORTS_VULKAN)
             src/vulkan/VulkanReadPixels.h
             src/vulkan/VulkanTexture.cpp
             src/vulkan/VulkanTexture.h
-            src/vulkan/VulkanUtility.cpp
-            src/vulkan/VulkanUtility.h
     )
     if (LINUX OR WIN32)
         list(APPEND SRCS src/vulkan/platform/VulkanPlatformLinuxWindows.cpp)

filament/backend/include/backend/DriverEnums.h

@@ -33,9 +33,9 @@
 
 #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 <array>
+#include <type_traits>
+#include <variant>
 
 #include <stddef.h>
 #include <stdint.h>
@@ -1302,7 +1302,7 @@ enum class Workaround : uint16_t {
     // for some uniform arrays, it's needed to do an initialization to avoid crash on adreno gpu
     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
+    // "Could not statically determine the target of a texture". See surface_light_indirect.fs
     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,

filament/backend/include/backend/Handle.h

@@ -130,7 +130,7 @@ struct Handle : public HandleBase {
     bool operator>=(const Handle& rhs) const noexcept { return getId() >= rhs.getId(); }
 
     // type-safe Handle cast
-    template<typename B, typename = std::enable_if_t<std::is_base_of<T, B>::value> >
+    template<typename B, typename = std::enable_if_t<std::is_base_of_v<T, B>> >
     Handle(Handle<B> const& base) noexcept : HandleBase(base) { } // NOLINT(hicpp-explicit-conversions,google-explicit-constructor)
 
 private:

filament/backend/include/backend/Platform.h

@@ -25,6 +25,8 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include <atomic>
+
 namespace filament::backend {
 
 class Driver;
@@ -41,6 +43,46 @@ public:
     struct Fence {};
     struct Stream {};
 
+    class ExternalImageHandle;
+
+    class ExternalImage {
+        friend class ExternalImageHandle;
+        std::atomic_uint32_t mRefCount{0};
+    protected:
+        virtual ~ExternalImage() noexcept;
+    };
+
+    class ExternalImageHandle {
+        ExternalImage* UTILS_NULLABLE mTarget = nullptr;
+        static void incref(ExternalImage* UTILS_NULLABLE p) noexcept;
+        static void decref(ExternalImage* UTILS_NULLABLE p) noexcept;
+
+    public:
+        ExternalImageHandle() noexcept;
+        ~ExternalImageHandle() noexcept;
+        explicit ExternalImageHandle(ExternalImage* UTILS_NULLABLE p) noexcept;
+        ExternalImageHandle(ExternalImageHandle const& rhs) noexcept;
+        ExternalImageHandle(ExternalImageHandle&& rhs) noexcept;
+        ExternalImageHandle& operator=(ExternalImageHandle const& rhs) noexcept;
+        ExternalImageHandle& operator=(ExternalImageHandle&& rhs) noexcept;
+
+        explicit operator bool() const noexcept { return mTarget != nullptr; }
+
+        ExternalImage* UTILS_NULLABLE get() noexcept { return mTarget; }
+        ExternalImage const* UTILS_NULLABLE get() const noexcept { return mTarget; }
+
+        ExternalImage* UTILS_NULLABLE operator->() noexcept { return mTarget; }
+        ExternalImage const* UTILS_NULLABLE operator->() const noexcept { return mTarget; }
+
+        ExternalImage& operator*() noexcept { return *mTarget; }
+        ExternalImage const& operator*() const noexcept { return *mTarget; }
+
+        void clear() noexcept;
+        void reset(ExternalImage* UTILS_NULLABLE p) noexcept;
+    };
+
+    using ExternalImageHandleRef = ExternalImageHandle const&;
+
     /**
      * The type of technique for stereoscopic rendering. (Note that the materials used will need to
      * be compatible with the chosen technique.)

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

@@ -51,10 +51,9 @@ protected:
     ~OpenGLPlatform() noexcept override;
 
 public:
-
     struct ExternalTexture {
-        unsigned int target;            // GLenum target
-        unsigned int id;                // GLuint id
+        unsigned int target; // GLenum target
+        unsigned int id; // GLuint id
     };
 
     /**
@@ -324,36 +323,45 @@ public:
      * Destroys an external texture handle and associated data.
      * @param texture a pointer to the handle to destroy.
      */
-    virtual void destroyExternalImage(ExternalTexture* UTILS_NONNULL texture) noexcept;
+    virtual void destroyExternalImageTexture(ExternalTexture* UTILS_NONNULL texture) noexcept;
 
     // called on the application thread to allow Filament to take ownership of the image
 
     /**
      * Takes ownership of the externalImage. The externalImage parameter depends on the Platform's
-     * concrete implementation. Ownership is released when destroyExternalImage() is called.
+     * concrete implementation. Ownership is released when destroyExternalImageTexture() is called.
      *
      * WARNING: This is called synchronously from the application thread (NOT the Driver thread)
      *
      * @param externalImage A token representing the platform's external image.
      * @see destroyExternalImage
+     * @{
      */
     virtual void retainExternalImage(void* UTILS_NONNULL externalImage) noexcept;
 
+    virtual void retainExternalImage(ExternalImageHandleRef externalImage) noexcept;
+    /** @}*/
+
     /**
      * Called to bind the platform-specific externalImage to an ExternalTexture.
      * ExternalTexture::id is guaranteed to be bound when this method is called and ExternalTexture
      * is updated with new values for id/target if necessary.
      *
      * WARNING: this method is not allowed to change the bound texture, or must restore the previous
-     * binding upon return. This is to avoid problem with a backend doing state caching.
+     * binding upon return. This is to avoid a problem with a backend doing state caching.
      *
      * @param externalImage The platform-specific external image.
      * @param texture an in/out pointer to ExternalTexture, id and target can be updated if necessary.
      * @return true on success, false on error.
+     * @{
      */
     virtual bool setExternalImage(void* UTILS_NONNULL externalImage,
             ExternalTexture* UTILS_NONNULL texture) noexcept;
 
+    virtual bool setExternalImage(ExternalImageHandleRef externalImage,
+            ExternalTexture* UTILS_NONNULL texture) noexcept;
+    /** @}*/
+
     /**
      * The method allows platforms to convert a user-supplied external image object into a new type
      * (e.g. HardwareBuffer => EGLImage). The default implementation returns source.

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

@@ -34,12 +34,14 @@ public:
     PlatformCocoaGL();
     ~PlatformCocoaGL() noexcept override;
 
+    ExternalImageHandle createExternalImage(void* cvPixelBuffer) noexcept;
+
 protected:
     // --------------------------------------------------------------------------------------------
     // Platform Interface
 
     Driver* createDriver(void* sharedContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const DriverConfig& driverConfig) noexcept override;
 
     // Currently returns 0
     int getOSVersion() const noexcept override;
@@ -59,10 +61,12 @@ protected:
     void destroySwapChain(SwapChain* swapChain) 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;
+    ExternalTexture* createExternalImageTexture() noexcept override;
+    void destroyExternalImageTexture(ExternalTexture* texture) noexcept override;
     void retainExternalImage(void* externalImage) noexcept override;
     bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept override;
+    void retainExternalImage(ExternalImageHandleRef externalImage) noexcept override;
+    bool setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept override;
 
 private:
     PlatformCocoaGLImpl* pImpl = nullptr;

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

@@ -32,11 +32,13 @@ public:
     PlatformCocoaTouchGL();
     ~PlatformCocoaTouchGL() noexcept override;
 
+    ExternalImageHandle createExternalImage(void* cvPixelBuffer) noexcept;
+
     // --------------------------------------------------------------------------------------------
     // Platform Interface
 
     Driver* createDriver(void* sharedGLContext,
-            const Platform::DriverConfig& driverConfig) noexcept override;
+            const DriverConfig& driverConfig) noexcept override;
 
     int getOSVersion() const noexcept final { return 0; }
 
@@ -56,10 +58,12 @@ public:
     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;
+    ExternalTexture* createExternalImageTexture() noexcept override;
+    void destroyExternalImageTexture(ExternalTexture* texture) noexcept override;
     void retainExternalImage(void* externalImage) noexcept override;
     bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept override;
+    void retainExternalImage(ExternalImageHandleRef externalImage) noexcept override;
+    bool setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept override;
 
 private:
     PlatformCocoaTouchGLImpl* pImpl = nullptr;

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

@@ -47,6 +47,11 @@ public:
     // Return true if we're on an OpenGL platform (as opposed to OpenGL ES). false by default.
     virtual bool isOpenGL() const noexcept;
 
+    /**
+     * Creates an ExternalImage from a EGLImageKHR
+     */
+    ExternalImageHandle createExternalImage(EGLImageKHR eglImage) noexcept;
+
 protected:
     // --------------------------------------------------------------------------------------------
     // Helper for EGL configs and attributes parameters
@@ -118,9 +123,10 @@ protected:
     void destroyFence(Fence* fence) noexcept override;
     FenceStatus waitFence(Fence* fence, uint64_t timeout) noexcept override;
 
-    OpenGLPlatform::ExternalTexture* createExternalImageTexture() noexcept override;
-    void destroyExternalImage(ExternalTexture* texture) noexcept override;
+    ExternalTexture* createExternalImageTexture() noexcept override;
+    void destroyExternalImageTexture(ExternalTexture* texture) noexcept override;
     bool setExternalImage(void* externalImage, ExternalTexture* texture) noexcept override;
+    bool setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept override;
 
     /**
      * Logs glGetError() to slog.e
@@ -188,6 +194,12 @@ protected:
 
     void initializeGlExtensions() noexcept;
 
+    struct ExternalImageEGL : public ExternalImage {
+        EGLImageKHR eglImage = EGL_NO_IMAGE;
+    protected:
+        ~ExternalImageEGL() override;
+    };
+
 protected:
     EGLConfig findSwapChainConfig(uint64_t flags, bool window, bool pbuffer) const;
 

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

@@ -57,6 +57,11 @@ protected:
     Driver* createDriver(void* sharedContext,
             const Platform::DriverConfig& driverConfig) noexcept override;
 
+    /**
+     * Creates an ExternalImage from a EGLImageKHR
+     */
+    ExternalImageHandle createExternalImage(AHardwareBuffer const *buffer, bool sRGB) noexcept;
+
     // --------------------------------------------------------------------------------------------
     // OpenGLPlatform Interface
 
@@ -89,6 +94,15 @@ protected:
      */
     AcquiredImage transformAcquiredImage(AcquiredImage source) noexcept override;
 
+    bool setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept override;
+
+    struct ExternalImageEGLAndroid : public ExternalImageEGL {
+        AHardwareBuffer* aHardwareBuffer = nullptr;
+        bool sRGB = false;
+    protected:
+        ~ExternalImageEGLAndroid() override;
+    };
+
 protected:
     bool makeCurrent(ContextType type,
             SwapChain* drawSwapChain,

filament/backend/include/backend/platforms/PlatformMetal.h

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef TNT_FILAMENT_BACKEND_PRIVATE_METALPLATFORM_H
-#define TNT_FILAMENT_BACKEND_PRIVATE_METALPLATFORM_H
+#ifndef TNT_FILAMENT_BACKEND_PRIVATE_PLATFORMMETAL_H
+#define TNT_FILAMENT_BACKEND_PRIVATE_PLATFORMMETAL_H
 
 #include <backend/DriverEnums.h>
 #include <backend/Platform.h>
@@ -24,9 +24,12 @@
 
 namespace filament::backend {
 
-class MetalPlatform final : public Platform {
+struct PlatformMetalImpl;
+
+class PlatformMetal final : public Platform {
 public:
-    ~MetalPlatform() override;
+    PlatformMetal();
+    ~PlatformMetal() noexcept override;
 
     Driver* createDriver(void* sharedContext, const Platform::DriverConfig& driverConfig) noexcept override;
     int getOSVersion() const noexcept override { return 0; }
@@ -54,11 +57,30 @@ public:
      */
     id<MTLCommandBuffer> createAndEnqueueCommandBuffer() noexcept;
 
-private:
-    id<MTLCommandQueue> mCommandQueue = nil;
+    /**
+     * The action to take if a Drawable cannot be acquired.
+     *
+     * Each frame rendered requires a CAMetalDrawable texture, which is presented on-screen at the
+     * completion of each frame. These are limited and provided round-robin style by the system.
+     */
+    enum class DrawableFailureBehavior : uint8_t {
+        /**
+         * Terminates the application and reports an error message (default).
+         */
+        PANIC,
+        /*
+         * Aborts execution of the current frame. The Metal backend will attempt to acquire a new
+         * drawable at the next frame.
+         */
+        ABORT_FRAME
+    };
+    void setDrawableFailureBehavior(DrawableFailureBehavior behavior) noexcept;
+    DrawableFailureBehavior getDrawableFailureBehavior() const noexcept;
 
+private:
+    PlatformMetalImpl* pImpl = nullptr;
 };
 
 } // namespace filament::backend
 
-#endif // TNT_FILAMENT_BACKEND_PRIVATE_METALPLATFORM_H
+#endif // TNT_FILAMENT_BACKEND_PRIVATE_PLATFORMMETAL_H

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

@@ -69,6 +69,16 @@ public:
 
     virtual ShaderModel getShaderModel() const noexcept = 0;
 
+    // The shader language used for shaders for this driver, used to inform matdbg.
+    //
+    // For OpenGL, this distinguishes whether the driver's shaders are powered by ESSL1 or ESSL3.
+    // This information is used by matdbg to display the correct shader code to the web UI and patch
+    // the correct chunk when rebuilding shaders live.
+    //
+    // Metal shaders can either be MSL or Metal libraries, but at time of writing, matdbg can only
+    // interface with MSL.
+    virtual ShaderLanguage getShaderLanguage() const noexcept = 0;
+
     // Returns the dispatcher. This is only called once during initialization of the CommandStream,
     // so it doesn't matter that it's virtual.
     virtual Dispatcher getDispatcher() const noexcept = 0;

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

@@ -126,8 +126,10 @@
  * Driver API below...
  */
 
+#if defined(__clang__)
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wunused-parameter"
+#endif
 
 DECL_DRIVER_API_0(tick)
 
@@ -213,6 +215,14 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureViewSwizzle,
         backend::TextureSwizzle, b,
         backend::TextureSwizzle, a)
 
+DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage2,
+        backend::SamplerType, target,
+        backend::TextureFormat, format,
+        uint32_t, width,
+        uint32_t, height,
+        backend::TextureUsage, usage,
+        backend::Platform::ExternalImageHandleRef, image)
+
 DECL_DRIVER_API_R_N(backend::TextureHandle, createTextureExternalImage,
         backend::SamplerType, target,
         backend::TextureFormat, format,
@@ -353,6 +363,7 @@ 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)
+DECL_DRIVER_API_SYNCHRONOUS_N(void, setupExternalImage2, backend::Platform::ExternalImageHandleRef, image)
 DECL_DRIVER_API_SYNCHRONOUS_N(void, setupExternalImage, void*, image)
 DECL_DRIVER_API_SYNCHRONOUS_N(backend::TimerQueryResult, getTimerQueryValue, backend::TimerQueryHandle, query, uint64_t*, elapsedTime)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isWorkaroundNeeded, backend::Workaround, workaround)
@@ -533,7 +544,9 @@ DECL_DRIVER_API_N(scissor,
         Viewport, scissor)
 
 
+#if defined(__clang__)
 #pragma clang diagnostic pop
+#endif
 
 #undef EXPAND
 

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

@@ -31,6 +31,7 @@
 
 #include <cstddef>
 #include <exception>
+#include <mutex>
 #include <type_traits>
 #include <unordered_map>
 #include <utility>
@@ -44,11 +45,26 @@
 
 namespace filament::backend {
 
+// This is used to not duplicate the code for the Tags management
+class DebugTag {
+public:
+    DebugTag();
+    void writeHandleTag(HandleBase::HandleId key, utils::CString&& tag) noexcept;
+    utils::CString findHandleTag(HandleBase::HandleId key) const noexcept;
+
+private:
+    // This is used to associate a tag to a handle. mDebugTags is only written the in the main
+    // driver thread, but it can be accessed from any thread, because it's called from handle_cast<>
+    // which is used by synchronous calls.
+    mutable utils::Mutex mDebugTagLock;
+    tsl::robin_map<HandleBase::HandleId, utils::CString> mDebugTags;
+};
+
 /*
  * A utility class to efficiently allocate and manage Handle<>
  */
 template<size_t P0, size_t P1, size_t P2>
-class HandleAllocator {
+class HandleAllocator : public DebugTag {
 public:
     HandleAllocator(const char* name, size_t size, bool disableUseAfterFreeCheck) noexcept;
     HandleAllocator(HandleAllocator const& rhs) = delete;
@@ -97,7 +113,7 @@ public:
      *  ConcreteTexture* p = reconstruct(h, w, h);
      */
     template<typename D, typename B, typename ... ARGS>
-    typename std::enable_if_t<std::is_base_of_v<B, D>, D>*
+    std::enable_if_t<std::is_base_of_v<B, D>, D>*
     destroyAndConstruct(Handle<B> const& handle, ARGS&& ... args) {
         assert_invariant(handle);
         D* addr = handle_cast<D*>(const_cast<Handle<B>&>(handle));
@@ -116,7 +132,7 @@ public:
      *  ConcreteTexture* p = construct(h, w, h);
      */
     template<typename D, typename B, typename ... ARGS>
-    typename std::enable_if_t<std::is_base_of_v<B, D>, D>*
+    std::enable_if_t<std::is_base_of_v<B, D>, D>*
     construct(Handle<B> const& handle, ARGS&& ... args) noexcept {
         assert_invariant(handle);
         D* addr = handle_cast<D*>(const_cast<Handle<B>&>(handle));
@@ -133,7 +149,7 @@ public:
      *      deallocate(h, p);
      */
     template <typename B, typename D,
-            typename = typename std::enable_if_t<std::is_base_of_v<B, D>, D>>
+            typename = std::enable_if_t<std::is_base_of_v<B, D>, D>>
     void deallocate(Handle<B>& handle, D const* p) noexcept {
         // allow to destroy the nullptr, similarly to operator delete
         if (p) {
@@ -161,9 +177,9 @@ public:
      *      ConcreteTexture* p = handle_cast<ConcreteTexture*>(h);
      */
     template<typename Dp, typename B>
-    inline typename std::enable_if_t<
+    inline std::enable_if_t<
             std::is_pointer_v<Dp> &&
-            std::is_base_of_v<B, typename std::remove_pointer_t<Dp>>, Dp>
+            std::is_base_of_v<B, std::remove_pointer_t<Dp>>, Dp>
     handle_cast(Handle<B>& handle) {
         assert_invariant(handle);
         auto [p, tag] = handleToPointer(handle.getId());
@@ -200,6 +216,8 @@ public:
         return static_cast<Dp>(p);
     }
 
+    utils::CString getHandleTag(HandleBase::HandleId key) const noexcept;
+
     template<typename B>
     bool is_valid(Handle<B>& handle) {
         if (!handle) {
@@ -217,9 +235,9 @@ public:
     }
 
     template<typename Dp, typename B>
-    inline typename std::enable_if_t<
+    inline std::enable_if_t<
             std::is_pointer_v<Dp> &&
-            std::is_base_of_v<B, typename std::remove_pointer_t<Dp>>, Dp>
+            std::is_base_of_v<B, std::remove_pointer_t<Dp>>, Dp>
     handle_cast(Handle<B> const& handle) {
         return handle_cast<Dp>(const_cast<Handle<B>&>(handle));
     }
@@ -227,24 +245,12 @@ public:
     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)) {
+        uint32_t key = id;
+        if (UTILS_LIKELY(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);
+            key &= ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
         }
-    }
-
-    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)";
+        writeHandleTag(key, std::move(tag));
     }
 
 private:
@@ -347,9 +353,8 @@ private:
         if (UTILS_LIKELY(p)) {
             uint32_t const tag = (uint32_t(age) << HANDLE_AGE_SHIFT) & HANDLE_AGE_MASK;
             return arenaPointerToHandle(p, tag);
-        } else {
-            return allocateHandleSlow(SIZE);
         }
+        return allocateHandleSlow(SIZE);
     }
 
     template<size_t SIZE>
@@ -421,7 +426,6 @@ 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;
 };

filament/backend/include/private/backend/VirtualMachineEnv.h

@@ -18,7 +18,7 @@
 #define TNT_FILAMENT_DRIVER_ANDROID_VIRTUAL_MACHINE_ENV_H
 
 #include <utils/compiler.h>
-#include <utils/debug.h>
+#include <utils/Mutex.h>
 
 #include <jni.h>
 
@@ -26,25 +26,17 @@ namespace filament {
 
 class VirtualMachineEnv {
 public:
+    // must be called before VirtualMachineEnv::get() from a thread that is attached to the JavaVM
     static jint JNI_OnLoad(JavaVM* vm) noexcept;
 
-    static VirtualMachineEnv& get() noexcept {
-        // declaring this thread local, will ensure it's destroyed with the calling thread
-        static thread_local VirtualMachineEnv instance;
-        return instance;
-    }
+    // must be called on backend thread
+    static VirtualMachineEnv& get() noexcept;
 
-    static JNIEnv* getThreadEnvironment() noexcept {
-        JNIEnv* env;
-        assert_invariant(sVirtualMachine);
-        if (sVirtualMachine->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
-            return nullptr; // this should not happen
-        }
-        return env;
-    }
+    // can be called from any thread that already has a JniEnv
+    static JNIEnv* getThreadEnvironment() noexcept;
 
-    inline JNIEnv* getEnvironment() noexcept {
-        assert_invariant(mVirtualMachine);
+    // must be called from the backend thread
+    JNIEnv* getEnvironment() noexcept {
         JNIEnv* env = mJniEnv;
         if (UTILS_UNLIKELY(!env)) {
             return getEnvironmentSlow();
@@ -55,20 +47,14 @@ public:
     static void handleException(JNIEnv* env) noexcept;
 
 private:
-    VirtualMachineEnv() noexcept : mVirtualMachine(sVirtualMachine) {
-        // We're not initializing the JVM here -- but we could -- because most of the time
-        // we don't need the jvm. Instead we do the initialization on first use. This means we could get
-        // a nasty slow down the very first time, but we'll live with it for now.
-    }
-
-    ~VirtualMachineEnv() {
-        if (mVirtualMachine) {
-            mVirtualMachine->DetachCurrentThread();
-        }
-    }
-
+    explicit VirtualMachineEnv(JavaVM* vm) noexcept;
+    ~VirtualMachineEnv() noexcept;
     JNIEnv* getEnvironmentSlow() noexcept;
+
+    static utils::Mutex sLock;
     static JavaVM* sVirtualMachine;
+    static JavaVM* getVirtualMachine();
+
     JNIEnv* mJniEnv = nullptr;
     JavaVM* mVirtualMachine = nullptr;
 };

filament/backend/src/HandleAllocator.cpp

@@ -19,6 +19,7 @@
 #include <backend/Handle.h>
 
 #include <utils/Allocator.h>
+#include <utils/CString.h>
 #include <utils/Log.h>
 #include <utils/Panic.h>
 #include <utils/compiler.h>
@@ -29,7 +30,9 @@
 #include <exception>
 #include <limits>
 #include <mutex>
+#include <utility>
 
+#include <stdint.h>
 #include <stdlib.h>
 #include <string.h>
 
@@ -80,9 +83,6 @@ 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>
@@ -147,6 +147,42 @@ void HandleAllocator<P0, P1, P2>::deallocateHandleSlow(HandleBase::HandleId id,
     ::free(p);
 }
 
+template<size_t P0, size_t P1, size_t P2>
+UTILS_NOINLINE
+CString HandleAllocator<P0, P1, P2>::getHandleTag(HandleBase::HandleId id) const noexcept {
+    uint32_t key = id;
+    if (UTILS_LIKELY(isPoolHandle(id))) {
+        // Truncate the age to get the debug tag
+        key &= ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+    }
+    return findHandleTag(key);
+}
+
+DebugTag::DebugTag() {
+    // Reserve initial space for debug tags. This prevents excessive calls to malloc when the first
+    // few tags are set.
+    mDebugTags.reserve(512);
+}
+
+UTILS_NOINLINE
+CString DebugTag::findHandleTag(HandleBase::HandleId key) const noexcept {
+    std::unique_lock const lock(mDebugTagLock);
+    if (auto pos = mDebugTags.find(key); pos != mDebugTags.end()) {
+        return pos->second;
+    }
+    return "(no tag)";
+}
+
+UTILS_NOINLINE
+void DebugTag::writeHandleTag(HandleBase::HandleId key, CString&& tag) noexcept {
+    // This line is the costly part. In the future, we could potentially use a custom
+    // allocator.
+    std::unique_lock const lock(mDebugTagLock);
+    // Pool based tags will be recycled after a certain age. Heap-based tag will never be recycled, therefore,
+    // this can grow indefinitely, once we're in the slow mode.
+    mDebugTags[key] = std::move(tag);
+}
+
 // Explicit template instantiations.
 #if defined (FILAMENT_SUPPORTS_OPENGL)
 template class HandleAllocatorGL;

filament/backend/src/Platform.cpp

@@ -16,8 +16,93 @@
 
 #include <backend/Platform.h>
 
+#include <utils/compiler.h>
+
+#include <atomic>
+#include <utility>
+
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament::backend {
 
+void Platform::ExternalImageHandle::incref(ExternalImage* p) noexcept {
+    if (p) {
+        // incrementing the ref-count doesn't acquire or release anything
+        p->mRefCount.fetch_add(1, std::memory_order_relaxed);
+    }
+}
+
+void Platform::ExternalImageHandle::decref(ExternalImage* p) noexcept {
+    if (p) {
+        // When decrementing the ref-count, unless it reaches zero, there is no need to acquire data; we need to
+        // release all previous writes though so they can be visible to the thread that will actually delete the
+        // object.
+        if (p->mRefCount.fetch_sub(1, std::memory_order_release) == 1) {
+            // if we reach zero, we're about to delete the object, we need to acquire all previous writes from other
+            // threads (i.e.: the memory from other threads prior to the decref() need to be visible now.
+            std::atomic_thread_fence(std::memory_order_acquire);
+            delete p;
+        }
+    }
+}
+
+Platform::ExternalImageHandle::ExternalImageHandle() noexcept = default;
+
+Platform::ExternalImageHandle::~ExternalImageHandle() noexcept {
+    decref(mTarget);
+}
+
+Platform::ExternalImageHandle::ExternalImageHandle(ExternalImage* p) noexcept
+        : mTarget(p) {
+    incref(mTarget);
+}
+
+Platform::ExternalImageHandle::ExternalImageHandle(ExternalImageHandle const& rhs) noexcept
+        : mTarget(rhs.mTarget) {
+    incref(mTarget);
+}
+
+Platform::ExternalImageHandle::ExternalImageHandle(ExternalImageHandle&& rhs) noexcept
+        : mTarget(rhs.mTarget) {
+    rhs.mTarget = nullptr;
+}
+
+Platform::ExternalImageHandle& Platform::ExternalImageHandle::operator=(ExternalImageHandle const& rhs) noexcept {
+    if (UTILS_LIKELY(this != &rhs)) {
+        incref(rhs.mTarget);
+        decref(mTarget);
+        mTarget = rhs.mTarget;
+    }
+    return *this;
+}
+
+Platform::ExternalImageHandle& Platform::ExternalImageHandle::operator=(ExternalImageHandle&& rhs) noexcept {
+    if (UTILS_LIKELY(this != &rhs)) {
+        decref(mTarget);
+        mTarget = rhs.mTarget;
+        rhs.mTarget = nullptr;
+    }
+    return *this;
+}
+
+void Platform::ExternalImageHandle::clear() noexcept {
+    decref(mTarget);
+    mTarget = nullptr;
+}
+
+void Platform::ExternalImageHandle::reset(ExternalImage* p) noexcept {
+    incref(p);
+    decref(mTarget);
+    mTarget = p;
+}
+
+// --------------------------------------------------------------------------------------------------------------------
+
+Platform::ExternalImage::~ExternalImage() noexcept = default;
+
+// --------------------------------------------------------------------------------------------------------------------
+
 Platform::Platform() noexcept = default;
 
 // this generates the vtable in this translation unit

filament/backend/src/VirtualMachineEnv.cpp

@@ -18,12 +18,28 @@
 
 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/Mutex.h>
+#include <utils/Panic.h>
 
 #include <jni.h>
 
+#include <mutex>
+
 namespace filament {
 
-JavaVM* VirtualMachineEnv::sVirtualMachine = nullptr;
+using namespace utils;
+
+// This Mutex shouldn't be subject to the Static Initialization Order Fiasco because its initial state is
+// a single int initialized to 0.
+/* static*/ Mutex VirtualMachineEnv::sLock;
+/* static*/ JavaVM* VirtualMachineEnv::sVirtualMachine = nullptr;
+
+UTILS_NOINLINE
+JavaVM* VirtualMachineEnv::getVirtualMachine() {
+    std::lock_guard const lock(sLock);
+    assert_invariant(sVirtualMachine);
+    return sVirtualMachine;
+}
 
 /*
  * This is typically called by filament_jni.so when it is loaded. If filament_jni.so is not used,
@@ -35,15 +51,75 @@ JavaVM* VirtualMachineEnv::sVirtualMachine = nullptr;
 UTILS_PUBLIC
 UTILS_NOINLINE
 jint VirtualMachineEnv::JNI_OnLoad(JavaVM* vm) noexcept {
-    JNIEnv* env = nullptr;
-    if (UTILS_UNLIKELY(vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK)) {
-        // this should not happen
-        return -1;
+    std::lock_guard const lock(sLock);
+    if (sVirtualMachine) {
+        // It doesn't make sense for JNI_OnLoad() to be called more than once
+        return JNI_VERSION_1_6;
     }
+
+    // Here we check this VM at least has JNI_VERSION_1_6
+    JNIEnv* env = nullptr;
+    jint const result = vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6);
+
+    FILAMENT_CHECK_POSTCONDITION(result == JNI_OK)
+            << "Couldn't get JniEnv* from the VM, error = " << result;
+
     sVirtualMachine = vm;
     return JNI_VERSION_1_6;
 }
 
+UTILS_NOINLINE
+VirtualMachineEnv& VirtualMachineEnv::get() noexcept {
+    JavaVM* const vm = getVirtualMachine();
+    // declaring this thread local, will ensure it's destroyed with the calling thread
+    thread_local VirtualMachineEnv instance{ vm };
+    return instance;
+}
+
+UTILS_NOINLINE
+JNIEnv* VirtualMachineEnv::getThreadEnvironment() noexcept {
+    JavaVM* const vm = getVirtualMachine();
+    JNIEnv* env = nullptr;
+    jint const result = vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6);
+
+    FILAMENT_CHECK_POSTCONDITION(result == JNI_OK)
+            << "Couldn't get JniEnv* from the VM, error = " << result;
+
+    return env;
+}
+
+VirtualMachineEnv::VirtualMachineEnv(JavaVM* vm) noexcept : mVirtualMachine(vm) {
+    // We're not initializing the JVM here -- but we could -- because most of the time
+    // we don't need the jvm. Instead, we do the initialization on first use. This means we could get
+    // a nasty slow down the very first time, but we'll live with it for now.
+}
+
+VirtualMachineEnv::~VirtualMachineEnv() noexcept {
+    if (mVirtualMachine) {
+        mVirtualMachine->DetachCurrentThread();
+    }
+}
+
+UTILS_NOINLINE
+JNIEnv* VirtualMachineEnv::getEnvironmentSlow() noexcept {
+    FILAMENT_CHECK_PRECONDITION(mVirtualMachine)
+            << "JNI_OnLoad() has not been called";
+
+#if defined(__ANDROID__)
+    jint const result = mVirtualMachine->AttachCurrentThread(&mJniEnv, nullptr);
+#else
+    jint const result = mVirtualMachine->AttachCurrentThread(reinterpret_cast<void**>(&mJniEnv), nullptr);
+#endif
+
+    FILAMENT_CHECK_POSTCONDITION(result == JNI_OK)
+            << "JavaVM::AttachCurrentThread failed with error " << result;
+
+    FILAMENT_CHECK_POSTCONDITION(mJniEnv)
+            << "JavaVM::AttachCurrentThread returned a null mJniEnv";
+
+    return mJniEnv;
+}
+
 UTILS_NOINLINE
 void VirtualMachineEnv::handleException(JNIEnv* const env) noexcept {
     if (UTILS_UNLIKELY(env->ExceptionCheck())) {
@@ -52,16 +128,5 @@ void VirtualMachineEnv::handleException(JNIEnv* const env) noexcept {
     }
 }
 
-UTILS_NOINLINE
-JNIEnv* VirtualMachineEnv::getEnvironmentSlow() noexcept {
-#if defined(__ANDROID__)
-    mVirtualMachine->AttachCurrentThread(&mJniEnv, nullptr);
-#else
-    mVirtualMachine->AttachCurrentThread(reinterpret_cast<void**>(&mJniEnv), nullptr);
-#endif
-    assert_invariant(mJniEnv);
-    return mJniEnv;
-}
-
 } // namespace filament
 

filament/backend/src/metal/MetalBuffer.h

@@ -18,9 +18,9 @@
 #define TNT_FILAMENT_DRIVER_METALBUFFER_H
 
 #include "MetalContext.h"
-#include "MetalPlatform.h"
 
 #include <backend/DriverEnums.h>
+#include <backend/platforms/PlatformMetal.h>
 
 #include <Metal/Metal.h>
 
@@ -54,12 +54,12 @@ public:
         }
     }
 
-    static void setPlatform(MetalPlatform* p) { platform = p; }
+    static void setPlatform(PlatformMetal* p) { platform = p; }
 
 private:
     typedef std::chrono::steady_clock clock_t;
 
-    static MetalPlatform* platform;
+    static PlatformMetal* platform;
 
     std::chrono::time_point<clock_t> mBeginning;
     const char* mName;
@@ -141,7 +141,7 @@ public:
         assert_invariant(type != Type::NONE);
         return aliveBuffers[toIndex(type)];
     }
-    static void setPlatform(MetalPlatform* p) { platform = p; }
+    static void setPlatform(PlatformMetal* p) { platform = p; }
 
 private:
     void swap(TrackedMetalBuffer& other) noexcept {
@@ -152,7 +152,7 @@ private:
     id<MTLBuffer> mBuffer;
     Type mType = Type::NONE;
 
-    static MetalPlatform* platform;
+    static PlatformMetal* platform;
     static std::array<uint64_t, TypeCount> aliveBuffers;
 };
 

filament/backend/src/metal/MetalBuffer.mm

@@ -23,8 +23,8 @@ namespace filament {
 namespace backend {
 
 std::array<uint64_t, TrackedMetalBuffer::TypeCount> TrackedMetalBuffer::aliveBuffers = { 0 };
-MetalPlatform* TrackedMetalBuffer::platform = nullptr;
-MetalPlatform* ScopedAllocationTimer::platform = nullptr;
+PlatformMetal* TrackedMetalBuffer::platform = nullptr;
+PlatformMetal* ScopedAllocationTimer::platform = nullptr;
 
 MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType, BufferUsage usage,
         size_t size, bool forceGpuBuffer)

filament/backend/src/metal/MetalContext.h

@@ -128,6 +128,7 @@ struct MetalContext {
     std::atomic<uint64_t> latestCompletedCommandBufferId = 0;
     id<MTLCommandBuffer> pendingCommandBuffer = nil;
     id<MTLRenderCommandEncoder> currentRenderPassEncoder = nil;
+    uint32_t currentFrame = 0;
 
     std::atomic<bool> memorylessLimitsReached = false;
 
@@ -156,6 +157,7 @@ struct MetalContext {
     RenderPassFlags currentRenderPassFlags;
     MetalRenderTarget* currentRenderTarget = nullptr;
     bool validPipelineBound = false;
+    bool currentRenderPassAbandoned = false;
 
     // State trackers.
     PipelineStateTracker pipelineState;

filament/backend/src/metal/MetalDriver.h

@@ -37,7 +37,7 @@
 namespace filament {
 namespace backend {
 
-class MetalPlatform;
+class PlatformMetal;
 
 class MetalBuffer;
 class MetalProgram;
@@ -51,22 +51,23 @@ struct BufferState;
 #endif
 
 class MetalDriver final : public DriverBase {
-    explicit MetalDriver(MetalPlatform* platform, const Platform::DriverConfig& driverConfig) noexcept;
+    explicit MetalDriver(PlatformMetal* platform, const Platform::DriverConfig& driverConfig) noexcept;
     ~MetalDriver() noexcept override;
     Dispatcher getDispatcher() const noexcept final;
 
 public:
-    static Driver* create(MetalPlatform* platform, const Platform::DriverConfig& driverConfig);
+    static Driver* create(PlatformMetal* platform, const Platform::DriverConfig& driverConfig);
 
 private:
 
     friend class MetalSwapChain;
     friend struct MetalDescriptorSet;
 
-    MetalPlatform& mPlatform;
+    PlatformMetal& mPlatform;
     MetalContext* mContext;
 
     ShaderModel getShaderModel() const noexcept final;
+    ShaderLanguage getShaderLanguage() const noexcept final;
 
     // Overrides the default implementation by wrapping the call to fn in an @autoreleasepool block.
     void execute(std::function<void(void)> const& fn) noexcept final;

filament/backend/src/metal/MetalDriver.mm

@@ -30,7 +30,7 @@
 #include "MetalState.h"
 #include "MetalTimerQuery.h"
 
-#include "MetalPlatform.h"
+#include <backend/platforms/PlatformMetal.h>
 
 #include <CoreVideo/CVMetalTexture.h>
 #include <CoreVideo/CVPixelBuffer.h>
@@ -57,7 +57,7 @@
 namespace filament {
 namespace backend {
 
-Driver* MetalDriverFactory::create(MetalPlatform* const platform, const Platform::DriverConfig& driverConfig) {
+Driver* MetalDriverFactory::create(PlatformMetal* const platform, const Platform::DriverConfig& driverConfig) {
 #if 0
     // this is useful for development, but too verbose even for debug builds
     // For reference on a 64-bits machine in Release mode:
@@ -96,7 +96,7 @@ Driver* MetalDriverFactory::create(MetalPlatform* const platform, const Platform
 }
 
 UTILS_NOINLINE
-Driver* MetalDriver::create(MetalPlatform* const platform, const Platform::DriverConfig& driverConfig) {
+Driver* MetalDriver::create(PlatformMetal* const platform, const Platform::DriverConfig& driverConfig) {
     assert_invariant(platform);
     size_t defaultSize = FILAMENT_METAL_HANDLE_ARENA_SIZE_IN_MB * 1024U * 1024U;
     Platform::DriverConfig validConfig {driverConfig};
@@ -109,7 +109,7 @@ Dispatcher MetalDriver::getDispatcher() const noexcept {
 }
 
 MetalDriver::MetalDriver(
-        MetalPlatform* platform, const Platform::DriverConfig& driverConfig) noexcept
+        PlatformMetal* platform, const Platform::DriverConfig& driverConfig) noexcept
     : mPlatform(*platform),
       mContext(new MetalContext),
       mHandleAllocator(
@@ -246,6 +246,7 @@ void MetalDriver::tick(int) {
 
 void MetalDriver::beginFrame(int64_t monotonic_clock_ns,
         int64_t refreshIntervalNs, uint32_t frameId) {
+    mContext->currentFrame = frameId;
     DEBUG_LOG("beginFrame(monotonic_clock_ns = %lld, refreshIntervalNs = %lld, frameId = %d)\n",
             monotonic_clock_ns, refreshIntervalNs, frameId);
 #if defined(FILAMENT_METAL_PROFILING)
@@ -512,6 +513,14 @@ void MetalDriver::createTextureViewSwizzleR(Handle<HwTexture> th, Handle<HwTextu
     mContext->textures.insert(construct_handle<MetalTexture>(th, *mContext, src, r, g, b, a));
 }
 
+void MetalDriver::createTextureExternalImage2R(Handle<HwTexture> th,
+        backend::SamplerType target,
+        backend::TextureFormat format,
+        uint32_t width, uint32_t height, backend::TextureUsage usage,
+        Platform::ExternalImageHandleRef image) {
+    // FIXME: implement createTextureExternalImage2R
+}
+
 void MetalDriver::createTextureExternalImageR(Handle<HwTexture> th,
         backend::SamplerType target,
         backend::TextureFormat format,
@@ -631,19 +640,19 @@ void MetalDriver::createFenceR(Handle<HwFence> fh, int dummy) {
 void MetalDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow, uint64_t flags) {
     if (UTILS_UNLIKELY(flags & SWAP_CHAIN_CONFIG_APPLE_CVPIXELBUFFER)) {
         CVPixelBufferRef pixelBuffer = (CVPixelBufferRef) nativeWindow;
-        construct_handle<MetalSwapChain>(sch, *mContext, pixelBuffer, flags);
+        construct_handle<MetalSwapChain>(sch, *mContext, mPlatform, pixelBuffer, flags);
         // This release matches the retain call in setupExternalImage. The MetalSwapchain will have
         // retained the buffer by now.
         CVPixelBufferRelease((CVPixelBufferRef)pixelBuffer);
     } else {
         auto* metalLayer = (__bridge CAMetalLayer*) nativeWindow;
-        construct_handle<MetalSwapChain>(sch, *mContext, metalLayer, flags);
+        construct_handle<MetalSwapChain>(sch, *mContext, mPlatform, metalLayer, flags);
     }
 }
 
 void MetalDriver::createSwapChainHeadlessR(Handle<HwSwapChain> sch,
         uint32_t width, uint32_t height, uint64_t flags) {
-    construct_handle<MetalSwapChain>(sch, *mContext, width, height, flags);
+    construct_handle<MetalSwapChain>(sch, *mContext, mPlatform, width, height, flags);
 }
 
 void MetalDriver::createTimerQueryR(Handle<HwTimerQuery> tqh, int) {
@@ -746,6 +755,10 @@ Handle<HwTexture> MetalDriver::createTextureViewSwizzleS() noexcept {
     return alloc_handle<MetalTexture>();
 }
 
+Handle<HwTexture> MetalDriver::createTextureExternalImage2S() noexcept {
+    return alloc_handle<MetalTexture>();
+}
+
 Handle<HwTexture> MetalDriver::createTextureExternalImageS() noexcept {
     return alloc_handle<MetalTexture>();
 }
@@ -946,6 +959,10 @@ ShaderModel MetalDriver::getShaderModel() const noexcept {
 #endif
 }
 
+ShaderLanguage MetalDriver::getShaderLanguage() const noexcept {
+    return ShaderLanguage::MSL;
+}
+
 Handle<HwStream> MetalDriver::createStreamNative(void* stream) {
     return {};
 }
@@ -1134,8 +1151,8 @@ FeatureLevel MetalDriver::getFeatureLevel() {
 
 math::float2 MetalDriver::getClipSpaceParams() {
     // virtual and physical z-coordinate of clip-space is in [-w, 0]
-    // Note: this is actually never used (see: main.vs), but it's a backend API so we implement it
-    // properly.
+    // Note: this is actually never used (see: surface_main.vs), but it's a backend API so we
+    // implement it properly.
     return math::float2{ 1.0f, 0.0f };
 }
 
@@ -1213,6 +1230,10 @@ void MetalDriver::update3DImage(Handle<HwTexture> th, uint32_t level,
             th.getId(), level, xoffset, yoffset, zoffset, width, height, depth);
 }
 
+void MetalDriver::setupExternalImage2(Platform::ExternalImageHandleRef image) {
+    // FIXME: implement setupExternalImage2
+}
+
 void MetalDriver::setupExternalImage(void* image) {
     // setupExternalImage is called on the Filament thread when creating a Texture or SwapChain from
     // a CVPixelBuffer external image. Here we take ownership of the passed in buffer by calling
@@ -1268,6 +1289,13 @@ void MetalDriver::beginRenderPass(Handle<HwRenderTarget> rth,
     MTLRenderPassDescriptor* descriptor = [MTLRenderPassDescriptor renderPassDescriptor];
     renderTarget->setUpRenderPassAttachments(descriptor, params);
 
+    if (renderTarget->involvesAbandonedSwapChain()) {
+        mContext->currentRenderPassAbandoned = true;
+        return;
+    } else {
+        mContext->currentRenderPassAbandoned = false;
+    }
+
     mContext->currentRenderPassEncoder =
             [getPendingCommandBuffer(mContext) renderCommandEncoderWithDescriptor:descriptor];
     if (!mContext->groupMarkers.empty()) {
@@ -1329,6 +1357,10 @@ void MetalDriver::endRenderPass(int dummy) {
     os_signpost_interval_end(mContext->log, OS_SIGNPOST_ID_EXCLUSIVE, "Render pass");
 #endif
 
+    if (UTILS_UNLIKELY(mContext->currentRenderPassAbandoned)) {
+        return;
+    }
+
     [mContext->currentRenderPassEncoder endEncoding];
 
     // Command encoders are one time use. Set it to nil to release the encoder and ensure we don't
@@ -1629,6 +1661,11 @@ void MetalDriver::blitDEPRECATED(TargetBufferFlags buffers,
     auto srcTarget = handle_cast<MetalRenderTarget>(src);
     auto dstTarget = handle_cast<MetalRenderTarget>(dst);
 
+    if (UTILS_UNLIKELY(srcTarget->involvesAbandonedSwapChain() ||
+                dstTarget->involvesAbandonedSwapChain())) {
+        return;
+    }
+
     FILAMENT_CHECK_PRECONDITION(buffers == TargetBufferFlags::COLOR0)
             << "blitDEPRECATED only supports COLOR0";
 
@@ -1913,6 +1950,10 @@ void MetalDriver::bindDescriptorSet(
 }
 
 void MetalDriver::draw2(uint32_t indexOffset, uint32_t indexCount, uint32_t instanceCount) {
+    if (UTILS_UNLIKELY(mContext->currentRenderPassAbandoned)) {
+        return;
+    }
+
     FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder != nullptr)
             << "draw() without a valid command encoder.";
     DEBUG_LOG("draw2(...)\n");
@@ -1956,6 +1997,9 @@ void MetalDriver::draw2(uint32_t indexOffset, uint32_t indexCount, uint32_t inst
 
 void MetalDriver::draw(PipelineState ps, Handle<HwRenderPrimitive> rph,
         uint32_t const indexOffset, uint32_t const indexCount, uint32_t const instanceCount) {
+    if (UTILS_UNLIKELY(mContext->currentRenderPassAbandoned)) {
+        return;
+    }
     MetalRenderPrimitive const* const rp = handle_cast<MetalRenderPrimitive>(rph);
     ps.primitiveType = rp->type;
     ps.vertexBufferInfo = rp->vertexBuffer->vbih;

filament/backend/src/metal/MetalDriverFactory.h

@@ -21,12 +21,12 @@
 
 namespace filament {
 namespace backend {
-class MetalPlatform;
+class PlatformMetal;
 class Driver;
 
 class MetalDriverFactory {
 public:
-    static Driver* create(MetalPlatform* platform, const Platform::DriverConfig& driverConfig);
+    static Driver* create(PlatformMetal* platform, const Platform::DriverConfig& driverConfig);
 };
 
 } // namespace backend

filament/backend/src/metal/MetalHandles.h

@@ -30,6 +30,7 @@
 #include "MetalState.h" // for MetalState::VertexDescription
 
 #include <backend/DriverEnums.h>
+#include <backend/platforms/PlatformMetal.h>
 
 #include <utils/bitset.h>
 #include <utils/CString.h>
@@ -51,13 +52,16 @@ class MetalSwapChain : public HwSwapChain {
 public:
 
     // Instantiate a SwapChain from a CAMetalLayer
-    MetalSwapChain(MetalContext& context, CAMetalLayer* nativeWindow, uint64_t flags);
+    MetalSwapChain(MetalContext& context, PlatformMetal& platform, CAMetalLayer* nativeWindow,
+            uint64_t flags);
 
     // Instantiate a SwapChain from a CVPixelBuffer
-    MetalSwapChain(MetalContext& context, CVPixelBufferRef pixelBuffer, uint64_t flags);
+    MetalSwapChain(MetalContext& context, PlatformMetal& platform, CVPixelBufferRef pixelBuffer,
+            uint64_t flags);
 
     // Instantiate a headless SwapChain.
-    MetalSwapChain(MetalContext& context, int32_t width, int32_t height, uint64_t flags);
+    MetalSwapChain(MetalContext& context, PlatformMetal& platform, int32_t width, int32_t height,
+            uint64_t flags);
 
     ~MetalSwapChain();
 
@@ -86,6 +90,8 @@ public:
 
     bool isPixelBuffer() const { return type == SwapChainType::CVPIXELBUFFERREF; }
 
+    bool isAbandoned() const;
+
 private:
 
     enum class SwapChainType {
@@ -103,6 +109,7 @@ private:
     void ensureDepthStencilTexture();
 
     MetalContext& context;
+    PlatformMetal& platform;
     id<CAMetalDrawable> drawable = nil;
     id<MTLTexture> depthStencilTexture = nil;
     id<MTLTexture> headlessDrawable = nil;
@@ -114,6 +121,8 @@ private:
     MetalExternalImage externalImage;
     SwapChainType type;
 
+    int64_t abandonedUntilFrame = -1;
+
     // These fields store a callback to notify the client that a frame is ready for presentation. If
     // !frameScheduled.callback, then the Metal backend automatically calls presentDrawable when the
     // frame is committed. Otherwise, the Metal backend will not automatically present the frame.
@@ -341,6 +350,8 @@ public:
 
     void setUpRenderPassAttachments(MTLRenderPassDescriptor* descriptor, const RenderPassParams& params);
 
+    bool involvesAbandonedSwapChain() const noexcept;
+
     MTLViewport getViewportFromClientViewport(
             Viewport rect, float depthRangeNear, float depthRangeFar) {
         const int32_t height = int32_t(getAttachmentSize().y);

filament/backend/src/metal/MetalHandles.mm

@@ -69,8 +69,10 @@ static inline MTLTextureUsage getMetalTextureUsage(TextureUsage usage) {
     return MTLTextureUsage(u);
 }
 
-MetalSwapChain::MetalSwapChain(MetalContext& context, CAMetalLayer* nativeWindow, uint64_t flags)
+MetalSwapChain::MetalSwapChain(
+        MetalContext& context, PlatformMetal& platform, CAMetalLayer* nativeWindow, uint64_t flags)
     : context(context),
+      platform(platform),
       depthStencilFormat(decideDepthStencilFormat(flags)),
       layer(nativeWindow),
       layerDrawableMutex(std::make_shared<std::mutex>()),
@@ -94,15 +96,19 @@ MetalSwapChain::MetalSwapChain(MetalContext& context, CAMetalLayer* nativeWindow
     layer.device = context.device;
 }
 
-MetalSwapChain::MetalSwapChain(MetalContext& context, int32_t width, int32_t height, uint64_t flags)
+MetalSwapChain::MetalSwapChain(MetalContext& context, PlatformMetal& platform, int32_t width,
+        int32_t height, uint64_t flags)
     : context(context),
+      platform(platform),
       depthStencilFormat(decideDepthStencilFormat(flags)),
       headlessWidth(width),
       headlessHeight(height),
       type(SwapChainType::HEADLESS) {}
 
-MetalSwapChain::MetalSwapChain(MetalContext& context, CVPixelBufferRef pixelBuffer, uint64_t flags)
+MetalSwapChain::MetalSwapChain(MetalContext& context, PlatformMetal& platform,
+        CVPixelBufferRef pixelBuffer, uint64_t flags)
     : context(context),
+      platform(platform),
       depthStencilFormat(decideDepthStencilFormat(flags)),
       externalImage(MetalExternalImage::createFromImage(context, pixelBuffer)),
       type(SwapChainType::CVPIXELBUFFERREF) {
@@ -140,6 +146,10 @@ NSUInteger MetalSwapChain::getSurfaceHeight() const {
     return (NSUInteger) layer.drawableSize.height;
 }
 
+bool MetalSwapChain::isAbandoned() const {
+    return context.currentFrame < abandonedUntilFrame;
+}
+
 id<MTLTexture> MetalSwapChain::acquireDrawable() {
     if (drawable) {
         return drawable.texture;
@@ -180,7 +190,18 @@ id<MTLTexture> MetalSwapChain::acquireDrawable() {
         drawable = [layer nextDrawable];
     }
 
-    FILAMENT_CHECK_POSTCONDITION(drawable != nil) << "Could not obtain drawable.";
+    if (UTILS_UNLIKELY(drawable == nil)) {
+        switch (platform.getDrawableFailureBehavior()) {
+            case PlatformMetal::DrawableFailureBehavior::PANIC:
+                FILAMENT_CHECK_POSTCONDITION(drawable != nil) << "Could not obtain drawable.";
+                break;
+
+            case PlatformMetal::DrawableFailureBehavior::ABORT_FRAME:
+                abandonedUntilFrame = context.currentFrame + 1;
+                return nil;
+        }
+    }
+
     return drawable.texture;
 }
 
@@ -1117,12 +1138,20 @@ void MetalRenderTarget::setUpRenderPassAttachments(MTLRenderPassDescriptor* desc
     }
 }
 
+bool MetalRenderTarget::involvesAbandonedSwapChain() const noexcept {
+    const auto* draw = context->currentDrawSwapChain;
+    const auto* read = context->currentReadSwapChain;
+    return (draw && draw->isAbandoned()) || (read && read->isAbandoned());
+}
+
 MetalRenderTarget::Attachment MetalRenderTarget::getDrawColorAttachment(size_t index) {
     assert_invariant(index < MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT);
     Attachment result = color[index];
     if (index == 0 && defaultRenderTarget) {
         assert_invariant(context->currentDrawSwapChain);
         result.texture = context->currentDrawSwapChain->acquireDrawable();
+        // acquireDrawable may fail to acquire the drawable, in which case result.texture will be
+        // nil, and an invalid attachment
     }
     return result;
 }
@@ -1133,6 +1162,8 @@ MetalRenderTarget::Attachment MetalRenderTarget::getReadColorAttachment(size_t i
     if (index == 0 && defaultRenderTarget) {
         assert_invariant(context->currentReadSwapChain);
         result.texture = context->currentReadSwapChain->acquireDrawable();
+        // acquireDrawable may fail to acquire the drawable, in which case result.texture will be
+        // nil, and an invalid attachment
     }
     return result;
 }

filament/backend/src/metal/PlatformMetal.mm

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-#include "MetalPlatform.h"
+#include <backend/platforms/PlatformMetal.h>
 
 #include "MetalDriverFactory.h"
 
@@ -22,19 +22,32 @@
 
 #import <Foundation/Foundation.h>
 
+#include <atomic>
+
 namespace filament::backend {
 
+struct PlatformMetalImpl {
+    id<MTLCommandQueue> mCommandQueue = nil;
+    // read form driver thread, read/written to from client thread
+    std::atomic<PlatformMetal::DrawableFailureBehavior> mDrawableFailureBehavior =
+            PlatformMetal::DrawableFailureBehavior::PANIC;
+};
+
 Platform* createDefaultMetalPlatform() {
-    return new MetalPlatform();
+    return new PlatformMetal();
 }
 
-MetalPlatform::~MetalPlatform() = default;
+PlatformMetal::PlatformMetal() : pImpl(new PlatformMetalImpl) {}
 
-Driver* MetalPlatform::createDriver(void* /*sharedContext*/, const Platform::DriverConfig& driverConfig) noexcept {
+PlatformMetal::~PlatformMetal() noexcept {
+    delete pImpl;
+}
+
+Driver* PlatformMetal::createDriver(void* /*sharedContext*/, const Platform::DriverConfig& driverConfig) noexcept {
     return MetalDriverFactory::create(this, driverConfig);
 }
 
-id<MTLDevice> MetalPlatform::createDevice() noexcept {
+id<MTLDevice> PlatformMetal::createDevice() noexcept {
     id<MTLDevice> result;
 
 #if !defined(FILAMENT_IOS)
@@ -62,16 +75,24 @@ id<MTLDevice> MetalPlatform::createDevice() noexcept {
     return result;
 }
 
-id<MTLCommandQueue> MetalPlatform::createCommandQueue(id<MTLDevice> device) noexcept {
-    mCommandQueue = [device newCommandQueue];
-    mCommandQueue.label = @"Filament";
-    return mCommandQueue;
+id<MTLCommandQueue> PlatformMetal::createCommandQueue(id<MTLDevice> device) noexcept {
+    pImpl->mCommandQueue = [device newCommandQueue];
+    pImpl->mCommandQueue.label = @"Filament";
+    return pImpl->mCommandQueue;
 }
 
-id<MTLCommandBuffer> MetalPlatform::createAndEnqueueCommandBuffer() noexcept {
-    id<MTLCommandBuffer> commandBuffer = [mCommandQueue commandBuffer];
+id<MTLCommandBuffer> PlatformMetal::createAndEnqueueCommandBuffer() noexcept {
+    id<MTLCommandBuffer> commandBuffer = [pImpl->mCommandQueue commandBuffer];
     [commandBuffer enqueue];
     return commandBuffer;
 }
 
+void PlatformMetal::setDrawableFailureBehavior(DrawableFailureBehavior behavior) noexcept {
+    pImpl->mDrawableFailureBehavior = behavior;
+}
+
+PlatformMetal::DrawableFailureBehavior PlatformMetal::getDrawableFailureBehavior() const noexcept {
+    return pImpl->mDrawableFailureBehavior;
+}
+
 } // namespace filament

filament/backend/src/noop/NoopDriver.cpp

@@ -17,6 +17,10 @@
 #include "noop/NoopDriver.h"
 #include "CommandStreamDispatcher.h"
 
+#include <backend/Handle.h>
+
+#include <stdint.h>
+
 namespace filament::backend {
 
 Driver* NoopDriver::create() {
@@ -39,6 +43,10 @@ ShaderModel NoopDriver::getShaderModel() const noexcept {
 #endif
 }
 
+ShaderLanguage NoopDriver::getShaderLanguage() const noexcept {
+    return ShaderLanguage::ESSL3;
+}
+
 // explicit instantiation of the Dispatcher
 template class ConcreteDispatcher<NoopDriver>;
 
@@ -258,6 +266,9 @@ void NoopDriver::update3DImage(Handle<HwTexture> th,
     scheduleDestroy(std::move(data));
 }
 
+void NoopDriver::setupExternalImage2(Platform::ExternalImageHandleRef image) {
+}
+
 void NoopDriver::setupExternalImage(void* image) {
 }
 

filament/backend/src/noop/NoopDriver.h

@@ -34,6 +34,7 @@ public:
 
 private:
     ShaderModel getShaderModel() const noexcept final;
+    ShaderLanguage getShaderLanguage() const noexcept final;
 
     uint64_t nextFakeHandle = 1;
 

filament/backend/src/opengl/GLUtils.h

@@ -18,6 +18,7 @@
 #define TNT_FILAMENT_BACKEND_OPENGL_GLUTILS_H
 
 #include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/Log.h>
 
 #include <backend/DriverEnums.h>
@@ -25,6 +26,8 @@
 #include <string_view>
 #include <unordered_set>
 
+#include <stdint.h>
+#include <stddef.h>
 #include <string.h>
 
 #include "gl_headers.h"
@@ -50,7 +53,7 @@ void assertFramebufferStatus(utils::io::ostream& out, GLenum target, const char*
 #   define CHECK_GL_FRAMEBUFFER_STATUS(out, target) { GLUtils::checkFramebufferStatus(out, target, __func__, __LINE__); }
 #endif
 
-constexpr inline GLuint getComponentCount(ElementType type) noexcept {
+constexpr GLuint getComponentCount(ElementType type) noexcept {
     using ElementType = ElementType;
     switch (type) {
         case ElementType::BYTE:
@@ -90,7 +93,7 @@ constexpr inline GLuint getComponentCount(ElementType type) noexcept {
 // Our enums to GLenum conversions
 // ------------------------------------------------------------------------------------------------
 
-constexpr inline GLbitfield getAttachmentBitfield(TargetBufferFlags flags) noexcept {
+constexpr GLbitfield getAttachmentBitfield(TargetBufferFlags flags) noexcept {
     GLbitfield mask = 0;
     if (any(flags & TargetBufferFlags::COLOR_ALL)) {
         mask |= (GLbitfield)GL_COLOR_BUFFER_BIT;
@@ -104,7 +107,7 @@ constexpr inline GLbitfield getAttachmentBitfield(TargetBufferFlags flags) noexc
     return mask;
 }
 
-constexpr inline GLenum getBufferUsage(BufferUsage usage) noexcept {
+constexpr GLenum getBufferUsage(BufferUsage usage) noexcept {
     switch (usage) {
         case BufferUsage::STATIC:
             return GL_STATIC_DRAW;
@@ -113,7 +116,7 @@ constexpr inline GLenum getBufferUsage(BufferUsage usage) noexcept {
     }
 }
 
-constexpr inline GLenum getBufferBindingType(BufferObjectBinding bindingType) noexcept {
+constexpr GLenum getBufferBindingType(BufferObjectBinding bindingType) noexcept {
     switch (bindingType) {
         case BufferObjectBinding::VERTEX:
             return GL_ARRAY_BUFFER;
@@ -134,11 +137,11 @@ constexpr inline GLenum getBufferBindingType(BufferObjectBinding bindingType) no
     }
 }
 
-constexpr inline GLboolean getNormalization(bool normalized) noexcept {
+constexpr GLboolean getNormalization(bool normalized) noexcept {
     return GLboolean(normalized ? GL_TRUE : GL_FALSE);
 }
 
-constexpr inline GLenum getComponentType(ElementType type) noexcept {
+constexpr GLenum getComponentType(ElementType type) noexcept {
     using ElementType = ElementType;
     switch (type) {
         case ElementType::BYTE:
@@ -183,12 +186,30 @@ constexpr inline GLenum getComponentType(ElementType type) noexcept {
     }
 }
 
-constexpr inline GLenum getCubemapTarget(uint16_t layer) noexcept {
+constexpr GLenum getTextureTargetNotExternal(SamplerType target) noexcept {
+    switch (target) {
+        case SamplerType::SAMPLER_2D:
+            return GL_TEXTURE_2D;
+        case SamplerType::SAMPLER_3D:
+            return GL_TEXTURE_3D;
+        case SamplerType::SAMPLER_2D_ARRAY:
+            return GL_TEXTURE_2D_ARRAY;
+        case SamplerType::SAMPLER_CUBEMAP:
+            return GL_TEXTURE_CUBE_MAP;
+        case SamplerType::SAMPLER_CUBEMAP_ARRAY:
+            return GL_TEXTURE_CUBE_MAP_ARRAY;
+        case SamplerType::SAMPLER_EXTERNAL:
+            // we should never be here
+            return GL_TEXTURE_2D;
+    }
+}
+
+constexpr GLenum getCubemapTarget(uint16_t layer) noexcept {
     assert_invariant(layer <= 5);
     return GL_TEXTURE_CUBE_MAP_POSITIVE_X + layer;
 }
 
-constexpr inline GLenum getWrapMode(SamplerWrapMode mode) noexcept {
+constexpr GLenum getWrapMode(SamplerWrapMode mode) noexcept {
     using SamplerWrapMode = SamplerWrapMode;
     switch (mode) {
         case SamplerWrapMode::REPEAT:
@@ -200,7 +221,7 @@ constexpr inline GLenum getWrapMode(SamplerWrapMode mode) noexcept {
     }
 }
 
-constexpr inline GLenum getTextureFilter(SamplerMinFilter filter) noexcept {
+constexpr GLenum getTextureFilter(SamplerMinFilter filter) noexcept {
     using SamplerMinFilter = SamplerMinFilter;
     switch (filter) {
         case SamplerMinFilter::NEAREST:
@@ -215,12 +236,12 @@ constexpr inline GLenum getTextureFilter(SamplerMinFilter filter) noexcept {
     }
 }
 
-constexpr inline GLenum getTextureFilter(SamplerMagFilter filter) noexcept {
+constexpr GLenum getTextureFilter(SamplerMagFilter filter) noexcept {
     return GL_NEAREST + GLenum(filter);
 }
 
 
-constexpr inline GLenum getBlendEquationMode(BlendEquation mode) noexcept {
+constexpr GLenum getBlendEquationMode(BlendEquation mode) noexcept {
     using BlendEquation = BlendEquation;
     switch (mode) {
         case BlendEquation::ADD:               return GL_FUNC_ADD;
@@ -231,7 +252,7 @@ constexpr inline GLenum getBlendEquationMode(BlendEquation mode) noexcept {
     }
 }
 
-constexpr inline GLenum getBlendFunctionMode(BlendFunction mode) noexcept {
+constexpr GLenum getBlendFunctionMode(BlendFunction mode) noexcept {
     using BlendFunction = BlendFunction;
     switch (mode) {
         case BlendFunction::ZERO:                  return GL_ZERO;
@@ -248,7 +269,7 @@ constexpr inline GLenum getBlendFunctionMode(BlendFunction mode) noexcept {
     }
 }
 
-constexpr inline GLenum getCompareFunc(SamplerCompareFunc func) noexcept {
+constexpr GLenum getCompareFunc(SamplerCompareFunc func) noexcept {
     switch (func) {
         case SamplerCompareFunc::LE:    return GL_LEQUAL;
         case SamplerCompareFunc::GE:    return GL_GEQUAL;
@@ -262,25 +283,25 @@ constexpr inline GLenum getCompareFunc(SamplerCompareFunc func) noexcept {
 }
 
 #ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
-constexpr inline GLenum getTextureCompareMode(SamplerCompareMode mode) noexcept {
+constexpr GLenum getTextureCompareMode(SamplerCompareMode mode) noexcept {
     return mode == SamplerCompareMode::NONE ?
            GL_NONE : GL_COMPARE_REF_TO_TEXTURE;
 }
 
-constexpr inline GLenum getTextureCompareFunc(SamplerCompareFunc func) noexcept {
+constexpr GLenum getTextureCompareFunc(SamplerCompareFunc func) noexcept {
     return getCompareFunc(func);
 }
 #endif
 
-constexpr inline GLenum getDepthFunc(SamplerCompareFunc func) noexcept {
+constexpr GLenum getDepthFunc(SamplerCompareFunc func) noexcept {
     return getCompareFunc(func);
 }
 
-constexpr inline GLenum getStencilFunc(SamplerCompareFunc func) noexcept {
+constexpr GLenum getStencilFunc(SamplerCompareFunc func) noexcept {
     return getCompareFunc(func);
 }
 
-constexpr inline GLenum getStencilOp(StencilOperation op) noexcept {
+constexpr GLenum getStencilOp(StencilOperation op) noexcept {
     switch (op) {
         case StencilOperation::KEEP:        return GL_KEEP;
         case StencilOperation::ZERO:        return GL_ZERO;
@@ -293,7 +314,7 @@ constexpr inline GLenum getStencilOp(StencilOperation op) noexcept {
     }
 }
 
-constexpr inline GLenum getFormat(PixelDataFormat format) noexcept {
+constexpr GLenum getFormat(PixelDataFormat format) noexcept {
     using PixelDataFormat = PixelDataFormat;
     switch (format) {
         case PixelDataFormat::RGB:              return GL_RGB;
@@ -317,7 +338,7 @@ constexpr inline GLenum getFormat(PixelDataFormat format) noexcept {
     }
 }
 
-constexpr inline GLenum getType(PixelDataType type) noexcept {
+constexpr GLenum getType(PixelDataType type) noexcept {
     using PixelDataType = PixelDataType;
     switch (type) {
         case PixelDataType::UBYTE:                return GL_UNSIGNED_BYTE;
@@ -342,7 +363,7 @@ constexpr inline GLenum getType(PixelDataType type) noexcept {
 }
 
 #if !defined(__EMSCRIPTEN__)  && !defined(FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2)
-constexpr inline GLenum getSwizzleChannel(TextureSwizzle c) noexcept {
+constexpr GLenum getSwizzleChannel(TextureSwizzle c) noexcept {
     using TextureSwizzle = TextureSwizzle;
     switch (c) {
         case TextureSwizzle::SUBSTITUTE_ZERO:   return GL_ZERO;
@@ -355,7 +376,7 @@ constexpr inline GLenum getSwizzleChannel(TextureSwizzle c) noexcept {
 }
 #endif
 
-constexpr inline GLenum getCullingMode(CullingMode mode) noexcept {
+constexpr GLenum getCullingMode(CullingMode mode) noexcept {
     switch (mode) {
         case CullingMode::NONE:
             // should never happen
@@ -370,7 +391,7 @@ constexpr inline GLenum getCullingMode(CullingMode mode) noexcept {
 }
 
 // ES2 supported internal formats for texturing and how they  map to a format/type
-constexpr inline std::pair<GLenum, GLenum> textureFormatToFormatAndType(
+constexpr std::pair<GLenum, GLenum> textureFormatToFormatAndType(
         TextureFormat format) noexcept {
     switch (format) {
         case TextureFormat::R8:         return { 0x1909 /*GL_LUMINANCE*/, GL_UNSIGNED_BYTE };

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -75,9 +75,11 @@
 #include <emscripten.h>
 #endif
 
+#if defined(__clang__)
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wunknown-pragmas"
 #pragma ide diagnostic ignored "OCUnusedGlobalDeclarationInspection"
+#endif
 
 // We can only support this feature on OpenGL ES 3.1+
 // Support is currently disabled as we don't need it
@@ -349,6 +351,10 @@ ShaderModel OpenGLDriver::getShaderModel() const noexcept {
     return mContext.getShaderModel();
 }
 
+ShaderLanguage OpenGLDriver::getShaderLanguage() const noexcept {
+    return mContext.isES2() ? ShaderLanguage::ESSL1 : ShaderLanguage::ESSL3;
+}
+
 // ------------------------------------------------------------------------------------------------
 // Change and track GL state
 // ------------------------------------------------------------------------------------------------
@@ -576,6 +582,10 @@ Handle<HwTexture> OpenGLDriver::createTextureViewSwizzleS() noexcept {
     return initHandle<GLTexture>();
 }
 
+Handle<HwTexture> OpenGLDriver::createTextureExternalImage2S() noexcept {
+    return initHandle<GLTexture>();
+}
+
 Handle<HwTexture> OpenGLDriver::createTextureExternalImageS() noexcept {
     return initHandle<GLTexture>();
 }
@@ -897,25 +907,7 @@ void OpenGLDriver::createTextureR(Handle<HwTexture> th, SamplerType target, uint
 
             t->gl.internalFormat = internalFormat;
 
-            switch (target) {
-                case SamplerType::SAMPLER_EXTERNAL:
-                    // we can't be here -- doesn't matter what we do
-                case SamplerType::SAMPLER_2D:
-                    t->gl.target = GL_TEXTURE_2D;
-                    break;
-                case SamplerType::SAMPLER_3D:
-                    t->gl.target = GL_TEXTURE_3D;
-                    break;
-                case SamplerType::SAMPLER_2D_ARRAY:
-                    t->gl.target = GL_TEXTURE_2D_ARRAY;
-                    break;
-                case SamplerType::SAMPLER_CUBEMAP:
-                    t->gl.target = GL_TEXTURE_CUBE_MAP;
-                    break;
-                case SamplerType::SAMPLER_CUBEMAP_ARRAY:
-                    t->gl.target = GL_TEXTURE_CUBE_MAP_ARRAY;
-                    break;
-            }
+            t->gl.target = getTextureTargetNotExternal(target);
 
             if (t->samples > 1) {
                 // Note: we can't be here in practice because filament's user API doesn't
@@ -989,8 +981,7 @@ void OpenGLDriver::createTextureViewR(Handle<HwTexture> th,
 }
 
 void OpenGLDriver::createTextureViewSwizzleR(Handle<HwTexture> th, Handle<HwTexture> srch,
-        backend::TextureSwizzle r, backend::TextureSwizzle g, backend::TextureSwizzle b,
-        backend::TextureSwizzle a) {
+        TextureSwizzle r, TextureSwizzle g, TextureSwizzle b, TextureSwizzle a) {
 
     DEBUG_MARKER()
     GLTexture const* const src = handle_cast<GLTexture const*>(srch);
@@ -1052,6 +1043,57 @@ void OpenGLDriver::createTextureViewSwizzleR(Handle<HwTexture> th, Handle<HwText
     CHECK_GL_ERROR(utils::slog.e)
 }
 
+void OpenGLDriver::createTextureExternalImage2R(Handle<HwTexture> th, SamplerType target,
+    TextureFormat format, uint32_t width, uint32_t height, TextureUsage usage,
+    Platform::ExternalImageHandleRef image) {
+    DEBUG_MARKER()
+
+    usage |= TextureUsage::SAMPLEABLE;
+    usage &= ~TextureUsage::UPLOADABLE;
+
+    auto& gl = mContext;
+    GLenum internalFormat = getInternalFormat(format);
+    if (UTILS_UNLIKELY(gl.isES2())) {
+        // on ES2, format and internal format must match
+        // FIXME: handle compressed texture format
+        internalFormat = textureFormatToFormatAndType(format).first;
+    }
+    assert_invariant(internalFormat);
+
+    GLTexture* const t = construct<GLTexture>(th, target, 1, 1, width, height, 1, format, usage);
+    assert_invariant(t);
+
+    t->externalTexture = mPlatform.createExternalImageTexture();
+    if (t->externalTexture) {
+        if (target == SamplerType::SAMPLER_EXTERNAL) {
+            if (UTILS_LIKELY(gl.ext.OES_EGL_image_external_essl3)) {
+                t->externalTexture->target = GL_TEXTURE_EXTERNAL_OES;
+            } else {
+                // revert to texture 2D if external is not supported; what else can we do?
+                t->externalTexture->target = GL_TEXTURE_2D;
+            }
+        } else {
+            t->externalTexture->target = getTextureTargetNotExternal(target);
+        }
+
+        t->gl.target = t->externalTexture->target;
+        t->gl.id = t->externalTexture->id;
+        // internalFormat actually depends on the external image, but it doesn't matter
+        // because it's not used anywhere for anything important.
+        t->gl.internalFormat = internalFormat;
+        t->gl.baseLevel = 0;
+        t->gl.maxLevel = 0;
+        t->gl.external = true; // forces bindTexture() call (they're never cached)
+    }
+
+    bindTexture(OpenGLContext::DUMMY_TEXTURE_BINDING, t);
+    if (mPlatform.setExternalImage(image, t->externalTexture)) {
+        // the target and id can be reset each time
+        t->gl.target = t->externalTexture->target;
+        t->gl.id = t->externalTexture->id;
+    }
+}
+
 void OpenGLDriver::createTextureExternalImageR(Handle<HwTexture> th, SamplerType target,
     TextureFormat format, uint32_t width, uint32_t height, TextureUsage usage, void* image) {
     DEBUG_MARKER()
@@ -1073,6 +1115,16 @@ void OpenGLDriver::createTextureExternalImageR(Handle<HwTexture> th, SamplerType
 
     t->externalTexture = mPlatform.createExternalImageTexture();
     if (t->externalTexture) {
+        if (target == SamplerType::SAMPLER_EXTERNAL) {
+            if (UTILS_LIKELY(gl.ext.OES_EGL_image_external_essl3)) {
+                t->externalTexture->target = GL_TEXTURE_EXTERNAL_OES;
+            } else {
+                // revert to texture 2D if external is not supported; what else can we do?
+                t->externalTexture->target = GL_TEXTURE_2D;
+            }
+        } else {
+            t->externalTexture->target = getTextureTargetNotExternal(target);
+        }
         t->gl.target = t->externalTexture->target;
         t->gl.id = t->externalTexture->id;
         // internalFormat actually depends on the external image, but it doesn't matter
@@ -1864,7 +1916,7 @@ void OpenGLDriver::destroyTexture(Handle<HwTexture> th) {
                         detachStream(t);
                     }
                     if (UTILS_UNLIKELY(t->target == SamplerType::SAMPLER_EXTERNAL)) {
-                        mPlatform.destroyExternalImage(t->externalTexture);
+                        mPlatform.destroyExternalImageTexture(t->externalTexture);
                     } else {
                         glDeleteTextures(1, &t->gl.id);
                     }
@@ -2803,6 +2855,10 @@ void OpenGLDriver::setCompressedTextureData(GLTexture* t, uint32_t level,
     CHECK_GL_ERROR(utils::slog.e)
 }
 
+void OpenGLDriver::setupExternalImage2(Platform::ExternalImageHandleRef image) {
+    mPlatform.retainExternalImage(image);
+}
+
 void OpenGLDriver::setupExternalImage(void* image) {
     mPlatform.retainExternalImage(image);
 }
@@ -3433,6 +3489,14 @@ void OpenGLDriver::whenFrameComplete(const std::function<void()>& fn) noexcept {
 
 void OpenGLDriver::whenGpuCommandsComplete(const std::function<void()>& fn) noexcept {
     GLsync sync = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0);
+    // glFenceSync can return 0 in certain situations. For example, we've seen this happen on Web
+    // when the GL context has been lost.
+    // Unfortunately, there's not much we can do here. The fn callback will never execute, which
+    // could cause issues. If we've lost the WebGL context though, Filament is most likely shutting
+    // down anyway, so in practice this might not be a big problem.
+    if (!sync) {
+        return;
+    }
     mGpuCommandCompleteOps.emplace_back(sync, fn);
     CHECK_GL_ERROR(utils::slog.e)
 }
@@ -4090,4 +4154,6 @@ template class ConcreteDispatcher<OpenGLDriver>;
 
 } // namespace filament::backend
 
+#if defined(__clang__)
 #pragma clang diagnostic pop
+#endif

filament/backend/src/opengl/OpenGLDriver.h

@@ -204,6 +204,7 @@ private:
     }
 
     ShaderModel getShaderModel() const noexcept final;
+    ShaderLanguage getShaderLanguage() const noexcept final;
 
     /*
      * Driver interface

filament/backend/src/opengl/OpenGLPlatform.cpp

@@ -121,14 +121,24 @@ OpenGLPlatform::ExternalTexture* OpenGLPlatform::createExternalImageTexture() no
     return nullptr;
 }
 
-void OpenGLPlatform::destroyExternalImage(
+void OpenGLPlatform::destroyExternalImageTexture(
         UTILS_UNUSED ExternalTexture* texture) noexcept {
 }
 
+void OpenGLPlatform::retainExternalImage(
+        UTILS_UNUSED ExternalImageHandleRef externalImage) noexcept {
+}
+
 void OpenGLPlatform::retainExternalImage(
         UTILS_UNUSED void* externalImage) noexcept {
 }
 
+bool OpenGLPlatform::setExternalImage(
+        UTILS_UNUSED ExternalImageHandleRef externalImage,
+        UTILS_UNUSED ExternalTexture* texture) noexcept {
+    return false;
+}
+
 bool OpenGLPlatform::setExternalImage(
         UTILS_UNUSED void* externalImage,
         UTILS_UNUSED ExternalTexture* texture) noexcept {

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

@@ -16,13 +16,28 @@
 
 #include "ExternalStreamManagerAndroid.h"
 
-#include <utils/api_level.h>
+#include <private/backend/VirtualMachineEnv.h>
+
+#include <backend/Platform.h>
+
 #include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/Log.h>
+#include <utils/ostream.h>
 
-#include <dlfcn.h>
+#if __has_include(<android/surface_texture.h>)
+#   include <android/surface_texture.h>
+#   include <android/surface_texture_jni.h>
+#else
+struct ASurfaceTexture;
+typedef struct ASurfaceTexture ASurfaceTexture;
+#endif
 
-#include <chrono>
+#include <jni.h>
+
+#include <stdint.h>
+
+#include <new>
 
 using namespace utils;
 
@@ -32,13 +47,8 @@ using namespace backend;
 using Stream = Platform::Stream;
 
 
-template <typename T>
-static void loadSymbol(T*& pfn, const char *symbol) noexcept {
-    pfn = (T*)dlsym(RTLD_DEFAULT, symbol);
-}
-
 ExternalStreamManagerAndroid& ExternalStreamManagerAndroid::create() noexcept {
-    return *(new ExternalStreamManagerAndroid{});
+    return *(new(std::nothrow) ExternalStreamManagerAndroid{});
 }
 
 void ExternalStreamManagerAndroid::destroy(ExternalStreamManagerAndroid* pExternalStreamManagerAndroid) noexcept {
@@ -56,23 +66,13 @@ ExternalStreamManagerAndroid::~ExternalStreamManagerAndroid() noexcept = default
 
 UTILS_NOINLINE
 JNIEnv* ExternalStreamManagerAndroid::getEnvironmentSlow() noexcept {
-    JNIEnv * env = mVm.getEnvironment();
+    JNIEnv* const env = mVm.getEnvironment();
     mJniEnv = env;
-
     jclass SurfaceTextureClass = env->FindClass("android/graphics/SurfaceTexture");
-
-    mSurfaceTextureClass_updateTexImage = env->GetMethodID(
-            SurfaceTextureClass, "updateTexImage", "()V");
-
-    mSurfaceTextureClass_attachToGLContext = env->GetMethodID(
-            SurfaceTextureClass, "attachToGLContext", "(I)V");
-
-    mSurfaceTextureClass_detachFromGLContext = env->GetMethodID(
-            SurfaceTextureClass, "detachFromGLContext", "()V");
-
-    mSurfaceTextureClass_getTimestamp = env->GetMethodID(
-            SurfaceTextureClass, "getTimestamp", "()J");
-
+    mSurfaceTextureClass_updateTexImage = env->GetMethodID(SurfaceTextureClass, "updateTexImage", "()V");
+    mSurfaceTextureClass_attachToGLContext = env->GetMethodID(SurfaceTextureClass, "attachToGLContext", "(I)V");
+    mSurfaceTextureClass_detachFromGLContext = env->GetMethodID(SurfaceTextureClass, "detachFromGLContext", "()V");
+    mSurfaceTextureClass_getTimestamp = env->GetMethodID(SurfaceTextureClass, "getTimestamp", "()J");
     return env;
 }
 
@@ -82,7 +82,7 @@ Stream* ExternalStreamManagerAndroid::acquire(jobject surfaceTexture) noexcept {
     if (!env) {
         return nullptr; // this should not happen
     }
-    EGLStream* stream = new EGLStream();
+    EGLStream* stream = new(std::nothrow) EGLStream();
     stream->jSurfaceTexture = env->NewGlobalRef(surfaceTexture);
     if (__builtin_available(android 28, *)) {
         stream->nSurfaceTexture = ASurfaceTexture_fromSurfaceTexture(env, surfaceTexture);
@@ -91,29 +91,30 @@ Stream* ExternalStreamManagerAndroid::acquire(jobject surfaceTexture) noexcept {
 }
 
 void ExternalStreamManagerAndroid::release(Stream* handle) noexcept {
-    EGLStream* stream = static_cast<EGLStream*>(handle);
+    EGLStream const* stream = static_cast<EGLStream*>(handle);
     if (__builtin_available(android 28, *)) {
         ASurfaceTexture_release(stream->nSurfaceTexture);
     }
-    JNIEnv* const env = getEnvironment();
+    // use VirtualMachineEnv::getEnvironment() directly because we don't need to cache JNI methods here
+    JNIEnv* const env = mVm.getEnvironment();
     assert_invariant(env); // we should have called attach() by now
     env->DeleteGlobalRef(stream->jSurfaceTexture);
     delete stream;
 }
 
 void ExternalStreamManagerAndroid::attach(Stream* handle, intptr_t tname) noexcept {
-    EGLStream* stream = static_cast<EGLStream*>(handle);
+    EGLStream const* stream = static_cast<EGLStream*>(handle);
     if (__builtin_available(android 28, *)) {
         // associate our GL texture to the SurfaceTexture
         ASurfaceTexture* const aSurfaceTexture = stream->nSurfaceTexture;
-        if (UTILS_UNLIKELY(ASurfaceTexture_attachToGLContext(aSurfaceTexture, (uint32_t)tname))) {
+        if (UTILS_UNLIKELY(ASurfaceTexture_attachToGLContext(aSurfaceTexture, uint32_t(tname)))) {
             // Unfortunately, before API 26 SurfaceTexture was always created in attached mode,
             // so attachToGLContext can fail. We consider this the unlikely case, because
             // this is how it should work.
             // So now we have to detach the surfacetexture from its texture
             ASurfaceTexture_detachFromGLContext(aSurfaceTexture);
             // and finally, try attaching again
-            ASurfaceTexture_attachToGLContext(aSurfaceTexture, (uint32_t)tname);
+            ASurfaceTexture_attachToGLContext(aSurfaceTexture, uint32_t(tname));
         }
     } else {
         JNIEnv* const env = getEnvironment();
@@ -121,19 +122,19 @@ void ExternalStreamManagerAndroid::attach(Stream* handle, intptr_t tname) noexce
 
         // associate our GL texture to the SurfaceTexture
         jobject jSurfaceTexture = stream->jSurfaceTexture;
-        env->CallVoidMethod(jSurfaceTexture, mSurfaceTextureClass_attachToGLContext, (jint)tname);
+        env->CallVoidMethod(jSurfaceTexture, mSurfaceTextureClass_attachToGLContext, jint(tname));
         if (UTILS_UNLIKELY(env->ExceptionCheck())) {
             // Unfortunately, before API 26 SurfaceTexture was always created in attached mode,
             // so attachToGLContext can fail. We consider this the unlikely case, because
             // this is how it should work.
             env->ExceptionClear();
 
-            // so now we have to detach the surfacetexture from its texture
+            // so now we have to detach the SurfaceTexture from its texture
             env->CallVoidMethod(jSurfaceTexture, mSurfaceTextureClass_detachFromGLContext);
             VirtualMachineEnv::handleException(env);
 
             // and finally, try attaching again
-            env->CallVoidMethod(jSurfaceTexture, mSurfaceTextureClass_attachToGLContext, (jint)tname);
+            env->CallVoidMethod(jSurfaceTexture, mSurfaceTextureClass_attachToGLContext, jint(tname));
             VirtualMachineEnv::handleException(env);
         }
     }
@@ -144,7 +145,7 @@ void ExternalStreamManagerAndroid::detach(Stream* handle) noexcept {
     if (__builtin_available(android 28, *)) {
         ASurfaceTexture_detachFromGLContext(stream->nSurfaceTexture);
     } else {
-        JNIEnv* const env = mVm.getEnvironment();
+        JNIEnv* const env = getEnvironment();
         assert_invariant(env); // we should have called attach() by now
         env->CallVoidMethod(stream->jSurfaceTexture, mSurfaceTextureClass_detachFromGLContext);
         VirtualMachineEnv::handleException(env);
@@ -152,12 +153,12 @@ void ExternalStreamManagerAndroid::detach(Stream* handle) noexcept {
 }
 
 void ExternalStreamManagerAndroid::updateTexImage(Stream* handle, int64_t* timestamp) noexcept {
-    EGLStream* stream = static_cast<EGLStream*>(handle);
+    EGLStream const* stream = static_cast<EGLStream*>(handle);
     if (__builtin_available(android 28, *)) {
         ASurfaceTexture_updateTexImage(stream->nSurfaceTexture);
         *timestamp = ASurfaceTexture_getTimestamp(stream->nSurfaceTexture);
     } else {
-        JNIEnv* const env = mVm.getEnvironment();
+        JNIEnv* const env = getEnvironment();
         assert_invariant(env); // we should have called attach() by now
         env->CallVoidMethod(stream->jSurfaceTexture, mSurfaceTextureClass_updateTexImage);
         VirtualMachineEnv::handleException(env);

filament/backend/src/opengl/platforms/ExternalStreamManagerAndroid.h

@@ -21,14 +21,19 @@
 
 #include <backend/Platform.h>
 
+#include <utils/compiler.h>
+
 #if __has_include(<android/surface_texture.h>)
 #   include <android/surface_texture.h>
-#   include <android/surface_texture_jni.h>
 #else
 struct ASurfaceTexture;
 typedef struct ASurfaceTexture ASurfaceTexture;
 #endif
 
+#include <jni.h>
+
+#include <stdint.h>
+
 namespace filament::backend {
 
 /*
@@ -70,7 +75,8 @@ private:
         ASurfaceTexture*    nSurfaceTexture = nullptr;
     };
 
-    inline JNIEnv* getEnvironment() noexcept {
+    // Must only be called from the backend thread
+    JNIEnv* getEnvironment() noexcept {
         JNIEnv* env = mJniEnv;
         if (UTILS_UNLIKELY(!env)) {
             return getEnvironmentSlow();
@@ -85,7 +91,6 @@ private:
     jmethodID mSurfaceTextureClass_attachToGLContext{};
     jmethodID mSurfaceTextureClass_detachFromGLContext{};
 };
-
 } // namespace filament::backend
 
 #endif //TNT_FILAMENT_BACKEND_OPENGL_ANDROID_EXTERNAL_STREAM_MANAGER_ANDROID_H

filament/backend/src/opengl/platforms/PlatformCocoaGL.mm

@@ -54,8 +54,15 @@ struct PlatformCocoaGLImpl {
     CVOpenGLTextureCacheRef mTextureCache = nullptr;
     std::unique_ptr<CocoaExternalImage::SharedGl> mExternalImageSharedGl;
     void updateOpenGLContext(NSView *nsView, bool resetView, bool clearView);
+    struct ExternalImageCocoaGL : public Platform::ExternalImage {
+        CVPixelBufferRef cvBuffer;
+    protected:
+        ~ExternalImageCocoaGL() noexcept final;
+    };
 };
 
+PlatformCocoaGLImpl::ExternalImageCocoaGL::~ExternalImageCocoaGL() noexcept = default;
+
 CocoaGLSwapChain::CocoaGLSwapChain( NSView* inView )
         : view(inView)
         , previousBounds(NSZeroRect)
@@ -309,17 +316,12 @@ OpenGLPlatform::ExternalTexture* PlatformCocoaGL::createExternalImageTexture() n
     if (!pImpl->mExternalImageSharedGl) {
         pImpl->mExternalImageSharedGl = std::make_unique<CocoaExternalImage::SharedGl>();
     }
-
     ExternalTexture* outTexture = new CocoaExternalImage(pImpl->mTextureCache,
             *pImpl->mExternalImageSharedGl);
-
-    // the actual id/target will be set in setExternalImage.
-    outTexture->id = 0;
-    outTexture->target = GL_TEXTURE_2D;
     return outTexture;
 }
 
-void PlatformCocoaGL::destroyExternalImage(ExternalTexture* texture) noexcept {
+void PlatformCocoaGL::destroyExternalImageTexture(ExternalTexture* texture) noexcept {
     auto* p = static_cast<CocoaExternalImage*>(texture);
     delete p;
 }
@@ -344,6 +346,36 @@ bool PlatformCocoaGL::setExternalImage(void* externalImage, ExternalTexture* tex
     return true;
 }
 
+Platform::ExternalImageHandle PlatformCocoaGL::createExternalImage(void* cvPixelBuffer) noexcept {
+    auto* p = new(std::nothrow) PlatformCocoaGLImpl::ExternalImageCocoaGL;
+    p->cvBuffer = (CVPixelBufferRef) cvPixelBuffer;
+    return ExternalImageHandle{ p };
+}
+
+void PlatformCocoaGL::retainExternalImage(ExternalImageHandleRef externalImage) noexcept {
+    auto const* const cocoaGlExternalImage
+            = static_cast<PlatformCocoaGLImpl::ExternalImageCocoaGL const*>(externalImage.get());
+    // Take ownership of the passed in buffer. It will be released the next time
+    // setExternalImage is called, or when the texture is destroyed.
+    CVPixelBufferRef pixelBuffer = cocoaGlExternalImage->cvBuffer;
+    CVPixelBufferRetain(pixelBuffer);
+}
+
+bool PlatformCocoaGL::setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept {
+    auto const* const cocoaGlExternalImage
+            = static_cast<PlatformCocoaGLImpl::ExternalImageCocoaGL const*>(externalImage.get());
+    CVPixelBufferRef cvPixelBuffer = cocoaGlExternalImage->cvBuffer;
+    CocoaExternalImage* cocoaExternalImage = static_cast<CocoaExternalImage*>(texture);
+    if (!cocoaExternalImage->set(cvPixelBuffer)) {
+        return false;
+    }
+    texture->target = cocoaExternalImage->getTarget();
+    texture->id = cocoaExternalImage->getGlTexture();
+    // we used to set the internalFormat, but it's not used anywhere on the gl backend side
+    // cocoaExternalImage->getInternalFormat();
+    return true;
+}
+
 void PlatformCocoaGLImpl::updateOpenGLContext(NSView *nsView, bool resetView,
                                               bool clearView) {
     NSOpenGLContext* glContext = mGLContext;

filament/backend/src/opengl/platforms/PlatformCocoaTouchGL.mm

@@ -47,8 +47,15 @@ struct PlatformCocoaTouchGLImpl {
     GLuint mDefaultDepthbuffer = 0;
     CVOpenGLESTextureCacheRef mTextureCache = nullptr;
     CocoaTouchExternalImage::SharedGl* mExternalImageSharedGl = nullptr;
+    struct ExternalImageCocoaTouchGL : public Platform::ExternalImage {
+        CVPixelBufferRef cvBuffer;
+    protected:
+        ~ExternalImageCocoaTouchGL() noexcept final;
+    };
 };
 
+PlatformCocoaTouchGLImpl::ExternalImageCocoaTouchGL::~ExternalImageCocoaTouchGL() noexcept = default;
+
 PlatformCocoaTouchGL::PlatformCocoaTouchGL()
         : pImpl(new PlatformCocoaTouchGLImpl) {
 }
@@ -198,13 +205,10 @@ void PlatformCocoaTouchGL::commit(Platform::SwapChain* swapChain) noexcept {
 OpenGLPlatform::ExternalTexture* PlatformCocoaTouchGL::createExternalImageTexture() noexcept {
     ExternalTexture* outTexture = new CocoaTouchExternalImage(pImpl->mTextureCache,
             *pImpl->mExternalImageSharedGl);
-    // the actual id/target will be set in setExternalImage*(
-    outTexture->id = 0;
-    outTexture->target = GL_TEXTURE_2D;
     return outTexture;
 }
 
-void PlatformCocoaTouchGL::destroyExternalImage(ExternalTexture* texture) noexcept {
+void PlatformCocoaTouchGL::destroyExternalImageTexture(ExternalTexture* texture) noexcept {
     auto* p = static_cast<CocoaTouchExternalImage*>(texture);
     delete p;
 }
@@ -229,4 +233,35 @@ bool PlatformCocoaTouchGL::setExternalImage(void* externalImage, ExternalTexture
     return true;
 }
 
+Platform::ExternalImageHandle PlatformCocoaTouchGL::createExternalImage(void* cvPixelBuffer) noexcept {
+    auto* p = new(std::nothrow) PlatformCocoaTouchGLImpl::ExternalImageCocoaTouchGL;
+    p->cvBuffer = (CVPixelBufferRef) cvPixelBuffer;
+    return ExternalImageHandle{ p };
+}
+
+void PlatformCocoaTouchGL::retainExternalImage(ExternalImageHandleRef externalImage) noexcept {
+    auto const* const cocoaTouchGlExternalImage
+            = static_cast<PlatformCocoaTouchGLImpl::ExternalImageCocoaTouchGL const*>(externalImage.get());
+    // Take ownership of the passed in buffer. It will be released the next time
+    // setExternalImage is called, or when the texture is destroyed.
+    CVPixelBufferRef pixelBuffer = cocoaTouchGlExternalImage->cvBuffer;
+    CVPixelBufferRetain(pixelBuffer);
+}
+
+bool PlatformCocoaTouchGL::setExternalImage(ExternalImageHandleRef externalImage, ExternalTexture* texture) noexcept {
+    auto const* const cocoaTouchGlExternalImage
+            = static_cast<PlatformCocoaTouchGLImpl::ExternalImageCocoaTouchGL const*>(externalImage.get());
+    CVPixelBufferRef cvPixelBuffer = cocoaTouchGlExternalImage->cvBuffer;
+    CocoaTouchExternalImage* cocoaExternalImage = static_cast<CocoaTouchExternalImage*>(texture);
+    if (!cocoaExternalImage->set(cvPixelBuffer)) {
+        return false;
+    }
+    texture->target = cocoaExternalImage->getTarget();
+    texture->id = cocoaExternalImage->getGlTexture();
+    // we used to set the internalFormat, but it's not used anywhere on the gl backend side
+    // cocoaExternalImage->getInternalFormat();
+    return true;
+}
+
+
 } // namespace filament::backend

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

@@ -117,7 +117,9 @@ bool PlatformEGL::isOpenGL() const noexcept {
     return false;
 }
 
-Driver* PlatformEGL::createDriver(void* sharedContext, const Platform::DriverConfig& driverConfig) noexcept {
+PlatformEGL::ExternalImageEGL::~ExternalImageEGL() = default;
+
+Driver* PlatformEGL::createDriver(void* sharedContext, const DriverConfig& driverConfig) noexcept {
     mEGLDisplay = eglGetDisplay(EGL_DEFAULT_DISPLAY);
     assert_invariant(mEGLDisplay != EGL_NO_DISPLAY);
 
@@ -699,16 +701,10 @@ FenceStatus PlatformEGL::waitFence(
 OpenGLPlatform::ExternalTexture* PlatformEGL::createExternalImageTexture() noexcept {
     ExternalTexture* outTexture = new(std::nothrow) ExternalTexture{};
     glGenTextures(1, &outTexture->id);
-    if (UTILS_LIKELY(ext.gl.OES_EGL_image_external_essl3)) {
-        outTexture->target = GL_TEXTURE_EXTERNAL_OES;
-    } else {
-        // if texture external is not supported, revert to texture 2d
-        outTexture->target = GL_TEXTURE_2D;
-    }
     return outTexture;
 }
 
-void PlatformEGL::destroyExternalImage(ExternalTexture* texture) noexcept {
+void PlatformEGL::destroyExternalImageTexture(ExternalTexture* texture) noexcept {
     glDeleteTextures(1, &texture->id);
     delete texture;
 }
@@ -728,6 +724,18 @@ bool PlatformEGL::setExternalImage(void* externalImage,
     return true;
 }
 
+Platform::ExternalImageHandle PlatformEGL::createExternalImage(EGLImageKHR eglImage) noexcept {
+    auto* const p = new(std::nothrow) ExternalImageEGL;
+    p->eglImage = eglImage;
+    return ExternalImageHandle{p};
+}
+
+bool PlatformEGL::setExternalImage(ExternalImageHandleRef externalImage,
+        UTILS_UNUSED_IN_RELEASE ExternalTexture* texture) noexcept {
+    auto const* const eglExternalImage = static_cast<ExternalImageEGL const*>(externalImage.get());
+    return setExternalImage(eglExternalImage->eglImage, texture);
+}
+
 // -----------------------------------------------------------------------------------------------
 
 void PlatformEGL::initializeGlExtensions() noexcept {

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

@@ -231,6 +231,26 @@ Driver* PlatformEGLAndroid::createDriver(void* sharedContext,
     return driver;
 }
 
+PlatformEGLAndroid::ExternalImageEGLAndroid::~ExternalImageEGLAndroid() = default;
+
+Platform::ExternalImageHandle PlatformEGLAndroid::createExternalImage(AHardwareBuffer const* buffer, bool sRGB) noexcept {
+    auto* const p = new(std::nothrow) ExternalImageEGLAndroid;
+    p->aHardwareBuffer = const_cast<AHardwareBuffer*>(buffer);
+    p->sRGB = sRGB;
+    return ExternalImageHandle{ p };
+}
+
+bool PlatformEGLAndroid::setExternalImage(ExternalImageHandleRef externalImage,
+        UTILS_UNUSED_IN_RELEASE ExternalTexture* texture) noexcept {
+    auto const* const eglExternalImage = static_cast<ExternalImageEGLAndroid const*>(externalImage.get());
+    if (eglExternalImage->aHardwareBuffer) {
+        // TODO: implement PlatformEGLAndroid::setExternalImage w/ AHardwareBuffer
+        return true;
+    }
+    // not a AHardwareBuffer, fallback to the inherited version
+    return PlatformEGL::setExternalImage(externalImage, texture);
+}
+
 void PlatformEGLAndroid::setPresentationTime(int64_t presentationTimeInNanosecond) noexcept {
     EGLSurface currentDrawSurface = eglGetCurrentSurface(EGL_DRAW);
     if (currentDrawSurface != EGL_NO_SURFACE) {

filament/backend/src/vulkan/VulkanBlitter.cpp

@@ -21,6 +21,7 @@
 #include "VulkanHandles.h"
 #include "VulkanSamplerCache.h"
 #include "VulkanTexture.h"
+#include "vulkan/utils/Image.h"
 
 #include <utils/FixedCapacityVector.h>
 #include <utils/Panic.h>
@@ -61,8 +62,8 @@ inline void blitFast(VulkanCommandBuffer* commands, VkImageAspectFlags aspect, V
             .dstOffsets = { dstRect[0], dstRect[1] },
     }};
     vkCmdBlitImage(cmdbuf,
-            src.getImage(), imgutil::getVkLayout(VulkanLayout::TRANSFER_SRC),
-            dst.getImage(), imgutil::getVkLayout(VulkanLayout::TRANSFER_DST),
+            src.getImage(), fvkutils::getVkLayout(VulkanLayout::TRANSFER_SRC),
+            dst.getImage(), fvkutils::getVkLayout(VulkanLayout::TRANSFER_DST),
             1, blitRegions, filter);
 
     if (oldSrcLayout == VulkanLayout::UNDEFINED) {
@@ -104,8 +105,8 @@ inline void resolveFast(VulkanCommandBuffer* commands, VkImageAspectFlags aspect
             .extent = { src.getExtent2D().width, src.getExtent2D().height, 1 },
     }};
     vkCmdResolveImage(cmdbuffer,
-            src.getImage(), imgutil::getVkLayout(VulkanLayout::TRANSFER_SRC),
-            dst.getImage(), imgutil::getVkLayout(VulkanLayout::TRANSFER_DST),
+            src.getImage(), fvkutils::getVkLayout(VulkanLayout::TRANSFER_SRC),
+            dst.getImage(), fvkutils::getVkLayout(VulkanLayout::TRANSFER_DST),
             1, resolveRegions);
 
     if (oldSrcLayout == VulkanLayout::UNDEFINED) {

filament/backend/src/vulkan/VulkanCommands.h

@@ -23,8 +23,8 @@
 
 #include "VulkanAsyncHandles.h"
 #include "VulkanConstants.h"
-#include "VulkanUtility.h"
 #include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/StaticVector.h"
 
 #include <utils/Condition.h>
 #include <utils/FixedCapacityVector.h>
@@ -79,7 +79,7 @@ struct VulkanCommandBuffer {
     void reset() noexcept;
 
     inline void insertWait(VkSemaphore sem) {
-        mWaitSemaphores.insert(sem);
+        mWaitSemaphores.push_back(sem);
     }
 
     void pushMarker(char const* marker) noexcept;
@@ -115,7 +115,7 @@ private:
     bool const isProtected;
     VkDevice mDevice;
     VkQueue mQueue;
-    CappedArray<VkSemaphore, 2> mWaitSemaphores;
+    fvkutils::StaticVector<VkSemaphore, 2> mWaitSemaphores;
     VkCommandBuffer mBuffer;
     VkSemaphore mSubmission;
     VkFence mFence;

filament/backend/src/vulkan/VulkanContext.cpp

@@ -20,7 +20,6 @@
 #include "VulkanHandles.h"
 #include "VulkanMemory.h"
 #include "VulkanTexture.h"
-#include "VulkanUtility.h"
 
 #include <backend/PixelBufferDescriptor.h>
 

filament/backend/src/vulkan/VulkanContext.h

@@ -18,8 +18,8 @@
 #define TNT_FILAMENT_BACKEND_VULKANCONTEXT_H
 
 #include "VulkanConstants.h"
-#include "VulkanImageUtility.h"
-#include "VulkanUtility.h"
+#include "vulkan/utils/Image.h"
+#include "vulkan/utils/Definitions.h"
 
 #include "vulkan/memory/ResourcePointer.h"
 
@@ -28,6 +28,8 @@
 #include <utils/Mutex.h>
 #include <utils/Slice.h>
 
+#include <bluevk/BlueVK.h>
+
 #include <memory>
 
 VK_DEFINE_HANDLE(VmaAllocator)
@@ -113,11 +115,11 @@ public:
         return (uint32_t) VK_MAX_MEMORY_TYPES;
     }
 
-    inline VkFormatList const& getAttachmentDepthStencilFormats() const {
+    inline fvkutils::VkFormatList const& getAttachmentDepthStencilFormats() const {
         return mDepthStencilFormats;
     }
 
-    inline VkFormatList const& getBlittableDepthStencilFormats() const {
+    inline fvkutils::VkFormatList const& getBlittableDepthStencilFormats() const {
         return mBlittableDepthStencilFormats;
     }
 
@@ -175,8 +177,8 @@ private:
     bool mLazilyAllocatedMemorySupported = false;
     bool mProtectedMemorySupported = false;
 
-    VkFormatList mDepthStencilFormats;
-    VkFormatList mBlittableDepthStencilFormats;
+    fvkutils::VkFormatList mDepthStencilFormats;
+    fvkutils::VkFormatList mBlittableDepthStencilFormats;
 
     // For convenience so that VulkanPlatform can initialize the private fields.
     friend class VulkanPlatform;

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -26,9 +26,12 @@
 #include "VulkanHandles.h"
 #include "VulkanMemory.h"
 #include "VulkanTexture.h"
-#include "memory/ResourceManager.h"
-#include "memory/ResourcePointer.h"
+#include "vulkan/memory/ResourceManager.h"
+#include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/Conversion.h"
+#include "vulkan/utils/Definitions.h"
 
+#include <backend/DriverEnums.h>
 #include <backend/platforms/VulkanPlatform.h>
 
 #include <utils/CString.h>
@@ -43,11 +46,13 @@ using namespace bluevk;
 
 using utils::FixedCapacityVector;
 
+#if defined(__clang__)
 // Vulkan functions often immediately dereference pointers, so it's fine to pass in a pointer
 // to a stack-allocated variable.
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wreturn-stack-address"
 #pragma clang diagnostic ignored "-Wunused-parameter"
+#endif
 
 namespace filament::backend {
 
@@ -295,6 +300,10 @@ ShaderModel VulkanDriver::getShaderModel() const noexcept {
 #endif
 }
 
+ShaderLanguage VulkanDriver::getShaderLanguage() const noexcept {
+    return ShaderLanguage::SPIRV;
+}
+
 void VulkanDriver::terminate() {
     // Flush and wait here to make sure all queued commands are executed and resources that are tied
     // to those commands are no longer referenced.
@@ -536,16 +545,25 @@ void VulkanDriver::createTextureViewSwizzleR(Handle<HwTexture> th, Handle<HwText
         backend::TextureSwizzle r, backend::TextureSwizzle g, backend::TextureSwizzle b,
         backend::TextureSwizzle a) {
    TextureSwizzle const swizzleArray[] = {r, g, b, a};
-   VkComponentMapping const swizzle = getSwizzleMap(swizzleArray);
+   VkComponentMapping const swizzle = fvkutils::getSwizzleMap(swizzleArray);
    auto src = resource_ptr<VulkanTexture>::cast(&mResourceManager, srch);
    auto texture = resource_ptr<VulkanTexture>::make(&mResourceManager, th, mPlatform->getDevice(),
            mPlatform->getPhysicalDevice(), mContext, mAllocator, &mCommands, src, swizzle);
    texture.inc();
 }
 
-void VulkanDriver::createTextureExternalImageR(Handle<HwTexture> th,
+void VulkanDriver::createTextureExternalImage2R(Handle<HwTexture> th,
         backend::SamplerType target,  backend::TextureFormat format,
-        uint32_t width, uint32_t height, backend::TextureUsage usage, void* externalImage) {
+        uint32_t width, uint32_t height, backend::TextureUsage usage,
+        Platform::ExternalImageHandleRef externalImage) {
+    FVK_SYSTRACE_SCOPE();
+
+    // FIXME: implement createTextureExternalImage2R
+}
+
+void VulkanDriver::createTextureExternalImageR(Handle<HwTexture> th, backend::SamplerType target,
+        backend::TextureFormat format, uint32_t width, uint32_t height, backend::TextureUsage usage,
+        void* externalImage) {
     FVK_SYSTRACE_SCOPE();
 
     const auto& metadata = mPlatform->getExternalImageMetadata(externalImage);
@@ -555,7 +573,7 @@ void VulkanDriver::createTextureExternalImageR(Handle<HwTexture> th,
 
     assert_invariant(width == metadata.width);
     assert_invariant(height == metadata.height);
-    assert_invariant(getVkFormat(format) == metadata.format);
+    assert_invariant(fvkutils::getVkFormat(format) == metadata.format);
 
     const auto& data = mPlatform->createExternalImage(externalImage, metadata);
 
@@ -700,6 +718,11 @@ void VulkanDriver::createFenceR(Handle<HwFence> fh, int) {
 }
 
 void VulkanDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow, uint64_t flags) {
+    // Running gc() to guard against an edge case where the old swapchains need to have been
+    // destroyed before the new swapchain can be created. Otherwise, we would fail
+    // vkCreateSwapchainKHR with VK_ERROR_NATIVE_WINDOW_IN_USE_KHR.
+    mResourceManager.gc();
+
     if ((flags & backend::SWAP_CHAIN_CONFIG_SRGB_COLORSPACE) != 0 && !isSRGBSwapChainSupported()) {
         FVK_LOGW << "sRGB swapchain requested, but Platform does not support it"
                  << utils::io::endl;
@@ -778,6 +801,10 @@ Handle<HwTexture> VulkanDriver::createTextureViewSwizzleS() noexcept {
     return mResourceManager.allocHandle<VulkanTexture>();
 }
 
+Handle<HwTexture> VulkanDriver::createTextureExternalImage2S() noexcept {
+    return mResourceManager.allocHandle<VulkanTexture>();
+}
+
 Handle<HwTexture> VulkanDriver::createTextureExternalImageS() noexcept {
     return mResourceManager.allocHandle<VulkanTexture>();
 }
@@ -925,7 +952,7 @@ FenceStatus VulkanDriver::getFenceStatus(Handle<HwFence> fh) {
 // We create all textures using VK_IMAGE_TILING_OPTIMAL, so our definition of "supported" is that
 // the GPU supports the given texture format with non-zero optimal tiling features.
 bool VulkanDriver::isTextureFormatSupported(TextureFormat format) {
-    VkFormat vkformat = getVkFormat(format);
+    VkFormat vkformat = fvkutils::getVkFormat(format);
     if (vkformat == VK_FORMAT_UNDEFINED) {
         return false;
     }
@@ -952,7 +979,7 @@ bool VulkanDriver::isTextureFormatMipmappable(TextureFormat format) {
 }
 
 bool VulkanDriver::isRenderTargetFormatSupported(TextureFormat format) {
-    VkFormat vkformat = getVkFormat(format);
+    VkFormat vkformat = fvkutils::getVkFormat(format);
     if (vkformat == VK_FORMAT_UNDEFINED) {
         return false;
     }
@@ -1010,12 +1037,11 @@ bool VulkanDriver::isDepthStencilResolveSupported() {
 
 bool VulkanDriver::isDepthStencilBlitSupported(TextureFormat format) {
     auto const& formats = mContext.getBlittableDepthStencilFormats();
-    return std::find(formats.begin(), formats.end(), getVkFormat(format)) != formats.end();
+    return std::find(formats.begin(), formats.end(), fvkutils::getVkFormat(format)) !=
+           formats.end();
 }
 
-bool VulkanDriver::isProtectedTexturesSupported() {
-    return false;
-}
+bool VulkanDriver::isProtectedTexturesSupported() { return false; }
 
 bool VulkanDriver::isDepthClampSupported() {
     return mContext.isDepthClampSupported();
@@ -1086,8 +1112,8 @@ FeatureLevel VulkanDriver::getFeatureLevel() {
 
 math::float2 VulkanDriver::getClipSpaceParams() {
     // virtual and physical z-coordinate of clip-space is in [-w, 0]
-    // Note: this is actually never used (see: main.vs), but it's a backend API, so we implement it
-    // properly.
+    // Note: this is actually never used (see: surface_main.vs), but it's a backend API, so we
+    // implement it properly.
     return math::float2{ 1.0f, 0.0f };
 }
 
@@ -1158,6 +1184,9 @@ void VulkanDriver::update3DImage(Handle<HwTexture> th, uint32_t level, uint32_t
     scheduleDestroy(std::move(data));
 }
 
+void VulkanDriver::setupExternalImage2(Platform::ExternalImageHandleRef image) {
+}
+
 void VulkanDriver::setupExternalImage(void* image) {
 }
 
@@ -1668,25 +1697,25 @@ void VulkanDriver::bindPipeline(PipelineState const& pipelineState) {
     auto rt = mCurrentRenderPass.renderTarget;
 
     VulkanPipelineCache::RasterState const vulkanRasterState{
-        .cullMode = getCullMode(rasterState.culling),
-        .frontFace = getFrontFace(rasterState.inverseFrontFaces),
+        .cullMode = fvkutils::getCullMode(rasterState.culling),
+        .frontFace = fvkutils::getFrontFace(rasterState.inverseFrontFaces),
         .depthBiasEnable = (depthOffset.constant || depthOffset.slope) ? true : false,
         .blendEnable = rasterState.hasBlending(),
         .depthWriteEnable = rasterState.depthWrite,
         .alphaToCoverageEnable = rasterState.alphaToCoverage,
-        .srcColorBlendFactor = getBlendFactor(rasterState.blendFunctionSrcRGB),
-        .dstColorBlendFactor = getBlendFactor(rasterState.blendFunctionDstRGB),
-        .srcAlphaBlendFactor = getBlendFactor(rasterState.blendFunctionSrcAlpha),
-        .dstAlphaBlendFactor = getBlendFactor(rasterState.blendFunctionDstAlpha),
+        .srcColorBlendFactor = fvkutils::getBlendFactor(rasterState.blendFunctionSrcRGB),
+        .dstColorBlendFactor = fvkutils::getBlendFactor(rasterState.blendFunctionDstRGB),
+        .srcAlphaBlendFactor = fvkutils::getBlendFactor(rasterState.blendFunctionSrcAlpha),
+        .dstAlphaBlendFactor = fvkutils::getBlendFactor(rasterState.blendFunctionDstAlpha),
         .colorWriteMask = (VkColorComponentFlags) (rasterState.colorWrite ? 0xf : 0x0),
         .rasterizationSamples = rt->getSamples(),
         .depthClamp = rasterState.depthClamp,
         .colorTargetCount = rt->getColorTargetCount(mCurrentRenderPass),
         .colorBlendOp = rasterState.blendEquationRGB,
-        .alphaBlendOp =  rasterState.blendEquationAlpha,
+        .alphaBlendOp = rasterState.blendEquationAlpha,
         .depthCompareOp = rasterState.depthFunc,
         .depthBiasConstantFactor = depthOffset.constant,
-        .depthBiasSlopeFactor = depthOffset.slope
+        .depthBiasSlopeFactor = depthOffset.slope,
     };
 
     // unfortunately in Vulkan the topology is per pipeline
@@ -1723,7 +1752,7 @@ void VulkanDriver::bindPipeline(PipelineState const& pipelineState) {
     mBoundPipeline = {
         .program = program,
         .pipelineLayout = pipelineLayout,
-        .descriptorSetMask = DescriptorSetMask(descriptorSetMaskTable[layoutCount]),
+        .descriptorSetMask = fvkutils::DescriptorSetMask(descriptorSetMaskTable[layoutCount]),
     };
 
     mPipelineCache.bindLayout(pipelineLayout);
@@ -1872,4 +1901,6 @@ template class ConcreteDispatcher<VulkanDriver>;
 
 } // namespace filament::backend
 
+#if defined(__clang__)
 #pragma clang diagnostic pop
+#endif

filament/backend/src/vulkan/VulkanDriver.h

@@ -26,12 +26,13 @@
 #include "VulkanReadPixels.h"
 #include "VulkanSamplerCache.h"
 #include "VulkanStagePool.h"
-#include "VulkanUtility.h"
+#include "vulkan/caching/VulkanDescriptorSetManager.h"
+#include "vulkan/caching/VulkanPipelineLayoutCache.h"
+#include "vulkan/memory/ResourceManager.h"
+#include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/Definitions.h"
+
 #include "backend/DriverEnums.h"
-#include "caching/VulkanDescriptorSetManager.h"
-#include "caching/VulkanPipelineLayoutCache.h"
-#include "memory/ResourceManager.h"
-#include "memory/ResourcePointer.h"
 
 #include "DriverBase.h"
 #include "private/backend/Driver.h"
@@ -93,6 +94,7 @@ private:
     Dispatcher getDispatcher() const noexcept final;
 
     ShaderModel getShaderModel() const noexcept final;
+    ShaderLanguage getShaderLanguage() const noexcept final;
 
     template<typename T>
     friend class ConcreteDispatcher;
@@ -141,13 +143,14 @@ private:
     struct {
         resource_ptr<VulkanProgram> program;
         VkPipelineLayout pipelineLayout;
-        DescriptorSetMask descriptorSetMask;
+        fvkutils::DescriptorSetMask descriptorSetMask;
     } mBoundPipeline = {};
 
     // We need to store information about a render pass to enable better barriers at the end of a
     // renderpass.
     struct {
-        using AttachmentArray = CappedArray<VulkanAttachment, MAX_RENDERTARGET_ATTACHMENT_TEXTURES>;
+        using AttachmentArray =
+                fvkutils::StaticVector<VulkanAttachment, MAX_RENDERTARGET_ATTACHMENT_TEXTURES>;
         AttachmentArray attachments;
     } mRenderPassFboInfo = {};
 

filament/backend/src/vulkan/VulkanFboCache.cpp

@@ -14,12 +14,12 @@
  * limitations under the License.
  */
 
-#include "vulkan/VulkanFboCache.h"
-
-#include <utils/Panic.h>
+#include "VulkanFboCache.h"
 
 #include "VulkanConstants.h"
-#include "VulkanUtility.h"
+#include "vulkan/utils/Image.h"
+
+#include <utils/Panic.h>
 
 // If any VkRenderPass or VkFramebuffer is unused for more than TIME_BEFORE_EVICTION frames, it
 // is evicted from the cache.
@@ -214,7 +214,7 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
         if (config.colorFormat[i] == VK_FORMAT_UNDEFINED) {
             continue;
         }
-        const VkImageLayout subpassLayout = imgutil::getVkLayout(VulkanLayout::COLOR_ATTACHMENT);
+        const VkImageLayout subpassLayout = fvkutils::getVkLayout(VulkanLayout::COLOR_ATTACHMENT);
         uint32_t index;
 
         if (!hasSubpasses) {
@@ -259,8 +259,8 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
             .storeOp = (config.usesLazilyAllocatedMemory & (1 << i)) ? kDisableStore : kEnableStore,
             .stencilLoadOp = kDontCare,
             .stencilStoreOp = kDisableStore,
-            .initialLayout = imgutil::getVkLayout(VulkanLayout::COLOR_ATTACHMENT),
-            .finalLayout = imgutil::getVkLayout(FINAL_COLOR_ATTACHMENT_LAYOUT),
+            .initialLayout = fvkutils::getVkLayout(VulkanLayout::COLOR_ATTACHMENT),
+            .finalLayout = fvkutils::getVkLayout(FINAL_COLOR_ATTACHMENT_LAYOUT),
         };
     }
 
@@ -287,7 +287,7 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
 
         pResolveAttachment->attachment = attachmentIndex;
         pResolveAttachment->layout
-                = imgutil::getVkLayout(VulkanLayout::COLOR_ATTACHMENT_RESOLVE);
+                = fvkutils::getVkLayout(VulkanLayout::COLOR_ATTACHMENT_RESOLVE);
         ++pResolveAttachment;
 
         attachments[attachmentIndex++] = {
@@ -297,8 +297,8 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
             .storeOp = kEnableStore,
             .stencilLoadOp = kDontCare,
             .stencilStoreOp = kDisableStore,
-            .initialLayout = imgutil::getVkLayout(VulkanLayout::COLOR_ATTACHMENT),
-            .finalLayout = imgutil::getVkLayout(FINAL_COLOR_ATTACHMENT_LAYOUT),
+            .initialLayout = fvkutils::getVkLayout(VulkanLayout::COLOR_ATTACHMENT),
+            .finalLayout = fvkutils::getVkLayout(FINAL_COLOR_ATTACHMENT_LAYOUT),
         };
     }
 
@@ -307,7 +307,7 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
         const bool clear = any(config.clear & TargetBufferFlags::DEPTH);
         const bool discardStart = any(config.discardStart & TargetBufferFlags::DEPTH);
         const bool discardEnd = any(config.discardEnd & TargetBufferFlags::DEPTH);
-        depthAttachmentRef.layout = imgutil::getVkLayout(VulkanLayout::DEPTH_ATTACHMENT);
+        depthAttachmentRef.layout = fvkutils::getVkLayout(VulkanLayout::DEPTH_ATTACHMENT);
         depthAttachmentRef.attachment = attachmentIndex;
         attachments[attachmentIndex++] = {
             .format = config.depthFormat,
@@ -316,8 +316,8 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey const& config) noexcept
             .storeOp = discardEnd ? kDisableStore : kEnableStore,
             .stencilLoadOp = VK_ATTACHMENT_LOAD_OP_DONT_CARE,
             .stencilStoreOp = VK_ATTACHMENT_STORE_OP_DONT_CARE,
-            .initialLayout = imgutil::getVkLayout(config.initialDepthLayout),
-            .finalLayout = imgutil::getVkLayout(FINAL_DEPTH_ATTACHMENT_LAYOUT),
+            .initialLayout = fvkutils::getVkLayout(config.initialDepthLayout),
+            .finalLayout = fvkutils::getVkLayout(FINAL_DEPTH_ATTACHMENT_LAYOUT),
         };
     }
     renderPassInfo.attachmentCount = attachmentIndex;

filament/backend/src/vulkan/VulkanHandles.cpp

@@ -22,9 +22,11 @@
 #include "VulkanDriver.h"
 
 #include "VulkanMemory.h"
-#include "VulkanUtility.h"
 #include "vulkan/memory/ResourcePointer.h"
-#include "spirv/VulkanSpirvUtils.h"
+#include "vulkan/utils/Conversion.h"
+#include "vulkan/utils/Definitions.h"
+#include "vulkan/utils/Image.h"
+#include "vulkan/utils/Spirv.h"
 
 #include <backend/platforms/VulkanPlatform.h>
 
@@ -56,10 +58,10 @@ template<typename Bitmask>
 inline void fromStageFlags(backend::ShaderStageFlags stage, descriptor_binding_t binding,
         Bitmask& mask) {
     if ((bool) (stage & ShaderStageFlags::VERTEX)) {
-        mask.set(binding + getVertexStageShift<Bitmask>());
+        mask.set(binding + fvkutils::getVertexStageShift<Bitmask>());
     }
     if ((bool) (stage & ShaderStageFlags::FRAGMENT)) {
-        mask.set(binding + getFragmentStageShift<Bitmask>());
+        mask.set(binding + fvkutils::getFragmentStageShift<Bitmask>());
     }
 }
 
@@ -206,7 +208,7 @@ VulkanProgram::VulkanProgram(VkDevice device, Program const& builder) noexcept
         size_t dataSize = blob.size();
 
         if (!specializationConstants.empty()) {
-            workaroundSpecConstant(blob, specializationConstants, shader);
+            fvkutils::workaroundSpecConstant(blob, specializationConstants, shader);
             data = (uint32_t*) shader.data();
             dataSize = shader.size() * 4;
         }
@@ -314,8 +316,8 @@ VulkanRenderTarget::VulkanRenderTarget(VkDevice device, VkPhysicalDevice physica
     // Constrain the sample count according to both kinds of sample count masks obtained from
     // VkPhysicalDeviceProperties. This is consistent with the VulkanTexture constructor.
     auto const& limits = context.getPhysicalDeviceLimits();
-    samples = reduceSampleCount(samples, limits.framebufferDepthSampleCounts &
-            limits.framebufferColorSampleCounts);
+    samples = samples = fvkutils::reduceSampleCount(samples,
+            limits.framebufferDepthSampleCounts & limits.framebufferColorSampleCounts);
 
     auto& rpkey = mInfo->rpkey;
     rpkey.samples = samples;
@@ -498,7 +500,7 @@ VulkanVertexBufferInfo::VulkanVertexBufferInfo(
         Attribute attrib = attributes[attribIndex];
         bool const isInteger = attrib.flags & Attribute::FLAG_INTEGER_TARGET;
         bool const isNormalized = attrib.flags & Attribute::FLAG_NORMALIZED;
-        VkFormat vkformat = getVkFormat(attrib.type, isNormalized, isInteger);
+        VkFormat vkformat = fvkutils::getVkFormat(attrib.type, isNormalized, isInteger);
 
         // HACK: Re-use the positions buffer as a dummy buffer for disabled attributes. Filament's
         // vertex shaders declare all attributes as either vec4 or uvec4 (the latter for bone

filament/backend/src/vulkan/VulkanHandles.h

@@ -25,8 +25,9 @@
 #include "VulkanFboCache.h"
 #include "VulkanSwapChain.h"
 #include "VulkanTexture.h"
-#include "VulkanUtility.h"
 #include "vulkan/memory/Resource.h"
+#include "vulkan/utils/StaticVector.h"
+#include "vulkan/utils/Definitions.h"
 
 #include <backend/Program.h>
 
@@ -44,11 +45,11 @@ namespace {
 template<typename Bitmask>
 inline uint8_t collapsedCount(Bitmask const& mask) {
     static_assert(sizeof(mask) <= 64);
-    constexpr uint64_t VERTEX_MASK = (1ULL << getFragmentStageShift<Bitmask>()) - 1ULL;
-    constexpr uint64_t FRAGMENT_MASK = (VERTEX_MASK << getFragmentStageShift<Bitmask>());
+    constexpr uint64_t VERTEX_MASK = (1ULL << fvkutils::getFragmentStageShift<Bitmask>()) - 1ULL;
+    constexpr uint64_t FRAGMENT_MASK = (VERTEX_MASK << fvkutils::getFragmentStageShift<Bitmask>());
     uint64_t val = mask.getValue();
-    val = ((val & VERTEX_MASK) >> getVertexStageShift<Bitmask>()) |
-        ((val & FRAGMENT_MASK) >> getFragmentStageShift<Bitmask>());
+    val = ((val & VERTEX_MASK) >> fvkutils::getVertexStageShift<Bitmask>()) |
+          ((val & FRAGMENT_MASK) >> fvkutils::getFragmentStageShift<Bitmask>());
     return (uint8_t) Bitmask(val).count();
 }
 
@@ -67,10 +68,10 @@ struct VulkanDescriptorSetLayout : public HwDescriptorSetLayout, fvkmemory::Reso
     // The bitmask representation of a set layout.
     struct Bitmask {
         // TODO: better utiltize the space below and use bitset instead.
-        UniformBufferBitmask ubo;         // 8 bytes
-        UniformBufferBitmask dynamicUbo;  // 8 bytes
-        SamplerBitmask sampler;           // 8 bytes
-        InputAttachmentBitmask inputAttachment; // 8 bytes
+        fvkutils::UniformBufferBitmask ubo;         // 8 bytes
+        fvkutils::UniformBufferBitmask dynamicUbo;  // 8 bytes
+        fvkutils::SamplerBitmask sampler;           // 8 bytes
+        fvkutils::InputAttachmentBitmask inputAttachment; // 8 bytes
 
         bool operator==(Bitmask const& right) const {
             return ubo == right.ubo && dynamicUbo == right.dynamicUbo && sampler == right.sampler &&
@@ -138,7 +139,7 @@ public:
     using OnRecycle = std::function<void(VulkanDescriptorSet*)>;
 
     VulkanDescriptorSet(VkDescriptorSet rawSet,
-            UniformBufferBitmask const& dynamicUboMask,
+            fvkutils::UniformBufferBitmask const& dynamicUboMask,
             uint8_t uniqueDynamicUboCount,
             OnRecycle&& onRecycleFn)
         : vkSet(rawSet),
@@ -164,7 +165,7 @@ public:
     void acquire(fvkmemory::resource_ptr<VulkanBufferObject> buffer);
 
     VkDescriptorSet const vkSet;
-    UniformBufferBitmask const dynamicUboMask;
+    fvkutils::UniformBufferBitmask const dynamicUboMask;
     uint8_t const uniqueDynamicUboCount;
 
 private:
@@ -193,7 +194,7 @@ private:
 };
 
 struct VulkanProgram : public HwProgram, fvkmemory::Resource {
-    using BindingList = CappedArray<uint16_t, MAX_SAMPLER_COUNT>;
+    using BindingList = fvkutils::StaticVector<uint16_t, MAX_SAMPLER_COUNT>;
 
     VulkanProgram(VkDevice device, Program const& builder) noexcept;
     ~VulkanProgram();

filament/backend/src/vulkan/VulkanMemory.cpp

@@ -16,6 +16,7 @@
 
 #include <bluevk/BlueVK.h> // must be included before vk_mem_alloc
 
+#if defined(__clang__)
 #pragma clang diagnostic push
 
 // Needed because not all clang versions have the warning -Wdeprecated-copy.
@@ -32,6 +33,7 @@
 #pragma clang diagnostic ignored "-Wextra-semi"
 #pragma clang diagnostic ignored "-Wc++98-compat-extra-semi"
 #pragma clang diagnostic ignored "-Wthread-safety-analysis"
+#endif
 
 static const PFN_vkGetInstanceProcAddr& vkGetInstanceProcAddr = bluevk::vkGetInstanceProcAddr;
 static const PFN_vkGetDeviceProcAddr& vkGetDeviceProcAddr = bluevk::vkGetDeviceProcAddr;
@@ -39,4 +41,7 @@ static const PFN_vkGetDeviceProcAddr& vkGetDeviceProcAddr = bluevk::vkGetDeviceP
 #define VMA_STATIC_VULKAN_FUNCTIONS 0
 #define VMA_IMPLEMENTATION
 #include "vk_mem_alloc.h"
+
+#if defined(__clang__)
 #pragma clang diagnostic pop
+#endif

filament/backend/src/vulkan/VulkanMemory.h

@@ -27,7 +27,9 @@
 #define VMA_DYNAMIC_VULKAN_FUNCTIONS 1
 #endif
 
+#if defined(__clang__)
 #pragma clang diagnostic ignored "-Wc++98-compat-extra-semi"
+#endif
 
 #include "vk_mem_alloc.h"
 

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -24,12 +24,14 @@
 #include "VulkanConstants.h"
 #include "VulkanHandles.h"
 #include "VulkanTexture.h"
-#include "VulkanUtility.h"
+#include "vulkan/utils/Conversion.h"
 
+#if defined(__clang__)
 // Vulkan functions often immediately dereference pointers, so it's fine to pass in a pointer
 // to a stack-allocated variable.
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wreturn-stack-address"
+#endif
 
 using namespace bluevk;
 
@@ -194,7 +196,7 @@ VulkanPipelineCache::PipelineCacheEntry* VulkanPipelineCache::createPipeline() n
 
     vkDs.depthTestEnable = VK_TRUE;
     vkDs.depthWriteEnable = raster.depthWriteEnable;
-    vkDs.depthCompareOp = getCompareOp(raster.depthCompareOp);
+    vkDs.depthCompareOp = fvkutils::getCompareOp(raster.depthCompareOp);
     vkDs.depthBoundsTestEnable = VK_FALSE;
     vkDs.stencilTestEnable = VK_FALSE;
     vkDs.minDepthBounds = 0.0f;
@@ -323,4 +325,6 @@ bool VulkanPipelineCache::PipelineEqual::operator()(const PipelineKey& k1,
 
 } // namespace filament::backend
 
+#if defined(__clang__)
 #pragma clang diagnostic pop
+#endif

filament/backend/src/vulkan/VulkanPipelineCache.h

@@ -19,7 +19,6 @@
 
 #include "VulkanCommands.h"
 #include "VulkanMemory.h"
-#include "VulkanUtility.h"
 
 #include <backend/DriverEnums.h>
 #include <backend/TargetBufferInfo.h>
@@ -68,8 +67,10 @@ public:
         VkSpecializationInfo* specializationInfos = nullptr;
     };
 
+#if defined(__clang__)
     #pragma clang diagnostic push
     #pragma clang diagnostic warning "-Wpadded"
+#endif
 
     // The RasterState POD contains standard graphics-related state like blending, culling, etc.
     // The following states are omitted because Filament never changes them:
@@ -212,7 +213,9 @@ private:
         bool operator()(const PipelineKey& k1, const PipelineKey& k2) const;
     };
 
+#if defined(__clang__)
     #pragma clang diagnostic pop
+#endif
 
     // CACHE ENTRY STRUCTS
     // -------------------

filament/backend/src/vulkan/VulkanReadPixels.cpp

@@ -19,8 +19,9 @@
 #include "DataReshaper.h"
 #include "VulkanCommands.h"
 #include "VulkanHandles.h"
-#include "VulkanImageUtility.h"
 #include "VulkanTexture.h"
+#include "vulkan/utils/Conversion.h"  // getComponentType()
+#include "vulkan/utils/Image.h"
 
 #include <utils/Log.h>
 
@@ -218,7 +219,7 @@ void VulkanReadPixels::run(fvkmemory::resource_ptr<VulkanRenderTarget> srcTarget
     };
     vkBeginCommandBuffer(cmdbuffer, &binfo);
 
-    imgutil::transitionLayout(cmdbuffer, {
+    fvkutils::transitionLayout(cmdbuffer, {
         .image = stagingImage,
         .oldLayout = VulkanLayout::UNDEFINED,
         .newLayout = VulkanLayout::TRANSFER_DST,
@@ -265,8 +266,8 @@ void VulkanReadPixels::run(fvkmemory::resource_ptr<VulkanRenderTarget> srcTarget
             imageCopyRegion.srcOffset.y + imageCopyRegion.extent.height <= srcExtent.height);
 
     vkCmdCopyImage(cmdbuffer, srcAttachment.getImage(),
-            imgutil::getVkLayout(VulkanLayout::TRANSFER_SRC), stagingImage,
-            imgutil::getVkLayout(VulkanLayout::TRANSFER_DST), 1, &imageCopyRegion);
+            fvkutils::getVkLayout(VulkanLayout::TRANSFER_SRC), stagingImage,
+            fvkutils::getVkLayout(VulkanLayout::TRANSFER_DST), 1, &imageCopyRegion);
 
     // Restore the source image layout.
     srcTexture->transitionLayout(cmdbuffer, srcRange, srcTexture->getDefaultLayout());
@@ -318,8 +319,8 @@ void VulkanReadPixels::run(fvkmemory::resource_ptr<VulkanRenderTarget> srcTarget
         vkMapMemory(device, stagingMemory, 0, VK_WHOLE_SIZE, 0, (void**) &srcPixels);
         srcPixels += subResourceLayout.offset;
 
-        if (!DataReshaper::reshapeImage(&p, getComponentType(srcFormat),
-                    getComponentCount(srcFormat), srcPixels,
+        if (!DataReshaper::reshapeImage(&p, fvkutils::getComponentType(srcFormat),
+                    fvkutils::getComponentCount(srcFormat), srcPixels,
                     static_cast<int>(subResourceLayout.rowPitch), static_cast<int>(width),
                     static_cast<int>(height), swizzle)) {
             FVK_LOGE << "Unsupported PixelDataFormat or PixelDataType" << utils::io::endl;

filament/backend/src/vulkan/VulkanSamplerCache.cpp

@@ -15,6 +15,7 @@
  */
 
 #include "vulkan/VulkanSamplerCache.h"
+#include "vulkan/utils/Conversion.h"
 
 #include <utils/Panic.h>
 
@@ -114,7 +115,7 @@ VkSampler VulkanSamplerCache::getSampler(SamplerParams params) noexcept {
         .anisotropyEnable = params.anisotropyLog2 == 0 ? 0u : 1u,
         .maxAnisotropy = (float)(1u << params.anisotropyLog2),
         .compareEnable = getCompareEnable(params.compareMode),
-        .compareOp = getCompareOp(params.compareFunc),
+        .compareOp = fvkutils::getCompareOp(params.compareFunc),
         .minLod = 0.0f,
         .maxLod = getMaxLod(params.filterMin),
         .borderColor = VK_BORDER_COLOR_INT_OPAQUE_BLACK,

filament/backend/src/vulkan/VulkanSamplerCache.h

@@ -18,7 +18,6 @@
 #define TNT_FILAMENT_BACKEND_VULKANSAMPLERCACHE_H
 
 #include "VulkanContext.h"
-#include "VulkanUtility.h"
 
 #include <tsl/robin_map.h>
 

filament/backend/src/vulkan/VulkanStagePool.cpp

@@ -18,9 +18,9 @@
 
 #include "VulkanCommands.h"
 #include "VulkanConstants.h"
-#include "VulkanImageUtility.h"
 #include "VulkanMemory.h"
-#include "VulkanUtility.h"
+#include "vulkan/utils/Conversion.h"
+#include "vulkan/utils/Image.h"
 
 #include <utils/Panic.h>
 
@@ -72,7 +72,7 @@ VulkanStage const* VulkanStagePool::acquireStage(uint32_t numBytes) {
 
 VulkanStageImage const* VulkanStagePool::acquireImage(PixelDataFormat format, PixelDataType type,
         uint32_t width, uint32_t height) {
-    const VkFormat vkformat = getVkFormat(format, type);
+    const VkFormat vkformat = fvkutils::getVkFormat(format, type);
     for (auto image : mFreeImages) {
         if (image->format == vkformat && image->width == width && image->height == height) {
             mFreeImages.erase(image);
@@ -113,7 +113,7 @@ VulkanStageImage const* VulkanStagePool::acquireImage(PixelDataFormat format, Pi
 
     assert_invariant(result == VK_SUCCESS);
 
-    VkImageAspectFlags const aspectFlags = getImageAspect(vkformat);
+    VkImageAspectFlags const aspectFlags = fvkutils::getImageAspect(vkformat);
     VkCommandBuffer const cmdbuffer = mCommands->get().buffer();
 
     // We use VK_IMAGE_LAYOUT_GENERAL here because the spec says:
@@ -122,7 +122,7 @@ VulkanStageImage const* VulkanStagePool::acquireImage(PixelDataFormat format, Pi
     // VK_IMAGE_LAYOUT_PREINITIALIZED or VK_IMAGE_LAYOUT_GENERAL layout. Calling
     // vkGetImageSubresourceLayout for a linear image returns a subresource layout mapping that is
     // valid for either of those image layouts."
-    imgutil::transitionLayout(cmdbuffer, {
+    fvkutils::transitionLayout(cmdbuffer, {
             .image = image->image,
             .oldLayout = VulkanLayout::UNDEFINED,
             .newLayout = VulkanLayout::READ_WRITE, // (= VK_IMAGE_LAYOUT_GENERAL)

filament/backend/src/vulkan/VulkanTexture.cpp

@@ -17,8 +17,8 @@
 #include "VulkanCommands.h"
 #include "VulkanMemory.h"
 #include "VulkanTexture.h"
-#include "VulkanUtility.h"
 #include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/Conversion.h"
 
 #include <DataReshaper.h>
 #include <backend/DriverEnums.h>
@@ -152,7 +152,7 @@ VulkanTextureState::VulkanTextureState(VkDevice device, VmaAllocator allocator,
         bool isProtected)
     : mVkFormat(format),
       mViewType(viewType),
-      mFullViewRange{filament::backend::getImageAspect(format), 0, levels, 0, layerCount},
+      mFullViewRange{fvkutils::getImageAspect(format), 0, levels, 0, layerCount},
       mDefaultLayout(defaultLayout),
       mIsProtected(isProtected),
       mStagePool(stagePool),
@@ -169,7 +169,7 @@ VulkanTexture::VulkanTexture(VkDevice device, VmaAllocator allocator,
     : HwTexture(SamplerType::SAMPLER_2D, 1, samples, width, height, 1, TextureFormat::UNUSED,
               tusage),
       mState(fvkmemory::resource_ptr<VulkanTextureState>::construct(resourceManager, device,
-              allocator, commands, stagePool, format, imgutil::getViewType(SamplerType::SAMPLER_2D),
+              allocator, commands, stagePool, format, fvkutils::getViewType(SamplerType::SAMPLER_2D),
               1, 1, getDefaultLayoutImpl(tusage), any(usage & TextureUsage::PROTECTED))) {
     mState->mTextureImage = image;
     mState->mTextureImageMemory = memory;
@@ -183,9 +183,10 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         uint8_t levels, TextureFormat tformat, uint8_t samples, uint32_t w, uint32_t h,
         uint32_t depth, TextureUsage tusage, VulkanStagePool& stagePool)
     : HwTexture(target, levels, samples, w, h, depth, tformat, tusage),
+
       mState(fvkmemory::resource_ptr<VulkanTextureState>::construct(resourceManager, device,
-              allocator, commands, stagePool, backend::getVkFormat(tformat),
-              imgutil::getViewType(target), levels, getLayerCount(target, depth),
+              allocator, commands, stagePool, fvkutils::getVkFormat(tformat),
+              fvkutils::getViewType(target), levels, getLayerCount(target, depth),
               VulkanLayout::UNDEFINED, any(usage & TextureUsage::PROTECTED))) {
     // Create an appropriately-sized device-only VkImage, but do not fill it yet.
     VkImageCreateInfo imageInfo{
@@ -281,22 +282,23 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
     // any kind of attachment (color or depth).
     const auto& limits = context.getPhysicalDeviceLimits();
     if (imageInfo.usage & VK_IMAGE_USAGE_SAMPLED_BIT) {
-        samples = reduceSampleCount(samples, isVkDepthFormat(mState->mVkFormat)
-                                                     ? limits.sampledImageDepthSampleCounts
-                                                     : limits.sampledImageColorSampleCounts);
+        samples = fvkutils::reduceSampleCount(samples,
+                fvkutils::isVkDepthFormat(mState->mVkFormat)
+                        ? limits.sampledImageDepthSampleCounts
+                        : limits.sampledImageColorSampleCounts);
     }
     if (imageInfo.usage & VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT) {
-        samples = reduceSampleCount(samples, limits.framebufferColorSampleCounts);
+        samples = fvkutils::reduceSampleCount(samples, limits.framebufferColorSampleCounts);
     }
 
     if (imageInfo.usage & VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) {
-        samples = reduceSampleCount(samples, limits.sampledImageDepthSampleCounts);
+        samples = fvkutils::reduceSampleCount(samples, limits.sampledImageDepthSampleCounts);
     }
     this->samples = samples;
     imageInfo.samples = (VkSampleCountFlagBits) samples;
 
     VkResult result = vkCreateImage(mState->mDevice, &imageInfo, VKALLOC, &mState->mTextureImage);
-    if (result == VK_SUCCESS || FVK_ENABLED(FVK_DEBUG_TEXTURE)) {
+    if (result != VK_SUCCESS || FVK_ENABLED(FVK_DEBUG_TEXTURE)) {
         FVK_LOGD << "vkCreateImage: "
             << "image = " << mState->mTextureImage << ", "
             << "result = " << result << ", "
@@ -401,8 +403,8 @@ void VulkanTexture::updateImage(const PixelBufferDescriptor& data, uint32_t widt
     }
 
     // If format conversion is both required and supported, use vkCmdBlitImage.
-    const VkFormat hostFormat = backend::getVkFormat(hostData->format, hostData->type);
-    const VkFormat deviceFormat = getVkFormatLinear(mState->mVkFormat);
+    const VkFormat hostFormat = fvkutils::getVkFormat(hostData->format, hostData->type);
+    const VkFormat deviceFormat = fvkutils::getVkFormatLinear(mState->mVkFormat);
     if (hostFormat != deviceFormat && hostFormat != VK_FORMAT_UNDEFINED) {
         assert_invariant(xoffset == 0 && yoffset == 0 && zoffset == 0 &&
                 "Offsets not yet supported when format conversion is required.");
@@ -461,7 +463,7 @@ void VulkanTexture::updateImage(const PixelBufferDescriptor& data, uint32_t widt
 
     VulkanLayout const newLayout = VulkanLayout::TRANSFER_DST;
     VulkanLayout nextLayout = getLayout(transitionRange.baseArrayLayer, miplevel);
-    VkImageLayout const newVkLayout = imgutil::getVkLayout(newLayout);
+    VkImageLayout const newVkLayout = fvkutils::getVkLayout(newLayout);
 
     if (nextLayout == VulkanLayout::UNDEFINED) {
         nextLayout = getDefaultLayout();
@@ -508,8 +510,8 @@ void VulkanTexture::updateImageWithBlit(const PixelBufferDescriptor& hostData, u
     VulkanLayout const oldLayout = getLayout(layer, miplevel);
     transitionLayout(&commands, range, newLayout);
 
-    vkCmdBlitImage(cmdbuf, stage->image, imgutil::getVkLayout(VulkanLayout::TRANSFER_SRC),
-            mState->mTextureImage, imgutil::getVkLayout(newLayout), 1, blitRegions, VK_FILTER_NEAREST);
+    vkCmdBlitImage(cmdbuf, stage->image, fvkutils::getVkLayout(VulkanLayout::TRANSFER_SRC),
+            mState->mTextureImage, fvkutils::getVkLayout(newLayout), 1, blitRegions, VK_FILTER_NEAREST);
 
     transitionLayout(&commands, range, oldLayout);
 }
@@ -557,7 +559,7 @@ VkImageView VulkanTexture::getImageView(VkImageSubresourceRange range, VkImageVi
 
 VkImageAspectFlags VulkanTexture::getImageAspect() const {
     // Helper function in VulkanUtility
-    return filament::backend::getImageAspect(mState->mVkFormat);
+    return fvkutils::getImageAspect(mState->mVkFormat);
 }
 
 bool VulkanTexture::transitionLayout(VulkanCommandBuffer* commands,
@@ -600,7 +602,7 @@ bool VulkanTexture::transitionLayout(VkCommandBuffer cmdbuf, VkImageSubresourceR
                 if (layout == newLayout) {
                     continue;
                 }
-                hasTransitions = hasTransitions || imgutil::transitionLayout(cmdbuf, {
+                hasTransitions = hasTransitions || fvkutils::transitionLayout(cmdbuf, {
                     .image = mState->mTextureImage,
                     .oldLayout = layout,
                     .newLayout = newLayout,
@@ -615,7 +617,7 @@ bool VulkanTexture::transitionLayout(VkCommandBuffer cmdbuf, VkImageSubresourceR
             }
         }
     } else if (newLayout != oldLayout) {
-        hasTransitions = imgutil::transitionLayout(cmdbuf, {
+        hasTransitions = fvkutils::transitionLayout(cmdbuf, {
             .image = mState->mTextureImage,
             .oldLayout = oldLayout,
             .newLayout = newLayout,
@@ -650,7 +652,7 @@ void VulkanTexture::samplerToAttachmentBarrier(VulkanCommandBuffer* commands,
         VkImageSubresourceRange const& range) {
     VkCommandBuffer const cmdbuf = commands->buffer();
     VkImageLayout const layout =
-            imgutil::getVkLayout(getLayout(range.baseArrayLayer, range.baseMipLevel));
+            fvkutils::getVkLayout(getLayout(range.baseArrayLayer, range.baseMipLevel));
     VkImageMemoryBarrier barrier = {
             .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
             .srcAccessMask = VK_ACCESS_SHADER_READ_BIT,
@@ -673,7 +675,7 @@ void VulkanTexture::attachmentToSamplerBarrier(VulkanCommandBuffer* commands,
         VkImageSubresourceRange const& range) {
     VkCommandBuffer const cmdbuf = commands->buffer();
     VkImageLayout const layout
-            = imgutil::getVkLayout(getLayout(range.baseArrayLayer, range.baseMipLevel));
+            = fvkutils::getVkLayout(getLayout(range.baseArrayLayer, range.baseMipLevel));
     VkImageMemoryBarrier barrier = {
             .sType = VK_STRUCTURE_TYPE_IMAGE_MEMORY_BARRIER,
             .srcAccessMask = VK_ACCESS_COLOR_ATTACHMENT_WRITE_BIT,

filament/backend/src/vulkan/VulkanTexture.h

@@ -20,9 +20,9 @@
 #include "DriverBase.h"
 
 #include "VulkanBuffer.h"
-#include "VulkanImageUtility.h"
 #include "vulkan/memory/Resource.h"
 #include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/Image.h"
 
 #include <utils/Hash.h>
 #include <utils/RangeMap.h>

filament/backend/src/vulkan/caching/VulkanDescriptorSetManager.cpp

@@ -16,11 +16,10 @@
 
 #include "VulkanDescriptorSetManager.h"
 
-#include <vulkan/VulkanCommands.h>
-#include <vulkan/VulkanHandles.h>
-#include <vulkan/VulkanUtility.h>
-#include <vulkan/VulkanConstants.h>
-#include <vulkan/VulkanImageUtility.h>
+#include "vulkan/VulkanCommands.h"
+#include "vulkan/VulkanHandles.h"
+#include "vulkan/VulkanConstants.h"
+
 #include <utils/FixedCapacityVector.h>
 #include <utils/Panic.h>
 
@@ -207,17 +206,17 @@ uint32_t createBindings(VkDescriptorSetLayoutBinding* toBind, uint32_t count, Vk
     mask.forEachSetBit([&](size_t index) {
         VkShaderStageFlags stages = 0;
         uint32_t binding = 0;
-        if (index < getFragmentStageShift<Bitmask>()) {
+        if (index < fvkutils::getFragmentStageShift<Bitmask>()) {
             binding = (uint32_t) index;
             stages |= VK_SHADER_STAGE_VERTEX_BIT;
-            auto fragIndex = index + getFragmentStageShift<Bitmask>();
+            auto fragIndex = index + fvkutils::getFragmentStageShift<Bitmask>();
             if (mask.test(fragIndex)) {
                 stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
                 alreadySeen.set(fragIndex);
             }
         } else if (!alreadySeen.test(index)) {
             // We are in fragment stage bits
-            binding = (uint32_t) (index - getFragmentStageShift<Bitmask>());
+            binding = (uint32_t) (index - fvkutils::getFragmentStageShift<Bitmask>());
             stages |= VK_SHADER_STAGE_FRAGMENT_BIT;
         }
 
@@ -346,7 +345,6 @@ private:
             mVkLayouts;
 };
 
-
 VulkanDescriptorSetManager::VulkanDescriptorSetManager(VkDevice device,
         fvkmemory::ResourceManager* resourceManager)
     : mDevice(device),
@@ -376,10 +374,10 @@ void VulkanDescriptorSetManager::unbind(uint8_t setIndex) {
 }
 
 void VulkanDescriptorSetManager::commit(VulkanCommandBuffer* commands,
-        VkPipelineLayout pipelineLayout, DescriptorSetMask const& setMask) {
+        VkPipelineLayout pipelineLayout, fvkutils::DescriptorSetMask const& setMask) {
     // setMask indicates the set of descriptor sets the driver wants to bind, curMask is the
     // actual set of sets that *needs* to be bound.
-    DescriptorSetMask curMask = setMask;
+    fvkutils::DescriptorSetMask curMask = setMask;
 
     auto& updateSets = mStashedSets;
     auto& lastBoundSets = mLastBoundInfo.boundSets;
@@ -458,7 +456,7 @@ void VulkanDescriptorSetManager::updateSampler(fvkmemory::resource_ptr<VulkanDes
     } else {
         info.imageView = texture->getViewForType(range, expectedType);
     }
-    info.imageLayout = imgutil::getVkLayout(texture->getDefaultLayout());
+    info.imageLayout = fvkutils::getVkLayout(texture->getDefaultLayout());
     VkWriteDescriptorSet const descriptorWrite = {
         .sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET,
         .pNext = nullptr,

filament/backend/src/vulkan/caching/VulkanDescriptorSetManager.h

@@ -18,9 +18,8 @@
 #define TNT_FILAMENT_BACKEND_CACHING_VULKANDESCRIPTORSETMANAGER_H
 
 #include "vulkan/VulkanHandles.h"
-#include "vulkan/VulkanTexture.h"
-#include "vulkan/VulkanUtility.h"
 #include "vulkan/memory/ResourcePointer.h"
+#include "vulkan/utils/Definitions.h"  // For DescriptorSetMask
 
 #include <backend/DriverEnums.h>
 #include <backend/Program.h>
@@ -68,7 +67,7 @@ public:
     void unbind(uint8_t setIndex);
 
     void commit(VulkanCommandBuffer* commands, VkPipelineLayout pipelineLayout,
-            DescriptorSetMask const& setMask);
+            fvkutils::DescriptorSetMask const& setMask);
 
     fvkmemory::resource_ptr<VulkanDescriptorSet> createSet(Handle<HwDescriptorSet> handle,
             fvkmemory::resource_ptr<VulkanDescriptorSetLayout> layout);
@@ -93,7 +92,7 @@ private:
 
     struct {
         VkPipelineLayout pipelineLayout = VK_NULL_HANDLE;
-        DescriptorSetMask setMask;
+        fvkutils::DescriptorSetMask setMask;
         DescriptorSetArray boundSets = {};
     } mLastBoundInfo;
 };

filament/backend/src/vulkan/memory/ResourcePointer.h

@@ -81,7 +81,7 @@ public:
     inline resource_ptr() = default;
 
     // move constructor operator
-    inline resource_ptr(resource_ptr<D>&& rhs) {
+    inline resource_ptr(resource_ptr<D>&& rhs) noexcept {
         (*this) = std::move(rhs);
     }
 
@@ -98,7 +98,7 @@ public:
     }
 
     // move operator
-    inline resource_ptr<D>& operator=(resource_ptr<D> && rhs) {
+    inline resource_ptr<D>& operator=(resource_ptr<D> && rhs) noexcept {
         std::swap(mRef, rhs.mRef);
         return *this;
     }

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

@@ -21,7 +21,7 @@
 #include "vulkan/platform/VulkanPlatformSwapChainImpl.h"
 #include "vulkan/VulkanConstants.h"
 #include "vulkan/VulkanDriver.h"
-#include "vulkan/VulkanUtility.h"
+#include "vulkan/utils/Helper.h"
 
 #include <bluevk/BlueVK.h>
 #include <utils/PrivateImplementation-impl.h>
@@ -126,7 +126,7 @@ void printDeviceInfo(VkInstance instance, VkPhysicalDevice device) {
     const int minor = VK_VERSION_MINOR(deviceProperties.apiVersion);
 
     const FixedCapacityVector<VkPhysicalDevice> physicalDevices
-            = filament::backend::enumerate(vkEnumeratePhysicalDevices, instance);
+            = fvkutils::enumerate(vkEnumeratePhysicalDevices, instance);
 
     FVK_LOGI << "Selected physical device '" << deviceProperties.deviceName << "' from "
                   << physicalDevices.size() << " physical devices. "
@@ -172,7 +172,7 @@ ExtensionSet getInstanceExtensions(ExtensionSet const& externallyRequiredExts =
     };
     ExtensionSet exts;
     FixedCapacityVector<VkExtensionProperties> const availableExts =
-            filament::backend::enumerate(vkEnumerateInstanceExtensionProperties,
+            fvkutils::enumerate(vkEnumerateInstanceExtensionProperties,
                     static_cast<char const*>(nullptr) /* pLayerName */);
     for (auto const& extProps: availableExts) {
         utils::CString name { extProps.extensionName };
@@ -212,7 +212,7 @@ ExtensionSet getDeviceExtensions(VkPhysicalDevice device) {
     ExtensionSet exts;
     // Identify supported physical device extensions
     FixedCapacityVector<VkExtensionProperties> const extensions
-            = filament::backend::enumerate(vkEnumerateDeviceExtensionProperties, device,
+            = fvkutils::enumerate(vkEnumerateDeviceExtensionProperties, device,
                     static_cast<const char*>(nullptr) /* pLayerName */);
     for (auto const& extension: extensions) {
         utils::CString name { extension.extensionName };
@@ -473,7 +473,7 @@ inline int deviceTypeOrder(VkPhysicalDeviceType deviceType) {
 VkPhysicalDevice selectPhysicalDevice(VkInstance instance,
         VulkanPlatform::Customization::GPUPreference const& gpuPreference) {
     FixedCapacityVector<VkPhysicalDevice> const physicalDevices =
-            filament::backend::enumerate(vkEnumeratePhysicalDevices, instance);
+            fvkutils::enumerate(vkEnumeratePhysicalDevices, instance);
     struct DeviceInfo {
         VkPhysicalDevice device = VK_NULL_HANDLE;
         VkPhysicalDeviceType deviceType = VK_PHYSICAL_DEVICE_TYPE_OTHER;
@@ -508,7 +508,7 @@ VkPhysicalDevice selectPhysicalDevice(VkInstance instance,
 
         // Does the device support the VK_KHR_swapchain extension?
         FixedCapacityVector<VkExtensionProperties> const extensions
-                = filament::backend::enumerate(vkEnumerateDeviceExtensionProperties,
+                = fvkutils::enumerate(vkEnumerateDeviceExtensionProperties,
                         candidateDevice, static_cast<char const*>(nullptr) /* pLayerName */);
         bool supportsSwapchain = false;
         for (auto const& extension: extensions) {
@@ -560,7 +560,7 @@ VkPhysicalDevice selectPhysicalDevice(VkInstance instance,
     return device;
 }
 
-VkFormatList findAttachmentDepthStencilFormats(VkPhysicalDevice device) {
+fvkutils::VkFormatList findAttachmentDepthStencilFormats(VkPhysicalDevice device) {
     VkFormatFeatureFlags const features = VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT;
 
     // The ordering here indicates the preference of choosing depth+stencil format.
@@ -579,17 +579,17 @@ VkFormatList findAttachmentDepthStencilFormats(VkPhysicalDevice device) {
             selectedFormats.push_back(format);
         }
     }
-    VkFormatList ret(selectedFormats.size());
+    fvkutils::VkFormatList ret(selectedFormats.size());
     std::copy(selectedFormats.begin(), selectedFormats.end(), ret.begin());
     return ret;
 }
 
-VkFormatList findBlittableDepthStencilFormats(VkPhysicalDevice device) {
+fvkutils::VkFormatList findBlittableDepthStencilFormats(VkPhysicalDevice device) {
     std::vector<VkFormat> selectedFormats;
     VkFormatFeatureFlags const required = VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT |
             VK_FORMAT_FEATURE_BLIT_SRC_BIT | VK_FORMAT_FEATURE_BLIT_DST_BIT;
-    for (VkFormat format : ALL_VK_FORMATS) {
-        if (isVkDepthFormat(format)) {
+    for (VkFormat format : fvkutils::ALL_VK_FORMATS) {
+        if (fvkutils::isVkDepthFormat(format)) {
             VkFormatProperties props;
             vkGetPhysicalDeviceFormatProperties(device, format, &props);
             if ((props.optimalTilingFeatures & required) == required) {
@@ -597,7 +597,7 @@ VkFormatList findBlittableDepthStencilFormats(VkPhysicalDevice device) {
             }
         }
     }
-    VkFormatList ret(selectedFormats.size());
+    fvkutils::VkFormatList ret(selectedFormats.size());
     std::copy(selectedFormats.begin(), selectedFormats.end(), ret.begin());
     return ret;
 }

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

@@ -199,7 +199,6 @@ VulkanPlatform::ExternalImageMetadata VulkanPlatform::getExternalImageMetadataIm
     FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
             << "vkGetAndroidHardwareBufferProperties failed with error="
             << static_cast<int32_t>(result);
-
     FILAMENT_CHECK_POSTCONDITION(metadata.format == formatInfo.format)
             << "mismatched image format for external image (AHB)";
     metadata.externalFormat = formatInfo.externalFormat;

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

@@ -17,7 +17,9 @@
 #include "VulkanPlatformSwapChainImpl.h"
 
 #include "vulkan/VulkanConstants.h"
-#include "vulkan/VulkanUtility.h"
+#include "vulkan/utils/Definitions.h"
+#include "vulkan/utils/Helper.h"
+#include "vulkan/utils/Image.h"
 
 #include <backend/DriverEnums.h>
 
@@ -29,9 +31,8 @@ namespace filament::backend {
 namespace {
 
 std::tuple<VkImage, VkDeviceMemory> createImageAndMemory(VulkanContext const& context,
-        VkDevice device, VkExtent2D extent, VkFormat format,
-        bool isProtected) {
-    bool const isDepth = isVkDepthFormat(format);
+        VkDevice device, VkExtent2D extent, VkFormat format, bool isProtected) {
+    bool const isDepth = fvkutils::isVkDepthFormat(format);
     // Filament expects blit() to work with any texture, so we almost always set these usage flags
     // (see copyFrame() and readPixels()).
     VkImageUsageFlags const blittable =
@@ -83,9 +84,9 @@ std::tuple<VkImage, VkDeviceMemory> createImageAndMemory(VulkanContext const& co
     return std::tuple(image, imageMemory);
 }
 
-VkFormat selectDepthFormat(VkFormatList const& depthFormats, bool hasStencil) {
+VkFormat selectDepthFormat(fvkutils::VkFormatList const& depthFormats, bool hasStencil) {
     auto const formatItr = std::find_if(depthFormats.begin(), depthFormats.end(),
-            hasStencil ? isVkStencilFormat : isVkDepthFormat);
+            hasStencil ? fvkutils::isVkStencilFormat : fvkutils::isVkDepthFormat);
     assert_invariant(
             formatItr != depthFormats.end() && "Cannot find suitable swapchain depth format");
     return *formatItr;
@@ -117,7 +118,7 @@ void VulkanPlatformSwapChainImpl::destroy() {
     mSwapChainBundle.colors.clear();
 }
 
-VkImage VulkanPlatformSwapChainImpl::createImage(VkExtent2D extent, VkFormat format, 
+VkImage VulkanPlatformSwapChainImpl::createImage(VkExtent2D extent, VkFormat format,
         bool isProtected) {
     auto [image, memory] = createImageAndMemory(mContext, mDevice, extent, format, isProtected);
     mMemory.insert({image, memory});
@@ -140,9 +141,8 @@ VulkanPlatformSurfaceSwapChain::VulkanPlatformSurfaceSwapChain(VulkanContext con
 }
 
 VulkanPlatformSurfaceSwapChain::~VulkanPlatformSurfaceSwapChain() {
-    vkDestroySwapchainKHR(mDevice, mSwapchain, VKALLOC);
-    vkDestroySurfaceKHR(mInstance, mSurface, VKALLOC);
     destroy();
+    vkDestroySurfaceKHR(mInstance, mSurface, VKALLOC);
 }
 
 VkResult VulkanPlatformSurfaceSwapChain::create() {
@@ -170,7 +170,7 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
 
     // Find a suitable surface format.
     FixedCapacityVector<VkSurfaceFormatKHR> const surfaceFormats
-            = enumerate(vkGetPhysicalDeviceSurfaceFormatsKHR, mPhysicalDevice, mSurface);
+            = fvkutils::enumerate(vkGetPhysicalDeviceSurfaceFormatsKHR, mPhysicalDevice, mSurface);
     std::array<VkFormat, 2> expectedFormats = {
             VK_FORMAT_R8G8B8A8_UNORM,
             VK_FORMAT_B8G8R8A8_UNORM,
@@ -194,8 +194,8 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
     // Verify that our chosen present mode is supported. In practice all devices support the FIFO
     // mode, but we check for it anyway for completeness.  (and to avoid validation warnings)
     VkPresentModeKHR const desiredPresentMode = VK_PRESENT_MODE_FIFO_KHR;
-    FixedCapacityVector<VkPresentModeKHR> presentModes
-            = enumerate(vkGetPhysicalDeviceSurfacePresentModesKHR, mPhysicalDevice, mSurface);
+    FixedCapacityVector<VkPresentModeKHR> presentModes = fvkutils::enumerate(
+            vkGetPhysicalDeviceSurfacePresentModesKHR, mPhysicalDevice, mSurface);
     bool foundSuitablePresentMode = false;
     for (VkPresentModeKHR mode: presentModes) {
         if (mode == desiredPresentMode) {
@@ -252,11 +252,11 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
     FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateSwapchainKHR failed."
                                                        << " error=" << static_cast<int32_t>(result);
 
-    mSwapChainBundle.colors = enumerate(vkGetSwapchainImagesKHR, mDevice, mSwapchain);
+    mSwapChainBundle.colors = fvkutils::enumerate(vkGetSwapchainImagesKHR, mDevice, mSwapchain);
     mSwapChainBundle.colorFormat = surfaceFormat.format;
     mSwapChainBundle.depthFormat =
             selectDepthFormat(mContext.getAttachmentDepthStencilFormats(), mHasStencil);
-    mSwapChainBundle.depth = createImage(mSwapChainBundle.extent, 
+    mSwapChainBundle.depth = createImage(mSwapChainBundle.extent,
             mSwapChainBundle.depthFormat, mIsProtected);
     mSwapChainBundle.isProtected = mIsProtected;
 
@@ -330,7 +330,7 @@ bool VulkanPlatformSurfaceSwapChain::hasResized() {
             || perceivedExtent.height == VULKAN_UNDEFINED_EXTENT) {
         perceivedExtent = mFallbackExtent;
     }
-    return !equivalent(mSwapChainBundle.extent, perceivedExtent);
+    return !fvkutils::equivalent(mSwapChainBundle.extent, perceivedExtent);
 }
 
 bool VulkanPlatformSurfaceSwapChain::isProtected() {
@@ -344,6 +344,22 @@ VkResult VulkanPlatformSurfaceSwapChain::recreate() {
 }
 
 void VulkanPlatformSurfaceSwapChain::destroy() {
+    // The next part is not ideal. We don't have a good signal on when it's ok to destroy
+    // a swapchain. This is a spec oversight and mentioned as much:
+    // https://github.com/KhronosGroup/Vulkan-Docs/issues/1678
+    //
+    // One workaround [1] is:
+    // https://docs.vulkan.org/samples/latest/samples/api/swapchain_recreation/README.html
+    //
+    // The proper fix is to use VK_EXT_swapchain_maintenance1, but availability of this extension is
+    // unknown (not yet ratified).
+    //
+    // Instead of adding too much mechanics, we're taking a hacksaw to the problem - just wait for
+    // the queue to be idle. The hope is that this only happens on resize, where performance
+    // degradation is less obvious (until, of course, people complain about lag when rotating their
+    // phone). If necessary, we can revisit and implement the workaround [1].
+    vkQueueWaitIdle(mQueue);
+
     VulkanPlatformSwapChainImpl::destroy();
 
     for (uint32_t i = 0; i < IMAGE_READY_SEMAPHORE_COUNT; ++i) {
@@ -352,6 +368,10 @@ void VulkanPlatformSurfaceSwapChain::destroy() {
             mImageReady[i] = VK_NULL_HANDLE;
         }
     }
+    if (mSwapchain) {
+        vkDestroySwapchainKHR(mDevice, mSwapchain, VKALLOC);
+        mSwapchain = VK_NULL_HANDLE;
+    }
 }
 
 VulkanPlatformHeadlessSwapChain::VulkanPlatformHeadlessSwapChain(VulkanContext const& context,

filament/backend/src/vulkan/utils/Conversion.cpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2019 The Android Open Source Project
+ * 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.
@@ -14,17 +14,13 @@
  * limitations under the License.
  */
 
-#include "VulkanUtility.h"
+#include "vulkan/utils/Conversion.h"
 
-#include <utils/algorithm.h>
-#include <utils/debug.h>
 #include <utils/Panic.h>
 
 #include "private/backend/BackendUtils.h"
 
-using namespace bluevk;
-
-namespace filament::backend {
+namespace filament::backend::fvkutils {
 
 VkFormat getVkFormat(ElementType type, bool normalized, bool integer) {
     using ElementType = ElementType;
@@ -235,12 +231,6 @@ VkFormat getVkFormat(TextureFormat format) {
     }
 }
 
-// Converts PixelBufferDescriptor format + type pair into a VkFormat.
-//
-// NOTE: This function only returns formats that support VK_FORMAT_FEATURE_BLIT_SRC_BIT as per
-// "Required Format Support" in the Vulkan specification. These are the only formats that can be
-// used for format conversion. If the requested format does not support this feature, then
-// VK_FORMAT_UNDEFINED is returned.
 VkFormat getVkFormat(PixelDataFormat format, PixelDataType type) {
     if (type == PixelDataType::USHORT_565) return VK_FORMAT_R5G6B5_UNORM_PACK16;
     if (type == PixelDataType::UINT_2_10_10_10_REV) return VK_FORMAT_A2B10G10R10_UNORM_PACK32;
@@ -284,10 +274,6 @@ VkFormat getVkFormat(PixelDataFormat format, PixelDataType type) {
     return VK_FORMAT_UNDEFINED;
 }
 
-// Converts an SRGB Vulkan format identifier into its corresponding canonical UNORM format. If the
-// given format is not an SRGB format, it is returned unmodified. This function is useful when
-// determining if blit-based conversion is needed, since SRGB is orthogonal to the actual bit layout
-// of color components.
 VkFormat getVkFormatLinear(VkFormat format) {
     switch (format) {
         case VK_FORMAT_R8_SRGB: return VK_FORMAT_R8_UNORM;
@@ -328,8 +314,6 @@ VkFormat getVkFormatLinear(VkFormat format) {
     return format;
 }
 
-// See also FTexture::computeTextureDataSize, which takes a public-facing Texture format rather
-// than a driver-level Texture format, and can account for a specified byte alignment.
 uint32_t getBytesPerPixel(TextureFormat format) {
     return (uint32_t) getFormatSize(format);
 }
@@ -611,48 +595,4 @@ VkShaderStageFlags getShaderStageFlags(ShaderStageFlags stageFlags) {
     return flags;
 }
 
-bool equivalent(const VkRect2D& a, const VkRect2D& b) {
-    // These are all integers so there's no need for an epsilon.
-    return a.extent.width == b.extent.width && a.extent.height == b.extent.height &&
-            a.offset.x == b.offset.x && a.offset.y == b.offset.y;
-}
-
-bool equivalent(const VkExtent2D& a, const VkExtent2D& b) {
-    return a.height == b.height && a.width == b.width;
-}
-
-VkImageAspectFlags getImageAspect(VkFormat format) {
-    switch (format) {
-        case VK_FORMAT_D16_UNORM_S8_UINT:
-        case VK_FORMAT_D24_UNORM_S8_UINT:
-        case VK_FORMAT_D32_SFLOAT_S8_UINT:
-            return VK_IMAGE_ASPECT_DEPTH_BIT | VK_IMAGE_ASPECT_STENCIL_BIT;
-        case VK_FORMAT_D16_UNORM:
-        case VK_FORMAT_X8_D24_UNORM_PACK32:
-        case VK_FORMAT_D32_SFLOAT:
-            return VK_IMAGE_ASPECT_DEPTH_BIT;
-        case VK_FORMAT_S8_UINT:
-            return VK_IMAGE_ASPECT_STENCIL_BIT;
-        default:
-            return VK_IMAGE_ASPECT_COLOR_BIT;
-    }
-}
-
-bool isVkDepthFormat(VkFormat format) {
-    return (getImageAspect(format) & VK_IMAGE_ASPECT_DEPTH_BIT) != 0;
-}
-
-bool isVkStencilFormat(VkFormat format) {
-    return (getImageAspect(format) & VK_IMAGE_ASPECT_STENCIL_BIT) != 0;
-}
-
-static uint32_t mostSignificantBit(uint32_t x) { return 1ul << (31ul - utils::clz(x)); }
-
-uint8_t reduceSampleCount(uint8_t sampleCount, VkSampleCountFlags mask) {
-    if (sampleCount & mask) {
-        return sampleCount;
-    }
-    return mostSignificantBit((sampleCount - 1) & mask);
-}
-
-} // namespace filament::backend
+} // namespace filament::backend::fvkutils

filament/backend/src/vulkan/utils/Conversion.h

@@ -0,0 +1,76 @@
+/*
+ * 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_VULKAN_UTILS_CONVERSION_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_CONVERSION_H
+
+#include <backend/DriverEnums.h>
+
+#include <private/backend/BackendUtils.h>  // for getFormatSize()
+
+#include <bluevk/BlueVK.h>
+
+// Methods for converting Filament types to Vulkan types
+
+namespace filament::backend::fvkutils {
+
+VkFormat getVkFormat(ElementType type, bool normalized, bool integer);
+VkFormat getVkFormat(TextureFormat format);
+
+// Converts PixelBufferDescriptor format + type pair into a VkFormat.
+// NOTE: This function only returns formats that support VK_FORMAT_FEATURE_BLIT_SRC_BIT as per
+// "Required Format Support" in the Vulkan specification. These are the only formats that can be
+// used for format conversion. If the requested format does not support this feature, then
+// VK_FORMAT_UNDEFINED is returned.
+VkFormat getVkFormat(PixelDataFormat format, PixelDataType type);
+
+// Converts an SRGB Vulkan format identifier into its corresponding canonical UNORM format. If the
+// given format is not an SRGB format, it is returned unmodified. This function is useful when
+// determining if blit-based conversion is needed, since SRGB is orthogonal to the actual bit layout
+// of color components.
+VkFormat getVkFormatLinear(VkFormat format);
+
+// See also FTexture::computeTextureDataSize, which takes a public-facing Texture format rather
+// than a driver-level Texture format, and can account for a specified byte alignment.
+uint32_t getBytesPerPixel(TextureFormat format);
+
+VkCompareOp getCompareOp(SamplerCompareFunc func);
+VkBlendFactor getBlendFactor(BlendFunction mode);
+VkCullModeFlags getCullMode(CullingMode mode);
+VkFrontFace getFrontFace(bool inverseFrontFaces);
+PixelDataType getComponentType(VkFormat format);
+uint32_t getComponentCount(VkFormat format);
+VkComponentMapping getSwizzleMap(TextureSwizzle const swizzle[4]);
+VkShaderStageFlags getShaderStageFlags(ShaderStageFlags stageFlags);
+
+inline VkImageViewType getViewType(SamplerType target) {
+    switch (target) {
+        case SamplerType::SAMPLER_CUBEMAP:
+            return VK_IMAGE_VIEW_TYPE_CUBE;
+        case SamplerType::SAMPLER_2D_ARRAY:
+            return VK_IMAGE_VIEW_TYPE_2D_ARRAY;
+        case SamplerType::SAMPLER_CUBEMAP_ARRAY:
+            return VK_IMAGE_VIEW_TYPE_CUBE_ARRAY;
+        case SamplerType::SAMPLER_3D:
+            return VK_IMAGE_VIEW_TYPE_3D;
+        default:
+            return VK_IMAGE_VIEW_TYPE_2D;
+    }
+}
+
+}// namespace filament::backend::fvkutils
+
+#endif// TNT_FILAMENT_BACKEND_VULKAN_UTILS_CONVERSION_H

filament/backend/src/vulkan/utils/Definitions.h

@@ -1,7 +1,7 @@
 /*
- * Copyright (C) 2019 The Android Open Source Project
+ * Copyright (C) 2024 The Android Open Source Project
  *
-* Licensed under the Apache License, Version 2.0 (the "License");
+ * 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
  *
@@ -14,82 +14,17 @@
  * limitations under the License.
  */
 
-#ifndef TNT_FILAMENT_BACKEND_VULKANUTILITY_H
-#define TNT_FILAMENT_BACKEND_VULKANUTILITY_H
-
-#include <backend/DriverEnums.h>
+#ifndef TNT_FILAMENT_BACKEND_VULKAN_UTILS_DEFINITIONS_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_DEFINITIONS_H
 
 #include <utils/bitset.h>
 #include <utils/FixedCapacityVector.h>
 
 #include <bluevk/BlueVK.h>
 
-#include <utility>
+// Definitions for common types used across classes.
 
-namespace filament::backend {
-
-VkFormat getVkFormat(ElementType type, bool normalized, bool integer);
-VkFormat getVkFormat(TextureFormat format);
-VkFormat getVkFormat(PixelDataFormat format, PixelDataType type);
-VkFormat getVkFormatLinear(VkFormat format);
-uint32_t getBytesPerPixel(TextureFormat format);
-VkCompareOp getCompareOp(SamplerCompareFunc func);
-VkBlendFactor getBlendFactor(BlendFunction mode);
-VkCullModeFlags getCullMode(CullingMode mode);
-VkFrontFace getFrontFace(bool inverseFrontFaces);
-PixelDataType getComponentType(VkFormat format);
-uint32_t getComponentCount(VkFormat format);
-VkComponentMapping getSwizzleMap(TextureSwizzle const swizzle[4]);
-VkShaderStageFlags getShaderStageFlags(ShaderStageFlags stageFlags);
-
-bool equivalent(const VkRect2D& a, const VkRect2D& b);
-bool equivalent(const VkExtent2D& a, const VkExtent2D& b);
-bool isVkDepthFormat(VkFormat format);
-bool isVkStencilFormat(VkFormat format);
-
-VkImageAspectFlags getImageAspect(VkFormat format);
-uint8_t reduceSampleCount(uint8_t sampleCount, VkSampleCountFlags mask);
-
-// Helper function for the vkEnumerateX methods. These methods have the format of
-// VkResult vkEnumerateX(InputType1 arg1, InputTyp2 arg2, ..., uint32_t* size,
-//         OutputType* output_arg)
-// Instead of macros and explicitly listing the template params, Variadic Template was also
-// considered, but because the "variadic" part of the vk methods (i.e. the inputs) are before the
-// non-variadic parts, this breaks the template type matching logic. Hence, we use a macro approach
-// here.
-#define EXPAND_ENUM(...)                                                          \
-    uint32_t size = 0;                                                            \
-    VkResult result = func(__VA_ARGS__, nullptr);                                 \
-    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "enumerate size error"; \
-    utils::FixedCapacityVector<OutType> ret(size);                                \
-    result = func(__VA_ARGS__, ret.data());                                       \
-    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "enumerate error";      \
-    return std::move(ret);
-
-#define EXPAND_ENUM_NO_ARGS() EXPAND_ENUM(&size)
-#define EXPAND_ENUM_ARGS(...) EXPAND_ENUM(__VA_ARGS__, &size)
-
-template <typename OutType>
-utils::FixedCapacityVector<OutType> enumerate(VKAPI_ATTR VkResult (*func)(uint32_t*, OutType*)) {
-    EXPAND_ENUM_NO_ARGS();
-}
-
-template <typename InType, typename OutType>
-utils::FixedCapacityVector<OutType> enumerate(
-        VKAPI_ATTR VkResult (*func)(InType, uint32_t*, OutType*), InType inData) {
-    EXPAND_ENUM_ARGS(inData);
-}
-
-template <typename InTypeA, typename InTypeB, typename OutType>
-utils::FixedCapacityVector<OutType> enumerate(
-        VKAPI_ATTR VkResult (*func)(InTypeA, InTypeB, uint32_t*, OutType*), InTypeA inDataA,
-        InTypeB inDataB) {
-    EXPAND_ENUM_ARGS(inDataA, inDataB);
-}
-
-#undef EXPAND_ENUM
-#undef EXPAND_ENUM_NO_ARGS
-#undef EXPAND_ENUM_ARGS
+namespace filament::backend::fvkutils {
 
 // Useful shorthands
 using VkFormatList = utils::FixedCapacityVector<VkFormat>;
@@ -406,128 +341,6 @@ constexpr VkFormat ALL_VK_FORMATS[] = {
         VK_FORMAT_R16G16_S10_5_NV,
 };
 
-// An Array that will be statically fixed in capacity, but the "size" (as in user added elements) is
-// variable. Note that this class is movable.
-template<typename T, uint16_t CAPACITY>
-class CappedArray {
-private:
-    using FixedSizeArray = std::array<T, CAPACITY>;
-
-public:
-    using const_iterator = typename FixedSizeArray::const_iterator;
-    using iterator = typename FixedSizeArray::iterator;
-
-    CappedArray() = default;
-
-    // Delete copy constructor/assignment.
-    CappedArray(CappedArray const& rhs) = delete;
-    CappedArray& operator=(CappedArray& rhs) = delete;
-
-    CappedArray(CappedArray&& rhs) noexcept {
-        this->swap(rhs);
-    }
-
-    CappedArray& operator=(CappedArray&& rhs) noexcept {
-        this->swap(rhs);
-        return *this;
-    }
-
-    inline ~CappedArray() {
-        clear();
-    }
-
-    inline const_iterator begin() const {
-        if (mInd == 0) {
-            return mArray.cend();
-        }
-        return mArray.cbegin();
-    }
-
-    inline const_iterator end() const {
-        if (mInd > 0 && mInd < CAPACITY) {
-            return mArray.begin() + mInd;
-        }
-        return mArray.cend();
-    }
-
-    inline iterator begin() {
-        if (mInd == 0) {
-            return mArray.end();
-        }
-        return mArray.begin();
-    }
-
-    inline iterator end() {
-        if (mInd > 0 && mInd < CAPACITY) {
-            return mArray.begin() + mInd;
-        }
-        return mArray.end();
-    }
-
-    inline T back() {
-        assert_invariant(mInd > 0);
-        return *(mArray.begin() + mInd);
-    }
-
-    inline void pop_back() {
-        assert_invariant(mInd > 0);
-        mInd--;
-    }
-
-    inline const_iterator find(T item) {
-        return std::find(begin(), end(), item);
-    }
-
-    inline void insert(T item) {
-        assert_invariant(mInd < CAPACITY);
-        mArray[mInd++] = item;
-    }
-
-    inline void erase(T item) {
-        PANIC_PRECONDITION("CappedArray::erase should not be called");
-    }
-
-    inline void clear() {
-        if (mInd == 0) {
-            return;
-        }
-        mInd = 0;
-    }
-
-    inline T& operator[](uint16_t ind) {
-        return mArray[ind];
-    }
-
-    inline T const& operator[](uint16_t ind) const {
-        return mArray[ind];
-    }
-
-    inline uint32_t size() const {
-        return mInd;
-    }
-
-    T* data() {
-        return mArray.data();
-    }
-
-    T const* data() const {
-        return mArray.data();
-    }
-
-    bool operator==(CappedArray const& b) const {
-        return this->mArray == b.mArray;
-    }
-
-private:
-    void swap(CappedArray& rhs) {
-        std::swap(mArray, rhs.mArray);
-        std::swap(mInd, rhs.mInd);
-    }
-
-    FixedSizeArray mArray;
-    uint32_t mInd = 0;
-};
-
 using UniformBufferBitmask = utils::bitset64;
 using SamplerBitmask = utils::bitset64;
 
@@ -550,7 +363,6 @@ static constexpr uint8_t getFragmentStageShift() noexcept {
 // We have at most 4 descriptor sets. This is to indicate which ones are active.
 using DescriptorSetMask = utils::bitset8;
 
+} // namespace filament::backend::fvkutils
 
-} // namespace filament::backend
-
-#endif // TNT_FILAMENT_BACKEND_VULKANUTILITY_H
+#endif // TNT_FILAMENT_BACKEND_VULKAN_UTILS_DEFINITIONS_H

filament/backend/src/vulkan/utils/Helper.h

@@ -0,0 +1,84 @@
+/*
+ * 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_VULKAN_UTILS_HELPER_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_HELPER_H
+
+#include <backend/DriverEnums.h>
+
+#include <utils/bitset.h>
+#include <utils/FixedCapacityVector.h>
+
+#include <bluevk/BlueVK.h>
+
+#include <utility>
+
+namespace filament::backend::fvkutils {
+
+inline bool equivalent(const VkRect2D& a, const VkRect2D& b) {
+    // These are all integers so there's no need for an epsilon.
+    return a.extent.width == b.extent.width && a.extent.height == b.extent.height &&
+           a.offset.x == b.offset.x && a.offset.y == b.offset.y;
+}
+
+inline bool equivalent(const VkExtent2D& a, const VkExtent2D& b) {
+    return a.height == b.height && a.width == b.width;
+}
+
+// Helper function for the vkEnumerateX methods. These methods have the format of
+// VkResult vkEnumerateX(InputType1 arg1, InputTyp2 arg2, ..., uint32_t* size,
+//         OutputType* output_arg)
+// Instead of macros and explicitly listing the template params, Variadic Template was also
+// considered, but because the "variadic" part of the vk methods (i.e. the inputs) are before the
+// non-variadic parts, this breaks the template type matching logic. Hence, we use a macro approach
+// here.
+#define EXPAND_ENUM(...)                                                          \
+    uint32_t size = 0;                                                            \
+    VkResult result = func(__VA_ARGS__, nullptr);                                 \
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "enumerate size error"; \
+    utils::FixedCapacityVector<OutType> ret(size);                                \
+    result = func(__VA_ARGS__, ret.data());                                       \
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "enumerate error";      \
+    return std::move(ret);
+
+#define EXPAND_ENUM_NO_ARGS() EXPAND_ENUM(&size)
+#define EXPAND_ENUM_ARGS(...) EXPAND_ENUM(__VA_ARGS__, &size)
+
+template <typename OutType>
+utils::FixedCapacityVector<OutType> enumerate(VKAPI_ATTR VkResult (*func)(uint32_t*, OutType*)) {
+    EXPAND_ENUM_NO_ARGS();
+}
+
+template <typename InType, typename OutType>
+utils::FixedCapacityVector<OutType> enumerate(
+        VKAPI_ATTR VkResult (*func)(InType, uint32_t*, OutType*), InType inData) {
+    EXPAND_ENUM_ARGS(inData);
+}
+
+template <typename InTypeA, typename InTypeB, typename OutType>
+utils::FixedCapacityVector<OutType> enumerate(
+        VKAPI_ATTR VkResult (*func)(InTypeA, InTypeB, uint32_t*, OutType*), InTypeA inDataA,
+        InTypeB inDataB) {
+    EXPAND_ENUM_ARGS(inDataA, inDataB);
+}
+
+#undef EXPAND_ENUM
+#undef EXPAND_ENUM_NO_ARGS
+#undef EXPAND_ENUM_ARGS
+
+} // namespace filament::backend::fvkutils
+
+#endif // TNT_FILAMENT_BACKEND_VULKAN_UTILS_HELPER_H

filament/backend/src/vulkan/utils/Image.cpp

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 
-#include "VulkanImageUtility.h"
+#include "vulkan/utils/Image.h"
 
-#include "VulkanTexture.h"
+#include "vulkan/VulkanTexture.h"
 
 #include <utils/Panic.h>
 #include <utils/algorithm.h>
@@ -26,7 +26,7 @@
 
 using namespace bluevk;
 
-namespace filament::backend::imgutil {
+namespace filament::backend::fvkutils {
 
 namespace {
 
@@ -159,7 +159,41 @@ bool transitionLayout(VkCommandBuffer cmdbuffer,
     return true;
 }
 
-}// namespace filament::backend
+VkImageAspectFlags getImageAspect(VkFormat format) {
+    switch (format) {
+        case VK_FORMAT_D16_UNORM_S8_UINT:
+        case VK_FORMAT_D24_UNORM_S8_UINT:
+        case VK_FORMAT_D32_SFLOAT_S8_UINT:
+            return VK_IMAGE_ASPECT_DEPTH_BIT | VK_IMAGE_ASPECT_STENCIL_BIT;
+        case VK_FORMAT_D16_UNORM:
+        case VK_FORMAT_X8_D24_UNORM_PACK32:
+        case VK_FORMAT_D32_SFLOAT:
+            return VK_IMAGE_ASPECT_DEPTH_BIT;
+        case VK_FORMAT_S8_UINT:
+            return VK_IMAGE_ASPECT_STENCIL_BIT;
+        default:
+            return VK_IMAGE_ASPECT_COLOR_BIT;
+    }
+}
+
+bool isVkDepthFormat(VkFormat format) {
+    return (getImageAspect(format) & VK_IMAGE_ASPECT_DEPTH_BIT) != 0;
+}
+
+bool isVkStencilFormat(VkFormat format) {
+    return (getImageAspect(format) & VK_IMAGE_ASPECT_STENCIL_BIT) != 0;
+}
+
+static uint32_t mostSignificantBit(uint32_t x) { return 1ul << (31ul - utils::clz(x)); }
+
+uint8_t reduceSampleCount(uint8_t sampleCount, VkSampleCountFlags mask) {
+    if (sampleCount & mask) {
+        return sampleCount;
+    }
+    return mostSignificantBit((sampleCount - 1) & mask);
+}
+
+} // namespace filament::backend::fvkutils
 
 bool operator<(const VkImageSubresourceRange& a, const VkImageSubresourceRange& b) {
     if (a.aspectMask < b.aspectMask) return true;

filament/backend/src/vulkan/utils/Image.h

@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef TNT_FILAMENT_BACKEND_VULKANIMAGEUTILITY_H
-#define TNT_FILAMENT_BACKEND_VULKANIMAGEUTILITY_H
+#ifndef TNT_FILAMENT_BACKEND_VULKAN_UTILS_IMAGE_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_IMAGE_H
 
 #include <backend/DriverEnums.h>
 
@@ -59,22 +59,7 @@ struct VulkanLayoutTransition {
     VkImageSubresourceRange subresources;
 };
 
-namespace imgutil {
-
-inline VkImageViewType getViewType(SamplerType target) {
-    switch (target) {
-        case SamplerType::SAMPLER_CUBEMAP:
-            return VK_IMAGE_VIEW_TYPE_CUBE;
-        case SamplerType::SAMPLER_2D_ARRAY:
-            return VK_IMAGE_VIEW_TYPE_2D_ARRAY;
-        case SamplerType::SAMPLER_CUBEMAP_ARRAY:
-            return VK_IMAGE_VIEW_TYPE_CUBE_ARRAY;
-        case SamplerType::SAMPLER_3D:
-            return VK_IMAGE_VIEW_TYPE_3D;
-        default:
-            return VK_IMAGE_VIEW_TYPE_2D;
-    }
-}
+namespace fvkutils {
 
 constexpr inline VkImageLayout getVkLayout(VulkanLayout layout) {
     switch (layout) {
@@ -109,7 +94,15 @@ constexpr inline VkImageLayout getVkLayout(VulkanLayout layout) {
 // no transition necessary).
 bool transitionLayout(VkCommandBuffer cmdbuffer, VulkanLayoutTransition transition);
 
-} // namespace imgutil
+bool isVkDepthFormat(VkFormat format);
+
+bool isVkStencilFormat(VkFormat format);
+
+VkImageAspectFlags getImageAspect(VkFormat format);
+
+uint8_t reduceSampleCount(uint8_t sampleCount, VkSampleCountFlags mask);
+
+} // namespace fvkutils
 
 } // namespace filament::backend
 
@@ -117,5 +110,4 @@ bool operator<(const VkImageSubresourceRange& a, const VkImageSubresourceRange&
 
 utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::VulkanLayout& layout);
 
-
-#endif // TNT_FILAMENT_BACKEND_VULKANIMAGEUTILITY_H
+#endif // TNT_FILAMENT_BACKEND_VULKAN_UTILS_IMAGE_H

filament/backend/src/vulkan/utils/Spirv.cpp

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-#include "VulkanSpirvUtils.h"
+#include "vulkan/utils/Spirv.h"
 
 #include <utils/compiler.h>   // UTILS_UNUSED_IN_RELEASE, UTILS_FALLTHROUGH
 #include <utils/debug.h>      // assert_invariant
@@ -22,12 +22,11 @@
 
 #include <spirv/unified1/spirv.hpp>
 
-#include <unordered_map>
-#include <variant>
-#include <vector>
 #include <cstring>
+#include <unordered_map>
+#include <vector>
 
-namespace filament::backend {
+namespace filament::backend::fvkutils {
 
 namespace {
 
@@ -99,7 +98,7 @@ void workaroundSpecConstant(Program::ShaderBlob const& blob,
     uint32_t const* data = (uint32_t*) blob.data();
     uint32_t* outputData = output.data();
 
-    std::memcpy(&outputData[0], &data[0], HEADER_SIZE * 4);
+    memcpy(&outputData[0], &data[0], HEADER_SIZE * 4);
     size_t outputCursor = HEADER_SIZE;
 
     for (uint32_t cursor = HEADER_SIZE, cursorEnd = dataSize; cursor < cursorEnd;) {
@@ -147,61 +146,4 @@ void workaroundSpecConstant(Program::ShaderBlob const& blob,
     output.resize(outputCursor);
 }
 
-std::tuple<uint32_t,uint32_t, uint32_t> getProgramBindings(Program::ShaderBlob const& blob) {
-    std::unordered_map<uint32_t, uint32_t> targetToSet, targetToBinding;
-
-    constexpr size_t HEADER_SIZE = 5;
-
-    size_t const dataSize = blob.size() / 4;
-    uint32_t const* data = (uint32_t*) blob.data();
-
-    for (uint32_t cursor = HEADER_SIZE, cursorEnd = dataSize; cursor < cursorEnd;) {
-        uint32_t const firstWord = data[cursor];
-        uint32_t const wordCount = firstWord >> 16;
-        uint32_t const op = firstWord & 0x0000FFFF;
-
-        switch(op) {
-            case spv::Op::OpDecorate: {
-                if (data[cursor + 2] == spv::Decoration::DecorationDescriptorSet) {
-                    uint32_t const targetVar = data[cursor + 1];
-                    uint32_t const setId = data[cursor + 3];
-                    targetToSet[targetVar] = setId;
-                } else if (data[cursor + 2] == spv::Decoration::DecorationBinding) {
-                    uint32_t const targetVar = data[cursor + 1];
-                    uint32_t const binding = data[cursor + 3];
-                    targetToBinding[targetVar] = binding;
-                }
-                break;
-            }
-            default:
-                break;
-        }
-        cursor += wordCount;
-    }
-
-    constexpr uint32_t UBO = 0;
-    constexpr uint32_t SAMPLER = 1;
-    constexpr uint32_t IATTACHMENT = 2;
-    uint32_t ubo = 0, sampler = 0, inputAttachment = 0;
-
-    for (auto const& [target, setId]: targetToSet) {
-        uint32_t const binding = targetToBinding[target];
-        assert_invariant(binding < 32);
-        switch(setId) {
-            case UBO:
-                ubo |= (1 << binding);
-                break;
-            case SAMPLER:
-                sampler |= (1 << binding);
-                break;
-            case IATTACHMENT:
-                inputAttachment |= (1 << binding);
-                break;
-            default:
-                PANIC_POSTCONDITION("unexpected %d", (int) setId);
-        }
-    }
-    return {ubo, sampler, inputAttachment};
-}
-
-} // namespace filament::backend
+} // namespace filament::backend::fvkutils

filament/backend/src/vulkan/utils/Spirv.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023 The Android Open Source Project
+ * 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.
@@ -14,8 +14,8 @@
  * limitations under the License.
  */
 
-#ifndef TNT_FILAMENT_BACKEND_VULKANSPIRVUTILS_H
-#define TNT_FILAMENT_BACKEND_VULKANSPIRVUTILS_H
+#ifndef TNT_FILAMENT_BACKEND_VULKAN_UTILS_SPIRV_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_SPIRV_H
 
 #include <backend/Program.h>
 
@@ -24,7 +24,7 @@
 #include <tuple>
 #include <vector>
 
-namespace filament::backend {
+namespace filament::backend::fvkutils {
 
 using SpecConstantValue = Program::SpecializationConstant::Type;
 
@@ -44,8 +44,9 @@ void workaroundSpecConstant(Program::ShaderBlob const& blob,
         std::vector<uint32_t>& output);
 
 // bindings for UBO, samplers, input attachment
-std::tuple<uint32_t, uint32_t, uint32_t> getProgramBindings(Program::ShaderBlob const& blob);
+// This is no longer needed after the descriptor set refactor, but the code is good for reference. 
+// std::tuple<uint32_t, uint32_t, uint32_t> getProgramBindings(Program::ShaderBlob const& blob);
 
-} // namespace filament::backend
+} // namespace filament::backend::fvkutils
 
-#endif // TNT_FILAMENT_BACKEND_VULKANSPIRVUTILS_H
+#endif // TNT_FILAMENT_BACKEND_VULKAN_UTILS_SPIRV_H

filament/backend/src/vulkan/utils/StaticVector.h

@@ -0,0 +1,134 @@
+/*
+ * 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_VULKAN_UTILS_STATICVECTOR_H
+#define TNT_FILAMENT_BACKEND_VULKAN_UTILS_STATICVECTOR_H
+
+// An Array that will be statically fixed in capacity, but the "size" (as in user added elements) is
+// variable. Note that this class is movable.
+
+#include <utils/Panic.h>
+
+#include <array>
+
+namespace filament::backend::fvkutils {
+
+template<typename T, uint16_t CAPACITY>
+class StaticVector {
+private:
+    using FixedSizeArray = std::array<T, CAPACITY>;
+
+    static_assert(CAPACITY <= (1LL << (8 * sizeof(uint16_t))));
+
+public:
+    using const_iterator = typename FixedSizeArray::const_iterator;
+    using iterator = typename FixedSizeArray::iterator;
+
+    StaticVector() = default;
+
+    // Delete copy constructor/assignment.
+    StaticVector(StaticVector const& rhs) = delete;
+    StaticVector& operator=(StaticVector& rhs) = delete;
+
+    StaticVector(StaticVector&& rhs) noexcept {
+        std::swap(mSize, rhs.mSize);
+        std::swap(mArray, rhs.mArray);
+    }
+
+    StaticVector& operator=(StaticVector&& rhs) noexcept {
+        std::swap(mSize, rhs.mSize);
+        std::swap(mArray, rhs.mArray);
+        return *this;
+    }
+
+    inline ~StaticVector() {
+        clear();
+    }
+
+    inline const_iterator begin() const {
+        return mArray.cbegin();
+    }
+
+    inline const_iterator end() const {
+        assert_invariant(mSize <= CAPACITY);
+        return mArray.begin() + mSize;
+    }
+
+    inline iterator begin() {
+        return mArray.begin();
+    }
+
+    inline iterator end() {
+        assert_invariant(mSize <= CAPACITY);
+        return mArray.begin() + mSize;
+    }
+
+    inline T back() {
+        assert_invariant(mSize > 0);
+        return *(mArray.begin() + mSize);
+    }
+
+    inline void pop_back() {
+        assert_invariant(mSize > 0);
+        mSize--;
+    }
+
+    inline const_iterator find(T item) {
+        return std::find(begin(), end(), item);
+    }
+
+    inline void push_back(T item) {
+        assert_invariant(mSize < CAPACITY);
+        mArray[mSize++] = item;
+    }
+
+    inline void clear() {
+        mSize = 0;
+    }
+
+    inline T& operator[](size_t index) {
+        assert_invariant(index < mSize);
+        return mArray[index];
+    }
+
+    inline T const& operator[](size_t index) const {
+        return mArray[index];
+    }
+
+    inline uint16_t size() const {
+        return mSize;
+    }
+
+    T* data() {
+        return mArray.data();
+    }
+
+    T const* data() const {
+        return mArray.data();
+    }
+
+    bool operator==(StaticVector const& b) const {
+        return this->mArray == b.mArray && this->mSize == b.mSize;
+    }
+
+private:
+    FixedSizeArray mArray;
+    uint16_t mSize = 0;
+};
+
+} // namespace filament::backend::fvkutils
+
+#endif // TNT_FILAMENT_BACKEND_VULKAN_UTILS_STATICVECTOR_H

filament/include/filament/Box.h

@@ -183,7 +183,7 @@ struct UTILS_PUBLIC Aabb {
      * Returns the 8 corner vertices of the AABB.
      */
     Corners getCorners() const {
-        return Aabb::Corners{ .vertices = {
+        return Corners{ .vertices = {
                 { min.x, min.y, min.z },
                 { max.x, min.y, min.z },
                 { min.x, max.y, min.z },

filament/include/filament/BufferObject.h

@@ -73,7 +73,7 @@ public:
 
         /**
          * The binding type for this buffer object. (defaults to VERTEX)
-         * @param BindingType Distinguishes between SSBO, VBO, etc. For now this must be VERTEX.
+         * @param bindingType Distinguishes between SSBO, VBO, etc. For now this must be VERTEX.
          * @return A reference to this Builder for chaining calls.
          */
         Builder& bindingType(BindingType bindingType) noexcept;
@@ -91,7 +91,7 @@ public:
          * @param len Length of name, should be less than or equal to 128
          * @return This Builder, for chaining calls.
          */
-        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+        Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept;
 
         /**
          * Creates the BufferObject and returns a pointer to it. After creation, the buffer

filament/include/filament/Camera.h

@@ -400,14 +400,14 @@ public:
      *          engine.getTransformManager().getInstance(camera->getEntity()), model);
      * ~~~~~~~~~~~
      *
-     * @param model The camera position and orientation provided as a rigid transform matrix.
+     * @param modelMatrix The camera position and orientation provided as a rigid transform matrix.
      *
      * @note The Camera "looks" towards its -z axis
      *
      * @warning \p model must be a rigid transform
      */
-    void setModelMatrix(const math::mat4& model) noexcept;
-    void setModelMatrix(const math::mat4f& model) noexcept; //!< @overload
+    void setModelMatrix(const math::mat4& modelMatrix) noexcept;
+    void setModelMatrix(const math::mat4f& modelMatrix) noexcept; //!< @overload
 
     /** Set the position of an eye relative to this Camera (head).
      *

filament/include/filament/Color.h

@@ -194,7 +194,7 @@ inline sRGBColorA Color::toSRGB<ACCURATE>(LinearColorA const& color) {
 }
 
 inline LinearColor Color::toLinear(RgbType type, math::float3 color) {
-    return (type == RgbType::LINEAR) ? color : Color::toLinear<ACCURATE>(color);
+    return (type == RgbType::LINEAR) ? color : toLinear<ACCURATE>(color);
 }
 
 // converts an RGBA color to linear space
@@ -202,11 +202,11 @@ inline LinearColor Color::toLinear(RgbType type, math::float3 color) {
 inline LinearColorA Color::toLinear(RgbaType type, math::float4 color) {
     switch (type) {
         case RgbaType::sRGB:
-            return Color::toLinear<ACCURATE>(color) * math::float4{color.a, color.a, color.a, 1.0f};
+            return toLinear<ACCURATE>(color) * math::float4{color.a, color.a, color.a, 1.0f};
         case RgbaType::LINEAR:
             return color * math::float4{color.a, color.a, color.a, 1.0f};
         case RgbaType::PREMULTIPLIED_sRGB:
-            return Color::toLinear<ACCURATE>(color);
+            return toLinear<ACCURATE>(color);
         case RgbaType::PREMULTIPLIED_LINEAR:
             return color;
     }

filament/include/filament/Engine.h

@@ -537,7 +537,7 @@ public:
             Platform* UTILS_NULLABLE platform = nullptr,
             void* UTILS_NULLABLE sharedContext = nullptr,
             const Config* UTILS_NULLABLE config = nullptr) {
-        return Engine::Builder()
+        return Builder()
                 .backend(backend)
                 .platform(platform)
                 .sharedContext(sharedContext)
@@ -557,7 +557,7 @@ public:
             Platform* UTILS_NULLABLE platform = nullptr,
             void* UTILS_NULLABLE sharedContext = nullptr,
             const Config* UTILS_NULLABLE config = nullptr) {
-        Engine::Builder()
+        Builder()
                 .backend(backend)
                 .platform(platform)
                 .sharedContext(sharedContext)
@@ -970,6 +970,25 @@ public:
      */
     void flushAndWait();
 
+    /**
+     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
+     * all commands to this point are executed. Note that does guarantee that the
+     * hardware is actually finished.
+     *
+     * A timeout can be specified, if for some reason this flushAndWait doesn't complete before the timeout, it will
+     * return false, true otherwise.
+     *
+     * <p>This is typically used right after destroying the <code>SwapChain</code>,
+     * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
+     * timely fashion, such as when responding to Android's
+     * <code>android.view.SurfaceHolder.Callback.surfaceDestroyed</code></p>
+     *
+     * @param timeout A timeout in nanoseconds
+     * @return true if successful, false if flushAndWait timed out, in which case it wasn't successful and commands
+     * might still be executing on both the CPU and GPU sides.
+     */
+    bool flushAndWait(uint64_t timeout);
+
     /**
      * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) but does not wait
      * for commands to be either executed or the hardware finished.

filament/include/filament/IndexBuffer.h

@@ -96,7 +96,7 @@ public:
          * @param len Length of name, should be less than or equal to 128
          * @return This Builder, for chaining calls.
          */
-        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+        Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept;
 
         /**
          * Creates the IndexBuffer object and returns a pointer to it. After creation, the index

filament/include/filament/InstanceBuffer.h

@@ -83,7 +83,7 @@ public:
          * @param len Length of name, should be less than or equal to 128
          * @return This Builder, for chaining calls.
          */
-        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+        Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept;
 
         /**
          * Creates the InstanceBuffer object and returns a pointer to it.

filament/include/filament/Material.h

@@ -118,10 +118,10 @@ public:
         Builder& package(const void* UTILS_NONNULL payload, size_t size);
 
         template<typename T>
-        using is_supported_constant_parameter_t = typename std::enable_if<
-                std::is_same<int32_t, T>::value ||
-                std::is_same<float, T>::value ||
-                std::is_same<bool, T>::value>::type;
+        using is_supported_constant_parameter_t = std::enable_if_t<
+                std::is_same_v<int32_t, T> ||
+                std::is_same_v<float, T> ||
+                std::is_same_v<bool, T>>;
 
         /**
          * Specialize a constant parameter specified in the material definition with a concrete
@@ -177,7 +177,7 @@ public:
          *            memory or other resources.
          * @exception utils::PreConditionPanic if a parameter to a builder function was invalid.
          */
-        Material* UTILS_NULLABLE build(Engine& engine);
+        Material* UTILS_NULLABLE build(Engine& engine) const;
     private:
         friend class FMaterial;
     };

filament/include/filament/MaterialInstance.h

@@ -56,35 +56,35 @@ class UTILS_PUBLIC MaterialInstance : public FilamentAPI {
     };
 
 public:
-    using CullingMode = filament::backend::CullingMode;
-    using TransparencyMode = filament::TransparencyMode;
-    using DepthFunc = filament::backend::SamplerCompareFunc;
-    using StencilCompareFunc = filament::backend::SamplerCompareFunc;
-    using StencilOperation = filament::backend::StencilOperation;
-    using StencilFace = filament::backend::StencilFace;
+    using CullingMode = backend::CullingMode;
+    using TransparencyMode = TransparencyMode;
+    using DepthFunc = backend::SamplerCompareFunc;
+    using StencilCompareFunc = backend::SamplerCompareFunc;
+    using StencilOperation = backend::StencilOperation;
+    using StencilFace = backend::StencilFace;
 
     template<typename T>
-    using is_supported_parameter_t = typename std::enable_if<
-            std::is_same<float, T>::value ||
-            std::is_same<int32_t, T>::value ||
-            std::is_same<uint32_t, T>::value ||
-            std::is_same<math::int2, T>::value ||
-            std::is_same<math::int3, T>::value ||
-            std::is_same<math::int4, T>::value ||
-            std::is_same<math::uint2, T>::value ||
-            std::is_same<math::uint3, T>::value ||
-            std::is_same<math::uint4, T>::value ||
-            std::is_same<math::float2, T>::value ||
-            std::is_same<math::float3, T>::value ||
-            std::is_same<math::float4, T>::value ||
-            std::is_same<math::mat4f, T>::value ||
+    using is_supported_parameter_t = std::enable_if_t<
+            std::is_same_v<float, T> ||
+            std::is_same_v<int32_t, T> ||
+            std::is_same_v<uint32_t, T> ||
+            std::is_same_v<math::int2, T> ||
+            std::is_same_v<math::int3, T> ||
+            std::is_same_v<math::int4, T> ||
+            std::is_same_v<math::uint2, T> ||
+            std::is_same_v<math::uint3, T> ||
+            std::is_same_v<math::uint4, T> ||
+            std::is_same_v<math::float2, T> ||
+            std::is_same_v<math::float3, T> ||
+            std::is_same_v<math::float4, T> ||
+            std::is_same_v<math::mat4f, T> ||
             // these types are slower as they need a layout conversion
-            std::is_same<bool, T>::value ||
-            std::is_same<math::bool2, T>::value ||
-            std::is_same<math::bool3, T>::value ||
-            std::is_same<math::bool4, T>::value ||
-            std::is_same<math::mat3f, T>::value
-    >::type;
+            std::is_same_v<bool, T> ||
+            std::is_same_v<math::bool2, T> ||
+            std::is_same_v<math::bool3, T> ||
+            std::is_same_v<math::bool4, T> ||
+            std::is_same_v<math::mat3f, T>
+    >;
 
     /**
      * Creates a new MaterialInstance using another MaterialInstance as a template for initialization.
@@ -121,13 +121,13 @@ public:
 
     /** inline helper to provide the name as a null-terminated string literal */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(StringLiteral name, T const& value) {
+    void setParameter(StringLiteral name, T const& value) {
         setParameter<T>(name.data, name.size, value);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(const char* UTILS_NONNULL name, T const& value) {
+    void setParameter(const char* UTILS_NONNULL name, T const& value) {
         setParameter<T>(name, strlen(name), value);
     }
 
@@ -148,14 +148,14 @@ public:
 
     /** inline helper to provide the name as a null-terminated string literal */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(StringLiteral name, const T* UTILS_NONNULL values, size_t count) {
+    void setParameter(StringLiteral name, const T* UTILS_NONNULL values, size_t count) {
         setParameter<T>(name.data, name.size, values, count);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline void setParameter(const char* UTILS_NONNULL name,
-            const T* UTILS_NONNULL values, size_t count) {
+    void setParameter(const char* UTILS_NONNULL name,
+                      const T* UTILS_NONNULL values, size_t count) {
         setParameter<T>(name, strlen(name), values, count);
     }
 
@@ -176,14 +176,14 @@ public:
             Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler);
 
     /** inline helper to provide the name as a null-terminated string literal */
-    inline void setParameter(StringLiteral name,
-            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
+    void setParameter(StringLiteral name,
+                      Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
         setParameter(name.data, name.size, texture, sampler);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* UTILS_NONNULL name,
-            Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
+    void setParameter(const char* UTILS_NONNULL name,
+                      Texture const* UTILS_NULLABLE texture, TextureSampler const& sampler) {
         setParameter(name, strlen(name), texture, sampler);
     }
 
@@ -202,12 +202,12 @@ public:
             RgbType type, math::float3 color);
 
     /** inline helper to provide the name as a null-terminated string literal */
-    inline void setParameter(StringLiteral name, RgbType type, math::float3 color) {
+    void setParameter(StringLiteral name, RgbType type, math::float3 color) {
         setParameter(name.data, name.size, type, color);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) {
+    void setParameter(const char* UTILS_NONNULL name, RgbType type, math::float3 color) {
         setParameter(name, strlen(name), type, color);
     }
 
@@ -226,12 +226,12 @@ public:
             RgbaType type, math::float4 color);
 
     /** inline helper to provide the name as a null-terminated string literal */
-    inline void setParameter(StringLiteral name, RgbaType type, math::float4 color) {
+    void setParameter(StringLiteral name, RgbaType type, math::float4 color) {
         setParameter(name.data, name.size, type, color);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
-    inline void setParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) {
+    void setParameter(const char* UTILS_NONNULL name, RgbaType type, math::float4 color) {
         setParameter(name, strlen(name), type, color);
     }
 
@@ -251,13 +251,13 @@ public:
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline T getParameter(StringLiteral name) const {
+    T getParameter(StringLiteral name) const {
         return getParameter<T>(name.data, name.size);
     }
 
     /** inline helper to provide the name as a null-terminated C string */
     template<typename T, typename = is_supported_parameter_t<T>>
-    inline T getParameter(const char* UTILS_NONNULL name) const {
+    T getParameter(const char* UTILS_NONNULL name) const {
         return getParameter<T>(name, strlen(name));
     }
 

filament/include/filament/MorphTargetBuffer.h

@@ -76,7 +76,7 @@ public:
          * @param len Length of name, should be less than or equal to 128
          * @return This Builder, for chaining calls.
          */
-        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+        Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept;
 
         /**
          * Creates the MorphTargetBuffer object and returns a pointer to it.

filament/include/filament/Options.h

@@ -86,10 +86,10 @@ struct DynamicResolutionOptions {
     /**
      * Upscaling quality
      * LOW:    bilinear filtered blit. Fastest, poor quality
-     * MEDIUM: AMD FidelityFX FSR1 w/ mobile optimizations
+     * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
      * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
      * ULTRA:  AMD FidelityFX FSR1
-     *      FSR1 require a well anti-aliased (MSAA or TAA), noise free scene.
+     *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene. Avoid FXAA and dithering.
      *
      * The default upscaling quality is set to LOW.
      */

filament/include/filament/RenderableManager.h

@@ -220,7 +220,7 @@ public:
          * the renderable are immutable.
          * STATIC geometry has the same restrictions as STATIC_BOUNDS, but in addition disallows
          * skinning, morphing and changing the VertexBuffer or IndexBuffer in any way.
-         * @param enable whether this renderable has static bounds. false by default.
+         * @param type type of geometry.
          */
         Builder& geometryType(GeometryType type) noexcept;
 
@@ -454,7 +454,7 @@ public:
          *
          * @param primitiveIndex zero-based index of the primitive, must be less than the primitive
          *                       count passed to Builder constructor
-         * @param indicesAndWeightsVectors pairs of bone index and bone weight for all vertices of
+         * @param indicesAndWeightsVector pairs of bone index and bone weight for all vertices of
          *                                 the primitive sequentially
          *
          * @return Builder reference for chaining calls.
@@ -501,7 +501,7 @@ public:
          * @param primitiveIndex zero-based index of the primitive, must be less than the count passed to Builder constructor
          * @param offset specifies where in the morph target buffer to start reading (expressed as a number of vertices)
          */
-        RenderableManager::Builder& morphing(uint8_t level,
+        Builder& morphing(uint8_t level,
                 size_t primitiveIndex, size_t offset) noexcept;
 
 
@@ -798,6 +798,13 @@ public:
     void setMaterialInstanceAt(Instance instance,
             size_t primitiveIndex, MaterialInstance const* UTILS_NONNULL materialInstance);
 
+    /**
+     * Clear the MaterialInstance for the given primitive.
+     * @param instance Renderable's instance
+     * @param primitiveIndex Primitive index
+     */
+    void clearMaterialInstanceAt(Instance instance, size_t primitiveIndex);
+
     /**
      * Retrieves the material instance that is bound to the given primitive.
      */
@@ -845,20 +852,20 @@ public:
     /*! \cond PRIVATE */
     template<typename T>
     struct is_supported_vector_type {
-        using type = typename std::enable_if<
-                std::is_same<math::float4, T>::value ||
-                std::is_same<math::half4,  T>::value ||
-                std::is_same<math::float3, T>::value ||
-                std::is_same<math::half3,  T>::value
-        >::type;
+        using type = std::enable_if_t<
+                std::is_same_v<math::float4, T> ||
+                std::is_same_v<math::half4,  T> ||
+                std::is_same_v<math::float3, T> ||
+                std::is_same_v<math::half3,  T>
+        >;
     };
 
     template<typename T>
     struct is_supported_index_type {
-        using type = typename std::enable_if<
-                std::is_same<uint16_t, T>::value ||
-                std::is_same<uint32_t, T>::value
-        >::type;
+        using type = std::enable_if_t<
+                std::is_same_v<uint16_t, T> ||
+                std::is_same_v<uint32_t, T>
+        >;
     };
     /*! \endcond */
 

filament/include/filament/Renderer.h

@@ -105,7 +105,7 @@ public:
      * @param historySize requested history size. The returned vector could be smaller.
      * @return A vector of FrameInfo.
      */
-    utils::FixedCapacityVector<Renderer::FrameInfo> getFrameInfoHistory(
+    utils::FixedCapacityVector<FrameInfo> getFrameInfoHistory(
             size_t historySize = 1) const noexcept;
 
     /**