Merge branch 'rc/1.63.0' into release

Author: poweifeng

.github/workflows/postsubmit.yml

@@ -50,6 +50,7 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.FILAMENTBOT_TOKEN }}
         run: |
+          bash docs_src/build/install_mdbook.sh && source ~/.bashrc
           COMMIT_HASH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | head -n 1 | sed "s/commit //g")
           git config --global user.email "[email protected]"
           git config --global user.name "Filament Bot"

.github/workflows/presubmit.yml

@@ -130,13 +130,43 @@ jobs:
         run: |
           bash build/common/get-mesa.sh
           pip install tifffile numpy
-      - name: Run Test
+      - name: Render and compare
+        id: render_compare
         run: |
-          echo "${{ steps.get_commit_msg.outputs.msg }}" | bash test/renderdiff/test.sh
+          TEST_DIR=test/renderdiff
+          source ${TEST_DIR}/src/preamble.sh
+          start_
+          GOLDEN_BRANCH=$(echo "${{ steps.get_commit_msg.outputs.msg }}" | python3 ${TEST_DIR}/src/commit_msg.py)
+          bash ${TEST_DIR}/generate.sh && \
+              python3 ${TEST_DIR}/src/golden_manager.py \
+                  --branch=${GOLDEN_BRANCH} \
+                  --output=${GOLDEN_OUTPUT_DIR}
+
+          # Note that we need to upload the output even if comparison fails, so we undo `set -ex`
+          end_
+
+          python3 ${TEST_DIR}/src/compare.py \
+              --src=${GOLDEN_OUTPUT_DIR} \
+              --dest=${RENDER_OUTPUT_DIR} \
+              --out=${DIFF_OUTPUT_DIR} 2>&1 | tee compare_output.txt
+
+          if grep "Failed" compare_output.txt > /dev/null; then
+             DELIMITER="EOF_FILE_CONTENT_$(date +%s)" # Using timestamp to make it more unique
+             echo "err<<$DELIMITER" >> "$GITHUB_OUTPUT"
+             cat compare_output.txt >> "$GITHUB_OUTPUT"
+             echo "$DELIMITER" >> "$GITHUB_OUTPUT"
+          fi
       - uses: actions/upload-artifact@v4
         with:
           name: presubmit-renderdiff-result
           path: ./out/renderdiff
+      - name: Compare result
+        run: |
+          ERROR_STR="${{ steps.render_compare.outputs.err }}"
+          if [ -n "${ERROR_STR}" ]; then
+              echo "${ERROR_STR}"
+              exit 1
+          fi
 
   validate-wgsl-webgpu:
     name: validate-wgsl-webgpu

CMakeLists.txt

@@ -41,6 +41,8 @@ option(FILAMENT_ENABLE_ASAN_UBSAN "Enable Address and Undefined Behavior Sanitiz
 
 option(FILAMENT_ENABLE_TSAN "Enable Thread Sanitizer" OFF)
 
+option(FILAMENT_ENABLE_COVERAGE "Enable LLVM code coverage" OFF)
+
 option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)
 
 option(FILAMENT_ENABLE_MULTIVIEW "Enable multiview for Filament" OFF)
@@ -460,6 +462,10 @@ if (NOT MSVC AND NOT WEBGL)
 endif()
 set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} ${EXTRA_SANITIZE_OPTIONS}")
 
+if (FILAMENT_ENABLE_COVERAGE)
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fprofile-instr-generate -fcoverage-mapping")
+endif()
+
 # Disable the stack check for macOS to workaround a known issue in clang 11.0.0.
 # See: https://forums.developer.apple.com/thread/121887
 if (APPLE)

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.62.2'
+    implementation 'com.google.android.filament:filament-android:1.63.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:
 
 ```shell
-pod 'Filament', '~> 1.62.2'
+pod 'Filament', '~> 1.63.0'
 ```
 
 ## Documentation
