Merge branch 'rc/1.32.3' into release

LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2023 The Android Open Source Project
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.32.2'
+    implementation 'com.google.android.filament:filament-android:1.32.3'
 }
 ```
 
@@ -41,7 +41,6 @@ Here are all the libraries available in the group `com.google.android.filament`:
 | ------------- | ------------- |
 | [![filament-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
 | [![gltfio-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
-| [![gltfio-android-lite](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android-lite/badge.svg?subject=gltfio-android-lite)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android-lite) | Trimmed version of `gltfio` that does not support some glTF extensions. |
 | [![filament-utils-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
 | [![filamat-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
 | [![filamat-android-lite](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite/badge.svg?subject=filamat-android-lite)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android-lite) | A much smaller alternative to `filamat-android` that can only generate OpenGL shaders. It does not provide validation or optimizations. |
@@ -51,7 +50,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```
-pod 'Filament', '~> 1.32.2'
+pod 'Filament', '~> 1.32.3'
 ```
 
 ### Snapshots

RELEASE_NOTES.md

@@ -7,6 +7,15 @@ 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.32.3
+
+- fog: added an option to disable the fog after a certain distance [⚠️ **Recompile Materials**].
+- fog: fog color now takes exposure and IBL intensity into account [⚠️ **Recompile Materials**].
+- materials: implement cascades debugging as a post-process [⚠️ **Recompile Materials**].
+- materials: use 9 digits or less for floats [⚠️ **Recompile Materials**].
+- gltfio: fix skinning when objects are far from the origin
+- materials: remove 4 unneeded variants from `unlit` materials [⚠️ **Recompile Materials**].
+
 ## v1.32.2
 
 - lighting: the sun disc was computed in low/medium quality instead of high quality. This will

android/build.gradle

@@ -126,6 +126,7 @@ buildscript {
         "-fno-asynchronous-unwind-tables",
         "-fno-rtti",
         "-ffast-math",
+        "-fno-finite-math-only",
         "-ffp-contract=fast",
         "-fvisibility-inlines-hidden",
         "-fvisibility=hidden",

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

@@ -315,12 +315,13 @@ Java_com_google_android_filament_View_nSetBloomOptions(JNIEnv*, jclass,
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetFogOptions(JNIEnv *, jclass , jlong nativeView,
-        jfloat distance, jfloat maximumOpacity, jfloat height, jfloat heightFalloff, jfloat r,
-        jfloat g, jfloat b, jfloat density, jfloat inScatteringStart,
+        jfloat distance, jfloat maximumOpacity, jfloat height, jfloat heightFalloff, jfloat cutOffDistance,
+        jfloat r, jfloat g, jfloat b, jfloat density, jfloat inScatteringStart,
         jfloat inScatteringSize, jboolean fogColorFromIbl, jboolean enabled) {
     View* view = (View*) nativeView;
     View::FogOptions options = {
              .distance = distance,
+             .cutOffDistance = cutOffDistance,
              .maximumOpacity = maximumOpacity,
              .height = height,
              .heightFalloff = heightFalloff,

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

@@ -356,16 +356,16 @@ public Builder lightChannel(@IntRange(from = 0, to = 7) int channel, boolean ena
 
         /**
          * Specifies the number of draw instance of this renderable. The default is 1 instance and
-         * the maximum number of instances allowed is 65535. 0 is invalid.
+         * the maximum number of instances allowed is 32767. 0 is invalid.
          * All instances are culled using the same bounding box, so care must be taken to make
          * sure all instances render inside the specified bounding box.
          * The material can use getInstanceIndex() in the vertex shader to get the instance index and
          * possibly adjust the position or transform.
          *
-         * @param instanceCount the number of instances silently clamped between 1 and 65535.
+         * @param instanceCount the number of instances silently clamped between 1 and 32767.
          */
         @NonNull
-        public Builder instances(@IntRange(from = 1, to = 65535) int instanceCount) {
+        public Builder instances(@IntRange(from = 1, to = 32767) int instanceCount) {
             nBuilderInstances(mNativeBuilder, instanceCount);
             return this;
         }

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

@@ -962,7 +962,8 @@ public void setFogOptions(@NonNull FogOptions options) {
         assertFloat3In(options.color);
         mFogOptions = options;
         nSetFogOptions(getNativeObject(), options.distance, options.maximumOpacity, options.height,
-                options.heightFalloff, options.color[0], options.color[1], options.color[2],
+                options.heightFalloff, options.cutOffDistance,
+                options.color[0], options.color[1], options.color[2],
                 options.density, options.inScatteringStart, options.inScatteringSize,
                 options.fogColorFromIbl,
                 options.enabled);
@@ -1157,7 +1158,7 @@ void clearNativeObject() {
     private static native void nSetSSCTOptions(long nativeView, float ssctLightConeRad, float ssctStartTraceDistance, float ssctContactDistanceMax, float ssctIntensity, float v, float v1, float v2, float ssctDepthBias, float ssctDepthSlopeBias, int ssctSampleCount, int ssctRayCount, boolean ssctEnabled);
     private static native void nSetBloomOptions(long nativeView, long dirtNativeObject, float dirtStrength, float strength, int resolution, float anamorphism, int levels, int blendMode, boolean threshold, boolean enabled, float highlight,
             boolean lensFlare, boolean starburst, float chromaticAberration, int ghostCount, float ghostSpacing, float ghostThreshold, float haloThickness, float haloRadius, float haloThreshold);
-    private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, boolean enabled);
+    private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, boolean enabled);
     private static native void nSetBlendMode(long nativeView, int blendMode);
     private static native void nSetDepthOfFieldOptions(long nativeView, float cocScale, float maxApertureDiameter, boolean enabled, int filter,
             boolean nativeResolution, int foregroundRingCount, int backgroundRingCount, int fastGatherRingCount, int maxForegroundCOC, int maxBackgroundCOC);
@@ -1392,48 +1393,87 @@ public enum BlendMode {
     }
 
     /**
-     * Options to control fog in the scene
+     * Options to control large-scale fog in the scene
      */
     public static class FogOptions {
         /**
-         * distance in world units from the camera where the fog starts ( >= 0.0 )
+         * Distance in world units [m] from the camera to where the fog starts ( >= 0.0 )
          */
         public float distance = 0.0f;
+        /**
+         * Distance in world units [m] after which the fog calculation is disabled.
+         * This can be used to exclude the skybox, which is desirable if it already contains clouds or
+         * fog. The default value is +infinity which applies the fog to everything.
+         *
+         * Note: The SkyBox is typically at a distance of 1e19 in world space (depending on the near
+         * plane distance and projection used though).
+         */
+        public float cutOffDistance = Float.POSITIVE_INFINITY;
         /**
          * fog's maximum opacity between 0 and 1
          */
         public float maximumOpacity = 1.0f;
         /**
-         * fog's floor in world units
+         * Fog's floor in world units [m]. This sets the "sea level".
          */
         public float height = 0.0f;
         /**
-         * how fast fog dissipates with altitude
+         * How fast the fog dissipates with altitude. heightFalloff has a unit of [1/m].
+         * It can be expressed as 1/H, where H is the altitude change in world units [m] that causes a
+         * factor 2.78 (e) change in fog density.
+         *
+         * A falloff of 0 means the fog density is constant everywhere and may result is slightly
+         * faster computations.
          */
         public float heightFalloff = 1.0f;
         /**
-         * fog's color (linear), see fogColorFromIbl
+         *  Fog's color is used for ambient light in-scattering, a good value is
+         *  to use the average of the ambient light, possibly tinted towards blue
+         *  for outdoors environments. Color component's values should be between 0 and 1, values
+         *  above one are allowed but could create a non energy-conservative fog (this is dependant
+         *  on the IBL's intensity as well).
+         *
+         *  We assume that our fog has no absorption and therefore all the light it scatters out
+         *  becomes ambient light in-scattering and has lost all directionality, i.e.: scattering is
+         *  isotropic. This somewhat simulates Rayleigh scattering.
+         *
+         *  This value is used as a tint instead, when fogColorFromIbl is enabled.
+         *
+         *  @see fogColorFromIbl
          */
         @NonNull @Size(min = 3)
-        public float[] color = {0.5f, 0.5f, 0.5f};
+        public float[] color = {1.0f, 1.0f, 1.0f};
         /**
-         * fog's density at altitude given by 'height'
+         * Extinction factor in [1/m] at altitude 'height'. The extinction factor controls how much
+         * light is absorbed and out-scattered per unit of distance. Each unit of extinction reduces
+         * the incoming light to 37% of its original value.
+         *
+         * Note: The extinction factor is related to the fog density, it's usually some constant K times
+         * the density at sea level (more specifically at fog height). The constant K depends on
+         * the composition of the fog/atmosphere.
+         *
+         * For historical reason this parameter is called `density`.
          */
         public float density = 0.1f;
         /**
-         * distance in world units from the camera where in-scattering starts
+         * Distance in world units [m] from the camera where the Sun in-scattering starts.
          */
         public float inScatteringStart = 0.0f;
         /**
-         * size of in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
+         * Very inaccurately simulates the Sun's in-scattering. That is, the light from the sun that
+         * is scattered (by the fog) towards the camera.
+         * Size of the Sun in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100).
+         * Smaller values result is a larger scattering size.
          */
         public float inScatteringSize = -1.0f;
         /**
-         * Fog color will be modulated by the IBL color in the view direction.
+         * The fog color will be sampled from the IBL in the view direction and tinted by `color`.
+         * Depending on the scene this can produce very convincing results.
+         * This simulate a more anisotropic phase-function.
          */
         public boolean fogColorFromIbl = false;
         /**
-         * enable or disable fog
+         * Enable or disable large-scale fog
          */
         public boolean enabled = false;
     }

android/gradle.properties

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