Materials: add useDefaultDepthVariant flag (#9020)

NEW_RELEASE_NOTES.md

@@ -10,3 +10,5 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 - engine: add a `linearFog` material parameter. [⚠️ **New Material Version**]
 - opengl: When `Material::compile()` is called on a platform which doesn't support parallel compilation, shaders are automatically compiled over a number of frames
+- Added `useDefaultDepthVariant` material parameter to force Filament to use its default variant for
+  depth-only passes. [**Requires recompiling materials**]

docs_src/src_markdeep/Materials.md.html

@@ -1281,6 +1281,45 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: useDefaultDepthVariant
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    This parameter forces Filament to use its default variant for depth passes, such as those used
+     in shadow rendering. This provides an optimization for materials with expensive custom vertex
+     shaders. For example, custom vertex shader computations intended to be consumed by the fragment
+     stage can be skipped during the depth-only pass. This parameter is only meaningful if the
+     material has a vertex block.
+     This parameter should not be set to `true` for vertex blocks that modify geometry (i.e.,
+     modifying `worldPosition`), otherwise shadows may render incorrectly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    variables : [
+        customColor
+    ],
+    useDefaultDepthVariant : true
+}
+
+vertex {
+    void materialVertex(inout MaterialVertexInputs material) {
+        material.customColor = /* expensive computation that can be skipped for depth-only passes */
+    }
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = variable_customColor;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Vertex and attributes: requires
 
 Type

libs/filamat/include/filamat/MaterialBuilder.h

@@ -638,6 +638,12 @@ public:
     //! specify compute kernel group size
     MaterialBuilder& groupSize(filament::math::uint3 groupSize) noexcept;
 
+    /**
+     * Force Filament to use its default variant for depth passes. Useful if a material provides a
+     * custom vertex shader which can be skipped during depth-only passes.
+     */
+    MaterialBuilder& useDefaultDepthVariant() noexcept;
+
     /**
      * Build the material. If you are using the Filament engine with this library, you should use
      * the job system provided by Engine.
@@ -972,6 +978,8 @@ private:
     filament::UserVariantFilterMask mVariantFilter = {};
 
     bool mNoSamplerValidation = false;
+
+    bool mUseDefaultDepthVariant = false;
 };
 
 } // namespace filamat

libs/filamat/src/MaterialBuilder.cpp

@@ -404,6 +404,11 @@ MaterialBuilder& MaterialBuilder::groupSize(math::uint3 const groupSize) noexcep
     return *this;
 }
 
+MaterialBuilder& MaterialBuilder::useDefaultDepthVariant() noexcept {
+    mUseDefaultDepthVariant = true;
+    return *this;
+}
+
 MaterialBuilder& MaterialBuilder::materialDomain(
         MaterialDomain const materialDomain) noexcept {
     mMaterialDomain = materialDomain;
@@ -931,7 +936,8 @@ bool MaterialBuilder::generateShaders(JobSystem& jobSystem, const std::vector<Va
             mMaterialVertexCode.getResolved(), mMaterialVertexCode.getLineOffset(),
             mMaterialDomain);
 
-    container.emplace<bool>(MaterialHasCustomDepthShader, needsStandardDepthProgram());
+    container.emplace<bool>(MaterialHasCustomDepthShader,
+            needsStandardDepthProgram() && !mUseDefaultDepthVariant);
 
     std::atomic_bool cancelJobs(false);
     bool firstJob = true;

libs/filament-matp/src/ParametersProcessor.cpp

@@ -1355,6 +1355,13 @@ static bool processVariantFilter(MaterialBuilder& builder, const JsonishValue& v
     return true;
 }
 
+static bool processUseDefaultDepthVariant(MaterialBuilder& builder, const JsonishValue& value) {
+    if (value.toJsonBool()->getBool()) {
+        builder.useDefaultDepthVariant();
+    }
+    return true;
+}
+
 ParametersProcessor::ParametersProcessor() {
     using Type = JsonishValue::Type;
     mParameters["name"]                          = { &processName, Type::STRING };
@@ -1402,6 +1409,7 @@ ParametersProcessor::ParametersProcessor() {
     mParameters["featureLevel"]                  = { &processFeatureLevel, Type::NUMBER };
     mParameters["groupSize"]                     = { &processGroupSizes, Type::ARRAY };
     mParameters["stereoscopicType"]              = { &processStereoscopicType, Type::STRING };
+    mParameters["useDefaultDepthVariant"]        = { &processUseDefaultDepthVariant, Type::BOOL };
     mParameters["linearFog"]                     = { &processLinearFog, Type::BOOL };
 }