Merge branch 'rc/1.9.2' into release

BRANCHING.md

@@ -0,0 +1,81 @@
+![Filament branching strategy](art/diagrams/branching.png)
+
+## Which branch do I open my PR against?
+
+For normal development, open PRs against main. Once they're merged, no further action is necessary.
+
+If you discover a bug with the latest *release candidate*, open a bug fix PR against the release
+candidate branch (rc/1.9.0, for example). Once the PR is merged, decide whether it makes sense for
+the fix to also go into main. If it was a temporary fix, simply make the _correct_ fix in main as
+you would any other change. If the fix is good for main as well, use `git cherry-pick <sha>` to
+cherry-pick it into main.
+
+If an immediate hotfix is needed on the *release* branch, open a PR against the release branch. Once
+the PR is merged, decide whether the fix is temporary or permanent. If the fix was temporary, make
+the _correct_ fix in both the next release candidate branch _and_ main. If the fix is good, use `git
+cherry-pick <sha>` to cherry-pick it into the relase candidate branch and main.
+
+## What consitutes a bug?
+
+Only bug fix PRs should be opened against the *release candidate* branch.
+
+Bugs are defined as one of the following _introduced since the prior release_:
+
+- crashes
+- rendering issues
+- unintentional binary size increases
+- unintentional public API changes
+
+For example, a long-standing crash just recently discovered would not necessitate a bug fix PR.
+
+## Creating a GitHub Release
+
+Be sure to choose the *release* branch when drafting a GitHub release.
+
+## Git Commands
+
+These commands assume a release candidate branch called *rc/1.9.0*.
+
+### Creating a Release Candidate Branch
+
+```
+$ git checkout main
+$ git pull
+$ git branch rc/1.9.0
+$ git push origin rc/1.9.0
+```
+
+### Merging the Release Candidate Branch Into Release
+
+There may be temporary hotfixes in the release branch that should be overriden by the new release
+candidate. To accomplish this, we first merge release into rc using the _ours_ strategy. Then we
+merge rc into release.
+
+```
+$ git checkout rc/1.9.0
+$ git pull
+$ git fetch origin release:release
+$ git merge -s ours release
+$ git checkout release
+$ git merge --no-ff rc/1.9.0
+$ git push origin release
+```
+
+### Deleting the Release Candidate Branch
+
+```
+$ git branch -d rc/1.9.0
+$ git push origin --delete rc/1.9.0
+```
+
+### See a History of the Release Branch
+
+```
+$ git log --oneline --first-parent
+
+442b061 (HEAD -> release) Merge branch 'rc/1.9.2' into release
+ac50d21 Hotfix
+94dc2f7 Hotfix
+b34ed5b Merge branch 'rc/1.9.1' into release
+aeef498 Merge branch 'rc/1.9.0' into release
+```

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.9.1'
+    implementation 'com.google.android.filament:filament-android:1.9.2'
 }
 ```
 
@@ -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.9.1'
+pod 'Filament', '~> 1.9.2'
 ```
 
 ### Snapshots
@@ -143,6 +143,8 @@ Here are a few screenshots of applications that use Filament in production:
 - Physical light units
 - Point lights, spot lights and directional light
 - Spot and directional light shadows
+- Cascaded shadows
+- VSM or PCF shadows
 - Contact shadows
 - Screen-space ambient occlusion
 - Screen-space refraction

RELEASE_NOTES.md

@@ -3,6 +3,14 @@
 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.9.2
+
+- Fixes / improvements for contact shadows, fog, and DOF
+- Reduce SSAO creases caused by geometry tessellation
+- Fix compilation warnings and issue with Clang 12
+- Fix JNI crashes
+- Rename .blurScale to .cocScale in DOF options
+
 ## v1.9.1
 
 - Improvements to SSAO quality

android/common/CallbackUtils.h

@@ -25,11 +25,11 @@
 
 struct CallbackJni {
 #ifdef ANDROID
-    jclass handlerClass;
-    jmethodID post;
+    jclass handlerClass = nullptr;
+    jmethodID post = nullptr;
 #endif
-    jclass executorClass;
-    jmethodID execute;
+    jclass executorClass = nullptr;
+    jmethodID execute = nullptr;
 };
 
 void acquireCallbackJni(JNIEnv* env, CallbackJni& callbackUtils);

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

