Test commit

This reverts commit 30387af61c.

Causes breakage on Pixel 8pro for 1P apps.

.github/actions/android-continuous/action.yml

@@ -0,0 +1,17 @@
+name: 'Android Continuous'
+inputs:
+  build-abi:
+    description: 'The target platform ABI'
+    required: true
+    default: 'armeabi-v7a'
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-java@v3
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+    - name: Run build script
+      run: |
+        cd build/android && printf "y" | ./build.sh continuous ${{ inputs.build-abi }}
+      shell: bash

.github/workflows/android-continuous.yml

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

.github/workflows/presubmit.yml

@@ -49,8 +49,10 @@ jobs:
           distribution: 'temurin'
           java-version: '17'
       - name: Run build script
+        # Only build 1 64 bit target during presubmit to cut down build times during presubmit
+        # Continuous builds will build everything
         run: |
-          cd build/android && printf "y" | ./build.sh presubmit
+          cd build/android && printf "y" | ./build.sh presubmit arm64-v8a
 
   build-ios:
     name: build-iOS

.github/workflows/release.yml

@@ -120,7 +120,7 @@ jobs:
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
-          cd build/android && printf "y" | ./build.sh release
+          cd build/android && printf "y" | ./build.sh release armeabi-v7a,arm64-v8a,x86,x86_64
           cd ../..
           mv out/filament-android-release.aar out/filament-${TAG}-android.aar
           mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.54.0'
+    implementation 'com.google.android.filament:filament-android:1.54.3'
 }
 ```
 
@@ -51,19 +51,9 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.54.0'
+pod 'Filament', '~> 1.54.3'
 ```
 
