Merge branch 'rc/1.56.1' into release

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.56.0'
+    implementation 'com.google.android.filament:filament-android:1.56.1'
 }
 ```
 
@@ -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.0'
+pod 'Filament', '~> 1.56.1'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,6 +7,8 @@ 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.1
+
 ## v1.56.0
 
 - backend: descriptor layouts distinguish samplers and external samplers (b/376089915) [⚠️ **New Material Version**]

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

@@ -499,6 +499,37 @@ Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
     return (jint)engine->getActiveFeatureLevel();
 }
 
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nHasFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    std::optional<bool> result = engine->getFeatureFlag(name);
+    env->ReleaseStringUTFChars(name_, name);
+    return result.has_value();
+}
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nSetFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_, jboolean value) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    jboolean result = engine->setFeatureFlag(name, (bool)value);
+    env->ReleaseStringUTFChars(name_, name);
+    return result;
+}
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nGetFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    std::optional<bool> result = engine->getFeatureFlag(name);
+    env->ReleaseStringUTFChars(name_, name);
+    return result.value_or(false); // we should never fail here
+}
+
 extern "C" JNIEXPORT jlong JNICALL Java_com_google_android_filament_Engine_nCreateBuilder(JNIEnv*,
         jclass) {
     Engine::Builder* builder = new Engine::Builder{};
@@ -565,6 +596,16 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
     builder->paused((bool) paused);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nSetBuilderFeature(JNIEnv *env, jclass clazz,
+        jlong nativeBuilder, jstring name_, jboolean value) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    builder->feature(name, (bool)value);
+    env->ReleaseStringUTFChars(name_, name);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;

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

@@ -258,6 +258,17 @@ public Builder paused(boolean paused) {
             return this;
         }
 
+        /**
+         * Set a feature flag value. This is the only way to set constant feature flags.
+         * @param name feature name
+         * @param value true to enable, false to disable
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder feature(@NonNull String name, boolean value) {
+            nSetBuilderFeature(mNativeBuilder, name, value);
+            return this;
+        }
+
         /**
          * Creates an instance of Engine
          *
@@ -393,6 +404,7 @@ public static class Config {
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL backend.
+         * @Deprecated use "backend.disable_parallel_shader_compile" feature flag instead
          */
         public boolean disableParallelShaderCompile = false;
 
@@ -433,6 +445,7 @@ public static class Config {
 
         /**
          * Disable backend handles use-after-free checks.
+         * @Deprecated use "backend.disable_handle_use_after_free_check" feature flag instead
          */
         public boolean disableHandleUseAfterFreeCheck = false;
 
@@ -469,6 +482,7 @@ public enum ShaderLanguage {
          * Assert the native window associated to a SwapChain is valid when calling makeCurrent().
          * This is only supported for:
          *      - PlatformEGLAndroid
+         * @Deprecated use "backend.opengl.assert_native_window_is_valid" feature flag instead
          */
         public boolean assertNativeWindowIsValid = false;
     }
@@ -693,11 +707,11 @@ public Config getConfig() {
 
     /**
      * Returns the maximum number of stereoscopic eyes supported by Filament. The actual number of
-     * eyes rendered is set at Engine creation time with the {@link
-     * Engine#Config#stereoscopicEyeCount} setting.
+     * eyes rendered is set at Engine creation time with the {@link Config#stereoscopicEyeCount}
+     * setting.
      *
      * @return the max number of stereoscopic eyes supported
-     * @see Engine#Config#stereoscopicEyeCount
+     * @see Config#stereoscopicEyeCount
      */
     public long getMaxStereoscopicEyes() {
         return nGetMaxStereoscopicEyes(getNativeObject());
@@ -894,7 +908,8 @@ public boolean isValidMaterial(@NonNull Material object) {
 
     /**
      * Returns whether the object is valid.
-     * @param object Object to check for validity
+     * @param ma Material
+     * @param mi MaterialInstance to check for validity
      * @return returns true if the specified object is valid.
      */
     public boolean isValidMaterialInstance(@NonNull Material ma, MaterialInstance mi) {
@@ -1316,6 +1331,39 @@ public void unprotected() {
      */
     public static native long getSteadyClockTimeNano();
 
+
+    /**
+     * Checks if a feature flag exists
+     * @param name name of the feature flag to check
+     * @return true if it exists false otherwise
+     */
+    public boolean hasFeatureFlag(@NonNull String name) {
+        return nHasFeatureFlag(mNativeObject, name);
+    }
+
+    /**
+     * Set the value of a non-constant feature flag.
+     * @param name name of the feature flag to set
+     * @param value value to set
+     * @return true if the value was set, false if the feature flag is constant or doesn't exist.
+     */
+    public boolean setFeatureFlag(@NonNull String name, boolean value) {
+        return nSetFeatureFlag(mNativeObject, name, value);
+    }
+
+    /**
+     * Retrieves the value of any feature flag.
+     * @param name name of the feature flag
+     * @return the value of the flag if it exists
+     * @exception IllegalArgumentException is thrown if the feature flag doesn't exist
+     */
+    public boolean getFeatureFlag(@NonNull String name) {
+        if (!hasFeatureFlag(name)) {
+            throw new IllegalArgumentException("The feature flag \"" + name + "\" doesn't exist");
+        }
+        return nGetFeatureFlag(mNativeObject, name);
+    }
+
     @UsedByReflection("TextureHelper.java")
     public long getNativeObject() {
         if (mNativeObject == 0) {
@@ -1405,6 +1453,9 @@ private static void assertDestroy(boolean success) {
     private static native int nGetSupportedFeatureLevel(long nativeEngine);
     private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
     private static native int nGetActiveFeatureLevel(long nativeEngine);
+    private static native boolean nHasFeatureFlag(long nativeEngine, String name);
+    private static native boolean nSetFeatureFlag(long nativeEngine, String name, boolean value);
+    private static native boolean nGetFeatureFlag(long nativeEngine, String name);
 
     private static native long nCreateBuilder();
     private static native void nDestroyBuilder(long nativeBuilder);
@@ -1420,5 +1471,6 @@ private static native void nSetBuilderConfig(long nativeBuilder, long commandBuf
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
     private static native void nSetBuilderPaused(long nativeBuilder, boolean paused);
+    private static native void nSetBuilderFeature(long nativeBuilder, String name, boolean value);
     private static native long nBuilderBuild(long nativeBuilder);
 }

android/gradle.properties

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

android/samples/sample-hello-triangle/src/main/java/com/google/android/filament/hellotriangle/MainActivity.kt

@@ -112,7 +112,13 @@ class MainActivity : Activity() {
     }
 
     private fun setupFilament() {
-        engine = Engine.Builder().featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0).build()
+        val config = Engine.Config()
+        //config.forceGLES2Context = true
+
+        engine = Engine.Builder()
+            .config(config)
+            .featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0)
+            .build()
         renderer = engine.createRenderer()
         scene = engine.createScene()
         view = engine.createView()
@@ -123,7 +129,9 @@ class MainActivity : Activity() {
         scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
 
         // post-processing is not supported at feature level 0
-        view.isPostProcessingEnabled = false
+        if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
+            view.isPostProcessingEnabled = false
+        }
 
         // Tell the view which camera we want to use
         view.camera = camera

filament/backend/src/metal/MetalDriver.mm

@@ -861,10 +861,20 @@
 
 void MetalDriver::destroyDescriptorSet(Handle<HwDescriptorSet> dsh) {
     DEBUG_LOG("destroyDescriptorSet(dsh = %d)\n", dsh.getId());
-    if (dsh) {
-        executeAfterCurrentCommandBufferCompletes(
-                [this, dsh]() mutable { destruct_handle<MetalDescriptorSet>(dsh); });
+    if (!dsh) {
+        return;
+    }
+
+    // Unbind this descriptor set.
+    auto* descriptorSet = handle_cast<MetalDescriptorSet>(dsh);
+    for (size_t i = 0; i < MAX_DESCRIPTOR_SET_COUNT; i++) {
+        if (UTILS_UNLIKELY(mContext->currentDescriptorSets[i] == descriptorSet)) {
+            mContext->currentDescriptorSets[i] = nullptr;
+        }
     }
+
+    executeAfterCurrentCommandBufferCompletes(
+            [this, dsh]() mutable { destruct_handle<MetalDescriptorSet>(dsh); });
 }
 
 void MetalDriver::terminate() {

filament/backend/src/opengl/OpenGLContext.cpp

@@ -614,7 +614,7 @@ FeatureLevel OpenGLContext::resolveFeatureLevel(GLint major, GLint minor,
                 featureLevel = FeatureLevel::FEATURE_LEVEL_2;
                 if (gets.max_texture_image_units >= MAX_FRAGMENT_SAMPLER_COUNT &&
                     gets.max_combined_texture_image_units >=
-                    (MAX_FRAGMENT_SAMPLER_COUNT + MAX_VERTEX_SAMPLER_COUNT)) {
+                            (MAX_FRAGMENT_SAMPLER_COUNT + MAX_VERTEX_SAMPLER_COUNT)) {
                     featureLevel = FeatureLevel::FEATURE_LEVEL_3;
                 }
             }
@@ -623,15 +623,13 @@ FeatureLevel OpenGLContext::resolveFeatureLevel(GLint major, GLint minor,
 #   ifndef IOS // IOS is guaranteed to have ES3.x
     else if (UTILS_UNLIKELY(major == 2)) {
         // Runtime OpenGL version is ES 2.x
-#       if defined(BACKEND_OPENGL_LEVEL_GLES30)
-        // mandatory extensions (all supported by Mali-400 and Adreno 304)
-        assert_invariant(exts.OES_depth_texture);
-        assert_invariant(exts.OES_depth24);
-        assert_invariant(exts.OES_packed_depth_stencil);
-        assert_invariant(exts.OES_rgb8_rgba8);
-        assert_invariant(exts.OES_standard_derivatives);
-        assert_invariant(exts.OES_texture_npot);
-#       endif
+        // note: mandatory extensions (all supported by Mali-400 and Adreno 304)
+        //      OES_depth_texture
+        //      OES_depth24
+        //      OES_packed_depth_stencil
+        //      OES_rgb8_rgba8
+        //      OES_standard_derivatives
+        //      OES_texture_npot
         featureLevel = FeatureLevel::FEATURE_LEVEL_0;
     }
 #   endif // IOS

filament/backend/src/opengl/OpenGLDriver.cpp

@@ -394,24 +394,21 @@ void OpenGLDriver::bindTexture(GLuint unit, GLTexture const* t) noexcept {
 }
 
 bool OpenGLDriver::useProgram(OpenGLProgram* p) noexcept {
-    if (UTILS_UNLIKELY(mBoundProgram == p)) {
-        // program didn't change, don't do anything.
-        return true;
-    }
-
-    // compile/link the program if needed and call glUseProgram
-    bool const success = p->use(this, mContext);
-    assert_invariant(success == p->isValid());
-
-    if (success) {
-        // TODO: we could even improve this if the program could tell us which of the descriptors
-        //       bindings actually changed. In practice, it is likely that set 0 or 1 might not
-        //       change often.
-        decltype(mInvalidDescriptorSetBindings) changed;
-        changed.setValue((1 << MAX_DESCRIPTOR_SET_COUNT) - 1);
-        mInvalidDescriptorSetBindings |= changed;
-
-        mBoundProgram = p;
+    bool success = true;
+    if (mBoundProgram != p) {
+        // compile/link the program if needed and call glUseProgram
+        success = p->use(this, mContext);
+        assert_invariant(success == p->isValid());
+        if (success) {
+            // TODO: we could even improve this if the program could tell us which of the descriptors
+            //       bindings actually changed. In practice, it is likely that set 0 or 1 might not
+            //       change often.
+            decltype(mInvalidDescriptorSetBindings) changed;
+            changed.setValue((1 << MAX_DESCRIPTOR_SET_COUNT) - 1);
+            mInvalidDescriptorSetBindings |= changed;
+
+            mBoundProgram = p;
+        }
     }
 
     if (UTILS_UNLIKELY(mContext.isES2() && success)) {

filament/backend/src/opengl/OpenGLProgram.cpp

@@ -255,7 +255,9 @@ void OpenGLProgram::updateUniforms(
     for (size_t i = 0, c = records.uniforms.size(); i < c; i++) {
         Program::Uniform const& u = records.uniforms[i];
         GLint const loc = records.locations[i];
-        if (loc < 0) {
+        // mRec709Location is special, it is handled by setRec709ColorSpace() and the corresponding
+        // entry in `buffer` is typically not initialized, so we skip it.
+        if (loc < 0 || loc == mRec709Location) {
             continue;
         }
         // u.offset is in 'uint32_t' units

filament/backend/src/vulkan/VulkanAsyncHandles.h

@@ -30,43 +30,20 @@ namespace filament::backend {
 
 // Wrapper to enable use of shared_ptr for implementing shared ownership of low-level Vulkan fences.
 struct VulkanCmdFence {
-    struct SetValueScope {
-    public:
-        ~SetValueScope() {
-            mHolder->mutex.unlock();
-            mHolder->condition.notify_all();
-        }
-
-    private:
-        SetValueScope(VulkanCmdFence* fenceHolder, VkResult result) :
-            mHolder(fenceHolder) {
-            mHolder->mutex.lock();
-            mHolder->status.store(result);
-        }
-        VulkanCmdFence* mHolder;
-        friend struct VulkanCmdFence;
-    };
-
-    VulkanCmdFence(VkFence ifence);
-    ~VulkanCmdFence() = default;
-
-    SetValueScope setValue(VkResult value) {
-        return {this, value};
+    VulkanCmdFence(VkResult initialStatus) {
+        // Internally we use the VK_INCOMPLETE status to mean "not yet submitted". When this fence
+        // gets submitted, its status changes to VK_NOT_READY. Finally, when the GPU actually
+        // finishes executing the command buffer, the status changes to VK_SUCCESS.
+        status.store(initialStatus);
     }
 
-    VkFence& getFence() {
-        return fence;
-    }
+    ~VulkanCmdFence() = default;
 
-    VkResult getStatus() {
-        std::unique_lock<utils::Mutex> lock(mutex);
-        return status.load(std::memory_order_acquire);
-    }
+    void setStatus(VkResult value) { status.store(value); }
+
+    VkResult getStatus() { return status.load(std::memory_order_acquire); }
 
 private:
-    VkFence fence;
-    utils::Condition condition;
-    utils::Mutex mutex;
     std::atomic<VkResult> status;
 };