Merge branch 'rc/1.9.6' into release

BRANCHING.md

@@ -27,55 +27,3 @@ Bugs are defined as one of the following _introduced since the prior release_:
 - 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.5'
+    implementation 'com.google.android.filament:filament-android:1.9.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.9.5'
+pod 'Filament', '~> 1.9.6'
 ```
 
 ### Snapshots

RELEASE_GUIDE.md

@@ -0,0 +1,138 @@
+# Filament Release Guide
+
+This guide makes use of some "environment variables":
+- $RELEASE = the new version of Filament we are releasing today. (e.g., 1.9.3)
+- $NEXT_RELEASE = the version we plan to release next week (e.g., 1.9.4)
+
+Before starting, ensure that each of these branches is up-to-date with origin:
+- release
+- rc/$RELEASE
+- main
+
+## 0. Make sure the rc/$RELEASE branch has the correct version.
+
+It should have the version corresponding to its name, $RELEASE.
+
+## 1. Update RELEASE_NOTES.md on the rc branch.
+
+Checkout the rc/$RELEASE branch. In RELEASE_NOTES.md, locate the header corresponding to $RELEASE
+and write release notes. To see which commits make up the release, run:
+
+```
+build/common/release.sh -c rc/$RELEASE
+```
+
+Commit the changes to rc/$RELEASE with the title:
+
+```
+Update RELEASE_NOTES for $RELEASE
+```
+
+## 2. Bump versions on main to $RELEASE.
+
+Checkout main and run the following command to bump Filament's version to $RELEASE:
+
+```
+build/common/bump-version.sh $RELEASE
+```
+
+Commit changes to main with the title:
+
+```
+Bump version to $RELEASE
+```
+
+Do not push to origin yet.
+
+## 3. Cherry-pick RELEASE_NOTES change from rc branch to main.
+
+```
+git cherry-pick rc/$RELEASE
+```
+
+Update the headers. The "Next release" header becomes a header for $NEXT_RELEASE, and a new "Next
+release" header is added.
+
+For example, this:
+
+```
+## Next release (main branch)
+- foo
+- bar
+
+## v1.9.3
+- baz
+- bat
+```
+
+becomes:
+
+```
+## Next release (main branch)
+
+## v1.9.4
+- foo
+- bar
+
+## v1.9.3
+- baz
+- bat
+```
+
+Ammend these changes to the cherry-picked change.
+
+```
+git add -u
+git commit --amend --no-edit
+```
+
+## 4. Run release script.
+
+```
+build/common/release.sh rc/$RELEASE rc/$NEXT_RELEASE
+```
+
+This script will merge rc/$RELEASE into release, delete the rc branch, and create a new rc
+branch called rc/$NEXT_RELEASE. Verify that everything looks okay locally.
+
+## 5. Push the release branch.
+
+```
+git push origin release
+```
+
+## 6. Create the GitHub release.
+
+Use the GitHub UI to create a GitHub release corresponding to $RELEASE version.
+Make sure the target is set to the release branch.
+
+## 7. Delete the old rc branch.
+
+```
+git push origin --delete rc/$RELEASE
+```
+
+## 8. Bump the version on the new rc branch to $NEXT_RELEASE.
+
+```
+git checkout rc/$NEXT_RELEASE
+build/common/bump-version.sh $NEXT_RELEASE
+```
+
+Commit the changes to rc/$NEXT_RELEASE with the title:
+
+```
+Bump version to $NEXT_RELEASE
+```
+
+## 9. Push main.
+
+```
+git push origin main
+```
+
+## 10. Push the new rc branch.
+
+```
+git push origin rc/$NEXT_RELEASE
+```

RELEASE_NOTES.md

@@ -5,6 +5,15 @@ A new header is inserted each time a *tag* is created.
 
 ## Next release (main branch)
 
+## v1.9.6
+
+- Added View::setVsmShadowOptions (experimental)
+- Add anisotropic shadow map sampling with VSM (experimental)
+- matc: fixed bug where some compilation failures still exited with code 0
+- Vulkan + Android: fix build break
+- Add optional XCB support to PlatformVkLinux
+- Fix Vulkan black screen on Windows with NVIDIA hardware
+
 ## v1.9.5
 
 - Added a new Live Wallpaper Android sample

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

@@ -136,6 +136,15 @@ Java_com_google_android_filament_View_nSetShadowType(JNIEnv*, jclass, jlong nati
     view->setShadowType((View::ShadowType) type);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetVsmShadowOptions(JNIEnv*, jclass, jlong nativeView,
+        jint anisotropy) {
+    View* view = (View*) nativeView;
+    View::VsmShadowOptions options;
+    options.anisotropy = (uint8_t) anisotropy;
+    view->setVsmShadowOptions(options);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetRenderQuality(JNIEnv*, jclass,

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

@@ -75,6 +75,7 @@ public class View {
     private VignetteOptions mVignetteOptions;
     private ColorGrading mColorGrading;
     private TemporalAntiAliasingOptions mTemporalAntiAliasingOptions;
+    private VsmShadowOptions mVsmShadowOptions;
 
     /**
      * Generic quality level.
@@ -582,6 +583,25 @@ public enum ShadowType {
         VSM
     }
 
+    /**
+     * View-level options for VSM shadowing.
+     *
+     * @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.
+         *
+         * <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;
+    }
+
     /**
      * Used to select buffers.
      */
@@ -1182,6 +1202,37 @@ public void setShadowType(ShadowType type) {
         nSetShadowType(getNativeObject(), type.ordinal());
     }
 
+    /**
+     * Sets VSM shadowing options that apply across the entire View.
+     *
+     * Additional light-specific VSM options can be set with
+     * {@link LightManager.Builder#shadowOptions}.
+     *
+     * Only applicable when shadow type is set to ShadowType::VSM.
+     *
+     * <strong>Warning: This API is still experimental and subject to change.</strong>
+     *
+     * @param options Options for shadowing.
+     * @see #setShadowType
+     */
+    public void setVsmShadowOptions(@NonNull VsmShadowOptions options) {
+        mVsmShadowOptions = options;
+        nSetVsmShadowOptions(getNativeObject(), options.anisotropy);
+    }
+
+    /**
+     * Gets the VSM shadowing options.
+     * @see #setVsmShadowOptions
+     * @return VSM shadow options currently set.
+     */
+    @NonNull
+    public VsmShadowOptions getVsmShadowOptions() {
+        if (mVsmShadowOptions == null) {
+            mVsmShadowOptions = new VsmShadowOptions();
+        }
+        return mVsmShadowOptions;
+    }
+
     /**
      * Activates or deactivates ambient occlusion.
      * @see #setAmbientOcclusionOptions
@@ -1374,6 +1425,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 nSetColorGrading(long nativeView, long nativeColorGrading);
     private static native void nSetPostProcessingEnabled(long nativeView, boolean enabled);
     private static native boolean nIsPostProcessingEnabled(long nativeView);

android/gradle.properties

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