@@ -196,7 +196,7 @@ Java_com_google_android_filament_View_nGetAmbientOcclusion(JNIEnv*, jclass, jlon
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetAmbientOcclusionOptions(JNIEnv*, jclass,
     jlong nativeView, jfloat radius, jfloat bias, jfloat power, jfloat resolution, jfloat intensity,
-    jint quality, jint upsampling, jboolean enabled) {
+    jint quality, jint upsampling, jboolean enabled, jfloat minHorizonAngleRad) {
     View* view = (View*) nativeView;
     View::AmbientOcclusionOptions options = {
             .radius = radius,
@@ -206,7 +206,8 @@ Java_com_google_android_filament_View_nSetAmbientOcclusionOptions(JNIEnv*, jclas
             .intensity = intensity,
             .quality = (View::QualityLevel)quality,
             .upsampling = (View::QualityLevel)upsampling,
-            .enabled = (bool)enabled
+            .enabled = (bool)enabled,
+            .minHorizonAngleRad = minHorizonAngleRad
     };
     view->setAmbientOcclusionOptions(options);
 }
@@ -262,9 +263,9 @@ Java_com_google_android_filament_View_nSetBlendMode(JNIEnv *, jclass , jlong nat
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetDepthOfFieldOptions(JNIEnv *, jclass ,
-        jlong nativeView, jfloat focusDistance, jfloat blurScale, jfloat maxApertureDiameter, jboolean enabled) {
+        jlong nativeView, jfloat focusDistance, jfloat cocScale, jfloat maxApertureDiameter, jboolean enabled) {
     View* view = (View*) nativeView;
-    view->setDepthOfFieldOptions({.focusDistance = focusDistance, .blurScale = blurScale,
+    view->setDepthOfFieldOptions({.focusDistance = focusDistance, .cocScale = cocScale,
             .maxApertureDiameter = maxApertureDiameter, .enabled = (bool)enabled});
 }
 

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

@@ -188,6 +188,13 @@ public static class AmbientOcclusionOptions {
          * enable or disable screen space ambient occlusion
          */
         public boolean enabled = false;
+
+        /**
+         * Minimal angle to consider in radian. This is used to reduce the creases that can
+         * appear due to insufficiently tessellated geometry.
+         * For e.g. a good values to try could be around 0.2.
+         */
+        public float minHorizonAngleRad = 0.0f;
     }
 
     /**
@@ -335,9 +342,9 @@ public static class FogOptions {
         public float inScatteringStart = 0.0f;
 
         /**
-         * size of in-scattering (>=0 to activate). Good values are >> 1 (e.g. ~10 - 100)
+         * size of in-scattering (>0 to activate). Good values are >> 1 (e.g. ~10 - 100)
          */
-        public float inScatteringSize = 0.0f;
+        public float inScatteringSize = -1.0f;
 
         /**
          * fog color will be modulated by the IBL color in the view direction
@@ -360,8 +367,17 @@ public static class DepthOfFieldOptions {
         /** focus distance in world units */
         public float focusDistance = 10.0f;
 
-        /** scale factor controlling the amount of blur (values other than 1.0 are not physically correct)*/
-        public float blurScale = 1.0f;
+        /**
+         * circle of confusion scale factor (amount of blur)
+         *
+         * <p>cocScale can be used to set the depth of field blur independently from the camera
+         * aperture, e.g. for artistic reasons. This can be achieved by setting:</p>
+         * <code>
+         *      cocScale = cameraAperture / desiredDoFAperture
+         * </code>
+         *
+         */
+        public float cocScale = 1.0f;
 
         /** maximum aperture diameter in meters (zero to disable bokeh rotation) */
         public float maxApertureDiameter = 0.01f;
@@ -1061,7 +1077,7 @@ public void setAmbientOcclusionOptions(@NonNull AmbientOcclusionOptions options)
         mAmbientOcclusionOptions = options;
         nSetAmbientOcclusionOptions(getNativeObject(), options.radius, options.bias, options.power,
                 options.resolution, options.intensity, options.quality.ordinal(), options.upsampling.ordinal(),
-                options.enabled);
+                options.enabled, options.minHorizonAngleRad);
     }
 
     /**
@@ -1173,7 +1189,7 @@ public FogOptions getFogOptions() {
      */
     public void setDepthOfFieldOptions(@NonNull DepthOfFieldOptions options) {
         mDepthOfFieldOptions = options;
-        nSetDepthOfFieldOptions(getNativeObject(), options.focusDistance, options.blurScale, options.maxApertureDiameter, options.enabled);
+        nSetDepthOfFieldOptions(getNativeObject(), options.focusDistance, options.cocScale, options.maxApertureDiameter, options.enabled);
     }
 
     /**
@@ -1225,11 +1241,11 @@ void clearNativeObject() {
     private static native boolean nIsFrontFaceWindingInverted(long nativeView);
     private static native void nSetAmbientOcclusion(long nativeView, int ordinal);
     private static native int nGetAmbientOcclusion(long nativeView);
-    private static native void nSetAmbientOcclusionOptions(long nativeView, float radius, float bias, float power, float resolution, float intensity, int quality, int upsampling, boolean enabled);
+    private static native void nSetAmbientOcclusionOptions(long nativeView, float radius, float bias, float power, float resolution, float intensity, int quality, int upsampling, boolean enabled, float minHorizonAngleRad);
     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);
     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 nSetBlendMode(long nativeView, int blendMode);
-    private static native void nSetDepthOfFieldOptions(long nativeView, float focusDistance, float blurScale, float maxApertureDiameter, boolean enabled);
+    private static native void nSetDepthOfFieldOptions(long nativeView, float focusDistance, float cocScale, float maxApertureDiameter, boolean enabled);
     private static native void nSetVignetteOptions(long nativeView, float midPoint, float roundness, float feather, float r, float g, float b, float a, boolean enabled);
     private static native void nSetTemporalAntiAliasingOptions(long nativeView, float feedback, float filterWidth, boolean enabled);
 }

android/gradle.properties

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

art/diagrams/branching.drawio

@@ -0,0 +1 @@
+<mxfile host="app.diagrams.net" modified="2020-09-14T19:00:14.695Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.83 Safari/537.36" etag="dN_ZQ720OjeZq7fcsGJR" version="13.6.6" type="device"><diagram id="0Au-6x1pa8pepmiu9SBl" name="Page-1">7V1tc6M4Ev41rr3dqqR4N/44yUxmt+7m6mozV7vzUQbZaAOIA9lO9tefJN4lYWMC2JNMqqbGNCBEq5+nW62WvTDvo+fPKUiCL9iH4cLQ/OeF+XFh0L+lQ/9jkpdcoi9LyTZFfiGrBY/ob1gItUK6Qz7MWhcSjEOCkrbQw3EMPdKSgTTFh/ZlGxy2n5qALZQEjx4IZekfyCdBLnVtrZb/CtE2KJ+sa8WZCJQXF4IsAD4+NETmp4V5n2JM8k/R8z0MmfZKveT3PXScrTqWwpj0uSH4/bDdfAn9P795Xx8f/vuETRvc2HkrexDuihcuOkteSg1AnyqkOMQpCfAWxyD8VEvvUryLfcgeo9Gj+pp/YZxQoU6Ff0FCXorRBTuCqSggUVichbH/gY0VPYxxDHPJAwrDosmMpPgJ3uMQp7xPpsb/6BlZCaWRgHQLyZE3t/Lr2Ns1bixU9xniCJL0hV6QwhAQtG+bAyisaltdV936H4xoVwytgMCNXppKgQBzZbfbyPAu9WBxWz1+9EOjH7WIj+oZI7x8qyOc6+30CJ+0BGdsS2gN4bnjZfUYrzCk9MeUeAgQgY8J4Ho4UApuax1kSc6JG/TMRu9uQzXeULJvQ9e3VOp3jbXpOMfUv4cpgc9HFVZCYCkgoDw+1IRagiRocGkpG13Fq3cLCacnJNyrgoSujzFgsw6Rt0v33Dj0WcarjJZG9mb05cFL44KEOams29l1+bqHvtdrtmAseQ9GdYjOmyNY58r4VR8l5mhBaFbwbnBMHkCEQqbQ3/Ea86aHo9jti+LrikTcNwcUw7o2pIwy/3o7SCn92GmojD59e904ajNiZbPZGJ6nGhffWTv2SFjRV22sGO6lsWJIOo4AiiU914G5flrXagO+zDTJWInstLy1JZ3rukLppj2V0k1J6alHW9JvV7faDKqfydZFU78CxY8ySX1DnqFvNkcffe46aCpkikkP7fhUSLzeKN5j0qmQYQ+wqdcnPp4R+ZPdTkGWH31rnPn4XLTMD17Kg5i+aeMmdvitea6+jR/V941rwD7IghHm9f2t+bqmBPqc2cl5uF/0uhePc4w+Or7m9OTo1N83C2aY1wWWt5dpsrTLTaD/+BSb/958fXr4/Ncd/Oc+WYZrWMWnk2eCC59Vfv7W8l9dPus4gtoQrT1cy7/V7q7DwylNfiDQFIkqtdadMUIqKQZaaeoYqGoi75i0VNodm429mKrPmRPbuB5U+7+1a1v20ZWg4ZDWV4Zi8jOvB9RlpU4/1RkUlVYI90KQZchrgVyf1U2WdSZTVzRY5ayhNBjX6oXS0SYtcq5tP1s6YhZIViUipYZN2cs6cyYjzCGAnM3LDvObY8e3I634ljHs6WD3YjNDZUiwHGAho2USxozKriAOU9mAOg5zJ2F4/WTN2tQUL2edpwuzZlqjl5L7F5459ZmcXj7LcA1oVKQf1GhczoRGbWY0zpnHmCfp5xpXlvQzh2Tip5nyVB7z4lOeqWcyutWOsy2930zmdEOO0W5o4hpv05AQqt/S4y849nlmJMJpjOLtwrhnnaL/YnjI9QcBRa2heSD2kQ8I+7xOQewF7JnZgu2YSJ+gfyuZJ0UaaZtTe9wLOm/CuxCBEG1jZj90vCGV3zHcIg+EH4oTEfL9sItL2i7nTIvqzxAC51qOKxFEVSExC0NY8vx21vXf7x7thiOA1BKGqi/axYZssaGp0S77Y4Oh/SPcwxAnEeSdPVDcLvi+KILiHWRQxjGjAl4zc59319B22Q6E7w7durDabpvmheFtum8c3ifjbHM5Dw+Yehu+huPMGk6bcnW0yeD7NaDGvw3wjvWVBMwTHyB8yrG63m2ZL6Yxc+GTq2sqH84hHfsLFto6IUMvoh+27AOO6SAVQtrnSi42zJtIeTyAowgRAllzPkppyM5a0OgQS89VxA7vjk8MQwwX+tGJM1m0MGQ2/z3RydyrHIOjBamh1bzRgiVvnrIY3fy2YX1IkhQnKeLgZeiHgEf+FSsUswAHRAxN8TpL+KAI/BKBmEYRnRzjBTBNX24S5D1xQuEswuIQ1o8PMZ+gQKrNPFzZhMhjq7cFE/kQhDyeQSTg6Enhu6MX0xToZXXpcMWyfvDL6/hFiEB1azWMX2xbWCzUhIY6+OXcglbpOUWHJy1QteSFADuPlRg1xAz1dZbjvopN6MjAjOQQyxCf9uDNiciFJzs4DTGKoq+O60t/qUIrArb5BQUdiS3Gu2gN07qLnxH5dbduXcIf5KUQ8OiqjtqoQcMG7613KCTvjukscS+jnJedLJBSJ/WHBFLXU36iWJU+d1FEqRZjElI0XWH09X5B19lcZtrK54zFZd0qa1GZU/NEn0ysT68h32cqViIAhdV1c4Kwa9OwddX2HBUtlGmd0WlBrgOsRlAYnAsWIb1K69J2NENTcPFUe6LUXDwkBX4Fpe9zF/r23CM1On1L33UkFfB2xKLygpoYHS+ncQS6uA488q4rtRnLGzyqPZVyod0F91S+ij8ckbXn3VSpdsHOAAIZs8alK0wbMTLLs9ujY3u5FLLmPRE5Gmjkb0pY8vTR4n0sZr8Oi0JcXdHexeInY0j+6CrrRceE7jTbanRj9H01HQ/SOvx/p5s/ccNE/nfWerZZgnVX0OO8m3jUCB8SrE9eTzomWicq9xTROmG555H3urZyz1fBYyXFohcuvr7QFy/MCI6JdiZI4JhuZ8KR97q2nQmvAoeuXfBb0dToGJJz//G1JBOk+UtfcLGdSJq1ul01/oS8vWiCvfNLun20XbFGY2JWMYZ8i8EPg5/C4C+82We1PGaXhm3d2gMtXhNyADQoEtsaaRq4ssUCS+1E16yjN0y0HLe6cAj22lzg+LZnWEdszzL6caKi2WEFcGebXcdzzu3XtFYnx49uXY3HClVQFEE/L8jTAkzqGjwthtDntSf/IAEXZAHehUyw5kvI1EB+zgtKECnvOaeOt6rd7agN5K1ueY2KWA8olxyfWRJY1NuQoq6nRz63bHhdtsqraKqHrRsPK0oN31fO1xW+1NLW5ai+Kq+ZJeer2KVWDlig18OVS5heWuPl/G+HyxM3GedXlvs3reS5Plm2QukUFPtg7rjB8M1v2iNJqRVtm0aZP6f9bCqWO5T06Y1uqHqTl3hsMQgX9TpEZe2SIVeGrzTmCgAcMCA8cJJk23z4xh6+u48C1995BOH4JoXAZxdkMUgoXzCN8FK4WkO8Ai3EXEFFVRvgNbkyE8GchjyYZSB9uW30MBlVXVxHIMz4G+4x8jPOBxkO9/lAhsz3LJRlw42CujBkP/+k0HC+B0qpXq7VJwiTQpUeHQumVtongjvfeTRqyShXsFc0P9r10VceXLCMqppRMCWKTciDioAyD4x7sgyTFpGKbozDOnXVSINmLFX2QHeNqXhGLhr9pUJbBL0AxCiLGJRYx6lCOZwO8CfedGlS7QpQ/kL8vI8yD6R+hZIkhXuEd1kLJPeNhrkxHwKOKPJTxoGV0NARxMVGHx7kpFDhFZtu2qvsOrfegghg9l05tilMTheq4x2FCbqq1U0xou1hgfSw/sW2PCisf/jO/PR/</diagram></mxfile>

filament/backend/src/opengl/CocoaTouchExternalImage.mm

@@ -258,7 +258,7 @@ void main() {
     glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, texture, 0);
 
     CHECK_GL_ERROR(utils::slog.e)
-    CHECK_GL_FRAMEBUFFER_STATUS(utils::slog.e)
+    CHECK_GL_FRAMEBUFFER_STATUS(utils::slog.e, GL_FRAMEBUFFER)
 
     // geometry
     glBindVertexArray(0);

filament/backend/src/opengl/GLUtils.cpp

@@ -56,8 +56,8 @@ void checkGLError(io::ostream& out, const char* function, size_t line) noexcept
     debug_trap();
 }
 
-void checkFramebufferStatus(io::ostream& out, const char* function, size_t line) noexcept {
-    GLenum status = glCheckFramebufferStatus(GL_FRAMEBUFFER);
+void checkFramebufferStatus(io::ostream& out, GLenum target, const char* function, size_t line) noexcept {
+    GLenum status = glCheckFramebufferStatus(target);
     const char* error = "unknown";
     switch (status) {
         case GL_FRAMEBUFFER_COMPLETE:

filament/backend/src/opengl/GLUtils.h

@@ -31,17 +31,17 @@ namespace filament {
 namespace GLUtils {
 
 void checkGLError(utils::io::ostream& out, const char* function, size_t line) noexcept;
-void checkFramebufferStatus(utils::io::ostream& out, const char* function, size_t line) noexcept;
+void checkFramebufferStatus(utils::io::ostream& out, GLenum target, const char* function, size_t line) noexcept;
 
 #ifdef NDEBUG
 #define CHECK_GL_ERROR(out)
-#define CHECK_GL_FRAMEBUFFER_STATUS(out)
+#define CHECK_GL_FRAMEBUFFER_STATUS(out, target)
 #else
 #ifdef _MSC_VER
     #define __PRETTY_FUNCTION__ __FUNCSIG__
 #endif
 #define CHECK_GL_ERROR(out) { GLUtils::checkGLError(out, __PRETTY_FUNCTION__, __LINE__); }
-#define CHECK_GL_FRAMEBUFFER_STATUS(out) { GLUtils::checkFramebufferStatus(out, __PRETTY_FUNCTION__, __LINE__); }
+#define CHECK_GL_FRAMEBUFFER_STATUS(out, target) { GLUtils::checkFramebufferStatus(out, target, __PRETTY_FUNCTION__, __LINE__); }
 #endif
 
 constexpr inline GLuint getComponentCount(backend::ElementType type) noexcept {

filament/backend/src/opengl/OpenGLBlitter.cpp

@@ -133,7 +133,7 @@ void OpenGLBlitter::blit(GLuint srcTextureExternal, GLuint dstTexture2d, GLuint
     glBindFramebuffer(GL_FRAMEBUFFER, mFBO);
     glFramebufferTexture2D(GL_FRAMEBUFFER, GL_COLOR_ATTACHMENT0, GL_TEXTURE_2D, dstTexture2d, 0);
     CHECK_GL_ERROR(utils::slog.e)
-    CHECK_GL_FRAMEBUFFER_STATUS(utils::slog.e)
+    CHECK_GL_FRAMEBUFFER_STATUS(utils::slog.e, GL_FRAMEBUFFER)
 
     // geometry
     glBindBuffer(GL_ARRAY_BUFFER, 0);