@@ -63,7 +63,7 @@ pod 'Filament', '~> 1.62.2'
 - [Materials](https://google.github.io/filament/Materials.html), the full reference
   documentation for our material system. This document explains our different material models, how
   to use the material compiler `matc` and how to write custom materials.
-- [Material Properties](https://google.github.io/filament/Material%20Properties.pdf), a reference
+- [Material Properties](https://google.github.io/filament/notes/material_properties.html), a reference
   sheet for the standard material model.
 
 ## Examples

RELEASE_NOTES.md

@@ -7,6 +7,11 @@ 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.63.0
+
+- Rename `sampler` parameter `unfilterable` to `filterable` [⚠️ **New Material Version**]
+- Added `Renderer::shouldRenderFrame()`
+
 ## v1.62.2
 
 - Metal: fix, respect alpha to coverage rasterization

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

@@ -36,6 +36,12 @@ Java_com_google_android_filament_Renderer_nSkipFrame(JNIEnv *, jclass, jlong nat
     renderer->skipFrame(uint64_t(vsyncSteadyClockTimeNano));
 }
 
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Renderer_nShouldRenderFrame(JNIEnv *, jclass, jlong nativeRenderer) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    return (jboolean) renderer->shouldRenderFrame();
+}
+
 extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_Renderer_nBeginFrame(JNIEnv *, jclass, jlong nativeRenderer,
         jlong nativeSwapChain, jlong frameTimeNanos) {

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

@@ -311,6 +311,21 @@ public void skipFrame(long vsyncSteadyClockTimeNano) {
         nSkipFrame(getNativeObject(), vsyncSteadyClockTimeNano);
     }
 
+    /**
+     * Returns true if the current frame should be rendered.
+     *
+     * This is a convenience method that returns the same value as {@link #beginFrame}.
+     *
+     * @return
+     *      <code>false</code> the current frame should be skipped<br>
+     *      <code>true</code> the current frame can be rendered
+     *
+     * @see #beginFrame
+     */
+    public boolean shouldRenderFrame() {
+        return nShouldRenderFrame(getNativeObject());
+    }
+
     /**
      * Sets up a frame for this <code>Renderer</code>.
      * <p><code>beginFrame</code> manages frame pacing, and returns whether or not a frame should be
@@ -731,6 +746,7 @@ void clearNativeObject() {
     private static native void nSetPresentationTime(long nativeObject, long monotonicClockNanos);
     private static native void nSetVsyncTime(long nativeObject, long steadyClockTimeNano);
     private static native void nSkipFrame(long nativeObject, long vsyncSteadyClockTimeNano);
+    private static native boolean nShouldRenderFrame(long nativeObject);
     private static native boolean nBeginFrame(long nativeRenderer, long nativeSwapChain, long frameTimeNanos);
     private static native void nEndFrame(long nativeRenderer);
     private static native void nRender(long nativeRenderer, long nativeView);

android/gradle.properties

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

build.sh

@@ -54,15 +54,16 @@ function print_help {
     echo "        Build arm64/x86_64 universal libraries."
     echo "        For iOS, this builds universal binaries for devices and the simulator (implies -s)."
     echo "        For macOS, this builds universal binaries for both Apple silicon and Intel-based Macs."
-    echo "    -w"
-    echo "        Build Web documents (compiles .md.html files to .html)."
     echo "    -k sample1,sample2,..."
     echo "        When building for Android, also build select sample APKs."
     echo "        sampleN is an Android sample, e.g., sample-gltf-viewer."
     echo "        This automatically performs a partial desktop build and install."
     echo "    -b"
     echo "        Enable Address and Undefined Behavior Sanitizers (asan/ubsan) for debugging."
     echo "        This is only for the desktop build."
+    echo "    -V"
+    echo "        Enable LLVM code coverage for debug builds."
+    echo "        This is only for the desktop build."
     echo "    -x value"
     echo "        Define a preprocessor flag FILAMENT_BACKEND_DEBUG_FLAG with [value]. This is useful for"
     echo "        enabling debug paths in the backend from the build script. For example, make a"
@@ -182,8 +183,6 @@ BUILD_JS_DOCS=false
 
 ISSUE_CMAKE_ALWAYS=false
 
-ISSUE_WEB_DOCS=false
-
 ANDROID_SAMPLES=()
 BUILD_ANDROID_SAMPLES=false
 
@@ -208,6 +207,7 @@ MATOPT_OPTION=""
 MATOPT_GRADLE_OPTION=""
 
 ASAN_UBSAN_OPTION=""
+COVERAGE_OPTION=""
 
 BACKEND_DEBUG_FLAG_OPTION=""
 
@@ -275,6 +275,7 @@ function build_desktop_target {
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${ASAN_UBSAN_OPTION} \
+            ${COVERAGE_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
             ${STEREOSCOPIC_OPTION} \
             ${OSMESA_OPTION} \
@@ -726,21 +727,6 @@ function build_ios {
     fi
 }
 
-function build_web_docs {
-    echo "Building Web documents..."
-
-    mkdir -p out/web-docs
-    cp -f docs/web-docs-package.json out/web-docs/package.json
-    pushd out/web-docs > /dev/null
-
-    npm install > /dev/null
-
-    # Generate documents
-    npx markdeep-rasterizer ../../docs/Filament.md.html ../../docs/Materials.md.html  ../../docs/
-
-    popd > /dev/null
-}
-
 function validate_build_command {
     set +e
     # Make sure CMake is installed
@@ -772,16 +758,6 @@ function validate_build_command {
         echo "Error: EMSDK is not set, exiting"
         exit 1
     fi
-    # Web documents require node and npm for processing
-    if [[ "${ISSUE_WEB_DOCS}" == "true" ]]; then
-        local node_binary=$(command -v node)
-        local npm_binary=$(command -v npm)
-        local npx_binary=$(command -v npx)
-        if [[ ! "${node_binary}" ]] || [[ ! "${npm_binary}" ]] || [[ ! "${npx_binary}" ]]; then
-            echo "Error: Web documents require node, npm and npx to be installed"
-            exit 1
-        fi
-    fi
 
     # Make sure FILAMENT_BACKEND_DEBUG_FLAG is only meant for debug builds
     if [[ "${ISSUE_DEBUG_BUILD}" != "true" ]] && [[ ! -z "${BACKEND_DEBUG_FLAG_OPTION}" ]]; then
@@ -821,8 +797,7 @@ function run_tests {
 function check_debug_release_build {
     if [[ "${ISSUE_DEBUG_BUILD}" == "true" || \
           "${ISSUE_RELEASE_BUILD}" == "true" || \
-          "${ISSUE_CLEAN}" == "true" || \
-          "${ISSUE_WEB_DOCS}" == "true" ]]; then
+          "${ISSUE_CLEAN}" == "true" ]]; then
         "$@";
     else
         echo "You must declare a debug or release target for $@ builds."
@@ -835,7 +810,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgimp:q:uvWslwedtk:bx:S:X:" opt; do
+while getopts ":hacCfgimp:q:uvWslwedtk:bVx:S:X:" opt; do
     case ${opt} in
         h)
             print_help
@@ -973,16 +948,16 @@ while getopts ":hacCfgimp:q:uvWslwedtk:bx:S:X:" opt; do
             BUILD_UNIVERSAL_LIBRARIES=true
             echo "Building universal libraries."
             ;;
-        w)
-            ISSUE_WEB_DOCS=true
-            ;;
         k)
             BUILD_ANDROID_SAMPLES=true
             ANDROID_SAMPLES=$(echo "${OPTARG}" | tr ',' '\n')
             ;;
         b)  ASAN_UBSAN_OPTION="-DFILAMENT_ENABLE_ASAN_UBSAN=ON"
             echo "Enabled ASAN/UBSAN"
             ;;
+        V)  COVERAGE_OPTION="-DFILAMENT_ENABLE_COVERAGE=ON"
+            echo "Enabled coverage"
+            ;;
         x)  BACKEND_DEBUG_FLAG_OPTION="-DFILAMENT_BACKEND_DEBUG_FLAG=${OPTARG}"
             ;;
         S)  case $(echo "${OPTARG}" | tr '[:upper:]' '[:lower:]') in
@@ -1059,10 +1034,6 @@ if [[ "${ISSUE_WEBGL_BUILD}" == "true" ]]; then
     check_debug_release_build build_webgl
 fi
 
-if [[ "${ISSUE_WEB_DOCS}" == "true" ]]; then
-    build_web_docs
-fi
-
 if [[ "${RUN_TESTS}" == "true" ]]; then
     run_tests
 fi