Update spirv-tools to v2024.2 (dd4b663)

Texture handles were resolved to pointers when updating a SamplerGroup,
as that point the handle was checked for use-after-free. However, the
texture could be destroyed later while still active in the SamplerGroup,
this would result in using the pointer which now contains garbage.

We now keep the handle and resolve the texture when binding samplers
to the program; which will also perform the use-after-free check.

.github/workflows/android-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - uses: actions/setup-java@v3
         with:
           distribution: 'temurin'

.github/workflows/ios-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/ios && printf "y" | ./build.sh continuous

.github/workflows/linux-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/linux && printf "y" | ./build.sh continuous

.github/workflows/mac-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/mac && printf "y" | ./build.sh continuous

.github/workflows/npm-deploy.yml

@@ -13,7 +13,7 @@ jobs:
     name: npm-deploy
     runs-on: macos-14
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
         with:
           ref: ${{ github.event.inputs.release_tag }}
       # Setup .npmrc file to publish to npm

.github/workflows/presubmit.yml

@@ -18,7 +18,7 @@ jobs:
         os: [macos-14, ubuntu-22.04]
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           WORKFLOW_OS=`echo \`uname\` | sed "s/Darwin/mac/" | tr [:upper:] [:lower:]`
@@ -32,7 +32,7 @@ jobs:
     runs-on: windows-2019
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           build\windows\build-github.bat presubmit
@@ -43,7 +43,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - uses: actions/setup-java@v3
         with:
           distribution: 'temurin'
@@ -57,7 +57,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/ios && printf "y" | ./build.sh presubmit
@@ -70,7 +70,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh presubmit

.github/workflows/release.yml

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

.github/workflows/web-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-14
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh continuous

.github/workflows/windows-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: windows-2019
 
     steps:
-      - uses: actions/checkout@v3.3.0
+      - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           build\windows\build-github.bat continuous

CMakeLists.txt

@@ -735,7 +735,6 @@ add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
-add_subdirectory(${EXTERNAL}/hat-trie/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)
 add_subdirectory(${EXTERNAL}/robin-map/tnt)
 add_subdirectory(${EXTERNAL}/smol-v/tnt)

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.52.1'
+    implementation 'com.google.android.filament:filament-android:1.53.1'
 }
 ```
 
@@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.52.1'
+pod 'Filament', '~> 1.53.1'
 ```
 
 ### Snapshots
@@ -176,6 +176,7 @@ steps:
   - [x] KHR_materials_unlit
   - [x] KHR_materials_variants
   - [x] KHR_materials_volume
+  - [x] KHR_materials_specular
   - [x] KHR_mesh_quantization
   - [x] KHR_texture_basisu
   - [x] KHR_texture_transform

RELEASE_NOTES.md

@@ -7,6 +7,22 @@ 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.53.2
+
+
+## v1.53.1
+
+
+## v1.53.0
+
+- engine: fix skinning normals with large transforms (b/342459864) [⚠️ **New Material Version**]
+
+## v1.52.3
+
+
+## v1.52.2
+
+
 ## v1.52.1
 
 - Add instructions for using Mesa for software rasterization

android/build.gradle

@@ -83,12 +83,12 @@ buildscript {
         'minSdk': 21,
         'targetSdk': 34,
         'compileSdk': 34,
-        'kotlin': '1.9.21',
-        'kotlin_coroutines': '1.7.3',
+        'kotlin': '2.0.0',
+        'kotlin_coroutines': '1.9.0-RC',
         'buildTools': '34.0.0',
-        'ndk': '26.1.10909125',
-        'androidx_core': '1.12.0',
-        'androidx_annotations': '1.7.0'
+        'ndk': '27.0.11718014',
+        'androidx_core': '1.13.1',
+        'androidx_annotations': '1.8.0'
     ]
 
     ext.deps = [
@@ -104,7 +104,7 @@ buildscript {
     ]
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.2.0'
+        classpath 'com.android.tools.build:gradle:8.4.1'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 

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

@@ -420,6 +420,13 @@ Java_com_google_android_filament_Engine_nSetPaused(JNIEnv*, jclass,
     engine->setPaused(paused);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nUnprotected(JNIEnv*, jclass,
+        jlong nativeEngine, jboolean paused) {
+    Engine* engine = (Engine*) nativeEngine;
+    engine->unprotected();
+}
+
 // Managers...
 
 extern "C" JNIEXPORT jlong JNICALL
@@ -564,3 +571,9 @@ Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nat
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     return (jlong) builder->build();
 }
+
+extern "C"
+JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_getSteadyClockTimeNano(JNIEnv *env, jclass clazz) {
+    return (jlong)Engine::getSteadyClockTimeNano();
+}

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

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

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

@@ -187,3 +187,10 @@ Java_com_google_android_filament_Renderer_nSetPresentationTime(JNIEnv *, jclass
     Renderer *renderer = (Renderer *) nativeRenderer;
     renderer->setPresentationTime(monotonicClockNanos);
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Renderer_nSetVsyncTime(JNIEnv *, jclass,
+    jlong nativeRenderer, jlong steadyClockTimeNano) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    renderer->setVsyncTime(steadyClockTimeNano);
+}

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

@@ -1289,6 +1289,24 @@ public class Engine {
         nSetPaused(getNativeObject(), paused);
     }
 
+    /**
+     * Switch the command queue to unprotected mode. Protected mode can be activated via
+     * Renderer::beginFrame() using a protected SwapChain.
+     * @see Renderer
+     * @see SwapChain
+     */
+    public void unprotected() {
+        nUnprotected(getNativeObject());
+    }
+
+    /**
+     * Get the current time. This is a convenience function that simply returns the
+     * time in nanosecond since epoch of std::chrono::steady_clock.
+     * @return current time in nanosecond since epoch of std::chrono::steady_clock.
+     * @see Renderer#beginFrame
+     */
+    public static native long getSteadyClockTimeNano();
+
     @UsedByReflection("TextureHelper.java")
     public long getNativeObject() {
         if (mNativeObject == 0) {
@@ -1366,6 +1384,7 @@ public class Engine {
     private static native void nFlush(long nativeEngine);
     private static native boolean nIsPaused(long nativeEngine);
     private static native void nSetPaused(long nativeEngine, boolean paused);
+    private static native void nUnprotected(long nativeEngine);
     private static native long nGetTransformManager(long nativeEngine);
     private static native long nGetLightManager(long nativeEngine);
     private static native long nGetRenderableManager(long nativeEngine);

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

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

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

@@ -284,6 +284,19 @@ public class Renderer {
         nSetPresentationTime(getNativeObject(), monotonicClockNanos);
     }
 
+    /**
+     * The use of this method is optional. It sets the VSYNC time expressed as the duration in
+     * nanosecond since epoch of std::chrono::steady_clock.
+     * If called, passing 0 to frameTimeNanos in Renderer.BeginFrame will use this
+     * time instead.
+     * @param steadyClockTimeNano duration in nanosecond since epoch of std::chrono::steady_clock
+     * @see Engine#getSteadyClockTimeNano
+     * @see Renderer#beginFrame
+     */
+    public void setVsyncTime(long steadyClockTimeNano) {
+        nSetVsyncTime(getNativeObject(), steadyClockTimeNano);
+    }
+
     /**
      * Sets up a frame for this <code>Renderer</code>.
      * <p><code>beginFrame</code> manages frame pacing, and returns whether or not a frame should be
@@ -702,6 +715,7 @@ public class Renderer {
     }
 
     private static native void nSetPresentationTime(long nativeObject, long monotonicClockNanos);
+    private static native void nSetVsyncTime(long nativeObject, long steadyClockTimeNano);
     private static native boolean nBeginFrame(long nativeRenderer, long nativeSwapChain, long frameTimeNanos);
     private static native void nEndFrame(long nativeRenderer);
     private static native void nRender(long nativeRenderer, long nativeView);

android/gltfio-android/CMakeLists.txt

@@ -120,7 +120,6 @@ set(GLTFIO_INCLUDE_DIRS
         ../../third_party/cgltf
         ../../third_party/meshoptimizer/src
         ../../third_party/robin-map
-        ../../third_party/hat-trie
         ../../third_party/stb
         ../../libs/utils/include
         ../../libs/ktxreader/include

android/gradle.properties

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

android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 #Wed Nov 17 10:40:18 PST 2021
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

build/android/build.sh

@@ -57,7 +57,8 @@ FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/ndk.version)}
 
 # Install the required NDK version specifically (if not present)
 if [[ ! -d "${ANDROID_HOME}/ndk/$FILAMENT_NDK_VERSION" ]]; then
-    ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION" > /dev/null
+    yes | ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager --licenses
+    ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION"
 fi
 
 # Only build 1 64 bit target during presubmit to cut down build times during presubmit

build/android/ndk.version

@@ -1 +1 @@
-26.1.10909125
+27.0.11718014

filament/backend/include/backend/Platform.h

@@ -75,6 +75,8 @@ public:
          */
         size_t textureUseAfterFreePoolSize = 0;
 
+        size_t metalUploadBufferSizeBytes = 512 * 1024;
+
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL and Metal backends.

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

@@ -90,8 +90,13 @@ protected:
     AcquiredImage transformAcquiredImage(AcquiredImage source) noexcept override;
 
 private:
+    struct InitializeJvmForPerformanceManagerIfNeeded {
+        InitializeJvmForPerformanceManagerIfNeeded();
+    };
+
     int mOSVersion;
     ExternalStreamManagerAndroid& mExternalStreamManager;
+    InitializeJvmForPerformanceManagerIfNeeded const mInitializeJvmForPerformanceManagerIfNeeded;
     utils::PerformanceHintManager mPerformanceHintManager;
     utils::PerformanceHintManager::Session mPerformanceHintSession;
 

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

@@ -90,6 +90,20 @@ public:
         VkExtent2D extent = {0, 0};
     };
 
+    struct ImageSyncData {
+        static constexpr uint32_t INVALID_IMAGE_INDEX = UINT32_MAX;
+
+        // The index of the next image as returned by vkAcquireNextImage or equivalent.
+        uint32_t imageIndex = INVALID_IMAGE_INDEX;
+
+        // Semaphore to be signaled once the image is available.
+        VkSemaphore imageReadySemaphore = VK_NULL_HANDLE;
+
+        // A function called right before vkQueueSubmit. After this call, the image must be 
+        // available. This pointer can be null if imageReadySemaphore is not VK_NULL_HANDLE.
+        std::function<void(SwapChainPtr handle)> explicitImageReadyWait = nullptr;
+    };
+
     VulkanPlatform();
 
     ~VulkanPlatform() override;
@@ -127,6 +141,12 @@ public:
          * before recreating the swapchain. Default is true.
          */
         bool flushAndWaitOnWindowResize = true;
+
+        /**
+         * Whether the swapchain image should be transitioned to a layout suitable for
+         * presentation. Default is true.
+         */
+        bool transitionSwapChainImageLayoutForPresent = true;
     };
 
     /**
@@ -155,13 +175,10 @@ public:
      * corresponding VkImage will be used as the output color attachment. The client should signal
      * the `clientSignal` semaphore when the image is ready to be used by the backend.
      * @param handle         The handle returned by createSwapChain()
-     * @param clientSignal   The semaphore that the client will signal to indicate that the backend
-     *                       may render into the image.
-     * @param index          Pointer to memory that will be filled with the index that corresponding
-     *                       to an image in the `SwapChainBundle.colors` array.
+     * @param outImageSyncData The synchronization data used for image readiness
      * @return               Result of acquire
      */
-    virtual VkResult acquire(SwapChainPtr handle, VkSemaphore clientSignal, uint32_t* index);
+    virtual VkResult acquire(SwapChainPtr handle, ImageSyncData* outImageSyncData);
 
     /**
      * Present the image corresponding to `index` to the display. The client should wait on

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

@@ -173,14 +173,26 @@ public:
                 uint8_t const age = (tag & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
                 auto const pNode = static_cast<typename Allocator::Node*>(p);
                 uint8_t const expectedAge = pNode[-1].age;
-                ASSERT_POSTCONDITION(expectedAge == age,
-                        "use-after-free of Handle with id=%d", handle.getId());
+                FILAMENT_CHECK_POSTCONDITION(expectedAge == age) <<
+                        "use-after-free of Handle with id=" << handle.getId();
             }
         }
 
         return static_cast<Dp>(p);
     }
 
+    template<typename B>
+    bool is_valid(Handle<B>& handle) {
+        if (handle && isPoolHandle(handle.getId())) {
+            auto [p, tag] = handleToPointer(handle.getId());
+            uint8_t const age = (tag & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
+            auto const pNode = static_cast<typename Allocator::Node*>(p);
+            uint8_t const expectedAge = pNode[-1].age;
+            return expectedAge == age;
+        }
+        return true;
+    }
+
     template<typename Dp, typename B>
     inline typename std::enable_if_t<
             std::is_pointer_v<Dp> &&
@@ -240,8 +252,8 @@ private:
             Node* const pNode = static_cast<Node*>(p);
             uint8_t& expectedAge = pNode[-1].age;
             if (UTILS_UNLIKELY(!mUseAfterFreeCheckDisabled)) {
-                ASSERT_POSTCONDITION(expectedAge == age,
-                        "double-free of Handle of size %d at %p", size, p);
+                FILAMENT_CHECK_POSTCONDITION(expectedAge == age) <<
+                        "double-free of Handle of size " << size << " at " << p;
             }
             expectedAge = (expectedAge + 1) & 0xF; // fixme
 

filament/backend/src/Callable.cpp

@@ -27,8 +27,8 @@ PresentCallable::PresentCallable(PresentFn fn, void* user) noexcept
 }
 
 void PresentCallable::operator()(bool presentFrame) noexcept {
-    ASSERT_PRECONDITION(mPresentFn, "This PresentCallable was already called. " \
-            "PresentCallables should be called exactly once.");
+    FILAMENT_CHECK_PRECONDITION(mPresentFn) << "This PresentCallable was already called. "
+                                               "PresentCallables should be called exactly once.";
     mPresentFn(presentFrame, mUser);
     // Set mPresentFn to nullptr to denote that the callable has been called.
     mPresentFn = nullptr;

filament/backend/src/CircularBuffer.cpp

@@ -119,9 +119,9 @@ void* CircularBuffer::alloc(size_t size) noexcept {
         data = mmap(nullptr, size * 2 + BLOCK_SIZE,
                 PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0);
 
-        ASSERT_POSTCONDITION(data,
-                "couldn't allocate %u KiB of virtual address space for the command buffer",
-                (size * 2 / 1024));
+        FILAMENT_CHECK_POSTCONDITION(data) <<
+                "couldn't allocate " << (size * 2 / 1024) <<
+                " KiB of virtual address space for the command buffer";
 
         slog.d << "WARNING: Using soft CircularBuffer (" << (size * 2 / 1024) << " KiB)"
                << io::endl;

filament/backend/src/CommandBufferQueue.cpp

@@ -74,8 +74,6 @@ void CommandBufferQueue::setPaused(bool paused) {
 
 bool CommandBufferQueue::isExitRequested() const {
     std::lock_guard<utils::Mutex> const lock(mLock);
-    ASSERT_PRECONDITION( mExitRequested == 0 || mExitRequested == EXIT_REQUESTED,
-            "mExitRequested is corrupted (value = 0x%08x)!", mExitRequested);
     return (bool)mExitRequested;
 }
 
@@ -108,11 +106,11 @@ void CommandBufferQueue::flush() noexcept {
     mCondition.notify_one();
 
     // circular buffer is too small, we corrupted the stream
-    ASSERT_POSTCONDITION(used <= mFreeSpace,
+    FILAMENT_CHECK_POSTCONDITION(used <= mFreeSpace) <<
             "Backend CommandStream overflow. Commands are corrupted and unrecoverable.\n"
             "Please increase minCommandBufferSizeMB inside the Config passed to Engine::create.\n"
-            "Space used at this time: %u bytes, overflow: %u bytes",
-            (unsigned)used, unsigned(used - mFreeSpace));
+            "Space used at this time: " << used <<
+            " bytes, overflow: " << used - mFreeSpace << " bytes";
 
     // wait until there is enough space in the buffer
     mFreeSpace -= used;
@@ -131,9 +129,11 @@ void CommandBufferQueue::flush() noexcept {
 #endif
 
         SYSTRACE_NAME("waiting: CircularBuffer::flush()");
-        ASSERT_POSTCONDITION(!mPaused,
+
+        FILAMENT_CHECK_POSTCONDITION(!mPaused) <<
                 "CommandStream is full, but since the rendering thread is paused, "
-                "the buffer cannot flush and we will deadlock. Instead, abort.");
+                "the buffer cannot flush and we will deadlock. Instead, abort.";
+
         mCondition.wait(lock, [this, requiredSize]() -> bool {
             // TODO: on macOS, we need to call pumpEvents from time to time
             return mFreeSpace >= requiredSize;
@@ -149,10 +149,6 @@ std::vector<CommandBufferQueue::Range> CommandBufferQueue::waitForCommands() con
     while ((mCommandBuffersToExecute.empty() || mPaused) && !mExitRequested) {
         mCondition.wait(lock);
     }
-
-    ASSERT_PRECONDITION( mExitRequested == 0 || mExitRequested == EXIT_REQUESTED,
-            "mExitRequested is corrupted (value = 0x%08x)!", mExitRequested);
-
     return std::move(mCommandBuffersToExecute);
 }
 

filament/backend/src/HandleAllocator.cpp

@@ -113,9 +113,9 @@ HandleBase::HandleId HandleAllocator<P0, P1, P2>::allocateHandleSlow(size_t size
 
     HandleBase::HandleId id = (++mId) | HANDLE_HEAP_FLAG;
 
-    ASSERT_POSTCONDITION(mId < HANDLE_HEAP_FLAG,
+    FILAMENT_CHECK_POSTCONDITION(mId < HANDLE_HEAP_FLAG) <<
             "No more Handle ids available! This can happen if HandleAllocator arena has been full"
-            " for a while. Please increase FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB");
+            " for a while. Please increase FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB";
 
     mOverflowMap.emplace(id, p);
     lock.unlock();

filament/backend/src/VirtualMachineEnv.cpp

@@ -16,13 +16,23 @@
 
 #include "private/backend/VirtualMachineEnv.h"
 
+#include <utils/compiler.h>
 #include <utils/debug.h>
 
+#include <jni.h>
+
 namespace filament {
 
 JavaVM* VirtualMachineEnv::sVirtualMachine = nullptr;
 
-// This is called when the library is loaded. We need this to get a reference to the global VM
+/*
+ * This is typically called by filament_jni.so when it is loaded. If filament_jni.so is not used,
+ * then this must be called manually -- however, this is a problem because VirtualMachineEnv.h
+ * is currently private and part of backend.
+ * For now, we authorize this usage, but we will need to fix it; by making a proper public
+ * API for this.
+ */
+UTILS_PUBLIC
 UTILS_NOINLINE
 jint VirtualMachineEnv::JNI_OnLoad(JavaVM* vm) noexcept {
     JNIEnv* env = nullptr;

filament/backend/src/metal/MetalBlitter.mm

@@ -109,9 +109,8 @@ inline bool MTLSizeEqual(T a, T b) noexcept {
 MetalBlitter::MetalBlitter(MetalContext& context) noexcept : mContext(context) { }
 
 void MetalBlitter::blit(id<MTLCommandBuffer> cmdBuffer, const BlitArgs& args, const char* label) {
-
-    ASSERT_PRECONDITION(args.source.region.size.depth == args.destination.region.size.depth,
-            "Blitting requires the source and destination regions to have the same depth.");
+    FILAMENT_CHECK_PRECONDITION(args.source.region.size.depth == args.destination.region.size.depth)
+            << "Blitting requires the source and destination regions to have the same depth.";
 
     // Determine if the blit for color or depth are eligible to use a MTLBlitCommandEncoder.
     // blitFastPath returns true upon success.
@@ -327,7 +326,8 @@ id<MTLFunction> MetalBlitter::compileFragmentFunction(BlitFunctionKey key) const
             utils::slog.e << description << utils::io::endl;
         }
     }
-    ASSERT_POSTCONDITION(library && function, "Unable to compile fragment shader for MetalBlitter.");
+    FILAMENT_CHECK_POSTCONDITION(library && function)
+            << "Unable to compile fragment shader for MetalBlitter.";
 
     return function;
 }
@@ -352,7 +352,8 @@ id<MTLFunction> MetalBlitter::getBlitVertexFunction() {
             utils::slog.e << description << utils::io::endl;
         }
     }
-    ASSERT_POSTCONDITION(library && function, "Unable to compile vertex shader for MetalBlitter.");
+    FILAMENT_CHECK_POSTCONDITION(library && function)
+            << "Unable to compile vertex shader for MetalBlitter.";
 
     mVertexFunction = function;
 

filament/backend/src/metal/MetalBuffer.h

@@ -204,6 +204,15 @@ public:
 
 private:
 
+    enum class UploadStrategy {
+        POOL,
+        BUMP_ALLOCATOR,
+    };
+
+    void uploadWithPoolBuffer(void* src, size_t size, size_t byteOffset) const;
+    void uploadWithBumpAllocator(void* src, size_t size, size_t byteOffset) const;
+
+    UploadStrategy mUploadStrategy;
     TrackedMetalBuffer mBuffer;
     size_t mBufferSize = 0;
     void* mCpuBuffer = nullptr;

filament/backend/src/metal/MetalBuffer.mm

@@ -27,7 +27,16 @@ MetalPlatform* TrackedMetalBuffer::platform = nullptr;
 MetalPlatform* ScopedAllocationTimer::platform = nullptr;
 
 MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType, BufferUsage usage,
-        size_t size, bool forceGpuBuffer) : mBufferSize(size), mContext(context) {
+        size_t size, bool forceGpuBuffer)
+    : mBufferSize(size), mContext(context) {
+    const MetalBumpAllocator& allocator = *mContext.bumpAllocator;
+    // VERTEX is also used for index buffers
+    if (allocator.getCapacity() > 0 && bindingType == BufferObjectBinding::VERTEX) {
+        mUploadStrategy = UploadStrategy::BUMP_ALLOCATOR;
+    } else {
+        mUploadStrategy = UploadStrategy::POOL;
+    }
+
     // If the buffer is less than 4K in size and is updated frequently, we don't use an explicit
     // buffer. Instead, we use immediate command encoder methods like setVertexBytes:length:atIndex:.
     // This won't work for SSBOs, since they are read/write.
@@ -44,7 +53,8 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType,
         mBuffer = { [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate],
             TrackedMetalBuffer::Type::GENERIC };
     }
-    ASSERT_POSTCONDITION(mBuffer, "Could not allocate Metal buffer of size %zu.", size);
+    FILAMENT_CHECK_POSTCONDITION(mBuffer)
+            << "Could not allocate Metal buffer of size " << size << ".";
 }
 
 MetalBuffer::~MetalBuffer() {
@@ -57,37 +67,26 @@ void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
     if (size <= 0) {
         return;
     }
-    ASSERT_PRECONDITION(size + byteOffset <= mBufferSize,
-            "Attempting to copy %zu bytes into a buffer of size %zu at offset %zu",
-            size, mBufferSize, byteOffset);
+    FILAMENT_CHECK_PRECONDITION(size + byteOffset <= mBufferSize)
+            << "Attempting to copy " << size << " bytes into a buffer of size " << mBufferSize
+            << " at offset " << byteOffset;
+    // The copy blit requires that byteOffset be a multiple of 4.
+    FILAMENT_CHECK_PRECONDITION(!(byteOffset & 0x3)) << "byteOffset must be a multiple of 4";
 
-    // Either copy into the Metal buffer or into our cpu buffer.
+    // If we have a cpu buffer, we can directly copy into it.
     if (mCpuBuffer) {
         memcpy(static_cast<uint8_t*>(mCpuBuffer) + byteOffset, src, size);
         return;
     }
 
-    // Acquire a staging buffer to hold the contents of this update.
-    MetalBufferPool* bufferPool = mContext.bufferPool;
-    const MetalBufferPoolEntry* const staging = bufferPool->acquireBuffer(size);
-    memcpy(staging->buffer.get().contents, src, size);
-
-    // The blit below requires that byteOffset be a multiple of 4.
-    ASSERT_PRECONDITION(!(byteOffset & 0x3u), "byteOffset must be a multiple of 4");
-
-    // Encode a blit from the staging buffer into the private GPU buffer.
-    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
-    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
-    blitEncoder.label = @"Buffer upload blit";
-    [blitEncoder copyFromBuffer:staging->buffer.get()
-                   sourceOffset:0
-                       toBuffer:mBuffer.get()
-              destinationOffset:byteOffset
-                           size:size];
-    [blitEncoder endEncoding];
-    [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> cb) {
-        bufferPool->releaseBuffer(staging);
-    }];
+    switch (mUploadStrategy) {
+        case UploadStrategy::BUMP_ALLOCATOR:
+            uploadWithBumpAllocator(src, size, byteOffset);
+            break;
+        case UploadStrategy::POOL:
+            uploadWithPoolBuffer(src, size, byteOffset);
+            break;
+    }
 }
 
 void MetalBuffer::copyIntoBufferUnsynchronized(void* src, size_t size, size_t byteOffset) {
@@ -198,5 +197,42 @@ void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLCommandEncod
     }
 }
 
+void MetalBuffer::uploadWithPoolBuffer(void* src, size_t size, size_t byteOffset) const {
+    MetalBufferPool* bufferPool = mContext.bufferPool;
+    const MetalBufferPoolEntry* const staging = bufferPool->acquireBuffer(size);
+    memcpy(staging->buffer.get().contents, src, size);
+
+    // Encode a blit from the staging buffer into the private GPU buffer.
+    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
+    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
+    blitEncoder.label = @"Buffer upload blit - pool buffer";
+    [blitEncoder copyFromBuffer:staging->buffer.get()
+                   sourceOffset:0
+                       toBuffer:mBuffer.get()
+              destinationOffset:byteOffset
+                           size:size];
+    [blitEncoder endEncoding];
+    [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> cb) {
+        bufferPool->releaseBuffer(staging);
+    }];
+}
+
+void MetalBuffer::uploadWithBumpAllocator(void* src, size_t size, size_t byteOffset) const {
+    MetalBumpAllocator& allocator = *mContext.bumpAllocator;
+    auto [buffer, offset] = allocator.allocateStagingArea(size);
+    memcpy(static_cast<char*>(buffer.contents) + offset, src, size);
+
+    // Encode a blit from the staging buffer into the private GPU buffer.
+    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
+    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
+    blitEncoder.label = @"Buffer upload blit - bump allocator";
+    [blitEncoder copyFromBuffer:buffer
+                   sourceOffset:offset
+                       toBuffer:mBuffer.get()
+              destinationOffset:byteOffset
+                           size:size];
+    [blitEncoder endEncoding];
+}
+
 } // namespace backend
 } // namespace filament

filament/backend/src/metal/MetalBufferPool.h

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

filament/backend/src/metal/MetalBufferPool.mm

@@ -48,7 +48,8 @@ MetalBufferPoolEntry const* MetalBufferPool::acquireBuffer(size_t numBytes) {
         buffer = [mContext.device newBufferWithLength:numBytes
                                               options:MTLResourceStorageModeShared];
     }
