Merge branch 'main' into pf/matdbg-fix-collision

Author: poweifeng

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.56.3'
+    implementation 'com.google.android.filament:filament-android:1.56.4'
 }
 ```
 
@@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.56.3'
+pod 'Filament', '~> 1.56.4'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,6 +7,9 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.56.5
+
+
 ## v1.56.4
 
 

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

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

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

@@ -344,9 +344,18 @@ public Material(long nativeMaterial) {
     }
 
     public static class Builder {
+        public enum ShadowSamplingQuality {
+            /** 2x2 PCF */
+            HARD,
+            /** 3x3 gaussian filter */
+            LOW,
+        }
+
         private Buffer mBuffer;
         private int mSize;
         private int mShBandCount = 0;
+        private ShadowSamplingQuality mShadowSamplingQuality = ShadowSamplingQuality.LOW;
+
 
         /**
          * Specifies the material data. The material data is a binary blob produced by
@@ -378,6 +387,18 @@ public Builder sphericalHarmonicsBandCount(@IntRange(from = 0) int shBandCount)
             return this;
         }
 
+        /**
+         * Set the quality of shadow sampling. This is only taken into account
+         * if this material is lit and in the surface domain.
+         * @param quality
+         * @return Reference to this Builder for chaining calls.
+         */
+        @NonNull
+        public Builder shadowSamplingQuality(ShadowSamplingQuality quality) {
+            mShadowSamplingQuality = quality;
+            return this;
+        }
+
         /**
          * Creates and returns the Material object.
          *
@@ -390,7 +411,7 @@ public Builder sphericalHarmonicsBandCount(@IntRange(from = 0) int shBandCount)
         @NonNull
         public Material build(@NonNull Engine engine) {
             long nativeMaterial = nBuilderBuild(engine.getNativeObject(),
-                mBuffer, mSize, mShBandCount);
+                mBuffer, mSize, mShBandCount, mShadowSamplingQuality.ordinal());
             if (nativeMaterial == 0) throw new IllegalStateException("Couldn't create Material");
             return new Material(nativeMaterial);
         }
@@ -1041,7 +1062,7 @@ void clearNativeObject() {
         mNativeObject = 0;
     }
 
-    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount);
+    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount, int shadowQuality);
     private static native long nCreateInstance(long nativeMaterial);
     private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
     private static native long nGetDefaultInstance(long nativeMaterial);

android/gradle.properties

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

docs/Filament.html

@@ -155,6 +155,7 @@ struct MetalContext {
 
     RenderPassFlags currentRenderPassFlags;
     MetalRenderTarget* currentRenderTarget = nullptr;
+    bool validPipelineBound = false;
 
     // State trackers.
     PipelineStateTracker pipelineState;

docs/remote/filament.js

@@ -1657,6 +1657,7 @@
     // during the draw call when the program is invalid. The shader compile error has already been
     // dumped to the console at this point, so it's fine to simply return early.
     if (FILAMENT_ENABLE_MATDBG && UTILS_UNLIKELY(!functions)) {
+        mContext->validPipelineBound = false;
         return;
     }
 
@@ -1789,6 +1790,8 @@
                                                    clamp:0.0];
         mContext->currentPolygonOffset = ps.polygonOffset;
     }
+
+    mContext->validPipelineBound = true;
 }
 
 void MetalDriver::bindRenderPrimitive(Handle<HwRenderPrimitive> rph) {
@@ -1886,6 +1889,10 @@
             << "draw() without a valid command encoder.";
     DEBUG_LOG("draw2(...)\n");
 
+    if (FILAMENT_ENABLE_MATDBG && UTILS_UNLIKELY(!mContext->validPipelineBound)) {
+        return;
+    }
+
     // Bind the offset data.
     if (mContext->dynamicOffsets.isDirty()) {
         const auto [size, data] = mContext->dynamicOffsets.getOffsets();

docs/remote/filament.wasm

@@ -103,6 +103,11 @@ class UTILS_PUBLIC Material : public FilamentAPI {
         Builder& operator=(Builder const& rhs) noexcept;
         Builder& operator=(Builder&& rhs) noexcept;
 
+        enum class ShadowSamplingQuality : uint8_t {
+            HARD,   // 2x2 PCF
+            LOW     // 3x3 gaussian filter
+        };
+
         /**
          * Specifies the material data. The material data is a binary blob produced by
          * libfilamat or by matc.
@@ -152,6 +157,14 @@ class UTILS_PUBLIC Material : public FilamentAPI {
          */
         Builder& sphericalHarmonicsBandCount(size_t shBandCount) noexcept;
 
+        /**
+         * Set the quality of shadow sampling. This is only taken into account
+         * if this material is lit and in the surface domain.
+         * @param quality
+         * @return
+         */
+        Builder& shadowSamplingQuality(ShadowSamplingQuality quality) noexcept;
+
         /**
          * Creates the Material object and returns a pointer to it.
          *

docs/webgl/filament.js

@@ -438,7 +438,7 @@ struct MultiSampleAntiAliasingOptions {
  * @see setTemporalAntiAliasingOptions()
  */
 struct TemporalAntiAliasingOptions {
-    float filterWidth = 1.0f;   //!< reconstruction filter width typically between 0.2 (sharper, aliased) and 1.5 (smoother)
+    float filterWidth = 1.0f;   //!< reconstruction filter width typically between 1 (sharper) and 2 (smoother)
     float feedback = 0.12f;     //!< history feedback, between 0 (maximum temporal AA) and 1 (no temporal AA).
     float lodBias = -1.0f;      //!< texturing lod bias (typically -1 or -2)
     float sharpness = 0.0f;     //!< post-TAA sharpen, especially useful when upscaling is true.

docs/webgl/filament.wasm

@@ -2622,7 +2622,7 @@ void PostProcessManager::TaaJitterCamera(
     current.projection = inoutCameraInfo->projection * inoutCameraInfo->getUserViewMatrix();
     current.frameId = previous.frameId + 1;
 
-    auto jitterPosition = [pattern = taaOptions.jitterPattern](size_t frameIndex){
+    auto jitterPosition = [pattern = taaOptions.jitterPattern](size_t frameIndex) -> float2 {
         using JitterPattern = TemporalAntiAliasingOptions::JitterPattern;
         switch (pattern) {
             case JitterPattern::RGSS_X4:
@@ -2636,6 +2636,7 @@ void PostProcessManager::TaaJitterCamera(
             case JitterPattern::HALTON_23_X32:
                 return sHaltonSamples(frameIndex);
         }
+        return { 0.0f, 0.0f };
     };
 
     // sample position within a pixel [-0.5, 0.5]
@@ -2759,15 +2760,31 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::taa(FrameGraph& fg,
                 }};
 
                 constexpr float2 sampleOffsets[9] = {
-                        { -1.0f, -1.0f }, {  0.0f, -1.0f }, {  1.0f, -1.0f },
-                        { -1.0f,  0.0f }, {  0.0f,  0.0f }, {  1.0f,  0.0f },
-                        { -1.0f,  1.0f }, {  0.0f,  1.0f }, {  1.0f,  1.0f },
+                        { -1.0f, -1.0f }, {  0.0f, -1.0f }, {  1.0f, -1.0f }, { -1.0f,  0.0f },
+                        {  0.0f,  0.0f },
+                        {  1.0f,  0.0f }, { -1.0f,  1.0f }, {  0.0f,  1.0f }, {  1.0f,  1.0f },
                 };
 
                 constexpr float2 subSampleOffsets[4] = {
-                        { -0.25f, 0.25f }, {  0.25f, 0.25f }, { 0.25f, -0.25f }, { -0.25f, -0.25f }
+                        { -0.25f,  0.25f },
+                        {  0.25f,  0.25f },
+                        {  0.25f, -0.25f },
+                        { -0.25f, -0.25f }
                 };
 
+                UTILS_UNUSED
+                auto const lanczos = [](float x, float a) -> float {
+                    if (x <= std::numeric_limits<float>::epsilon()) {
+                        return 1.0f;
+                    }
+                    if (std::abs(x) <= a) {
+                        return (a * std::sin(f::PI * x) * std::sin(f::PI * x / a))
+                               / ((f::PI * f::PI) * (x * x));
+                    }
+                    return 0.0f;
+                };
+
+                float const filterWidth = std::clamp(taaOptions.filterWidth, 1.0f, 2.0f);
                 float4 sum = 0.0;
                 float4 weights[9];
 
@@ -2777,11 +2794,9 @@ FrameGraphId<FrameGraphTexture> PostProcessManager::taa(FrameGraph& fg,
                 for (size_t i = 0; i < 9; i++) {
                     float2 const o = sampleOffsets[i];
                     for (size_t j = 0; j < 4; j++) {
-                        float2 const s = taaOptions.upscaling ? subSampleOffsets[j] : float2{ 0 };
-                        float2 const d = (o - current.jitter - s) / taaOptions.filterWidth;
-                        // This is a gaussian fit of a 3.3-wide Blackman-Harris window
-                        // see: "High Quality Temporal Supersampling" by Brian Karis
-                        weights[i][j] = std::exp(-2.29f * (d.x * d.x + d.y * d.y));
+                        float2 const subPixelOffset = taaOptions.upscaling ? subSampleOffsets[j] : float2{ 0 };
+                        float2 const d = (o - (current.jitter - subPixelOffset)) / filterWidth;
+                        weights[i][j] = lanczos(length(d), filterWidth);
                     }
                     sum += weights[i];
                 }

docs/webgl/triangle.filamat

@@ -428,7 +428,7 @@ class PostProcessManager {
 
     template<size_t SIZE>
     struct JitterSequence {
-        auto operator()(size_t i) const noexcept { return positions[i % SIZE] - 0.5f; }
+        math::float2 operator()(size_t i) const noexcept { return positions[i % SIZE] - 0.5f; }
         const std::array<math::float2, SIZE> positions;
     };
 

filament/backend/src/metal/MetalContext.h

@@ -680,8 +680,6 @@ RenderPass::Command* RenderPass::generateCommandsImpl(RenderPass::CommandTypeFla
         cmd.info.hasMorphing = (bool)morphing.handle;
         cmd.info.hasSkinning = (bool)skinning.handle;
 
-        assert_invariant(cmd.info.hasHybridInstancing || cmd.info.instanceCount <= 1);
-
         // soaInstanceInfo[i].count is the number of instances the user has requested, either for
         // manual or hybrid instancing. Instanced stereo multiplies the number of instances by the
         // eye count.

filament/backend/src/metal/MetalDriver.mm

@@ -123,6 +123,7 @@ struct Material::BuilderDetails {
     size_t mSize = 0;
     bool mDefaultMaterial = false;
     int32_t mShBandsCount = 3;
+    Builder::ShadowSamplingQuality mShadowSamplingQuality = Builder::ShadowSamplingQuality::LOW;
     std::unordered_map<
         utils::CString,
         std::variant<int32_t, float, bool>,
@@ -152,6 +153,11 @@ Material::Builder& Material::Builder::sphericalHarmonicsBandCount(size_t shBandC
     return *this;
 }
 
+Material::Builder& Material::Builder::shadowSamplingQuality(ShadowSamplingQuality quality) noexcept {
+    mImpl->mShadowSamplingQuality = quality;
+    return *this;
+}
+
 template<typename T, typename>
 Material::Builder& Material::Builder::constant(const char* name, size_t nameLength, T value) {
     FILAMENT_CHECK_PRECONDITION(name != nullptr) << "name cannot be null";
@@ -550,7 +556,7 @@ Program FMaterial::getProgramWithVariants(
             << "The material '" << mName.c_str()
             << "' has not been compiled to include the required GLSL or SPIR-V chunks for the "
                "vertex shader (variant="
-            << variant.key << ", filtered=" << vertexVariant.key << ").";
+            << +variant.key << ", filtered=" << +vertexVariant.key << ").";
 
     /*
      * Fragment shader
@@ -565,7 +571,7 @@ Program FMaterial::getProgramWithVariants(
             << "The material '" << mName.c_str()
             << "' has not been compiled to include the required GLSL or SPIR-V chunks for the "
                "fragment shader (variant="
-            << variant.key << ", filtered=" << ").";
+            << +variant.key << ", filtered=" << +fragmentVariant.key << ").";
 
     Program program;
     program.shader(ShaderStage::VERTEX, vsBuilder.data(), vsBuilder.size())
@@ -996,7 +1002,11 @@ void FMaterial::processSpecializationConstants(FEngine& engine, Material::Builde
             +ReservedSpecializationConstants::CONFIG_STEREO_EYE_COUNT,
             (int)engine.getConfig().stereoscopicEyeCount });
     mSpecializationConstants.push_back({
-            +ReservedSpecializationConstants::CONFIG_SH_BANDS_COUNT, builder->mShBandsCount });
+            +ReservedSpecializationConstants::CONFIG_SH_BANDS_COUNT,
+            builder->mShBandsCount });
+    mSpecializationConstants.push_back({
+            +ReservedSpecializationConstants::CONFIG_SHADOW_SAMPLING_METHOD,
+            (int32_t)builder->mShadowSamplingQuality });
     if (UTILS_UNLIKELY(parser->getShaderLanguage() == ShaderLanguage::ESSL1)) {
         // The actual value of this spec-constant is set in the OpenGLDriver backend.
         mSpecializationConstants.push_back({

filament/include/filament/Material.h

@@ -149,7 +149,7 @@ void DescriptorSet::setSampler(
 
 DescriptorSet DescriptorSet::duplicate(DescriptorSetLayout const& layout) const noexcept {
     DescriptorSet set{layout};
-    memcpy(set.mDescriptors.data(), mDescriptors.data(), mDescriptors.size() * sizeof(Desc));
+    set.mDescriptors = mDescriptors; // Use the vector's assignment operator
     set.mDirty = mDirty;
     set.mValid = mValid;
     return set;