Merge branch 'rc/1.52.0' into release

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.51.8'
+    implementation 'com.google.android.filament:filament-android:1.52.0'
 }
 ```
 
@@ -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.51.8'
+pod 'Filament', '~> 1.52.0'
 ```
 
 ### Snapshots

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.52.0
+
+
 ## v1.51.8
 
 - filagui: Fix regression which broke WebGL

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

@@ -518,6 +518,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
         jint stereoscopicType, jlong stereoscopicEyeCount,
         jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
         jboolean disableHandleUseAfterFreeCheck,
+        jint preferredShaderLanguage,
         jboolean forceGLES2Context) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     Engine::Config config = {
@@ -534,7 +535,8 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .resourceAllocatorCacheSizeMB = (uint32_t) resourceAllocatorCacheSizeMB,
             .resourceAllocatorCacheMaxAge = (uint8_t) resourceAllocatorCacheMaxAge,
             .disableHandleUseAfterFreeCheck = (bool) disableHandleUseAfterFreeCheck,
-            .forceGLES2Context = (bool) forceGLES2Context
+            .preferredShaderLanguage = (Engine::Config::ShaderLanguage) preferredShaderLanguage,
+            .forceGLES2Context = (bool) forceGLES2Context,
     };
     builder->config(&config);
 }

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

