Merge branch 'rc/1.25.2' into release

Fix #5720

.github/actions/verify-release-notes/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.10.4
+
+RUN pip3 install pygithub==1.55
+
+ENV PYTHONUNBUFFERED=1
+
+COPY verify_release_notes.py /verify_release_notes.py
+
+RUN chmod +x /verify_release_notes.py
+ENTRYPOINT [ "/verify_release_notes.py" ]

.github/actions/verify-release-notes/action.yml

@@ -0,0 +1,35 @@
+name: 'Verify Release Notes'
+description: 'Verifies that a RELEASE_NOTES file has been modified'
+inputs:
+  repo-token:
+    description: 'The GitHub token'
+    required: true
+  pull-request-number:
+    description: 'The Pull Request number'
+    required: true
+  bypass-label-name:
+    description: 'The Label used to bypass this check'
+    required: false
+    default: 'internal'
+  release-notes-file:
+    description: 'The path to the RELEASE_NOTES file'
+    required: false
+    default: 'RELEASE_NOTES.md'
+  pull-request-repo-full-name:
+    description: 'The full name of the Pull Request repo'
+    required: false
+    default: ${{ github.event.pull_request.head.repo.full_name }}
+  pull-request-head-ref:
+    description: 'The HEAD ref of the Pull Request'
+    required: false
+    default: ${{ github.event.pull_request.head.ref }}
+runs:
+  using: 'docker'
+  image: 'Dockerfile'
+  args:
+    - ${{ inputs.repo-token }}
+    - ${{ inputs.pull-request-number }}
+    - ${{ inputs.bypass-label-name }}
+    - ${{ inputs.release-notes-file }}
+    - ${{ inputs.pull-request-repo-full-name }}
+    - ${{ inputs.pull-request-head-ref }}

.github/actions/verify-release-notes/verify_release_notes.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+# 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.
+
+from github import Github
+import sys, os
+
+def print_usage():
+    print('Verify that a GitHub pull request modifies a RELEASE_NOTES file')
+    print()
+    print('Usage:')
+    print('  verify_release_notes.py [arguments]')
+    print()
+    print('Arguments:')
+    print('1. github token')
+    print('2. pull request number')
+    print('3. bypass label name')
+    print('4. release notes file path')
+    print('5. pull request repo full name')
+    print('6. pull request head ref')
+    print()
+    print('The GITHUB_REPOSITORY environment variable must be set (e.g., google/filament).')
+
+def leave_single_comment(pull_request, comment_body):
+    """ Leaves a comment on a PR once, without leaving a duplicate comment. """
+    # To avoid spamming the PR author, we'll use this comment tag (which will render invisibly on
+    # GitHub) to check if we've already left a comment on this PR.
+    COMMENT_TAG = '<!-- verify_release_notes -->\n'
+    comments = pull_request.get_issue_comments()
+    for comment in comments:
+        if comment.body.find(COMMENT_TAG) != -1:
+            return
+    # The GitHub token may not have WRITE permissions to leave a comment (for example, for 3P
+    # contributors). In that case, we simply won't leave a comment.
+    try:
+        pull_request.create_issue_comment(f'{COMMENT_TAG}{comment_body}')
+    except:
+        print("Unable to leave comment. Continuing.")
+
+# The first argument is the path to this script.
+if len(sys.argv) != 7:
+    print_usage()
+    sys.exit(1)
+
+authentication_token = sys.argv[1]
+pull_number = sys.argv[2]
+bypass_label_name = sys.argv[3]
+release_notes_file = sys.argv[4]
+pr_repo_full_name = sys.argv[5]
+pr_head_ref = sys.argv[6]
+
+g = Github(authentication_token)
+
+repo_name = os.environ.get('GITHUB_REPOSITORY')
+if repo_name is None:
+    print("The GITHUB_REPOSITORY environment variable must be set.")
+    sys.exit(1)
+
+repo = g.get_repo(repo_name)
+
+pull_request = repo.get_pull(int(pull_number))
+
+# First check if the PR has the "bypass" label. This label is used for PRs that don't need to update
+# RELEASE_NOTES. If so, we can exit immediately.
+labels = [l.name for l in pull_request.labels]
+if bypass_label_name in labels:
+    print(f"PR number {pull_number} in repo {repo_name} contains the '{bypass_label_name}' label.")
+    print("Exiting with success.")
+    sys.exit(0)
+
+# Next, check if the release notes file (RELEASE_NOTES.md or similar) has been modified.
+files = pull_request.get_files()
+for file in files:
+    if file.filename == release_notes_file:
+        print(f"PR number {pull_number} in repo {repo_name} modifies '{release_notes_file}'.")
+        print("Exiting with success.")
+        sys.exit(0)
+
+# At this point, we issue a warning to the PR author to remember to modify the release notes, and
+# exit with failure.
+edit_url = f"https://github.com/{pr_repo_full_name}/edit/{pr_head_ref}/{release_notes_file}"
+comment = (f"Please add a release note line to [{release_notes_file}]({edit_url}). "
+    f"If this PR does not warrant a release note, add the '{bypass_label_name}' label "
+    f"to this PR.")
+print(comment)
+leave_single_comment(pull_request, comment)
+
+sys.exit(1)

.github/workflows/android-continuous.yml

@@ -33,10 +33,6 @@ jobs:
         with:
           name: gltfio-android-release
           path: out/gltfio-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: gltfio-android-lite-release
-          path: out/gltfio-android-lite-release.aar
       - uses: actions/upload-artifact@v1.0.0
         with:
           name: filament-utils-android-release

.github/workflows/release.yml

@@ -126,7 +126,6 @@ jobs:
           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/gltfio-android-lite-release.aar out/gltfio-${TAG}-lite-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
         env:

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

@@ -0,0 +1,26 @@
+name: Verify Release Notes
+
+on:
+  pull_request:
+    branches:
+      - main
+    types: [opened, synchronize, reopened, labeled]
+
+jobs:
+  verify-release-notes:
+    name: Verify Release Notes
+    runs-on: ubuntu-latest
+    steps:
+      # We *only* need to check out the .github/ directory.
+      # The verify RELEASE_NOTES script uses the GitHub API to verify that RELEASE_NOTES was
+      # modified.
+      - name: Check out action
+        uses: Bhacaz/checkout-files@73e17cfbe8d7e0c6b2672b20cb05a718e20d18d4
+        with:
+          files: .github
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Verify release notes
+        uses: ./.github/actions/verify-release-notes
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          pull-request-number: ${{ github.event.pull_request.number }}

BUILDING.md

@@ -144,6 +144,9 @@ make sure the command line tools are setup by running:
 $ xcode-select --install
 ```
 
+If you wish to run the Vulkan backend instead of the default Metal backend, you must install
+the LunarG SDK, enable "System Global Components", and reboot your machine.
+
 Then run `cmake` and `ninja` to trigger a build:
 
 ```
@@ -349,7 +352,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.5.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.9.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 python ./emsdk.py install latest
 python ./emsdk.py activate latest

CMakeLists.txt

@@ -23,6 +23,8 @@ option(FILAMENT_SUPPORTS_XCB "Include XCB support in Linux builds" ON)
 
 option(FILAMENT_SUPPORTS_XLIB "Include XLIB support in Linux builds" ON)
 
+option(FILAMENT_SUPPORTS_EGL_ON_LINUX "Use EGL for OpenGL in Linux builds" OFF)
+
 option(FILAMENT_SUPPORTS_WAYLAND "Include Wayland support in Linux builds" OFF)
 
 option(FILAMENT_SKIP_SDL2 "Skip dependencies of SDL2, and SDL2" OFF)
@@ -103,6 +105,9 @@ if (LINUX)
     if (FILAMENT_SUPPORTS_WAYLAND)
         add_definitions(-DFILAMENT_SUPPORTS_WAYLAND)
         set(FILAMENT_SUPPORTS_X11 FALSE)
+    elseif (FILAMENT_SUPPORTS_EGL_ON_LINUX)
+        add_definitions(-DFILAMENT_SUPPORTS_EGL_ON_LINUX)
+        set(FILAMENT_SUPPORTS_X11 FALSE)
     else ()
         if (FILAMENT_SUPPORTS_XCB)
             add_definitions(-DFILAMENT_SUPPORTS_XCB)
@@ -275,6 +280,10 @@ if (FILAMENT_USE_EXTERNAL_GLES3)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DUSE_EXTERNAL_GLES3")
 endif()
 
+if (FILAMENT_SUPPORTS_EGL_ON_LINUX)
+  set(EGL TRUE)
+endif()
+
 if (FILAMENT_USE_SWIFTSHADER)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DFILAMENT_USE_SWIFTSHADER")
 endif()
@@ -584,15 +593,6 @@ if (FILAMENT_USE_SWIFTSHADER)
     find_library(SWIFTSHADER_VK NAMES vk_swiftshader HINTS "$ENV{SWIFTSHADER_LD_LIBRARY_PATH}")
     message(STATUS "Found SwiftShader VK library in: ${SWIFTSHADER_VK}.")
     add_definitions(-DFILAMENT_VKLIBRARY_PATH=\"${SWIFTSHADER_VK}\")
-elseif (FILAMENT_SUPPORTS_VULKAN)
-    if (APPLE OR FILAMENT_LINUX_IS_MOBILE)
-        find_library(Vulkan_LIBRARY NAMES vulkan HINTS "$ENV{VULKAN_SDK}/lib" "$ENV{VULKAN_SDK}/macOS/lib")
-        if (Vulkan_LIBRARY)
-            set(Vulkan_FOUND ON)
-            message(STATUS "Found Vulkan library in SDK: ${Vulkan_LIBRARY}.")
-            add_definitions(-DFILAMENT_VKLIBRARY_PATH=\"${Vulkan_LIBRARY}\")
-        endif()
-    endif()
 endif()
 
 # ==================================================================================================
@@ -650,10 +650,12 @@ add_subdirectory(${LIBRARIES}/image)
 add_subdirectory(${LIBRARIES}/ktxreader)
 add_subdirectory(${LIBRARIES}/math)
 add_subdirectory(${LIBRARIES}/mathio)
+add_subdirectory(${LIBRARIES}/uberz)
 add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${LIBRARIES}/viewer)
 add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
+add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
 add_subdirectory(${EXTERNAL}/hat-trie/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)
@@ -686,10 +688,6 @@ if (FILAMENT_SUPPORTS_VULKAN)
     add_subdirectory(${EXTERNAL}/vkmemalloc/tnt)
 endif()
 
-if (APPLE)
-    add_subdirectory(${EXTERNAL}/moltenvk/tnt)
-endif()
-
 set(FILAMENT_SAMPLES_BINARY_DIR ${PROJECT_BINARY_DIR}/samples)
 
 if (WEBGL)
@@ -706,9 +704,6 @@ if (IS_HOST_PLATFORM)
 
     add_subdirectory(${FILAMENT}/samples)
 
-    add_subdirectory(${EXTERNAL}/basisu/tnt)
-    add_subdirectory(${EXTERNAL}/astcenc/tnt)
-    add_subdirectory(${EXTERNAL}/etc2comp)
     add_subdirectory(${EXTERNAL}/libassimp/tnt)
     add_subdirectory(${EXTERNAL}/libpng/tnt)
     add_subdirectory(${EXTERNAL}/libsdl2/tnt)
@@ -727,9 +722,10 @@ if (IS_HOST_PLATFORM)
     add_subdirectory(${TOOLS}/rgb-to-lmsr)
     add_subdirectory(${TOOLS}/roughness-prefilter)
     add_subdirectory(${TOOLS}/specular-color)
+    add_subdirectory(${TOOLS}/uberz)
 endif()
 
 # Generate exported executables for cross-compiled builds (Android, WebGL, and iOS)
 if (NOT CMAKE_CROSSCOMPILING)
-    export(TARGETS matc cmgen filamesh mipgen resgen glslminifier FILE ${IMPORT_EXECUTABLES})
+    export(TARGETS matc cmgen filamesh mipgen resgen uberz glslminifier FILE ${IMPORT_EXECUTABLES})
 endif()

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.21.2'
+    implementation 'com.google.android.filament:filament-android:1.25.2'
 }
 ```
 
@@ -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.21.2'
+pod 'Filament', '~> 1.25.2'
 ```
 
 ### Snapshots
@@ -177,6 +177,7 @@ steps:
   - [x] KHR_materials_variants
   - [x] KHR_materials_volume
   - [x] KHR_mesh_quantization
+  - [x] KHR_texture_basisu
   - [x] KHR_texture_transform
 
 

RELEASE_GUIDE.md

@@ -50,13 +50,13 @@ Do not push to origin yet.
 git cherry-pick rc/$RELEASE
 ```
 
-Update the headers. The "Next release" header becomes a header for $NEXT_RELEASE, and a new "Next
-release" header is added.
+Update the headers. The "main branch" header becomes a header for $NEXT_RELEASE, and a new "main
+branch" header is added.
 
 For example, this:
 
 ```
-## Next release (main branch)
+## main branch
 - foo
 - bar
 
