Testing stencilling 2

This reverts commits
- b70aa43727 "depth clamp cannot work with VSM"
- 6c0bd360b3 "Add support for depth clamp and use it for shadows"

NEW_RELEASE_NOTES.md

@@ -7,3 +7,5 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- Add a `name` API to Filament objects for debugging handle use-after-free assertions

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
-            bool depthClamp                             : 1;        // 32
+            uint8_t padding                             : 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,7 +309,6 @@ 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)

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,34 @@ 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 tag's age to N bits.
+            constexpr uint8_t N = 2; // support a history of 4 tags
+            constexpr uint8_t mask = (1 << N) - 1;
+
+            uint8_t const age = (id & HANDLE_AGE_MASK) >> HANDLE_AGE_SHIFT;
+            uint8_t const newAge = age & mask;
+            uint32_t const key = (id & ~HANDLE_AGE_MASK) | (newAge << HANDLE_AGE_SHIFT);
+
+            // 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)";
+        }
+        if (auto pos = mDebugTags.find(id); pos != mDebugTags.end()) {
+            return pos->second;
+        }
+        return "(no tag)";
+    }
+
 private:
 
     template<typename D>
@@ -363,6 +394,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/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/MetalContext.h

@@ -112,7 +112,6 @@ 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.mm

@@ -834,10 +834,6 @@ bool MetalDriver::isProtectedTexturesSupported() {
     return false;
 }
 
-bool MetalDriver::isDepthClampSupported() {
-    return true;
-}
-
 bool MetalDriver::isWorkaroundNeeded(Workaround workaround) {
     switch (workaround) {
         case Workaround::SPLIT_EASU:
@@ -1755,13 +1751,6 @@ 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) {
@@ -2072,6 +2061,10 @@ 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);

filament/backend/src/metal/MetalState.h

@@ -382,7 +382,6 @@ 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,10 +202,6 @@ bool NoopDriver::isProtectedTexturesSupported() {
     return true;
 }
 
-bool NoopDriver::isDepthClampSupported() {
-    return false;
-}
-
 bool NoopDriver::isWorkaroundNeeded(Workaround) {
     return false;
 }
@@ -392,4 +388,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

@@ -676,7 +676,6 @@ 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);
@@ -747,7 +746,6 @@ 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;
@@ -1046,6 +1044,11 @@ void OpenGLContext::resetState() noexcept {
     );
     glDepthMask(state.raster.depthMask);
     glDepthFunc(state.raster.depthFunc);
