Merge branch 'rc/1.32.0' into release

google · Mar 14, 2023 · 2a579c4 · 2a579c4
2 parents 979d674 + efdc801
commit 2a579c4
Show file tree

Hide file tree

Showing 87 changed files with 1,832 additions and 1,439 deletions.
diff --git a/NEW_RELEASE_NOTES.md b/NEW_RELEASE_NOTES.md
@@ -7,4 +7,3 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
-
diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.31.7'
+    implementation 'com.google.android.filament:filament-android:1.32.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:
 
 ```
-pod 'Filament', '~> 1.31.7'
+pod 'Filament', '~> 1.32.0'
 ```
 
 ### Snapshots

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -7,6 +7,16 @@ 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.0
+
+- fog: fixed fog height falloff and computation precision on mobile [⚠️ **Recompile Materials**]
+- materials: new alphaToCoverage property can be used to control alpha to coverage behavior
+- materials: added `getUserWorldFromWorldMatrix()` and `getUserWorldPosition()` to retrieve the
+  API-level (user) world position in materials. Deprecated `getWorldOffset()`. [⚠️ **Recompile
+  Materials**]
+- engine: fix precision issue with `shading_view` in large scenes
+- vulkan: readPixels is now async (#6560)
+
 ## v1.31.7
 
 ## v1.31.6

diff --git a/android/filamat-android/src/main/cpp/MaterialBuilder.cpp b/android/filamat-android/src/main/cpp/MaterialBuilder.cpp
@@ -250,6 +250,13 @@ Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderMaskThr
     builder->maskThreshold(maskThreshold);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderAlphaToCoverage(JNIEnv*,
+        jclass, jlong nativeBuilder, jboolean enable) {
+    auto builder = (MaterialBuilder*) nativeBuilder;
+    builder->alphaToCoverage(enable);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderShadowMultiplier(
         JNIEnv*, jclass, jlong nativeBuilder, jboolean shadowMultiplier) {

diff --git a/...id/filamat-android/src/main/java/com/google/android/filament/filamat/MaterialBuilder.java b/...id/filamat-android/src/main/java/com/google/android/filament/filamat/MaterialBuilder.java
@@ -360,6 +360,12 @@ public MaterialBuilder maskThreshold(float threshold) {
         return this;
     }
 
+    @NonNull
+    public MaterialBuilder alphaToCoverage(boolean enable) {
+        nMaterialBuilderAlphaToCoverage(mNativeObject, enable);
+        return this;
+    }
+
     @NonNull
     public MaterialBuilder shadowMultiplier(boolean shadowMultiplier) {
         nMaterialBuilderShadowMultiplier(mNativeObject, shadowMultiplier);
@@ -584,6 +590,7 @@ private static native void nMaterialBuilderVariable(long nativeBuilder, int vari
     private static native void nMaterialBuilderDepthCulling(long nativeBuilder, boolean enable);
     private static native void nMaterialBuilderDoubleSided(long nativeBuilder, boolean doubleSided);
     private static native void nMaterialBuilderMaskThreshold(long nativeBuilder, float mode);
+    private static native void nMaterialBuilderAlphaToCoverage(long nativeBuilder, boolean enable);
 
     private static native void nMaterialBuilderShadowMultiplier(long mNativeObject,
             boolean shadowMultiplier);

diff --git a/android/filament-android/src/main/cpp/Material.cpp b/android/filament-android/src/main/cpp/Material.cpp
@@ -153,6 +153,14 @@ Java_com_google_android_filament_Material_nIsDoubleSided(JNIEnv*, jclass,
     return (jboolean) material->isDoubleSided();
 }
 
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Material_nIsAlphaToCoverageEnabled(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jboolean) material->isAlphaToCoverageEnabled();
+}
+
 extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_Material_nGetMaskThreshold(JNIEnv*, jclass,

diff --git a/android/filament-android/src/main/cpp/MaterialInstance.cpp b/android/filament-android/src/main/cpp/MaterialInstance.cpp
@@ -457,7 +457,6 @@ extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetMaskThreshold(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nGetMaskThreshold()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->getMaskThreshold();
 }
@@ -466,7 +465,6 @@ extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingVariance(JNIEnv* env,
         jclass clazz, jlong nativeMaterialInstance) {
-    // TODO: implement nGetSpecularAntiAliasingVariance()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->getSpecularAntiAliasingVariance();
 }
@@ -475,7 +473,6 @@ extern "C"
 JNIEXPORT jfloat JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingThreshold(JNIEnv* env,
         jclass clazz, jlong nativeMaterialInstance) {
-    // TODO: implement nGetSpecularAntiAliasingThreshold()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->getSpecularAntiAliasingThreshold();
 }
@@ -484,7 +481,6 @@ extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDoubleSided(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nIsDoubleSided()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isDoubleSided();
 }
@@ -493,7 +489,6 @@ extern "C"
 JNIEXPORT jint JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetCullingMode(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nGetCullingMode()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return (jint)instance->getCullingMode();
 }
@@ -502,7 +497,6 @@ extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsColorWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nIsColorWriteEnabled()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isColorWriteEnabled();
 }
@@ -511,7 +505,6 @@ extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDepthWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nIsDepthWriteEnabled()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isDepthWriteEnabled();
 }
@@ -520,7 +513,6 @@ extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsStencilWriteEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nIsStencilWriteEnabled()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isStencilWriteEnabled();
 }
@@ -529,7 +521,6 @@ extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsDepthCullingEnabled(JNIEnv* env, jclass clazz,
         jlong nativeMaterialInstance) {
-    // TODO: implement nIsDepthCullingEnabled()
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isDepthCullingEnabled();
 }
diff --git a/android/filament-android/src/main/java/com/google/android/filament/Material.java b/android/filament-android/src/main/java/com/google/android/filament/Material.java
@@ -503,6 +503,17 @@ public boolean isDoubleSided() {
         return nIsDoubleSided(getNativeObject());
     }
 
+    /**
+     * Indicates whether instances of this material will use alpha to coverage.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/rasterization:alphatocoverage">
+     * Rasterization: alphaToCoverage</a>
+     */
+    public boolean isAlphaToCoverageEnabled() {
+        return nIsAlphaToCoverageEnabled(getNativeObject());
+    }
+
     /**
      * Returns the alpha mask threshold used when the blending mode is set to masked.
      *
@@ -915,6 +926,7 @@ void clearNativeObject() {
     private static native boolean nIsDepthWriteEnabled(long nativeMaterial);
     private static native boolean nIsDepthCullingEnabled(long nativeMaterial);
     private static native boolean nIsDoubleSided(long nativeMaterial);
+    private static native boolean nIsAlphaToCoverageEnabled(long nativeMaterial);
     private static native float nGetMaskThreshold(long nativeMaterial);
     private static native float nGetSpecularAntiAliasingVariance(long nativeMaterial);
     private static native float nGetSpecularAntiAliasingThreshold(long nativeMaterial);

diff --git a/android/gradle.properties b/android/gradle.properties
@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.31.7
+VERSION_NAME=1.32.0
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 

diff --git a/android/samples/sample-material-builder/src/main/res/values/strings.xml b/android/samples/sample-material-builder/src/main/res/values/strings.xml
@@ -1,3 +1,3 @@
 <resources>
-  <string name="app_name">Image-Based Lighting</string>
+  <string name="app_name">Material Builder</string>
 </resources>
diff --git a/docs/Materials.md.html b/docs/Materials.md.html
@@ -1362,6 +1362,11 @@
       ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
       information.
 
+!!! Note
+    When `blending` is set to `masked`, alpha to coverage is automatically enabled for the material.
+    If this behavior is undesirable, refer to the Rasterization: alphaToCoverage section to turn
+    alpha to coverage off using the `alphaToCoverage` property.
+
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
     blending : transparent
@@ -1602,6 +1607,37 @@
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### Rasterization: alphaToCoverage
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:     Enables or disables alpha to coverage. When alpha to coverage is enabled, the coverage of
+      fragment is derived from its alpha. This property is only meaningful when MSAA is enabled.
+      Note: setting `blending` to `masked` automatically enables alpha to coverage. If this is not
+      desired, you can override this behavior by setting alpha to coverage to false as in the
+      example below.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    name : "Alpha to coverage",
+    shadingModel : lit,
+    blending : masked,
+    alphaToCoverage : false
+}
+
+fragment {
+    void material(inout MaterialInputs material) {
+        prepareMaterial(material);
+        material.baseColor = materialParams.albedo;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Lighting: reflections
 
 Type
@@ -1910,8 +1946,9 @@
 
 !!! TIP: worldPosition
     To achieve good precision, the `worldPosition` coordinate in the vertex shader is shifted by the
-    camera position. To get the true world-space position, users can add this to
-    `getWorldOffset()`.
+    camera position. To get the true world-space position, users can use
+    `getUserWorldPosition()`, however be aware that the true world-position might not
+    be able to fit in a `float` or might be represented with severely reduced precision.
 
 !!! TIP: UV attributes
     By default the vertex shader of a material will flip the Y coordinate of the UV attributes
@@ -2264,8 +2301,9 @@
                  Name               |   Type   |            Description
 :-----------------------------------|:--------:|:------------------------------------
 **getResolution()**                 | float4   |  Dimensions of the view's effective (physical) viewport in pixels: `width`, `height`, `1 / width`, `1 / height`. This might be different from `View::getViewport()` for instance because of added rendering guard-bands.
-**getWorldCameraPosition()**        | float3   |  Position of the camera/eye in world space
-**getWorldOffset()**                | float3   |  The shift required to obtain API-level world space
+**getWorldCameraPosition()**        | float3   |  Position of the camera/eye in world space (see note below)
+**getWorldOffset()**                | float3   |  [deprecated] The shift required to obtain API-level world space. Use getUserWorldPosition() instead
+**getUserWorldFromWorldMatrix()**   | float4x4 |  Matrix that converts from world space to API-level (user) world space.
 **getTime()**                       | float    |  Current time as a remainder of 1 second. Yields a value between 0 and 1
 **getUserTime()**                   | float4   |  Current time in seconds: `time`, `(double)time - time`, `0`, `0`
 **getUserTimeMode(float m)**        | float    |  Current time modulo m in seconds
@@ -2275,7 +2313,7 @@
 !!! TIP: world space
     To achieve good precision, the "world space" in Filament's shading system does not necessarily
     match the API-level world space. To obtain the position of the API-level camera, custom
-    materials can add `getWorldOffset()` to `getWorldCameraPosition()`.
+    materials can use `getUserWorldFromWorldMatrix()` to transform `getWorldCameraPosition()`.
 
 ### Vertex only
 
@@ -2297,6 +2335,7 @@
 :---------------------------------------|:--------:|:------------------------------------
 **getWorldTangentFrame()**              | float3x3 |  Matrix containing in each column the `tangent` (`frame[0]`), `bi-tangent` (`frame[1]`) and `normal` (`frame[2]`) of the vertex in world space. If the material does not compute a tangent space normal for bump mapping or if the shading is not anisotropic, only the `normal` is valid in this matrix.
 **getWorldPosition()**                  | float3   |  Position of the fragment in world space (see note below about world-space)
+**getUserWorldPosition()**              | float3   |  Position of the fragment in API-level (user) world-space (see note below about world-space)
 **getWorldViewVector()**                | float3   |  Normalized vector in world space from the fragment position to the eye
 **getWorldNormalVector()**              | float3   |  Normalized normal in world space, after bump mapping (must be used after `prepareMaterial()`)
 **getWorldGeometricNormalVector()**     | float3   |  Normalized normal in world space, before bump mapping (can be used before `prepareMaterial()`)
@@ -2313,9 +2352,10 @@
 **ycbcrToRgb(float, float2)**           | float3   |  Converts a luminance and CbCr pair to a sRGB color
 **uvToRenderTargetUV(float2)**          | float2   |  Transforms a UV coordinate to allow sampling from a `RenderTarget` attachment
 
-!!! TIP: world space
-    To obtain API-level world space coordinates, custom materials should add `getWorldOffset()` to
-    `getWorldPosition()` (et al).
+!!! TIP: world-space
+    To obtain API-level world-space coordinates, custom materials should use `getUserWorldPosition()`
+    or use `getUserWorldFromWorldMatrix()`. Note that API-level world-space coordinates should
+    never or rarely be used because they may not fit in a float3 or have severely reduced precision.
 
 !!! TIP: sampling from render targets
     When sampling from a `filament::Texture` that is attached to a `filament::RenderTarget` for

diff --git a/docs/webgl/albedo.ktx2 b/docs/webgl/albedo.ktx2
diff --git a/docs/webgl/ao.ktx2 b/docs/webgl/ao.ktx2
diff --git a/docs/webgl/default_env/default_env_ibl.ktx b/docs/webgl/default_env/default_env_ibl.ktx
diff --git a/docs/webgl/default_env/default_env_skybox.ktx b/docs/webgl/default_env/default_env_skybox.ktx
diff --git a/docs/webgl/default_env/default_env_skybox_tiny.ktx b/docs/webgl/default_env/default_env_skybox_tiny.ktx
diff --git a/docs/webgl/filament.js b/docs/webgl/filament.js
diff --git a/docs/webgl/filament.wasm b/docs/webgl/filament.wasm
diff --git a/docs/webgl/metallic.ktx2 b/docs/webgl/metallic.ktx2
diff --git a/docs/webgl/normal.ktx2 b/docs/webgl/normal.ktx2
diff --git a/docs/webgl/parquet.filamat b/docs/webgl/parquet.filamat
diff --git a/docs/webgl/plastic.filamat b/docs/webgl/plastic.filamat
diff --git a/docs/webgl/roughness.ktx2 b/docs/webgl/roughness.ktx2
diff --git a/docs/webgl/suzanne.filamesh b/docs/webgl/suzanne.filamesh
diff --git a/docs/webgl/textured.filamat b/docs/webgl/textured.filamat
diff --git a/docs/webgl/triangle.filamat b/docs/webgl/triangle.filamat