-### Snapshots
-
-If you prefer to live on the edge, you can download a continuous build by following the following
-steps:
-
-1. Find the [commit](https://github.com/google/filament/commits/main) you're interested in.
-2. Click the green check mark under the commit message.
-3. Click on the _Details_ link for the platform you're interested in.
-4. On the top left click _Summary_, then in the _Artifacts_ section choose the desired artifact.
-
 ## Documentation
 
 - [Filament](https://google.github.io/filament/Filament.html), an in-depth explanation of

RELEASE_NOTES.md

@@ -7,6 +7,16 @@ 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.54.3
+
+
+## v1.54.2
+
+- Add a `name` API to Filament objects for debugging handle use-after-free assertions
+
+## v1.54.1
+
+
 ## v1.54.0
 
 - materials: add a new `stereoscopicType` material parameter. [⚠️ **New Material Version**]

android/gradle.properties

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

build/android/build.sh

@@ -60,13 +60,7 @@ if [[ ! -d "${ANDROID_HOME}/ndk/$FILAMENT_NDK_VERSION" ]]; then
     yes | ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager --licenses
     ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION"
 fi
-
-# Only build 1 64 bit target during presubmit to cut down build times during presubmit
-# Continuous builds will build everything
 ANDROID_ABIS=
-if [[ "$TARGET" == "presubmit" ]]; then
-  ANDROID_ABIS="-q arm64-v8a"
-fi
 
 # Build the Android sample-gltf-viewer APK during release.
 BUILD_SAMPLES=
@@ -74,5 +68,19 @@ if [[ "$TARGET" == "release" ]]; then
     BUILD_SAMPLES="-k sample-gltf-viewer"
 fi
 
+function build_android() {
+    local ABI=$1
+
+    # Do the following in two steps so that we do not run out of space
+    if [[ -n "${BUILD_DEBUG}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_DEBUG}
+        rm -rf out/cmake-android-debug-*
+    fi
+    if [[ -n "${BUILD_RELEASE}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_RELEASE}
+        rm -rf out/cmake-android-release-*
+    fi
+}
+
 pushd `dirname $0`/../.. > /dev/null
-FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android $ANDROID_ABIS -c $BUILD_SAMPLES $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+build_android $2

docs/Materials.md.html

@@ -1308,7 +1308,12 @@ Description
       declare a variable called `eyeDirection` you can access it in the fragment shader using
       `variable_eyeDirection`. In the vertex shader, the interpolant name is simply a member of
       the `MaterialVertexInputs` structure (`material.eyeDirection` in your example). Each
-      interpolant is of type `float4` (`vec4`) in the shaders.
+      interpolant is of type `float4` (`vec4`) in the shaders. By default the precision of the
+      interpolant is `highp` in *both* the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if `default` is specified the default precision is used is the fragment shader
+      (`mediump`) and in the vertex shader (`highp`).
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
@@ -1320,7 +1325,11 @@ material {
         }
     ],
     variables : [
-         eyeDirection
+         eyeDirection,
+         {
+            name : eyeColor,
+            precision : medium
+         }
     ],
     vertexDomain : device,
     depthWrite : false,

filament/CMakeLists.txt

@@ -61,6 +61,7 @@ set(SRCS
         src/Engine.cpp
         src/Exposure.cpp
         src/Fence.cpp
+        src/FilamentBuilder.cpp
         src/FrameInfo.cpp
         src/FrameSkipper.cpp
         src/Froxelizer.cpp

filament/backend/include/backend/DriverEnums.h

@@ -1058,7 +1058,7 @@ struct RasterState {
             bool inverseFrontFaces                      : 1;        // 31
 
             //! padding, must be 0
-            uint8_t padding                             : 1;        // 32
+            bool depthClamp                             : 1;        // 32
         };
         uint32_t u = 0;
     };

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

@@ -162,6 +162,10 @@ DECL_DRIVER_API_0(finish)
 // reset state tracking, if the driver does any state tracking (e.g. GL)
 DECL_DRIVER_API_0(resetState)
 
+DECL_DRIVER_API_N(setDebugTag,
+        backend::HandleBase::HandleId, handleId,
+        utils::CString, tag)
+
 /*
  * Creating driver objects
  * -----------------------
@@ -305,6 +309,7 @@ DECL_DRIVER_API_SYNCHRONOUS_0(bool, isParallelShaderCompileSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isDepthStencilResolveSupported)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isDepthStencilBlitSupported, backend::TextureFormat, format)
 DECL_DRIVER_API_SYNCHRONOUS_0(bool, isProtectedTexturesSupported)
+DECL_DRIVER_API_SYNCHRONOUS_0(bool, isDepthClampSupported)
 DECL_DRIVER_API_SYNCHRONOUS_0(uint8_t, getMaxDrawBuffers)
 DECL_DRIVER_API_SYNCHRONOUS_0(size_t, getMaxUniformBufferSize)
 DECL_DRIVER_API_SYNCHRONOUS_0(math::float2, getClipSpaceParams)
@@ -439,12 +444,10 @@ DECL_DRIVER_API_N(setPushConstant,
         backend::PushConstantVariant, value)
 
 DECL_DRIVER_API_N(insertEventMarker,
-        const char*, string,
-        uint32_t, len = 0)
+        const char*, string)
 
 DECL_DRIVER_API_N(pushGroupMarker,
-        const char*, string,
-        uint32_t, len = 0)
+        const char*, string)
 
 DECL_DRIVER_API_0(popGroupMarker)
 

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

@@ -20,11 +20,12 @@
 #include <backend/Handle.h>
 
 #include <utils/Allocator.h>
+#include <utils/CString.h>
 #include <utils/Log.h>
+#include <utils/Panic.h>
 #include <utils/compiler.h>
 #include <utils/debug.h>
 #include <utils/ostream.h>
-#include <utils/Panic.h>
 
 #include <tsl/robin_map.h>
 
@@ -173,8 +174,10 @@ 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;
-                FILAMENT_CHECK_POSTCONDITION(expectedAge == age) <<
-                        "use-after-free of Handle with id=" << handle.getId();
+                // getHandleTag() is only called if the check fails.
+                FILAMENT_CHECK_POSTCONDITION(expectedAge == age)
+                        << "use-after-free of Handle with id=" << handle.getId()
+                        << ", tag=" << getHandleTag(handle.getId()).c_str_safe();
             }
         }
 
@@ -201,6 +204,29 @@ public:
         return handle_cast<Dp>(const_cast<Handle<B>&>(handle));
     }
 
+    void associateTagToHandle(HandleBase::HandleId id, utils::CString&& tag) noexcept {
+        // TODO: for now, only pool handles check for use-after-free, so we only keep tags for
+        // those
+        if (isPoolHandle(id)) {
+            // Truncate the age to get the debug tag
+            uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+            // This line is the costly part. In the future, we could potentially use a custom
+            // allocator.
+            mDebugTags[key] = std::move(tag);
+        }
+    }
+
+    utils::CString getHandleTag(HandleBase::HandleId id) const noexcept {
+        if (!isPoolHandle(id)) {
+            return "(no tag)";
+        }
+        uint32_t const key = id & ~(HANDLE_DEBUG_TAG_MASK ^ HANDLE_AGE_MASK);
+        if (auto pos = mDebugTags.find(key); pos != mDebugTags.end()) {
+            return pos->second;
+        }
+        return "(no tag)";
+    }
+
 private:
 
     template<typename D>
@@ -318,12 +344,24 @@ private:
         }
     }
 
-    // we handle a 4 bits age per address
-    static constexpr uint32_t HANDLE_HEAP_FLAG      = 0x80000000u;      // pool vs heap handle
-    static constexpr uint32_t HANDLE_AGE_MASK       = 0x78000000u;      // handle's age
-    static constexpr uint32_t HANDLE_INDEX_MASK     = 0x07FFFFFFu;      // handle index
-    static constexpr uint32_t HANDLE_TAG_MASK       = HANDLE_AGE_MASK;
-    static constexpr uint32_t HANDLE_AGE_SHIFT      = 27;
+    // number if bits allotted to the handle's age (currently 4 max)
+    static constexpr uint32_t HANDLE_AGE_BIT_COUNT = 4;
+    // number if bits allotted to the handle's debug tag (HANDLE_AGE_BIT_COUNT max)
+    static constexpr uint32_t HANDLE_DEBUG_TAG_BIT_COUNT = 2;
+    // bit shift for both the age and debug tag
+    static constexpr uint32_t HANDLE_AGE_SHIFT = 27;
+    // mask for the heap (vs pool) flag
+    static constexpr uint32_t HANDLE_HEAP_FLAG = 0x80000000u;
+    // mask for the age
+    static constexpr uint32_t HANDLE_AGE_MASK =
+            ((1 << HANDLE_AGE_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the debug tag
+    static constexpr uint32_t HANDLE_DEBUG_TAG_MASK =
+            ((1 << HANDLE_DEBUG_TAG_BIT_COUNT) - 1) << HANDLE_AGE_SHIFT;
+    // mask for the index
+    static constexpr uint32_t HANDLE_INDEX_MASK = 0x07FFFFFFu;
+
+    static_assert(HANDLE_DEBUG_TAG_BIT_COUNT <= HANDLE_AGE_BIT_COUNT);
 
     static bool isPoolHandle(HandleBase::HandleId id) noexcept {
         return (id & HANDLE_HEAP_FLAG) == 0u;
@@ -338,7 +376,7 @@ private:
         // a non-pool handle.
         if (UTILS_LIKELY(isPoolHandle(id))) {
             char* const base = (char*)mHandleArena.getArea().begin();
-            uint32_t const tag = id & HANDLE_TAG_MASK;
+            uint32_t const tag = id & HANDLE_AGE_MASK;
             size_t const offset = (id & HANDLE_INDEX_MASK) * Allocator::getAlignment();
             return { static_cast<void*>(base + offset), tag };
         }
@@ -353,7 +391,7 @@ private:
         size_t const offset = (char*)p - base;
         assert_invariant((offset % Allocator::getAlignment()) == 0);
         auto id = HandleBase::HandleId(offset / Allocator::getAlignment());
-        id |= tag & HANDLE_TAG_MASK;
+        id |= tag & HANDLE_AGE_MASK;
         assert_invariant((id & HANDLE_HEAP_FLAG) == 0);
         return id;
     }
@@ -363,6 +401,7 @@ private:
     // Below is only used when running out of space in the HandleArena
     mutable utils::Mutex mLock;
     tsl::robin_map<HandleBase::HandleId, void*> mOverflowMap;
+    tsl::robin_map<HandleBase::HandleId, utils::CString> mDebugTags;
     HandleBase::HandleId mId = 0;
     bool mUseAfterFreeCheckDisabled = false;
 };

filament/backend/src/CircularBuffer.cpp

@@ -24,7 +24,7 @@
 #include <utils/debug.h>
 #include <utils/ostream.h>
 
-#if !defined(WIN32) && !defined(__EMSCRIPTEN__) && !defined(IOS)
+#if !defined(WIN32) && !defined(__EMSCRIPTEN__)
 #    include <sys/mman.h>
 #    include <unistd.h>
 #    define HAS_MMAP 1

filament/backend/src/HandleAllocator.cpp

@@ -80,6 +80,9 @@ HandleAllocator<P0, P1, P2>::HandleAllocator(const char* name, size_t size,
         bool disableUseAfterFreeCheck) noexcept
     : mHandleArena(name, size, disableUseAfterFreeCheck),
       mUseAfterFreeCheckDisabled(disableUseAfterFreeCheck) {
+    // Reserve initial space for debug tags. This prevents excessive calls to malloc when the first
+    // few tags are set.
+    mDebugTags.reserve(512);
 }
 
 template <size_t P0, size_t P1, size_t P2>

filament/backend/src/metal/MetalBuffer.h

@@ -160,6 +160,8 @@ public:
          size_t size, bool forceGpuBuffer = false);
     ~MetalBuffer();
 
+    [[nodiscard]] bool wasAllocationSuccessful() const noexcept { return mBuffer || mCpuBuffer; }
+
     MetalBuffer(const MetalBuffer& rhs) = delete;
     MetalBuffer& operator=(const MetalBuffer& rhs) = delete;
 

filament/backend/src/metal/MetalBuffer.mm

@@ -53,8 +53,8 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferObjectBinding bindingType,
         mBuffer = { [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate],
             TrackedMetalBuffer::Type::GENERIC };
     }
-    FILAMENT_CHECK_POSTCONDITION(mBuffer)
-            << "Could not allocate Metal buffer of size " << size << ".";
+    // mBuffer might fail to be allocated. Clients can check for this by calling
+    // wasAllocationSuccessful().
 }
 
 MetalBuffer::~MetalBuffer() {

filament/backend/src/metal/MetalContext.h

@@ -112,6 +112,7 @@ struct MetalContext {
     std::array<BufferState, MAX_SSBO_COUNT> ssboState;
     CullModeStateTracker cullModeState;
     WindingStateTracker windingState;
+    DepthClampStateTracker depthClampState;
     Handle<HwRenderPrimitive> currentRenderPrimitive;
 
     // State caches.

filament/backend/src/metal/MetalDriver.h

@@ -57,7 +57,6 @@ class MetalDriver final : public DriverBase {
 
 public:
     static Driver* create(MetalPlatform* platform, const Platform::DriverConfig& driverConfig);
-    void runAtNextTick(const std::function<void()>& fn) noexcept;
 
 private:
 
@@ -73,10 +72,12 @@ private:
 
     /*
      * Tasks run regularly on the driver thread.
+     * Not thread-safe; tasks are run from the driver thead and must be enqueued from the driver
+     * thread.
      */
+    void runAtNextTick(const std::function<void()>& fn) noexcept;
     void executeTickOps() noexcept;
     std::vector<std::function<void()>> mTickOps;
-    std::mutex mTickOpsLock;
 
     /*
      * Driver interface

filament/backend/src/metal/MetalDriver.mm

@@ -320,17 +320,40 @@ void MetalDriver::createVertexBufferR(Handle<HwVertexBuffer> vbh,
         uint32_t vertexCount, Handle<HwVertexBufferInfo> vbih) {
     MetalVertexBufferInfo const* const vbi = handle_cast<const MetalVertexBufferInfo>(vbih);
     construct_handle<MetalVertexBuffer>(vbh, *mContext, vertexCount, vbi->bufferCount, vbih);
+    // No actual GPU memory is allocated here, so no need to check for allocation success.
 }
 
 void MetalDriver::createIndexBufferR(Handle<HwIndexBuffer> ibh, ElementType elementType,
         uint32_t indexCount, BufferUsage usage) {
-    auto elementSize = (uint8_t) getElementTypeSize(elementType);
-    construct_handle<MetalIndexBuffer>(ibh, *mContext, usage, elementSize, indexCount);
+    auto elementSize = (uint8_t)getElementTypeSize(elementType);
+    auto* indexBuffer =
+            construct_handle<MetalIndexBuffer>(ibh, *mContext, usage, elementSize, indexCount);
+    auto& buffer = indexBuffer->buffer;
+    // If the allocation was not successful, postpone the error message until the next tick, to give
+    // Filament a chance to call setDebugTag on the handle; this way we get a nicer error message.
+    if (UTILS_UNLIKELY(!buffer.wasAllocationSuccessful())) {
+        const size_t byteCount = buffer.getSize();
+        runAtNextTick([byteCount, this, ibh]() {
+            FILAMENT_CHECK_POSTCONDITION(false)
+                    << "Could not allocate Metal index buffer of size " << byteCount
+                    << ", tag=" << mHandleAllocator.getHandleTag(ibh.getId()).c_str_safe();
+        });
+    }
 }
 
 void MetalDriver::createBufferObjectR(Handle<HwBufferObject> boh, uint32_t byteCount,
         BufferObjectBinding bindingType, BufferUsage usage) {
-    construct_handle<MetalBufferObject>(boh, *mContext, bindingType, usage, byteCount);
+    auto* bufferObject =
+            construct_handle<MetalBufferObject>(boh, *mContext, bindingType, usage, byteCount);
+    // If the allocation was not successful, postpone the error message until the next tick, to give
+    // Filament a chance to call setDebugTag on the handle; this way we get a nicer error message.
+    if (UTILS_UNLIKELY(!bufferObject->getBuffer()->wasAllocationSuccessful())) {
+        runAtNextTick([byteCount, this, boh]() {
+            FILAMENT_CHECK_POSTCONDITION(false)
+                    << "Could not allocate Metal buffer of size " << byteCount
+                    << ", tag=" << mHandleAllocator.getHandleTag(boh.getId()).c_str_safe();
+        });
+    }
 }
 
 void MetalDriver::createTextureR(Handle<HwTexture> th, SamplerType target, uint8_t levels,
@@ -834,6 +857,10 @@ bool MetalDriver::isProtectedTexturesSupported() {
     return false;
 }
 
+bool MetalDriver::isDepthClampSupported() {
+    return true;
+}
+
 bool MetalDriver::isWorkaroundNeeded(Workaround workaround) {
     switch (workaround) {
         case Workaround::SPLIT_EASU:
@@ -1275,11 +1302,11 @@ void MetalDriver::setPushConstant(backend::ShaderStage stage, uint8_t index,
     pushConstants.setPushConstant(value, index);
 }
 
-void MetalDriver::insertEventMarker(const char* string, uint32_t len) {
+void MetalDriver::insertEventMarker(const char* string) {
 
 }
 
-void MetalDriver::pushGroupMarker(const char* string, uint32_t len) {
+void MetalDriver::pushGroupMarker(const char* string) {
     mContext->groupMarkers.push(string);
 }
 
@@ -1751,6 +1778,13 @@ void MetalDriver::bindPipeline(PipelineState const& ps) {
         [mContext->currentRenderPassEncoder setFrontFacingWinding:winding];
     }
 
+    // depth clip mode
+    MTLDepthClipMode depthClipMode = rs.depthClamp ? MTLDepthClipModeClamp : MTLDepthClipModeClip;
+    mContext->depthClampState.updateState(depthClipMode);
+    if (mContext->depthClampState.stateChanged()) {
+        [mContext->currentRenderPassEncoder setDepthClipMode:depthClipMode];
+    }
+
     // Set the depth-stencil state, if a state change is needed.
     DepthStencilState depthState;
     if (depthAttachment) {
@@ -1760,6 +1794,8 @@ void MetalDriver::bindPipeline(PipelineState const& ps) {
     if (stencilAttachment) {
         const auto& ss = ps.stencilState;
 
+        // Ben test
+
         auto& front = depthState.front;
         front.stencilCompare = getMetalCompareFunction(ss.front.stencilFunc);
         front.stencilOperationStencilFail = getMetalStencilOperation(ss.front.stencilOpStencilFail);
@@ -2061,16 +2097,17 @@ void MetalDriver::enumerateBoundBuffers(BufferObjectBinding bindingType,
 void MetalDriver::resetState(int) {
 }
 
+void MetalDriver::setDebugTag(HandleBase::HandleId handleId, utils::CString tag) {
+    mHandleAllocator.associateTagToHandle(handleId, std::move(tag));
+}
+
 void MetalDriver::runAtNextTick(const std::function<void()>& fn) noexcept {
-    std::lock_guard<std::mutex> const lock(mTickOpsLock);
     mTickOps.push_back(fn);
 }
 
 void MetalDriver::executeTickOps() noexcept {
     std::vector<std::function<void()>> ops;
-    mTickOpsLock.lock();
     std::swap(ops, mTickOps);
-    mTickOpsLock.unlock();
     for (const auto& f : ops) {
         f();
     }

filament/backend/src/metal/MetalHandles.mm

@@ -257,10 +257,6 @@ void MetalSwapChain::present() {
     }
 }
 
-#ifndef FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD
-#define FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD 1
-#endif
-
 class PresentDrawableData {
 public:
     PresentDrawableData() = delete;
@@ -279,14 +275,10 @@ public:
            [that->mDrawable present];
         }
 
-#if FILAMENT_RELEASE_PRESENT_DRAWABLE_MAIN_THREAD == 1
         // mDrawable is acquired on the driver thread. Typically, we would release this object on
         // the same thread, but after receiving consistent crash reports from within
         // [CAMetalDrawable dealloc], we suspect this object requires releasing on the main thread.
         dispatch_async(dispatch_get_main_queue(), ^{ cleanupAndDestroy(that); });
-#else
-        that->mDriver->runAtNextTick([that]() { cleanupAndDestroy(that); });
-#endif
     }
 
 private:

filament/backend/src/metal/MetalState.h

@@ -382,6 +382,7 @@ using SamplerStateCache = StateCache<SamplerState, id<MTLSamplerState>, SamplerS
 
 using CullModeStateTracker = StateTracker<MTLCullMode>;
 using WindingStateTracker = StateTracker<MTLWinding>;
+using DepthClampStateTracker = StateTracker<MTLDepthClipMode>;
 
 // Argument encoder
 

filament/backend/src/noop/NoopDriver.cpp

@@ -202,6 +202,10 @@ bool NoopDriver::isProtectedTexturesSupported() {
     return true;
 }
 
+bool NoopDriver::isDepthClampSupported() {
+    return false;
+}
+
 bool NoopDriver::isWorkaroundNeeded(Workaround) {
     return false;
 }
@@ -316,10 +320,10 @@ void NoopDriver::setPushConstant(backend::ShaderStage stage, uint8_t index,
         backend::PushConstantVariant value) {
 }
 
-void NoopDriver::insertEventMarker(char const* string, uint32_t len) {
+void NoopDriver::insertEventMarker(char const* string) {
 }
 
-void NoopDriver::pushGroupMarker(char const* string,  uint32_t len) {
+void NoopDriver::pushGroupMarker(char const* string) {
 }
 
 void NoopDriver::popGroupMarker(int) {
@@ -388,4 +392,7 @@ void NoopDriver::endTimerQuery(Handle<HwTimerQuery> tqh) {
 void NoopDriver::resetState(int) {
 }
 
+void NoopDriver::setDebugTag(HandleBase::HandleId handleId, utils::CString tag) {
+}
+
 } // namespace filament

filament/backend/src/opengl/OpenGLContext.cpp

@@ -541,9 +541,6 @@ void OpenGLContext::initBugs(Bugs* bugs, Extensions const& exts,
             bugs->delay_fbo_destruction = true;
             // PowerVR seems to have no problem with this (which is good for us)
             bugs->allow_read_only_ancillary_feedback_loop = true;
-            // PowerVR doesn't respect lengths passed to glShaderSource, so concatenate them into a
-            // single string.
-            bugs->concatenate_shader_strings = true;
         } else if (strstr(renderer, "Apple")) {
             // Apple GPU
         } else if (strstr(renderer, "Tegra") ||
@@ -679,6 +676,7 @@ void OpenGLContext::initExtensionsGLES(Extensions* ext, GLint major, GLint minor
 #ifndef __EMSCRIPTEN__
     ext->EXT_debug_marker = exts.has("GL_EXT_debug_marker"sv);
 #endif
+    ext->EXT_depth_clamp = exts.has("GL_EXT_depth_clamp"sv);
     ext->EXT_discard_framebuffer = exts.has("GL_EXT_discard_framebuffer"sv);
 #ifndef __EMSCRIPTEN__
     ext->EXT_disjoint_timer_query = exts.has("GL_EXT_disjoint_timer_query"sv);
@@ -749,6 +747,7 @@ void OpenGLContext::initExtensionsGL(Extensions* ext, GLint major, GLint minor)
     ext->EXT_color_buffer_half_float = true;  // Assumes core profile.
     ext->EXT_clip_cull_distance = true;
     ext->EXT_debug_marker = exts.has("GL_EXT_debug_marker"sv);
+    ext->EXT_depth_clamp = true;
     ext->EXT_discard_framebuffer = false;
     ext->EXT_disjoint_timer_query = true;
     ext->EXT_multisampled_render_to_texture = false;

filament/backend/src/opengl/OpenGLContext.h

@@ -220,8 +220,9 @@ public:
         bool EXT_color_buffer_float;
         bool EXT_color_buffer_half_float;
         bool EXT_debug_marker;
-        bool EXT_disjoint_timer_query;
+        bool EXT_depth_clamp;
         bool EXT_discard_framebuffer;
+        bool EXT_disjoint_timer_query;
         bool EXT_multisampled_render_to_texture2;
         bool EXT_multisampled_render_to_texture;
         bool EXT_protected_textures;
@@ -239,10 +240,10 @@ public:
         bool KHR_parallel_shader_compile;
         bool KHR_texture_compression_astc_hdr;
         bool KHR_texture_compression_astc_ldr;
-        bool OES_depth_texture;
-        bool OES_depth24;
-        bool OES_packed_depth_stencil;
         bool OES_EGL_image_external_essl3;
+        bool OES_depth24;
+        bool OES_depth_texture;
+        bool OES_packed_depth_stencil;
         bool OES_rgb8_rgba8;
         bool OES_standard_derivatives;
         bool OES_texture_npot;
@@ -315,12 +316,6 @@ public:
         // bugs or performance issues.
         bool force_feature_level0;
 
-        // Some drivers don't respect the length argument of glShaderSource() and (apparently)
-        // require each shader source string to be null-terminated. This works around the issue by
-        // concatenating the strings into a single null-terminated string before passing it to
-        // glShaderSource().
-        bool concatenate_shader_strings;
-
     } bugs = {};
 
     // state getters -- as needed.
@@ -567,9 +562,6 @@ private:
             {   bugs.force_feature_level0,
                     "force_feature_level0",
                     ""},
-            {   bugs.concatenate_shader_strings,
-                    "concatenate_shader_strings",
-                    ""},
     }};
 
     // this is chosen to minimize code size
@@ -636,6 +628,7 @@ constexpr size_t OpenGLContext::getIndexForCap(GLenum cap) noexcept { //NOLINT
 #ifdef BACKEND_OPENGL_VERSION_GL
         case GL_PROGRAM_POINT_SIZE:             index = 10; break;
 #endif
+        case GL_DEPTH_CLAMP:                    index = 11; break;
         default: break;
     }
     assert_invariant(index < state.enables.caps.size());

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -451,6 +451,14 @@ void OpenGLDriver::setRasterState(RasterState rs) noexcept {
     } else {
         gl.disable(GL_SAMPLE_ALPHA_TO_COVERAGE);
     }
+
+    if (gl.ext.EXT_depth_clamp) {
+        if (rs.depthClamp) {
+            gl.enable(GL_DEPTH_CLAMP);
+        } else {
+            gl.disable(GL_DEPTH_CLAMP);
+        }
+    }
 }
 
 void OpenGLDriver::setStencilState(StencilState ss) noexcept {
@@ -2119,6 +2127,10 @@ bool OpenGLDriver::isProtectedTexturesSupported() {
     return getContext().ext.EXT_protected_textures;
 }
 
+bool OpenGLDriver::isDepthClampSupported() {
+    return getContext().ext.EXT_depth_clamp;
+}
+
 bool OpenGLDriver::isWorkaroundNeeded(Workaround workaround) {
     switch (workaround) {
         case Workaround::SPLIT_EASU:
@@ -2210,6 +2222,10 @@ void OpenGLDriver::makeCurrent(Handle<HwSwapChain> schDraw, Handle<HwSwapChain>
 // Updating driver objects
 // ------------------------------------------------------------------------------------------------
 
+void OpenGLDriver::setDebugTag(HandleBase::HandleId handleId, utils::CString tag) {
+    mHandleAllocator.associateTagToHandle(handleId, std::move(tag));
+}
+
 void OpenGLDriver::setVertexBufferObject(Handle<HwVertexBuffer> vbh,
         uint32_t index, Handle<HwBufferObject> boh) {
    DEBUG_MARKER()
@@ -3180,23 +3196,23 @@ void OpenGLDriver::bindSamplers(uint32_t index, Handle<HwSamplerGroup> sbh) {
     CHECK_GL_ERROR(utils::slog.e)
 }
 
-void OpenGLDriver::insertEventMarker(char const* string, uint32_t len) {
+void OpenGLDriver::insertEventMarker(char const* string) {
 #ifndef __EMSCRIPTEN__
 #ifdef GL_EXT_debug_marker
     auto& gl = mContext;
     if (gl.ext.EXT_debug_marker) {
-        glInsertEventMarkerEXT(GLsizei(len ? len : strlen(string)), string);
+        glInsertEventMarkerEXT(GLsizei(strlen(string)), string);
     }
 #endif
 #endif
 }
 
-void OpenGLDriver::pushGroupMarker(char const* string, uint32_t len) {
+void OpenGLDriver::pushGroupMarker(char const* string) {
 #ifndef __EMSCRIPTEN__
 #ifdef GL_EXT_debug_marker
 #if DEBUG_GROUP_MARKER_LEVEL & DEBUG_GROUP_MARKER_OPENGL
     if (UTILS_LIKELY(mContext.ext.EXT_debug_marker)) {
-        glPushGroupMarkerEXT(GLsizei(len ? len : strlen(string)), string);
+        glPushGroupMarkerEXT(GLsizei(strlen(string)), string);
     }
 #endif
 #endif

filament/backend/src/opengl/ShaderCompilerService.cpp

@@ -597,40 +597,30 @@ void ShaderCompilerService::compileShaders(OpenGLContext& context,
                 version = "#version 310 es\n";
             }
 
-            const std::array<const char*, 5> sources = {
-                    version.data(),
-                    prolog.data(),
-                    specializationConstantString.c_str(),
-                    packingFunctions.data(),
-                    body.data()
+            std::array<std::string_view, 5> sources = {
+                version,
+                prolog,
+                specializationConstantString,
+                packingFunctions,
+                { body.data(), body.size() - 1 }  // null-terminated
             };
 
-            const std::array<GLint, 5> lengths = {
-                    (GLint)version.length(),
-                    (GLint)prolog.length(),
-                    (GLint)specializationConstantString.length(),
-                    (GLint)packingFunctions.length(),
-                    (GLint)body.length() - 1 // null terminated
-            };
+            // Some of the sources may be zero-length. Remove them as to avoid passing lengths of
+            // zero to glShaderSource(). glShaderSource should work with lengths of zero, but some
+            // drivers instead interpret zero as a sentinel for a null-terminated string.
+            auto partitionPoint = std::stable_partition(
+                    sources.begin(), sources.end(), [](std::string_view s) { return !s.empty(); });
+            size_t count = std::distance(sources.begin(), partitionPoint);
+
+            std::array<const char*, 5> shaderStrings;
+            std::array<GLint, 5> lengths;
+            for (size_t i = 0; i < count; i++) {
+                shaderStrings[i] = sources[i].data();
+                lengths[i] = sources[i].size();
+            }
 
             GLuint const shaderId = glCreateShader(glShaderType);
-
-            if (UTILS_UNLIKELY(context.bugs.concatenate_shader_strings)) {
-                size_t totalSize = 0;
-                for (size_t i = 0; i < sources.size(); i++) {
-                    totalSize += lengths[i];
-                }
-                std::string concatenatedShaderSource;
-                concatenatedShaderSource.reserve(totalSize);
-                for (size_t i = 0; i < sources.size(); i++) {
-                    concatenatedShaderSource.append(sources[i], lengths[i]);
-                }
-                const GLchar* ptr = concatenatedShaderSource.c_str();
-                GLint length = concatenatedShaderSource.length();
-                glShaderSource(shaderId, 1, &ptr, &length);
-            } else {
-                glShaderSource(shaderId, sources.size(), sources.data(), lengths.data());
-            }
+            glShaderSource(shaderId, count, shaderStrings.data(), lengths.data());
 
             glCompileShader(shaderId);
 

filament/backend/src/opengl/gl_headers.h

@@ -201,6 +201,12 @@ using namespace glext;
 #   define GL_CLIP_DISTANCE1                        0x3001
 #endif
 
+#if defined(GL_EXT_depth_clamp)
+#   define GL_DEPTH_CLAMP                           GL_DEPTH_CLAMP_EXT
+#else
+#   define GL_DEPTH_CLAMP                           0x864F
+#endif
+
 #if defined(GL_KHR_debug)
 #   define GL_DEBUG_OUTPUT                          GL_DEBUG_OUTPUT_KHR
 #   define GL_DEBUG_OUTPUT_SYNCHRONOUS              GL_DEBUG_OUTPUT_SYNCHRONOUS_KHR

filament/backend/src/vulkan/VulkanContext.h

@@ -125,6 +125,10 @@ public:
         return mPhysicalDeviceFeatures.imageCubeArray == VK_TRUE;
     }
 
+    inline bool isDepthClampSupported() const noexcept {
+        return mPhysicalDeviceFeatures.depthClamp == VK_TRUE;
+    }
+
     inline bool isDebugMarkersSupported() const noexcept {
         return mDebugMarkersSupported;
     }

filament/backend/src/vulkan/VulkanDriver.cpp

@@ -944,6 +944,10 @@ bool VulkanDriver::isProtectedTexturesSupported() {
     return false;
 }
 
+bool VulkanDriver::isDepthClampSupported() {
+    return mContext.isDepthClampSupported();
+}
+
 bool VulkanDriver::isWorkaroundNeeded(Workaround workaround) {
     switch (workaround) {
         case Workaround::SPLIT_EASU: {
@@ -1602,13 +1606,13 @@ void VulkanDriver::setPushConstant(backend::ShaderStage stage, uint8_t index,
             value);
 }
 
-void VulkanDriver::insertEventMarker(char const* string, uint32_t len) {
+void VulkanDriver::insertEventMarker(char const* string) {
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS)
-    mCommands.insertEventMarker(string, len);
+    mCommands.insertEventMarker(string, strlen(string));
 #endif
 }
 
-void VulkanDriver::pushGroupMarker(char const* string, uint32_t) {
+void VulkanDriver::pushGroupMarker(char const* string) {
     // Turns out all the markers are 0-terminated, so we can just pass it without len.
 #if FVK_ENABLED(FVK_DEBUG_GROUP_MARKERS)
     mCommands.pushGroupMarker(string);
@@ -1816,6 +1820,7 @@ void VulkanDriver::bindPipeline(PipelineState const& pipelineState) {
         .dstAlphaBlendFactor = getBlendFactor(rasterState.blendFunctionDstAlpha),
         .colorWriteMask = (VkColorComponentFlags) (rasterState.colorWrite ? 0xf : 0x0),
         .rasterizationSamples = rt->getSamples(),
+        .depthClamp = rasterState.depthClamp,
         .colorTargetCount = rt->getColorTargetCount(mCurrentRenderPass),
         .colorBlendOp = rasterState.blendEquationRGB,
         .alphaBlendOp =  rasterState.blendEquationAlpha,
@@ -2032,6 +2037,10 @@ void VulkanDriver::debugCommandBegin(CommandStream* cmds, bool synchronous, cons
 void VulkanDriver::resetState(int) {
 }
 
+void VulkanDriver::setDebugTag(HandleBase::HandleId handleId, utils::CString tag) {
+    mResourceAllocator.associateHandle(handleId, std::move(tag));
+}
+
 // explicit instantiation of the Dispatcher
 template class ConcreteDispatcher<VulkanDriver>;
 

filament/backend/src/vulkan/VulkanHandles.cpp

@@ -16,7 +16,6 @@
 
 #include "VulkanHandles.h"
 
-#include "VulkanDriver.h"
 #include "VulkanConstants.h"
 #include "VulkanDriver.h"
 #include "VulkanMemory.h"

filament/backend/src/vulkan/VulkanPipelineCache.cpp

@@ -184,6 +184,7 @@ VulkanPipelineCache::PipelineCacheEntry* VulkanPipelineCache::createPipeline() n
     vkRaster.polygonMode = VK_POLYGON_MODE_FILL;
     vkRaster.cullMode = raster.cullMode;
     vkRaster.frontFace = raster.frontFace;
+    vkRaster.depthClampEnable = raster.depthClamp;
     vkRaster.depthBiasEnable = raster.depthBiasEnable;
     vkRaster.depthBiasConstantFactor = raster.depthBiasConstantFactor;
     vkRaster.depthBiasClamp = 0.0f;

filament/backend/src/vulkan/VulkanPipelineCache.h

@@ -90,7 +90,8 @@ public:
         VkBlendFactor         srcAlphaBlendFactor : 5;
         VkBlendFactor         dstAlphaBlendFactor : 5;
         VkColorComponentFlags colorWriteMask : 4;
-        uint8_t               rasterizationSamples;    // offset = 4 bytes
+        uint8_t               rasterizationSamples : 4;// offset = 4 bytes
+        uint8_t               depthClamp : 4;
         uint8_t               colorTargetCount;        // offset = 5 bytes
         BlendEquation         colorBlendOp : 4;        // offset = 6 bytes
         BlendEquation         alphaBlendOp : 4;

filament/backend/src/vulkan/VulkanResourceAllocator.h

@@ -105,6 +105,10 @@ public:
         mHandleAllocatorImpl.deallocate(handle, obj);
     }
 
+    inline void associateHandle(HandleBase::HandleId id, utils::CString&& tag) noexcept {
+        mHandleAllocatorImpl.associateTagToHandle(id, std::move(tag));
+    }
+
 private:
     AllocatorImpl mHandleAllocatorImpl;
 

filament/backend/src/vulkan/VulkanTexture.cpp

@@ -97,13 +97,11 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         imageInfo.extent.depth = 1;
     }
 
-    // Filament expects blit() to work with any texture, so we almost always set these usage flags.
-    // TODO: investigate performance implications of setting these flags.
-    constexpr VkImageUsageFlags blittable = VK_IMAGE_USAGE_TRANSFER_DST_BIT |
-            VK_IMAGE_USAGE_TRANSFER_SRC_BIT;
-
-    if (any(usage & (TextureUsage::BLIT_DST | TextureUsage::BLIT_SRC))) {
-        imageInfo.usage |= blittable;
+    if (any(usage & TextureUsage::BLIT_SRC)) {
+        imageInfo.usage |= VK_IMAGE_USAGE_TRANSFER_SRC_BIT;
+    }
+    if (any(usage & TextureUsage::BLIT_DST)) {
+        imageInfo.usage |= VK_IMAGE_USAGE_TRANSFER_DST_BIT;
     }
 
     if (any(usage & TextureUsage::SAMPLEABLE)) {
@@ -121,7 +119,7 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         imageInfo.usage |= VK_IMAGE_USAGE_SAMPLED_BIT;
     }
     if (any(usage & TextureUsage::COLOR_ATTACHMENT)) {
-        imageInfo.usage |= VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT | blittable;
+        imageInfo.usage |= VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT;
         if (any(usage & TextureUsage::SUBPASS_INPUT)) {
             imageInfo.usage |= VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT;
         }
@@ -130,10 +128,9 @@ VulkanTexture::VulkanTexture(VkDevice device, VkPhysicalDevice physicalDevice,
         imageInfo.usage |= VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT;
     }
     if (any(usage & TextureUsage::UPLOADABLE)) {
-        imageInfo.usage |= blittable;
+        imageInfo.usage |= VK_IMAGE_USAGE_TRANSFER_DST_BIT;
     }
     if (any(usage & TextureUsage::DEPTH_ATTACHMENT)) {
-        imageInfo.usage |= blittable;
         imageInfo.usage |= VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT;
 
         // Depth resolves uses a custom shader and therefore needs to be sampleable.

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

@@ -325,6 +325,7 @@ VkDevice createLogicalDevice(VkPhysicalDevice physicalDevice,
     // We could simply enable all supported features, but since that may have performance
     // consequences let's just enable the features we need.
     VkPhysicalDeviceFeatures enabledFeatures{
+            .depthClamp = features.depthClamp,
             .samplerAnisotropy = features.samplerAnisotropy,
             .textureCompressionETC2 = features.textureCompressionETC2,
             .textureCompressionBC = features.textureCompressionBC,

filament/include/filament/BufferObject.h

@@ -54,7 +54,7 @@ public:
     using BufferDescriptor = backend::BufferDescriptor;
     using BindingType = backend::BufferObjectBinding;
 
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -78,6 +78,21 @@ public:
          */
         Builder& bindingType(BindingType bindingType) noexcept;
 
+        /**
+         * Associate an optional name with this BufferObject for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this BufferObject
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the BufferObject and returns a pointer to it. After creation, the buffer
          * object is uninitialized. Use BufferObject::setBuffer() to initialize it.

filament/include/filament/FilamentAPI.h

@@ -19,6 +19,7 @@
 
 #include <utils/compiler.h>
 #include <utils/PrivateImplementation.h>
+#include <utils/CString.h>
 
 #include <stddef.h>
 
@@ -54,6 +55,23 @@ public:
 template<typename T>
 using BuilderBase = utils::PrivateImplementation<T>;
 
+// This needs to be public because it is used in the following template.
+UTILS_PUBLIC void builderMakeName(utils::CString& outName, const char* name, size_t len) noexcept;
+
+template <typename Builder>
+class UTILS_PUBLIC BuilderNameMixin {
+public:
+    Builder& name(const char* name, size_t len) noexcept {
+        builderMakeName(mName, name, len);
+        return static_cast<Builder&>(*this);
+    }
+
+    utils::CString const& getName() const noexcept { return mName; }
+
+private:
+    utils::CString mName;
+};
+
 } // namespace filament
 
 #endif // TNT_FILAMENT_FILAMENTAPI_H

filament/include/filament/IndexBuffer.h

@@ -59,7 +59,7 @@ public:
         UINT = uint8_t(backend::ElementType::UINT),      //!< 32-bit indices
     };
 
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -83,6 +83,21 @@ public:
          */
         Builder& bufferType(IndexType indexType) noexcept;
 
+        /**
+         * Associate an optional name with this IndexBuffer for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this IndexBuffer
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the IndexBuffer object and returns a pointer to it. After creation, the index
          * buffer is uninitialized. Use IndexBuffer::setBuffer() to initialize the IndexBuffer.

filament/include/filament/InstanceBuffer.h

@@ -38,7 +38,7 @@ class UTILS_PUBLIC InstanceBuffer : public FilamentAPI {
     struct BuilderDetails;
 
 public:
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
 
     public:
@@ -70,6 +70,21 @@ public:
          */
         Builder& localTransforms(math::mat4f const* UTILS_NULLABLE localTransforms) noexcept;
 
+        /**
+         * Associate an optional name with this InstanceBuffer for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this InstanceBuffer
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the InstanceBuffer object and returns a pointer to it.
          */

filament/include/filament/MorphTargetBuffer.h

@@ -39,7 +39,7 @@ class UTILS_PUBLIC MorphTargetBuffer : public FilamentAPI {
     struct BuilderDetails;
 
 public:
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -63,6 +63,21 @@ public:
          */
         Builder& count(size_t count) noexcept;
 
+        /**
+         * Associate an optional name with this MorphTargetBuffer for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this MorphTargetBuffer
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the MorphTargetBuffer object and returns a pointer to it.
          *

filament/include/filament/SkinningBuffer.h

@@ -39,7 +39,7 @@ class UTILS_PUBLIC SkinningBuffer : public FilamentAPI {
     struct BuilderDetails;
 
 public:
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -69,6 +69,21 @@ public:
          */
         Builder& initialize(bool initialize = true) noexcept;
 
+        /**
+         * Associate an optional name with this SkinningBuffer for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this SkinningBuffer
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the SkinningBuffer object and returns a pointer to it.
          *

filament/include/filament/Stream.h

@@ -94,7 +94,7 @@ public:
      *
      * To create a NATIVE stream, call the <pre>stream</pre> method on the builder.
      */
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -136,6 +136,21 @@ public:
          */
         Builder& height(uint32_t height) noexcept;
 
+        /**
+         * Associate an optional name with this Stream for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this Stream
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the Stream object and returns a pointer to it.
          *

filament/include/filament/Texture.h

@@ -112,7 +112,7 @@ public:
 
 
     //! Use Builder to construct a Texture object instance
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -202,6 +202,21 @@ public:
          */
         Builder& swizzle(Swizzle r, Swizzle g, Swizzle b, Swizzle a) noexcept;
 
+        /**
+         * Associate an optional name with this Texture for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this Texture
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+         // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the Texture object and returns a pointer to it.
          *

filament/include/filament/VertexBuffer.h

@@ -61,7 +61,7 @@ public:
     using AttributeType = backend::ElementType;
     using BufferDescriptor = backend::BufferDescriptor;
 
-    class Builder : public BuilderBase<BuilderDetails> {
+    class Builder : public BuilderBase<BuilderDetails>, public BuilderNameMixin<Builder> {
         friend struct BuilderDetails;
     public:
         Builder() noexcept;
@@ -158,6 +158,21 @@ public:
          */
         Builder& advancedSkinning(bool enabled) noexcept;
 
+        /**
+         * Associate an optional name with this VertexBuffer for debugging purposes.
+         *
+         * name will show in error messages and should be kept as short as possible. The name is
+         * truncated to a maximum of 128 characters.
+         *
+         * The name string is copied during this method so clients may free its memory after
+         * the function returns.
+         *
+         * @param name A string to identify this VertexBuffer
+         * @param len Length of name, should be less than or equal to 128
+         * @return This Builder, for chaining calls.
+         */
+        // Builder& name(const char* UTILS_NONNULL name, size_t len) noexcept; // inherited
+
         /**
          * Creates the VertexBuffer object and returns a pointer to it.
          *

filament/include/filament/View.h

@@ -24,6 +24,7 @@
 
 #include <utils/compiler.h>
 #include <utils/Entity.h>
+#include <utils/FixedCapacityVector.h>
 
 #include <math/mathfwd.h>
 
@@ -727,7 +728,7 @@ public:
     void setDebugCamera(Camera* UTILS_NULLABLE camera) noexcept;
 
     //! debugging: returns a Camera from the point of view of *the* dominant directional light used for shadowing.
-    Camera const* UTILS_NULLABLE getDirectionalShadowCamera() const noexcept;
+    utils::FixedCapacityVector<Camera const*> getDirectionalShadowCameras() const noexcept;
 
 
     /** Result of a picking query */

filament/src/FilamentBuilder.cpp

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2024 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <filament/FilamentAPI.h>
+
+#include <algorithm>
+
+namespace filament {
+
+void builderMakeName(utils::CString& outName, const char* name, size_t len) noexcept {
+    if (!name) {
+        return;
+    }
+    size_t const length = std::min(len, size_t { 128u });
+    outName = utils::CString(name, length);
+}
+
+} // namespace filament

filament/src/FrameSkipper.cpp

@@ -16,16 +16,22 @@
 
 #include "FrameSkipper.h"
 
-#include <utils/Log.h>
+#include <backend/DriverEnums.h>
+
+#include <utils/compiler.h>
 #include <utils/debug.h>
 
+#include <algorithm>
+
+#include <stddef.h>
+
 namespace filament {
 
 using namespace utils;
 using namespace backend;
 
 FrameSkipper::FrameSkipper(size_t latency) noexcept
-        : mLast(latency - 1) {
+        : mLast(std::max(latency, MAX_FRAME_LATENCY) - 1) {
     assert_invariant(latency <= MAX_FRAME_LATENCY);
 }
 
@@ -41,31 +47,32 @@ void FrameSkipper::terminate(DriverApi& driver) noexcept {
 
 bool FrameSkipper::beginFrame(DriverApi& driver) noexcept {
     auto& fences = mDelayedFences;
-    auto fence = fences.front();
-    if (fence) {
-        auto status = driver.getFenceStatus(fence);
-        if (status == FenceStatus::TIMEOUT_EXPIRED) {
-            // Sync not ready, skip frame
+    if (fences.front()) {
+        // Do we have a latency old fence?
+        auto status = driver.getFenceStatus(fences.front());
+        if (UTILS_UNLIKELY(status == FenceStatus::TIMEOUT_EXPIRED)) {
+            // The fence hasn't signaled yet, skip this frame
             return false;
         }
         assert_invariant(status == FenceStatus::CONDITION_SATISFIED);
-        driver.destroyFence(fence);
     }
-    // shift all fences down by 1
-    std::move(fences.begin() + 1, fences.end(), fences.begin());
-    fences.back() = {};
     return true;
 }
 
 void FrameSkipper::endFrame(DriverApi& driver) noexcept {
-    // If the user produced a new frame despite the fact that the previous one wasn't finished
-    // (i.e. FrameSkipper::beginFrame() returned false), we need to make sure to replace
-    // a fence that might be here already)
-    auto& fence = mDelayedFences[mLast];
-    if (fence) {
-        driver.destroyFence(fence);
+    auto& fences = mDelayedFences;
+    size_t const last = mLast;
+
+    // pop the oldest fence and advance the other ones
+    if (fences.front()) {
+        driver.destroyFence(fences.front());
     }
-    fence = driver.createFence();
+    std::move(fences.begin() + 1, fences.end(), fences.begin());
+
+    // add a new fence to the end
+    assert_invariant(!fences[last]);
+
+    fences[last] = driver.createFence();
 }
 
 } // namespace filament

filament/src/FrameSkipper.h

@@ -22,6 +22,9 @@
 
 #include <array>
 
+#include <stddef.h>
+#include <stdint.h>
+
 namespace filament {
 
 /*
@@ -60,7 +63,7 @@ public:
 private:
     using Container = std::array<backend::Handle<backend::HwFence>, MAX_FRAME_LATENCY>;
     mutable Container mDelayedFences{};
-    size_t mLast;
+    uint8_t const mLast;
 };
 
 } // namespace filament

filament/src/PerViewUniforms.cpp

@@ -459,10 +459,12 @@ void PerViewUniforms::bind(backend::DriverApi& driver) noexcept {
 
 void PerViewUniforms::unbindSamplers() noexcept {
     auto& samplerGroup = mSamplers;
+    samplerGroup.clearSampler(PerViewSib::SHADOW_MAP);
+    samplerGroup.clearSampler(PerViewSib::IBL_SPECULAR);
     samplerGroup.clearSampler(PerViewSib::SSAO);
     samplerGroup.clearSampler(PerViewSib::SSR);
     samplerGroup.clearSampler(PerViewSib::STRUCTURE);
-    samplerGroup.clearSampler(PerViewSib::SHADOW_MAP);
+    samplerGroup.clearSampler(PerViewSib::FOG);
 }
 
 } // namespace filament

filament/src/PostProcessManager.cpp

@@ -494,7 +494,6 @@ PostProcessManager::StructurePassOutput PostProcessManager::structure(FrameGraph
 
     struct StructureMipmapData {
         FrameGraphId<FrameGraphTexture> depth;
-        uint32_t rt[8];
     };
 
     fg.addPass<StructureMipmapData>("StructureMipmap",
@@ -505,7 +504,7 @@ PostProcessManager::StructurePassOutput PostProcessManager::structure(FrameGraph
                             .level = uint8_t(i)
                     });
                     out = builder.write(out, FrameGraphTexture::Usage::DEPTH_ATTACHMENT);
-                    data.rt[i - 1] = builder.declareRenderPass("Structure mip target", {
+                    builder.declareRenderPass("Structure mip target", {
                             .attachments = { .depth = out }
                     });
                 }
@@ -2946,6 +2945,10 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::upscale(FrameGraph& fg, bool
                                     1.0f / outputDesc.height});
                     }
 
+                    if (blitterNames[index] == "blitLow") {
+                        mi->setParameter("levelOfDetail", 0.0f);
+                    }
+
                     mi->setParameter("viewport", float4{
                             (float)vp.left   / inputDesc.width,
                             (float)vp.bottom / inputDesc.height,
@@ -3004,9 +3007,8 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::blit(FrameGraph& fg, bool tr
         SamplerMagFilter filterMag,
         SamplerMinFilter filterMin) noexcept {
 
-    // TODO: add support for sub-resources
-    assert_invariant(fg.getSubResourceDescriptor(input).layer == 0);
-    assert_invariant(fg.getSubResourceDescriptor(input).level == 0);
+    uint32_t const layer = fg.getSubResourceDescriptor(input).layer;
+    float const levelOfDetail = fg.getSubResourceDescriptor(input).level;
 
     struct QuadBlitData {
         FrameGraphId<FrameGraphTexture> input;
@@ -3032,7 +3034,8 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::blit(FrameGraph& fg, bool tr
                 // --------------------------------------------------------------------------------
                 // set uniforms
 
-                PostProcessMaterial const& material = getPostProcessMaterial("blitLow");
+                PostProcessMaterial const& material =
+                        getPostProcessMaterial(layer ? "blitArray" : "blitLow");
                 auto* mi = material.getMaterialInstance(mEngine);
                 mi->setParameter("color", color, {
                         .filterMag = filterMag,
@@ -3044,6 +3047,10 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::blit(FrameGraph& fg, bool tr
                         float(vp.width)  / inputDesc.width,
                         float(vp.height) / inputDesc.height
                 });
+                mi->setParameter("levelOfDetail", levelOfDetail);
+                if (layer) {
+                    mi->setParameter("layerIndex", layer);
+                }
                 mi->commit(driver);
                 mi->use(driver);
 
@@ -3186,6 +3193,7 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::resolve(FrameGraph& fg,
                 assert_invariant(dst);
                 assert_invariant(srcDesc.format == dstDesc.format);
                 assert_invariant(srcDesc.width == dstDesc.width && srcDesc.height == dstDesc.height);
+                assert_invariant(srcDesc.samples > 1 && dstDesc.samples <= 1);
                 driver.resolve(
                         dst, dstSubDesc.level, dstSubDesc.layer,
                         src, srcSubDesc.level, srcSubDesc.layer);

filament/src/RenderPass.cpp

@@ -419,7 +419,8 @@ RenderPass::Command* RenderPass::instanceify(FEngine& engine,
 UTILS_ALWAYS_INLINE // This function exists only to make the code more readable. we want it inlined.
 inline              // and we don't need it in the compilation unit
 void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
-        FMaterialInstance const* const UTILS_RESTRICT mi, bool inverseFrontFaces) noexcept {
+        FMaterialInstance const* const UTILS_RESTRICT mi,
+        bool inverseFrontFaces, bool hasDepthClamp) noexcept {
 
     FMaterial const * const UTILS_RESTRICT ma = mi->getMaterial();
     variant = Variant::filterVariant(variant, ma->isVariantLit());
@@ -460,6 +461,7 @@ void RenderPass::setupColorCommand(Command& cmdDraw, Variant variant,
     cmdDraw.info.rasterState.colorWrite = mi->isColorWriteEnabled();
     cmdDraw.info.rasterState.depthWrite = mi->isDepthWriteEnabled();
     cmdDraw.info.rasterState.depthFunc = mi->getDepthFunc();
+    cmdDraw.info.rasterState.depthClamp = hasDepthClamp;
     cmdDraw.info.materialVariant = variant;
     // we keep "RasterState::colorWrite" to the value set by material (could be disabled)
 }
@@ -558,6 +560,9 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
     bool const hasInstancedStereo =
             renderFlags & IS_INSTANCED_STEREOSCOPIC;
 
+    bool const hasDepthClamp =
+            renderFlags & HAS_DEPTH_CLAMP;
+
     float const cameraPositionDotCameraForward = dot(cameraPosition, cameraForward);
 
     auto const* const UTILS_RESTRICT soaWorldAABBCenter = soa.data<FScene::WORLD_AABB_CENTER>();
@@ -577,6 +582,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
         cmd.info.rasterState.depthWrite = true;
         cmd.info.rasterState.depthFunc = RasterState::DepthFunc::GE;
         cmd.info.rasterState.alphaToCoverage = false;
+        cmd.info.rasterState.depthClamp = hasDepthClamp;
     }
 
     for (uint32_t i = range.first; i < range.last; ++i) {
@@ -610,7 +616,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
         //   Here, objects close to the camera (but behind) will be drawn first.
         // An alternative that keeps the mathematical ordering is given here:
         //   distanceBits ^= ((int32_t(distanceBits) >> 31) | 0x80000000u);
-        float const distance = -dot(soaWorldAABBCenter[i], cameraForward) - cameraPositionDotCameraForward;
+        float const distance = -(dot(soaWorldAABBCenter[i], cameraForward) - cameraPositionDotCameraForward);
         uint32_t const distanceBits = reinterpret_cast<uint32_t const&>(distance);
 
         // calculate the per-primitive face winding order inversion
@@ -691,7 +697,8 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
             cmd.info.morphingOffset = primitive.getMorphingBufferOffset();
 
             if constexpr (isColorPass) {
-                RenderPass::setupColorCommand(cmd, renderableVariant, mi, inverseFrontFaces);
+                RenderPass::setupColorCommand(cmd, renderableVariant, mi,
+                        inverseFrontFaces, hasDepthClamp);
                 const bool blendPass = Pass(cmd.key & PASS_MASK) == Pass::BLENDED;
                 if (blendPass) {
                     // TODO: at least for transparent objects, AABB should be per primitive

filament/src/RenderPass.h

@@ -284,6 +284,7 @@ public:
     static constexpr RenderFlags HAS_SHADOWING             = 0x01;
     static constexpr RenderFlags HAS_INVERSE_FRONT_FACES   = 0x02;
     static constexpr RenderFlags IS_INSTANCED_STEREOSCOPIC = 0x04;
+    static constexpr RenderFlags HAS_DEPTH_CLAMP           = 0x08;
 
     // Arena used for commands
     using Arena = utils::Arena<
@@ -444,7 +445,7 @@ private:
             uint8_t instancedStereoEyeCount) noexcept;
 
     static void setupColorCommand(Command& cmdDraw, Variant variant,
-            FMaterialInstance const* mi, bool inverseFrontFaces) noexcept;
+            FMaterialInstance const* mi, bool inverseFrontFaces, bool hasDepthClamp) noexcept;
 
     static void updateSummedPrimitiveCounts(
             FScene::RenderableSoa& renderableData, utils::Range<uint32_t> vr) noexcept;
@@ -528,7 +529,9 @@ public:
     // like above but allows to set specific flags
     RenderPassBuilder& renderFlags(
             RenderPass::RenderFlags mask, RenderPass::RenderFlags value) noexcept {
-        mFlags = (mFlags & mask) | (value & mask);
+        value &= mask;
+        mFlags &= ~mask;
+        mFlags |= value;
         return *this;
     }
 

filament/src/RendererUtils.cpp

@@ -40,6 +40,7 @@
 #include <utils/Panic.h>
 
 #include <algorithm>
+#include <optional>
 #include <utility>
 
 #include <stddef.h>
@@ -50,8 +51,9 @@ namespace filament {
 using namespace backend;
 using namespace math;
 
-FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
+RendererUtils::ColorPassOutput RendererUtils::colorPass(
         FrameGraph& fg, const char* name, FEngine& engine, FView const& view,
+        ColorPassInput const& colorPassInput,
         FrameGraphTexture::Descriptor const& colorBufferDesc,
         ColorPassConfig const& config, PostProcessManager::ColorGradingConfig colorGradingConfig,
         RenderPass::Executor passExecutor) noexcept {
@@ -67,31 +69,28 @@ FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
         FrameGraphId<FrameGraphTexture> structure;
     };
 
-    Blackboard& blackboard = fg.getBlackboard();
-
     auto& colorPass = fg.addPass<ColorPassData>(name,
             [&](FrameGraph::Builder& builder, ColorPassData& data) {
 
                 TargetBufferFlags const clearColorFlags = config.clearFlags & TargetBufferFlags::COLOR;
                 TargetBufferFlags clearDepthFlags = config.clearFlags & TargetBufferFlags::DEPTH;
                 TargetBufferFlags clearStencilFlags = config.clearFlags & TargetBufferFlags::STENCIL;
-                uint8_t layerCount = 1;
 
-                data.shadows = blackboard.get<FrameGraphTexture>("shadows");
-                data.ssao = blackboard.get<FrameGraphTexture>("ssao");
-                data.color = blackboard.get<FrameGraphTexture>("color");
-                data.depth = blackboard.get<FrameGraphTexture>("depth");
+                data.color = colorPassInput.linearColor;
+                data.depth = colorPassInput.depth;
+                data.shadows = colorPassInput.shadows;
+                data.ssao = colorPassInput.ssao;
 
                 // Screen-space reflection or refractions
                 if (config.hasScreenSpaceReflectionsOrRefractions) {
-                    data.ssr = blackboard.get<FrameGraphTexture>("ssr");
+                    data.ssr = colorPassInput.ssr;
                     if (data.ssr) {
                         data.ssr = builder.sample(data.ssr);
                     }
                 }
 
                 if (config.hasContactShadows) {
-                    data.structure = blackboard.get<FrameGraphTexture>("structure");
+                    data.structure = colorPassInput.structure;
                     assert_invariant(data.structure);
                     data.structure = builder.sample(data.structure);
                 }
@@ -154,6 +153,8 @@ FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
                 }
 
                 if (colorGradingConfig.asSubpass) {
+                    assert_invariant(config.msaa <= 1);
+                    assert_invariant(colorBufferDesc.samples <= 1);
                     data.output = builder.createTexture("Tonemapped Buffer", {
                             .width = colorBufferDesc.width,
                             .height = colorBufferDesc.height,
@@ -172,9 +173,6 @@ FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
 
                 data.color = builder.write(data.color, FrameGraphTexture::Usage::COLOR_ATTACHMENT);
                 data.depth = builder.write(data.depth, FrameGraphTexture::Usage::DEPTH_ATTACHMENT);
-                if (view.hasStereo() && engine.getConfig().stereoscopicType == StereoscopicType::MULTIVIEW) {
-                    layerCount = engine.getConfig().stereoscopicEyeCount;
-                }
 
                 /*
                  * There is a bit of magic happening here regarding the viewport used.
@@ -196,9 +194,8 @@ FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
                         .stencil = data.stencil },
                         .clearColor = config.clearColor,
                         .samples = config.msaa,
-                        .layerCount = layerCount,
+                        .layerCount = static_cast<uint8_t>(colorBufferDesc.depth),
                         .clearFlags = clearColorFlags | clearDepthFlags | clearStencilFlags});
-                blackboard["depth"] = data.depth;
             },
             [=, passExecutor = std::move(passExecutor), &view, &engine](FrameGraphResources const& resources,
                     ColorPassData const& data, DriverApi& driver) {
@@ -264,24 +261,21 @@ FrameGraphId<FrameGraphTexture> RendererUtils::colorPass(
             }
     );
 
-    // when color grading is done as a subpass, the output of the color-pass is the ldr buffer
-    auto output = colorGradingConfig.asSubpass ? colorPass->output : colorPass->color;
-
-    blackboard["color"] = output;
-    return output;
+    return {
+            .linearColor = colorPass->color,
+            .tonemappedColor = colorPass->output,   // can be null
+            .depth = colorPass->depth
+    };
 }
 
-std::pair<FrameGraphId<FrameGraphTexture>, bool> RendererUtils::refractionPass(
+std::optional<RendererUtils::ColorPassOutput> RendererUtils::refractionPass(
         FrameGraph& fg, FEngine& engine, FView const& view,
+        ColorPassInput colorPassInput,
         ColorPassConfig config,
         PostProcessManager::ScreenSpaceRefConfig const& ssrConfig,
         PostProcessManager::ColorGradingConfig colorGradingConfig,
         RenderPass const& pass) noexcept {
 
-    auto& blackboard = fg.getBlackboard();
-    auto input = blackboard.get<FrameGraphTexture>("color");
-    FrameGraphId<FrameGraphTexture> output;
-
     // find the first refractive object in channel 2
     RenderPass::Command const* const refraction = std::partition_point(pass.begin(), pass.end(),
             [](auto const& command) {
@@ -296,34 +290,35 @@ std::pair<FrameGraphId<FrameGraphTexture>, bool> RendererUtils::refractionPass(
 
     // if there wasn't any refractive object, just skip everything below.
     if (UTILS_UNLIKELY(hasScreenSpaceRefraction)) {
-        PostProcessManager& ppm = engine.getPostProcessManager();
-
-        // clear the color/depth buffers, which will orphan (and cull) the color pass
-        input.clear();
-        blackboard.remove("color");
-        blackboard.remove("depth");
-
+        assert_invariant(!colorPassInput.linearColor);
+        assert_invariant(!colorPassInput.depth);
         config.hasScreenSpaceReflectionsOrRefractions = true;
 
-        input = RendererUtils::colorPass(fg, "Color Pass (opaque)", engine, view, {
+        PostProcessManager& ppm = engine.getPostProcessManager();
+        auto const opaquePassOutput = RendererUtils::colorPass(fg,
+                "Color Pass (opaque)", engine, view, colorPassInput, {
                         // When rendering the opaques, we need to conserve the sample buffer,
                         // so create a config that specifies the sample count.
                         .width = config.physicalViewport.width,
                         .height = config.physicalViewport.height,
                         .samples = config.msaa,
                         .format = config.hdrFormat
-                }, config, { .asSubpass = false },
+                },
+                config, { .asSubpass = false, .customResolve = false },
                 pass.getExecutor(pass.begin(), refraction));
 
         // generate the mipmap chain
         PostProcessManager::generateMipmapSSR(ppm, fg,
-                input, ssrConfig.refraction, true, ssrConfig);
+                opaquePassOutput.linearColor,
+                ssrConfig.refraction,
+                true, ssrConfig);
 
         // Now we're doing the refraction pass proper.
-        // This uses the same framebuffer (color and depth) used by the opaque pass. This happens
-        // automatically because these are set in the Blackboard (they were set by the opaque
-        // pass). For this reason, `desc` below is only used in colorPass() for the width and
-        // height.
+        // This uses the same framebuffer (color and depth) used by the opaque pass.
+        // For this reason, the `colorBufferDesc` parameter of colorPass() below is only used  for
+        // the width and height.
+        colorPassInput.linearColor = opaquePassOutput.linearColor;
+        colorPassInput.depth = opaquePassOutput.depth;
 
         // Since we're reusing the existing target we don't want to clear any of its buffer.
         // Important: if this target ended up being an imported target, then the clearFlags
@@ -331,22 +326,25 @@ std::pair<FrameGraphId<FrameGraphTexture>, bool> RendererUtils::refractionPass(
         // and we'd end up clearing the opaque pass. This scenario never happens because it is
         // prevented in Renderer.cpp's final blit.
         config.clearFlags = TargetBufferFlags::NONE;
-        output = RendererUtils::colorPass(fg, "Color Pass (transparent)", engine, view, {
+        auto transparentPassOutput = RendererUtils::colorPass(fg, "Color Pass (transparent)",
+                engine, view, colorPassInput, {
                         .width = config.physicalViewport.width,
                         .height = config.physicalViewport.height },
-                config, colorGradingConfig, pass.getExecutor(refraction, pass.end()));
+                config, colorGradingConfig,
+                pass.getExecutor(refraction, pass.end()));
 
         if (config.msaa > 1 && !colorGradingConfig.asSubpass) {
             // We need to do a resolve here because later passes (such as color grading or DoF) will
             // need to sample from 'output'. However, because we have MSAA, we know we're not
             // sampleable. And this is because in the SSR case, we had to use a renderbuffer to
             // conserve the multi-sample buffer.
-            output = ppm.resolve(fg, "Resolved Color Buffer", output, { .levels = 1 });
+            transparentPassOutput.linearColor = ppm.resolve(fg, "Resolved Color Buffer",
+                    transparentPassOutput.linearColor, { .levels = 1 });
         }
-    } else {
-        output = input;
+        return transparentPassOutput;
     }
-    return { output, hasScreenSpaceRefraction };
+
+    return std::nullopt;
 }
 
 UTILS_NOINLINE

filament/src/RendererUtils.h

@@ -21,14 +21,19 @@
 #include "RenderPass.h"
 
 #include "fg/FrameGraphId.h"
+#include "fg/FrameGraphTexture.h"
+
+#include <filament/Viewport.h>
 
 #include <backend/DriverEnums.h>
 #include <backend/PixelBufferDescriptor.h>
 
+#include <math/vec2.h>
 #include <math/vec4.h>
 
 #include <stdint.h>
 
+#include <optional>
 #include <utility>
 
 namespace filament {
@@ -71,15 +76,32 @@ public:
         bool screenSpaceReflectionHistoryNotReady;
     };
 
-    static FrameGraphId<FrameGraphTexture> colorPass(
+    struct ColorPassInput {
+        FrameGraphId<FrameGraphTexture> linearColor;
+        FrameGraphId<FrameGraphTexture> tonemappedColor;
+        FrameGraphId<FrameGraphTexture> depth;
+        FrameGraphId<FrameGraphTexture> shadows;
+        FrameGraphId<FrameGraphTexture> ssao;
+        FrameGraphId<FrameGraphTexture> ssr;
+        FrameGraphId<FrameGraphTexture> structure;
+    };
+    struct ColorPassOutput {
+        FrameGraphId<FrameGraphTexture> linearColor;
+        FrameGraphId<FrameGraphTexture> tonemappedColor;
+        FrameGraphId<FrameGraphTexture> depth;
+    };
+
+    static ColorPassOutput colorPass(
             FrameGraph& fg, const char* name, FEngine& engine, FView const& view,
+            ColorPassInput const& colorPassInput,
             FrameGraphTexture::Descriptor const& colorBufferDesc,
             ColorPassConfig const& config,
             PostProcessManager::ColorGradingConfig colorGradingConfig,
             RenderPass::Executor passExecutor) noexcept;
 
-    static std::pair<FrameGraphId<FrameGraphTexture>, bool> refractionPass(
+    static std::optional<RendererUtils::ColorPassOutput> refractionPass(
             FrameGraph& fg, FEngine& engine, FView const& view,
+            ColorPassInput colorPassInput,
             ColorPassConfig config,
             PostProcessManager::ScreenSpaceRefConfig const& ssrConfig,
             PostProcessManager::ColorGradingConfig colorGradingConfig,

filament/src/ResourceAllocator.cpp

@@ -143,12 +143,14 @@ void ResourceAllocator::terminate() noexcept {
     }
 }
 
-RenderTargetHandle ResourceAllocator::createRenderTarget(const char*,
+RenderTargetHandle ResourceAllocator::createRenderTarget(const char* name,
         TargetBufferFlags targetBufferFlags, uint32_t width, uint32_t height,
         uint8_t samples, uint8_t layerCount, MRT color, TargetBufferInfo depth,
         TargetBufferInfo stencil) noexcept {
-    return mBackend.createRenderTarget(targetBufferFlags,
+    auto handle = mBackend.createRenderTarget(targetBufferFlags,
             width, height, samples ? samples : 1u, layerCount, color, depth, stencil);
+    mBackend.setDebugTag(handle.getId(), CString{ name });
+    return handle;
 }
 
 void ResourceAllocator::destroyRenderTarget(RenderTargetHandle h) noexcept {
@@ -170,9 +172,9 @@ backend::TextureHandle ResourceAllocator::createTexture(const char* name,
 
     // do we have a suitable texture in the cache?
     TextureHandle handle;
+    TextureKey const key{ name, target, levels, format, samples, width, height, depth, usage, swizzle };
     if constexpr (mEnabled) {
         auto& textureCache = mTextureCache;
-        const TextureKey key{ name, target, levels, format, samples, width, height, depth, usage, swizzle };
         auto it = textureCache.find(key);
         if (UTILS_LIKELY(it != textureCache.end())) {
             // we do, move the entry to the in-use list, and remove from the cache
@@ -190,7 +192,6 @@ backend::TextureHandle ResourceAllocator::createTexture(const char* name,
                         swizzle[0], swizzle[1], swizzle[2], swizzle[3]);
             }
         }
-        mDisposer->checkout(handle, key);
     } else {
         if (swizzle == defaultSwizzle) {
             handle = mBackend.createTexture(
@@ -201,12 +202,14 @@ backend::TextureHandle ResourceAllocator::createTexture(const char* name,
                     swizzle[0], swizzle[1], swizzle[2], swizzle[3]);
         }
     }
+    mDisposer->checkout(handle, key);
+    mBackend.setDebugTag(handle.getId(), CString{ name });
     return handle;
 }
 
 void ResourceAllocator::destroyTexture(TextureHandle h) noexcept {
+    auto const key = mDisposer->checkin(h);
     if constexpr (mEnabled) {
-        auto const key = mDisposer->checkin(h);
         if (UTILS_LIKELY(key.has_value())) {
             uint32_t const size = key.value().getSize();
             mTextureCache.emplace(key.value(), TextureCachePayload{ h, mAge, size });

filament/src/ShadowMap.cpp

@@ -57,9 +57,6 @@ namespace filament {
 using namespace math;
 using namespace backend;
 
-// do this only if depth-clamp is available
-static constexpr bool USE_DEPTH_CLAMP = false;
-
 ShadowMap::ShadowMap(FEngine& engine) noexcept
         : mPerShadowMapUniforms(engine),
           mShadowType(ShadowType::DIRECTIONAL),
@@ -126,7 +123,8 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
         FScene::LightSoa const& lightData, size_t index,
         filament::CameraInfo const& camera,
         ShadowMapInfo const& shadowMapInfo,
-        SceneInfo const& sceneInfo) noexcept {
+        SceneInfo const& sceneInfo,
+        bool useDepthClamp) noexcept {
 
     // reset the visible shadow status
     mHasVisibleShadows = false;
@@ -137,13 +135,20 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
 
     const auto direction = lightData.elementAt<FScene::SHADOW_DIRECTION>(index);
 
-    auto [Mv, znear, zfar, lsClippedShadowVolume, vertexCount, visibleShadows] =
-            computeDirectionalShadowBounds(engine, direction, params, camera, sceneInfo);
+    auto const [Mv, znear, zfar, lsClippedShadowVolume, vertexCount, visibleShadows] =
+            computeDirectionalShadowBounds(engine, direction, params, camera, sceneInfo,
+                    useDepthClamp);
 
     if (UTILS_UNLIKELY(!visibleShadows)) {
         return {};
     }
 
+    // if the 2D bounds of the intersection is empty seen from the light, we have no shadow
+    Aabb const bounds = compute2DBounds(Mv, lsClippedShadowVolume.data(), vertexCount);
+    if (UTILS_UNLIKELY(!(bounds.min.x < bounds.max.x && bounds.min.y < bounds.max.y))) {
+        return {};
+    }
+
     /*
      * Compute the light's projection matrix
      * (directional/point lights, i.e. projection to use, including znear/zfar clip planes)
@@ -161,12 +166,17 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
     mat4f W, Wp, L;
     // We can't use LISPSM in stable mode
     const bool useLispsm = params.options.lispsm && !params.options.stable;
-    if (useLispsm) {
+
+    if (useLispsm ||
+            (!params.options.stable && !engine.debug.shadowmap.disable_light_frustum_align)) {
         // Orient the shadow map in the direction of the view vector by constructing a
         const float3 lsCameraFwd = Mv.upperLeft() * camera.getForwardVector();
         L = computeLightRotation(lsCameraFwd);
         LMp = L * Mp;
         LMpMv = LMp * Mv;
+    }
+
+    if (useLispsm) {
         W = applyLISPSM(Wp, camera, params,
                 LMp, Mv, LMpMv, lsClippedShadowVolume, vertexCount, direction);
     }
@@ -184,8 +194,7 @@ ShadowMap::ShaderParameters ShadowMap::updateDirectional(FEngine& engine,
     //   In LiPSM mode, we're using the warped space here.
     float4 f = computeFocusParams(LMpMv, WLMp,
             lsClippedShadowVolume, vertexCount,
-            camera, sceneInfo.csNearFar,
-            params.options.shadowFar, params.options.stable);
+            camera, params.options.shadowFar, params.options.stable);
 
     if (params.options.stable) {
         const auto lsRef = lightData.elementAt<FScene::SHADOW_REF>(index);
@@ -386,7 +395,8 @@ ShadowMap::DirectionalShadowBounds ShadowMap::computeDirectionalShadowBounds(
         float3 const direction,
         FLightManager::ShadowParams params,
         filament::CameraInfo const& camera,
-        SceneInfo const& sceneInfo) noexcept {
+        SceneInfo const& sceneInfo,
+        bool useDepthClamp) noexcept {
 
     // we use aligned_storage<> here to avoid the default initialization of std::array<>
     using Storage = std::aligned_storage<sizeof(FrustumBoxIntersection)>::type;
@@ -448,36 +458,49 @@ ShadowMap::DirectionalShadowBounds ShadowMap::computeDirectionalShadowBounds(
 
     // Compute the intersection of the view volume with the intersection of receivers and casters
     // in light space. This returns a set of points on the convex-hull of the intersection.
+    mat4f const projection = camera.cullingProjection *
+            (camera.view * FCamera::rigidTransformInverse(MvAtOrigin));
     size_t const vertexCount = intersectFrustumWithBox(lsClippedShadowVolume,
-            camera.cullingProjection * camera.view * FCamera::rigidTransformInverse(MvAtOrigin),
-            sceneInfo.csNearFar, lsLightFrustumBounds);
+            projection, lsLightFrustumBounds);
 
     if (UTILS_UNLIKELY(vertexCount < 4)) {
         return {};
     }
 
     /*
-    * Adjust the scene's zmax (i.e. Near plane) and zmin (i.e. Far plane) in light space.
-    * (near/far correspond to max/min because the light looks down the -z axis).
-    *  - The Near plane is set to the shadow casters max z (i.e. closest to the light)
-    *  - The Far plane is set to the closest of the farthest shadow casters and receivers
-    *    i.e.: shadow casters behind the last receivers can't cast any shadows
-    *
-    *  If "depth clamp" is supported, we can further tighten the near plane to the
-    *  shadow receiver.
-    *
-    *  Note: L has no influence here, since we're only interested in z values
-    *        (L is a rotation around z)
-    */
+     * Adjust the scene's zmax (i.e. Near plane) and zmin (i.e. Far plane) in light space.
+     * (near/far correspond to max/min because the light looks down the -z axis).
+     *
+     *   - For the Far plane, the light frustum is already set to the closest of receivers and
+     *     casters (i.e.: shadow casters behind the last receivers can't cast any shadows).
+     *     But it can be moved closer up to the farthest point in the camera frustum & light
+     *     frustum intersection.
+     *
+     *  - The Near plane is already set to the shadow casters max z (i.e. closest to the light)
+     *
+     *  If "depth clamp" is supported, we can further tighten the near plane to the
+     *  shadow receiver (i.e. to the closest point of camera frustum & light frustum intersection).
+     *
+     *  Note: L has no influence here, since we're only interested in z values
+     *        (L is a rotation around z)
+     */
 
+    float lsClippedShadowVolumeFarthest = std::numeric_limits<float>::max();
+    float lsClippedShadowVolumeNearest = std::numeric_limits<float>::lowest();
     for (size_t i = 0; i < vertexCount; ++i) {
         float3 const v = lsClippedShadowVolume[i];
-        // far: figure out the farthest shadow receivers
-        lsLightFrustumBounds.min.z = min(lsLightFrustumBounds.min.z, v.z);
-        if constexpr (USE_DEPTH_CLAMP) {
-            lsLightFrustumBounds.max.z = max(lsLightFrustumBounds.max.z, v.z);
-        }
+        lsClippedShadowVolumeFarthest = std::min(lsClippedShadowVolumeFarthest, v.z);
+        lsClippedShadowVolumeNearest = std::max(lsClippedShadowVolumeNearest, v.z);
     }
+
+    lsLightFrustumBounds.min.z =
+            std::max(lsLightFrustumBounds.min.z, lsClippedShadowVolumeFarthest);
+
+    if (useDepthClamp) {
+        lsLightFrustumBounds.max.z =
+                std::min(lsLightFrustumBounds.max.z, lsClippedShadowVolumeNearest);
+    }
+
     if (engine.debug.shadowmap.far_uses_shadowcasters) {
         // far: closest of the farthest shadow casters and receivers
         lsLightFrustumBounds.min.z =
@@ -611,7 +634,7 @@ math::float4 ShadowMap::computeFocusParams(
         mat4f const& LMpMv,
         mat4f const& WLMp,
         FrustumBoxIntersection const& lsShadowVolume, size_t vertexCount,
-        filament::CameraInfo const& camera, float2 const& csNearFar,
+        filament::CameraInfo const& camera,
         float shadowFar, bool stable) noexcept {
     float2 s, o;
     if (stable) {
@@ -626,7 +649,7 @@ math::float4 ShadowMap::computeFocusParams(
                 return wsViewVolumeBoundingSphere;
             } else {
                 mat4f const viewFromClip = inverse(camera.cullingProjection);
-                Corners const wsFrustumVertices = computeFrustumCorners(viewFromClip, csNearFar);
+                Corners const wsFrustumVertices = computeFrustumCorners(viewFromClip);
                 float4 const wsViewVolumeBoundingSphere =
                         computeBoundingSphere(wsFrustumVertices.vertices, 8);
                 return wsViewVolumeBoundingSphere;
@@ -794,26 +817,25 @@ Aabb ShadowMap::compute2DBounds(const mat4f& lightView,
 }
 
 ShadowMap::Corners ShadowMap::computeFrustumCorners(
-        mat4f const& projectionInverse,
-        float2 csNearFar) noexcept {
+        mat4f const& projectionInverse) noexcept {
 
     Corners out;
 
     // compute view frustum in world space (from its NDC)
     // matrix to convert: ndc -> camera -> world
-    float const near = csNearFar.x;
-    float const far  = csNearFar.y;
+    float const near = -1.0f;
+    float const far  =  1.0f;
 
     Corners const csViewFrustumCorners = {
             .vertices = {
                     { -1, -1, far  },
-                    { 1,  -1, far  },
-                    { -1, 1,  far  },
-                    { 1,  1,  far  },
+                    {  1, -1, far  },
+                    { -1,  1, far  },
+                    {  1,  1, far  },
                     { -1, -1, near },
-                    { 1,  -1, near },
-                    { -1, 1,  near },
-                    { 1,  1,  near },
+                    {  1, -1, near },
+                    { -1,  1, near },
+                    {  1,  1, near },
             }
     };
 
@@ -895,11 +917,11 @@ void ShadowMap::snapLightFrustum(float2& s, float2& o,
 
 size_t ShadowMap::intersectFrustumWithBox(
         FrustumBoxIntersection& UTILS_RESTRICT outVertices,
-        mat4f const& UTILS_RESTRICT projection, math::float2 const& UTILS_RESTRICT csNearFar,
+        mat4f const& UTILS_RESTRICT projection,
         Aabb const& UTILS_RESTRICT box)
 {
     Frustum const frustum{ projection };
-    Corners const frustumVertices{ computeFrustumCorners(inverse(projection), csNearFar) };
+    Corners const frustumVertices{ computeFrustumCorners(inverse(projection)) };
 
     constexpr const float EPSILON = 1.0f / 8192.0f; // ~0.012 mm
     size_t vertexCount = 0;
@@ -1203,9 +1225,8 @@ void ShadowMap::visitScene(const FScene& scene, uint32_t visibleLayers,
 }
 
 ShadowMap::SceneInfo::SceneInfo(
-        FScene const& scene, uint8_t visibleLayers, mat4f const& viewMatrix) noexcept
-        : vsNearFar(std::numeric_limits<float>::lowest(), std::numeric_limits<float>::max()),
-          visibleLayers(visibleLayers) {
+        FScene const& scene, uint8_t visibleLayers) noexcept
+        : visibleLayers(visibleLayers) {
 
     // the code below only works with affine transforms
     // Filament's API requires viewMatrix to be rigid (and thus affine).
@@ -1224,9 +1245,6 @@ ShadowMap::SceneInfo::SceneInfo(
             [&](Aabb receiver, Culler::result_type) {
                 wsShadowReceiversVolume.min = min(wsShadowReceiversVolume.min, receiver.min);
                 wsShadowReceiversVolume.max = max(wsShadowReceiversVolume.max, receiver.max);
-                auto r = Aabb::transform(viewMatrix.upperLeft(), viewMatrix[3].xyz, receiver);
-                vsNearFar.x = std::max(vsNearFar.x, r.max.z);
-                vsNearFar.y = std::min(vsNearFar.y, r.min.z);
             }
     );
 }

filament/src/ShadowMap.h

@@ -109,20 +109,13 @@ public:
     struct SceneInfo {
 
         SceneInfo() noexcept = default;
-        SceneInfo(FScene const& scene, uint8_t visibleLayers, math::mat4f const& viewMatrix) noexcept;
-
-        // scratch data: The near and far planes, in clip space, to use for this shadow map
-        math::float2 csNearFar = { -1.0f, 1.0f };
+        SceneInfo(FScene const& scene, uint8_t visibleLayers) noexcept;
 
         // scratch data: light's near/far expressed in light-space, calculated from the scene's
         // content assuming the light is at the origin.
         math::float2 lsCastersNearFar;
         math::float2 lsReceiversNearFar;
 
-        // Viewing camera's near/far expressed in view-space, calculated from the
-        // scene's content.
-        math::float2 vsNearFar;
-
         // World-space shadow-casters volume
         Aabb wsShadowCastersVolume;
 
@@ -154,7 +147,8 @@ public:
             const FScene::LightSoa& lightData, size_t index,
             filament::CameraInfo const& camera,
             ShadowMapInfo const& shadowMapInfo,
-            SceneInfo const& sceneInfo) noexcept;
+            SceneInfo const& sceneInfo,
+            bool useDepthClamp) noexcept;
 
     ShaderParameters updateSpot(FEngine& engine,
             const FScene::LightSoa& lightData, size_t index,
@@ -244,7 +238,8 @@ private:
             math::float3 direction,
             FLightManager::ShadowParams params,
             filament::CameraInfo const& camera,
-            SceneInfo const& sceneInfo) noexcept;
+            SceneInfo const& sceneInfo,
+            bool useDepthClamp) noexcept;
 
     static math::mat4f applyLISPSM(math::mat4f& Wp,
             filament::CameraInfo const& camera, FLightManager::ShadowParams const& params,
@@ -260,7 +255,7 @@ private:
             math::mat4f const& LMpMv,
             math::mat4f const& WLMp,
             FrustumBoxIntersection const& lsShadowVolume, size_t vertexCount,
-            filament::CameraInfo const& camera, math::float2 const& csNearFar,
+            filament::CameraInfo const& camera,
             float shadowFar, bool stable) noexcept;
 
     static inline void snapLightFrustum(math::float2& s, math::float2& o,
@@ -271,8 +266,7 @@ private:
             SceneInfo const& sceneInfo,
             bool stable, bool focusShadowCasters, bool farUsesShadowCasters) noexcept;
 
-    static Corners computeFrustumCorners(const math::mat4f& projectionInverse,
-            math::float2 csNearFar = { -1.0f, 1.0f }) noexcept;
+    static Corners computeFrustumCorners(const math::mat4f& projectionInverse) noexcept;
 
     static inline math::float2 computeNearFar(math::mat4f const& view,
             math::float3 const* wsVertices, size_t count) noexcept;
@@ -307,7 +301,7 @@ private:
 
     static size_t intersectFrustumWithBox(
             FrustumBoxIntersection& outVertices,
-            math::mat4f const& projection, math::float2 const& csNearFar,
+            math::mat4f const& projection,
             Aabb const& box);
 
     static math::mat4f warpFrustum(float n, float f) noexcept;

filament/src/ShadowMapManager.cpp

@@ -39,17 +39,20 @@
 #include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
 
-#include <utils/FixedCapacityVector.h>
-#include <utils/Range.h>
-#include <utils/Slice.h>
 #include <utils/compiler.h>
 #include <utils/debug.h>
+#include <utils/FixedCapacityVector.h>
+#include <utils/BitmaskEnum.h>
+#include <utils/Range.h>
+#include <utils/Slice.h>
 
 #include <math/half.h>
 #include <math/mat4.h>
 #include <math/vec4.h>
 #include <math/scalar.h>
 
+#include <algorithm>
+#include <array>
 #include <cmath>
 #include <limits>
 #include <new>
@@ -63,12 +66,15 @@ namespace filament {
 using namespace backend;
 using namespace math;
 
-ShadowMapManager::ShadowMapManager(FEngine& engine) {
+ShadowMapManager::ShadowMapManager(FEngine& engine)
+    : mIsDepthClampSupported(engine.getDriverApi().isDepthClampSupported()) {
     FDebugRegistry& debugRegistry = engine.getDebugRegistry();
     debugRegistry.registerProperty("d.shadowmap.visualize_cascades",
             &engine.debug.shadowmap.visualize_cascades);
-    debugRegistry.registerProperty("d.shadowmap.tightly_bound_scene",
-            &engine.debug.shadowmap.tightly_bound_scene);
+    debugRegistry.registerProperty("d.shadowmap.disable_light_frustum_align",
+            &engine.debug.shadowmap.disable_light_frustum_align);
+    debugRegistry.registerProperty("d.shadowmap.depth_clamp",
+            &engine.debug.shadowmap.depth_clamp);
 }
 
 ShadowMapManager::~ShadowMapManager() {
@@ -147,7 +153,7 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::update(
     calculateTextureRequirements(engine, view, lightData);
 
     // Compute scene-dependent values shared across all shadow maps
-    ShadowMap::SceneInfo const info{ *view.getScene(), view.getVisibleLayers(), cameraInfo.view };
+    ShadowMap::SceneInfo const info{ *view.getScene(), view.getVisibleLayers() };
 
     shadowTechnique |= updateCascadeShadowMaps(
             engine, view, cameraInfo, renderableData, lightData, info);
@@ -361,7 +367,20 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
 
                     // generate and sort the commands for rendering the shadow map
 
+                    RenderPass::RenderFlags renderPassFlags{};
+
+                    bool const canUseDepthClamp =
+                            shadowMap.getShadowType() == ShadowType::DIRECTIONAL &&
+                            !view.hasVSM() &&
+                            mIsDepthClampSupported &&
+                            engine.debug.shadowmap.depth_clamp;
+
+                    if (canUseDepthClamp) {
+                        renderPassFlags |= RenderPass::HAS_DEPTH_CLAMP;
+                    }
+
                     RenderPass const pass = passBuilder
+                            .renderFlags(RenderPass::HAS_DEPTH_CLAMP, renderPassFlags)
                             .camera(cameraInfo)
                             .visibilityMask(entry.visibilityMask)
                             .geometry(scene->getRenderableData(),
@@ -543,65 +562,9 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
     FLightManager::ShadowParams const& params = lcm.getShadowParams(directionalLight);
 
     // Adjust the camera's projection for the light's shadowFar
-    cameraInfo.zf = params.options.shadowFar > 0.0f ? params.options.shadowFar : cameraInfo.zf;
     if (UTILS_UNLIKELY(params.options.shadowFar > 0.0f)) {
         cameraInfo.zf = params.options.shadowFar;
-        float const n = cameraInfo.zn;
-        float const f = cameraInfo.zf;
-
-        /*
-         *  Updating a projection matrix near and far planes:
-         *
-         *  We assume that the near and far plane equations are of the form:
-         *           N = { 0, 0,  1,  n }
-         *           F = { 0, 0, -1, -f }
-         *
-         *  We also assume that the lower-left 2x2 of the projection is all 0:
-         *       P =   A   0   C   0
-         *             0   B   D   0
-         *             0   0   E   F
-         *             0   0   G   H
-         *
-         *  It result that we need to calculate E and F while leaving all other parameter unchanged.
-         *
-         *  We know that:
-         *       with N, F the near/far normalized plane equation parameters
-         *            sn, sf arbitrary scale factors (they don't affect the planes)
-         *            m is the transpose of projection (see Frustum.cpp)
-         *
-         *       sn * N == -m[3] - m[2]
-         *       sf * F == -m[3] + m[2]
-         *
-         *       sn * N + sf * F == -2 * m[3]
-         *       sn * N - sf * F == -2 * m[2]
-         *
-         *       sn * N.z + sf * F.z == -2 * m[3].z
-         *       sn * N.w + sf * F.w == -2 * m[3].w
-         *       sn * N.z - sf * F.z == -2 * m[2].z
-         *       sn * N.w - sf * F.w == -2 * m[2].w
-         *
-         *       sn * N.z + sf * F.z == -2 * p[2].w
-         *       sn * N.w + sf * F.w == -2 * p[3].w
-         *       sn * N.z - sf * F.z == -2 * p[2].z
-         *       sn * N.w - sf * F.w == -2 * p[3].z
-         *
-         *  We now need to solve for { p[2].z, p[3].z, sn, sf } :
-         *
-         *       sn == -2 * (p[2].w * F.w - p[3].w * F.z) / (N.z * F.w - N.w * F.z)
-         *       sf == -2 * (p[2].w * N.w - p[3].w * N.z) / (F.z * N.w - F.w * N.z)
-         *   p[2].z == (sf * F.z - sn * N.z) / 2
-         *   p[3].z == (sf * F.w - sn * N.w) / 2
-         */
-        auto& p = cameraInfo.cullingProjection;
-        float4 const N = { 0, 0,  1,  n };  // near plane equation
-        float4 const F = { 0, 0, -1, -f };  // far plane equation
-        // near plane equation scale factor
-        float const sn = -2.0f * (p[2].w * F.w - p[3].w * F.z) / (N.z * F.w - N.w * F.z);
-        // far plane equation scale factor
-        float const sf = -2.0f * (p[2].w * N.w - p[3].w * N.z) / (F.z * N.w - F.w * N.z);
-        // New values for the projection
-        p[2].z = (sf * F.z - sn * N.z) * 0.5f;
-        p[3].z = (sf * F.w - sn * N.w) * 0.5f;
+        updateNearFarPlanes(&cameraInfo.cullingProjection, cameraInfo.zn, cameraInfo.zf);
     }
 
     const ShadowMap::ShadowMapInfo shadowMapInfo{
@@ -631,8 +594,10 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
         // Compute scene-dependent values shared across all cascades
         ShadowMap::updateSceneInfoDirectional(MvAtOrigin, *scene, sceneInfo);
 
+        // we always do culling without depth clamp, because objects behind the camera
+        // must be rendered regardless
         shadowMap.updateDirectional(engine,
-                lightData, 0, cameraInfo, shadowMapInfo, sceneInfo);
+                lightData, 0, cameraInfo, shadowMapInfo, sceneInfo, false);
 
         hasVisibleShadows = shadowMap.hasVisibleShadows();
 
@@ -648,15 +613,7 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
     uint32_t cascadeHasVisibleShadows = 0;
 
     if (hasVisibleShadows) {
-        // Adjust the near and far planes to tightly bound the scene.
-        float vsNear = -cameraInfo.zn;
-        float vsFar = -cameraInfo.zf;
-        if (engine.debug.shadowmap.tightly_bound_scene && !params.options.stable) {
-            vsNear = std::min(vsNear, sceneInfo.vsNearFar.x);
-            vsFar = std::max(vsFar, sceneInfo.vsNearFar.y);
-        }
-
-        const size_t cascadeCount = cascadedShadowMaps.size();
+        uint32_t const cascadeCount = cascadedShadowMaps.size();
 
         // We divide the camera frustum into N cascades. This gives us N + 1 split positions.
         // The first split position is the near plane; the last split position is the far plane.
@@ -667,9 +624,8 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
         }
 
         const CascadeSplits splits({
-                .proj = cameraInfo.cullingProjection,
-                .near = vsNear,
-                .far = vsFar,
+                .near = -cameraInfo.zn,
+                .far = -cameraInfo.zf,
                 .cascadeCount = cascadeCount,
                 .splitPositions = splitPercentages
         });
@@ -679,10 +635,7 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
         static_assert(CONFIG_MAX_SHADOW_CASCADES <= 5,
                 "At most, a float4 can fit 4 split positions for 5 shadow cascades");
         float4 wsSplitPositionUniform{ -std::numeric_limits<float>::infinity() };
-        std::copy(splits.beginWs() + 1, splits.endWs(), &wsSplitPositionUniform[0]);
-
-        float csSplitPosition[CONFIG_MAX_SHADOW_CASCADES + 1];
-        std::copy(splits.beginCs(), splits.endCs(), csSplitPosition);
+        std::copy(splits.begin() + 1, splits.end(), &wsSplitPositionUniform[0]);
 
         mShadowMappingUniforms.cascadeSplits = wsSplitPositionUniform;
 
@@ -695,10 +648,20 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
             ShadowMap& shadowMap = cascadedShadowMaps[i];
             assert_invariant(shadowMap.getLightIndex() == 0);
 
-            sceneInfo.csNearFar = { csSplitPosition[i], csSplitPosition[i + 1] };
+            // update cameraInfo culling projection for the cascade
+            float const* nearFarPlanes = splits.begin();
+            cameraInfo.zn = -nearFarPlanes[i];
+            cameraInfo.zf = -nearFarPlanes[i + 1];
+            updateNearFarPlanes(&cameraInfo.cullingProjection, cameraInfo.zn, cameraInfo.zf);
+
+            bool const canUseDepthClamp =
+                    !view.hasVSM() &&
+                    mIsDepthClampSupported &&
+                    engine.debug.shadowmap.depth_clamp;
 
             auto shaderParameters = shadowMap.updateDirectional(engine,
-                    lightData, 0, cameraInfo, shadowMapInfo, sceneInfo);
+                    lightData, 0, cameraInfo, shadowMapInfo, sceneInfo,
+                    canUseDepthClamp);
 
             if (shadowMap.hasVisibleShadows()) {
                 const size_t shadowIndex = shadowMap.getShadowIndex();
@@ -1069,8 +1032,78 @@ ShadowMapManager::CascadeSplits::CascadeSplits(Params const& params) noexcept
         : mSplitCount(params.cascadeCount + 1) {
     for (size_t s = 0; s < mSplitCount; s++) {
         mSplitsWs[s] = params.near + (params.far - params.near) * params.splitPositions[s];
-        mSplitsCs[s] = mat4f::project(params.proj, float3(0.0f, 0.0f, mSplitsWs[s])).z;
     }
 }
 
+void ShadowMapManager::updateNearFarPlanes(mat4f* projection,
+        float nearDistance, float farDistance) noexcept {
+    float const n = nearDistance;
+    float const f = farDistance;
+
+    /*
+     *  Updating a projection matrix near and far planes:
+     *
+     *  We assume that the near and far plane equations are of the form:
+     *           N = { 0, 0,  1,  n }
+     *           F = { 0, 0, -1, -f }
+     *
+     *  We also assume that the lower-left 2x2 of the projection is all 0:
+     *       P =   A   0   C   0
+     *             0   B   D   0
+     *             0   0   E   F
+     *             0   0   G   H
+     *
+     *  It result that we need to calculate E and F while leaving all other parameter unchanged.
+     *
+     *  We know that:
+     *       with N, F the near/far normalized plane equation parameters
+     *            sn, sf arbitrary scale factors (they don't affect the planes)
+     *            m is the transpose of projection (see Frustum.cpp)
+     *
+     *       sn * N == -m[3] - m[2]
+     *       sf * F == -m[3] + m[2]
+     *
+     *       sn * N + sf * F == -2 * m[3]
+     *       sn * N - sf * F == -2 * m[2]
+     *
+     *       sn * N.z + sf * F.z == -2 * m[3].z
+     *       sn * N.w + sf * F.w == -2 * m[3].w
+     *       sn * N.z - sf * F.z == -2 * m[2].z
+     *       sn * N.w - sf * F.w == -2 * m[2].w
+     *
+     *       sn * N.z + sf * F.z == -2 * p[2].w
+     *       sn * N.w + sf * F.w == -2 * p[3].w
+     *       sn * N.z - sf * F.z == -2 * p[2].z
+     *       sn * N.w - sf * F.w == -2 * p[3].z
+     *
+     *  We now need to solve for { p[2].z, p[3].z, sn, sf } :
+     *
+     *       sn == -2 * (p[2].w * F.w - p[3].w * F.z) / (N.z * F.w - N.w * F.z)
+     *       sf == -2 * (p[2].w * N.w - p[3].w * N.z) / (F.z * N.w - F.w * N.z)
+     *   p[2].z == (sf * F.z - sn * N.z) / 2
+     *   p[3].z == (sf * F.w - sn * N.w) / 2
+     */
+    auto& p = *projection;
+    float4 const N = { 0, 0,  1,  n };  // near plane equation
+    float4 const F = { 0, 0, -1, -f };  // far plane equation
+    // near plane equation scale factor
+    float const sn = -2.0f * (p[2].w * F.w - p[3].w * F.z) / (N.z * F.w - N.w * F.z);
+    // far plane equation scale factor
+    float const sf = -2.0f * (p[2].w * N.w - p[3].w * N.z) / (F.z * N.w - F.w * N.z);
+    // New values for the projection
+    p[2].z = (sf * F.z - sn * N.z) * 0.5f;
+    p[3].z = (sf * F.w - sn * N.w) * 0.5f;
+}
+
+utils::FixedCapacityVector<Camera const*>
+ShadowMapManager::getDirectionalShadowCameras() const noexcept {
+    if (!mInitialized) return {};
+    auto const csm = getCascadedShadowMap();
+    auto result = utils::FixedCapacityVector<Camera const*>::with_capacity(csm.size());
+    for (ShadowMap const& sm : csm) {
+        result.push_back(sm.hasVisibleShadows() ? sm.getDebugCamera() : nullptr);
+    }
+    return result;
+}
+
 } // namespace filament

filament/src/ShadowMapManager.h

@@ -40,6 +40,7 @@
 
 #include <utils/BitmaskEnum.h>
 #include <utils/compiler.h>
+#include <utils/FixedCapacityVector.h>
 #include <utils/debug.h>
 #include <utils/Range.h>
 #include <utils/Slice.h>
@@ -58,6 +59,7 @@
 
 namespace filament {
 
+class Camera;
 class FCamera;
 class FView;
 class FrameGraph;
@@ -138,16 +140,16 @@ public:
     bool hasSpotShadows() const { return !mSpotShadowMapCount; }
 
     // for debugging only
-    FCamera const* getDirectionalShadowCamera() const noexcept {
-        if (!mInitialized) return nullptr;
-        return getShadowMap(0).getDebugCamera();
-    }
+    utils::FixedCapacityVector<Camera const*> getDirectionalShadowCameras() const noexcept;
 
 private:
     explicit ShadowMapManager(FEngine& engine);
 
     void terminate(FEngine& engine);
 
+    static void updateNearFarPlanes(math::mat4f* projection,
+            float nearDistance, float farDistance) noexcept;
+
     ShadowMapManager::ShadowTechnique updateCascadeShadowMaps(FEngine& engine,
             FView& view, CameraInfo cameraInfo, FScene::RenderableSoa& renderableData,
             FScene::LightSoa const& lightData, ShadowMap::SceneInfo sceneInfo) noexcept;
@@ -186,27 +188,21 @@ private:
         constexpr static size_t SPLIT_COUNT = CONFIG_MAX_SHADOW_CASCADES + 1;
 
         struct Params {
-            math::mat4f proj;
             float near = 0.0f;
             float far = 0.0f;
-            size_t cascadeCount = 1;
+            uint32_t cascadeCount = 1;
             std::array<float, SPLIT_COUNT> splitPositions = { 0.0f };
         };
 
         explicit CascadeSplits(Params const& params) noexcept;
 
         // Split positions in world-space.
-        const float* beginWs() const { return mSplitsWs; }
-        const float* endWs() const { return mSplitsWs + mSplitCount; }
-
-        // Split positions in clip-space.
-        const float* beginCs() const { return mSplitsCs; }
-        const float* endCs() const { return mSplitsCs + mSplitCount; }
+        const float* begin() const { return mSplitsWs; }
+        const float* end() const { return mSplitsWs + mSplitCount; }
 
     private:
         float mSplitsWs[SPLIT_COUNT];
-        float mSplitsCs[SPLIT_COUNT];
-        size_t mSplitCount;
+        uint32_t mSplitCount;
     };
 
     // Atlas requirements, updated in ShadowMapManager::update(),
@@ -236,6 +232,7 @@ private:
     ShadowMapCacheContainer mShadowMapCache;
     uint32_t mDirectionalShadowMapCount = 0;
     uint32_t mSpotShadowMapCount = 0;
+    bool const mIsDepthClampSupported;
     bool mInitialized = false;
 
     ShadowMap& getShadowMap(size_t index) noexcept {
@@ -248,10 +245,14 @@ private:
     }
 
     utils::Slice<ShadowMap> getCascadedShadowMap() noexcept {
-        ShadowMap* const p = &getShadowMap(0);
+        ShadowMap const* const p = &getShadowMap(0);
         return { p, mDirectionalShadowMapCount };
     }
 
+    utils::Slice<ShadowMap> getCascadedShadowMap() const noexcept {
+        return const_cast<ShadowMapManager*>(this)->getCascadedShadowMap();
+    }
+
     utils::Slice<ShadowMap> getSpotShadowMaps() noexcept {
         ShadowMap* const p = &getShadowMap(CONFIG_MAX_SHADOW_CASCADES);
         return { p, mSpotShadowMapCount };

filament/src/View.cpp

@@ -73,8 +73,8 @@ const char* View::getName() const noexcept {
     return downcast(this)->getName();
 }
 
-Camera const* View::getDirectionalShadowCamera() const noexcept {
-    return downcast(this)->getDirectionalShadowCamera();
+utils::FixedCapacityVector<Camera const*> View::getDirectionalShadowCameras() const noexcept {
+    return downcast(this)->getDirectionalShadowCameras();
 }
 
 void View::setShadowingEnabled(bool enabled) noexcept {

filament/src/components/RenderableManager.cpp

@@ -588,6 +588,9 @@ void FRenderableManager::create(
             // full size of the UBO.
             instances.handle = driver.createBufferObject(sizeof(PerRenderableUib),
                     BufferObjectBinding::UNIFORM, backend::BufferUsage::DYNAMIC);
+            if (auto name = instances.buffer->getName(); !name.empty()) {
+                driver.setDebugTag(instances.handle.getId(), std::move(name));
+            }
         }
 
         const uint32_t boneCount = builder->mSkinningBoneCount;

filament/src/details/BufferObject.cpp

@@ -20,6 +20,8 @@
 
 #include "FilamentAPI-impl.h"
 
+#include <utils/CString.h>
+
 namespace filament {
 
 struct BufferObject::BuilderDetails {
@@ -56,6 +58,9 @@ FBufferObject::FBufferObject(FEngine& engine, const BufferObject::Builder& build
     FEngine::DriverApi& driver = engine.getDriverApi();
     mHandle = driver.createBufferObject(builder->mByteCount, builder->mBindingType,
             backend::BufferUsage::STATIC);
+    if (auto name = builder.getName(); !name.empty()) {
+        driver.setDebugTag(mHandle.getId(), std::move(name));
+    }
 }
 
 void FBufferObject::terminate(FEngine& engine) {

filament/src/details/DebugRegistry.cpp

@@ -28,12 +28,6 @@
 #include <string_view>
 #include <utility>
 
-#ifndef NDEBUG
-#   define DEBUG_PROPERTIES_WRITABLE true
-#else
-#   define DEBUG_PROPERTIES_WRITABLE false
-#endif
-
 using namespace filament::math;
 using namespace utils;
 
@@ -79,17 +73,15 @@ bool FDebugRegistry::hasProperty(const char* name) const noexcept {
 
 template<typename T>
 bool FDebugRegistry::setProperty(const char* name, T v) noexcept {
-    if constexpr (DEBUG_PROPERTIES_WRITABLE) {
-        auto info = getPropertyInfo(name);
-        T* const addr = static_cast<T*>(info.first);
-        if (addr) {
-            auto old = *addr;
-            *addr = v;
-            if (info.second && old != v) {
-                info.second();
-            }
-            return true;
+    auto info = getPropertyInfo(name);
+    T* const addr = static_cast<T*>(info.first);
+    if (addr) {
+        auto old = *addr;
+        *addr = v;
+        if (info.second && old != v) {
+            info.second();
         }
+        return true;
     }
     return false;
 }
@@ -118,19 +110,32 @@ template bool FDebugRegistry::getProperty<float2>(const char* name, float2* v) c
 template bool FDebugRegistry::getProperty<float3>(const char* name, float3* v) const noexcept;
 template bool FDebugRegistry::getProperty<float4>(const char* name, float4* v) const noexcept;
 
-void FDebugRegistry::registerDataSource(std::string_view name,
+bool FDebugRegistry::registerDataSource(std::string_view name,
         void const* data, size_t count) noexcept {
     auto& dataSourceMap = mDataSourceMap;
-    if (dataSourceMap.find(name) == dataSourceMap.end()) {
+    bool const found = dataSourceMap.find(name) == dataSourceMap.end();
+    if (found) {
         dataSourceMap[name] = { data, count };
     }
+    return found;
 }
 
-void FDebugRegistry::registerDataSource(std::string_view name,
+bool FDebugRegistry::registerDataSource(std::string_view name,
         utils::Invocable<DataSource()>&& creator) noexcept {
-    mDataSourceCreatorMap[name] = std::move(creator);
+    auto& dataSourceCreatorMap = mDataSourceCreatorMap;
+    bool const found = dataSourceCreatorMap.find(name) == dataSourceCreatorMap.end();
+    if (found) {
+        dataSourceCreatorMap[name] = std::move(creator);
+    }
+    return found;
 }
 
+void FDebugRegistry::unregisterDataSource(std::string_view name) noexcept {
+    mDataSourceCreatorMap.erase(name);
+    mDataSourceMap.erase(name);
+}
+
+
 DebugRegistry::DataSource FDebugRegistry::getDataSource(const char* name) const noexcept {
     std::string_view const key{ name };
     auto& dataSourceMap = mDataSourceMap;

filament/src/details/DebugRegistry.h

@@ -101,12 +101,14 @@ public:
     }
 
     // registers a DataSource directly
-    void registerDataSource(std::string_view name, void const* data, size_t count) noexcept;
+    bool registerDataSource(std::string_view name, void const* data, size_t count) noexcept;
 
     // registers a DataSource lazily
-    void registerDataSource(std::string_view name,
+    bool registerDataSource(std::string_view name,
             utils::Invocable<DataSource()>&& creator) noexcept;
 
+    void unregisterDataSource(std::string_view name) noexcept;
+
 #if !defined(_MSC_VER)
 private:
 #endif

filament/src/details/Engine.h

@@ -590,7 +590,8 @@ private:
     Config mConfig;
 
 public:
-    // these are the debug properties used by FDebug. They're accessed directly by modules who need them.
+    // These are the debug properties used by FDebug.
+    // They're accessed directly by modules who need them.
     struct {
         struct {
             bool debug_directional_shadowmap = false;
@@ -598,7 +599,8 @@ public:
             bool far_uses_shadowcasters = true;
             bool focus_shadowcasters = true;
             bool visualize_cascades = false;
-            bool tightly_bound_scene = true;
+            bool disable_light_frustum_align = false;
+            bool depth_clamp = true;
             float dzn = -1.0f;
             float dzf =  1.0f;
             float display_shadow_texture_scale = 0.25f;

filament/src/details/IndexBuffer.cpp

@@ -20,6 +20,8 @@
 
 #include "FilamentAPI-impl.h"
 
+#include <utils/CString.h>
+
 namespace filament {
 
 struct IndexBuffer::BuilderDetails {
@@ -58,6 +60,9 @@ FIndexBuffer::FIndexBuffer(FEngine& engine, const IndexBuffer::Builder& builder)
             (backend::ElementType)builder->mIndexType,
             uint32_t(builder->mIndexCount),
             backend::BufferUsage::STATIC);
+    if (auto name = builder.getName(); !name.empty()) {
+        driver.setDebugTag(mHandle.getId(), std::move(name));
+    }
 }
 
 void FIndexBuffer::terminate(FEngine& engine) {

filament/src/details/InstanceBuffer.cpp

@@ -61,7 +61,8 @@ InstanceBuffer* InstanceBuffer::Builder::build(Engine& engine) {
 
 // ------------------------------------------------------------------------------------------------
 
-FInstanceBuffer::FInstanceBuffer(FEngine& engine, const Builder& builder) {
+FInstanceBuffer::FInstanceBuffer(FEngine& engine, const Builder& builder)
+    : mName(builder.getName()) {
     mInstanceCount = builder->mInstanceCount;
 
     mLocalTransforms.reserve(mInstanceCount);

filament/src/details/InstanceBuffer.h

@@ -25,6 +25,7 @@
 
 #include <math/mat4.h>
 
+#include <utils/CString.h>
 #include <utils/FixedCapacityVector.h>
 
 namespace filament {
@@ -46,10 +47,13 @@ public:
     void prepare(FEngine& engine, math::mat4f rootTransform, const PerRenderableData& ubo,
             backend::Handle<backend::HwBufferObject> handle);
 
+    utils::CString const& getName() const noexcept { return mName; }
+
 private:
     friend class RenderableManager;
 
     utils::FixedCapacityVector<math::mat4f> mLocalTransforms;
+    utils::CString mName;
     size_t mInstanceCount;
 };
 

filament/src/details/Material.cpp

@@ -192,19 +192,27 @@ Material* Material::Builder::build(Engine& engine) {
         return nullptr;
     }
 
+    // Print a warning if the material's stereo type doesn't align with the engine's setting.
     MaterialDomain materialDomain;
+    UserVariantFilterMask variantFilterMask;
     materialParser->getMaterialDomain(&materialDomain);
-    if (materialDomain == MaterialDomain::SURFACE) {
+    materialParser->getMaterialVariantFilterMask(&variantFilterMask);
+    bool const hasStereoVariants = !(variantFilterMask & UserVariantFilterMask(UserVariantFilterBit::STE));
+    if (materialDomain == MaterialDomain::SURFACE && hasStereoVariants) {
         StereoscopicType const engineStereoscopicType = engine.getConfig().stereoscopicType;
-        StereoscopicType materialStereoscopicType = StereoscopicType::NONE;
-        materialParser->getStereoscopicType(&materialStereoscopicType);
-        if (materialStereoscopicType != engineStereoscopicType) {
-            CString name;
-            materialParser->getName(&name);
-            slog.w << "The stereoscopic type in the compiled material '" << name.c_str_safe()
-                    << "' is " << (int)materialStereoscopicType
-                    << ", which is not compatiable with the engine's setting "
-                    << (int)engineStereoscopicType << "." << io::endl;
+        // Default materials are always compiled with either 'instanced' or 'multiview'.
+        // So, we only verify compatibility if the engine is set up for stereo.
+        if (engineStereoscopicType != StereoscopicType::NONE) {
+            StereoscopicType materialStereoscopicType = StereoscopicType::NONE;
+            materialParser->getStereoscopicType(&materialStereoscopicType);
+            if (materialStereoscopicType != engineStereoscopicType) {
+                CString name;
+                materialParser->getName(&name);
+                slog.w << "The stereoscopic type in the compiled material '" << name.c_str_safe()
+                        << "' is " << (int)materialStereoscopicType
+                        << ", which is not compatiable with the engine's setting "
+                        << (int)engineStereoscopicType << "." << io::endl;
+            }
         }
     }
 
@@ -610,6 +618,7 @@ Program FMaterial::getProgramWithVariants(
 
 void FMaterial::createAndCacheProgram(Program&& p, Variant variant) const noexcept {
     auto program = mEngine.getDriverApi().createProgram(std::move(p));
+    mEngine.getDriverApi().setDebugTag(program.getId(), mName);
     assert_invariant(program);
     mCachedPrograms[variant.key] = program;
 }

filament/src/details/MaterialInstance.cpp

@@ -51,6 +51,7 @@ FMaterialInstance::FMaterialInstance(FEngine& engine, FMaterial const* material)
         mUniforms = UniformBuffer(material->getUniformInterfaceBlock().getSize());
         mUbHandle = driver.createBufferObject(mUniforms.getSize(),
                 BufferObjectBinding::UNIFORM, backend::BufferUsage::STATIC);
+        driver.setDebugTag(mUbHandle.getId(), material->getName());
     }
 
     if (!material->getSamplerInterfaceBlock().isEmpty()) {
@@ -116,6 +117,7 @@ FMaterialInstance::FMaterialInstance(FEngine& engine,
         mUniforms.setUniforms(other->getUniformBuffer());
         mUbHandle = driver.createBufferObject(mUniforms.getSize(),
                 BufferObjectBinding::UNIFORM, backend::BufferUsage::DYNAMIC);
+        driver.setDebugTag(mUbHandle.getId(), material->getName());
     }
 
     if (!material->getSamplerInterfaceBlock().isEmpty()) {

filament/src/details/MorphTargetBuffer.cpp

@@ -25,6 +25,8 @@
 #include <math/mat4.h>
 #include <math/norm.h>
 
+#include <utils/CString.h>
+
 namespace filament {
 
 using namespace backend;
@@ -124,6 +126,11 @@ FMorphTargetBuffer::FMorphTargetBuffer(FEngine& engine, const Builder& builder)
             mCount,
             TextureUsage::DEFAULT);
 
+    if (auto name = builder.getName(); !name.empty()) {
+        driver.setDebugTag(mPbHandle.getId(), name);
+        driver.setDebugTag(mTbHandle.getId(), std::move(name));
+    }
+
     // create and update sampler group
     mSbHandle = driver.createSamplerGroup(PerRenderPrimitiveMorphingSib::SAMPLER_COUNT,
             utils::FixedSizeString<32>("Morph target samplers"));

filament/src/details/Renderer.cpp

@@ -651,20 +651,25 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
 
     const bool isProtectedContent =  mSwapChain && mSwapChain->isProtected();
 
+    // Conditions to meet to be able to use the sub-pass rendering path. This is regardless of
+    // whether the backend supports subpasses (or if they are disabled in the debugRegistry).
+    const bool isSubpassPossible =
+             msaaSampleCount <= 1 &&
+             hasColorGrading &&
+             !bloomOptions.enabled && !dofOptions.enabled && !taaOptions.enabled;
+
     // asSubpass is disabled with TAA (although it's supported) because performance was degraded
     // on qualcomm hardware -- we might need a backend dependent toggle at some point
     const PostProcessManager::ColorGradingConfig colorGradingConfig{
             .asSubpass =
-                    hasColorGrading &&
-                    msaaSampleCount <= 1 &&
-                    !bloomOptions.enabled && !dofOptions.enabled && !taaOptions.enabled &&
+                    isSubpassPossible &&
                     driver.isFrameBufferFetchSupported() &&
                     !engine.debug.renderer.disable_subpasses,
             .customResolve =
-                    msaaOptions.customResolve &&
                     msaaSampleCount > 1 &&
-                    hasColorGrading &&
                     driver.isFrameBufferFetchMultiSampleSupported() &&
+                    msaaOptions.customResolve &&
+                    hasColorGrading &&
                     !engine.debug.renderer.disable_subpasses,
             .translucent = needsAlphaChannel,
             .fxaa = hasFXAA,
@@ -673,6 +678,9 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
                     TextureFormat::RGBA8 : getLdrFormat(needsAlphaChannel)
     };
 
+    // by construction (msaaSampleCount) both asSubpass and customResolve can't be true
+    assert_invariant(colorGradingConfig.asSubpass + colorGradingConfig.customResolve < 2);
+
     // whether we're scaled at all
      bool scaled = any(notEqual(scale, float2(1.0f)));
 
@@ -695,13 +703,12 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
 
     CameraInfo cameraInfo = view.computeCameraInfo(engine);
 
-    // when colorgrading-as-subpass is active, we know that many other effects are disabled
-    // such as dof, bloom. Moreover, if fxaa and scaling are not enabled, we're essentially in
-    // a very fast rendering path -- in this case, we would need an extra blit to "resolve" the
-    // buffer padding (because there are no other pass that can do it as a side effect).
-    // In this case, it is better to skip the padding, which won't be helping much.
-    const bool noBufferPadding = (colorGradingConfig.asSubpass && !hasFXAA && !scaled)
-            || engine.debug.renderer.disable_buffer_padding;
+    // If fxaa and scaling are not enabled, we're essentially in a very fast rendering path -- in
+    // this case, we would need an extra blit to "resolve" the buffer padding (because there are no
+    // other pass that can do it as a side effect). In this case, it is better to skip the padding,
+    // which won't be helping much.
+    const bool noBufferPadding = (isSubpassPossible &&
+            !hasFXAA && !scaled) || engine.debug.renderer.disable_buffer_padding;
 
     // guardBand must be a multiple of 16 to guarantee the same exact rendering up to 4 mip levels.
     float const guardBand = guardBandOptions.enabled ? 16.0f : 0.0f;
@@ -816,14 +823,14 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
         blackboard["shadows"] = shadows;
     }
 
-    // When we don't have a custom RenderTarget, currentRenderTarget below is nullptr and is
+    // When we don't have a custom RenderTarget, customRenderTarget below is nullptr and is
     // recorded in the list of targets already rendered into -- this ensures that
     // initializeClearFlags() is called only once for the default RenderTarget.
     auto& previousRenderTargets = mPreviousRenderTargets;
-    FRenderTarget* const currentRenderTarget = downcast(view.getRenderTarget());
+    FRenderTarget* const customRenderTarget = downcast(view.getRenderTarget());
     if (UTILS_LIKELY(
-            previousRenderTargets.find(currentRenderTarget) == previousRenderTargets.end())) {
-        previousRenderTargets.insert(currentRenderTarget);
+            previousRenderTargets.find(customRenderTarget) == previousRenderTargets.end())) {
+        previousRenderTargets.insert(customRenderTarget);
         initializeClearFlags();
     }
 
@@ -840,10 +847,10 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
     const TargetBufferFlags keepOverrideStartFlags = TargetBufferFlags::ALL & ~discardStartFlags;
     TargetBufferFlags keepOverrideEndFlags = TargetBufferFlags::NONE;
 
-    if (currentRenderTarget) {
+    if (customRenderTarget) {
         // For custom RenderTarget, we look at each attachment flag and if they have their
         // SAMPLEABLE usage bit set, we assume they must not be discarded after the render pass.
-        keepOverrideEndFlags |= currentRenderTarget->getSampleableAttachmentsMask();
+        keepOverrideEndFlags |= customRenderTarget->getSampleableAttachmentsMask();
     }
 
     // Renderer's ClearOptions apply once at the beginning of the frame (not for each View),
@@ -952,7 +959,6 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
             .scale = aoOptions.resolution,
             .picking = view.hasPicking()
     });
-    blackboard["structure"] = structure;
     const auto picking = picking_;
 
 
@@ -1000,7 +1006,6 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
             ssReflectionsOptions.enabled ? TextureFormat::RGBA16F : TextureFormat::R11F_G11F_B10F,
             view.getCameraUser().getFieldOfView(Camera::Fov::VERTICAL), config.scale);
     config.ssrLodOffset = ssrConfig.lodOffset;
-    blackboard["ssr"] = ssrConfig.ssr;
 
     // --------------------------------------------------------------------------------------------
     // screen-space reflections pass
@@ -1014,6 +1019,10 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
                 { .width = svp.width, .height = svp.height });
 
         if (UTILS_LIKELY(reflections)) {
+            fg.addTrivialSideEffectPass("SSR Cleanup", [&view](DriverApi& driver) {
+                view.getPerViewUniforms().prepareStructure({});
+                view.commitUniforms(driver);
+            });
             // generate the mipchain
             PostProcessManager::generateMipmapSSR(ppm, fg,
                     reflections, ssrConfig.reflection, false, ssrConfig);
@@ -1104,24 +1113,45 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
     );
 
     // the color pass itself + color-grading as subpass if needed
-    auto colorPassOutput = RendererUtils::colorPass(fg, "Color Pass", mEngine, view,
+    auto colorPassOutput = RendererUtils::colorPass(fg, "Color Pass", mEngine, view, {
+                .shadows = blackboard.get<FrameGraphTexture>("shadows"),
+                .ssao = blackboard.get<FrameGraphTexture>("ssao"),
+                .ssr = ssrConfig.ssr,
+                .structure = structure
+            },
             colorBufferDesc, config, colorGradingConfigForColor, pass.getExecutor());
 
     if (view.isScreenSpaceRefractionEnabled() && !pass.empty()) {
-        // this cancels the colorPass() call above if refraction is active.
-        // the color pass + refraction + color-grading as subpass if needed
-        const auto [output, enabled] = RendererUtils::refractionPass(fg, mEngine, view,
+        // This cancels the colorPass() call above if refraction is active.
+        // The color pass + refraction + color-grading as subpass if needed
+        auto const output = RendererUtils::refractionPass(fg, mEngine, view, {
+                        .shadows = blackboard.get<FrameGraphTexture>("shadows"),
+                        .ssao = blackboard.get<FrameGraphTexture>("ssao"),
+                        .ssr = ssrConfig.ssr,
+                        .structure = structure
+                },
                 config, ssrConfig, colorGradingConfigForColor, pass);
-        colorPassOutput = output;
-        hasScreenSpaceRefraction = enabled;
+
+        hasScreenSpaceRefraction = output.has_value();
+        if (hasScreenSpaceRefraction) {
+            colorPassOutput = output.value();
+        }
     }
 
+    fg.addTrivialSideEffectPass("Finish Color Passes", [&view](DriverApi& driver) {
+        // Unbind SSAO sampler, b/c the FrameGraph will delete the texture at the end of the pass.
+        view.cleanupRenderPasses();
+        view.commitUniforms(driver);
+    });
+
     if (colorGradingConfig.customResolve) {
+        assert_invariant(fg.getDescriptor(colorPassOutput.linearColor).samples <= 1);
         // TODO: we have to "uncompress" (i.e. detonemap) the color buffer here because it's used
         //       by many other passes (Bloom, TAA, DoF, etc...). We could make this more
         //       efficient by using ARM_shader_framebuffer_fetch. We use a load/store (i.e.
         //       subpass) here because it's more convenient.
-        colorPassOutput = ppm.customResolveUncompressPass(fg, colorPassOutput);
+        colorPassOutput.linearColor =
+                ppm.customResolveUncompressPass(fg, colorPassOutput.linearColor);
     }
 
     // export the color buffer if screen-space reflections are enabled
@@ -1137,7 +1167,9 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
                     // The "output" of this pass is going to be used during the next frame as
                     // an "import".
                     builder.sideEffect();
-                    data.history = builder.sample(colorPassOutput); // FIXME: an access must be declared for detach(), why?
+
+                    // we can't use colorPassOutput here because it could be tonemapped
+                    data.history = builder.sample(colorPassOutput.linearColor); // FIXME: an access must be declared for detach(), why?
                 }, [&view, projection](FrameGraphResources const& resources, auto const& data,
                         backend::DriverApi&) {
                     auto& history = view.getFrameHistory();
@@ -1147,19 +1179,20 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
                 });
     }
 
-    FrameGraphId<FrameGraphTexture> input = colorPassOutput;
-    fg.addTrivialSideEffectPass("Finish Color Passes", [&view](DriverApi& driver) {
-        // Unbind SSAO sampler, b/c the FrameGraph will delete the texture at the end of the pass.
-        view.cleanupRenderPasses();
-        view.commitUniforms(driver);
-    });
+    // this is the output of the color pass / input to post processing,
+    // this is only used later for comparing it with the output after post-processing
+    FrameGraphId<FrameGraphTexture> const postProcessInput = colorGradingConfig.asSubpass ?
+                                                             colorPassOutput.tonemappedColor :
+                                                             colorPassOutput.linearColor;
+
+    // input can change below
+    FrameGraphId<FrameGraphTexture> input = postProcessInput;
 
     // Resolve depth -- which might be needed because of TAA or DoF. This pass will be culled
     // if the depth is not used below or if the depth is not MS (e.g. it could have been
     // auto-resolved).
     // In practice, this is used on Vulkan and older Metal devices.
-    auto depth = blackboard.get<FrameGraphTexture>("depth");
-    depth = ppm.resolve(fg, "Resolved Depth Buffer", depth, { .levels = 1 });
+    auto depth = ppm.resolve(fg, "Resolved Depth Buffer", colorPassOutput.depth, { .levels = 1 });
 
     // Debug: CSM visualisation
     if (UTILS_UNLIKELY(engine.debug.shadowmap.visualize_cascades &&
@@ -1275,7 +1308,7 @@ void FRenderer::renderJob(RootArenaScope& rootArenaScope, FView& view) {
     // The intermediate buffer is accomplished with a "fake" opaqueBlit (i.e. blit) operation.
 
     const bool outputIsSwapChain =
-            (input == colorPassOutput) && (viewRenderTarget == mRenderTargetHandle);
+            (input == postProcessInput) && (viewRenderTarget == mRenderTargetHandle);
     if (mightNeedFinalBlit) {
         if (blendModeTranslucent ||
             xvp != svp ||

filament/src/details/SkinningBuffer.cpp

@@ -27,6 +27,8 @@
 #include <math/half.h>
 #include <math/mat4.h>
 
+#include <utils/CString.h>
+
 #include <cstring>
 
 namespace filament {
@@ -80,6 +82,11 @@ FSkinningBuffer::FSkinningBuffer(FEngine& engine, const Builder& builder)
             BufferObjectBinding::UNIFORM,
             BufferUsage::DYNAMIC);
 
+    if (auto name = builder.getName(); !name.empty()) {
+        // TODO: We should also tag the texture created inside createIndicesAndWeightsHandle.
+        driver.setDebugTag(mHandle.getId(), std::move(name));
+    }
+
     if (builder->mInitialize) {
         // initialize the bones to identity (before rounding up)
         auto* out = driver.allocatePod<PerRenderableBoneUib::BoneData>(mBoneCount);

filament/src/details/Stream.cpp

@@ -23,10 +23,10 @@
 
 #include <backend/PixelBufferDescriptor.h>
 
+#include <utils/CString.h>
 #include <utils/Panic.h>
 #include <filament/Stream.h>
 
-
 namespace filament {
 
 using namespace backend;
@@ -80,6 +80,10 @@ FStream::FStream(FEngine& engine, const Builder& builder) noexcept
     } else {
         mStreamHandle = engine.getDriverApi().createStreamAcquired();
     }
+
+    if (auto name = builder.getName(); !name.empty()) {
+        engine.getDriverApi().setDebugTag(mStreamHandle.getId(), std::move(name));
+    }
 }
 
 void FStream::terminate(FEngine& engine) noexcept {

filament/src/details/Texture.cpp

@@ -243,6 +243,11 @@ FTexture::FTexture(FEngine& engine, const Builder& builder) {
         mHandle = driver.importTexture(builder->mImportedId,
                 mTarget, mLevelCount, mFormat, mSampleCount, mWidth, mHeight, mDepth, mUsage);
     }
+    if (auto name = builder.getName(); !name.empty()) {
+        driver.setDebugTag(mHandle.getId(), std::move(name));
+    } else {
+        driver.setDebugTag(mHandle.getId(), CString{"FTexture"});
+    }
 }
 
 // frees driver resources, object becomes invalid

filament/src/details/VertexBuffer.cpp

@@ -29,6 +29,7 @@
 
 #include <utils/bitset.h>
 #include <utils/compiler.h>
+#include <utils/CString.h>
 #include <utils/debug.h>
 #include <utils/Log.h>
 #include <utils/ostream.h>
@@ -259,7 +260,9 @@ FVertexBuffer::FVertexBuffer(FEngine& engine, const VertexBuffer::Builder& build
             mBufferCount, mDeclaredAttributes.count(), mAttributes);
 
     mHandle = driver.createVertexBuffer(mVertexCount, mVertexBufferInfoHandle);
-
+    if (auto name = builder.getName(); !name.empty()) {
+        driver.setDebugTag(mHandle.getId(), name);
+    }
 
     // calculate buffer sizes
     size_t bufferSizes[MAX_VERTEX_BUFFER_COUNT] = {};
@@ -287,6 +290,9 @@ FVertexBuffer::FVertexBuffer(FEngine& engine, const VertexBuffer::Builder& build
                 if (!mBufferObjects[i]) {
                     BufferObjectHandle bo = driver.createBufferObject(bufferSizes[i],
                             backend::BufferObjectBinding::VERTEX, backend::BufferUsage::STATIC);
+                    if (auto name = builder.getName(); !name.empty()) {
+                        driver.setDebugTag(bo.getId(), name);
+                    }
                     driver.setVertexBufferObject(mHandle, i, bo);
                     mBufferObjects[i] = bo;
                 }
@@ -303,6 +309,9 @@ FVertexBuffer::FVertexBuffer(FEngine& engine, const VertexBuffer::Builder& build
                 if (!mBufferObjects[i]) {
                     BufferObjectHandle const bo = driver.createBufferObject(bufferSizes[i],
                             backend::BufferObjectBinding::VERTEX, backend::BufferUsage::STATIC);
+                    if (auto name = builder.getName(); !name.empty()) {
+                        driver.setDebugTag(bo.getId(), name);
+                    }
                     driver.setVertexBufferObject(mHandle, i, bo);
                     mBufferObjects[i] = bo;
                 }

filament/src/details/View.cpp

@@ -31,15 +31,17 @@
 #include "details/Skybox.h"
 
 #include <filament/Exposure.h>
+#include <filament/DebugRegistry.h>
 #include <filament/TextureSampler.h>
 #include <filament/View.h>
 
 #include <private/filament/UibStructs.h>
 
+#include <utils/compiler.h>
+#include <utils/debug.h>
 #include <utils/Profiler.h>
 #include <utils/Slice.h>
 #include <utils/Systrace.h>
-#include <utils/debug.h>
 #include <utils/Zip2Iterator.h>
 
 #include <math/scalar.h>
@@ -47,6 +49,7 @@
 
 #include <array>
 #include <memory>
+#include <tuple>
 
 using namespace utils;
 
@@ -78,21 +81,29 @@ FView::FView(FEngine& engine)
     mPidController.setOutputDeadBand(-0.01f, 0.05f);
 
 #ifndef NDEBUG
-    debugRegistry.registerDataSource("d.view.frame_info",
-            [this]() -> DebugRegistry::DataSource {
-                assert_invariant(!mDebugFrameHistory);
-                mDebugFrameHistory = std::make_unique<std::array<DebugRegistry::FrameHistory, 5*60>>();
-                return { mDebugFrameHistory->data(), mDebugFrameHistory->size() };
+    // This can fail if another view has already registered this data source
+    mDebugState->owner = debugRegistry.registerDataSource("d.view.frame_info",
+            [weak = std::weak_ptr<DebugState>(mDebugState)]() -> DebugRegistry::DataSource {
+                // the View could have been destroyed by the time we do this
+                auto const state = weak.lock();
+                if (!state) {
+                    return { nullptr, 0 };
+                }
+                // Lazily allocate the buffer for the debug data source, and mark this
+                // data source as active. It can never go back to inactive.
+                assert_invariant(!state->debugFrameHistory);
+                state->active = true;
+                state->debugFrameHistory =
+                        std::make_unique<std::array<DebugRegistry::FrameHistory, 5 * 60>>();
+                return { state->debugFrameHistory->data(), state->debugFrameHistory->size() };
             });
-    debugRegistry.registerProperty("d.view.pid.kp", &engine.debug.view.pid.kp);
-    debugRegistry.registerProperty("d.view.pid.ki", &engine.debug.view.pid.ki);
-    debugRegistry.registerProperty("d.view.pid.kd", &engine.debug.view.pid.kd);
-    // default parameters for debugging UI
-    engine.debug.view.pid.kp = 1.0f - std::exp(-1.0f / 8.0f);
-    engine.debug.view.pid.ki = PID_CONTROLLER_Ki;
-    engine.debug.view.pid.kd = PID_CONTROLLER_Kd;
-    mPidController.setParallelGains(
-            engine.debug.view.pid.kp, engine.debug.view.pid.ki, engine.debug.view.pid.kd);
+
+    if (UTILS_UNLIKELY(mDebugState->owner)) {
+        // publish the properties (they will be initialized in the main loop)
+        debugRegistry.registerProperty("d.view.pid.kp", &engine.debug.view.pid.kp);
+        debugRegistry.registerProperty("d.view.pid.ki", &engine.debug.view.pid.ki);
+        debugRegistry.registerProperty("d.view.pid.kd", &engine.debug.view.pid.kd);
+    }
 #endif
 
     // allocate UBOs
@@ -126,6 +137,12 @@ void FView::terminate(FEngine& engine) {
     mFroxelizer.terminate(driver);
 
     engine.getEntityManager().destroy(mFogEntity);
+
+#ifndef NDEBUG
+    if (UTILS_UNLIKELY(mDebugState->owner)) {
+        engine.getDebugRegistry().unregisterDataSource("d.view.frame_info");
+    }
+#endif
 }
 
 void FView::setViewport(filament::Viewport const& viewport) noexcept {
@@ -167,6 +184,16 @@ float2 FView::updateScale(FEngine& engine,
         Renderer::FrameRateOptions const& frameRateOptions,
         Renderer::DisplayInfo const& displayInfo) noexcept {
 
+#ifndef NDEBUG
+    if (UTILS_LIKELY(!mDebugState->active)) {
+        // if we're not active, update the debug properties with the normal values
+        // and use that for configuring the PID controller.
+        engine.debug.view.pid.kp = 1.0f - std::exp(-frameRateOptions.scaleRate);
+        engine.debug.view.pid.ki = PID_CONTROLLER_Ki;
+        engine.debug.view.pid.kd = PID_CONTROLLER_Kd;
+    }
+#endif
+
     DynamicResolutionOptions const& options = mDynamicResolution;
     if (options.enabled) {
         if (!UTILS_UNLIKELY(info.valid)) {
@@ -250,14 +277,15 @@ float2 FView::updateScale(FEngine& engine,
 
 #ifndef NDEBUG
     // only for debugging...
-    if (mDebugFrameHistory) {
+    if (UTILS_UNLIKELY(mDebugState->active && mDebugState->debugFrameHistory)) {
+        auto* const debugFrameHistory = mDebugState->debugFrameHistory.get();
         using namespace std::chrono;
         using duration_ms = duration<float, std::milli>;
         const float target = (1000.0f * float(frameRateOptions.interval)) / displayInfo.refreshRate;
         const float targetWithHeadroom = target * (1.0f - frameRateOptions.headRoomRatio);
-        std::move(mDebugFrameHistory->begin() + 1,
-                mDebugFrameHistory->end(), mDebugFrameHistory->begin());
-        mDebugFrameHistory->back() = {
+        std::move(debugFrameHistory->begin() + 1,
+                debugFrameHistory->end(), debugFrameHistory->begin());
+        debugFrameHistory->back() = {
                 .target             = target,
                 .targetWithHeadroom = targetWithHeadroom,
                 .frameTime          = duration_cast<duration_ms>(info.frameTime).count(),
@@ -1012,10 +1040,8 @@ void FView::commitFrameHistory(FEngine& engine) noexcept {
     auto& frameHistory = mFrameHistory;
 
     FrameHistoryEntry& last = frameHistory.back();
-    disposer.destroy(last.taa.color.handle);
-    disposer.destroy(last.ssr.color.handle);
-    last.taa.color.handle.clear();
-    last.ssr.color.handle.clear();
+    disposer.destroy(std::move(last.taa.color.handle));
+    disposer.destroy(std::move(last.ssr.color.handle));
 
     // and then push the new history entry to the history stack
     frameHistory.commit();
@@ -1027,10 +1053,8 @@ void FView::clearFrameHistory(FEngine& engine) noexcept {
     auto& frameHistory = mFrameHistory;
     for (size_t i = 0; i < frameHistory.size(); ++i) {
         FrameHistoryEntry& last = frameHistory[i];
-        disposer.destroy(last.taa.color.handle);
-        disposer.destroy(last.ssr.color.handle);
-        last.taa.color.handle.clear();
-        last.ssr.color.handle.clear();
+        disposer.destroy(std::move(last.taa.color.handle));
+        disposer.destroy(std::move(last.ssr.color.handle));
     }
 }
 

filament/src/details/View.h

@@ -201,9 +201,9 @@ public:
 
     void setStereoscopicOptions(StereoscopicOptions const& options) noexcept;
 
-    FCamera const* getDirectionalShadowCamera() const noexcept {
-        if (!mShadowMapManager) return nullptr;
-        return mShadowMapManager->getDirectionalShadowCamera();
+    utils::FixedCapacityVector<Camera const*> getDirectionalShadowCameras() const noexcept {
+        if (!mShadowMapManager) return {};
+        return mShadowMapManager->getDirectionalShadowCameras();
     }
 
     void setRenderTarget(FRenderTarget* renderTarget) noexcept {
@@ -576,7 +576,12 @@ private:
                                                     }};
 
 #ifndef NDEBUG
-    std::unique_ptr<std::array<DebugRegistry::FrameHistory, 5*60>> mDebugFrameHistory;
+    struct DebugState {
+        std::unique_ptr<std::array<DebugRegistry::FrameHistory, 5*60>> debugFrameHistory{};
+        bool owner = false;
+        bool active = false;
+    };
+    std::shared_ptr<DebugState> mDebugState{ new DebugState };
 #endif
 };
 

filament/src/fg/PassNode.cpp

@@ -190,10 +190,10 @@ void RenderPassNode::resolve() noexcept {
                 minHeight = std::min(minHeight, h);
                 maxHeight = std::max(maxHeight, h);
             }
-            // additionally, clear implies discardStart
-            rt.backend.params.flags.discardStart |= (
-                    rt.descriptor.clearFlags & rt.targetBufferFlags);
         }
+        // additionally, clear implies discardStart
+        rt.backend.params.flags.discardStart |= (
+                rt.descriptor.clearFlags & rt.targetBufferFlags);
 
         assert_invariant(minWidth == maxWidth);
         assert_invariant(minHeight == maxHeight);

filament/src/materials/blitArray.mat

@@ -10,6 +10,10 @@ material {
             type : int,
             name : layerIndex
         },
+        {
+            type : float,
+            name : levelOfDetail,
+        },
         {
             type : float4,
             name : viewport,
@@ -33,6 +37,6 @@ vertex {
 
 fragment {
     void postProcess(inout PostProcessInputs postProcess) {
-        postProcess.color = textureLod(materialParams_color, vec3(variable_vertex.xy, materialParams.layerIndex), 0.0);
+        postProcess.color = textureLod(materialParams_color, vec3(variable_vertex.xy, materialParams.layerIndex), materialParams.levelOfDetail);
     }
 }

filament/src/materials/blitLow.mat

@@ -10,6 +10,10 @@ material {
             type : float4,
             name : viewport,
             precision: high
+        },
+        {
+            type : float,
+            name : levelOfDetail,
         }
     ],
     variables : [
@@ -33,7 +37,7 @@ fragment {
 #if FILAMENT_EFFECTIVE_VERSION == 100
         postProcess.color = texture2D(materialParams_color, variable_vertex.xy);
 #else
-        postProcess.color = textureLod(materialParams_color, variable_vertex.xy, 0.0);
+        postProcess.color = textureLod(materialParams_color, variable_vertex.xy, materialParams.levelOfDetail);
 #endif
     }
 }

ios/CocoaPods/Filament.podspec

@@ -1,12 +1,12 @@
 Pod::Spec.new do |spec|
   spec.name = "Filament"
-  spec.version = "1.54.0"
+  spec.version = "1.54.3"
   spec.license = { :type => "Apache 2.0", :file => "LICENSE" }
   spec.homepage = "https://google.github.io/filament"
   spec.authors = "Google LLC."
   spec.summary = "Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WASM/WebGL."
   spec.platform = :ios, "11.0"
-  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.54.0/filament-v1.54.0-ios.tgz" }
+  spec.source = { :http => "https://github.com/google/filament/releases/download/v1.54.3/filament-v1.54.3-ios.tgz" }
 
   # Fix linking error with Xcode 12; we do not yet support the simulator on Apple silicon.
   spec.pod_target_xcconfig = {

libs/filamat/include/filamat/MaterialBuilder.h

@@ -323,6 +323,9 @@ public:
     //! Custom variables (all float4).
     MaterialBuilder& variable(Variable v, const char* name) noexcept;
 
+    MaterialBuilder& variable(Variable v, const char* name,
+            ParameterPrecision precision) noexcept;
+
     /**
      * Require a specified attribute.
      *
@@ -708,11 +711,17 @@ public:
         ShaderStage stage;
     };
 
+    struct CustomVariable {
+        utils::CString name;
+        Precision precision = Precision::DEFAULT;
+        bool hasPrecision = false;
+    };
+
     static constexpr size_t MATERIAL_PROPERTIES_COUNT = filament::MATERIAL_PROPERTIES_COUNT;
     using Property = filament::Property;
 
     using PropertyList = bool[MATERIAL_PROPERTIES_COUNT];
-    using VariableList = utils::CString[MATERIAL_VARIABLES_COUNT];
+    using VariableList = CustomVariable[MATERIAL_VARIABLES_COUNT];
     using OutputList = std::vector<Output>;
 
     static constexpr size_t MAX_COLOR_OUTPUT = filament::backend::MRT::MAX_SUPPORTED_RENDER_TARGET_COUNT;

libs/filamat/src/MaterialBuilder.cpp

@@ -234,7 +234,21 @@ MaterialBuilder& MaterialBuilder::variable(Variable v, const char* name) noexcep
         case Variable::CUSTOM2:
         case Variable::CUSTOM3:
             assert(size_t(v) < MATERIAL_VARIABLES_COUNT);
-            mVariables[size_t(v)] = CString(name);
+            mVariables[size_t(v)] = { CString(name), Precision::DEFAULT, false };
+            break;
+    }
+    return *this;
+}
+
+MaterialBuilder& MaterialBuilder::variable(Variable v,
+        const char* name, ParameterPrecision precision) noexcept {
+    switch (v) {
+        case Variable::CUSTOM0:
+        case Variable::CUSTOM1:
+        case Variable::CUSTOM2:
+        case Variable::CUSTOM3:
+            assert(size_t(v) < MATERIAL_VARIABLES_COUNT);
+            mVariables[size_t(v)] = { CString(name), precision, true };
             break;
     }
     return *this;
@@ -1383,7 +1397,7 @@ bool MaterialBuilder::checkMaterialLevelFeatures(MaterialInfo const& info) const
 
 bool MaterialBuilder::hasCustomVaryings() const noexcept {
     for (const auto& variable : mVariables) {
-        if (!variable.empty()) {
+        if (!variable.name.empty()) {
             return true;
         }
     }

libs/filamat/src/shaders/CodeGenerator.cpp

@@ -451,15 +451,20 @@ io::sstream& CodeGenerator::generatePostProcessMain(io::sstream& out, ShaderStag
 }
 
 io::sstream& CodeGenerator::generateVariable(io::sstream& out, ShaderStage stage,
-        const CString& name, size_t index) {
-
+        const MaterialBuilder::CustomVariable& variable, size_t index) {
+    auto const& name = variable.name;
+    const char* precisionString = getPrecisionQualifier(variable.precision);
     if (!name.empty()) {
         if (stage == ShaderStage::VERTEX) {
             out << "\n#define VARIABLE_CUSTOM" << index << " " << name.c_str() << "\n";
             out << "\n#define VARIABLE_CUSTOM_AT" << index << " variable_" << name.c_str() << "\n";
-            out << "LAYOUT_LOCATION(" << index << ") VARYING vec4 variable_" << name.c_str() << ";\n";
+            out << "LAYOUT_LOCATION(" << index << ") VARYING " << precisionString << " vec4 variable_" << name.c_str() << ";\n";
         } else if (stage == ShaderStage::FRAGMENT) {
-            out << "\nLAYOUT_LOCATION(" << index << ") VARYING highp vec4 variable_" << name.c_str() << ";\n";
+            if (!variable.hasPrecision && variable.precision == Precision::DEFAULT) {
+                // for backward compatibility
+                precisionString = "highp";
+            }
+            out << "\nLAYOUT_LOCATION(" << index << ") VARYING " << precisionString << " vec4 variable_" << name.c_str() << ";\n";
         }
     }
     return out;

libs/filamat/src/shaders/CodeGenerator.h

@@ -103,7 +103,7 @@ public:
 
     // generate declarations for custom interpolants
     static utils::io::sstream& generateVariable(utils::io::sstream& out, ShaderStage stage,
-            const utils::CString& name, size_t index);
+            const MaterialBuilder::CustomVariable& variable, size_t index);
 
     // generate declarations for non-custom "in" variables
     utils::io::sstream& generateShaderInputs(utils::io::sstream& out, ShaderStage type,

libs/filamentapp/include/filamentapp/Cube.h

@@ -28,8 +28,14 @@
 
 class Cube {
 public:
+
     Cube(filament::Engine& engine, filament::Material const* material, filament::math::float3 linearColor, bool culling = true);
 
+    Cube(Cube const&) = delete;
+    Cube& operator=(Cube const&) = delete;
+
+    Cube(Cube&& rhs) noexcept;
+
     utils::Entity getSolidRenderable() {
         return mSolidRenderable;
     }
@@ -55,8 +61,8 @@ private:
     filament::Material const* mMaterial = nullptr;
     filament::MaterialInstance* mMaterialInstanceSolid = nullptr;
     filament::MaterialInstance* mMaterialInstanceWireFrame = nullptr;
-    utils::Entity mSolidRenderable;
-    utils::Entity mWireFrameRenderable;
+    utils::Entity mSolidRenderable{};
+    utils::Entity mWireFrameRenderable{};
 };
 
 

libs/filamentapp/include/filamentapp/FilamentApp.h

@@ -211,11 +211,11 @@ private:
         filament::Camera* mOrthoCamera;
 
         std::vector<std::unique_ptr<CView>> mViews;
-        CView* mMainView;
-        CView* mUiView;
+        CView* mMainView;   // well, the main view
+        CView* mUiView;     // the imgui ui
         CView* mDepthView;
-        GodView* mGodView;
-        CView* mOrthoView;
+        GodView* mGodView;  // the debug view with "god" camera
+        CView* mOrthoView;  // directional shadow map view
 
         size_t mWidth = 0;
         size_t mHeight = 0;

libs/filamentapp/src/Cube.cpp

@@ -104,11 +104,23 @@ Cube::Cube(Engine& engine, filament::Material const* material, float3 linearColo
             .build(engine, mWireFrameRenderable);
 }
 
+Cube::Cube(Cube&& rhs) noexcept
+        : mEngine(rhs.mEngine) {
+    using std::swap;
+    swap(rhs.mVertexBuffer, mVertexBuffer);
+    swap(rhs.mIndexBuffer, mIndexBuffer);
+    swap(rhs.mMaterial, mMaterial);
+    swap(rhs.mMaterialInstanceSolid, mMaterialInstanceSolid);
+    swap(rhs.mMaterialInstanceWireFrame, mMaterialInstanceWireFrame);
+    swap(rhs.mSolidRenderable, mSolidRenderable);
+    swap(rhs.mWireFrameRenderable, mWireFrameRenderable);
+}
+
 void Cube::mapFrustum(filament::Engine& engine, Camera const* camera) {
     // the Camera far plane is at infinity, but we want it closer for display
     const mat4 vm(camera->getModelMatrix());
     mat4 p(vm * inverse(camera->getCullingProjectionMatrix()));
-    return mapFrustum(engine, p);
+    mapFrustum(engine, p);
 }
 
 void Cube::mapFrustum(filament::Engine& engine, filament::math::mat4 const& transform) {
@@ -122,7 +134,7 @@ void Cube::mapFrustum(filament::Engine& engine, filament::math::mat4 const& tran
 
 void Cube::mapAabb(filament::Engine& engine, filament::Box const& box) {
     mat4 p = mat4::translation(box.center) * mat4::scaling(box.halfExtent);
-    return mapFrustum(engine, p);
+    mapFrustum(engine, p);
 }
 
 Cube::~Cube() {

libs/filamentapp/src/FilamentApp.cpp

@@ -1,4 +1,3 @@
-#include <memory>
 
 /*
  * Copyright (C) 2015 The Android Open Source Project
@@ -56,6 +55,13 @@
 
 #include <stb_image.h>
 
+#include <algorithm>
+#include <cstdlib>
+#include <memory>
+#include <vector>
+
+#include <stdint.h>
+
 #include "generated/resources/filamentapp.h"
 
 using namespace filament;
@@ -138,10 +144,17 @@ void FilamentApp::run(const Config& config, SetupCallback setupCallback,
             .package(FILAMENTAPP_TRANSPARENTCOLOR_DATA, FILAMENTAPP_TRANSPARENTCOLOR_SIZE)
             .build(*mEngine);
 
-    std::unique_ptr<Cube> cameraCube(new Cube(*mEngine, mTransparentMaterial, {1,0,0}));
+    std::unique_ptr<Cube> cameraCube{ new Cube(*mEngine, mTransparentMaterial, { 1, 0, 0 }) };
+
     // we can't cull the light-frustum because it's not applied a rigid transform
     // and currently, filament assumes that for culling
-    std::unique_ptr<Cube> lightmapCube(new Cube(*mEngine, mTransparentMaterial, {0,1,0}, false));
+    std::vector<Cube> lightmapCubes;
+    lightmapCubes.reserve(4);
+    lightmapCubes.emplace_back(*mEngine, mTransparentMaterial, float3{ 0, 1, 0 }, false);
+    lightmapCubes.emplace_back(*mEngine, mTransparentMaterial, float3{ 0, 0, 1 }, false);
+    lightmapCubes.emplace_back(*mEngine, mTransparentMaterial, float3{ 1, 1, 0 }, false);
+    lightmapCubes.emplace_back(*mEngine, mTransparentMaterial, float3{ 1, 0, 0 }, false);
+
     mScene = mEngine->createScene();
 
     window->mMainView->getView()->setVisibleLayers(0x4, 0x4);
@@ -151,16 +164,15 @@ void FilamentApp::run(const Config& config, SetupCallback setupCallback,
 
         rcm.setLayerMask(rcm.getInstance(cameraCube->getSolidRenderable()), 0x3, 0x2);
         rcm.setLayerMask(rcm.getInstance(cameraCube->getWireFrameRenderable()), 0x3, 0x2);
-
-        rcm.setLayerMask(rcm.getInstance(lightmapCube->getSolidRenderable()), 0x3, 0x2);
-        rcm.setLayerMask(rcm.getInstance(lightmapCube->getWireFrameRenderable()), 0x3, 0x2);
-
-        // Create the camera mesh
         mScene->addEntity(cameraCube->getWireFrameRenderable());
         mScene->addEntity(cameraCube->getSolidRenderable());
 
-        mScene->addEntity(lightmapCube->getWireFrameRenderable());
-        mScene->addEntity(lightmapCube->getSolidRenderable());
+        for (auto&& cube : lightmapCubes) {
+            rcm.setLayerMask(rcm.getInstance(cube.getSolidRenderable()), 0x3, 0x2);
+            rcm.setLayerMask(rcm.getInstance(cube.getWireFrameRenderable()), 0x3, 0x2);
+            mScene->addEntity(cube.getWireFrameRenderable());
+            mScene->addEntity(cube.getSolidRenderable());
+        }
 
         window->mDepthView->getView()->setVisibleLayers(0x4, 0x4);
         window->mGodView->getView()->setVisibleLayers(0x6, 0x6);
@@ -425,10 +437,26 @@ void FilamentApp::run(const Config& config, SetupCallback setupCallback,
         window->mDebugCamera->lookAt(eye, center, up);
 
         // Update the cube distortion matrix used for frustum visualization.
-        const Camera* lightmapCamera = window->mMainView->getView()->getDirectionalShadowCamera();
-        if (lightmapCamera) {
-            lightmapCube->mapFrustum(*mEngine, lightmapCamera);
+        auto& rcm = mEngine->getRenderableManager();
+        auto const csm = window->mMainView->getView()->getDirectionalShadowCameras();
+        // show/hide the cascades
+        for (size_t i = 0 ; i < 4; i++) {
+            rcm.setLayerMask(rcm.getInstance(lightmapCubes[i].getSolidRenderable()), 0x3, 0x0);
+            rcm.setLayerMask(rcm.getInstance(lightmapCubes[i].getWireFrameRenderable()), 0x3, 0x0);
         }
+        if (!csm.empty()) {
+            for (size_t i = 0, c = csm.size(); i < c; i++) {
+                if (csm[i]) {
+                    lightmapCubes[i].mapFrustum(*mEngine, csm[i]);
+                }
+                uint8_t const layer = csm[i] ? 0x2 : 0x0;
+                rcm.setLayerMask(rcm.getInstance(lightmapCubes[i].getSolidRenderable()),
+                        0x3, layer);
+                rcm.setLayerMask(rcm.getInstance(lightmapCubes[i].getWireFrameRenderable()),
+                        0x3, layer);
+            }
+        }
+
         cameraCube->mapFrustum(*mEngine, window->mMainCamera);
 
         // Delay rendering for roughly one monitor refresh interval
@@ -452,11 +480,14 @@ void FilamentApp::run(const Config& config, SetupCallback setupCallback,
 
         if (config.splitView) {
             if(!window->mOrthoView->getView()->hasCamera()) {
-                Camera const* debugDirectionalShadowCamera =
-                        window->mMainView->getView()->getDirectionalShadowCamera();
-                if (debugDirectionalShadowCamera) {
-                    window->mOrthoView->setCamera(
-                            const_cast<Camera*>(debugDirectionalShadowCamera));
+                auto const csm = window->mMainView->getView()->getDirectionalShadowCameras();
+                if (!csm.empty()) {
+                    // here we could choose the cascade
+                    Camera const* debugDirectionalShadowCamera = csm[0];
+                    if (debugDirectionalShadowCamera) {
+                        window->mOrthoView->setCamera(
+                                const_cast<Camera*>(debugDirectionalShadowCamera));
+                    }
                 }
             }
         }
@@ -484,7 +515,7 @@ void FilamentApp::run(const Config& config, SetupCallback setupCallback,
     cleanupCallback(mEngine, window->mMainView->getView(), mScene);
 
     cameraCube.reset();
-    lightmapCube.reset();
+    lightmapCubes.clear();
     window.reset();
 
     mIBL.reset();
@@ -736,12 +767,6 @@ FilamentApp::Window::Window(FilamentApp* filamentApp,
         mGodView->setCamera(mMainCamera);
         mGodView->setGodCamera(mDebugCamera);
         mGodView->setCameraManipulator(mDebugCameraMan);
-
-        // Ortho view obviously uses an ortho camera
-        Camera const* debugDirectionalShadowCamera = mMainView->getView()->getDirectionalShadowCamera();
-        if (debugDirectionalShadowCamera) {
-            mOrthoView->setCamera(const_cast<Camera *>(debugDirectionalShadowCamera));
-        }
     }
 
     // configure the cameras
@@ -907,9 +932,7 @@ void FilamentApp::Window::configureCamerasForWindow() {
 
     const bool splitview = mViews.size() > 2;
 
-    // To trigger a floating-point exception, users could shrink the window to be smaller than
-    // the sidebar. To prevent this we simply clamp the width of the main viewport.
-    const uint32_t mainWidth = splitview ? width : std::max(1, (int) width - sidebar);
+    const uint32_t mainWidth = std::max(2, (int) width - sidebar);
 
     double near = mFilamentApp->mCameraNear;
     double far = mFilamentApp->mCameraFar;
@@ -924,7 +947,7 @@ void FilamentApp::Window::configureCamerasForWindow() {
     } else {
         mMainCamera->setLensProjection(mFilamentApp->mCameraFocalLength, 1.0, near, far);
     }
-    mDebugCamera->setProjection(45.0, double(width) / height, 0.0625, 4096, Camera::Fov::VERTICAL);
+    mDebugCamera->setProjection(45.0, double(mainWidth) / height, 0.0625, 4096, Camera::Fov::VERTICAL);
 
     auto aspectRatio = double(mainWidth) / height;
     if (mMainView->getView()->getStereoscopicOptions().enabled) {
@@ -935,12 +958,12 @@ void FilamentApp::Window::configureCamerasForWindow() {
 
     // We're in split view when there are more views than just the Main and UI views.
     if (splitview) {
-        uint32_t vpw = width / 2;
-        uint32_t vph = height / 2;
-        mMainView->setViewport ({            0,            0, vpw,         vph          });
-        mDepthView->setViewport({ int32_t(vpw),            0, width - vpw, vph          });
-        mGodView->setViewport  ({ int32_t(vpw), int32_t(vph), width - vpw, height - vph });
-        mOrthoView->setViewport({            0, int32_t(vph), vpw,         height - vph });
+        uint32_t const vpw = mainWidth / 2;
+        uint32_t const vph = height / 2;
+        mMainView->setViewport ({ sidebar +            0,            0, vpw, vph });
+        mDepthView->setViewport({ sidebar + int32_t(vpw),            0, vpw, vph });
+        mGodView->setViewport  ({ sidebar + int32_t(vpw), int32_t(vph), vpw, vph });
+        mOrthoView->setViewport({ sidebar +            0, int32_t(vph), vpw, vph });
     } else {
         mMainView->setViewport({ sidebar, 0, mainWidth, height });
     }

libs/gltfio/src/MaterialProvider.cpp

@@ -56,7 +56,13 @@ bool operator==(const MaterialKey& k1, const MaterialKey& k2) {
         (k1.volumeThicknessUV == k2.volumeThicknessUV) &&
         (k1.hasSheen == k2.hasSheen) &&
         (k1.hasIOR == k2.hasIOR) &&
-        (k1.hasVolume == k2.hasVolume);
+        (k1.hasVolume == k2.hasVolume) &&
+        (k1.hasSpecular == k2.hasSpecular) &&
+        (k1.hasSpecularTexture == k2.hasSpecularTexture) &&
+        (k1.hasSpecularColorTexture == k2.hasSpecularColorTexture) &&
+        (k1.specularTextureUV == k2.specularTextureUV) &&
+        (k1.specularColorTextureUV == k2.specularColorTextureUV)
+        ;
 }
 
 // Filament supports up to 2 UV sets. glTF has arbitrary texcoord set indices, but it allows

libs/gltfio/src/UbershaderProvider.cpp

@@ -259,6 +259,24 @@ MaterialInstance* UbershaderProvider::createMaterialInstance(MaterialKey* config
     mi->setParameter("occlusionUvMatrix", identity);
     mi->setParameter("emissiveUvMatrix", identity);
 
+    // set to -1 all possibly optional parameters
+    for (auto const* param : {
+            "clearCoatIndex",
+            "clearCoatRoughnessIndex",
+            "clearCoatNormalIndex",
+            "sheenColorIndex",
+            "sheenRoughnessIndex",
+            "volumeThicknessUvMatrix",
+            "volumeThicknessIndex",
+            "transmissionIndex",
+            "specularIndex",
+            "specularColorIndex",
+    }) {
+        if (material->hasParameter(param)) {
+            mi->setParameter(param, -1);
+        }
+    }
+
     if (config->hasClearCoat) {
         mi->setParameter("clearCoatIndex",
                 getUvIndex(config->clearCoatUV, config->hasClearCoatTexture));
@@ -340,10 +358,10 @@ MaterialInstance* UbershaderProvider::createMaterialInstance(MaterialKey* config
         mi->setParameter("sheenRoughnessMap", mDummyTexture, sampler);
     }
 
-    if (mi->getMaterial()->hasParameter("ior")) {
+    if (material->hasParameter("ior")) {
         mi->setParameter("ior", 1.5f);
     }
-    if (mi->getMaterial()->hasParameter("reflectance")) {
+    if (material->hasParameter("reflectance")) {
         mi->setParameter("reflectance", 0.5f);
     }
 
@@ -355,6 +373,14 @@ MaterialInstance* UbershaderProvider::createMaterialInstance(MaterialKey* config
         mi->setParameter("specularColorMap", mDummyTexture, sampler);
     }
 
+    if (material->hasParameter("specularColorFactor")) {
+        mi->setParameter("specularColorFactor", float3(1.0f));
+    }
+
+    if (material->hasParameter("specularStrength")) {
+        mi->setParameter("specularStrength", 1.0f);
+    }
+
     return mi;
 }
 

libs/gltfio/src/extended/AssetLoaderExtended.cpp

@@ -527,11 +527,13 @@ bool AssetLoaderExtended::createPrimitive(Input* input, Output* out,
 
     if (!mCgltfBuffersLoaded) {
         mCgltfBuffersLoaded = utility::loadCgltfBuffers(gltf, mGltfPath.c_str(), mUriDataCache);
-        if (!mCgltfBuffersLoaded) return false;
+        if (!mCgltfBuffersLoaded) {
+            return false;
+        }
+        utility::decodeMeshoptCompression(gltf);
     }
 
     utility::decodeDracoMeshes(gltf, prim, input->dracoCache);
-    utility::decodeMeshoptCompression(gltf);
 
     auto slots = computeGeometries(prim, jobType, attributesMap, morphTargets, out->uvmap, mEngine);
 

libs/viewer/include/viewer/AutomationEngine.h

@@ -224,6 +224,9 @@ public:
      */
     static void exportSettings(const Settings& settings, const char* filename);
 
+    static void exportScreenshot(View* view, Renderer* renderer, std::string filename,
+            bool autoclose, AutomationEngine* automationEngine);
+
     Options getOptions() const { return mOptions; }
     bool isRunning() const { return mIsRunning; }
     size_t currentTest() const { return mCurrentTest; }

libs/viewer/src/AutomationEngine.cpp

@@ -56,7 +56,7 @@ static void convertRGBAtoRGB(void* buffer, uint32_t width, uint32_t height) {
     }
 }
 
-static void exportScreenshot(View* view, Renderer* renderer, std::string filename,
+void AutomationEngine::exportScreenshot(View* view, Renderer* renderer, std::string filename,
         bool autoclose, AutomationEngine* automationEngine) {
     const Viewport& vp = view->getViewport();
     const size_t byteCount = vp.width * vp.height * 4;
@@ -244,7 +244,8 @@ void AutomationEngine::tick(Engine* engine, const ViewerContent& content, float
     }
 
     if (mOptions.exportScreenshots) {
-        exportScreenshot(content.view, content.renderer, prefix + ".ppm", isLastTest, this);
+        AutomationEngine::exportScreenshot(
+                content.view, content.renderer, prefix + ".ppm", isLastTest, this);
     }
 
     if (isLastTest) {

samples/gltf_viewer.cpp

@@ -61,8 +61,10 @@
 #include <algorithm>
 #include <array>
 #include <fstream>
+#include <iomanip>
 #include <iostream>
 #include <set>
+#include <sstream>
 #include <string>
 
 #include "generated/resources/gltf_demo.h"
@@ -137,6 +139,8 @@ struct App {
 
     AutomationSpec* automationSpec = nullptr;
     AutomationEngine* automationEngine = nullptr;
+    bool screenshot = false;
+    uint8_t screenshotSeq = 0;
 };
 
 static const char* DEFAULT_IBL = "assets/ibl/lightroom_14b";
@@ -877,10 +881,15 @@ int main(int argc, char** argv) {
 
             if (ImGui::CollapsingHeader("Debug")) {
                 auto& debug = engine->getDebugRegistry();
-                if (ImGui::Button("Capture frame")) {
-                    bool* captureFrame =
-                            debug.getPropertyAddress<bool>("d.renderer.doFrameCapture");
-                    *captureFrame = true;
+                if (engine->getBackend() == Engine::Backend::METAL) {
+                    if (ImGui::Button("Capture frame")) {
+                        bool* captureFrame =
+                                debug.getPropertyAddress<bool>("d.renderer.doFrameCapture");
+                        *captureFrame = true;
+                    }
+                }
+                if (ImGui::Button("Screenshot")) {
+                    app.screenshot = true;
                 }
                 ImGui::Checkbox("Disable buffer padding",
                         debug.getPropertyAddress<bool>("d.renderer.disable_buffer_padding"));
@@ -894,6 +903,10 @@ int main(int argc, char** argv) {
                         debug.getPropertyAddress<bool>("d.shadowmap.far_uses_shadowcasters"));
                 ImGui::Checkbox("Focus shadow casters",
                         debug.getPropertyAddress<bool>("d.shadowmap.focus_shadowcasters"));
+                ImGui::Checkbox("Disable light frustum alignment",
+                        debug.getPropertyAddress<bool>("d.shadowmap.disable_light_frustum_align"));
+                ImGui::Checkbox("Depth clamp",
+                        debug.getPropertyAddress<bool>("d.shadowmap.depth_clamp"));
 
                 bool debugDirectionalShadowmap;
                 if (debug.getProperty("d.shadowmap.debug_directional_shadowmap",
@@ -1134,6 +1147,14 @@ int main(int argc, char** argv) {
     };
 
     auto postRender = [&app](Engine* engine, View* view, Scene*, Renderer* renderer) {
+        if (app.screenshot) {
+            std::ostringstream stringStream;
+            stringStream << "screenshot" << std::setfill('0') << std::setw(2) << +app.screenshotSeq;
+            AutomationEngine::exportScreenshot(
+                    view, renderer, stringStream.str() + ".ppm", false, app.automationEngine);
+            ++app.screenshotSeq;
+            app.screenshot = false;
+        }
         if (app.automationEngine->shouldClose()) {
             FilamentApp::get().close();
             return;

tools/matc/src/matc/ParametersProcessor.cpp

@@ -615,14 +615,51 @@ static bool processVariables(MaterialBuilder& builder, const JsonishValue& value
     }
 
     for (size_t i = 0; i < elements.size(); i++) {
-        auto elementValue = elements[i];
+        ParameterPrecision precision = ParameterPrecision::DEFAULT;
         MaterialBuilder::Variable v = intToVariable(i);
-        if (elementValue->getType() != JsonishValue::Type::STRING) {
+        std::string nameString;
+
+        auto elementValue = elements[i];
+        if (elementValue->getType() == JsonishValue::Type::OBJECT) {
+
+            JsonishObject const& jsonObject = *elementValue->toJsonObject();
+
+            const JsonishValue* nameValue = jsonObject.getValue("name");
+            if (!nameValue) {
+                std::cerr << "variables: entry without 'name' key." << std::endl;
+                return false;
+            }
+            if (nameValue->getType() != JsonishValue::STRING) {
+                std::cerr << "variables: name value must be STRING." << std::endl;
+                return false;
+            }
+
+            const JsonishValue* precisionValue = jsonObject.getValue("precision");
+            if (precisionValue) {
+                if (precisionValue->getType() != JsonishValue::STRING) {
+                    std::cerr << "variables: precision must be a STRING." << std::endl;
+                    return false;
+                }
+                auto precisionString = precisionValue->toJsonString();
+                if (!Enums::isValid<ParameterPrecision>(precisionString->getString())){
+                    return logEnumIssue("variables", *precisionString, Enums::map<ParameterPrecision>());
+                }
+            }
+
+            nameString = nameValue->toJsonString()->getString();
+            if (precisionValue) {
+                precision = Enums::toEnum<ParameterPrecision>(
+                        precisionValue->toJsonString()->getString());
+            }
+            builder.variable(v, nameString.c_str(), precision);
+        } else if (elementValue->getType() == JsonishValue::Type::STRING) {
+            nameString = elementValue->toJsonString()->getString();
+            builder.variable(v, nameString.c_str());
+        } else {
             std::cerr << "variables: array index " << i << " is not a STRING. found:" <<
                     JsonishValue::typeToString(elementValue->getType()) << std::endl;
             return false;
         }
-        builder.variable(v, elementValue->toJsonString()->getString().c_str());
     }
 
     return true;

web/filament-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "filament",
-  "version": "1.54.0",
+  "version": "1.54.3",
   "description": "Real-time physically based rendering engine",
   "main": "filament.js",
   "module": "filament.js",