Fix web morphing sample

fixes #6622

.github/workflows/android-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/android && printf "y" | ./build.sh continuous

.github/workflows/ios-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/ios && printf "y" | ./build.sh continuous

.github/workflows/linux-continuous.yml

@@ -10,10 +10,10 @@ on:
 jobs:
   build-linux:
     name: build-linux
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/linux && printf "y" | ./build.sh continuous

.github/workflows/mac-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/mac && printf "y" | ./build.sh continuous

.github/workflows/presubmit.yml

@@ -15,10 +15,10 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-18.04]
+        os: [macos-latest, ubuntu-22.04]
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           WORKFLOW_OS=`echo \`uname\` | sed "s/Darwin/mac/" | tr [:upper:] [:lower:]`
@@ -32,7 +32,7 @@ jobs:
     runs-on: windows-2019
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           build\windows\build-github.bat presubmit
@@ -43,7 +43,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/android && printf "y" | ./build.sh presubmit
@@ -53,7 +53,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/ios && printf "y" | ./build.sh presubmit
@@ -66,7 +66,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh presubmit

.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-latest, ubuntu-18.04]
+        os: [macos-latest, ubuntu-22.04]
 
     steps:
       - name: Decide Git ref
@@ -39,24 +39,29 @@ jobs:
         run: |
           REF=${RELEASE_TAG:-${GITHUB_REF}}
           TAG=${REF##*/}
-          echo ::set-output name=ref::${REF}
-          echo ::set-output name=tag::${TAG}
-      - uses: actions/checkout@v2.0.0
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@v3.3.0
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - name: Run build script
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
           WORKFLOW_OS=`echo \`uname\` | sed "s/Darwin/mac/" | tr [:upper:] [:lower:]`
           cd build/$WORKFLOW_OS && printf "y" | ./build.sh release
-      - name: Upload release assets
-        run: |
-          xargs -L 1 sudo pip3 install < build/common/requirements.txt
+          cd ../..
           if [ -f out/filament-release-darwin.tgz ]; then mv out/filament-release-darwin.tgz out/filament-${TAG}-mac.tgz; fi;
           if [ -f out/filament-release-linux.tgz ]; then mv out/filament-release-linux.tgz out/filament-${TAG}-linux.tgz; fi;
-          python3 build/common/upload-assets.py ${TAG} out/*.tgz
+      - uses: actions/github-script@v6
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
-          GITHUB_API_KEY: ${{ secrets.GITHUB_API_KEY }}
+        with:
+          script: |
+            const upload = require('./build/common/upload-release-assets');
+            const { TAG } = process.env;
+            const globber = await glob.create('out/*.tgz');
+            await upload({ github, context }, await globber.glob(), TAG);
 
   build-web:
     name: build-web
@@ -69,22 +74,27 @@ jobs:
         run: |
           REF=${RELEASE_TAG:-${GITHUB_REF}}
           TAG=${REF##*/}
-          echo ::set-output name=ref::${REF}
-          echo ::set-output name=tag::${TAG}
-      - uses: actions/checkout@v2.0.0
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@v3.3.0
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - name: Run build script
-        run: |
-          cd build/web && printf "y" | ./build.sh release
-      - name: Upload release assets
-        run: |
-          xargs -L 1 sudo pip3 install < build/common/requirements.txt
-          mv out/filament-release-web.tgz out/filament-${TAG}-web.tgz
-          python3 build/common/upload-assets.py ${TAG} out/*.tgz
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
-          GITHUB_API_KEY: ${{ secrets.GITHUB_API_KEY }}
+        run: |
+          cd build/web && printf "y" | ./build.sh release
+          cd ../..
+          mv out/filament-release-web.tgz out/filament-${TAG}-web.tgz
+      - uses: actions/github-script@v6
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
+        with:
+          script: |
+            const upload = require('./build/common/upload-release-assets');
+            const { TAG } = process.env;
+            const globber = await glob.create('out/*.tgz');
+            await upload({ github, context }, await globber.glob(), TAG);
 
   build-android:
     name: build-android
@@ -97,14 +107,22 @@ jobs:
         run: |
           REF=${RELEASE_TAG:-${GITHUB_REF}}
           TAG=${REF##*/}
-          echo ::set-output name=ref::${REF}
-          echo ::set-output name=tag::${TAG}
-      - uses: actions/checkout@v2.0.0
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@v3.3.0
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - name: Run build script
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
           cd build/android && printf "y" | ./build.sh release
+          cd ../..
+          mv out/filament-android-release.aar out/filament-${TAG}-android.aar
+          mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
+          mv out/filamat-android-lite-release.aar out/filamat-${TAG}-lite-android.aar
+          mv out/gltfio-android-release.aar out/gltfio-${TAG}-android.aar
+          mv out/filament-utils-android-release.aar out/filament-utils-${TAG}-android.aar
       - name: Sign sample-gltf-viewer
         run: |
           echo "${APK_KEYSTORE_BASE64}" > filament.jks.base64
@@ -119,18 +137,15 @@ jobs:
           TAG: ${{ steps.git_ref.outputs.tag }}
           APK_KEYSTORE_BASE64: ${{ secrets.APK_KEYSTORE_BASE64 }}
           APK_KEYSTORE_PASS: ${{ secrets.APK_KEYSTORE_PASS }}
-      - name: Upload release assets
-        run: |
-          xargs -L 1 sudo pip3 install < build/common/requirements.txt
-          mv out/filament-android-release.aar out/filament-${TAG}-android.aar
-          mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
-          mv out/filamat-android-lite-release.aar out/filamat-${TAG}-lite-android.aar
-          mv out/gltfio-android-release.aar out/gltfio-${TAG}-android.aar
-          mv out/filament-utils-android-release.aar out/filament-utils-${TAG}-android.aar
-          python3 build/common/upload-assets.py ${TAG} out/*.aar out/*.apk
+      - uses: actions/github-script@v6
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
-          GITHUB_API_KEY: ${{ secrets.GITHUB_API_KEY }}
+        with:
+          script: |
+            const upload = require('./build/common/upload-release-assets');
+            const { TAG } = process.env;
+            const globber = await glob.create(['out/*.aar', 'out/*.apk'].join('\n'));
+            await upload({ github, context }, await globber.glob(), TAG);
 
   build-ios:
     name: build-ios
@@ -143,22 +158,27 @@ jobs:
         run: |
           REF=${RELEASE_TAG:-${GITHUB_REF}}
           TAG=${REF##*/}
-          echo ::set-output name=ref::${REF}
-          echo ::set-output name=tag::${TAG}
-      - uses: actions/checkout@v2.0.0
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
+      - uses: actions/checkout@v3.3.0
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - name: Run build script
-        run: |
-          cd build/ios && printf "y" | ./build.sh release
-      - name: Upload release assets
-        run: |
-          xargs -L 1 sudo pip3 install < build/common/requirements.txt
-          mv out/filament-release-ios.tgz out/filament-${TAG}-ios.tgz
-          python3 build/common/upload-assets.py ${TAG} out/*.tgz
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
-          GITHUB_API_KEY: ${{ secrets.GITHUB_API_KEY }}
+        run: |
+          cd build/ios && printf "y" | ./build.sh release
+          cd ../..
+          mv out/filament-release-ios.tgz out/filament-${TAG}-ios.tgz
+      - uses: actions/github-script@v6
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
+        with:
+          script: |
+            const upload = require('./build/common/upload-release-assets');
+            const { TAG } = process.env;
+            const globber = await glob.create('out/*.tgz');
+            await upload({ github, context }, await globber.glob(), TAG);
 
   build-windows:
     name: build-windows
@@ -171,22 +191,26 @@ jobs:
         run: |
           REF=${RELEASE_TAG:-${GITHUB_REF}}
           TAG=${REF##*/}
-          echo ::set-output name=ref::${REF}
-          echo ::set-output name=tag::${TAG}
+          echo "ref=${REF}" >> $GITHUB_OUTPUT
+          echo "tag=${TAG}" >> $GITHUB_OUTPUT
         shell: bash
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
         with:
           ref: ${{ steps.git_ref.outputs.ref }}
       - name: Run build script