@@ -68,7 +68,7 @@ For example, this:
 becomes:
 
 ```
-## Next release (main branch)
+## main branch
 
 ## v1.9.4
 - foo
@@ -138,3 +138,34 @@ git push origin main
 ```
 git push origin -u rc/$NEXT_RELEASE
 ```
+
+## 11. Rebuild the GitHub release (if failed).
+
+Sometimes the GitHub release job will fail. In this case, you can manually re-run the release job.
+
+### Remove any assets uploaded to the release (if needed).
+
+For example, if rebuilding the Mac release, ensure that the `filament-<version>-mac.tgz` artifact
+is removed from the release assets.
+
+### Update the release branch (if needed).
+
+If you need to add one or more new commits to the release, perform the following:
+
+First, push the new commit(s) to the `release` branch.
+
+Then, with the release branch checked out with the new commit(s), run
+
+```
+git tag -f -a <release tagname>
+git push origin -f <release tagname>
+```
+
+This will update and force push the tag.
+
+### Re-run the GitHub release workflow
+
+Navigate to [Filament's release
+workflow](https://github.com/google/filament/actions/workflows/release.yml). Hit the _Run workflow_
+dropdown. Modify _Platform to build_ and _Release tag to build_, then hit _Run workflow_. This will
+initiate a new release run.

RELEASE_NOTES.md

@@ -3,7 +3,110 @@
 This file contains one line summaries of commits that are worthy of mentioning in release notes.
 A new header is inserted each time a *tag* is created.
 
-## v1.21.3 (currently main branch)
+## main branch
+
+## v1.25.2
+
+- engine: `Camera::getNear()` and `Camera::getCullingFar()` now return `doubles`
+- Metal: implement scissor support.
+- engine: `Renderer::getUserTime()` now returns seconds as documented (#5722) [⚠️ **API Fix**]
+
+## v1.25.1
+
+- engine: add support for automatic instancing. Must be enabled with `Engine::setAutomaticInstancingEnabled(bool)`
+
+## v1.25.0
+
+- Vulkan: smol-v blobs are now 8-byte aligned within the filamat archive. [⚠️ **Recompile Materials**]
+- backend: added support for EGL on linux (headless)
+- uberz tool: add --append and --template arguments.
+- matc tool: add --template argument.
+
+## v1.24.0
+
+- ImGuiHelper: add support for Y flip.
+- Metal: ignore `MTLTexture` formatting when importing external textures.
+- materials: add a new `instanced` material parameter that is now mandatory in order to call `getInstanceIndex()`
+- gltfio: UbershaderProvider now takes the ubershader archive in its constructor [⚠️ **API Change**]
+- gltfio: Fix morphing with sparse accessors.
+- gltfio: Fix models that use signed integers for morphing.
+- engine: Documentation improvements regarding SkinningBuffer and fix an off-by-one assert when setting a SkinningBuffer.
+- picking is now exposed to JavaScript
+- gltf_viewer: Exercise picking functionality.
+- OpenGL: add WebGL support for ReadPixels
+- Vulkan: add assert and error message for OOM (debug builds)
+- Vulkan: fix crash with picking and 2-component ReadPixels.
+- backend: workaround broken GLES timer query on some Mali-Gxx old drivers
+- backend: revert c049a1 & reenable b2cdf9 ("don't issue a flush systematically after framegraph's execute")
+- gltfio: namespace now lives under Filament [⚠️ **API Change**]
+- gltfio: UbershaderLoader renamed to UbershaderProvider [⚠️ **API Change**]
+- gltfio: MaterialGenerator renamed to JitShaderProvider [⚠️ **API Change**]
+
+## v1.23.2
+
+- gltfio: Fix morphing for un-packed accessors.
+- gltfio: Ubershaders are now packaged into flexible archives.
+- gltfio: Remove poorly maintained lite flavor.
+- engine: Disable user scissor while rendering the Shadow Maps.
+- engine: Merge identical backend `RenderPrimitives` together.
+- engine: Improve `ResourceAllocator` performance a bit by reserving 128 cache entries.
+- utils: Remove `std::hash<T>` definitions for `libutils` types. Use `T::Hasher` explicitly instead. [⚠️ **API Change**]
+- backend: Fix WGL context attributes.
+- Metal: Fix potential invalid shaders when using gltfio in Ubershader mode. [⚠️ **Recompile Materials to get the fix**]
+
+## v1.23.1
+
+- gltfio: support skinning with bones that do not belong to any scene.
+- gltfio: add `attachSkin` / `detachSkin` method to FilamentAsset.
+- gltfio: ubershader mode: set sheen to `OPAQUE`.
+- Metal: fix issues seen with dynamic resolution on M1 Macs.
+- engine: add a "global" mode for render primitive's `blendOrder`.
+- engine: remove `RenderManager::setGeometryAt(index, count)`. [⚠️ **API Change**]
+- engine: fix overallocation by about 17MB.
+- WebGL: Add JS bindings for Texture class methods.
+
+## v1.23.0
+
+- engine: Changed UBOs layout [⚠️ **Material breakage**].
+- engine: Normals on morphed models have been fixed (core Filament change).
+- Java: View has several minor changes due to generated code, such as field ordering.
+- gltfio: Fix crash when reloading glTF assets.
+- gltfio: introduce cross-fade animation API [**NEW API**].
+
+## v1.22.2
+
+- Java: Minor API change: rename `ssctStartTraceDistance` to `ssctShadowDistance`. [⚠️ **API Change**]
+- Java: Minor API change: rename `blendingMode` to `blendMode`. [⚠️ **API Change**]
+- engine: Fix some memory leaks.
+
+## v1.22.1
+
+- Metal: Shaders now use `half` floating-point arithmetic when possible for improved performance. [⚠️ **Recompile Materials**]
+- engine: add support for presentation time in `Renderer`
+- engine: added guard bands support for screen-space effects
+- gltfio: Add multi-scene support.
+- gltfio: Various glTF-related cleanup and enhancements.
+- gltfio: Add support for KHR_texture_basisu.
+
+## v1.22.0
+
+- engine: Changed UBOs layout [⚠️ **Material breakage**].
+- engine: Improve effects relying on mipmapping
+- engine: Fix assert seen with VSM shadows.
+- WebGL: Fix `isTextureFormatSupported` for ETC2 formats.
+
+## v1.21.3
+
+- Java: Renamed the `KTXLoader` Kotlin class to `KTX1Loader`.  [⚠️ **API Change**].
+- libs: Added `Ktx2Reader` and `BasisEncoder` to support Basis-encoded KTX2 files.
+- engine: Remove deprecated `Stream` APIs, see `Texture::import()` for an alternative [⚠️ **API Change**].
+- tools: Removed KTX1 compression support from mipgen.  [⚠️ **API Change**].
+- tools: Added support for KTX2 to mipgen.
+- gltfio: Added `resetBoneMatrices()` method.
+- gltfio: Introduced `TextureProvider` interface.  [⚠️ **API Change**].
+- gltfio: Fix progress indicator when error occurs.
+- samples: Desktop and Web Suzanne samples now use KTX2 instead of KTX1.
+- samples: Fix regression with sample-gltf-viewer and zip files.
 
 ## v1.21.2
 
@@ -453,7 +556,7 @@ devices.
 - engine: Fix RenderTarget NPE when depth is not present.
 - engine: Improvements to Camera APIs. Move focus distance from DofOptions to Camera.
 - engine: VSM shadows now support `shadowMultiplier`.
-- java: Expose severla MaterialInstance APIs (setColorWrite, setDepthWrite, setDepthCulling) that
+- java: Expose several MaterialInstance APIs (setColorWrite, setDepthWrite, setDepthCulling) that
   should have been public.
 - java: fix bug with Texture::setImage buffer size calculation.
 

android/build.gradle

@@ -11,6 +11,9 @@
 // com.google.android.filament.exclude-vulkan
 //     When set, support for Vulkan will be excluded.
 //
+// com.google.android.filament.matdbg
+//     When set, enables matdbg, disables shader optimizations
+//
 // com.google.android.filament.skip-samples
 //     Exclude samples from the project. Useful to speed up compilation.
 //
@@ -59,6 +62,11 @@ buildscript {
             .forUseAtConfigurationTime()
             .isPresent()
 
+    def matdbg = providers
+            .gradleProperty("com.google.android.filament.matdbg")
+            .forUseAtConfigurationTime()
+            .isPresent()
+
     def abis = ["arm64-v8a", "armeabi-v7a", "x86_64", "x86"]
     def newAbis = providers
             .gradleProperty("com.google.android.filament.abis")
@@ -73,10 +81,10 @@ buildscript {
         'minSdk': 19,
         'targetSdk': 31,
         'compileSdk': 31,
-        'kotlin': '1.6.10',
-        'kotlin_coroutines': '1.6.0',
+        'kotlin': '1.6.21',
+        'kotlin_coroutines': '1.6.1',
         'buildTools': '32.0.0',
-        'ndk': '23.1.7779620'
+        'ndk': '24.0.8215888'
     ]
 
     ext.deps = [
@@ -93,22 +101,23 @@ buildscript {
 
     dependencies {
         // NOTE: See TODO in gradle.properties once we move to Gradle 7.4
-        classpath 'com.android.tools.build:gradle:7.1.1'
+        classpath 'com.android.tools.build:gradle:7.2.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 
     ext.cmakeArgs = [
+        "--no-warn-unused-cli",
         "-DANDROID_PIE=ON",
         "-DANDROID_PLATFORM=21",
         "-DANDROID_STL=c++_static",
         "-DFILAMENT_DIST_DIR=${filamentPath}".toString(),
-        "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString()
+        "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString(),
+        "-DFILAMENT_ENABLE_MATDBG=${matdbg ? 'ON' : 'OFF'}".toString(),
+        "-DFILAMENT_DISABLE_MATOPT=${matdbg ? 'ON' : 'OFF'}".toString()
     ]
 
     ext.cppFlags = [
         "-std=c++17",
-        "-Wno-unused-command-line-argument",
-        "-Wl,--hash-style=both", // Required to support API levels below 23
         "-fno-stack-protector",
         "-fno-exceptions",
         "-fno-unwind-tables",
@@ -121,8 +130,13 @@ buildscript {
         "-fomit-frame-pointer",
         "-ffunction-sections",
         "-fdata-sections",
+        "-no-canonical-prefixes",
+        "-Wformat",
+        "-Werror=format-security",
+        "-Wno-unused-command-line-argument",
         "-Wl,--gc-sections",
         "-Wl,-Bsymbolic-functions",
+        "-Wl,--hash-style=both", // Required to support API levels below 23
     ]
 
     ext.abis = abis

android/buildSrc/build.gradle

@@ -1,4 +1,3 @@
-
 plugins {
     id 'groovy-gradle-plugin'
 }

android/filamat-android/build.gradle

@@ -1,4 +1,6 @@
 android {
+    namespace 'com.google.android.filament.filamat'
+
     flavorDimensions "functionality"
     productFlavors {
         full {

android/filament-android/build.gradle

@@ -1,3 +1,7 @@
+android {
+    namespace 'com.google.android.filament'
+}
+
 dependencies {
     implementation deps.androidx.annotations
 }

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

@@ -84,13 +84,13 @@ Java_com_google_android_filament_Camera_nLookAt(JNIEnv*, jclass, jlong nativeCam
     camera->lookAt({eye_x, eye_y, eye_z}, {center_x, center_y, center_z}, {up_x, up_y, up_z});
 }
 
-extern "C" JNIEXPORT jfloat JNICALL
+extern "C" JNIEXPORT jdouble JNICALL
 Java_com_google_android_filament_Camera_nGetNear(JNIEnv*, jclass, jlong nativeCamera) {
     Camera *camera = (Camera *) nativeCamera;
     return camera->getNear();
 }
 
-extern "C" JNIEXPORT jfloat JNICALL
+extern "C" JNIEXPORT jdouble JNICALL
 Java_com_google_android_filament_Camera_nGetCullingFar(JNIEnv*, jclass,
         jlong nativeCamera) {
     Camera *camera = (Camera *) nativeCamera;

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

@@ -316,3 +316,15 @@ Java_com_google_android_filament_Engine_nGetEntityManager(JNIEnv*, jclass, jlong
     Engine* engine = (Engine*) nativeEngine;
     return (jlong) &engine->getEntityManager();
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nSetAutomaticInstancingEnabled(JNIEnv*, jclass, jlong nativeEngine, jboolean enable) {
+    Engine* engine = (Engine*) nativeEngine;
+    engine->setAutomaticInstancingEnabled(enable);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsAutomaticInstancingEnabled(JNIEnv*, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jboolean)engine->isAutomaticInstancingEnabled();
+}

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

@@ -120,6 +120,14 @@ Java_com_google_android_filament_RenderableManager_nBuilderBlendOrder(JNIEnv*, j
     builder->blendOrder((size_t) index, (uint16_t) blendOrder);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nBuilderGlobalBlendOrderEnabled(JNIEnv*, jclass,
+        jlong nativeBuilder, jint index, jboolean enabled) {
+    RenderableManager::Builder *builder = (RenderableManager::Builder *) nativeBuilder;
+    builder->globalBlendOrderEnabled((size_t) index, (bool) enabled);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nBuilderBoundingBox(JNIEnv*, jclass,
         jlong nativeBuilder, jfloat cx, jfloat cy, jfloat cz, jfloat ex, jfloat ey, jfloat ez) {
@@ -422,15 +430,6 @@ Java_com_google_android_filament_RenderableManager_nSetGeometryAt__JIIIJJII(JNIE
             (size_t) offset, (size_t) count);
 }
 
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_RenderableManager_nSetGeometryAt__JIIIII(JNIEnv*, jclass,
-        jlong nativeRenderableManager, jint i, jint primitiveIndex, jint primitiveType, jint offset,
-        jint count) {
-    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
-    rm->setGeometryAt((RenderableManager::Instance) i, (size_t) primitiveIndex,
-            (RenderableManager::PrimitiveType) primitiveType, (size_t) offset, (size_t) count);
-}
-
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_RenderableManager_nSetBlendOrderAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex, jint blendOrder) {
@@ -439,6 +438,14 @@ Java_com_google_android_filament_RenderableManager_nSetBlendOrderAt(JNIEnv*, jcl
             (uint16_t) blendOrder);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nSetGlobalBlendOrderEnabledAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex, jboolean enabled) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    rm->setGlobalBlendOrderEnabledAt((RenderableManager::Instance) i, (size_t) primitiveIndex,
+            (bool) enabled);
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_RenderableManager_nGetEnabledAttributesAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex) {

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

@@ -156,12 +156,9 @@ Java_com_google_android_filament_Renderer_nResetUserTime(JNIEnv*, jclass, jlong
 }
 
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_Renderer_nSetDisplayInfo(JNIEnv*, jclass, jlong nativeRenderer,
-        jfloat refreshRate, jlong presentationDeadlineNanos, jlong vsyncOffsetNanos) {
+Java_com_google_android_filament_Renderer_nSetDisplayInfo(JNIEnv*, jclass, jlong nativeRenderer, jfloat refreshRate) {
     Renderer *renderer = (Renderer *) nativeRenderer;
-    renderer->setDisplayInfo({ .refreshRate = refreshRate,
-                               .presentationDeadlineNanos = (uint64_t)presentationDeadlineNanos,
-                               .vsyncOffsetNanos = (uint64_t)vsyncOffsetNanos });
+    renderer->setDisplayInfo({ .refreshRate = refreshRate });
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -183,3 +180,10 @@ Java_com_google_android_filament_Renderer_nSetClearOptions(JNIEnv *, jclass ,
                                 .clear = (bool) clear,
                                 .discard = (bool) discard});
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Renderer_nSetPresentationTime(JNIEnv *, jclass ,
+    jlong nativeRenderer, jlong monotonicClockNanos) {
+    Renderer *renderer = (Renderer *) nativeRenderer;
+    renderer->setPresentationTime(monotonicClockNanos);
+}

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

@@ -98,16 +98,6 @@ Java_com_google_android_filament_Stream_nBuilderStreamSource(JNIEnv* env,
     builder->setStreamSource(env, streamSource);
 }
 
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_Stream_nBuilderStream(JNIEnv*, jclass,
-        jlong nativeStreamBuilder, jlong externalTextureId) {
-    StreamBuilder* builder = (StreamBuilder*) nativeStreamBuilder;
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-declarations"
-    builder->builder()->stream(externalTextureId);
-#pragma clang diagnostic pop
-}
-
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Stream_nBuilderWidth(JNIEnv*, jclass,
         jlong nativeStreamBuilder, jint width) {
@@ -143,41 +133,6 @@ Java_com_google_android_filament_Stream_nSetDimensions(JNIEnv*, jclass, jlong na
     stream->setDimensions((uint32_t) width, (uint32_t) height);
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_Stream_nReadPixels(JNIEnv *env, jclass,
-        jlong nativeStream, jlong nativeEngine,
-        jint xoffset, jint yoffset, jint width, jint height,
-        jobject storage, jint remaining,
-        jint left, jint top, jint type, jint alignment, jint stride, jint format,
-        jobject handler, jobject runnable) {
-    Stream *stream = (Stream *) nativeStream;
-    Engine *engine = (Engine *) nativeEngine;
-
-    stride = stride ? stride : width;
-    size_t sizeInBytes = PixelBufferDescriptor::computeDataSize(
-            (PixelDataFormat) format, (PixelDataType) type,
-            (size_t) stride, (size_t) (height + top), (size_t) alignment);
-
-    AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (remaining << nioBuffer.getShift())) {
-        // BufferOverflowException
-        return -1;
-    }
-
-    void *buffer = nioBuffer.getData();
-    auto *callback = JniBufferCallback::make(engine, env, handler, runnable, std::move(nioBuffer));
-
-    PixelBufferDescriptor desc(buffer, sizeInBytes, (backend::PixelDataFormat) format,
-            (backend::PixelDataType) type, (uint8_t) alignment, (uint32_t) left, (uint32_t) top,
-            (uint32_t) stride,
-            callback->getHandler(), &JniBufferCallback::postToJavaAndDestroy, callback);
-
-    stream->readPixels(uint32_t(xoffset), uint32_t(yoffset), uint32_t(width), uint32_t(height),
-            std::move(desc));
-
-    return 0;
-}
-
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Stream_nGetTimestamp(JNIEnv*, jclass, jlong nativeStream) {
     Stream *stream = (Stream *) nativeStream;

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

@@ -259,14 +259,14 @@ Java_com_google_android_filament_View_nSetAmbientOcclusionOptions(JNIEnv*, jclas
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetSSCTOptions(JNIEnv *, jclass, jlong nativeView,
-        jfloat ssctLightConeRad, jfloat ssctStartTraceDistance, jfloat ssctContactDistanceMax,
+        jfloat ssctLightConeRad, jfloat ssctShadowDistance, jfloat ssctContactDistanceMax,
         jfloat ssctIntensity, jfloat ssctLightDirX, jfloat ssctLightDirY, jfloat ssctLightDirZ,
         jfloat ssctDepthBias, jfloat ssctDepthSlopeBias, jint ssctSampleCount,
         jint ssctRayCount, jboolean ssctEnabled) {
     View* view = (View*) nativeView;
     View::AmbientOcclusionOptions options = view->getAmbientOcclusionOptions();
     options.ssct.lightConeRad = ssctLightConeRad;
-    options.ssct.shadowDistance = ssctStartTraceDistance;
+    options.ssct.shadowDistance = ssctShadowDistance;
     options.ssct.contactDistanceMax = ssctContactDistanceMax;
     options.ssct.intensity = ssctIntensity;
     options.ssct.lightDirection = math::float3{ ssctLightDirX, ssctLightDirY, ssctLightDirZ };
@@ -461,3 +461,11 @@ Java_com_google_android_filament_View_nPick(JNIEnv* env, jclass,
         JniCallback::postToJavaAndDestroy(callback);
     }, callback->getHandler());
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,
+        jlong nativeView, jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setGuardBandOptions({ .enabled = (bool)enabled });
+}

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

@@ -400,7 +400,7 @@ public class Camera {
     }
 
     /**
-     * Sets the camera's view matrix.
+     * Sets the camera's model matrix.
      * <p>
      * Helper method to set the camera's entity transform component.
      * Remember that the Camera "looks" towards its -z axis.
@@ -412,29 +412,29 @@ public class Camera {
      *          engine.getTransformManager().getInstance(camera->getEntity()), viewMatrix);
      * </pre>
      *
-     * @param viewMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.
+     * @param modelMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.
      */
-    public void setModelMatrix(@NonNull @Size(min = 16) float[] viewMatrix) {
-        Asserts.assertMat4fIn(viewMatrix);
-        nSetModelMatrix(getNativeObject(), viewMatrix);
+    public void setModelMatrix(@NonNull @Size(min = 16) float[] modelMatrix) {
+        Asserts.assertMat4fIn(modelMatrix);
+        nSetModelMatrix(getNativeObject(), modelMatrix);
     }
 
     /**
-     * Sets the camera's view matrix.
+     * Sets the camera's model matrix.
      * <p>
      * Helper method to set the camera's entity transform component.
      * Remember that the Camera "looks" towards its -z axis.
      * <p>
      *
-     * @param viewMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.
+     * @param modelMatrix The camera position and orientation provided as a <b>rigid transform</b> matrix.
      */
-    public void setModelMatrix(@NonNull @Size(min = 16) double[] viewMatrix) {
-        Asserts.assertMat4In(viewMatrix);
-        nSetModelMatrixFp64(getNativeObject(), viewMatrix);
+    public void setModelMatrix(@NonNull @Size(min = 16) double[] modelMatrix) {
+        Asserts.assertMat4In(modelMatrix);
+        nSetModelMatrixFp64(getNativeObject(), modelMatrix);
     }
 
     /**
-     * Sets the camera's view matrix.
+     * Sets the camera's model matrix.
      *
      * @param eyeX      x-axis position of the camera in world space
      * @param eyeY      y-axis position of the camera in world space
@@ -456,7 +456,7 @@ public class Camera {
      * @return Distance to the near plane
      */
     public float getNear() {
-        return nGetNear(getNativeObject());
+        return (float)nGetNear(getNativeObject());
     }
 
     /**
@@ -464,7 +464,7 @@ public class Camera {
      * @return Distance to the far plane
      */
     public float getCullingFar() {
-        return nGetCullingFar(getNativeObject());
+        return (float)nGetCullingFar(getNativeObject());
     }
 
     /**
@@ -549,10 +549,10 @@ public class Camera {
     /**
      * Retrieves the camera's view matrix. The view matrix is the inverse of the model matrix.
      *
-     * @param out A 16-float array where the model view will be stored, or null in which
+     * @param out A 16-float array where the view matrix will be stored, or null in which
      *            case a new array is allocated.
      *
-     * @return A 16-float array containing the camera's view as a column-major matrix.
+     * @return A 16-float array containing the camera's column-major view matrix.
      */
     @NonNull @Size(min = 16)
     public float[] getViewMatrix(@Nullable @Size(min = 16) float[] out) {
@@ -567,7 +567,7 @@ public class Camera {
      * @param out A 16-double array where the model view will be stored, or null in which
      *            case a new array is allocated.
      *
-     * @return A 16-double array containing the camera's view as a column-major matrix.
+     * @return A 16-double array containing the camera's column-major view matrix.
      */
     @NonNull @Size(min = 16)
     public double[] getViewMatrix(@Nullable @Size(min = 16) double[] out) {
@@ -787,8 +787,8 @@ public class Camera {
     private static native void nSetModelMatrix(long nativeCamera, float[] in);
     private static native void nSetModelMatrixFp64(long nativeCamera, double[] in);
     private static native void nLookAt(long nativeCamera, double eyeX, double eyeY, double eyeZ, double centerX, double centerY, double centerZ, double upX, double upY, double upZ);
-    private static native float nGetNear(long nativeCamera);
-    private static native float nGetCullingFar(long nativeCamera);
+    private static native double nGetNear(long nativeCamera);
+    private static native double nGetCullingFar(long nativeCamera);
     private static native void nGetProjectionMatrix(long nativeCamera, double[] out);
     private static native void nGetCullingProjectionMatrix(long nativeCamera, double[] out);
     private static native void nGetScaling(long nativeCamera, double[] out);

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

@@ -258,6 +258,44 @@ public class Engine {
         return sBackendValues[(int) nGetBackend(getNativeObject())];
     }
 
+    /**
+     * Helper to enable accurate translations.
+     * If you need this Engine to handle a very large world space, one way to achieve this
+     * automatically is to enable accurate translations in the TransformManager. This helper
+     * provides a convenient way of doing that.
+     * This is typically called once just after creating the Engine.
+     */
+    public void enableAccurateTranslations() {
+        getTransformManager().setAccurateTranslationsEnabled(true);
+    }
+
+    /**
+     * 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
+     * (i.e. use the same geometry) and use the same MaterialInstance. If it is known that the
+     * scene doesn't contain any identical primitives, automatic instancing can have some
+     * overhead and it is then best to disable it.
+     *
+     * Disabled by default.
+     *
+     * @param enable true to enable, false to disable automatic instancing.
+     *
+     * @see RenderableManager
+     * @see MaterialInstance
+     */
+    public void setAutomaticInstancingEnabled(boolean enable) {
+        nSetAutomaticInstancingEnabled(getNativeObject(), enable);
+    }
+
+    /**
+     * @return true if automatic instancing is enabled, false otherwise.
+     * @see setAutomaticInstancingEnabled
+     */
+    public boolean isAutomaticInstancingEnabled() {
+        return nIsAutomaticInstancingEnabled(getNativeObject());
+    }
+
+
     // SwapChain
 
     /**
@@ -593,8 +631,11 @@ public class Engine {
     }
 
     /**
-     * Destroys an <code>entity</code> and all its components.
+     * Destroys all Filament-known components from this <code>entity</code>.
      * <p>
+     * This method destroys Filament components only, not the <code>entity</code> itself. To destroy
+     * the <code>entity</code> use <code>EntityManager#destroy</code>.
+     *
      * It is recommended to destroy components individually before destroying their
      * <code>entity</code>, this gives more control as to when the destruction really happens.
      * Otherwise, orphaned components are garbage collected, which can happen at a later time.
@@ -717,4 +758,6 @@ public class Engine {
     private static native long nGetRenderableManager(long nativeEngine);
     private static native long nGetJobSystem(long nativeEngine);
     private static native long nGetEntityManager(long nativeEngine);
+    private static native void nSetAutomaticInstancingEnabled(long nativeEngine, boolean enable);
+    private static native boolean nIsAutomaticInstancingEnabled(long nativeEngine);
 }

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

@@ -104,12 +104,12 @@ public class MorphTargetBuffer {
     }
 
     /**
-     * Updates positions of morph target at the index.
+     * Updates float4 positions for the given morph target.
      *
      * @param engine {@link Engine} instance
      * @param targetIndex The index of morph target to be updated
-     * @param positions Pointer to at least count positions
-     * @param count Number of position elements in positions
+     * @param positions An array with at least count*4 floats
+     * @param count Number of float4 vectors in positions to be consumed
      */
     public void setPositionsAt(@NonNull Engine engine,
             @IntRange(from = 0) int targetIndex,
@@ -122,12 +122,15 @@ public class MorphTargetBuffer {
     }
 
     /**
-     * Updates tangents of morph target at the index.
+     * Updates tangents for the given morph target.
+     *
+     * These quaternions must be represented as signed shorts, where real numbers in the [-1,+1]
+     * range multiplied by 32767.
      *
      * @param engine {@link Engine} instance
      * @param targetIndex The index of morph target to be updated
-     * @param tangents Pointer to at least count tangents
-     * @param count Number of tangent elements in tangents
+     * @param tangents An array with at least "count*4" shorts
+     * @param count number of short4 quaternions in tangents
      */
     public void setTangentsAt(@NonNull Engine engine,
             @IntRange(from = 0) int targetIndex,
@@ -140,14 +143,14 @@ public class MorphTargetBuffer {
     }
 
     /**
-     * @return number of vertex count in this {@link MorphTargetBuffer}
+     * @return number of vertices in this {@link MorphTargetBuffer}
      */
     public int getVertexCount() {
         return nGetVertexCount(mNativeObject);
     }
 
     /**
-     * @return number of target count in this {@link MorphTargetBuffer}
+     * @return number of morph targets in this {@link MorphTargetBuffer}
      */
     public int getCount() {
         return nGetCount(mNativeObject);

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

@@ -191,7 +191,9 @@ public class RenderableManager {
         }
 
         /**
-         * Sets an ordering index for blended primitives that all live at the same Z value.
+         * Sets the drawing order for blended primitives. The drawing order is either global or
+         * local (default) to this Renderable. In either case, the Renderable priority takes
+         * precedence.
          *
          * @param index the primitive of interest
          * @param blendOrder draw order number (0 by default). Only the lowest 15 bits are used.
@@ -203,6 +205,18 @@ public class RenderableManager {
             return this;
         }
 
+       /**
+         * Sets whether the blend order is global or local to this Renderable (by default).
+         *
+         * @param index the primitive of interest
+         * @param enabled true for global, false for local blend ordering.
+         */
+        @NonNull
+        public Builder globalBlendOrderEnabled(@IntRange(from = 0) int index, boolean enabled) {
+            nBuilderGlobalBlendOrderEnabled(mNativeBuilder, index, enabled);
+            return this;
+        }
+
         /**
          * The axis-aligned bounding box of the renderable.
          *
@@ -792,18 +806,9 @@ public class RenderableManager {
                 0, indices.getIndexCount());
     }
 
-    /**
-     * Changes the geometry for the given primitive.
-     *
-     * @see Builder#geometry Builder.geometry
-     */
-    public void setGeometryAt(@EntityInstance int i, @IntRange(from = 0) int primitiveIndex,
-            @NonNull PrimitiveType type, @IntRange(from = 0) int offset, @IntRange(from = 0) int count) {
-        nSetGeometryAt(mNativeObject, i, primitiveIndex, type.getValue(), offset, count);
-    }
-
-    /**
-     * Changes the ordering index for blended primitives that all live at the same Z value.
+     /**
+     * Changes the drawing order for blended primitives. The drawing order is either global or
+     * local (default) to this Renderable. In either case, the Renderable priority takes precedence.
      *
      * @see Builder#blendOrder
      *
@@ -816,6 +821,20 @@ public class RenderableManager {
         nSetBlendOrderAt(mNativeObject, instance, primitiveIndex, blendOrder);
     }
 
+    /**
+     * Changes whether the blend order is global or local to this Renderable (by default).
+     *
+     * @see Builder#globalBlendOrderEnabled
+     *
+     * @param instance the renderable of interest
+     * @param primitiveIndex the primitive of interest
+     * @param enabled true for global, false for local blend ordering.
+     */
+    public void setGlobalBlendOrderEnabledAt(@EntityInstance int instance, @IntRange(from = 0) int primitiveIndex,
+            boolean enabled) {
+        nSetGlobalBlendOrderEnabledAt(mNativeObject, instance, primitiveIndex, enabled);
+    }
+
     /**
      * Retrieves the set of enabled attribute slots in the given primitive's VertexBuffer.
      */
@@ -853,6 +872,7 @@ public class RenderableManager {
     private static native void nBuilderGeometry(long nativeBuilder, int index, int value, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int minIndex, int maxIndex, int count);
     private static native void nBuilderMaterial(long nativeBuilder, int index, long nativeMaterialInstance);
     private static native void nBuilderBlendOrder(long nativeBuilder, int index, int blendOrder);
+    private static native void nBuilderGlobalBlendOrderEnabled(long nativeBuilder, int index, boolean enabled);
     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);
@@ -891,7 +911,7 @@ public class RenderableManager {
     private static native void nSetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex, long nativeMaterialInstance);
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
-    private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, int offset, int count);
     private static native void nSetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex, int blendOrder);
+    private static native void nSetGlobalBlendOrderEnabledAt(long nativeRenderableManager, int i, int primitiveIndex, boolean enabled);
     private static native int nGetEnabledAttributesAt(long nativeRenderableManager, int i, int primitiveIndex);
 }

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

@@ -61,13 +61,17 @@ public class Renderer {
         /**
          * How far in advance a buffer must be queued for presentation at a given time in ns
          * On Android you can use {@link android.view.Display#getPresentationDeadlineNanos()}.
+         * @deprecated this value is ignored
          */
+        @Deprecated
         public long presentationDeadlineNanos = 0;
 
         /**
          * Offset by which vsyncSteadyClockTimeNano provided in beginFrame() is offset in ns
          * On Android you can use {@link android.view.Display#getAppVsyncOffsetNanos()}.
+         * @deprecated this value is ignored
          */
+        @Deprecated
         public long vsyncOffsetNanos = 0;
     };
 
@@ -175,8 +179,7 @@ public class Renderer {
      */
     public void setDisplayInfo(@NonNull DisplayInfo info) {
         mDisplayInfo = info;
-        nSetDisplayInfo(getNativeObject(),
-                info.refreshRate, info.presentationDeadlineNanos, info.vsyncOffsetNanos);
+        nSetDisplayInfo(getNativeObject(), info.refreshRate);
     }
 
     /**
@@ -247,6 +250,23 @@ public class Renderer {
         return mEngine;
     }
 
+    /**
+     * Set the time at which the frame must be presented to the display.
+     * <p>
+     * This must be called between {@link #beginFrame} and {@link #endFrame}.
+     * </p>
+     *
+     * @param monotonicClockNanos  The time in nanoseconds corresponding to the system monotonic
+     *                             up-time clock. The presentation time is typically set in the
+     *                             middle of the period of interest and cannot be too far in the
+     *                             future as it is limited by how many buffers are available in
+     *                             the display sub-system. Typically it is set to 1 or 2 vsync
+     *                             periods away.
+     */
+    public void setPresentationTime(long monotonicClockNanos) {
+        nSetPresentationTime(getNativeObject(), monotonicClockNanos);
+    }
+
     /**
      * Sets up a frame for this <code>Renderer</code>.
      * <p><code>beginFrame</code> manages frame pacing, and returns whether or not a frame should be
@@ -531,6 +551,10 @@ public class Renderer {
      * Typically, this will happen after multiple calls to {@link #beginFrame},
      * {@link #render}, {@link #endFrame}.</p>
      * <br>
+     * <p>OpenGL only: if issuing a <code>readPixels</code> on a {@link RenderTarget} backed by a
+     * {@link Texture} that had data uploaded to it via {@link Texture#setImage}, the data returned
+     * from <code>readPixels</code> will be y-flipped with respect to the {@link Texture#setImage}
+     * call.</p>
      * <p><code>readPixels</code> is intended for debugging and testing.
      * It will impact performance significantly.</p>
      *
@@ -660,6 +684,7 @@ public class Renderer {
         mNativeObject = 0;
     }
 
+    private static native void nSetPresentationTime(long nativeObject, long monotonicClockNanos);
     private static native boolean nBeginFrame(long nativeRenderer, long nativeSwapChain, long frameTimeNanos);
     private static native void nEndFrame(long nativeRenderer);
     private static native void nRender(long nativeRenderer, long nativeView);
@@ -681,8 +706,7 @@ public class Renderer {
             Object handler, Runnable callback);
     private static native double nGetUserTime(long nativeRenderer);
     private static native void nResetUserTime(long nativeRenderer);
-    private static native void nSetDisplayInfo(long nativeRenderer,
-            float refreshRate, long presentationDeadlineNanos, long vsyncOffsetNanos);
+    private static native void nSetDisplayInfo(long nativeRenderer, float refreshRate);
     private static native void nSetFrameRateOptions(long nativeRenderer,
             float interval, float headRoomRatio, float scaleRate, int history);
     private static native void nSetClearOptions(long nativeRenderer,

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

@@ -103,9 +103,6 @@ public class Stream {
         /** Not synchronized but copy-free. Good for video. */
         NATIVE,
 
-        /** Synchronized, but GL-only and incurs copies. Good for AR on devices before API 26. */
-        TEXTURE_ID,
-
         /** Synchronized, copy-free, and take a release callback. Good for AR but requires API 26+. */
         ACQUIRED,
     };
@@ -121,7 +118,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} or {@link StreamType#TEXTURE_ID TEXTURE_ID} stream, call one of the <pre>stream</pre> methods
+     * To create a {@link StreamType#NATIVE NATIVE} stream, call one of the <pre>stream</pre> methods
      * on the builder.
      */
     public static class Builder {
@@ -156,27 +153,6 @@ public class Stream {
             throw new IllegalArgumentException("Invalid stream source: " + streamSource);
         }
 
-        /**
-         * Creates a {@link StreamType#TEXTURE_ID TEXTURE_ID} stream. A copy stream will sample data from the supplied
-         * external texture and copy it into an internal private texture.
-         *
-         * <p>Currently only OpenGL external texture ids are supported.</p>
-         *
-         * @param externalTextureId An opaque texture id (typically a GLuint created with
-         *                          <code>glGenTextures()</code>) in a context shared with
-         *                          filament -- in that case this texture's target must be
-         *                          <code>GL_TEXTURE_EXTERNAL_OES.</code>
-         * @return This Builder, for chaining calls.
-         * @see Texture#setExternalStream
-         * @deprecated this method existed only for ARCore which doesn't need this anymore, use {@link Texture.Builder#importTexture(long)} instead.
-         */
-        @Deprecated
-        @NonNull
-        public Builder stream(long externalTextureId) {
-            nBuilderStream(mNativeBuilder, externalTextureId);
-            return this;
-        }
-
         /**
          * @param width initial width of the incoming stream. Whether this value is used is
          *              stream dependent. On Android, it must be set when using
@@ -276,92 +252,6 @@ public class Stream {
         nSetDimensions(getNativeObject(), width, height);
     }
 
-    /**
-     * Reads back the content of the last frame of a <code>Stream</code> since the last call to
-     * {@link Renderer#beginFrame}.
-     *
-     * <p>The Stream must be a copy stream, which can be checked with {@link #getStreamType()}.
-     * This function is a no-op otherwise.</p>
-     *
-     * <pre>
-     *
-     *  Stream buffer                  User buffer (PixelBufferDescriptor)
-     *  +--------------------+
-     *  |                    |                .stride         .alignment
-     *  |                    |         ----------------------->-->
-     *  |                    |         O----------------------+--+   low addresses
-     *  |                    |         |          |           |  |
-     *  |             w      |         |          | .top      |  |
-     *  |       <--------->  |         |          V           |  |
-     *  |       +---------+  |         |     +---------+      |  |
-     *  |       |     ^   |  | ======> |     |         |      |  |
-     *  |   x   |    h|   |  |         |.left|         |      |  |
-     *  +------>|     v   |  |         +---->|         |      |  |
-     *  |       +.........+  |         |     +.........+      |  |
-     *  |            ^       |         |                      |  |
-     *  |          y |       |         +----------------------+--+  high addresses
-     *  O------------+-------+
-     *
-     * </pre>
-     *
-     * <p>Typically readPixels() will be called after {@link Renderer#beginFrame}.</p>
-     *
-     * <p>After calling this method, the callback associated with <code>buffer</code>
-     * will be invoked on the main thread, indicating that the read-back has completed.
-     * Typically, this will happen after multiple calls to {@link Renderer#beginFrame},
-     * {@link Renderer#render}, {@link Renderer#endFrame}.</p>
-     *
-     * <p><code>readPixels</code> is intended for debugging and testing.
-     * It will impact performance significantly.</p>
-     *
-     * @param xoffset   left offset of the sub-region to read back
-     * @param yoffset   bottom offset of the sub-region to read back
-     * @param width     width of the sub-region to read back
-     * @param height    height of the sub-region to read back
-     * @param buffer    client-side buffer where the read-back will be written
-     *
-     *                  <p>
-     *                  The following format are always supported:
-     *                      <li>{@link Texture.Format#RGBA}</li>
-     *                      <li>{@link Texture.Format#RGBA_INTEGER}</li>
-     *                  </p>
-     *
-     *                  <p>
-     *                  The following types are always supported:
-     *                      <li>{@link Texture.Type#UBYTE}</li>
-     *                      <li>{@link Texture.Type#UINT}</li>
-     *                      <li>{@link Texture.Type#INT}</li>
-     *                      <li>{@link Texture.Type#FLOAT}</li>
-     *                  </p>
-     *
-     *                  <p>Other combination of format/type may be supported. If a combination is
-     *                  not supported, this operation may fail silently. Use a DEBUG build
-     *                  to get some logs about the failure.</p>
-     *
-     * @exception BufferOverflowException if the specified parameters would result in reading
-     * outside of <code>buffer</code>.
-     */
-    public void readPixels(
-            @IntRange(from = 0) int xoffset, @IntRange(from = 0) int yoffset,
-            @IntRange(from = 0) int width, @IntRange(from = 0) int height,
-            @NonNull Texture.PixelBufferDescriptor buffer) {
-
-        if (buffer.storage.isReadOnly()) {
-            throw new ReadOnlyBufferException();
-        }
-
-        int result = nReadPixels(getNativeObject(), mNativeEngine,
-                xoffset, yoffset, width, height,
-                buffer.storage, buffer.storage.remaining(),
-                buffer.left, buffer.top, buffer.type.ordinal(), buffer.alignment,
-                buffer.stride, buffer.format.ordinal(),
-                buffer.handler, buffer.callback);
-
-        if (result < 0) {
-            throw new BufferOverflowException();
-        }
-    }
-
     /**
      * Returns the presentation time of the currently displayed frame in nanosecond.
      *
@@ -387,7 +277,6 @@ public class Stream {
     private static native long nCreateBuilder();
     private static native void nDestroyBuilder(long nativeStreamBuilder);
     private static native void nBuilderStreamSource(long nativeStreamBuilder, Object streamSource);
-    private static native void nBuilderStream(long nativeStreamBuilder, long externalTextureId);
     private static native void nBuilderWidth(long nativeStreamBuilder, int width);
     private static native void nBuilderHeight(long nativeStreamBuilder, int height);
     private static native long nBuilderBuild(long nativeStreamBuilder, long nativeEngine);

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

@@ -157,8 +157,6 @@ public class DisplayHelper {
             info = new Renderer.DisplayInfo();
         }
         info.refreshRate = DisplayHelper.getRefreshRate(display);
-        info.presentationDeadlineNanos = DisplayHelper.getPresentationDeadlineNanos(display);
-        info.vsyncOffsetNanos = DisplayHelper.getAppVsyncOffsetNanos(display);
         return info;
     }
 

android/filament-utils-android/build.gradle

@@ -1,6 +1,8 @@
 apply plugin: 'kotlin-android'
 
 android {
+    namespace 'com.google.android.filament.utils'
+
     sourceSets {
         main {
             kotlin.srcDirs += "src/main/java"
@@ -10,14 +12,14 @@ android {
     defaultConfig {
         missingDimensionStrategy 'functionality', 'full'
     }
-
-    // No need to package up the following shared libs, which arise as a side effect of our
-    // externalNativeBuild dependencies. When clients pick and choose from project-level gradle
-    // dependencies, these shared libs already get pulled in, so we need to avoid the error:
-    // "More than one file was found with OS independent path ..."
     packagingOptions {
-        exclude 'lib/*/libfilament-jni.so'
-        exclude 'lib/*/libgltfio-jni.so'
+        // No need to package up the following shared libs, which arise as a side effect of our
+        // externalNativeBuild dependencies. When clients pick and choose from project-level gradle
+        // dependencies, these shared libs already get pulled in, so we need to avoid the error:
+        // "More than one file was found with OS independent path ..."
+        jniLibs {
+            excludes += ['lib/*/libfilament-jni.so', 'lib/*/libgltfio-jni.so']
+        }
     }
 }
 

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

@@ -169,6 +169,7 @@ Java_com_google_android_filament_utils_AutomationEngine_nGetViewerOptions(JNIEnv
     const jfieldID cameraFocalLength = env->GetFieldID(klass, "cameraFocalLength", "F");
     const jfieldID cameraFocusDistance = env->GetFieldID(klass, "cameraFocusDistance", "F");
     const jfieldID autoScaleEnabled = env->GetFieldID(klass, "autoScaleEnabled", "Z");
+    const jfieldID autoInstancingEnabled = env->GetFieldID(klass, "autoInstancingEnabled", "Z");
 
     env->SetFloatField(result, cameraAperture, options.cameraAperture);
     env->SetFloatField(result, cameraSpeed, options.cameraSpeed);
@@ -179,6 +180,7 @@ Java_com_google_android_filament_utils_AutomationEngine_nGetViewerOptions(JNIEnv
     env->SetFloatField(result, cameraFocalLength, options.cameraFocalLength);
     env->SetFloatField(result, cameraFocusDistance, options.cameraFocusDistance);
     env->SetBooleanField(result, autoScaleEnabled, options.autoScaleEnabled);
+    env->SetBooleanField(result, autoInstancingEnabled, options.autoInstancingEnabled);
 }
 
 extern "C" JNIEXPORT jlong JNICALL

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

@@ -99,8 +99,8 @@ JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void*) {
 
     int rc;
 
-    // KTXLoader
-    jclass ktxloaderClass = env->FindClass("com/google/android/filament/utils/KTXLoader");
+    // KTX1Loader
+    jclass ktxloaderClass = env->FindClass("com/google/android/filament/utils/KTX1Loader");
     if (ktxloaderClass == nullptr) return JNI_ERR;
     static const JNINativeMethod ktxMethods[] = {
         {(char*)"nCreateKTXTexture", (char*)"(JLjava/nio/Buffer;IZ)J", reinterpret_cast<void*>(nCreateKTXTexture)},

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

@@ -40,7 +40,7 @@ import com.google.android.filament.Renderer;
  *
  * When executing a test, clients should call tick() after each frame is rendered, which provides an
  * opportunity to push settings to Filament, increment the current test index (if enough time has
- * elapsed), and request an asychronous screenshot.
+ * elapsed), and request an asynchronous screenshot.
  *
  * The time to sleep between tests is configurable and can be set to zero. Automation also waits a
  * specified minimum number of frames between tests.
@@ -103,6 +103,7 @@ public class AutomationEngine {
         public float cameraFocalLength = 28.0f;
         public float cameraFocusDistance = 0.0f;
         public boolean autoScaleEnabled = true;
+        public boolean autoInstancingEnabled = false;
     }
 
     /**

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

@@ -24,12 +24,12 @@ import com.google.android.filament.Texture
 import java.nio.Buffer
 
 /**
- * Utilities for consuming KTX files and producing Filament textures, IBLs, and sky boxes.
+ * Utilities for consuming KTX1 files and producing Filament textures, IBLs, and sky boxes.
  *
  * KTX is a simple container format that makes it easy to bundle miplevels and cubemap faces
  * into a single file.
  */
-object KTXLoader {
+object KTX1Loader {
     class Options {
         var srgb = false
     }

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

@@ -114,7 +114,7 @@ class ModelViewer(
         view.scene = scene
         view.camera = camera
 
-        materialProvider = UbershaderLoader(engine)
+        materialProvider = UbershaderProvider(engine)
         assetLoader = AssetLoader(engine, materialProvider, EntityManager.get())
         resourceLoader = ResourceLoader(engine, normalizeSkinningWeights, recomputeBoundingBoxes, ignoreBindTransform)
 

android/gltfio-android/CMakeLists.txt

@@ -11,49 +11,72 @@ add_library(dracodec STATIC IMPORTED)
 set_target_properties(dracodec PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libdracodec.a)
 
+add_library(ktxreader STATIC IMPORTED)
+set_target_properties(ktxreader PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libktxreader.a)
+
+add_library(stb STATIC IMPORTED)
+set_target_properties(stb PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libstb.a)
+
+add_library(basis_transcoder STATIC IMPORTED)
+set_target_properties(basis_transcoder PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libbasis_transcoder.a)
+
+add_library(zstd STATIC IMPORTED)
+set_target_properties(zstd PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libzstd.a)
+
 add_library(utils STATIC IMPORTED)
 set_target_properties(utils PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libutils.a)
 
-add_library(gltfio_resources STATIC IMPORTED)
-set_target_properties(gltfio_resources PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libgltfio_resources.a)
+add_library(uberzlib STATIC IMPORTED)
+set_target_properties(uberzlib PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberzlib.a)
 
-add_library(gltfio_resources_lite STATIC IMPORTED)
-set_target_properties(gltfio_resources_lite PROPERTIES IMPORTED_LOCATION
-        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libgltfio_resources_lite.a)
+add_library(uberarchive STATIC IMPORTED)
+set_target_properties(uberarchive PROPERTIES IMPORTED_LOCATION
+        ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberarchive.a)
 
 set(CMAKE_SHARED_LINKER_FLAGS_RELEASE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} -Wl,--version-script=${CMAKE_CURRENT_SOURCE_DIR}/libgltfio-jni.map")
 
 set(GLTFIO_SRCS
         ${GLTFIO_DIR}/include/gltfio/Animator.h
         ${GLTFIO_DIR}/include/gltfio/AssetLoader.h
-        ${GLTFIO_DIR}/include/gltfio/MaterialProvider.h
-        ${GLTFIO_DIR}/include/gltfio/ResourceLoader.h
         ${GLTFIO_DIR}/include/gltfio/FilamentAsset.h
         ${GLTFIO_DIR}/include/gltfio/FilamentInstance.h
+        ${GLTFIO_DIR}/include/gltfio/MaterialProvider.h
+        ${GLTFIO_DIR}/include/gltfio/NodeManager.h
+        ${GLTFIO_DIR}/include/gltfio/ResourceLoader.h
+        ${GLTFIO_DIR}/include/gltfio/TextureProvider.h
         ${GLTFIO_DIR}/include/gltfio/math.h
 
+        ${GLTFIO_DIR}/src/ArchiveCache.cpp
+        ${GLTFIO_DIR}/src/ArchiveCache.h
         ${GLTFIO_DIR}/src/Animator.cpp
         ${GLTFIO_DIR}/src/AssetLoader.cpp
-        ${GLTFIO_DIR}/src/DracoCache.cpp
-        ${GLTFIO_DIR}/src/DracoCache.h
         ${GLTFIO_DIR}/src/DependencyGraph.cpp
         ${GLTFIO_DIR}/src/DependencyGraph.h
+        ${GLTFIO_DIR}/src/DracoCache.cpp
+        ${GLTFIO_DIR}/src/DracoCache.h
         ${GLTFIO_DIR}/src/FFilamentAsset.h
-        ${GLTFIO_DIR}/src/FilamentAsset.cpp
         ${GLTFIO_DIR}/src/FFilamentInstance.h
+        ${GLTFIO_DIR}/src/FilamentAsset.cpp
         ${GLTFIO_DIR}/src/FilamentInstance.cpp
+        ${GLTFIO_DIR}/src/FNodeManager.h
         ${GLTFIO_DIR}/src/GltfEnums.h
+        ${GLTFIO_DIR}/src/Ktx2Provider.cpp
         ${GLTFIO_DIR}/src/MaterialProvider.cpp
+        ${GLTFIO_DIR}/src/NodeManager.cpp
         ${GLTFIO_DIR}/src/ResourceLoader.cpp
-        ${GLTFIO_DIR}/src/TangentsJob.h
+        ${GLTFIO_DIR}/src/StbProvider.cpp
         ${GLTFIO_DIR}/src/TangentsJob.cpp
-        ${GLTFIO_DIR}/src/UbershaderLoader.cpp
+        ${GLTFIO_DIR}/src/TangentsJob.h
+        ${GLTFIO_DIR}/src/UbershaderProvider.cpp
         ${GLTFIO_DIR}/src/Wireframe.cpp
         ${GLTFIO_DIR}/src/Wireframe.h
         ${GLTFIO_DIR}/src/upcast.h
-        ${GLTFIO_DIR}/src/Image.cpp
 
         src/main/cpp/Animator.cpp
         src/main/cpp/AssetLoader.cpp
@@ -61,11 +84,10 @@ set(GLTFIO_SRCS
         src/main/cpp/FilamentInstance.cpp
         src/main/cpp/MaterialKey.cpp
         src/main/cpp/MaterialKey.h
-        src/main/cpp/UbershaderLoader.cpp
+        src/main/cpp/UbershaderProvider.cpp
         src/main/cpp/ResourceLoader.cpp
 
-        ${FILAMENT_DIR}/include/gltfio/resources/gltfresources_lite.h
-        ${FILAMENT_DIR}/include/gltfio/resources/gltfresources.h
+        ${FILAMENT_DIR}/include/gltfio/materials/uberarchive.h
 
         ../common/NioUtils.cpp
 )
@@ -73,30 +95,23 @@ set(GLTFIO_SRCS
 set(GLTFIO_INCLUDE_DIRS
         ..
         ${FILAMENT_DIR}/include
-        ${FILAMENT_DIR}/include/gltfio/resources
         ../../filament/backend/include
         ../../libs/gltfio/include
+        ../../third_party/basisu/zstd
         ../../third_party/cgltf
         ../../third_party/robin-map
         ../../third_party/hat-trie
         ../../third_party/stb
         ../../libs/utils/include
+        ../../libs/ktxreader/include
 )
 
 add_library(gltfio-jni SHARED ${GLTFIO_SRCS})
 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)
-
-if(GLTFIO_LITE)
-        target_compile_definitions(gltfio-jni PUBLIC GLTFIO_LITE=1)
-        target_link_libraries(gltfio-jni filament-jni utils log gltfio_resources_lite)
-else()
-        target_link_libraries(gltfio-jni filament-jni utils log gltfio_resources)
-
-        # Enable Draco in the non-lite variant of gltfio.
-        target_link_libraries(gltfio-jni dracodec)
-        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)
-endif()
+target_link_libraries(gltfio-jni filament-jni utils uberzlib log stb ktxreader basis_transcoder zstd uberarchive)
+target_link_libraries(gltfio-jni dracodec)
+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/build.gradle

@@ -1,27 +1,20 @@
 android {
+    namespace 'com.google.android.filament.gltfio'
+
     flavorDimensions "functionality"
     productFlavors {
         full {
             dimension "functionality"
         }
-
-        lite {
-            dimension "functionality"
-
-            externalNativeBuild {
-                cmake {
-                    arguments.add("-DGLTFIO_LITE=ON")
-                }
-            }
-        }
     }
-
-    // No need to package up the following shared libs, which arise as a side effect of our
-    // externalNativeBuild dependencies. When clients pick and choose from project-level gradle
-    // dependencies, these shared libs already get pulled in, so we need to avoid the error:
-    // "More than one file was found with OS independent path ..."
     packagingOptions {
-        exclude 'lib/*/libfilament-jni.so'
+        // No need to package up the following shared libs, which arise as a side effect of our
+        // externalNativeBuild dependencies. When clients pick and choose from project-level gradle
+        // dependencies, these shared libs already get pulled in, so we need to avoid the error:
+        // "More than one file was found with OS independent path ..."
+        jniLibs {
+            excludes += ['lib/*/libfilament-jni.so']
+        }
     }
 }
 
@@ -40,11 +33,6 @@ afterEvaluate { project ->
                 artifactId = POM_ARTIFACT_ID_FULL
                 from components.fullRelease
             }
-
-            liteRelease(MavenPublication) {
-                artifactId = POM_ARTIFACT_ID_LITE
-                from components.liteRelease
-            }
         }
     }
 }

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

@@ -20,7 +20,7 @@
 
 using namespace filament;
 using namespace filament::math;
-using namespace gltfio;
+using namespace filament::gltfio;
 using namespace utils;
 
 extern "C" JNIEXPORT void JNICALL
@@ -36,6 +36,19 @@ Java_com_google_android_filament_gltfio_Animator_nUpdateBoneMatrices(JNIEnv*, jc
     animator->updateBoneMatrices();
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_Animator_nApplyCrossFade(JNIEnv*, jclass, jlong nativeAnimator,
+        jint previousAnimIndex, jfloat previousAnimTime, jfloat alpha) {
+    Animator* animator = (Animator*) nativeAnimator;
+    animator->applyCrossFade(previousAnimIndex, previousAnimTime, alpha);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_Animator_nResetBoneMatrices(JNIEnv*, jclass, jlong nativeAnimator) {
+    Animator* animator = (Animator*) nativeAnimator;
+    animator->resetBoneMatrices();
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_gltfio_Animator_nGetAnimationCount(JNIEnv*, jclass, jlong nativeAnimator) {
     Animator* animator = (Animator*) nativeAnimator;

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

@@ -30,7 +30,7 @@
 #include "MaterialKey.h"
 
 using namespace filament;
-using namespace gltfio;
+using namespace filament::gltfio;
 using namespace utils;
 
 class JavaMaterialProvider : public MaterialProvider {

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

@@ -20,7 +20,7 @@
 
 using namespace filament;
 using namespace filament::math;
-using namespace gltfio;
+using namespace filament::gltfio;
 using namespace utils;
 
 extern "C" JNIEXPORT jint JNICALL
@@ -120,10 +120,34 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nGetLightEntities(JNIEnv* env, jclass,
         jlong nativeAsset, jintArray result) {
     FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
+    const jsize available = env->GetArrayLength(result);
+    const size_t minCount = std::min(available, (jsize) asset->getLightEntityCount());
+    if (minCount == 0) {
+        return;
+    }
     Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
-    std::copy_n(asset->getLightEntities(),
-            std::min(available, (jsize) asset->getLightEntityCount()), entities);
+    std::copy_n(asset->getLightEntities(), minCount, entities);
+    env->ReleaseIntArrayElements(result, (jint*) entities, 0);
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentAsset_nGetRenderableEntityCount(JNIEnv*, jclass,
+        jlong nativeAsset) {
+    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
+    return asset->getRenderableEntityCount();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentAsset_nGetRenderableEntities(JNIEnv* env, jclass,
+        jlong nativeAsset, jintArray result) {
+    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
+    const jsize available = env->GetArrayLength(result);
+    const size_t minCount = std::min(available, (jsize) asset->getRenderableEntityCount());
+    if (minCount == 0) {
+        return;
+    }
+    Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
+    std::copy_n(asset->getRenderableEntities(), minCount, entities);
     env->ReleaseIntArrayElements(result, (jint*) entities, 0);
 }
 
@@ -131,10 +155,13 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nGetCameraEntities(JNIEnv* env, jclass,
         jlong nativeAsset, jintArray result) {
     FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
+    const jsize available = env->GetArrayLength(result);
+    const size_t minCount = std::min(available, (jsize) asset->getCameraEntityCount());
+    if (minCount == 0) {
+        return;
+    }
     Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
-    std::copy_n(asset->getCameraEntities(),
-            std::min(available, (jsize) asset->getCameraEntityCount()), entities);
+    std::copy_n(asset->getCameraEntities(), minCount, entities);
     env->ReleaseIntArrayElements(result, (jint*) entities, 0);
 }
 
@@ -313,3 +340,19 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nReleaseSourceData(JNIEnv*
     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,7 +20,7 @@
 
 #include <algorithm>
 
-using namespace gltfio;
+using namespace filament::gltfio;
 using namespace utils;
 
 extern "C" JNIEXPORT jint JNICALL

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

@@ -20,7 +20,7 @@
 
 #include "MaterialKey.h"
 
-using namespace gltfio;
+using namespace filament::gltfio;
 
 MaterialKeyHelper& MaterialKeyHelper::get() {
     static MaterialKeyHelper helper;

android/gltfio-android/src/main/cpp/MaterialKey.h

@@ -22,10 +22,12 @@
 
 class MaterialKeyHelper {
 public:
+    using MaterialKey = filament::gltfio::MaterialKey;
+
     static MaterialKeyHelper& get();
 
-    void copy(JNIEnv* env, gltfio::MaterialKey& dst, jobject src);
-    void copy(JNIEnv* env, jobject dst, const gltfio::MaterialKey& src);
+    void copy(JNIEnv* env, MaterialKey& dst, jobject src);
+    void copy(JNIEnv* env, jobject dst, const MaterialKey& src);
 
     void init(JNIEnv* env); // called only from the Java static class constructor
 

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

@@ -19,13 +19,14 @@
 #include <filament/Engine.h>
 
 #include <gltfio/ResourceLoader.h>
+#include <gltfio/TextureProvider.h>
 
 #include <utils/Log.h>
 
 #include "common/NioUtils.h"
 
 using namespace filament;
-using namespace gltfio;
+using namespace filament::gltfio;
 using namespace utils;
 
 static void destroy(void*, size_t, void *userData) {
@@ -114,3 +115,34 @@ Java_com_google_android_filament_gltfio_ResourceLoader_nAsyncCancelLoad(JNIEnv*,
     ResourceLoader* loader = (ResourceLoader*) nativeLoader;
     loader->asyncCancelLoad();
 }
+
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_gltfio_ResourceLoader_nCreateStbProvider(JNIEnv*, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jlong) createStbProvider(engine);
+}
+
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_gltfio_ResourceLoader_nCreateKtx2Provider(JNIEnv*, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jlong) createKtx2Provider(engine);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_ResourceLoader_nDestroyTextureProvider(JNIEnv*, jclass,
+        jlong nativeProvider) {
+    TextureProvider* provider = (TextureProvider*) nativeProvider;
+    delete provider;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_ResourceLoader_nAddTextureProvider(JNIEnv* env, jclass,
+        jlong nativeLoader, jstring url, jlong nativeProvider) {
+    ResourceLoader* loader = (ResourceLoader*) nativeLoader;
+    TextureProvider* provider = (TextureProvider*) nativeProvider;
+    const char* cstring = env->GetStringUTFChars(url, nullptr);
+    loader->addTextureProvider(cstring, provider);
+    env->ReleaseStringUTFChars(url, cstring);
+}

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

@@ -17,37 +17,38 @@
 #include <jni.h>
 
 #include <gltfio/MaterialProvider.h>
+#include <gltfio/materials/uberarchive.h>
 
 #include <utils/debug.h>
 
 #include "MaterialKey.h"
 
 using namespace filament;
-using namespace gltfio;
+using namespace filament::gltfio;
 
 extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nCreateUbershaderLoader(JNIEnv*, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nCreateUbershaderProvider(JNIEnv*, jclass,
         jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
-    return (jlong) createUbershaderLoader(engine);
+    return (jlong) createUbershaderProvider(engine, UBERARCHIVE_DEFAULT_DATA, UBERARCHIVE_DEFAULT_SIZE);
 }
 
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nDestroyUbershaderLoader(JNIEnv*, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nDestroyUbershaderProvider(JNIEnv*, jclass,
         jlong nativeProvider) {
     auto provider = (MaterialProvider*) nativeProvider;
     delete provider;
 }
 
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nDestroyMaterials(JNIEnv*, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nDestroyMaterials(JNIEnv*, jclass,
         jlong nativeProvider) {
     auto provider = (MaterialProvider*) nativeProvider;
     provider->destroyMaterials();
 }
 
 extern "C" JNIEXPORT long JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nCreateMaterialInstance(JNIEnv* env, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nCreateMaterialInstance(JNIEnv* env, jclass,
         jlong nativeProvider, jobject materialKey, jintArray uvmap, jstring label) {
     MaterialKey nativeKey = {};
 
@@ -80,14 +81,14 @@ Java_com_google_android_filament_gltfio_UbershaderLoader_nCreateMaterialInstance
 }
 
 extern "C" JNIEXPORT int JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nGetMaterialCount(JNIEnv*, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nGetMaterialCount(JNIEnv*, jclass,
         jlong nativeProvider) {
     auto provider = (MaterialProvider*) nativeProvider;
     return provider->getMaterialsCount();
 }
 
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_UbershaderLoader_nGetMaterials(JNIEnv* env, jclass,
+Java_com_google_android_filament_gltfio_UbershaderProvider_nGetMaterials(JNIEnv* env, jclass,
         jlong nativeProvider, jlongArray result) {
     auto provider = (MaterialProvider *) nativeProvider;
     auto materials = provider->getMaterials();

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

@@ -66,6 +66,36 @@ public class Animator {
         nUpdateBoneMatrices(getNativeObject());
     }
 
+    /**
+     * Applies a blended transform to the union of nodes affected by two animations.
+     * Used for cross-fading from a previous skinning-based animation or rigid body animation.
+     *
+     * First, this stashes the current transform hierarchy into a transient memory buffer.
+     *
+     * Next, this applies previousAnimIndex / previousAnimTime to the actual asset by internally
+     * calling applyAnimation().
+     *
+     * Finally, the stashed local transforms are lerped (via the scale / translation / rotation
+     * components) with their live counterparts, and the results are pushed to the asset.
+     *
+     * To achieve a cross fade effect with skinned models, clients will typically call animator
+     * methods in this order: (1) applyAnimation (2) applyCrossFade (3) updateBoneMatrices. The
+     * animation that clients pass to applyAnimation is the "current" animation corresponding to
+     * alpha=1, while the "previous" animation passed to applyCrossFade corresponds to alpha=0.
+     */
+    public void applyCrossFade(int previousAnimIndex, float previousAnimTime, float alpha) {
+        nApplyCrossFade(getNativeObject(), previousAnimIndex, previousAnimTime, alpha);
+    }
+
+    /**
+     * Pass the identity matrix into all bone nodes, useful for returning to the T pose.
+     *
+     * <p>NOTE: this operation is independent of <code>animation</code>.</p>
+     */
+    public void resetBoneMatrices() {
+        nResetBoneMatrices(getNativeObject());
+    }
+
     /**
      * Returns the number of <code>animation</code> definitions in the glTF asset.
      */
@@ -109,6 +139,8 @@ public class Animator {
 
     private static native void nApplyAnimation(long nativeAnimator, int index, float time);
     private static native void nUpdateBoneMatrices(long nativeAnimator);
+    private static native void nApplyCrossFade(long nativeAnimator, int animIndex, float animTime, float alpha);
+    private static native void nResetBoneMatrices(long nativeAnimator);
     private static native int nGetAnimationCount(long nativeAnimator);
     private static native float nGetAnimationDuration(long nativeAnimator, int index);
     private static native String nGetAnimationName(long nativeAnimator, int index);

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

@@ -45,7 +45,7 @@ import java.nio.Buffer;
  *
  *     ...
  *
- *     materialProvider = UbershaderLoader(engine)
+ *     materialProvider = UbershaderProvider(engine)
  *     assetLoader = AssetLoader(engine, materialProvider, EntityManager.get())
  *
  *     filamentAsset = assets.open("models/lucy.gltf").use { input ->

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

@@ -30,9 +30,9 @@ import com.google.android.filament.MaterialInstance;
  *
  * <p>For usage instructions, see the documentation for {@link AssetLoader}.</p>
  *
- * <p>This class owns a hierarchy of entities that have been loaded from a glTF asset. Every entity has
- * a <code>TransformManager</code> component, and some entities also have
- * <code>NameComponentManager</code> and/or <code>RenderableManager</code> components.</p>
+ * <p>This class owns a hierarchy of entities that have been loaded from a glTF asset. Every entity
+ * has a <code>TransformManager</code> component, and some entities also have compnents managed by
+ * <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
@@ -113,6 +113,15 @@ public class FilamentAsset {
         return result;
     }
 
+    /**
+     * Gets only the entities that have renderable components.
+     */
+    public @NonNull @Entity int[] getRenderableEntities() {
+        int[] result = new int[nGetRenderableEntityCount(mNativeObject)];
+        nGetRenderableEntities(mNativeObject, result);
+        return result;
+    }
+
     /**
      * Gets only the entities that have camera components.
      *
@@ -232,17 +241,37 @@ public class FilamentAsset {
         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(int skinIndex) {
+    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(int skinIndex) {
+    public @NonNull @Entity int[] getJointsAt(@IntRange(from = 0) int skinIndex) {
         int[] result = new int[getJointCountAt(skinIndex)];
         nGetJointsAt(getNativeObject(), skinIndex, result);
         return result;
@@ -321,6 +350,9 @@ public class FilamentAsset {
     private static native int nGetLightEntityCount(long nativeAsset);
     private static native void nGetLightEntities(long nativeAsset, int[] result);
 
+    private static native int nGetRenderableEntityCount(long nativeAsset);
+    private static native void nGetRenderableEntities(long nativeAsset, int[] result);
+
     private static native int nGetCameraEntityCount(long nativeAsset);
     private static native void nGetCameraEntities(long nativeAsset, int[] result);
 
@@ -333,6 +365,9 @@ public class FilamentAsset {
     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);

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

@@ -35,6 +35,8 @@ import java.nio.Buffer;
  */
 public class ResourceLoader {
     private final long mNativeObject;
+    private final long mNativeStbProvider;
+    private final long mNativeKtx2Provider;
 
     /**
      * Constructs a resource loader tied to the given Filament engine.
@@ -46,6 +48,11 @@ public class ResourceLoader {
     public ResourceLoader(@NonNull Engine engine) {
         long nativeEngine = engine.getNativeObject();
         mNativeObject = nCreateResourceLoader(nativeEngine, false, false, false);
+        mNativeStbProvider = nCreateStbProvider(nativeEngine);
+        mNativeKtx2Provider = nCreateKtx2Provider(nativeEngine);
+        nAddTextureProvider(mNativeObject, "image/jpeg", mNativeStbProvider);
+        nAddTextureProvider(mNativeObject, "image/png", mNativeStbProvider);
+        nAddTextureProvider(mNativeObject, "image/ktx2", mNativeKtx2Provider);
     }
 
     /**
@@ -63,6 +70,11 @@ public class ResourceLoader {
         long nativeEngine = engine.getNativeObject();
         mNativeObject = nCreateResourceLoader(nativeEngine, normalizeSkinningWeights,
                 recomputeBoundingBoxes, ignoreBindTransform);
+        mNativeStbProvider = nCreateStbProvider(nativeEngine);
+        mNativeKtx2Provider = nCreateKtx2Provider(nativeEngine);
+        nAddTextureProvider(mNativeObject, "image/jpeg", mNativeStbProvider);
+        nAddTextureProvider(mNativeObject, "image/png", mNativeStbProvider);
+        nAddTextureProvider(mNativeObject, "image/ktx2", mNativeKtx2Provider);
     }
 
     /**
@@ -70,6 +82,8 @@ public class ResourceLoader {
      */
     public void destroy() {
         nDestroyResourceLoader(mNativeObject);
+        nDestroyTextureProvider(mNativeStbProvider);
+        nDestroyTextureProvider(mNativeKtx2Provider);
     }
 
     /**
@@ -178,4 +192,9 @@ public class ResourceLoader {
     private static native float nAsyncGetLoadProgress(long nativeLoader);
     private static native void nAsyncUpdateLoad(long nativeLoader);
     private static native void nAsyncCancelLoad(long nativeLoader);
+
+    private static native long nCreateStbProvider(long nativeEngine);
+    private static native long nCreateKtx2Provider(long nativeEngine);
+    private static native void nAddTextureProvider(long nativeLoader, String url, long nativeProvider);
+    private static native void nDestroyTextureProvider(long nativeProvider);
 }

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

@@ -31,7 +31,7 @@ import androidx.annotation.Size;
  * <p>This class is used by {@link AssetLoader} to create Filament materials.
  * Client applications do not need to call methods on it.</p>
  */
-public class UbershaderLoader implements MaterialProvider {
+public class UbershaderProvider implements MaterialProvider {
     private static final VertexBuffer.VertexAttribute[] sVertexAttributesValues =
             VertexBuffer.VertexAttribute.values();
 
@@ -42,16 +42,16 @@ public class UbershaderLoader implements MaterialProvider {
      *
      * @param engine the engine used to create materials
      */
-    public UbershaderLoader(Engine engine) {
+    public UbershaderProvider(Engine engine) {
         long nativeEngine = engine.getNativeObject();
-        mNativeObject = nCreateUbershaderLoader(nativeEngine);
+        mNativeObject = nCreateUbershaderProvider(nativeEngine);
     }
 
     /**
      * Frees memory associated with the native material provider.
      * */
     public void destroy() {
-        nDestroyUbershaderLoader(mNativeObject);
+        nDestroyUbershaderProvider(mNativeObject);
         mNativeObject = 0;
     }
 
@@ -92,8 +92,8 @@ public class UbershaderLoader implements MaterialProvider {
         return mNativeObject;
     }
 
-    private static native long nCreateUbershaderLoader(long nativeEngine);
-    private static native void nDestroyUbershaderLoader(long nativeProvider);
+    private static native long nCreateUbershaderProvider(long nativeEngine);
+    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);

android/gradle.properties

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

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.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.3.3-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

android/samples/sample-gltf-viewer/build.gradle

@@ -25,6 +25,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.gltf'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.gltf"
@@ -32,6 +34,7 @@ android {
         targetSdkVersion versions.targetSdk
         missingDimensionStrategy 'functionality', 'full'
     }
+
     // NOTE: This is a workaround required because the AGP task collectReleaseDependencies
     //       is not configuration-cache friendly yet; this is only useful for Play publication
     dependenciesInfo {

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

@@ -150,12 +150,12 @@ class MainActivity : Activity() {
         val scene = modelViewer.scene
         val ibl = "default_env"
         readCompressedAsset("envs/$ibl/${ibl}_ibl.ktx").let {
-            scene.indirectLight = KTXLoader.createIndirectLight(engine, it)
+            scene.indirectLight = KTX1Loader.createIndirectLight(engine, it)
             scene.indirectLight!!.intensity = 30_000.0f
             viewerContent.indirectLight = modelViewer.scene.indirectLight
         }
         readCompressedAsset("envs/$ibl/${ibl}_skybox.ktx").let {
-            scene.skybox = KTXLoader.createSkybox(engine, it)
+            scene.skybox = KTX1Loader.createSkybox(engine, it)
         }
     }
 
@@ -297,9 +297,10 @@ class MainActivity : Activity() {
 
         val gltfBuffer = pathToBufferMapping[gltfPath]!!
 
-        // The gltf is often not at the root level (e.g. if a folder is zipped) so
-        // we need to extract its path in order to resolve the embedded uri strings.
-        var prefix = URI(gltfPath!!).resolve("..")
+        // In a zip file, the gltf file might be in the same folder as resources, or in a different
+        // folder. It is crucial to test against both of these cases. In any case, the resource
+        // paths are all specified relative to the location of the gltf file.
+        var prefix = URI(gltfPath!!).resolve(".")
 
         withContext(Dispatchers.Main) {
             if (gltfPath!!.endsWith(".glb")) {
@@ -308,7 +309,7 @@ class MainActivity : Activity() {
                 modelViewer.loadModelGltf(gltfBuffer) { uri ->
                     val path = prefix.resolve(uri).toString()
                     if (!pathToBufferMapping.contains(path)) {
-                        Log.e(TAG, "Could not find '$uri' in zip using prefix '$prefix'")
+                        Log.e(TAG, "Could not find '$uri' in zip using prefix '$prefix' and base path '${gltfPath!!}'")
                         setStatusText("Zip is missing $path")
                     }
                     pathToBufferMapping[path]

android/samples/sample-hello-camera/build.gradle

@@ -16,6 +16,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.hellocam'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.hellocamera"

android/samples/sample-hello-triangle/build.gradle

@@ -16,6 +16,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.hellotriangle'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.hellotriangle"

android/samples/sample-image-based-lighting/build.gradle

@@ -22,6 +22,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.ibl'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.ibl"

android/samples/sample-lit-cube/build.gradle

@@ -15,6 +15,8 @@ clean.doFirst {
     delete "src/main/assets"
 }
 android {
+    namespace 'com.google.android.filament.litcube'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.litcube"

android/samples/sample-live-wallpaper/build.gradle

@@ -4,6 +4,8 @@ apply plugin: 'kotlin-android'
 project.ext.isSample = true
 
 android {
+    namespace 'com.google.android.filament.livewallpaper'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.livewallpaper"

android/samples/sample-material-builder/build.gradle

@@ -19,6 +19,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.material_builder'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.material_builder"

android/samples/sample-multi-view/build.gradle

@@ -15,6 +15,8 @@ clean.doFirst {
     delete "src/main/assets"
 }
 android {
+    namespace 'com.google.android.filament.multiview'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.multiview"

android/samples/sample-page-curl/build.gradle

@@ -18,6 +18,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.pagecurl'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.pagecurl"

android/samples/sample-page-curl/src/main/materials/curl.mat

@@ -59,7 +59,7 @@ vertex {
         vec3 p1 = deformPoint(theta, apex, uv.s + e, uv.t);
         vec3 p2 = deformPoint(theta, apex, uv.s, uv.t + e);
         vec3 normal = normalize(cross(p1 - p, p2 - p));
-        material.worldNormal = objectUniforms.worldFromModelNormalMatrix * normal;
+        material.worldNormal = getWorldFromModelNormalMatrix() * normal;
         mat4 transform = getWorldFromModelMatrix();
         material.worldPosition = mulMat4x4Float3(transform, p);
     }

android/samples/sample-stream-test/build.gradle

@@ -16,6 +16,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.streamtest'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.streamtest"

android/samples/sample-stream-test/src/main/java/com/google/android/filament/streamtest/MainActivity.kt

@@ -79,8 +79,6 @@ class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallba
     // Performs the rendering and schedules new frames
     private val frameScheduler = FrameCallback()
 
-    private var externalTextureID: Int = 0
-
     @RequiresApi(30)
     class Api30Impl {
         companion object {
@@ -103,8 +101,6 @@ class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallba
         setupView()
         setupScene()
 
-        externalTextureID = createExternalTexture()
-
         @Suppress("deprecation")
         val display = if (Build.VERSION.SDK_INT >= 30) {
             Api30Impl.getDisplay(this)
@@ -112,7 +108,7 @@ class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallba
             windowManager.defaultDisplay!!
         }
 
-        streamHelper = StreamHelper(engine, materialInstance, display, externalTextureID)
+        streamHelper = StreamHelper(engine, materialInstance, display)
         this.title = streamHelper.getTestName()
     }
 
@@ -445,31 +441,4 @@ class MainActivity : Activity(), ActivityCompat.OnRequestPermissionsResultCallba
         check(EGL14.eglMakeCurrent(display, surface, surface, context)) { "Error making GL context." }
         return context
     }
-
-    private  fun createExternalTexture(): Int {
-        val textures = IntArray(1)
-        GLES30.glGenTextures(1, textures, 0)
-        val result = textures[0]
-
-        val textureTarget = GLES11Ext.GL_TEXTURE_EXTERNAL_OES
-        GLES30.glBindTexture(textureTarget, result)
-        GLES30.glTexParameteri(textureTarget, GLES30.GL_TEXTURE_WRAP_S, GLES30.GL_CLAMP_TO_EDGE)
-        GLES30.glTexParameteri(textureTarget, GLES30.GL_TEXTURE_WRAP_T, GLES30.GL_CLAMP_TO_EDGE)
-        GLES30.glTexParameteri(textureTarget, GLES30.GL_TEXTURE_MIN_FILTER, GLES30.GL_NEAREST)
-        GLES30.glTexParameteri(textureTarget, GLES30.GL_TEXTURE_MAG_FILTER, GLES30.GL_NEAREST)
-
-        if (!GLES30.glIsTexture(result)) {
-            throw RuntimeException("OpenGL error: $result is an invalid texture.")
-        }
-
-        val error = GLES30.glGetError()
-        if (error != GLES30.GL_NO_ERROR) {
-            val errorString = GLU.gluErrorString(error)
-            throw RuntimeException("OpenGL error: $errorString!")
-        }
-
-        return result
-    }
-
-
 }

android/samples/sample-stream-test/src/main/java/com/google/android/filament/streamtest/StreamHelper.kt

@@ -37,7 +37,6 @@ class StreamHelper(
     private val filamentEngine: Engine,
     private val filamentMaterial: MaterialInstance,
     private val display: Display,
-    private val externalTextureId: Int
 ) {
     /**
      * The StreamSource configures the source data for the texture.
@@ -51,7 +50,6 @@ class StreamHelper(
      */
     enum class StreamSource {
         CANVAS_STREAM_NATIVE,     // copy-free but does not guarantee synchronization
-        CANVAS_STREAM_TEXID,      // synchronized but incurs a copy
         CANVAS_STREAM_ACQUIRED,   // synchronized and copy-free
     }
 
@@ -127,10 +125,6 @@ class StreamHelper(
 
             surface.unlockCanvasAndPost(canvas)
 
-            if (streamSource == StreamSource.CANVAS_STREAM_TEXID) {
-                surfaceTexture!!.updateTexImage()
-            }
-
             if (streamSource == StreamSource.CANVAS_STREAM_ACQUIRED) {
                 val image = imageReader!!.acquireLatestImage()
                 filamentStream!!.setAcquiredImage(
@@ -146,7 +140,7 @@ class StreamHelper(
 
     fun nextTest() {
         stopTest()
-        streamSource = StreamSource.values()[(streamSource.ordinal + 1) % 3]
+        streamSource = StreamSource.values()[(streamSource.ordinal + 1) % StreamSource.values().size]
         startTest()
     }
 
@@ -213,23 +207,6 @@ class StreamHelper(
             filamentTexture.setExternalStream(filamentEngine, filamentStream!!)
         }
 
-        if (streamSource == StreamSource.CANVAS_STREAM_TEXID) {
-
-            // Create the Android surface that will hold the canvas image.
-            surfaceTexture = SurfaceTexture(externalTextureId)
-            surfaceTexture!!.setDefaultBufferSize(resolution.width, resolution.height)
-            canvasSurface = Surface(surfaceTexture)
-
-            // Create the Filament Stream object that gets bound to the Texture.
-            filamentStream = Stream.Builder()
-                    .stream(externalTextureId.toLong())
-                    .width(resolution.width)
-                    .height(resolution.height)
-                    .build(filamentEngine)
-
-            filamentTexture.setExternalStream(filamentEngine, filamentStream!!)
-        }
-
         if (streamSource == StreamSource.CANVAS_STREAM_ACQUIRED) {
             filamentStream = Stream.Builder()
                     .width(resolution.width)

android/samples/sample-texture-view/build.gradle

@@ -16,6 +16,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.textureview'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.textureview"

android/samples/sample-textured-object/build.gradle

@@ -22,6 +22,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.textured'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.textured"

android/samples/sample-transparent-view/build.gradle

@@ -16,6 +16,8 @@ clean.doFirst {
 }
 
 android {
+    namespace 'com.google.android.filament.transparentrendering'
+
     compileSdkVersion versions.compileSdk
     defaultConfig {
         applicationId "com.google.android.filament.textureview"

build.sh

@@ -2,7 +2,7 @@
 set -e
 
 # Host tools required by Android, WebGL, and iOS builds
-MOBILE_HOST_TOOLS="matc resgen cmgen filamesh"
+MOBILE_HOST_TOOLS="matc resgen cmgen filamesh uberz"
 WEB_HOST_TOOLS="${MOBILE_HOST_TOOLS} mipgen filamesh"
 
 function print_help {
@@ -98,9 +98,9 @@ function print_matdbg_help {
     echo ""
     echo "FOR ANDROID BUILDS:"
     echo ""
-    echo "1) The most reliable way to enable matdbg is to bypass Gradle and"
-    echo "   directly modify the appropriate two lines in the following file:"
-    echo "       ./android/filament-android/CMakeLists.txt"
+    echo "1) For Android Studio builds, make sure to set:"
+    echo "       -Pcom.google.android.filament.matdbg"
+    echo "   option in Preferences > Build > Compiler > Command line options."
     echo ""
     echo "2) The port number is hardcoded to 8081 so you will need to do:"
     echo "       adb forward tcp:8081 tcp:8081"
@@ -156,6 +156,7 @@ VULKAN_ANDROID_GRADLE_OPTION=""
 SWIFTSHADER_OPTION="-DFILAMENT_USE_SWIFTSHADER=OFF"
 
 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
+MATDBG_GRADLE_OPTION=""
 
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false
@@ -303,7 +304,7 @@ function build_webgl_with_target {
 }
 
 function build_webgl {
-    # For the host tools, supress install and always use Release.
+    # For the host tools, suppress install and always use Release.
     local old_install_command=${INSTALL_COMMAND}; INSTALL_COMMAND=
     local old_issue_debug_build=${ISSUE_DEBUG_BUILD}; ISSUE_DEBUG_BUILD=false
     local old_issue_release_build=${ISSUE_RELEASE_BUILD}; ISSUE_RELEASE_BUILD=true
@@ -402,7 +403,7 @@ function ensure_android_build {
 function build_android {
     ensure_android_build
 
-    # Supress intermediate desktop tools install
+    # Suppress intermediate desktop tools install
     local old_install_command=${INSTALL_COMMAND}
     INSTALL_COMMAND=
 
@@ -456,6 +457,7 @@ function build_android {
             -Pcom.google.android.filament.dist-dir=../out/android-debug/filament \
             -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \
             ${VULKAN_ANDROID_GRADLE_OPTION} \
+            ${MATDBG_GRADLE_OPTION} \
             :filament-android:assembleDebug \
             :gltfio-android:assembleDebug \
             :filament-utils-android:assembleDebug
@@ -476,14 +478,12 @@ function build_android {
 
         if [[ "${INSTALL_COMMAND}" ]]; then
             echo "Installing out/filamat-android-debug.aar..."
-            cp filamat-android/build/outputs/aar/filamat-android-lite-debug.aar ../out/
             cp filamat-android/build/outputs/aar/filamat-android-full-debug.aar ../out/filamat-android-debug.aar
 
             echo "Installing out/filament-android-debug.aar..."
             cp filament-android/build/outputs/aar/filament-android-debug.aar ../out/
 
             echo "Installing out/gltfio-android-debug.aar..."
-            cp gltfio-android/build/outputs/aar/gltfio-android-lite-debug.aar ../out/
             cp gltfio-android/build/outputs/aar/gltfio-android-full-debug.aar ../out/gltfio-android-debug.aar
 
             echo "Installing out/filament-utils-android-debug.aar..."
@@ -504,6 +504,7 @@ function build_android {
             -Pcom.google.android.filament.dist-dir=../out/android-release/filament \
             -Pcom.google.android.filament.abis=${ABI_GRADLE_OPTION} \
             ${VULKAN_ANDROID_GRADLE_OPTION} \
+            ${MATDBG_GRADLE_OPTION} \
             :filament-android:assembleRelease \
             :gltfio-android:assembleRelease \
             :filament-utils-android:assembleRelease
@@ -531,7 +532,6 @@ function build_android {
             cp filament-android/build/outputs/aar/filament-android-release.aar ../out/
 
             echo "Installing out/gltfio-android-release.aar..."
-            cp gltfio-android/build/outputs/aar/gltfio-android-lite-release.aar ../out/
             cp gltfio-android/build/outputs/aar/gltfio-android-full-release.aar ../out/gltfio-android-release.aar
 
             echo "Installing out/filament-utils-android-release.aar..."
@@ -598,7 +598,7 @@ function archive_ios {
 }
 
 function build_ios {
-    # Supress intermediate desktop tools install
+    # Suppress intermediate desktop tools install
     local old_install_command=${INSTALL_COMMAND}
     INSTALL_COMMAND=
 
@@ -754,6 +754,7 @@ while getopts ":hacCfijmp:q:uvslwtdk:" opt; do
         d)
             PRINT_MATDBG_HELP=true
             MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_DISABLE_MATOPT=ON, -DFILAMENT_BUILD_FILAMAT=ON"
+            MATDBG_GRADLE_OPTION="-Pcom.google.android.filament.matdbg"
             ;;
         f)
             ISSUE_CMAKE_ALWAYS=true

build/android/build.sh

@@ -49,7 +49,8 @@ FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/ndk.version)}
 
 # Install the required NDK version specifically (if not present)
 if [[ ! -d "${ANDROID_HOME}/ndk/$FILAMENT_NDK_VERSION" ]]; then
-    ${ANDROID_HOME}/tools/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION" > /dev/null
+    # NOTE: We MUST use Java 1.8 to run sdkmanager currently, it fails starting with Java 11
+    JAVA_HOME=${JAVA_HOME_8_X64} ${ANDROID_HOME}/tools/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION" > /dev/null
 fi
 
 # Only build 1 64 bit target during presubmit to cut down build times during presubmit

build/android/ndk.version

@@ -1 +1 @@
-23.1.7779620
+24.0.8215888

build/common/requirements.txt

@@ -7,7 +7,7 @@ Deprecated==1.2.13
 idna==3.3
 pycparser==2.21
 PyGithub==1.55
-PyJWT==2.3.0
+PyJWT==2.4.0
 PyNaCl==1.5.0
 requests==2.27.1
 urllib3==1.26.9

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.5.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.9.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 ./emsdk install latest
 ./emsdk activate latest

build/windows/build-github.bat

@@ -119,9 +119,8 @@ cmake ..\.. ^
 :: Some resource libraries require significant heap space to compile, so first compile them serially.
 @echo on
 cmake --build . --target filagui --config %config% || exit /b
-cmake --build . --target gltfio_resources --config %config% || exit /b
-cmake --build . --target gltfio_resources_lite --config %config% || exit /b
-cmake --build . --target gltf-resources --config %config% || exit /b
+cmake --build . --target uberarchive --config %config% || exit /b
+cmake --build . --target gltf-demo-resources --config %config% || exit /b
 cmake --build . --target filamentapp-resources --config %config% || exit /b
 cmake --build . --target sample-resources --config %config% || exit /b
 cmake --build . --target suzanne-resources --config %config% || exit /b

docs/Materials.html

@@ -118,6 +118,7 @@ counter-increment: h6;margin-right:10px}
 &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;<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>
 &nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock" class="level2"><span class="tocNumber">4.4&nbsp; </span>Fragment block</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock/preparematerialfunction" class="level3"><span class="tocNumber">4.4.1&nbsp; </span>prepareMaterial function</a><br>
 &nbsp;&nbsp;&nbsp;&nbsp;<a href="#materialdefinitions/fragmentblock/materialfragmentinputs" class="level3"><span class="tocNumber">4.4.2&nbsp; </span>Material fragment inputs</a><br>
@@ -1536,7 +1537,7 @@ non-shader data.
 
 </p><dl><dt>Type</dt><dd><p>     array of <code>string</code>
 
-</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>dynamicLighting</code>, <code>directionalLighting</code>, <code>shadowReceiver</code> or <code>skinning</code>.
+</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>dynamicLighting</code>, <code>directionalLighting</code>, <code>shadowReceiver</code>,<code>skinning</code> or <code>ssr</code>.
 
 </p></dd><dt>Description</dt><dd><p>      Used to specify a list of shader variants that the application guarantees will never be
       needed. These shader variants are skipped during the code generation phase, thus reducing
@@ -1561,7 +1562,9 @@ non-shader data.
 </li>
 <li class="minus"><code>fog</code>, used when global fog is applied to the scene
 </li>
-<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver</li></ul>
+<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver
+</li>
+<li class="minus"><code>ssr</code>, used when screen-space reflections are enabled in the View</li></ul>
 
 <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>
@@ -1607,7 +1610,8 @@ non-shader data.
 
 </p><dl><dt>Type</dt><dd><p>     array of <code>string</code>
 
-</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>uv0</code>, <code>uv1</code>, <code>color</code>, <code>position</code>, <code>tangents</code>.
+</p></dd><dt>Value</dt><dd><p>      Each entry must be any of <code>uv0</code>, <code>uv1</code>, <code>color</code>, <code>position</code>, <code>tangents</code>, <code>custom0</code>
+      through <code>custom7</code>.
 
 </p></dd><dt>Description</dt><dd><p>      Lists the vertex attributes required by the material. The <code>position</code> attribute is always
       required and does not need to be specified. The <code>tangents</code> attribute is automatically required
@@ -1622,7 +1626,8 @@ non-shader data.
 <span class="line">        },</span>
 <span class="line">    ],</span>
 <span class="line">    requires : [</span>
-<span class="line">        uv0</span>
+<span class="line">        uv0,</span>
+<span class="line">        custom0</span>
 <span class="line">    ],</span>
 <span class="line">    shadingModel : lit,</span>
 <span class="line">}</span>
@@ -1631,6 +1636,7 @@ non-shader data.
 <span class="line">    void material(inout MaterialInputs material) {</span>
 <span class="line">        prepareMaterial(material);</span>
 <span class="line">        material.baseColor = texture(materialParams_texture, getUV0());</span>
+<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>
@@ -1759,8 +1765,9 @@ non-shader data.
           render target is brightened.
 </li>
     <li class="minus"><strong class="asterisk">Masked</strong>: blending is disabled. This blending mode enables alpha masking. The alpha channel
-          of the material's output defines whether a fragment is discarded or not. See the maskThreshold
-          section for more information.</li></ul>
+          of the material's output defines whether a fragment is discarded or not. Additionally,
+          ALPHA_TO_COVERAGE is enabled for non-translucent views. See the maskThreshold section for more
+          information.</li></ul>
 
 <p></p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    blending : transparent</span>
@@ -1851,8 +1858,9 @@ and sorting issues are minimized or eliminated</span></center></div></center>
 </p></dd><dt>Value</dt><dd><p>      A value between <code>0.0</code> and <code>1.0</code>. Defaults to <code>0.4</code>.
 
 </p></dd><dt>Description</dt><dd><p>      Sets the minimum alpha value a fragment must have to not be discarded when the <code>blending</code> mode
-      is set to <code>masked</code>. When the blending mode is not <code>masked</code>, this value is ignored. This value
-      can be used to controlled the appearance of alpha-masked objects.
+      is set to <code>masked</code>. If the fragment is not discarded, its source alpha is set to 1. When the
+      blending mode is not <code>masked</code>, this value is ignored. This value can be used to controlled the
+      appearance of alpha-masked objects.
 
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    blending : masked,</span>
@@ -2274,15 +2282,31 @@ APIs listed in the <a href="#shaderpublicapis">Shader public APIs</a> section.
     this behavior using the <code>flipUV</code> property and setting it to <code>false</code>.</p></div>
 
 <p></p>
+<a class="target" name="customvertexattributes">&nbsp;</a><a class="target" name="materialdefinitions/vertexblock/customvertexattributes">&nbsp;</a><a class="target" name="toc4.3.2">&nbsp;</a><h3>Custom vertex attributes</h3>
+<p>
+
+
+You can use up to 8 custom vertex attributes, all of type <code>float4</code>. These attributes can be accessed
+using the vertex block shader functions <code>getCustom0()</code> to <code>getCustom7()</code>. However, before using
+custom attributes, you <em class="asterisk">must</em> declare those attributes as required in the <code>requires</code> property of
+the material:
+
+</p><pre class="listing tilde"><code><span class="line">material {</span>
+<span class="line">    requires : [</span>
+<span class="line">        custom0,</span>
+<span class="line">        custom1,</span>
+<span class="line">        custom2</span>
+<span class="line">    ]</span>
+<span class="line">}</span></code></pre>
 <a class="target" name="fragmentblock">&nbsp;</a><a class="target" name="materialdefinitions/fragmentblock">&nbsp;</a><a class="target" name="toc4.4">&nbsp;</a><h2>Fragment block</h2>
 <p>
 
 
-The fragment block must be used to control the fragment shading stage of the material. The vertex
+The fragment block must be used to control the fragment shading stage of the material. The fragment
 block must contain valid
 <a href="https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf">ESSL 3.0</a>
 code (the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
-inside the vertex block but you <strong class="asterisk">must</strong> declare the <code>material</code> function:
+inside the fragment block but you <strong class="asterisk">must</strong> declare the <code>material</code> function:
 
 </p><pre class="listing tilde"><code><span class="line">fragment {</span>
 <span class="line">    <span class="hljs-type">void</span> material(<span class="hljs-keyword">inout</span> MaterialInputs material) {</span>
@@ -2316,7 +2340,7 @@ standard lit shading model:
 
 
 Note that you <strong class="asterisk">must</strong> call <code>prepareMaterial(material)</code> before exiting the  <code>material()</code> function.
-This <code>prepareMaterial</code> function sets up the internal state of the material mdoel. Some of the APIs
+This <code>prepareMaterial</code> function sets up the internal state of the material model. Some of the APIs
 described in the Fragment APIs section - like <code>shading_normal</code> for instance - can only be accessed
 <em class="underscore">after</em> invoking <code>prepareMaterial()</code>.
 
@@ -2616,7 +2640,7 @@ type aliases:
 <p>
 
 </p><div class="table"><table class="table"><tbody><tr><th style="text-align:left"> Name </th><th style="text-align:center"> Type </th><th style="text-align:left"> Description </th></tr>
-<tr><td style="text-align:left"> <strong class="asterisk">getResolution()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Resolution of the view in pixels: <code>width</code>, <code>height</code>, <code>1 / width</code>, <code>1 / height</code> </td></tr>
+<tr><td style="text-align:left"> <strong class="asterisk">getResolution()</strong> </td><td style="text-align:center"> float4 </td><td style="text-align:left"> Dimensions of the view's effective viewport in pixels: <code>width</code>, <code>height</code>, <code>1 / width</code>, <code>1 / height</code>. This might be different from <code>View::getViewport()</code> for instance because of added rendering guard-bands. This can be used in conjunction with <code>getNormalizedViewportCoord()</code> to generate pixel coordinates. </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getWorldCameraPosition()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> Position of the camera/eye in world space </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getWorldOffset()</strong> </td><td style="text-align:center"> float3 </td><td style="text-align:left"> The shift required to obtain API-level world space </td></tr>
 <tr><td style="text-align:left"> <strong class="asterisk">getTime()</strong> </td><td style="text-align:center"> float </td><td style="text-align:left"> Current time as a remainder of 1 second. Yields a value between 0 and 1 </td></tr>
@@ -2821,7 +2845,9 @@ variants:
 </li>
 <li class="minus"><code>fog</code>, used when global fog is applied to the scene
 </li>
-<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver</li></ul>
+<li class="minus"><code>vsm</code>, used when VSM shadows are enabled and the object is a shadow receiver
+</li>
+<li class="minus"><code>ssr</code>, used when screen-space reflections are enabled in the View</li></ul>
 
 <p></p><p>
 

docs/Materials.md.html

@@ -1119,13 +1119,35 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: instanced
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Allows a material to access the instance index (i.e.: **`gl_InstanceIndex`**) of instanced
+     primitives using `getInstanceIndex()` in the material's shader code. Never use
+     **`gl_InstanceIndex`** directly. This is typically used with
+     `RenderableManager::Builder::instances()`. `getInstanceIndex()` is available in both the
+     vertex and fragment shader.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    instanced : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Vertex and attributes: requires
 
 Type
 :    array of `string`
 
 Value
-:     Each entry must be any of `uv0`, `uv1`, `color`, `position`, `tangents`.
+:     Each entry must be any of `uv0`, `uv1`, `color`, `position`, `tangents`, `custom0`
+      through `custom7`.
 
 Description
 :     Lists the vertex attributes required by the material. The `position` attribute is always
@@ -1142,7 +1164,8 @@ material {
         },
     ],
     requires : [
-        uv0
+        uv0,
+        custom0
     ],
     shadingModel : lit,
 }
@@ -1151,6 +1174,7 @@ fragment {
     void material(inout MaterialInputs material) {
         prepareMaterial(material);
         material.baseColor = texture(materialParams_texture, getUV0());
+        material.baseColor.rgb *= getCustom0().rgb;
     }
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1841,13 +1865,30 @@ struct MaterialVertexInputs {
     of the current mesh: `material.uv0 = vec2(mesh_uv0.x, 1.0 - mesh_uv0.y)`. You can control
     this behavior using the `flipUV` property and setting it to `false`.
 
+### Custom vertex attributes
+
+You can use up to 8 custom vertex attributes, all of type `float4`. These attributes can be accessed
+using the vertex block shader functions `getCustom0()` to `getCustom7()`. However, before using
+custom attributes, you *must* declare those attributes as required in the `requires` property of
+the material:
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    requires : [
+        custom0,
+        custom1,
+        custom2
+    ]
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ## Fragment block
 
-The fragment block must be used to control the fragment shading stage of the material. The vertex
+The fragment block must be used to control the fragment shading stage of the material. The fragment
 block must contain valid
 [ESSL 3.0](https://www.khronos.org/registry/OpenGL/specs/es/3.0/GLSL_ES_Specification_3.00.pdf)
 code (the version of GLSL supported in OpenGL ES 3.0). You are free to create multiple functions
-inside the vertex block but you **must** declare the `material` function:
+inside the fragment block but you **must** declare the `material` function:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GLSL
 fragment {
@@ -1882,7 +1923,7 @@ fragment {
 ### prepareMaterial function
 
 Note that you **must** call `prepareMaterial(material)` before exiting the  `material()` function.
-This `prepareMaterial` function sets up the internal state of the material mdoel. Some of the APIs
+This `prepareMaterial` function sets up the internal state of the material model. Some of the APIs
 described in the Fragment APIs section - like `shading_normal` for instance - can only be accessed
 _after_ invoking `prepareMaterial()`.
 
@@ -2169,7 +2210,7 @@ type aliases:
 
                  Name               |   Type   |            Description
 :-----------------------------------|:--------:|:------------------------------------
-**getResolution()**                 | float4   |  Resolution of the view in pixels: `width`, `height`, `1 / width`, `1 / height`
+**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
 **getTime()**                       | float    |  Current time as a remainder of 1 second. Yields a value between 0 and 1

docs/viewer/filament-viewer.js

@@ -15,22 +15,17 @@
 */
 
 // If you are bundling this with rollup, webpack, or esbuild, the following URL should be trimmed.
-import { LitElement, html, css } from "https://unpkg.com/lit-element?module";
+import { LitElement, html, css } from "https://unpkg.com/lit?module";
 
-// To allow the DOM to render before the Filament WASM module is ready, we maintain a little
-// queue of tasks that get invoked as soon as the module is done loading.
+// This little utility checks if the Filament module is ready for action.
+// If so, it immediately calls the given function. If not, it asks the Filament
+// loader to call it as soon as the module becomes ready.
 class FilamentTasks {
-    constructor() {
-        this.tasks = []
-        if (!Filament.Engine) {
-            Filament.init([], () => { for (const task of this.tasks) task(); });
-        }
-    }
     add(callback) {
-        if (!Filament.Engine) {
-            this.tasks.push(callback);
-        } else {
+        if (Filament.isReady) {
             callback();
+        } else {
+            Filament.init([], callback);
         }
     }
 }
@@ -68,6 +63,7 @@ class FilamentViewer extends LitElement {
         this.sky = null;          // Path to skybox ktx.
         this.enableDrop = null;   // Enables drag and drop.
         this.intensity = 30000;   // Intensity of the image based light.
+        this.materialVariant = 0; // Index of material variant.
 
         // Private properties:
         this.filamentTasks = new FilamentTasks();
@@ -84,6 +80,7 @@ class FilamentViewer extends LitElement {
             sky: { type: String },
             enableDrop: { type: Boolean },
             intensity: { type: Number },
+            materialVariant: { type: Number },
         }
     }
 
@@ -116,6 +113,7 @@ class FilamentViewer extends LitElement {
         if (props.has("intensity") && this.indirectLight) {
             this.indirectLight.setIntensity(this.intensity);
         }
+        if (props.has("materialVariant") && this.asset) this._applyMaterialVariant();
     }
 
     static get styles() {
@@ -248,7 +246,7 @@ class FilamentViewer extends LitElement {
             return response.arrayBuffer();
         }).then(arrayBuffer => {
             const ktxData = new Uint8Array(arrayBuffer);
-            this.indirectLight = this.engine.createIblFromKtx(ktxData);
+            this.indirectLight = this.engine.createIblFromKtx1(ktxData);
             this.indirectLight.setIntensity(this.intensity);
             this.scene.setIndirectLight(this.indirectLight);
         });
@@ -266,7 +264,7 @@ class FilamentViewer extends LitElement {
             return response.arrayBuffer();
         }).then(arrayBuffer => {
             const ktxData = new Uint8Array(arrayBuffer);
-            this.skybox = this.engine.createSkyFromKtx(ktxData);
+            this.skybox = this.engine.createSkyFromKtx1(ktxData);
             this.scene.setSkybox(this.skybox);
         });
     }
@@ -311,7 +309,7 @@ class FilamentViewer extends LitElement {
                 asyncInterval: 30
             };
 
-            const doneAddingResources = resourceLoader => {
+            const doneAddingResources = (resourceLoader, stbProvider, ktx2Provider) => {
                 this.srcBlobResources = {};
                 resourceLoader.asyncBeginLoad(this.asset);
                 const timer = setInterval(() => {
@@ -320,6 +318,8 @@ class FilamentViewer extends LitElement {
                     if (progress >= 1) {
                         clearInterval(timer);
                         resourceLoader.delete();
+                        stbProvider.delete();
+                        ktx2Provider.delete();
                         this.animator = this.asset.getAnimator();
                         this.animationStartTime = Date.now();
                     }
@@ -337,13 +337,20 @@ class FilamentViewer extends LitElement {
                     config.recomputeBoundingBoxes,
                     config.ignoreBindTransform);
 
+                const stbProvider = new Filament.gltfio$StbProvider(this.engine);
+                const ktx2Provider = new Filament.gltfio$Ktx2Provider(this.engine);
+
+                resourceLoader.addStbProvider("image/jpeg", stbProvider);
+                resourceLoader.addStbProvider("image/png", stbProvider);
+                resourceLoader.addKtx2Provider("image/ktx2", ktx2Provider);
+
                 let remaining = Object.keys(this.srcBlobResources).length;
                 for (const name in this.srcBlobResources) {
                     this.srcBlobResources[name].arrayBuffer().then(buffer => {
                         const desc = getBufferDescriptor(new Uint8Array(buffer));
                         resourceLoader.addResourceData(name, getBufferDescriptor(desc));
                         if (--remaining === 0) {
-                            doneAddingResources(resourceLoader);
+                            doneAddingResources(resourceLoader, stbProvider, ktx2Provider);
                         }
                     });
                 }
@@ -375,6 +382,7 @@ class FilamentViewer extends LitElement {
             this.asset.loadResources(() => {
                 this.animator = this.asset.getAnimator();
                 this.animationStartTime = Date.now();
+                this._applyMaterialVariant();
             }, null, basePath);
 
             this._updateOverlay();
@@ -383,9 +391,11 @@ class FilamentViewer extends LitElement {
 
     _updateAsset() {
         // Invoke the first glTF animation if it exists.
-        if (this.animator && this.animator.getAnimationCount() > 0) {
-            const ms = Date.now() - this.animationStartTime;
-            this.animator.applyAnimation(0, ms / 1000);
+        if (this.animator) {
+            if (this.animator.getAnimationCount() > 0) {
+                const ms = Date.now() - this.animationStartTime;
+                this.animator.applyAnimation(0, ms / 1000);
+            }
             this.animator.updateBoneMatrices();
         }
 
@@ -426,6 +436,20 @@ class FilamentViewer extends LitElement {
 
         window.requestAnimationFrame(this._renderFrame.bind(this));
     }
+
+    _applyMaterialVariant() {
+        if (!this.hasAttribute("materialVariant")) {
+            return;
+        }
+        const names = this.asset.getMaterialVariantNames();
+        const index = this.materialVariant;
+        if (index < 0 || index >= names.length) {
+            console.error(`Material variant ${index} does not exist in this asset.`);
+            return;
+        }
+        console.info(this.src, `Applying material variant: ${names[index]}`);
+        this.asset.applyMaterialVariant(index);
+    }
 }
 
 customElements.define("filament-viewer", FilamentViewer);

docs/viewer/index.html

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

filament/CMakeLists.txt

@@ -63,6 +63,7 @@ set(SRCS
         src/FrameSkipper.cpp
         src/Froxelizer.cpp
         src/Frustum.cpp
+        src/HwRenderPrimitiveFactory.cpp
         src/IndexBuffer.cpp
         src/IndirectLight.cpp
         src/LightManager.cpp
@@ -77,6 +78,7 @@ set(SRCS
         src/RenderTarget.cpp
         src/RenderableManager.cpp
         src/Renderer.cpp
+        src/RendererUtils.cpp
         src/ResourceAllocator.cpp
         src/ResourceList.cpp
         src/Scene.cpp
@@ -130,6 +132,7 @@ set(SRCS
 
 set(PRIVATE_HDRS
         src/Allocators.h
+        src/BufferPoolAllocator.h
         src/ColorSpace.h
         src/Culler.h
         src/DFG.h
@@ -138,11 +141,13 @@ set(PRIVATE_HDRS
         src/FrameInfo.h
         src/FrameSkipper.h
         src/Froxelizer.h
+        src/HwRenderPrimitiveFactory.h
         src/Intersections.h
         src/MaterialParser.h
         src/PerViewUniforms.h
         src/PIDController.h
         src/PostProcessManager.h
+        src/RendererUtils.h
         src/RenderPass.h
         src/RenderPrimitive.h
         src/ResourceAllocator.h
@@ -454,6 +459,34 @@ add_custom_command(
         APPEND
 )
 
+add_custom_command(
+        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur1L.filamat"
+        DEPENDS src/materials/separableGaussianBlur.vs
+        DEPENDS src/materials/separableGaussianBlur.fs
+        APPEND
+)
+
+add_custom_command(
+        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur2L.filamat"
+        DEPENDS src/materials/separableGaussianBlur.vs
+        DEPENDS src/materials/separableGaussianBlur.fs
+        APPEND
+)
+
+add_custom_command(
+        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur3L.filamat"
+        DEPENDS src/materials/separableGaussianBlur.vs
+        DEPENDS src/materials/separableGaussianBlur.fs
+        APPEND
+)
+
+add_custom_command(
+        OUTPUT "${MATERIAL_DIR}/separableGaussianBlur4L.filamat"
+        DEPENDS src/materials/separableGaussianBlur.vs
+        DEPENDS src/materials/separableGaussianBlur.fs
+        APPEND
+)
+
 add_custom_command(
         OUTPUT ${RESGEN_OUTPUTS}
         COMMAND resgen ${RESGEN_FLAGS} ${MATERIAL_BINS}

filament/README.md

@@ -44,10 +44,11 @@ To link against debug builds of Filament, you must also link against:
 
 - `matdbg`, Support library that adds an interactive web-based debugger to Filament
 
-To use the Vulkan backend on macOS you must also make the following libraries available at runtime:
-- `MoltenVK_icd.json`
-- `libMoltenVK.dylib`
-- `libvulkan.1.dylib`
+To use the Vulkan backend on macOS you must install the LunarG SDK, enable "System Global
+Components", and reboot your machine.
+
+The easiest way to install those files is to use the macOS
+[LunarG Vulkan SDK](https://www.lunarg.com/vulkan-sdk/) installer.
 
 ## Linking against Filament
 

filament/backend/CMakeLists.txt

@@ -65,8 +65,6 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
             src/opengl/gl_headers.h
             src/opengl/GLUtils.cpp
             src/opengl/GLUtils.h
-            src/opengl/OpenGLBlitter.cpp
-            src/opengl/OpenGLBlitter.h
             src/opengl/OpenGLContext.cpp
             src/opengl/OpenGLContext.h
             src/opengl/OpenGLDriver.cpp
@@ -89,7 +87,6 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
     endif ()
     if (ANDROID)
         list(APPEND SRCS src/opengl/platforms/ExternalStreamManagerAndroid.cpp)
-        list(APPEND SRCS src/android/ExternalTextureManagerAndroid.cpp)
         list(APPEND SRCS src/opengl/platforms/PlatformEGLAndroid.cpp)
     elseif (IOS)
         list(APPEND SRCS src/opengl/platforms/PlatformCocoaTouchGL.mm)
@@ -101,6 +98,8 @@ if (FILAMENT_SUPPORTS_OPENGL AND NOT FILAMENT_USE_EXTERNAL_GLES3 AND NOT FILAMEN
     elseif (LINUX)
         if (FILAMENT_SUPPORTS_X11)
             list(APPEND SRCS src/opengl/platforms/PlatformGLX.cpp)
+        elseif (FILAMENT_SUPPORTS_EGL_ON_LINUX)
+            list(APPEND SRCS src/opengl/platforms/PlatformEGLHeadless.cpp)
         endif()
     elseif (WIN32)
         list(APPEND SRCS src/opengl/platforms/PlatformWGL.cpp)
@@ -307,6 +306,9 @@ endif()
 
 if (LINUX)
     target_link_libraries(${TARGET} PRIVATE dl)
+    if(FILAMENT_SUPPORTS_EGL_ON_LINUX)
+       target_link_libraries(${TARGET} PUBLIC EGL)
+    endif()
 endif()
 
 # ==================================================================================================
@@ -392,6 +394,8 @@ if (APPLE)
         test/test_MRT.cpp
         test/test_LoadImage.cpp
         test/test_RenderExternalImage.cpp
+        test/test_StencilBuffer.cpp
+        test/test_Scissor.cpp
         )
 
     target_link_libraries(backend_test PRIVATE
@@ -440,16 +444,3 @@ if (APPLE AND NOT IOS)
     target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
 endif()
 
-if (APPLE AND NOT Vulkan_LIBRARY AND NOT FILAMENT_USE_SWIFTSHADER)
-    message(STATUS "No Vulkan SDK was found, using prebuilt MoltenVK.")
-    set(MOLTENVK_DIR "../../third_party/moltenvk")
-    configure_file(
-            ${MOLTENVK_DIR}/libvulkan.1.dylib
-            ${PROJECT_BINARY_DIR}/libvulkan.1.dylib COPYONLY)
-    configure_file(
-            ${MOLTENVK_DIR}/MoltenVK_icd.json
-            ${PROJECT_BINARY_DIR}/MoltenVK_icd.json COPYONLY)
-    configure_file(
-            ${MOLTENVK_DIR}/libMoltenVK.dylib
-            ${PROJECT_BINARY_DIR}/libMoltenVK.dylib COPYONLY)
-endif()

filament/backend/include/backend/DriverEnums.h

@@ -42,22 +42,22 @@
  */
 namespace filament::backend {
 
-static constexpr uint64_t SWAP_CHAIN_CONFIG_TRANSPARENT = 0x1;
-static constexpr uint64_t SWAP_CHAIN_CONFIG_READABLE = 0x2;
-static constexpr uint64_t SWAP_CHAIN_CONFIG_ENABLE_XCB = 0x4;
+static constexpr uint64_t SWAP_CHAIN_CONFIG_TRANSPARENT         = 0x1;
+static constexpr uint64_t SWAP_CHAIN_CONFIG_READABLE            = 0x2;
+static constexpr uint64_t SWAP_CHAIN_CONFIG_ENABLE_XCB          = 0x4;
 static constexpr uint64_t SWAP_CHAIN_CONFIG_APPLE_CVPIXELBUFFER = 0x8;
 
-static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT = 16; // This is guaranteed by OpenGL ES.
-static constexpr size_t MAX_VERTEX_SAMPLER_COUNT = 16;   // This is guaranteed by OpenGL ES.
-static constexpr size_t MAX_FRAGMENT_SAMPLER_COUNT = 16; // This is guaranteed by OpenGL ES.
-static constexpr size_t MAX_SAMPLER_COUNT = 32;          // This is guaranteed by OpenGL ES.
-static constexpr size_t MAX_VERTEX_BUFFER_COUNT = 16;    // Max number of bound buffer objects.
+static constexpr size_t MAX_VERTEX_ATTRIBUTE_COUNT  = 16;   // This is guaranteed by OpenGL ES.
+static constexpr size_t MAX_VERTEX_SAMPLER_COUNT    = 16;   // This is guaranteed by OpenGL ES.
+static constexpr size_t MAX_FRAGMENT_SAMPLER_COUNT  = 16;   // This is guaranteed by OpenGL ES.
+static constexpr size_t MAX_SAMPLER_COUNT           = 32;   // This is guaranteed by OpenGL ES.
+static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
 
 static_assert(MAX_VERTEX_BUFFER_COUNT <= MAX_VERTEX_ATTRIBUTE_COUNT,
         "The number of buffer objects that can be attached to a VertexBuffer must be "
         "less than or equal to the maximum number of vertex attributes.");
 
-static constexpr size_t CONFIG_BINDING_COUNT = 8;
+static constexpr size_t CONFIG_BINDING_COUNT = 12;  // This is guaranteed by OpenGL ES.
 
 /**
  * Selects which driver a particular Engine should use.
@@ -128,7 +128,6 @@ inline constexpr TargetBufferFlags getTargetBufferFlagsAt(size_t index) noexcept
 enum class BufferUsage : uint8_t {
     STATIC,      //!< content modified once, used many times
     DYNAMIC,     //!< content modified frequently, used many times
-    STREAM,      //!< content invalidated and modified frequently, used many times
 };
 
 /**
@@ -719,7 +718,7 @@ enum class SamplerCompareMode : uint8_t {
     COMPARE_TO_TEXTURE = 1
 };
 
-//! comparison function for the depth sampler
+//! comparison function for the depth / stencil sampler
 enum class SamplerCompareFunc : uint8_t {
     // don't change the enums values
     LE = 0,     //!< Less or equal
@@ -728,11 +727,11 @@ enum class SamplerCompareFunc : uint8_t {
     G,          //!< Strictly greater than
     E,          //!< Equal
     NE,         //!< Not equal
-    A,          //!< Always. Depth testing is deactivated.
-    N           //!< Never. The depth test always fails.
+    A,          //!< Always. Depth / stencil testing is deactivated.
+    N           //!< Never. The depth / stencil test always fails.
 };
 
-//! Sampler paramters
+//! Sampler parameters
 struct SamplerParams { // NOLINT
     union {
         struct {
@@ -785,10 +784,21 @@ enum class BlendFunction : uint8_t {
     SRC_ALPHA_SATURATE      //!< f(src, dst) = (1,1,1) * min(src.a, 1 - dst.a), 1
 };
 
+//! stencil operation
+enum class StencilOperation : uint8_t {
+    KEEP,                   //!< Keeps the current value.
+    ZERO,                   //!< Sets the value to 0.
+    REPLACE,                //!< Sets the value to the stencil reference value.
+    INCR,                   //!< Increments the current value. Clamps to the maximum representable unsigned value.
+    INCR_WRAP,              //!< Increments the current value. Wraps value to zero when incrementing the maximum representable unsigned value.
+    DECR,                   //!< Decrements the current value. Clamps to 0.
+    DECR_WRAP,              //!< Decrements the current value. Wraps value to the maximum representable unsigned value when decrementing a value of zero.
+    INVERT,                 //!< Bitwise inverts the current value.
+};
+
 //! Stream for external textures
 enum class StreamType {
     NATIVE,     //!< Not synchronized but copy-free. Good for video.
-    TEXTURE_ID, //!< Synchronized, but GL-only and incurs copies. Good for AR on devices before API 26.
     ACQUIRED,   //!< Synchronized, copy-free, and take a release callback. Good for AR but requires API 26+.
 };
 
@@ -818,9 +828,11 @@ struct RasterState {
     using DepthFunc = backend::SamplerCompareFunc;
     using BlendEquation = backend::BlendEquation;
     using BlendFunction = backend::BlendFunction;
+    using StencilFunction = backend::SamplerCompareFunc;
+    using StencilOperation = backend::StencilOperation;
 
     RasterState() noexcept { // NOLINT
-        static_assert(sizeof(RasterState) == sizeof(uint32_t),
+        static_assert(sizeof(RasterState) == sizeof(uint64_t),
                 "RasterState size not what was intended");
         culling = CullingMode::BACK;
         blendEquationRGB = BlendEquation::ADD;
@@ -829,6 +841,10 @@ struct RasterState {
         blendFunctionSrcAlpha = BlendFunction::ONE;
         blendFunctionDstRGB = BlendFunction::ZERO;
         blendFunctionDstAlpha = BlendFunction::ZERO;
+        stencilFunc = StencilFunction::A;
+        stencilOpStencilFail = StencilOperation::KEEP;
+        stencilOpDepthFail = StencilOperation::KEEP;
+        stencilOpDepthStencilPass = StencilOperation::KEEP;
     }
 
     bool operator == (RasterState rhs) const noexcept { return u == rhs.u; }
@@ -857,40 +873,56 @@ struct RasterState {
     union {
         struct {
             //! culling mode
-            CullingMode culling                 : 2;        //  2
+            CullingMode culling                         : 2;        //  2
 
             //! blend equation for the red, green and blue components
-            BlendEquation blendEquationRGB      : 3;        //  5
+            BlendEquation blendEquationRGB              : 3;        //  5
             //! blend equation for the alpha component
-            BlendEquation blendEquationAlpha    : 3;        //  8
+            BlendEquation blendEquationAlpha            : 3;        //  8
 
             //! blending function for the source color
-            BlendFunction blendFunctionSrcRGB   : 4;        // 12
+            BlendFunction blendFunctionSrcRGB           : 4;        // 12
             //! blending function for the source alpha
-            BlendFunction blendFunctionSrcAlpha : 4;        // 16
+            BlendFunction blendFunctionSrcAlpha         : 4;        // 16
             //! blending function for the destination color
-            BlendFunction blendFunctionDstRGB   : 4;        // 20
+            BlendFunction blendFunctionDstRGB           : 4;        // 20
             //! blending function for the destination alpha
-            BlendFunction blendFunctionDstAlpha : 4;        // 24
+            BlendFunction blendFunctionDstAlpha         : 4;        // 24
 
             //! Whether depth-buffer writes are enabled
-            bool depthWrite                     : 1;        // 25
+            bool depthWrite                             : 1;        // 25
             //! Depth test function
-            DepthFunc depthFunc                 : 3;        // 28
+            DepthFunc depthFunc                         : 3;        // 28
 
             //! Whether color-buffer writes are enabled
-            bool colorWrite                     : 1;        // 29
+            bool colorWrite                             : 1;        // 29
 
             //! use alpha-channel as coverage mask for anti-aliasing
-            bool alphaToCoverage                : 1;        // 30
+            bool alphaToCoverage                        : 1;        // 30
 
             //! whether front face winding direction must be inverted
-            bool inverseFrontFaces              : 1;        // 31
+            bool inverseFrontFaces                      : 1;        // 31
 
+            //! Whether stencil-buffer writes are enabled
+            bool stencilWrite                           : 1;        // 32
+            //! Stencil reference value
+            uint8_t stencilRef                          : 8;        // 40
+            //! Stencil test function
+            StencilFunction stencilFunc                 : 3;        // 43
+            //! Stencil operation when stencil test fails
+            StencilOperation stencilOpStencilFail       : 3;        // 46
             //! padding, must be 0
-            uint8_t padding                     : 1;        // 32
+            uint8_t padding0                            : 2;        // 48
+            //! Stencil operation when stencil test passes but depth test fails
+            StencilOperation stencilOpDepthFail         : 3;        // 51
+            //! Stencil operation when both stencil and depth test pass
+            StencilOperation stencilOpDepthStencilPass  : 3;        // 54
+            //! padding, must be 0
+            uint8_t padding1                            : 2;        // 56
+            //! padding, must be 0
+            uint8_t padding2                            : 8;        // 64
         };
-        uint32_t u = 0;
+        uint64_t u = 0;
     };
 };
 
@@ -913,7 +945,7 @@ struct ShaderStageFlags {
                (fragment && type == ShaderType::FRAGMENT);
     }
 };
-static constexpr ShaderStageFlags ALL_SHADER_STAGE_FLAGS = { .vertex = true, .fragment = true };
+static constexpr ShaderStageFlags ALL_SHADER_STAGE_FLAGS = { true, true };
 
 /**
  * Selects which buffers to clear at the beginning of the render pass, as well as which buffers

filament/backend/include/backend/Handle.h

@@ -26,6 +26,7 @@
 #include <stdint.h>
 
 #include <limits>
+#include <type_traits>
 
 namespace filament::backend {
 

filament/backend/include/private/backend/CommandStream.h

@@ -34,6 +34,7 @@
 #include <utils/compiler.h>
 #include <utils/ThreadUtils.h>
 
+#include <cstddef>
 #include <functional>
 #include <tuple>
 #include <thread>

filament/backend/include/private/backend/Driver.h

@@ -26,6 +26,8 @@
 
 #include <utils/compiler.h>
 
+#include <functional>
+
 #include <stdint.h>
 
 // Command debugging off. debugging virtuals are not called.

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

@@ -217,7 +217,14 @@ DECL_DRIVER_API_R_N(backend::TextureHandle, importTexture,
 DECL_DRIVER_API_R_N(backend::SamplerGroupHandle, createSamplerGroup,
         uint32_t, size)
 
-DECL_DRIVER_API_R_0(backend::RenderPrimitiveHandle, createRenderPrimitive)
+DECL_DRIVER_API_R_N(backend::RenderPrimitiveHandle, createRenderPrimitive,
+        backend::VertexBufferHandle, vbh,
+        backend::IndexBufferHandle, ibh,
+        backend::PrimitiveType, pt,
+        uint32_t, offset,
+        uint32_t, minIndex,
+        uint32_t, maxIndex,
+        uint32_t, count)
 
 DECL_DRIVER_API_R_N(backend::ProgramHandle, createProgram,
         backend::Program&&, program)
@@ -246,11 +253,6 @@ DECL_DRIVER_API_R_N(backend::SwapChainHandle, createSwapChainHeadless,
         uint32_t, height,
         uint64_t, flags)
 
-DECL_DRIVER_API_R_N(backend::StreamHandle, createStreamFromTextureId,
-        intptr_t, externalTextureId,
-        uint32_t, width,
-        uint32_t, height)
-
 DECL_DRIVER_API_R_0(backend::TimerQueryHandle, createTimerQuery)
 
 
@@ -323,6 +325,14 @@ DECL_DRIVER_API_N(updateBufferObject,
         backend::BufferDescriptor&&, data,
         uint32_t, byteOffset)
 
+DECL_DRIVER_API_N(updateBufferObjectUnsynchronized,
+        backend::BufferObjectHandle, ibh,
+        backend::BufferDescriptor&&, data,
+        uint32_t, byteOffset)
+
+DECL_DRIVER_API_N(resetBufferObject,
+        backend::BufferObjectHandle, ibh)
+
 DECL_DRIVER_API_N(updateSamplerGroup,
         backend::SamplerGroupHandle, ubh,
         backend::SamplerGroup&&, samplerGroup)
@@ -382,19 +392,6 @@ DECL_DRIVER_API_0(endRenderPass)
 
 DECL_DRIVER_API_0(nextSubpass)
 
-DECL_DRIVER_API_N(setRenderPrimitiveBuffer,
-        backend::RenderPrimitiveHandle, rph,
-        backend::VertexBufferHandle, vbh,
-        backend::IndexBufferHandle, ibh)
-
-DECL_DRIVER_API_N(setRenderPrimitiveRange,
-        backend::RenderPrimitiveHandle, rph,
-        backend::PrimitiveType, pt,
-        uint32_t, offset,
-        uint32_t, minIndex,
-        uint32_t, maxIndex,
-        uint32_t, count)
-
 DECL_DRIVER_API_N(beginTimerQuery,
         backend::TimerQueryHandle, query)
 
@@ -461,14 +458,6 @@ DECL_DRIVER_API_N(readPixels,
         uint32_t, height,
         backend::PixelBufferDescriptor&&, data)
 
-DECL_DRIVER_API_N(readStreamPixels,
-        backend::StreamHandle, sh,
-        uint32_t, x,
-        uint32_t, y,
-        uint32_t, width,
-        uint32_t, height,
-        backend::PixelBufferDescriptor&&, data)
-
 /*
  * Rendering operations
  * --------------------

filament/backend/include/private/backend/OpenGLPlatform.h

@@ -82,15 +82,6 @@ public:
     virtual void detach(Stream* stream) noexcept = 0;
     virtual void updateTexImage(Stream* stream, int64_t* timestamp) noexcept = 0;
 
-    // external texture storage
-    virtual ExternalTexture* createExternalTextureStorage() noexcept = 0;
-
-    // this is called synchronously in the application thread (NOT the Driver thread)
-    virtual void reallocateExternalStorage(ExternalTexture* ets,
-            uint32_t w, uint32_t h, TextureFormat format) noexcept = 0;
-
-    virtual void destroyExternalTextureStorage(ExternalTexture* ets) noexcept = 0;
-
     // The method allows platforms to convert a user-supplied external image object into a new type
     // (e.g. HardwareBuffer => EGLImage). It makes sense for the default implementation to do nothing.
     virtual AcquiredImage transformAcquiredImage(AcquiredImage source) noexcept { return source; }

filament/backend/include/private/backend/Program.h

@@ -67,6 +67,8 @@ public:
             utils::Invocable<utils::io::ostream&(utils::io::ostream& out)>&& logger);
 
     // sets one of the program's shader (e.g. vertex, fragment)
+    // string-based shaders are null terminated, consequently the size parameter must include the
+    // null terminating character.
     Program& shader(Shader shader, void const* data, size_t size) noexcept;
 
     // sets the 'bindingPoint' uniform block's name for this program.
@@ -84,10 +86,14 @@ public:
     Program& setSamplerGroup(size_t bindingPoint, ShaderStageFlags stageFlags,
             Sampler const* samplers, size_t count) noexcept;
 
+    // string-based shaders are null terminated, consequently the size parameter must include the
+    // null terminating character.
     Program& withVertexShader(void const* data, size_t size) {
         return shader(Shader::VERTEX, data, size);
     }
 
+    // string-based shaders are null terminated, consequently the size parameter must include the
+    // null terminating character.
     Program& withFragmentShader(void const* data, size_t size) {
         return shader(Shader::FRAGMENT, data, size);
     }

filament/backend/include/private/backend/SamplerGroup.h

@@ -17,17 +17,18 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 
-#include <array>
-#include <stddef.h>
-
 #include <utils/compiler.h>
 #include <utils/bitset.h>
 
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 
-namespace filament {
-namespace backend {
+#include <array>
+#include <memory>
+
+#include <stddef.h>
+
+namespace filament::backend {
 
 class SamplerGroup {
 public:
@@ -151,7 +152,6 @@ private:
     mutable utils::bitset32 mDirty;
 };
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
 
 #endif // TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H

filament/backend/src/DataReshaper.h

@@ -58,26 +58,16 @@ public:
         }
     }
 
-    // Converts a 4-channel image of UBYTE, INT, UINT, or FLOAT to a different type.
+    // Converts a n-channel image of UBYTE, INT, UINT, or FLOAT to a different type.
     template<typename dstComponentType, typename srcComponentType>
     static void reshapeImage(uint8_t* dest, const uint8_t* src,  size_t srcBytesPerRow,
-            size_t dstBytesPerRow, size_t dstChannelCount, size_t height, bool swizzle, bool flip) {
-        const size_t srcChannelCount = 4;
+            size_t srcChannelCount, size_t dstBytesPerRow, size_t dstChannelCount,
+            size_t width, size_t height, bool swizzle) {
         const dstComponentType dstMaxValue = getMaxValue<dstComponentType>();
         const srcComponentType srcMaxValue = getMaxValue<srcComponentType>();
-        const size_t width = (srcBytesPerRow / sizeof(srcComponentType)) / srcChannelCount;
         const size_t minChannelCount = filament::math::min(srcChannelCount, dstChannelCount);
         assert_invariant(minChannelCount <= 4);
         const int inds[4] = {swizzle ? 2 : 0, 1, swizzle ? 0 : 2, 3};
-
-        int srcStride;
-        if (flip) {
-            src += srcBytesPerRow * (height - 1);
-            srcStride = -srcBytesPerRow;
-        } else {
-            srcStride = srcBytesPerRow;
-        }
-
         for (size_t row = 0; row < height; ++row) {
             const srcComponentType* in = (const srcComponentType*) src;
             dstComponentType* out = (dstComponentType*) dest;
@@ -97,15 +87,15 @@ public:
                 in += srcChannelCount;
                 out += dstChannelCount;
             }
-            src += srcStride;
+            src += srcBytesPerRow;
             dest += dstBytesPerRow;
         }
     }
 
-    // Converts a 4-channel image of UBYTE, INT, UINT, or FLOAT to a different type.
+    // Converts a n-channel image of UBYTE, INT, UINT, or FLOAT to a different type.
     static bool reshapeImage(PixelBufferDescriptor* dst, PixelDataType srcType,
-            const uint8_t* srcBytes, int srcBytesPerRow, int width, int height, bool swizzle,
-            bool flip) {
+            uint32_t srcChannelCount,  const uint8_t* srcBytes, int srcBytesPerRow, int width,
+            int height, bool swizzle) {
         size_t dstChannelCount;
         switch (dst->format) {
             case PixelDataFormat::R_INTEGER: dstChannelCount = 1; break;
@@ -118,8 +108,9 @@ public:
             case PixelDataFormat::RGBA: dstChannelCount = 4; break;
             default: return false;
         }
-        void (*reshaper)(uint8_t*, const uint8_t*, size_t, size_t, size_t, size_t, bool, bool)
-                = nullptr;
+        void (*reshaper)(uint8_t* dest, const uint8_t* src, size_t srcBytesPerRow,
+                size_t srcChannelCount, size_t dstBytesPerRow, size_t dstChannelCount,
+                size_t width, size_t height, bool swizzle) = nullptr;
         constexpr auto UBYTE = PixelDataType::UBYTE, FLOAT = PixelDataType::FLOAT,
                 UINT = PixelDataType::UINT, INT = PixelDataType::INT;
         switch (dst->type) {
@@ -165,11 +156,10 @@ public:
         uint8_t* dstBytes = (uint8_t*) dst->buffer;
         const int dstBytesPerRow = PixelBufferDescriptor::computeDataSize(dst->format, dst->type,
                 dst->stride ? dst->stride : width, 1, dst->alignment);
-        reshaper(dstBytes, srcBytes, srcBytesPerRow, dstBytesPerRow, dstChannelCount, height,
-                swizzle, flip);
+        reshaper(dstBytes, srcBytes, srcBytesPerRow, srcChannelCount, dstBytesPerRow,
+                dstChannelCount, width, height, swizzle);
         return true;
     }
-
 };
 
 template<> inline float getMaxValue() { return 1.0f; }

filament/backend/src/Platform.cpp

@@ -53,6 +53,10 @@
         #if defined (FILAMENT_DRIVER_SUPPORTS_VULKAN)
             #include "vulkan/PlatformVkLinuxX11.h"
         #endif
+    #elif defined(FILAMENT_SUPPORTS_EGL_ON_LINUX)
+        #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
+            #include "opengl/platforms/PlatformEGLHeadless.h"
+        #endif
     #endif
 #elif defined(WIN32)
     #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3) && !defined(FILAMENT_USE_SWIFTSHADER)
@@ -157,6 +161,8 @@ DefaultPlatform* DefaultPlatform::create(Backend* backend) noexcept {
         #elif defined(__linux__)
             #if defined(FILAMENT_SUPPORTS_X11)
                 return new PlatformGLX();
+            #elif defined(FILAMENT_SUPPORTS_EGL_ON_LINUX)
+                return new PlatformEGLHeadless();
             #endif
         #elif defined(WIN32)
             return new PlatformWGL();

filament/backend/src/android/ExternalTextureManagerAndroid.cpp

@@ -1,222 +0,0 @@
-/*
- * Copyright (C) 2018 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-
-#include "ExternalTextureManagerAndroid.h"
-
-#include <utils/api_level.h>
-#include <utils/compiler.h>
-#include <utils/Log.h>
-
-#include <dlfcn.h>
-
-using namespace utils;
-
-namespace filament::backend {
-
-template <typename T>
-static void loadSymbol(T*& pfn, const char *symbol) noexcept {
-    pfn = (T*)dlsym(RTLD_DEFAULT, symbol);
-}
-
-// ------------------------------------------------------------------------------------------------
-
-namespace ndk {
-/*
- * This mimics the GraphicBuffer class for pre-API 26
- */
-template<typename NATIVE_TYPE, typename REF>
-struct ANativeObjectBase : public NATIVE_TYPE, public REF {
-};
-
-struct android_native_base_t {
-    unsigned int magic;
-    unsigned int version;
-    void* reserved[4];
-    void (* incRef)(struct android_native_base_t* base);
-    void (* decRef)(struct android_native_base_t* base);
-};
-
-struct ANativeWindowBuffer {
-    struct android_native_base_t common;
-    unsigned int width;
-    unsigned int height;
-    unsigned int stride;
-    unsigned int format;
-    unsigned int usage_deprecated;
-    uintptr_t layerCount;
-    void* reserved[1];
-    const void* handle;
-    uint64_t usage;
-    void* reserved_proc[8 - (sizeof(uint64_t) / sizeof(void*))];
-};
-
-struct RefBase {
-    virtual ~RefBase() = default;
-    void* ref;
-};
-
-struct GraphicBuffer : public ANativeObjectBase<ANativeWindowBuffer, RefBase> {
-};
-struct GraphicBufferWrapper {
-    GraphicBuffer* graphicBuffer;
-};
-} // namespace ndk
-
-// ------------------------------------------------------------------------------------------------
-using namespace ndk;
-
-struct EGLExternalTexture : public ExternalTextureManagerAndroid::ExternalTexture {
-    GraphicBufferWrapper* graphicBufferWrapper = nullptr;
-};
-
-ExternalTextureManagerAndroid& ExternalTextureManagerAndroid::create() noexcept {
-    return *(new ExternalTextureManagerAndroid{});
-}
-
-void ExternalTextureManagerAndroid::destroy(ExternalTextureManagerAndroid* pExternalTextureManager) noexcept {
-    delete pExternalTextureManager;
-}
-
-// called on gl thread
-ExternalTextureManagerAndroid::ExternalTextureManagerAndroid() noexcept
-        : mVm(VirtualMachineEnv::get()) {
-}
-
-// not quite sure on which thread this is going to be called
-ExternalTextureManagerAndroid::~ExternalTextureManagerAndroid() noexcept {
-    if (__builtin_available(android 26, *)) {
-    } else {
-        if (mGraphicBufferClass) {
-            JNIEnv* env = VirtualMachineEnv::getThreadEnvironment();
-            if (env) {
-                env->DeleteGlobalRef(mGraphicBufferClass);
-            }
-        }
-    }
-}
-
-// called on gl thread
-Platform::ExternalTexture* ExternalTextureManagerAndroid::createExternalTexture() noexcept {
-    if (__builtin_available(android 26, *)) {
-    } else {
-        // initialize java stuff on-demand
-        if (!mGraphicBufferClass) {
-            JNIEnv* env = mVm.getEnvironment();
-            mGraphicBufferClass = env->FindClass("android/view/GraphicBuffer");
-            mGraphicBuffer_nCreateGraphicBuffer = env->GetStaticMethodID(
-                    mGraphicBufferClass, "nCreateGraphicBuffer", "(IIII)J");
-            mGraphicBuffer_nDestroyGraphicBuffer = env->GetStaticMethodID(
-                    mGraphicBufferClass, "nDestroyGraphicBuffer", "(J)V");
-
-            mGraphicBufferClass = static_cast<jclass>(env->NewGlobalRef(mGraphicBufferClass));
-        }
-    }
-    EGLExternalTexture* ets = new EGLExternalTexture;
-    return ets;
-}
-
-// called on app thread
-void ExternalTextureManagerAndroid::reallocate(
-        Platform::ExternalTexture* ets, uint32_t w, uint32_t h,
-        TextureFormat format, uint64_t usage) noexcept {
-    destroyStorage(ets);
-    alloc(ets, w, h, format, usage);
-}
-
-// called on gl thread
-void ExternalTextureManagerAndroid::destroy(Platform::ExternalTexture* ets) noexcept {
-    destroyStorage(ets);
-    delete static_cast<EGLExternalTexture*>(ets);
-}
-
-// called on app thread
-void ExternalTextureManagerAndroid::alloc(
-        Platform::ExternalTexture* t,
-        uint32_t w, uint32_t h, TextureFormat format, uint64_t usage) noexcept {
-
-    EGLExternalTexture* ets = static_cast<EGLExternalTexture*>(t);
-
-    AHardwareBuffer_Desc desc = { w, h, 1, 0, usage, 0, 0, 0 };
-    switch (format) {
-        case TextureFormat::RGB8:
-            // don't use R8G8B8 here because some drivers produce garbled images
-            desc.format = AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM;
-            break;
-        case TextureFormat::RGBA8:
-            desc.format = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM;
-            break;
-        case TextureFormat::RGB565:
-            desc.format = AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM;
-            break;
-        case TextureFormat::RGB10_A2:
-            desc.format = AHARDWAREBUFFER_FORMAT_R10G10B10A2_UNORM;
-            break;
-        default:
-            slog.e << "Unsupported format " << (int)format << ", use RGBA8 or RGB8 only."
-                   << io::endl;
-            return;
-    }
-
-    if (__builtin_available(android 26, *)) {
-        // allocate new storage...
-        AHardwareBuffer* buffer = nullptr;
-        if (AHardwareBuffer_allocate(&desc, &buffer) < 0) {
-            slog.e << "AHardwareBuffer_allocate() failed" << io::endl;
-            return;
-        }
-        ets->hardwareBuffer = buffer;
-    } else {
-        // note: This is called on the application thread (not the GL thread)
-        JNIEnv* env = VirtualMachineEnv::getThreadEnvironment();
-        if (!env) {
-            return; // this should not happen
-        }
-
-        jlong graphicBufferWrapperJni = env->CallStaticLongMethod(mGraphicBufferClass,
-                mGraphicBuffer_nCreateGraphicBuffer, w, h, desc.format, usage);
-        VirtualMachineEnv::handleException(env);
-
-        if (graphicBufferWrapperJni) {
-            GraphicBuffer* const gb = ((GraphicBufferWrapper*)graphicBufferWrapperJni)->graphicBuffer;
-            ets->graphicBufferWrapper = (GraphicBufferWrapper*)graphicBufferWrapperJni;
-            ets->clientBuffer = static_cast<ANativeWindowBuffer*>(gb);
-        }
-    }
-}
-
-// called on gl thread
-void ExternalTextureManagerAndroid::destroyStorage(Platform::ExternalTexture* t) noexcept {
-        EGLExternalTexture* ets = static_cast<EGLExternalTexture*>(t);
-    if (__builtin_available(android 26, *)) {
-        // destroy the current storage if any
-        if (ets->hardwareBuffer) {
-            AHardwareBuffer_release(ets->hardwareBuffer);
-            ets->hardwareBuffer = nullptr;
-        }
-    } else {
-        if (ets->graphicBufferWrapper) {
-            JNIEnv* env = VirtualMachineEnv::get().getEnvironment();
-            env->CallStaticVoidMethod(mGraphicBufferClass,
-                    mGraphicBuffer_nDestroyGraphicBuffer, (jlong)ets->graphicBufferWrapper);
-            VirtualMachineEnv::handleException(env);
-            ets->graphicBufferWrapper = nullptr;
-        }
-    }
-}
-
-} // namespace filament::backend
-

filament/backend/src/android/ExternalTextureManagerAndroid.h

@@ -1,84 +0,0 @@
-/*
- * Copyright (C) 2018 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.
- */
-
-#ifndef TNT_FILAMENT_DRIVER_ANDROID_EXTERNAL_TEXTURE_MANAGER_ANDROID_H
-#define TNT_FILAMENT_DRIVER_ANDROID_EXTERNAL_TEXTURE_MANAGER_ANDROID_H
-
-#include "private/backend/VirtualMachineEnv.h"
-
-#include <backend/DriverEnums.h>
-#include <backend/Platform.h>
-
-#include <android/api-level.h>
-#include <android/hardware_buffer.h>
-
-namespace filament::backend {
-
-/*
- * ExternalTextureManagerAndroid::ExternalTexture is basically a wrapper for AHardwareBuffer.
- *
- * This class doesn't rely on GL or EGL, and could be used for other Android platform if needed
- * (e.g. Vulkan).
- *
- * ExternalTextureManagerAndroid handle allocation/destruction using either Java or the NDK,
- * whichever is available.
- */
-class ExternalTextureManagerAndroid {
-public:
-
-    struct ExternalTexture : public Platform::ExternalTexture {
-        void* clientBuffer = nullptr;
-        AHardwareBuffer* hardwareBuffer = nullptr;
-    };
-
-    // must be called on backend thread
-    static ExternalTextureManagerAndroid& create() noexcept;
-
-    // must be called on backend thread
-    static void destroy(ExternalTextureManagerAndroid* pExternalTextureManager) noexcept;
-
-    // must be called on backend thread (only because we don't synchronize
-    Platform::ExternalTexture* createExternalTexture() noexcept;
-
-    // called on app thread
-    void reallocate(
-        Platform::ExternalTexture* ets, uint32_t w, uint32_t h,
-        TextureFormat format, uint64_t usage) noexcept;
-
-    // must be called on backend thread
-    void destroy(Platform::ExternalTexture* ets) noexcept;
-
-private:
-    ExternalTextureManagerAndroid() noexcept;
-    ~ExternalTextureManagerAndroid() noexcept;
-
-    // called on app thread
-    void alloc(Platform::ExternalTexture* ets,
-               uint32_t w, uint32_t h, TextureFormat format, uint64_t usage) noexcept;
-
-    // called on gl thread
-    void destroyStorage(Platform::ExternalTexture* ets) noexcept;
-
-    VirtualMachineEnv& mVm;
-
-    jclass mGraphicBufferClass = nullptr;
-    jmethodID mGraphicBuffer_nCreateGraphicBuffer = nullptr;
-    jmethodID mGraphicBuffer_nDestroyGraphicBuffer = nullptr;
-};
-
-} // namespace filament::backend
-
-#endif // TNT_FILAMENT_DRIVER_ANDROID_EXTERNAL_TEXTURE_MANAGER_ANDROID_H

filament/backend/src/metal/MetalBuffer.h

@@ -42,7 +42,8 @@ public:
      * Update the buffer with data inside src. Potentially allocates a new buffer allocation to hold
      * the bytes which will be released when the current frame is finished.
      */
-    void copyIntoBuffer(void* src, size_t size, size_t byteOffset = 0);
+    void copyIntoBuffer(void* src, size_t size, size_t byteOffset);
+    void copyIntoBufferUnsynchronized(void* src, size_t size, size_t byteOffset);
 
     /**
      * Denotes that this buffer is used for a draw call ensuring that its allocation remains valid
@@ -57,12 +58,6 @@ public:
      */
     id<MTLBuffer> getGpuBufferForDraw(id<MTLCommandBuffer> cmdBuffer) noexcept;
 
-    /**
-     * Returns the offset into the buffer returned by getGpuBufferForDraw. This is always 0 for
-     * non-STREAM buffers.
-     */
-    size_t getGpuBufferStreamOffset() noexcept { return mCurrentStreamStart; }
-
     void* getCpuBuffer() const noexcept { return mCpuBuffer; }
 
     enum Stage {
@@ -84,13 +79,9 @@ private:
 
     BufferUsage mUsage;
     size_t mBufferSize = 0;
-    size_t mCurrentStreamStart = 0;
-    size_t mCurrentStreamEnd = 0;
     const MetalBufferPoolEntry* mBufferPoolEntry = nullptr;
     void* mCpuBuffer = nullptr;
     MetalContext& mContext;
-
-    void copyIntoStreamBuffer(void* src, size_t size);
 };
 
 } // namespace backend

filament/backend/src/metal/MetalBuffer.mm

@@ -28,11 +28,6 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferUsage usage, size_t size,
     // If the buffer is less than 4K in size and is updated frequently, we don't use an explicit
     // buffer. Instead, we use immediate command encoder methods like setVertexBytes:length:atIndex:.
     if (size <= 4 * 1024) {
-        // We'll take the same approach for STREAM buffers under 4K.
-        if (usage == BufferUsage::STREAM) {
-            usage = BufferUsage::DYNAMIC;
-        }
-
         if (usage == BufferUsage::DYNAMIC && !forceGpuBuffer) {
             mBufferPoolEntry = nullptr;
             mCpuBuffer = malloc(size);
@@ -61,13 +56,6 @@ void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
             "Attempting to copy %d bytes into a buffer of size %d at offset %d",
             size, mBufferSize, byteOffset);
 
-    if (mUsage == BufferUsage::STREAM) {
-        // byteOffset must be 0 for STREAM buffers.
-        assert_invariant(byteOffset == 0);
-        copyIntoStreamBuffer(src, size);
-        return;
-    }
-
     // Either copy into the Metal buffer or into our cpu buffer.
     if (mCpuBuffer) {
         memcpy(static_cast<uint8_t*>(mCpuBuffer) + byteOffset, src, size);
@@ -84,32 +72,9 @@ void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
     memcpy(static_cast<uint8_t*>(mBufferPoolEntry->buffer.contents) + byteOffset, src, size);
 }
 
-void MetalBuffer::copyIntoStreamBuffer(void* src, size_t size) {
-    // Stream buffers are handled a bit differently. In STREAM mode, we have a single large buffer.
-    // At each update we "advance" into the buffer, keeping track of the where we're at, and bind
-    // the buffer at that location. Effectively, "byteOffset" is managed automatically.
-
-    assert_invariant(size <= mBufferSize);
-    assert_invariant(!mCpuBuffer);
-
-    mCurrentStreamStart = mCurrentStreamEnd;
-    mCurrentStreamEnd += size;
-
-    if (mCurrentStreamEnd > mBufferSize) {
-        // Allocate a new buffer and reset the stream offset.
-        mCurrentStreamStart = 0;
-        mCurrentStreamEnd = size;
-
-        if (mBufferPoolEntry) { mContext.bufferPool->releaseBuffer(mBufferPoolEntry); }
-        mBufferPoolEntry = mContext.bufferPool->acquireBuffer(mBufferSize);
-    }
-
-    // Lazily acquire a new buffer if we haven't already.
-    if (!mBufferPoolEntry) {
-        mBufferPoolEntry = mContext.bufferPool->acquireBuffer(mBufferSize);
-    }
-
-    memcpy(static_cast<uint8_t*>(mBufferPoolEntry->buffer.contents) + mCurrentStreamStart, src, size);
+void MetalBuffer::copyIntoBufferUnsynchronized(void* src, size_t size, size_t byteOffset) {
+    // TODO: implement the unsynchronized version
+    copyIntoBuffer(src, size, byteOffset);
 }
 
 id<MTLBuffer> MetalBuffer::getGpuBufferForDraw(id<MTLCommandBuffer> cmdBuffer) noexcept {
@@ -163,7 +128,7 @@ void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLRenderComman
             continue;
         }
         metalBuffers[b] = gpuBuffer;
-        metalOffsets[b] = offsets[b] + buffer->mCurrentStreamStart;
+        metalOffsets[b] = offsets[b];
     }
 
     if (stages & Stage::VERTEX) {

filament/backend/src/metal/MetalContext.h

@@ -116,6 +116,8 @@ struct MetalContext {
 
     std::stack<const char*> groupMarkers;
 
+    MTLViewport currentViewport;
+
 #if defined(FILAMENT_METAL_PROFILING)
     // Logging and profiling.
     os_log_t log;