test: single simple program

1. changes weren't refreshed for windows/linux-mesa vulkan. This
   is due to a reordering of the shaders when the shader source
   is replaced. We fix this by ensuring the ordering before
   writing out the edit.
   Fixes #7286

2. A condition was flipped in the SourceFormatter causing the
   format feature to not work on linux

3. The material update status wasn't really propagated to the
   front-end due to not updating the status counter.

.github/actions/android-continuous/action.yml

@@ -0,0 +1,17 @@
+name: 'Android Continuous'
+inputs:
+  build-abi:
+    description: 'The target platform ABI'
+    required: true
+    default: 'armeabi-v7a'
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-java@v3
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+    - name: Run build script
+      run: |
+        cd build/android && printf "y" | ./build.sh continuous ${{ inputs.build-abi }}
+      shell: bash

.github/actions/ubuntu-apt-add-src/action.yml

@@ -0,0 +1,9 @@
+name: 'ubuntu apt add deb-src'
+runs:
+  using: "composite"
+  steps:
+    - name: "ubuntu apt add deb-src"
+      run: |
+          echo "deb-src http://archive.ubuntu.com/ubuntu jammy main restricted universe" | sudo tee /etc/apt/sources.list.d/my.list
+          sudo apt-get update
+      shell: bash

.github/workflows/android-continuous.yml

@@ -10,30 +10,13 @@ on:
 jobs:
   build-android:
     name: build-android
-    runs-on: macos-14
+    # We intentially use a larger runner here to enable larger disk space
+    # (standard linux runner will fail on disk space and faster build time).
+    runs-on: ubuntu-22.04-32core
 
     steps:
       - uses: actions/checkout@v4.1.6
-      - uses: actions/setup-java@v3
+      - name: Run Android Continuous
+        uses: ./.github/actions/android-continuous
         with:
-          distribution: 'temurin'
+          build-abi: armeabi-v7a,arm64-v8a,x86_64
-          java-version: '17'
-      - name: Run build script
-        run: |
-          cd build/android && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filament-android
-          path: out/filament-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filamat-android-full
-          path: out/filamat-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: gltfio-android-release
-          path: out/gltfio-android-release.aar
-      - uses: actions/upload-artifact@v1.0.0
-        with:
-          name: filament-utils-android-release
-          path: out/filament-utils-android-release.aar

.github/workflows/ios-continuous.yml

@@ -10,14 +10,14 @@ on:
 jobs:
   build-ios:
     name: build-ios
-    runs-on: macos-14
+    runs-on: macos-14-xlarge
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/ios && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
         with:
           name: filament-ios
           path: out/filament-release-ios.tgz

.github/workflows/linux-continuous.yml

@@ -10,14 +10,14 @@ on:
 jobs:
   build-linux:
     name: build-linux
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-22.04-16core
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/linux && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
         with:
           name: filament-linux
           path: out/filament-release-linux.tgz

.github/workflows/mac-continuous.yml

@@ -10,14 +10,14 @@ on:
 jobs:
   build-mac:
     name: build-mac
-    runs-on: macos-14
+    runs-on: macos-14-xlarge
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/mac && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
         with:
           name: filament-mac
           path: out/filament-release-darwin.tgz

.github/workflows/presubmit.yml

@@ -15,7 +15,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-14, ubuntu-22.04]
+        os: [macos-14-xlarge, ubuntu-22.04-16core]
 
     steps:
       - uses: actions/checkout@v4.1.6
@@ -29,7 +29,7 @@ jobs:
 
   build-windows:
     name: build-windows
-    runs-on: windows-2019
+    runs-on: win-2019-16core
 
     steps:
       - uses: actions/checkout@v4.1.6
@@ -40,7 +40,7 @@ jobs:
 
   build-android:
     name: build-android
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core
 
     steps:
       - uses: actions/checkout@v4.1.6
@@ -49,12 +49,14 @@ jobs:
           distribution: 'temurin'
           java-version: '17'
       - name: Run build script
+        # Only build 1 64 bit target during presubmit to cut down build times during presubmit
+        # Continuous builds will build everything
         run: |
-          cd build/android && printf "y" | ./build.sh presubmit
+          cd build/android && printf "y" | ./build.sh presubmit arm64-v8a
 
   build-ios:
     name: build-iOS
-    runs-on: macos-14
+    runs-on: macos-14-xlarge
 
     steps:
       - uses: actions/checkout@v4.1.6
@@ -67,10 +69,38 @@ jobs:
 
   build-web:
     name: build-web
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh presubmit
+
+  validate-docs:
+    name: validate-docs
+    runs-on: ubuntu-22.04-4core
+    steps:
+      - uses: actions/checkout@v4.1.6
+        with:
+          fetch-depth: 0
+      - name: Check for manual edits to /docs
+        run: |
+           echo "${{ github.event.pull_request.head.sha }} -- ${{ github.event.pull_request.head.sha }}"
+           # disable for now
+           # bash docs_src/build/presubmit_check.sh ${{ github.event.pull_request.head.sha }}
+
+  test-renderdiff:
+    name: test-renderdiff
+    runs-on: ubuntu-22.04-16core
+
+    steps:
+      - uses: actions/checkout@v4.1.6
+      - uses: ./.github/actions/ubuntu-apt-add-src
+      - name: Run script
+        run: |
+          source ./build/linux/ci-common.sh && bash test/renderdiff/test.sh
+      - uses: actions/upload-artifact@v4
+        with:
+          name: presubmit-renderdiff-result
+          path: ./out/renderdiff_tests

.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
 
     strategy:
       matrix:
-        os: [macos-14, ubuntu-22.04]
+        os: [macos-14-xlarge, ubuntu-22.04-32core]
 
     steps:
       - name: Decide Git ref
@@ -65,7 +65,7 @@ jobs:
 
   build-web:
     name: build-web
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core
     if: github.event_name == 'release' || github.event.inputs.platform == 'web'
 
     steps:
@@ -98,7 +98,7 @@ jobs:
 
   build-android:
     name: build-android
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core
     if: github.event_name == 'release' || github.event.inputs.platform == 'android'
 
     steps:
@@ -120,7 +120,7 @@ jobs:
         env:
           TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
-          cd build/android && printf "y" | ./build.sh release
+          cd build/android && printf "y" | ./build.sh release armeabi-v7a,arm64-v8a,x86,x86_64
           cd ../..
           mv out/filament-android-release.aar out/filament-${TAG}-android.aar
           mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
@@ -152,7 +152,7 @@ jobs:
 
   build-ios:
     name: build-ios
-    runs-on: macos-14
+    runs-on: macos-14-xlarge
     if: github.event_name == 'release' || github.event.inputs.platform == 'ios'
 
     steps:
@@ -185,7 +185,7 @@ jobs:
 
   build-windows:
     name: build-windows
-    runs-on: windows-2019
+    runs-on: windows-2019-32core
     if: github.event_name == 'release' || github.event.inputs.platform == 'windows'
 
     steps:
@@ -205,6 +205,7 @@ jobs:
           TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
           build\windows\build-github.bat release
+          echo on
           move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
         shell: cmd
       - uses: actions/github-script@v6

.github/workflows/web-continuous.yml

@@ -10,14 +10,14 @@ on:
 jobs:
   build-web:
     name: build-web
-    runs-on: macos-14
+    runs-on: ubuntu-22.04-16core
 
     steps:
       - uses: actions/checkout@v4.1.6
       - name: Run build script
         run: |
           cd build/web && printf "y" | ./build.sh continuous
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
         with:
           name: filament-web
           path: out/filament-release-web.tgz

.github/workflows/windows-continuous.yml

@@ -10,7 +10,7 @@ on:
 jobs:
   build-windows:
     name: build-windows
-    runs-on: windows-2019
+    runs-on: windows-2019-32core
 
     steps:
       - uses: actions/checkout@v4.1.6
@@ -18,7 +18,7 @@ jobs:
         run: |
           build\windows\build-github.bat continuous
         shell: cmd
-      - uses: actions/upload-artifact@v1.0.0
+      - uses: actions/upload-artifact@v4
         with:
           name: filament-windows
           path: out/filament-windows.tgz

BUILDING.md