+
+    utils::slog.e << "stencil front=" << 
+        state.stencil.front.func.func << " "  <<
+        state.stencil.front.func.ref << " "  <<
+        state.stencil.front.func.mask << " " << utils::io::endl;
     
     // state.stencil
     glStencilFuncSeparate(

filament/backend/src/opengl/OpenGLContext.h

@@ -220,9 +220,8 @@ public:
         bool EXT_color_buffer_float;
         bool EXT_color_buffer_half_float;
         bool EXT_debug_marker;
-        bool EXT_depth_clamp;
-        bool EXT_discard_framebuffer;
         bool EXT_disjoint_timer_query;
+        bool EXT_discard_framebuffer;
         bool EXT_multisampled_render_to_texture2;
         bool EXT_multisampled_render_to_texture;
         bool EXT_protected_textures;
@@ -240,10 +239,10 @@ public:
         bool KHR_parallel_shader_compile;
         bool KHR_texture_compression_astc_hdr;
         bool KHR_texture_compression_astc_ldr;
-        bool OES_EGL_image_external_essl3;
-        bool OES_depth24;
         bool OES_depth_texture;
+        bool OES_depth24;
         bool OES_packed_depth_stencil;
+        bool OES_EGL_image_external_essl3;
         bool OES_rgb8_rgba8;
         bool OES_standard_derivatives;
         bool OES_texture_npot;
@@ -628,7 +627,6 @@ 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,14 +451,6 @@ 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 {
@@ -468,20 +460,20 @@ void OpenGLDriver::setStencilState(StencilState ss) noexcept {
 
     // stencil test / operation
     // GL_STENCIL_TEST must be enabled if we're testing OR writing to the stencil buffer.
-    if (UTILS_LIKELY(
-            ss.front.stencilFunc == StencilState::StencilFunction::A &&
-            ss.back.stencilFunc == StencilState::StencilFunction::A &&
-            ss.front.stencilOpDepthFail == StencilOperation::KEEP &&
-            ss.back.stencilOpDepthFail == StencilOperation::KEEP &&
-            ss.front.stencilOpStencilFail == StencilOperation::KEEP &&
-            ss.back.stencilOpStencilFail == StencilOperation::KEEP &&
-            ss.front.stencilOpDepthStencilPass == StencilOperation::KEEP &&
-            ss.back.stencilOpDepthStencilPass == StencilOperation::KEEP)) {
-        // that's equivalent to having the stencil test disabled
-        gl.disable(GL_STENCIL_TEST);
-    } else {
+    // if (UTILS_LIKELY(
+    //         ss.front.stencilFunc == StencilState::StencilFunction::A &&
+    //         ss.back.stencilFunc == StencilState::StencilFunction::A &&
+    //         ss.front.stencilOpDepthFail == StencilOperation::KEEP &&
+    //         ss.back.stencilOpDepthFail == StencilOperation::KEEP &&
+    //         ss.front.stencilOpStencilFail == StencilOperation::KEEP &&
+    //         ss.back.stencilOpStencilFail == StencilOperation::KEEP &&
+    //         ss.front.stencilOpDepthStencilPass == StencilOperation::KEEP &&
+    //         ss.back.stencilOpDepthStencilPass == StencilOperation::KEEP) && false) {
+    //     // that's equivalent to having the stencil test disabled
+    //     gl.disable(GL_STENCIL_TEST);
+    // } else {
         gl.enable(GL_STENCIL_TEST);
-    }
+//    }
 
     // glStencilFuncSeparate() also sets the reference value, which may be used depending
     // on the stencilOp, so we always need to call glStencilFuncSeparate().
@@ -489,9 +481,9 @@ void OpenGLDriver::setStencilState(StencilState ss) noexcept {
             getStencilFunc(ss.front.stencilFunc), ss.front.ref, ss.front.readMask,
             getStencilFunc(ss.back.stencilFunc), ss.back.ref, ss.back.readMask);
 
-    if (UTILS_LIKELY(!ss.stencilWrite)) {
-        gl.stencilMaskSeparate(0x00, 0x00);
-    } else {
+//    if (UTILS_LIKELY(!ss.stencilWrite)) {
+//        gl.stencilMaskSeparate(0x00, 0x00);
+//    } else {
         // Stencil ops are only relevant when stencil write is enabled
         gl.stencilOpSeparate(
                 getStencilOp(ss.front.stencilOpStencilFail),
@@ -501,7 +493,7 @@ void OpenGLDriver::setStencilState(StencilState ss) noexcept {
                 getStencilOp(ss.back.stencilOpDepthFail),
                 getStencilOp(ss.back.stencilOpDepthStencilPass));
         gl.stencilMaskSeparate(ss.front.writeMask, ss.back.writeMask);
-    }
+//    }
 }
 
 // ------------------------------------------------------------------------------------------------
@@ -2127,10 +2119,6 @@ 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:
@@ -2222,6 +2210,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()

filament/backend/src/opengl/gl_headers.h

@@ -201,12 +201,6 @@ 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,10 +125,6 @@ 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,10 +944,6 @@ bool VulkanDriver::isProtectedTexturesSupported() {
     return false;
 }
 
-bool VulkanDriver::isDepthClampSupported() {
-    return mContext.isDepthClampSupported();
-}
-
 bool VulkanDriver::isWorkaroundNeeded(Workaround workaround) {
     switch (workaround) {
         case Workaround::SPLIT_EASU: {
@@ -1820,8 +1816,6 @@ void VulkanDriver::bindPipeline(PipelineState const& pipelineState) {
         .dstAlphaBlendFactor = getBlendFactor(rasterState.blendFunctionDstAlpha),
         .colorWriteMask = (VkColorComponentFlags) (rasterState.colorWrite ? 0xf : 0x0),
         .rasterizationSamples = rt->getSamples(),
-        .depthClamp = rasterState.depthClamp,
-        .reserved = 0,
         .colorTargetCount = rt->getColorTargetCount(mCurrentRenderPass),
         .colorBlendOp = rasterState.blendEquationRGB,
         .alphaBlendOp =  rasterState.blendEquationAlpha,
@@ -2038,6 +2032,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/VulkanPipelineCache.cpp

@@ -184,7 +184,6 @@ 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,9 +90,7 @@ public:
         VkBlendFactor         srcAlphaBlendFactor : 5;
         VkBlendFactor         dstAlphaBlendFactor : 5;
         VkColorComponentFlags colorWriteMask : 4;
-        uint8_t               rasterizationSamples : 4;// offset = 4 bytes
-        uint8_t               depthClamp : 1;
-        uint8_t               reserved : 3;
+        uint8_t               rasterizationSamples;    // offset = 4 bytes
         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/platform/VulkanPlatform.cpp

@@ -325,7 +325,6 @@ 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,22 @@ public:
 template<typename T>
 using BuilderBase = utils::PrivateImplementation<T>;
 
+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/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/PostProcessManager.cpp

@@ -2945,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,
@@ -3003,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;
@@ -3031,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,
@@ -3043,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);
 

filament/src/RenderPass.cpp

@@ -419,8 +419,7 @@ 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, bool hasDepthClamp) noexcept {
+        FMaterialInstance const* const UTILS_RESTRICT mi, bool inverseFrontFaces) noexcept {
 
     FMaterial const * const UTILS_RESTRICT ma = mi->getMaterial();
     variant = Variant::filterVariant(variant, ma->isVariantLit());
@@ -461,7 +460,6 @@ 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)
 }
@@ -560,9 +558,6 @@ 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>();
@@ -582,7 +577,6 @@ 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) {
@@ -697,8 +691,7 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
             cmd.info.morphingOffset = primitive.getMorphingBufferOffset();
 
             if constexpr (isColorPass) {
-                RenderPass::setupColorCommand(cmd, renderableVariant, mi,
-                        inverseFrontFaces, hasDepthClamp);
+                RenderPass::setupColorCommand(cmd, renderableVariant, mi, inverseFrontFaces);
                 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,7 +284,6 @@ 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<
@@ -445,7 +444,7 @@ private:
             uint8_t instancedStereoEyeCount) noexcept;
 
     static void setupColorCommand(Command& cmdDraw, Variant variant,
-            FMaterialInstance const* mi, bool inverseFrontFaces, bool hasDepthClamp) noexcept;
+            FMaterialInstance const* mi, bool inverseFrontFaces) noexcept;
 
     static void updateSummedPrimitiveCounts(
             FScene::RenderableSoa& renderableData, utils::Range<uint32_t> vr) noexcept;

filament/src/ShadowMap.cpp

@@ -829,13 +829,13 @@ ShadowMap::Corners ShadowMap::computeFrustumCorners(
     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 },
             }
     };
 

filament/src/ShadowMapManager.cpp

@@ -66,15 +66,15 @@ namespace filament {
 using namespace backend;
 using namespace math;
 
-ShadowMapManager::ShadowMapManager(FEngine& engine)
-    : mIsDepthClampSupported(engine.getDriverApi().isDepthClampSupported()) {
+// do this only if depth-clamp is available
+static constexpr bool USE_DEPTH_CLAMP = false;
+
+ShadowMapManager::ShadowMapManager(FEngine& engine) {
     FDebugRegistry& debugRegistry = engine.getDebugRegistry();
     debugRegistry.registerProperty("d.shadowmap.visualize_cascades",
             &engine.debug.shadowmap.visualize_cascades);
     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() {
@@ -367,22 +367,7 @@ FrameGraphId<FrameGraphTexture> ShadowMapManager::render(FEngine& engine, FrameG
 
                     // generate and sort the commands for rendering the shadow map
 
-                    RenderPass::RenderFlags renderPassFlags{};
-                    if (view.isFrontFaceWindingInverted()) {
-                        renderPassFlags |= RenderPass::HAS_INVERSE_FRONT_FACES;
-                    }
-
-                    bool const canUseDepthClamp =
-                            !view.hasVSM() &&
-                            mIsDepthClampSupported &&
-                            engine.debug.shadowmap.depth_clamp;
-
-                    if (canUseDepthClamp) {
-                        renderPassFlags |= RenderPass::HAS_DEPTH_CLAMP;
-                    }
-
                     RenderPass const pass = passBuilder
-                            .renderFlags(renderPassFlags)
                             .camera(cameraInfo)
                             .visibilityMask(entry.visibilityMask)
                             .geometry(scene->getRenderableData(),
@@ -656,14 +641,8 @@ ShadowMapManager::ShadowTechnique ShadowMapManager::updateCascadeShadowMaps(FEng
             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,
-                    canUseDepthClamp);
+                    lightData, 0, cameraInfo, shadowMapInfo, sceneInfo, USE_DEPTH_CLAMP);
 
             if (shadowMap.hasVisibleShadows()) {
                 const size_t shadowIndex = shadowMap.getShadowIndex();

filament/src/ShadowMapManager.h

@@ -232,7 +232,6 @@ private:
     ShadowMapCacheContainer mShadowMapCache;
     uint32_t mDirectionalShadowMapCount = 0;
     uint32_t mSpotShadowMapCount = 0;
-    bool const mIsDepthClampSupported;
     bool mInitialized = false;
 
     ShadowMap& getShadowMap(size_t index) 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,6 +28,12 @@
 #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;
 
@@ -73,15 +79,17 @@ bool FDebugRegistry::hasProperty(const char* name) const noexcept {
 
 template<typename T>
 bool FDebugRegistry::setProperty(const char* name, T v) noexcept {
-    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();
+    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;
         }
-        return true;
     }
     return false;
 }

filament/src/details/Engine.h

@@ -600,7 +600,6 @@ public:
             bool focus_shadowcasters = true;
             bool visualize_cascades = false;
             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/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,9 @@ 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));
+    }
 }
 
 // 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/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
     }
 }

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

