Fix Android release build (#6133)

to emulate the bindless API in the gl backend we always used the highest
texture unit available. However at feature level 3, we support up to 62
textures, so the that max was bumped to 62 -- however, where we're not
on a feature level 2 device, that texture unit doesn't exist.

Instead we now always use binding 31, which is guaranteed to exist by 
EGL's minspec.

BUILDING.md

@@ -15,7 +15,7 @@ To build Filament for Android you must also install the following:
 
 - Android Studio Arctic Fox or more recent
 - Android SDK
-- Android NDK "side-by-side" 23.1 or higher
+- Android NDK 25.1 or higher
 
 ### Environment variables
 
@@ -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.9.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 python ./emsdk.py install latest
 python ./emsdk.py activate latest
@@ -365,13 +368,11 @@ export EMSDK=<your chosen home for the emscripten SDK>
 
 The EMSDK variable is required so that the build script can find the Emscripten SDK. The build
 creates a `samples` folder that can be used as the root of a simple static web server. Note that you
-cannot open the HTML directly from the filesystem due to CORS. One way to deal with this is to
-use Python to create a quick localhost server:
+cannot open the HTML directly from the filesystem due to CORS. We recommend using the emrun tool
+to create a quick localhost server:
 
 ```
-cd out/cmake-webgl-release/web/samples
-python3 -m http.server     # Python 3
-python -m SimpleHTTPServer # Python 2.7
+emrun out/cmake-webgl-release/web/samples --no_browser --port 8000
 ```
 
 You can then open http://localhost:8000/suzanne.html in your web browser.

CMakeLists.txt

@@ -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)
@@ -33,16 +35,16 @@ set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
 
