Merge branch 'rc/1.9.10' into release

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.9.9'
+    implementation 'com.google.android.filament:filament-android:1.9.10'
 }
 ```
 
@@ -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.9'
+pod 'Filament', '~> 1.9.10'
 ```
 
 ### Snapshots

RELEASE_NOTES.md

@@ -5,6 +5,22 @@ A new header is inserted each time a *tag* is created.
 
 ## Next release (main branch)
 
+## v.1.9.11
+
+## v1.9.10
+
+- Introduce libibl_lite library.
+- engine: Fix EXC_BAD_INSTRUCTION seen when using headless SwapChains on macOS with OpenGL.
+- engine: Add new callback API to SwapChain.
+- engine: Fix SwiftShader crash when using an IBL without a reflections texture.
+- filamat: Shrink internal Skybox material size.
+- filamat: improvements to generated material size.
+- filamat: silence spirv-opt warnings in release builds.
+- matc: Add fog variant filter.
+- matc: Fix crash when building mobile materials.
+- math: reduce template bloat for matrices.
+- Vulkan: robustness improvements.
+
 ## v1.9.9
 
 - Vulkan: internal robustness improvements

android/Windows.md

@@ -6,11 +6,29 @@ In addition to the requirements for [building Filament on Windows](../BUILDING.m
 need the Android SDK and NDK. See [Getting Started with the
 NDK](https://developer.android.com/ndk/guides/) for detailed installation instructions.
 
+You'll also need [Ninja 1.8](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) (or
+more recent) and [Git for Windows](https://git-scm.com/download/win) to clone the repository and run
+Bash scripts.
+
 Ensure the `%ANDROID_HOME%` environment variable is set to your Android SDK installation location.
 
 On Windows, we require VS2019 for building the host tools. All of the following commands should be
 executed in a *Visual Studio x64 Native Tools Command Prompt for VS 2019*.
 
+### A Note About Python 3
+
+Python 3 is required. If CMake errors because it cannot find Python 3:
+
+```
+Could NOT find PythonInterp: Found unsuitable version "1.4", but required is at least "3"
+```
+
+then add the following flag to the CMake invocations:
+
+```
+-DPYTHON_EXECUTABLE:FILEPATH=\path\to\python3
+```
+
 ## Desktop Tools
 
 First, a few Filament tools need to be compiled for desktop.

android/common/CallbackUtils.cpp

@@ -95,3 +95,25 @@ void JniImageCallback::invoke(void*, void* user) {
     JniImageCallback* data = reinterpret_cast<JniImageCallback*>(user);
     delete data;
 }
+
+// -----------------------------------------------------------------------------------------------
+
+JniCallback* JniCallback::make(JNIEnv* env, jobject handler, jobject callback) {
+    return new JniCallback(env, handler, callback);
+}
+
+JniCallback::JniCallback(JNIEnv* env, jobject handler, jobject callback)
+        : mEnv(env)
+        , mHandler(env->NewGlobalRef(handler))
+        , mCallback(env->NewGlobalRef(callback)) {
+    acquireCallbackJni(env, mCallbackUtils);
+}
+
+JniCallback::~JniCallback() {
+    releaseCallbackJni(mEnv, mCallbackUtils, mHandler, mCallback);
+}
+
+void JniCallback::invoke(void* user) {
+    JniCallback* data = reinterpret_cast<JniCallback*>(user);
+    delete data;
+}

android/common/CallbackUtils.h

@@ -62,8 +62,8 @@ struct JniImageCallback {
 
 private:
     JniImageCallback(JNIEnv* env, jobject handler, jobject runnable, long image);
-    JniImageCallback(JniBufferCallback const &) = delete;
-    JniImageCallback(JniBufferCallback&&) = delete;
+    JniImageCallback(JniImageCallback const &) = delete;
+    JniImageCallback(JniImageCallback&&) = delete;
     ~JniImageCallback();
 
     JNIEnv* mEnv;
@@ -72,3 +72,20 @@ struct JniImageCallback {
     long mImage;
     CallbackJni mCallbackUtils;
 };
+
+struct JniCallback {
+    static JniCallback* make(JNIEnv* env, jobject handler, jobject runnable);
+
+    static void invoke(void* user);
+
+private:
+    JniCallback(JNIEnv* env, jobject handler, jobject runnable);
+    JniCallback(JniCallback const &) = delete;
+    JniCallback(JniCallback&&) = delete;
+    ~JniCallback();
+
+    JNIEnv* mEnv;
+    jobject mHandler;
+    jobject mCallback;
+    CallbackJni mCallbackUtils;
+};

android/filament-android/CMakeLists.txt

@@ -17,9 +17,9 @@ add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
 
-add_library(ibl STATIC IMPORTED)
-set_target_properties(ibl PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libibl.a)
+add_library(ibl-lite STATIC IMPORTED)
+set_target_properties(ibl-lite PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libibl-lite.a)
 
 add_library(filaflat STATIC IMPORTED)
 set_target_properties(filaflat PROPERTIES IMPORTED_LOCATION
@@ -70,6 +70,7 @@ add_library(filament-jni SHARED
     src/main/cpp/SkyBox.cpp
     src/main/cpp/Stream.cpp
     src/main/cpp/SurfaceOrientation.cpp
+    src/main/cpp/SwapChain.cpp
     src/main/cpp/Texture.cpp
     src/main/cpp/TextureSampler.cpp
     src/main/cpp/TransformManager.cpp
@@ -91,7 +92,7 @@ target_link_libraries(filament-jni
     PRIVATE filaflat
     PRIVATE filabridge
     PRIVATE geometry
-    PRIVATE ibl
+    PRIVATE ibl-lite
     PRIVATE log
     PRIVATE GLESv3
     PRIVATE EGL

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

@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2020 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.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <jni.h>
+
+#include <filament/SwapChain.h>
+
+#include "common/CallbackUtils.h"
+
+using namespace filament;
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_SwapChain_nSetFrameCompletedCallback(JNIEnv* env, jclass,
+        jlong nativeSwapChain, jobject handler, jobject runnable) {
+    SwapChain* swapChain = (SwapChain*) nativeSwapChain;
+    auto *callback = JniCallback::make(env, handler, runnable);
+    swapChain->setFrameCompletedCallback(&JniCallback::invoke, callback);
+}

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

@@ -104,6 +104,31 @@ public Object getNativeWindow() {
         return mSurface;
     }
 
+    /**
+     * FrameCompletedCallback is a callback function that notifies an application when a frame's
+     * contents have completed rendering on the GPU.
+     *
+     * <p>
+     * Use setFrameCompletedCallback to set a callback on an individual SwapChain. Each time a frame
+     * completes GPU rendering, the callback will be called.
+     * </p>
+     *
+     * <p>
+     * The FrameCompletedCallback is guaranteed to be called on the main Filament thread.
+     * </p>
+     *
+     * <p>
+     * Warning: Only Filament's Metal backend supports frame callbacks. Other backends ignore the
+     * callback (which will never be called) and proceed normally.
+     * </p>
+     *
+     * @param handler     A {@link java.util.concurrent.Executor Executor}.
+     * @param callback    The Runnable callback to invoke.
+     */
+    public void setFrameCompletedCallback(@NonNull Object handler, @NonNull Runnable callback) {
+        nSetFrameCompletedCallback(getNativeObject(), handler, callback);
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed SwapChain");
@@ -114,4 +139,6 @@ public long getNativeObject() {
     void clearNativeObject() {
         mNativeObject = 0;
     }
+
+    private static native void nSetFrameCompletedCallback(long nativeSwapChain, Object handler, Runnable callback);
 }

android/gradle.properties

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

docs/Materials.html

@@ -135,7 +135,7 @@
 </p><ul>
 <li class="minus"><a href="https://github.com/romainguy">Romain Guy</a>, <a href="https://twitter.com/romainguy">@romainguy</a>
 </li>
-<li class="minus"><a href="https://github.com/pixelflinger">Mathias Agopian</a>, <a href="https://twitter.com/darthmoosious">@romainguy</a></li></ul>
+<li class="minus"><a href="https://github.com/pixelflinger">Mathias Agopian</a>, <a href="https://twitter.com/darthmoosious">@darthmoosious</a></li></ul>
 
 <p></p>
 <a class="target" name="overview">&#xA0;</a><a class="target" name="overview">&#xA0;</a><a class="target" name="toc2">&#xA0;</a><h1>Overview</h1>
@@ -2313,7 +2313,7 @@
 <tr><td style="text-align:left"> <strong class="asterisk">getWorldNormalVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized normal in world space, after bump mapping (must be used after <code>prepareMaterial()</code>) </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getWorldGeometricNormalVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Normalized normal in world space, before bump mapping (can be used before <code>prepareMaterial()</code>) </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getWorldReflectedVector()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Reflection of the view vector about the normal (must be used after <code>prepareMaterial()</code>) </td></tr>
-<tr><td style="text-align:left"> <strong class="asterisk">getNormalizedViewportCoord(float2)</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> Normalized viewport position (i.e. clip-space position normalized to [0, 1], can be used before <code>prepareMaterial()</code>) </td></tr>
+<tr><td style="text-align:left"> <strong class="asterisk">getNormalizedViewportCoord()</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> Normalized viewport position (i.e. clip-space position normalized to [0, 1], can be used before <code>prepareMaterial()</code>) </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getNdotV()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> The result of <code>dot(normal, view)</code>, always strictly greater than 0 (must be used after <code>prepareMaterial()</code>) </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getColor()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Interpolated color of the fragment, if the color attribute is required </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getUV0()</strong> </td><td style="text-align:center"> float2 </td><td style="text-align:left"> First interpolated set of UV coordinates, only available if the uv0 attribute is required </td></tr>

docs/Materials.md.html

@@ -13,7 +13,7 @@
 ## Authors
 
 - [Romain Guy](https://github.com/romainguy), [@romainguy](https://twitter.com/romainguy)
-- [Mathias Agopian](https://github.com/pixelflinger), [@romainguy](https://twitter.com/darthmoosious)
+- [Mathias Agopian](https://github.com/pixelflinger), [@darthmoosious](https://twitter.com/darthmoosious)
 
 # Overview
 

filament/CMakeLists.txt

@@ -350,7 +350,7 @@ target_link_libraries(${TARGET} PUBLIC utils)
 target_link_libraries(${TARGET} PUBLIC geometry) # TODO: remove this dependency after deprecating VertexBuffer::populateTangentQuaternions
 target_link_libraries(${TARGET} PUBLIC filaflat)
 target_link_libraries(${TARGET} PUBLIC filabridge)
-target_link_libraries(${TARGET} PUBLIC ibl)
+target_link_libraries(${TARGET} PUBLIC ibl-lite)
 
 if (FILAMENT_ENABLE_MATDBG)
     target_link_libraries(${TARGET} PUBLIC matdbg)

filament/backend/include/backend/DriverEnums.h

@@ -22,6 +22,8 @@
 #include <utils/BitmaskEnum.h>
 #include <utils/unwindows.h> // Because we define ERROR in the FenceStatus enum.
 
+#include <backend/PresentCallable.h>
+
 #include <math/vec4.h>
 
 #include <array>    // FIXME: STL headers are not allowed in public headers
@@ -885,6 +887,11 @@ struct PolygonOffset {
 };
 
 
+using FrameScheduledCallback = void(*)(backend::PresentCallable callable, void* user);
+
+using FrameCompletedCallback = void(*)(void* user);
+
+
 } // namespace backend
 } // namespace filament
 

filament/backend/include/backend/PresentCallable.h

@@ -36,19 +36,21 @@ namespace backend {
  * within a CATransation:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * void myFrameFinishedCallback(PresentCallable presentCallable, void* user) {
+ * void myFrameScheduledCallback(PresentCallable presentCallable, void* user) {
  *     [CATransaction begin];
  *     // Update other UI elements...
  *     presentCallable();
  *     [CATransaction commit];
  * }
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  *
- * To obtain a PresentCallable, pass a backend::FrameFinishedCallback to the beginFrame() function.
- * The callback is called with a PresentCallable object and optional user data:
+ * To obtain a PresentCallable, set a SwapChain::FrameScheduledCallback on a SwapChain with the
+ * SwapChain::setFrameScheduledCallback method. The callback is called with a PresentCallable object
+ * and optional user data:
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- * if (renderer->beginFrame(swapChain, myFrameFinishedCallback, nullptr)) {
+ * swapChain->setFrameScheduledCallback(myFrameScheduledCallback, nullptr);
+ * if (renderer->beginFrame(swapChain)) {
  *     renderer->render(view);
  *     renderer->endFrame();
  * }
@@ -57,14 +59,14 @@ namespace backend {
  * @remark Only Filament's Metal backend supports PresentCallables and frame callbacks. Other
  * backends ignore the callback (which will never be called) and proceed normally.
  *
- * @remark The backend::FrameFinishedCallback is called on an arbitrary thread.
+ * @remark The SwapChain::FrameScheduledCallback is called on an arbitrary thread.
  *
  * Applications *must* call each PresentCallable they receive. Each PresentCallable represents a
  * frame that is waiting to be presented. If an application fails to call a PresentCallable, a
  * memory leak could occur. To "cancel" the presentation of a frame, pass false to the
  * PresentCallable, which will cancel the presentation of the frame and release associated memory.
  *
- * @see Renderer, SwapChain, Renderer.beginFrame
+ * @see Renderer, SwapChain::setFrameScheduledCallback
  */
 class UTILS_PUBLIC PresentCallable {
 public:
@@ -92,18 +94,9 @@ class UTILS_PUBLIC PresentCallable {
 };
 
 /**
- * FrameFinishedCallback is a callback function that notifies an application when Filament has
- * finished processing a frame and that frame is ready to be scheduled for presentation.
- *
- * beginFrame() takes an optional FrameFinishedCallback. If the callback is provided, then that
- * frame will *not* automatically be scheduled for presentation. Instead, the application must call
- * the given PresentCallable.
- *
- * @remark The backend::FrameFinishedCallback is called on an arbitrary thread.
- *
- * @see PresentCallable, beginFrame()
+ * @deprecated, FrameFinishedCallback has been renamed to SwapChain::FrameScheduledCallback.
  */
-using FrameFinishedCallback = void(*)(PresentCallable callable, void* user);
+using FrameFinishedCallback UTILS_DEPRECATED = void(*)(PresentCallable callable, void* user);
 
 } // namespace backend
 } // namespace filament

filament/backend/include/private/backend/DriverAPI.inc

@@ -133,8 +133,16 @@ DECL_DRIVER_API_0(tick)
 
 DECL_DRIVER_API_N(beginFrame,
         int64_t, monotonic_clock_ns,
-        uint32_t, frameId,
-        backend::FrameFinishedCallback, callback,
+        uint32_t, frameId)
+
+DECL_DRIVER_API_N(setFrameScheduledCallback,
+        backend::SwapChainHandle, sch,
+        backend::FrameScheduledCallback, callback,
+        void*, user)
+
+DECL_DRIVER_API_N(setFrameCompletedCallback,
+        backend::SwapChainHandle, sch,
+        backend::FrameCompletedCallback, callback,
         void*, user)
 
 DECL_DRIVER_API_N(setPresentationTime,

filament/backend/src/metal/MetalContext.h

@@ -28,6 +28,7 @@ namespace filament {
 namespace backend {
 namespace metal {
 
+class MetalDriver;
 class MetalBlitter;
 class MetalBufferPool;
 class MetalRenderTarget;
@@ -39,6 +40,7 @@ struct MetalSamplerGroup;
 struct MetalVertexBuffer;
 
 struct MetalContext {
+    MetalDriver* driver;
     id<MTLDevice> device = nullptr;
     id<MTLCommandQueue> commandQueue = nullptr;