@@ -356,7 +356,7 @@ same version that our continuous builds use.
 
 ```shell
 cd <your chosen parent folder for the emscripten SDK>
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 python ./emsdk.py install latest
 python ./emsdk.py activate latest

CMakeLists.txt

@@ -45,6 +45,8 @@ option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)
 
 option(FILAMENT_ENABLE_MULTIVIEW "Enable multiview for Filament" OFF)
 
+option(FILAMENT_SUPPORTS_OSMESA "Enable OSMesa (headless GL context) for Filament" OFF)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
@@ -73,6 +75,10 @@ set(FILAMENT_BACKEND_DEBUG_FLAG "" CACHE STRING
     "A debug flag meant for enabling/disabling backend debugging paths"
 )
 
+set(FILAMENT_OSMESA_PATH "" CACHE STRING
+    "Path to the OSMesa header and lib"
+)
+
 # Enable exceptions by default in spirv-cross.
 set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS OFF)
 
@@ -132,12 +138,22 @@ else()
 endif()
 
 if (LINUX)
+    if (NOT FILAMENT_OSMESA_PATH STREQUAL "")
+        if (NOT EXISTS ${FILAMENT_OSMESA_PATH}/)
+            message(FATAL_ERROR "Cannot find specified OSMesa build directory: ${FILAMENT_OSMESA_PATH}")
+        endif()
+        set(FILAMENT_SUPPORTS_OSMESA TRUE)
+    endif()
+
     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)
+    elseif (FILAMENT_SUPPORTS_OSMESA)
+        set(FILAMENT_SUPPORTS_X11 FALSE)
+        add_definitions(-DFILAMENT_SUPPORTS_OSMESA)
     else ()
         if (FILAMENT_SUPPORTS_XCB)
             add_definitions(-DFILAMENT_SUPPORTS_XCB)
@@ -441,10 +457,19 @@ if (NOT WEBGL)
     set(GC_SECTIONS "-Wl,--gc-sections")
 endif()
 
+# Prevents stacks from being made for executable by explicitly adding this linker flag. Otherwise,
+# it generates warnings newly introduced as of GNU LD 2.39. Modern security practices strongly
+# recommend marking the stack as non-executable using the -z noexecstack linker flag to prevent
+# stack-based buffer overflow exploits.
+# See: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ffcf9c5700e49c0aee42dcba9a12ba21338e8136
+if (LINUX)
+    set(NO_EXEC_STACK "-Wl,-z,noexecstack")
+endif()
+
 set(B_SYMBOLIC_FUNCTIONS "-Wl,-Bsymbolic-functions")
 
 if (ANDROID)
-set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
+    set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
 endif()
 
 if (APPLE)
@@ -459,7 +484,7 @@ if (APPLE)
     set(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> qc -S <TARGET> <LINK_FLAGS> <OBJECTS>")
 endif()
 
-set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS} ${NO_EXEC_STACK}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS} ${BINARY_ALIGNMENT}")
 
 if (WEBGL_PTHREADS)
@@ -509,11 +534,14 @@ else()
     option(FILAMENT_BUILD_FILAMAT "Build filamat and JNI buildings" OFF)
 endif()
 
-# By default, link in matdbg for Desktop + Debug only since it pulls in filamat and a web server.
+# By default, link in matdbg/fgviewer for Desktop + Debug only since it pulls in filamat and a web server.
 if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND IS_HOST_PLATFORM)
     option(FILAMENT_ENABLE_MATDBG "Enable the material debugger" ON)
+    # TODO: Uncomment below when fgviewer is ready
+    # option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" ON)
 else()
     option(FILAMENT_ENABLE_MATDBG "Enable the material debugger" OFF)
+    option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" OFF)
 endif()
 
 # Only optimize materials in Release mode (so error message lines match the source code)
@@ -639,10 +667,6 @@ function(list_licenses OUTPUT MODULES)
 endfunction()
 
 set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/linux/combine-static-libs.sh")
-if (WIN32)
-    set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/windows/combine-static-libs.bat")
-    set(CMAKE_AR "lib.exe")
-endif()
 
 # Add a custom command to TARGET that combines the static libraries in DEPS into a single archive.
 function(combine_static_libs TARGET OUTPUT DEPS)
@@ -657,12 +681,22 @@ function(combine_static_libs TARGET OUTPUT DEPS)
         endif()
     endforeach()
 
-    add_custom_command(
+    if (WIN32)
-        TARGET ${TARGET} POST_BUILD
+        add_custom_command(
-        COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
+            TARGET ${TARGET} POST_BUILD
-        COMMENT "Combining ${target} dependencies into single shared library"
+            COMMAND lib.exe /nologo /out:temp.lib ${DEPS_FILES}
-        VERBATIM
+            COMMAND "${CMAKE_COMMAND}" -E rename temp.lib ${OUTPUT}
-    )
+            COMMENT "Combining ${target} dependencies into single shared library"
+            VERBATIM
+        )
+    else()
+        add_custom_command(
+            TARGET ${TARGET} POST_BUILD
+            COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
+            COMMENT "Combining ${target} dependencies into single shared library"
+            VERBATIM
+        )
+    endif()
 endfunction()
 
 # ==================================================================================================
@@ -733,6 +767,7 @@ add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${LIBRARIES}/viewer)
 add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
+add_subdirectory(${EXTERNAL}/abseil/tnt)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)
@@ -762,6 +797,11 @@ if (FILAMENT_BUILD_FILAMAT OR IS_HOST_PLATFORM)
     if (FILAMENT_ENABLE_MATDBG OR IS_HOST_PLATFORM)
         add_subdirectory(${LIBRARIES}/matdbg)
     endif()
+
+    # TODO: Uncomment below when fgviewer is ready
+    # if (FILAMENT_ENABLE_FGVIEWER OR IS_HOST_PLATFORM)
+    #     add_subdirectory(${LIBRARIES}/fgviewer)
+    # endif()
 endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)

CODE_STYLE.md

@@ -121,9 +121,21 @@ private:
 - other headers are sorted in reverse order of their layering, that is, lower layer headers last
 - within a layer, headers are sorted alphabetically
 - strive for implementing one class per file
-- `STL` limited in public headers to:
+- `STL` limited in **filament** public headers to:
-    - `type_traits`
+    - `array`
+    - `initializer_list`
+    - `iterator`
     - `limits`
+    - `optional`
+    - `type_traits`
+    - `utility`
+    - `variant`
+
+For **libfilament** the rule of thumb is that STL headers that don't generate code are allowed (e.g. `type_traits`),
+conversely containers and algorithms are not allowed. There are exceptions such as `array`. See above for the full list.
+- The following `STL` headers are banned entirely, from public and private headers as well as implementation files:
+  - `iostream`
+
 
 *Sorting the headers is important to help catching missing `#include` directives.*
 

NEW_RELEASE_NOTES.md

@@ -7,3 +7,5 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+
+- Support including PlatformMetal.h in C++ files.

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.54.0'
+    implementation 'com.google.android.filament:filament-android:1.57.0'
 }
 ```
 
@@ -51,19 +51,9 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.54.0'
+pod 'Filament', '~> 1.57.0'
 ```
 