samples/gltf_viewer.cpp

@@ -905,8 +905,6 @@ int main(int argc, char** argv) {
                         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",

samples/hellotriangle.cpp

@@ -20,6 +20,7 @@
 #include <filament/Material.h>
 #include <filament/MaterialInstance.h>
 #include <filament/RenderableManager.h>
+#include <filament/Renderer.h>
 #include <filament/Scene.h>
 #include <filament/Skybox.h>
 #include <filament/TransformManager.h>
@@ -46,23 +47,33 @@ using utils::EntityManager;
 struct App {
     Config config;
     VertexBuffer* vb;
+    VertexBuffer* vb2;
     IndexBuffer* ib;
     Material* mat;
     Camera* cam;
     Entity camera;
     Skybox* skybox;
     Entity renderable;
+    Entity r2;
 };
 
 struct Vertex {
-    filament::math::float2 position;
+    filament::math::float3 position;
     uint32_t color;
 };
 
+float const z = 5;
+
 static const Vertex TRIANGLE_VERTICES[3] = {
-    {{1, 0}, 0xffff0000u},
-    {{cos(M_PI * 2 / 3), sin(M_PI * 2 / 3)}, 0xff00ff00u},
-    {{cos(M_PI * 4 / 3), sin(M_PI * 4 / 3)}, 0xff0000ffu},
+    {{1, 0, z}, 0xffff0000u},
+    {{cos(M_PI * 2 / 3), sin(M_PI * 2 / 3), z}, 0xff00ff00u},
+    {{cos(M_PI * 4 / 3), sin(M_PI * 4 / 3), z}, 0xff0000ffu},
+};
+
+static Vertex T2[3] = {
+        TRIANGLE_VERTICES[0],
+        TRIANGLE_VERTICES[1],
+        TRIANGLE_VERTICES[2],
 };
 
 static constexpr uint16_t TRIANGLE_INDICES[3] = { 0, 1, 2 };
@@ -120,25 +131,39 @@ static int handleCommandLineArguments(int argc, char* argv[], App* app) {
 }
 
 int main(int argc, char** argv) {
+    T2[0].position.z = z - 10;
+    T2[1].position.z = z - 10;
+    T2[2].position.z = z - 10;
+
+    T2[0].color = 0xFF0000FF;
+    T2[1].color = 0xFF0000FF;
+    T2[2].color = 0xFF0000FF;
+
     App app{};
     app.config.title = "hellotriangle";
     app.config.featureLevel = backend::FeatureLevel::FEATURE_LEVEL_0;
     handleCommandLineArguments(argc, argv, &app);
 
     auto setup = [&app](Engine* engine, View* view, Scene* scene) {
-        app.skybox = Skybox::Builder().color({0.1, 0.125, 0.25, 1.0}).build(*engine);
-        scene->setSkybox(app.skybox);
         view->setPostProcessingEnabled(false);
-        static_assert(sizeof(Vertex) == 12, "Strange vertex size.");
-        app.vb = VertexBuffer::Builder()
+        view->setStencilBufferEnabled(true);
+
+        
+//        app.skybox = Skybox::Builder().color({0.1, 0.125, 0.25, 1.0}).build(*engine);
+//        scene->setSkybox(app.skybox);
+        static_assert(sizeof(Vertex) == 16, "Strange vertex size.");
+        auto builder = VertexBuffer::Builder()
                 .vertexCount(3)
                 .bufferCount(1)
-                .attribute(VertexAttribute::POSITION, 0, VertexBuffer::AttributeType::FLOAT2, 0, 12)
-                .attribute(VertexAttribute::COLOR, 0, VertexBuffer::AttributeType::UBYTE4, 8, 12)
-                .normalized(VertexAttribute::COLOR)
-                .build(*engine);
+                .attribute(VertexAttribute::POSITION, 0, VertexBuffer::AttributeType::FLOAT3, 0, 16)
+                .attribute(VertexAttribute::COLOR, 0, VertexBuffer::AttributeType::UBYTE4, 12, 16)
+                .normalized(VertexAttribute::COLOR);
+        app.vb = builder.build(*engine);
+        app.vb2 = builder.build(*engine);
         app.vb->setBufferAt(*engine, 0,
-                VertexBuffer::BufferDescriptor(TRIANGLE_VERTICES, 36, nullptr));
+                VertexBuffer::BufferDescriptor(TRIANGLE_VERTICES, 48, nullptr));
+        app.vb2->setBufferAt(*engine, 0,
+                VertexBuffer::BufferDescriptor(T2, 48, nullptr));
         app.ib = IndexBuffer::Builder()
                 .indexCount(3)
                 .bufferType(IndexBuffer::IndexType::USHORT)
@@ -149,22 +174,67 @@ int main(int argc, char** argv) {
                 .package(RESOURCES_BAKEDCOLOR_DATA, RESOURCES_BAKEDCOLOR_SIZE)
                 .build(*engine);
         app.renderable = EntityManager::get().create();
+        app.r2 = EntityManager::get().create();
+
+        auto inst1 = app.mat->createInstance();
+        inst1->setDepthWrite(false);        
+        inst1->setDepthFunc(MaterialInstance::DepthFunc::A);        
+        inst1->setDepthCulling(false);
+        
+        inst1->setStencilWrite(true);
+        inst1->setStencilCompareFunction(MaterialInstance::StencilCompareFunc::E);
+        inst1->setStencilOpDepthStencilPass(MaterialInstance::StencilOperation::REPLACE);
+        inst1->setStencilReferenceValue(6);
+
+        auto inst2 = app.mat->createInstance();
+        inst2->setDepthWrite(false);
+        inst2->setDepthFunc(MaterialInstance::DepthFunc::A);
+        inst2->setDepthCulling(false);
+        
+        inst2->setStencilWrite(true);
+        inst2->setStencilCompareFunction(MaterialInstance::StencilCompareFunc::L);
+        inst2->setStencilOpDepthStencilPass(MaterialInstance::StencilOperation::REPLACE);
+        inst2->setStencilReferenceValue(6);
+
+
+        auto& renderableMan = engine->getRenderableManager();
+
         RenderableManager::Builder(1)
                 .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
-                .material(0, app.mat->getDefaultInstance())
+                .material(0, inst1)
                 .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, app.vb, app.ib, 0, 3)
                 .culling(false)
                 .receiveShadows(false)
                 .castShadows(false)
                 .build(*engine, app.renderable);
+
+
+        RenderableManager::Builder(1)
+                .boundingBox({{ -1, -1, -1 }, { 1, 1, 1 }})
+                .material(0, inst2)
+                .geometry(0, RenderableManager::PrimitiveType::TRIANGLES, app.vb2, app.ib, 0, 3)
+                .culling(false)
+                .receiveShadows(false)
+                .castShadows(false)
+                .build(*engine, app.r2);
+
         scene->addEntity(app.renderable);
+
+
+        auto r1inst = renderableMan.getInstance(app.renderable);
+        renderableMan.setPriority(r1inst, 7);
+
+        scene->addEntity(app.r2);        
+        auto r2inst = renderableMan.getInstance(app.r2);
+        renderableMan.setPriority(r2inst, 6);
+
         app.camera = utils::EntityManager::get().create();
         app.cam = engine->createCamera(app.camera);
         view->setCamera(app.cam);
     };
 
     auto cleanup = [&app](Engine* engine, View*, Scene*) {
-        engine->destroy(app.skybox);
+//        engine->destroy(app.skybox);
         engine->destroy(app.renderable);
         engine->destroy(app.mat);
         engine->destroy(app.vb);
@@ -174,19 +244,24 @@ int main(int argc, char** argv) {
     };
 
     FilamentApp::get().animate([&app](Engine* engine, View* view, double now) {
-        constexpr float ZOOM = 1.5f;
+        constexpr float ZOOM = 1.5;
         const uint32_t w = view->getViewport().width;
         const uint32_t h = view->getViewport().height;
         const float aspect = (float) w / h;
         app.cam->setProjection(Camera::Projection::ORTHO,
             -aspect * ZOOM, aspect * ZOOM,
-            -ZOOM, ZOOM, 0, 1);
+            -ZOOM, ZOOM, -100, 100);
         auto& tcm = engine->getTransformManager();
         tcm.setTransform(tcm.getInstance(app.renderable),
                 filament::math::mat4f::rotation(now, filament::math::float3{ 0, 0, 1 }));
     });
 
-    FilamentApp::get().run(app.config, setup, cleanup);
+
+    auto preRender = [](Engine*, View* view, Scene*, Renderer* renderer) {
+        renderer->setClearOptions({ .clearStencil = 0u, .clear = true,  });
+    };
+
+    FilamentApp::get().run(app.config, setup, cleanup, {}, preRender);
 
     return 0;
 }