Merge branch 'rc/1.10.6' into release

CMakeLists.txt

@@ -41,8 +41,8 @@ set(FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB "1" CACHE STRING
     "Size of the command-stream buffer. As a rule of thumb use the same value as FILAMENT_PER_FRRAME_COMMANDS_SIZE_IN_MB, default 1."
 )
 
-set(FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB "2" CACHE STRING
-    "Size of the OpenGL handle arena, default 2."
+set(FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB "4" CACHE STRING
+    "Size of the OpenGL handle arena, default 4."
 )
 
 # ==================================================================================================

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.10.5'
+    implementation 'com.google.android.filament:filament-android:1.10.6'
 }
 ```
 
@@ -63,7 +63,7 @@ A much smaller alternative to `filamat-android` that can only generate OpenGL sh
 iOS projects can use CocoaPods to install the latest release:
 
 ```
-pod 'Filament', '~> 1.10.5'
+pod 'Filament', '~> 1.10.6'
 ```
 
 ### Snapshots
@@ -190,6 +190,7 @@ Here are a few screenshots of applications that use Filament in production:
   - [x] KHR_draco_mesh_compression
   - [x] KHR_lights_punctual
   - [x] KHR_materials_clearcoat
+  - [x] KHR_materials_ior
   - [x] KHR_materials_pbrSpecularGlossiness
   - [x] KHR_materials_sheen
   - [x] KHR_materials_transmission

RELEASE_NOTES.md

@@ -3,7 +3,18 @@
 This file contains one line summaries of commits that are worthy of mentioning in release notes.
 A new header is inserted each time a *tag* is created.
 
-## v1.10.6 (currently main branch)
+## v1.10.7 (currently main branch)
+
+## v1.10.6
+
+- engine: Use exponential VSM and improve VSM user settings [⚠️ **Recompile Materials for VSM**].
+- engine: Optional blurring of VSM shadowmaps.
+- engine: Fix a crash when using lens flares.
+- engine: Fix backend crashes when using an unsupported sample count.
+- gltfio: Add new `getAsset`API to `FilamentInstance`.
+- gltfio: Introduce support for extras strings.
+- OpenGL: Increase OpenGL backend handle arena from 2 to 4 MiB.
+- Vulkan: Fix Texture swizzle support.
 
 ## v1.10.5
 

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

@@ -77,7 +77,7 @@ Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env,
         jlong nativeBuilder, jint mapSize, jint cascades, jfloatArray splitPositions,
         jfloat constantBias, jfloat normalBias, jfloat shadowFar, jfloat shadowNearHint,
         jfloat shadowFarHint, jboolean stable, jboolean screenSpaceContactShadows, jint stepCount,
-        jfloat maxShadowDistance, jint vsmMsaaSamples) {
+        jfloat maxShadowDistance, jint vsmMsaaSamples, jfloat blurWidth) {
     LightManager::Builder *builder = (LightManager::Builder *) nativeBuilder;
     LightManager::ShadowOptions shadowOptions {
             .mapSize = (uint32_t)mapSize,
@@ -92,7 +92,8 @@ Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env,
             .stepCount = uint8_t(stepCount),
             .maxShadowDistance = maxShadowDistance,
             .vsm = {
-                    .msaaSamples = (uint8_t) vsmMsaaSamples
+                    .msaaSamples = (uint8_t) vsmMsaaSamples,
+                    .blurWidth = blurWidth
             }
     };
     jfloat *nativeSplits = env->GetFloatArrayElements(splitPositions, NULL);

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

@@ -138,10 +138,15 @@ Java_com_google_android_filament_View_nSetShadowType(JNIEnv*, jclass, jlong nati
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetVsmShadowOptions(JNIEnv*, jclass, jlong nativeView,
-        jint anisotropy) {
+        jint anisotropy, jboolean mipmapping, jfloat exponent, jfloat minVarianceScale,
+        jfloat lightBleedReduction) {
     View* view = (View*) nativeView;
     View::VsmShadowOptions options;
-    options.anisotropy = (uint8_t) anisotropy;
+    options.anisotropy = (uint8_t)anisotropy;
+    options.mipmapping = (bool)mipmapping;
+    options.exponent = exponent;
+    options.minVarianceScale = minVarianceScale;
+    options.lightBleedReduction = lightBleedReduction;
     view->setVsmShadowOptions(options);
 }
 

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

@@ -188,7 +188,7 @@ public enum Type {
      * Control the quality / performance of the shadow map associated to this light
      */
     public static class ShadowOptions {
-        /** Size of the shadow map in texels. Must be a power-of-two. */
+        /** Size of the shadow map in texels. Must be a power-of-two and larger or equal to 8. */
         public int mapSize = 1024;
 
         /**
@@ -242,15 +242,17 @@ public static class ShadowOptions {
 
         /** Constant bias in world units (e.g. meters) by which shadows are moved away from the
          * light. 1mm by default.
+         * This is ignored when the View's ShadowType is set to VSM.
          */
         public float constantBias = 0.05f;
 
         /** Amount by which the maximum sampling error is scaled. The resulting value is used
          * to move the shadow away from the fragment normal. Should be 1.0.
+         * This is ignored when the View's ShadowType is set to VSM.
          */
         public float normalBias = 0.4f;
 
-        /** Distance from the camera after which shadows are clipped. this is used to clip
+        /** Distance from the camera after which shadows are clipped. This is used to clip
          * shadows that are too far and wouldn't contribute to the scene much, improving
          * performance and quality. This value is always positive.
          * Use 0.0f to use the camera far distance.
@@ -324,6 +326,12 @@ public static class ShadowOptions {
          */
         @IntRange(from = 1)
         public int vsmMsaaSamples = 1;
+
+        /**
+         * Blur width for the VSM blur. Zero do disable.
+         * The maximum value is 125.
+         */
+        public float blurWidth = 0.0f;
     }
 
     public static class ShadowCascades {
@@ -452,7 +460,8 @@ public Builder shadowOptions(@NonNull ShadowOptions options) {
                     options.mapSize, options.shadowCascades, options.cascadeSplitPositions,
                     options.constantBias, options.normalBias, options.shadowFar, options.shadowNearHint,
                     options.shadowFarHint, options.stable, options.screenSpaceContactShadows,
-                    options.stepCount, options.maxShadowDistance, options.vsmMsaaSamples);
+                    options.stepCount, options.maxShadowDistance, options.vsmMsaaSamples,
+                    options.blurWidth);
             return this;
         }
 
@@ -1086,7 +1095,7 @@ public long getNativeObject() {
     private static native void nDestroyBuilder(long nativeBuilder);
     private static native boolean nBuilderBuild(long nativeBuilder, long nativeEngine, int entity);
     private static native void nBuilderCastShadows(long nativeBuilder, boolean enable);
-    private static native void nBuilderShadowOptions(long nativeBuilder, int mapSize, int cascades, float[] splitPositions, float constantBias, float normalBias, float shadowFar, float shadowNearHint, float shadowFarhint, boolean stable, boolean screenSpaceContactShadows, int stepCount, float maxShadowDistance, int vsmMsaaSamples);
+    private static native void nBuilderShadowOptions(long nativeBuilder, int mapSize, int cascades, float[] splitPositions, float constantBias, float normalBias, float shadowFar, float shadowNearHint, float shadowFarhint, boolean stable, boolean screenSpaceContactShadows, int stepCount, float maxShadowDistance, int vsmMsaaSamples, float blurWidth);
     private static native void nBuilderCastLight(long nativeBuilder, boolean enabled);
     private static native void nBuilderPosition(long nativeBuilder, float x, float y, float z);
     private static native void nBuilderDirection(long nativeBuilder, float x, float y, float z);

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

@@ -687,20 +687,44 @@ public enum ShadowType {
     /**
      * View-level options for VSM shadowing.
      *
+     * <strong>Warning: This API is still experimental and subject to change.</strong>
+     *
      * @see View#setVsmShadowOptions
      */
     public static class VsmShadowOptions {
         /**
          * Sets the number of anisotropic samples to use when sampling a VSM shadow map. If greater
          * than 0, mipmaps will automatically be generated each frame for all lights.
+         * This implies mipmapping below.
          *
          * <p>
          * The number of anisotropic samples = 2 ^ vsmAnisotropy.
          * </p>
          *
-         * <strong>Warning: This API is still experimental and subject to change.</strong>
          */
         public int anisotropy = 0;
+
+        /**
+         * Whether to generate mipmaps for all VSM shadow maps.
+         */
+        public boolean mipmapping = false;
+
+        /**
+         * EVSM exponent
+         * The maximum value permissible is 5.54 for a shadow map in fp16, or 42.0 for a
+         * shadow map in fp32. Currently the shadow map bit depth is always fp16.
+         */
+        public float exponent = 5.54f;
+
+        /**
+         * VSM minimum variance scale, must be positive.
+         */
+        public float minVarianceScale = 1.0f;
+
+        /**
+         * VSM light bleeding reduction amount, between 0 and 1.
+         */
+        public float lightBleedReduction = 0.2f;
     }
 
     /**
@@ -1308,7 +1332,8 @@ public void setShadowType(ShadowType type) {
      */
     public void setVsmShadowOptions(@NonNull VsmShadowOptions options) {
         mVsmShadowOptions = options;
-        nSetVsmShadowOptions(getNativeObject(), options.anisotropy);
+        nSetVsmShadowOptions(getNativeObject(), options.anisotropy, options.mipmapping,
+                options.exponent, options.minVarianceScale, options.lightBleedReduction);
     }
 
     /**
@@ -1522,7 +1547,7 @@ void clearNativeObject() {
     private static native void nSetRenderQuality(long nativeView, int hdrColorBufferQuality);
     private static native void nSetDynamicLightingOptions(long nativeView, float zLightNear, float zLightFar);
     private static native void nSetShadowType(long nativeView, int type);
-    private static native void nSetVsmShadowOptions(long nativeView, int anisotropy);
+    private static native void nSetVsmShadowOptions(long nativeView, int anisotropy, boolean mipmapping, float exponent, float minVarianceScale, float lightBleedReduction);
     private static native void nSetColorGrading(long nativeView, long nativeColorGrading);
     private static native void nSetPostProcessingEnabled(long nativeView, boolean enabled);
     private static native boolean nIsPostProcessingEnabled(long nativeView);

android/gltfio-android/src/main/cpp/FilamentAsset.cpp

@@ -192,6 +192,15 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nGetName(JNIEnv* env, jcla
     return val ? env->NewStringUTF(val) : nullptr;
 }
 
+extern "C" JNIEXPORT jstring JNICALL
+Java_com_google_android_filament_gltfio_FilamentAsset_nGetExtras(JNIEnv* env, jclass,
+        jlong nativeAsset, jint entityId) {
+    Entity entity = Entity::import(entityId);
+    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
+    const auto val = asset->getExtras(entity);
+    return val ? env->NewStringUTF(val) : nullptr;
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nGetAnimator(JNIEnv* , jclass,
         jlong nativeAsset) {

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java

@@ -149,10 +149,11 @@ public FilamentAsset createInstancedAsset(@NonNull Buffer buffer,
         if (nativeAsset == 0) {
             return null;
         }
+        FilamentAsset asset = new FilamentAsset(mEngine, nativeAsset);
         for (int i = 0; i < nativeInstances.length; i++) {
-            instances[i] = new FilamentInstance(nativeInstances[i]);
+            instances[i] = new FilamentInstance(asset, nativeInstances[i]);
         }
-        return new FilamentAsset(mEngine, nativeAsset);
+        return asset;
     }
 
     /**
@@ -178,7 +179,7 @@ public FilamentInstance createInstance(@NonNull FilamentAsset asset) {
         if (nativeInstance == 0) {
             return null;
         }
-        return new FilamentInstance(nativeInstance);
+        return new FilamentInstance(asset, nativeInstance);
     }
 
     /**

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java

@@ -186,6 +186,16 @@ public String getName(@Entity int entity) {
         return nGetName(getNativeObject(), entity);
     }
 
+    /**
+     * Gets the glTF extras string for the asset or a specific node.
+     *
+     * @param entity the entity corresponding to the glTF node, or 0 to get the asset-level string.
+     * @return the requested extras string, or null if it does not exist.
+     */
+    public @Nullable String getExtras(@Entity int entity) {
+        return nGetExtras(mNativeObject, entity);
+    }
+
     /**
      * Creates or retrieves the <code>Animator</code> interface for this asset.
      *
@@ -252,6 +262,7 @@ void clearNativeObject() {
 
     private static native void nGetBoundingBox(long nativeAsset, float[] box);
     private static native String nGetName(long nativeAsset, int entity);
+    private static native String nGetExtras(long nativeAsset, int entity);
     private static native long nGetAnimator(long nativeAsset);
     private static native int nGetResourceUriCount(long nativeAsset);
     private static native void nGetResourceUris(long nativeAsset, String[] result);

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java

@@ -28,10 +28,12 @@
  * @see AssetLoader
  */
 public class FilamentInstance {
+    private FilamentAsset mAsset;
     private long mNativeObject;
     private Animator mAnimator;
 
-    FilamentInstance(long nativeObject) {
+    FilamentInstance(FilamentAsset asset, long nativeObject) {
+        mAsset = asset;
         mNativeObject = nativeObject;
         mAnimator = null;
     }
@@ -46,6 +48,11 @@ void clearNativeObject() {
         mNativeObject = 0;
     }
 
+    @SuppressWarnings("unused")
+    public @NonNull FilamentAsset getAsset() {
+        return mAsset;
+    }
+
     /**
      * Gets the transform root for the asset, which has no matching glTF node.
      */

android/gradle.properties

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

filament/CMakeLists.txt

@@ -108,6 +108,7 @@ set(PRIVATE_HDRS
         src/RenderPass.h
         src/ResourceAllocator.h
         src/ToneMapping.h
+        src/TypedUniformBuffer.h
         src/UniformBuffer.h
         src/components/CameraManager.h
         src/components/LightManager.h

filament/backend/CMakeLists.txt

@@ -235,8 +235,8 @@ function(build_vkshader SOURCE TARGET_PATH)
             DEPENDS matc ${SOURCE_PATH}
             COMMENT "Building SPIR-V")
 endfunction()
-build_vkshader("BlitColor.vs" "BlitColorVs.spv")
-build_vkshader("BlitColor.fs" "BlitColorFs.spv")
+build_vkshader("BlitDepth.vs" "BlitDepthVs.spv")
+build_vkshader("BlitDepth.fs" "BlitDepthFs.spv")
 
 add_custom_command(
         OUTPUT ${RESGEN_OUTPUTS}
@@ -281,7 +281,7 @@ if(FILAMENT_SUPPORTS_OPENGL AND NOT IOS AND NOT ANDROID AND NOT WEBGL)
 endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)
-    target_link_libraries(${TARGET} PUBLIC bluevk vkmemalloc vkshaders)
+    target_link_libraries(${TARGET} PUBLIC bluevk vkmemalloc vkshaders smol-v)
 endif()
 
 if (FILAMENT_SUPPORTS_METAL)

filament/backend/include/private/backend/SamplerGroup.h

@@ -80,6 +80,10 @@ class SamplerGroup {
         setSampler(index, { t, s });
     }
 
+    inline void clearSampler(size_t index)  {
+        setSampler(index, {});
+    }
+
 private:
 #if !defined(NDEBUG)
     friend utils::io::ostream& operator<<(utils::io::ostream& out, const SamplerGroup& rhs);

filament/backend/src/metal/MetalContext.h

@@ -24,6 +24,7 @@
 #include <Metal/Metal.h>
 #include <QuartzCore/QuartzCore.h>
 
+#include <array>
 #include <stack>
 
 #include <tsl/robin_set.h>
@@ -43,6 +44,8 @@ struct MetalIndexBuffer;
 struct MetalSamplerGroup;
 struct MetalVertexBuffer;
 
+constexpr static uint8_t MAX_SAMPLE_COUNT = 8;  // Metal devices support at most 8 MSAA samples
+
 struct MetalContext {
     MetalDriver* driver;
     id<MTLDevice> device = nullptr;
@@ -55,6 +58,9 @@ struct MetalContext {
     bool supportsTextureSwizzling = false;
     uint8_t maxColorRenderTargets = 4;
 
+    // sampleCountLookup[requestedSamples] gives a <= sample count supported by the device.
+    std::array<uint8_t, MAX_SAMPLE_COUNT + 1> sampleCountLookup;
+
     // Tracks resources used by command buffers.
     MetalResourceTracker resourceTracker;