-### Snapshots
-
-If you prefer to live on the edge, you can download a continuous build by following the following
-steps:
-
-1. Find the [commit](https://github.com/google/filament/commits/main) you're interested in.
-2. Click the green check mark under the commit message.
-3. Click on the _Details_ link for the platform you're interested in.
-4. On the top left click _Summary_, then in the _Artifacts_ section choose the desired artifact.
-
 ## Documentation
 
 - [Filament](https://google.github.io/filament/Filament.html), an in-depth explanation of

RELEASE_NOTES.md

@@ -7,6 +7,63 @@ A new header is inserted each time a *tag* is created.
 Instead, if you are authoring a PR for the main branch, add your release note to
 [NEW_RELEASE_NOTES.md](./NEW_RELEASE_NOTES.md).
 
+## v1.57.1
+
+
+## v1.57.0
+
+- matdbg: Add support for debugging ESSL 1.0 shaders
+- backend: New platform API to better handle external textures [⚠️ **New Material Version**]
+
+## v1.56.8
+
+
+## v1.56.7
+
+
+## v1.56.6
+
+fix crash: the 'target_node' of Animation Channel may be nullpointer.
+
+## v1.56.5
+
+
+## v1.56.4
+
+
+## v1.56.3
+
+
+## v1.56.2
+
+- vk: fix stage pool gc logic
+
+## v1.56.1
+
+## v1.56.0
+
+- backend: descriptor layouts distinguish samplers and external samplers (b/376089915) [⚠️ **New Material Version**]
+
+## v1.55.1
+
+
+## v1.55.0
+- Add descriptor sets to describe shader resources. [⚠️ **New Material Version**]
+
+## v1.54.5
+
+
+## v1.54.4
+
+- Add support for multi-layered render target with array textures.
+
+## v1.54.3
+
+
+## v1.54.2
+
+- Add a `name` API to Filament objects for debugging handle use-after-free assertions
+
 ## v1.54.1
 
 
@@ -634,7 +691,7 @@ Instead, if you are authoring a PR for the main branch, add your release note to
 
 - engine: Binary size improvements.
 - engine: Add basic support for instanced renderables [**NEW API**].
-- engine: Fix, first imaged passsed to `Stream::SetAcquiredImage` is ignored and leaked.
+- engine: Fix, first imaged passed to `Stream::SetAcquiredImage` is ignored and leaked.
 - Vulkan: Robustness improvements.
 - Java: Fix, lookAt z axis negated.
 - gltfio: Be graceful when model has > 4 weights per vert.

android/build.gradle

@@ -11,6 +11,9 @@
 // com.google.android.filament.exclude-vulkan
 //     When set, support for Vulkan will be excluded.
 //
+// com.google.android.filament.fgviewer
+//     When set, enables fgviewer
+//
 // com.google.android.filament.matdbg
 //     When set, enables matdbg
 //
@@ -61,6 +64,11 @@ buildscript {
             .gradleProperty("com.google.android.filament.exclude-vulkan")
             .isPresent()
 
+    // TODO: Uncomment below when fgviewer is ready
+    // def fgviewer = providers
+    //         .gradleProperty("com.google.android.filament.fgviewer")
+    //         .isPresent()
+
     def matdbg = providers
             .gradleProperty("com.google.android.filament.matdbg")
             .isPresent()
@@ -83,12 +91,12 @@ buildscript {
         'minSdk': 21,
         'targetSdk': 34,
         'compileSdk': 34,
-        'kotlin': '2.0.0',
+        'kotlin': '2.0.21',
-        'kotlin_coroutines': '1.9.0-RC',
+        'kotlin_coroutines': '1.9.0',
-        'buildTools': '34.0.0',
+        'buildTools': '35.0.0',
         'ndk': '27.0.11718014',
         'androidx_core': '1.13.1',
-        'androidx_annotations': '1.8.0'
+        'androidx_annotations': '1.9.0'
     ]
 
     ext.deps = [
@@ -104,7 +112,7 @@ buildscript {
     ]
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.4.1'
+        classpath 'com.android.tools.build:gradle:8.6.1'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 
@@ -115,6 +123,8 @@ buildscript {
         "-DANDROID_STL=c++_static",
         "-DFILAMENT_DIST_DIR=${filamentPath}".toString(),
         "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString(),
+        // TODO: Uncomment below when fgviewer is ready
+        // "-DFILAMENT_ENABLE_FGVIEWER=${fgviewer ? 'ON' : 'OFF'}".toString(),
         "-DFILAMENT_ENABLE_MATDBG=${matdbg ? 'ON' : 'OFF'}".toString(),
         "-DFILAMENT_DISABLE_MATOPT=${matnopt ? 'ON' : 'OFF'}".toString()
     ]

android/filament-android/CMakeLists.txt

@@ -2,6 +2,8 @@ cmake_minimum_required(VERSION 3.19)
 project(filament-android)
 
 option(FILAMENT_SUPPORTS_VULKAN "Enables Vulkan on Android" OFF)
+# TODO: Uncomment below when fgviewer is ready
+# option(FILAMENT_ENABLE_FGVIEWER "Enables Frame Graph Viewer" OFF)
 option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
 option(FILAMENT_DISABLE_MATOPT "Disables material optimizations" OFF)
 
@@ -51,6 +53,13 @@ add_library(smol-v STATIC IMPORTED)
 set_target_properties(smol-v PROPERTIES IMPORTED_LOCATION
         ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libsmol-v.a)
 
+# TODO: Uncomment below when fgviewer is ready
+# if (FILAMENT_ENABLE_FGVIEWER)
+#     add_library(fgviewer STATIC IMPORTED)
+#     set_target_properties(fgviewer PROPERTIES IMPORTED_LOCATION
+#             ${FILAMENT_DIR}/lib/${ANDROID_ABI}/libfgviewer.a)
+# endif()
+
 if (FILAMENT_ENABLE_MATDBG)
     add_library(matdbg STATIC IMPORTED)
     set_target_properties(matdbg PROPERTIES IMPORTED_LOCATION
@@ -117,6 +126,8 @@ target_link_libraries(filament-jni
     # libgeometry is PUBLIC because gltfio uses it.
     PUBLIC geometry
 
+    # TODO: Uncomment below when fgviewer is ready
+    # $<$<STREQUAL:${FILAMENT_ENABLE_FGVIEWER},ON>:fgviewer>
     $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:matdbg>
     $<$<STREQUAL:${FILAMENT_ENABLE_MATDBG},ON>:filamat>
     $<$<STREQUAL:${FILAMENT_SUPPORTS_VULKAN},ON>:bluevk>

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

@@ -392,11 +392,11 @@ Java_com_google_android_filament_Engine_nIsValidSwapChain(JNIEnv*, jclass,
     return (jboolean)engine->isValid((SwapChain*)nativeSwapChain);
 }
 
-extern "C" JNIEXPORT void JNICALL
+extern "C" JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
-        jlong nativeEngine) {
+        jlong nativeEngine, jlong timeout) {
     Engine* engine = (Engine*) nativeEngine;
-    engine->flushAndWait();
+    return engine->flushAndWait((uint64_t)timeout);
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -499,6 +499,37 @@ Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
     return (jint)engine->getActiveFeatureLevel();
 }
 
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nHasFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    std::optional<bool> result = engine->getFeatureFlag(name);
+    env->ReleaseStringUTFChars(name_, name);
+    return result.has_value();
+}
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nSetFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_, jboolean value) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    jboolean result = engine->setFeatureFlag(name, (bool)value);
+    env->ReleaseStringUTFChars(name_, name);
+    return result;
+}
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nGetFeatureFlag(JNIEnv *env, jclass clazz,
+        jlong nativeEngine, jstring name_) {
+    Engine* engine = (Engine*) nativeEngine;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    std::optional<bool> result = engine->getFeatureFlag(name);
+    env->ReleaseStringUTFChars(name_, name);
+    return result.value_or(false); // we should never fail here
+}
+
 extern "C" JNIEXPORT jlong JNICALL Java_com_google_android_filament_Engine_nCreateBuilder(JNIEnv*,
         jclass) {
     Engine::Builder* builder = new Engine::Builder{};
@@ -520,13 +551,12 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
 extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderConfig(JNIEnv*,
         jclass, jlong nativeBuilder, jlong commandBufferSizeMB, jlong perRenderPassArenaSizeMB,
         jlong driverHandleArenaSizeMB, jlong minCommandBufferSizeMB, jlong perFrameCommandsSizeMB,
-        jlong jobSystemThreadCount,
+        jlong jobSystemThreadCount, jboolean disableParallelShaderCompile,
-        jlong textureUseAfterFreePoolSize, jboolean disableParallelShaderCompile,
         jint stereoscopicType, jlong stereoscopicEyeCount,
         jlong resourceAllocatorCacheSizeMB, jlong resourceAllocatorCacheMaxAge,
         jboolean disableHandleUseAfterFreeCheck,
         jint preferredShaderLanguage,
-        jboolean forceGLES2Context) {
+        jboolean forceGLES2Context, jboolean assertNativeWindowIsValid) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
     Engine::Config config = {
             .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
@@ -535,7 +565,6 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .minCommandBufferSizeMB = (uint32_t) minCommandBufferSizeMB,
             .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
             .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
-            .textureUseAfterFreePoolSize = (uint32_t) textureUseAfterFreePoolSize,
             .disableParallelShaderCompile = (bool) disableParallelShaderCompile,
             .stereoscopicType = (Engine::StereoscopicType) stereoscopicType,
             .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
@@ -544,6 +573,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
             .disableHandleUseAfterFreeCheck = (bool) disableHandleUseAfterFreeCheck,
             .preferredShaderLanguage = (Engine::Config::ShaderLanguage) preferredShaderLanguage,
             .forceGLES2Context = (bool) forceGLES2Context,
+            .assertNativeWindowIsValid = (bool) assertNativeWindowIsValid,
     };
     builder->config(&config);
 }
@@ -566,6 +596,16 @@ extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBu
     builder->paused((bool) paused);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nSetBuilderFeature(JNIEnv *env, jclass clazz,
+        jlong nativeBuilder, jstring name_, jboolean value) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    const char *name = env->GetStringUTFChars(name_, 0);
+    builder->feature(name, (bool)value);
+    env->ReleaseStringUTFChars(name_, name);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder) {
     Engine::Builder* builder = (Engine::Builder*) nativeBuilder;

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

@@ -38,7 +38,7 @@ Java_com_google_android_filament_EntityManager_nCreateArray(JNIEnv* env, jclass,
     // (which it is), but still.
     em->create((size_t) n, reinterpret_cast<Entity *>(entities));
 
-    env->ReleaseIntArrayElements(entities_, entities, JNI_ABORT);
+    env->ReleaseIntArrayElements(entities_, entities, 0);
 }
 
 extern "C" JNIEXPORT jint JNICALL

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

@@ -167,7 +167,7 @@ Java_com_google_android_filament_IndirectLight_nGetDirectionEstimateStatic(JNIEn
     jfloat *outDirection = env->GetFloatArrayElements(outDirection_, NULL);
     *reinterpret_cast<filament::math::float3*>(outDirection) = IndirectLight::getDirectionEstimate((filament::math::float3*)sh);
     env->ReleaseFloatArrayElements(outDirection_, outDirection, 0);
-    env->ReleaseFloatArrayElements(sh_, sh, JNI_ABORT);
+    env->ReleaseFloatArrayElements(sh_, sh, 0);
 }
 
 extern "C" JNIEXPORT void JNICALL
@@ -178,5 +178,5 @@ Java_com_google_android_filament_IndirectLight_nGetColorEstimateStatic(JNIEnv *e
     *reinterpret_cast<filament::math::float4*>(outColor) =
             IndirectLight::getColorEstimate((filament::math::float3*)sh, math::float3{x, y, z});
     env->ReleaseFloatArrayElements(outColor_, outColor, 0);
-    env->ReleaseFloatArrayElements(sh_, sh, JNI_ABORT);
+    env->ReleaseFloatArrayElements(sh_, sh, 0);
 }

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

@@ -25,13 +25,14 @@ using namespace filament;
 
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Material_nBuilderBuild(JNIEnv *env, jclass,
-        jlong nativeEngine, jobject buffer_, jint size, jint shBandCount) {
+        jlong nativeEngine, jobject buffer_, jint size, jint shBandCount, jint shadowQuality) {
     Engine* engine = (Engine*) nativeEngine;
     AutoBuffer buffer(env, buffer_, size);
     auto builder = Material::Builder();
     if (shBandCount) {
         builder.sphericalHarmonicsBandCount(shBandCount);
     }
+    builder.shadowSamplingQuality((Material::Builder::ShadowSamplingQuality)shadowQuality);
     Material* material = builder
             .package(buffer.getData(), buffer.getSize())
             .build(*engine);

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

@@ -329,6 +329,18 @@ Java_com_google_android_filament_MaterialInstance_nSetCullingMode(JNIEnv*,
     instance->setCullingMode((MaterialInstance::CullingMode) cullingMode);
 }
 
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetCullingModeSeparate(JNIEnv*, jclass,
+        jlong nativeMaterialInstance,
+        jlong colorPassCullingMode, jlong shadowPassCullingMode) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setCullingMode(
+            (MaterialInstance::CullingMode) colorPassCullingMode,
+            (MaterialInstance::CullingMode) shadowPassCullingMode);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_MaterialInstance_nSetColorWrite(JNIEnv*,
@@ -505,6 +517,14 @@ Java_com_google_android_filament_MaterialInstance_nGetCullingMode(JNIEnv* env, j
     return (jint)instance->getCullingMode();
 }
 
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetShadowCullingMode(JNIEnv* env, jclass,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return (jint)instance->getShadowCullingMode();
+}
+
 extern "C"
 JNIEXPORT jboolean JNICALL
 Java_com_google_android_filament_MaterialInstance_nIsColorWriteEnabled(JNIEnv* env, jclass clazz,

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

@@ -459,6 +459,13 @@ Java_com_google_android_filament_RenderableManager_nSetMaterialInstanceAt(JNIEnv
             materialInstance);
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_RenderableManager_nClearMaterialInstanceAt(JNIEnv*, jclass,
+        jlong nativeRenderableManager, jint i, jint primitiveIndex) {
+    RenderableManager *rm = (RenderableManager *) nativeRenderableManager;
+    rm->clearMaterialInstanceAt((RenderableManager::Instance) i, (size_t) primitiveIndex);
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_RenderableManager_nGetMaterialInstanceAt(JNIEnv*, jclass,
         jlong nativeRenderableManager, jint i, jint primitiveIndex) {

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

@@ -138,6 +138,13 @@ Java_com_google_android_filament_Texture_nBuilderImportTexture(JNIEnv*, jclass,
     builder->import((intptr_t)id);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Texture_nBuilderExternal(JNIEnv*, jclass, jlong nativeBuilder) {
+    Texture::Builder *builder = (Texture::Builder *) nativeBuilder;
+    builder->external();
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_Texture_nBuilderBuild(JNIEnv*, jclass,
         jlong nativeBuilder, jlong nativeEngine) {

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

@@ -222,6 +222,20 @@ Java_com_google_android_filament_View_nIsFrontFaceWindingInverted(JNIEnv*,
     return static_cast<jboolean>(view->isFrontFaceWindingInverted());
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetTransparentPickingEnabled(JNIEnv*,
+        jclass, jlong nativeView, jboolean enabled) {
+    View* view = (View*) nativeView;
+    view->setTransparentPickingEnabled(enabled);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_View_nIsTransparentPickingEnabled(JNIEnv*,
+        jclass, jlong nativeView) {
+    View* view = (View*) nativeView;
+    return static_cast<jboolean>(view->isTransparentPickingEnabled());
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetAmbientOcclusion(JNIEnv*, jclass, jlong nativeView, jint ordinal) {
     View* view = (View*) nativeView;

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

@@ -224,13 +224,12 @@ public class Engine {
             nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
                     config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
                     config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
-                    config.jobSystemThreadCount,
+                    config.jobSystemThreadCount, config.disableParallelShaderCompile,
-                    config.textureUseAfterFreePoolSize, config.disableParallelShaderCompile,
                     config.stereoscopicType.ordinal(), config.stereoscopicEyeCount,
                     config.resourceAllocatorCacheSizeMB, config.resourceAllocatorCacheMaxAge,
                     config.disableHandleUseAfterFreeCheck,
                     config.preferredShaderLanguage.ordinal(),
-                    config.forceGLES2Context);
+                    config.forceGLES2Context, config.assertNativeWindowIsValid);
             return this;
         }
 
@@ -259,6 +258,17 @@ public class Engine {
             return this;
         }
 
+        /**
+         * Set a feature flag value. This is the only way to set constant feature flags.
+         * @param name feature name
+         * @param value true to enable, false to disable
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder feature(@NonNull String name, boolean value) {
+            nSetBuilderFeature(mNativeBuilder, name, value);
+            return this;
+        }
+
         /**
          * Creates an instance of Engine
          *
@@ -394,6 +404,7 @@ public class Engine {
         /**
          * Set to `true` to forcibly disable parallel shader compilation in the backend.
          * Currently only honored by the GL backend.
+         * @Deprecated use "backend.disable_parallel_shader_compile" feature flag instead
          */
         public boolean disableParallelShaderCompile = false;
 
@@ -419,12 +430,12 @@ public class Engine {
          */
         public long stereoscopicEyeCount = 2;
 
-        /*
+        /**
          * @Deprecated This value is no longer used.
          */
         public long resourceAllocatorCacheSizeMB = 64;
 
-        /*
+        /**
          * This value determines how many frames texture entries are kept for in the cache. This
          * is a soft limit, meaning some texture older than this are allowed to stay in the cache.
          * Typically only one texture is evicted per frame.
@@ -432,12 +443,13 @@ public class Engine {
          */
         public long resourceAllocatorCacheMaxAge = 1;
 
-        /*
+        /**
          * Disable backend handles use-after-free checks.
+         * @Deprecated use "backend.disable_handle_use_after_free_check" feature flag instead
          */
         public boolean disableHandleUseAfterFreeCheck = false;
 
-        /*
+        /**
          * Sets a preferred shader language for Filament to use.
          *
          * The Metal backend supports two shader languages: MSL (Metal Shading Language) and
@@ -459,12 +471,20 @@ public class Engine {
         };
         public ShaderLanguage preferredShaderLanguage = ShaderLanguage.DEFAULT;
 
-        /*
+        /**
          * When the OpenGL ES backend is used, setting this value to true will force a GLES2.0
          * context if supported by the Platform, or if not, will have the backend pretend
          * it's a GLES2 context. Ignored on other backends.
          */
         public boolean forceGLES2Context = false;
+
+        /**
+         * Assert the native window associated to a SwapChain is valid when calling makeCurrent().
+         * This is only supported for:
+         *      - PlatformEGLAndroid
+         * @Deprecated use "backend.opengl.assert_native_window_is_valid" feature flag instead
+         */
+        public boolean assertNativeWindowIsValid = false;
     }
 
     private Engine(long nativeEngine, Config config) {
@@ -687,11 +707,11 @@ public class Engine {
 
     /**
      * Returns the maximum number of stereoscopic eyes supported by Filament. The actual number of
-     * eyes rendered is set at Engine creation time with the {@link
+     * eyes rendered is set at Engine creation time with the {@link Config#stereoscopicEyeCount}
-     * Engine#Config#stereoscopicEyeCount} setting.
+     * setting.
      *
      * @return the max number of stereoscopic eyes supported
-     * @see Engine#Config#stereoscopicEyeCount
+     * @see Config#stereoscopicEyeCount
      */
     public long getMaxStereoscopicEyes() {
         return nGetMaxStereoscopicEyes(getNativeObject());
@@ -888,7 +908,8 @@ public class Engine {
 
     /**
      * Returns whether the object is valid.
-     * @param object Object to check for validity
+     * @param ma Material
+     * @param mi MaterialInstance to check for validity
      * @return returns true if the specified object is valid.
      */
     public boolean isValidMaterialInstance(@NonNull Material ma, MaterialInstance mi) {
@@ -1250,7 +1271,28 @@ public class Engine {
      * {@link  android.view.SurfaceHolder.Callback#surfaceDestroyed surfaceDestroyed}.</p>
      */
     public void flushAndWait() {
-        nFlushAndWait(getNativeObject());
+        boolean unused = flushAndWait(Fence.WAIT_FOR_EVER);
+    }
+
+    /**
+     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
+     * all commands to this point are executed. Note that does guarantee that the
+     * hardware is actually finished.
+     *
+     * A timeout can be specified, if for some reason this flushAndWait doesn't complete before the timeout, it will
+     * return false, true otherwise.
+     *
+     * <p>This is typically used right after destroying the <code>SwapChain</code>,
+     * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
+     * timely fashion, such as when responding to Android's
+     * <code>android.view.SurfaceHolder.Callback.surfaceDestroyed</code></p>
+     *
+     * @param timeout A timeout in nanoseconds
+     * @return true if successful, false if flushAndWait timed out, in which case it wasn't successful and commands
+     * might still be executing on both the CPU and GPU sides.
+     */
+    public boolean flushAndWait(long timeout) {
+        return nFlushAndWait(getNativeObject(), timeout);
     }
 
     /**
@@ -1310,6 +1352,39 @@ public class Engine {
      */
     public static native long getSteadyClockTimeNano();
 
+
+    /**
+     * Checks if a feature flag exists
+     * @param name name of the feature flag to check
+     * @return true if it exists false otherwise
+     */
+    public boolean hasFeatureFlag(@NonNull String name) {
+        return nHasFeatureFlag(mNativeObject, name);
+    }
+
+    /**
+     * Set the value of a non-constant feature flag.
+     * @param name name of the feature flag to set
+     * @param value value to set
+     * @return true if the value was set, false if the feature flag is constant or doesn't exist.
+     */
+    public boolean setFeatureFlag(@NonNull String name, boolean value) {
+        return nSetFeatureFlag(mNativeObject, name, value);
+    }
+
+    /**
+     * Retrieves the value of any feature flag.
+     * @param name name of the feature flag
+     * @return the value of the flag if it exists
+     * @exception IllegalArgumentException is thrown if the feature flag doesn't exist
+     */
+    public boolean getFeatureFlag(@NonNull String name) {
+        if (!hasFeatureFlag(name)) {
+            throw new IllegalArgumentException("The feature flag \"" + name + "\" doesn't exist");
+        }
+        return nGetFeatureFlag(mNativeObject, name);
+    }
+
     @UsedByReflection("TextureHelper.java")
     public long getNativeObject() {
         if (mNativeObject == 0) {
@@ -1383,7 +1458,7 @@ public class Engine {
     private static native boolean nIsValidRenderTarget(long nativeEngine, long nativeTarget);
     private static native boolean nIsValidSwapChain(long nativeEngine, long nativeSwapChain);
     private static native void nDestroyEntity(long nativeEngine, int entity);
-    private static native void nFlushAndWait(long nativeEngine);
+    private static native boolean nFlushAndWait(long nativeEngine, long timeout);
     private static native void nFlush(long nativeEngine);
     private static native boolean nIsPaused(long nativeEngine);
     private static native void nSetPaused(long nativeEngine, boolean paused);
@@ -1399,6 +1474,9 @@ public class Engine {
     private static native int nGetSupportedFeatureLevel(long nativeEngine);
     private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
     private static native int nGetActiveFeatureLevel(long nativeEngine);
+    private static native boolean nHasFeatureFlag(long nativeEngine, String name);
+    private static native boolean nSetFeatureFlag(long nativeEngine, String name, boolean value);
+    private static native boolean nGetFeatureFlag(long nativeEngine, String name);
 
     private static native long nCreateBuilder();
     private static native void nDestroyBuilder(long nativeBuilder);
@@ -1406,14 +1484,14 @@ public class Engine {
     private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
             long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
             long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
-            long textureUseAfterFreePoolSize, boolean disableParallelShaderCompile,
+            boolean disableParallelShaderCompile, int stereoscopicType, long stereoscopicEyeCount,
-            int stereoscopicType, long stereoscopicEyeCount,
             long resourceAllocatorCacheSizeMB, long resourceAllocatorCacheMaxAge,
             boolean disableHandleUseAfterFreeCheck,
             int preferredShaderLanguage,
-            boolean forceGLES2Context);
+            boolean forceGLES2Context, boolean assertNativeWindowIsValid);
     private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
     private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
     private static native void nSetBuilderPaused(long nativeBuilder, boolean paused);
+    private static native void nSetBuilderFeature(long nativeBuilder, String name, boolean value);
     private static native long nBuilderBuild(long nativeBuilder);
 }

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

@@ -344,9 +344,18 @@ public class Material {
     }
 
     public static class Builder {
+        public enum ShadowSamplingQuality {
+            /** 2x2 PCF */
+            HARD,
+            /** 3x3 gaussian filter */
+            LOW,
+        }
+
         private Buffer mBuffer;
         private int mSize;
         private int mShBandCount = 0;
+        private ShadowSamplingQuality mShadowSamplingQuality = ShadowSamplingQuality.LOW;
+
 
         /**
          * Specifies the material data. The material data is a binary blob produced by
@@ -378,6 +387,18 @@ public class Material {
             return this;
         }
 
+        /**
+         * Set the quality of shadow sampling. This is only taken into account
+         * if this material is lit and in the surface domain.
+         * @param quality
+         * @return Reference to this Builder for chaining calls.
+         */
+        @NonNull
+        public Builder shadowSamplingQuality(ShadowSamplingQuality quality) {
+            mShadowSamplingQuality = quality;
+            return this;
+        }
+
         /**
          * Creates and returns the Material object.
          *
@@ -390,7 +411,7 @@ public class Material {
         @NonNull
         public Material build(@NonNull Engine engine) {
             long nativeMaterial = nBuilderBuild(engine.getNativeObject(),
-                mBuffer, mSize, mShBandCount);
+                mBuffer, mSize, mShBandCount, mShadowSamplingQuality.ordinal());
             if (nativeMaterial == 0) throw new IllegalStateException("Couldn't create Material");
             return new Material(nativeMaterial);
         }
@@ -1041,7 +1062,7 @@ public class Material {
         mNativeObject = 0;
     }
 
-    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount);
+    private static native long nBuilderBuild(long nativeEngine, @NonNull Buffer buffer, int size, int shBandCount, int shadowQuality);
     private static native long nCreateInstance(long nativeMaterial);
     private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
     private static native long nGetDefaultInstance(long nativeMaterial);

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

@@ -556,6 +556,20 @@ public class MaterialInstance {
         nSetCullingMode(getNativeObject(), mode.ordinal());
     }
 
+    /**
+     * Overrides the default triangle culling state that was set on the material separately for the
+     * color and shadow passes
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/rasterization:culling">
+     * Rasterization: culling</a>
+     */
+    public void setCullingMode(@NonNull Material.CullingMode colorPassCullingMode,
+                               @NonNull Material.CullingMode shadowPassCullingMode) {
+        nSetCullingModeSeparate(getNativeObject(),
+            colorPassCullingMode.ordinal(), shadowPassCullingMode.ordinal());
+    }
+
     /**
      * Returns the face culling mode.
      */
@@ -564,6 +578,14 @@ public class MaterialInstance {
         return sCullingModeValues[nGetCullingMode(getNativeObject())];
     }
 
+    /**
+     * Returns the face culling mode for the shadow passes.
+     */
+    @NonNull
+    public Material.CullingMode getShadowCullingMode() {
+        return sCullingModeValues[nGetShadowCullingMode(getNativeObject())];
+    }
+
     /**
      * Overrides the default color-buffer write state that was set on the material.
      *
@@ -920,6 +942,8 @@ public class MaterialInstance {
 
     private static native void nSetDoubleSided(long nativeMaterialInstance, boolean doubleSided);
     private static native void nSetCullingMode(long nativeMaterialInstance, long mode);
+    private static native void nSetCullingModeSeparate(long nativeMaterialInstance,
+            long colorPassCullingMode, long shadowPassCullingMode);
     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);
@@ -952,6 +976,7 @@ public class MaterialInstance {
     private static native float nGetSpecularAntiAliasingThreshold(long nativeMaterialInstance);
     private static native boolean nIsDoubleSided(long nativeMaterialInstance);
     private static native int nGetCullingMode(long nativeMaterialInstance);
+    private static native int nGetShadowCullingMode(long nativeMaterialInstance);
     private static native boolean nIsColorWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsDepthWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsStencilWriteEnabled(long nativeMaterialInstance);

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

@@ -869,6 +869,13 @@ public class RenderableManager {
         nSetMaterialInstanceAt(mNativeObject, i, primitiveIndex, materialInstance.getNativeObject());
     }
 
+    /**
+     * Clears the material instance for the given primitive.
+     */
+    public void clearMaterialInstanceAt(@EntityInstance int i, @IntRange(from = 0) int primitiveIndex) {
+        nClearMaterialInstanceAt(mNativeObject, i, primitiveIndex);
+    }
+
     /**
      * Creates a MaterialInstance Java wrapper object for a particular material instance.
      */
@@ -1012,6 +1019,7 @@ public class RenderableManager {
     private static native void nGetAxisAlignedBoundingBox(long nativeRenderableManager, int i, float[] center, float[] halfExtent);
     private static native int nGetPrimitiveCount(long nativeRenderableManager, int i);
     private static native void nSetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex, long nativeMaterialInstance);
+    private static native void nClearMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native long nGetMaterialInstanceAt(long nativeRenderableManager, int i, int primitiveIndex);
     private static native void nSetGeometryAt(long nativeRenderableManager, int i, int primitiveIndex, int primitiveType, long nativeVertexBuffer, long nativeIndexBuffer, int offset, int count);
     private static native void nSetBlendOrderAt(long nativeRenderableManager, int i, int primitiveIndex, int blendOrder);

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

@@ -800,6 +800,19 @@ public class Texture {
             return this;
         }
 
+        /**
+         * Creates an external texture. The content must be set using setExternalImage().
+         * The sampler can be SAMPLER_EXTERNAL or SAMPLER_2D depending on the format. Generally
+         * YUV formats must use SAMPLER_EXTERNAL. This depends on the backend features and is not
+         * validated.
+         * @return This Builder, for chaining calls.
+         */
+        @NonNull
+        public Builder external() {
+            nBuilderExternal(mNativeBuilder);
+            return this;
+        }
+
         /**
          * Creates a new <code>Texture</code> instance.
          * @param engine The {@link Engine} to associate this <code>Texture</code> with.
@@ -1261,6 +1274,7 @@ public class Texture {
     private static native void nBuilderUsage(long nativeBuilder, int flags);
     private static native void nBuilderSwizzle(long nativeBuilder, int r, int g, int b, int a);
     private static native void nBuilderImportTexture(long nativeBuilder, long id);
+    private static native void nBuilderExternal(long nativeBuilder);
     private static native long nBuilderBuild(long nativeBuilder, long nativeEngine);
 
     private static native int nGetWidth(long nativeTexture, int level);

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

@@ -745,6 +745,33 @@ public class View {
         nSetFrontFaceWindingInverted(getNativeObject(), inverted);
     }
 
+    /**
+     * Returns true if transparent picking is enabled.
+     *
+     * @see #setTransparentPickingEnabled
+     */
+    public boolean isTransparentPickingEnabled() {
+        return nIsTransparentPickingEnabled(getNativeObject());
+    }
+
+    /**
+     * Enables or disables transparent picking. Disabled by default.
+     *
+     * When transparent picking is enabled, View::pick() will pick from both
+     * transparent and opaque renderables. When disabled, View::pick() will only
+     * pick from opaque renderables.
+     *
+     * <p>
+     * Transparent picking will create an extra pass for rendering depth
+     * from both transparent and opaque renderables. 
+     * </p>
+     *
+     * @param enabled true enables transparent picking, false disables it.
+     */
+    public void setTransparentPickingEnabled(boolean enabled) {
+        nSetTransparentPickingEnabled(getNativeObject(), enabled);
+    }
+
     /**
      * Sets options relative to dynamic lighting for this view.
      *
@@ -1281,6 +1308,8 @@ public class View {
     private static native boolean nIsPostProcessingEnabled(long nativeView);
     private static native void nSetFrontFaceWindingInverted(long nativeView, boolean inverted);
     private static native boolean nIsFrontFaceWindingInverted(long nativeView);
+    private static native void nSetTransparentPickingEnabled(long nativeView, boolean enabled);
+    private static native boolean nIsTransparentPickingEnabled(long nativeView);
     private static native void nSetAmbientOcclusion(long nativeView, int ordinal);
     private static native int nGetAmbientOcclusion(long nativeView);
     private static native void nSetAmbientOcclusionOptions(long nativeView, float radius, float bias, float power, float resolution, float intensity, float bilateralThreshold, int quality, int lowPassFilter, int upsampling, boolean enabled, boolean bentNormals, float minHorizonAngleRad);
@@ -1391,10 +1420,10 @@ public class View {
         /**
          * Upscaling quality
          * LOW:    bilinear filtered blit. Fastest, poor quality
-         * MEDIUM: AMD FidelityFX FSR1 w/ mobile optimizations
+         * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
          * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
          * ULTRA:  AMD FidelityFX FSR1
-         *      FSR1 require a well anti-aliased (MSAA or TAA), noise free scene.
+         *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene. Avoid FXAA and dithering.
          *
          * The default upscaling quality is set to LOW.
          */

android/gradle.properties

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

android/gradle/wrapper/gradle-wrapper.properties

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

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

@@ -6,6 +6,10 @@ plugins {
 
 project.ext.isSample = true
 
+kotlin {
+    jvmToolchain(versions.jdk)
+}
+
 filamentTools {
     cmgenArgs = "-q --format=ktx --size=256 --extract-blur=0.1 --deploy=src/main/assets/envs/default_env"
     iblInputFile = project.layout.projectDirectory.file("../../../third_party/environments/lightroom_14b.hdr")
@@ -13,7 +17,7 @@ filamentTools {
 }
 
 // don't forget to update MainACtivity.kt when/if changing this.
-task copyMesh(type: Copy) {
+tasks.register('copyMesh', Copy) {
     from "../../../third_party/models/BusterDrone"
     into "src/main/assets/models"
 }

android/samples/sample-hello-triangle/src/main/java/com/google/android/filament/hellotriangle/MainActivity.kt

@@ -112,7 +112,13 @@ class MainActivity : Activity() {
     }
 
     private fun setupFilament() {
-        engine = Engine.Builder().featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0).build()
+        val config = Engine.Config()
+        //config.forceGLES2Context = true
+
+        engine = Engine.Builder()
+            .config(config)
+            .featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0)
+            .build()
         renderer = engine.createRenderer()
         scene = engine.createScene()
         view = engine.createView()
@@ -123,7 +129,9 @@ class MainActivity : Activity() {
         scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
 
         // post-processing is not supported at feature level 0
-        view.isPostProcessingEnabled = false
+        if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
+            view.isPostProcessingEnabled = false
+        }
 
         // Tell the view which camera we want to use
         view.camera = camera

build.sh

@@ -23,6 +23,8 @@ function print_help {
     echo "        This is sometimes needed instead of -c (which still misses some clean steps)."
     echo "    -d"
     echo "        Enable matdbg."
+    echo "    -t"
+    echo "        Enable fgviewer."
     echo "    -f"
     echo "        Always invoke CMake before incremental builds."
     echo "    -g"
@@ -64,6 +66,9 @@ function print_help {
     echo "        enabling debug paths in the backend from the build script. For example, make a"
     echo "        systrace-enabled build without directly changing #defines. Remember to add -f when"
     echo "        changing this option."
+    echo "    -X osmesa_path"
+    echo "        Indicates a path to a completed OSMesa build. OSMesa is used to create an offscreen GL"
+    echo "        context for software rasterization"
     echo "    -S type"
     echo "        Enable stereoscopic rendering where type is one of [instanced|multiview]. This is only"
     echo "        meant for building the samples."
@@ -122,6 +127,27 @@ function print_matdbg_help {
     echo ""
 }
 
+function print_fgviewer_help {
+    echo "fgviewer is enabled in the build, but some extra steps are needed."
+    echo ""
+    echo "FOR DESKTOP BUILDS:"
+    echo ""
+    echo "Please set the port environment variable before launching. e.g., on macOS do:"
+    echo "   export FILAMENT_FGVIEWER_PORT=8085"
+    echo ""
+    echo "FOR ANDROID BUILDS:"
+    echo ""
+    echo "1) For Android Studio builds, make sure to set:"
+    echo "       -Pcom.google.android.filament.fgviewer"
+    echo "   option in Preferences > Build > Compiler > Command line options."
+    echo ""
+    echo "2) The port number is hardcoded to 8085 so you will need to do:"
+    echo "       adb forward tcp:8085 tcp:8085"
+    echo ""
+    echo "3) Be sure to enable INTERNET permission in your app's manifest file."
+    echo ""
+}
+
 # Unless explicitly specified, NDK version will be selected as highest available version within same major release chain
 FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/build/android/ndk.version | cut -f 1 -d ".")}
 
@@ -169,6 +195,7 @@ VULKAN_ANDROID_GRADLE_OPTION=""
 EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=OFF"
 
 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
+FGVIEWER_OPTION="-DFILAMENT_ENABLE_FGVIEWER=OFF"
 MATDBG_GRADLE_OPTION=""
 
 MATOPT_OPTION=""
@@ -180,6 +207,8 @@ BACKEND_DEBUG_FLAG_OPTION=""
 
 STEREOSCOPIC_OPTION=""
 
+OSMESA_OPTION=""
+
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false
 
@@ -235,11 +264,13 @@ function build_desktop_target {
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \
             ${EGL_ON_LINUX_OPTION} \
+            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${ASAN_UBSAN_OPTION} \
             ${BACKEND_DEBUG_FLAG_OPTION} \
             ${STEREOSCOPIC_OPTION} \
+            ${OSMESA_OPTION} \
             ${architectures} \
             ../..
         ln -sf "out/cmake-${lc_target}/compile_commands.json" \
@@ -370,6 +401,7 @@ function build_android_target {
             -DFILAMENT_NDK_VERSION="${FILAMENT_NDK_VERSION}" \
             -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \
             -DCMAKE_TOOLCHAIN_FILE="../../build/toolchain-${arch}-linux-android.cmake" \
+            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${VULKAN_ANDROID_OPTION} \
@@ -607,6 +639,7 @@ function build_ios_target {
             -DPLATFORM_NAME="${platform}" \
             -DIOS=1 \
             -DCMAKE_TOOLCHAIN_FILE=../../third_party/clang/iOS.cmake \
+            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${STEREOSCOPIC_OPTION} \
@@ -796,7 +829,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgijmp:q:uvslwedk:bx:S:" opt; do
+while getopts ":hacCfgijmp:q:uvslwedtk:bx:S:X:" opt; do
     case ${opt} in
         h)
             print_help
@@ -817,6 +850,12 @@ while getopts ":hacCfgijmp:q:uvslwedk:bx:S:" opt; do
             MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_BUILD_FILAMAT=ON"
             MATDBG_GRADLE_OPTION="-Pcom.google.android.filament.matdbg"
             ;;
+        t)
+            # TODO: Uncomment below when fgviewer is ready
+            # PRINT_FGVIEWER_HELP=true
+            # FGVIEWER_OPTION="-DFILAMENT_ENABLE_FGVIEWER=ON"
+            #FGVIEWER_GRADLE_OPTION="-Pcom.google.android.filament.fgviewer"
+            ;;
         f)
             ISSUE_CMAKE_ALWAYS=true
             ;;
@@ -950,6 +989,8 @@ while getopts ":hacCfgijmp:q:uvslwedk:bx:S:" opt; do
                     exit 1
             esac
             ;;
+        X)  OSMESA_OPTION="-DFILAMENT_OSMESA_PATH=${OPTARG}"
+            ;;
         \?)
             echo "Invalid option: -${OPTARG}" >&2
             echo ""
@@ -1019,3 +1060,7 @@ fi
 if [[ "${PRINT_MATDBG_HELP}" == "true" ]]; then
     print_matdbg_help
 fi
+
+if [[ "${PRINT_FGVIEWER_HELP}" == "true" ]]; then
+    print_fgviewer_help
+fi

build/android/build.sh

@@ -60,13 +60,7 @@ if [[ ! -d "${ANDROID_HOME}/ndk/$FILAMENT_NDK_VERSION" ]]; then
     yes | ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager --licenses
     ${ANDROID_HOME}/cmdline-tools/latest/bin/sdkmanager "ndk;$FILAMENT_NDK_VERSION"
 fi
-
-# Only build 1 64 bit target during presubmit to cut down build times during presubmit
-# Continuous builds will build everything
 ANDROID_ABIS=
-if [[ "$TARGET" == "presubmit" ]]; then
-  ANDROID_ABIS="-q arm64-v8a"
-fi
 
 # Build the Android sample-gltf-viewer APK during release.
 BUILD_SAMPLES=
@@ -74,5 +68,19 @@ if [[ "$TARGET" == "release" ]]; then
     BUILD_SAMPLES="-k sample-gltf-viewer"
 fi
 
+function build_android() {
+    local ABI=$1
+
+    # Do the following in two steps so that we do not run out of space
+    if [[ -n "${BUILD_DEBUG}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_DEBUG}
+        rm -rf out/cmake-android-debug-*
+    fi
+    if [[ -n "${BUILD_RELEASE}" ]]; then
+        FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android -q ${ABI} -c ${BUILD_SAMPLES} ${GENERATE_ARCHIVES} ${BUILD_RELEASE}
+        rm -rf out/cmake-android-release-*
+    fi
+}
+
 pushd `dirname $0`/../.. > /dev/null
-FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION} ./build.sh -p android $ANDROID_ABIS -c $BUILD_SAMPLES $GENERATE_ARCHIVES $BUILD_DEBUG $BUILD_RELEASE
+build_android $2

build/linux/ci-common.sh

@@ -1,16 +1,16 @@
 #!/bin/bash
 
 # version of clang we want to use
-GITHUB_CLANG_VERSION=14
+export GITHUB_CLANG_VERSION=14
 # version of CMake to use instead of the default one
-CMAKE_VERSION=3.19.5
+export GITHUB_CMAKE_VERSION=3.19.5
 # version of ninja to use
-NINJA_VERSION=1.10.2
+export GITHUB_NINJA_VERSION=1.10.2
 
 # Steps for GitHub Workflows
 if [[ "$GITHUB_WORKFLOW" ]]; then
     # Install ninja
-    wget -q https://github.com/ninja-build/ninja/releases/download/v$NINJA_VERSION/ninja-linux.zip
+    wget -q https://github.com/ninja-build/ninja/releases/download/v$GITHUB_NINJA_VERSION/ninja-linux.zip
     unzip -q ninja-linux.zip
     export PATH="$PWD:$PATH"
 
@@ -18,9 +18,9 @@ if [[ "$GITHUB_WORKFLOW" ]]; then
     mkdir -p cmake
     cd cmake
 
-    sudo wget https://github.com/Kitware/CMake/releases/download/v$CMAKE_VERSION/cmake-$CMAKE_VERSION-Linux-x86_64.sh
+    sudo wget https://github.com/Kitware/CMake/releases/download/v$GITHUB_CMAKE_VERSION/cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh
-    sudo chmod +x ./cmake-$CMAKE_VERSION-Linux-x86_64.sh
+    sudo chmod +x ./cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh
-    sudo ./cmake-$CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
+    sudo ./cmake-$GITHUB_CMAKE_VERSION-Linux-x86_64.sh --skip-license > /dev/null
     sudo update-alternatives --install /usr/bin/cmake cmake $(pwd)/bin/cmake 1000 --force
 
     cd ..

build/linux/combine-static-libs.sh

@@ -131,7 +131,7 @@ if [[ "${has_universal}" == "true" ]]; then
             archives+=("$REPLY")
         done < <(find "$(pwd)/${archs_temp_dir}/${arch}" -iname '*.a' -print0)
 
-        combine_static_libs "$arch_output" "$archives"
+        combine_static_libs "$arch_output" "${archives[@]}"
     done
 
     # Finally, combine the single-architecture archives into a universal binary.

build/web/ci-common.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
 if [ `uname` == "Linux" ];then
-    curl -OL https://github.com/ninja-build/ninja/releases/download/v1.10.2/ninja-linux.zip
+    source `dirname $0`/../linux/ci-common.sh
-    unzip -q ninja-linux.zip
 elif [ `uname` == "Darwin" ];then
     curl -OL https://github.com/ninja-build/ninja/releases/download/v1.10.2/ninja-mac.zip
     unzip -q ninja-mac.zip
@@ -13,11 +12,8 @@ fi
 chmod +x ninja
 export PATH="$PWD:$PATH"
 
-# FIXME: kokoro machines have node and npm but currently they are symlinked to non-existent files
-# npm install -g typescript
-
 # Install emscripten.
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 ./emsdk install latest
 ./emsdk activate latest

build/windows/build-github.bat

@@ -115,17 +115,23 @@ cmake ..\.. ^
     -DFILAMENT_SUPPORTS_VULKAN=ON ^
     || exit /b
 
+set build_flags=-j %NUMBER_OF_PROCESSORS%
+
+@echo on
+
+:: we've upgraded the windows machines, so the following are no longer accurate as of 09/19/24, but
+:: keeping around the comment for record.
+
 :: Attempt to fix "error C1060: compiler is out of heap space" seen on CI.
 :: Some resource libraries require significant heap space to compile, so first compile them serially.
-@echo on
+:: cmake --build . --target filagui --config %config% %build_flags% || exit /b
-cmake --build . --target filagui --config %config% || exit /b
+:: cmake --build . --target uberarchive --config %config% %build_flags% || exit /b
-cmake --build . --target uberarchive --config %config% || exit /b
+:: cmake --build . --target gltf-demo-resources --config %config% %build_flags% || exit /b
-cmake --build . --target gltf-demo-resources --config %config% || exit /b
+:: cmake --build . --target filamentapp-resources --config %config% %build_flags% || exit /b
-cmake --build . --target filamentapp-resources --config %config% || exit /b
+:: cmake --build . --target sample-resources --config %config% %build_flags% || exit /b
-cmake --build . --target sample-resources --config %config% || exit /b
+:: cmake --build . --target suzanne-resources --config %config% %build_flags% || exit /b
-cmake --build . --target suzanne-resources --config %config% || exit /b
 
-cmake --build . %INSTALL% --config %config% -- /m || exit /b
+cmake --build . %INSTALL% --config %config% %build_flags% -- /m || exit /b
 @echo off
 
 echo Disk info after building variant: %variant%

build/windows/combine-static-libs.bat

@@ -1,39 +0,0 @@
-@echo off
-set selfName=%0
-
-:: Check that we have at least 3 arguments.
-set argC=0
-for %%x in (%*) do Set /A argC+=1
-if %argC% LSS 3 goto :print_help
-
-set AR_TOOL=%1
-shift
-set OUTPUT_PATH=%1
-shift
-
-set ARCHIVES=
-:loop
-if [%1]==[] goto :finished
-set ARCHIVES=%ARCHIVES% %1
-shift
-goto :loop
-
-:finished
-
-%AR_TOOL% /nologo /out:%OUTPUT_PATH% %ARCHIVES% || goto :error
-
-exit /B %ERRORLEVEL%
-
-:print_help
-echo %selfName%. Combine multiple static libraries using an archiver tool.
-echo;
-echo Usage:
-echo     %selfName% ^<path-to-ar^> ^<output-archive^> ^<archives^>...
-echo;
-echo Notes:
-echo     ^<archives^> must be a list of absolute paths to static library archives.
-echo     This script creates a temporary working directory inside the current directory.
-exit /B 1
-
-:error
-exit /B %ERRORLEVEL%

docs/Materials.html

@@ -1787,7 +1787,12 @@ non-shader data.
       declare a variable called <code>eyeDirection</code> you can access it in the fragment shader using
       <code>variable_eyeDirection</code>. In the vertex shader, the interpolant name is simply a member of
       the <code>MaterialVertexInputs</code> structure (<code>material.eyeDirection</code> in your example). Each
-      interpolant is of type <code>float4</code> (<code>vec4</code>) in the shaders.
+      interpolant is of type <code>float4</code> (<code>vec4</code>) in the shaders. By default the precision of the
+      interpolant is <code>highp</code> in <em class="asterisk">both</em> the vertex and fragment shaders.
+      An alternate syntax can be used to specify both the name and precision of the interpolant.
+      In this case the specified precision is used as-is in both fragment and vertex stages, in
+      particular if <code>default</code> is specified the default precision is used is the fragment shader
+      (<code>mediump</code>) and in the vertex shader (<code>highp</code>).
 
 </p></dd></dl><p></p><pre class="listing tilde"><code><span class="line">material {</span>
 <span class="line">    name : Skybox,</span>
@@ -1798,7 +1803,11 @@ non-shader data.
 <span class="line">        }</span>
 <span class="line">    ],</span>
 <span class="line">    variables : [</span>
-<span class="line">         eyeDirection</span>
+<span class="line">         eyeDirection,</span>
+<span class="line">         {</span>
+<span class="line">            name : eyeColor,</span>
+<span class="line">            precision : medium</span>
+<span class="line">         }</span>
 <span class="line">    ],</span>
 <span class="line">    vertexDomain : device,</span>
 <span class="line">    depthWrite : <span class="hljs-literal">false</span>,</span>

docs_src/.gitignore

@@ -0,0 +1,2 @@
+book
+src/dup/*.md

docs_src/README.md

@@ -0,0 +1,89 @@
+# Documentation
+
+Filament's documentation (which you are reading) is a collection of pages created with [`mdBook`].
+
+## How the book is created and updated {#how-to-create}
+### Prerequisites
+ - Install [`mdBook`] for your platform
+ - `selenium` package for python
+   ```shell
+   python3 -m pip install selenium
+   ```
+
+### Generate  {#how-to-generate}
+We wrote a python script to gather and transform the different documents in the project tree into a
+single book. This script can be found in [`docs_src/build/run.py`]. In addition,
+[`docs_src/build/duplicates.json`] is used to describe the markdown files that are copied and
+transformed from the source tree. These copies are placed into `docs_src/src/dup`.
+
+To collect the pages and generate the book, run the following
+```shell
+cd docs_src
+python3 build/run.py
+```
+
+### Copy to `docs`
+`docs` is the github-specfic directory for producing a web frontend (i.e. documentation) for a
+project.
+
+(To be completed)
+
+## Document sources
+We list the different document sources and how they are copied and processed into the collection
+of markdown files that are then processed with `mdBook`.
+
+### Introductory docs {#introductory-doc}
+The [github landing page] for Filament displays an extensive introduction to Filament. It
+links to `BUILDING.md` and `CONTRIBUTING.md`, which are conventional pages for building or
+contributing to the project. We copy these pages from their respective locations in the project
+tree into `docs_src/src/dup`. Moreover, to restore valid linkage between the pages, we need
+to perform a number of URL replacements in addition to the copy. These replacements are
+described in [`docs_src/build/duplicates.json`].
+
+### Core concept docs
+The primary design of Filament as a phyiscally-based renderer and details of its materials
+system are described in `Filament.md.html` and `Materials.md.html`, respectively. These two
+documents are written in [`markdeep`]. To embed them into our book, we
+ 1. Convert the markdeep into html
+ 2. Embed the html output in a markdown file
+ 3. Place the markdown file in `docs_src/src/main`
+
+We describe step 1 in detail for the sake of record:
+ - Start a local-only server to serve the markdeep file (e.g. `Filament.md.html`)
+ - Start a `selenium` driver (essentially run chromium in headless mode)
+ - Visit the local page through the driver (i.e. open url `http://localhost:xx/Filament.md.html?export`)
+ - Parse out the exported output in the retrieved html (note that the output of the markdeep
+   export is an html with the output captured in a `<pre>` tag).
+ - Replace css styling in the exported output as needed (so they don't interfere with the book's css.
+ - Replace resource urls to refer to locations relative to the mdbook structure.
+
+### READMEs
+Filament depends on a number of libraries, which reside in the directory `libs`. These individual
+libaries often have README.md in their root to describe itself. We collect these descriptions into our
+book. In addition, client usage of Filament also requires using a set of binary tools, which are
+located in `tools`. Some of tools also have README.md as description. We also collect them into the book.
+
+The process for copying and processing these READMEs is outlined in [Introductory docs](#introductory-doc).
+
+### Other technical notes
+These are technical documents that do not fit into a library, tool, or directory of the
+Filament source tree. We collect them into the `docs_src/src/notes` directory. No additional
+processing are needed for these documents.
+
+## Adding more documents
+To add any documentation, first consider the type of the document you like to add. If it
+belongs to any of the above sources, then simply place the document in the appropriate place,
+add a link in `SUMMARY.md`, and perform the steps outlined in
+[how-to create section](#how-to-create).
+
+For example, if you are adding a general technical note, then you would
+ - Place the document (file with extension `.md`) in `docs_src/src/notes`
+ - Add a link in [`docs_src/src/SUMMARY.md`]
+ - Run the commands in the [Generate](#how-to-generate) section
+
+[github landing page]: https://google.github.io/filament
+[`mdBook`]: https://rust-lang.github.io/mdBook/
+[`markdeep`]: https://casual-effects.com/markdeep/
+[`docs_src/build/run.py`]: https://github.com/google/filament/blob/main/docs_src/build/run.py
+[`docs_src/build/duplicates.json`]: https://github.com/google/filament/blob/main/docs_src/build/duplicates.json
+[`docs_src/src/SUMMARY.md`]: https://github.com/google/filament/blob/main/docs_src/src/SUMMARY.md

docs_src/book.toml

@@ -0,0 +1,20 @@
+[book]
+authors = []
+language = "en"
+multilingual = false
+src = "src"
+title = "Filament"
+
+[build]
+create-missing = false
+
+[output.html]
+mathjax-support = true
+default-theme = "light"
+preferred-dark-theme = "light"
+
+[output.html.print]
+enable = false
+
+[output.html.fold]
+enable = false

docs_src/build/checks.py

@@ -0,0 +1,140 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This script contains several checks on the current commit, each corresponds to `possible_conditions`
+# in the main function below
+#   - Direct (non-filamentbot) edits of /docs
+#   - Edits to sources of READMEs that are duplicated to /docs
+#       or edits to /docs_src sources
+#   - Commit message has DOCS_BYPASS
+#   - Commit message has DOCS_FORCE
+#   - Commit message has DOCS_ALLOW_DIRECT_EDITS
+
+import json
+import sys
+import os
+
+from utils import execute, ArgParseImpl
+
+CUR_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.join(CUR_DIR, '../../')
+
+def get_last_commit_hash():
+  res, ret = execute('git rev-parse HEAD', cwd=ROOT_DIR)
+  assert res == 0, 'Failed to get the last commit hash'
+  return ret.strip()
+
+def get_edited_files(commit_hash):
+  INSERT = '#####?????'
+  res, ret = execute(f'git show --name-only --pretty=%b{INSERT} {commit_hash}')
+  assert res == 0, 'Failed to get edited filed'
+  files = []
+  _, after = ret.split(INSERT)
+  for r in filter(lambda a: len(a) > 0, after.split('\n')):
+    if r.startswith('commit'):
+      break
+    files.append(r)
+  return files
+
+# Returns True if there were no direct edits to '/docs'
+def check_no_direct_edits(commit_hash, printing=True):
+  bad = [f'\t{f}' for f in get_edited_files(commit_hash) if f.startswith('docs/')]
+  if printing and len(bad) > 0:
+    print(f'Found edits to /docs:\n' + '\n'.join(bad))
+  return len(bad) == 0
+
+# Returns True if docs sources have been modified
+def check_has_source_edits(commit_hash, printing=True):
+  config = {}
+  with open(f'{CUR_DIR}/duplicates.json') as config_txt:
+    config = json.loads(config_txt.read())
+  source_files = set(config.keys())
+  edited_files = set(get_edited_files(commit_hash))
+  overlap = [f'\t{f}' for f in list(source_files & edited_files)]
+  if printing and len(overlap) > 0:
+    print(f'Found edited source files:\n' + '\n'.join(overlap))
+  return len(overlap) > 0
+
+# Returns true in a given TAG is found in the commit msg
+def commit_msg_has_tag(commit_hash, tag, printing=True):
+  res, ret = execute(f'git log --pretty=%B {commit_hash}', cwd=ROOT_DIR)
+  for l in ret.split('\n'):
+    if tag == l.strip():
+      if printing:
+        print(f'Found tag={tag} in commit message')
+      return True
+  return False
+
+if __name__ == "__main__":
+  parser = ArgParseImpl()
+
+  TAG_DOCS_BYPASS = 'DOCS_BYPASS'
+  TAG_DOCS_FORCE = 'DOCS_FORCE'
+  TAG_DOCS_ALLOW_DIRECT_EDITS = 'DOCS_ALLOW_DIRECT_EDITS'
+
+  possible_conditions = {
+      'no_direct_edits':
+          check_no_direct_edits,
+      'source_edits':
+          check_has_source_edits,
+      'commit_docs_bypass':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_BYPASS),
+      'commit_docs_force':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_FORCE),
+      'commit_docs_allow_direct_edits':
+          lambda h: commit_msg_has_tag(h, TAG_DOCS_ALLOW_DIRECT_EDITS),
+  }
+
+  possible_str = ', '.join(list(possible_conditions.keys()))
+  parser.add_argument(
+      '--do-and',
+      type=str,
+      help=(
+          f'A conjunction of boolean conditions. Possible values are={possible_str}. '
+          'Negation is done with `-`'
+      )
+  )
+  parser.add_argument(
+      '--do-or',
+      type=str,
+      help=(
+          f'A disjunction of boolean conditions. Possible values are={possible_str}. '
+          'Negation is done with `-`'
+      )
+  )
+
+  args, _ = parser.parse_known_args(sys.argv[1:len(sys.argv) - 1])
+  commit_hash = sys.argv[-1]
+
+  assert not (args.do_and and args.do_or), "Must not supply both '--do-and' and '--do-or'"
+  assert args.do_and or args.do_or, "Must supply argument '--do-and' or '--do-or'"
+  conds = args.do_and.split(',') if args.do_and else args.do_or.split(',')
+  conds = [c.strip() for c in conds]
+  assert all(
+    [c in possible_conditions.keys() for c in
+     [(c.replace('-', '') if c.startswith('-') else c) for c in conds]]),\
+     f"Not all conditions are valid names. Only {possible_str} are accepted"
+
+  res = []
+  for cond in conds:
+    if cond.startswith('-'):
+      f = lambda: not possible_conditions[cond.replace('-', '')]()
+    else:
+      f = possible_conditions[cond]
+    res.append(f(commit_hash))
+
+  if args.do_and:
+    exit(0 if all(res) else 1)
+  else:
+    exit(0 if any(res) else 1)

docs_src/build/duplicates.json

@@ -0,0 +1,74 @@
+{
+    "README.md": {
+        "dest": "dup/intro.md",
+        "link_transforms": {
+            "BUILDING.md": "building.md",
+            "/CONTRIBUTING.md": "contributing.md",
+            "/CODE_STYLE.md": "code_style.md",
+            "docs/images/samples": "../images/samples"
+        }
+    },
+    "BUILDING.md": {
+        "dest": "dup/building.md"
+    },
+    "CONTRIBUTING.md": {
+        "dest": "dup/contributing.md"
+    },
+    "CODE_STYLE.md": {
+        "dest": "dup/code_style.md"
+    },
+    "libs/uberz/README.md": {
+        "dest": "dup/uberz.md"
+    },
+    "libs/bluegl/README.md": {
+        "dest": "dup/bluegl.md"
+    },
+    "libs/bluevk/README.md": {
+        "dest": "dup/bluevk.md"
+    },
+    "libs/gltfio/README.md": {
+        "dest": "dup/gltfio.md"
+    },
+    "libs/filamat/README.md": {
+        "dest": "dup/filamat.md"
+    },
+    "libs/iblprefilter/README.md": {
+        "dest": "dup/iblprefilter.md"
+    },
+    "libs/matdbg/README.md": {
+        "dest": "dup/matdbg.md"
+    },
+    "tools/normal-blending/README.md": {
+        "dest": "dup/normal_blending.md"
+    },
+    "tools/filamesh/README.md": {
+        "dest": "dup/filamesh.md"
+    },
+    "tools/beamsplitter/README.md": {
+        "dest": "dup/beamsplitter.md"
+    },
+    "tools/cmgen/README.md": {
+        "dest": "dup/cmgen.md"
+    },
+    "tools/mipgen/README.md": {
+        "dest": "dup/mipgen.md"
+    },
+    "tools/matinfo/README.md": {
+        "dest": "dup/matinfo.md"
+    },
+    "tools/roughness-prefilter/README.md": {
+        "dest": "dup/roughness_prefilter.md"
+    },
+    "tools/zbloat/README.md": {
+        "dest": "dup/zbloat.md"
+    },
+    "tools/cso-lut/README.md": {
+        "dest": "dup/cso_lut.md"
+    },
+    "tools/specular-color/README.md": {
+        "dest": "dup/specular_color.md"
+    },
+    "docs_src/README.md": {
+        "dest": "dup/docs.md"
+    }
+}

docs_src/build/install_mdbook.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/bash
+
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+DARWIN_X86=1
+LINUX_X86=2
+DARWIN_ARM=3
+LINUX_ARM=4
+
+function add_cargo_path() {
+    local BASH_P="${HOME}/.bashrc"
+    local PATH_LINE='export PATH=${PATH}:~/.cargo/bin'
+    local TYPE=$1
+    if [ ${TYPE} == ${DARWIN_ARM} ] || [ ${TYPE} == ${DARWIN_X86} ]; then
+        BASH_P="${HOME}/.bash_profile"
+    fi
+    if ! (grep "${PATH_LINE}" ${BASH_P}); then
+        echo "${PATH_LINE}" >> ${BASH_P}
+    fi
+    source ${BASH_P}
+}
+
+function download_mdbook() {
+    if command -v mdbook >/dev/null 2>&1; then
+        echo "mdbook already installed"
+        exit 0
+    fi
+
+    local CHECK_UNAME="
+import sys;
+parts=[a.lower() for a in sys.stdin.read().strip().split(' ')];
+def get_type():
+  if 'darwin' in parts:
+    if 'x86_64' in parts:
+      return ${DARWIN_X86}
+    elif 'aarch' in parts:
+      return ${DARWIN_ARM}
+  elif 'linux' in parts:
+    if 'x86_64' in parts:
+      return ${LINUX_X86}
+    elif 'aarch' in parts:
+      return ${LINUX_ARM}
+  return 0
+print(get_type())
+"
+    local TYPE=`uname -a | python3 -c "${CHECK_UNAME}"`
+    if [ ${TYPE} == ${DARWIN_ARM} ] || [ ${TYPE} == ${LINUX_ARM} ]; then
+        # No github prebuilts are available, we build it with rust from source.
+        # First, need to install rust and cargo
+        if ! (command -v rustc >/dev/null 2>&1) || ! (command -v cargo >/dev/null 2>&1); then
+            echo "*** Need to install Rust ***"
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+        fi
+        if ! (command -v cargo >/dev/null 2>&1); then
+            echo "*** Still cannot find `cargo` ***"
+            exit 1
+        fi
+        cargo install mdbook
+    else
+        # Download prebuilts from github
+        mkdir -p ${HOME}/.cargo/bin
+        echo "*** Downloading mdbook from github release ***"
+        DL_URL='https://github.com/rust-lang/mdBook/releases/download/v0.4.43/mdbook-v0.4.43-x86_64-apple-darwin.tar.gz '
+        if [ ${TYPE} == ${LINUX_X86} ]; then
+            DL_URL='https://github.com/rust-lang/mdBook/releases/download/v0.4.43/mdbook-v0.4.43-x86_64-unknown-linux-gnu.tar.gz'
+        fi
+        curl -L -o ~/Downloads/mdbook.tar.gz ${DL_URL}
+        mkdir -p /tmp/mdbook
+        tar -xvzf ~/Downloads/mdbook.tar.gz -C /tmp/mdbook >/dev/null 2>&1
+        mv /tmp/mdbook/mdbook ~/.cargo/bin/
+    fi
+    add_cargo_path ${TYPE}
+}
+
+download_mdbook

docs_src/build/presubmit_check.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/bash
+
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+COMMIT_HASH=$1
+python3 docs_src/build/checks.py --do-or="no_direct_edits,commit_docs_allow_direct_edits" $COMMIT_HASH ||\
+    (echo "Direct edits to /docs are not allowed. Please see /docs_src/README.md if you need to bypass this check." && exit 1)

docs_src/build/run.py

@@ -0,0 +1,128 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import os
+import re
+from utils import execute, ArgParseImpl
+
+CUR_DIR = os.path.dirname(os.path.abspath(__file__))
+DOCS_SRC_DIR = os.path.join(CUR_DIR, '../')
+ROOT_DIR = os.path.join(CUR_DIR, '../../')
+SRC_DIR = os.path.join(CUR_DIR, '../src')
+MARKDEEP_DIR = os.path.join(CUR_DIR, '../markdeep')
+DUP_DIR = os.path.join(SRC_DIR, 'dup')
+MAIN_DIR = os.path.join(SRC_DIR, 'main')
+
+def transform_dup_file_link(line, transforms):
+  URL_CONTENT = '[-a-zA-Z0-9()@:%_\+.~#?&//=]+'
+  res = re.findall(f'\[(.+)\]\(({URL_CONTENT})\)', line)
+  for text, url in  res:
+    word = f'[{text}]({url})'
+    for tkey in transforms.keys():
+      if url.startswith(tkey):
+        nurl = url.replace(tkey, transforms[tkey])
+        line = line.replace(word, f'[{text}]({nurl})')
+        break
+  return line
+
+def pull_duplicates():
+  if not os.path.exists(DUP_DIR):
+    os.mkdir(DUP_DIR)
+
+  config = {}
+  with open(f'{CUR_DIR}/duplicates.json') as config_txt:
+    config = json.loads(config_txt.read())
+
+  for fin in config.keys():
+    new_name = config[fin]['dest']
+    link_transforms = config[fin].get('link_transforms', {})
+    fpath = os.path.join(ROOT_DIR, fin)
+    new_fpath = os.path.join(SRC_DIR, new_name)
+
+    with open(fpath, 'r') as in_file:
+      with open(new_fpath, 'w') as out_file:
+        for line in in_file.readlines():
+          out_file.write(transform_dup_file_link(line, link_transforms))
+
+def pull_markdeep_docs():
+  import http.server
+  import socketserver
+  import threading
+  from selenium import webdriver
+  from selenium.webdriver.chrome.options import Options
+  from selenium.webdriver.common.by import By
+  import time
+
+  class Server(socketserver.ThreadingMixIn, http.server.HTTPServer):
+    """Handle requests in a separate thread."""
+
+  class Handler(http.server.SimpleHTTPRequestHandler):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, directory=MARKDEEP_DIR, **kwargs)
+
+  def start_server(port):
+    """Starts the web server in a separate thread."""
+    httpd = Server(("", port), Handler)
+    server_thread = threading.Thread(target=httpd.serve_forever)
+    server_thread.daemon = True  # Allow main thread to exit
+    server_thread.start()
+    print(f"Server started on port {port}...")
+    return httpd
+
+  PORT = 12345
+  httpd = start_server(PORT)
+
+  # Set up Chrome options for headless mode
+  chrome_options = Options()
+  chrome_options.add_argument("--headless")
+
+  # This option is necessary for running on some VMs
+  chrome_options.add_argument("--no-sandbox")
+
+  # Create a new Chrome instance in headless mode
+  driver = webdriver.Chrome(options=chrome_options)
+
+  for doc in ['Filament', 'Materials']:
+    # Open the URL with ?export, which markdeep will export the resulting html.
+    driver.get(f"http://localhost:{PORT}/{doc}.md.html?export")
+
+    time.sleep(3)
+    # We extract the html from the resulting "page" (an html output itself).
+    text = driver.find_elements(By.TAG_NAME, "pre")[0].text
+
+    # 1. Remove the double empty lines.  These make the following text seem like markdown text as oppose to embedded html.
+    # 2. Remove the max-width styling from the body tag.
+    # 3. Remove the font-family styling from the body tag.
+    text = text.replace("\n\n","\n")\
+               .replace("max-width:680px;", "")\
+               .replace("font-family:Palatino", "--font-family:Palatino")\
+               .replace("\"./images", "\"../images")\
+               .replace("\"images/", "\"../images/")
+
+    # Save the page source as .md with embedded html
+    with open(f'{MAIN_DIR}/{doc.lower()}.md', "w", encoding="utf-8") as f:
+      f.write(text)
+
+  # Close the browser
+  driver.quit()
+  # Shutdown the server
+  httpd.shutdown()
+
+if __name__ == "__main__":
+  pull_duplicates()
+  pull_markdeep_docs()
+
+  res, err = execute('mdbook build', cwd=DOCS_SRC_DIR)
+  assert res == 0, f"failed to execute `mdbook`. return-code={res} err=\"{err}\""

docs_src/build/utils.py

@@ -0,0 +1,68 @@
+# Copyright (C) 2025 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import subprocess
+import os
+import argparse
+import sys
+
+def execute(cmd,
+            cwd=None,
+            capture_output=True,
+            stdin=None,
+            env=None,
+            raise_errors=False):
+  in_env = os.environ
+  in_env.update(env if env else {})
+  home = os.environ['HOME']
+  if f'{home}/bin' not in in_env['PATH']:
+    in_env['PATH'] = in_env['PATH'] + f':{home}/bin'
+
+  stdout = subprocess.PIPE if capture_output else sys.stdout
+  stderr = subprocess.PIPE if capture_output else sys.stdout
+  output = ''
+  err_output = ''
+  return_code = -1
+  kwargs = {
+      'cwd': cwd,
+      'env': in_env,
+      'stdout': stdout,
+      'stderr': stderr,
+      'stdin': stdin,
+      'universal_newlines': True
+  }
+  if capture_output:
+    process = subprocess.Popen(cmd.split(' '), **kwargs)
+    output, err_output = process.communicate()
+    return_code = process.returncode
+  else:
+    return_code = subprocess.call(cmd.split(' '), **kwargs)
+
+  if return_code:
+    # Error
+    if raise_errors:
+      raise subprocess.CalledProcessError(return_code, cmd)
+  if output:
+    if type(output) != str:
+      try:
+        output = output.decode('utf-8').strip()
+      except UnicodeDecodeError as e:
+        print('cannot decode ', output, file=sys.stderr)
+  return return_code, (output if return_code == 0 else err_output)
+
+class ArgParseImpl(argparse.ArgumentParser):
+  def error(self, message):
+    sys.stderr.write('error: %s\n' % message)
+    self.print_help()
+    sys.exit(1)

docs_src/markdeep/README.md

@@ -0,0 +1,10 @@
+# Markdeep documents
+
+Markdeep documents require special processing before they can be compiled into the group.
+The "original" are stored in this folder. The processing part takes place in
+`docs_src/build/run.py`.
+
+## Editing
+While editing the file, you might consider doing the following
+ - `python3 -m http.server 8001`
+ - visit `http://localhost:8001/Filament.md.html` in the browser to view the result

docs_src/src/SUMMARY.md

@@ -0,0 +1,39 @@
+# Summary
+
+- [Introduction](./dup/intro.md)
+  - [Build](./dup/building.md)
+    - [Build for Android on Windows](./build/windows_android.md)
+  - [Contribute](./dup/contributing.md)
+  - [Coding Style](./dup/code_style.md)
+- [Core Concepts](./main/README.md)
+  - [Filament](./main/filament.md)
+  - [Materials](./main/materials.md)
+- [Tutorials and Samples](./samples/README.md)
+  - [iOS Tutorial](./samples/ios.md)
+  - [Web Tutorial](./samples/web.md)
+- [Technical Notes](./notes/README.md)
+  - [Versioning](./notes/versioning.md)
+  - [Documentation](./dup/docs.md)
+  - [Debugging](./notes/debugging.md)
+    - [Metal](./notes/metal_debugging.md)
+    - [Vulkan](./notes/vulkan_debugging.md)
+    - [SPIR-V](./notes/spirv_debugging.md)
+  - [Libraries](./notes/libs.md)
+    - [bluegl](./dup/bluegl.md)
+    - [bluevk](./dup/bluevk.md)
+    - [filamat](./dup/filamat.md)
+    - [gltfio](./dup/gltfio.md)
+    - [iblprefilter](./dup/iblprefilter.md)
+    - [matdbg](./dup/matdbg.md)
+    - [uberz](./dup/uberz.md)
+  - [Tools](./notes/tools.md)
+    - [beamsplitter](./dup/beamsplitter.md)
+    - [cmgen](./dup/cmgen.md)
+    - [cso-lut](./dup/cso_lut.md)
+    - [filamesh](./dup/filamesh.md)
+    - [normal-blending](./dup/normal_blending.md)
+    - [mipgen](./dup/mipgen.md)
+    - [matinfo](./dup/matinfo.md)
+    - [roughness-prefilter](./dup/roughness_prefilter.md)
+    - [specular-color](./dup/specular_color.md)
+    - [zbloat](./dup/zbloat.md)

docs_src/src/dup/README.txt

@@ -0,0 +1,2 @@
+Do not manually edit any file in this folder. They have been autogenerated
+by a script.