@@ -244,13 +244,25 @@ Java_com_google_android_filament_RenderableManager_nBuilderMorphing(JNIEnv*, jcl
     builder->morphing(targetCount);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderMorphingStandard(JNIEnv*, jclass,
+        jlong nativeBuilder, jlong nativeMorphTargetBuffer) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
+    builder->morphing(morphTargetBuffer);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nBuilderSetMorphTargetBufferAt(JNIEnv*, jclass,
         jlong nativeBuilder, int level, int primitiveIndex, jlong nativeMorphTargetBuffer,
         int offset, int count) {
     RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
-    MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
-    builder->morphing(level, primitiveIndex, morphTargetBuffer, offset, count);
+    if (nativeMorphTargetBuffer) {
+        MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
+        builder->morphing(level, primitiveIndex, morphTargetBuffer, offset, count);
+    } else {
+        builder->morphing(level, primitiveIndex, offset, count);
+    }
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -326,9 +338,14 @@ Java_com_google_android_filament_RenderableManager_nSetMorphTargetBufferAt(JNIEn
         jclass, jlong nativeRenderableManager, jint i, int level, jint primitiveIndex,
         jlong nativeMorphTargetBuffer, jint offset, jint count) {
     RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
-    MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
-    rm->setMorphTargetBufferAt((RenderableManager::Instance) i, (uint8_t) level,
-            (size_t) primitiveIndex, morphTargetBuffer, (size_t) offset, (size_t) count);
+    if (nativeMorphTargetBuffer) {
+        MorphTargetBuffer *morphTargetBuffer = (MorphTargetBuffer *) nativeMorphTargetBuffer;
+        rm->setMorphTargetBufferAt((RenderableManager::Instance) i, (uint8_t) level,
+                (size_t) primitiveIndex, morphTargetBuffer, (size_t) offset, (size_t) count);
+    } else {
+        rm->setMorphTargetBufferAt((RenderableManager::Instance) i, (uint8_t) level,
+                (size_t) primitiveIndex, (size_t) offset, (size_t) count);
+    }
 }
 
 extern "C" JNIEXPORT jint JNICALL

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

@@ -226,6 +226,7 @@ public Builder config(Config config) {
                     config.stereoscopicType.ordinal(), config.stereoscopicEyeCount,
                     config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
                     config.disableHandleUseAfterFreeCheck,
+                    config.preferredShaderLanguage.ordinal(),
                     config.forceGLES2Context);
             return this;
         }
@@ -430,6 +431,28 @@ public static class Config {
          */
         public boolean disableHandleUseAfterFreeCheck = false;
 
+        /*
+         * Sets a preferred shader language for Filament to use.
+         *
+         * The Metal backend supports two shader languages: MSL (Metal Shading Language) and
+         * METAL_LIBRARY (precompiled .metallib). This option controls which shader language is
+         * used when materials contain both.
+         *
+         * By default, when preferredShaderLanguage is unset, Filament will prefer METAL_LIBRARY
+         * shaders if present within a material, falling back to MSL. Setting
+         * preferredShaderLanguage to ShaderLanguage::MSL will instead instruct Filament to check
+         * for the presence of MSL in a material first, falling back to METAL_LIBRARY if MSL is not
+         * present.
+         *
+         * When using a non-Metal backend, setting this has no effect.
+         */
+        public enum ShaderLanguage {
+            DEFAULT,
+            MSL,
+            METAL_LIBRARY,
+        };
+        public ShaderLanguage preferredShaderLanguage = ShaderLanguage.DEFAULT;
+
         /*
          * When the OpenGL ES backend is used, setting this value to true will force a GLES2.0
          * context if supported by the Platform, or if not, will have the backend pretend
@@ -1362,6 +1385,7 @@ private static native void nSetBuilderConfig(long nativeBuilder, long commandBuf
             int stereoscopicType, long stereoscopicEyeCount,
             long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
             boolean disableHandleUseAfterFreeCheck,
+            int preferredShaderLanguage,
             boolean forceGLES2Context);
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);

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

@@ -524,14 +524,7 @@ public Builder skinning(@IntRange(from = 0, to = 255) int boneCount, @NonNull Bu
         }
 
         /**
-         * Controls if the renderable has vertex morphing targets, zero by default. This is
-         * required to enable GPU morphing.
-         *
-         * <p>Filament supports two morphing modes: standard (default) and legacy.</p>
-         *
-         * <p>For standard morphing, A {@link MorphTargetBuffer} must be created and provided via
-         * {@link RenderableManager#setMorphTargetBufferAt}. Standard morphing supports up to
-         * <code>CONFIG_MAX_MORPH_TARGET_COUNT</code> morph targets.</p>
+         * Controls if the renderable has legacy vertex morphing targets, zero by default.
          *
          * For legacy morphing, the attached {@link VertexBuffer} must provide data in the
          * appropriate {@link VertexBuffer.VertexAttribute} slots (<code>MORPH_POSITION_0</code> etc).
@@ -549,6 +542,22 @@ public Builder morphing(@IntRange(from = 0, to = 255) int targetCount) {
             return this;
         }
 
+        /**
+         * Controls if the renderable has vertex morphing targets, zero by default.
+         *
+         * <p>For standard morphing, A {@link MorphTargetBuffer} must be provided.
+         * Standard morphing supports up to
+         * <code>CONFIG_MAX_MORPH_TARGET_COUNT</code> morph targets.</p>
+         *
+         * <p>See also {@link RenderableManager#setMorphWeights}, which can be called on a per-frame basis
+         * to advance the animation.</p>
+         */
+        @NonNull
+        public Builder morphing(@NonNull MorphTargetBuffer morphTargetBuffer) {
+            nBuilderMorphingStandard(mNativeBuilder, morphTargetBuffer.getNativeObject());
+            return this;
+        }
+
         /**
          * Specifies the morph target buffer for a primitive.
          *
@@ -565,6 +574,17 @@ public Builder morphing(@IntRange(from = 0, to = 255) int targetCount) {
          * @param count number of vertices in the morph target buffer to read, must equal the geometry's count (for triangles, this should be a multiple of 3)
          */
         @NonNull
+        public Builder morphing(@IntRange(from = 0) int level,
+                                @IntRange(from = 0) int primitiveIndex,
+                                @IntRange(from = 0) int offset,
+                                @IntRange(from = 0) int count) {
+            nBuilderSetMorphTargetBufferAt(mNativeBuilder, level, primitiveIndex, 0, offset, count);
+            return this;
+        }
+
+        /** @deprecated */
+        @Deprecated
+        @NonNull
         public Builder morphing(@IntRange(from = 0) int level,
                                 @IntRange(from = 0) int primitiveIndex,
                                 @NonNull MorphTargetBuffer morphTargetBuffer,
@@ -575,10 +595,8 @@ public Builder morphing(@IntRange(from = 0) int level,
             return this;
         }
 
-        /**
-         * Utility method to specify morph target buffer for a primitive.
-         * For details, see the {@link RenderableManager.Builder#morphing}.
-         */
+        /** @deprecated */
+        @Deprecated
         @NonNull
         public Builder morphing(@IntRange(from = 0) int level,
                                 @IntRange(from = 0) int primitiveIndex,
@@ -687,6 +705,16 @@ public void setMorphWeights(@EntityInstance int i, @NonNull float[] weights, @In
      *
      * @see Builder#morphing
      */
+    public void setMorphTargetBufferAt(@EntityInstance int i,
+                                       @IntRange(from = 0) int level,
+                                       @IntRange(from = 0) int primitiveIndex,
+                                       @IntRange(from = 0) int offset,
+                                       @IntRange(from = 0) int count) {
+        nSetMorphTargetBufferAt(mNativeObject, i, level, primitiveIndex, 0, offset, count);
+    }
+
+    /** @deprecated */
+    @Deprecated
     public void setMorphTargetBufferAt(@EntityInstance int i,
                                        @IntRange(from = 0) int level,
                                        @IntRange(from = 0) int primitiveIndex,
@@ -697,10 +725,8 @@ public void setMorphTargetBufferAt(@EntityInstance int i,
                 morphTargetBuffer.getNativeObject(), offset, count);
     }
 
-    /**
-     * Utility method to change morph target buffer for the given primitive.
-     * For details, see the {@link RenderableManager#setMorphTargetBufferAt}.
-     */
+    /** @deprecated */
+    @Deprecated
     public void setMorphTargetBufferAt(@EntityInstance int i,
                                        @IntRange(from = 0) int level,
                                        @IntRange(from = 0) int primitiveIndex,
@@ -1006,6 +1032,7 @@ public long getNativeObject() {
     private static native int nBuilderSkinningBones(long nativeBuilder, int boneCount, Buffer bones, int remaining);
     private static native void nBuilderSkinningBuffer(long nativeBuilder, long nativeSkinningBuffer, int boneCount, int offset);
     private static native void nBuilderMorphing(long nativeBuilder, int targetCount);
+    private static native void nBuilderMorphingStandard(long nativeBuilder, long nativeMorphTargetBuffer);
     private static native void nBuilderSetMorphTargetBufferAt(long nativeBuilder, int level, int primitiveIndex, long nativeMorphTargetBuffer, int offset, int count);
     private static native void nBuilderEnableSkinningBuffers(long nativeBuilder, boolean enabled);
     private static native void nBuilderFog(long nativeBuilder, boolean enabled);

android/gradle.properties

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

filament/backend/CMakeLists.txt

@@ -417,7 +417,9 @@ if (APPLE OR LINUX)
         test/test_MissingRequiredAttributes.cpp
         test/test_ReadPixels.cpp
         test/test_BufferUpdates.cpp
+        test/test_Callbacks.cpp
         test/test_MRT.cpp
+        test/test_PushConstants.cpp
         test/test_LoadImage.cpp
         test/test_StencilBuffer.cpp
         test/test_Scissor.cpp
@@ -478,6 +480,10 @@ if (APPLE)
        # linker from removing "unused" symbols.
        target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
        set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
+
+       # This is needed after XCode 15.3
+       set_target_properties(backend_test_mac PROPERTIES BUILD_WITH_INSTALL_RPATH TRUE)
+       set_target_properties(backend_test_mac PROPERTIES INSTALL_RPATH /usr/local/lib)
     endif()
 endif()
 

filament/backend/include/backend/DriverEnums.h

@@ -24,12 +24,14 @@
 
 #include <backend/PresentCallable.h>
 
+#include <utils/Invocable.h>
 #include <utils/ostream.h>
 
 #include <math/vec4.h>
 
 #include <array>        // FIXME: STL headers are not allowed in public headers
 #include <type_traits>  // FIXME: STL headers are not allowed in public headers
+#include <variant>      // FIXME: STL headers are not allowed in public headers
 
 #include <stddef.h>
 #include <stdint.h>
@@ -90,12 +92,15 @@ static constexpr uint64_t SWAP_CHAIN_HAS_STENCIL_BUFFER         = SWAP_CHAIN_CON
  */
 static constexpr uint64_t SWAP_CHAIN_CONFIG_PROTECTED_CONTENT   = 0x40;
 
-
 static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT  = 16;   // This is guaranteed by OpenGL ES.
 static constexpr size_t MAX_SAMPLER_COUNT           = 62;   // Maximum needed at feature level 3.
 static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
 static constexpr size_t MAX_SSBO_COUNT              = 4;    // This is guaranteed by OpenGL ES.
 
+static constexpr size_t MAX_PUSH_CONSTANT_COUNT     = 32;   // Vulkan 1.1 spec allows for 128-byte
+                                                            // of push constant (we assume 4-byte
+                                                            // types).
+
 // Per feature level caps
 // Use (int)FeatureLevel to index this array
 static constexpr struct {
@@ -112,7 +117,7 @@ static_assert(MAX_VERTEX_BUFFER_COUNT <= MAX_VERTEX_ATTRIBUTE_COUNT,
         "The number of buffer objects that can be attached to a VertexBuffer must be "
         "less than or equal to the maximum number of vertex attributes.");
 
-static constexpr size_t CONFIG_UNIFORM_BINDING_COUNT = 10;  // This is guaranteed by OpenGL ES.
+static constexpr size_t CONFIG_UNIFORM_BINDING_COUNT = 9;   // This is guaranteed by OpenGL ES.
 static constexpr size_t CONFIG_SAMPLER_BINDING_COUNT = 4;   // This is guaranteed by OpenGL ES.
 
 /**
@@ -331,7 +336,7 @@ enum class UniformType : uint8_t {
 /**
  * Supported constant parameter types
  */
- enum class ConstantType : uint8_t {
+enum class ConstantType : uint8_t {
   INT,
   FLOAT,
   BOOL
@@ -1218,13 +1223,15 @@ struct StencilState {
     uint8_t padding = 0;
 };
 
+using PushConstantVariant = std::variant<int32_t, float, bool>;
+
 static_assert(sizeof(StencilState::StencilOperations) == 5u,
         "StencilOperations size not what was intended");
 
 static_assert(sizeof(StencilState) == 12u,
         "StencilState size not what was intended");
 
-using FrameScheduledCallback = void(*)(PresentCallable callable, void* user);
+using FrameScheduledCallback = utils::Invocable<void(backend::PresentCallable)>;
 
 enum class Workaround : uint16_t {
     // The EASU pass must split because shader compiler flattens early-exit branch

filament/backend/include/backend/PresentCallable.h

@@ -48,7 +48,7 @@ namespace filament::backend {
  * and optional user data:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * swapChain->setFrameScheduledCallback(myFrameScheduledCallback, nullptr);
+ * swapChain->setFrameScheduledCallback(nullptr, myFrameScheduledCallback);
  * if (renderer->beginFrame(swapChain)) {
  *     renderer->render(view);
  *     renderer->endFrame();
@@ -58,8 +58,6 @@ namespace filament::backend {
  * @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
  * backends ignore the callback (which will never be called) and proceed normally.
  *
- * @remark The SwapChain::FrameScheduledCallback is called on an arbitrary thread.
- *
  * Applications *must* call each PresentCallable they receive. Each PresentCallable represents a
  * frame that is waiting to be presented. If an application fails to call a PresentCallable, a
  * memory leak could occur. To "cancel" the presentation of a frame, pass false to the

filament/backend/include/backend/Program.h

@@ -117,6 +117,14 @@ class Program {
     Program& specializationConstants(
             utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;
 
+    struct PushConstant {
+        utils::CString name;
+        ConstantType type;
+    };
+
+    Program& pushConstants(ShaderStage stage,
+            utils::FixedCapacityVector<PushConstant> constants) noexcept;
+
     Program& cacheId(uint64_t cacheId) noexcept;
 
     Program& multiview(bool multiview) noexcept;
@@ -148,6 +156,15 @@ class Program {
         return mSpecializationConstants;
     }
 
+    utils::FixedCapacityVector<PushConstant> const& getPushConstants(
+            ShaderStage stage) const noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
+    utils::FixedCapacityVector<PushConstant>& getPushConstants(ShaderStage stage) noexcept {
+        return mPushConstants[static_cast<uint8_t>(stage)];
+    }
+
     uint64_t getCacheId() const noexcept { return mCacheId; }
 
     bool isMultiview() const noexcept { return mMultiview; }
@@ -165,6 +182,7 @@ class Program {
     uint64_t mCacheId{};
     utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
     utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
+    std::array<utils::FixedCapacityVector<PushConstant>, SHADER_TYPE_COUNT> mPushConstants;
     utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> mAttributes;
     std::array<UniformInfo, Program::UNIFORM_BINDING_COUNT> mBindingUniformInfo;
     CompilerPriorityQueue mPriorityQueue = CompilerPriorityQueue::HIGH;