-    ASSERT_POSTCONDITION(buffer, "Could not allocate Metal staging buffer of size %zu.", numBytes);
+    FILAMENT_CHECK_POSTCONDITION(buffer)
+            << "Could not allocate Metal staging buffer of size " << numBytes << ".";
     MetalBufferPoolEntry* stage = new MetalBufferPoolEntry {
         .buffer = { buffer, TrackedMetalBuffer::Type::STAGING },
         .capacity = numBytes,
@@ -115,5 +116,38 @@ void MetalBufferPool::reset() noexcept {
     mFreeStages.clear();
 }
 
+MetalBumpAllocator::MetalBumpAllocator(id<MTLDevice> device, size_t capacity)
+    : mDevice(device), mCapacity(capacity) {
+    if (mCapacity > 0) {
+        mCurrentUploadBuffer = { [device newBufferWithLength:capacity options:MTLStorageModeShared],
+            TrackedMetalBuffer::Type::STAGING };
+    }
+}
+
+std::pair<id<MTLBuffer>, size_t> MetalBumpAllocator::allocateStagingArea(size_t size) {
+    if (size == 0) {
+        return { nil, 0 };
+    }
+    if (size > mCapacity) {
+        return { [mDevice newBufferWithLength:size options:MTLStorageModeShared], 0 };
+    }
+    assert_invariant(mCurrentUploadBuffer);
+
+    // Align the head to a 4-byte boundary.
+    mHead = (mHead + 3) & ~3;
+
+    if (UTILS_LIKELY(mHead + size <= mCapacity)) {
+        const size_t oldHead = mHead;
+        mHead += size;
+        return { mCurrentUploadBuffer.get(), oldHead };
+    }
+
+    // We're finished with the current allocation.
+    mCurrentUploadBuffer = { [mDevice newBufferWithLength:mCapacity options:MTLStorageModeShared],
+        TrackedMetalBuffer::Type::STAGING };
+
+    return { mCurrentUploadBuffer.get(), 0 };
+}
+
 } // namespace backend
 } // namespace filament

filament/backend/src/metal/MetalContext.h

@@ -44,6 +44,7 @@ namespace backend {
 class MetalDriver;
 class MetalBlitter;
 class MetalBufferPool;
+class MetalBumpAllocator;
 class MetalRenderTarget;
 class MetalSamplerGroup;
 class MetalSwapChain;
@@ -141,6 +142,7 @@ struct MetalContext {
     utils::FixedCircularBuffer<Handle<HwTexture>> texturesToDestroy;
 
     MetalBufferPool* bufferPool;
+    MetalBumpAllocator* bumpAllocator;
 
     MetalSwapChain* currentDrawSwapChain = nil;
     MetalSwapChain* currentReadSwapChain = nil;

filament/backend/src/metal/MetalContext.mm

@@ -113,7 +113,8 @@ id<MTLCommandBuffer> getPendingCommandBuffer(MetalContext* context) {
             }
         }
     }];
-    ASSERT_POSTCONDITION(context->pendingCommandBuffer, "Could not obtain command buffer.");
+    FILAMENT_CHECK_POSTCONDITION(context->pendingCommandBuffer)
+            << "Could not obtain command buffer.";
     return context->pendingCommandBuffer;
 }
 

filament/backend/src/metal/MetalDriver.mm

@@ -171,6 +171,8 @@ MetalDriver::MetalDriver(MetalPlatform* platform, const Platform::DriverConfig&
     mContext->samplerStateCache.setDevice(mContext->device);
     mContext->argumentEncoderCache.setDevice(mContext->device);
     mContext->bufferPool = new MetalBufferPool(*mContext);
+    mContext->bumpAllocator =
+            new MetalBumpAllocator(mContext->device, driverConfig.metalUploadBufferSizeBytes);
     mContext->blitter = new MetalBlitter(*mContext);
 
     if (@available(iOS 12, *)) {
@@ -181,7 +183,8 @@ MetalDriver::MetalDriver(MetalPlatform* platform, const Platform::DriverConfig&
 
     CVReturn success = CVMetalTextureCacheCreate(kCFAllocatorDefault, nullptr, mContext->device,
             nullptr, &mContext->textureCache);
-    ASSERT_POSTCONDITION(success == kCVReturnSuccess, "Could not create Metal texture cache.");
+    FILAMENT_CHECK_POSTCONDITION(success == kCVReturnSuccess)
+            << "Could not create Metal texture cache.";
 
     if (@available(iOS 12, *)) {
         dispatch_queue_t queue = dispatch_get_global_queue(QOS_CLASS_DEFAULT, 0);
@@ -208,6 +211,7 @@ MetalDriver::~MetalDriver() noexcept {
     mContext->emptyTexture = nil;
     CFRelease(mContext->textureCache);
     delete mContext->bufferPool;
+    delete mContext->bumpAllocator;
     delete mContext->blitter;
     delete mContext->timerQueryImpl;
     delete mContext->shaderCompiler;
@@ -289,14 +293,14 @@ void MetalDriver::endFrame(uint32_t frameId) {
 }
 
 void MetalDriver::flush(int) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-                        "flush must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "flush must be called outside of a render pass.";
     submitPendingCommands(mContext);
 }
 
 void MetalDriver::finish(int) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "finish must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "finish must be called outside of a render pass.";
     // Wait for all frames to finish by submitting and waiting on a dummy command buffer.
     submitPendingCommands(mContext);
     id<MTLCommandBuffer> oneOffBuffer = [mContext->commandQueue commandBuffer];
@@ -357,19 +361,19 @@ void MetalDriver::importTextureR(Handle<HwTexture> th, intptr_t i,
         TextureFormat format, uint8_t samples, uint32_t width, uint32_t height,
         uint32_t depth, TextureUsage usage) {
     id<MTLTexture> metalTexture = (id<MTLTexture>) CFBridgingRelease((void*) i);
-    ASSERT_PRECONDITION(metalTexture.width == width,
-            "Imported id<MTLTexture> width (%d) != Filament texture width (%d)",
-            metalTexture.width, width);
-    ASSERT_PRECONDITION(metalTexture.height == height,
-            "Imported id<MTLTexture> height (%d) != Filament texture height (%d)",
-            metalTexture.height, height);
-    ASSERT_PRECONDITION(metalTexture.mipmapLevelCount == levels,
-            "Imported id<MTLTexture> levels (%d) != Filament texture levels (%d)",
-            metalTexture.mipmapLevelCount, levels);
+    FILAMENT_CHECK_PRECONDITION(metalTexture.width == width)
+            << "Imported id<MTLTexture> width (" << metalTexture.width
+            << ") != Filament texture width (" << width << ")";
+    FILAMENT_CHECK_PRECONDITION(metalTexture.height == height)
+            << "Imported id<MTLTexture> height (" << metalTexture.height
+            << ") != Filament texture height (" << height << ")";
+    FILAMENT_CHECK_PRECONDITION(metalTexture.mipmapLevelCount == levels)
+            << "Imported id<MTLTexture> levels (" << metalTexture.mipmapLevelCount
+            << ") != Filament texture levels (" << levels << ")";
     MTLTextureType filamentMetalType = getMetalType(target);
-    ASSERT_PRECONDITION(metalTexture.textureType == filamentMetalType,
-            "Imported id<MTLTexture> type (%d) != Filament texture type (%d)",
-            metalTexture.textureType, filamentMetalType);
+    FILAMENT_CHECK_PRECONDITION(metalTexture.textureType == filamentMetalType)
+            << "Imported id<MTLTexture> type (" << metalTexture.textureType
+            << ") != Filament texture type (" << filamentMetalType << ")";
     mContext->textures.insert(construct_handle<MetalTexture>(th, *mContext,
         target, levels, format, samples, width, height, depth, usage, metalTexture));
 }
@@ -398,8 +402,8 @@ void MetalDriver::createRenderTargetR(Handle<HwRenderTarget> rth,
         TargetBufferFlags targetBufferFlags, uint32_t width, uint32_t height,
         uint8_t samples, uint8_t layerCount, MRT color,
         TargetBufferInfo depth, TargetBufferInfo stencil) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "createRenderTarget must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "createRenderTarget must be called outside of a render pass.";
     // Clamp sample count to what the device supports.
     auto& sc = mContext->sampleCountLookup;
     samples = sc[std::min(MAX_SAMPLE_COUNT, samples)];
@@ -410,33 +414,33 @@ void MetalDriver::createRenderTargetR(Handle<HwRenderTarget> rth,
             continue;
         }
         const auto& buffer = color[i];
-        ASSERT_PRECONDITION(buffer.handle,
-                "The COLOR%u flag was specified, but invalid color handle provided.", i);
+        FILAMENT_CHECK_PRECONDITION(buffer.handle)
+                << "The COLOR" << i << " flag was specified, but invalid color handle provided.";
         auto colorTexture = handle_cast<MetalTexture>(buffer.handle);
-        ASSERT_PRECONDITION(colorTexture->getMtlTextureForWrite(),
-                "Color texture passed to render target has no texture allocation");
+        FILAMENT_CHECK_PRECONDITION(colorTexture->getMtlTextureForWrite())
+                << "Color texture passed to render target has no texture allocation";
         colorTexture->extendLodRangeTo(buffer.level);
         colorAttachments[i] = { colorTexture, color[i].level, color[i].layer };
     }
 
     MetalRenderTarget::Attachment depthAttachment = {};
     if (any(targetBufferFlags & TargetBufferFlags::DEPTH)) {
-        ASSERT_PRECONDITION(depth.handle,
-                "The DEPTH flag was specified, but invalid depth handle provided.");
+        FILAMENT_CHECK_PRECONDITION(depth.handle)
+                << "The DEPTH flag was specified, but invalid depth handle provided.";
         auto depthTexture = handle_cast<MetalTexture>(depth.handle);
-        ASSERT_PRECONDITION(depthTexture->getMtlTextureForWrite(),
-                "Depth texture passed to render target has no texture allocation.");
+        FILAMENT_CHECK_PRECONDITION(depthTexture->getMtlTextureForWrite())
+                << "Depth texture passed to render target has no texture allocation.";
         depthTexture->extendLodRangeTo(depth.level);
         depthAttachment = { depthTexture, depth.level, depth.layer };
     }
 
     MetalRenderTarget::Attachment stencilAttachment = {};
     if (any(targetBufferFlags & TargetBufferFlags::STENCIL)) {
-        ASSERT_PRECONDITION(stencil.handle,
-                "The STENCIL flag was specified, but invalid stencil handle provided.");
+        FILAMENT_CHECK_PRECONDITION(stencil.handle)
+                << "The STENCIL flag was specified, but invalid stencil handle provided.";
         auto stencilTexture = handle_cast<MetalTexture>(stencil.handle);
-        ASSERT_PRECONDITION(stencilTexture->getMtlTextureForWrite(),
-                "Stencil texture passed to render target has no texture allocation.");
+        FILAMENT_CHECK_PRECONDITION(stencilTexture->getMtlTextureForWrite())
+                << "Stencil texture passed to render target has no texture allocation.";
         stencilTexture->extendLodRangeTo(stencil.level);
         stencilAttachment = { stencilTexture, stencil.level, stencil.layer };
     }
@@ -881,8 +885,8 @@ void MetalDriver::updateIndexBuffer(Handle<HwIndexBuffer> ibh, BufferDescriptor&
 
 void MetalDriver::updateBufferObject(Handle<HwBufferObject> boh, BufferDescriptor&& data,
         uint32_t byteOffset) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "updateBufferObject must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "updateBufferObject must be called outside of a render pass.";
     auto* bo = handle_cast<MetalBufferObject>(boh);
     bo->updateBuffer(data.buffer, data.size, byteOffset);
     scheduleDestroy(std::move(data));
@@ -921,8 +925,8 @@ void MetalDriver::update3DImage(Handle<HwTexture> th, uint32_t level,
         uint32_t xoffset, uint32_t yoffset, uint32_t zoffset,
         uint32_t width, uint32_t height, uint32_t depth,
         PixelBufferDescriptor&& data) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "update3DImage must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "update3DImage must be called outside of a render pass.";
     auto tex = handle_cast<MetalTexture>(th);
     tex->loadImage(level, MTLRegionMake3D(xoffset, yoffset, zoffset, width, height, depth), data);
     scheduleDestroy(std::move(data));
@@ -938,15 +942,15 @@ void MetalDriver::setupExternalImage(void* image) {
 }
 
 void MetalDriver::setExternalImage(Handle<HwTexture> th, void* image) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "setExternalImage must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "setExternalImage must be called outside of a render pass.";
     auto texture = handle_cast<MetalTexture>(th);
     texture->externalImage.set((CVPixelBufferRef) image);
 }
 
 void MetalDriver::setExternalImagePlane(Handle<HwTexture> th, void* image, uint32_t plane) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "setExternalImagePlane must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "setExternalImagePlane must be called outside of a render pass.";
     auto texture = handle_cast<MetalTexture>(th);
     texture->externalImage.set((CVPixelBufferRef) image, plane);
 }
@@ -961,15 +965,15 @@ TimerQueryResult MetalDriver::getTimerQueryValue(Handle<HwTimerQuery> tqh, uint6
 }
 
 void MetalDriver::generateMipmaps(Handle<HwTexture> th) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-                        "generateMipmaps must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "generateMipmaps must be called outside of a render pass.";
     auto tex = handle_cast<MetalTexture>(th);
     tex->generateMipmaps();
 }
 
 void MetalDriver::updateSamplerGroup(Handle<HwSamplerGroup> sbh, BufferDescriptor&& data) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "updateSamplerGroup must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "updateSamplerGroup must be called outside of a render pass.";
 
     auto sb = handle_cast<MetalSamplerGroup>(sbh);
     assert_invariant(sb->size == data.size / sizeof(SamplerDescriptor));
@@ -1261,8 +1265,8 @@ void MetalDriver::bindSamplers(uint32_t index, Handle<HwSamplerGroup> sbh) {
 
 void MetalDriver::setPushConstant(backend::ShaderStage stage, uint8_t index,
         backend::PushConstantVariant value) {
-    ASSERT_PRECONDITION(
-            isInRenderPass(mContext), "setPushConstant must be called inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(isInRenderPass(mContext))
+            << "setPushConstant must be called inside a render pass.";
     assert_invariant(static_cast<size_t>(stage) < mContext->currentPushConstants.size());
     MetalPushConstantBuffer& pushConstants =
             mContext->currentPushConstants[static_cast<size_t>(stage)];
@@ -1319,8 +1323,8 @@ void MetalDriver::stopCapture(int) {
 
 void MetalDriver::readPixels(Handle<HwRenderTarget> src, uint32_t x, uint32_t y, uint32_t width,
         uint32_t height, PixelBufferDescriptor&& data) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-                        "readPixels must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "readPixels must be called outside of a render pass.";
 
     auto srcTarget = handle_cast<MetalRenderTarget>(src);
     // We always readPixels from the COLOR0 attachment.
@@ -1334,17 +1338,19 @@ void MetalDriver::readPixels(Handle<HwRenderTarget> src, uint32_t x, uint32_t y,
     width = std::min(static_cast<uint32_t>(srcTextureSize.width), width);
 
     const MTLPixelFormat format = getMetalFormat(data.format, data.type);
-    ASSERT_PRECONDITION(format != MTLPixelFormatInvalid,
-            "The chosen combination of PixelDataFormat (%d) and PixelDataType (%d) is not supported for "
-            "readPixels.", (int) data.format, (int) data.type);
+    FILAMENT_CHECK_PRECONDITION(format != MTLPixelFormatInvalid)
+            << "The chosen combination of PixelDataFormat (" << (int)data.format
+            << ") and PixelDataType (" << (int)data.type
+            << ") is not supported for "
+               "readPixels.";
 
     const bool formatConversionNecessary = srcTexture.pixelFormat != format;
 
     // TODO: MetalBlitter does not currently support format conversions to integer types.
     // The format and type must match the source pixel format exactly.
-    ASSERT_PRECONDITION(!formatConversionNecessary || !isMetalFormatInteger(format),
-            "readPixels does not support integer format conversions from MTLPixelFormat (%d) to (%d).",
-            (int) srcTexture.pixelFormat, (int) format);
+    FILAMENT_CHECK_PRECONDITION(!formatConversionNecessary || !isMetalFormatInteger(format))
+            << "readPixels does not support integer format conversions from MTLPixelFormat ("
+            << (int)srcTexture.pixelFormat << ") to (" << (int)format << ").";
 
     MTLTextureDescriptor* textureDescriptor =
             [MTLTextureDescriptor texture2DDescriptorWithPixelFormat:format
@@ -1410,31 +1416,31 @@ void MetalDriver::resolve(
     assert_invariant(srcTexture);
     assert_invariant(dstTexture);
 
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder == nil,
-            "resolve() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder == nil)
+            << "resolve() cannot be invoked inside a render pass.";
 
-    ASSERT_PRECONDITION(
-            dstTexture->width == srcTexture->width && dstTexture->height == srcTexture->height,
-            "invalid resolve: src and dst sizes don't match");
+    FILAMENT_CHECK_PRECONDITION(
+            dstTexture->width == srcTexture->width && dstTexture->height == srcTexture->height)
+            << "invalid resolve: src and dst sizes don't match";
 
-    ASSERT_PRECONDITION(srcTexture->samples > 1 && dstTexture->samples == 1,
-            "invalid resolve: src.samples=%u, dst.samples=%u",
-            +srcTexture->samples, +dstTexture->samples);
+    FILAMENT_CHECK_PRECONDITION(srcTexture->samples > 1 && dstTexture->samples == 1)
+            << "invalid resolve: src.samples=" << +srcTexture->samples
+            << ", dst.samples=" << +dstTexture->samples;
 
-    ASSERT_PRECONDITION(srcTexture->format == dstTexture->format,
-            "src and dst texture format don't match");
+    FILAMENT_CHECK_PRECONDITION(srcTexture->format == dstTexture->format)
+            << "src and dst texture format don't match";
 
-    ASSERT_PRECONDITION(!isDepthFormat(srcTexture->format),
-            "can't resolve depth formats");
+    FILAMENT_CHECK_PRECONDITION(!isDepthFormat(srcTexture->format))
+            << "can't resolve depth formats";
 
-    ASSERT_PRECONDITION(!isStencilFormat(srcTexture->format),
-            "can't resolve stencil formats");
+    FILAMENT_CHECK_PRECONDITION(!isStencilFormat(srcTexture->format))
+            << "can't resolve stencil formats";
 
-    ASSERT_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST),
-            "texture doesn't have BLIT_DST");
+    FILAMENT_CHECK_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST))
+            << "texture doesn't have BLIT_DST";
 
-    ASSERT_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC),
-            "texture doesn't have BLIT_SRC");
+    FILAMENT_CHECK_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC))
+            << "texture doesn't have BLIT_SRC";
 
     // FIXME: on metal the blit() call below always take the slow path (using a shader)
 
@@ -1459,21 +1465,22 @@ void MetalDriver::blit(
     assert_invariant(srcTexture);
     assert_invariant(dstTexture);
 
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder == nil,
-            "blit() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder == nil)
+            << "blit() cannot be invoked inside a render pass.";
 
-    ASSERT_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST),
-            "texture doesn't have BLIT_DST");
+    FILAMENT_CHECK_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST))
+            << "texture doesn't have BLIT_DST";
 
-    ASSERT_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC),
-            "texture doesn't have BLIT_SRC");
+    FILAMENT_CHECK_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC))
+            << "texture doesn't have BLIT_SRC";
 
-    ASSERT_PRECONDITION(srcTexture->format == dstTexture->format,
-            "src and dst texture format don't match");
+    FILAMENT_CHECK_PRECONDITION(srcTexture->format == dstTexture->format)
+            << "src and dst texture format don't match";
 
-    ASSERT_PRECONDITION(isBlitableTextureType(srcTexture->getMtlTextureForRead().textureType) &&
-                        isBlitableTextureType(dstTexture->getMtlTextureForWrite().textureType),
-            "Metal does not support blitting to/from non-2D textures.");
+    FILAMENT_CHECK_PRECONDITION(
+            isBlitableTextureType(srcTexture->getMtlTextureForRead().textureType) &&
+            isBlitableTextureType(dstTexture->getMtlTextureForWrite().textureType))
+            << "Metal does not support blitting to/from non-2D textures.";
 
     MetalBlitter::BlitArgs args{};
     args.filter = SamplerMagFilter::NEAREST;