-        run: |
-          build\windows\build-github.bat release
-        shell: cmd
-      - name: Upload release assets
-        run: |
-          pip3 install PyGithub
-          mv out/filament-windows.tgz out/filament-${TAG}-windows.tgz
-          python build/common/upload-assets.py ${TAG} out/*.tgz
-        shell: bash
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
-          GITHUB_API_KEY: ${{ secrets.GITHUB_API_KEY }}
+        run: |
+          build\windows\build-github.bat release
+          cd ..\..
+          move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
+        shell: cmd
+      - uses: actions/github-script@v6
+        env:
+          TAG: ${{ steps.git_ref.outputs.tag }}
+        with:
+          script: |
+            const upload = require('./build/common/upload-release-assets');
+            const { TAG } = process.env;
+            const globber = await glob.create('out/*.tgz');
+            await upload({ github, context }, await globber.glob(), TAG);

.github/workflows/verify-release-notes.yml

@@ -24,3 +24,4 @@ jobs:
         with:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           pull-request-number: ${{ github.event.pull_request.number }}
+          release-notes-file: 'NEW_RELEASE_NOTES.md'

.github/workflows/web-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: macos-latest
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh continuous

.github/workflows/windows-continuous.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: windows-2019
 
     steps:
-      - uses: actions/checkout@v2.0.0
+      - uses: actions/checkout@v3.3.0
       - name: Run build script
         run: |
           build\windows\build-github.bat continuous

BUILDING.md

@@ -15,7 +15,7 @@ To build Filament for Android you must also install the following:
 
 - Android Studio Arctic Fox or more recent
 - Android SDK
-- Android NDK "side-by-side" 23.1 or higher
+- Android NDK 25.1 or higher
 
 ### Environment variables
 
@@ -92,6 +92,8 @@ Make sure you've installed the following dependencies:
 - `libc++abi-7-dev` (`libcxxabi-static` on Fedora) or higher
 - `ninja-build`
 - `libxi-dev`
+- `libxcomposite-dev` (`libXcomposite-devel` on Fedora)
+- `libxxf86vm-dev` (`libXxf86vm-devel` on Fedora)
 
 After dependencies have been installed, we highly recommend using the [easy build](#easy-build)
 script.
@@ -352,7 +354,7 @@ same version that our continuous builds use.
 
 ```
 cd <your chosen parent folder for the emscripten SDK>
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.9.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 python ./emsdk.py install latest
 python ./emsdk.py activate latest
@@ -368,13 +370,11 @@ export EMSDK=<your chosen home for the emscripten SDK>
 
 The EMSDK variable is required so that the build script can find the Emscripten SDK. The build
 creates a `samples` folder that can be used as the root of a simple static web server. Note that you
-cannot open the HTML directly from the filesystem due to CORS. One way to deal with this is to
-use Python to create a quick localhost server:
+cannot open the HTML directly from the filesystem due to CORS. We recommend using the emrun tool
+to create a quick localhost server:
 
 ```
-cd out/cmake-webgl-release/web/samples
-python3 -m http.server     # Python 3
-python -m SimpleHTTPServer # Python 2.7
+emrun out/cmake-webgl-release/web/samples --no_browser --port 8000
 ```
 
 You can then open http://localhost:8000/suzanne.html in your web browser.

CMakeLists.txt

@@ -31,20 +31,22 @@ option(FILAMENT_SKIP_SDL2 "Skip dependencies of SDL2, and SDL2" OFF)
 
 option(FILAMENT_LINUX_IS_MOBILE "Treat Linux as Mobile" OFF)
 
+option(FILAMENT_ENABLE_ASAN_UBSAN "Enable Address and Undefined Behavior Sanitizers" OFF)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
 
-set(FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB "2" CACHE STRING
-    "Per render pass arena size. Must be roughly 1 MB larger than FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB, default 2."
+set(FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB "3" CACHE STRING
+    "Per render pass arena size. Must be roughly 1 MB larger than FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB, default 3."
 )
 
-set(FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB "1" CACHE STRING
-    "Size of the high-level draw commands buffer. Rule of thumb, 1 MB less than FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB, default 1."
+set(FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB "2" CACHE STRING
+    "Size of the high-level draw commands buffer. Rule of thumb, 1 MB less than FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB, default 2."
 )
 
-set(FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB "1" CACHE STRING
-    "Size of the command-stream buffer. As a rule of thumb use the same value as FILAMENT_PER_FRRAME_COMMANDS_SIZE_IN_MB, default 1."
+set(FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB "2" CACHE STRING
+    "Size of the command-stream buffer. As a rule of thumb use the same value as FILAMENT_PER_FRRAME_COMMANDS_SIZE_IN_MB, default 2."
 )
 
 set(FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB "4" CACHE STRING
@@ -67,25 +69,30 @@ endif()
 # ==================================================================================================
 find_program(CCACHE_PROGRAM ccache)
 if (CCACHE_PROGRAM)
-    set(C_LAUNCHER   "${CCACHE_PROGRAM}")
-    set(CXX_LAUNCHER "${CCACHE_PROGRAM}")
-
-    configure_file(build/launch-c.in   launch-c)
-    configure_file(build/launch-cxx.in launch-cxx)
-
-    execute_process(COMMAND chmod a+rx
-        "${CMAKE_BINARY_DIR}/launch-c"
-        "${CMAKE_BINARY_DIR}/launch-cxx"
-    )
-
-    if (CMAKE_GENERATOR STREQUAL "Xcode")
-        set(CMAKE_XCODE_ATTRIBUTE_CC         "${CMAKE_BINARY_DIR}/launch-c")
-        set(CMAKE_XCODE_ATTRIBUTE_CXX        "${CMAKE_BINARY_DIR}/launch-cxx")
-        set(CMAKE_XCODE_ATTRIBUTE_LD         "${CMAKE_BINARY_DIR}/launch-c")
-        set(CMAKE_XCODE_ATTRIBUTE_LDPLUSPLUS "${CMAKE_BINARY_DIR}/launch-cxx")
+    if (WIN32)
+        set(CMAKE_C_COMPILER_LAUNCHER   "${CCACHE_PROGRAM}")
+        set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
     else()
-        set(CMAKE_C_COMPILER_LAUNCHER        "${CMAKE_BINARY_DIR}/launch-c")
-        set(CMAKE_CXX_COMPILER_LAUNCHER      "${CMAKE_BINARY_DIR}/launch-cxx")
+        set(C_LAUNCHER   "${CCACHE_PROGRAM}")
+        set(CXX_LAUNCHER "${CCACHE_PROGRAM}")
+
+        configure_file(build/launch-c.in   launch-c)
+        configure_file(build/launch-cxx.in launch-cxx)
+
+        execute_process(COMMAND chmod a+rx
+            "${CMAKE_CURRENT_BINARY_DIR}/launch-c"
+            "${CMAKE_CURRENT_BINARY_DIR}/launch-cxx"
+        )
+
+        if (CMAKE_GENERATOR STREQUAL "Xcode")
+            set(CMAKE_XCODE_ATTRIBUTE_CC         "${CMAKE_CURRENT_BINARY_DIR}/launch-c")
+            set(CMAKE_XCODE_ATTRIBUTE_CXX        "${CMAKE_CURRENT_BINARY_DIR}/launch-cxx")
+            set(CMAKE_XCODE_ATTRIBUTE_LD         "${CMAKE_CURRENT_BINARY_DIR}/launch-c")
+            set(CMAKE_XCODE_ATTRIBUTE_LDPLUSPLUS "${CMAKE_CURRENT_BINARY_DIR}/launch-cxx")
+        else()
+            set(CMAKE_C_COMPILER_LAUNCHER        "${CMAKE_CURRENT_BINARY_DIR}/launch-c")
+            set(CMAKE_CXX_COMPILER_LAUNCHER      "${CMAKE_CURRENT_BINARY_DIR}/launch-cxx")
+        endif()
     endif()
 endif()
 
@@ -99,6 +106,10 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 # ==================================================================================================
 if (UNIX AND NOT APPLE AND NOT ANDROID AND NOT WEBGL)
     set(LINUX TRUE)
+else()
+    # since cmake 3.25 LINUX is automatically set based on CMAKE_SYSTEM_NAME, which the android
+    # cmake files are setting to "Linux".
+    set(LINUX FALSE)
 endif()
 
 if (LINUX)
@@ -337,19 +348,23 @@ endif()
 # ==================================================================================================
 # Release compiler flags
 # ==================================================================================================
-if (NOT MSVC)
+if (NOT MSVC AND NOT IOS)
+    # Omitting stack frame pointers prevents the generation of readable stack traces in crash reports on iOS
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fomit-frame-pointer")
 
     # These aren't compatible with -fembed-bitcode (and seem to have no effect on Apple platforms anyway)
-    if (NOT IOS)
-        set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -ffunction-sections -fdata-sections")
-    endif()
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -ffunction-sections -fdata-sections")
 endif()
 
 # On Android RELEASE builds, we disable exceptions and RTTI to save some space (about 75 KiB
 # saved by -fno-exception and 10 KiB saved by -fno-rtti).
 if (ANDROID OR IOS OR WEBGL)
-    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fno-exceptions -fno-unwind-tables -fno-asynchronous-unwind-tables -fno-rtti")
+    set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fno-exceptions -fno-rtti")
+
+    if (ANDROID OR WEBGL)
+        # Omitting unwind info prevents the generation of readable stack traces in crash reports on iOS
+        set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fno-unwind-tables -fno-asynchronous-unwind-tables")
+    endif()
 endif()
 
 # With WebGL, we disable RTTI even for debug builds because we pass emscripten::val back and forth
@@ -359,13 +374,17 @@ if (WEBGL)
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fno-rtti")
 endif()
 
+if (WEBGL_PTHREADS)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread")
+endif()
+
 # ==================================================================================================
 # Debug compiler flags
 # ==================================================================================================
-# ASAN is deactivated for now because:
-#  -fsanitize=undefined causes extremely long link times
-#  -fsanitize=address causes a crash with assimp, which we can't explain for now
-#set(EXTRA_SANITIZE_OPTIONS "-fsanitize=undefined -fsanitize=address")
+if (FILAMENT_ENABLE_ASAN_UBSAN)
+   set(EXTRA_SANITIZE_OPTIONS "-fsanitize=address -fsanitize=undefined")
+endif()
+
 if (NOT MSVC AND NOT WEBGL)
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fstack-protector")
 endif()
@@ -401,8 +420,8 @@ endif()
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS}")
 
-if (WEBGL)
-    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s USE_WEBGL2=1")
+if (WEBGL_PTHREADS)
+    set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -pthread")
 endif()
 
 # ==================================================================================================
@@ -485,9 +504,14 @@ if (FILAMENT_SUPPORTS_METAL)
     set(MATC_API_FLAGS ${MATC_API_FLAGS} -a metal)
 endif()
 
-# Disable optimizations and enable debug info (preserves names in SPIR-V)
+# Enable debug info (preserves names in SPIR-V)
+if (FILAMENT_ENABLE_MATDBG)
+    set(MATC_OPT_FLAGS ${MATC_OPT_FLAGS} -d)
+endif()
+
+# Disable optimizations
 if (FILAMENT_DISABLE_MATOPT)
-    set(MATC_OPT_FLAGS -gd)
+    set(MATC_OPT_FLAGS ${MATC_OPT_FLAGS} -g)
 endif()
 
 set(MATC_BASE_FLAGS ${MATC_API_FLAGS} -p ${MATC_TARGET} ${MATC_OPT_FLAGS})
@@ -542,7 +566,7 @@ function(list_licenses OUTPUT MODULES)
         endif()
     endforeach()
     configure_file(${FILAMENT}/build/licenses.inc.in ${OUTPUT})
-endfunction(list_licenses)
+endfunction()
 
 set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/linux/combine-static-libs.sh")
 if (WIN32)
@@ -662,7 +686,8 @@ add_subdirectory(${EXTERNAL}/imgui/tnt)
 add_subdirectory(${EXTERNAL}/robin-map/tnt)
 add_subdirectory(${EXTERNAL}/smol-v/tnt)
 add_subdirectory(${EXTERNAL}/benchmark/tnt)
-add_subdirectory(${EXTERNAL}/meshoptimizer)
+add_subdirectory(${EXTERNAL}/meshoptimizer/tnt)
+add_subdirectory(${EXTERNAL}/mikktspace)
 add_subdirectory(${EXTERNAL}/cgltf/tnt)
 add_subdirectory(${EXTERNAL}/draco/tnt)
 add_subdirectory(${EXTERNAL}/jsmn/tnt)

CODE_STYLE.md

@@ -164,8 +164,7 @@ private:
 
 ### Strings
 
-- Never use `std::string` in the Filament core renderer. Prefer `utils::CString` or
-  `utils::StaticString`.
+- Never use `std::string` in the Filament core renderer. Prefer `utils::CString` or `std::string_view`.
 - When using `std::string` in tools, always include the `std::` qualifier to disambiguate it
   from other string types.
 

NEW_RELEASE_NOTES.md

@@ -0,0 +1,9 @@
+# Filament Release Notes log
+
+**If you are merging a PR into main**: please add the release note below, under the *Release notes
+for next branch cut* header.
+
+**If you are cherry-picking a commit into an rc/ branch**: add the release note under the
+appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
+
+## Release notes for next branch cut

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.25.4'
+    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.25.4'
+pod 'Filament', '~> 1.32.0'
 ```
 
 ### Snapshots
@@ -117,9 +117,9 @@ steps:
 - Image-based lighting
 - Physically-based camera (shutter speed, sensitivity and aperture)
 - Physical light units
-- Point lights, spot lights and directional light
+- Point lights, spot lights, and directional light
 - Specular anti-aliasing
-- Spot and directional light shadows
+- Point, spot, and directional light shadows
 - Cascaded shadows
 - EVSM, PCSS, DPCF, or PCF shadows
 - Transparent shadows
@@ -179,6 +179,7 @@ steps:
   - [x] KHR_mesh_quantization
   - [x] KHR_texture_basisu
   - [x] KHR_texture_transform
+  - [x] EXT_meshopt_compression
 
 
 ## Rendering with Filament

RELEASE_NOTES.md

@@ -3,7 +3,160 @@
 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.
 
-## main branch
+**Do not edit this file unless you are performing a release or cherry-picking into an rc/ branch.**
+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
+
+- engine: the default render channel is now 2 instead of 0
+- gltfio: Fix crash when a MIME type has no texture provider
+
+## v1.31.5
+
+- gltfio: fix potential early freeing of data provided with `ResourceLoader::addResourceData`.
+
+## v1.31.4
+
+- engine: fix broken picking [⚠️ **Recompile Materials to get the fix**]
+- engine: added support for sRGB swapchains. See `SwapChain.h`
+- bluegl: support Windows32
+
+## v1.31.3
+
+- vulkan: fix memory leak in readPixels
+- engine: added support for draw-commands channels (stronger ordering of commands/renderables)
+
+## v1.31.2
+
+## v1.31.1
+
+- gltfio: expose joint inverse bind matrices via method on FilamentInstance
+- filamesh: add error when uv coords size does not match num of vertices. (#6351)
+
+## v1.31.0
+
+- java: fix confusing typo in Camera documentation
+- engine: the output color space can be set on `ColorGrading`. This API currently has limitations,
+  please refer to the documentation for more details
+- Support for RGTC and BPTC texture compression
+- engine: fix TransformManager high precision mode when using transactions
+- web: added TypeScript definition for `Engine.destroy`
+- materials: `getNormalizedViewportCoord()` now returns the logical (i.e. user) viewport
+             normalized position and keeps z reversed [⚠️ **Recompile Materials**]
+- backend: workaround Adreno shader compiler bug (#6355) [⚠️ **Recompile Materials**]
+- geometry: change computing tangent basis from normal vector to use Frisvad's method
+
+## v1.30.0
+
+- engine: optimize per-shadow UBO [⚠️ **Recompile Materials**]
+- engine: fix potential memory corruption with larger scenes
+- engine: VSM's MSAA setting is now per-view instead of per-light [⚠️ **API Change**]
+
+## v1.29.0
+
+- gltfio: calculate primitive's AABB correctly.
+- gltfio: recompute bounding boxes with morph targets
+- engine: add missing getters on `MaterialInstance`
+- WebGL: add missing `ColorGrading` JS bindings
+- engine: improvements/cleanup of Shadow mapping code [⚠️ **Recompile Materials**]
+
+## v1.28.3
+
+
+- backend: add support for GGP platform
+- engine: primitives with `CullingMode::FRONT_AND_BACK` are now skipped.
+
+## v1.28.2
+
+- gltfio: support EXT_meshopt_compression
+- release packaging: fixed location of default IBL file
+
+## v1.28.1
+
+- gltfio: fix reloading crash in ubershader mode
+- Vulkan: improve performance in the readPixels path
+- engine: raise the spot shadows limit to 64, from 14.
+- engine: add experimental support for point light shadows.
+- gltfio: fix ubershader issues with assignment of dummy textures
+- gltfio: material instances and variants are now accessed via `FilamentInstance` [⚠️ **API Change**]
+- gltfio: the animator can now only be accessed via `FilamentInstance` [⚠️ **API Change**]
+- engine: fix "stable" shadows and make the default cascade splits logarithmic.
+- engine: Add new quality options to EVSM shadows + rendering fixes
+
+## v1.28.0
+
+- engine: LiSPSM is now a user settable option
+- engine: get the morph target buffer to the given primitive
+- Java: Fix TransformManager.getChildren()
+- Metal: newer devices are no longer limited to 16 samplers per Material.
+- gltfio: fix interpretation of occlusion strength
+- engine: minsdk is now 21 instead of 19. This allows the use of OpenGL ES 3.1
+- Vulkan: fix black screen regression
+
+## v1.27.2
+
+- gltfio: punctual lights are now duplicated when adding new asset instances
+- gltfio: FilamentInstance getAsset method now returns an immutable asset
+- gltfio: allow zero-instance assets
+- gltfio: fix regression with meshes that have no material
+- gltfio: fix regression with recomputeBoundingBoxes()
+- filamesh / matinfo: fix minor ASAN issues
+- engine: Added `Engine::resetBackendState()`, available only in WebGL builds
+
+## v1.27.1
+
+- Java: add methods for TransformManager.getChildCount(), TransformManager.getChildren() and Scene.hasEntity()
+- engine: Fix stencil buffer writes with OpenGL backend.
+- gltfio: add new virtual method to MaterialProvider that all plugins must implement
+- gltfio: add an assert for inconsistent sRGB flags among usages of a particular texture
+- engine: improve scissor documentation
+- backend: scissor is no longer clipped to the viewport (done on filament side)
+- samples: add debug overdraw visualization to gltf_viewer
+
+## v1.27.0
+
+- WebGL: reduce max instance count to work around Chrome issues [⚠️ **Recompile Materials**]
+- engine: rework material/shader sampler binding code [⚠️ **Recompile Materials**]
+- gltfio: move the API for `recomputeBoundingBoxes` [⚠️ **API Change**]
+- engine: add support for specialization constants [⚠️ **Recompile Materials**]
+- gltfio: fix spotlight regression
+- gltfio: clear the MaterialInstance cache when creating new instances
+
+## v1.26.0
+
+- engine: new feature level APIs, see `Engine::getSupportedFeatureLevel()`
+- engine: add new stencil API to `View` and stencil state APIs to `MaterialInstance` [**NEW API**].
+- engine: Fix guard bands and TAA with `vertexDomain:Device` [⚠️ **Recompile Materials**]
+- engine: `clipSpaceTransform` is now only available with `vertexDomain:Device` [⚠️ **API Change**]
+- gltfio: add unified `AssetLoader::createAsset()` method [⚠️ **API Change**]
+- gltfio: all assets are now "instanced" [⚠️ **API Change**]
+
+## v1.25.6
+
+- engine: Add `CONFIG_MINSPEC_UBO_SIZE` as a nicer way to allow exceeding the ES3.0 minspec.
+- gltfio: minor efficiency improvement for Android and WebGL builds.
+- gltfio: add support for concurrent texture downloading and decoding.
+
+## v1.25.5
+
+- WebGL: upgraded the JS bindings to work with emsdk 3.1.15
+- WebGL: added missing IBL builder to TypeScript annotations
+- engine: Fix incorrect precision restoration when computing accurate world translations
+- engine: make `MaterialInstance` public API friendly to `std::string_view` parameters
+- gltfio: add 'detach' methods to allow ownership transfer of entities and components
 
 ## v1.25.4
 

android/build.gradle

@@ -12,7 +12,10 @@
 //     When set, support for Vulkan will be excluded.
 //
 // com.google.android.filament.matdbg
-//     When set, enables matdbg, disables shader optimizations
+//     When set, enables matdbg
+//
+// com.google.android.filament.matnopt
+//     When set, disable shader optimizations.
 //
 // com.google.android.filament.skip-samples
 //     Exclude samples from the project. Useful to speed up compilation.
@@ -29,15 +32,12 @@
 
 // Publishing to Maven Central:
 //   - Build and upload artifacts with ./gradlew publish
-//   - Close and release staging repo on Nexus with ./gradlew closeAndReleaseRepository
+//   - Close and release staging repo on Nexus with ./gradlew closeAndReleaseStagingRepository
 //
 // The following is needed in ~/gradle/gradle.properties:
 //
-//     SONATYPE_NEXUS_USERNAME=nexus_user
-//     SONATYPE_NEXUS_PASSWORD=nexus_password
-//
-//     nexusUsername=nexus_user
-//     nexusPassword=nexus_password
+//     sonatypeUsername=nexus_user
+//     sonatypePassword=nexus_password
 //
 //     signing.keyId=pgp_key_id
 //     signing.password=pgp_key_password
@@ -47,7 +47,7 @@
 buildscript {
     def path = providers
             .gradleProperty("com.google.android.filament.dist-dir")
-            .forUseAtConfigurationTime().get()
+            .get()
 
     def directory = objects.fileProperty().fileValue(new File(path)).getAsFile().get()
     def filamentPath = directory.absolutePath
@@ -59,18 +59,19 @@ buildscript {
     // Warning: changing this property does not work well with incremental builds.
     def excludeVulkan = providers
             .gradleProperty("com.google.android.filament.exclude-vulkan")
-            .forUseAtConfigurationTime()
             .isPresent()
 
     def matdbg = providers
             .gradleProperty("com.google.android.filament.matdbg")
-            .forUseAtConfigurationTime()
+            .isPresent()
+
+    def matnopt = providers
+            .gradleProperty("com.google.android.filament.matnopt")
             .isPresent()
 
     def abis = ["arm64-v8a", "armeabi-v7a", "x86_64", "x86"]
     def newAbis = providers
             .gradleProperty("com.google.android.filament.abis")
-            .forUseAtConfigurationTime()
             .get()
             .split(',')
     if (!newAbis.contains("all")) {
@@ -79,18 +80,20 @@ buildscript {
 
     ext.versions = [
         'minSdk': 19,
-        'targetSdk': 31,
-        'compileSdk': 31,
-        'kotlin': '1.7.10',
-        'kotlin_coroutines': '1.6.1',
-        'buildTools': '33.0.0',
-        'ndk': '25.0.8775105'
+        'targetSdk': 33,
+        'compileSdk': 33,
+        'kotlin': '1.8.0',
+        'kotlin_coroutines': '1.6.4',
+        'buildTools': '33.0.1',
+        'ndk': '25.1.8937393',
+        'androidx_core': '1.9.0',
+        'androidx_annotations': '1.3.0'
     ]
 
     ext.deps = [
         'androidx': [
-            'annotations': "androidx.annotation:annotation:1.3.0",
-            'core': "androidx.core:core:1.7.0",
+            'annotations': "androidx.annotation:annotation:${versions.androidx_annotations}",
+            'core': "androidx.core:core:${versions.androidx_core}",
         ],
         'kotlin': "org.jetbrains.kotlin:kotlin-stdlib-jdk8:${versions.kotlin}",
         'coroutines': [
@@ -100,8 +103,7 @@ buildscript {
     ]
 
     dependencies {
-        // NOTE: See TODO in gradle.properties once we move to Gradle 7.4
-        classpath 'com.android.tools.build:gradle:7.2.1'
+        classpath 'com.android.tools.build:gradle:7.4.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 
@@ -113,7 +115,7 @@ buildscript {
         "-DFILAMENT_DIST_DIR=${filamentPath}".toString(),
         "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString(),
         "-DFILAMENT_ENABLE_MATDBG=${matdbg ? 'ON' : 'OFF'}".toString(),
-        "-DFILAMENT_DISABLE_MATOPT=${matdbg ? 'ON' : 'OFF'}".toString()
+        "-DFILAMENT_DISABLE_MATOPT=${matnopt ? 'ON' : 'OFF'}".toString()
     ]
 
     ext.cppFlags = [
@@ -148,14 +150,18 @@ buildscript {
 }
 
 plugins {
-    id 'io.codearte.nexus-staging' version '0.30.0'
+    id "io.github.gradle-nexus.publish-plugin" version "1.1.0"
 }
 
-// Nexus Staging configuration
-// See https://github.com/Codearte/gradle-nexus-staging-plugin/
-nexusStaging {
+// See https://github.com/gradle-nexus/publish-plugin
+// Publish to https://oss.sonatype.org/ (not s01)
+nexusPublishing {
     packageGroup = 'com.google.android'
-    stagingProfileId = '9a75a224a4f17b'
+    repositories {
+        sonatype {
+            stagingProfileId = '9a75a224a4f17b'
+        }
+    }
 }
 
 subprojects {

android/filamat-android/src/main/cpp/MaterialBuilder.cpp

@@ -126,8 +126,8 @@ Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderUniform
         JNIEnv* env, jclass, jlong nativeBuilder, jint uniformType, jint precision, jstring name_) {
     auto builder = (MaterialBuilder*) nativeBuilder;
     const char* name = env->GetStringUTFChars(name_, nullptr);
-    builder->parameter((MaterialBuilder::UniformType) uniformType,
-            (MaterialBuilder::ParameterPrecision) precision, name);
+    builder->parameter(name, (MaterialBuilder::UniformType) uniformType,
+            (MaterialBuilder::ParameterPrecision) precision);
     env->ReleaseStringUTFChars(name_, name);
 }
 
@@ -137,8 +137,8 @@ Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderUniform
         jstring name_) {
     auto builder = (MaterialBuilder*) nativeBuilder;
     const char* name = env->GetStringUTFChars(name_, nullptr);
-    builder->parameter((MaterialBuilder::UniformType) uniformType, (size_t) size,
-            (MaterialBuilder::ParameterPrecision) precision, name);
+    builder->parameter(name, (size_t) size, (MaterialBuilder::UniformType) uniformType,
+            (MaterialBuilder::ParameterPrecision) precision);
     env->ReleaseStringUTFChars(name_, name);
 }
 
@@ -148,9 +148,8 @@ Java_com_google_android_filament_filamat_MaterialBuilder_nMaterialBuilderSampler
         jint precision, jstring name_) {
     auto builder = (MaterialBuilder*) nativeBuilder;
     const char* name = env->GetStringUTFChars(name_, nullptr);
-    builder->parameter((MaterialBuilder::SamplerType) samplerType,
-            (MaterialBuilder::SamplerFormat) format, (MaterialBuilder::ParameterPrecision) precision,
-            name);
+    builder->parameter(name, (MaterialBuilder::SamplerType) samplerType,
+            (MaterialBuilder::SamplerFormat) format, (MaterialBuilder::ParameterPrecision) precision);
     env->ReleaseStringUTFChars(name_, name);
 }
 
@@ -251,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) {

android/filamat-android/src/main/java/com/google/android/filament/filamat/MaterialBuilder.java

@@ -360,6 +360,12 @@ public class MaterialBuilder {
         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 @@ public class MaterialBuilder {
     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);

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

@@ -328,3 +328,24 @@ Java_com_google_android_filament_Engine_nIsAutomaticInstancingEnabled(JNIEnv*, j
     Engine* engine = (Engine*) nativeEngine;
     return (jboolean)engine->isAutomaticInstancingEnabled();
 }
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nGetSupportedFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->getSupportedFeatureLevel();
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nSetActiveFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine, jint ordinal) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->setActiveFeatureLevel((Engine::FeatureLevel)ordinal);
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->getActiveFeatureLevel();
+}

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

@@ -76,10 +76,10 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env, jclass,
         jlong nativeBuilder, jint mapSize, jint cascades, jfloatArray splitPositions,
         jfloat constantBias, jfloat normalBias, jfloat shadowFar, jfloat shadowNearHint,
-        jfloat shadowFarHint, jboolean stable,
+        jfloat shadowFarHint, jboolean stable, jboolean lispsm,
         jfloat polygonOffsetConstant, jfloat polygonOffsetSlope,
         jboolean screenSpaceContactShadows, jint stepCount,
-        jfloat maxShadowDistance, jint vsmMsaaSamples, jfloat blurWidth, jfloat shadowBulbRadius) {
+        jfloat maxShadowDistance, jboolean elvsm, jfloat blurWidth, jfloat shadowBulbRadius) {
     LightManager::Builder *builder = (LightManager::Builder *) nativeBuilder;
     LightManager::ShadowOptions shadowOptions {
             .mapSize = (uint32_t)mapSize,
@@ -90,13 +90,14 @@ Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env,
             .shadowNearHint = shadowNearHint,
             .shadowFarHint = shadowFarHint,
             .stable = (bool)stable,
+            .lispsm = (bool)lispsm,
             .polygonOffsetConstant = polygonOffsetConstant,
             .polygonOffsetSlope = polygonOffsetConstant,
             .screenSpaceContactShadows = (bool)screenSpaceContactShadows,
             .stepCount = uint8_t(stepCount),
             .maxShadowDistance = maxShadowDistance,
             .vsm = {
-                    .msaaSamples = (uint8_t) vsmMsaaSamples,
+                    .elvsm = (bool)elvsm,
                     .blurWidth = blurWidth
             },
             .shadowBulbRadius = shadowBulbRadius

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,

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

@@ -341,6 +341,14 @@ Java_com_google_android_filament_MaterialInstance_nSetDepthWrite(JNIEnv*,
     instance->setDepthWrite(enable);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilWrite(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jboolean enable) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilWrite(enable);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_MaterialInstance_nSetDepthCulling(JNIEnv*,
@@ -349,6 +357,70 @@ Java_com_google_android_filament_MaterialInstance_nSetDepthCulling(JNIEnv*,
     instance->setDepthCulling(enable);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilCompareFunction(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong function, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilCompareFunction(
+            static_cast<MaterialInstance::StencilCompareFunc>(function),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpStencilFail(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpStencilFail(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpDepthFail(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpDepthFail(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpDepthStencilPass(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpDepthStencilPass(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilReferenceValue(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint value, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilReferenceValue(value, static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilReadMask(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint readMask, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilReadMask(readMask, static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilWriteMask(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint writeMask, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilWriteMask(writeMask, static_cast<MaterialInstance::StencilFace>(face));
+}
+
 extern "C"
 JNIEXPORT jstring JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetName(JNIEnv* env, jclass,
@@ -380,3 +452,75 @@ Java_com_google_android_filament_MaterialInstance_nDuplicate(JNIEnv* env, jclass
     }
     return (jlong)mi;
 }
+
+extern "C"
+JNIEXPORT jfloat JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetMaskThreshold(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->getMaskThreshold();
+}
+
+extern "C"
+JNIEXPORT jfloat JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingVariance(JNIEnv* env,
+        jclass clazz, jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->getSpecularAntiAliasingVariance();
+}
+
+extern "C"
+JNIEXPORT jfloat JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetSpecularAntiAliasingThreshold(JNIEnv* env,
+        jclass clazz, jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->getSpecularAntiAliasingThreshold();
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsDoubleSided(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->isDoubleSided();
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetCullingMode(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return (jint)instance->getCullingMode();
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsColorWriteEnabled(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->isColorWriteEnabled();
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsDepthWriteEnabled(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->isDepthWriteEnabled();
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsStencilWriteEnabled(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->isStencilWriteEnabled();
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_MaterialInstance_nIsDepthCullingEnabled(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return instance->isDepthCullingEnabled();
+}

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

@@ -150,6 +150,13 @@ Java_com_google_android_filament_RenderableManager_nBuilderPriority(JNIEnv*, jcl
     builder->priority((uint8_t) priority);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderChannel(JNIEnv*, jclass,
+        jlong nativeBuilder, jint channel) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    builder->channel((uint8_t) channel);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nBuilderCulling(JNIEnv*, jclass,
         jlong nativeBuilder, jboolean enabled) {
@@ -339,6 +346,13 @@ Java_com_google_android_filament_RenderableManager_nSetPriority(JNIEnv*, jclass,
     rm->setPriority((RenderableManager::Instance) i, (uint8_t) priority);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nSetChannel(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint channel) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    rm->setChannel((RenderableManager::Instance) i, (uint8_t) channel);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetCulling(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jboolean enabled) {

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

@@ -83,3 +83,11 @@ Java_com_google_android_filament_Scene_nGetLightCount(JNIEnv *env, jclass type,
     Scene* scene = (Scene*) nativeScene;
     return (jint) scene->getLightCount();
 }
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Scene_nHasEntity(JNIEnv *env, jclass type, jlong nativeScene,
+        jint entityId) {
+    Scene* scene = (Scene*) nativeScene;
+    Entity entity = Entity::import(entityId);
+    return (jboolean) scene->hasEntity(entity);
+}

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

@@ -16,6 +16,7 @@
 
 #include <jni.h>
 
+#include <filament/Engine.h>
 #include <filament/SwapChain.h>
 
 #include "common/CallbackUtils.h"
@@ -32,3 +33,9 @@ Java_com_google_android_filament_SwapChain_nSetFrameCompletedCallback(JNIEnv* en
         JniCallback::postToJavaAndDestroy(callback);
     }, callback);
 }
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_SwapChain_nIsSRGBSwapChainSupported(JNIEnv *, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (bool)SwapChain::isSRGBSwapChainSupported(*engine);
+}

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

@@ -110,6 +110,26 @@ Java_com_google_android_filament_TransformManager_nGetParent(JNIEnv*, jclass,
     return tm->getParent((TransformManager::Instance) i).getId();
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_TransformManager_nGetChildCount(JNIEnv*, jclass,
+        jlong nativeTransformManager, jint i) {
+    TransformManager* tm = (TransformManager*) nativeTransformManager;
+    return tm->getChildCount((TransformManager::Instance) i);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_TransformManager_nGetChildren(JNIEnv* env,
+        jclass, jlong nativeTransformManager, jint i,
+        jintArray outEntities_, jint count) {
+    TransformManager* tm = (TransformManager*) nativeTransformManager;
+    jint* entities = env->GetIntArrayElements(outEntities_, nullptr);
+    // This is very very gross, we just pretend Entity is just like an jint
+    // (which it is), but still.
+    tm->getChildren((TransformManager::Instance) i,
+            reinterpret_cast<Entity *>(entities), (size_t) count);
+    env->ReleaseIntArrayElements(outEntities_, entities, 0);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_TransformManager_nSetTransform(JNIEnv* env,
         jclass, jlong nativeTransformManager, jint i,

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

@@ -149,12 +149,13 @@ Java_com_google_android_filament_View_nSetShadowType(JNIEnv*, jclass, jlong nati
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetVsmShadowOptions(JNIEnv*, jclass, jlong nativeView,
-        jint anisotropy, jboolean mipmapping, jfloat minVarianceScale,
+        jint anisotropy, jboolean mipmapping, jboolean highPrecision, jfloat minVarianceScale,
         jfloat lightBleedReduction) {
     View* view = (View*) nativeView;
     View::VsmShadowOptions options;
     options.anisotropy = (uint8_t)anisotropy;
     options.mipmapping = (bool)mipmapping;
+    options.highPrecision = (bool)highPrecision;
     options.minVarianceScale = minVarianceScale;
     options.lightBleedReduction = lightBleedReduction;
     view->setVsmShadowOptions(options);
@@ -462,6 +463,21 @@ Java_com_google_android_filament_View_nPick(JNIEnv* env, jclass,
     }, callback->getHandler());
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetStencilBufferEnabled(JNIEnv *, jclass, jlong nativeView,
+        jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setStencilBufferEnabled(enabled);
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsStencilBufferEnabled(JNIEnv *, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return view->isStencilBufferEnabled();
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,

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

@@ -365,7 +365,7 @@ public class Camera {
      * By default, this is an identity matrix.
      * </p>
      *
-     * @param scaling     diagonal of the scaling matrix to be applied after the projection matrix.
+     * @param inScaling     diagonal of the scaling matrix to be applied after the projection matrix.
      *
      * @see Camera#setProjection
      * @see Camera#setLensProjection
@@ -409,7 +409,7 @@ public class Camera {
      *
      * <pre>
      *  engine.getTransformManager().setTransform(
-     *          engine.getTransformManager().getInstance(camera->getEntity()), viewMatrix);
+     *          engine.getTransformManager().getInstance(camera->getEntity()), modelMatrix);
      * </pre>
      *
      * @param modelMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.

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

@@ -47,7 +47,7 @@ import com.google.android.filament.proguard.UsedByReflection;
  * <pre>
  * import com.google.android.filament.*
  *
- * Engin engine         = Engine.create();
+ * Engine engine        = Engine.create();
  * SwapChain swapChain  = engine.createSwapChain(nativeWindow);
  * Renderer renderer    = engine.createRenderer();
  * Scene scene          = engine.createScene();
@@ -107,6 +107,7 @@ import com.google.android.filament.proguard.UsedByReflection;
  */
 public class Engine {
     private static final Backend[] sBackendValues = Backend.values();
+    private static final FeatureLevel[] sFeatureLevelValues = FeatureLevel.values();
 
     private long mNativeObject;
 
@@ -141,6 +142,18 @@ public class Engine {
         NOOP,
     }
 
+    /**
+     * Defines the backend's feature levels.
+     */
+    public enum FeatureLevel {
+        /** Reserved, don't use */
+        FEATURE_LEVEL_0,
+        /** OpenGL ES 3.0 features (default) */
+        FEATURE_LEVEL_1,
+        /** OpenGL ES 3.1 features + 31 textures units + cubemap arrays */
+        FEATURE_LEVEL_2
+    };
+
     private Engine(long nativeEngine) {
         mNativeObject = nativeEngine;
         mTransformManager = new TransformManager(nGetTransformManager(nativeEngine));
@@ -269,6 +282,50 @@ public class Engine {
         getTransformManager().setAccurateTranslationsEnabled(true);
     }
 
+    /**
+     * Query the feature level supported by the selected backend.
+     *
+     * A specific feature level needs to be set before the corresponding features can be used.
+     *
+     * @return FeatureLevel supported the selected backend.
+     * @see #setActiveFeatureLevel
+     */
+    @NonNull
+    public FeatureLevel getSupportedFeatureLevel() {
+        return sFeatureLevelValues[(int) nGetSupportedFeatureLevel(getNativeObject())];
+    }
+
+    /**
+     * Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
+     * active. The selected feature level must not be higher than the value returned by
+     * getActiveFeatureLevel() and it's not possible lower the active feature level.
+     *
+     * @param featureLevel the feature level to activate. If featureLevel is lower than
+     *                     getActiveFeatureLevel(), the current (higher) feature level is kept.
+     *                     If featureLevel is higher than getSupportedFeatureLevel(), an exception
+     *                     is thrown, or the program is terminated if exceptions are disabled.
+     *
+     * @return the active feature level.
+     *
+     * @see #getSupportedFeatureLevel
+     * @see #getActiveFeatureLevel
+     */
+    @NonNull
+    public FeatureLevel setActiveFeatureLevel(@NonNull FeatureLevel featureLevel) {
+        return sFeatureLevelValues[(int) nSetActiveFeatureLevel(getNativeObject(), featureLevel.ordinal())];
+    }
+
+    /**
+     * Returns the currently active feature level.
+     * @return currently active feature level
+     * @see #getSupportedFeatureLevel
+     * @see #setActiveFeatureLevel
+     */
+    @NonNull
+    public FeatureLevel getActiveFeatureLevel() {
+        return sFeatureLevelValues[(int) nGetActiveFeatureLevel(getNativeObject())];
+    }
+
     /**
      * Enables or disables automatic instancing of render primitives. Instancing of render primitive
      * can greatly reduce CPU overhead but requires the instanced primitives to be identical
@@ -289,7 +346,7 @@ public class Engine {
 
     /**
      * @return true if automatic instancing is enabled, false otherwise.
-     * @see setAutomaticInstancingEnabled
+     * @see #setAutomaticInstancingEnabled
      */
     public boolean isAutomaticInstancingEnabled() {
         return nIsAutomaticInstancingEnabled(getNativeObject());
@@ -760,4 +817,7 @@ public class Engine {
     private static native long nGetEntityManager(long nativeEngine);
     private static native void nSetAutomaticInstancingEnabled(long nativeEngine, boolean enable);
     private static native boolean nIsAutomaticInstancingEnabled(long nativeEngine);
+    private static native int nGetSupportedFeatureLevel(long nativeEngine);
+    private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
+    private static native int nGetActiveFeatureLevel(long nativeEngine);
 }

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

@@ -240,7 +240,7 @@ public class LightManager {
          */
         @NonNull
         @Size(min = 3)
-        public float[] cascadeSplitPositions = { 0.25f, 0.50f, 0.75f };
+        public float[] cascadeSplitPositions = { 0.125f, 0.25f, 0.50f };
 
         /** Constant bias in world units (e.g. meters) by which shadows are moved away from the
          * light. 1mm by default.
@@ -280,9 +280,25 @@ public class LightManager {
          * Controls whether the shadow map should be optimized for resolution or stability.
          * When set to true, all resolution enhancing features that can affect stability are
          * disabling, resulting in significantly lower resolution shadows, albeit stable ones.
+         *
+         * Setting this flag to true always disables LiSPSM (see below).
          */
         public boolean stable = false;
 
+        /**
+         * LiSPSM, or light-space perspective shadow-mapping is a technique allowing to better
+         * optimize the use of the shadow-map texture. When enabled the effective resolution of
+         * shadows is greatly improved and yields result similar to using cascades without the
+         * extra cost. LiSPSM comes with some drawbacks however, in particular it is incompatible
+         * with blurring because it effectively affects the blur kernel size.
+         *
+         * Blurring is only an issue when using ShadowType.VSM with a large blur or with
+         * ShadowType.PCSS however.
+         *
+         * If these blurring artifacts become problematic, this flag can be used to disable LiSPSM.
+         */
+        public boolean lispsm = false;
+
         /**
          * Constant bias in depth-resolution units by which shadows are moved away from the
          * light. The default value of 0.5 is used to round depth values up.
@@ -334,17 +350,12 @@ public class LightManager {
          */
 
         /**
-         * The number of MSAA samples to use when rendering VSM shadow maps.
-         * Must be a power-of-two and greater than or equal to 1. A value of 1 effectively turns
-         * off MSAA.
-         * Higher values may not be available depending on the underlying hardware.
-         *
-         * <p>
-         * <strong>Warning: This API is still experimental and subject to change.</strong>
-         * </p>
+         * When elvsm is set to true, "Exponential Layered VSM without Layers" are used. It is
+         * an improvement to the default EVSM which suffers important light leaks. Enabling
+         * ELVSM for a single shadowmap doubles the memory usage of all shadow maps.
+         * ELVSM is mostly useful when large blurs are used.
          */
-        @IntRange(from = 1)
-        public int vsmMsaaSamples = 1;
+        public boolean elvsm = false;
 
         /**
          * Blur width for the VSM blur. Zero do disable.
@@ -470,11 +481,6 @@ public class LightManager {
         /**
          * Whether this Light casts shadows (disabled by default)
          *
-         * <p>
-         * <b>warning:</b>
-         *  {@link Type#POINT} lights cannot cast shadows.
-         * </p>
-         *
          * @param enable Enables or disables casting shadows from this Light.
          *
          * @return This Builder, for chaining calls.
@@ -496,11 +502,11 @@ public class LightManager {
             nBuilderShadowOptions(mNativeBuilder,
                     options.mapSize, options.shadowCascades, options.cascadeSplitPositions,
                     options.constantBias, options.normalBias, options.shadowFar, options.shadowNearHint,
-                    options.shadowFarHint, options.stable,
+                    options.shadowFarHint, options.stable, options.lispsm,
                     options.polygonOffsetConstant, options.polygonOffsetSlope,
                     options.screenSpaceContactShadows,
-                    options.stepCount, options.maxShadowDistance, options.vsmMsaaSamples,
-                    options.blurWidth, options.shadowBulbRadius);
+                    options.stepCount, options.maxShadowDistance,
+                    options.elvsm, options.blurWidth, options.shadowBulbRadius);
             return this;
         }
 
@@ -998,8 +1004,6 @@ public class LightManager {
      *                      lightbulbs.
      *
      * @param efficiency    Efficiency in percent. This depends on the type of lightbulb used.
-     *
-     * @return This Builder, for chaining calls.
      */
     public void setIntensity(@EntityInstance int i, float watts, float efficiency) {
         nSetIntensity(mNativeObject, i , watts, efficiency);
@@ -1158,7 +1162,14 @@ public class LightManager {
     private static native void nDestroyBuilder(long nativeBuilder);
     private static native boolean nBuilderBuild(long nativeBuilder, long nativeEngine, int entity);
     private static native void nBuilderCastShadows(long nativeBuilder, boolean enable);
-    private static native void nBuilderShadowOptions(long nativeBuilder, int mapSize, int cascades, float[] splitPositions, float constantBias, float normalBias, float shadowFar, float shadowNearHint, float shadowFarhint, boolean stable, float polygonOffsetConstant, float polygonOffsetSlope, boolean screenSpaceContactShadows, int stepCount, float maxShadowDistance, int vsmMsaaSamples, float blurWidth, float shadowBulbRadius);
+    private static native void nBuilderShadowOptions(long nativeBuilder, int mapSize,
+            int cascades, float[] splitPositions,
+             float constantBias, float normalBias,
+             float shadowFar, float shadowNearHint, float shadowFarhint,
+             boolean stable, boolean lispsm,
+             float polygonOffsetConstant, float polygonOffsetSlope,
+             boolean screenSpaceContactShadows, int stepCount, float maxShadowDistance,
+             boolean elvsm, float blurWidth, float shadowBulbRadius);
     private static native void nBuilderCastLight(long nativeBuilder, boolean enabled);
     private static native void nBuilderPosition(long nativeBuilder, float x, float y, float z);
     private static native void nBuilderDirection(long nativeBuilder, float x, float y, float z);

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

@@ -36,6 +36,7 @@ import java.util.Set;
  *
  * @see <a href="https://google.github.io/filament/Materials.html">Filament Materials Guide</a>
  */
+@UsedByNative("AssetLoader.cpp")
 public class Material {
     static final class EnumCache {
         private EnumCache() { }
@@ -502,6 +503,17 @@ public class Material {
         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.
      *
@@ -914,6 +926,7 @@ public class Material {
     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);

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

@@ -20,7 +20,11 @@ import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
 import androidx.annotation.Size;
 
+import com.google.android.filament.proguard.UsedByNative;
+
+@UsedByNative("AssetLoader.cpp")
 public class MaterialInstance {
+    private static final Material.CullingMode[] sCullingModeValues = Material.CullingMode.values();
     private Material mMaterial;
     private String mName;
     private long mNativeObject;
@@ -49,6 +53,54 @@ public class MaterialInstance {
         MAT4
     }
 
+    /**
+     * Operations that control how the stencil buffer is updated.
+     */
+    public enum StencilOperation {
+        /**
+         * Keeps the current value.
+         */
+        KEEP,
+        /**
+         * Sets the value to 0.
+         */
+        ZERO,
+        /**
+         * Sets the value to the stencil reference value.
+         */
+        REPLACE,
+        /**
+         * Increments the current value. Clamps to the maximum representable unsigned value.
+         */
+        INCR_CLAMP,
+        /**
+         * Increments the current value. Wraps value to zero when incrementing the maximum
+         * representable unsigned value.
+         */
+        INCR_WRAP,
+        /**
+         * Decrements the current value. Clamps to 0.
+         */
+        DECR_CLAMP,
+        /**
+         * Decrements the current value. Wraps value to the maximum representable unsigned value
+         * when decrementing a value of zero.
+         */
+        DECR_WRAP,
+        /**
+         * Bitwise inverts the current value.
+         */
+        INVERT,
+    }
+
+    public enum StencilFace {
+        FRONT,
+        BACK,
+        FRONT_AND_BACK
+    }
+    // Converts the StencilFace enum ordinal to Filament's equivalent bit field.
+    static final int[] sStencilFaceMapping = {0x1, 0x2, 0x3};
+
     public MaterialInstance(Engine engine, long nativeMaterialInstance) {
         mNativeObject = nativeMaterialInstance;
         mNativeMaterial = nGetMaterial(mNativeObject);
@@ -351,19 +403,40 @@ public class MaterialInstance {
     }
 
     /**
-     * Set up a custom scissor rectangle; by default this encompasses the View.
+     * Set-up a custom scissor rectangle; by default it is disabled.
      *
-     * @param left      left coordinate of the scissor box
-     * @param bottom    bottom coordinate of the scissor box
+     * <p>
+     * The scissor rectangle gets clipped by the View's viewport, in other words, the scissor
+     * cannot affect fragments outside of the View's Viewport.
+     * </p>
+     *
+     * <p>
+     * Currently the scissor is not compatible with dynamic resolution and should always be
+     * disabled when dynamic resolution is used.
+     * </p>
+     *
+     * @param left      left coordinate of the scissor box relative to the viewport
+     * @param bottom    bottom coordinate of the scissor box relative to the viewport
      * @param width     width of the scissor box
      * @param height    height of the scissor box
+     *
+     * @see #unsetScissor
+     * @see View#setViewport
+     * @see View#setDynamicResolutionOptions
      */
     public void setScissor(@IntRange(from = 0) int left, @IntRange(from = 0) int bottom,
             @IntRange(from = 0) int width, @IntRange(from = 0) int height) {
         nSetScissor(getNativeObject(), left, bottom, width, height);
     }
 
-    /** Returns the scissor rectangle to its default setting, which encompasses the View. */
+    /**
+     * Returns the scissor rectangle to its default disabled setting.
+     * <p>
+     * Currently the scissor is not compatible with dynamic resolution and should always be
+     * disabled when dynamic resolution is used.
+     * </p>
+     * @see View#setDynamicResolutionOptions
+     */
     public void unsetScissor() {
         nUnsetScissor(getNativeObject());
     }
@@ -401,6 +474,14 @@ public class MaterialInstance {
         nSetMaskThreshold(getNativeObject(), threshold);
     }
 
+    /**
+     * Gets the minimum alpha value a fragment must have to not be discarded when the blend
+     * mode is MASKED
+     */
+    public float getMaskThreshold() {
+        return nGetMaskThreshold(getNativeObject());
+    }
+
     /**
      * Sets the screen space variance of the filter kernel used when applying specular
      * anti-aliasing. The default value is set to 0.15. The specified value should be between
@@ -414,6 +495,14 @@ public class MaterialInstance {
         nSetSpecularAntiAliasingVariance(getNativeObject(), variance);
     }
 
+    /**
+     * Gets the screen space variance of the filter kernel used when applying specular
+     * anti-aliasing.
+     */
+    public float getSpecularAntiAliasingVariance() {
+        return nGetSpecularAntiAliasingVariance(getNativeObject());
+    }
+
     /**
      * Sets the clamping threshold used to suppress estimation errors when applying specular
      * anti-aliasing. The default value is set to 0.2. The specified value should be between 0
@@ -427,6 +516,14 @@ public class MaterialInstance {
         nSetSpecularAntiAliasingThreshold(getNativeObject(), threshold);
     }
 
+    /**
+     * Gets the clamping threshold used to suppress estimation errors when applying specular
+     * anti-aliasing.
+     */
+    public float getSpecularAntiAliasingThreshold() {
+        return nGetSpecularAntiAliasingThreshold(getNativeObject());
+    }
+
     /**
      * Enables or disables double-sided lighting if the parent Material has double-sided capability,
      * otherwise prints a warning. If double-sided lighting is enabled, backface culling is
@@ -440,6 +537,14 @@ public class MaterialInstance {
         nSetDoubleSided(getNativeObject(), doubleSided);
     }
 
+    /**
+     * Returns whether double-sided lighting is enabled when the parent Material has double-sided
+     * capability.
+     */
+    public boolean isDoubleSided() {
+        return nIsDoubleSided(getNativeObject());
+    }
+
     /**
      * Overrides the default triangle culling state that was set on the material.
      *
@@ -447,10 +552,18 @@ public class MaterialInstance {
      * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/rasterization:culling">
      * Rasterization: culling</a>
      */
-    public void setCullingMode(Material.CullingMode mode) {
+    public void setCullingMode(@NonNull Material.CullingMode mode) {
         nSetCullingMode(getNativeObject(), mode.ordinal());
     }
 
+    /**
+     * Returns the face culling mode.
+     */
+    @NonNull
+    public Material.CullingMode getCullingMode() {
+        return sCullingModeValues[nGetCullingMode(getNativeObject())];
+    }
+
     /**
      * Overrides the default color-buffer write state that was set on the material.
      *
@@ -462,6 +575,13 @@ public class MaterialInstance {
         nSetColorWrite(getNativeObject(), enable);
     }
 
+    /**
+     * Returns whether color write is enabled.
+     */
+    public boolean isColorWriteEnabled() {
+        return nIsColorWriteEnabled(getNativeObject());
+    }
+
     /**
      * Overrides the default depth-buffer write state that was set on the material.
      *
@@ -473,6 +593,27 @@ public class MaterialInstance {
         nSetDepthWrite(getNativeObject(), enable);
     }
 
+    /**
+     * Returns whether depth write is enabled.
+     */
+    public boolean isDepthWriteEnabled() {
+        return nIsDepthWriteEnabled(getNativeObject());
+    }
+
+    /**
+     * Enables or Disable stencil writes
+     */
+    public void setStencilWrite(boolean enable) {
+        nSetStencilWrite(getNativeObject(), enable);
+    }
+
+    /**
+     * Returns whether stencil write is enabled.
+     */
+    public boolean isStencilWriteEnabled() {
+        return nIsStencilWriteEnabled(getNativeObject());
+    }
+
     /**
      * Overrides the default depth testing state that was set on the material.
      *
@@ -484,6 +625,215 @@ public class MaterialInstance {
         nSetDepthCulling(getNativeObject(), enable);
     }
 
+    /**
+     * Returns whether depth culling is enabled.
+     */
+    public boolean isDepthCullingEnabled() {
+        return nIsDepthCullingEnabled(getNativeObject());
+    }
+
+    /**
+     * Sets the stencil comparison function (default is {@link TextureSampler.CompareFunction#ALWAYS}).
+     *
+     * <p>
+     * It's possible to set separate stencil comparison functions; one for front-facing polygons,
+     * and one for back-facing polygons. The face parameter determines the comparison function(s)
+     * updated by this call.
+     * </p>
+     *
+     * @param func the stencil comparison function
+     * @param face the faces to update the comparison function for
+     */
+    public void setStencilCompareFunction(TextureSampler.CompareFunction func, StencilFace face) {
+        nSetStencilCompareFunction(getNativeObject(), func.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil comparison function for both front and back-facing polygons.
+     * @see #setStencilCompareFunction(TextureSampler.CompareFunction, StencilFace)
+     */
+    public void setStencilCompareFunction(TextureSampler.CompareFunction func) {
+        setStencilCompareFunction(func, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil fail operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The stencil fail operation is performed to update values in the stencil buffer when the
+     * stencil test fails.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil fail operations; one for front-facing polygons, and one
+     * for back-facing polygons. The face parameter determines the stencil fail operation(s) updated
+     * by this call.
+     * </p>
+     *
+     * @param op the stencil fail operation
+     * @param face the faces to update the stencil fail operation for
+     */
+    public void setStencilOpStencilFail(StencilOperation op, StencilFace face) {
+        nSetStencilOpStencilFail(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil fail operation for both front and back-facing polygons.
+     * @see #setStencilOpStencilFail(StencilOperation, StencilFace)
+     */
+    public void setStencilOpStencilFail(StencilOperation op) {
+        setStencilOpStencilFail(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the depth fail operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The depth fail operation is performed to update values in the stencil buffer when the depth
+     * test fails.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate depth fail operations; one for front-facing polygons, and one
+     * for back-facing polygons. The face parameter determines the depth fail operation(s) updated
+     * by this call.
+     * </p>
+     *
+     * @param op the depth fail operation
+     * @param face the faces to update the depth fail operation for
+     */
+    public void setStencilOpDepthFail(StencilOperation op, StencilFace face) {
+        nSetStencilOpDepthFail(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the depth fail operation for both front and back-facing polygons.
+     * @see #setStencilOpDepthFail(StencilOperation, StencilFace)
+     */
+    public void setStencilOpDepthFail(StencilOperation op) {
+        setStencilOpDepthFail(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the depth-stencil pass operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The depth-stencil pass operation is performed to update values in the stencil buffer when
+     * both the stencil test and depth test pass.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate depth-stencil pass operations; one for front-facing polygons,
+     * and one for back-facing polygons. The face parameter determines the depth-stencil pass
+     * operation(s) updated by this call.
+     * </p>
+     *
+     * @param op the depth-stencil pass operation
+     * @param face the faces to update the depth-stencil operation for
+     */
+    public void setStencilOpDepthStencilPass(StencilOperation op, StencilFace face) {
+        nSetStencilOpDepthStencilPass(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the depth-stencil pass operation for both front and back-facing polygons.
+     * @see #setStencilOpDepthStencilPass(StencilOperation, StencilFace)
+     */
+    public void setStencilOpDepthStencilPass(StencilOperation op) {
+        setStencilOpDepthStencilPass(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil reference value (default is 0).
+     *
+     * <p>
+     * The stencil reference value is the left-hand side for stencil comparison tests. It's also
+     * used as the replacement stencil value when {@link StencilOperation} is
+     * {@link StencilOperation#REPLACE}.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil reference values; one for front-facing polygons, and
+     * one for back-facing polygons. The face parameter determines the reference value(s) updated by
+     * this call.
+     * </p>
+     *
+     * @param value the stencil reference value (only the least significant 8 bits are used)
+     * @param face the faces to update the reference value for
+     */
+    public void setStencilReferenceValue(@IntRange(from = 0, to = 255) int value, StencilFace face) {
+        nSetStencilReferenceValue(getNativeObject(), value, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil reference value for both front and back-facing polygons.
+     * @see #setStencilReferenceValue(int, StencilFace)
+     */
+    public void setStencilReferenceValue(@IntRange(from = 0, to = 255) int value) {
+        setStencilReferenceValue(value, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil read mask (default is 0xFF).
+     *
+     * <p>
+     * The stencil read mask masks the bits of the values participating in the stencil comparison
+     * test- both the value read from the stencil buffer and the reference value.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil read masks; one for front-facing polygons, and one for
+     * back-facing polygons. The face parameter determines the stencil read mask(s) updated by this
+     * call.
+     * </p>
+     *
+     * @param readMask the read mask (only the least significant 8 bits are used)
+     * @param face the faces to update the read mask for
+     */
+    public void setStencilReadMask(@IntRange(from = 0, to = 255) int readMask, StencilFace face) {
+        nSetStencilReadMask(getNativeObject(), readMask, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil read mask for both front and back-facing polygons.
+     * @see #setStencilReadMask(int, StencilFace)
+     */
+    public void setStencilReadMask(@IntRange(from = 0, to = 255) int readMask) {
+        setStencilReadMask(readMask, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil write mask (default is 0xFF).
+     *
+     * <p>
+     * The stencil write mask masks the bits in the stencil buffer updated by stencil operations.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil write masks; one for front-facing polygons, and one for
+     * back-facing polygons. The face parameter determines the stencil write mask(s) updated by this
+     * call.
+     * </p>
+     *
+     * @param writeMask the write mask (only the least significant 8 bits are used)
+     * @param face the faces to update the read mask for
+     */
+    public void setStencilWriteMask(@IntRange(from = 0, to = 255) int writeMask, StencilFace face) {
+        nSetStencilWriteMask(getNativeObject(), writeMask, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil write mask for both front and back-facing polygons.
+     * @see #setStencilWriteMask(int, StencilFace)
+     */
+    public void setStencilWriteMask(int writeMask) {
+        setStencilWriteMask(writeMask, StencilFace.FRONT_AND_BACK);
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed MaterialInstance");
@@ -556,10 +906,37 @@ public class MaterialInstance {
     private static native void nSetCullingMode(long nativeMaterialInstance, long mode);
     private static native void nSetColorWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetDepthWrite(long nativeMaterialInstance, boolean enable);
+    private static native void nSetStencilWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetDepthCulling(long nativeMaterialInstance, boolean enable);
 
+    private static native void nSetStencilCompareFunction(long nativeMaterialInstance,
+            long function, long face);
+    private static native void nSetStencilOpStencilFail(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilOpDepthFail(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilOpDepthStencilPass(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilReferenceValue(long nativeMaterialInstance, int value,
+            long face);
+    private static native void nSetStencilReadMask(long nativeMaterialInstance, int readMask,
+            long face);
+    private static native void nSetStencilWriteMask(long nativeMaterialInstance, int writeMask,
+            long face);
+
     private static native String nGetName(long nativeMaterialInstance);
     private static native long nGetMaterial(long nativeMaterialInstance);
 
     private static native long nDuplicate(long otherNativeMaterialInstance, String name);
+
+
+    private static native float nGetMaskThreshold(long nativeMaterialInstance);
+    private static native float nGetSpecularAntiAliasingVariance(long nativeMaterialInstance);
+    private static native float nGetSpecularAntiAliasingThreshold(long nativeMaterialInstance);
+    private static native boolean nIsDoubleSided(long nativeMaterialInstance);
+    private static native int nGetCullingMode(long nativeMaterialInstance);
+    private static native boolean nIsColorWriteEnabled(long nativeMaterialInstance);
+    private static native boolean nIsDepthWriteEnabled(long nativeMaterialInstance);
+    private static native boolean nIsStencilWriteEnabled(long nativeMaterialInstance);
+    private static native boolean nIsDepthCullingEnabled(long nativeMaterialInstance);
 }

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

@@ -257,23 +257,79 @@ public class RenderableManager {
          * Provides coarse-grained control over draw order.
          *
          * <p>In general Filament reserves the right to re-order renderables to allow for efficient
-         * rendering. However clients can control ordering at a coarse level using <em>priority</em>.</p>
+         * rendering. However clients can control ordering at a coarse level using \em priority.
+         * The priority is applied separately for opaque and translucent objects, that is, opaque
+         * objects are always drawn before translucent objects regardless of the priority.</p>
          *
          * <p>For example, this could be used to draw a semitransparent HUD, if a client wishes to
          * avoid using a separate View for the HUD. Note that priority is completely orthogonal to
          * {@link Builder#layerMask}, which merely controls visibility.</p>
+
+         * <p>The Skybox always using the lowest priority, so it's drawn last, which may improve
+         * performance.</p>
          *
          * <p>The priority is clamped to the range [0..7], defaults to 4; 7 is lowest priority
          * (rendered last).</p>
          *
          * @see Builder#blendOrder
          */
+
+        /**
+         * Provides coarse-grained control over draw order.
+         *
+         * <p>In general Filament reserves the right to re-order renderables to allow for efficient
+         * rendering. However clients can control ordering at a coarse level using priority.
+         * The priority is applied separately for opaque and translucent objects, that is, opaque
+         * objects are always drawn before translucent objects regardless of the priority.</p>
+         *
+         * <p>For example, this could be used to draw a semitransparent HUD, if a client wishes to
+         * avoid using a separate View for the HUD. Note that priority is completely orthogonal to
+         * {@link Builder#layerMask}, which merely controls visibility.</p>
+
+         * <p>The Skybox always using the lowest priority, so it's drawn last, which may improve
+         * performance.</p>
+         *
+         * @param priority clamped to the range [0..7], defaults to 4; 7 is lowest priority
+         *                 (rendered last).
+         *
+         * @return Builder reference for chaining calls.
+         *
+         * @see Builder#channel
+         * @see Builder#blendOrder
+         * @see #setPriority
+         * @see #setBlendOrderAt
+         */
         @NonNull
         public Builder priority(@IntRange(from = 0, to = 7) int priority) {
             nBuilderPriority(mNativeBuilder, priority);
             return this;
         }
 
+        /**
+         * Set the channel this renderable is associated to. There can be 4 channels.
+         *
+         * <p>All renderables in a given channel are rendered together, regardless of anything else.
+         * They are sorted as usual within a channel.</p>
+         * <p>Channels work similarly to priorities, except that they enforce the strongest
+         * ordering.</p>
+         *
+         * <p>Channels 0 and 1 may not have render primitives using a material with `refractionType`
+         * set to `screenspace`.</p>
+         *
+         * @param channel clamped to the range [0..3], defaults to 2.
+         *
+         * @return Builder reference for chaining calls.
+         *
+         * @see Builder::blendOrder()
+         * @see Builder::priority()
+         * @see RenderableManager::setBlendOrderAt()
+         */
+        @NonNull
+        public Builder channel(@IntRange(from = 0, to = 3) int channel) {
+            nBuilderChannel(mNativeBuilder, channel);
+            return this;
+        }
+
         /**
          * Controls frustum culling, true by default.
          *
@@ -655,6 +711,15 @@ public class RenderableManager {
         nSetPriority(mNativeObject, i, priority);
     }
 
+    /**
+     * Changes the channel of a renderable
+     *
+     * @see Builder#channel
+     */
+    public void setChannel(@EntityInstance int i, @IntRange(from = 0, to = 3) int channel) {
+        nSetChannel(mNativeObject, i, channel);
+    }
+
     /**
      * Changes whether or not frustum culling is on.
      *
@@ -876,6 +941,7 @@ public class RenderableManager {
     private static native void nBuilderBoundingBox(long nativeBuilder, float cx, float cy, float cz, float ex, float ey, float ez);
     private static native void nBuilderLayerMask(long nativeBuilder, int select, int value);
     private static native void nBuilderPriority(long nativeBuilder, int priority);
+    private static native void nBuilderChannel(long nativeBuilder, int channel);
     private static native void nBuilderCulling(long nativeBuilder, boolean enabled);
     private static native void nBuilderCastShadows(long nativeBuilder, boolean enabled);
     private static native void nBuilderReceiveShadows(long nativeBuilder, boolean enabled);
@@ -898,6 +964,7 @@ public class RenderableManager {
     private static native void nSetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float cx, float cy, float cz, float ex, float ey, float ez);
     private static native void nSetLayerMask(long nativeRenderableManager, int i, int select, int value);
     private static native void nSetPriority(long nativeRenderableManager, int i, int priority);
+    private static native void nSetChannel(long nativeRenderableManager, int i, int channel);
     private static native void nSetCulling(long nativeRenderableManager, int i, boolean enabled);
     private static native void nSetLightChannel(long nativeRenderableManager, int i, int channel, boolean enable);
     private static native boolean nGetLightChannel(long nativeRenderableManager, int i, int channel);

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

@@ -124,7 +124,24 @@ public class Renderer {
      */
     public static class ClearOptions {
         /**
-         * Color to use to clear the SwapChain
+         * Color (sRGB linear) to use to clear the RenderTarget (typically the SwapChain).
+         *
+         * The RenderTarget is cleared using this color, which won't be tone-mapped since
+         * tone-mapping is part of View rendering (this is not).
+         *
+         * When a View is rendered, there are 3 scenarios to consider:
+         * - Pixels rendered by the View replace the clear color (or blend with it in
+         *   `BlendMode.TRANSLUCENT` mode).
+         *
+         * - With blending mode set to `BlendMode.TRANSLUCENT`, Pixels untouched by the View
+         *   are considered fulling transparent and let the clear color show through.
+         *
+         * - With blending mode set to `BlendMode.OPAQUE`, Pixels untouched by the View
+         *   are set to the clear color. However, because it is now used in the context of a View,
+         *   it will go through the post-processing stage, which includes tone-mapping.
+         *
+         * For consistency, it is recommended to always use a Skybox to clear an opaque View's
+         * background, or to use black or fully-transparent (i.e. {0,0,0,0}) as the clear color.
          */
         @NonNull
         public float[] clearColor = { 0.0f, 0.0f, 0.0f, 0.0f };

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

@@ -163,6 +163,15 @@ public class Scene {
         return nGetLightCount(getNativeObject());
     }
 
+    /**
+     * Returns true if the given entity is in the Scene.
+     *
+     * @return Whether the given entity is in the Scene.
+     */
+    public boolean hasEntity(@Entity int entity) {
+        return nHasEntity(getNativeObject(), entity);
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed Scene");
@@ -182,4 +191,5 @@ public class Scene {
     private static native void nRemoveEntities(long nativeScene, int[] entities);
     private static native int nGetRenderableCount(long nativeScene);
     private static native int nGetLightCount(long nativeScene);
+    private static native boolean nHasEntity(long nativeScene, int entity);
 }

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

@@ -29,7 +29,6 @@ import java.nio.ReadOnlyBufferException;
  * Stream supports three different configurations:
  *
  * <dl>
- * <dt>TEXTURE_ID</dt>   <dd>takes an OpenGL texture ID and incurs a copy</dd>
  * <dt>ACQUIRED</dt>     <dd>connects to an Android AHardwareBuffer</dd>
  * <dt>NATIVE</dt>       <dd>connects to an Android SurfaceTexture</dd>
  * </dl>
@@ -66,12 +65,6 @@ import java.nio.ReadOnlyBufferException;
  * </ul>
  *
  * <p>
- * The <b>TEXTURE_ID</b> configuration achieves synchronization automatically. In this mode,
- * Filament performs a copy on the main thread during beginFrame by blitting the external image into
- * an internal round-robin queue of images. This copy has a run-time cost.
- * </p>
- *
- * <p>
  * For <b>ACQUIRED</b> streams, there is no need to perform the copy because Filament explictly
  * acquires the stream, then releases it later via a callback function. This configuration is
  * especially useful when the Vulkan backend is enabled.
@@ -118,8 +111,7 @@ public class Stream {
      * By default, Stream objects are {@link StreamType#ACQUIRED ACQUIRED} and must have external images pushed to them via
      * {@link #setAcquiredImage}.
      *
-     * To create a {@link StreamType#NATIVE NATIVE} stream, call one of the <pre>stream</pre> methods
-     * on the builder.
+     * To create a {@link StreamType#NATIVE NATIVE} stream, call the <pre>stream</pre> method on the builder.
      */
     public static class Builder {
         @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"}) // Keep to finalize native resources
@@ -211,7 +203,7 @@ public class Stream {
     }
 
     /**
-     * Indicates whether this <code>Stream</code> is NATIVE, TEXTURE_ID, or ACQUIRED.
+     * Indicates whether this <code>Stream</code> is NATIVE or ACQUIRED.
      */
     public StreamType getStreamType() {
         return sStreamTypeValues[nGetStreamType(getNativeObject())];
@@ -230,7 +222,7 @@ public class Stream {
      * also where the callback is invoked. This method can only be used for streams that were
      * constructed without calling the {@link Builder.stream} method.
      *
-     * See {@link Stream} for more information about NATIVE, TEXTURE_ID, and ACQUIRED configurations.
+     * See {@link Stream} for more information about NATIVE and ACQUIRED configurations.
      *
      * @param hwbuffer {@link android.hardware.HardwareBuffer HardwareBuffer} (requires API level 26)
      * @param handler {@link java.util.concurrent.Executor Executor} or {@link android.os.Handler Handler}.

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

@@ -91,11 +91,34 @@ public class SwapChain {
      */
     public static final long CONFIG_ENABLE_XCB = 0x4;
 
+    /**
+     * Indicates that the SwapChain must automatically perform linear to sRGB encoding.
+     *
+     * This flag is ignored if isSRGBSwapChainSupported() is false.
+     *
+     * When using this flag, post-processing should be disabled.
+     *
+     * @see SwapChain#isSRGBSwapChainSupported
+     * @see View#setPostProcessingEnabled
+     */
+    public static final long CONFIG_SRGB_COLORSPACE = 0x10;
+
     SwapChain(long nativeSwapChain, Object surface) {
         mNativeObject = nativeSwapChain;
         mSurface = surface;
     }
 
+    /**
+     * Return whether createSwapChain supports the SWAP_CHAIN_CONFIG_SRGB_COLORSPACE flag.
+     * The default implementation returns false.
+     *
+     * @param engine A reference to the filament Engine
+     * @return true if SWAP_CHAIN_CONFIG_SRGB_COLORSPACE is supported, false otherwise.
+     */
+    public static boolean isSRGBSwapChainSupported(@NonNull Engine engine) {
+        return nIsSRGBSwapChainSupported(engine.getNativeObject());
+    }
+
     /**
      * @return the native <code>Object</code> this <code>SwapChain</code> was created from or null
      *         for a headless SwapChain.
@@ -141,4 +164,5 @@ public class SwapChain {
     }
 
     private static native void nSetFrameCompletedCallback(long nativeSwapChain, Object handler, Runnable callback);
+    private static native boolean nIsSRGBSwapChainSupported(long nativeEngine);
 }

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

@@ -250,7 +250,19 @@ public class Texture {
         SRGB8_ALPHA8_ASTC_10x8,
         SRGB8_ALPHA8_ASTC_10x10,
         SRGB8_ALPHA8_ASTC_12x10,
-        SRGB8_ALPHA8_ASTC_12x12
+        SRGB8_ALPHA8_ASTC_12x12,
+
+        // RGTC formats available with a GLES extension
+        RED_RGTC1,              // BC4 unsigned
+        SIGNED_RED_RGTC1,       // BC4 signed
+        RED_GREEN_RGTC2,        // BC5 unsigned
+        SIGNED_RED_GREEN_RGTC2, // BC5 signed
+
+        // BPTC formats available with a GLES extension
+        RGB_BPTC_SIGNED_FLOAT,  // BC6H signed
+        RGB_BPTC_UNSIGNED_FLOAT,// BC6H unsigned
+        RGBA_BPTC_UNORM,        // BC7
+        SRGB_ALPHA_BPTC_UNORM   // BC7 sRGB
     }
 
     /**
@@ -296,7 +308,19 @@ public class Texture {
         SRGB8_ALPHA8_ASTC_10x8,
         SRGB8_ALPHA8_ASTC_10x10,
         SRGB8_ALPHA8_ASTC_12x10,
-        SRGB8_ALPHA8_ASTC_12x12
+        SRGB8_ALPHA8_ASTC_12x12,
+
+        // RGTC formats available with a GLES extension
+        RED_RGTC1,              // BC4 unsigned
+        SIGNED_RED_RGTC1,       // BC4 signed
+        RED_GREEN_RGTC2,        // BC5 unsigned
+        SIGNED_RED_GREEN_RGTC2, // BC5 signed
+
+        // BPTC formats available with a GLES extension
+        RGB_BPTC_SIGNED_FLOAT,  // BC6H signed
+        RGB_BPTC_UNSIGNED_FLOAT,// BC6H unsigned
+        RGBA_BPTC_UNORM,        // BC7
+        SRGB_ALPHA_BPTC_UNORM   // BC7 sRGB
     }
 
     /**
@@ -884,7 +908,7 @@ public class Texture {
     // TODO: add a setImage() version that takes an android Bitmap
 
     /**
-     * <code>setImage</code> is used to modify the whole content of the texure from a CPU-buffer.
+     * <code>setImage</code> is used to modify the whole content of the texture from a CPU-buffer.
      *
      *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D SAMPLER_2D} or
      *  {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}. If the later is specified
@@ -951,11 +975,11 @@ public class Texture {
     }
 
     /**
-     * <code>setImage</code> is used to modify a sub-region of the 3D texture or 2D texture array
-     * from a CPU-buffer.
+     * <code>setImage</code> is used to modify a sub-region of a 3D texture, 2D texture array or
+     * cubemap from a CPU-buffer. Cubemaps are treated like a 2D array of six layers.
      *
-     *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D_ARRAY SAMPLER_2D_ARRAY} or
-     *  {@link Sampler#SAMPLER_3D SAMPLER_3D}.</p>
+     *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D_ARRAY SAMPLER_2D_ARRAY},
+     *  {@link Sampler#SAMPLER_3D SAMPLER_3D} or {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}.</p>
      *
      * @param engine    {@link Engine} this texture is associated to. Must be the
      *                  instance passed to {@link Builder#build Builder.build()}.

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

@@ -276,7 +276,7 @@ public class TextureSampler {
     }
 
     /**
-     * Sets the wrapping mode in the t (depth) direction.
+     * Sets the wrapping mode in the r (depth) direction.
      * @param mode wrapping mode
      */
     public void setWrapModeR(WrapMode mode) {

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

@@ -16,6 +16,7 @@
 
 package com.google.android.filament;
 
+import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.Size;
@@ -199,6 +200,36 @@ import androidx.annotation.Size;
         return nGetParent(mNativeObject, i);
     }
 
+    /**
+     * Returns the number of children of an {@link EntityInstance}.
+     *
+     * @param i the {@link EntityInstance} of the transform component to query.
+     * @return The number of children of the queried component.
+     */
+    public int getChildCount(@EntityInstance int i) {
+        return nGetChildCount(mNativeObject, i);
+    }
+
+    /**
+     * Gets a list of children for a transform component.
+     *
+     * @param i           the {@link EntityInstance} of the transform component to get the children
+     *                    from.
+     * @param outEntities array to receive the result sized to the maximum number of children to
+     *                    retrieve. If <code>null</code> is given, a new suitable array sized to
+     *                    {@link #getChildCount(int)} is allocated.
+     * @return Array of retrieved children {@link Entity}.
+     */
+    public @Entity @NonNull int[] getChildren(@EntityInstance int i, @Nullable int[] outEntities) {
+        if (outEntities == null) {
+            outEntities = new int[getChildCount(i)];
+        }
+        if (outEntities.length > 0) {
+            nGetChildren(mNativeObject, i, outEntities, outEntities.length);
+        }
+        return outEntities;
+    }
+
     /**
      * Sets a local transform of a transform component.
      * <p>This operation can be slow if the hierarchy of transform is too deep, and this
@@ -360,6 +391,8 @@ import androidx.annotation.Size;
     private static native void nDestroy(long nativeTransformManager, int entity);
     private static native void nSetParent(long nativeTransformManager, int i, int newParent);
     private static native int nGetParent(long nativeTransformManager, int i);
+    private static native int nGetChildCount(long nativeTransformManager, int i);
+    private static native void nGetChildren(long nativeEntityManager, int i, int[] outEntities, int count);
     private static native void nSetTransform(long nativeTransformManager, int i, float[] localTransform);
     private static native void nSetTransformFp64(long nativeTransformManager, int i, double[] localTransform);
     private static native void nGetTransform(long nativeTransformManager, int i, float[] outLocalTransform);

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

@@ -793,7 +793,7 @@ public class View {
     public void setVsmShadowOptions(@NonNull VsmShadowOptions options) {
         mVsmShadowOptions = options;
         nSetVsmShadowOptions(getNativeObject(), options.anisotropy, options.mipmapping,
-                options.minVarianceScale, options.lightBleedReduction);
+                options.highPrecision, options.minVarianceScale, options.lightBleedReduction);
     }
 
     /**
@@ -1011,6 +1011,45 @@ public class View {
         return mDepthOfFieldOptions;
     }
 
+    /**
+     * Enables use of the stencil buffer.
+     *
+     * <p>
+     * The stencil buffer is an 8-bit, per-fragment unsigned integer stored alongside the depth
+     * buffer. The stencil buffer is cleared at the beginning of a frame and discarded after the
+     * color pass.
+     * </p>
+     *
+     * <p>
+     * Each fragment's stencil value is set during rasterization by specifying stencil operations on
+     * a {@link Material}. The stencil buffer can be used as a mask for later rendering by setting a
+     * {@link Material}'s stencil comparison function and reference value. Fragments that don't pass
+     * the stencil test are then discarded.
+     * </p>
+     *
+     * <p>
+     * Post-processing must be enabled in order to use the stencil buffer.
+     * </p>
+     *
+     * <p>
+     * A renderable's priority (see {@link RenderableManager#setPriority(int, int)}) is useful to
+     * control the order in which primitives are drawn.
+     * </p>
+     *
+     * @param enabled True to enable the stencil buffer, false disables it (default)
+     */
+    public void setStencilBufferEnabled(boolean enabled) {
+        nSetStencilBufferEnabled(getNativeObject(), enabled);
+    }
+
+    /**
+     * @return true if the stencil buffer is enabled.
+     * @see View#setStencilBufferEnabled(boolean)
+     */
+    public boolean isStencilBufferEnabled() {
+        return nIsStencilBufferEnabled(getNativeObject());
+    }
+
     /**
      * A class containing the result of a picking query
      */
@@ -1105,7 +1144,7 @@ public class View {
     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, boolean mipmapping, float minVarianceScale, float lightBleedReduction);
+    private static native void nSetVsmShadowOptions(long nativeView, int anisotropy, boolean mipmapping, boolean highPrecision, float minVarianceScale, float lightBleedReduction);
     private static native void nSetSoftShadowOptions(long nativeView, float penumbraScale, float penumbraRatioScale);
     private static native void nSetColorGrading(long nativeView, long nativeColorGrading);
     private static native void nSetPostProcessingEnabled(long nativeView, boolean enabled);
@@ -1131,6 +1170,8 @@ public class View {
     private static native void nSetGuardBandOptions(long nativeView, boolean enabled);
     private static native boolean nIsScreenSpaceRefractionEnabled(long nativeView);
     private static native void nPick(long nativeView, int x, int y, Object handler, InternalOnPickCallback internalCallback);
+    private static native void nSetStencilBufferEnabled(long nativeView, boolean enabled);
+    private static native boolean nIsStencilBufferEnabled(long nativeView);
 
     /**
      * List of available ambient occlusion techniques.
@@ -1776,6 +1817,20 @@ public class View {
          * Whether to generate mipmaps for all VSM shadow maps.
          */
         public boolean mipmapping = false;
+        /**
+         * The number of MSAA samples to use when rendering VSM shadow maps.
+         * Must be a power-of-two and greater than or equal to 1. A value of 1 effectively turns
+         * off MSAA.
+         * Higher values may not be available depending on the underlying hardware.
+         */
+        public int msaaSamples = 1;
+        /**
+         * Whether to use a 32-bits or 16-bits texture format for VSM shadow maps. 32-bits
+         * precision is rarely needed, but it does reduces light leaks as well as "fading"
+         * of the shadows in some situations. Setting highPrecision to true for a single
+         * shadow map will double the memory usage of all shadow maps.
+         */
+        public boolean highPrecision = false;
         /**
          * VSM minimum variance scale, must be positive.
          */

android/filament-utils-android/src/main/cpp/AutomationEngine.cpp

@@ -70,7 +70,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nStartBatchMode(JNIEnv*
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclass klass,
-        jlong nativeAutomation, jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
+        jlong nativeAutomation, jlong nativeEngine,
+        jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
     using MaterialPointer = MaterialInstance*;
     jsize materialCount = 0;
     jlong* longMaterials = nullptr;
@@ -90,7 +91,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
         .materials = ptrMaterials,
         .materialCount = (size_t) materialCount,
     };
-    automation->tick(content, deltaTime);
+    Engine* engine = (Engine*)nativeEngine;
+    automation->tick(engine, content, deltaTime);
     if (longMaterials) {
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
         delete[] ptrMaterials;
@@ -99,7 +101,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nApplySettings(JNIEnv* env, jclass klass,
-        jlong nativeAutomation, jstring json, jlong view, jlongArray materials, jlong nativeIbl,
+        jlong nativeAutomation, jlong nativeEngine,
+        jstring json, jlong view, jlongArray materials, jlong nativeIbl,
         jint sunlightEntity, jintArray assetLights, jlong nativeLm, jlong scene, jlong renderer) {
     using MaterialPointer = MaterialInstance*;
 
@@ -140,8 +143,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nApplySettings(JNIEnv* e
         .assetLights = (Entity*) intLights,
         .assetLightCount = (size_t) lightCount,
     };
-
-    automation->applySettings(nativeJson, jsonLength, content);
+    Engine* engine = (Engine*)nativeEngine;
+    automation->applySettings(engine, nativeJson, jsonLength, content);
     env->ReleaseStringUTFChars(json, nativeJson);
     if (longMaterials) {
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
@@ -163,6 +166,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nGetViewerOptions(JNIEnv
     const jfieldID cameraAperture = env->GetFieldID(klass, "cameraAperture", "F");
     const jfieldID cameraSpeed = env->GetFieldID(klass, "cameraSpeed", "F");
     const jfieldID cameraISO = env->GetFieldID(klass, "cameraISO", "F");
+    const jfieldID cameraNear = env->GetFieldID(klass, "cameraNear", "F");
+    const jfieldID cameraFar = env->GetFieldID(klass, "cameraFar", "F");
     const jfieldID groundShadowStrength = env->GetFieldID(klass, "groundShadowStrength", "F");
     const jfieldID groundPlaneEnabled = env->GetFieldID(klass, "groundPlaneEnabled", "Z");
     const jfieldID skyboxEnabled = env->GetFieldID(klass, "skyboxEnabled", "Z");
@@ -174,6 +179,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nGetViewerOptions(JNIEnv
     env->SetFloatField(result, cameraAperture, options.cameraAperture);
     env->SetFloatField(result, cameraSpeed, options.cameraSpeed);
     env->SetFloatField(result, cameraISO, options.cameraISO);
+    env->SetFloatField(result, cameraNear, options.cameraNear);
+    env->SetFloatField(result, cameraFar, options.cameraFar);
     env->SetFloatField(result, groundShadowStrength, options.groundShadowStrength);
     env->SetBooleanField(result, groundPlaneEnabled, options.groundPlaneEnabled);
     env->SetBooleanField(result, skyboxEnabled, options.skyboxEnabled);

android/filament-utils-android/src/main/java/com/google/android/filament/utils/AutomationEngine.java

@@ -97,6 +97,8 @@ public class AutomationEngine {
         public float cameraAperture = 16.0f;
         public float cameraSpeed = 125.0f;
         public float cameraISO = 100.0f;
+        public float cameraNear = 0.1f;
+        public float cameraFar = 100.0f;
         public float groundShadowStrength = 0.75f;
         public boolean groundPlaneEnabled = false;
         public boolean skyboxEnabled = true;
@@ -156,10 +158,11 @@ public class AutomationEngine {
      * This is when settings get applied, screenshots are (optionally) exported, and the internal
      * test counter is potentially incremented.
      *
+     * @param engine        The filament Engine of interest.
      * @param content       Contains the Filament View, Materials, and Renderer that get modified.
      * @param deltaTime     The amount of time that has passed since the previous tick in seconds.
      */
-    public void tick(@NonNull ViewerContent content, float deltaTime) {
+    public void tick(@NonNull Engine engine, @NonNull ViewerContent content, float deltaTime) {
         if (content.view == null || content.renderer == null) {
             throw new IllegalStateException("Must provide a View and Renderer");
         }
@@ -172,7 +175,7 @@ public class AutomationEngine {
         }
         long nativeView = content.view.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nTick(mNativeObject, nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
+        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
     }
 
     /**
@@ -184,10 +187,12 @@ public class AutomationEngine {
      * This updates the stashed Settings object, then pushes those settings to the given
      * Filament objects. Clients can optionally call getColorGrading() after calling this method.
      *
+     * @param engine        Filament Engine to use.
      * @param settingsJson  Contains the JSON string with a set of changes that need to be pushed.
      * @param content       Contains a set of Filament objects that you want to mutate.
      */
-    public void applySettings(@NonNull String settingsJson, @NonNull ViewerContent content) {
+    public void applySettings(@NonNull Engine engine, @NonNull String settingsJson,
+        @NonNull ViewerContent content) {
         if (content.view == null || content.renderer == null) {
             throw new IllegalStateException("Must provide a View and Renderer");
         }
@@ -206,7 +211,8 @@ public class AutomationEngine {
         long nativeLm = content.lightManager.getNativeObject();
         long nativeScene = content.scene.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nApplySettings(mNativeObject, settingsJson, nativeView, nativeMaterialInstances,
+        nApplySettings(mNativeObject, engine.getNativeObject(),
+                settingsJson, nativeView, nativeMaterialInstances,
                 nativeIbl, content.sunlight, content.assetLights, nativeLm, nativeScene,
                 nativeRenderer);
     }
@@ -267,9 +273,10 @@ public class AutomationEngine {
             int minFrameCount, boolean verbose);
     private static native void nStartRunning(long nativeObject);
     private static native void nStartBatchMode(long nativeObject);
-    private static native void nTick(long nativeObject, long view, long[] materials, long renderer,
-            float deltaTime);
-    private static native void nApplySettings(long nativeObject, String jsonSettings, long view,
+    private static native void nTick(long nativeObject, long nativeEngine,
+            long view, long[] materials, long renderer, float deltaTime);
+    private static native void nApplySettings(long nativeObject, long nativeEngine,
+            String jsonSettings, long view,
             long[] materials, long ibl, int sunlight, int[] assetLights, long lightManager,
             long scene, long renderer);
     private static native void nGetViewerOptions(long nativeObject, Object result);

android/filament-utils-android/src/main/java/com/google/android/filament/utils/ModelViewer.kt

@@ -27,8 +27,8 @@ import com.google.android.filament.gltfio.*
 import kotlinx.coroutines.*
 import java.nio.Buffer
 
-private const val kNearPlane = 0.05     // 5 cm
-private const val kFarPlane = 1000.0    // 1 km
+private const val kNearPlane = 0.05f     // 5 cm
+private const val kFarPlane = 1000.0f    // 1 km
 private const val kAperture = 16f
 private const val kShutterSpeed = 1f / 125f
 private const val kSensitivity = 100f
@@ -73,8 +73,6 @@ class ModelViewer(
         get() = resourceLoader.asyncGetLoadProgress()
 
     var normalizeSkinningWeights = true
-    var recomputeBoundingBoxes = false
-    var ignoreBindTransform = false
 
     var cameraFocalLength = 28f
         set(value) {
@@ -82,6 +80,18 @@ class ModelViewer(
             updateCameraProjection()
         }
 
+    var cameraNear = kNearPlane
+        set(value) {
+            field = value
+            updateCameraProjection()
+        }
+
+    var cameraFar = kFarPlane
+        set(value) {
+            field = value
+            updateCameraProjection()
+        }
+
     val scene: Scene
     val view: View
     val camera: Camera
@@ -116,7 +126,7 @@ class ModelViewer(
 
         materialProvider = UbershaderProvider(engine)
         assetLoader = AssetLoader(engine, materialProvider, EntityManager.get())
-        resourceLoader = ResourceLoader(engine, normalizeSkinningWeights, recomputeBoundingBoxes, ignoreBindTransform)
+        resourceLoader = ResourceLoader(engine, normalizeSkinningWeights)
 
         // Always add a direct light source since it is required for shadowing.
         // We highly recommend adding an indirect light as well.
@@ -178,10 +188,10 @@ class ModelViewer(
      */
     fun loadModelGlb(buffer: Buffer) {
         destroyModel()
-        asset = assetLoader.createAssetFromBinary(buffer)
+        asset = assetLoader.createAsset(buffer)
         asset?.let { asset ->
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.animator
+            animator = asset.getInstance().animator
             asset.releaseSourceData()
         }
     }
@@ -193,7 +203,7 @@ class ModelViewer(
      */
     fun loadModelGltf(buffer: Buffer, callback: (String) -> Buffer?) {
         destroyModel()
-        asset = assetLoader.createAssetFromJson(buffer)
+        asset = assetLoader.createAsset(buffer)
         asset?.let { asset ->
             for (uri in asset.resourceUris) {
                 val resourceBuffer = callback(uri)
@@ -204,7 +214,7 @@ class ModelViewer(
                 resourceLoader.addResourceData(uri, resourceBuffer)
             }
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.animator
+            animator = asset.getInstance().animator
             asset.releaseSourceData()
         }
     }
@@ -216,7 +226,7 @@ class ModelViewer(
      */
     fun loadModelGltfAsync(buffer: Buffer, callback: (String) -> Buffer) {
         destroyModel()
-        asset = assetLoader.createAssetFromJson(buffer)
+        asset = assetLoader.createAsset(buffer)
         fetchResourcesJob = CoroutineScope(Dispatchers.IO).launch {
             fetchResources(asset!!, callback)
         }
@@ -312,8 +322,8 @@ class ModelViewer(
 
     private fun addDetachListener(view: android.view.View) {
         view.addOnAttachStateChangeListener(object : android.view.View.OnAttachStateChangeListener {
-            override fun onViewAttachedToWindow(v: android.view.View?) {}
-            override fun onViewDetachedFromWindow(v: android.view.View?) {
+            override fun onViewAttachedToWindow(v: android.view.View) {}
+            override fun onViewDetachedFromWindow(v: android.view.View) {
                 uiHelper.detach()
 
                 destroyModel()
@@ -361,7 +371,7 @@ class ModelViewer(
                 resourceLoader.addResourceData(uri, buffer)
             }
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.animator
+            animator = asset.getInstance().animator
             asset.releaseSourceData()
         }
     }
@@ -370,7 +380,8 @@ class ModelViewer(
         val width = view.viewport.width
         val height = view.viewport.height
         val aspect = width.toDouble() / height.toDouble()
-        camera.setLensProjection(cameraFocalLength.toDouble(), aspect, kNearPlane, kFarPlane)
+        camera.setLensProjection(cameraFocalLength.toDouble(), aspect,
+            cameraNear.toDouble(), cameraFar.toDouble())
     }
 
     inner class SurfaceCallback : UiHelper.RendererCallback {

android/gltfio-android/CMakeLists.txt

@@ -11,6 +11,10 @@ add_library(dracodec STATIC IMPORTED)
 set_target_properties(dracodec PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libdracodec.a)
 
+add_library(meshoptimizer STATIC IMPORTED)
+set_target_properties(meshoptimizer PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libmeshoptimizer.a)
+
 add_library(ktxreader STATIC IMPORTED)
 set_target_properties(ktxreader PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libktxreader.a)
@@ -76,7 +80,7 @@ set(GLTFIO_SRCS
         ${GLTFIO_DIR}/src/UbershaderProvider.cpp
         ${GLTFIO_DIR}/src/Wireframe.cpp
         ${GLTFIO_DIR}/src/Wireframe.h
-        ${GLTFIO_DIR}/src/upcast.h
+        ${GLTFIO_DIR}/src/downcast.h
 
         src/main/cpp/Animator.cpp
         src/main/cpp/AssetLoader.cpp
@@ -99,6 +103,7 @@ set(GLTFIO_INCLUDE_DIRS
         ../../libs/gltfio/include
         ../../third_party/basisu/zstd
         ../../third_party/cgltf
+        ../../third_party/meshoptimizer/src
         ../../third_party/robin-map
         ../../third_party/hat-trie
         ../../third_party/stb
@@ -111,7 +116,7 @@ target_include_directories(gltfio-jni PRIVATE ${GLTFIO_INCLUDE_DIRS})
 set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.symbols)
 set_target_properties(gltfio-jni PROPERTIES LINK_DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map)
 target_link_libraries(gltfio-jni filament-jni utils uberzlib log stb ktxreader basis_transcoder zstd uberarchive)
-target_link_libraries(gltfio-jni dracodec)
+target_link_libraries(gltfio-jni dracodec meshoptimizer)
 target_compile_definitions(gltfio-jni PUBLIC GLTFIO_DRACO_SUPPORTED=1)
 target_include_directories(gltfio-jni PRIVATE ${DRACO_DIR}/src)
 target_include_directories(gltfio-jni PRIVATE ${DRACO_DIR}/tnt)

android/gltfio-android/src/main/AndroidManifest.xml

@@ -14,5 +14,4 @@
   limitations under the License.
  -->
 
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.gltfio" />
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

android/gltfio-android/src/main/cpp/AssetLoader.cpp

@@ -42,6 +42,7 @@ class JavaMaterialProvider : public MaterialProvider {
 
     jmethodID mMaterialKeyConstructor;
     jmethodID mCreateMaterialInstance;
+    jmethodID mGetMaterial;
     jmethodID mGetMaterials;
     jmethodID mNeedsDummyData;
     jmethodID mDestroyMaterials;
@@ -72,6 +73,10 @@ public:
                 "(L" JAVA_MATERIAL_KEY ";[ILjava/lang/String;Ljava/lang/String;)Lcom/google/android/filament/MaterialInstance;");
         assert_invariant(mCreateMaterialInstance);
 
+        mGetMaterial = env->GetMethodID(providerClass, "getMaterial",
+                "(L" JAVA_MATERIAL_KEY ";[ILjava/lang/String;)Lcom/google/android/filament/Material;");
+        assert_invariant(mGetMaterial);
+
         mGetMaterials = env->GetMethodID(providerClass, "getMaterials",
                 "()[Lcom/google/android/filament/Material;");
         assert_invariant(mGetMaterials);
@@ -103,7 +108,7 @@ public:
         jstring stringExtras = extras ? mEnv->NewStringUTF(extras) : nullptr;
 
         // Allocate space for the output argument.
-        jintArray uvMapArray = mEnv->NewIntArray(8);
+        jintArray uvMapArray = mEnv->NewIntArray(uvmap->size());
 
         // Call the Java-based material provider.
         jobject materialInstance = mEnv->CallObjectMethod(mJavaProvider, mCreateMaterialInstance,
@@ -139,6 +144,49 @@ public:
         return (MaterialInstance*) mEnv->CallLongMethod(materialInstance, mMaterialInstanceGetNativeObject);
     }
 
+    Material* getMaterial(MaterialKey* config, UvMap* uvmap, const char* label) override {
+        // Create a Java object for the material key and copy the native fields into it.
+        jobject javaKey = mEnv->NewObject(mMaterialKeyClass, mMaterialKeyConstructor);
+
+        auto& helper = MaterialKeyHelper::get();
+        helper.copy(mEnv, javaKey, *config);
+
+        // Convert the optional label into a Java string.
+        jstring stringLabel = label ? mEnv->NewStringUTF(label) : nullptr;
+
+        // Allocate space for the output argument.
+        jintArray uvMapArray = mEnv->NewIntArray(uvmap->size());
+
+        // Call the Java-based material provider.
+        jobject material = mEnv->CallObjectMethod(mJavaProvider, mGetMaterial,
+                javaKey, uvMapArray, stringLabel);
+
+        // Copy the UvMap results from the JVM array into the native array.
+        if (uvmap) {
+            jint* elements = mEnv->GetIntArrayElements(uvMapArray, nullptr);
+            for (size_t i = 0; i < uvmap->size(); i++) {
+                (*uvmap)[i] = (UvSet) elements[i];
+            }
+            mEnv->ReleaseIntArrayElements(uvMapArray, elements, JNI_ABORT);
+        }
+
+        // The config parameter is an in-out parameter so we need to copy the results from Java.
+        helper.copy(mEnv, *config, javaKey);
+
+        mEnv->DeleteLocalRef(javaKey);
+        mEnv->DeleteLocalRef(uvMapArray);
+
+        if (stringLabel) {
+            mEnv->DeleteLocalRef(stringLabel);
+        }
+
+        if (material == nullptr) {
+            return nullptr;
+        }
+
+        return (Material*) mEnv->CallLongMethod(material, mMaterialGetNativeObject);
+    }
+
     const Material* const* getMaterials() const noexcept override {
         jobjectArray javaMaterials = (jobjectArray) mEnv->CallObjectMethod(mJavaProvider, mGetMaterials);
 
@@ -207,20 +255,11 @@ Java_com_google_android_filament_gltfio_AssetLoader_nDestroyAssetLoader(JNIEnv*,
 }
 
 extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_gltfio_AssetLoader_nCreateAssetFromBinary(JNIEnv* env, jclass,
+Java_com_google_android_filament_gltfio_AssetLoader_nCreateAsset(JNIEnv* env, jclass,
         jlong nativeLoader, jobject javaBuffer, jint remaining) {
     AssetLoader* loader = (AssetLoader*) nativeLoader;
     AutoBuffer buffer(env, javaBuffer, remaining);
-    return (jlong) loader->createAssetFromBinary((const uint8_t *) buffer.getData(),
-            buffer.getSize());
-}
-
-extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_gltfio_AssetLoader_nCreateAssetFromJson(JNIEnv* env, jclass,
-        jlong nativeLoader, jobject javaBuffer, jint remaining) {
-    AssetLoader* loader = (AssetLoader*) nativeLoader;
-    AutoBuffer buffer(env, javaBuffer, remaining);
-    return (jlong) loader->createAssetFromJson((const uint8_t *) buffer.getData(),
+    return (jlong) loader->createAsset((const uint8_t *) buffer.getData(),
             buffer.getSize());
 }
 

android/gltfio-android/src/main/cpp/FilamentAsset.cpp

@@ -172,27 +172,6 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nGetCameraEntityCount(JNIE
     return asset->getCameraEntityCount();
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetMaterialInstanceCount(JNIEnv*, jclass,
-        jlong nativeAsset) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return asset->getMaterialInstanceCount();
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetMaterialInstances(JNIEnv* env, jclass,
-        jlong nativeAsset, jlongArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
-    jsize count = std::min(available, (jsize) asset->getMaterialInstanceCount());
-    jlong* dst = env->GetLongArrayElements(result, nullptr);
-    const MaterialInstance * const* src = asset->getMaterialInstances();
-    for (jsize i = 0; i < count; i++) {
-        dst[i] = (jlong) src[i];
-    }
-    env->ReleaseLongArrayElements(result, dst, 0);
-}
-
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nGetBoundingBox(JNIEnv* env, jclass,
         jlong nativeAsset, jfloatArray result) {
@@ -228,49 +207,11 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nGetExtras(JNIEnv* env, jc
     return val ? env->NewStringUTF(val) : nullptr;
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetSkinCount(JNIEnv* , jclass,
-        jlong nativeAsset) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jint) asset->getSkinCount();
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetSkinNames(JNIEnv* env, jclass,
-        jlong nativeAsset, jobjectArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
-    for (int i = 0; i < available; ++i) {
-        const char* name = asset->getSkinNameAt(i);
-        if (name) {
-            env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
-        }
-    }
-}
-
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetJointCountAt(JNIEnv* , jclass,
-        jlong nativeAsset, jint skinIndex) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jint) asset->getJointCountAt(skinIndex);
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetJointsAt(JNIEnv* env, jclass,
-        jlong nativeAsset, jint skinIndex, jintArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
-    Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
-    std::copy_n(asset->getJointsAt(skinIndex),
-        std::min(available, (jsize) asset->getJointCountAt(skinIndex)), entities);
-    env->ReleaseIntArrayElements(result, (jint*) entities, 0);
-}
-
 extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetAnimator(JNIEnv* , jclass,
+Java_com_google_android_filament_gltfio_FilamentAsset_nGetInstance(JNIEnv* , jclass,
         jlong nativeAsset) {
     FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jlong) asset->getAnimator();
+    return (jlong) asset->getInstance();
 }
 
 extern "C" JNIEXPORT jint JNICALL
@@ -310,49 +251,9 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nGetMorphTargetNames(JNIEn
     }
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetMaterialVariantCount(JNIEnv*, jclass,
-        jlong nativeAsset) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jint) asset->getMaterialVariantCount();
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetMaterialVariantNames(JNIEnv* env, jclass,
-        jlong nativeAsset, jobjectArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    for (int i = 0; i < asset->getMaterialVariantCount(); ++i) {
-        const char* name = asset->getMaterialVariantName(i);
-        env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
-    }
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nApplyMaterialVariant(JNIEnv* env, jclass,
-        jlong nativeAsset, jint variantIndex) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    asset->applyMaterialVariant(variantIndex);
-}
-
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nReleaseSourceData(JNIEnv* env, jclass,
         jlong nativeAsset) {
     FilamentAsset* asset = (FilamentAsset*) nativeAsset;
     asset->releaseSourceData();
 }
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nAttachSkin(JNIEnv* env, jclass,
-        jlong nativeAsset, jint skinIndex, jint targetEntity) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    Entity target = Entity::import(targetEntity);
-    asset->attachSkin(skinIndex, target);
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nDetachSkin(JNIEnv* env, jclass,
-        jlong nativeAsset, jint skinIndex, jint targetEntity) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    Entity target = Entity::import(targetEntity);
-    asset->detachSkin(skinIndex, target);
-}

android/gltfio-android/src/main/cpp/FilamentInstance.cpp

@@ -20,6 +20,7 @@
 
 #include <algorithm>
 
+using namespace filament;
 using namespace filament::gltfio;
 using namespace utils;
 
@@ -61,3 +62,95 @@ Java_com_google_android_filament_gltfio_FilamentInstance_nApplyMaterialVariant(J
     FilamentInstance* instance = (FilamentInstance*) nativeInstance;
     instance->applyMaterialVariant(variantIndex);
 }
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetMaterialVariantCount(JNIEnv*, jclass,
+        jlong nativeInstance) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return (jint) instance->getMaterialVariantCount();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetMaterialVariantNames(JNIEnv* env, jclass,
+        jlong nativeInstance, jobjectArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    for (int i = 0; i < instance->getMaterialVariantCount(); ++i) {
+        const char* name = instance->getMaterialVariantName(i);
+        env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
+    }
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetMaterialInstanceCount(JNIEnv*, jclass,
+        jlong nativeInstance) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return instance->getMaterialInstanceCount();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetMaterialInstances(JNIEnv* env, jclass,
+        jlong nativeInstance, jlongArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    jsize available = env->GetArrayLength(result);
+    jsize count = std::min(available, (jsize) instance->getMaterialInstanceCount());
+    jlong* dst = env->GetLongArrayElements(result, nullptr);
+    const MaterialInstance * const* src = instance->getMaterialInstances();
+    for (jsize i = 0; i < count; i++) {
+        dst[i] = (jlong) src[i];
+    }
+    env->ReleaseLongArrayElements(result, dst, 0);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nAttachSkin(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jint targetEntity) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    Entity target = Entity::import(targetEntity);
+    instance->attachSkin(skinIndex, target);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nDetachSkin(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jint targetEntity) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    Entity target = Entity::import(targetEntity);
+    instance->detachSkin(skinIndex, target);
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetSkinCount(JNIEnv* , jclass,
+        jlong nativeInstance) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return (jint) instance->getSkinCount();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetSkinNames(JNIEnv* env, jclass,
+        jlong nativeInstance, jobjectArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    jsize available = env->GetArrayLength(result);
+    for (int i = 0; i < available; ++i) {
+        const char* name = instance->getSkinNameAt(i);
+        if (name) {
+            env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
+        }
+    }
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetJointCountAt(JNIEnv* , jclass,
+        jlong nativeInstance, jint skinIndex) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return (jint) instance->getJointCountAt(skinIndex);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetJointsAt(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jintArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    jsize available = env->GetArrayLength(result);
+    Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
+    std::copy_n(instance->getJointsAt(skinIndex),
+        std::min(available, (jsize) instance->getJointCountAt(skinIndex)), entities);
+    env->ReleaseIntArrayElements(result, (jint*) entities, 0);
+}

android/gltfio-android/src/main/cpp/ResourceLoader.cpp

@@ -36,11 +36,9 @@ static void destroy(void*, size_t, void *userData) {
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_gltfio_ResourceLoader_nCreateResourceLoader(JNIEnv*, jclass,
-        jlong nativeEngine, jboolean normalizeSkinningWeights, jboolean recomputeBoundingBoxes,
-        jboolean ignoreBindTransform) {
+        jlong nativeEngine, jboolean normalizeSkinningWeights) {
     Engine* engine = (Engine*) nativeEngine;
-    return (jlong) new ResourceLoader({ engine, {}, (bool) normalizeSkinningWeights,
-            (bool) recomputeBoundingBoxes, (bool) ignoreBindTransform});
+    return (jlong) new ResourceLoader({ engine, {}, (bool) normalizeSkinningWeights});
 }
 
 extern "C" JNIEXPORT void JNICALL

android/gltfio-android/src/main/cpp/UbershaderProvider.cpp

@@ -49,16 +49,19 @@ Java_com_google_android_filament_gltfio_UbershaderProvider_nDestroyMaterials(JNI
 
 extern "C" JNIEXPORT long JNICALL
 Java_com_google_android_filament_gltfio_UbershaderProvider_nCreateMaterialInstance(JNIEnv* env, jclass,
-        jlong nativeProvider, jobject materialKey, jintArray uvmap, jstring label) {
+        jlong nativeProvider, jobject materialKey, jintArray uvmap, jstring label, jstring extras) {
     MaterialKey nativeKey = {};
 
     auto& helper = MaterialKeyHelper::get();
     helper.copy(env, nativeKey, materialKey);
 
     const char* nativeLabel = label ? env->GetStringUTFChars(label, nullptr) : nullptr;
+    const char* nativeExtras = extras ? env->GetStringUTFChars(extras, nullptr) : nullptr;
+
     UvMap nativeUvMap = {};
     auto provider = (MaterialProvider*) nativeProvider;
-    MaterialInstance* instance = provider->createMaterialInstance(&nativeKey, &nativeUvMap, nativeLabel);
+    MaterialInstance* instance = provider->createMaterialInstance(&nativeKey, &nativeUvMap,
+            nativeLabel, nativeExtras);
 
     // Copy the UvMap results from the native array into the JVM array.
     jint* elements = env->GetIntArrayElements(uvmap, nullptr);
@@ -77,9 +80,47 @@ Java_com_google_android_filament_gltfio_UbershaderProvider_nCreateMaterialInstan
         env->ReleaseStringUTFChars(label, nativeLabel);
     }
 
+    if (extras) {
+        env->ReleaseStringUTFChars(extras, nativeExtras);
+    }
+
     return (long) instance;
 }
 
+extern "C" JNIEXPORT long JNICALL
+Java_com_google_android_filament_gltfio_UbershaderProvider_nGetMaterial(JNIEnv* env, jclass,
+        jlong nativeProvider, jobject materialKey, jintArray uvmap, jstring label) {
+    MaterialKey nativeKey = {};
+
+    auto& helper = MaterialKeyHelper::get();
+    helper.copy(env, nativeKey, materialKey);
+
+    const char* nativeLabel = label ? env->GetStringUTFChars(label, nullptr) : nullptr;
+
+    UvMap nativeUvMap = {};
+    auto provider = (MaterialProvider*) nativeProvider;
+    Material* material = provider->getMaterial(&nativeKey, &nativeUvMap, nativeLabel);
+
+    // Copy the UvMap results from the native array into the JVM array.
+    jint* elements = env->GetIntArrayElements(uvmap, nullptr);
+    if (elements) {
+        const size_t javaSize = env->GetArrayLength(uvmap);
+        for (int i = 0, n = std::min(javaSize, nativeUvMap.size()); i < n; ++i) {
+            elements[i] = nativeUvMap[i];
+        }
+        env->ReleaseIntArrayElements(uvmap, elements, 0);
+    }
+
+    // The config parameter is an in-out parameter so we need to copy the results back to Java.
+    helper.copy(env, materialKey, nativeKey);
+
+    if (label) {
+        env->ReleaseStringUTFChars(label, nativeLabel);
+    }
+
+    return (long) material;
+}
+
 extern "C" JNIEXPORT int JNICALL
 Java_com_google_android_filament_gltfio_UbershaderProvider_nGetMaterialCount(JNIEnv*, jclass,
         jlong nativeProvider) {

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/AssetLoader.java

@@ -26,8 +26,8 @@ import java.nio.Buffer;
 
 /**
  * Consumes a blob of glTF 2.0 content (either JSON or GLB) and produces a {@link FilamentAsset}
- * object, which is a bundle of Filament entities, material instances, textures, vertex buffers,
- * and index buffers.
+ * object, which is a bundle of Filament textures, vertex buffers, index buffers, etc. An asset is
+ * composed of 1 or more FilamentInstance objects which contain entities and components.
  *
  * <p>AssetLoader does not fetch external buffer data or create textures on its own. Clients can use
  * the provided {@link ResourceLoader} class for this, which obtains the URI list from the asset.
@@ -51,7 +51,7 @@ import java.nio.Buffer;
  *     filamentAsset = assets.open("models/lucy.gltf").use { input -&gt;
  *         val bytes = ByteArray(input.available())
  *         input.read(bytes)
- *         assetLoader.createAssetFromJson(ByteBuffer.wrap(bytes))!!
+ *         assetLoader.createAsset(ByteBuffer.wrap(bytes))!!
  *     }
  *
  *     val resourceLoader = ResourceLoader(engine)
@@ -115,20 +115,11 @@ public class AssetLoader {
     }
 
     /**
-     * Creates a {@link FilamentAsset} from the contents of a GLB file.
+     * Creates a {@link FilamentAsset} from the contents of a GLB or GLTF file.
      */
     @Nullable
-    public FilamentAsset createAssetFromBinary(@NonNull Buffer buffer) {
-        long nativeAsset = nCreateAssetFromBinary(mNativeObject, buffer, buffer.remaining());
-        return nativeAsset != 0 ? new FilamentAsset(mEngine, nativeAsset) : null;
-    }
-
-    /**
-     * Creates a {@link FilamentAsset} from the contents of a GLTF file.
-     */
-    @Nullable
-    public FilamentAsset createAssetFromJson(@NonNull Buffer buffer) {
-        long nativeAsset = nCreateAssetFromJson(mNativeObject, buffer, buffer.remaining());
+    public FilamentAsset createAsset(@NonNull Buffer buffer) {
+        long nativeAsset = nCreateAsset(mNativeObject, buffer, buffer.remaining());
         return nativeAsset != 0 ? new FilamentAsset(mEngine, nativeAsset) : null;
     }
 
@@ -158,7 +149,7 @@ public class AssetLoader {
     }
 
     /**
-     * Adds a new instance to an instanced asset.
+     * Adds a new instance to the asset.
      *
      * Use this with caution. It is more efficient to pre-allocate a max number of instances, and
      * gradually add them to the scene as needed. Instances can also be "recycled" by removing and
@@ -169,8 +160,6 @@ public class AssetLoader {
      * create/destroy churn, as noted above.
      *
      * This cannot be called after FilamentAsset#releaseSourceData().
-     * This cannot be called on a non-instanced asset.
-     * Animation is not supported in new instances.
      * See also AssetLoader#createInstancedAsset().
      */
     @Nullable
@@ -202,8 +191,7 @@ public class AssetLoader {
     private static native long nCreateAssetLoader(long nativeEngine, Object provider,
             long nativeEntities);
     private static native void nDestroyAssetLoader(long nativeLoader);
-    private static native long nCreateAssetFromBinary(long nativeLoader, Buffer buffer, int remaining);
-    private static native long nCreateAssetFromJson(long nativeLoader, Buffer buffer, int remaining);
+    private static native long nCreateAsset(long nativeLoader, Buffer buffer, int remaining);
     private static native long nCreateInstancedAsset(long nativeLoader, Buffer buffer, int remaining,
             long[] nativeInstances);
     private static native long nCreateInstance(long nativeLoader, long nativeAsset);

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentAsset.java

@@ -23,7 +23,6 @@ import androidx.annotation.Nullable;
 import com.google.android.filament.Box;
 import com.google.android.filament.Engine;
 import com.google.android.filament.Entity;
-import com.google.android.filament.MaterialInstance;
 
 /**
  * Owns a bundle of Filament objects that have been created by <code>AssetLoader</code>.
@@ -35,25 +34,32 @@ import com.google.android.filament.MaterialInstance;
  * <code>NameComponentManager</code>, <code>RenderableManager</code>, and others.</p>
  *
  * <p>In addition to the aforementioned entities, an asset has strong ownership over a list of
- * <code>VertexBuffer</code>, <code>IndexBuffer</code>, <code>MaterialInstance</code>, and
- * <code>Texture</code>.</p>
+ * <code>VertexBuffer</code>, <code>IndexBuffer</code>, and <code>Texture</code>.</p>
  *
  * <p>Clients can use {@link ResourceLoader} to create textures, compute tangent quaternions, and
  * upload data into vertex buffers and index buffers.</p>
  *
  * @see ResourceLoader
- * @see Animator
+ * @see FilamentInstance
  * @see AssetLoader
  */
 public class FilamentAsset {
     private long mNativeObject;
-    private Animator mAnimator;
+    private FilamentInstance mPrimaryInstance;
     private Engine mEngine;
 
     FilamentAsset(Engine engine, long nativeObject) {
         mEngine = engine;
         mNativeObject = nativeObject;
-        mAnimator = null;
+    }
+
+    public FilamentInstance getInstance() {
+        if (mPrimaryInstance != null) {
+            return mPrimaryInstance;
+        }
+        long nativeInstance = nGetInstance(getNativeObject());
+        mPrimaryInstance = new FilamentInstance(this, nativeInstance);
+        return mPrimaryInstance;
     }
 
     long getNativeObject() {
@@ -169,19 +175,11 @@ public class FilamentAsset {
         return result;
     }
 
-    public @NonNull MaterialInstance[] getMaterialInstances() {
-        final int count = nGetMaterialInstanceCount(mNativeObject);
-        MaterialInstance[] result = new MaterialInstance[count];
-        long[] natives = new long[count];
-        nGetMaterialInstances(mNativeObject, natives);
-        for (int i = 0; i < count; i++) {
-            result[i] = new MaterialInstance(mEngine, natives[i]);
-        }
-        return result;
-    }
-
     /**
      * Gets the bounding box computed from the supplied min / max values in glTF accessors.
+     *
+     * This does not return a bounding box over all FilamentInstance, it's just a straightforward
+     * AAAB that can be determined at load time from the asset data.
      */
     public @NonNull Box getBoundingBox() {
         float[] box = new float[6];
@@ -206,77 +204,6 @@ public class FilamentAsset {
         return nGetExtras(mNativeObject, entity);
     }
 
-    /**
-     * Retrieves the <code>Animator</code> interface for this asset.
-     *
-     * <p>When calling this for the first time, this must be called after
-     * {@link ResourceLoader#loadResources} or {@link ResourceLoader#asyncBeginLoad}. When the asset
-     * is destroyed, its animator becomes invalid.</p>
-     */
-    public @NonNull Animator getAnimator() {
-        if (mAnimator != null) {
-            return mAnimator;
-        }
-        long nativeAnimator = nGetAnimator(getNativeObject());
-        if (nativeAnimator == 0) {
-            throw new IllegalStateException("Unable to create animator");
-        }
-        mAnimator = new Animator(nativeAnimator);
-        return mAnimator;
-    }
-
-    /**
-     * Gets the skin count of this asset.
-     */
-    public int getSkinCount() {
-        return nGetSkinCount(getNativeObject());
-    }
-
-    /**
-     * Gets the skin name at skin index in this asset.
-     */
-    public @NonNull String[] getSkinNames() {
-        String[] result = new String[getSkinCount()];
-        nGetSkinNames(getNativeObject(), result);
-        return result;
-    }
-
-    /**
-     * Attaches the given skin to the given node, which must have an associated mesh with
-     * BONE_INDICES and BONE_WEIGHTS attributes.
-     *
-     * This is a no-op if the given skin index or target is invalid.
-     */
-    public void attachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
-        nAttachSkin(getNativeObject(), skinIndex, target);
-    }
-
-    /**
-     * Attaches the given skin to the given node, which must have an associated mesh with
-     * BONE_INDICES and BONE_WEIGHTS attributes.
-     *
-     * This is a no-op if the given skin index or target is invalid.
-     */
-    public void detachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
-        nDetachSkin(getNativeObject(), skinIndex, target);
-    }
-
-    /**
-     * Gets the joint count at skin index in this asset.
-     */
-    public int getJointCountAt(@IntRange(from = 0) int skinIndex) {
-        return nGetJointCountAt(getNativeObject(), skinIndex);
-    }
-
-    /**
-     * Gets joints at skin index in this asset.
-     */
-    public @NonNull @Entity int[] getJointsAt(@IntRange(from = 0) int skinIndex) {
-        int[] result = new int[getJointCountAt(skinIndex)];
-        nGetJointsAt(getNativeObject(), skinIndex, result);
-        return result;
-    }
-
     /**
      * Gets the names of all morph targets in the given entity.
      */
@@ -295,31 +222,6 @@ public class FilamentAsset {
         return uris;
     }
 
-    /**
-     * Returns the names of all material variants.
-     */
-    public @NonNull String[] getMaterialVariantNames() {
-        String[] names = new String[nGetMaterialVariantCount(mNativeObject)];
-        nGetMaterialVariantNames(mNativeObject, names);
-        return names;
-    }
-
-    /**
-     * Applies the given material variant to all primitives that it affects.
-     *
-     * This is efficient because it merely swaps around persistent MaterialInstances. If you change
-     * a material parameter while a certain variant is active, the updated value will be remembered
-     * after you re-apply that variant.
-     *
-     * If the asset is instanced, this affects all instances in the same way.
-     * To set the variant on an individual instance, use FilamentInstance#applyMaterialVariant.
-     *
-     * Ignored if variantIndex is out of bounds.
-     */
-    public void applyMaterialVariant(@IntRange(from = 0) int variantIndex) {
-        nApplyMaterialVariant(getNativeObject(), variantIndex);
-    }
-
     /**
      * Reclaims CPU-side memory for URI strings, binding lists, and raw animation data.
      *
@@ -331,8 +233,10 @@ public class FilamentAsset {
         nReleaseSourceData(mNativeObject);
     }
 
+    public Engine getEngine() { return mEngine; }
+
     void clearNativeObject() {
-        if (mAnimator != null) mAnimator.clearNativeObject();
+        mPrimaryInstance = null;
         mNativeObject = 0;
     }
 
@@ -356,28 +260,17 @@ public class FilamentAsset {
     private static native int nGetCameraEntityCount(long nativeAsset);
     private static native void nGetCameraEntities(long nativeAsset, int[] result);
 
-    private static native int nGetMaterialInstanceCount(long nativeAsset);
-    private static native void nGetMaterialInstances(long nativeAsset, long[] nativeResults);
-
-    private static native int nGetMaterialVariantCount(long nativeAsset);
-    private static native void nGetMaterialVariantNames(long nativeAsset, String[] result);
-
     private static native int nGetMorphTargetCount(long nativeAsset, int entity);
     private static native void nGetMorphTargetNames(long nativeAsset, int entity, String[] result);
 
-    private static native void nAttachSkin(long nativeAsset, int skinIndex, int entity);
-    private static native void nDetachSkin(long nativeAsset, int skinIndex, int entity);
-
     private static native void nGetBoundingBox(long nativeAsset, float[] box);
     private static native String nGetName(long nativeAsset, int entity);
     private static native String nGetExtras(long nativeAsset, int entity);
-    private static native long nGetAnimator(long nativeAsset);
-    private static native void nApplyMaterialVariant(long nativeAsset, int variantIndex);
-    private static native int nGetSkinCount(long nativeAsset);
-    private static native void nGetSkinNames(long nativeAsset, String[] result);
-    private static native int nGetJointCountAt(long nativeAsset, int skinIndex);
-    private static native void nGetJointsAt(long nativeAsset, int skinIndex, int[] result);
+
+    private static native long nGetInstance(long nativeAsset);
+
     private static native int nGetResourceUriCount(long nativeAsset);
     private static native void nGetResourceUris(long nativeAsset, String[] result);
+
     private static native void nReleaseSourceData(long nativeAsset);
 }

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/FilamentInstance.java

@@ -19,7 +19,9 @@ package com.google.android.filament.gltfio;
 import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
 
+import com.google.android.filament.Engine;
 import com.google.android.filament.Entity;
+import com.google.android.filament.MaterialInstance;
 
 /**
  * Provides access to a hierarchy of entities that have been instanced from a glTF asset.
@@ -85,6 +87,58 @@ public class FilamentInstance {
         return mAnimator;
     }
 
+    /**
+     * Gets the skin count of this instance.
+     */
+    public int getSkinCount() {
+        return nGetSkinCount(getNativeObject());
+    }
+
+    /**
+     * Gets the skin name at skin index in this instance.
+     */
+    public @NonNull String[] getSkinNames() {
+        String[] result = new String[getSkinCount()];
+        nGetSkinNames(getNativeObject(), result);
+        return result;
+    }
+
+    /**
+     * Attaches the given skin to the given node, which must have an associated mesh with
+     * BONE_INDICES and BONE_WEIGHTS attributes.
+     *
+     * This is a no-op if the given skin index or target is invalid.
+     */
+    public void attachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
+        nAttachSkin(getNativeObject(), skinIndex, target);
+    }
+
+    /**
+     * Attaches the given skin to the given node, which must have an associated mesh with
+     * BONE_INDICES and BONE_WEIGHTS attributes.
+     *
+     * This is a no-op if the given skin index or target is invalid.
+     */
+    public void detachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
+        nDetachSkin(getNativeObject(), skinIndex, target);
+    }
+
+    /**
+     * Gets the joint count at skin index in this instance.
+     */
+    public int getJointCountAt(@IntRange(from = 0) int skinIndex) {
+        return nGetJointCountAt(getNativeObject(), skinIndex);
+    }
+
+    /**
+     * Gets joints at skin index in this instance.
+     */
+    public @NonNull @Entity int[] getJointsAt(@IntRange(from = 0) int skinIndex) {
+        int[] result = new int[getJointCountAt(skinIndex)];
+        nGetJointsAt(getNativeObject(), skinIndex, result);
+        return result;
+    }
+
     /**
      * Applies the given material variant to all primitives in this instance.
      *
@@ -94,9 +148,43 @@ public class FilamentInstance {
         nApplyMaterialVariant(mNativeObject, variantIndex);
     }
 
-    private static native int nGetRoot(long nativeAsset);
-    private static native int nGetEntityCount(long nativeAsset);
-    private static native void nGetEntities(long nativeAsset, int[] result);
-    private static native long nGetAnimator(long nativeAsset);
-    private static native void nApplyMaterialVariant(long nativeAsset, int variantIndex);
+    public @NonNull MaterialInstance[] getMaterialInstances() {
+        final int count = nGetMaterialInstanceCount(mNativeObject);
+        MaterialInstance[] result = new MaterialInstance[count];
+        long[] natives = new long[count];
+        nGetMaterialInstances(mNativeObject, natives);
+        Engine engine = mAsset.getEngine();
+        for (int i = 0; i < count; i++) {
+            result[i] = new MaterialInstance(engine, natives[i]);
+        }
+        return result;
+    }
+
+    /**
+     * Returns the names of all material variants.
+     */
+    public @NonNull String[] getMaterialVariantNames() {
+        String[] names = new String[nGetMaterialVariantCount(mNativeObject)];
+        nGetMaterialVariantNames(mNativeObject, names);
+        return names;
+    }
+
+    private static native int nGetRoot(long nativeInstance);
+    private static native int nGetEntityCount(long nativeInstance);
+    private static native void nGetEntities(long nativeInstance, int[] result);
+    private static native long nGetAnimator(long nativeInstance);
+
+    private static native int nGetMaterialInstanceCount(long nativeAsset);
+    private static native void nGetMaterialInstances(long nativeAsset, long[] nativeResults);
+
+    private static native void nApplyMaterialVariant(long nativeInstance, int variantIndex);
+    private static native int nGetMaterialVariantCount(long nativeAsset);
+    private static native void nGetMaterialVariantNames(long nativeAsset, String[] result);
+
+    private static native void nGetJointsAt(long nativeInstance, int skinIndex, int[] result);
+    private static native int nGetSkinCount(long nativeInstance);
+    private static native void nGetSkinNames(long nativeInstance, String[] result);
+    private static native int nGetJointCountAt(long nativeInstance, int skinIndex);
+    private static native void nAttachSkin(long nativeInstance, int skinIndex, int entity);
+    private static native void nDetachSkin(long nativeInstance, int skinIndex, int entity);
 }

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/MaterialProvider.java

@@ -24,47 +24,85 @@ import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.Size;
 
-public interface MaterialProvider {
+import com.google.android.filament.proguard.UsedByNative;
 
+@UsedByNative("AssetLoader.cpp")
+public interface MaterialProvider {
     /**
      * MaterialKey specifies the requirements for a requested glTF material.
      * The provider creates Filament materials that fulfill these requirements.
      */
+    @UsedByNative("MaterialKey.cpp")
     public static class MaterialKey {
+        @UsedByNative("MaterialKey.cpp")
         public boolean doubleSided;
+        @UsedByNative("MaterialKey.cpp")
         public boolean unlit;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasVertexColors;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasBaseColorTexture;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasNormalTexture;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasOcclusionTexture;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasEmissiveTexture;
+        @UsedByNative("MaterialKey.cpp")
         public boolean useSpecularGlossiness;
+        @UsedByNative("MaterialKey.cpp")
         public int alphaMode;                       // 0 = OPAQUE, 1 = MASK, 2 = BLEND
+        @UsedByNative("MaterialKey.cpp")
         public boolean enableDiagnostics;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasMetallicRoughnessTexture; // piggybacks with specularRoughness
+        @UsedByNative("MaterialKey.cpp")
         public int metallicRoughnessUV;             // piggybacks with specularRoughness
+        @UsedByNative("MaterialKey.cpp")
         public int baseColorUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasClearCoatTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int clearCoatUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasClearCoatRoughnessTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int clearCoatRoughnessUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasClearCoatNormalTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int clearCoatNormalUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasClearCoat;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasTransmission;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasTextureTransforms;
+        @UsedByNative("MaterialKey.cpp")
         public int emissiveUV;
+        @UsedByNative("MaterialKey.cpp")
         public int aoUV;
+        @UsedByNative("MaterialKey.cpp")
         public int normalUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasTransmissionTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int transmissionUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasSheenColorTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int sheenColorUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasSheenRoughnessTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int sheenRoughnessUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasVolumeThicknessTexture;
+        @UsedByNative("MaterialKey.cpp")
         public int volumeThicknessUV;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasSheen;
+        @UsedByNative("MaterialKey.cpp")
         public boolean hasIOR;
 
         public MaterialKey() {}
@@ -104,6 +142,12 @@ public interface MaterialProvider {
     public @Nullable MaterialInstance createMaterialInstance(MaterialKey config,
             @NonNull @Size(min = 8) int[] uvmap, @Nullable String label, @Nullable String extras);
 
+    /**
+     * Creates or fetches a compiled Filament material corresponding to the given config.
+     */
+    public @Nullable Material getMaterial(MaterialKey config, @NonNull @Size(min = 8) int[] uvmap,
+            @Nullable String label);
+
     /**
      * Creates and returns an array containing all cached materials.
      */

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/ResourceLoader.java

@@ -47,7 +47,7 @@ public class ResourceLoader {
      */
     public ResourceLoader(@NonNull Engine engine) {
         long nativeEngine = engine.getNativeObject();
-        mNativeObject = nCreateResourceLoader(nativeEngine, false, false, false);
+        mNativeObject = nCreateResourceLoader(nativeEngine, false);
         mNativeStbProvider = nCreateStbProvider(nativeEngine);
         mNativeKtx2Provider = nCreateKtx2Provider(nativeEngine);
         nAddTextureProvider(mNativeObject, "image/jpeg", mNativeStbProvider);
@@ -60,16 +60,12 @@ public class ResourceLoader {
      *
      * @param engine the engine that gets passed to all builder methods
      * @param normalizeSkinningWeights scale non-conformant skinning weights so they sum to 1
-     * @param recomputeBoundingBoxes use computed bounding boxes rather than the ones in the asset
-     * @param ignoreBindTransform ignore skinned primitives bind transform when compute bounding boxes
      * @throws IllegalAccessException
      * @throws InvocationTargetException
      */
-    public ResourceLoader(@NonNull Engine engine, boolean normalizeSkinningWeights,
-            boolean recomputeBoundingBoxes, boolean ignoreBindTransform) {
+    public ResourceLoader(@NonNull Engine engine, boolean normalizeSkinningWeights) {
         long nativeEngine = engine.getNativeObject();
-        mNativeObject = nCreateResourceLoader(nativeEngine, normalizeSkinningWeights,
-                recomputeBoundingBoxes, ignoreBindTransform);
+        mNativeObject = nCreateResourceLoader(nativeEngine, normalizeSkinningWeights);
         mNativeStbProvider = nCreateStbProvider(nativeEngine);
         mNativeKtx2Provider = nCreateKtx2Provider(nativeEngine);
         nAddTextureProvider(mNativeObject, "image/jpeg", mNativeStbProvider);
@@ -181,7 +177,7 @@ public class ResourceLoader {
     }
 
     private static native long nCreateResourceLoader(long nativeEngine,
-            boolean normalizeSkinningWeights, boolean recomputeBoundingBoxes, boolean ignoreBindTransform);
+            boolean normalizeSkinningWeights);
     private static native void nDestroyResourceLoader(long nativeLoader);
     private static native void nAddResourceData(long nativeLoader, String url, Buffer buffer,
             int remaining);

android/gltfio-android/src/main/java/com/google/android/filament/gltfio/UbershaderProvider.java

@@ -20,6 +20,7 @@ import com.google.android.filament.Engine;
 import com.google.android.filament.MaterialInstance;
 import com.google.android.filament.Material;
 import com.google.android.filament.VertexBuffer;
+import com.google.android.filament.proguard.UsedByNative;
 
 import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
@@ -57,10 +58,16 @@ public class UbershaderProvider implements MaterialProvider {
 
     public @Nullable MaterialInstance createMaterialInstance(MaterialKey config,
             @NonNull @Size(min = 8) int[] uvmap, @Nullable String label, @Nullable String extras) {
-        long nativeMaterialInstance = nCreateMaterialInstance(mNativeObject, config, uvmap, label);
+        long nativeMaterialInstance = nCreateMaterialInstance(mNativeObject, config, uvmap, label, extras);
         return nativeMaterialInstance == 0 ? null : new MaterialInstance(null, nativeMaterialInstance);
     }
 
+    public @Nullable Material getMaterial(MaterialKey config, @NonNull @Size(min = 8) int[] uvmap,
+            @Nullable String label) {
+        long nativeMaterial = nGetMaterial(mNativeObject, config, uvmap, label);
+        return nativeMaterial == 0 ? null : new Material(nativeMaterial);
+    }
+
     public @NonNull Material[] getMaterials() {
         final int count = nGetMaterialCount(mNativeObject);
         Material[] result = new Material[count];
@@ -88,6 +95,7 @@ public class UbershaderProvider implements MaterialProvider {
         nDestroyMaterials(mNativeObject);
     }
 
+    @UsedByNative("AssetLoader.cpp")
     public long getNativeObject() {
         return mNativeObject;
     }
@@ -96,6 +104,8 @@ public class UbershaderProvider implements MaterialProvider {
     private static native void nDestroyUbershaderProvider(long nativeProvider);
     private static native void nDestroyMaterials(long nativeProvider);
     private static native long nCreateMaterialInstance(long nativeProvider,
+            MaterialKey config, int[] uvmap, String label, String extras);
+    private static native long nGetMaterial(long nativeProvider,
             MaterialKey config, int[] uvmap, String label);
     private static native int nGetMaterialCount(long nativeProvider);
     private static native void nGetMaterials(long nativeProvider, long[] result);

android/gradle.properties

@@ -1,5 +1,5 @@
 GROUP=com.google.android.filament
-VERSION_NAME=1.25.4
+VERSION_NAME=1.32.0
 
 POM_DESCRIPTION=Real-time physically based rendering engine for Android.
 
@@ -19,10 +19,8 @@ org.gradle.jvmargs=-Xmx1536m
 
 android.useAndroidX=true
 
-org.gradle.unsafe.configuration-cache=true
-# TODO: Remove this when we switch to Gradle 7.4
-org.gradle.unsafe.configuration-cache.max-problems=3
-
 com.google.android.filament.tools-dir=../../../out/release/filament
 com.google.android.filament.dist-dir=../out/android-release/filament
 com.google.android.filament.abis=all
+#com.google.android.filament.matdbg
+#com.google.android.filament.matnopt

android/gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 #Wed Nov 17 10:40:18 PST 2021
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/proguard-rules.pro

@@ -14,3 +14,17 @@
 -keepclassmembers class * {
   @com.google.android.filament.proguard.UsedBy* *;
 }
+
+# These classes is loaded via env->FindClass() from Utils.cpp
+# They are in the utils namespace and therefore not covered by previous rules.
+-keep class com.google.android.filament.utils.KTX1Loader
+-keep class com.google.android.filament.utils.HDRLoader
+
+# These native JNI methods are loaded via env->RegisterNatives() from Utils.cpp
+-keepclassmembers class com.google.android.filament.utils.KTX1Loader {
+   native <methods>;
+}
+-keepclassmembers class com.google.android.filament.utils.HDRLoader {
+   native <methods>;
+}
+

android/samples/README.md

@@ -112,9 +112,9 @@ the Android SDK.
 
 ## Android Studio
 
-You must use Android Studio 3.6 RC 1 or higher. To open the project, point Studio to the `android`
-folder. After opening the project and syncing to gradle, select the sample of your choice using the
-drop-down widget in the toolbar.
+You must use the latest stable release of Android Studio. To open the project, point Studio to the
+`android` folder. After opening the project and syncing to gradle, select the sample of your choice
+using the drop-down widget in the toolbar.
 
 ## Compiling
 

android/samples/sample-gltf-viewer/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.gltf">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <uses-permission android:name="android.permission.INTERNET" />
 

android/samples/sample-gltf-viewer/src/main/java/com/google/android/filament/gltf/MainActivity.kt

@@ -353,9 +353,11 @@ class MainActivity : Activity() {
     fun loadSettings(message: RemoteServer.ReceivedMessage) {
         val json = StandardCharsets.UTF_8.decode(message.buffer).toString()
         viewerContent.assetLights = modelViewer.asset?.lightEntities
-        automation.applySettings(json, viewerContent)
+        automation.applySettings(modelViewer.engine, json, viewerContent)
         modelViewer.view.colorGrading = automation.getColorGrading(modelViewer.engine)
         modelViewer.cameraFocalLength = automation.viewerOptions.cameraFocalLength
+        modelViewer.cameraNear = automation.viewerOptions.cameraNear
+        modelViewer.cameraFar = automation.viewerOptions.cameraFar
         updateRootTransform()
     }
 
@@ -417,7 +419,7 @@ class MainActivity : Activity() {
 
     // Just for testing purposes, this releases the current model and reloads the default model.
     inner class DoubleTapListener : GestureDetector.SimpleOnGestureListener() {
-        override fun onDoubleTap(e: MotionEvent?): Boolean {
+        override fun onDoubleTap(e: MotionEvent): Boolean {
             modelViewer.destroyModel()
             createDefaultRenderables()
             return super.onDoubleTap(e)

android/samples/sample-hello-camera/src/main/AndroidManifest.xml

@@ -16,8 +16,7 @@
   limitations under the License.
  -->
 
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.hellocam">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <uses-permission android:name="android.permission.CAMERA" />
 

android/samples/sample-hello-triangle/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.hellotriangle">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-image-based-lighting/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.ibl">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <uses-permission android:name="android.permission.INTERNET" />
 

android/samples/sample-lit-cube/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.litcube">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-live-wallpaper/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.livewallpaper">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <uses-feature android:name="android.software.live_wallpaper" />
 

android/samples/sample-material-builder/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.material_builder">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

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>

android/samples/sample-multi-view/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.multiview">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-multi-view/src/main/java/com/google/android/filament/multiview/MainActivity.kt

@@ -27,6 +27,7 @@ import android.view.animation.LinearInterpolator
 
 import com.google.android.filament.*
 import com.google.android.filament.RenderableManager.*
+import com.google.android.filament.Renderer.ClearOptions
 import com.google.android.filament.VertexBuffer.*
 import com.google.android.filament.android.DisplayHelper
 import com.google.android.filament.android.UiHelper
@@ -64,7 +65,6 @@ class MainActivity : Activity() {
     private lateinit var view0: View
     private lateinit var view1: View
     private lateinit var view2: View
-    private lateinit var view3: View
     private lateinit var view4: View
     // We need skybox to set the background color
     private lateinit var skybox: Skybox
@@ -119,15 +119,19 @@ class MainActivity : Activity() {
         view0 = engine.createView()
         view1 = engine.createView()
         view2 = engine.createView()
-        view3 = engine.createView()
         view4 = engine.createView()
 
         view0.setName("view0");
         view1.setName("view1");
         view2.setName("view2");
-        view3.setName("view3");
         view4.setName("view4");
 
+//  Useful for debugging issues
+//        view0.isPostProcessingEnabled = false
+//        view1.isPostProcessingEnabled = false
+//        view2.isPostProcessingEnabled = false
+//        view4.isPostProcessingEnabled = false
+
         view4.blendMode = View.BlendMode.TRANSLUCENT;
 
         skybox =  Skybox.Builder().build(engine);
@@ -140,13 +144,11 @@ class MainActivity : Activity() {
         view0.camera = camera
         view1.camera = camera
         view2.camera = camera
-        view3.camera = camera
         view4.camera = camera
 
         view0.scene = scene
         view1.scene = scene
         view2.scene = scene
-        view3.scene = scene
         view4.scene = scene
     }
 
@@ -379,7 +381,6 @@ class MainActivity : Activity() {
         engine.destroyView(view0)
         engine.destroyView(view1)
         engine.destroyView(view2)
-        engine.destroyView(view3)
         engine.destroyView(view4)
         engine.destroySkybox(skybox)
         engine.destroyScene(scene)
@@ -407,19 +408,18 @@ class MainActivity : Activity() {
                 // If beginFrame() returns false you should skip the frame
                 // This means you are sending frames too quickly to the GPU
                 if (renderer.beginFrame(swapChain!!, frameTimeNanos)) {
-                    skybox.setColor(0.035f, 0.035f, 0.035f, 1.0f);
+                    scene.skybox = skybox
+                    skybox.setColor(0.35f, 0.35f, 0.35f, 1.0f);
+
                     renderer.render(view0)
 
-                    skybox.setColor(1.0f, 0.0f, 0.0f, 1.0f);
+                    skybox.setColor(1.0f, 1.0f, 0.0f, 1.0f);
+
                     renderer.render(view1)
 
-                    skybox.setColor(0.0f, 1.0f, 0.0f, 1.0f);
+                    scene.skybox = null
+
                     renderer.render(view2)
-
-                    skybox.setColor(0.0f, 0.0f, 1.0f, 1.0f);
-                    renderer.render(view3)
-
-                    skybox.setColor(0.0f, 0.0f, 0.0f, 0.0f);
                     renderer.render(view4)
 
                     renderer.endFrame()
@@ -433,6 +433,10 @@ class MainActivity : Activity() {
             swapChain?.let { engine.destroySwapChain(it) }
             swapChain = engine.createSwapChain(surface)
             renderer.setDisplayInfo(DisplayHelper.getDisplayInfo(surfaceView.display, Renderer.DisplayInfo()))
+            renderer.clearOptions = renderer.clearOptions.apply {
+                clear = true
+                clearColor = floatArrayOf( 0.0f, 0.0f, 1.0f, 0.0f )
+            }
         }
 
         override fun onDetachedFromSurface() {
@@ -453,7 +457,6 @@ class MainActivity : Activity() {
             view0.viewport = Viewport(0,         0,          width / 2, height / 2)
             view1.viewport = Viewport(width / 2, 0,          width / 2, height / 2)
             view2.viewport = Viewport(0,         height / 2, width / 2, height / 2)
-            view3.viewport = Viewport(width / 2, height / 2, width / 2, height / 2)
             view4.viewport = Viewport(width / 4, height / 4, width / 2, height / 2)
         }
     }

android/samples/sample-page-curl/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.pagecurl">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-stream-test/src/main/AndroidManifest.xml

@@ -16,8 +16,7 @@
   limitations under the License.
  -->
 
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.streamtest">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-texture-view/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.textureview">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-textured-object/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.textured">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

android/samples/sample-transparent-view/src/main/AndroidManifest.xml

@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.google.android.filament.transparentrendering">
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
   <application
       android:allowBackup="true"

build.sh

@@ -22,9 +22,11 @@ function print_help {
     echo "        All (and only) git-ignored files under android/ are deleted."
     echo "        This is sometimes needed instead of -c (which still misses some clean steps)."
     echo "    -d"
-    echo "        Enable matdbg and disable material optimization."
+    echo "        Enable matdbg."
     echo "    -f"
     echo "        Always invoke CMake before incremental builds."
+    echo "    -g"
+    echo "        Disable material optimization."
     echo "    -i"
     echo "        Install build output"
     echo "    -m"
@@ -56,6 +58,9 @@ function print_help {
     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 ""
     echo "Build types:"
     echo "    release"
@@ -162,6 +167,11 @@ EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=OFF"
 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
 MATDBG_GRADLE_OPTION=""
 
+MATOPT_OPTION=""
+MATOPT_GRADLE_OPTION=""
+
+ASAN_UBSAN_OPTION=""
+
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false
 
@@ -221,6 +231,8 @@ function build_desktop_target {
             ${SWIFTSHADER_OPTION} \
             ${EGL_ON_LINUX_OPTION} \
             ${MATDBG_OPTION} \
+            ${MATOPT_OPTION} \
+            ${ASAN_UBSAN_OPTION} \
             ${deployment_target} \
             ${architectures} \
             ../..
@@ -347,6 +359,7 @@ function build_android_target {
             -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \
             -DCMAKE_TOOLCHAIN_FILE="../../build/toolchain-${arch}-linux-android.cmake" \
             ${MATDBG_OPTION} \
+            ${MATOPT_OPTION} \
             ${VULKAN_ANDROID_OPTION} \
             ../..
     fi
@@ -463,6 +476,7 @@ function build_android {
             -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \
             ${VULKAN_ANDROID_GRADLE_OPTION} \
             ${MATDBG_GRADLE_OPTION} \
+            ${MATOPT_GRADLE_OPTION} \
             :filament-android:assembleDebug \
             :gltfio-android:assembleDebug \
             :filament-utils-android:assembleDebug
@@ -510,6 +524,7 @@ function build_android {
             -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \
             ${VULKAN_ANDROID_GRADLE_OPTION} \
             ${MATDBG_GRADLE_OPTION} \
+            ${MATOPT_GRADLE_OPTION} \
             :filament-android:assembleRelease \
             :gltfio-android:assembleRelease \
             :filament-utils-android:assembleRelease
@@ -576,6 +591,7 @@ function build_ios_target {
             -DIOS=1 \
             -DCMAKE_TOOLCHAIN_FILE=../../third_party/clang/iOS.cmake \
             ${MATDBG_OPTION} \
+            ${MATOPT_OPTION} \
             ../..
     fi
 
@@ -740,7 +756,7 @@ function run_tests {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfijmp:q:uvslwtedk:" opt; do
+while getopts ":hacCfijmp:q:uvslwtedk:b" opt; do
     case ${opt} in
         h)
             print_help
@@ -758,12 +774,16 @@ while getopts ":hacCfijmp:q:uvslwtedk:" opt; do
             ;;
         d)
             PRINT_MATDBG_HELP=true
-            MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_DISABLE_MATOPT=ON, -DFILAMENT_BUILD_FILAMAT=ON"
+            MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_BUILD_FILAMAT=ON"
             MATDBG_GRADLE_OPTION="-Pcom.google.android.filament.matdbg"
             ;;
         f)
             ISSUE_CMAKE_ALWAYS=true
             ;;
+        g)
+            MATOPT_OPTION="-DFILAMENT_DISABLE_MATOPT=ON"
+            MATOPT_GRADLE_OPTION="-Pcom.google.android.filament.matnopt"
+            ;;
         i)
             INSTALL_COMMAND=install
             ;;
@@ -849,7 +869,7 @@ while getopts ":hacCfijmp:q:uvslwtedk:" opt; do
             ;;
         e)
             EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=ON -DFILAMENT_SKIP_SDL2=ON -DFILAMENT_SKIP_SAMPLES=ON"
-            echo "EGL on Linux support enabled; skipping SLD2."
+            echo "EGL on Linux support enabled; skipping SDL2."
             ;;
         l)
             IOS_BUILD_SIMULATOR=true
@@ -863,6 +883,9 @@ while getopts ":hacCfijmp:q:uvslwtedk:" opt; do
             BUILD_ANDROID_SAMPLES=true
             ANDROID_SAMPLES=$(echo "${OPTARG}" | tr ',' '\n')
             ;;
+        b)  ASAN_UBSAN_OPTION="-DFILAMENT_ENABLE_ASAN_UBSAN=ON"
+            echo "Enabled ASAN/UBSAN"
+            ;;
         \?)
             echo "Invalid option: -${OPTARG}" >&2
             echo ""

build/android/ndk.version

@@ -1 +1 @@
-25.0.8775105
+25.1.8937393

build/common/check-headers.sh

@@ -44,6 +44,10 @@ FILAMENT_HEADERS="$1"
 includes=()
 pushd "$FILAMENT_HEADERS" >/dev/null
 for f in $(find . -name '*.h'); do
+    # Ignore platform headers. These may contain platform-specific includes.
+    if [[ "$f" == *backend/platforms/* ]]; then
+        continue
+    fi
     include_path="${f#./}"    # strip leading ./
     includes+=("${include_path}")
 done

build/common/check-metal-shaders.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+
+set -e
+
+function print_help {
+    local self_name=$(basename "$0")
+    echo "This tool verifies that every Metal shader in the given Filament material file(s) successfully compiles."
+    echo "Requires the matinfo tool and xcrun to be on the system PATH."
+    echo ""
+    echo "Usage:"
+    echo "    $self_name [options] [<material> ...]"
+    echo ""
+    echo "Options:"
+    echo "    -h"
+    echo "        Print this help message."
+    echo "    -w"
+    echo "        Pass the -w flag to the Metal compiler, to disable warnings."
+    echo ""
+}
+
+COMP_FLAGS=""
+while getopts ":hw" opt; do
+    case ${opt} in
+        h)
+            print_help
+            exit 1
+            ;;
+        w)
+            COMP_FLAGS="${COMP_FLAGS} -w"
+            ;;
+    esac
+done
+
+shift $((OPTIND - 1))
+
+if [[ "$#" == "0" ]]; then
+    print_help
+    exit 1
+fi
+
+# Make sure matinfo and xcrun are available.
+if [[ ! $(command -v matinfo) ]]; then
+    echo "Error: matinfo not on PATH."
+    exit 1
+fi
+if [[ ! $(command -v xcrun) ]]; then
+    echo "Error: xcrun not on PATH."
+    exit 1
+fi
+
+function check_material {
+    local material="$1"
+
+    tmpdir="$(mktemp -d /tmp/check_metal_shaders.XXXXX)"
+
+    # First check that the material is valid.
+    if [[ ! $(matinfo "${material}") ]]; then
+        echo "Invalid material file: ${material}"
+        exit 1
+    fi
+
+    echo "Checking that Metal shaders compile: ${material}"
+
+    set +e
+    local i=0
+    while true; do
+        # The file must have a .metal extension.
+        metalFile="${tmpdir}/${i}.metal"
+
+        # Extract shader i. matinfo will return a non-zero exit code if the shader doesn't exist,
+        # which means we're finished with this material.
+        matinfo --print-metal=${i} "${material}" > "${metalFile}" 2> /dev/null
+
+        if [[ "$?" -ne 0 ]]; then
+            break
+        fi
+
+        echo "Testing Metal shader ${i}"
+
+        # Attempt to compile the Metal shader.
+        xcrun -sdk macosx metal ${COMP_FLAGS} -c "${metalFile}" -o /dev/null
+
+        if [[ "$?" -ne 0 ]]; then
+            echo "Error compiling Metal shader: ${metalFile}"
+            exit 1
+        fi
+
+        ((i++))
+    done
+    set -e
+
+    rm -r "${tmpdir}"
+}
+
+for material in "$@"
+do
+    check_material "${material}"
+done
+

build/common/requirements.txt

@@ -1,14 +0,0 @@
-setuptools==40.6.2
-wheel==0.37.1
-certifi==2021.10.8
-cffi==1.15.0
-charset-normalizer==2.0.12
-Deprecated==1.2.13
-idna==3.3
-pycparser==2.21
-PyGithub==1.55
-PyJWT==2.4.0
-PyNaCl==1.5.0
-requests==2.27.1
-urllib3==1.26.9
-wrapt==1.14.0

build/common/upload-assets.py

@@ -1,93 +0,0 @@
-# Copyright (C) 2019 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.
-
-
-# requirements.txt created via:
-#
-# pip3 install virtualenv
-# python3 -m venv env
-# pip3 install PyGithub
-# pip3 install wheel
-# --all includes wheel and setuputils, which is needed for GitHub Actions
-# pip3 freeze --all > requirements.txt
-# Manually move 'setuptools' and 'wheel' lines to the beginning of the file.
-# Manually remove the 'pip' line.
-#
-# Requirements are installed in GitHub Actions via:
-# xargs -L 1 sudo pip3 install < build/common/requirements.txt
-# xargs must be used because the ordering of the dependencies matters (namely, setuptools).
-# sudo must be used to uninstall non-matching versions of packages.
-# pip is removed to avoid conflicts with the pre-installed pip version on Actions.
-# This technique does not work with Windows, unfortunately.
-
-from github import Github
-import os, sys
-
-def print_usage():
-    print('Upload assets to a Filament GitHub release.')
-    print()
-    print('Usage:')
-    print('  upload-assets.py <tag> <asset>...')
-    print()
-    print('Notes:')
-    print('  The GitHub release must already be created prior to running this script. This is typically done')
-    print('  through the GitHub web UI.')
-    print()
-    print('  <tag> is the Git tag for the desired release to attach assets to, for example, "v1.4.2".')
-    print()
-    print('  <asset> is a path to the asset file to upload. The file name will be used as the name of the')
-    print('  asset.')
-    print()
-    print('  The GITHUB_API_KEY environment variable must be set to a valid authentication token for a')
-    print('  collaborator account of the Filament repository.')
-
-# The first argument is the path to this script.
-if len(sys.argv) < 3:
-    print_usage()
-    sys.exit(1)
-
-tag = sys.argv[1]
-assets = sys.argv[2:]
-
-authentication_token = os.environ.get('GITHUB_API_KEY')
-if not authentication_token:
-    sys.stderr.write('Error: the GITHUB_API_KEY is not set.\n')
-    sys.exit(1)
-
-g = Github(authentication_token)
-
-FILAMENT_REPO = "google/filament"
-filament = g.get_repo(FILAMENT_REPO)
-
-def find_release_from_tag(repo, tag):
-    """ Find a release in the repo for the given Git tag string. """
-    releases = repo.get_releases()
-    for r in releases:
-        if r.tag_name == tag:
-            return r
-    return None
-
-release = find_release_from_tag(filament, tag)
-if not release:
-    sys.stderr.write(f"Error: Could not find release with tag '{tag}'.\n")
-    sys.exit(1)
-
-print(f"Found release with tag '{tag}'.")
-
-for asset_path in assets:
-    sys.stdout.write(f'Uploding asset: {asset_path}... ')
-    asset_name = os.path.basename(asset_path)
-    asset = release.upload_asset(asset_path, name=asset_name)
-    if asset:
-        sys.stdout.write('Success!\n')

build/common/upload-release-assets/index.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright (C) 2022 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.
+ */
+
+const uploadReleaseAssets = async ({github, context}, assetPathsToUpload, releaseTag) => {
+    const fs = require('fs/promises');
+    const path = require('path');
+
+    const filesToUpload = assetPathsToUpload.map(assetPath => ({
+        buffer: fs.readFile(assetPath),
+        assetName: path.basename(assetPath)
+    }));
+
+    const findReleaseMatchingTag = async tag => {
+        const { data: releases } = await github.rest.repos.listReleases(context.repo);
+        const release = releases.find(release => release.tag_name === releaseTag);
+        if (!release) {
+            throw new Error(`Could not locate release with tag '${releaseTag}'`);
+        }
+        return release;
+    };
+
+    const release = await findReleaseMatchingTag(releaseTag);
+
+    console.log(`Found release named '${release.name}' matching tag '${release.tag_name}'.`);
+
+    const uploadPromises = [];
+    for (const file of filesToUpload) {
+        console.log(`Uploading asset ${file.assetName}.`);
+        const p = github.rest.repos.uploadReleaseAsset({
+            ...context.repo,
+            release_id: release.id,
+            name: file.assetName,
+            data: await file.buffer
+        });
+        uploadPromises.push(p);
+    }
+
+    await Promise.all(uploadPromises);
+    console.log("Done!");
+}
+
+module.exports = uploadReleaseAssets;
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+// To test this script locally, uncomment the code below and run:
+//
+// npm install
+// node index.js
+
+// const { Octokit } = require("@octokit/rest");
+// const glob = require("@actions/glob");
+// (async () => {
+//     const github = new Octokit({
+//         auth: ""     // <-- paste GitHub auth token here
+//     });
+//     const context = {
+//         repo: {
+//             owner: "bejado",
+//             repo: "filament",
+//         },
+//     };
+//     const globber = await glob.create('*.txt');
+//     await uploadReleaseAssets({ github, context }, await globber.glob(), 'vtest-28');
+// })();

build/common/upload-release-assets/package-lock.json

@@ -0,0 +1,546 @@
+{
+  "name": "upload-release-assets",
+  "version": "1.0.0",
+  "lockfileVersion": 2,
+  "requires": true,
+  "packages": {
+    "": {
+      "version": "1.0.0",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@actions/glob": "^0.3.0",
+        "@octokit/rest": "^19.0.5"
+      }
+    },
+    "node_modules/@actions/core": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz",
+      "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==",
+      "dependencies": {
+        "@actions/http-client": "^2.0.1",
+        "uuid": "^8.3.2"
+      }
+    },
+    "node_modules/@actions/glob": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@actions/glob/-/glob-0.3.0.tgz",
+      "integrity": "sha512-tJP1ZhF87fd6LBnaXWlahkyvdgvsLl7WnreW1EZaC8JWjpMXmzqWzQVe/IEYslrkT9ymibVrKyJN4UMD7uQM2w==",
+      "dependencies": {
+        "@actions/core": "^1.2.6",
+        "minimatch": "^3.0.4"
+      }
+    },
+    "node_modules/@actions/http-client": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.0.1.tgz",
+      "integrity": "sha512-PIXiMVtz6VvyaRsGY268qvj57hXQEpsYogYOu2nrQhlf+XCGmZstmuZBbAybUl1nQGnvS1k1eEsQ69ZoD7xlSw==",
+      "dependencies": {
+        "tunnel": "^0.0.6"
+      }
+    },
+    "node_modules/@octokit/auth-token": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-3.0.2.tgz",
+      "integrity": "sha512-pq7CwIMV1kmzkFTimdwjAINCXKTajZErLB4wMLYapR2nuB/Jpr66+05wOTZMSCBXP6n4DdDWT2W19Bm17vU69Q==",
+      "dependencies": {
+        "@octokit/types": "^8.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/core": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-4.1.0.tgz",
+      "integrity": "sha512-Czz/59VefU+kKDy+ZfDwtOIYIkFjExOKf+HA92aiTZJ6EfWpFzYQWw0l54ji8bVmyhc+mGaLUbSUmXazG7z5OQ==",
+      "dependencies": {
+        "@octokit/auth-token": "^3.0.0",
+        "@octokit/graphql": "^5.0.0",
+        "@octokit/request": "^6.0.0",
+        "@octokit/request-error": "^3.0.0",
+        "@octokit/types": "^8.0.0",
+        "before-after-hook": "^2.2.0",
+        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/endpoint": {
+      "version": "7.0.3",
+      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-7.0.3.tgz",
+      "integrity": "sha512-57gRlb28bwTsdNXq+O3JTQ7ERmBTuik9+LelgcLIVfYwf235VHbN9QNo4kXExtp/h8T423cR5iJThKtFYxC7Lw==",
+      "dependencies": {
+        "@octokit/types": "^8.0.0",
+        "is-plain-object": "^5.0.0",
+        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/graphql": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-5.0.4.tgz",
+      "integrity": "sha512-amO1M5QUQgYQo09aStR/XO7KAl13xpigcy/kI8/N1PnZYSS69fgte+xA4+c2DISKqUZfsh0wwjc2FaCt99L41A==",
+      "dependencies": {
+        "@octokit/request": "^6.0.0",
+        "@octokit/types": "^8.0.0",
+        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/openapi-types": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-14.0.0.tgz",
+      "integrity": "sha512-HNWisMYlR8VCnNurDU6os2ikx0s0VyEjDYHNS/h4cgb8DeOxQ0n72HyinUtdDVxJhFy3FWLGl0DJhfEWk3P5Iw=="
+    },
+    "node_modules/@octokit/plugin-paginate-rest": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-5.0.1.tgz",
+      "integrity": "sha512-7A+rEkS70pH36Z6JivSlR7Zqepz3KVucEFVDnSrgHXzG7WLAzYwcHZbKdfTXHwuTHbkT1vKvz7dHl1+HNf6Qyw==",
+      "dependencies": {
+        "@octokit/types": "^8.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=4"
+      }
+    },
+    "node_modules/@octokit/plugin-request-log": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-request-log/-/plugin-request-log-1.0.4.tgz",
+      "integrity": "sha512-mLUsMkgP7K/cnFEw07kWqXGF5LKrOkD+lhCrKvPHXWDywAwuDUeDwWBpc69XK3pNX0uKiVt8g5z96PJ6z9xCFA==",
+      "peerDependencies": {
+        "@octokit/core": ">=3"
+      }
+    },
+    "node_modules/@octokit/plugin-rest-endpoint-methods": {
+      "version": "6.7.0",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-6.7.0.tgz",
+      "integrity": "sha512-orxQ0fAHA7IpYhG2flD2AygztPlGYNAdlzYz8yrD8NDgelPfOYoRPROfEyIe035PlxvbYrgkfUZIhSBKju/Cvw==",
+      "dependencies": {
+        "@octokit/types": "^8.0.0",
+        "deprecation": "^2.3.1"
+      },
+      "engines": {
+        "node": ">= 14"
+      },
+      "peerDependencies": {
+        "@octokit/core": ">=3"
+      }
+    },
+    "node_modules/@octokit/request": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-6.2.2.tgz",
+      "integrity": "sha512-6VDqgj0HMc2FUX2awIs+sM6OwLgwHvAi4KCK3mT2H2IKRt6oH9d0fej5LluF5mck1lRR/rFWN0YIDSYXYSylbw==",
+      "dependencies": {
+        "@octokit/endpoint": "^7.0.0",
+        "@octokit/request-error": "^3.0.0",
+        "@octokit/types": "^8.0.0",
+        "is-plain-object": "^5.0.0",
+        "node-fetch": "^2.6.7",
+        "universal-user-agent": "^6.0.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/request-error": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-3.0.2.tgz",
+      "integrity": "sha512-WMNOFYrSaX8zXWoJg9u/pKgWPo94JXilMLb2VManNOby9EZxrQaBe/QSC4a1TzpAlpxofg2X/jMnCyZgL6y7eg==",
+      "dependencies": {
+        "@octokit/types": "^8.0.0",
+        "deprecation": "^2.0.0",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/rest": {
+      "version": "19.0.5",
+      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-19.0.5.tgz",
+      "integrity": "sha512-+4qdrUFq2lk7Va+Qff3ofREQWGBeoTKNqlJO+FGjFP35ZahP+nBenhZiGdu8USSgmq4Ky3IJ/i4u0xbLqHaeow==",
+      "dependencies": {
+        "@octokit/core": "^4.1.0",
+        "@octokit/plugin-paginate-rest": "^5.0.0",
+        "@octokit/plugin-request-log": "^1.0.4",
+        "@octokit/plugin-rest-endpoint-methods": "^6.7.0"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/@octokit/types": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-8.0.0.tgz",
+      "integrity": "sha512-65/TPpOJP1i3K4lBJMnWqPUJ6zuOtzhtagDvydAWbEXpbFYA0oMKKyLb95NFZZP0lSh/4b6K+DQlzvYQJQQePg==",
+      "dependencies": {
+        "@octokit/openapi-types": "^14.0.0"
+      }
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
+    },
+    "node_modules/before-after-hook": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz",
+      "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="
+    },
+    "node_modules/deprecation": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
+      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
+    },
+    "node_modules/is-plain-object": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
+      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q==",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/node-fetch": {
+      "version": "2.6.7",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz",
+      "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==",
+      "dependencies": {
+        "whatwg-url": "^5.0.0"
+      },
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      },
+      "peerDependencies": {
+        "encoding": "^0.1.0"
+      },
+      "peerDependenciesMeta": {
+        "encoding": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "dependencies": {
+        "wrappy": "1"
+      }
+    },
+    "node_modules/tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
+    },
+    "node_modules/tunnel": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg==",
+      "engines": {
+        "node": ">=0.6.11 <=0.7.0 || >=0.7.3"
+      }
+    },
+    "node_modules/universal-user-agent": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
+      "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
+    },
+    "node_modules/uuid": {
+      "version": "8.3.2",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
+      "bin": {
+        "uuid": "dist/bin/uuid"
+      }
+    },
+    "node_modules/webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="
+    },
+    "node_modules/whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "dependencies": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
+    "node_modules/wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
+    }
+  },
+  "dependencies": {
+    "@actions/core": {
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@actions/core/-/core-1.10.0.tgz",
+      "integrity": "sha512-2aZDDa3zrrZbP5ZYg159sNoLRb61nQ7awl5pSvIq5Qpj81vwDzdMRKzkWJGJuwVvWpvZKx7vspJALyvaaIQyug==",
+      "requires": {
+        "@actions/http-client": "^2.0.1",
+        "uuid": "^8.3.2"
+      }
+    },
+    "@actions/glob": {
+      "version": "0.3.0",
+      "resolved": "https://registry.npmjs.org/@actions/glob/-/glob-0.3.0.tgz",
+      "integrity": "sha512-tJP1ZhF87fd6LBnaXWlahkyvdgvsLl7WnreW1EZaC8JWjpMXmzqWzQVe/IEYslrkT9ymibVrKyJN4UMD7uQM2w==",
+      "requires": {
+        "@actions/core": "^1.2.6",
+        "minimatch": "^3.0.4"
+      }
+    },
+    "@actions/http-client": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@actions/http-client/-/http-client-2.0.1.tgz",
+      "integrity": "sha512-PIXiMVtz6VvyaRsGY268qvj57hXQEpsYogYOu2nrQhlf+XCGmZstmuZBbAybUl1nQGnvS1k1eEsQ69ZoD7xlSw==",
+      "requires": {
+        "tunnel": "^0.0.6"
+      }
+    },
+    "@octokit/auth-token": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@octokit/auth-token/-/auth-token-3.0.2.tgz",
+      "integrity": "sha512-pq7CwIMV1kmzkFTimdwjAINCXKTajZErLB4wMLYapR2nuB/Jpr66+05wOTZMSCBXP6n4DdDWT2W19Bm17vU69Q==",
+      "requires": {
+        "@octokit/types": "^8.0.0"
+      }
+    },
+    "@octokit/core": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/@octokit/core/-/core-4.1.0.tgz",
+      "integrity": "sha512-Czz/59VefU+kKDy+ZfDwtOIYIkFjExOKf+HA92aiTZJ6EfWpFzYQWw0l54ji8bVmyhc+mGaLUbSUmXazG7z5OQ==",
+      "requires": {
+        "@octokit/auth-token": "^3.0.0",
+        "@octokit/graphql": "^5.0.0",
+        "@octokit/request": "^6.0.0",
+        "@octokit/request-error": "^3.0.0",
+        "@octokit/types": "^8.0.0",
+        "before-after-hook": "^2.2.0",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/endpoint": {
+      "version": "7.0.3",
+      "resolved": "https://registry.npmjs.org/@octokit/endpoint/-/endpoint-7.0.3.tgz",
+      "integrity": "sha512-57gRlb28bwTsdNXq+O3JTQ7ERmBTuik9+LelgcLIVfYwf235VHbN9QNo4kXExtp/h8T423cR5iJThKtFYxC7Lw==",
+      "requires": {
+        "@octokit/types": "^8.0.0",
+        "is-plain-object": "^5.0.0",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/graphql": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/@octokit/graphql/-/graphql-5.0.4.tgz",
+      "integrity": "sha512-amO1M5QUQgYQo09aStR/XO7KAl13xpigcy/kI8/N1PnZYSS69fgte+xA4+c2DISKqUZfsh0wwjc2FaCt99L41A==",
+      "requires": {
+        "@octokit/request": "^6.0.0",
+        "@octokit/types": "^8.0.0",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/openapi-types": {
+      "version": "14.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-14.0.0.tgz",
+      "integrity": "sha512-HNWisMYlR8VCnNurDU6os2ikx0s0VyEjDYHNS/h4cgb8DeOxQ0n72HyinUtdDVxJhFy3FWLGl0DJhfEWk3P5Iw=="
+    },
+    "@octokit/plugin-paginate-rest": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-5.0.1.tgz",
+      "integrity": "sha512-7A+rEkS70pH36Z6JivSlR7Zqepz3KVucEFVDnSrgHXzG7WLAzYwcHZbKdfTXHwuTHbkT1vKvz7dHl1+HNf6Qyw==",
+      "requires": {
+        "@octokit/types": "^8.0.0"
+      }
+    },
+    "@octokit/plugin-request-log": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-request-log/-/plugin-request-log-1.0.4.tgz",
+      "integrity": "sha512-mLUsMkgP7K/cnFEw07kWqXGF5LKrOkD+lhCrKvPHXWDywAwuDUeDwWBpc69XK3pNX0uKiVt8g5z96PJ6z9xCFA==",
+      "requires": {}
+    },
+    "@octokit/plugin-rest-endpoint-methods": {
+      "version": "6.7.0",
+      "resolved": "https://registry.npmjs.org/@octokit/plugin-rest-endpoint-methods/-/plugin-rest-endpoint-methods-6.7.0.tgz",
+      "integrity": "sha512-orxQ0fAHA7IpYhG2flD2AygztPlGYNAdlzYz8yrD8NDgelPfOYoRPROfEyIe035PlxvbYrgkfUZIhSBKju/Cvw==",
+      "requires": {
+        "@octokit/types": "^8.0.0",
+        "deprecation": "^2.3.1"
+      }
+    },
+    "@octokit/request": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/@octokit/request/-/request-6.2.2.tgz",
+      "integrity": "sha512-6VDqgj0HMc2FUX2awIs+sM6OwLgwHvAi4KCK3mT2H2IKRt6oH9d0fej5LluF5mck1lRR/rFWN0YIDSYXYSylbw==",
+      "requires": {
+        "@octokit/endpoint": "^7.0.0",
+        "@octokit/request-error": "^3.0.0",
+        "@octokit/types": "^8.0.0",
+        "is-plain-object": "^5.0.0",
+        "node-fetch": "^2.6.7",
+        "universal-user-agent": "^6.0.0"
+      }
+    },
+    "@octokit/request-error": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/@octokit/request-error/-/request-error-3.0.2.tgz",
+      "integrity": "sha512-WMNOFYrSaX8zXWoJg9u/pKgWPo94JXilMLb2VManNOby9EZxrQaBe/QSC4a1TzpAlpxofg2X/jMnCyZgL6y7eg==",
+      "requires": {
+        "@octokit/types": "^8.0.0",
+        "deprecation": "^2.0.0",
+        "once": "^1.4.0"
+      }
+    },
+    "@octokit/rest": {
+      "version": "19.0.5",
+      "resolved": "https://registry.npmjs.org/@octokit/rest/-/rest-19.0.5.tgz",
+      "integrity": "sha512-+4qdrUFq2lk7Va+Qff3ofREQWGBeoTKNqlJO+FGjFP35ZahP+nBenhZiGdu8USSgmq4Ky3IJ/i4u0xbLqHaeow==",
+      "requires": {
+        "@octokit/core": "^4.1.0",
+        "@octokit/plugin-paginate-rest": "^5.0.0",
+        "@octokit/plugin-request-log": "^1.0.4",
+        "@octokit/plugin-rest-endpoint-methods": "^6.7.0"
+      }
+    },
+    "@octokit/types": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/@octokit/types/-/types-8.0.0.tgz",
+      "integrity": "sha512-65/TPpOJP1i3K4lBJMnWqPUJ6zuOtzhtagDvydAWbEXpbFYA0oMKKyLb95NFZZP0lSh/4b6K+DQlzvYQJQQePg==",
+      "requires": {
+        "@octokit/openapi-types": "^14.0.0"
+      }
+    },
+    "balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
+    },
+    "before-after-hook": {
+      "version": "2.2.3",
+      "resolved": "https://registry.npmjs.org/before-after-hook/-/before-after-hook-2.2.3.tgz",
+      "integrity": "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="
+    },
+    "brace-expansion": {
+      "version": "1.1.11",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.11.tgz",
+      "integrity": "sha512-iCuPHDFgrHX7H2vEI/5xpz07zSHB00TpugqhmYtVmMO6518mCuRMoOYFldEBl0g187ufozdaHgWKcYFb61qGiA==",
+      "requires": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="
+    },
+    "deprecation": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/deprecation/-/deprecation-2.3.1.tgz",
+      "integrity": "sha512-xmHIy4F3scKVwMsQ4WnVaS8bHOx0DmVwRywosKhaILI0ywMDWPtBSku2HNxRvF7jtwDRsoEwYQSfbxj8b7RlJQ=="
+    },
+    "is-plain-object": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/is-plain-object/-/is-plain-object-5.0.0.tgz",
+      "integrity": "sha512-VRSzKkbMm5jMDoKLbltAkFQ5Qr7VDiTFGXxYFXXowVj387GeGNOCsOH6Msy00SGZ3Fp84b1Naa1psqgcCIEP5Q=="
+    },
+    "minimatch": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.2.tgz",
+      "integrity": "sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==",
+      "requires": {
+        "brace-expansion": "^1.1.7"
+      }
+    },
+    "node-fetch": {
+      "version": "2.6.7",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.7.tgz",
+      "integrity": "sha512-ZjMPFEfVx5j+y2yF35Kzx5sF7kDzxuDj6ziH4FFbOp87zKDZNx8yExJIb05OGF4Nlt9IHFIMBkRl41VdvcNdbQ==",
+      "requires": {
+        "whatwg-url": "^5.0.0"
+      }
+    },
+    "once": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz",
+      "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==",
+      "requires": {
+        "wrappy": "1"
+      }
+    },
+    "tr46": {
+      "version": "0.0.3",
+      "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz",
+      "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw=="
+    },
+    "tunnel": {
+      "version": "0.0.6",
+      "resolved": "https://registry.npmjs.org/tunnel/-/tunnel-0.0.6.tgz",
+      "integrity": "sha512-1h/Lnq9yajKY2PEbBadPXj3VxsDDu844OnaAo52UVmIzIvwwtBPIuNvkjuzBlTWpfJyUbG3ez0KSBibQkj4ojg=="
+    },
+    "universal-user-agent": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/universal-user-agent/-/universal-user-agent-6.0.0.tgz",
+      "integrity": "sha512-isyNax3wXoKaulPDZWHQqbmIx1k2tb9fb3GGDBRxCscfYV2Ch7WxPArBsFEG8s/safwXTT7H4QGhaIkTp9447w=="
+    },
+    "uuid": {
+      "version": "8.3.2",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg=="
+    },
+    "webidl-conversions": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz",
+      "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ=="
+    },
+    "whatwg-url": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz",
+      "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==",
+      "requires": {
+        "tr46": "~0.0.3",
+        "webidl-conversions": "^3.0.0"
+      }
+    },
+    "wrappy": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz",
+      "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ=="
+    }
+  }
+}

build/common/upload-release-assets/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "upload-release-assets",
+  "version": "1.0.0",
+  "description": "Upload Filament release assets",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Google",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@actions/glob": "^0.3.0",
+    "@octokit/rest": "^19.0.5"
+  }
+}

build/linux/ci-common.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # version of clang we want to use
-GITHUB_CLANG_VERSION=8
+GITHUB_CLANG_VERSION=14
 # version of CMake to use instead of the default one
 CMAKE_VERSION=3.19.5
 # version of ninja to use

build/web/ci-common.sh

@@ -17,7 +17,7 @@ export PATH="$PWD:$PATH"
 # npm install -g typescript
 
 # Install emscripten.
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.9.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 ./emsdk install latest
 ./emsdk activate latest

docs/Filament.md.html

@@ -1143,7 +1143,7 @@ Where $F(v,h)$ is the Fresnel term of the cloth specular BRDF in equation $\ref{
 Subsurface scattering is implemented using the wrapped diffuse lighting technique, in its energy conservative form:
 
 $$\begin{equation}
-f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left< \NoL + \frac{w}{(1 + w)^2} \right> \left< c_{subsurface} + \NoL \right>
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left< \frac{\NoL + w}{(1 + w)^2} \right> \left< c_{subsurface} + \NoL \right>
 \end{equation}$$
 
 Where $w$ is a value between 0 and 1 defining by how much the diffuse light should wrap around the terminator. To avoid introducing another parameter, we fix $w = 0.5$. Note that with wrap diffuse lighting, the diffuse term must not be multiplied by $\NoL$. The effect of this cheap
@@ -1435,7 +1435,7 @@ The term $ \lambda(l) $ in equations $ \ref{spotAbsorber} $ and $ \ref{spotRefle
  $ \ref{spotAngleAtt} $ below.
 
 $$\begin{equation}\label{spotAngleAtt}
-\lambda(l) = \frac{l \times spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
+\lambda(l) = \frac{l \cdot spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
 \end{equation}$$
 
 #### Attenuation function
@@ -3682,7 +3682,7 @@ However we only need the real bases:
 
 $$\begin{align*}
 y^{m > 0}_l &= \sqrt{2} K^m_l cos(m \phi) P^m_l(cos \theta) \\
-y^{m < 0}_l &= \sqrt{2} K^m_l sin(m \phi) P^{|m|}_l(cos \theta) \\
+y^{m < 0}_l &= \sqrt{2} K^m_l sin(|m| \phi) P^{|m|}_l(cos \theta) \\
 y^0_l &= K^0_l P^0_l(cos \theta)
 \end{align*}$$
 
@@ -3716,19 +3716,18 @@ $l = 2$      | $y^{-2}_2$ $y^{-1}_2$ $y^0_2$ $y^1_2$ $y^2_2$
 It’s also fairly easy to compute the trigonometric terms recursively:
 
 $$\begin{align*}
-C_m &\equiv cos(m \phi) \\
-S_m &\equiv sin(m \phi) \\
+C_m &\equiv cos(m \phi)sin(\theta)^m \\
+S_m &\equiv sin(m \phi)sin(\theta)^m \\
 \{ x, y, z \} &= \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
 \end{align*}$$
 
 Using the angle sum trigonometric identities:
 
 $$\begin{align*}
-cos(m \phi + \phi) &= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = \frac{(x C_m - y S_m)}{sin(\theta)^{|m + 1|}} \\
-sin(m \phi + \phi) &= sin(m \phi) sin(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = \frac{(x S_m - y C_m)}{sin(\theta)^{|m + 1|}}
+cos(m \phi + \phi) &= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = x C_m - y S_m \\
+sin(m \phi + \phi) &= sin(m \phi) cos(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = x S_m - y C_m
 \end{align*}$$
 
-The equations above have an extra term $sin(\theta)^{-|m + 1|}$ but we can compensate for that in the $P^{|m|}_l(z)$ recursion by multiplying $P^l_l(z)$ by $sin(\theta)^{|m + 1|}$ which greatly simplifies the third equation in $\ref{shRecursions}$ because $P^l_l(cos \theta) sin(\theta)^{-l} = (-1)^l(2l - 1)!!$.
 
 Listing [nonNormalizedSHBasis] shows the C++ code to compute the non-normalized SH basis $\frac{y^m_l(s)}{\sqrt{2} K^m_l}$:
 
@@ -3822,7 +3821,7 @@ Since $\left< cos \theta \right>$ does not depend on $\phi$ (azimuthal independe
 
 $$\begin{align*}
 C^0_l &= 2\pi \int_0^{\pi} \left< cos \theta \right> y^0_l(\theta) sin \theta d\theta \\
-C^0_l &= 2\pi K^)_l \int_0^{\frac{\pi}{2}} P^0_l(cos \theta) cos \theta sin \theta d\theta \\
+C^0_l &= 2\pi K^m_l \int_0^{\frac{\pi}{2}} P^0_l(cos \theta) cos \theta sin \theta d\theta \\
 C^m_l &= 0, m != 0
 \end{align*}$$
 

docs/Materials.html

@@ -86,36 +86,39 @@ counter-increment: h6;margin-right:10px}
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/format/example" class="level3"><span class="tocNumber">4.1.2&nbsp; </span>Example</a><br>
 &nbsp;&nbsp;<a href="#materialdefinitions/materialblock" class="level2"><span class="tocNumber">4.2&nbsp; </span>Material block</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:name" class="level3"><span class="tocNumber">4.2.1&nbsp; </span>General: name</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:shadingmodel" class="level3"><span class="tocNumber">4.2.2&nbsp; </span>General: shadingModel</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:parameters" class="level3"><span class="tocNumber">4.2.3&nbsp; </span>General: parameters</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:variantfilter" class="level3"><span class="tocNumber">4.2.4&nbsp; </span>General: variantFilter</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:flipuv" class="level3"><span class="tocNumber">4.2.5&nbsp; </span>General: flipUV</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:quality" class="level3"><span class="tocNumber">4.2.6&nbsp; </span>General: quality</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:requires" class="level3"><span class="tocNumber">4.2.7&nbsp; </span>Vertex and attributes: requires</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:variables" class="level3"><span class="tocNumber">4.2.8&nbsp; </span>Vertex and attributes: variables</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain" class="level3"><span class="tocNumber">4.2.9&nbsp; </span>Vertex and attributes: vertexDomain</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:interpolation" class="level3"><span class="tocNumber">4.2.10&nbsp; </span>Vertex and attributes: interpolation</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:blending" class="level3"><span class="tocNumber">4.2.11&nbsp; </span>Blending and transparency: blending</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending" class="level3"><span class="tocNumber">4.2.12&nbsp; </span>Blending and transparency: postLightingBlending</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:transparency" class="level3"><span class="tocNumber">4.2.13&nbsp; </span>Blending and transparency: transparency</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold" class="level3"><span class="tocNumber">4.2.14&nbsp; </span>Blending and transparency: maskThreshold</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode" class="level3"><span class="tocNumber">4.2.15&nbsp; </span>Blending and transparency: refractionMode</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype" class="level3"><span class="tocNumber">4.2.16&nbsp; </span>Blending and transparency: refractionType</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:culling" class="level3"><span class="tocNumber">4.2.17&nbsp; </span>Rasterization: culling</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:colorwrite" class="level3"><span class="tocNumber">4.2.18&nbsp; </span>Rasterization: colorWrite</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthwrite" class="level3"><span class="tocNumber">4.2.19&nbsp; </span>Rasterization: depthWrite</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthculling" class="level3"><span class="tocNumber">4.2.20&nbsp; </span>Rasterization: depthCulling</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:doublesided" class="level3"><span class="tocNumber">4.2.21&nbsp; </span>Rasterization: doubleSided</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:reflections" class="level3"><span class="tocNumber">4.2.22&nbsp; </span>Lighting: reflections</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:shadowmultiplier" class="level3"><span class="tocNumber">4.2.23&nbsp; </span>Lighting: shadowMultiplier</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:transparentshadow" class="level3"><span class="tocNumber">4.2.24&nbsp; </span>Lighting: transparentShadow</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange" class="level3"><span class="tocNumber">4.2.25&nbsp; </span>Lighting: clearCoatIorChange</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion" class="level3"><span class="tocNumber">4.2.26&nbsp; </span>Lighting: multiBounceAmbientOcclusion</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:specularambientocclusion" class="level3"><span class="tocNumber">4.2.27&nbsp; </span>Lighting: specularAmbientOcclusion</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing" class="level3"><span class="tocNumber">4.2.28&nbsp; </span>Anti-aliasing: specularAntiAliasing</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance" class="level3"><span class="tocNumber">4.2.29&nbsp; </span>Anti-aliasing: specularAntiAliasingVariance</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold" class="level3"><span class="tocNumber">4.2.30&nbsp; </span>Anti-aliasing: specularAntiAliasingThreshold</a><br>
-&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/shading:customsurfaceshading" class="level3"><span class="tocNumber">4.2.31&nbsp; </span>Shading: customSurfaceShading</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:featurelevel" class="level3"><span class="tocNumber">4.2.2&nbsp; </span>General: featureLevel</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:shadingmodel" class="level3"><span class="tocNumber">4.2.3&nbsp; </span>General: shadingModel</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:parameters" class="level3"><span class="tocNumber">4.2.4&nbsp; </span>General: parameters</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:variantfilter" class="level3"><span class="tocNumber">4.2.5&nbsp; </span>General: variantFilter</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:flipuv" class="level3"><span class="tocNumber">4.2.6&nbsp; </span>General: flipUV</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:quality" class="level3"><span class="tocNumber">4.2.7&nbsp; </span>General: quality</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:instanced" class="level3"><span class="tocNumber">4.2.8&nbsp; </span>General: instanced</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/general:vertexdomaindevicejittered" class="level3"><span class="tocNumber">4.2.9&nbsp; </span>General: vertexDomainDeviceJittered</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:requires" class="level3"><span class="tocNumber">4.2.10&nbsp; </span>Vertex and attributes: requires</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:variables" class="level3"><span class="tocNumber">4.2.11&nbsp; </span>Vertex and attributes: variables</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:vertexdomain" class="level3"><span class="tocNumber">4.2.12&nbsp; </span>Vertex and attributes: vertexDomain</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/vertexandattributes:interpolation" class="level3"><span class="tocNumber">4.2.13&nbsp; </span>Vertex and attributes: interpolation</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:blending" class="level3"><span class="tocNumber">4.2.14&nbsp; </span>Blending and transparency: blending</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:postlightingblending" class="level3"><span class="tocNumber">4.2.15&nbsp; </span>Blending and transparency: postLightingBlending</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:transparency" class="level3"><span class="tocNumber">4.2.16&nbsp; </span>Blending and transparency: transparency</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:maskthreshold" class="level3"><span class="tocNumber">4.2.17&nbsp; </span>Blending and transparency: maskThreshold</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractionmode" class="level3"><span class="tocNumber">4.2.18&nbsp; </span>Blending and transparency: refractionMode</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/blendingandtransparency:refractiontype" class="level3"><span class="tocNumber">4.2.19&nbsp; </span>Blending and transparency: refractionType</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:culling" class="level3"><span class="tocNumber">4.2.20&nbsp; </span>Rasterization: culling</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:colorwrite" class="level3"><span class="tocNumber">4.2.21&nbsp; </span>Rasterization: colorWrite</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthwrite" class="level3"><span class="tocNumber">4.2.22&nbsp; </span>Rasterization: depthWrite</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:depthculling" class="level3"><span class="tocNumber">4.2.23&nbsp; </span>Rasterization: depthCulling</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/rasterization:doublesided" class="level3"><span class="tocNumber">4.2.24&nbsp; </span>Rasterization: doubleSided</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:reflections" class="level3"><span class="tocNumber">4.2.25&nbsp; </span>Lighting: reflections</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:shadowmultiplier" class="level3"><span class="tocNumber">4.2.26&nbsp; </span>Lighting: shadowMultiplier</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:transparentshadow" class="level3"><span class="tocNumber">4.2.27&nbsp; </span>Lighting: transparentShadow</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:clearcoatiorchange" class="level3"><span class="tocNumber">4.2.28&nbsp; </span>Lighting: clearCoatIorChange</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:multibounceambientocclusion" class="level3"><span class="tocNumber">4.2.29&nbsp; </span>Lighting: multiBounceAmbientOcclusion</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/lighting:specularambientocclusion" class="level3"><span class="tocNumber">4.2.30&nbsp; </span>Lighting: specularAmbientOcclusion</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasing" class="level3"><span class="tocNumber">4.2.31&nbsp; </span>Anti-aliasing: specularAntiAliasing</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance" class="level3"><span class="tocNumber">4.2.32&nbsp; </span>Anti-aliasing: specularAntiAliasingVariance</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold" class="level3"><span class="tocNumber">4.2.33&nbsp; </span>Anti-aliasing: specularAntiAliasingThreshold</a><br>
+&nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/materialblock/shading:customsurfaceshading" class="level3"><span class="tocNumber">4.2.34&nbsp; </span>Shading: customSurfaceShading</a><br>
 &nbsp;&nbsp;<a href="#materialdefinitions/vertexblock" class="level2"><span class="tocNumber">4.3&nbsp; </span>Vertex block</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/vertexblock/materialvertexinputs" class="level3"><span class="tocNumber">4.3.1&nbsp; </span>Material vertex inputs</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/vertexblock/customvertexattributes" class="level3"><span class="tocNumber">4.3.2&nbsp; </span>Custom vertex attributes</a><br>
@@ -775,7 +778,7 @@ and with (right)</span></center></div></center>
 
 The <code>bentNormal</code> property defines the average unoccluded direction at a point on the surface. It is
 used to improve the accuracy of indirect lighting. Bent normals can also improve the quality of
-specular ambient occlusion (see section  <a href="#toc4.2.27">4.2.27</a> about
+specular ambient occlusion (see section  <a href="#toc4.2.30">4.2.30</a> about
 <code>specularAmbientOcclusion</code>).
 
 </p><p>
@@ -890,7 +893,7 @@ light to bend further away from the initial path.
 <p></p><p>
 
 The appearance of a refractive material will greatly depend on the <code>refractionType</code> and
-<code>refractionMode</code> settings of the material. Refer to section  <a href="#toc4.2.16">4.2.16</a> and section  <a href="#toc4.2.15">4.2.15</a>
+<code>refractionMode</code> settings of the material. Refer to section  <a href="#toc4.2.19">4.2.19</a> and section  <a href="#toc4.2.18">4.2.18</a>
 for more information.
 
 </p><p>
@@ -1423,7 +1426,36 @@ non-shader data.
 <span class="line">material {</span>
 <span class="line">    name : <span class="hljs-string">"Wet pavement"</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="general:shadingmodel">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:shadingmodel">&nbsp;</a><a class="target" name="toc4.2.2">&nbsp;</a><h3>General: shadingModel</h3>
+<a class="target" name="general:featurelevel">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:featurelevel">&nbsp;</a><a class="target" name="toc4.2.2">&nbsp;</a><h3>General: featureLevel</h3>
+<p>
+
+
+</p><dl><table><tbody><tr valign="top"><td><dt>Type</dt></td><td><dd><p>     <code>number</code>
+
+</p></dd></td></tr><tr valign="top"><td><dt>Value</dt></td><td><dd><p>      An integer value, either 1, 2 or 3. Defaults to 1.
+
+</p></dd></td></tr></tbody></table></dl><div class="table">
+<table class="table"><tbody><tr><th style="text-align:left"> Feature Level </th><th style="text-align:left"> Guaranteed features </th></tr>
+<tr><td style="text-align:left"> 1 </td><td style="text-align:left"> 9 textures per material </td></tr>
+<tr><td style="text-align:left"> 2 </td><td style="text-align:left"> 9 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
+<tr><td style="text-align:left"> 3 </td><td style="text-align:left"> 12 textures per material, cubemap arrays, ESSL 3.10 </td></tr>
+</tbody></table><center><div class="tablecaption"><a class="target" name="table_featurelevels">&nbsp;</a><b style="font-style:normal;">Table&nbsp;13:</b> Feature levels</div></center></div>
+
+<p></p><p>
+
+</p><dl><dt>Description</dt><dd><p>      Sets the feature level of the material. Each feature level defines a set of features the
+      material can use. If the material uses a feature not supported by the selected level, <code>matc</code>
+      will generate an error during compilation. A given feature level is guaranteed to support
+      all features of lower feature levels.
+
+</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
+<span class="line">    featureLevel : <span class="hljs-number">2</span></span>
+<span class="line">}</span></code></pre><p>
+
+</p><dl><table><tbody><tr valign="top"><td><dt>Bugs</dt></td><td><dd><p>      <code>matc</code> doesn't verify that a material is not using features above its selected feature level.
+
+</p></dd></td></tr></tbody></table></dl><p></p>
+<a class="target" name="general:shadingmodel">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:shadingmodel">&nbsp;</a><a class="target" name="toc4.2.3">&nbsp;</a><h3>General: shadingModel</h3>
 <p>
 
 
@@ -1440,7 +1472,7 @@ non-shader data.
 <span class="line">material {</span>
 <span class="line">    shadingModel : <span class="hljs-string">"subsurface"</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="general:parameters">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:parameters">&nbsp;</a><a class="target" name="toc4.2.3">&nbsp;</a><h3>General: parameters</h3>
+<a class="target" name="general:parameters">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:parameters">&nbsp;</a><a class="target" name="toc4.2.4">&nbsp;</a><h3>General: parameters</h3>
 <p>
 
 
@@ -1450,7 +1482,7 @@ non-shader data.
       name must be a valid GLSL identifier. Entries also have an optional <code>precision</code>, which can be
       one of <code>default</code> (best precision for the platform, typically <code>high</code> on desktop, <code>medium</code> on
       mobile), <code>low</code>, <code>medium</code>, <code>high</code>. The type must be one of the types described in
-      <a href="#table_materialparamstypes">table&nbsp;13</a>.
+      <a href="#table_materialparamstypes">table&nbsp;14</a>.
 
 </p></dd></dl><div class="table">
 <table class="table"><tbody><tr><th style="text-align:left"> Type </th><th style="text-align:left"> Description </th></tr>
@@ -1473,9 +1505,10 @@ non-shader data.
 <tr><td style="text-align:left"> float3×3 </td><td style="text-align:left"> Matrix of 3×3 floats </td></tr>
 <tr><td style="text-align:left"> float4×4 </td><td style="text-align:left"> Matrix of 4×4 floats </td></tr>
 <tr><td style="text-align:left"> sampler2d </td><td style="text-align:left"> 2D texture </td></tr>
+<tr><td style="text-align:left"> sampler2dArray </td><td style="text-align:left"> Array of 2D textures </td></tr>
 <tr><td style="text-align:left"> samplerExternal </td><td style="text-align:left"> External texture (platform-specific) </td></tr>
 <tr><td style="text-align:left"> samplerCubemap </td><td style="text-align:left"> Cubemap texture </td></tr>
-</tbody></table><center><div class="tablecaption"><a class="target" name="table_materialparamstypes">&nbsp;</a><b style="font-style:normal;">Table&nbsp;13:</b> Material parameter types</div></center></div>
+</tbody></table><center><div class="tablecaption"><a class="target" name="table_materialparamstypes">&nbsp;</a><b style="font-style:normal;">Table&nbsp;14:</b> Material parameter types</div></center></div>
 
 <p></p><p>
 
@@ -1484,7 +1517,7 @@ non-shader data.
 
 </p></dd><dt>Arrays</dt><dd><p>      A parameter can define an array of values by appending <code>[size]</code> after the type name, where
       <code>size</code> is a positive integer. For instance: <code>float[9]</code> declares an array of nine <code>float</code>
-      values. Arrays of samplers are <em class="underscore">not</em> supported at the moment.
+      values. This syntax does not apply to samplers as arrays are treated as separate types.
 
 </p></dd><dt>Description</dt><dd><p>      Lists the parameters required by your material. These parameters can be set at runtime using
       Filament's material API. Accessing parameters from the shaders varies depending on the type of
@@ -1531,7 +1564,7 @@ non-shader data.
 <span class="line">        material.reflectance = materialParams.metallicReflectance.y;</span>
 <span class="line">    }</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="general:variantfilter">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:variantfilter">&nbsp;</a><a class="target" name="toc4.2.4">&nbsp;</a><h3>General: variantFilter</h3>
+<a class="target" name="general:variantfilter">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:variantfilter">&nbsp;</a><a class="target" name="toc4.2.5">&nbsp;</a><h3>General: variantFilter</h3>
 <p>
 
 
@@ -1573,7 +1606,7 @@ non-shader data.
 <span class="line">    blending : transparent,</span>
 <span class="line">    variantFilter : [ skinning ]</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="general:flipuv">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:flipuv">&nbsp;</a><a class="target" name="toc4.2.5">&nbsp;</a><h3>General: flipUV</h3>
+<a class="target" name="general:flipuv">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:flipuv">&nbsp;</a><a class="target" name="toc4.2.6">&nbsp;</a><h3>General: flipUV</h3>
 <p>
 
 
@@ -1588,7 +1621,7 @@ non-shader data.
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    flipUV : <span class="hljs-literal">false</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="general:quality">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:quality">&nbsp;</a><a class="target" name="toc4.2.6">&nbsp;</a><h3>General: quality</h3>
+<a class="target" name="general:quality">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:quality">&nbsp;</a><a class="target" name="toc4.2.7">&nbsp;</a><h3>General: quality</h3>
 <p>
 
 
@@ -1604,7 +1637,43 @@ non-shader data.
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    quality : default</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="vertexandattributes:requires">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires">&nbsp;</a><a class="target" name="toc4.2.7">&nbsp;</a><h3>Vertex and attributes: requires</h3>
+<a class="target" name="general:instanced">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:instanced">&nbsp;</a><a class="target" name="toc4.2.8">&nbsp;</a><h3>General: instanced</h3>
+<p>
+
+
+</p><dl><dt>Type</dt><dd><p>     <code>boolean</code>
+
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+
+</p></dd><dt>Description</dt><dd><p>     Allows a material to access the instance index (i.e.: <strong class="asterisk"><code>gl_InstanceIndex</code></strong>) of instanced
+     primitives using <code>getInstanceIndex()</code> in the material's shader code. Never use
+     <strong class="asterisk"><code>gl_InstanceIndex</code></strong> directly. This is typically used with
+     <code>RenderableManager::Builder::instances()</code>. <code>getInstanceIndex()</code> is available in both the
+     vertex and fragment shader.
+
+</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
+<span class="line">    instanced : <span class="hljs-literal">true</span></span>
+<span class="line">}</span></code></pre>
+<a class="target" name="general:vertexdomaindevicejittered">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/general:vertexdomaindevicejittered">&nbsp;</a><a class="target" name="toc4.2.9">&nbsp;</a><h3>General: vertexDomainDeviceJittered</h3>
+<p>
+
+
+</p><dl><dt>Type</dt><dd><p>     <code>boolean</code>
+
+</p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
+
+</p></dd><dt>Description</dt><dd><p>     Only meaningful for <code>vertexDomain:Device</code> materials, this parameter specifies whether the
+     filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
+     Generally it needs to be applied because by definition <code>vertexDomain:Device</code> materials
+     vertices are not transformed and used <em class="asterisk">as is</em>.
+     However, if the vertex shader uses for instance <code>getViewFromClipMatrix()</code> (or other
+     matrices based on the projection), the clip-space transform is already applied.
+     Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
+
+</p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
+<span class="line">    vertexDomainDeviceJittered : <span class="hljs-literal">true</span></span>
+<span class="line">}</span></code></pre>
+<a class="target" name="vertexandattributes:requires">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:requires">&nbsp;</a><a class="target" name="toc4.2.10">&nbsp;</a><h3>Vertex and attributes: requires</h3>
 <p>
 
 
@@ -1639,7 +1708,7 @@ non-shader data.
 <span class="line">        material.baseColor.rgb *= getCustom0().rgb;</span>
 <span class="line">    }</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="vertexandattributes:variables">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables">&nbsp;</a><a class="target" name="toc4.2.8">&nbsp;</a><h3>Vertex and attributes: variables</h3>
+<a class="target" name="vertexandattributes:variables">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:variables">&nbsp;</a><a class="target" name="toc4.2.11">&nbsp;</a><h3>Vertex and attributes: variables</h3>
 <p>
 
 
@@ -1686,7 +1755,7 @@ non-shader data.
 <span class="line">        material.eyeDirection.xyz = mulMat3x3Float3(getWorldFromViewMatrix(), u);</span>
 <span class="line">    }</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="toc4.2.9">&nbsp;</a><h3>Vertex and attributes: vertexDomain</h3>
+<a class="target" name="vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:vertexdomain">&nbsp;</a><a class="target" name="toc4.2.12">&nbsp;</a><h3>Vertex and attributes: vertexDomain</h3>
 <p>
 
 
@@ -1715,7 +1784,7 @@ non-shader data.
 <p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    vertexDomain : device</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="vertexandattributes:interpolation">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation">&nbsp;</a><a class="target" name="toc4.2.10">&nbsp;</a><h3>Vertex and attributes: interpolation</h3>
+<a class="target" name="vertexandattributes:interpolation">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/vertexandattributes:interpolation">&nbsp;</a><a class="target" name="toc4.2.13">&nbsp;</a><h3>Vertex and attributes: interpolation</h3>
 <p>
 
 
@@ -1731,7 +1800,7 @@ non-shader data.
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    interpolation : flat</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="blendingandtransparency:blending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending">&nbsp;</a><a class="target" name="toc4.2.11">&nbsp;</a><h3>Blending and transparency: blending</h3>
+<a class="target" name="blendingandtransparency:blending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:blending">&nbsp;</a><a class="target" name="toc4.2.14">&nbsp;</a><h3>Blending and transparency: blending</h3>
 <p>
 
 
@@ -1772,7 +1841,7 @@ non-shader data.
 <p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    blending : transparent</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="toc4.2.12">&nbsp;</a><h3>Blending and transparency: postLightingBlending</h3>
+<a class="target" name="blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:postlightingblending">&nbsp;</a><a class="target" name="toc4.2.15">&nbsp;</a><h3>Blending and transparency: postLightingBlending</h3>
 <p>
 
 
@@ -1802,7 +1871,7 @@ non-shader data.
 <p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    postLightingBlending : add</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="blendingandtransparency:transparency">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency">&nbsp;</a><a class="target" name="toc4.2.13">&nbsp;</a><h3>Blending and transparency: transparency</h3>
+<a class="target" name="blendingandtransparency:transparency">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:transparency">&nbsp;</a><a class="target" name="toc4.2.16">&nbsp;</a><h3>Blending and transparency: transparency</h3>
 <p>
 
 
@@ -1849,7 +1918,7 @@ and correctly sorted</span></center></div></center>
 and sorting issues are minimized or eliminated</span></center></div></center>
 
 <p></p>
-<a class="target" name="blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="toc4.2.14">&nbsp;</a><h3>Blending and transparency: maskThreshold</h3>
+<a class="target" name="blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:maskthreshold">&nbsp;</a><a class="target" name="toc4.2.17">&nbsp;</a><h3>Blending and transparency: maskThreshold</h3>
 <p>
 
 
@@ -1866,7 +1935,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 <span class="line">    blending : masked,</span>
 <span class="line">    maskThreshold : <span class="hljs-number">0.5</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="toc4.2.15">&nbsp;</a><h3>Blending and transparency: refractionMode</h3>
+<a class="target" name="blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractionmode">&nbsp;</a><a class="target" name="toc4.2.18">&nbsp;</a><h3>Blending and transparency: refractionMode</h3>
 <p>
 
 
@@ -1887,7 +1956,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    refractionMode : cubemap,</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="toc4.2.16">&nbsp;</a><h3>Blending and transparency: refractionType</h3>
+<a class="target" name="blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/blendingandtransparency:refractiontype">&nbsp;</a><a class="target" name="toc4.2.19">&nbsp;</a><h3>Blending and transparency: refractionType</h3>
 <p>
 
 
@@ -1906,7 +1975,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 <span class="line">    refractionMode : cubemap,</span>
 <span class="line">    refractionType : thin,</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="rasterization:culling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:culling">&nbsp;</a><a class="target" name="toc4.2.17">&nbsp;</a><h3>Rasterization: culling</h3>
+<a class="target" name="rasterization:culling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:culling">&nbsp;</a><a class="target" name="toc4.2.20">&nbsp;</a><h3>Rasterization: culling</h3>
 <p>
 
 
@@ -1920,7 +1989,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    culling : none</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="rasterization:colorwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite">&nbsp;</a><a class="target" name="toc4.2.18">&nbsp;</a><h3>Rasterization: colorWrite</h3>
+<a class="target" name="rasterization:colorwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:colorwrite">&nbsp;</a><a class="target" name="toc4.2.21">&nbsp;</a><h3>Rasterization: colorWrite</h3>
 <p>
 
 
@@ -1933,7 +2002,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    colorWrite : <span class="hljs-literal">false</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="rasterization:depthwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite">&nbsp;</a><a class="target" name="toc4.2.19">&nbsp;</a><h3>Rasterization: depthWrite</h3>
+<a class="target" name="rasterization:depthwrite">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthwrite">&nbsp;</a><a class="target" name="toc4.2.22">&nbsp;</a><h3>Rasterization: depthWrite</h3>
 <p>
 
 
@@ -1946,7 +2015,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd></td></tr></tbody></table></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    depthWrite : <span class="hljs-literal">false</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="rasterization:depthculling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling">&nbsp;</a><a class="target" name="toc4.2.20">&nbsp;</a><h3>Rasterization: depthCulling</h3>
+<a class="target" name="rasterization:depthculling">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:depthculling">&nbsp;</a><a class="target" name="toc4.2.23">&nbsp;</a><h3>Rasterization: depthCulling</h3>
 <p>
 
 
@@ -1960,7 +2029,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    depthCulling : <span class="hljs-literal">false</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="rasterization:doublesided">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided">&nbsp;</a><a class="target" name="toc4.2.21">&nbsp;</a><h3>Rasterization: doubleSided</h3>
+<a class="target" name="rasterization:doublesided">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/rasterization:doublesided">&nbsp;</a><a class="target" name="toc4.2.24">&nbsp;</a><h3>Rasterization: doubleSided</h3>
 <p>
 
 
@@ -1968,26 +2037,24 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 
 </p></dd><dt>Value</dt><dd><p>      <code>true</code> or <code>false</code>. Defaults to <code>false</code>.
 
-</p></dd><dt>Description</dt><dd><p>      Only available in the <code>unlit</code> shading model. If this property is enabled, the final color
-      computed by the material is multiplied by the shadowing factor (or visibility). This allows to
-      create transparent shadow-receiving objects (for instance an invisible ground plane in AR).
-      This is only supported with shadows from directional lights.
+</p></dd><dt>Description</dt><dd><p>      Enables two-sided rendering and its capability to be toggled at run time. When set to <code>true</code>,
+      <code>culling</code> is automatically set to <code>none</code>; if the triangle is back-facing, the triangle's
+      normal is flipped to become front-facing. When explicitly set to <code>false</code>, this allows the
+      double-sidedness to be toggled at run time.
 
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
-<span class="line">    name : <span class="hljs-string">"Invisible shadow plane"</span>,</span>
-<span class="line">    shadingModel : unlit,</span>
-<span class="line">    shadowMultiplier : <span class="hljs-literal">true</span>,</span>
-<span class="line">    blending : transparent</span>
+<span class="line">    name : <span class="hljs-string">"Double sided material"</span>,</span>
+<span class="line">    shadingModel : lit,</span>
+<span class="line">    doubleSided : <span class="hljs-literal">true</span></span>
 <span class="line">}</span>
 <span class="line"></span>
 <span class="line">fragment {</span>
 <span class="line">    void material(inout MaterialInputs material) {</span>
 <span class="line">        prepareMaterial(material);</span>
-<span class="line">        <span class="hljs-comment">// baseColor defines the color and opacity of the final shadow</span></span>
-<span class="line">        material.baseColor = vec4(0.0, 0.0, 0.0, 0.7);</span>
+<span class="line">        material.baseColor = materialParams.albedo;</span>
 <span class="line">    }</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="lighting:reflections">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:reflections">&nbsp;</a><a class="target" name="toc4.2.22">&nbsp;</a><h3>Lighting: reflections</h3>
+<a class="target" name="lighting:reflections">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:reflections">&nbsp;</a><a class="target" name="toc4.2.25">&nbsp;</a><h3>Lighting: reflections</h3>
 <p>
 
 
@@ -2004,7 +2071,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 <span class="line">    name : <span class="hljs-string">"Glossy metal"</span>,</span>
 <span class="line">    reflections : screenspace</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="lighting:shadowmultiplier">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier">&nbsp;</a><a class="target" name="toc4.2.23">&nbsp;</a><h3>Lighting: shadowMultiplier</h3>
+<a class="target" name="lighting:shadowmultiplier">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:shadowmultiplier">&nbsp;</a><a class="target" name="toc4.2.26">&nbsp;</a><h3>Lighting: shadowMultiplier</h3>
 <p>
 
 
@@ -2031,7 +2098,7 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 <span class="line">        material.baseColor = vec4(0.0, 0.0, 0.0, 0.7);</span>
 <span class="line">    }</span>
 <span class="line">}</span></code></pre>
-<a class="target" name="lighting:transparentshadow">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow">&nbsp;</a><a class="target" name="toc4.2.24">&nbsp;</a><h3>Lighting: transparentShadow</h3>
+<a class="target" name="lighting:transparentshadow">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:transparentshadow">&nbsp;</a><a class="target" name="toc4.2.27">&nbsp;</a><h3>Lighting: transparentShadow</h3>
 <p>
 
 
@@ -2065,7 +2132,7 @@ radius of 4. Model <a href="https://sketchfab.com/3d-models/bottle-of-water-48fd
 by <a href="https://sketchfab.com/person-x">T-Art</a>.</span></center></div></center>
 
 <p></p>
-<a class="target" name="lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="toc4.2.25">&nbsp;</a><h3>Lighting: clearCoatIorChange</h3>
+<a class="target" name="lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:clearcoatiorchange">&nbsp;</a><a class="target" name="toc4.2.28">&nbsp;</a><h3>Lighting: clearCoatIorChange</h3>
 <p>
 
 
@@ -2087,7 +2154,7 @@ with <code>clearCoatIorChange</code> enabled (left) and disabled
 (right).</span></center></div></center>
 
 <p></p>
-<a class="target" name="lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="toc4.2.26">&nbsp;</a><h3>Lighting: multiBounceAmbientOcclusion</h3>
+<a class="target" name="lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:multibounceambientocclusion">&nbsp;</a><a class="target" name="toc4.2.29">&nbsp;</a><h3>Lighting: multiBounceAmbientOcclusion</h3>
 <p>
 
 
@@ -2116,7 +2183,7 @@ occclusion enabled (left) and disabled (right).</span></center></div></center>
 occclusion enabled and disabled.</span></center></div></center>
 
 <p></p>
-<a class="target" name="lighting:specularambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion">&nbsp;</a><a class="target" name="toc4.2.27">&nbsp;</a><h3>Lighting: specularAmbientOcclusion</h3>
+<a class="target" name="lighting:specularambientocclusion">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/lighting:specularambientocclusion">&nbsp;</a><a class="target" name="toc4.2.30">&nbsp;</a><h3>Lighting: specularAmbientOcclusion</h3>
 <p>
 
 
@@ -2142,7 +2209,7 @@ occclusion enabled and disabled.</span></center></div></center>
 particularly visible under the hose.</span></center></div></center>
 
 <p></p>
-<a class="target" name="anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="toc4.2.28">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasing</h3>
+<a class="target" name="anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasing">&nbsp;</a><a class="target" name="toc4.2.31">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasing</h3>
 <p>
 
 
@@ -2159,7 +2226,7 @@ particularly visible under the hose.</span></center></div></center>
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    specularAntiAliasing : <span class="hljs-literal">true</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="toc4.2.29">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingVariance</h3>
+<a class="target" name="anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingvariance">&nbsp;</a><a class="target" name="toc4.2.32">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingVariance</h3>
 <p>
 
 
@@ -2174,7 +2241,7 @@ particularly visible under the hose.</span></center></div></center>
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    specularAntiAliasingVariance : <span class="hljs-number">0.2</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="toc4.2.30">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingThreshold</h3>
+<a class="target" name="anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/anti-aliasing:specularantialiasingthreshold">&nbsp;</a><a class="target" name="toc4.2.33">&nbsp;</a><h3>Anti-aliasing: specularAntiAliasingThreshold</h3>
 <p>
 
 
@@ -2188,7 +2255,7 @@ particularly visible under the hose.</span></center></div></center>
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    specularAntiAliasingThreshold : <span class="hljs-number">0.1</span></span>
 <span class="line">}</span></code></pre>
-<a class="target" name="shading:customsurfaceshading">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading">&nbsp;</a><a class="target" name="toc4.2.31">&nbsp;</a><h3>Shading: customSurfaceShading</h3>
+<a class="target" name="shading:customsurfaceshading">&nbsp;</a><a class="target" name="materialdefinitions/materialblock/shading:customsurfaceshading">&nbsp;</a><a class="target" name="toc4.2.34">&nbsp;</a><h3>Shading: customSurfaceShading</h3>
 <p>
 
 
@@ -2252,7 +2319,7 @@ APIs listed in the <a href="#shaderpublicapis">Shader public APIs</a> section.
 <span class="line">    float3 worldNormal;        <span class="hljs-comment">// only if the shading model is not unlit</span></span>
 <span class="line">    float4 worldPosition;      <span class="hljs-comment">// always available (see note below about world-space)</span></span>
 <span class="line"></span>
-<span class="line">    <span class="hljs-type">mat4</span>   clipSpaceTransform; <span class="hljs-comment">// default: identity, transforms the clip-space position</span></span>
+<span class="line">    <span class="hljs-type">mat4</span>   clipSpaceTransform; <span class="hljs-comment">// default: identity, transforms the clip-space position, only available for `vertexDomain:device`</span></span>
 <span class="line"></span>
 <span class="line">    <span class="hljs-comment">// variable* names are replaced with actual names</span></span>
 <span class="line">    float4 variable0;          <span class="hljs-comment">// if 1 or more variables is defined</span></span>
@@ -2747,7 +2814,7 @@ source material definition file.
 <p>
 
 
-The command line flags relevant to application development are described in <a href="#table_matcflags">table&nbsp;14</a>.
+The command line flags relevant to application development are described in <a href="#table_matcflags">table&nbsp;15</a>.
 </p><div class="table">
 <table class="table"><tbody><tr><th style="text-align:right"> Flag </th><th style="text-align:center"> Value </th><th style="text-align:left"> Usage </th></tr>
 <tr><td style="text-align:right"> <strong class="asterisk">-o</strong>, <strong class="asterisk">—output</strong> </td><td style="text-align:center"> [path] </td><td style="text-align:left"> Specify the output file path </td></tr>
@@ -2756,7 +2823,7 @@ The command line flags relevant to application development are described in <a h
 <tr><td style="text-align:right"> <strong class="asterisk">-S</strong>, <strong class="asterisk">—optimize-size</strong> </td><td style="text-align:center"> N/A </td><td style="text-align:left"> Optimize compiled material for size instead of just performance </td></tr>
 <tr><td style="text-align:right"> <strong class="asterisk">-r</strong>, <strong class="asterisk">—reflect</strong> </td><td style="text-align:center"> parameters </td><td style="text-align:left"> Outputs the specified metadata as JSON </td></tr>
 <tr><td style="text-align:right"> <strong class="asterisk">-v</strong>, <strong class="asterisk">—variant-filter</strong> </td><td style="text-align:center"> [variant] </td><td style="text-align:left"> Filters out the specified, comma-separated variants </td></tr>
-</tbody></table><center><div class="tablecaption"><a class="target" name="table_matcflags">&nbsp;</a><b style="font-style:normal;">Table&nbsp;14:</b> List of <code>matc</code> flags</div></center></div>
+</tbody></table><center><div class="tablecaption"><a class="target" name="table_matcflags">&nbsp;</a><b style="font-style:normal;">Table&nbsp;15:</b> List of <code>matc</code> flags</div></center></div>
 
 <p></p><p>
 

docs/Materials.md.html

@@ -932,6 +932,37 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: featureLevel
+
+Type
+:    `number`
+
+Value
+:     An integer value, either 1, 2 or 3. Defaults to 1.
+
+      Feature Level    |        Guaranteed features
+:----------------------|:---------------------------------
+1                      | 9 textures per material
+2                      | 9 textures per material, cubemap arrays, ESSL 3.10
+3                      | 12 textures per material, cubemap arrays, ESSL 3.10
+[Table [featureLevels]: Feature levels]
+
+Description
+:     Sets the feature level of the material. Each feature level defines a set of features the
+      material can use. If the material uses a feature not supported by the selected level, `matc`
+      will generate an error during compilation. A given feature level is guaranteed to support
+      all features of lower feature levels.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    featureLevel : 2
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bugs
+:     `matc` doesn't verify that a material is not using features above its selected feature level.
+
+
 ### General: shadingModel
 
 Type
@@ -986,6 +1017,7 @@ uint4                  | Vector of 4 unsigned integers
 float3x3               | Matrix of 3x3 floats
 float4x4               | Matrix of 4x4 floats
 sampler2d              | 2D texture
+sampler2dArray         | Array of 2D textures
 samplerExternal        | External texture (platform-specific)
 samplerCubemap         | Cubemap texture
 [Table [materialParamsTypes]: Material parameter types]
@@ -997,7 +1029,7 @@ Samplers
 Arrays
 :     A parameter can define an array of values by appending `[size]` after the type name, where
       `size` is a positive integer. For instance: `float[9]` declares an array of nine `float`
-      values. Arrays of samplers are _not_ supported at the moment.
+      values. This syntax does not apply to samplers as arrays are treated as separate types.
 
 Description
 :     Lists the parameters required by your material. These parameters can be set at runtime using
@@ -1140,6 +1172,29 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: vertexDomainDeviceJittered
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Only meaningful for `vertexDomain:Device` materials, this parameter specifies whether the
+     filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
+     Generally it needs to be applied because by definition `vertexDomain:Device` materials
+     vertices are not transformed and used *as is*.
+     However, if the vertex shader uses for instance `getViewFromClipMatrix()` (or other
+     matrices based on the projection), the clip-space transform is already applied.
+     Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    vertexDomainDeviceJittered : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Vertex and attributes: requires
 
 Type
@@ -1307,6 +1362,11 @@ Description
       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
@@ -1527,24 +1587,53 @@ Value
 :     `true` or `false`. Defaults to `false`.
 
 Description
-:     Only available in the `unlit` shading model. If this property is enabled, the final color
-      computed by the material is multiplied by the shadowing factor (or visibility). This allows to
-      create transparent shadow-receiving objects (for instance an invisible ground plane in AR).
-      This is only supported with shadows from directional lights.
+:     Enables two-sided rendering and its capability to be toggled at run time. When set to `true`,
+      `culling` is automatically set to `none`; if the triangle is back-facing, the triangle's
+      normal is flipped to become front-facing. When explicitly set to `false`, this allows the
+      double-sidedness to be toggled at run time.
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
-    name : "Invisible shadow plane",
-    shadingModel : unlit,
-    shadowMultiplier : true,
-    blending : transparent
+    name : "Double sided material",
+    shadingModel : lit,
+    doubleSided : true
 }
 
 fragment {
     void material(inout MaterialInputs material) {
         prepareMaterial(material);
-        // baseColor defines the color and opacity of the final shadow
-        material.baseColor = vec4(0.0, 0.0, 0.0, 0.7);
+        material.baseColor = materialParams.albedo;
+    }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### 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;
     }
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1845,7 +1934,7 @@ struct MaterialVertexInputs {
     float3 worldNormal;        // only if the shading model is not unlit
     float4 worldPosition;      // always available (see note below about world-space)
 
-    mat4   clipSpaceTransform; // default: identity, transforms the clip-space position
+    mat4   clipSpaceTransform; // default: identity, transforms the clip-space position, only available for `vertexDomain:device`
 
     // variable* names are replaced with actual names
     float4 variable0;          // if 1 or more variables is defined
@@ -1857,8 +1946,9 @@ struct MaterialVertexInputs {
 
 !!! 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
@@ -2210,9 +2300,10 @@ type aliases:
 
                  Name               |   Type   |            Description
 :-----------------------------------|:--------:|:------------------------------------
-**getResolution()**                 | float4   |  Dimensions of the view's effective viewport in pixels: `width`, `height`, `1 / width`, `1 / height`. This might be different from `View::getViewport()` for instance because of added rendering guard-bands. This can be used in conjunction with `getNormalizedViewportCoord()` to generate pixel coordinates.
-**getWorldCameraPosition()**        | float3   |  Position of the camera/eye in world space
-**getWorldOffset()**                | float3   |  The shift required to obtain API-level world space
+**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 (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
@@ -2222,7 +2313,7 @@ type aliases:
 !!! 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
 
@@ -2244,11 +2335,12 @@ The following APIs are only available from the fragment block:
 :---------------------------------------|:--------:|:------------------------------------
 **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()`)
 **getWorldReflectedVector()**           | float3   |  Reflection of the view vector about the normal (must be used after `prepareMaterial()`)
-**getNormalizedViewportCoord()**        | float3   |  Normalized viewport position (i.e. NDC coordinates normalized to [0, 1], can be used before `prepareMaterial()`)
+**getNormalizedViewportCoord()**        | float3   |  Normalized user viewport position (i.e. NDC coordinates normalized to [0, 1] for the position, [1, 0] for the depth), can be used before `prepareMaterial()`). Because the user viewport is smaller than the actual physical viewport, these coordinates can be negative or superior to 1 in the non-visible area of the physical viewport.
 **getNdotV()**                          | float    |  The result of `dot(normal, view)`, always strictly greater than 0 (must be used after `prepareMaterial()`)
 **getColor()**                          | float4   |  Interpolated color of the fragment, if the color attribute is required
 **getUV0()**                            | float2   |  First interpolated set of UV coordinates, only available if the uv0 attribute is required
@@ -2260,9 +2352,10 @@ The following APIs are only available from the fragment block:
 **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

docs/remote/index.html

@@ -261,7 +261,7 @@ class App {
         this.renderer.setClearOptions({clearColor: kBackgroundColor, clear: true});
 
         this.render = this.render.bind(this);
-        this.simpleViewer = new Filament.SimpleViewer(engine, scene, view, kInitialSidebarWidth);
+        this.simpleViewer = new Filament.ViewerGui(engine, scene, view, kInitialSidebarWidth);
 
         this.mouseX = -1;
         this.mouseY = -1;

docs/viewer/index.html

@@ -43,7 +43,7 @@ filament-viewer::part(canvas) {
 </p>
 
 </main>
-<script src="https://unpkg.com/filament@1.22.0/filament.js"></script>
+<script src="https://unpkg.com/filament@1.25.3/filament.js"></script>
 <script src="https://unpkg.com/gltumble"></script>
 <script src="filament-viewer.js" type="module"></script>
 </body>