-set(FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB "2" CACHE STRING
-    "Per render pass arena size. Must be roughly 1 MB larger than FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB, default 2."
+set(FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB "3" CACHE STRING
+    "Per render pass arena size. Must be roughly 1 MB larger than FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB, default 3."
 )
 
-set(FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB "1" CACHE STRING
-    "Size of the high-level draw commands buffer. Rule of thumb, 1 MB less than FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB, default 1."
+set(FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB "2" CACHE STRING
+    "Size of the high-level draw commands buffer. Rule of thumb, 1 MB less than FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB, default 2."
 )
 
-set(FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB "1" CACHE STRING
-    "Size of the command-stream buffer. As a rule of thumb use the same value as FILAMENT_PER_FRRAME_COMMANDS_SIZE_IN_MB, default 1."
+set(FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB "2" CACHE STRING
+    "Size of the command-stream buffer. As a rule of thumb use the same value as FILAMENT_PER_FRRAME_COMMANDS_SIZE_IN_MB, default 2."
 )
 
 set(FILAMENT_OPENGL_HANDLE_ARENA_SIZE_IN_MB "4" CACHE STRING
@@ -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()
@@ -350,6 +359,10 @@ if (WEBGL)
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fno-rtti")
 endif()
 
+if (WEBGL_PTHREADS)
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pthread")
+endif()
+
 # ==================================================================================================
 # Debug compiler flags
 # ==================================================================================================
@@ -392,8 +405,8 @@ endif()
 set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS}")
 
-if (WEBGL)
-    set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s USE_WEBGL2=1")
+if (WEBGL_PTHREADS)
+    set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -pthread")
 endif()
 
 # ==================================================================================================
@@ -584,15 +597,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()
 
 # ==================================================================================================
@@ -699,7 +703,9 @@ if (IS_HOST_PLATFORM)
     if (FILAMENT_SUPPORTS_OPENGL)
         add_subdirectory(${LIBRARIES}/bluegl)
     endif()
-    add_subdirectory(${LIBRARIES}/filamentapp)
+    if (NOT FILAMENT_SKIP_SDL2)
+      add_subdirectory(${LIBRARIES}/filamentapp)
+    endif()
     add_subdirectory(${LIBRARIES}/imageio)
 
     add_subdirectory(${FILAMENT}/samples)

CODE_STYLE.md

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

README.md

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

RELEASE_GUIDE.md

@@ -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

@@ -5,6 +5,103 @@ A new header is inserted each time a *tag* is created.
 
 ## main branch
 
+## v1.27.2
+
+- gltfio: punctual lights are now duplicated when adding new asset instances
+- gltfio: FilamentInstance getAsset method now returns an immutable asset
+- gltfio: allow zero-instance assets
+- gltfio: fix regression with meshes that have no material
+- gltfio: fix regression with recomputeBoundingBoxes()
+- filamesh / matinfo: fix minor ASAN issues
+
+## v1.27.1
+
+- Java: add methods for TransformManager.getChildCount(), TransformManager.getChildren() and Scene.hasEntity()
+- engine: Fix stencil buffer writes with OpenGL backend.
+- gltfio: add new virtual method to MaterialProvider that all plugins must implement
+- gltfio: add an assert for inconsistent sRGB flags among usages of a particular texture
+- engine: improve scissor documentation
+- backend: scissor is no longer clipped to the viewport (done on filament side)
+- samples: add debug overdraw visualization to gltf_viewer
+
+## v1.27.0
+
+- WebGL: reduce max instance count to work around Chrome issues [⚠️ **Recompile Materials**]
+- engine: rework material/shader sampler binding code [⚠️ **Recompile Materials**]
+- gltfio: move the API for `recomputeBoundingBoxes` [⚠️ **API Change**]
+- engine: add support for specialization constants [⚠️ **Recompile Materials**]
+- gltfio: fix spotlight regression
+- gltfio: clear the MaterialInstance cache when creating new instances
+
+## v1.26.0
+
+- engine: new feature level APIs, see `Engine::getSupportedFeatureLevel()`
+- engine: add new stencil API to `View` and stencil state APIs to `MaterialInstance` [**NEW API**].
+- engine: Fix guard bands and TAA with `vertexDomain:Device` [⚠️ **Recompile Materials**]
+- engine: `clipSpaceTransform` is now only available with `vertexDomain:Device` [⚠️ **API Change**]
+- gltfio: add unified `AssetLoader::createAsset()` method [⚠️ **API Change**]
+- gltfio: all assets are now "instanced" [⚠️ **API Change**]
+
+## v1.25.6
+
+- engine: Add `CONFIG_MINSPEC_UBO_SIZE` as a nicer way to allow exceeding the ES3.0 minspec.
+- gltfio: minor efficiency improvement for Android and WebGL builds.
+- gltfio: add support for concurrent texture downloading and decoding.
+
+## v1.25.5
+
+- WebGL: upgraded the JS bindings to work with emsdk 3.1.15
+- WebGL: added missing IBL builder to TypeScript annotations
+- engine: Fix incorrect precision restoration when computing accurate world translations
+- engine: make `MaterialInstance` public API friendly to `std::string_view` parameters
+- gltfio: add 'detach' methods to allow ownership transfer of entities and components
+
+## v1.25.4
+
+- backend: streamline texture upload APIs [⚠️ **API Change**]
+
+## v1.25.3
+
+- engine: Fix Adreno gpu crash introduced by gpu morph target change
+- engine: Add optional memory configuration parameters to Engine initialization
+
+## 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.

android/build.gradle

@@ -29,15 +29,12 @@
 
 // Publishing to Maven Central:
 //   - Build and upload artifacts with ./gradlew publish
-//   - Close and release staging repo on Nexus with ./gradlew closeAndReleaseRepository
+//   - Close and release staging repo on Nexus with ./gradlew closeAndReleaseStagingRepository
 //
 // The following is needed in ~/gradle/gradle.properties:
 //
-//     SONATYPE_NEXUS_USERNAME=nexus_user
-//     SONATYPE_NEXUS_PASSWORD=nexus_password
-//
-//     nexusUsername=nexus_user
-//     nexusPassword=nexus_password
+//     sonatypeUsername=nexus_user
+//     sonatypePassword=nexus_password
 //
 //     signing.keyId=pgp_key_id
 //     signing.password=pgp_key_password
@@ -47,7 +44,7 @@
 buildscript {
     def path = providers
             .gradleProperty("com.google.android.filament.dist-dir")
-            .forUseAtConfigurationTime().get()
+            .get()
 
     def directory = objects.fileProperty().fileValue(new File(path)).getAsFile().get()
     def filamentPath = directory.absolutePath
@@ -59,18 +56,15 @@ buildscript {
     // Warning: changing this property does not work well with incremental builds.
     def excludeVulkan = providers
             .gradleProperty("com.google.android.filament.exclude-vulkan")
-            .forUseAtConfigurationTime()
             .isPresent()
 
     def matdbg = providers
             .gradleProperty("com.google.android.filament.matdbg")
-            .forUseAtConfigurationTime()
             .isPresent()
 
     def abis = ["arm64-v8a", "armeabi-v7a", "x86_64", "x86"]
     def newAbis = providers
             .gradleProperty("com.google.android.filament.abis")
-            .forUseAtConfigurationTime()
             .get()
             .split(',')
     if (!newAbis.contains("all")) {
@@ -79,18 +73,20 @@ buildscript {
 
     ext.versions = [
         'minSdk': 19,
-        'targetSdk': 31,
-        'compileSdk': 31,
-        'kotlin': '1.6.21',
+        'targetSdk': 33,
+        'compileSdk': 33,
+        'kotlin': '1.7.10',
         'kotlin_coroutines': '1.6.1',
-        'buildTools': '32.0.0',
-        'ndk': '24.0.8215888'
+        'buildTools': '33.0.0',
+        'ndk': '25.1.8937393',
+        'androidx_core': '1.9.0',
+        'androidx_annotations': '1.3.0'
     ]
 
     ext.deps = [
         'androidx': [
-            'annotations': "androidx.annotation:annotation:1.3.0",
-            'core': "androidx.core:core:1.7.0",
+            'annotations': "androidx.annotation:annotation:${versions.androidx_annotations}",
+            'core': "androidx.core:core:${versions.androidx_core}",
         ],
         'kotlin': "org.jetbrains.kotlin:kotlin-stdlib-jdk8:${versions.kotlin}",
         'coroutines': [
@@ -101,7 +97,7 @@ buildscript {
 
     dependencies {
         // NOTE: See TODO in gradle.properties once we move to Gradle 7.4
-        classpath 'com.android.tools.build:gradle:7.2.0'
+        classpath 'com.android.tools.build:gradle:7.3.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 
@@ -148,14 +144,18 @@ buildscript {
 }
 
 plugins {
-    id 'io.codearte.nexus-staging' version '0.30.0'
+    id "io.github.gradle-nexus.publish-plugin" version "1.1.0"
 }
 
-// Nexus Staging configuration
-// See https://github.com/Codearte/gradle-nexus-staging-plugin/
-nexusStaging {
+// See https://github.com/gradle-nexus/publish-plugin
+// Publish to https://oss.sonatype.org/ (not s01)
+nexusPublishing {
     packageGroup = 'com.google.android'
-    stagingProfileId = '9a75a224a4f17b'
+    repositories {
+        sonatype {
+            stagingProfileId = '9a75a224a4f17b'
+        }
+    }
 }
 
 subprojects {

android/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,36 @@ 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();
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nGetSupportedFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->getSupportedFeatureLevel();
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nSetActiveFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine, jint ordinal) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->setActiveFeatureLevel((Engine::FeatureLevel)ordinal);
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jint)engine->getActiveFeatureLevel();
+}

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

@@ -341,6 +341,14 @@ Java_com_google_android_filament_MaterialInstance_nSetDepthWrite(JNIEnv*,
     instance->setDepthWrite(enable);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilWrite(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jboolean enable) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilWrite(enable);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_MaterialInstance_nSetDepthCulling(JNIEnv*,
@@ -349,6 +357,70 @@ Java_com_google_android_filament_MaterialInstance_nSetDepthCulling(JNIEnv*,
     instance->setDepthCulling(enable);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilCompareFunction(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong function, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilCompareFunction(
+            static_cast<MaterialInstance::StencilCompareFunc>(function),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpStencilFail(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpStencilFail(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpDepthFail(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpDepthFail(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilOpDepthStencilPass(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jlong op, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilOpDepthStencilPass(
+            static_cast<MaterialInstance::StencilOperation>(op),
+            static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilReferenceValue(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint value, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilReferenceValue(value, static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilReadMask(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint readMask, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilReadMask(readMask, static_cast<MaterialInstance::StencilFace>(face));
+}
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetStencilWriteMask(JNIEnv*, jclass,
+        jlong nativeMaterialInstance, jint writeMask, jlong face) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setStencilWriteMask(writeMask, static_cast<MaterialInstance::StencilFace>(face));
+}
+
 extern "C"
 JNIEXPORT jstring JNICALL
 Java_com_google_android_filament_MaterialInstance_nGetName(JNIEnv* env, jclass,

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

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

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

@@ -188,69 +188,6 @@ Java_com_google_android_filament_Texture_nGetInternalFormat(JNIEnv*, jclass,
     return (jint) texture->getFormat();
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_Texture_nSetImage(JNIEnv* env, jclass, jlong nativeTexture,
-        jlong nativeEngine, jint level, 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) {
-    Texture* texture = (Texture*) nativeTexture;
-    Engine* engine = (Engine*) nativeEngine;
-
-    size_t sizeInBytes = getTextureDataSize(texture, (size_t) level, (Texture::Format) format,
-            (Texture::Type) type, (size_t) stride, (size_t) height, (size_t) alignment);
-
-    AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
-        // BufferOverflowException
-        return -1;
-    }
-
-    void *buffer = nioBuffer.getData();
-    auto *callback = JniBufferCallback::make(engine, env, handler, runnable, std::move(nioBuffer));
-
-    Texture::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);
-
-    texture->setImage(*engine, (size_t) level, (uint32_t) xoffset, (uint32_t) yoffset,
-            (uint32_t) width, (uint32_t) height, std::move(desc));
-
-    return 0;
-}
-
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_Texture_nSetImageCompressed(JNIEnv *env, jclass,
-        jlong nativeTexture, jlong nativeEngine, jint level, jint xoffset, jint yoffset,
-        jint width, jint height, jobject storage,  jint remaining,
-        jint, jint, jint, jint, jint compressedSizeInBytes, jint compressedFormat,
-        jobject handler, jobject runnable) {
-    Texture *texture = (Texture *) nativeTexture;
-    Engine *engine = (Engine *) nativeEngine;
-
-    size_t sizeInBytes = (size_t) compressedSizeInBytes;
-
-    AutoBuffer nioBuffer(env, storage, 0);
-    if (sizeInBytes > (size_t(remaining) << nioBuffer.getShift())) {
-        // BufferOverflowException
-        return -1;
-    }
-
-    void *buffer = nioBuffer.getData();
-    auto *callback = JniBufferCallback::make(engine, env, handler, runnable, std::move(nioBuffer));
-
-    Texture::PixelBufferDescriptor desc(buffer, sizeInBytes,
-            (backend::CompressedPixelDataType) compressedFormat, (uint32_t) compressedSizeInBytes,
-            callback->getHandler(), &JniBufferCallback::postToJavaAndDestroy, callback);
-
-    texture->setImage(*engine, (size_t) level, (uint32_t) xoffset, (uint32_t) yoffset,
-            (uint32_t) width, (uint32_t) height, std::move(desc));
-
-    return 0;
-}
-
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Texture_nSetImage3D(JNIEnv* env, jclass, jlong nativeTexture,
         jlong nativeEngine, jint level,
@@ -353,7 +290,10 @@ Java_com_google_android_filament_Texture_nSetImageCubemap(JNIEnv *env, jclass,
             (uint32_t) stride,
             callback->getHandler(), &JniBufferCallback::postToJavaAndDestroy, callback);
 
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     texture->setImage(*engine, (size_t) level, std::move(desc), faceOffsets);
+#pragma clang diagnostic pop
 
     return 0;
 }
@@ -388,7 +328,10 @@ Java_com_google_android_filament_Texture_nSetImageCubemapCompressed(JNIEnv *env,
             (backend::CompressedPixelDataType) compressedFormat, (uint32_t) compressedSizeInBytes,
             callback->getHandler(), &JniBufferCallback::postToJavaAndDestroy, callback);
 
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
     texture->setImage(*engine, (size_t) level, std::move(desc), faceOffsets);
+#pragma clang diagnostic pop
 
     return 0;
 }

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

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

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

@@ -462,6 +462,21 @@ Java_com_google_android_filament_View_nPick(JNIEnv* env, jclass,
     }, callback->getHandler());
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetStencilBufferEnabled(JNIEnv *, jclass, jlong nativeView,
+        jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setStencilBufferEnabled(enabled);
+}
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsStencilBufferEnabled(JNIEnv *, jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return view->isStencilBufferEnabled();
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,

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

@@ -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

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

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

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

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

@@ -20,6 +20,9 @@ import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
 import androidx.annotation.Size;
 
+import com.google.android.filament.proguard.UsedByNative;
+
+@UsedByNative("AssetLoader.cpp")
 public class MaterialInstance {
     private Material mMaterial;
     private String mName;
@@ -49,6 +52,54 @@ public class MaterialInstance {
         MAT4
     }
 
+    /**
+     * Operations that control how the stencil buffer is updated.
+     */
+    public enum StencilOperation {
+        /**
+         * Keeps the current value.
+         */
+        KEEP,
+        /**
+         * Sets the value to 0.
+         */
+        ZERO,
+        /**
+         * Sets the value to the stencil reference value.
+         */
+        REPLACE,
+        /**
+         * Increments the current value. Clamps to the maximum representable unsigned value.
+         */
+        INCR_CLAMP,
+        /**
+         * Increments the current value. Wraps value to zero when incrementing the maximum
+         * representable unsigned value.
+         */
+        INCR_WRAP,
+        /**
+         * Decrements the current value. Clamps to 0.
+         */
+        DECR_CLAMP,
+        /**
+         * Decrements the current value. Wraps value to the maximum representable unsigned value
+         * when decrementing a value of zero.
+         */
+        DECR_WRAP,
+        /**
+         * Bitwise inverts the current value.
+         */
+        INVERT,
+    }
+
+    public enum StencilFace {
+        FRONT,
+        BACK,
+        FRONT_AND_BACK
+    }
+    // Converts the StencilFace enum ordinal to Filament's equivalent bit field.
+    static final int[] sStencilFaceMapping = {0x1, 0x2, 0x3};
+
     public MaterialInstance(Engine engine, long nativeMaterialInstance) {
         mNativeObject = nativeMaterialInstance;
         mNativeMaterial = nGetMaterial(mNativeObject);
@@ -351,19 +402,40 @@ public class MaterialInstance {
     }
 
     /**
-     * Set up a custom scissor rectangle; by default this encompasses the View.
+     * Set-up a custom scissor rectangle; by default it is disabled.
      *
-     * @param left      left coordinate of the scissor box
-     * @param bottom    bottom coordinate of the scissor box
+     * <p>
+     * The scissor rectangle gets clipped by the View's viewport, in other words, the scissor
+     * cannot affect fragments outside of the View's Viewport.
+     * </p>
+     *
+     * <p>
+     * Currently the scissor is not compatible with dynamic resolution and should always be
+     * disabled when dynamic resolution is used.
+     * </p>
+     *
+     * @param left      left coordinate of the scissor box relative to the viewport
+     * @param bottom    bottom coordinate of the scissor box relative to the viewport
      * @param width     width of the scissor box
      * @param height    height of the scissor box
+     *
+     * @see #unsetScissor
+     * @see View#setViewport
+     * @see View#setDynamicResolutionOptions
      */
     public void setScissor(@IntRange(from = 0) int left, @IntRange(from = 0) int bottom,
             @IntRange(from = 0) int width, @IntRange(from = 0) int height) {
         nSetScissor(getNativeObject(), left, bottom, width, height);
     }
 
-    /** Returns the scissor rectangle to its default setting, which encompasses the View. */
+    /**
+     * Returns the scissor rectangle to its default disabled setting.
+     * <p>
+     * Currently the scissor is not compatible with dynamic resolution and should always be
+     * disabled when dynamic resolution is used.
+     * </p>
+     * @see View#setDynamicResolutionOptions
+     */
     public void unsetScissor() {
         nUnsetScissor(getNativeObject());
     }
@@ -473,6 +545,10 @@ public class MaterialInstance {
         nSetDepthWrite(getNativeObject(), enable);
     }
 
+    public void setStencilWrite(boolean enable) {
+        nSetStencilWrite(getNativeObject(), enable);
+    }
+
     /**
      * Overrides the default depth testing state that was set on the material.
      *
@@ -484,6 +560,208 @@ public class MaterialInstance {
         nSetDepthCulling(getNativeObject(), enable);
     }
 
+    /**
+     * Sets the stencil comparison function (default is {@link TextureSampler.CompareFunction#ALWAYS}).
+     *
+     * <p>
+     * It's possible to set separate stencil comparison functions; one for front-facing polygons,
+     * and one for back-facing polygons. The face parameter determines the comparison function(s)
+     * updated by this call.
+     * </p>
+     *
+     * @param func the stencil comparison function
+     * @param face the faces to update the comparison function for
+     */
+    public void setStencilCompareFunction(TextureSampler.CompareFunction func, StencilFace face) {
+        nSetStencilCompareFunction(getNativeObject(), func.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil comparison function for both front and back-facing polygons.
+     * @see #setStencilCompareFunction(TextureSampler.CompareFunction, StencilFace)
+     */
+    public void setStencilCompareFunction(TextureSampler.CompareFunction func) {
+        setStencilCompareFunction(func, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil fail operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The stencil fail operation is performed to update values in the stencil buffer when the
+     * stencil test fails.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil fail operations; one for front-facing polygons, and one
+     * for back-facing polygons. The face parameter determines the stencil fail operation(s) updated
+     * by this call.
+     * </p>
+     *
+     * @param op the stencil fail operation
+     * @param face the faces to update the stencil fail operation for
+     */
+    public void setStencilOpStencilFail(StencilOperation op, StencilFace face) {
+        nSetStencilOpStencilFail(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil fail operation for both front and back-facing polygons.
+     * @see #setStencilOpStencilFail(StencilOperation, StencilFace)
+     */
+    public void setStencilOpStencilFail(StencilOperation op) {
+        setStencilOpStencilFail(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the depth fail operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The depth fail operation is performed to update values in the stencil buffer when the depth
+     * test fails.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate depth fail operations; one for front-facing polygons, and one
+     * for back-facing polygons. The face parameter determines the depth fail operation(s) updated
+     * by this call.
+     * </p>
+     *
+     * @param op the depth fail operation
+     * @param face the faces to update the depth fail operation for
+     */
+    public void setStencilOpDepthFail(StencilOperation op, StencilFace face) {
+        nSetStencilOpDepthFail(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the depth fail operation for both front and back-facing polygons.
+     * @see #setStencilOpDepthFail(StencilOperation, StencilFace)
+     */
+    public void setStencilOpDepthFail(StencilOperation op) {
+        setStencilOpDepthFail(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the depth-stencil pass operation (default is {@link StencilOperation#KEEP}).
+     *
+     * <p>
+     * The depth-stencil pass operation is performed to update values in the stencil buffer when
+     * both the stencil test and depth test pass.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate depth-stencil pass operations; one for front-facing polygons,
+     * and one for back-facing polygons. The face parameter determines the depth-stencil pass
+     * operation(s) updated by this call.
+     * </p>
+     *
+     * @param op the depth-stencil pass operation
+     * @param face the faces to update the depth-stencil operation for
+     */
+    public void setStencilOpDepthStencilPass(StencilOperation op, StencilFace face) {
+        nSetStencilOpDepthStencilPass(getNativeObject(), op.ordinal(),
+                sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the depth-stencil pass operation for both front and back-facing polygons.
+     * @see #setStencilOpDepthStencilPass(StencilOperation, StencilFace)
+     */
+    public void setStencilOpDepthStencilPass(StencilOperation op) {
+        setStencilOpDepthStencilPass(op, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil reference value (default is 0).
+     *
+     * <p>
+     * The stencil reference value is the left-hand side for stencil comparison tests. It's also
+     * used as the replacement stencil value when {@link StencilOperation} is
+     * {@link StencilOperation#REPLACE}.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil reference values; one for front-facing polygons, and
+     * one for back-facing polygons. The face parameter determines the reference value(s) updated by
+     * this call.
+     * </p>
+     *
+     * @param value the stencil reference value (only the least significant 8 bits are used)
+     * @param face the faces to update the reference value for
+     */
+    public void setStencilReferenceValue(@IntRange(from = 0, to = 255) int value, StencilFace face) {
+        nSetStencilReferenceValue(getNativeObject(), value, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil reference value for both front and back-facing polygons.
+     * @see #setStencilReferenceValue(int, StencilFace)
+     */
+    public void setStencilReferenceValue(@IntRange(from = 0, to = 255) int value) {
+        setStencilReferenceValue(value, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil read mask (default is 0xFF).
+     *
+     * <p>
+     * The stencil read mask masks the bits of the values participating in the stencil comparison
+     * test- both the value read from the stencil buffer and the reference value.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil read masks; one for front-facing polygons, and one for
+     * back-facing polygons. The face parameter determines the stencil read mask(s) updated by this
+     * call.
+     * </p>
+     *
+     * @param readMask the read mask (only the least significant 8 bits are used)
+     * @param face the faces to update the read mask for
+     */
+    public void setStencilReadMask(@IntRange(from = 0, to = 255) int readMask, StencilFace face) {
+        nSetStencilReadMask(getNativeObject(), readMask, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil read mask for both front and back-facing polygons.
+     * @see #setStencilReadMask(int, StencilFace)
+     */
+    public void setStencilReadMask(@IntRange(from = 0, to = 255) int readMask) {
+        setStencilReadMask(readMask, StencilFace.FRONT_AND_BACK);
+    }
+
+    /**
+     * Sets the stencil write mask (default is 0xFF).
+     *
+     * <p>
+     * The stencil write mask masks the bits in the stencil buffer updated by stencil operations.
+     * </p>
+     *
+     * <p>
+     * It's possible to set separate stencil write masks; one for front-facing polygons, and one for
+     * back-facing polygons. The face parameter determines the stencil write mask(s) updated by this
+     * call.
+     * </p>
+     *
+     * @param writeMask the write mask (only the least significant 8 bits are used)
+     * @param face the faces to update the read mask for
+     */
+    public void setStencilWriteMask(@IntRange(from = 0, to = 255) int writeMask, StencilFace face) {
+        nSetStencilWriteMask(getNativeObject(), writeMask, sStencilFaceMapping[face.ordinal()]);
+    }
+
+    /**
+     * Sets the stencil write mask for both front and back-facing polygons.
+     * @see #setStencilWriteMask(int, StencilFace)
+     */
+    public void setStencilWriteMask(int writeMask) {
+        setStencilWriteMask(writeMask, StencilFace.FRONT_AND_BACK);
+    }
+
     public long getNativeObject() {
         if (mNativeObject == 0) {
             throw new IllegalStateException("Calling method on destroyed MaterialInstance");
@@ -556,8 +834,24 @@ public class MaterialInstance {
     private static native void nSetCullingMode(long nativeMaterialInstance, long mode);
     private static native void nSetColorWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetDepthWrite(long nativeMaterialInstance, boolean enable);
+    private static native void nSetStencilWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetDepthCulling(long nativeMaterialInstance, boolean enable);
 
+    private static native void nSetStencilCompareFunction(long nativeMaterialInstance,
+            long function, long face);
+    private static native void nSetStencilOpStencilFail(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilOpDepthFail(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilOpDepthStencilPass(long nativeMaterialInstance, long op,
+            long face);
+    private static native void nSetStencilReferenceValue(long nativeMaterialInstance, int value,
+            long face);
+    private static native void nSetStencilReadMask(long nativeMaterialInstance, int readMask,
+            long face);
+    private static native void nSetStencilWriteMask(long nativeMaterialInstance, int writeMask,
+            long face);
+
     private static native String nGetName(long nativeMaterialInstance);
     private static native long nGetMaterial(long nativeMaterialInstance);
 

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

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

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

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

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

@@ -884,7 +884,7 @@ public class Texture {
     // TODO: add a setImage() version that takes an android Bitmap
 
     /**
-     * <code>setImage</code> is used to modify the whole content of the texure from a CPU-buffer.
+     * <code>setImage</code> is used to modify the whole content of the texture from a CPU-buffer.
      *
      *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D SAMPLER_2D} or
      *  {@link Sampler#SAMPLER_EXTERNAL SAMPLER_EXTERNAL}. If the later is specified
@@ -912,7 +912,7 @@ public class Texture {
     public void setImage(@NonNull Engine engine,
             @IntRange(from = 0) int level,
             @NonNull PixelBufferDescriptor buffer) {
-        setImage(engine, level, 0, 0, getWidth(level), getHeight(level), buffer);
+        setImage(engine, level, 0, 0, 0, getWidth(level), getHeight(level), 1, buffer);
     }
 
 
@@ -947,33 +947,15 @@ public class Texture {
             @IntRange(from = 0) int xoffset, @IntRange(from = 0) int yoffset,
             @IntRange(from = 0) int width, @IntRange(from = 0) int height,
             @NonNull PixelBufferDescriptor buffer) {
-        int result;
-        if (buffer.type == COMPRESSED) {
-            result = nSetImageCompressed(getNativeObject(), engine.getNativeObject(), level,
-                    xoffset, yoffset, width, height,
-                    buffer.storage, buffer.storage.remaining(),
-                    buffer.left, buffer.top, buffer.type.ordinal(), buffer.alignment,
-                    buffer.compressedSizeInBytes, buffer.compressedFormat.ordinal(),
-                    buffer.handler, buffer.callback);
-        } else {
-            result = nSetImage(getNativeObject(), engine.getNativeObject(), level,
-                    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();
-        }
+        setImage(engine, level, xoffset, yoffset, 0, width, height, 1, buffer);
     }
 
     /**
-     * <code>setImage</code> is used to modify a sub-region of the 3D texture or 2D texture array
-     * from a CPU-buffer.
+     * <code>setImage</code> is used to modify a sub-region of a 3D texture, 2D texture array or
+     * cubemap from a CPU-buffer. Cubemaps are treated like a 2D array of six layers.
      *
-     *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D_ARRAY SAMPLER_2D_ARRAY} or
-     *  {@link Sampler#SAMPLER_3D SAMPLER_3D}.</p>
+     *  <p>This <code>Texture</code> instance must use {@link Sampler#SAMPLER_2D_ARRAY SAMPLER_2D_ARRAY},
+     *  {@link Sampler#SAMPLER_3D SAMPLER_3D} or {@link Sampler#SAMPLER_CUBEMAP SAMPLER_CUBEMAP}.</p>
      *
      * @param engine    {@link Engine} this texture is associated to. Must be the
      *                  instance passed to {@link Builder#build Builder.build()}.
@@ -1046,7 +1028,9 @@ public class Texture {
      *
      * @see Builder#sampler
      * @see PixelBufferDescriptor
+     * @deprecated use {@link #setImage(Engine, int, int, int, int, int, int, int, PixelBufferDescriptor)}
      */
+     @Deprecated
     public void setImage(@NonNull Engine engine, @IntRange(from = 0) int level,
             @NonNull PixelBufferDescriptor buffer,
             @NonNull @Size(min = 6) int[] faceOffsetsInBytes) {
@@ -1258,18 +1242,6 @@ public class Texture {
     private static native int nGetTarget(long nativeTexture);
     private static native int nGetInternalFormat(long nativeTexture);
 
-    private static native int nSetImage(long nativeTexture, long nativeEngine,
-            int level, int xoffset, int yoffset, int width, int height,
-            Buffer storage, int remaining, int left, int top, int type, int alignment,
-            int stride, int format,
-            Object handler, Runnable callback);
-
-    private static native int nSetImageCompressed(long nativeTexture, long nativeEngine,
-            int level, int xoffset, int yoffset, int width, int height,
-            Buffer storage, int remaining, int left, int top, int type, int alignment,
-            int compressedSizeInBytes, int compressedFormat,
-            Object handler, Runnable callback);
-
     private static native int nSetImage3D(long nativeTexture, long nativeEngine,
             int level, int xoffset, int yoffset, int zoffset, int width, int height, int depth,
             Buffer storage, int remaining, int left, int top, int type, int alignment,

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

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

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

@@ -1011,6 +1011,45 @@ public class View {
         return mDepthOfFieldOptions;
     }
 
+    /**
+     * Enables use of the stencil buffer.
+     *
+     * <p>
+     * The stencil buffer is an 8-bit, per-fragment unsigned integer stored alongside the depth
+     * buffer. The stencil buffer is cleared at the beginning of a frame and discarded after the
+     * color pass.
+     * </p>
+     *
+     * <p>
+     * Each fragment's stencil value is set during rasterization by specifying stencil operations on
+     * a {@link Material}. The stencil buffer can be used as a mask for later rendering by setting a
+     * {@link Material}'s stencil comparison function and reference value. Fragments that don't pass
+     * the stencil test are then discarded.
+     * </p>
+     *
+     * <p>
+     * Post-processing must be enabled in order to use the stencil buffer.
+     * </p>
+     *
+     * <p>
+     * A renderable's priority (see {@link RenderableManager#setPriority(int, int)}) is useful to
+     * control the order in which primitives are drawn.
+     * </p>
+     *
+     * @param enabled True to enable the stencil buffer, false disables it (default)
+     */
+    public void setStencilBufferEnabled(boolean enabled) {
+        nSetStencilBufferEnabled(getNativeObject(), enabled);
+    }
+
+    /**
+     * @return true if the stencil buffer is enabled.
+     * @see View#setStencilBufferEnabled(boolean)
+     */
+    public boolean isStencilBufferEnabled() {
+        return nIsStencilBufferEnabled(getNativeObject());
+    }
+
     /**
      * A class containing the result of a picking query
      */
@@ -1131,6 +1170,8 @@ public class View {
     private static native void nSetGuardBandOptions(long nativeView, boolean enabled);
     private static native boolean nIsScreenSpaceRefractionEnabled(long nativeView);
     private static native void nPick(long nativeView, int x, int y, Object handler, InternalOnPickCallback internalCallback);
+    private static native void nSetStencilBufferEnabled(long nativeView, boolean enabled);
+    private static native boolean nIsStencilBufferEnabled(long nativeView);
 
     /**
      * List of available ambient occlusion techniques.

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

@@ -70,7 +70,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nStartBatchMode(JNIEnv*
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclass klass,
-        jlong nativeAutomation, jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
+        jlong nativeAutomation, jlong nativeEngine,
+        jlong view, jlongArray materials, jlong renderer, jfloat deltaTime) {
     using MaterialPointer = MaterialInstance*;
     jsize materialCount = 0;
     jlong* longMaterials = nullptr;
@@ -90,7 +91,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
         .materials = ptrMaterials,
         .materialCount = (size_t) materialCount,
     };
-    automation->tick(content, deltaTime);
+    Engine* engine = (Engine*)nativeEngine;
+    automation->tick(engine, content, deltaTime);
     if (longMaterials) {
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
         delete[] ptrMaterials;
@@ -99,7 +101,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nTick(JNIEnv* env, jclas
 
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_utils_AutomationEngine_nApplySettings(JNIEnv* env, jclass klass,
-        jlong nativeAutomation, jstring json, jlong view, jlongArray materials, jlong nativeIbl,
+        jlong nativeAutomation, jlong nativeEngine,
+        jstring json, jlong view, jlongArray materials, jlong nativeIbl,
         jint sunlightEntity, jintArray assetLights, jlong nativeLm, jlong scene, jlong renderer) {
     using MaterialPointer = MaterialInstance*;
 
@@ -140,8 +143,8 @@ Java_com_google_android_filament_utils_AutomationEngine_nApplySettings(JNIEnv* e
         .assetLights = (Entity*) intLights,
         .assetLightCount = (size_t) lightCount,
     };
-
-    automation->applySettings(nativeJson, jsonLength, content);
+    Engine* engine = (Engine*)nativeEngine;
+    automation->applySettings(engine, nativeJson, jsonLength, content);
     env->ReleaseStringUTFChars(json, nativeJson);
     if (longMaterials) {
         env->ReleaseLongArrayElements(materials, longMaterials, 0);
@@ -169,6 +172,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 +183,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/java/com/google/android/filament/utils/AutomationEngine.java

@@ -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;
     }
 
     /**
@@ -155,10 +156,11 @@ public class AutomationEngine {
      * This is when settings get applied, screenshots are (optionally) exported, and the internal
      * test counter is potentially incremented.
      *
+     * @param engine        The filament Engine of interest.
      * @param content       Contains the Filament View, Materials, and Renderer that get modified.
      * @param deltaTime     The amount of time that has passed since the previous tick in seconds.
      */
-    public void tick(@NonNull ViewerContent content, float deltaTime) {
+    public void tick(@NonNull Engine engine, @NonNull ViewerContent content, float deltaTime) {
         if (content.view == null || content.renderer == null) {
             throw new IllegalStateException("Must provide a View and Renderer");
         }
@@ -171,7 +173,7 @@ public class AutomationEngine {
         }
         long nativeView = content.view.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nTick(mNativeObject, nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
+        nTick(mNativeObject, engine.getNativeObject(), nativeView, nativeMaterialInstances, nativeRenderer, deltaTime);
     }
 
     /**
@@ -183,10 +185,12 @@ public class AutomationEngine {
      * This updates the stashed Settings object, then pushes those settings to the given
      * Filament objects. Clients can optionally call getColorGrading() after calling this method.
      *
+     * @param engine        Filament Engine to use.
      * @param settingsJson  Contains the JSON string with a set of changes that need to be pushed.
      * @param content       Contains a set of Filament objects that you want to mutate.
      */
-    public void applySettings(@NonNull String settingsJson, @NonNull ViewerContent content) {
+    public void applySettings(@NonNull Engine engine, @NonNull String settingsJson,
+        @NonNull ViewerContent content) {
         if (content.view == null || content.renderer == null) {
             throw new IllegalStateException("Must provide a View and Renderer");
         }
@@ -205,7 +209,8 @@ public class AutomationEngine {
         long nativeLm = content.lightManager.getNativeObject();
         long nativeScene = content.scene.getNativeObject();
         long nativeRenderer = content.renderer.getNativeObject();
-        nApplySettings(mNativeObject, settingsJson, nativeView, nativeMaterialInstances,
+        nApplySettings(mNativeObject, engine.getNativeObject(),
+                settingsJson, nativeView, nativeMaterialInstances,
                 nativeIbl, content.sunlight, content.assetLights, nativeLm, nativeScene,
                 nativeRenderer);
     }
@@ -266,9 +271,10 @@ public class AutomationEngine {
             int minFrameCount, boolean verbose);
     private static native void nStartRunning(long nativeObject);
     private static native void nStartBatchMode(long nativeObject);
-    private static native void nTick(long nativeObject, long view, long[] materials, long renderer,
-            float deltaTime);
-    private static native void nApplySettings(long nativeObject, String jsonSettings, long view,
+    private static native void nTick(long nativeObject, long nativeEngine,
+            long view, long[] materials, long renderer, float deltaTime);
+    private static native void nApplySettings(long nativeObject, long nativeEngine,
+            String jsonSettings, long view,
             long[] materials, long ibl, int sunlight, int[] assetLights, long lightManager,
             long scene, long renderer);
     private static native void nGetViewerOptions(long nativeObject, Object result);

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

@@ -73,8 +73,6 @@ class ModelViewer(
         get() = resourceLoader.asyncGetLoadProgress()
 
     var normalizeSkinningWeights = true
-    var recomputeBoundingBoxes = false
-    var ignoreBindTransform = false
 
     var cameraFocalLength = 28f
         set(value) {
@@ -114,9 +112,9 @@ 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)
+        resourceLoader = ResourceLoader(engine, normalizeSkinningWeights)
 
         // Always add a direct light source since it is required for shadowing.
         // We highly recommend adding an indirect light as well.
@@ -178,7 +176,7 @@ class ModelViewer(
      */
     fun loadModelGlb(buffer: Buffer) {
         destroyModel()
-        asset = assetLoader.createAssetFromBinary(buffer)
+        asset = assetLoader.createAsset(buffer)
         asset?.let { asset ->
             resourceLoader.asyncBeginLoad(asset)
             animator = asset.animator
@@ -193,7 +191,7 @@ class ModelViewer(
      */
     fun loadModelGltf(buffer: Buffer, callback: (String) -> Buffer?) {
         destroyModel()
-        asset = assetLoader.createAssetFromJson(buffer)
+        asset = assetLoader.createAsset(buffer)
         asset?.let { asset ->
             for (uri in asset.resourceUris) {
                 val resourceBuffer = callback(uri)
@@ -216,7 +214,7 @@ class ModelViewer(
      */
     fun loadModelGltfAsync(buffer: Buffer, callback: (String) -> Buffer) {
         destroyModel()
-        asset = assetLoader.createAssetFromJson(buffer)
+        asset = assetLoader.createAsset(buffer)
         fetchResourcesJob = CoroutineScope(Dispatchers.IO).launch {
             fetchResources(asset!!, callback)
         }
@@ -312,8 +310,8 @@ class ModelViewer(
 
     private fun addDetachListener(view: android.view.View) {
         view.addOnAttachStateChangeListener(object : android.view.View.OnAttachStateChangeListener {
-            override fun onViewAttachedToWindow(v: android.view.View?) {}
-            override fun onViewDetachedFromWindow(v: android.view.View?) {
+            override fun onViewAttachedToWindow(v: android.view.View) {}
+            override fun onViewDetachedFromWindow(v: android.view.View) {
                 uiHelper.detach()
 
                 destroyModel()

android/gltfio-android/CMakeLists.txt

@@ -35,9 +35,9 @@ add_library(uberzlib STATIC IMPORTED)
 set_target_properties(uberzlib PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libuberzlib.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(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")
 
@@ -52,6 +52,8 @@ set(GLTFIO_SRCS
         ${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/DependencyGraph.cpp
@@ -71,7 +73,7 @@ set(GLTFIO_SRCS
         ${GLTFIO_DIR}/src/StbProvider.cpp
         ${GLTFIO_DIR}/src/TangentsJob.cpp
         ${GLTFIO_DIR}/src/TangentsJob.h
-        ${GLTFIO_DIR}/src/UbershaderLoader.cpp
+        ${GLTFIO_DIR}/src/UbershaderProvider.cpp
         ${GLTFIO_DIR}/src/Wireframe.cpp
         ${GLTFIO_DIR}/src/Wireframe.h
         ${GLTFIO_DIR}/src/upcast.h
@@ -82,10 +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.h
+        ${FILAMENT_DIR}/include/gltfio/materials/uberarchive.h
 
         ../common/NioUtils.cpp
 )
@@ -93,9 +95,9 @@ 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
@@ -108,7 +110,7 @@ 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)
-target_link_libraries(gltfio-jni filament-jni utils uberzlib log stb ktxreader basis_transcoder zstd gltfio_resources)
+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)

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

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

android/gltfio-android/src/main/cpp/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

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

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

@@ -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
@@ -228,44 +228,6 @@ Java_com_google_android_filament_gltfio_FilamentAsset_nGetExtras(JNIEnv* env, jc
     return val ? env->NewStringUTF(val) : nullptr;
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetSkinCount(JNIEnv* , jclass,
-        jlong nativeAsset) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jint) asset->getSkinCount();
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetSkinNames(JNIEnv* env, jclass,
-        jlong nativeAsset, jobjectArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
-    for (int i = 0; i < available; ++i) {
-        const char* name = asset->getSkinNameAt(i);
-        if (name) {
-            env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
-        }
-    }
-}
-
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetJointCountAt(JNIEnv* , jclass,
-        jlong nativeAsset, jint skinIndex) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    return (jint) asset->getJointCountAt(skinIndex);
-}
-
-extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_gltfio_FilamentAsset_nGetJointsAt(JNIEnv* env, jclass,
-        jlong nativeAsset, jint skinIndex, jintArray result) {
-    FilamentAsset* asset = (FilamentAsset*) nativeAsset;
-    jsize available = env->GetArrayLength(result);
-    Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
-    std::copy_n(asset->getJointsAt(skinIndex),
-        std::min(available, (jsize) asset->getJointCountAt(skinIndex)), entities);
-    env->ReleaseIntArrayElements(result, (jint*) entities, 0);
-}
-
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_gltfio_FilamentAsset_nGetAnimator(JNIEnv* , jclass,
         jlong nativeAsset) {
@@ -340,19 +302,3 @@ 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
@@ -61,3 +61,57 @@ Java_com_google_android_filament_gltfio_FilamentInstance_nApplyMaterialVariant(J
     FilamentInstance* instance = (FilamentInstance*) nativeInstance;
     instance->applyMaterialVariant(variantIndex);
 }
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nAttachSkin(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jint targetEntity) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    Entity target = Entity::import(targetEntity);
+    instance->attachSkin(skinIndex, target);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nDetachSkin(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jint targetEntity) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    Entity target = Entity::import(targetEntity);
+    instance->detachSkin(skinIndex, target);
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetSkinCount(JNIEnv* , jclass,
+        jlong nativeInstance) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return (jint) instance->getSkinCount();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetSkinNames(JNIEnv* env, jclass,
+        jlong nativeInstance, jobjectArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    jsize available = env->GetArrayLength(result);
+    for (int i = 0; i < available; ++i) {
+        const char* name = instance->getSkinNameAt(i);
+        if (name) {
+            env->SetObjectArrayElement(result, (jsize) i, env->NewStringUTF(name));
+        }
+    }
+}
+
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetJointCountAt(JNIEnv* , jclass,
+        jlong nativeInstance, jint skinIndex) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    return (jint) instance->getJointCountAt(skinIndex);
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_gltfio_FilamentInstance_nGetJointsAt(JNIEnv* env, jclass,
+        jlong nativeInstance, jint skinIndex, jintArray result) {
+    FilamentInstance* instance = (FilamentInstance*) nativeInstance;
+    jsize available = env->GetArrayLength(result);
+    Entity* entities = (Entity*) env->GetIntArrayElements(result, nullptr);
+    std::copy_n(instance->getJointsAt(skinIndex),
+        std::min(available, (jsize) instance->getJointCountAt(skinIndex)), entities);
+    env->ReleaseIntArrayElements(result, (jint*) entities, 0);
+}

android/gltfio-android/src/main/cpp/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

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

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

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

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

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

@@ -182,6 +182,9 @@ public class FilamentAsset {
 
     /**
      * Gets the bounding box computed from the supplied min / max values in glTF accessors.
+     *
+     * This does not return a bounding box over all FilamentInstance, it's just a straightforward
+     * AAAB that can be determined at load time from the asset data.
      */
     public @NonNull Box getBoundingBox() {
         float[] box = new float[6];
@@ -225,58 +228,6 @@ public class FilamentAsset {
         return mAnimator;
     }
 
-    /**
-     * Gets the skin count of this asset.
-     */
-    public int getSkinCount() {
-        return nGetSkinCount(getNativeObject());
-    }
-
-    /**
-     * Gets the skin name at skin index in this asset.
-     */
-    public @NonNull String[] getSkinNames() {
-        String[] result = new String[getSkinCount()];
-        nGetSkinNames(getNativeObject(), result);
-        return result;
-    }
-
-    /**
-     * Attaches the given skin to the given node, which must have an associated mesh with
-     * BONE_INDICES and BONE_WEIGHTS attributes.
-     *
-     * This is a no-op if the given skin index or target is invalid.
-     */
-    public void attachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
-        nAttachSkin(getNativeObject(), skinIndex, target);
-    }
-
-    /**
-     * Attaches the given skin to the given node, which must have an associated mesh with
-     * BONE_INDICES and BONE_WEIGHTS attributes.
-     *
-     * This is a no-op if the given skin index or target is invalid.
-     */
-    public void detachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
-        nDetachSkin(getNativeObject(), skinIndex, target);
-    }
-
-    /**
-     * Gets the joint count at skin index in this asset.
-     */
-    public int getJointCountAt(@IntRange(from = 0) int skinIndex) {
-        return nGetJointCountAt(getNativeObject(), skinIndex);
-    }
-
-    /**
-     * Gets joints at skin index in this asset.
-     */
-    public @NonNull @Entity int[] getJointsAt(@IntRange(from = 0) int skinIndex) {
-        int[] result = new int[getJointCountAt(skinIndex)];
-        nGetJointsAt(getNativeObject(), skinIndex, result);
-        return result;
-    }
-
     /**
      * Gets the names of all morph targets in the given entity.
      */
@@ -365,18 +316,11 @@ 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);
     private static native long nGetAnimator(long nativeAsset);
     private static native void nApplyMaterialVariant(long nativeAsset, int variantIndex);
-    private static native int nGetSkinCount(long nativeAsset);
-    private static native void nGetSkinNames(long nativeAsset, String[] result);
-    private static native int nGetJointCountAt(long nativeAsset, int skinIndex);
-    private static native void nGetJointsAt(long nativeAsset, int skinIndex, int[] result);
     private static native int nGetResourceUriCount(long nativeAsset);
     private static native void nGetResourceUris(long nativeAsset, String[] result);
     private static native void nReleaseSourceData(long nativeAsset);

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

@@ -85,6 +85,58 @@ public class FilamentInstance {
         return mAnimator;
     }
 
+    /**
+     * Gets the skin count of this instance.
+     */
+    public int getSkinCount() {
+        return nGetSkinCount(getNativeObject());
+    }
+
+    /**
+     * Gets the skin name at skin index in this instance.
+     */
+    public @NonNull String[] getSkinNames() {
+        String[] result = new String[getSkinCount()];
+        nGetSkinNames(getNativeObject(), result);
+        return result;
+    }
+
+    /**
+     * Attaches the given skin to the given node, which must have an associated mesh with
+     * BONE_INDICES and BONE_WEIGHTS attributes.
+     *
+     * This is a no-op if the given skin index or target is invalid.
+     */
+    public void attachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
+        nAttachSkin(getNativeObject(), skinIndex, target);
+    }
+
+    /**
+     * Attaches the given skin to the given node, which must have an associated mesh with
+     * BONE_INDICES and BONE_WEIGHTS attributes.
+     *
+     * This is a no-op if the given skin index or target is invalid.
+     */
+    public void detachSkin(@IntRange(from = 0) int skinIndex, @Entity int target) {
+        nDetachSkin(getNativeObject(), skinIndex, target);
+    }
+
+    /**
+     * Gets the joint count at skin index in this instance.
+     */
+    public int getJointCountAt(@IntRange(from = 0) int skinIndex) {
+        return nGetJointCountAt(getNativeObject(), skinIndex);
+    }
+
+    /**
+     * Gets joints at skin index in this instance.
+     */
+    public @NonNull @Entity int[] getJointsAt(@IntRange(from = 0) int skinIndex) {
+        int[] result = new int[getJointCountAt(skinIndex)];
+        nGetJointsAt(getNativeObject(), skinIndex, result);
+        return result;
+    }
+
     /**
      * Applies the given material variant to all primitives in this instance.
      *
@@ -94,9 +146,15 @@ public class FilamentInstance {
         nApplyMaterialVariant(mNativeObject, variantIndex);
     }
 
-    private static native int nGetRoot(long nativeAsset);
-    private static native int nGetEntityCount(long nativeAsset);
-    private static native void nGetEntities(long nativeAsset, int[] result);
-    private static native long nGetAnimator(long nativeAsset);
-    private static native void nApplyMaterialVariant(long nativeAsset, int variantIndex);
+    private static native int nGetRoot(long nativeInstance);
+    private static native int nGetEntityCount(long nativeInstance);
+    private static native void nGetEntities(long nativeInstance, int[] result);
+    private static native long nGetAnimator(long nativeInstance);
+    private static native void nApplyMaterialVariant(long nativeInstance, int variantIndex);
+    private static native void nGetJointsAt(long nativeInstance, int skinIndex, int[] result);
+    private static native int nGetSkinCount(long nativeInstance);
+    private static native void nGetSkinNames(long nativeInstance, String[] result);
+    private static native int nGetJointCountAt(long nativeInstance, int skinIndex);
+    private static native void nAttachSkin(long nativeInstance, int skinIndex, int entity);
+    private static native void nDetachSkin(long nativeInstance, int skinIndex, int entity);
 }

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

@@ -24,12 +24,16 @@ import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 import androidx.annotation.Size;
 
+import com.google.android.filament.proguard.UsedByNative;
+
+@UsedByNative("AssetLoader.cpp")
 public interface MaterialProvider {
 
     /**
      * MaterialKey specifies the requirements for a requested glTF material.
      * The provider creates Filament materials that fulfill these requirements.
      */
+    @UsedByNative("MaterialKey.cpp")
     public static class MaterialKey {
         public boolean doubleSided;
         public boolean unlit;
@@ -104,6 +108,12 @@ public interface MaterialProvider {
     public @Nullable MaterialInstance createMaterialInstance(MaterialKey config,
             @NonNull @Size(min = 8) int[] uvmap, @Nullable String label, @Nullable String extras);
 
+    /**
+     * Creates or fetches a compiled Filament material corresponding to the given config.
+     */
+    public @Nullable Material getMaterial(MaterialKey config, @NonNull @Size(min = 8) int[] uvmap,
+            @Nullable String label);
+
     /**
      * Creates and returns an array containing all cached materials.
      */

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

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

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

@@ -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,25 +42,31 @@ 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;
     }
 
     public @Nullable MaterialInstance createMaterialInstance(MaterialKey config,
             @NonNull @Size(min = 8) int[] uvmap, @Nullable String label, @Nullable String extras) {
-        long nativeMaterialInstance = nCreateMaterialInstance(mNativeObject, config, uvmap, label);
+        long nativeMaterialInstance = nCreateMaterialInstance(mNativeObject, config, uvmap, label, extras);
         return nativeMaterialInstance == 0 ? null : new MaterialInstance(null, nativeMaterialInstance);
     }
 
+    public @Nullable Material getMaterial(MaterialKey config, @NonNull @Size(min = 8) int[] uvmap,
+            @Nullable String label) {
+        long nativeMaterial = nGetMaterial(mNativeObject, config, uvmap, label);
+        return nativeMaterial == 0 ? null : new Material(nativeMaterial);
+    }
+
     public @NonNull Material[] getMaterials() {
         final int count = nGetMaterialCount(mNativeObject);
         Material[] result = new Material[count];
@@ -92,10 +98,12 @@ 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, String extras);
+    private static native long nGetMaterial(long nativeProvider,
             MaterialKey config, int[] uvmap, String label);
     private static native int nGetMaterialCount(long nativeProvider);
     private static native void nGetMaterials(long nativeProvider, long[] result);

android/gradle.properties

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

android/gradle/wrapper/gradle-wrapper.properties

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

android/proguard-rules.pro

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

android/samples/sample-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/src/main/AndroidManifest.xml

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

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

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

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

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

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

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

build.sh

@@ -44,6 +44,8 @@ function print_help {
     echo "        Add iOS simulator support to the iOS build."
     echo "    -t"
     echo "        Enable SwiftShader support for Vulkan in desktop builds."
+    echo "    -e"
+    echo "        Enable EGL on Linux support for desktop builds."
     echo "    -l"
     echo "        Build arm64/x86_64 universal libraries."
     echo "        For iOS, this builds universal binaries for devices and the simulator (implies -s)."
@@ -155,6 +157,8 @@ VULKAN_ANDROID_GRADLE_OPTION=""
 
 SWIFTSHADER_OPTION="-DFILAMENT_USE_SWIFTSHADER=OFF"
 
+EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=OFF"
+
 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
 MATDBG_GRADLE_OPTION=""
 
@@ -215,6 +219,7 @@ function build_desktop_target {
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \
             ${SWIFTSHADER_OPTION} \
+            ${EGL_ON_LINUX_OPTION} \
             ${MATDBG_OPTION} \
             ${deployment_target} \
             ${architectures} \
@@ -735,7 +740,7 @@ function run_tests {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfijmp:q:uvslwtdk:" opt; do
+while getopts ":hacCfijmp:q:uvslwtedk:" opt; do
     case ${opt} in
         h)
             print_help
@@ -842,6 +847,10 @@ while getopts ":hacCfijmp:q:uvslwtdk:" opt; do
             SWIFTSHADER_OPTION="-DFILAMENT_USE_SWIFTSHADER=ON"
             echo "SwiftShader support enabled."
             ;;
+        e)
+            EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=ON -DFILAMENT_SKIP_SDL2=ON -DFILAMENT_SKIP_SAMPLES=ON"
+            echo "EGL on Linux support enabled; skipping SDL2."
+            ;;
         l)
             IOS_BUILD_SIMULATOR=true
             BUILD_UNIVERSAL_LIBRARIES=true

build/android/ndk.version

@@ -1 +1 @@
-24.0.8215888
+25.1.8937393

build/web/ci-common.sh

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

build/windows/build-github.bat

@@ -119,8 +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 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/Filament.html

@@ -1850,7 +1850,7 @@ Subsurface scattering is implemented using the wrapped diffuse lighting techniqu
 </p><p>
 
 $$\begin{equation}
-f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left&lt; \NoL + \frac{w}{(1 + w)^2} \right&gt; \left&lt; c_{subsurface} + \NoL \right&gt;
+f_{d}(v,h) = \frac{c_{diff}}{\pi}(1 - F(v,h)) \left&lt; \frac{\NoL + w}{(1 + w)^2} \right&gt; \left&lt; c_{subsurface} + \NoL \right&gt;
 \end{equation}$$
 
 </p><p>
@@ -2301,7 +2301,7 @@ The term \( \lambda(l) \) in equations \( \ref{spotAbsorber} \) and \( \ref{spot
 </p><p>
 
 $$\begin{equation}\label{spotAngleAtt}
-\lambda(l) = \frac{l \times spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
+\lambda(l) = \frac{l \cdot spotDirection - cos\theta_{outer}}{cos\theta_{inner} - cos\theta_{outer}}
 \end{equation}$$
 
 </p>
@@ -5605,7 +5605,7 @@ However we only need the real bases:
 
 $$\begin{align*}
 y^{m &gt; 0}_l &amp;= \sqrt{2} K^m_l cos(m \phi) P^m_l(cos \theta) \\
-y^{m &lt; 0}_l &amp;= \sqrt{2} K^m_l sin(m \phi) P^{|m|}_l(cos \theta) \\
+y^{m &lt; 0}_l &amp;= \sqrt{2} K^m_l sin(|m| \phi) P^{|m|}_l(cos \theta) \\
 y^0_l &amp;= K^0_l P^0_l(cos \theta)
 \end{align*}$$
 
@@ -5652,8 +5652,8 @@ It’s also fairly easy to compute the trigonometric terms recursively:
 </p><p>
 
 $$\begin{align*}
-C_m &amp;\equiv cos(m \phi) \\
-S_m &amp;\equiv sin(m \phi) \\
+C_m &amp;\equiv cos(m \phi)sin(\theta)^m \\
+S_m &amp;\equiv sin(m \phi)sin(\theta)^m \\
 \{ x, y, z \} &amp;= \{ cos \phi sin \theta, sin \phi sin \theta, cos \theta \}
 \end{align*}$$
 
@@ -5664,16 +5664,12 @@ Using the angle sum trigonometric identities:
 </p><p>
 
 $$\begin{align*}
-cos(m \phi + \phi) &amp;= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = \frac{(x C_m - y S_m)}{sin(\theta)^{|m + 1|}} \\
-sin(m \phi + \phi) &amp;= sin(m \phi) sin(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = \frac{(x S_m - y C_m)}{sin(\theta)^{|m + 1|}}
+cos(m \phi + \phi) &amp;= cos(m \phi) cos(\phi) - sin(m \phi) sin(\phi) \Leftrightarrow C_{m + 1} = x C_m - y S_m \\
+sin(m \phi + \phi) &amp;= sin(m \phi) cos(\phi) + cos(m \phi) sin(\phi) \Leftrightarrow S_{m + 1} = x S_m - y C_m
 \end{align*}$$
 
 </p><p>
 
-The equations above have an extra term \(sin(\theta)^{-|m + 1|}\) but we can compensate for that in the \(P^{|m|}_l(z)\) recursion by multiplying \(P^l_l(z)\) by \(sin(\theta)^{|m + 1|}\) which greatly simplifies the third equation in \(\ref{shRecursions}\) because \(P^l_l(cos \theta) sin(\theta)^{-l} = (-1)^l(2l - 1)!!\).
-
-</p><p>
-
 <a href="#listing_nonnormalizedshbasis">Listing&nbsp;47</a> shows the C++ code to compute the non-normalized SH basis \(\frac{y^m_l(s)}{\sqrt{2} K^m_l}\):
 
 </p><pre class="listing tilde"><code><span class="line"><span class="hljs-function"><span class="hljs-keyword">static</span> <span class="hljs-keyword">inline</span> <span class="hljs-keyword">size_t</span> <span class="hljs-title">SHindex</span><span class="hljs-params">(<span class="hljs-keyword">ssize_t</span> m, <span class="hljs-keyword">size_t</span> l)</span> </span>{</span>

docs/Filament.md.html

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

docs/Materials.html

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

docs/Materials.md.html

@@ -932,6 +932,37 @@ material {
 }
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+### General: featureLevel
+
+Type
+:    `number`
+
+Value
+:     An integer value, either 1, 2 or 3. Defaults to 1.
+
+      Feature Level    |        Guaranteed features
+:----------------------|:---------------------------------
+1                      | 9 textures per material
+2                      | 9 textures per material, cubemap arrays, ESSL 3.10
+3                      | 12 textures per material, cubemap arrays, ESSL 3.10
+[Table [featureLevels]: Feature levels]
+
+Description
+:     Sets the feature level of the material. Each feature level defines a set of features the
+      material can use. If the material uses a feature not supported by the selected level, `matc`
+      will generate an error during compilation. A given feature level is guaranteed to support
+      all features of lower feature levels.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    featureLevel : 2
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Bugs
+:     `matc` doesn't verify that a material is not using features above its selected feature level.
+
+
 ### General: shadingModel
 
 Type
@@ -986,6 +1017,7 @@ uint4                  | Vector of 4 unsigned integers
 float3x3               | Matrix of 3x3 floats
 float4x4               | Matrix of 4x4 floats
 sampler2d              | 2D texture
+sampler2dArray         | Array of 2D textures
 samplerExternal        | External texture (platform-specific)
 samplerCubemap         | Cubemap texture
 [Table [materialParamsTypes]: Material parameter types]
@@ -997,7 +1029,7 @@ Samplers
 Arrays
 :     A parameter can define an array of values by appending `[size]` after the type name, where
       `size` is a positive integer. For instance: `float[9]` declares an array of nine `float`
-      values. Arrays of samplers are _not_ supported at the moment.
+      values. This syntax does not apply to samplers as arrays are treated as separate types.
 
 Description
 :     Lists the parameters required by your material. These parameters can be set at runtime using
@@ -1119,6 +1151,50 @@ 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
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+### General: vertexDomainDeviceJittered
+
+Type
+:    `boolean`
+
+Value
+:     `true` or `false`. Defaults to `false`.
+
+Description
+:    Only meaningful for `vertexDomain:Device` materials, this parameter specifies whether the
+     filament clip-space transforms need to be applied or not, which affects TAA and guard bands.
+     Generally it needs to be applied because by definition `vertexDomain:Device` materials
+     vertices are not transformed and used *as is*.
+     However, if the vertex shader uses for instance `getViewFromClipMatrix()` (or other
+     matrices based on the projection), the clip-space transform is already applied.
+     Setting this parameter incorrectly can prevent TAA or the guard bands to work correctly.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
+material {
+    vertexDomainDeviceJittered : true
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ### Vertex and attributes: requires
 
 Type
@@ -1824,7 +1900,7 @@ struct MaterialVertexInputs {
     float3 worldNormal;        // only if the shading model is not unlit
     float4 worldPosition;      // always available (see note below about world-space)
 
-    mat4   clipSpaceTransform; // default: identity, transforms the clip-space position
+    mat4   clipSpaceTransform; // default: identity, transforms the clip-space position, only available for `vertexDomain:device`
 
     // variable* names are replaced with actual names
     float4 variable0;          // if 1 or more variables is defined

docs/viewer/index.html

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

filament/CMakeLists.txt

@@ -523,6 +523,9 @@ add_library(${TARGET} STATIC ${PRIVATE_HDRS} ${PUBLIC_HDRS} ${SRCS} ${DATA_BINS}
 # specify where the public headers of this library are
 target_include_directories(${TARGET} PUBLIC ${PUBLIC_HDR_DIR})
 
+# add this subproject to the Filament folder
+set_target_properties(${TARGET} PROPERTIES FOLDER Filament)
+
 # ==================================================================================================
 # Dependencies
 # ==================================================================================================

filament/README.md

@@ -44,10 +44,8 @@ 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.

filament/backend/CMakeLists.txt

@@ -11,11 +11,14 @@ set(GENERATION_ROOT ${CMAKE_CURRENT_BINARY_DIR})
 set(PUBLIC_HDRS
         include/backend/BufferDescriptor.h
         include/backend/CallbackHandler.h
+        include/backend/DriverApiForward.h
         include/backend/DriverEnums.h
         include/backend/Handle.h
         include/backend/PipelineState.h
         include/backend/PixelBufferDescriptor.h
         include/backend/Platform.h
+        include/backend/Program.h
+        include/backend/SamplerDescriptor.h
         include/backend/TargetBufferInfo.h
 )
 
@@ -46,9 +49,7 @@ set(PRIVATE_HDRS
         include/private/backend/Driver.h
         include/private/backend/DriverApi.h
         include/private/backend/DriverAPI.inc
-        include/private/backend/DriverApiForward.h
         include/private/backend/HandleAllocator.h
-        include/private/backend/Program.h
         include/private/backend/SamplerGroup.h
         src/CommandStreamDispatcher.h
         src/DataReshaper.h
@@ -98,11 +99,11 @@ 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)
-    else()
-        list(APPEND SRCS src/opengl/platforms/PlatformDummyGL.cpp)
     endif()
 endif()
 
@@ -221,6 +222,9 @@ add_library(${TARGET} STATIC ${PRIVATE_HDRS} ${PUBLIC_HDRS} ${SRCS})
 # specify where the public headers of this library are
 target_include_directories(${TARGET} PUBLIC ${PUBLIC_HDR_DIR})
 
+# add this subproject to the Filament folder
+set_target_properties(${TARGET} PROPERTIES FOLDER Filament)
+
 # ==================================================================================================
 # Expose a header-only target to minimize dependencies.
 # ==================================================================================================
@@ -266,6 +270,7 @@ set(DUMMY_SRC "${VKSHADERS_DIR}/dummy.c")
 add_custom_command(OUTPUT ${DUMMY_SRC} COMMAND echo "//" > ${DUMMY_SRC})
 
 add_library(vkshaders STATIC ${DUMMY_SRC} ${RESGEN_SOURCE})
+set_target_properties(vkshaders PROPERTIES FOLDER Filament/Generated)
 
 # ==================================================================================================
 # Dependencies
@@ -304,6 +309,9 @@ endif()
 
 if (LINUX)
     target_link_libraries(${TARGET} PRIVATE dl)
+    if(FILAMENT_SUPPORTS_EGL_ON_LINUX)
+       target_link_libraries(${TARGET} PUBLIC EGL)
+    endif()
 endif()
 
 # ==================================================================================================
@@ -390,6 +398,7 @@ if (APPLE)
         test/test_LoadImage.cpp
         test/test_RenderExternalImage.cpp
         test/test_StencilBuffer.cpp
+        test/test_Scissor.cpp
         )
 
     target_link_libraries(backend_test PRIVATE
@@ -428,6 +437,8 @@ if (APPLE)
         install(FILES "${BACKEND_TEST_COMBINED_OUTPUT}" DESTINATION lib/${DIST_DIR} RENAME ${BACKEND_TEST_LIB_NAME})
         install(FILES test/PlatformRunner.h DESTINATION include/backend_test)
     endif()
+
+    set_target_properties(backend_test PROPERTIES FOLDER Tests)
 endif()
 
 if (APPLE AND NOT IOS)
@@ -436,5 +447,6 @@ if (APPLE AND NOT IOS)
     # Because each test case is a separate file, the -force_load flag is necessary to prevent the
     # linker from removing "unused" symbols.
     target_link_libraries(backend_test_mac PRIVATE -force_load backend_test)
+    set_target_properties(backend_test_mac PROPERTIES FOLDER Tests)
 endif()
 

filament/backend/include/backend/DriverEnums.h

@@ -48,16 +48,36 @@ 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_SAMPLER_COUNT           = 62;   // Maximum needed at feature level 3.
 static constexpr size_t MAX_VERTEX_BUFFER_COUNT     = 16;   // Max number of bound buffer objects.
 
+// Per feature level caps
+// Use (int)FeatureLevel to index this array
+static constexpr struct {
+    const size_t MAX_VERTEX_SAMPLER_COUNT;
+    const size_t MAX_FRAGMENT_SAMPLER_COUNT;
+} FEATURE_LEVEL_CAPS[4] = {
+        {  0,  0 }, // do not use
+        { 16, 16 }, // guaranteed by OpenGL ES, Vulkan and Metal
+        { 16, 16 }, // guaranteed by OpenGL ES, Vulkan and Metal
+        { 31, 31 }, // guaranteed by Metal
+};
+
 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 = 12;  // This is guaranteed by OpenGL ES.
+static constexpr size_t CONFIG_UNIFORM_BINDING_COUNT = 10;  // This is guaranteed by OpenGL ES.
+static constexpr size_t CONFIG_SAMPLER_BINDING_COUNT = 4;   // This is guaranteed by OpenGL ES.
+
+/**
+ * Defines the backend's feature levels.
+ */
+enum class FeatureLevel : uint8_t {
+    FEATURE_LEVEL_1 = 1,  //!< OpenGL ES 3.0 features (default)
+    FEATURE_LEVEL_2,      //!< OpenGL ES 3.1 features + 16 textures units + cubemap arrays
+    FEATURE_LEVEL_3       //!< OpenGL ES 3.1 features + 31 textures units + cubemap arrays
+};
 
 /**
  * Selects which driver a particular Engine should use.
@@ -128,7 +148,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
 };
 
 /**
@@ -178,16 +197,18 @@ static constexpr uint64_t FENCE_WAIT_FOR_EVER = uint64_t(-1);
 /**
  * Shader model.
  *
- * These enumerants are used across all backends and refer to a level of functionality, rather
- * than to an OpenGL specific shader model.
+ * These enumerants are used across all backends and refer to a level of functionality and quality.
+ *
+ * For example, the OpenGL backend returns `MOBILE` if it supports OpenGL ES, or `DESKTOP` if it
+ * supports Desktop OpenGL, this is later used to select the proper shader.
+ *
+ * Shader quality vs. performance is also affected by ShaderModel.
  */
 enum class ShaderModel : uint8_t {
-    //! For testing
-    UNKNOWN    = 0,
-    GL_ES_30   = 1,    //!< Mobile level functionality
-    GL_CORE_41 = 2,    //!< Desktop level functionality
+    MOBILE  = 1,    //!< Mobile level functionality
+    DESKTOP = 2,    //!< Desktop level functionality
 };
-static constexpr size_t SHADER_MODEL_COUNT = 3;
+static constexpr size_t SHADER_MODEL_COUNT = 2;
 
 /**
  * Primitive types
@@ -236,11 +257,12 @@ enum class Precision : uint8_t {
 
 //! Texture sampler type
 enum class SamplerType : uint8_t {
-    SAMPLER_2D,         //!< 2D texture
-    SAMPLER_2D_ARRAY,   //!< 2D array texture
-    SAMPLER_CUBEMAP,    //!< Cube map texture
-    SAMPLER_EXTERNAL,   //!< External texture
-    SAMPLER_3D,         //!< 3D texture
+    SAMPLER_2D,             //!< 2D texture
+    SAMPLER_2D_ARRAY,       //!< 2D array texture
+    SAMPLER_CUBEMAP,        //!< Cube map texture
+    SAMPLER_EXTERNAL,       //!< External texture
+    SAMPLER_3D,             //!< 3D texture
+    SAMPLER_CUBEMAP_ARRAY,  //!< Cube map array texture (feature level 2)
 };
 
 //! Subpass type
@@ -628,6 +650,10 @@ static constexpr bool isS3TCSRGBCompression(TextureFormat format) noexcept {
     return format >= TextureFormat::DXT1_SRGB && format <= TextureFormat::DXT5_SRGBA;
 }
 
+static constexpr bool isASTCCompression(TextureFormat format) noexcept {
+    return format >= TextureFormat::RGBA_ASTC_4x4 && format <= TextureFormat::SRGB8_ALPHA8_ASTC_12x12;
+}
+
 //! Texture Cubemap Face
 enum class TextureCubemapFace : uint8_t {
     // don't change the enums values
@@ -639,54 +665,6 @@ enum class TextureCubemapFace : uint8_t {
     NEGATIVE_Z = 5, //!< -z face
 };
 
-inline constexpr int operator +(TextureCubemapFace rhs) noexcept {
-    return int(rhs);
-}
-
-//! Face offsets for all faces of a cubemap
-struct FaceOffsets {
-    using size_type = size_t;
-    union {
-        struct {
-            size_type px;   //!< +x face offset in bytes
-            size_type nx;   //!< -x face offset in bytes
-            size_type py;   //!< +y face offset in bytes
-            size_type ny;   //!< -y face offset in bytes
-            size_type pz;   //!< +z face offset in bytes
-            size_type nz;   //!< -z face offset in bytes
-        };
-        size_type offsets[6];
-    };
-    size_type  operator[](size_t n) const noexcept { return offsets[n]; }
-    size_type& operator[](size_t n) { return offsets[n]; }
-    FaceOffsets() noexcept = default;
-    explicit FaceOffsets(size_type faceSize) noexcept {
-        px = faceSize * 0;
-        nx = faceSize * 1;
-        py = faceSize * 2;
-        ny = faceSize * 3;
-        pz = faceSize * 4;
-        nz = faceSize * 5;
-    }
-    FaceOffsets(const FaceOffsets& rhs) noexcept {
-        px = rhs.px;
-        nx = rhs.nx;
-        py = rhs.py;
-        ny = rhs.ny;
-        pz = rhs.pz;
-        nz = rhs.nz;
-    }
-    FaceOffsets& operator=(const FaceOffsets& rhs) noexcept {
-        px = rhs.px;
-        nx = rhs.nx;
-        py = rhs.py;
-        ny = rhs.ny;
-        pz = rhs.pz;
-        nz = rhs.nz;
-        return *this;
-    }
-};
-
 //! Sampler Wrap mode
 enum class SamplerWrapMode : uint8_t {
     CLAMP_TO_EDGE,      //!< clamp-to-edge. The edge of the texture extends to infinity.
@@ -797,6 +775,13 @@ enum class StencilOperation : uint8_t {
     INVERT,                 //!< Bitwise inverts the current value.
 };
 
+//! stencil faces
+enum class StencilFace : uint8_t {
+    FRONT               = 0x1,              //!< Update stencil state for front-facing polygons.
+    BACK                = 0x2,              //!< Update stencil state for back-facing polygons.
+    FRONT_AND_BACK      = FRONT | BACK,     //!< Update stencil state for all polygons.
+};
+
 //! Stream for external textures
 enum class StreamType {
     NATIVE,     //!< Not synchronized but copy-free. Good for video.
@@ -829,11 +814,9 @@ 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(uint64_t),
+        static_assert(sizeof(RasterState) == sizeof(uint32_t),
                 "RasterState size not what was intended");
         culling = CullingMode::BACK;
         blendEquationRGB = BlendEquation::ADD;
@@ -842,10 +825,6 @@ 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; }
@@ -904,26 +883,10 @@ struct RasterState {
             //! whether front face winding direction must be inverted
             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 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
+            uint8_t padding                             : 1;        // 32
         };
-        uint64_t u = 0;
+        uint32_t u = 0;
     };
 };
 
@@ -932,21 +895,27 @@ struct RasterState {
  * \privatesection
  */
 
-enum ShaderType : uint8_t {
+enum class ShaderStage : uint8_t {
     VERTEX = 0,
     FRAGMENT = 1
 };
-static constexpr size_t PIPELINE_STAGE_COUNT = 2;
 
-struct ShaderStageFlags {
-    bool vertex : 1;
-    bool fragment : 1;
-    bool hasShaderType(ShaderType type) const {
-        return (vertex && type == ShaderType::VERTEX) ||
-               (fragment && type == ShaderType::FRAGMENT);
-    }
+static constexpr size_t PIPELINE_STAGE_COUNT = 2;
+enum class ShaderStageFlags : uint8_t {
+    NONE        =    0,
+    VERTEX      =    0x1,
+    FRAGMENT    =    0x2,
+    ALL_SHADER_STAGE_FLAGS = VERTEX | FRAGMENT
 };
-static constexpr ShaderStageFlags ALL_SHADER_STAGE_FLAGS = { true, true };
+
+static inline constexpr bool hasShaderType(ShaderStageFlags flags, ShaderStage type) noexcept {
+    switch (type) {
+        case ShaderStage::VERTEX:
+            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::VERTEX));
+        case ShaderStage::FRAGMENT:
+            return bool(uint8_t(flags) & uint8_t(ShaderStageFlags::FRAGMENT));
+    }
+}
 
 /**
  * Selects which buffers to clear at the beginning of the render pass, as well as which buffers
@@ -1017,6 +986,55 @@ struct PolygonOffset {
     float constant = 0;     // units in GL-speak
 };
 
+struct StencilState {
+    using StencilFunction = SamplerCompareFunc;
+
+    struct StencilOperations {
+        //! Stencil test function
+        StencilFunction stencilFunc                     : 3;                    // 3
+
+        //! Stencil operation when stencil test fails
+        StencilOperation stencilOpStencilFail           : 3;                    // 6
+
+        uint8_t padding0                                : 2;                    // 8
+
+        //! Stencil operation when stencil test passes but depth test fails
+        StencilOperation stencilOpDepthFail             : 3;                    // 11
+
+        //! Stencil operation when both stencil and depth test pass
+        StencilOperation stencilOpDepthStencilPass      : 3;                    // 14
+
+        uint8_t padding1                                : 2;                    // 16
+
+        //! Reference value for stencil comparison tests and updates
+        uint8_t ref;                                                            // 24
+
+        //! Masks the bits of the stencil values participating in the stencil comparison test.
+        uint8_t readMask;                                                       // 32
+
+        //! Masks the bits of the stencil values updated by the stencil test.
+        uint8_t writeMask;                                                      // 40
+    };
+
+    //! Stencil operations for front-facing polygons
+    StencilOperations front = {
+            .stencilFunc = StencilFunction::A, .ref = 0, .readMask = 0xff, .writeMask = 0xff };
+
+    //! Stencil operations for back-facing polygons
+    StencilOperations back  = {
+            .stencilFunc = StencilFunction::A, .ref = 0, .readMask = 0xff, .writeMask = 0xff };
+
+    //! Whether stencil-buffer writes are enabled
+    bool stencilWrite = false;
+
+    uint8_t padding = 0;
+};
+
+static_assert(sizeof(StencilState::StencilOperations) == 5u,
+        "StencilOperations size not what was intended");
+
+static_assert(sizeof(StencilState) == 12u,
+        "StencilState size not what was intended");
 
 using FrameScheduledCallback = void(*)(PresentCallable callable, void* user);
 
@@ -1027,16 +1045,25 @@ enum class Workaround : uint16_t {
     SPLIT_EASU,
     // Backend allows feedback loop with ancillary buffers (depth/stencil) as long as they're read-only for
     // the whole render pass.
-    ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP
+    ALLOW_READ_ONLY_ANCILLARY_FEEDBACK_LOOP,
+    // for some uniform arrays, it's needed to do an initialization to avoid crash on adreno gpu
+    ADRENO_UNIFORM_ARRAY_CRASH
 };
 
 } // namespace filament::backend
 
+template<> struct utils::EnableBitMaskOperators<filament::backend::ShaderStageFlags>
+        : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::TargetBufferFlags>
         : public std::true_type {};
 template<> struct utils::EnableBitMaskOperators<filament::backend::TextureUsage>
         : public std::true_type {};
-
+template<> struct utils::EnableBitMaskOperators<filament::backend::StencilFace>
+        : public std::true_type {};
+template<> struct utils::EnableIntegerOperators<filament::backend::TextureCubemapFace>
+        : public std::true_type {};
+template<> struct utils::EnableIntegerOperators<filament::backend::FeatureLevel>
+        : public std::true_type {};
 
 #if !defined(NDEBUG)
 utils::io::ostream& operator<<(utils::io::ostream& out, filament::backend::BufferUsage usage);
@@ -1062,7 +1089,6 @@ utils::io::ostream& operator<<(utils::io::ostream& out, filament::backend::Textu
 utils::io::ostream& operator<<(utils::io::ostream& out, filament::backend::BufferObjectBinding binding);
 utils::io::ostream& operator<<(utils::io::ostream& out, filament::backend::TextureSwizzle swizzle);
 utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::AttributeArray& type);
-utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::FaceOffsets& type);
 utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::PolygonOffset& po);
 utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::RasterState& rs);
 utils::io::ostream& operator<<(utils::io::ostream& out, const filament::backend::RenderPassParams& b);

filament/backend/include/backend/PipelineState.h

@@ -31,6 +31,7 @@ namespace filament::backend {
 struct PipelineState {
     Handle<HwProgram> program;
     RasterState rasterState;
+    StencilState stencilState;
     PolygonOffset polygonOffset;
     Viewport scissor{ 0, 0,
                       (uint32_t)std::numeric_limits<int32_t>::max(),

filament/backend/include/backend/PixelBufferDescriptor.h

@@ -280,7 +280,7 @@ public:
         }
 
         size_t bpr = bpp * stride;
-        size_t bprAligned = (bpr + (alignment - 1)) & -alignment;
+        size_t bprAligned = (bpr + (alignment - 1)) & (~alignment + 1);
         return bprAligned * height;
     }
 

filament/backend/include/backend/Platform.h

@@ -37,6 +37,10 @@ public:
         uintptr_t image = 0;
     };
 
+    struct DriverConfig {
+        size_t handleArenaSize = 0; // size of handle arena in bytes. Setting to 0 indicates default value is to be used. Driver clamps to valid values.
+    };
+
     virtual ~Platform() noexcept;
 
     /**
@@ -53,10 +57,12 @@ public:
      * @param sharedContext an optional shared context. This is not meaningful with all graphic
      *                      APIs and platforms.
      *                      For EGL platforms, this is an EGLContext.
+     * 
+     * @param driverConfig  specifies driver initialization parameters
      *
      * @return nullptr on failure, or a pointer to the newly created driver.
      */
-    virtual backend::Driver* createDriver(void* sharedContext) noexcept = 0;
+    virtual backend::Driver* createDriver(void* sharedContext, const DriverConfig& driverConfig) noexcept = 0;
 
     /**
      * Processes the platform's event queue when called from its primary event-handling thread.

filament/backend/include/backend/Program.h

@@ -27,6 +27,7 @@
 #include <backend/DriverEnums.h>
 
 #include <array>
+#include <variant>
 
 namespace filament::backend {
 
@@ -34,32 +35,32 @@ class Program {
 public:
 
     static constexpr size_t SHADER_TYPE_COUNT = 2;
-    static constexpr size_t BINDING_COUNT = CONFIG_BINDING_COUNT;
-
-    enum class Shader : uint8_t {
-        VERTEX = 0,
-        FRAGMENT = 1
-    };
+    static constexpr size_t UNIFORM_BINDING_COUNT = CONFIG_UNIFORM_BINDING_COUNT;
+    static constexpr size_t SAMPLER_BINDING_COUNT = CONFIG_SAMPLER_BINDING_COUNT;
 
     struct Sampler {
         utils::CString name = {};   // name of the sampler in the shader
-        uint16_t binding = 0;       // binding point of the sampler in the shader
-        bool strict = false;        // if true, this sampler must always have a bound texture
+        uint32_t binding = 0;       // binding point of the sampler in the shader
     };
 
     struct SamplerGroupData {
         utils::FixedCapacityVector<Sampler> samplers;
-        ShaderStageFlags stageFlags = ALL_SHADER_STAGE_FLAGS;
+        ShaderStageFlags stageFlags = ShaderStageFlags::ALL_SHADER_STAGE_FLAGS;
     };
 
-    using SamplerGroupInfo = std::array<SamplerGroupData, BINDING_COUNT>;
-    using UniformBlockInfo = std::array<utils::CString, BINDING_COUNT>;
+    using UniformBlockInfo = std::array<utils::CString, UNIFORM_BINDING_COUNT>;
+    using SamplerGroupInfo = std::array<SamplerGroupData, SAMPLER_BINDING_COUNT>;
+    using ShaderBlob = utils::FixedCapacityVector<uint8_t>;
+    using ShaderSource = std::array<ShaderBlob, SHADER_TYPE_COUNT>;
 
     Program() noexcept;
+
     Program(const Program& rhs) = delete;
     Program& operator=(const Program& rhs) = delete;
+
     Program(Program&& rhs) noexcept;
     Program& operator=(Program&& rhs) noexcept;
+
     ~Program() noexcept;
 
     // sets the material name and variant for diagnostic purposes only
@@ -69,15 +70,13 @@ public:
     // 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;
+    Program& shader(ShaderStage shader, void const* data, size_t size);
 
-    // sets the 'bindingPoint' uniform block's name for this program.
-    //
     // Note: This is only needed for GLES3.0 backends, because the layout(binding=) syntax is
     //       not permitted in glsl. The backend needs a way to associate a uniform block
     //       to a binding point.
-    //
-    Program& setUniformBlock(size_t bindingPoint, utils::CString uniformBlockName) noexcept;
+    Program& uniformBlockBindings(
+            utils::FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept;
 
     // sets the 'bindingPoint' sampler group descriptor for this program.
     // 'samplers' can be destroyed after this call.
@@ -86,32 +85,33 @@ 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);
-    }
+    struct SpecializationConstant {
+        uint32_t id;                                // id set in glsl
+        std::variant<int32_t, float, bool> value;   // value and type
+    };
+
+    Program& specializationConstants(
+            utils::FixedCapacityVector<SpecializationConstant> specConstants) noexcept;
 
-    // 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);
-    }
 
-    using ShaderBlob = utils::FixedCapacityVector<uint8_t>;
-    using ShaderSource = std::array<ShaderBlob, SHADER_TYPE_COUNT>;
     ShaderSource const& getShadersSource() const noexcept { return mShadersSource; }
     ShaderSource& getShadersSource() noexcept { return mShadersSource; }
 
-    UniformBlockInfo const& getUniformBlockInfo() const noexcept { return mUniformBlocks; }
-    UniformBlockInfo& getUniformBlockInfo() noexcept { return mUniformBlocks; }
+    UniformBlockInfo const& getUniformBlockBindings() const noexcept { return mUniformBlocks; }
+    UniformBlockInfo& getUniformBlockBindings() noexcept { return mUniformBlocks; }
 
     SamplerGroupInfo const& getSamplerGroupInfo() const { return mSamplerGroups; }
     SamplerGroupInfo& getSamplerGroupInfo() { return mSamplerGroups; }
 
-    const utils::CString& getName() const noexcept { return mName; }
+    utils::CString const& getName() const noexcept { return mName; }
+    utils::CString& getName() noexcept { return mName; }
 
-    bool hasSamplers() const noexcept { return mHasSamplers; }
+    utils::FixedCapacityVector<SpecializationConstant> const& getSpecializationConstants() const noexcept {
+        return mSpecializationConstants;
+    }
+    utils::FixedCapacityVector<SpecializationConstant>& getSpecializationConstants() noexcept {
+        return mSpecializationConstants;
+    }
 
 private:
     friend utils::io::ostream& operator<<(utils::io::ostream& out, const Program& builder);
@@ -119,9 +119,9 @@ private:
     UniformBlockInfo mUniformBlocks = {};
     SamplerGroupInfo mSamplerGroups = {};
     ShaderSource mShadersSource;
-    bool mHasSamplers = false;
     utils::CString mName;
     utils::Invocable<utils::io::ostream&(utils::io::ostream& out)> mLogger;
+    utils::FixedCapacityVector<SpecializationConstant> mSpecializationConstants;
 };
 
 } // namespace filament::backend

filament/backend/include/backend/SamplerDescriptor.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2017 The Android Open Source Project
+ * 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.
@@ -14,14 +14,26 @@
  * limitations under the License.
  */
 
-#include "PlatformDummyGL.h"
+//! \file
+
+#ifndef TNT_FILAMENT_BACKEND_SAMPLERDESCRIPTOR_H
+#define TNT_FILAMENT_BACKEND_SAMPLERDESCRIPTOR_H
+
+#include <backend/DriverEnums.h>
+#include <backend/Handle.h>
+
+#include <utils/compiler.h>
+
+#include <stddef.h>
+#include <stdint.h>
 
 namespace filament::backend {
 
-Driver* PlatformDummyGL::createDriver(void* const sharedGLContext) noexcept {
-    return nullptr;
-}
+struct UTILS_PUBLIC SamplerDescriptor {
+    Handle<HwTexture> t;
+    SamplerParams s{};
+};
 
 } // namespace filament::backend
 
-// ---------------------------------------------------------------------------------------------
+#endif // TNT_FILAMENT_BACKEND_SAMPLERDESCRIPTOR_H

filament/backend/include/private/backend/BackendUtils.h

@@ -21,19 +21,16 @@
 
 #include <backend/PixelBufferDescriptor.h>
 
+#include <string_view>
+
 #include <stddef.h>
 
-#ifndef FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB
-#    define FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB 1
-#endif
-
-namespace filament {
-namespace backend {
+namespace filament::backend {
 
 /**
  * Returns true if the shader string requests the Google-style line directive extension.
  */
-bool requestsGoogleLineDirectivesExtension(const char* shader, size_t length) noexcept;
+bool requestsGoogleLineDirectivesExtension(std::string_view source) noexcept;
 
 /**
  * Edit a GLSL shader string in-place so any Google-style line directives are turned into regular
@@ -69,7 +66,6 @@ size_t getBlockHeight(TextureFormat format) noexcept;
  */
 bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped);
 
-} // namespace backend
 } // namespace filament
 
 #endif // TNT_FILAMENT_BACKEND_PRIVATE_BACKENDUTILS_H

filament/backend/include/private/backend/CircularBuffer.h

@@ -17,13 +17,12 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H
 
+#include <utils/compiler.h>
+
 #include <stddef.h>
 #include <stdint.h>
 
-#include <utils/compiler.h>
-
-namespace filament {
-namespace backend {
+namespace filament::backend {
 
 class CircularBuffer {
 public:
@@ -85,7 +84,6 @@ private:
     void* mHead = nullptr;
 };
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend
 
 #endif // TNT_FILAMENT_BACKEND_PRIVATE_CIRCULARBUFFER_H

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

@@ -19,14 +19,13 @@
 
 #include "private/backend/CircularBuffer.h"
 #include "private/backend/Dispatcher.h"
-#include "private/backend/Program.h"
-#include "private/backend/SamplerGroup.h"
 #include "private/backend/Driver.h"
 
 #include <backend/BufferDescriptor.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 #include <backend/PipelineState.h>
+#include <backend/Program.h>
 #include <backend/PixelBufferDescriptor.h>
 #include <backend/PresentCallable.h>
 #include <backend/TargetBufferInfo.h>
@@ -37,9 +36,12 @@
 #include <cstddef>
 #include <functional>
 #include <tuple>
-#include <thread>
 #include <utility>
 
+#ifndef NDEBUG
+#include <thread>
+#endif
+
 #include <assert.h>
 #include <stddef.h>
 #include <stdint.h>

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

@@ -17,13 +17,12 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_DRIVER_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_DRIVER_H
 
+#include <backend/DriverApiForward.h>
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
 #include <backend/PipelineState.h>
 #include <backend/TargetBufferInfo.h>
 
-#include "private/backend/DriverApiForward.h"
-
 #include <utils/compiler.h>
 
 #include <functional>
@@ -48,7 +47,6 @@ class BufferDescriptor;
 class CallbackHandler;
 class PixelBufferDescriptor;
 class Program;
-class SamplerGroup;
 
 template<typename T>
 class ConcreteDispatcher;

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

@@ -304,6 +304,7 @@ DECL_DRIVER_API_SYNCHRONOUS_N(void, cancelExternalImage, void*, image)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, getTimerQueryValue, backend::TimerQueryHandle, query, uint64_t*, elapsedTime)
 DECL_DRIVER_API_SYNCHRONOUS_N(backend::SyncStatus, getSyncStatus, backend::SyncHandle, sh)
 DECL_DRIVER_API_SYNCHRONOUS_N(bool, isWorkaroundNeeded, backend::Workaround, workaround)
+DECL_DRIVER_API_SYNCHRONOUS_0(backend::FeatureLevel, getFeatureLevel)
 
 /*
  * Updating driver objects
@@ -325,18 +326,17 @@ 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)
-
-DECL_DRIVER_API_N(update2DImage,
-        backend::TextureHandle, th,
-        uint32_t, level,
-        uint32_t, xoffset,
-        uint32_t, yoffset,
-        uint32_t, width,
-        uint32_t, height,
-        backend::PixelBufferDescriptor&&, data)
+        backend::BufferDescriptor&&, data)
 
 DECL_DRIVER_API_N(setMinMaxLevels,
         backend::TextureHandle, th,
@@ -354,12 +354,6 @@ DECL_DRIVER_API_N(update3DImage,
         uint32_t, depth,
         backend::PixelBufferDescriptor&&, data)
 
-DECL_DRIVER_API_N(updateCubeImage,
-        backend::TextureHandle, th,
-        uint32_t, level,
-        backend::PixelBufferDescriptor&&, data,
-        backend::FaceOffsets, faceOffsets)
-
 DECL_DRIVER_API_N(generateMipmaps,
         backend::TextureHandle, th)
 

filament/backend/include/private/backend/DriverApi.h

@@ -17,7 +17,7 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_DRIVERAPI_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_DRIVERAPI_H
 
-#include "private/backend/DriverApiForward.h"
+#include "backend/DriverApiForward.h"
 #include "private/backend/CommandStream.h"
 
 #endif // TNT_FILAMENT_BACKEND_PRIVATE_DRIVERAPI_H

filament/backend/include/private/backend/MetalPlatform.h

@@ -29,7 +29,7 @@ class MetalPlatform : public DefaultPlatform {
 public:
     ~MetalPlatform() override;
 
-    Driver* createDriver(void* sharedContext) noexcept override;
+    Driver* createDriver(void* sharedContext, const Platform::DriverConfig& driverConfig) noexcept override;
     int getOSVersion() const noexcept override { return 0; }
 
     /**

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

@@ -33,7 +33,7 @@ protected:
      * Derived classes can use this to instantiate the default OpenGLDriver backend.
      * This is typically called from your implementation of createDriver()
      */
-    static Driver* createDefaultDriver(OpenGLPlatform* platform, void* sharedContext);
+    static Driver* createDefaultDriver(OpenGLPlatform* platform, void* sharedContext, const DriverConfig& driverConfig);
 
 public:
     ~OpenGLPlatform() noexcept override;

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

@@ -17,139 +17,77 @@
 #ifndef TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 #define TNT_FILAMENT_BACKEND_PRIVATE_SAMPLERGROUP_H
 
+#include "backend/DriverApiForward.h"
+
 #include <utils/compiler.h>
-#include <utils/bitset.h>
+#include <utils/FixedCapacityVector.h>
 
 #include <backend/DriverEnums.h>
 #include <backend/Handle.h>
-
-#include <array>
-#include <memory>
+#include <backend/SamplerDescriptor.h>
 
 #include <stddef.h>
 
 namespace filament::backend {
 
+class BufferDescriptor;
+
+/*
+ * FIXME: this should eventually be moved into Filament, outside of backend.
+ *        (but it is currently used by metal/vulkan backens)
+ */
+
 class SamplerGroup {
 public:
 
     using SamplerParams = backend::SamplerParams;
 
-    struct Sampler {
-        Handle<HwTexture> t;
-        SamplerParams s{};
-    };
-
-    SamplerGroup() noexcept { } // NOLINT
+    SamplerGroup() noexcept {} // NOLINT
 
     // create a sampler group
     explicit SamplerGroup(size_t count) noexcept;
 
-    // can be copied -- this preserves dirty bits
+    // can be copied. Sets dirty flag.
     SamplerGroup(const SamplerGroup& rhs) noexcept;
     SamplerGroup& operator=(const SamplerGroup& rhs) noexcept;
 
-    // and moved -- this cleans rhs's dirty flags
-    SamplerGroup(SamplerGroup&& rhs) noexcept;
-    SamplerGroup& operator=(SamplerGroup&& rhs) noexcept;
-
-    // copy the rhs samplers into this group and sets the dirty flag
-    SamplerGroup& setSamplers(SamplerGroup const& rhs) noexcept;
+    // and moved. Leaves rhs empty, keep diry flag on new SamplerGroup.
+    SamplerGroup(SamplerGroup&& rhs) noexcept = default;
+    SamplerGroup& operator=(SamplerGroup&& rhs) = default;
 
     ~SamplerGroup() noexcept = default;
 
-    // Efficiently move a SamplerGroup to the command stream. Always use std::move() on the
-    // returned value, as in the future this might return SamplerGroup by value.
-    SamplerGroup& toCommandStream() const noexcept;
-
-    // pointer to the sampler group
-    Sampler const* getSamplers() const noexcept { return mBuffer.data(); }
+    BufferDescriptor toBufferDescriptor(DriverApi& driver) const noexcept;
 
     // sampler count
     size_t getSize() const noexcept { return mBuffer.size(); }
 
     // return if any samplers has been changed
-    bool isDirty() const noexcept { return mDirty.any(); }
+    bool isDirty() const noexcept {
+        return mDirty;
+    }
 
     // mark the whole group as clean (no modified uniforms)
-    void clean() const noexcept { mDirty.reset(); }
+    void clean() const noexcept { mDirty = false; }
 
     // set sampler at given index
-    void setSampler(size_t index, Sampler sampler) noexcept;
+    void setSampler(size_t index, backend::SamplerDescriptor sampler) noexcept;
 
-    inline void setSampler(size_t index, Handle<HwTexture> t, SamplerParams s)  {
-        setSampler(index, { t, s });
-    }
-
-    inline void clearSampler(size_t index)  {
+    inline void clearSampler(size_t index) {
         setSampler(index, {});
     }
 
+
+    // FIXME: This is now [[deprecated]]. Currently it is only used by the Vulkan/Metal backends.
+    backend::SamplerDescriptor* data() noexcept { return mBuffer.data(); }
+
 private:
 #if !defined(NDEBUG)
     friend utils::io::ostream& operator<<(utils::io::ostream& out, const SamplerGroup& rhs);
 #endif
 
-    // This could probably be cleaned-up and moved to libutils
-    template<class T, size_t N>
-    class static_vector { //NOLINT
-        typename std::aligned_storage<sizeof(T), alignof(T)>::type mData[N];
-        uint32_t mSize = 0;
-    public:
-        static_vector() = default; //NOLINT
-
-        ~static_vector() noexcept {
-            for (auto& elem : *this) {
-                elem.~T();
-            }
-        }
-
-        explicit static_vector(size_t count) noexcept : mSize(count) {
-            assert_invariant(count < N);
-            std::uninitialized_fill_n(begin(), count, T{});
-        }
-
-        static_vector(static_vector const& rhs) noexcept : mSize(rhs.mSize) {
-            std::uninitialized_copy(rhs.begin(), rhs.end(), begin());
-        }
-
-        size_t size() const noexcept { return mSize; }
-
-        T* data() noexcept { return reinterpret_cast<T*>(&mData[0]); }
-
-        T const* data() const noexcept { return reinterpret_cast<T const*>(&mData[0]); }
-
-        static_vector& operator=(static_vector const& rhs) noexcept {
-            if (this != &rhs) {
-                const size_t n = std::min(mSize, rhs.mSize);
-                std::copy_n(rhs.begin(), n, begin());
-                for (size_t pos = n, c = mSize; pos < c; ++pos) {
-                    data()[pos].~T();
-                }
-                std::uninitialized_copy(rhs.begin() + n, rhs.end(), begin() + n);
-                mSize = rhs.mSize;
-            }
-            return *this;
-        }
-
-        const T& operator[](size_t pos) const noexcept {
-            assert_invariant(pos < mSize);
-            return data()[pos];
-        }
-
-        T& operator[](size_t pos) noexcept {
-            assert_invariant(pos < mSize);
-            return data()[pos];
-        }
-
-        T* begin() { return data(); }
-        T* end() { return data() + mSize; }
-        T const* begin() const { return data(); }
-        T const* end() const { return data() + mSize; }
-    };
-
-    static_vector<Sampler, backend::MAX_SAMPLER_COUNT> mBuffer;    // 128 bytes
-    mutable utils::bitset32 mDirty;
+    utils::FixedCapacityVector<backend::SamplerDescriptor> mBuffer;
+    mutable bool mDirty = false;
 };
 
 } // namespace filament::backend

filament/backend/src/BackendUtils.cpp

@@ -22,12 +22,10 @@
 
 #include <string_view>
 
-namespace filament {
-namespace backend {
+namespace filament::backend {
 
-bool requestsGoogleLineDirectivesExtension(const char* shader, size_t length) noexcept {
-    std::string_view s(shader, length);
-    return s.find("GL_GOOGLE_cpp_style_line_directive") != std::string_view::npos;
+bool requestsGoogleLineDirectivesExtension(std::string_view source) noexcept {
+    return source.find("GL_GOOGLE_cpp_style_line_directive") != std::string_view::npos;
 }
 
 void removeGoogleLineDirectives(char* shader, size_t length) noexcept {
@@ -380,8 +378,7 @@ bool reshape(const PixelBufferDescriptor& data, PixelBufferDescriptor& reshaped)
     }
 }
 
-} // namespace backend
-} // namespace filament
+} // namespace backend::filament
 
 
 namespace utils {

filament/backend/src/CommandBufferQueue.cpp

@@ -83,9 +83,9 @@ void CommandBufferQueue::flush() noexcept {
     // circular buffer is too small, we corrupted the stream
     ASSERT_POSTCONDITION(used <= mFreeSpace,
             "Backend CommandStream overflow. Commands are corrupted and unrecoverable.\n"
-            "Please increase FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB (currently %u MiB).\n"
+            "Please increase minCommandBufferSizeMB inside the Config passed to Engine::create.\n"
             "Space used at this time: %u bytes",
-            (unsigned)FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB, (unsigned)used);
+            (unsigned)used);
 
     // wait until there is enough space in the buffer
     mFreeSpace -= used;

filament/backend/src/DataReshaper.h

@@ -40,12 +40,13 @@ public:
     // trailing channels. This is useful for platforms that only accept 4-component data, since
     // users often wish to submit (or receive) 3-component data.
     template<typename componentType, size_t srcChannelCount, size_t dstChannelCount>
-    static void reshape(void* dest, const void* src, size_t numSrcBytes) {
+    static void reshape(void* UTILS_RESTRICT dest, const void* UTILS_RESTRICT src,
+            size_t numSrcBytes) {
         const componentType maxValue = getMaxValue<componentType>();
         const componentType* in = (const componentType*) src;
         componentType* out = (componentType*) dest;
         const size_t width = (numSrcBytes / sizeof(componentType)) / srcChannelCount;
-        const int minChannelCount = filament::math::min(srcChannelCount, dstChannelCount);
+        constexpr size_t minChannelCount = math::min(srcChannelCount, dstChannelCount);
         for (size_t column = 0; column < width; ++column) {
             for (size_t channel = 0; channel < minChannelCount; ++channel) {
                 out[channel] = in[channel];
@@ -58,36 +59,28 @@ 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;
+    static void reshapeImage(uint8_t* UTILS_RESTRICT dest, const uint8_t* UTILS_RESTRICT src,
+            size_t srcBytesPerRow,
+            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);
+        const size_t minChannelCount = 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;
-        }
-
+        UTILS_ASSUME(minChannelCount <= 4);
+        const int inds[4] = { swizzle ? 2 : 0, 1, swizzle ? 0 : 2, 3 };
         for (size_t row = 0; row < height; ++row) {
-            const srcComponentType* in = (const srcComponentType*) src;
-            dstComponentType* out = (dstComponentType*) dest;
+            const srcComponentType* in = (const srcComponentType*)src;
+            dstComponentType* out = (dstComponentType*)dest;
             for (size_t column = 0; column < width; ++column) {
                 for (size_t channel = 0; channel < minChannelCount; ++channel) {
                     if constexpr (std::is_same_v<dstComponentType, srcComponentType>) {
                         out[channel] = in[inds[channel]];
                     } else {
-                        // TODO: beware of overflows in the multiply
-                        // TODO: probably not correct for _INTEGER src/dst
+                        // FIXME: beware of overflows in the multiply
+                        // FIXME: probably not correct for _INTEGER src/dst
                         out[channel] = in[inds[channel]] * dstMaxValue / srcMaxValue;
                     }
                 }
@@ -97,15 +90,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.
-    static bool reshapeImage(PixelBufferDescriptor* dst, PixelDataType srcType,
-            const uint8_t* srcBytes, int srcBytesPerRow, int width, int height, bool swizzle,
-            bool flip) {
+    // Converts a n-channel image of UBYTE, INT, UINT, or FLOAT to a different type.
+    static bool reshapeImage(PixelBufferDescriptor* UTILS_RESTRICT dst, PixelDataType srcType,
+            uint32_t srcChannelCount,  const uint8_t* UTILS_RESTRICT srcBytes, int srcBytesPerRow,
+            int width, int height, bool swizzle) {
         size_t dstChannelCount;
         switch (dst->format) {
             case PixelDataFormat::R_INTEGER: dstChannelCount = 1; break;
@@ -118,8 +111,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 +159,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/DriverBase.h

@@ -28,7 +28,6 @@
 
 #include "private/backend/Dispatcher.h"
 #include "private/backend/Driver.h"
-#include "private/backend/SamplerGroup.h"
 
 #include <condition_variable>
 #include <memory>
@@ -104,10 +103,7 @@ struct HwProgram : public HwBase {
 };
 
 struct HwSamplerGroup : public HwBase {
-    // NOTE: we have to use out-of-line allocation here because the size of a Handle<> is limited
-    std::unique_ptr<SamplerGroup> sb; // FIXME: this shouldn't depend on filament::SamplerGroup
     HwSamplerGroup() noexcept = default;
-    explicit HwSamplerGroup(size_t size) noexcept : sb(new SamplerGroup(size)) { }
 };
 
 struct HwTexture : public HwBase {

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)
@@ -63,10 +67,6 @@
     #endif
 #elif defined(__EMSCRIPTEN__)
     #include "opengl/platforms/PlatformWebGL.h"
-#else
-    #if defined(FILAMENT_SUPPORTS_OPENGL) && !defined(FILAMENT_USE_EXTERNAL_GLES3)
-        #include "opengl/platforms/PlatformDummyGL.h"
-    #endif
 #endif
 
 #if defined (FILAMENT_SUPPORTS_METAL)
@@ -77,8 +77,7 @@ filament::backend::DefaultPlatform* createDefaultMetalPlatform();
 
 #include "noop/PlatformNoop.h"
 
-namespace filament {
-namespace backend {
+namespace filament::backend {
 
 // this generates the vtable in this translation unit
 Platform::~Platform() noexcept = default;
@@ -147,6 +146,7 @@ DefaultPlatform* DefaultPlatform::create(Backend* backend) noexcept {
     assert_invariant(*backend == Backend::OPENGL);
     #if defined(FILAMENT_SUPPORTS_OPENGL)
         #if defined(FILAMENT_USE_EXTERNAL_GLES3) || defined(FILAMENT_USE_SWIFTSHADER)
+            // Swiftshader OpenGLES support is deprecated and incomplete
             return nullptr;
         #elif defined(__ANDROID__)
             return new PlatformEGLAndroid();
@@ -157,20 +157,22 @@ 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();
         #elif defined(__EMSCRIPTEN__)
             return new PlatformWebGL();
         #else
-            return new PlatformDummyGL();
+            return nullptr;
         #endif
     #else
         return nullptr;
     #endif
 }
 
-// destroys an Platform create by create()
+// destroys a Platform created by create()
 void DefaultPlatform::destroy(DefaultPlatform** platform) noexcept {
     delete *platform;
     *platform = nullptr;
@@ -178,5 +180,4 @@ void DefaultPlatform::destroy(DefaultPlatform** platform) noexcept {
 
 DefaultPlatform::~DefaultPlatform() noexcept = default;
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend

filament/backend/src/Program.cpp

@@ -14,34 +14,49 @@
  * limitations under the License.
  */
 
-#include "private/backend/Program.h"
-
-using namespace utils;
+#include "backend/Program.h"
 
 namespace filament::backend {
 
-// We want these in the .cpp file so they're not inlined (not worth it)
-Program::Program() noexcept {}  // = default; does not work with msvc because of noexcept
+using namespace utils;
+
+// We want these in the .cpp file, so they're not inlined (not worth it)
+Program::Program() noexcept { // NOLINT(modernize-use-equals-default)
+}
+
 Program::Program(Program&& rhs) noexcept = default;
-Program& Program::operator=(Program&& rhs) noexcept = default;
+
+Program& Program::operator=(Program&& rhs) noexcept {
+    mUniformBlocks.operator=(rhs.mUniformBlocks);
+    mSamplerGroups.operator=(std::move(rhs.mSamplerGroups));
+    mShadersSource.operator=(std::move(rhs.mShadersSource));
+    mName.operator=(std::move(rhs.mName));
+    mLogger.operator=(std::move(rhs.mLogger));
+    return *this;
+}
+
 Program::~Program() noexcept = default;
 
-Program& Program::diagnostics(utils::CString const& name,
-        utils::Invocable<io::ostream&(utils::io::ostream&)>&& logger) {
+Program& Program::diagnostics(CString const& name,
+        Invocable<io::ostream&(io::ostream&)>&& logger) {
     mName = name;
     mLogger = std::move(logger);
     return *this;
 }
 
-Program& Program::shader(Program::Shader shader, void const* data, size_t size) noexcept {
+Program& Program::shader(ShaderStage shader, void const* data, size_t size) {
     ShaderBlob blob(size);
     std::copy_n((const uint8_t *)data, size, blob.data());
     mShadersSource[size_t(shader)] = std::move(blob);
     return *this;
 }
 
-Program& Program::setUniformBlock(size_t bindingPoint, utils::CString uniformBlockName) noexcept {
-    mUniformBlocks[bindingPoint] = std::move(uniformBlockName);
+Program& Program::uniformBlockBindings(
+        FixedCapacityVector<std::pair<utils::CString, uint8_t>> const& uniformBlockBindings) noexcept {
+    for (auto const& item : uniformBlockBindings) {
+        assert_invariant(item.second < UNIFORM_BINDING_COUNT);
+        mUniformBlocks[item.second] = item.first;
+    }
     return *this;
 }
 
@@ -53,7 +68,12 @@ Program& Program::setSamplerGroup(size_t bindingPoint, ShaderStageFlags stageFla
     samplerList.reserve(count);
     samplerList.resize(count);
     std::copy_n(samplers, count, samplerList.data());
-    mHasSamplers = true;
+    return *this;
+}
+
+Program& Program::specializationConstants(
+        FixedCapacityVector<SpecializationConstant> specConstants) noexcept {
+    mSpecializationConstants = std::move(specConstants);
     return *this;
 }
 
@@ -64,4 +84,5 @@ io::ostream& operator<<(io::ostream& out, const Program& builder) {
     return out;
 }
 
+
 } // namespace filament::backend

filament/backend/src/SamplerGroup.cpp

@@ -16,64 +16,53 @@
 
 #include "private/backend/SamplerGroup.h"
 
-namespace filament {
-namespace backend {
+#include "private/backend/DriverApi.h"
+
+#include "backend/BufferDescriptor.h"
+
+namespace filament::backend {
 
 // create a sampler buffer
 SamplerGroup::SamplerGroup(size_t count) noexcept
         : mBuffer(count) {
 }
 
-SamplerGroup::SamplerGroup(const SamplerGroup& rhs) noexcept = default;
-
-SamplerGroup::SamplerGroup(SamplerGroup&& rhs) noexcept
-        : mBuffer(rhs.mBuffer), mDirty(rhs.mDirty) {
-    rhs.clean();
+SamplerGroup::SamplerGroup(const SamplerGroup& rhs) noexcept :
+    mBuffer(rhs.mBuffer), mDirty(true) {
 }
 
-SamplerGroup& SamplerGroup::operator=(const SamplerGroup& rhs) noexcept = default;
-
-SamplerGroup& SamplerGroup::operator=(SamplerGroup&& rhs) noexcept {
+SamplerGroup& SamplerGroup::operator=(const SamplerGroup& rhs) noexcept {
     if (this != &rhs) {
         mBuffer = rhs.mBuffer;
-        mDirty = rhs.mDirty;
-        rhs.clean();
+        mDirty = true;
     }
     return *this;
 }
 
-SamplerGroup& SamplerGroup::toCommandStream() const noexcept {
-    /*
-     * This works because our move ctor preserves the data and cleans the dirty flags.
-     * if we changed the implementation in the future to do a real move, we'd have to change
-     * this method to return SamplerGroup by value, e.g.:
-     *    SamplerGroup copy(*this);
-     *    this->clean();
-     *    return copy;
-     */
-    return const_cast<SamplerGroup&>(*this);
-}
-
-SamplerGroup& SamplerGroup::setSamplers(SamplerGroup const& rhs) noexcept {
-    if (this != &rhs) {
-        mBuffer = rhs.mBuffer;
-        mDirty.setValue((1u << rhs.mBuffer.size()) - 1u);
-    }
-    return *this;
-}
-
-void SamplerGroup::setSampler(size_t index, Sampler sampler) noexcept {
+void SamplerGroup::setSampler(size_t index, SamplerDescriptor sampler) noexcept {
     if (UTILS_LIKELY(index < mBuffer.size())) {
+        // We cannot compare two texture handles to determine if an update is needed. Texture
+        // handles are (quickly) recycled and therefore can't be used for that purpose. e.g. if a
+        // texture is destroyed, its handle could be reused quickly by another texture.
+        // TODO: find a way to avoid marking dirty if the texture does not change.
         mBuffer[index] = sampler;
-        mDirty.set(index);
+        mDirty = true;
     }
 }
 
+BufferDescriptor SamplerGroup::toBufferDescriptor(DriverApi& driver) const noexcept {
+    BufferDescriptor p;
+    p.size = mBuffer.size() * sizeof(SamplerDescriptor);
+    p.buffer = driver.allocate(p.size); // TODO: use out-of-line buffer if too large
+    memcpy(p.buffer, static_cast<const void*>(mBuffer.data()), p.size); // inlined
+    clean();
+    return p;
+}
+
 #if !defined(NDEBUG)
 utils::io::ostream& operator<<(utils::io::ostream& out, const SamplerGroup& rhs) {
-    return out << "SamplerGroup(data=" << rhs.getSamplers() << ", size=" << rhs.getSize() << ")";
+    return out << "SamplerGroup(size=" << rhs.getSize() << ")";
 }
 #endif
 
-} // namespace backend
-} // namespace filament
+} // namespace filament::backend

filament/backend/src/metal/MetalBlitter.mm

@@ -365,7 +365,7 @@ void MetalBlitter::blitDepthPlane(id<MTLCommandBuffer> cmdBuffer, bool blitColor
     [encoder setViewport:viewport];
 
     DepthStencilState depthStencilState {
-        .compareFunction = MTLCompareFunctionAlways,
+        .depthCompare = MTLCompareFunctionAlways,
         .depthWriteEnabled = blitDepth
     };
     id<MTLDepthStencilState> depthStencil =

filament/backend/src/metal/MetalBuffer.h

@@ -24,8 +24,11 @@
 
 #include <Metal/Metal.h>
 
-namespace filament {
-namespace backend {
+#include <utils/compiler.h>
+
+#include <tuple>
+
+namespace filament::backend {
 
 class MetalBuffer {
 public:
@@ -42,7 +45,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
@@ -51,18 +55,9 @@ public:
      * @return The MTLBuffer representing the current state of the buffer to bind, or nil if there
      * is no device allocation.
      *
-     * For STREAM buffers, getGpuBufferStreamOffset() should be called to retrieve the correct
-     * buffer offset.
-     *
      */
     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 {
@@ -82,18 +77,117 @@ public:
 
 private:
 
-    BufferUsage mUsage;
+    id<MTLBuffer> mBuffer = nil;
     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
-} // namespace filament
+template <typename TYPE>
+static inline TYPE align(TYPE p, size_t alignment) noexcept {
+    // alignment must be a power-of-two
+    assert(alignment && !(alignment & alignment-1));
+    return (TYPE)((p + alignment - 1) & ~(alignment - 1));
+}
+
+/**
+ * Manages a single id<MTLBuffer>, allowing sub-allocations in a "ring" fashion. Each slot in the
+ * buffer has a fixed size. When a new allocation is made, previous allocations become available
+ * when the current id<MTLCommandBuffer> has finished executing on the GPU.
+ *
+ * If there are no slots available when a new allocation is requested, MetalRingBuffer falls back to
+ * allocating a new id<MTLBuffer> per allocation until a slot is freed.
+ *
+ * All methods must be called from the Metal backend thread.
+ */
+class MetalRingBuffer {
+public:
+    // In practice, MetalRingBuffer is used for argument buffers, which are kept in the constant
+    // address space. Constant buffers have specific alignment requirements when specifying an
+    // offset.
+#if defined(IOS)
+    static constexpr auto METAL_CONSTANT_BUFFER_OFFSET_ALIGNMENT = 4;
+#else
+    static constexpr auto METAL_CONSTANT_BUFFER_OFFSET_ALIGNMENT = 32;
+#endif
+    static inline auto computeSlotSize(MTLSizeAndAlign layout) {
+         return align(align(layout.size, layout.align), METAL_CONSTANT_BUFFER_OFFSET_ALIGNMENT);
+    }
+
+    MetalRingBuffer(id<MTLDevice> device, MTLResourceOptions options, MTLSizeAndAlign layout,
+            NSUInteger slotCount)
+        : mDevice(device),
+          mAuxBuffer(nil),
+          mBufferOptions(options),
+          mSlotSizeBytes(computeSlotSize(layout)),
+          mSlotCount(slotCount) {
+        mBuffer = [device newBufferWithLength:mSlotSizeBytes * mSlotCount options:mBufferOptions];
+        assert_invariant(mBuffer);
+    }
+
+    /**
+     * Create a new allocation in the buffer.
+     * @param cmdBuffer When this command buffer has finished executing on the GPU, the previous
+     *                  ring buffer allocation will be freed.
+     * @return the id<MTLBuffer> and offset for the new allocation
+     */
+    std::tuple<id<MTLBuffer>, NSUInteger> createNewAllocation(id<MTLCommandBuffer> cmdBuffer) {
+        const auto occupiedSlots = mOccupiedSlots.load(std::memory_order_relaxed);
+        assert_invariant(occupiedSlots <= mSlotCount);
+        if (UTILS_UNLIKELY(occupiedSlots == mSlotCount)) {
+            // We don't have any room left, so we fall back to creating a one-off aux buffer.
+            // If we already have an aux buffer, it will get freed here, unless it has been retained
+            // by a MTLCommandBuffer. In that case, it will be freed when the command buffer
+            // finishes executing.
+            mAuxBuffer = [mDevice newBufferWithLength:mSlotSizeBytes options:mBufferOptions];
+            assert_invariant(mAuxBuffer);
+            return {mAuxBuffer, 0};
+        }
+        mCurrentSlot = (mCurrentSlot + 1) % mSlotCount;
+        mOccupiedSlots.fetch_add(1, std::memory_order_relaxed);
+
+        // Release the previous allocation.
+        if (UTILS_UNLIKELY(mAuxBuffer)) {
+            mAuxBuffer = nil;
+        } else {
+            [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> buffer) {
+                mOccupiedSlots.fetch_sub(1, std::memory_order_relaxed);
+            }];
+        }
+        return getCurrentAllocation();
+    }
+
+    /**
+     * Returns an allocation (buffer and offset) that is guaranteed not to be in use by the GPU.
+     * @param cmdBuffer When this command buffer has finished executing on the GPU, the previous
+     *                  ring buffer allocation will be freed.
+     * @return the id<MTLBuffer> and offset for the current allocation
+     */
+    std::tuple<id<MTLBuffer>, NSUInteger> getCurrentAllocation() const {
+        if (UTILS_UNLIKELY(mAuxBuffer)) {
+            return { mAuxBuffer, 0 };
+        }
+        return { mBuffer, mCurrentSlot * mSlotSizeBytes };
+    }
+
+    bool canAccomodateLayout(MTLSizeAndAlign layout) const {
+        return mSlotSizeBytes >= computeSlotSize(layout);
+    }
+
+private:
+    id<MTLDevice> mDevice;
+    id<MTLBuffer> mBuffer;
+    id<MTLBuffer> mAuxBuffer;
+
+    MTLResourceOptions mBufferOptions;
+
+    NSUInteger mSlotSizeBytes;
+    NSUInteger mSlotCount;
+
+    NSUInteger mCurrentSlot = 0;
+    std::atomic<NSUInteger> mOccupiedSlots = 1;
+};
+
+} // namespace filament::backend
 
 #endif

filament/backend/src/metal/MetalBuffer.mm

@@ -16,9 +16,7 @@
 
 #include "MetalBuffer.h"
 
-#include <utils/Panic.h>
-
-#include <array>
+#include "MetalContext.h"
 
 namespace filament {
 namespace backend {
@@ -27,30 +25,21 @@ MetalBuffer::MetalBuffer(MetalContext& context, BufferUsage usage, size_t size,
         : mBufferSize(size), mContext(context) {
     // 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 (size <= 4 * 1024 && usage == BufferUsage::DYNAMIC && !forceGpuBuffer) {
+       mBuffer = nil;
+       mCpuBuffer = malloc(size);
+       return;
+   }
 
-        if (usage == BufferUsage::DYNAMIC && !forceGpuBuffer) {
-            mBufferPoolEntry = nullptr;
-            mCpuBuffer = malloc(size);
-        }
-    }
-
-    mUsage = usage;
+    // Otherwise, we allocate a private GPU buffer.
+    mBuffer = [context.device newBufferWithLength:size options:MTLResourceStorageModePrivate];
+    ASSERT_POSTCONDITION(mBuffer, "Could not allocate Metal buffer of size %zu.", size);
 }
 
 MetalBuffer::~MetalBuffer() {
     if (mCpuBuffer) {
         free(mCpuBuffer);
     }
-    // This buffer is being destroyed. If we have a buffer pool entry, release it as it is no longer
-    // needed.
-    if (mBufferPoolEntry) {
-        mContext.bufferPool->releaseBuffer(mBufferPoolEntry);
-    }
 }
 
 void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
@@ -58,86 +47,50 @@ void MetalBuffer::copyIntoBuffer(void* src, size_t size, size_t byteOffset) {
         return;
     }
     ASSERT_PRECONDITION(size + byteOffset <= mBufferSize,
-            "Attempting to copy %d bytes into a buffer of size %d at offset %d",
+            "Attempting to copy %zu bytes into a buffer of size %zu at offset %zu",
             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);
         return;
     }
 
-    // We're about to acquire a new buffer to hold the new contents. If we previously had obtained a
-    // buffer we release it, decrementing its reference count, as we no longer needs it.
-    if (mBufferPoolEntry) {
-        mContext.bufferPool->releaseBuffer(mBufferPoolEntry);
-    }
+    // Acquire a staging buffer to hold the contents of this update.
+    MetalBufferPool* bufferPool = mContext.bufferPool;
+    const MetalBufferPoolEntry* const staging = bufferPool->acquireBuffer(size);
+    memcpy(staging->buffer.contents, src, size);
 
-    mBufferPoolEntry = mContext.bufferPool->acquireBuffer(mBufferSize);
-    memcpy(static_cast<uint8_t*>(mBufferPoolEntry->buffer.contents) + byteOffset, src, size);
+    // The blit below requires that byteOffset be a multiple of 4.
+    ASSERT_PRECONDITION(!(byteOffset & 0x3u), "byteOffset must be a multiple of 4");
+
+    // Encode a blit from the staging buffer into the private GPU buffer.
+    id<MTLCommandBuffer> cmdBuffer = getPendingCommandBuffer(&mContext);
+    id<MTLBlitCommandEncoder> blitEncoder = [cmdBuffer blitCommandEncoder];
+    [blitEncoder copyFromBuffer:staging->buffer
+                   sourceOffset:0
+                       toBuffer:mBuffer
+              destinationOffset:byteOffset
+                           size:size];
+    [blitEncoder endEncoding];
+    [cmdBuffer addCompletedHandler:^(id<MTLCommandBuffer> cb) {
+        bufferPool->releaseBuffer(staging);
+    }];
 }
 
-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 {
-    if (!mBufferPoolEntry) {
-        // If there's a CPU buffer, then we return nil here, as the CPU-side buffer will be bound
-        // separately.
-        if (mCpuBuffer) {
-            return nil;
-        }
-
-        // If there isn't a CPU buffer, it means no data has been loaded into this buffer yet. To
-        // avoid an error, we'll allocate an empty buffer.
-        mBufferPoolEntry = mContext.bufferPool->acquireBuffer(mBufferSize);
+    // If there's a CPU buffer, then we return nil here, as the CPU-side buffer will be bound
+    // separately.
+    if (mCpuBuffer) {
+        return nil;
     }
-
-    // This buffer is being used in a draw call, so we retain it so it's not released back into the
-    // buffer pool until the frame has finished.
-    auto uniformDeleter = [bufferPool = mContext.bufferPool] (const void* resource) {
-        bufferPool->releaseBuffer((const MetalBufferPoolEntry*) resource);
-    };
-    if (mContext.resourceTracker.trackResource((__bridge void*) cmdBuffer, mBufferPoolEntry,
-            uniformDeleter)) {
-        // We only want to retain the buffer once per command buffer- trackResource will return
-        // true if this is the first time tracking this uniform for this command buffer.
-        mContext.bufferPool->retainBuffer(mBufferPoolEntry);
-    }
-
-    return mBufferPoolEntry->buffer;
+    assert_invariant(mBuffer);
+    return mBuffer;
 }
 
 void MetalBuffer::bindBuffers(id<MTLCommandBuffer> cmdBuffer, id<MTLRenderCommandEncoder> encoder,
@@ -163,7 +116,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/MetalBufferPool.mm

@@ -43,6 +43,7 @@ MetalBufferPoolEntry const* MetalBufferPool::acquireBuffer(size_t numBytes) {
     // We were not able to find a sufficiently large stage, so create a new one.
     id<MTLBuffer> buffer = [mContext.device newBufferWithLength:numBytes
                                                         options:MTLResourceStorageModeShared];
+    ASSERT_POSTCONDITION(buffer, "Could not allocate Metal staging buffer of size %zu.", numBytes);
     MetalBufferPoolEntry* stage = new MetalBufferPoolEntry({
         .buffer = buffer,
         .capacity = numBytes,

filament/backend/src/metal/MetalContext.h

@@ -79,7 +79,7 @@ struct MetalContext {
     // State trackers.
     PipelineStateTracker pipelineState;
     DepthStencilStateTracker depthStencilState;
-    UniformBufferState uniformState[VERTEX_BUFFER_START];
+    UniformBufferState uniformState[UNIFORM_BUFFER_COUNT];
     CullModeStateTracker cullModeState;
     WindingStateTracker windingState;
 
@@ -116,11 +116,17 @@ struct MetalContext {
 
     std::stack<const char*> groupMarkers;
 
+    MTLViewport currentViewport;
+
 #if defined(FILAMENT_METAL_PROFILING)
     // Logging and profiling.
     os_log_t log;
     os_signpost_id_t signpostId;
 #endif
+
+#ifndef NDEBUG
+    tsl::robin_set<HandleBase::HandleId> aliveTextures;
+#endif
 };
 
 void initializeSupportedGpuFamilies(MetalContext* context);