@@ -1511,18 +1518,18 @@ void MetalDriver::blitDEPRECATED(TargetBufferFlags buffers,
     // It is called between beginFrame and endFrame, but should never be called in the middle of
     // a render pass.
 
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder == nil,
-            "blitDEPRECATED() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder == nil)
+            << "blitDEPRECATED() cannot be invoked inside a render pass.";
 
     auto srcTarget = handle_cast<MetalRenderTarget>(src);
     auto dstTarget = handle_cast<MetalRenderTarget>(dst);
 
-    ASSERT_PRECONDITION(buffers == TargetBufferFlags::COLOR0,
-            "blitDEPRECATED only supports COLOR0");
+    FILAMENT_CHECK_PRECONDITION(buffers == TargetBufferFlags::COLOR0)
+            << "blitDEPRECATED only supports COLOR0";
 
-    ASSERT_PRECONDITION(srcRect.left >= 0 && srcRect.bottom >= 0 &&
-                        dstRect.left >= 0 && dstRect.bottom >= 0,
-            "Source and destination rects must be positive.");
+    FILAMENT_CHECK_PRECONDITION(
+            srcRect.left >= 0 && srcRect.bottom >= 0 && dstRect.left >= 0 && dstRect.bottom >= 0)
+            << "Source and destination rects must be positive.";
 
     auto isBlitableTextureType = [](MTLTextureType t) {
         return t == MTLTextureType2D || t == MTLTextureType2DMultisample ||
@@ -1534,9 +1541,10 @@ void MetalDriver::blitDEPRECATED(TargetBufferFlags buffers,
     MetalRenderTarget::Attachment const dstColorAttachment = dstTarget->getDrawColorAttachment(0);
 
     if (srcColorAttachment && dstColorAttachment) {
-        ASSERT_PRECONDITION(isBlitableTextureType(srcColorAttachment.getTexture().textureType) &&
-                            isBlitableTextureType(dstColorAttachment.getTexture().textureType),
-                           "Metal does not support blitting to/from non-2D textures.");
+        FILAMENT_CHECK_PRECONDITION(
+                isBlitableTextureType(srcColorAttachment.getTexture().textureType) &&
+                isBlitableTextureType(dstColorAttachment.getTexture().textureType))
+                << "Metal does not support blitting to/from non-2D textures.";
 
         MetalBlitter::BlitArgs args{};
         args.filter = filter;
@@ -1648,8 +1656,8 @@ void MetalDriver::finalizeSamplerGroup(MetalSamplerGroup* samplerGroup) {
 }
 
 void MetalDriver::bindPipeline(PipelineState const& ps) {
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder != nullptr,
-            "bindPipeline() without a valid command encoder.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder != nullptr)
+            << "bindPipeline() without a valid command encoder.";
 
     MetalVertexBufferInfo const* const vbi =
             handle_cast<MetalVertexBufferInfo>(ps.vertexBufferInfo);
@@ -1821,8 +1829,8 @@ void MetalDriver::bindPipeline(PipelineState const& ps) {
 }
 
 void MetalDriver::bindRenderPrimitive(Handle<HwRenderPrimitive> rph) {
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder != nullptr,
-            "bindRenderPrimitive() without a valid command encoder.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder != nullptr)
+            << "bindRenderPrimitive() without a valid command encoder.";
 
     // Bind the user vertex buffers.
     MetalBuffer* vertexBuffers[MAX_VERTEX_BUFFER_COUNT] = {};
@@ -1858,8 +1866,8 @@ void MetalDriver::bindRenderPrimitive(Handle<HwRenderPrimitive> rph) {
 }
 
 void MetalDriver::draw2(uint32_t indexOffset, uint32_t indexCount, uint32_t instanceCount) {
-    ASSERT_PRECONDITION(mContext->currentRenderPassEncoder != nullptr,
-            "draw() without a valid command encoder.");
+    FILAMENT_CHECK_PRECONDITION(mContext->currentRenderPassEncoder != nullptr)
+            << "draw() without a valid command encoder.";
 
     // Bind uniform buffers.
     MetalBuffer* uniformsToBind[Program::UNIFORM_BINDING_COUNT] = { nil };
@@ -1908,8 +1916,8 @@ void MetalDriver::draw(PipelineState ps, Handle<HwRenderPrimitive> rph,
 }
 
 void MetalDriver::dispatchCompute(Handle<HwProgram> program, math::uint3 workGroupCount) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "dispatchCompute must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "dispatchCompute must be called outside of a render pass.";
 
     auto mtlProgram = handle_cast<MetalProgram>(program);
 
@@ -2009,15 +2017,15 @@ void MetalDriver::scissor(Viewport scissorBox) {
 }
 
 void MetalDriver::beginTimerQuery(Handle<HwTimerQuery> tqh) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "beginTimerQuery must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "beginTimerQuery must be called outside of a render pass.";
     auto* tq = handle_cast<MetalTimerQuery>(tqh);
     mContext->timerQueryImpl->beginTimeElapsedQuery(tq);
 }
 
 void MetalDriver::endTimerQuery(Handle<HwTimerQuery> tqh) {
-    ASSERT_PRECONDITION(!isInRenderPass(mContext),
-            "endTimerQuery must be called outside of a render pass.");
+    FILAMENT_CHECK_PRECONDITION(!isInRenderPass(mContext))
+            << "endTimerQuery must be called outside of a render pass.";
     auto* tq = handle_cast<MetalTimerQuery>(tqh);
     mContext->timerQueryImpl->endTimeElapsedQuery(tq);
 }

filament/backend/src/metal/MetalEnums.h

@@ -71,7 +71,7 @@ constexpr inline MTLIndexType getIndexType(size_t elementSize) noexcept {
     } else if (elementSize == 4) {
         return MTLIndexTypeUInt32;
     }
-    ASSERT_POSTCONDITION(false, "Index element size not supported.");
+    FILAMENT_CHECK_POSTCONDITION(false) << "Index element size not supported.";
 }
 
 constexpr inline MTLVertexFormat getMetalFormat(ElementType type, bool normalized) noexcept {
@@ -100,7 +100,7 @@ constexpr inline MTLVertexFormat getMetalFormat(ElementType type, bool normalize
             case ElementType::SHORT4: return MTLVertexFormatShort4Normalized;
             case ElementType::USHORT4: return MTLVertexFormatUShort4Normalized;
             default:
-                ASSERT_POSTCONDITION(false, "Normalized format does not exist.");
+                FILAMENT_CHECK_POSTCONDITION(false) << "Normalized format does not exist.";
                 return MTLVertexFormatInvalid;
         }
     }
@@ -326,7 +326,8 @@ constexpr inline MTLCullMode getMetalCullMode(CullingMode cullMode) noexcept {
         case CullingMode::FRONT: return MTLCullModeFront;
         case CullingMode::BACK: return MTLCullModeBack;
         case CullingMode::FRONT_AND_BACK:
-            ASSERT_POSTCONDITION(false, "FRONT_AND_BACK culling is not supported in Metal.");
+            FILAMENT_CHECK_POSTCONDITION(false)
+                    << "FRONT_AND_BACK culling is not supported in Metal.";
     }
 }
 

filament/backend/src/metal/MetalExternalImage.mm

@@ -29,7 +29,7 @@
         auto description = [error.localizedDescription cStringUsingEncoding:NSUTF8StringEncoding]; \
         utils::slog.e << description << utils::io::endl;                                           \
     }                                                                                              \
-    ASSERT_POSTCONDITION(error == nil, message);
+    FILAMENT_CHECK_POSTCONDITION(error == nil) << message;
 
 namespace filament {
 namespace backend {
@@ -86,14 +86,14 @@ void MetalExternalImage::set(CVPixelBufferRef image) noexcept {
     }
 
     OSType formatType = CVPixelBufferGetPixelFormatType(image);
-    ASSERT_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA ||
-                         formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
-            "Metal external images must be in either 32BGRA or 420f format.");
+    FILAMENT_CHECK_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA ||
+            formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
+            << "Metal external images must be in either 32BGRA or 420f format.";
 
     size_t planeCount = CVPixelBufferGetPlaneCount(image);
-    ASSERT_POSTCONDITION(planeCount == 0 || planeCount == 2,
-            "The Metal backend does not support images with plane counts of %d.", planeCount);
-
+    FILAMENT_CHECK_POSTCONDITION(planeCount == 0 || planeCount == 2)
+            << "The Metal backend does not support images with plane counts of " << planeCount
+            << ".";
 
     if (planeCount == 0) {
         mImage = image;
@@ -138,8 +138,8 @@ void MetalExternalImage::set(CVPixelBufferRef image, size_t plane) noexcept {
     }
 
     const OSType formatType = CVPixelBufferGetPixelFormatType(image);
-    ASSERT_POSTCONDITION(formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
-            "Metal planar external images must be in the 420f format.");
+    FILAMENT_CHECK_POSTCONDITION(formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
+            << "Metal planar external images must be in the 420f format.";
 
     mImage = image;
 
@@ -191,8 +191,8 @@ CVMetalTextureRef MetalExternalImage::createTextureFromImage(CVPixelBufferRef im
     CVMetalTextureRef texture;
     CVReturn result = CVMetalTextureCacheCreateTextureFromImage(kCFAllocatorDefault,
             mContext.textureCache, image, nullptr, format, width, height, plane, &texture);
-    ASSERT_POSTCONDITION(result == kCVReturnSuccess,
-            "Could not create a CVMetalTexture from CVPixelBuffer.");
+    FILAMENT_CHECK_POSTCONDITION(result == kCVReturnSuccess)
+            << "Could not create a CVMetalTexture from CVPixelBuffer.";
 
     return texture;
 }
@@ -203,8 +203,8 @@ void MetalExternalImage::shutdown(MetalContext& context) noexcept {
 
 void MetalExternalImage::assertWritableImage(CVPixelBufferRef image) {
     OSType formatType = CVPixelBufferGetPixelFormatType(image);
-    ASSERT_PRECONDITION(formatType == kCVPixelFormatType_32BGRA,
-            "Metal SwapChain images must be in the 32BGRA format.");
+    FILAMENT_CHECK_PRECONDITION(formatType == kCVPixelFormatType_32BGRA)
+            << "Metal SwapChain images must be in the 32BGRA format.";
 }
 
 void MetalExternalImage::unset() {

filament/backend/src/metal/MetalHandles.h

@@ -109,6 +109,7 @@ private:
     NSUInteger headlessWidth = 0;
     NSUInteger headlessHeight = 0;
     CAMetalLayer* layer = nullptr;
+    std::shared_ptr<std::mutex> layerDrawableMutex;
     MetalExternalImage externalImage;
     SwapChainType type;
 

filament/backend/src/metal/MetalHandles.mm

@@ -73,6 +73,7 @@ MetalSwapChain::MetalSwapChain(MetalContext& context, CAMetalLayer* nativeWindow
     : context(context),
       depthStencilFormat(decideDepthStencilFormat(flags)),
       layer(nativeWindow),
+      layerDrawableMutex(std::make_shared<std::mutex>()),
       externalImage(context),
       type(SwapChainType::CAMETALLAYER) {
 
@@ -174,14 +175,24 @@ id<MTLTexture> MetalSwapChain::acquireDrawable() {
     }
 
     assert_invariant(isCaMetalLayer());
-    drawable = [layer nextDrawable];
 
-    ASSERT_POSTCONDITION(drawable != nil, "Could not obtain drawable.");
+    // CAMetalLayer's drawable pool is not thread safe. Use a mutex when
+    // calling -nextDrawable, or when releasing the last known reference
+    // to any CAMetalDrawable returned from a previous -nextDrawable.
+    {
+        std::lock_guard<std::mutex> lock(*layerDrawableMutex);
+        drawable = [layer nextDrawable];
+    }
+
+    FILAMENT_CHECK_POSTCONDITION(drawable != nil) << "Could not obtain drawable.";
     return drawable.texture;
 }
 
 void MetalSwapChain::releaseDrawable() {
-    drawable = nil;
+    if (drawable) {
+        std::lock_guard<std::mutex> lock(*layerDrawableMutex);
+        drawable = nil;
+    }
 }
 
 id<MTLTexture> MetalSwapChain::acquireDepthTexture() {
@@ -256,9 +267,11 @@ public:
     PresentDrawableData(const PresentDrawableData&) = delete;
     PresentDrawableData& operator=(const PresentDrawableData&) = delete;
 
-    static PresentDrawableData* create(id<CAMetalDrawable> drawable, MetalDriver* driver) {
+    static PresentDrawableData* create(id<CAMetalDrawable> drawable,
+            std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver) {
+        assert_invariant(drawableMutex);
         assert_invariant(driver);
-        return new PresentDrawableData(drawable, driver);
+        return new PresentDrawableData(drawable, drawableMutex, driver);
     }
 
     static void maybePresentAndDestroyAsync(PresentDrawableData* that, bool shouldPresent) {
@@ -277,16 +290,22 @@ public:
     }
 
 private:
-    PresentDrawableData(id<CAMetalDrawable> drawable, MetalDriver* driver)
-        : mDrawable(drawable), mDriver(driver) {}
+    PresentDrawableData(id<CAMetalDrawable> drawable, std::shared_ptr<std::mutex> drawableMutex,
+            MetalDriver* driver)
+        : mDrawable(drawable), mDrawableMutex(drawableMutex), mDriver(driver) {}
 
     static void cleanupAndDestroy(PresentDrawableData *that) {
-        that->mDrawable = nil;
+        if (that->mDrawable) {
+            std::lock_guard<std::mutex> lock(*(that->mDrawableMutex));
+            that->mDrawable = nil;
+        }
+        that->mDrawableMutex.reset();
         that->mDriver = nullptr;
         delete that;
     }
 
     id<CAMetalDrawable> mDrawable;
+    std::shared_ptr<std::mutex> mDrawableMutex;
     MetalDriver* mDriver = nullptr;
 };
 
@@ -304,8 +323,8 @@ void MetalSwapChain::scheduleFrameScheduledCallback() {
 
     struct Callback {
         Callback(std::shared_ptr<FrameScheduledCallback> callback, id<CAMetalDrawable> drawable,
-                MetalDriver* driver)
-            : f(callback), data(PresentDrawableData::create(drawable, driver)) {}
+                 std::shared_ptr<std::mutex> drawableMutex, MetalDriver* driver)
+            : f(callback), data(PresentDrawableData::create(drawable, drawableMutex, driver)) {}
         std::shared_ptr<FrameScheduledCallback> f;
         // PresentDrawableData* is destroyed by maybePresentAndDestroyAsync() later.
         std::unique_ptr<PresentDrawableData> data;
@@ -320,8 +339,8 @@ void MetalSwapChain::scheduleFrameScheduledCallback() {
 
     // This callback pointer will be captured by the block. Even if the scheduled handler is never
     // called, the unique_ptr will still ensure we don't leak memory.
-    __block auto callback =
-            std::make_unique<Callback>(frameScheduled.callback, drawable, context.driver);
+    __block auto callback = std::make_unique<Callback>(
+        frameScheduled.callback, drawable, layerDrawableMutex, context.driver);
 
     backend::CallbackHandler* handler = frameScheduled.handler;
     MetalDriver* driver = context.driver;
@@ -493,15 +512,16 @@ MetalTexture::MetalTexture(MetalContext& context, SamplerType target, uint8_t le
         externalImage(context, r, g, b, a) {
 
     devicePixelFormat = decidePixelFormat(&context, format);
-    ASSERT_POSTCONDITION(devicePixelFormat != MTLPixelFormatInvalid, "Texture format not supported.");
+    FILAMENT_CHECK_POSTCONDITION(devicePixelFormat != MTLPixelFormatInvalid)
+            << "Texture format not supported.";
 
     const BOOL mipmapped = levels > 1;
     const BOOL multisampled = samples > 1;
 
 #if defined(IOS)
     const BOOL textureArray = target == SamplerType::SAMPLER_2D_ARRAY;
-    ASSERT_PRECONDITION(!textureArray || !multisampled,
-            "iOS does not support multisampled texture arrays.");
+    FILAMENT_CHECK_PRECONDITION(!textureArray || !multisampled)
+            << "iOS does not support multisampled texture arrays.";
 #endif
 
     const auto get2DTextureType = [](SamplerType target, bool isMultisampled) {
@@ -536,12 +556,14 @@ MetalTexture::MetalTexture(MetalContext& context, SamplerType target, uint8_t le
             descriptor.usage = getMetalTextureUsage(usage);
             descriptor.storageMode = MTLStorageModePrivate;
             texture = [context.device newTextureWithDescriptor:descriptor];
-            ASSERT_POSTCONDITION(texture != nil, "Could not create Metal texture. Out of memory?");
+            FILAMENT_CHECK_POSTCONDITION(texture != nil)
+                    << "Could not create Metal texture. Out of memory?";
             break;
         case SamplerType::SAMPLER_CUBEMAP:
         case SamplerType::SAMPLER_CUBEMAP_ARRAY:
-            ASSERT_POSTCONDITION(!multisampled, "Multisampled cubemap faces not supported.");
-            ASSERT_POSTCONDITION(width == height, "Cubemap faces must be square.");
+            FILAMENT_CHECK_POSTCONDITION(!multisampled)
+                    << "Multisampled cubemap faces not supported.";
+            FILAMENT_CHECK_POSTCONDITION(width == height) << "Cubemap faces must be square.";
             descriptor = [MTLTextureDescriptor textureCubeDescriptorWithPixelFormat:devicePixelFormat
                                                                                size:width
                                                                           mipmapped:mipmapped];
@@ -550,7 +572,8 @@ MetalTexture::MetalTexture(MetalContext& context, SamplerType target, uint8_t le
             descriptor.usage = getMetalTextureUsage(usage);
             descriptor.storageMode = MTLStorageModePrivate;
             texture = [context.device newTextureWithDescriptor:descriptor];
-            ASSERT_POSTCONDITION(texture != nil, "Could not create Metal texture. Out of memory?");
+            FILAMENT_CHECK_POSTCONDITION(texture != nil)
+                    << "Could not create Metal texture. Out of memory?";
             break;
         case SamplerType::SAMPLER_3D:
             descriptor = [MTLTextureDescriptor new];
@@ -563,7 +586,8 @@ MetalTexture::MetalTexture(MetalContext& context, SamplerType target, uint8_t le
             descriptor.usage = getMetalTextureUsage(usage);
             descriptor.storageMode = MTLStorageModePrivate;
             texture = [context.device newTextureWithDescriptor:descriptor];
-            ASSERT_POSTCONDITION(texture != nil, "Could not create Metal texture. Out of memory?");
+            FILAMENT_CHECK_POSTCONDITION(texture != nil)
+                    << "Could not create Metal texture. Out of memory?";
             break;
         case SamplerType::SAMPLER_EXTERNAL:
             // If we're using external textures (CVPixelBufferRefs), we don't need to make any
@@ -765,9 +789,9 @@ void MetalTexture::loadSlice(uint32_t level, MTLRegion region, uint32_t byteOffs
         PixelBufferDescriptor const& data) noexcept {
     const PixelBufferShape shape = PixelBufferShape::compute(data, format, region.size, byteOffset);
 
-    ASSERT_PRECONDITION(data.size >= shape.totalBytes,
-            "Expected buffer size of at least %d but "
-            "received PixelBufferDescriptor with size %d.", shape.totalBytes, data.size);
+    FILAMENT_CHECK_PRECONDITION(data.size >= shape.totalBytes)
+            << "Expected buffer size of at least " << shape.totalBytes
+            << " but received PixelBufferDescriptor with size " << data.size << ".";
 
     // Earlier versions of iOS don't have the maxBufferLength query, but 256 MB is a safe bet.
     NSUInteger deviceMaxBufferLength = 256 * 1024 * 1024;   // 256 MB
@@ -988,9 +1012,9 @@ MetalRenderTarget::MetalRenderTarget(MetalContext* context, uint32_t width, uint
         }
         color[i] = colorAttachments[i];
 
-        ASSERT_PRECONDITION(color[i].getSampleCount() <= samples,
-                "MetalRenderTarget was initialized with a MSAA COLOR%d texture, but sample count is %d.",
-                i, samples);
+        FILAMENT_CHECK_PRECONDITION(color[i].getSampleCount() <= samples)
+                << "MetalRenderTarget was initialized with a MSAA COLOR" << i
+                << " texture, but sample count is " << samples << ".";
 
         auto t = color[i].metalTexture;
         const auto twidth = std::max(1u, t->width >> color[i].level);
@@ -1013,9 +1037,10 @@ MetalRenderTarget::MetalRenderTarget(MetalContext* context, uint32_t width, uint
     if (depthAttachment) {
         depth = depthAttachment;
 
-        ASSERT_PRECONDITION(depth.getSampleCount() <= samples,
-                "MetalRenderTarget was initialized with a MSAA DEPTH texture, but sample count is %d.",
-                samples);
+        FILAMENT_CHECK_PRECONDITION(depth.getSampleCount() <= samples)
+                << "MetalRenderTarget was initialized with a MSAA DEPTH texture, but sample count "
+                   "is "
+                << samples << ".";
 
         auto t = depth.metalTexture;
         const auto twidth = std::max(1u, t->width >> depth.level);
@@ -1038,9 +1063,10 @@ MetalRenderTarget::MetalRenderTarget(MetalContext* context, uint32_t width, uint
     if (stencilAttachment) {
         stencil = stencilAttachment;
 
-        ASSERT_PRECONDITION(stencil.getSampleCount() <= samples,
-                "MetalRenderTarget was initialized with a MSAA STENCIL texture, but sample count is %d.",
-                samples);
+        FILAMENT_CHECK_PRECONDITION(stencil.getSampleCount() <= samples)
+                << "MetalRenderTarget was initialized with a MSAA STENCIL texture, but sample "
+                   "count is "
+                << samples << ".";
 
         auto t = stencil.metalTexture;
         const auto twidth = std::max(1u, t->width >> stencil.level);

filament/backend/src/metal/MetalState.mm

@@ -100,7 +100,7 @@ id<MTLRenderPipelineState> PipelineStateCreator::operator()(id<MTLDevice> device
                                  reason:errorMessage
                                userInfo:nil] raise];
     }
-    ASSERT_POSTCONDITION(error == nil, "Could not create Metal pipeline state.");
+    FILAMENT_CHECK_POSTCONDITION(error == nil) << "Could not create Metal pipeline state.";
 
     return pipeline;
 }

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -304,6 +304,13 @@ void OpenGLDriver::bindSampler(GLuint unit, GLuint sampler) noexcept {
 void OpenGLDriver::setPushConstant(backend::ShaderStage stage, uint8_t index,
         backend::PushConstantVariant value) {
     assert_invariant(stage == ShaderStage::VERTEX || stage == ShaderStage::FRAGMENT);
+
+#if FILAMENT_ENABLE_MATDBG
+    if (UTILS_UNLIKELY(!mValidProgram)) {
+        return;
+    }
+#endif
+
     utils::Slice<std::pair<GLint, ConstantType>> constants;
     if (stage == ShaderStage::VERTEX) {
         constants = mCurrentPushConstants->vertexConstants;
@@ -340,15 +347,11 @@ void OpenGLDriver::bindTexture(GLuint unit, GLTexture const* t) noexcept {
 }
 
 bool OpenGLDriver::useProgram(OpenGLProgram* p) noexcept {
-    if (UTILS_UNLIKELY(!p->isValid())) {
-        // If the program is not valid, we can't call use().
-        return false;
-    }
-
     // set-up textures and samplers in the proper TMUs (as specified in setSamplers)
-    p->use(this, mContext);
+    bool const success = p->use(this, mContext);
+    assert_invariant(success == p->isValid());
 
-    if (UTILS_UNLIKELY(mContext.isES2())) {
+    if (UTILS_UNLIKELY(mContext.isES2() && success)) {
         for (uint32_t i = 0; i < Program::UNIFORM_BINDING_COUNT; i++) {
             auto [id, buffer, age] = mContext.getEs2UniformBinding(i);
             if (buffer) {
@@ -359,7 +362,8 @@ bool OpenGLDriver::useProgram(OpenGLProgram* p) noexcept {
         // when mPlatform.isSRGBSwapChainSupported() is false (no need to check though).
         p->setRec709ColorSpace(mRec709OutputColorspace);
     }
-    return true;
+
+    return success;
 }
 
 
@@ -1494,9 +1498,8 @@ void OpenGLDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow,
 
 #if !defined(__EMSCRIPTEN__)
     // note: in practice this should never happen on Android
-    ASSERT_POSTCONDITION(sc->swapChain,
-            "createSwapChain(%p, 0x%lx) failed. See logs for details.",
-            nativeWindow, flags);
+    FILAMENT_CHECK_POSTCONDITION(sc->swapChain) << "createSwapChain(" << nativeWindow << ", "
+                                                << flags << ") failed. See logs for details.";
 #endif
 
     // See if we need the emulated rec709 output conversion
@@ -1515,9 +1518,9 @@ void OpenGLDriver::createSwapChainHeadlessR(Handle<HwSwapChain> sch,
 
 #if !defined(__EMSCRIPTEN__)
     // note: in practice this should never happen on Android
-    ASSERT_POSTCONDITION(sc->swapChain,
-            "createSwapChainHeadless(%u, %u, 0x%lx) failed. See logs for details.",
-            width, height, flags);
+    FILAMENT_CHECK_POSTCONDITION(sc->swapChain)
+            << "createSwapChainHeadless(" << width << ", " << height << ", " << flags
+            << ") failed. See logs for details.";
 #endif
 
     // See if we need the emulated rec709 output conversion
@@ -2333,9 +2336,9 @@ void OpenGLDriver::updateSamplerGroup(Handle<HwSamplerGroup> sbh,
     auto const* const pSamplers = (SamplerDescriptor const*)data.buffer;
     for (size_t i = 0, c = sb->textureUnitEntries.size(); i < c; i++) {
         GLuint samplerId = 0u;
-        const GLTexture* t = nullptr;
-        if (UTILS_LIKELY(pSamplers[i].t)) {
-            t = handle_cast<const GLTexture*>(pSamplers[i].t);
+        Handle<HwTexture> th = pSamplers[i].t;
+        if (UTILS_LIKELY(th)) {
+            GLTexture const* const t = handle_cast<const GLTexture*>(th);
             assert_invariant(t);
 
             SamplerParams params = pSamplers[i].s;
@@ -2391,7 +2394,7 @@ void OpenGLDriver::updateSamplerGroup(Handle<HwSamplerGroup> sbh,
             // which is not an error.
         }
 
-        sb->textureUnitEntries[i] = { t, samplerId };
+        sb->textureUnitEntries[i] = { th, samplerId };
     }
     scheduleDestroy(std::move(data));
 }
@@ -3606,13 +3609,11 @@ void OpenGLDriver::resolve(
     assert_invariant(s);
     assert_invariant(d);
 
-    ASSERT_PRECONDITION(
-            d->width == s->width && d->height == s->height,
-            "invalid resolve: src and dst sizes don't match");
+    FILAMENT_CHECK_PRECONDITION(d->width == s->width && d->height == s->height)
+            << "invalid resolve: src and dst sizes don't match";
 
-    ASSERT_PRECONDITION(s->samples > 1 && d->samples == 1,
-            "invalid resolve: src.samples=%u, dst.samples=%u",
-            +s->samples, +d->samples);
+    FILAMENT_CHECK_PRECONDITION(s->samples > 1 && d->samples == 1)
+            << "invalid resolve: src.samples=" << +s->samples << ", dst.samples=" << +d->samples;
 
     blit(   dst, dstLevel, dstLayer, {},
             src, srcLevel, srcLayer, {},
@@ -3768,12 +3769,12 @@ void OpenGLDriver::blitDEPRECATED(TargetBufferFlags buffers,
     UTILS_UNUSED_IN_RELEASE auto& gl = mContext;
     assert_invariant(!gl.isES2());
 
-    ASSERT_PRECONDITION(buffers == TargetBufferFlags::COLOR0,
-            "blitDEPRECATED only supports COLOR0");
+    FILAMENT_CHECK_PRECONDITION(buffers == TargetBufferFlags::COLOR0)
+            << "blitDEPRECATED only supports COLOR0";
 
-    ASSERT_PRECONDITION(srcRect.left >= 0 && srcRect.bottom >= 0 &&
-                        dstRect.left >= 0 && dstRect.bottom >= 0,
-            "Source and destination rects must be positive.");
+    FILAMENT_CHECK_PRECONDITION(
+            srcRect.left >= 0 && srcRect.bottom >= 0 && dstRect.left >= 0 && dstRect.bottom >= 0)
+            << "Source and destination rects must be positive.";
 
 #ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
 

filament/backend/src/opengl/OpenGLDriver.h

@@ -126,7 +126,7 @@ public:
     struct GLSamplerGroup : public HwSamplerGroup {
         using HwSamplerGroup::HwSamplerGroup;
         struct Entry {
-            GLTexture const* texture = nullptr;
+            Handle<HwTexture> th;
             GLuint sampler = 0u;
         };
         utils::FixedCapacityVector<Entry> textureUnitEntries;
@@ -256,6 +256,11 @@ private:
         return mHandleAllocator.handle_cast<Dp, B>(handle);
     }
 
+    template<typename B>
+    bool is_valid(Handle<B>& handle) {
+        return mHandleAllocator.is_valid(handle);
+    }
+
     template<typename Dp, typename B>
     inline typename std::enable_if_t<
             std::is_pointer_v<Dp> &&

filament/backend/src/opengl/OpenGLProgram.cpp

@@ -20,21 +20,24 @@
 #include "OpenGLDriver.h"
 #include "ShaderCompilerService.h"
 
+#include <backend/DriverEnums.h>
 #include <backend/Program.h>
+#include <backend/Handle.h>
 
-#include <private/backend/BackendUtils.h>
-
-#include <utils/debug.h>
 #include <utils/compiler.h>
+#include <utils/debug.h>
+#include <utils/FixedCapacityVector.h>
 #include <utils/Log.h>
 #include <utils/Systrace.h>
 
+#include <algorithm>
 #include <array>
 #include <string_view>
 #include <utility>
 #include <new>
 
 #include <stddef.h>
+#include <stdint.h>
 
 namespace filament::backend {
 
@@ -241,8 +244,9 @@ void OpenGLProgram::updateSamplers(OpenGLDriver* const gld) const noexcept {
         assert_invariant(sb);
         if (!sb) continue; // should never happen, this would be a user error.
         for (uint8_t j = 0, m = sb->textureUnitEntries.size(); j < m; ++j, ++tmu) { // "<=" on purpose here
-            const GLTexture* const t = sb->textureUnitEntries[j].texture;
-            if (t) { // program may not use all samplers of sampler group
+            Handle<HwTexture> th = sb->textureUnitEntries[j].th;
+            if (th) { // program may not use all samplers of sampler group
+                GLTexture const* const t = gld->handle_cast<GLTexture const*>(th);
                 gld->bindTexture(tmu, t);
 #ifndef FILAMENT_SILENCE_NOT_SUPPORTED_BY_ES2
                 if (UTILS_LIKELY(!es2)) {

filament/backend/src/opengl/OpenGLProgram.h

@@ -53,11 +53,21 @@ public:
 
     bool isValid() const noexcept { return mToken || gl.program != 0; }
 
-    void use(OpenGLDriver* const gld, OpenGLContext& context) noexcept {
-        if (UTILS_UNLIKELY(!gl.program)) {
+    bool use(OpenGLDriver* const gld, OpenGLContext& context) noexcept {
+        // both non-null is impossible by construction
+        assert_invariant(!mToken || !gl.program);
+
+        if (UTILS_UNLIKELY(mToken && !gl.program)) {
+            // first time a program is used
             initialize(*gld);
         }
 
+        if (UTILS_UNLIKELY(!gl.program)) {
+            // compilation failed (token should be null)
+            assert_invariant(!mToken);
+            return false;
+        }
+
         context.useProgram(gl.program);
         if (UTILS_UNLIKELY(mUsedBindingsCount)) {
             // We rely on GL state tracking to avoid unnecessary glBindTexture / glBindSampler
@@ -74,6 +84,7 @@ public:
 
             updateSamplers(gld);
         }
+        return true;
     }
 
     // For ES2 only

filament/backend/src/opengl/ShaderCompilerService.cpp

@@ -359,7 +359,7 @@ ShaderCompilerService::program_token_t ShaderCompilerService::createProgram(
 GLuint ShaderCompilerService::getProgram(ShaderCompilerService::program_token_t& token) {
     GLuint const program = initialize(token);
     assert_invariant(token == nullptr);
-#ifndef FILAMENT_ENABLE_MATDBG
+#if !FILAMENT_ENABLE_MATDBG
     assert_invariant(program);
 #endif
     return program;
@@ -572,16 +572,23 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
 
             // split shader source, so we can insert the specialization constants and the packing
             // functions
-            auto const [prolog, body] = splitShaderSource({ shader_src, shader_len });
+            auto [version, prolog, body] = splitShaderSource({ shader_src, shader_len });
 
-            const std::array<const char*, 4> sources = {
+            // enable ESSL 3.10 if available
+            if (context.isAtLeastGLES<3, 1>()) {
+                version = "#version 310 es\n";
+            }
+
+            const std::array<const char*, 5> sources = {
+                    version.data(),
                     prolog.data(),
                     specializationConstantString.c_str(),
                     packingFunctions.data(),
                     body.data()
             };
 
-            const std::array<GLint, 4> lengths = {
+            const std::array<GLint, 5> lengths = {
+                    (GLint)version.length(),
                     (GLint)prolog.length(),
                     (GLint)specializationConstantString.length(),
                     (GLint)packingFunctions.length(),
@@ -661,6 +668,7 @@ void ShaderCompilerService::process_OVR_multiview2(OpenGLContext& context,
 
 // Tragically, OpenGL 4.1 doesn't support unpackHalf2x16 (appeared in 4.2) and
 // macOS doesn't support GL_ARB_shading_language_packing
+// Also GLES3.0 didn't have the full set of packing/unpacking functions
 std::string_view ShaderCompilerService::process_ARB_shading_language_packing(OpenGLContext& context) noexcept {
     using namespace std::literals;
 #ifdef BACKEND_OPENGL_VERSION_GL
@@ -700,21 +708,92 @@ highp uint packHalf2x16(vec2 v) {
     highp uint y = fp32tou16(v.y);
     return (y << 16u) | x;
 }
+highp uint packUnorm4x8(mediump vec4 v) {
+    v = round(clamp(v, 0.0, 1.0) * 255.0);
+    highp uint a = uint(v.x);
+    highp uint b = uint(v.y) <<  8;
+    highp uint c = uint(v.z) << 16;
+    highp uint d = uint(v.w) << 24;
+    return (a|b|c|d);
+}
+highp uint packSnorm4x8(mediump vec4 v) {
+    v = round(clamp(v, -1.0, 1.0) * 127.0);
+    highp uint a = uint((int(v.x) & 0xff));
+    highp uint b = uint((int(v.y) & 0xff)) <<  8;
+    highp uint c = uint((int(v.z) & 0xff)) << 16;
+    highp uint d = uint((int(v.w) & 0xff)) << 24;
+    return (a|b|c|d);
+}
+mediump vec4 unpackUnorm4x8(highp uint v) {
+    return vec4(float((v & 0x000000ffu)      ),
+                float((v & 0x0000ff00u) >>  8),
+                float((v & 0x00ff0000u) >> 16),
+                float((v & 0xff000000u) >> 24)) / 255.0;
+}
+mediump vec4 unpackSnorm4x8(highp uint v) {
+    int a = int(((v       ) & 0xffu) << 24u) >> 24 ;
+    int b = int(((v >>  8u) & 0xffu) << 24u) >> 24 ;
+    int c = int(((v >> 16u) & 0xffu) << 24u) >> 24 ;
+    int d = int(((v >> 24u) & 0xffu) << 24u) >> 24 ;
+    return clamp(vec4(float(a), float(b), float(c), float(d)) / 127.0, -1.0, 1.0);
+}
 )"sv;
     }
 #endif // BACKEND_OPENGL_VERSION_GL
+
+#ifdef BACKEND_OPENGL_VERSION_GLES
+    if (!context.isES2() && !context.isAtLeastGLES<3, 1>()) {
+        return R"(
+
+highp uint packUnorm4x8(mediump vec4 v) {
+    v = round(clamp(v, 0.0, 1.0) * 255.0);
+    highp uint a = uint(v.x);
+    highp uint b = uint(v.y) <<  8;
+    highp uint c = uint(v.z) << 16;
+    highp uint d = uint(v.w) << 24;
+    return (a|b|c|d);
+}
+highp uint packSnorm4x8(mediump vec4 v) {
+    v = round(clamp(v, -1.0, 1.0) * 127.0);
+    highp uint a = uint((int(v.x) & 0xff));
+    highp uint b = uint((int(v.y) & 0xff)) <<  8;
+    highp uint c = uint((int(v.z) & 0xff)) << 16;
+    highp uint d = uint((int(v.w) & 0xff)) << 24;
+    return (a|b|c|d);
+}
+mediump vec4 unpackUnorm4x8(highp uint v) {
+    return vec4(float((v & 0x000000ffu)      ),
+                float((v & 0x0000ff00u) >>  8),
+                float((v & 0x00ff0000u) >> 16),
+                float((v & 0xff000000u) >> 24)) / 255.0;
+}
+mediump vec4 unpackSnorm4x8(highp uint v) {
+    int a = int(((v       ) & 0xffu) << 24u) >> 24 ;
+    int b = int(((v >>  8u) & 0xffu) << 24u) >> 24 ;
+    int c = int(((v >> 16u) & 0xffu) << 24u) >> 24 ;
+    int d = int(((v >> 24u) & 0xffu) << 24u) >> 24 ;
+    return clamp(vec4(float(a), float(b), float(c), float(d)) / 127.0, -1.0, 1.0);
+}
+)"sv;
+    }
+#endif // BACKEND_OPENGL_VERSION_GLES
     return ""sv;
 }
 
-// split shader source code in two, the first section goes from the start to the line after the
-// last #extension, and the 2nd part goes from there to the end.
-std::array<std::string_view, 2> ShaderCompilerService::splitShaderSource(std::string_view source) noexcept {
+// split shader source code in three:
+// - the version line
+// - extensions
+// - everything else
+std::array<std::string_view, 3> ShaderCompilerService::splitShaderSource(std::string_view source) noexcept {
     auto start = source.find("#version");
     assert_invariant(start != std::string_view::npos);
 
+    auto version_eol = source.find('\n', start) + 1;
+    assert_invariant(version_eol != std::string_view::npos);
+
     auto pos = source.rfind("\n#extension");
     if (pos == std::string_view::npos) {
-        pos = start;
+        pos = version_eol;
     } else {
         ++pos;
     }
@@ -722,9 +801,10 @@ std::array<std::string_view, 2> ShaderCompilerService::splitShaderSource(std::st
     auto eol = source.find('\n', pos) + 1;
     assert_invariant(eol != std::string_view::npos);
 
-    std::string_view const version = source.substr(start, eol - start);
-    std::string_view const body = source.substr(version.length(), source.length() - version.length());
-    return { version, body };
+    std::string_view const version = source.substr(start, version_eol - start);
+    std::string_view const prolog = source.substr(version_eol, eol - version_eol);
+    std::string_view const body = source.substr(eol, source.length() - eol);
+    return { version, prolog, body };
 }
 
 /*

filament/backend/src/opengl/ShaderCompilerService.h

@@ -146,7 +146,7 @@ private:
 
     static std::string_view process_ARB_shading_language_packing(OpenGLContext& context) noexcept;
 
-    static std::array<std::string_view, 2> splitShaderSource(std::string_view source) noexcept;
+    static std::array<std::string_view, 3> splitShaderSource(std::string_view source) noexcept;
 
     static GLuint linkProgram(OpenGLContext& context,
             std::array<GLuint, Program::SHADER_TYPE_COUNT> shaders,

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

@@ -111,8 +111,8 @@ bool CocoaExternalImage::set(CVPixelBufferRef image) noexcept {
     }
 
     OSType formatType = CVPixelBufferGetPixelFormatType(image);
-    ASSERT_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA,
-            "macOS external images must be 32BGRA format.");
+    FILAMENT_CHECK_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA)
+            << "macOS external images must be 32BGRA format.";
 
     // The pixel buffer must be locked whenever we do rendering with it. We'll unlock it before
     // releasing.

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

@@ -135,13 +135,14 @@ bool CocoaTouchExternalImage::set(CVPixelBufferRef image) noexcept {
     }
 
     OSType formatType = CVPixelBufferGetPixelFormatType(image);
-    ASSERT_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA ||
-                         formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange,
-            "iOS external images must be in either 32BGRA or 420f format.");
+    FILAMENT_CHECK_POSTCONDITION(formatType == kCVPixelFormatType_32BGRA ||
+            formatType == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
+            << "iOS external images must be in either 32BGRA or 420f format.";
 
     size_t planeCount = CVPixelBufferGetPlaneCount(image);
-    ASSERT_POSTCONDITION(planeCount == 0 || planeCount == 2,
-            "The OpenGL backend does not support images with plane counts of %d.", planeCount);
+    FILAMENT_CHECK_POSTCONDITION(planeCount == 0 || planeCount == 2)
+            << "The OpenGL backend does not support images with plane counts of " << planeCount
+            << ".";
 
     // The pixel buffer must be locked whenever we do rendering with it. We'll unlock it before
     // releasing.

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

@@ -162,7 +162,7 @@ Driver* PlatformCocoaGL::createDriver(void* sharedContext, const Platform::Drive
     pImpl->mGLContext = nsOpenGLContext;
 
     int result = bluegl::bind();
-    ASSERT_POSTCONDITION(!result, "Unable to load OpenGL entry points.");
+    FILAMENT_CHECK_POSTCONDITION(!result) << "Unable to load OpenGL entry points.";
 
     UTILS_UNUSED_IN_RELEASE CVReturn success = CVOpenGLTextureCacheCreate(kCFAllocatorDefault, nullptr,
             [pImpl->mGLContext CGLContextObj], [pImpl->mGLContext.pixelFormat CGLPixelFormatObj], nullptr,

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

@@ -61,7 +61,7 @@ Driver* PlatformCocoaTouchGL::createDriver(void* const sharedGLContext, const Pl
     EAGLSharegroup* sharegroup = (__bridge EAGLSharegroup*) sharedGLContext;
 
     EAGLContext *context = [[EAGLContext alloc] initWithAPI:kEAGLRenderingAPIOpenGLES3 sharegroup:sharegroup];
-    ASSERT_POSTCONDITION(context, "Unable to create OpenGL ES context.");
+    FILAMENT_CHECK_POSTCONDITION(context) << "Unable to create OpenGL ES context.";
 
     [EAGLContext setCurrentContext:context];
 
@@ -103,7 +103,7 @@ void PlatformCocoaTouchGL::createContext(bool shared) {
     EAGLContext* const context = [[EAGLContext alloc]
                                   initWithAPI:kEAGLRenderingAPIOpenGLES3
                                    sharegroup:sharegroup];
-    ASSERT_POSTCONDITION(context, "Unable to create extra OpenGL ES context.");
+    FILAMENT_CHECK_POSTCONDITION(context) << "Unable to create extra OpenGL ES context.";
     [EAGLContext setCurrentContext:context];
     pImpl->mAdditionalContexts.push_back(context);
 }
@@ -180,7 +180,8 @@ bool PlatformCocoaTouchGL::makeCurrent(ContextType type, SwapChain* drawSwapChai
         glGetIntegerv(GL_FRAMEBUFFER_BINDING, &oldFramebuffer);
         glBindFramebuffer(GL_FRAMEBUFFER, pImpl->mDefaultFramebuffer);
         GLenum const status = glCheckFramebufferStatus(GL_FRAMEBUFFER);
-        ASSERT_POSTCONDITION(status == GL_FRAMEBUFFER_COMPLETE, "Incomplete framebuffer.");
+        FILAMENT_CHECK_POSTCONDITION(status == GL_FRAMEBUFFER_COMPLETE)
+                << "Incomplete framebuffer.";
         glBindFramebuffer(GL_FRAMEBUFFER, oldFramebuffer);
     }
     return true;

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

@@ -19,6 +19,8 @@
 #include <backend/platforms/PlatformEGL.h>
 #include <backend/platforms/PlatformEGLAndroid.h>
 
+#include <private/backend/VirtualMachineEnv.h>
+
 #include "opengl/GLUtils.h"
 #include "ExternalStreamManagerAndroid.h"
 
@@ -82,9 +84,23 @@ using EGLStream = Platform::Stream;
 
 // ---------------------------------------------------------------------------------------------
 
+PlatformEGLAndroid::InitializeJvmForPerformanceManagerIfNeeded::InitializeJvmForPerformanceManagerIfNeeded() {
+    // PerformanceHintManager() needs the calling thread to be a Java thread; so we need
+    // to attach this thread to the JVM before we initialize PerformanceHintManager.
+    // This should be done in PerformanceHintManager(), but libutils doesn't have access to
+    // VirtualMachineEnv.
+    if (PerformanceHintManager::isSupported()) {
+        (void)VirtualMachineEnv::get().getEnvironment();
+    }
+}
+
+// ---------------------------------------------------------------------------------------------
+
 PlatformEGLAndroid::PlatformEGLAndroid() noexcept
         : PlatformEGL(),
-          mExternalStreamManager(ExternalStreamManagerAndroid::create()) {
+          mExternalStreamManager(ExternalStreamManagerAndroid::create()),
+          mInitializeJvmForPerformanceManagerIfNeeded(),
+          mPerformanceHintManager() {
 
     char scratch[PROP_VALUE_MAX + 1];
     int length = __system_property_get("ro.build.version.release", scratch);

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

@@ -226,7 +226,7 @@ Driver* PlatformGLX::createDriver(void* const sharedGLContext,
     g_glx.setCurrentContext(mGLXDisplay, mDummySurface, mDummySurface, mGLXContext);
 
     int result = bluegl::bind();
-    ASSERT_POSTCONDITION(!result, "Unable to load OpenGL entry points.");
+    FILAMENT_CHECK_POSTCONDITION(!result) << "Unable to load OpenGL entry points.";
 
     return OpenGLPlatform::createDefaultDriver(this, sharedGLContext, driverConfig);
 }

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

@@ -154,7 +154,7 @@ Driver* PlatformWGL::createDriver(void* const sharedGLContext,
     }
 
     result = bluegl::bind();
-    ASSERT_POSTCONDITION(!result, "Unable to load OpenGL entry points.");
+    FILAMENT_CHECK_POSTCONDITION(!result) << "Unable to load OpenGL entry points.";
 
     return OpenGLPlatform::createDefaultDriver(this, sharedGLContext, driverConfig);
 

filament/backend/src/vulkan/VulkanBlitter.cpp

@@ -37,7 +37,7 @@ inline void blitFast(const VkCommandBuffer cmdbuffer, VkImageAspectFlags aspect,
         VulkanAttachment src, VulkanAttachment dst,
         const VkOffset3D srcRect[2], const VkOffset3D dstRect[2]) {
     if constexpr (FVK_ENABLED(FVK_DEBUG_BLITTER)) {
-        utils::slog.d << "Fast blit from=" << src.texture->getVkImage() << ",level=" << (int) src.level
+        FVK_LOGD << "Fast blit from=" << src.texture->getVkImage() << ",level=" << (int) src.level
                       << " layout=" << src.getLayout()
                       << " to=" << dst.texture->getVkImage() << ",level=" << (int) dst.level
                       << " layout=" << dst.getLayout() << utils::io::endl;
@@ -76,7 +76,7 @@ inline void blitFast(const VkCommandBuffer cmdbuffer, VkImageAspectFlags aspect,
 inline void resolveFast(const VkCommandBuffer cmdbuffer, VkImageAspectFlags aspect,
         VulkanAttachment src, VulkanAttachment dst) {
     if constexpr (FVK_ENABLED(FVK_DEBUG_BLITTER)) {
-        utils::slog.d << "Fast blit from=" << src.texture->getVkImage() << ",level=" << (int) src.level
+        FVK_LOGD << "Fast blit from=" << src.texture->getVkImage() << ",level=" << (int) src.level
                       << " layout=" << src.getLayout()
                       << " to=" << dst.texture->getVkImage() << ",level=" << (int) dst.level
                       << " layout=" << dst.getLayout() << utils::io::endl;

filament/backend/src/vulkan/VulkanCommands.cpp

@@ -178,7 +178,7 @@ VulkanCommandBuffer& VulkanCommands::get() {
     // presenting the swap chain or waiting on a fence.
     while (mAvailableBufferCount == 0) {
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
-        slog.i << "VulkanCommands has stalled. "
+        FVK_LOGI << "VulkanCommands has stalled. "
                << "If this occurs frequently, consider increasing VK_MAX_COMMAND_BUFFERS."
                << io::endl;
 #endif
@@ -289,7 +289,7 @@ bool VulkanCommands::flush() {
     };
 
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
-    slog.i << "Submitting cmdbuffer=" << cmdbuffer
+    FVK_LOGI << "Submitting cmdbuffer=" << cmdbuffer
            << " wait=(" << signals[0] << ", " << signals[1] << ") "
            << " signal=" << renderingFinished
            << " fence=" << currentbuf->fence->fence
@@ -305,7 +305,7 @@ bool VulkanCommands::flush() {
 
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
     if (result != VK_SUCCESS) {
-        utils::slog.d << "Failed command buffer submission result: " << result << utils::io::endl;
+        FVK_LOGD << "Failed command buffer submission result: " << result << utils::io::endl;
     }
 #endif
     assert_invariant(result == VK_SUCCESS);
@@ -320,7 +320,7 @@ VkSemaphore VulkanCommands::acquireFinishedSignal() {
     VkSemaphore semaphore = mSubmissionSignal;
     mSubmissionSignal = VK_NULL_HANDLE;
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
-    slog.i << "Acquiring " << semaphore << " (e.g. for vkQueuePresentKHR)" << io::endl;
+    FVK_LOGI << "Acquiring " << semaphore << " (e.g. for vkQueuePresentKHR)" << io::endl;
 #endif
     return semaphore;
 }
@@ -329,7 +329,7 @@ void VulkanCommands::injectDependency(VkSemaphore next) {
     assert_invariant(mInjectedSignal == VK_NULL_HANDLE);
     mInjectedSignal = next;
 #if FVK_ENABLED(FVK_DEBUG_COMMAND_BUFFER)
-    slog.i << "Injecting " << next << " (e.g. due to vkAcquireNextImageKHR)" << io::endl;
+    FVK_LOGI << "Injecting " << next << " (e.g. due to vkAcquireNextImageKHR)" << io::endl;
 #endif
 }
 
@@ -398,7 +398,7 @@ void VulkanCommands::pushGroupMarker(char const* str, VulkanGroupMarkers::Timest
     // If the timestamp is not 0, then we are carrying over a marker across buffer submits.
     // If it is 0, then this is a normal marker push and we should just print debug line as usual.
     if (timestamp.time_since_epoch().count() == 0.0) {
-        utils::slog.d << "----> " << str << utils::io::endl;
+        FVK_LOGD << "----> " << str << utils::io::endl;
     }
 #endif
 
@@ -436,7 +436,7 @@ void VulkanCommands::popGroupMarker() {
         auto const [marker, startTime] = mGroupMarkers->pop();
         auto const endTime = std::chrono::high_resolution_clock::now();
         std::chrono::duration<double> diff = endTime - startTime;
-        utils::slog.d << "<---- " << marker << " elapsed: " << (diff.count() * 1000) << " ms"
+        FVK_LOGD << "<---- " << marker << " elapsed: " << (diff.count() * 1000) << " ms"
                       << utils::io::endl;
 #else
         mGroupMarkers->pop();

filament/backend/src/vulkan/VulkanConstants.h

@@ -17,6 +17,8 @@
 #ifndef TNT_FILAMENT_BACKEND_VULKANCONSTANTS_H
 #define TNT_FILAMENT_BACKEND_VULKANCONSTANTS_H
 
+#include <utils/Log.h>
+
 #include <stdint.h>
 
 // In debug builds, we enable validation layers and set up a debug callback.
@@ -70,6 +72,11 @@
 // the currently active resources.
 #define FVK_DEBUG_RESOURCE_LEAK           0x00010000
 
+// Set this to enable logging "only" to one output stream. This is useful in the case where we want
+// to debug with print statements and want ordered logging (e.g slog.i and slog.e will not appear in
+// order of calls).
+#define FVK_DEBUG_FORCE_LOG_TO_I          0x00020000
+
 // Useful default combinations
 #define FVK_DEBUG_EVERYTHING              0xFFFFFFFF
 #define FVK_DEBUG_PERFORMANCE     \
@@ -133,6 +140,18 @@ static_assert(FVK_ENABLED(FVK_DEBUG_VALIDATION));
 #define FVK_HANDLE_ARENA_SIZE_IN_MB 8
 #endif
 
+#if FVK_ENABLED(FVK_DEBUG_FORCE_LOG_TO_I)
+    #define FVK_LOGI (utils::slog.i)
+    #define FVK_LOGD FVK_LOGI
+    #define FVK_LOGE FVK_LOGI
+    #define FVK_LOGW FVK_LOGI
+#else
+    #define FVK_LOGE (utils::slog.e)
+    #define FVK_LOGW (utils::slog.w)
+    #define FVK_LOGD (utils::slog.d)
+    #define FVK_LOGI (utils::slog.i)
+#endif
+
 // All vkCreate* functions take an optional allocator. For now we select the default allocator by
 // passing in a null pointer, and we highlight the argument by using the VKALLOC constant.
 constexpr struct VkAllocationCallbacks* VKALLOC = nullptr;

filament/backend/src/vulkan/VulkanContext.cpp

@@ -86,7 +86,7 @@ VulkanTimestamps::VulkanTimestamps(VkDevice device) : mDevice(device) {
     std::unique_lock<utils::Mutex> lock(mMutex);
     tqpCreateInfo.queryCount = mUsed.size() * 2;
     VkResult result = vkCreateQueryPool(mDevice, &tqpCreateInfo, VKALLOC, &mPool);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateQueryPool error.");
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateQueryPool error.";
     mUsed.reset();
 }
 
@@ -100,7 +100,7 @@ std::tuple<uint32_t, uint32_t> VulkanTimestamps::getNextQuery() {
 	    return std::make_tuple(timerIndex * 2, timerIndex * 2 + 1);
         }
     }
-    utils::slog.e << "More than " << maxTimers << " timers are not supported." << utils::io::endl;
+    FVK_LOGE << "More than " << maxTimers << " timers are not supported." << utils::io::endl;
     return std::make_tuple(0, 1);
 }
 
@@ -134,8 +134,8 @@ VulkanTimestamps::QueryResult VulkanTimestamps::getResult(VulkanTimerQuery const
     VkResult vkresult =
             vkGetQueryPoolResults(mDevice, mPool, index, 2, dataSize, (void*) result.data(),
                     stride, VK_QUERY_RESULT_64_BIT | VK_QUERY_RESULT_WITH_AVAILABILITY_BIT);
-    ASSERT_POSTCONDITION(vkresult == VK_SUCCESS || vkresult == VK_NOT_READY,
-            "vkGetQueryPoolResults error: %d", static_cast<int32_t>(vkresult));
+    FILAMENT_CHECK_POSTCONDITION(vkresult == VK_SUCCESS || vkresult == VK_NOT_READY)
+            << "vkGetQueryPoolResults error: " << static_cast<int32_t>(vkresult);
     if (vkresult == VK_NOT_READY) {
         return {0, 0, 0, 0};
     }

filament/backend/src/vulkan/VulkanContext.h

@@ -131,6 +131,10 @@ public:
         return mDebugUtilsSupported;
     }
 
+    inline bool isMultiviewEnabled() const noexcept {
+        return mMultiviewEnabled;
+    }
+
     inline bool isClipDistanceSupported() const noexcept {
         return mPhysicalDeviceFeatures.shaderClipDistance == VK_TRUE;
     }
@@ -141,6 +145,7 @@ private:
     VkPhysicalDeviceFeatures mPhysicalDeviceFeatures = {};
     bool mDebugMarkersSupported = false;
     bool mDebugUtilsSupported = false;
+    bool mMultiviewEnabled = false;
 
     VkFormatList mDepthStencilFormats;
     VkFormatList mBlittableDepthStencilFormats;

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -115,15 +115,15 @@ VKAPI_ATTR VkBool32 VKAPI_CALL debugReportCallback(VkDebugReportFlagsEXT flags,
         VkDebugReportObjectTypeEXT objectType, uint64_t object, size_t location,
         int32_t messageCode, const char* pLayerPrefix, const char* pMessage, void* pUserData) {
     if (flags & VK_DEBUG_REPORT_ERROR_BIT_EXT) {
-        utils::slog.e << "VULKAN ERROR: (" << pLayerPrefix << ") " << pMessage << utils::io::endl;
+        FVK_LOGE << "VULKAN ERROR: (" << pLayerPrefix << ") " << pMessage << utils::io::endl;
     } else {
         // TODO: emit best practices warnings about aggressive pipeline barriers.
         if (strstr(pMessage, "ALL_GRAPHICS_BIT") || strstr(pMessage, "ALL_COMMANDS_BIT")) {
             return VK_FALSE;
         }
-        utils::slog.w << "VULKAN WARNING: (" << pLayerPrefix << ") " << pMessage << utils::io::endl;
+        FVK_LOGW << "VULKAN WARNING: (" << pLayerPrefix << ") " << pMessage << utils::io::endl;
     }
-    utils::slog.e << utils::io::endl;
+    FVK_LOGE << utils::io::endl;
     return VK_FALSE;
 }
 #endif // FVK_EANBLED(FVK_DEBUG_VALIDATION)
@@ -133,18 +133,18 @@ VKAPI_ATTR VkBool32 VKAPI_CALL debugUtilsCallback(VkDebugUtilsMessageSeverityFla
         VkDebugUtilsMessageTypeFlagsEXT types, const VkDebugUtilsMessengerCallbackDataEXT* cbdata,
         void* pUserData) {
     if (severity & VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT) {
-        utils::slog.e << "VULKAN ERROR: (" << cbdata->pMessageIdName << ") " << cbdata->pMessage
-                      << utils::io::endl;
+        FVK_LOGE << "VULKAN ERROR: (" << cbdata->pMessageIdName << ") " << cbdata->pMessage
+                 << utils::io::endl;
     } else {
         // TODO: emit best practices warnings about aggressive pipeline barriers.
         if (strstr(cbdata->pMessage, "ALL_GRAPHICS_BIT")
                 || strstr(cbdata->pMessage, "ALL_COMMANDS_BIT")) {
             return VK_FALSE;
         }
-        utils::slog.w << "VULKAN WARNING: (" << cbdata->pMessageIdName << ") " << cbdata->pMessage
-                      << utils::io::endl;
+        FVK_LOGW << "VULKAN WARNING: (" << cbdata->pMessageIdName << ") " << cbdata->pMessage
+                 << utils::io::endl;
     }
-    utils::slog.e << utils::io::endl;
+    FVK_LOGE << utils::io::endl;
     return VK_FALSE;
 }
 #endif // FVK_EANBLED(FVK_DEBUG_DEBUG_UTILS)
@@ -173,7 +173,8 @@ DebugUtils::DebugUtils(VkInstance instance, VkDevice device, VulkanContext const
         };
         VkResult result = vkCreateDebugUtilsMessengerEXT(instance, &createInfo,
                 VKALLOC, &mDebugMessenger);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to create Vulkan debug messenger.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+                << "Unable to create Vulkan debug messenger.";
     }
 #endif // FVK_EANBLED(FVK_DEBUG_VALIDATION)
 }
@@ -247,7 +248,8 @@ VulkanDriver::VulkanDriver(VulkanPlatform* platform, VulkanContext const& contex
         };
         VkResult result = createDebugReportCallback(mPlatform->getInstance(), &cbinfo, VKALLOC,
                 &mDebugCallback);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to create Vulkan debug callback.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+                << "Unable to create Vulkan debug callback.";
     }
 #endif
 
@@ -290,7 +292,7 @@ Driver* VulkanDriver::create(VulkanPlatform* platform, VulkanContext const& cont
     //    VulkanRenderTarget            : 312       few
     // -- less than or equal to 312 bytes
 
-    utils::slog.d
+    FVK_LOGD
            << "\nVulkanSwapChain: " << sizeof(VulkanSwapChain)
            << "\nVulkanBufferObject: " << sizeof(VulkanBufferObject)
            << "\nVulkanVertexBuffer: " << sizeof(VulkanVertexBuffer)
@@ -323,6 +325,10 @@ ShaderModel VulkanDriver::getShaderModel() const noexcept {
 }
 
 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.
+    finish(0);
+
     delete mEmptyBufferObject;
     delete mEmptyTexture;
 
@@ -391,7 +397,10 @@ void VulkanDriver::collectGarbage() {
 }
 void VulkanDriver::beginFrame(int64_t monotonic_clock_ns,
         int64_t refreshIntervalNs, uint32_t frameId) {
+    FVK_SYSTRACE_CONTEXT();
+    FVK_SYSTRACE_START("beginFrame");
     // Do nothing.
+    FVK_SYSTRACE_END();
 }
 
 void VulkanDriver::setFrameScheduledCallback(Handle<HwSwapChain> sch,
@@ -651,8 +660,8 @@ void VulkanDriver::createFenceR(Handle<HwFence> fh, int) {
 
 void VulkanDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow, uint64_t flags) {
     if ((flags & backend::SWAP_CHAIN_CONFIG_SRGB_COLORSPACE) != 0 && !isSRGBSwapChainSupported()) {
-        utils::slog.w << "sRGB swapchain requested, but Platform does not support it"
-                      << utils::io::endl;
+        FVK_LOGW << "sRGB swapchain requested, but Platform does not support it"
+                 << utils::io::endl;
         flags = flags | ~(backend::SWAP_CHAIN_CONFIG_SRGB_COLORSPACE);
     }
     auto swapChain = mResourceAllocator.construct<VulkanSwapChain>(sch, mPlatform, mContext,
@@ -663,7 +672,7 @@ void VulkanDriver::createSwapChainR(Handle<HwSwapChain> sch, void* nativeWindow,
 void VulkanDriver::createSwapChainHeadlessR(Handle<HwSwapChain> sch, uint32_t width,
         uint32_t height, uint64_t flags) {
     if ((flags & backend::SWAP_CHAIN_CONFIG_SRGB_COLORSPACE) != 0 && !isSRGBSwapChainSupported()) {
-        utils::slog.w << "sRGB swapchain requested, but Platform does not support it"
+        FVK_LOGW << "sRGB swapchain requested, but Platform does not support it"
                       << utils::io::endl;
         flags = flags | ~(backend::SWAP_CHAIN_CONFIG_SRGB_COLORSPACE);
     }
@@ -905,7 +914,7 @@ bool VulkanDriver::isStereoSupported() {
         case backend::StereoscopicType::INSTANCED:
             return mContext.isClipDistanceSupported();
         case backend::StereoscopicType::MULTIVIEW:
-            // TODO: implement multiview feature in Vulkan.
+            return mContext.isMultiviewEnabled();
         case backend::StereoscopicType::NONE:
             return false;
     }
@@ -1090,7 +1099,8 @@ TimerQueryResult VulkanDriver::getTimerQueryValue(Handle<HwTimerQuery> tqh, uint
         return TimerQueryResult::NOT_READY;
     }
 
-    ASSERT_POSTCONDITION(timestamp1 >= timestamp0, "Timestamps are not monotonically increasing.");
+    FILAMENT_CHECK_POSTCONDITION(timestamp1 >= timestamp0)
+            << "Timestamps are not monotonically increasing.";
 
     // NOTE: MoltenVK currently writes system time so the following delta will always be zero.
     // However there are plans for implementing this properly. See the following GitHub ticket.
@@ -1495,8 +1505,8 @@ void VulkanDriver::endRenderPass(int) {
 }
 
 void VulkanDriver::nextSubpass(int) {
-    ASSERT_PRECONDITION(mCurrentRenderPass.currentSubpass == 0,
-            "Only two subpasses are currently supported.");
+    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.currentSubpass == 0)
+            << "Only two subpasses are currently supported.";
 
     VulkanRenderTarget* renderTarget = mCurrentRenderPass.renderTarget;
     assert_invariant(renderTarget);
@@ -1636,36 +1646,36 @@ void VulkanDriver::resolve(
     FVK_SYSTRACE_CONTEXT();
     FVK_SYSTRACE_START("resolve");
 
-    ASSERT_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE,
-            "resolve() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+            << "resolve() cannot be invoked inside a render pass.";
 
     auto* const srcTexture = mResourceAllocator.handle_cast<VulkanTexture*>(src);
     auto* const dstTexture = mResourceAllocator.handle_cast<VulkanTexture*>(dst);
     assert_invariant(srcTexture);
     assert_invariant(dstTexture);
 
-    ASSERT_PRECONDITION(
-            dstTexture->width == srcTexture->width && dstTexture->height == srcTexture->height,
-            "invalid resolve: src and dst sizes don't match");
+    FILAMENT_CHECK_PRECONDITION(
+            dstTexture->width == srcTexture->width && dstTexture->height == srcTexture->height)
+            << "invalid resolve: src and dst sizes don't match";
 
-    ASSERT_PRECONDITION(srcTexture->samples > 1 && dstTexture->samples == 1,
-            "invalid resolve: src.samples=%u, dst.samples=%u",
-            +srcTexture->samples, +dstTexture->samples);
+    FILAMENT_CHECK_PRECONDITION(srcTexture->samples > 1 && dstTexture->samples == 1)
+            << "invalid resolve: src.samples=" << +srcTexture->samples
+            << ", dst.samples=" << +dstTexture->samples;
 
-    ASSERT_PRECONDITION(srcTexture->format == dstTexture->format,
-            "src and dst texture format don't match");
+    FILAMENT_CHECK_PRECONDITION(srcTexture->format == dstTexture->format)
+            << "src and dst texture format don't match";
 
-    ASSERT_PRECONDITION(!isDepthFormat(srcTexture->format),
-            "can't resolve depth formats");
+    FILAMENT_CHECK_PRECONDITION(!isDepthFormat(srcTexture->format))
+            << "can't resolve depth formats";
 
-    ASSERT_PRECONDITION(!isStencilFormat(srcTexture->format),
-            "can't resolve stencil formats");
+    FILAMENT_CHECK_PRECONDITION(!isStencilFormat(srcTexture->format))
+            << "can't resolve stencil formats";
 
-    ASSERT_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST),
-            "texture doesn't have BLIT_DST");
+    FILAMENT_CHECK_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST))
+            << "texture doesn't have BLIT_DST";
 
-    ASSERT_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC),
-            "texture doesn't have BLIT_SRC");
+    FILAMENT_CHECK_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC))
+            << "texture doesn't have BLIT_SRC";
 
     mBlitter.resolve(
             { .texture = dstTexture, .level = dstLevel, .layer = dstLayer },
@@ -1681,20 +1691,20 @@ void VulkanDriver::blit(
     FVK_SYSTRACE_CONTEXT();
     FVK_SYSTRACE_START("blit");
 
-    ASSERT_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE,
-            "blit() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+            << "blit() cannot be invoked inside a render pass.";
 
     auto* const srcTexture = mResourceAllocator.handle_cast<VulkanTexture*>(src);
     auto* const dstTexture = mResourceAllocator.handle_cast<VulkanTexture*>(dst);
 
-    ASSERT_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST),
-            "texture doesn't have BLIT_DST");
+    FILAMENT_CHECK_PRECONDITION(any(dstTexture->usage & TextureUsage::BLIT_DST))
+            << "texture doesn't have BLIT_DST";
 
-    ASSERT_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC),
-            "texture doesn't have BLIT_SRC");
+    FILAMENT_CHECK_PRECONDITION(any(srcTexture->usage & TextureUsage::BLIT_SRC))
+            << "texture doesn't have BLIT_SRC";
 
-    ASSERT_PRECONDITION(srcTexture->format == dstTexture->format,
-            "src and dst texture format don't match");
+    FILAMENT_CHECK_PRECONDITION(srcTexture->format == dstTexture->format)
+            << "src and dst texture format don't match";
 
     // The Y inversion below makes it so that Vk matches GL and Metal.
 
@@ -1726,15 +1736,15 @@ void VulkanDriver::blitDEPRECATED(TargetBufferFlags buffers,
 
     // Note: blitDEPRECATED is only used for Renderer::copyFrame()
 
-    ASSERT_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE,
-            "blitDEPRECATED() cannot be invoked inside a render pass.");
+    FILAMENT_CHECK_PRECONDITION(mCurrentRenderPass.renderPass == VK_NULL_HANDLE)
+            << "blitDEPRECATED() cannot be invoked inside a render pass.";
 
-    ASSERT_PRECONDITION(buffers == TargetBufferFlags::COLOR0,
-            "blitDEPRECATED only supports COLOR0");
+    FILAMENT_CHECK_PRECONDITION(buffers == TargetBufferFlags::COLOR0)
+            << "blitDEPRECATED only supports COLOR0";
 
-    ASSERT_PRECONDITION(srcRect.left >= 0 && srcRect.bottom >= 0 &&
-                        dstRect.left >= 0 && dstRect.bottom >= 0,
-            "Source and destination rects must be positive.");
+    FILAMENT_CHECK_PRECONDITION(
+            srcRect.left >= 0 && srcRect.bottom >= 0 && dstRect.left >= 0 && dstRect.bottom >= 0)
+            << "Source and destination rects must be positive.";
 
     VulkanRenderTarget* dstTarget = mResourceAllocator.handle_cast<VulkanRenderTarget*>(dst);
     VulkanRenderTarget* srcTarget = mResourceAllocator.handle_cast<VulkanRenderTarget*>(src);
@@ -1852,9 +1862,9 @@ void VulkanDriver::bindPipeline(PipelineState const& pipelineState) {
         // matching characteristics. (e.g. if the missing texture is a 3D texture)
         if (UTILS_UNLIKELY(texture->getPrimaryImageLayout() == VulkanLayout::UNDEFINED)) {
 #if FVK_ENABLED(FVK_DEBUG_TEXTURE) && FVK_ENABLED_DEBUG_SAMPLER_NAME
-            utils::slog.w << "Uninitialized texture bound to '" << bindingToName[binding] << "'";
-            utils::slog.w << " in material '" << program->name.c_str() << "'";
-            utils::slog.w << " at binding point " << +binding << utils::io::endl;
+            FVK_LOGW << "Uninitialized texture bound to '" << bindingToName[binding] << "'";
+            FVK_LOGW << " in material '" << program->name.c_str() << "'";
+            FVK_LOGW << " at binding point " << +binding << utils::io::endl;
 #endif
             texture = mEmptyTexture;
         }
@@ -2004,7 +2014,7 @@ void VulkanDriver::debugCommandBegin(CommandStream* cmds, bool synchronous, cons
         assert_invariant(inRenderPass);
         inRenderPass = false;
     } else if (inRenderPass && OUTSIDE_COMMANDS.find(command) != OUTSIDE_COMMANDS.end()) {
-        utils::slog.e << command.data() << " issued inside a render pass." << utils::io::endl;
+        FVK_LOGE << command.data() << " issued inside a render pass." << utils::io::endl;
     }
 #endif
 }

filament/backend/src/vulkan/VulkanFboCache.cpp

@@ -64,8 +64,8 @@ VulkanFboCache::VulkanFboCache(VkDevice device)
     : mDevice(device) {}
 
 VulkanFboCache::~VulkanFboCache() {
-    ASSERT_POSTCONDITION(mFramebufferCache.empty() && mRenderPassCache.empty(),
-            "Please explicitly call terminate() while the VkDevice is still alive.");
+    FILAMENT_CHECK_POSTCONDITION(mFramebufferCache.empty() && mRenderPassCache.empty())
+            << "Please explicitly call terminate() while the VkDevice is still alive.";
 }
 
 VkFramebuffer VulkanFboCache::getFramebuffer(FboKey config) noexcept {
@@ -95,7 +95,7 @@ VkFramebuffer VulkanFboCache::getFramebuffer(FboKey config) noexcept {
     }
 
     #if FVK_ENABLED(FVK_DEBUG_FBO_CACHE)
-    utils::slog.d << "Creating framebuffer " << config.width << "x" << config.height << " "
+    FVK_LOGD << "Creating framebuffer " << config.width << "x" << config.height << " "
         << "for render pass " << config.renderPass << ", "
         << "samples = " << int(config.samples) << ", "
         << "depth = " << (config.depth ? 1 : 0) << ", "
@@ -115,7 +115,7 @@ VkFramebuffer VulkanFboCache::getFramebuffer(FboKey config) noexcept {
     mRenderPassRefCount[info.renderPass]++;
     VkFramebuffer framebuffer;
     VkResult error = vkCreateFramebuffer(mDevice, &info, VKALLOC, &framebuffer);
-    ASSERT_POSTCONDITION(!error, "Unable to create framebuffer.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to create framebuffer.";
     mFramebufferCache[config] = {framebuffer, mCurrentTime};
     return framebuffer;
 }
@@ -306,11 +306,11 @@ VkRenderPass VulkanFboCache::getRenderPass(RenderPassKey config) noexcept {
     // Finally, create the VkRenderPass.
     VkRenderPass renderPass;
     VkResult error = vkCreateRenderPass(mDevice, &renderPassInfo, VKALLOC, &renderPass);
-    ASSERT_POSTCONDITION(!error, "Unable to create render pass.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to create render pass.";
     mRenderPassCache[config] = {renderPass, mCurrentTime};
 
     #if FVK_ENABLED(FVK_DEBUG_FBO_CACHE)
-    utils::slog.d << "Created render pass " << renderPass << " with "
+    FVK_LOGD << "Created render pass " << renderPass << " with "
         << "samples = " << int(config.samples) << ", "
         << "depth = " << (hasDepth ? 1 : 0) << ", "
         << "colorAttachmentCount[0] = " << subpasses[0].colorAttachmentCount

filament/backend/src/vulkan/VulkanHandles.cpp

@@ -237,7 +237,7 @@ VulkanProgram::VulkanProgram(VkDevice device, Program const& builder) noexcept
             .pCode = data,
         };
         VkResult result = vkCreateShaderModule(mDevice, &moduleInfo, VKALLOC, &module);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to create shader module.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "Unable to create shader module.";
 
 #if FVK_ENABLED(FVK_DEBUG_DEBUG_UTILS)
         std::string name{ builder.getName().c_str(), builder.getName().size() };
@@ -292,8 +292,8 @@ VulkanProgram::VulkanProgram(VkDevice device, Program const& builder) noexcept
     }
 
 #if FVK_ENABLED(FVK_DEBUG_SHADER_MODULE)
-    utils::slog.d << "Created VulkanProgram " << builder << ", shaders = (" << modules[0]
-                  << ", " << modules[1] << ")" << utils::io::endl;
+    FVK_LOGD << "Created VulkanProgram " << builder << ", shaders = (" << modules[0]
+             << ", " << modules[1] << ")" << utils::io::endl;
 #endif
 }
 

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -230,14 +230,15 @@ VulkanPipelineCache::PipelineCacheEntry* VulkanPipelineCache::createPipeline() n
     PipelineCacheEntry cacheEntry = {};
 
     #if FVK_ENABLED(FVK_DEBUG_SHADER_MODULE)
-        utils::slog.d << "vkCreateGraphicsPipelines with shaders = ("
-                << shaderStages[0].module << ", " << shaderStages[1].module << ")" << utils::io::endl;
+        FVK_LOGD << "vkCreateGraphicsPipelines with shaders = ("
+                 << shaderStages[0].module << ", " << shaderStages[1].module << ")"
+                 << utils::io::endl;
     #endif
     VkResult error = vkCreateGraphicsPipelines(mDevice, VK_NULL_HANDLE, 1, &pipelineCreateInfo,
             VKALLOC, &cacheEntry.handle);
     assert_invariant(error == VK_SUCCESS);
     if (error != VK_SUCCESS) {
-        utils::slog.e << "vkCreateGraphicsPipelines error " << error << utils::io::endl;
+        FVK_LOGE << "vkCreateGraphicsPipelines error " << error << utils::io::endl;
         return nullptr;
     }
 
@@ -252,7 +253,7 @@ void VulkanPipelineCache::bindProgram(VulkanProgram* program) noexcept {
 #if FVK_ENABLED(FVK_DEBUG_SHADER_MODULE)
     if (mPipelineRequirements.shaders[0] == VK_NULL_HANDLE ||
             mPipelineRequirements.shaders[1] == VK_NULL_HANDLE) {
-        utils::slog.e << "Binding missing shader: " << program->name.c_str() << utils::io::endl;
+        FVK_LOGE << "Binding missing shader: " << program->name.c_str() << utils::io::endl;
     }
 #endif
 }

filament/backend/src/vulkan/VulkanReadPixels.cpp

@@ -71,8 +71,8 @@ void TaskHandler::shutdown() {
     }
     mHasTaskCondition.notify_one();
     mThread.join();
-    ASSERT_POSTCONDITION(mTaskQueue.empty(),
-            "ReadPixels handler has tasks in the queue after shutdown");
+    FILAMENT_CHECK_POSTCONDITION(mTaskQueue.empty())
+            << "ReadPixels handler has tasks in the queue after shutdown";
 }
 
 void TaskHandler::loop() {
@@ -167,9 +167,9 @@ void VulkanReadPixels::run(VulkanRenderTarget* srcTarget, uint32_t const x, uint
     vkCreateImage(device, &imageInfo, VKALLOC, &stagingImage);
 
 #if FVK_ENABLED(FVK_DEBUG_READ_PIXELS)
-    utils::slog.d << "readPixels created image=" << stagingImage
-                  << " to copy from image=" << srcTexture->getVkImage()
-                  << " src-layout=" << srcTexture->getLayout(0, 0) << utils::io::endl;
+    FVK_LOGD << "readPixels created image=" << stagingImage
+             << " to copy from image=" << srcTexture->getVkImage()
+             << " src-layout=" << srcTexture->getLayout(0, 0) << utils::io::endl;
 #endif
 
     VkMemoryRequirements memReqs;
@@ -185,13 +185,13 @@ void VulkanReadPixels::run(VulkanRenderTarget* srcTarget, uint32_t const x, uint
     if (memoryTypeIndex >= VK_MAX_MEMORY_TYPES) {
         memoryTypeIndex = selectMemoryFunc(memReqs.memoryTypeBits,
                 VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT | VK_MEMORY_PROPERTY_HOST_COHERENT_BIT);
-        utils::slog.w
+        FVK_LOGW
                 << "readPixels is slow because VK_MEMORY_PROPERTY_HOST_CACHED_BIT is not available"
                 << utils::io::endl;
     }
 
-    ASSERT_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES,
-            "VulkanReadPixels: unable to find a memory type that meets requirements.");
+    FILAMENT_CHECK_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES)
+            << "VulkanReadPixels: unable to find a memory type that meets requirements.";
 
     VkMemoryAllocateInfo const allocInfo = {
             .sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,
@@ -303,7 +303,7 @@ void VulkanReadPixels::run(VulkanRenderTarget* srcTarget, uint32_t const x, uint
         VkResult status = vkWaitForFences(device, 1, &fence, VK_TRUE, UINT64_MAX);
         // Fence hasn't been reached. Try waiting again.
         if (status != VK_SUCCESS) {
-            utils::slog.e << "Failed to wait for readPixels fence" << utils::io::endl;
+            FVK_LOGE << "Failed to wait for readPixels fence" << utils::io::endl;
             return;
         }
 
@@ -321,7 +321,7 @@ void VulkanReadPixels::run(VulkanRenderTarget* srcTarget, uint32_t const x, uint
                     getComponentCount(srcFormat), srcPixels,
                     static_cast<int>(subResourceLayout.rowPitch), static_cast<int>(width),
                     static_cast<int>(height), swizzle)) {
-            utils::slog.e << "Unsupported PixelDataFormat or PixelDataType" << utils::io::endl;
+            FVK_LOGE << "Unsupported PixelDataFormat or PixelDataType" << utils::io::endl;
         }
 
         vkUnmapMemory(device, stagingMemory);

filament/backend/src/vulkan/VulkanResourceAllocator.h

@@ -111,11 +111,11 @@ private:
 #if DEBUG_RESOURCE_LEAKS
 public:
     void print() {
-        utils::slog.d << "Resource Allocator state (debug only)" << utils::io::endl;
+        FVK_LOGD << "Resource Allocator state (debug only)" << utils::io::endl;
         for (size_t i = 0; i < RESOURCE_TYPE_COUNT; i++) {
-            utils::slog.d << "[" << i << "]=" << mDebugOnlyResourceCount[i] << utils::io::endl;
+            FVK_LOGD << "[" << i << "]=" << mDebugOnlyResourceCount[i] << utils::io::endl;
         }
-        utils::slog.d << "+++++++++++++++++++++++++++++++++++++" << utils::io::endl;
+        FVK_LOGD << "+++++++++++++++++++++++++++++++++++++" << utils::io::endl;
     }
 private:
     utils::FixedCapacityVector<size_t> mDebugOnlyResourceCount;

filament/backend/src/vulkan/VulkanSamplerCache.cpp

@@ -122,7 +122,7 @@ VkSampler VulkanSamplerCache::getSampler(SamplerParams params) noexcept {
     };
     VkSampler sampler;
     VkResult error = vkCreateSampler(mDevice, &samplerInfo, VKALLOC, &sampler);
-    ASSERT_POSTCONDITION(!error, "Unable to create sampler.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to create sampler.";
     mCache.insert({params, sampler});
     return sampler;
 }

filament/backend/src/vulkan/VulkanStagePool.cpp

@@ -61,7 +61,7 @@ VulkanStage const* VulkanStagePool::acquireStage(uint32_t numBytes) {
 
 #if FVK_ENABLED(FVK_DEBUG_ALLOCATION)
     if (result != VK_SUCCESS) {
-        utils::slog.e << "Allocation error: " << result << utils::io::endl;
+        FVK_LOGE << "Allocation error: " << result << utils::io::endl;
     }
 #endif
 

filament/backend/src/vulkan/VulkanSwapChain.cpp

@@ -35,27 +35,12 @@ VulkanSwapChain::VulkanSwapChain(VulkanPlatform* platform, VulkanContext const&
       mStagePool(stagePool),
       mHeadless(extent.width != 0 && extent.height != 0 && !nativeWindow),
       mFlushAndWaitOnResize(platform->getCustomization().flushAndWaitOnWindowResize),
-      mCurrentImageReadyIndex(0),
+      mTransitionSwapChainImageLayoutForPresent(
+            platform->getCustomization().transitionSwapChainImageLayoutForPresent),
       mAcquired(false),
       mIsFirstRenderPass(true) {
     swapChain = mPlatform->createSwapChain(nativeWindow, flags, extent);
-    ASSERT_POSTCONDITION(swapChain, "Unable to create swapchain");
-
-    VkSemaphoreCreateInfo const createInfo = {
-            .sType = VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO,
-    };
-
-    // No need to wait on this semaphore before drawing when in Headless mode.
-    if (mHeadless) {
-		// Set all sempahores to VK_NULL_HANDLE
-		memset(mImageReady, 0, sizeof(mImageReady[0]) * IMAGE_READY_SEMAPHORE_COUNT);
-	} else {
-		for (uint32_t i = 0; i < IMAGE_READY_SEMAPHORE_COUNT; ++i) {
-			VkResult result =
-					vkCreateSemaphore(mPlatform->getDevice(), &createInfo, nullptr, mImageReady + i);
-			ASSERT_POSTCONDITION(result == VK_SUCCESS, "Failed to create semaphore");
-		}
-    }
+    FILAMENT_CHECK_POSTCONDITION(swapChain) << "Unable to create swapchain";
 
     update();
 }
@@ -67,11 +52,6 @@ VulkanSwapChain::~VulkanSwapChain() {
     mCommands->wait();
 
     mPlatform->destroy(swapChain);
-	for (uint32_t i = 0; i < IMAGE_READY_SEMAPHORE_COUNT; ++i) {
-		if (mImageReady[i] != VK_NULL_HANDLE) {
-			vkDestroySemaphore(mPlatform->getDevice(), mImageReady[i], VKALLOC);
-		}
-	}
 }
 
 void VulkanSwapChain::update() {
@@ -94,7 +74,7 @@ void VulkanSwapChain::update() {
 }
 
 void VulkanSwapChain::present() {
-    if (!mHeadless) {
+    if (!mHeadless && mTransitionSwapChainImageLayoutForPresent) {
         VkCommandBuffer const cmdbuf = mCommands->get().buffer();
         VkImageSubresourceRange const subresources{
                 .aspectMask = VK_IMAGE_ASPECT_COLOR_BIT,
@@ -105,16 +85,21 @@ void VulkanSwapChain::present() {
         };
         mColors[mCurrentSwapIndex]->transitionLayout(cmdbuf, subresources, VulkanLayout::PRESENT);
     }
-    mCommands->flush();
 
-    // We only present if it is not headless.  No-op for headless (but note that we still need the
-    // flush() in the above line).
+    mCommands->flush();
+    
+    // call the image ready wait function
+    if (mExplicitImageReadyWait != nullptr) {
+        mExplicitImageReadyWait(swapChain);
+    }
+
+    // We only present if it is not headless. No-op for headless.
     if (!mHeadless) {
         VkSemaphore const finishedDrawing = mCommands->acquireFinishedSignal();
         VkResult const result = mPlatform->present(swapChain, mCurrentSwapIndex, finishedDrawing);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS || result == VK_SUBOPTIMAL_KHR ||
-                                     result == VK_ERROR_OUT_OF_DATE_KHR,
-                "Cannot present in swapchain.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS || result == VK_SUBOPTIMAL_KHR ||
+                result == VK_ERROR_OUT_OF_DATE_KHR)
+                << "Cannot present in swapchain.";
     }
 
     // We presented the last acquired buffer.
@@ -138,13 +123,14 @@ void VulkanSwapChain::acquire(bool& resized) {
         update();
     }
 
-	mCurrentImageReadyIndex = (mCurrentImageReadyIndex + 1) % IMAGE_READY_SEMAPHORE_COUNT;
-	const VkSemaphore imageReady = mImageReady[mCurrentImageReadyIndex];
-    VkResult const result = mPlatform->acquire(swapChain, imageReady, &mCurrentSwapIndex);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS || result == VK_SUBOPTIMAL_KHR,
-            "Cannot acquire in swapchain.");
-    if (imageReady != VK_NULL_HANDLE) {
-        mCommands->injectDependency(imageReady);
+    VulkanPlatform::ImageSyncData imageSyncData;
+    VkResult const result = mPlatform->acquire(swapChain, &imageSyncData);
+    mCurrentSwapIndex = imageSyncData.imageIndex;
+    mExplicitImageReadyWait = imageSyncData.explicitImageReadyWait;
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS || result == VK_SUBOPTIMAL_KHR) 
+        << "Cannot acquire in swapchain.";
+    if (imageSyncData.imageReadySemaphore != VK_NULL_HANDLE) {
+        mCommands->injectDependency(imageSyncData.imageReadySemaphore);
     }
     mAcquired = true;
 }

filament/backend/src/vulkan/VulkanSwapChain.h

@@ -50,7 +50,10 @@ struct VulkanSwapChain : public HwSwapChain, VulkanResource {
     void acquire(bool& reized);
 
     inline VulkanTexture* getCurrentColor() const noexcept {
-        return mColors[mCurrentSwapIndex].get();
+        uint32_t const imageIndex = mCurrentSwapIndex;
+        FILAMENT_CHECK_PRECONDITION(
+            imageIndex != VulkanPlatform::ImageSyncData::INVALID_IMAGE_INDEX);
+        return mColors[imageIndex].get();
     }
 
     inline VulkanTexture* getDepth() const noexcept {
@@ -80,15 +83,15 @@ private:
     VulkanStagePool& mStagePool;
     bool const mHeadless;
     bool const mFlushAndWaitOnResize;
+    bool const mTransitionSwapChainImageLayoutForPresent;
 
     // We create VulkanTextures based on VkImages. VulkanTexture has facilities for doing layout
     // transitions, which are useful here.
     utils::FixedCapacityVector<std::unique_ptr<VulkanTexture>> mColors;
     std::unique_ptr<VulkanTexture> mDepth;
     VkExtent2D mExtent;
-    VkSemaphore mImageReady[IMAGE_READY_SEMAPHORE_COUNT];
-	uint32_t mCurrentImageReadyIndex;
     uint32_t mCurrentSwapIndex;
+    std::function<void(Platform::SwapChain* handle)> mExplicitImageReadyWait = nullptr;
     bool mAcquired;
     bool mIsFirstRenderPass;
 };

filament/backend/src/vulkan/VulkanTexture.cpp

@@ -113,7 +113,7 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         VkFormatProperties props;
         vkGetPhysicalDeviceFormatProperties(physicalDevice, mVkFormat, &props);
         if (!(props.optimalTilingFeatures & VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT)) {
-            utils::slog.w << "Texture usage is SAMPLEABLE but format " << mVkFormat << " is not "
+            FVK_LOGW << "Texture usage is SAMPLEABLE but format " << mVkFormat << " is not "
                     "sampleable with optimal tiling." << utils::io::endl;
         }
 #endif
@@ -163,7 +163,7 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
 
     VkResult error = vkCreateImage(mDevice, &imageInfo, VKALLOC, &mTextureImage);
     if (error || FVK_ENABLED(FVK_DEBUG_TEXTURE)) {
-        utils::slog.d << "vkCreateImage: "
+        FVK_LOGD << "vkCreateImage: "
             << "image = " << mTextureImage << ", "
             << "result = " << error << ", "
             << "handle = " << utils::io::hex << mTextureImage << utils::io::dec << ", "
@@ -177,7 +177,7 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
             << "target = " << static_cast<int>(target) <<", "
             << "format = " << mVkFormat << utils::io::endl;
     }
-    ASSERT_POSTCONDITION(!error, "Unable to create image.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to create image.";
 
     // Allocate memory for the VkImage and bind it.
     VkMemoryRequirements memReqs = {};
@@ -186,8 +186,8 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
     uint32_t memoryTypeIndex
             = context.selectMemoryType(memReqs.memoryTypeBits, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
 
-    ASSERT_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES,
-            "VulkanTexture: unable to find a memory type that meets requirements.");
+    FILAMENT_CHECK_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES)
+            << "VulkanTexture: unable to find a memory type that meets requirements.";
 
     VkMemoryAllocateInfo allocInfo = {
         .sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,
@@ -195,9 +195,9 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         .memoryTypeIndex = memoryTypeIndex,
     };
     error = vkAllocateMemory(mDevice, &allocInfo, nullptr, &mTextureImageMemory);
-    ASSERT_POSTCONDITION(!error, "Unable to allocate image memory.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to allocate image memory.";
     error = vkBindImageMemory(mDevice, mTextureImage, mTextureImageMemory, 0);
-    ASSERT_POSTCONDITION(!error, "Unable to bind image.");
+    FILAMENT_CHECK_POSTCONDITION(!error) << "Unable to bind image.";
 
     uint32_t layerCount = 0;
     if (target == SamplerType::SAMPLER_CUBEMAP) {
@@ -450,7 +450,7 @@ void VulkanTexture::transitionLayout(VkCommandBuffer cmdbuf, const VkImageSubres
     }
 
 #if FVK_ENABLED(FVK_DEBUG_LAYOUT_TRANSITION)
-    utils::slog.d << "transition texture=" << mTextureImage
+    FVK_LOGD << "transition texture=" << mTextureImage
                   << " (" << range.baseArrayLayer
                   << "," << range.baseMipLevel << ")"
                   << " count=(" << range.layerCount
@@ -539,7 +539,7 @@ void VulkanTexture::print() const {
                 layer < (mPrimaryViewRange.baseArrayLayer + mPrimaryViewRange.layerCount) &&
                 level >= mPrimaryViewRange.baseMipLevel &&
                 level < (mPrimaryViewRange.baseMipLevel + mPrimaryViewRange.levelCount);
-            utils::slog.d << "[" << mTextureImage << "]: (" << layer << "," << level
+            FVK_LOGD << "[" << mTextureImage << "]: (" << layer << "," << level
                           << ")=" << getLayout(layer, level)
                           << " primary=" << primary
                           << utils::io::endl;
@@ -548,7 +548,7 @@ void VulkanTexture::print() const {
 
     for (auto view: mCachedImageViews) {
         auto& range = view.first.range;
-        utils::slog.d << "[" << mTextureImage << ", imageView=" << view.second << "]=>"
+        FVK_LOGD << "[" << mTextureImage << ", imageView=" << view.second << "]=>"
                       << " (" << range.baseArrayLayer << "," << range.baseMipLevel << ")"
                       << " count=(" << range.layerCount << "," << range.levelCount << ")"
                       << " aspect=" << range.aspectMask << " viewType=" << view.first.type

filament/backend/src/vulkan/VulkanUtility.cpp

@@ -51,7 +51,7 @@ VkFormat getVkFormat(ElementType type, bool normalized, bool integer) {
             case ElementType::SHORT4: return VK_FORMAT_R16G16B16A16_SNORM;
             case ElementType::USHORT4: return VK_FORMAT_R16G16B16A16_UNORM;
             default:
-                ASSERT_POSTCONDITION(false, "Normalized format does not exist.");
+                FILAMENT_CHECK_POSTCONDITION(false) << "Normalized format does not exist.";
                 return VK_FORMAT_UNDEFINED;
         }
     }

filament/backend/src/vulkan/VulkanUtility.h

@@ -56,13 +56,13 @@ uint8_t reduceSampleCount(uint8_t sampleCount, VkSampleCountFlags mask);
 // 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);\
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "enumerate size error");\
-    utils::FixedCapacityVector<OutType> ret(size);\
-    result = func(__VA_ARGS__, ret.data());\
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "enumerate error");\
+#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)

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

@@ -170,9 +170,9 @@ public:
         };
         VkDescriptorSet vkSet;
         UTILS_UNUSED VkResult result = vkAllocateDescriptorSets(mDevice, &allocInfo, &vkSet);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS,
-                "Failed to allocate descriptor set code=%d size=%d capacity=%d count=%s", result,
-                mSize, mCapacity);
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+                << "Failed to allocate descriptor set code=" << result << " size=" << mSize
+                << " capacity=" << mCapacity << " count=" << "%s";
         mSize++;
         return createSet(layout->bitmask, vkSet);
     }

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

@@ -95,7 +95,7 @@ void printDeviceInfo(VkInstance instance, VkPhysicalDevice device) {
                 .pNext = &driverProperties,
         };
         vkGetPhysicalDeviceProperties2(device, &physicalDeviceProperties2);
-        utils::slog.i << "Vulkan device driver: " << driverProperties.driverName << " "
+        FVK_LOGI << "Vulkan device driver: " << driverProperties.driverName << " "
                       << driverProperties.driverInfo << utils::io::endl;
     }
 
@@ -128,7 +128,7 @@ void printDeviceInfo(VkInstance instance, VkPhysicalDevice device) {
     const FixedCapacityVector<VkPhysicalDevice> physicalDevices
             = filament::backend::enumerate(vkEnumeratePhysicalDevices, instance);
 
-    utils::slog.i << "Selected physical device '" << deviceProperties.deviceName << "' from "
+    FVK_LOGI << "Selected physical device '" << deviceProperties.deviceName << "' from "
                   << physicalDevices.size() << " physical devices. "
                   << "(vendor " << utils::io::hex << vendorID << ", "
                   << "device " << deviceID << ", "
@@ -142,15 +142,15 @@ void printDepthFormats(VkPhysicalDevice device) {
     // Note that Vulkan is more constrained than OpenGL ES 3.1 in this area.
     const VkFormatFeatureFlags required = VK_FORMAT_FEATURE_DEPTH_STENCIL_ATTACHMENT_BIT
                                               | VK_FORMAT_FEATURE_SAMPLED_IMAGE_BIT;
-    utils::slog.i << "Sampleable depth formats: ";
+    FVK_LOGI << "Sampleable depth formats: ";
     for (VkFormat format : ALL_VK_FORMATS) {
         VkFormatProperties props;
         vkGetPhysicalDeviceFormatProperties(device, format, &props);
         if ((props.optimalTilingFeatures & required) == required) {
-            utils::slog.i << format << " ";
+            FVK_LOGI << format << " ";
         }
     }
-    utils::slog.i << utils::io::endl;
+    FVK_LOGI << utils::io::endl;
 }
 #endif
 
@@ -176,6 +176,12 @@ ExtensionSet getInstanceExtensions(ExtensionSet const& externallyRequiredExts =
                     static_cast<char const*>(nullptr) /* pLayerName */);
     for (auto const& extProps: availableExts) {
         utils::CString name { extProps.extensionName };
+
+        // To workaround an Adreno bug where the extension name could be of 0 length.
+        if (name.size() == 0) {
+            continue;
+        }
+
         if (setContains(TARGET_EXTS, name) || setContains(externallyRequiredExts, name)) {
             exts.insert(name);
         }
@@ -192,6 +198,7 @@ ExtensionSet getDeviceExtensions(VkPhysicalDevice device) {
             VK_KHR_MAINTENANCE1_EXTENSION_NAME,
             VK_KHR_MAINTENANCE2_EXTENSION_NAME,
             VK_KHR_MAINTENANCE3_EXTENSION_NAME,
+            VK_KHR_MULTIVIEW_EXTENSION_NAME,
     };
     ExtensionSet exts;
     // Identify supported physical device extensions
@@ -200,6 +207,12 @@ ExtensionSet getDeviceExtensions(VkPhysicalDevice device) {
                     static_cast<const char*>(nullptr) /* pLayerName */);
     for (auto const& extension: extensions) {
         utils::CString name { extension.extensionName };
+
+        // To workaround an Adreno bug where the extension name could be of 0 length.
+        if (name.size() == 0) {
+            continue;
+        }
+
         if (setContains(TARGET_EXTS, name)) {
             exts.insert(name);
         }
@@ -229,11 +242,11 @@ VkInstance createInstance(ExtensionSet const& requiredExts) {
         instanceCreateInfo.ppEnabledLayerNames = enabledLayers.data();
     } else {
 #if defined(__ANDROID__)
-        utils::slog.d << "Validation layers are not available; did you set jniLibs in your "
-                      << "gradle file?" << utils::io::endl;
+        FVK_LOGD << "Validation layers are not available; did you set jniLibs in your "
+                 << "gradle file?" << utils::io::endl;
 #else
-        utils::slog.d << "Validation layer not available; did you install the Vulkan SDK?\n"
-                      << "Please ensure that VK_LAYER_PATH is set correctly." << utils::io::endl;
+        FVK_LOGD << "Validation layer not available; did you install the Vulkan SDK?\n"
+                 << "Please ensure that VK_LAYER_PATH is set correctly." << utils::io::endl;
 #endif // __ANDROID__
 
     }
@@ -281,8 +294,8 @@ VkInstance createInstance(ExtensionSet const& requiredExts) {
     }
 
     VkResult result = vkCreateInstance(&instanceCreateInfo, VKALLOC, &instance);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to create Vulkan instance. Result=%d",
-            result);
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+            << "Unable to create Vulkan instance. Result=" << result;
     return instance;
 }
 
@@ -322,6 +335,7 @@ VkDevice createLogicalDevice(VkPhysicalDevice physicalDevice,
     deviceCreateInfo.enabledExtensionCount = (uint32_t) requestExtensions.size();
     deviceCreateInfo.ppEnabledExtensionNames = requestExtensions.data();
 
+    void* pNext = nullptr;
     VkPhysicalDevicePortabilitySubsetFeaturesKHR portability = {
             .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_PORTABILITY_SUBSET_FEATURES_KHR,
             .pNext = nullptr,
@@ -329,11 +343,26 @@ VkDevice createLogicalDevice(VkPhysicalDevice physicalDevice,
             .mutableComparisonSamplers = VK_TRUE,
     };
     if (setContains(deviceExtensions, VK_KHR_PORTABILITY_SUBSET_EXTENSION_NAME)) {
-        deviceCreateInfo.pNext = &portability;
+        portability.pNext = pNext;
+        pNext = &portability;
     }
 
+    VkPhysicalDeviceMultiviewFeaturesKHR multiview = {
+            .sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_MULTIVIEW_FEATURES_KHR,
+            .pNext = nullptr,
+            .multiview = VK_TRUE,
+            .multiviewGeometryShader = VK_FALSE,
+            .multiviewTessellationShader = VK_FALSE
+    };
+    if (setContains(deviceExtensions, VK_KHR_MULTIVIEW_EXTENSION_NAME)) {
+        multiview.pNext = pNext;
+        pNext = &multiview;
+    }
+
+    deviceCreateInfo.pNext = pNext;
+
     VkResult result = vkCreateDevice(physicalDevice, &deviceCreateInfo, VKALLOC, &device);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateDevice error=%d.", result);
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateDevice error=" << result << ".";
 
     return device;
 }
@@ -406,8 +435,8 @@ inline int deviceTypeOrder(VkPhysicalDeviceType deviceType) {
         case VK_PHYSICAL_DEVICE_TYPE_OTHER:
             return 1;
         default:
-            utils::slog.w << "deviceTypeOrder: Unexpected deviceType: " << deviceType
-                          << utils::io::endl;
+            FVK_LOGW << "deviceTypeOrder: Unexpected deviceType: " << deviceType
+                     << utils::io::endl;
             return -1;
     }
 }
@@ -467,9 +496,9 @@ VkPhysicalDevice selectPhysicalDevice(VkInstance instance,
         deviceList[deviceInd].name = targetDeviceProperties.deviceName;
     }
 
-    ASSERT_PRECONDITION(gpuPreference.index < static_cast<int32_t>(deviceList.size()),
-            "Provided GPU index=%d >= the number of GPUs=%d", gpuPreference.index,
-            static_cast<int32_t>(deviceList.size()));
+    FILAMENT_CHECK_PRECONDITION(gpuPreference.index < static_cast<int32_t>(deviceList.size()))
+            << "Provided GPU index=" << gpuPreference.index
+            << " >= the number of GPUs=" << static_cast<int32_t>(deviceList.size());
 
     // Sort the found devices
     std::sort(deviceList.begin(), deviceList.end(),
@@ -497,7 +526,7 @@ VkPhysicalDevice selectPhysicalDevice(VkInstance instance,
                 return deviceTypeOrder(a.deviceType) < deviceTypeOrder(b.deviceType);
             });
     auto device = deviceList.back().device;
-    ASSERT_POSTCONDITION(device != VK_NULL_HANDLE, "Unable to find suitable device.");
+    FILAMENT_CHECK_POSTCONDITION(device != VK_NULL_HANDLE) << "Unable to find suitable device.";
     return device;
 }
 
@@ -586,21 +615,21 @@ void VulkanPlatform::terminate() {
 Driver* VulkanPlatform::createDriver(void* sharedContext,
         const Platform::DriverConfig& driverConfig) noexcept {
     // Load Vulkan entry points.
-    ASSERT_POSTCONDITION(bluevk::initialize(), "BlueVK is unable to load entry points.");
+    FILAMENT_CHECK_POSTCONDITION(bluevk::initialize()) << "BlueVK is unable to load entry points.";
 
     if (sharedContext) {
         VulkanSharedContext const* scontext = (VulkanSharedContext const*) sharedContext;
         // All fields of VulkanSharedContext should be present.
-        ASSERT_PRECONDITION(scontext->instance != VK_NULL_HANDLE,
-                "Client needs to provide VkInstance");
-        ASSERT_PRECONDITION(scontext->physicalDevice != VK_NULL_HANDLE,
-                "Client needs to provide VkPhysicalDevice");
-        ASSERT_PRECONDITION(scontext->logicalDevice != VK_NULL_HANDLE,
-                "Client needs to provide VkDevice");
-        ASSERT_PRECONDITION(scontext->graphicsQueueFamilyIndex != INVALID_VK_INDEX,
-                "Client needs to provide graphics queue family index");
-        ASSERT_PRECONDITION(scontext->graphicsQueueIndex != INVALID_VK_INDEX,
-                "Client needs to provide graphics queue index");
+        FILAMENT_CHECK_PRECONDITION(scontext->instance != VK_NULL_HANDLE)
+                << "Client needs to provide VkInstance";
+        FILAMENT_CHECK_PRECONDITION(scontext->physicalDevice != VK_NULL_HANDLE)
+                << "Client needs to provide VkPhysicalDevice";
+        FILAMENT_CHECK_PRECONDITION(scontext->logicalDevice != VK_NULL_HANDLE)
+                << "Client needs to provide VkDevice";
+        FILAMENT_CHECK_PRECONDITION(scontext->graphicsQueueFamilyIndex != INVALID_VK_INDEX)
+                << "Client needs to provide graphics queue family index";
+        FILAMENT_CHECK_PRECONDITION(scontext->graphicsQueueIndex != INVALID_VK_INDEX)
+                << "Client needs to provide graphics queue index";
 
         mImpl->mInstance = scontext->instance;
         mImpl->mPhysicalDevice = scontext->physicalDevice;
@@ -646,8 +675,8 @@ Driver* VulkanPlatform::createDriver(void* sharedContext,
 
     VulkanPlatform::Customization::GPUPreference const pref = getCustomization().gpu;
     bool const hasGPUPreference = pref.index >= 0 || !pref.deviceName.empty();
-    ASSERT_PRECONDITION(!(hasGPUPreference && sharedContext),
-            "Cannot both share context and indicate GPU preference");
+    FILAMENT_CHECK_PRECONDITION(!(hasGPUPreference && sharedContext))
+            << "Cannot both share context and indicate GPU preference";
 
     mImpl->mPhysicalDevice = mImpl->mPhysicalDevice == VK_NULL_HANDLE
                                      ? selectPhysicalDevice(mImpl->mInstance, pref)
@@ -689,6 +718,10 @@ Driver* VulkanPlatform::createDriver(void* sharedContext,
                 = pruneExtensions(mImpl->mPhysicalDevice, instExts, deviceExts);
         instExts = prunedInstExts;
         deviceExts = prunedDeviceExts;
+
+        if (driverConfig.stereoscopicType != StereoscopicType::MULTIVIEW) {
+            deviceExts.erase(VK_KHR_MULTIVIEW_EXTENSION_NAME);
+        }
     }
 
     mImpl->mDevice
@@ -704,11 +737,12 @@ Driver* VulkanPlatform::createDriver(void* sharedContext,
     // Store the extension support in the context
     context.mDebugUtilsSupported = setContains(instExts, VK_EXT_DEBUG_UTILS_EXTENSION_NAME);
     context.mDebugMarkersSupported = setContains(deviceExts, VK_EXT_DEBUG_MARKER_EXTENSION_NAME);
+    context.mMultiviewEnabled = setContains(deviceExts, VK_KHR_MULTIVIEW_EXTENSION_NAME);
 
 #ifdef NDEBUG
     // If we are in release build, we should not have turned on debug extensions
-    ASSERT_POSTCONDITION(!context.mDebugUtilsSupported && !context.mDebugMarkersSupported,
-            "Debug utils should not be enabled in release build.");
+    FILAMENT_CHECK_POSTCONDITION(!context.mDebugUtilsSupported && !context.mDebugMarkersSupported)
+            << "Debug utils should not be enabled in release build.";
 #endif
 
     context.mDepthStencilFormats = findAttachmentDepthStencilFormats(mImpl->mPhysicalDevice);
@@ -738,8 +772,8 @@ VulkanPlatform::SwapChainBundle VulkanPlatform::getSwapChainBundle(SwapChainPtr
     SWAPCHAIN_RET_FUNC(getSwapChainBundle, handle, )
 }
 
-VkResult VulkanPlatform::acquire(SwapChainPtr handle, VkSemaphore clientSignal, uint32_t* index) {
-    SWAPCHAIN_RET_FUNC(acquire, handle, clientSignal, index)
+VkResult VulkanPlatform::acquire(SwapChainPtr handle, ImageSyncData* outImageSyncData) {
+    SWAPCHAIN_RET_FUNC(acquire, handle, outImageSyncData)
 }
 
 VkResult VulkanPlatform::present(SwapChainPtr handle, uint32_t index,

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

@@ -123,7 +123,7 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
         };
         VkResult const result = vkCreateAndroidSurfaceKHR(instance, &createInfo, VKALLOC,
                 (VkSurfaceKHR*) &surface);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateAndroidSurfaceKHR error.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateAndroidSurfaceKHR error.";
     #elif defined(__linux__) && defined(FILAMENT_SUPPORTS_WAYLAND)
         wl* ptrval = reinterpret_cast<wl*>(nativeWindow);
         extent.width = ptrval->width;
@@ -138,11 +138,11 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
         };
         VkResult const result = vkCreateWaylandSurfaceKHR(instance, &createInfo, VKALLOC,
                 (VkSurfaceKHR*) &surface);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateWaylandSurfaceKHR error.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateWaylandSurfaceKHR error.";
     #elif defined(LINUX_OR_FREEBSD) && defined(FILAMENT_SUPPORTS_X11)
         if (g_x11_vk.library == nullptr) {
             g_x11_vk.library = dlopen(LIBRARY_X11, RTLD_LOCAL | RTLD_NOW);
-            ASSERT_PRECONDITION(g_x11_vk.library, "Unable to open X11 library.");
+            FILAMENT_CHECK_PRECONDITION(g_x11_vk.library) << "Unable to open X11 library.";
             #if defined(FILAMENT_SUPPORTS_XCB)
                 g_x11_vk.xcbConnect = (XCB_CONNECT) dlsym(g_x11_vk.library, "xcb_connect");
                 int screen;
@@ -151,7 +151,7 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
             #if defined(FILAMENT_SUPPORTS_XLIB)
                 g_x11_vk.openDisplay = (X11_OPEN_DISPLAY) dlsym(g_x11_vk.library, "XOpenDisplay");
                 g_x11_vk.display = g_x11_vk.openDisplay(NULL);
-                ASSERT_PRECONDITION(g_x11_vk.display, "Unable to open X11 display.");
+                FILAMENT_CHECK_PRECONDITION(g_x11_vk.display) << "Unable to open X11 display.";
             #endif
         }
         #if defined(FILAMENT_SUPPORTS_XCB) || defined(FILAMENT_SUPPORTS_XLIB)
@@ -164,8 +164,8 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
                 useXcb = true;
             #endif
             if (useXcb) {
-                ASSERT_POSTCONDITION(vkCreateXcbSurfaceKHR,
-                        "Unable to load vkCreateXcbSurfaceKHR function.");
+                FILAMENT_CHECK_POSTCONDITION(vkCreateXcbSurfaceKHR)
+                        << "Unable to load vkCreateXcbSurfaceKHR function.";
 
                 VkXcbSurfaceCreateInfoKHR const createInfo = {
                         .sType = VK_STRUCTURE_TYPE_XCB_SURFACE_CREATE_INFO_KHR,
@@ -174,13 +174,14 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
                 };
                 VkResult const result = vkCreateXcbSurfaceKHR(instance, &createInfo, VKALLOC,
                         (VkSurfaceKHR*) &surface);
-                ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateXcbSurfaceKHR error.");
+                FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+                        << "vkCreateXcbSurfaceKHR error.";
             }
         #endif
         #if defined(FILAMENT_SUPPORTS_XLIB)
             if (!useXcb) {
-                ASSERT_POSTCONDITION(vkCreateXlibSurfaceKHR,
-                        "Unable to load vkCreateXlibSurfaceKHR function.");
+                FILAMENT_CHECK_POSTCONDITION(vkCreateXlibSurfaceKHR)
+                        << "Unable to load vkCreateXlibSurfaceKHR function.";
 
                 VkXlibSurfaceCreateInfoKHR const createInfo = {
                         .sType = VK_STRUCTURE_TYPE_XLIB_SURFACE_CREATE_INFO_KHR,
@@ -189,7 +190,8 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
                 };
                 VkResult const result = vkCreateXlibSurfaceKHR(instance, &createInfo, VKALLOC,
                         (VkSurfaceKHR*) &surface);
-                ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateXlibSurfaceKHR error.");
+                FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+                        << "vkCreateXlibSurfaceKHR error.";
             }
         #endif
     #elif defined(WIN32)
@@ -200,7 +202,7 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
         };
         VkResult const result = vkCreateWin32SurfaceKHR(instance, &createInfo, nullptr,
                 (VkSurfaceKHR*) &surface);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateWin32SurfaceKHR error.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateWin32SurfaceKHR error.";
     #endif
     return std::make_tuple(surface, extent);
 }

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

@@ -68,20 +68,22 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
     VkSurfaceKHR surface;
     #if defined(__APPLE__)
         NSView* nsview = (__bridge NSView*) nativeWindow;
-        ASSERT_POSTCONDITION(nsview, "Unable to obtain Metal-backed NSView.");
+        FILAMENT_CHECK_POSTCONDITION(nsview) << "Unable to obtain Metal-backed NSView.";
 
         // Create the VkSurface.
-        ASSERT_POSTCONDITION(vkCreateMacOSSurfaceMVK, "Unable to load vkCreateMacOSSurfaceMVK.");
+        FILAMENT_CHECK_POSTCONDITION(vkCreateMacOSSurfaceMVK)
+                << "Unable to load vkCreateMacOSSurfaceMVK.";
         VkMacOSSurfaceCreateInfoMVK createInfo = {};
         createInfo.sType = VK_STRUCTURE_TYPE_MACOS_SURFACE_CREATE_INFO_MVK;
         createInfo.pView = (__bridge void*) nsview;
         VkResult result = vkCreateMacOSSurfaceMVK((VkInstance) instance, &createInfo, VKALLOC,
                 (VkSurfaceKHR*) &surface);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateMacOSSurfaceMVK error.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateMacOSSurfaceMVK error.";
     #elif defined(IOS) && defined(METAL_AVAILABLE)
         CAMetalLayer* metalLayer = (CAMetalLayer*) nativeWindow;
         // Create the VkSurface.
-        ASSERT_POSTCONDITION(vkCreateIOSSurfaceMVK, "Unable to load vkCreateIOSSurfaceMVK function.");
+        FILAMENT_CHECK_POSTCONDITION(vkCreateIOSSurfaceMVK)
+                << "Unable to load vkCreateIOSSurfaceMVK function.";
         VkIOSSurfaceCreateInfoMVK createInfo = {};
         createInfo.sType = VK_STRUCTURE_TYPE_IOS_SURFACE_CREATE_INFO_MVK;
         createInfo.pNext = NULL;
@@ -89,7 +91,7 @@ VulkanPlatform::SurfaceBundle VulkanPlatform::createVkSurfaceKHR(void* nativeWin
         createInfo.pView = metalLayer;
         VkResult result = vkCreateIOSSurfaceMVK((VkInstance) instance, &createInfo, VKALLOC,
                 (VkSurfaceKHR*) &surface);
-        ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkCreateIOSSurfaceMVK error.");
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "vkCreateIOSSurfaceMVK error.";
     #endif
     return std::make_tuple(surface, VkExtent2D {});
 }

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

@@ -50,8 +50,8 @@ std::tuple<VkImage, VkDeviceMemory> createImageAndMemory(VulkanContext const& co
     };
     VkImage image;
     VkResult result = vkCreateImage(device, &imageInfo, VKALLOC, &image);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS,
-            "Unable to create image: ", static_cast<int32_t>(result));
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+            << "Unable to create image: " << static_cast<int32_t>(result);
 
     // Allocate memory for the VkImage and bind it.
     VkDeviceMemory imageMemory;
@@ -61,8 +61,8 @@ std::tuple<VkImage, VkDeviceMemory> createImageAndMemory(VulkanContext const& co
     uint32_t memoryTypeIndex
             = context.selectMemoryType(memReqs.memoryTypeBits, VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
 
-    ASSERT_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES,
-            "VulkanPlatformSwapChainImpl: unable to find a memory type that meets requirements.");
+    FILAMENT_CHECK_POSTCONDITION(memoryTypeIndex < VK_MAX_MEMORY_TYPES)
+            << "VulkanPlatformSwapChainImpl: unable to find a memory type that meets requirements.";
 
     VkMemoryAllocateInfo allocInfo = {
             .sType = VK_STRUCTURE_TYPE_MEMORY_ALLOCATE_INFO,
@@ -70,9 +70,9 @@ std::tuple<VkImage, VkDeviceMemory> createImageAndMemory(VulkanContext const& co
             .memoryTypeIndex = memoryTypeIndex,
     };
     result = vkAllocateMemory(device, &allocInfo, nullptr, &imageMemory);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to allocate image memory.");
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "Unable to allocate image memory.";
     result = vkBindImageMemory(device, image, imageMemory, 0);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "Unable to bind image.");
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "Unable to bind image.";
     return std::tuple(image, imageMemory);
 }
 
@@ -133,6 +133,7 @@ VulkanPlatformSurfaceSwapChain::VulkanPlatformSurfaceSwapChain(VulkanContext con
 VulkanPlatformSurfaceSwapChain::~VulkanPlatformSurfaceSwapChain() {
     vkDestroySwapchainKHR(mDevice, mSwapchain, VKALLOC);
     vkDestroySurfaceKHR(mInstance, mSurface, VKALLOC);
+    destroy();
 }
 
 VkResult VulkanPlatformSurfaceSwapChain::create() {
@@ -153,7 +154,7 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
     // the number of images, though there may be limits related to the total amount of memory used
     // by presentable images."
     if (maxImageCount != 0 && desiredImageCount > maxImageCount) {
-        utils::slog.e << "Swap chain does not support " << desiredImageCount << " images."
+        FVK_LOGE << "Swap chain does not support " << desiredImageCount << " images."
                       << utils::io::endl;
         desiredImageCount = caps.minImageCount;
     }
@@ -178,8 +179,8 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
             break;
         }
     }
-    ASSERT_POSTCONDITION(surfaceFormat.format != VK_FORMAT_UNDEFINED,
-            "Cannot find suitable swapchain format");
+    FILAMENT_CHECK_POSTCONDITION(surfaceFormat.format != VK_FORMAT_UNDEFINED)
+            << "Cannot find suitable swapchain format";
 
     // 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)
@@ -193,8 +194,8 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
             break;
         }
     }
-    ASSERT_POSTCONDITION(foundSuitablePresentMode,
-            "Desired present mode is not supported by this device.");
+    FILAMENT_CHECK_POSTCONDITION(foundSuitablePresentMode)
+            << "Desired present mode is not supported by this device.";
 
     // Create the low-level swap chain.
     if (caps.currentExtent.width == VULKAN_UNDEFINED_EXTENT
@@ -237,8 +238,8 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
             .oldSwapchain = mSwapchain,
     };
     VkResult result = vkCreateSwapchainKHR(mDevice, &createInfo, VKALLOC, &mSwapchain);
-    ASSERT_POSTCONDITION(result == VK_SUCCESS, "vkGetPhysicalDeviceSurfaceFormatsKHR error: %d",
-            static_cast<int32_t>(result));
+    FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS)
+            << "vkGetPhysicalDeviceSurfaceFormatsKHR error: " << static_cast<int32_t>(result);
 
     mSwapChainBundle.colors = enumerate(vkGetSwapchainImagesKHR, mDevice, mSwapchain);
     mSwapChainBundle.colorFormat = surfaceFormat.format;
@@ -246,7 +247,7 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
             selectDepthFormat(mContext.getAttachmentDepthStencilFormats(), mHasStencil);
     mSwapChainBundle.depth = createImage(mSwapChainBundle.extent, mSwapChainBundle.depthFormat);
 
-    slog.i << "vkCreateSwapchain"
+    FVK_LOGI << "vkCreateSwapchain"
            << ": " << mSwapChainBundle.extent.width << "x" << mSwapChainBundle.extent.height << ", "
            << surfaceFormat.format << ", " << surfaceFormat.colorSpace << ", "
            << "swapchain-size=" << mSwapChainBundle.colors.size() << ", "
@@ -254,19 +255,29 @@ VkResult VulkanPlatformSurfaceSwapChain::create() {
            << "depth=" << mSwapChainBundle.depthFormat
            << io::endl;
 
+    VkSemaphoreCreateInfo const semaphoreCreateInfo = {
+            .sType = VK_STRUCTURE_TYPE_SEMAPHORE_CREATE_INFO,
+    };
+
+    for (uint32_t i = 0; i < IMAGE_READY_SEMAPHORE_COUNT; ++i) {
+        VkResult result = vkCreateSemaphore(mDevice, &semaphoreCreateInfo, nullptr,
+                mImageReady + i);
+        FILAMENT_CHECK_POSTCONDITION(result == VK_SUCCESS) << "Failed to create semaphore";
+    }
+
     return result;
 }
 
-VkResult VulkanPlatformSurfaceSwapChain::acquire(VkSemaphore clientSignal, uint32_t* index) {
-    // This immediately retrieves the index of the next available presentable image, and
-    // asynchronously requests the GPU to trigger the "imageAvailable" semaphore.
-    VkResult result = vkAcquireNextImageKHR(mDevice, mSwapchain, UINT64_MAX, clientSignal,
-            VK_NULL_HANDLE, index);
+VkResult VulkanPlatformSurfaceSwapChain::acquire(VulkanPlatform::ImageSyncData* outImageSyncData) {
+    mCurrentImageReadyIndex = (mCurrentImageReadyIndex + 1) % IMAGE_READY_SEMAPHORE_COUNT;
+    outImageSyncData->imageReadySemaphore = mImageReady[mCurrentImageReadyIndex];
+    VkResult result = vkAcquireNextImageKHR(mDevice, mSwapchain, UINT64_MAX,
+            outImageSyncData->imageReadySemaphore, VK_NULL_HANDLE, &outImageSyncData->imageIndex);
 
     // Users should be notified of a suboptimal surface, but it should not cause a cascade of
     // log messages or a loop of re-creations.
     if (result == VK_SUBOPTIMAL_KHR && !mSuboptimal) {
-        slog.w << "Vulkan Driver: Suboptimal swap chain." << io::endl;
+        FVK_LOGW << "Vulkan Driver: Suboptimal swap chain." << io::endl;
         mSuboptimal = true;
     }
     return result;
@@ -288,7 +299,7 @@ VkResult VulkanPlatformSurfaceSwapChain::present(uint32_t index, VkSemaphore fin
     // On Android Q and above, a suboptimal surface is always reported after screen rotation:
     // https://android-developers.googleblog.com/2020/02/handling-device-orientation-efficiently.html
     if (result == VK_SUBOPTIMAL_KHR && !mSuboptimal) {
-        utils::slog.w << "Vulkan Driver: Suboptimal swap chain." << utils::io::endl;
+        FVK_LOGW << "Vulkan Driver: Suboptimal swap chain." << utils::io::endl;
         mSuboptimal = true;
     }
     return result;
@@ -312,6 +323,17 @@ VkResult VulkanPlatformSurfaceSwapChain::recreate() {
     return create();
 }
 
+void VulkanPlatformSurfaceSwapChain::destroy() {
+    VulkanPlatformSwapChainImpl::destroy();
+
+    for (uint32_t i = 0; i < IMAGE_READY_SEMAPHORE_COUNT; ++i) {
+        if (mImageReady[i] != VK_NULL_HANDLE) {
+            vkDestroySemaphore(mDevice, mImageReady[i], VKALLOC);
+            mImageReady[i] = VK_NULL_HANDLE;
+        }
+    }
+}
+
 VulkanPlatformHeadlessSwapChain::VulkanPlatformHeadlessSwapChain(VulkanContext const& context,
         VkDevice device, VkQueue queue, VkExtent2D extent, uint64_t flags)
     : VulkanPlatformSwapChainImpl(context, device, queue),
@@ -343,8 +365,8 @@ VkResult VulkanPlatformHeadlessSwapChain::present(uint32_t index, VkSemaphore fi
     return VK_SUCCESS;
 }
 
-VkResult VulkanPlatformHeadlessSwapChain::acquire(VkSemaphore clientSignal, uint32_t* index) {
-    *index = mCurrentIndex;
+VkResult VulkanPlatformHeadlessSwapChain::acquire(VulkanPlatform::ImageSyncData* outImageSyncData) {
+    outImageSyncData->imageIndex = mCurrentIndex;
     mCurrentIndex = (mCurrentIndex + 1) % HEADLESS_SWAPCHAIN_SIZE;
     return VK_SUCCESS;
 }

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

@@ -42,7 +42,7 @@ struct VulkanPlatformSwapChainImpl : public Platform::SwapChain {
     ~VulkanPlatformSwapChainImpl();
 
     // Non-virtual override-able method
-    VkResult acquire(VkSemaphore clientSignal, uint32_t* index) {
+    VkResult acquire(VulkanPlatform::ImageSyncData* outImageSyncData) {
         PANIC_PRECONDITION("Should not be called");
         return VK_ERROR_UNKNOWN;
     }
@@ -86,7 +86,7 @@ struct VulkanPlatformSurfaceSwapChain : public VulkanPlatformSwapChainImpl {
     ~VulkanPlatformSurfaceSwapChain();
 
     // Non-virtual override
-    VkResult acquire(VkSemaphore clientSignal, uint32_t* index);
+    VkResult acquire(VulkanPlatform::ImageSyncData* outImageSyncData);
 
     // Non-virtual override
     VkResult present(uint32_t index, VkSemaphore finished);
@@ -97,7 +97,13 @@ struct VulkanPlatformSurfaceSwapChain : public VulkanPlatformSwapChainImpl {
     // Non-virtual override-able method
     bool hasResized();
 
+protected:
+    // Non-virtual override-able method
+    void destroy();
+
 private:
+    static constexpr int IMAGE_READY_SEMAPHORE_COUNT = FVK_MAX_COMMAND_BUFFERS;
+    
     VkResult create();
 
     VkInstance mInstance;
@@ -106,6 +112,8 @@ private:
     VkSurfaceKHR mSurface;
     VkSwapchainKHR mSwapchain = VK_NULL_HANDLE;
     VkExtent2D const mFallbackExtent;
+    VkSemaphore mImageReady[IMAGE_READY_SEMAPHORE_COUNT];
+    uint32_t mCurrentImageReadyIndex;
 
     bool mUsesRGB = false;
     bool mHasStencil = false;
@@ -121,7 +129,7 @@ struct VulkanPlatformHeadlessSwapChain : public VulkanPlatformSwapChainImpl {
     ~VulkanPlatformHeadlessSwapChain();
 
     // Non-virtual override
-    VkResult acquire(VkSemaphore clientSignal, uint32_t* index);
+    VkResult acquire(VulkanPlatform::ImageSyncData* outImageSyncData);
 
     // Non-virtual override
     VkResult present(uint32_t index, VkSemaphore finished);

filament/backend/src/vulkan/spirv/VulkanSpirvUtils.cpp

@@ -25,6 +25,7 @@
 #include <unordered_map>
 #include <variant>
 #include <vector>
+#include <cstring>
 
 namespace filament::backend {
 

filament/include/filament/Engine.h

@@ -298,6 +298,24 @@ public:
          */
         size_t textureUseAfterFreePoolSize = 0;
 
+        /**
+         * When uploading vertex or index data, the Filament Metal backend copies data
+         * into a shared staging area before transferring it to the GPU. This setting controls
+         * the total size of the buffer used to perform these allocations.
+         *
+         * Higher values can improve performance when performing many uploads across a small
+         * number of frames.
+         *
+         * This buffer remains alive throughout the lifetime of the Engine, so this size adds to the
+         * memory footprint of the app and should be set as conservative as possible.
+         *
+         * A value of 0 disables the shared staging buffer entirely; uploads will acquire an
+         * individual buffer from a pool of shared buffers.
+         *
+         * Only respected by the Metal backend.
+         */
+        size_t metalUploadBufferSizeBytes = 512 * 1024;
+
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL and Metal backends.
@@ -930,6 +948,14 @@ public:
      */
     void pumpMessageQueues();
 
+    /**
+     * Switch the command queue to unprotected mode. Protected mode can be activated via
+     * Renderer::beginFrame() using a protected SwapChain.
+     * @see Renderer
+     * @see SwapChain
+     */
+    void unprotected() noexcept;
+
     /**
      * Returns the default Material.
      *
@@ -1013,6 +1039,21 @@ public:
     void resetBackendState() noexcept;
 #endif
 
+    /**
+     * Get the current time. This is a convenience function that simply returns the
+     * time in nanosecond since epoch of std::chrono::steady_clock.
+     * A possible implementation is:
+     *
+     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+     *     return std::chrono::steady_clock::now().time_since_epoch().count();
+     * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+     *
+     * @return current time in nanosecond since epoch of std::chrono::steady_clock.
+     * @see Renderer::beginFrame()
+     */
+    static uint64_t getSteadyClockTimeNano() noexcept;
+
+
     DebugRegistry& getDebugRegistry() noexcept;
 
 protected:

filament/include/filament/IndirectLight.h

@@ -158,6 +158,8 @@ public:
          *
          * @return This Builder, for chaining calls.
          *
+         * @see Material::Builder::sphericalHarmonicsBandCount()
+         *
          * @note
          * Because the coefficients are pre-scaled, `sh[0]` is the environment's
          * average irradiance.

filament/include/filament/Material.h

@@ -140,6 +140,18 @@ public:
             return constant(name, strlen(name), value);
         }
 
+        /**
+         * Sets the quality of the indirect lights computations. This is only taken into account
+         * if this material is lit and in the surface domain. This setting will affect the
+         * IndirectLight computation if one is specified on the Scene and Spherical Harmonics
+         * are used for the irradiance.
+         *
+         * @param shBandCount Number of spherical harmonic bands. Must be 1, 2 or 3 (default).
+         * @return Reference to this Builder for chaining calls.
+         * @see IndirectLight
+         */
+        Builder& sphericalHarmonicsBandCount(size_t shBandCount) noexcept;
+
         /**
          * Creates the Material object and returns a pointer to it.
          *

filament/include/filament/MaterialInstance.h

@@ -140,6 +140,7 @@ public:
      * @param values        Array of values to set to the named parameter array.
      * @param count         Size of the array to set.
      * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
+     * @see Material::hasParameter
      */
     template<typename T, typename = is_supported_parameter_t<T>>
     void setParameter(const char* UTILS_NONNULL name, size_t nameLength,
@@ -234,6 +235,32 @@ public:
         setParameter(name, strlen(name), type, color);
     }
 
+    /**
+     * Gets the value of a parameter by name.
+     * 
+     * Note: Only supports non-texture parameters such as numeric and math types.
+     * 
+     * @param name          Name of the parameter as defined by Material. Cannot be nullptr.
+     * @param nameLength    Length in `char` of the name parameter.
+     * @throws utils::PreConditionPanic if name doesn't exist or no-op if exceptions are disabled.
+     * 
+     * @see Material::hasParameter
+     */
+    template<typename T>
+    T getParameter(const char* UTILS_NONNULL name, size_t nameLength) const;
+
+    /** 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 {
+        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 {
+        return getParameter<T>(name, strlen(name));
+    }
+
     /**
      * Set-up a custom scissor rectangle; by default it is disabled.
      *

filament/include/filament/Renderer.h

@@ -227,6 +227,17 @@ public:
     static constexpr CopyFrameFlag CLEAR = 0x4;
 
 
+    /**
+     * The use of this method is optional. It sets the VSYNC time expressed as the duration in
+     * nanosecond since epoch of std::chrono::steady_clock.
+     * If called, passing 0 to vsyncSteadyClockTimeNano in Renderer::BeginFrame will use this
+     * time instead.
+     * @param steadyClockTimeNano duration in nanosecond since epoch of std::chrono::steady_clock
+     * @see Engine::getSteadyClockTimeNano()
+     * @see Renderer::BeginFrame()
+     */
+    void setVsyncTime(uint64_t steadyClockTimeNano) noexcept;
+
     /**
      * Set-up a frame for this Renderer.
      *

filament/include/filament/SwapChain.h

@@ -116,7 +116,7 @@ class Engine;
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  * SDL_SysWMinfo wmi;
  * SDL_VERSION(&wmi.version);
- * ASSERT_POSTCONDITION(SDL_GetWindowWMInfo(sdlWindow, &wmi), "SDL version unsupported!");
+ * FILAMENT_CHECK_POSTCONDITION(SDL_GetWindowWMInfo(sdlWindow, &wmi)) << "SDL version unsupported!";
  * HDC nativeWindow = (HDC) wmi.info.win.hdc;
  *
  * using namespace filament;

filament/src/Engine.cpp

@@ -39,6 +39,8 @@
 #include <utils/compiler.h>
 #include <utils/Panic.h>
 
+#include <chrono>
+
 #include <stddef.h>
 #include <stdint.h>
 
@@ -299,7 +301,8 @@ void* Engine::streamAlloc(size_t size, size_t alignment) noexcept {
 // The external-facing execute does a flush, and is meant only for single-threaded environments.
 // It also discards the boolean return value, which would otherwise indicate a thread exit.
 void Engine::execute() {
-    ASSERT_PRECONDITION(!UTILS_HAS_THREADING, "Execute is meant for single-threaded platforms.");
+    FILAMENT_CHECK_PRECONDITION(!UTILS_HAS_THREADING)
+            << "Execute is meant for single-threaded platforms.";
     downcast(this)->flush();
     downcast(this)->execute();
 }
@@ -309,12 +312,14 @@ utils::JobSystem& Engine::getJobSystem() noexcept {
 }
 
 bool Engine::isPaused() const noexcept {
-    ASSERT_PRECONDITION(UTILS_HAS_THREADING, "Pause is meant for multi-threaded platforms.");
+    FILAMENT_CHECK_PRECONDITION(UTILS_HAS_THREADING)
+            << "Pause is meant for multi-threaded platforms.";
     return downcast(this)->isPaused();
 }
 
 void Engine::setPaused(bool paused) {
-    ASSERT_PRECONDITION(UTILS_HAS_THREADING, "Pause is meant for multi-threaded platforms.");
+    FILAMENT_CHECK_PRECONDITION(UTILS_HAS_THREADING)
+            << "Pause is meant for multi-threaded platforms.";
     downcast(this)->setPaused(paused);
 }
 
@@ -326,6 +331,10 @@ void Engine::pumpMessageQueues() {
     downcast(this)->pumpMessageQueues();
 }
 
+void Engine::unprotected() noexcept {
+    downcast(this)->unprotected();
+}
+
 void Engine::setAutomaticInstancingEnabled(bool enable) noexcept {
     downcast(this)->setAutomaticInstancingEnabled(enable);
 }
@@ -354,7 +363,7 @@ const Engine::Config& Engine::getConfig() const noexcept {
     return downcast(this)->getConfig();
 }
 
-bool Engine::isStereoSupported(StereoscopicType stereoscopicType) const noexcept {
+bool Engine::isStereoSupported(StereoscopicType) const noexcept {
     return downcast(this)->isStereoSupported();
 }
 
@@ -362,6 +371,10 @@ size_t Engine::getMaxStereoscopicEyes() noexcept {
     return FEngine::getMaxStereoscopicEyes();
 }
 
+uint64_t Engine::getSteadyClockTimeNano() noexcept {
+    return std::chrono::steady_clock::now().time_since_epoch().count();
+}
+
 #if defined(__EMSCRIPTEN__)
 void Engine::resetBackendState() noexcept {
     downcast(this)->resetBackendState();

filament/src/MaterialInstance.cpp

@@ -183,6 +183,35 @@ template UTILS_PUBLIC void MaterialInstance::setParameter<mat4f>   (const char*
 
 // ------------------------------------------------------------------------------------------------
 
+template<typename T>
+T FMaterialInstance::getParameterImpl(std::string_view name) const {
+    ssize_t offset = mMaterial->getUniformInterfaceBlock().getFieldOffset(name, 0);
+    assert_invariant(offset>=0);
+    return downcast(this)->getUniformBuffer().getUniform<T>(offset);
+}
+
+template<typename T>
+T MaterialInstance::getParameter(const char* name, size_t nameLength) const {
+    return downcast(this)->getParameterImpl<T>({ name, nameLength });
+}
+
+// explicit template instantiation of our supported types
+template UTILS_PUBLIC float MaterialInstance::getParameter<float>        (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC int32_t MaterialInstance::getParameter<int32_t>  (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC uint32_t MaterialInstance::getParameter<uint32_t>(const char* name, size_t nameLength) const;
+template UTILS_PUBLIC int2 MaterialInstance::getParameter<int2>        (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC int3 MaterialInstance::getParameter<int3>        (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC int4 MaterialInstance::getParameter<int4>        (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC uint2 MaterialInstance::getParameter<uint2>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC uint3 MaterialInstance::getParameter<uint3>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC uint4 MaterialInstance::getParameter<uint4>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC float2 MaterialInstance::getParameter<float2>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC float3 MaterialInstance::getParameter<float3>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC float4 MaterialInstance::getParameter<float4>      (const char* name, size_t nameLength) const;
+template UTILS_PUBLIC mat3f MaterialInstance::getParameter<mat3f>      (const char* name, size_t nameLength) const;
+
+// ------------------------------------------------------------------------------------------------
+
 Material const* MaterialInstance::getMaterial() const noexcept {
     return downcast(this)->getMaterial();
 }

filament/src/RenderPass.cpp

@@ -80,7 +80,8 @@ RenderPassBuilder& RenderPassBuilder::customCommand(
 }
 
 RenderPass RenderPassBuilder::build(FEngine& engine) {
-    ASSERT_POSTCONDITION(mRenderableSoa, "RenderPassBuilder::geometry() hasn't been called");
+    FILAMENT_CHECK_POSTCONDITION(mRenderableSoa)
+            << "RenderPassBuilder::geometry() hasn't been called";
     assert_invariant(mScissorViewport.width  <= std::numeric_limits<int32_t>::max());
     assert_invariant(mScissorViewport.height <= std::numeric_limits<int32_t>::max());
     return RenderPass{ engine, *this };

filament/src/Renderer.cpp

@@ -89,4 +89,8 @@ void Renderer::renderStandaloneView(View const* view) {
     downcast(this)->renderStandaloneView(downcast(view));
 }
 
+void Renderer::setVsyncTime(uint64_t steadyClockTimeNano) noexcept {
+    downcast(this)->setVsyncTime(steadyClockTimeNano);
+}
+
 } // namespace filament

filament/src/RendererUtils.cpp

@@ -353,14 +353,12 @@ UTILS_NOINLINE
 void RendererUtils::readPixels(backend::DriverApi& driver, Handle<HwRenderTarget> renderTargetHandle,
         uint32_t xoffset, uint32_t yoffset, uint32_t width, uint32_t height,
         backend::PixelBufferDescriptor&& buffer) {
-    ASSERT_PRECONDITION(
-            buffer.type != PixelDataType::COMPRESSED,
-            "buffer.format cannot be COMPRESSED");
+    FILAMENT_CHECK_PRECONDITION(buffer.type != PixelDataType::COMPRESSED)
+            << "buffer.format cannot be COMPRESSED";
 
-    ASSERT_PRECONDITION(
-            buffer.alignment > 0 && buffer.alignment <= 8 &&
-            !(buffer.alignment & (buffer.alignment - 1u)),
-            "buffer.alignment must be 1, 2, 4 or 8");
+    FILAMENT_CHECK_PRECONDITION(buffer.alignment > 0 && buffer.alignment <= 8 &&
+            !(buffer.alignment & (buffer.alignment - 1u)))
+            << "buffer.alignment must be 1, 2, 4 or 8";
 
     // It's not really possible to know here which formats will be supported because
     // it can vary depending on the RenderTarget, in GL the following are ALWAYS supported though:
@@ -373,8 +371,9 @@ void RendererUtils::readPixels(backend::DriverApi& driver, Handle<HwRenderTarget
             buffer.top + height,
             buffer.alignment);
 
-    ASSERT_PRECONDITION(buffer.size >= sizeNeeded,
-            "Pixel buffer too small: has %u bytes, needs %u bytes", buffer.size, sizeNeeded);
+    FILAMENT_CHECK_PRECONDITION(buffer.size >= sizeNeeded)
+            << "Pixel buffer too small: has " << buffer.size << " bytes, needs " << sizeNeeded
+            << " bytes";
 
     driver.readPixels(renderTargetHandle, xoffset, yoffset, width, height, std::move(buffer));
 }

filament/src/components/RenderableManager.cpp

@@ -322,19 +322,21 @@ void RenderableManager::BuilderDetails::processBoneIndicesAndWights(Engine& engi
     for (auto& bonePair: mBonePairs) {
         auto primitiveIndex = bonePair.first;
         auto entries = mEntries;
-        ASSERT_PRECONDITION(primitiveIndex < entries.size() && primitiveIndex >= 0,
-            "[primitive @ %u] primitiveindex is out of size (%u)", primitiveIndex, entries.size());
+        FILAMENT_CHECK_PRECONDITION(primitiveIndex < entries.size() && primitiveIndex >= 0)
+                << "[primitive @ " << primitiveIndex << "] primitiveindex is out of size ("
+                << entries.size() << ")";
         auto entry = mEntries[primitiveIndex];
         auto bonePairsForPrimitive = bonePair.second;
         auto vertexCount = entry.vertices->getVertexCount();
-        ASSERT_PRECONDITION(bonePairsForPrimitive.size() == vertexCount,
-            "[primitive @ %u] bone indices and weights pairs count (%u) must be equal to vertex count (%u)",
-            primitiveIndex, bonePairsForPrimitive.size(), vertexCount);
+        FILAMENT_CHECK_PRECONDITION(bonePairsForPrimitive.size() == vertexCount)
+                << "[primitive @ " << primitiveIndex << "] bone indices and weights pairs count ("
+                << bonePairsForPrimitive.size() << ") must be equal to vertex count ("
+                << vertexCount << ")";
         auto const& declaredAttributes = downcast(entry.vertices)->getDeclaredAttributes();
-        ASSERT_PRECONDITION(declaredAttributes[VertexAttribute::BONE_INDICES]
-        || declaredAttributes[VertexAttribute::BONE_WEIGHTS],
-            "[entity=%u, primitive @ %u] for advanced skinning set VertexBuffer::Builder::advancedSkinning()",
-            entity.getId(), primitiveIndex);
+        FILAMENT_CHECK_PRECONDITION(declaredAttributes[VertexAttribute::BONE_INDICES] ||
+                declaredAttributes[VertexAttribute::BONE_WEIGHTS])
+                << "[entity=" << entity.getId() << ", primitive @ " << primitiveIndex
+                << "] for advanced skinning set VertexBuffer::Builder::advancedSkinning()";
         for (size_t iVertex = 0; iVertex < vertexCount; iVertex++) {
             size_t const bonesPerVertex = bonePairsForPrimitive[iVertex].size();
             maxPairsCount += bonesPerVertex;
@@ -365,16 +367,20 @@ void RenderableManager::BuilderDetails::processBoneIndicesAndWights(Engine& engi
                 for (size_t k = 0; k < bonePairsForPrimitive[iVertex].size(); k++) {
                     auto boneWeight = bonePairsForPrimitive[iVertex][k][1];
                     auto boneIndex = bonePairsForPrimitive[iVertex][k][0];
-                    ASSERT_PRECONDITION(boneWeight >= 0,
-                            "[entity=%u, primitive @ %u] bone weight (%f) of vertex=%u is negative ",
-                            entity.getId(), primitiveIndex, boneWeight, iVertex);
+                    FILAMENT_CHECK_PRECONDITION(boneWeight >= 0)
+                            << "[entity=" << entity.getId() << ", primitive @ " << primitiveIndex
+                            << "] bone weight (" << boneWeight << ") of vertex=" << iVertex
+                            << " is negative";
                     if (boneWeight > 0.0f) {
-                        ASSERT_PRECONDITION(boneIndex >= 0,
-                            "[entity=%u, primitive @ %u] bone index (%i) of vertex=%u is negative ",
-                            entity.getId(), primitiveIndex, (int) boneIndex, iVertex);
-                        ASSERT_PRECONDITION(boneIndex < mSkinningBoneCount,
-                            "[entity=%u, primitive @ %u] bone index (%i) of vertex=%u is bigger then bone count (%u) ",
-                            entity.getId(), primitiveIndex, (int) boneIndex, iVertex, mSkinningBoneCount);
+                        FILAMENT_CHECK_PRECONDITION(boneIndex >= 0)
+                                << "[entity=" << entity.getId() << ", primitive @ "
+                                << primitiveIndex << "] bone index (" << (int)boneIndex
+                                << ") of vertex=" << iVertex << " is negative";
+                        FILAMENT_CHECK_PRECONDITION(boneIndex < mSkinningBoneCount)
+                                << "[entity=" << entity.getId() << ", primitive @ "
+                                << primitiveIndex << "] bone index (" << (int)boneIndex
+                                << ") of vertex=" << iVertex << " is bigger then bone count ("
+                                << mSkinningBoneCount << ")";
                         boneWeightsSum += boneWeight;
                         tempPairs[tempPairCount][0] = boneIndex;
                         tempPairs[tempPairCount][1] = boneWeight;
@@ -382,9 +388,10 @@ void RenderableManager::BuilderDetails::processBoneIndicesAndWights(Engine& engi
                     }
                 }
 
-                ASSERT_PRECONDITION(boneWeightsSum > 0,
-                    "[entity=%u, primitive @ %u] sum of bone weights of vertex=%u is %f, it should be positive.",
-                    entity.getId(), primitiveIndex, iVertex, boneWeightsSum);
+                FILAMENT_CHECK_PRECONDITION(boneWeightsSum > 0)
+                        << "[entity=" << entity.getId() << ", primitive @ " << primitiveIndex
+                        << "] sum of bone weights of vertex=" << iVertex << " is " << boneWeightsSum
+                        << ", it should be positive.";
 
                 // see https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#skinned-mesh-attributes
                 double const epsilon = 2e-7 * double(tempPairCount);
@@ -432,30 +439,29 @@ void RenderableManager::BuilderDetails::processBoneIndicesAndWights(Engine& engi
 RenderableManager::Builder::Result RenderableManager::Builder::build(Engine& engine, Entity entity) {
     bool isEmpty = true;
 
-    ASSERT_PRECONDITION(mImpl->mSkinningBoneCount <= CONFIG_MAX_BONE_COUNT,
-            "bone count > %u", CONFIG_MAX_BONE_COUNT);
+    FILAMENT_CHECK_PRECONDITION(mImpl->mSkinningBoneCount <= CONFIG_MAX_BONE_COUNT)
+            << "bone count > " << CONFIG_MAX_BONE_COUNT;
 
-    ASSERT_PRECONDITION(mImpl->mInstanceCount <= CONFIG_MAX_INSTANCES || !mImpl->mInstanceBuffer,
-            "instance count is %zu, but instance count is limited to CONFIG_MAX_INSTANCES (%zu) "
-            "instances when supplying transforms via an InstanceBuffer.",
-            mImpl->mInstanceCount,
-            CONFIG_MAX_INSTANCES);
+    FILAMENT_CHECK_PRECONDITION(
+            mImpl->mInstanceCount <= CONFIG_MAX_INSTANCES || !mImpl->mInstanceBuffer)
+            << "instance count is " << mImpl->mInstanceCount
+            << ", but instance count is limited to CONFIG_MAX_INSTANCES (" << CONFIG_MAX_INSTANCES
+            << ") instances when supplying transforms via an InstanceBuffer.";
 
     if (mImpl->mGeometryType == GeometryType::STATIC) {
-        ASSERT_PRECONDITION(mImpl->mSkinningBoneCount > 0,
-                "Skinning can't be used with STATIC geometry");
+        FILAMENT_CHECK_PRECONDITION(mImpl->mSkinningBoneCount > 0)
+                << "Skinning can't be used with STATIC geometry";
 
-        ASSERT_PRECONDITION(mImpl->mMorphTargetCount > 0,
-                "Morphing can't be used with STATIC geometry");
+        FILAMENT_CHECK_PRECONDITION(mImpl->mMorphTargetCount > 0)
+                << "Morphing can't be used with STATIC geometry";
     }
 
     if (mImpl->mInstanceBuffer) {
         size_t const bufferInstanceCount = mImpl->mInstanceBuffer->mInstanceCount;
-        ASSERT_PRECONDITION(mImpl->mInstanceCount <= bufferInstanceCount,
-                "instance count (%zu) must be less than or equal to the InstanceBuffer's instance "
-                "count "
-                "(%zu).",
-                mImpl->mInstanceCount, bufferInstanceCount);
+        FILAMENT_CHECK_PRECONDITION(mImpl->mInstanceCount <= bufferInstanceCount)
+                << "instance count (" << mImpl->mInstanceCount
+                << ") must be less than or equal to the InstanceBuffer's instance "
+                   "count (" << bufferInstanceCount << ").";
     }
 
     if (UTILS_LIKELY(mImpl->mSkinningBoneCount || mImpl->mSkinningBufferMode)) {
@@ -480,15 +486,15 @@ RenderableManager::Builder::Result RenderableManager::Builder::build(Engine& eng
         }
 
         // we want a feature level violation to be a hard error (exception if enabled, or crash)
-        ASSERT_PRECONDITION(downcast(engine).hasFeatureLevel(material->getFeatureLevel()),
-                "Material \"%s\" has feature level %u which is not supported by this Engine",
-                material->getName().c_str_safe(), (uint8_t)material->getFeatureLevel());
+        FILAMENT_CHECK_PRECONDITION(downcast(engine).hasFeatureLevel(material->getFeatureLevel()))
+                << "Material \"" << material->getName().c_str_safe() << "\" has feature level "
+                << (uint8_t)material->getFeatureLevel() << " which is not supported by this Engine";
 
         // reject invalid geometry parameters
-        ASSERT_PRECONDITION(entry.offset + entry.count <= entry.indices->getIndexCount(),
-                "[entity=%u, primitive @ %u] offset (%u) + count (%u) > indexCount (%u)",
-                entity.getId(), i,
-                entry.offset, entry.count, entry.indices->getIndexCount());
+        FILAMENT_CHECK_PRECONDITION(entry.offset + entry.count <= entry.indices->getIndexCount())
+                << "[entity=" << entity.getId() << ", primitive @ " << i << "] offset ("
+                << entry.offset << ") + count (" << entry.count << ") > indexCount ("
+                << entry.indices->getIndexCount() << ")";
 
         // this can't be an error because (1) those values are not immutable, so the caller
         // could fix later, and (2) the material's shader will work (i.e. compile), and
@@ -505,12 +511,11 @@ RenderableManager::Builder::Result RenderableManager::Builder::build(Engine& eng
         isEmpty = false;
     }
 
-    ASSERT_PRECONDITION(
-            !mImpl->mAABB.isEmpty() ||
-            (!mImpl->mCulling && (!(mImpl->mReceiveShadows || mImpl->mCastShadows)) ||
-             isEmpty),
-            "[entity=%u] AABB can't be empty, unless culling is disabled and "
-                    "the object is not a shadow caster/receiver", entity.getId());
+    FILAMENT_CHECK_PRECONDITION(!mImpl->mAABB.isEmpty() ||
+            (!mImpl->mCulling && (!(mImpl->mReceiveShadows || mImpl->mCastShadows)) || isEmpty))
+            << "[entity=" << entity.getId()
+            << "] AABB can't be empty, unless culling is disabled and "
+               "the object is not a shadow caster/receiver";
 
     downcast(engine).createRenderable(*this, entity);
     return Success;
@@ -804,9 +809,10 @@ void FRenderableManager::setMaterialInstanceAt(Instance instance, uint8_t level,
             FMaterial const* material = mi->getMaterial();
 
             // we want a feature level violation to be a hard error (exception if enabled, or crash)
-            ASSERT_PRECONDITION(mEngine.hasFeatureLevel(material->getFeatureLevel()),
-                    "Material \"%s\" has feature level %u which is not supported by this Engine",
-                    material->getName().c_str_safe(), (uint8_t)material->getFeatureLevel());
+            FILAMENT_CHECK_PRECONDITION(mEngine.hasFeatureLevel(material->getFeatureLevel()))
+                    << "Material \"" << material->getName().c_str_safe() << "\" has feature level "
+                    << (uint8_t)material->getFeatureLevel()
+                    << " which is not supported by this Engine";
 
             primitives[primitiveIndex].setMaterialInstance(mi);
             AttributeBitset const required = material->getRequiredAttributes();
@@ -881,8 +887,8 @@ void FRenderableManager::setBones(Instance ci,
     if (ci) {
         Bones const& bones = mManager[ci].bones;
 
-        ASSERT_PRECONDITION(!bones.skinningBufferMode,
-                "Disable skinning buffer mode to use this API");
+        FILAMENT_CHECK_PRECONDITION(!bones.skinningBufferMode)
+                << "Disable skinning buffer mode to use this API";
 
         assert_invariant(bones.handle && offset + boneCount <= bones.count);
         if (bones.handle) {
@@ -897,8 +903,8 @@ void FRenderableManager::setBones(Instance ci,
     if (ci) {
         Bones const& bones = mManager[ci].bones;
 
-        ASSERT_PRECONDITION(!bones.skinningBufferMode,
-                "Disable skinning buffer mode to use this API");
+        FILAMENT_CHECK_PRECONDITION(!bones.skinningBufferMode)
+                << "Disable skinning buffer mode to use this API";
 
         assert_invariant(bones.handle && offset + boneCount <= bones.count);
         if (bones.handle) {
@@ -913,12 +919,11 @@ void FRenderableManager::setSkinningBuffer(FRenderableManager::Instance ci,
 
     Bones& bones = mManager[ci].bones;
 
-    ASSERT_PRECONDITION(bones.skinningBufferMode,
-            "Enable skinning buffer mode to use this API");
+    FILAMENT_CHECK_PRECONDITION(bones.skinningBufferMode)
+            << "Enable skinning buffer mode to use this API";
 
-    ASSERT_PRECONDITION(
-            count <= CONFIG_MAX_BONE_COUNT,
-            "SkinningBuffer larger than 256 (count=%u)", count);
+    FILAMENT_CHECK_PRECONDITION(count <= CONFIG_MAX_BONE_COUNT)
+            << "SkinningBuffer larger than 256 (count=" << count << ")";
 
     // According to the OpenGL ES 3.2 specification in 7.6.3 Uniform
     // Buffer Object Bindings:
@@ -930,10 +935,9 @@ void FRenderableManager::setSkinningBuffer(FRenderableManager::Instance ci,
 
     count = CONFIG_MAX_BONE_COUNT;
 
-    ASSERT_PRECONDITION(
-            count + offset <= skinningBuffer->getBoneCount(),
-            "SkinningBuffer overflow (size=%u, count=%u, offset=%u)",
-            skinningBuffer->getBoneCount(), count, offset);
+    FILAMENT_CHECK_PRECONDITION(count + offset <= skinningBuffer->getBoneCount())
+            << "SkinningBuffer overflow (size=" << skinningBuffer->getBoneCount()
+            << ", count=" << count << ", offset=" << offset << ")";
 
     bones.handle = skinningBuffer->getHwHandle();
     bones.count = uint16_t(count);
@@ -953,9 +957,9 @@ static void updateMorphWeights(FEngine& engine, backend::Handle<backend::HwBuffe
 void FRenderableManager::setMorphWeights(Instance instance, float const* weights,
         size_t count, size_t offset) {
     if (instance) {
-        ASSERT_PRECONDITION(count + offset <= CONFIG_MAX_MORPH_TARGET_COUNT,
-                "Only %d morph targets are supported (count=%d, offset=%d)",
-                CONFIG_MAX_MORPH_TARGET_COUNT, count, offset);
+        FILAMENT_CHECK_PRECONDITION(count + offset <= CONFIG_MAX_MORPH_TARGET_COUNT)
+                << "Only " << CONFIG_MAX_MORPH_TARGET_COUNT
+                << " morph targets are supported (count=" << count << ", offset=" << offset << ")";
 
         MorphWeights const& morphWeights = mManager[instance].morphWeights;
         if (morphWeights.handle) {
@@ -970,9 +974,9 @@ void FRenderableManager::setMorphTargetBufferAt(Instance instance, uint8_t level
         assert_invariant(morphTargetBuffer);
 
         MorphWeights const& morphWeights = mManager[instance].morphWeights;
-        ASSERT_PRECONDITION(morphWeights.count == count,
-                "Only %d morph targets can be set (count=%d)",
-                morphWeights.count, count);
+        FILAMENT_CHECK_PRECONDITION(morphWeights.count == count)
+                << "Only " << morphWeights.count << " morph targets can be set (count=" << count
+                << ")";
 
         Slice<MorphTargets>& morphTargets = getMorphTargets(instance, level);
         if (primitiveIndex < morphTargets.size()) {

filament/src/components/RenderableManager.h

@@ -310,10 +310,10 @@ FILAMENT_DOWNCAST(RenderableManager)
 
 void FRenderableManager::setAxisAlignedBoundingBox(Instance instance, const Box& aabb) {
     if (instance) {
-        ASSERT_PRECONDITION(
-                static_cast<Visibility const&>(
-                        mManager[instance].visibility).geometryType == GeometryType::DYNAMIC,
-                "This renderable has staticBounds enabled; its AABB cannot change.");
+        FILAMENT_CHECK_PRECONDITION(
+                static_cast<Visibility const&>(mManager[instance].visibility).geometryType ==
+                GeometryType::DYNAMIC)
+                << "This renderable has staticBounds enabled; its AABB cannot change.";
         mManager[instance].aabb = aabb;
     }
 }
@@ -389,9 +389,8 @@ void FRenderableManager::setSkinning(Instance instance, bool enable) {
     if (instance) {
         Visibility& visibility = mManager[instance].visibility;
 
-        ASSERT_PRECONDITION(
-                visibility.geometryType != GeometryType::STATIC || !enable,
-                "Skinning can't be used with STATIC geometry");
+        FILAMENT_CHECK_PRECONDITION(visibility.geometryType != GeometryType::STATIC || !enable)
+                << "Skinning can't be used with STATIC geometry";
 
         visibility.skinning = enable;
     }
@@ -401,9 +400,8 @@ void FRenderableManager::setMorphing(Instance instance, bool enable) {
     if (instance) {
         Visibility& visibility = mManager[instance].visibility;
 
-        ASSERT_PRECONDITION(
-                visibility.geometryType != GeometryType::STATIC || !enable,
-                "Morphing can't be used with STATIC geometry");
+        FILAMENT_CHECK_PRECONDITION(visibility.geometryType != GeometryType::STATIC || !enable)
+                << "Morphing can't be used with STATIC geometry";
 
         visibility.morphing = enable;
     }

filament/src/details/Camera.cpp

@@ -97,9 +97,10 @@ void UTILS_NOINLINE FCamera::setCustomProjection(mat4 const& p,
 void UTILS_NOINLINE FCamera::setCustomEyeProjection(math::mat4 const* projection, size_t count,
         math::mat4 const& projectionForCulling, double near, double far) {
     const Engine::Config& config = mEngine.getConfig();
-    ASSERT_PRECONDITION(count >= config.stereoscopicEyeCount,
-            "All eye projections must be supplied together, count must be >= "
-            "config.stereoscopicEyeCount (%d)", config.stereoscopicEyeCount);
+    FILAMENT_CHECK_PRECONDITION(count >= config.stereoscopicEyeCount)
+            << "All eye projections must be supplied together, count must be >= "
+               "config.stereoscopicEyeCount ("
+            << config.stereoscopicEyeCount << ")";
     for (int i = 0; i < config.stereoscopicEyeCount; i++) {
         mEyeProjection[i] = projection[i];
     }
@@ -113,14 +114,13 @@ void UTILS_NOINLINE FCamera::setProjection(Camera::Projection projection,
         double bottom, double top,
         double near, double far) {
 
-    ASSERT_PRECONDITION(!(
-            left == right ||
-            bottom == top ||
+    FILAMENT_CHECK_PRECONDITION(!(left == right || bottom == top ||
             (projection == Projection::PERSPECTIVE && (near <= 0 || far <= near)) ||
-            (projection == Projection::ORTHO && (near == far))),
-            "Camera preconditions not met in setProjection(%s, %f, %f, %f, %f, %f, %f)",
-            projection == Camera::Projection::PERSPECTIVE ? "PERSPECTIVE" : "ORTHO",
-            left, right, bottom, top, near, far);
+            (projection == Projection::ORTHO && (near == far))))
+            << "Camera preconditions not met in setProjection("
+            << (projection == Camera::Projection::PERSPECTIVE ? "PERSPECTIVE" : "ORTHO") << ", "
+            << left << ", " << right << ", " << bottom << ", " << top << ", " << near << ", " << far
+            << ")";
 
     mat4 c, p;
     switch (projection) {
@@ -193,8 +193,9 @@ math::mat4 FCamera::getCullingProjectionMatrix() const noexcept {
 
 const math::mat4& FCamera::getUserProjectionMatrix(uint8_t eyeId) const {
     const Engine::Config& config = mEngine.getConfig();
-    ASSERT_PRECONDITION(eyeId < config.stereoscopicEyeCount,
-            "eyeId must be < config.stereoscopicEyeCount (%d)", config.stereoscopicEyeCount);
+    FILAMENT_CHECK_PRECONDITION(eyeId < config.stereoscopicEyeCount)
+            << "eyeId must be < config.stereoscopicEyeCount (" << config.stereoscopicEyeCount
+            << ")";
     return mEyeProjection[eyeId];
 }
 
@@ -210,8 +211,9 @@ void UTILS_NOINLINE FCamera::setModelMatrix(const mat4& modelMatrix) noexcept {
 
 void UTILS_NOINLINE FCamera::setEyeModelMatrix(uint8_t eyeId, math::mat4 const& model) {
     const Engine::Config& config = mEngine.getConfig();
-    ASSERT_PRECONDITION(eyeId < config.stereoscopicEyeCount,
-            "eyeId must be < config.stereoscopicEyeCount (%d)", config.stereoscopicEyeCount);
+    FILAMENT_CHECK_PRECONDITION(eyeId < config.stereoscopicEyeCount)
+            << "eyeId must be < config.stereoscopicEyeCount (" << config.stereoscopicEyeCount
+            << ")";
     mEyeFromView[eyeId] = inverse(model);
 }
 

filament/src/details/Engine.cpp

@@ -52,6 +52,7 @@
 
 #include <algorithm>
 #include <memory>
+#include <thread>
 
 #include "generated/resources/materials.h"
 
@@ -101,6 +102,7 @@ Engine* FEngine::create(Engine::Builder const& builder) {
         DriverConfig const driverConfig{
                 .handleArenaSize = instance->getRequestedDriverHandleArenaSize(),
                 .textureUseAfterFreePoolSize = instance->getConfig().textureUseAfterFreePoolSize,
+                .metalUploadBufferSizeBytes = instance->getConfig().metalUploadBufferSizeBytes,
                 .disableParallelShaderCompile = instance->getConfig().disableParallelShaderCompile,
                 .disableHandleUseAfterFreeCheck = instance->getConfig().disableHandleUseAfterFreeCheck,
                 .forceGLES2Context = instance->getConfig().forceGLES2Context,
@@ -158,8 +160,8 @@ FEngine* FEngine::getEngine(void* token) {
 
     FEngine* instance = static_cast<FEngine*>(token);
 
-    ASSERT_PRECONDITION(ThreadUtils::isThisThread(instance->mMainThreadId),
-            "Engine::createAsync() and Engine::getEngine() must be called on the same thread.");
+    FILAMENT_CHECK_PRECONDITION(ThreadUtils::isThisThread(instance->mMainThreadId))
+            << "Engine::createAsync() and Engine::getEngine() must be called on the same thread.";
 
     // we use mResourceAllocator as a proxy for "am I already initialized"
     if (!instance->mResourceAllocator) {
@@ -440,8 +442,8 @@ void FEngine::shutdown() {
     // by construction this should never be nullptr
     assert_invariant(mResourceAllocator);
 
-    ASSERT_PRECONDITION(ThreadUtils::isThisThread(mMainThreadId),
-            "Engine::shutdown() called from the wrong thread!");
+    FILAMENT_CHECK_PRECONDITION(ThreadUtils::isThisThread(mMainThreadId))
+            << "Engine::shutdown() called from the wrong thread!";
 
 #ifndef NDEBUG
     // print out some statistics about this run
@@ -475,6 +477,8 @@ void FEngine::shutdown() {
 
     destroy(mDefaultMaterial);
 
+    destroy(mUnprotectedDummySwapchain);
+
     /*
      * clean-up after the user -- we call terminate on each "leaked" object and clear each list.
      *
@@ -584,14 +588,14 @@ void FEngine::flush() {
 }
 
 void FEngine::flushAndWait() {
-    ASSERT_PRECONDITION(!mCommandBufferQueue.isPaused(),
-            "Cannot call flushAndWait() when rendering thread is paused!");
+    FILAMENT_CHECK_PRECONDITION(!mCommandBufferQueue.isPaused())
+            << "Cannot call flushAndWait() when rendering thread is paused!";
 
 #if defined(__ANDROID__)
 
     // first make sure we've not terminated filament
-    ASSERT_PRECONDITION(!mCommandBufferQueue.isExitRequested(),
-            "calling Engine::flushAndWait() after Engine::shutdown()!");
+    FILAMENT_CHECK_PRECONDITION(!mCommandBufferQueue.isExitRequested())
+            << "calling Engine::flushAndWait() after Engine::shutdown()!";
 
 #endif
 
@@ -609,10 +613,10 @@ void FEngine::flushAndWait() {
         // if the fence didn't trigger after 250ms, check that the command queue thread is still
         // running (otherwise indicating a precondition violation).
         if (UTILS_UNLIKELY(status == FenceStatus::TIMEOUT_EXPIRED)) {
-            ASSERT_PRECONDITION(!mCommandBufferQueue.isExitRequested(),
-                    "called Engine::shutdown() WHILE in Engine::flushAndWait()!");
+            FILAMENT_CHECK_PRECONDITION(!mCommandBufferQueue.isExitRequested())
+                    << "called Engine::shutdown() WHILE in Engine::flushAndWait()!";
             tryCount--;
-            ASSERT_POSTCONDITION(tryCount, "flushAndWait() failed inexplicably after 2s");
+            FILAMENT_CHECK_POSTCONDITION(tryCount) << "flushAndWait() failed inexplicably after 2s";
             // if the thread is still running, maybe we just need to give it more time
             continue;
         }
@@ -675,6 +679,7 @@ int FEngine::loop() {
     DriverConfig const driverConfig {
             .handleArenaSize = getRequestedDriverHandleArenaSize(),
             .textureUseAfterFreePoolSize = mConfig.textureUseAfterFreePoolSize,
+            .metalUploadBufferSizeBytes = mConfig.metalUploadBufferSizeBytes,
             .disableParallelShaderCompile = mConfig.disableParallelShaderCompile,
             .disableHandleUseAfterFreeCheck = mConfig.disableHandleUseAfterFreeCheck,
             .forceGLES2Context = mConfig.forceGLES2Context,
@@ -1239,10 +1244,10 @@ Engine::FeatureLevel FEngine::getSupportedFeatureLevel() const noexcept {
 }
 
 Engine::FeatureLevel FEngine::setActiveFeatureLevel(FeatureLevel featureLevel) {
-    ASSERT_PRECONDITION(featureLevel <= getSupportedFeatureLevel(),
-            "Feature level %u not supported", (unsigned)featureLevel);
-    ASSERT_PRECONDITION(mActiveFeatureLevel >= FeatureLevel::FEATURE_LEVEL_1,
-            "Cannot adjust feature level beyond 0 at runtime");
+    FILAMENT_CHECK_PRECONDITION(featureLevel <= getSupportedFeatureLevel())
+            << "Feature level " << (unsigned)featureLevel << " not supported";
+    FILAMENT_CHECK_PRECONDITION(mActiveFeatureLevel >= FeatureLevel::FEATURE_LEVEL_1)
+            << "Cannot adjust feature level beyond 0 at runtime";
     return (mActiveFeatureLevel = std::max(mActiveFeatureLevel, featureLevel));
 }
 
@@ -1252,6 +1257,13 @@ void FEngine::resetBackendState() noexcept {
 }
 #endif
 
+void FEngine::unprotected() noexcept {
+    if (UTILS_UNLIKELY(!mUnprotectedDummySwapchain)) {
+        mUnprotectedDummySwapchain = createSwapChain(1, 1, 0);
+    }
+    mUnprotectedDummySwapchain->makeCurrent(getDriverApi());
+}
+
 // ------------------------------------------------------------------------------------------------
 
 Engine::Builder::Builder() noexcept = default;

filament/src/details/Engine.h

@@ -406,6 +406,8 @@ public:
         getDriver().purge();
     }
 
+    void unprotected() noexcept;
+
     void setAutomaticInstancingEnabled(bool enable) noexcept {
         // instancing is not allowed at feature level 0
         if (hasFeatureLevel(FeatureLevel::FEATURE_LEVEL_1)) {
@@ -539,6 +541,7 @@ private:
 
     mutable FMaterial const* mDefaultMaterial = nullptr;
     mutable FMaterial const* mSkyboxMaterial = nullptr;
+    mutable FSwapChain* mUnprotectedDummySwapchain = nullptr;
 
     mutable FTexture* mDefaultIblTexture = nullptr;
     mutable FIndirectLight* mDefaultIbl = nullptr;
@@ -595,6 +598,7 @@ public:
             // capture to file. At the moment, only supported by the Metal backend.
             bool doFrameCapture = false;
             bool disable_buffer_padding = false;
+            bool disable_subpasses = false;
         } renderer;
         struct {
             bool debug_froxel_visualization = false;