wip: nix

Even if skinning is not fully implemented on FL0, we have clients which depend
on materials with skinning variants that otherwise could easily be converted to
FL0 materials. There are two proper ways to deal with this:

1. Support skinning/morphing in Feature Level 0.

2. Allow ESSL 1.0 code and ESSL 3.0 code to support different sets of variants.

However, the simplest solution is to just include skinning/morphing variants,
but disable codegen for ESSL 1.0 code, making them identical to the base
variants. This shouldn't increase the file size much due to the dictionary
deflation. Of course, skinning will not work correctly on FL0, but this has
always been the case. Future work here would be to properly implement one of the
two solutions described above.

.dir-locals.el

@@ -0,0 +1,7 @@
+;;; Directory Local Variables            -*- no-byte-compile: t -*-
+;;; For more information see (info "(emacs) Directory Variables")
+
+((c++-mode . ((c-file-style . "filament")
+              (apheleia-inhibit . t)))
+ (c-mode . ((c-file-style . "filament")
+            (apheleia-inhibit . t))))

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+
+[*.{c,cpp,h,inc,kt,java,js,md}]
+indent_style = space
+indent_size = 4
+max_line_length = 100

.github/ISSUE_TEMPLATE/bug_report.md

@@ -4,6 +4,8 @@ about: Create a report to help us improve
 
 ---
 
+⚠️ **Issues not using this template will be systematically closed.**
+
 **Describe the bug**
 A clear and concise description of what the bug is.
 
@@ -18,8 +20,8 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Logs**
-If applicable, copy logs from your console here. Please *do not*
-use screenshots of logs, copy them as text.
+If applicable, copy **full** logs from your console here. Please *do not*
+use screenshots of logs, copy them as text, use gist or attach an *uncompressed* file.
 
 **Desktop (please complete the following information):**
  - OS: [e.g. iOS]

.github/workflows/android-continuous.yml

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

.github/workflows/cocopods-deploy.yml

@@ -0,0 +1,30 @@
+name: CocoaPods Deploy
+
+# This must be run after the iOS release job has finished, and the iOS release
+# asset has been uploaded to Github.
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release tag to deploy (e.g., v1.42.2)'
+        required: true
+        default: 'v1.42.2'
+
+jobs:
+  cocoapods-deploy:
+    name: cocoapods-deploy
+    runs-on: macos-latest
+    steps:
+      - name: Check out iOS/CocoaPods directory
+        uses: Bhacaz/checkout-files@49fc3050859046bf4f4873678d46099985640e89
+        with:
+          files: ios/CocoaPods
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: ${{ github.event.inputs.release_tag }}
+      - name: Move podspec to root
+        run: mv ios/CocoaPods/*.podspec .
+      - name: Install CocoaPods
+        run: gem install cocoapods
+      - uses: michaelhenry/deploy-to-cocoapods-github-action@745686ab065f90596e0d5cfcf97bb2416d94262e
+        env:
+          COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}

.github/workflows/npm-deploy.yml

@@ -0,0 +1,33 @@
+name: Npm Deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_tag:
+        description: 'Release tag to deploy (e.g., v1.42.2)'
+        required: true
+        default: 'v1.42.2'
+
+jobs:
+  npm-deploy:
+    name: npm-deploy
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v3.3.0
+        with:
+          ref: ${{ github.event.inputs.release_tag }}
+      # Setup .npmrc file to publish to npm
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Run build script
+        run: |
+          cd build/web && printf "y" | ./build.sh release
+      - name: Deploy to npm
+        run: |
+          cd out/cmake-webgl-release/web/filament-js
+          npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+

.github/workflows/release.yml

@@ -124,7 +124,6 @@ jobs:
           cd ../..
           mv out/filament-android-release.aar out/filament-${TAG}-android.aar
           mv out/filamat-android-release.aar out/filamat-${TAG}-android.aar
-          mv out/filamat-android-lite-release.aar out/filamat-${TAG}-lite-android.aar
           mv out/gltfio-android-release.aar out/gltfio-${TAG}-android.aar
           mv out/filament-utils-android-release.aar out/filament-utils-${TAG}-android.aar
       - name: Sign sample-gltf-viewer
@@ -206,8 +205,7 @@ jobs:
           TAG: ${{ steps.git_ref.outputs.tag }}
         run: |
           build\windows\build-github.bat release
-          cd ..\..
-          move out\filament-windows.tgz out\filament-%TAG%-windows.tgz
+          move out\filament-windows.tgz out\filament-$Env:TAG-windows.tgz
         shell: cmd
       - uses: actions/github-script@v6
         env:

.gitignore

@@ -16,3 +16,7 @@ settings.json
 test*.png
 test*.json
 results
+/compile_commands.json
+/.cache
+# Nix
+/result*

BUILDING.md

@@ -5,7 +5,7 @@
 To build Filament, you must first install the following tools:
 
 - CMake 3.19 (or more recent)
-- clang 7.0 (or more recent)
+- clang 14.0 (or more recent)
 - [ninja 1.10](https://github.com/ninja-build/ninja/wiki/Pre-built-Ninja-packages) (or more recent)
 
 Additional dependencies may be required for your operating system. Please refer to the appropriate
@@ -40,25 +40,27 @@ inside the Filament source tree.
 
 To trigger an incremental debug build:
 
-```
-$ ./build.sh debug
+```shell
+./build.sh debug
 ```
 
 To trigger an incremental release build:
 
-```
-$ ./build.sh release
+```shell
+./build.sh release
 ```
 
 To trigger both incremental debug and release builds:
 
-```
-$ ./build.sh debug release
+```shell
+./build.sh debug release
 ```
 
+If build fails for some reasons, it may leave the `out/` directory in a broken state. You can
+force a clean build by adding the `-c` flag in that case.
+
 To install the libraries and executables in `out/debug/` and `out/release/`, add the `-i` flag.
-You can force a clean build by adding the `-c` flag. The script offers more features described
-by executing `build.sh -h`.
+The script offers more features described by executing `build.sh -h`.
 
 ### Filament-specific CMake Options
 
@@ -76,9 +78,9 @@ The following CMake options are boolean options specific to Filament:
 
 To turn an option on or off:
 
-```
-$ cd <cmake-build-directory>
-$ cmake . -DOPTION=ON       # Relace OPTION with the option name, set to ON / OFF
+```shell
+cd <cmake-build-directory>
+cmake . -DOPTION=ON       # Replace OPTION with the option name, set to ON / OFF
 ```
 
 Options can also be set with the CMake GUI.
@@ -87,10 +89,10 @@ Options can also be set with the CMake GUI.
 
 Make sure you've installed the following dependencies:
 
-- `clang-7` or higher
+- `clang-14` or higher
 - `libglu1-mesa-dev`
-- `libc++-7-dev` (`libcxx-devel` and `libcxx-static` on Fedora) or higher
-- `libc++abi-7-dev` (`libcxxabi-static` on Fedora) or higher
+- `libc++-14-dev` (`libcxx-devel` and `libcxx-static` on Fedora) or higher
+- `libc++abi-14-dev` (`libcxxabi-static` on Fedora) or higher
 - `ninja-build`
 - `libxi-dev`
 - `libxcomposite-dev` (`libXcomposite-devel` on Fedora)
@@ -102,38 +104,38 @@ script.
 If you'd like to run `cmake` directly rather than using the build script, it can be invoked as
 follows, with some caveats that are explained further down.
 
-```
-$ mkdir out/cmake-release
-$ cd out/cmake-release
-$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
+```shell
+mkdir out/cmake-release
+cd out/cmake-release
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
 ```
 
 Your Linux distribution might default to `gcc` instead of `clang`, if that's the case invoke
 `cmake` with the following command:
 
-```
-$ mkdir out/cmake-release
-$ cd out/cmake-release
-# Or use a specific version of clang, for instance /usr/bin/clang-7
-$ CC=/usr/bin/clang CXX=/usr/bin/clang++ CXXFLAGS=-stdlib=libc++ \
-    cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
+```shell
+mkdir out/cmake-release
+cd out/cmake-release
+# Or use a specific version of clang, for instance /usr/bin/clang-14
+CC=/usr/bin/clang CXX=/usr/bin/clang++ CXXFLAGS=-stdlib=libc++ \
+  cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
 ```
 
 You can also export the `CC` and `CXX` environment variables to always point to `clang`. Another
 solution is to use `update-alternatives` to both change the default compiler, and point to a
 specific version of clang:
 
-```
-$ update-alternatives --install /usr/bin/clang clang /usr/bin/clang-7 100
-$ update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-7 100
-$ update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100
-$ update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
+```shell
+update-alternatives --install /usr/bin/clang clang /usr/bin/clang-14 100
+update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-14 100
+update-alternatives --install /usr/bin/cc cc /usr/bin/clang 100
+update-alternatives --install /usr/bin/c++ c++ /usr/bin/clang++ 100
 ```
 
 Finally, invoke `ninja`:
 
-```
-$ ninja
+```shell
+ninja
 ```
 
 This will build Filament, its tests and samples, and various host tools.
@@ -143,8 +145,8 @@ This will build Filament, its tests and samples, and various host tools.
 To compile Filament you must have the most recent version of Xcode installed and you need to
 make sure the command line tools are setup by running:
 
-```
-$ xcode-select --install
+```shell
+xcode-select --install
 ```
 
 If you wish to run the Vulkan backend instead of the default Metal backend, you must install
@@ -152,11 +154,11 @@ the LunarG SDK, enable "System Global Components", and reboot your machine.
 
 Then run `cmake` and `ninja` to trigger a build:
 
-```
-$ mkdir out/cmake-release
-$ cd out/cmake-release
-$ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
-$ ninja
+```shell
+mkdir out/cmake-release
+cd out/cmake-release
+cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/filament ../..
+ninja
 ```
 
 ### iOS
@@ -164,24 +166,24 @@ $ ninja
 The easiest way to build Filament for iOS is to use `build.sh` and the
 `-p ios` flag. For instance to build the debug target:
 
-```
-$ ./build.sh -p ios debug
+```shell
+./build.sh -p ios debug
 ```
 
 See [ios/samples/README.md](./ios/samples/README.md) for more information.
 
 ### Windows
 
-#### Building on Windows with Visual Studio 2019
+#### Building on Windows with Visual Studio 2019 or later
 
 Install the following components:
 
-- [Visual Studio 2019](https://www.visualstudio.com/downloads)
-- [Windows 10 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk)
+- [Visual Studio 2019 or later](https://www.visualstudio.com/downloads)
+- [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)
 - [Python 3.7](https://www.python.org/ftp/python/3.7.0/python-3.7.0.exe)
 - [CMake 3.14 or later](https://github.com/Kitware/CMake/releases/download/v3.14.7/cmake-3.14.7-win64-x64.msi)
 
-The latest Windows SDK can also by installed by opening Visual Studio and selecting _Get Tools and
+The latest Windows SDK can also be installed by opening Visual Studio and selecting _Get Tools and
 Features..._ under the _Tools_ menu.
 
 By default, Windows treats the file system as case insensitive. Please do not enable case
@@ -191,10 +193,10 @@ using `fsutil.exe file queryCaseSensitiveInfo`.
 Next, open `x64 Native Tools Command Prompt for VS 2019`, create a working directory, and run
 CMake in it:
 
-```
-> mkdir out
-> cd out
-> cmake ..
+```bat
+mkdir out
+cd out
+cmake ..
 ```
 
 Open the generated solution file `TNT.sln` in Visual Studio.
@@ -204,15 +206,15 @@ target in the _Solution Explorer_ and choose _Build_ to build a specific target.
 
 For example, build the `material_sandbox` sample and run it from the `out` directory with:
 
-```
-> samples\Debug\material_sandbox.exe ..\assets\models\monkey\monkey.obj
+```bat
+samples\Debug\material_sandbox.exe ..\assets\models\monkey\monkey.obj
 ```
 
 You can also use CMake to invoke the build without opening Visual Studio. For example, from the
 `out` folder run the following command.
 
-```
-> cmake --build . --target gltf_viewer --config Release
+```bat
+cmake --build . --target gltf_viewer --config Release
 ```
 
 ### Android
@@ -237,8 +239,8 @@ To build Android on Windows machines, see [android/Windows.md](android/Windows.m
 The easiest way to build Filament for Android is to use `build.sh` and the
 `-p android` flag. For instance to build the release target:
 
-```
-$ ./build.sh -p android release
+```shell
+./build.sh -p android release
 ```
 
 Run `build.sh -h` for more information.
@@ -248,23 +250,23 @@ Run `build.sh -h` for more information.
 Invoke CMake in a build directory of your choice, inside of filament's directory. The commands
 below show how to build Filament for ARM 64-bit (`aarch64`).
 
-```
-$ mkdir out/android-build-release-aarch64
-$ cd out/android-build-release-aarch64
-$ cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \
-        -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../..
+```shell
+mkdir out/android-build-release-aarch64
+cd out/android-build-release-aarch64
+cmake -G Ninja -DCMAKE_TOOLCHAIN_FILE=../../build/toolchain-aarch64-linux-android.cmake \
+      -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../android-release/filament ../..
 ```
 
 And then invoke `ninja`:
 
-```
-$ ninja install
+```shell
+ninja install
 ```
 
 or
 
-```
-$ ninja install/strip
+```shell
+ninja install/strip
 ```
 
 This will generate Filament's Android binaries in `out/android-release`. This location is important
@@ -296,8 +298,8 @@ AAR.
 Alternatively you can build the AAR from the command line by executing the following in the
 `android/` directory:
 
-```
-$ ./gradlew -Pcom.google.android.filament.dist-dir=../../out/android-release/filament assembleRelease
+```shell
+./gradlew -Pcom.google.android.filament.dist-dir=../../out/android-release/filament assembleRelease
 ```
 
 The `-Pcom.google.android.filament.dist-dir` can be used to specify a different installation
@@ -311,7 +313,7 @@ sure to add the newly created module as a dependency to your application.
 If you do not wish to include all supported ABIs, make sure to create the appropriate flavors in
 your Gradle build file. For example:
 
-```
+```gradle
 flavorDimensions 'cpuArch'
 productFlavors {
     arm8 {
@@ -353,7 +355,7 @@ started, follow the instructions for building Filament on your platform ([macOS]
 Next, you need to install the Emscripten SDK. The following instructions show how to install the
 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
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
@@ -364,7 +366,7 @@ source ./emsdk_env.sh
 
 After this you can invoke the [easy build](#easy-build) script as follows:
 
-```
+```shell
 export EMSDK=<your chosen home for the emscripten SDK>
 ./build.sh -p webgl release
 ```
@@ -374,7 +376,7 @@ creates a `samples` folder that can be used as the root of a simple static web s
 cannot open the HTML directly from the filesystem due to CORS. We recommend using the emrun tool
 to create a quick localhost server:
 
-```
+```shell
 emrun out/cmake-webgl-release/web/samples --no_browser --port 8000
 ```
 
@@ -395,7 +397,7 @@ Some of the samples accept FBX/OBJ meshes while others rely on the `filamesh` fi
 generate a `filamesh ` file from an FBX/OBJ asset, run the `filamesh` tool
 (`./tools/filamesh/filamesh` in your build directory):
 
-```
+```shell
 filamesh ./assets/models/monkey/monkey.obj monkey.filamesh
 ```
 
@@ -405,7 +407,7 @@ files for the IBL (which are PNGs containing `R11F_G11F_B10F` data) or a path to
 containing two `.ktx` files (one for the IBL itself, one for the skybox). To generate an IBL
 simply use this command:
 
-```
+```shell
 cmgen -f ktx -x ./ibls/ my_ibl.exr
 ```
 
@@ -427,9 +429,9 @@ value is the desired roughness between 0 and 1.
 To generate the documentation you must first install `doxygen` and `graphviz`, then run the 
 following commands:
 
-```
-$ cd filament/filament
-$ doxygen docs/doxygen/filament.doxygen
+```shell
+cd filament/filament
+doxygen docs/doxygen/filament.doxygen
 ```
 
 Finally simply open `docs/html/index.html` in your web browser.
@@ -439,7 +441,7 @@ Finally simply open `docs/html/index.html` in your web browser.
 To try out Filament's Vulkan support with SwiftShader, first build SwiftShader and set the
 `SWIFTSHADER_LD_LIBRARY_PATH` variable to the folder that contains `libvk_swiftshader.dylib`:
 
-```
+```shell
 git clone https://github.com/google/swiftshader.git
 cd swiftshader/build
 cmake .. &&  make -j
@@ -454,7 +456,7 @@ Continuous testing turnaround can be quite slow if you need to build SwiftShader
 provide an Ubuntu-based Docker image that has it already built. The Docker image also includes
 everything necessary for building Filament. You can fetch and run the image as follows:
 
-```
+```shell
 docker pull ghcr.io/filament-assets/swiftshader
 docker run -it ghcr.io/filament-assets/swiftshader
 ```

CMakeLists.txt

@@ -3,6 +3,14 @@
 # ==================================================================================================
 cmake_minimum_required(VERSION 3.19)
 
+# ==================================================================================================
+# Toolchain configuration
+# ==================================================================================================
+if (APPLE AND NOT IOS)
+    # This must be set before project() is called
+    set(CMAKE_OSX_DEPLOYMENT_TARGET 10.15 CACHE STRING "")
+endif()
+
 # ==================================================================================================
 # Project declaration
 # ==================================================================================================
@@ -33,6 +41,8 @@ option(FILAMENT_LINUX_IS_MOBILE "Treat Linux as Mobile" OFF)
 
 option(FILAMENT_ENABLE_ASAN_UBSAN "Enable Address and Undefined Behavior Sanitizers" OFF)
 
+option(FILAMENT_ENABLE_FEATURE_LEVEL_0 "Enable Feature Level 0" ON)
+
 set(FILAMENT_NDK_VERSION "" CACHE STRING
     "Android NDK version or version prefix to be used when building for Android."
 )
@@ -57,6 +67,9 @@ set(FILAMENT_METAL_HANDLE_ARENA_SIZE_IN_MB "8" CACHE STRING
     "Size of the Metal handle arena, default 8."
 )
 
+# Enable exceptions by default in spirv-cross.
+set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS OFF)
+
 # ==================================================================================================
 # CMake policies
 # ==================================================================================================
@@ -308,8 +321,15 @@ if (WIN32)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -D_USE_MATH_DEFINES=1")
 endif()
 
+set(CMAKE_VERBOSE_MAKEFILE ON)
+
 if (LINUX)
     option(USE_STATIC_LIBCXX "Link against the static runtime libraries." ON)
+
+    if (DEFINED ENV{NIX_CC})
+        set(USE_STATIC_LIBCXX OFF)
+    endif()
+
     if (${USE_STATIC_LIBCXX})
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -stdlib=libc++")
         link_libraries("-static-libgcc -static-libstdc++")
@@ -329,6 +349,7 @@ endif()
 
 if (CYGWIN)
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-exceptions -fno-rtti")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
 endif()
 
 if (MSVC)
@@ -365,6 +386,7 @@ endif()
 # saved by -fno-exception and 10 KiB saved by -fno-rtti).
 if (ANDROID OR IOS OR WEBGL)
     set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -fno-exceptions -fno-rtti")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
 
     if (ANDROID OR WEBGL)
         # Omitting unwind info prevents the generation of readable stack traces in crash reports on iOS
@@ -372,6 +394,13 @@ if (ANDROID OR IOS OR WEBGL)
     endif()
 endif()
 
+# Turn off exceptions on iOS debug as well. This fixes an availability error we see when using
+# std::visit, which is not supported on iOS 11.0 when exceptions are enabled.
+if (IOS)
+    set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fno-exceptions")
+    set(SPIRV_CROSS_EXCEPTIONS_TO_ASSERTIONS ON)
+endif()
+
 # With WebGL, we disable RTTI even for debug builds because we pass emscripten::val back and forth
 # between C++ and JavaScript in order to efficiently access typed arrays, which are unbound.
 # NOTE: This is not documented in emscripten so we should consider a different approach.
@@ -479,13 +508,6 @@ else()
     option(FILAMENT_ENABLE_MATDBG "Enable the material debugger" OFF)
 endif()
 
-# By default, link in fgdbg for Desktop + Debug
-if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND IS_HOST_PLATFORM)
-    option(FILAMENT_ENABLE_FGDBG "Enable the framegraph debugger" ON)
-else()
-    option(FILAMENT_ENABLE_FGDBG "Enable the framegraph debugger" OFF)
-endif()
-
 # Only optimize materials in Release mode (so error message lines match the source code)
 if (CMAKE_BUILD_TYPE MATCHES Release)
     option(FILAMENT_DISABLE_MATOPT "Disable material optimizations" OFF)
@@ -516,6 +538,11 @@ if (FILAMENT_SUPPORTS_METAL)
     set(MATC_API_FLAGS ${MATC_API_FLAGS} -a metal)
 endif()
 
+# Disable ESSL 1.0 code generation.
+if (NOT FILAMENT_ENABLE_FEATURE_LEVEL_0)
+    set(MATC_API_FLAGS ${MATC_API_FLAGS} -1)
+endif()
+
 # Enable debug info (preserves names in SPIR-V)
 if (FILAMENT_ENABLE_MATDBG)
     set(MATC_OPT_FLAGS ${MATC_OPT_FLAGS} -d)
@@ -718,15 +745,13 @@ if (FILAMENT_BUILD_FILAMAT OR IS_HOST_PLATFORM)
     if (FILAMENT_ENABLE_MATDBG OR IS_HOST_PLATFORM)
         add_subdirectory(${LIBRARIES}/matdbg)
     endif()
-
-    if (FILAMENT_ENABLE_FGDBG OR IS_HOST_PLATFORM)
-        add_subdirectory(${LIBRARIES}/fgdbg)
-    endif()
 endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)
     add_subdirectory(${LIBRARIES}/bluevk)
     add_subdirectory(${EXTERNAL}/vkmemalloc/tnt)
+    set(SPIRV_HEADERS_SKIP_EXAMPLES ON)
+    add_subdirectory(${EXTERNAL}/spirv-headers)
 endif()
 
 set(FILAMENT_SAMPLES_BINARY_DIR ${PROJECT_BINARY_DIR}/samples)

CONTRIBUTING.md

@@ -27,7 +27,7 @@ again.
 
 ## Code Style
 
-See [CodeStyle.md](/CODE_STYLE.md)
+See [CODE_STYLE.md](/CODE_STYLE.md)
 
 ## Code reviews
 

NEW_RELEASE_NOTES.md

@@ -8,5 +8,4 @@ appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
 
-- engine: a new feature to set a transform on the global-scale fog  [⚠️ **Recompile materials**]
-- engine: large-scale fog can now be opted-out on a per-renderable basis
+- matc: Generate skinning variants for FL0 materials [⚠️ **Recompile materials**]

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.36.0'
+    implementation 'com.google.android.filament:filament-android:1.48.0'
 }
 ```
 
@@ -40,6 +40,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 | Artifact      | Description   |
 | ------------- | ------------- |
 | [![filament-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android/badge.svg?subject=filament-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android)  | The Filament rendering engine itself. |
+| [![filament-android-debug](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug/badge.svg?subject=filament-android-debug)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-android-debug)  | Debug version of `filament-android`. |
 | [![gltfio-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android/badge.svg?subject=gltfio-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/gltfio-android) | A glTF 2.0 loader for Filament, depends on `filament-android`. |
 | [![filament-utils-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android/badge.svg?subject=filament-utils-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filament-utils-android) | KTX loading, Kotlin math, and camera utilities, depends on `gltfio-android`. |
 | [![filamat-android](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android/badge.svg?subject=filamat-android)](https://maven-badges.herokuapp.com/maven-central/com.google.android.filament/filamat-android) | A runtime material builder/compiler. This library is large but contains a full shader compiler/validator/optimizer and supports both OpenGL and Vulkan. |
@@ -49,8 +50,8 @@ Here are all the libraries available in the group `com.google.android.filament`:
 
 iOS projects can use CocoaPods to install the latest release:
 
-```
-pod 'Filament', '~> 1.36.0'
+```shell
+pod 'Filament', '~> 1.48.0'
 ```
 
 ### Snapshots
@@ -312,7 +313,6 @@ and tools.
   - `bluegl`:                 OpenGL bindings for macOS, Linux and Windows
   - `bluevk`:                 Vulkan bindings for macOS, Linux, Windows and Android
   - `camutils`:               Camera manipulation utilities
-  - `fgdbg`:                  Frame Graph inspector and debugger (debug builds only)
   - `filabridge`:             Library shared by the Filament engine and host tools
   - `filaflat`:               Serialization/deserialization library used for materials
   - `filagui`:                Helper library for [Dear ImGui](https://github.com/ocornut/imgui)

RELEASE_GUIDE.md

@@ -9,11 +9,15 @@ Before starting, ensure that each of these branches is up-to-date with origin:
 - rc/$RELEASE
 - main
 
-## 0. Make sure the rc/$RELEASE branch has the correct version.
+## 0. Check versions.
 
-It should have the version corresponding to its name, $RELEASE.
+Make sure the rc/$RELEASE branch has the correct Filament version. It should have the version
+corresponding to its name, $RELEASE.
 
-## 1. Bump versions on main to $RELEASE.
+Make sure `MATERIAL_VERSION` has been bumped to a new version if this is a MAJOR or MINOR release
+(first two version numbers).
+
+## 1. Bump Filament versions on main to $RELEASE.
 
 Checkout main and run the following command to bump Filament's version to $RELEASE:
 
@@ -124,3 +128,15 @@ Navigate to [Filament's release
 workflow](https://github.com/google/filament/actions/workflows/release.yml). Hit the _Run workflow_
 dropdown. Modify _Platform to build_ and _Release tag to build_, then hit _Run workflow_. This will
 initiate a new release run.
+
+## 11. Kick off the npm and CocoaPods release jobs
+
+Navigate to [Filament's npm deploy
+workflow](https://github.com/google/filament/actions/workflows/npm-deploy.yml).
+Hit the _Run workflow_ dropdown. Modify _Release tag to deploy_ to the tag corresponding to this
+release (for example, v1.42.2).
+
+Navigate to [Filament's CocoaPods deploy
+workflow](https://github.com/google/filament/actions/workflows/cocopods-deploy.yml).
+Hit the _Run workflow_ dropdown. Modify _Release tag to deploy_ to the tag corresponding to this
+release (for example, v1.42.2).

RELEASE_NOTES.md

@@ -7,6 +7,143 @@ 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.49.0
+
+- matc: Fix ESSL 1.0 codegen when using external samplers [⚠️ **Recompile materials**]
+
+## v1.48.0
+
+- matc: New option `-1` to disable generation of ESSL 1.0 code in Feature Level 0 materials
+- matc: Support optimizations for ESSL 1.0 code [⚠️ **Recompile materials**]
+
+## v1.47.0
+
+- engine: Support up to 4 side-by-side stereoscopic eyes, configurable at Engine creation time. See
+  `Engine::Config::stereoscopicEyeCount`. [⚠️ **Recompile Materials**]
+
+## v1.46.0
+
+- engine: Allow instantiating Engine at a given feature level via `Engine::Builder::featureLevel`
+- matc: Enable `GL_OES_standard_derivatives` extension in ESSL 1.0 shaders
+- matc: Fix code generation of double sided and masked materials in ESSL 1.0 shaders
+- filagui: Add support for feature level 0
+- matc: Add support for post-process materials in feature level 0
+- engine: Add `Material::getFeatureLevel()`
+- engine: Add missing `Material::getReflectionMode()` method in Java
+- engine: Support basic usage of post-processing materials on feature level 0
+- engine: Fix critical GLES 2.0 bugs
+- engine: Add `FILAMENT_ENABLE_FEATURE_LEVEL_0` build-time option optionally allow building Filament
+  without FL0 support.
+
+## v1.45.1
+
+- engine: Added parameter for configuring JobSystem thread count
+- engine: In Java, introduce Engine.Builder
+- gltfio: fix ubershader index for transmission&volume material
+- engine: New tone mapper: `AgXTonemapper`.
+- matinfo: Add support for viewing ESSL 1.0 shaders
+- engine: Add `Renderer::getClearOptions()` [b/243846268]
+- engine: Fix stable shadows (again) when an IBL rotation is used
+
+## v1.45.0
+
+- materials: fix alpha masked materials when MSAA is turned on [⚠️ **Recompile materials**]
+- materials: better support materials with custom depth [**Recompile Materials**]
+- engine: fade shadows at shadowFar distance instead of hard cutoff [⚠️ **New Material Version**]
+
+## v1.44.0
+
+- engine: add support for skinning with more than four bones per vertex.
+- engine: remove `BloomOptions::anamorphism` which wasn't working well in most cases [**API CHANGE**]
+- engine: new API to return a Material's supported variants, C++ only (b/297456590)
+- build: fix emscripten-1.3.46 build
+- engine: materials built for feature level 0 can now also be loaded in higher feature levels [⚠️
+  **New Material Version**]
+
+## v1.43.1
+
+## v1.43.0
+
+- gltfio: Fix possible change of scale sign when decomposing transform matrix for animation
+- engine: Fixes "stable" shadows (see b/299310624)
+
+## v1.42.2
+
+- Fix possible NPE when updating fog options from Java/Kotlin
+- The `emissive` property was not applied properly to `MASKED` materials, and could cause
+  dark fringes to appear (recompile materials)
+- Allow glTF materials with transmission/volume extensions to choose their alpha mode
+  instead of forcing `MASKED`
+- Fix a crash in gltfio when not using ubershaders
+- Use flatmat for mat parameter in jsbinding
+- Fix TextureFlags for sheenRoughnessMap when textures of sheenRoughnessMap and sheenColorMap is same
+- Directional shadows can now be transformed (b/297095805)
+
+## v1.42.1
+
+- Fix potential `EXC_BAD_ACCESS` with Metal backend: b/297059776
+- `setFrameCompletedCallback` now takes a `backend::CallbackHandler`.
+
+## v1.42.0
+
+- engine: add preliminary support for instanced stereoscopic rendering [⚠️ **Recompile materials**]
+
+## v1.41.0
+
+- backend: fix #6997 : picking can fail on Adreno [⚠️ **New Material Version**]
+- backend: A partial workaround for PowerVR devices (#5118, b/190221124) [⚠️ **Recompile Materials**]
+
+## v1.40.5
+
+- backend: Disable timer queries on all Mali GPUs (fixes b/233754398)
+- engine: Add a way to query the validity of most filament objects (see `Engine::isValid`)
+- opengl: fix b/290388359 : possible crash when shutting down the engine
+- engine: Improve precision of frame time measurement when using emulated TimerQueries
+- backend: Improve frame pacing on Android and Vulkan.
+- backend: workaround b/291140208 (gltf_viewer crashes on Nexus 6P)
+- engine: support `setDepthFunc` for `MaterialInstance`
+- web: Added setDepthFunc()/getDepthFunc() to MaterialInstance
+- android: Added setDepthFunc()/getDepthFunc() to MaterialInstance
+
+## v1.40.4
+
+- gltfio: fix crash when compute morph target without material
+- matc: fix buggy `variant-filter` flag
+- web: Added missing setMat3Parameter()/setMat4Parameter() to MaterialInstance
+- opengl: fix b/290670707 : crash when using the blob cache
+- engine: fix a crash with `Material::compile()` when a callback is specified
+
+## v1.40.3
+
+## v1.40.2
+
+- rendering: dynamic resolution would not work with a translucent render target and quality > low
+- Java/Kotlin: user callbacks were not invoked on successful texture upload
+
+## v1.40.1
+
+## v1.40.0
+
+- matc: fix VSM high precision option on mobile [⚠️ **Recompile materials**]
+- vulkan: support sRGB swap chain
+- Add new `getMaxAutomaticInstances()` API on `Engine` to get max supported automatic instances.
+- UiHelper: fix jank when a `TextureView` is resized (fixes b\282220665)
+- backend: parallel shader compilation support. This breaks and improves the recent `Material::compile` API.
+
+## v1.39.0
+
+- matc: workaround a bug in spirv-tools causing vsm to fail [⚠️ **Recompile materials**]
+
+## v1.38.0
+
+- engine: a new feature to set a transform on the global-scale fog  [⚠️ **Recompile materials**]
+- engine: large-scale fog can now be opted-out on a per-renderable basis
+- engine: improve froxelizer resource efficiency [⚠️ **Recompile materials**]
+- matc: better accounting and validation of used samplers in user materials
+- engine: add support for sampling fog color from a custom texture [⚠️ **Recompile materials**]
+- vulkan: introduce new custom swapchain API
+- vulkan: new context sharing API
+
 ## v1.37.0
 
 - backend: added `Platform` blob cache APIs, typically used to cache programs [⚠️ **Recompile materials**]

android/Windows.md

@@ -135,7 +135,7 @@ gradlew -Pcom.google.android.filament.dist-dir=..\out\android-release\filament a
 If you're only interested in building SDK, you may skip samples build by passing a `com.google.android.filament.skip-samples` flag:
 
 ```
-gradlew -Pcom.google.android.filament.dist-dir=..\out\android-release\filament assembleRelease -Pfilament_skip_samples
+gradlew -Pcom.google.android.filament.dist-dir=..\out\android-release\filament assembleRelease -Pcom.google.android.filament.skip-samples
 ```
 
 

android/build.gradle

@@ -83,12 +83,12 @@ buildscript {
         'minSdk': 19,
         'targetSdk': 33,
         'compileSdk': 33,
-        'kotlin': '1.8.20',
-        'kotlin_coroutines': '1.6.4',
-        'buildTools': '33.0.2',
+        'kotlin': '1.9.0',
+        'kotlin_coroutines': '1.7.2',
+        'buildTools': '34.0.0',
         'ndk': '25.1.8937393',
-        'androidx_core': '1.10.0',
-        'androidx_annotations': '1.3.0'
+        'androidx_core': '1.10.1',
+        'androidx_annotations': '1.6.0'
     ]
 
     ext.deps = [
@@ -104,7 +104,7 @@ buildscript {
     ]
 
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.0.0'
+        classpath 'com.android.tools.build:gradle:8.1.0'
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}"
     }
 
@@ -152,7 +152,7 @@ buildscript {
 }
 
 plugins {
-    id "io.github.gradle-nexus.publish-plugin" version "1.1.0"
+    id "io.github.gradle-nexus.publish-plugin" version "1.3.0"
 }
 
 // See https://github.com/gradle-nexus/publish-plugin

android/filamat-android/CMakeLists.txt

@@ -6,9 +6,6 @@ option(FILAMENT_ENABLE_MATDBG "Enables Material debugger" OFF)
 set(FILAMENT_DIR ${FILAMENT_DIST_DIR})
 
 set(FILAMAT_FLAVOR "filamat")
-if(FILAMAT_LITE)
-    set(FILAMAT_FLAVOR "filamat_lite")
-endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)
     message("Library filamat ignores Vulkan settings")

android/filamat-android/build.gradle

@@ -1,29 +1,8 @@
 android {
     namespace 'com.google.android.filament.filamat'
 
-    flavorDimensions "functionality"
-    productFlavors {
-        full {
-            dimension "functionality"
-        }
-
-        lite {
-            dimension "functionality"
-
-            externalNativeBuild {
-                cmake {
-                    arguments.add("-DFILAMAT_LITE=ON")
-                }
-            }
-        }
-    }
-
     publishing {
-        singleVariant("fullRelease") {
-            withSourcesJar()
-            withJavadocJar()
-        }
-        singleVariant("liteRelease") {
+        singleVariant("release") {
             withSourcesJar()
             withJavadocJar()
         }
@@ -39,14 +18,9 @@ apply from: rootProject.file('gradle/gradle-mvn-push.gradle')
 afterEvaluate { project ->
     publishing {
         publications {
-            fullRelease(MavenPublication) {
+            release(MavenPublication) {
                 artifactId = POM_ARTIFACT_ID_FULL
-                from components.fullRelease
-            }
-
-            liteRelease(MavenPublication) {
-                artifactId = POM_ARTIFACT_ID_LITE
-                from components.liteRelease
+                from components.release
             }
         }
     }

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

@@ -25,15 +25,8 @@
 using namespace filament;
 using namespace utils;
 
-extern "C" JNIEXPORT jlong JNICALL
-Java_com_google_android_filament_Engine_nCreateEngine(JNIEnv*, jclass, jlong backend,
-        jlong sharedContext) {
-    return (jlong) Engine::create((Engine::Backend) backend, nullptr, (void*) sharedContext);
-}
-
 extern "C" JNIEXPORT void JNICALL
-Java_com_google_android_filament_Engine_nDestroyEngine(JNIEnv*, jclass,
-        jlong nativeEngine) {
+Java_com_google_android_filament_Engine_nDestroyEngine(JNIEnv*, jclass, jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
     Engine::destroy(&engine);
 }
@@ -278,6 +271,112 @@ Java_com_google_android_filament_Engine_nDestroyEntity(JNIEnv*, jclass,
     engine->destroy(entity);
 }
 
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidRenderer(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeRenderer) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Renderer*)nativeRenderer);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidView(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeView) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((View*)nativeView);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidScene(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeScene) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Scene*)nativeScene);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidFence(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeFence) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Fence*)nativeFence);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidStream(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeStream) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Stream*)nativeStream);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidIndexBuffer(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeIndexBuffer) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((IndexBuffer*)nativeIndexBuffer);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidVertexBuffer(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeVertexBuffer) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((VertexBuffer*)nativeVertexBuffer);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidSkinningBuffer(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeSkinningBuffer) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((SkinningBuffer*)nativeSkinningBuffer);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidIndirectLight(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeIndirectLight) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((IndirectLight*)nativeIndirectLight);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidMaterial(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeMaterial) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Material*)nativeMaterial);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidSkybox(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeSkybox) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Skybox*)nativeSkybox);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidColorGrading(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeColorGrading) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((ColorGrading*)nativeColorGrading);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidTexture(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeTexture) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((Texture*)nativeTexture);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidRenderTarget(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeTarget) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((RenderTarget*)nativeTarget);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Engine_nIsValidSwapChain(JNIEnv*, jclass,
+        jlong nativeEngine, jlong nativeSwapChain) {
+    Engine* engine = (Engine *)nativeEngine;
+    return (jboolean)engine->isValid((SwapChain*)nativeSwapChain);
+}
+
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
         jlong nativeEngine) {
@@ -285,6 +384,13 @@ Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
     engine->flushAndWait();
 }
 
+extern "C" JNIEXPORT void JNICALL
+Java_com_google_android_filament_Engine_nFlush(JNIEnv*, jclass,
+        jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    engine->flush();
+}
+
 // Managers...
 
 extern "C" JNIEXPORT jlong JNICALL
@@ -329,6 +435,13 @@ Java_com_google_android_filament_Engine_nIsAutomaticInstancingEnabled(JNIEnv*, j
     return (jboolean)engine->isAutomaticInstancingEnabled();
 }
 
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_nGetMaxStereoscopicEyes(JNIEnv*, jclass, jlong nativeEngine) {
+    Engine* engine = (Engine*) nativeEngine;
+    return (jlong) engine->getMaxStereoscopicEyes();
+}
+
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Engine_nGetSupportedFeatureLevel(JNIEnv *, jclass,
         jlong nativeEngine) {
@@ -348,4 +461,57 @@ Java_com_google_android_filament_Engine_nGetActiveFeatureLevel(JNIEnv *, jclass,
         jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
     return (jint)engine->getActiveFeatureLevel();
-}
+}
+
+extern "C" JNIEXPORT jlong JNICALL Java_com_google_android_filament_Engine_nCreateBuilder(JNIEnv*,
+        jclass) {
+    Engine::Builder* builder = new Engine::Builder{};
+    return (jlong) builder;
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nDestroyBuilder(JNIEnv*,
+        jclass, jlong nativeBuilder) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    delete builder;
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderBackend(
+        JNIEnv*, jclass, jlong nativeBuilder, jlong backend) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->backend((Engine::Backend) backend);
+}
+
+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 stereoscopicEyeCount) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    Engine::Config config = {
+            .commandBufferSizeMB = (uint32_t) commandBufferSizeMB,
+            .perRenderPassArenaSizeMB = (uint32_t) perRenderPassArenaSizeMB,
+            .driverHandleArenaSizeMB = (uint32_t) driverHandleArenaSizeMB,
+            .minCommandBufferSizeMB = (uint32_t) minCommandBufferSizeMB,
+            .perFrameCommandsSizeMB = (uint32_t) perFrameCommandsSizeMB,
+            .jobSystemThreadCount = (uint32_t) jobSystemThreadCount,
+            .stereoscopicEyeCount = (uint8_t) stereoscopicEyeCount,
+    };
+    builder->config(&config);
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderFeatureLevel(
+        JNIEnv*, jclass, jlong nativeBuilder, jint ordinal) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->featureLevel((Engine::FeatureLevel)ordinal);
+}
+
+extern "C" JNIEXPORT void JNICALL Java_com_google_android_filament_Engine_nSetBuilderSharedContext(
+        JNIEnv*, jclass, jlong nativeBuilder, jlong sharedContext) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    builder->sharedContext((void*) sharedContext);
+}
+
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_Engine_nBuilderBuild(JNIEnv*, jclass, jlong nativeBuilder) {
+    Engine::Builder* builder = (Engine::Builder*) nativeBuilder;
+    return (jlong) builder->build();
+}

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, 0);
+    env->ReleaseIntArrayElements(entities_, entities, JNI_ABORT);
 }
 
 extern "C" JNIEXPORT jint JNICALL

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

@@ -79,7 +79,8 @@ Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env,
         jfloat shadowFarHint, jboolean stable, jboolean lispsm,
         jfloat polygonOffsetConstant, jfloat polygonOffsetSlope,
         jboolean screenSpaceContactShadows, jint stepCount,
-        jfloat maxShadowDistance, jboolean elvsm, jfloat blurWidth, jfloat shadowBulbRadius) {
+        jfloat maxShadowDistance, jboolean elvsm, jfloat blurWidth, jfloat shadowBulbRadius,
+        jfloatArray transform) {
     LightManager::Builder *builder = (LightManager::Builder *) nativeBuilder;
     LightManager::ShadowOptions shadowOptions {
             .mapSize = (uint32_t)mapSize,
@@ -102,12 +103,18 @@ Java_com_google_android_filament_LightManager_nBuilderShadowOptions(JNIEnv* env,
             },
             .shadowBulbRadius = shadowBulbRadius
     };
+
     jfloat *nativeSplits = env->GetFloatArrayElements(splitPositions, NULL);
     const jsize splitCount = std::min((jsize) 3, env->GetArrayLength(splitPositions));
-    for (jsize i = 0; i < splitCount; i++) {
-        shadowOptions.cascadeSplitPositions[i] = nativeSplits[i];
-    }
+    std::copy_n(nativeSplits, splitCount, shadowOptions.cascadeSplitPositions);
     env->ReleaseFloatArrayElements(splitPositions, nativeSplits, 0);
+
+    jfloat* nativeTransform = env->GetFloatArrayElements(transform, NULL);
+    std::copy_n(nativeTransform,
+                std::min(4, env->GetArrayLength(transform)),
+                shadowOptions.transform.xyzw.v);
+    env->ReleaseFloatArrayElements(transform, nativeTransform, 0);
+
     builder->shadowOptions(shadowOptions);
 }
 

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

@@ -19,6 +19,7 @@
 #include <filament/Material.h>
 
 #include "common/NioUtils.h"
+#include "common/CallbackUtils.h"
 
 using namespace filament;
 
@@ -105,6 +106,22 @@ Java_com_google_android_filament_Material_nGetRefractionType(JNIEnv*, jclass,
     return (jint) material->getRefractionType();
 }
 
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetReflectionMode(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getReflectionMode();
+}
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Material_nGetFeatureLevel(JNIEnv*, jclass,
+        jlong nativeMaterial) {
+    Material* material = (Material*) nativeMaterial;
+    return (jint) material->getFeatureLevel();
+}
+
 extern "C"
 JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Material_nGetVertexDomain(JNIEnv*, jclass,
@@ -255,3 +272,17 @@ Java_com_google_android_filament_Material_nHasParameter(JNIEnv* env, jclass,
     env->ReleaseStringUTFChars(name_, name);
     return (jboolean) hasParameter;
 }
+
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_Material_nCompile(JNIEnv *env, jclass clazz,
+        jlong nativeMaterial, jint priority, jint variants, jobject handler, jobject runnable) {
+    Material* material = (Material*) nativeMaterial;
+    JniCallback* jniCallback = JniCallback::make(env, handler, runnable);
+    material->compile(
+            (Material::CompilerPriorityQueue) priority,
+            (UserVariantFilterBit) variants,
+            jniCallback->getHandler(), [jniCallback](Material*){
+                JniCallback::postToJavaAndDestroy(jniCallback);
+            });
+}

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

@@ -205,7 +205,7 @@ Java_com_google_android_filament_MaterialInstance_nSetIntParameterArray(JNIEnv *
             break;
     }
 
-    env->ReleaseIntArrayElements(v_, v, 0);
+    env->ReleaseIntArrayElements(v_, v, JNI_ABORT);
 
     env->ReleaseStringUTFChars(name_, name);
 }
@@ -246,17 +246,21 @@ Java_com_google_android_filament_MaterialInstance_nSetFloatParameterArray(JNIEnv
     env->ReleaseStringUTFChars(name_, name);
 }
 
+// defined in TextureSampler.cpp
+namespace filament::JniUtils {
+    TextureSampler from_long(jlong params) noexcept;
+} // TextureSamplerJniUtils
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_MaterialInstance_nSetParameterTexture(
         JNIEnv *env, jclass, jlong nativeMaterialInstance, jstring name_,
-        jlong nativeTexture, jint sampler_) {
+        jlong nativeTexture, jlong sampler_) {
     MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
     Texture* texture = (Texture*) nativeTexture;
-    TextureSampler& sampler = reinterpret_cast<TextureSampler&>(sampler_);
 
     const char *name = env->GetStringUTFChars(name_, 0);
-    instance->setParameter(name, texture, sampler);
+    instance->setParameter(name, texture, JniUtils::from_long(sampler_));
     env->ReleaseStringUTFChars(name_, name);
 }
 
@@ -357,6 +361,14 @@ Java_com_google_android_filament_MaterialInstance_nSetDepthCulling(JNIEnv*,
     instance->setDepthCulling(enable);
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_MaterialInstance_nSetDepthFunc(JNIEnv*,
+        jclass, jlong nativeMaterialInstance, jlong function) {
+    MaterialInstance* instance = (MaterialInstance*) nativeMaterialInstance;
+    instance->setDepthFunc(static_cast<MaterialInstance::DepthFunc>(function));
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_MaterialInstance_nSetStencilCompareFunction(JNIEnv*, jclass,
@@ -524,3 +536,11 @@ Java_com_google_android_filament_MaterialInstance_nIsDepthCullingEnabled(JNIEnv*
     MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
     return instance->isDepthCullingEnabled();
 }
+
+extern "C"
+JNIEXPORT jint JNICALL
+Java_com_google_android_filament_MaterialInstance_nGetDepthFunc(JNIEnv* env, jclass clazz,
+        jlong nativeMaterialInstance) {
+    MaterialInstance* instance = (MaterialInstance*)nativeMaterialInstance;
+    return (jint)instance->getDepthFunc();
+}

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

@@ -71,6 +71,13 @@ Java_com_google_android_filament_Scene_nRemoveEntities(JNIEnv *env, jclass type,
     env->ReleaseIntArrayElements(entities, (jint*) nativeEntities, JNI_ABORT);
 }
 
+extern "C" JNIEXPORT jint JNICALL
+Java_com_google_android_filament_Scene_nGetEntityCount(JNIEnv *env, jclass type,
+        jlong nativeScene) {
+    Scene* scene = (Scene*) nativeScene;
+    return (jint) scene->getEntityCount();
+}
+
 extern "C" JNIEXPORT jint JNICALL
 Java_com_google_android_filament_Scene_nGetRenderableCount(JNIEnv *env, jclass type,
         jlong nativeScene) {
@@ -91,3 +98,22 @@ Java_com_google_android_filament_Scene_nHasEntity(JNIEnv *env, jclass type, jlon
     Entity entity = Entity::import(entityId);
     return (jboolean) scene->hasEntity(entity);
 }
+
+extern "C"
+JNIEXPORT jboolean JNICALL
+Java_com_google_android_filament_Scene_nGetEntities(JNIEnv *env, jclass ,
+        jlong nativeScene, jintArray outArray, jint length) {
+    Scene const* const scene = (Scene*) nativeScene;
+    if (length < scene->getEntityCount()) {
+        // should not happen because we already checked on the java side
+        return JNI_FALSE;
+    }
+    jint *out = (jint *) env->GetIntArrayElements(outArray, nullptr);
+    scene->forEach([out, length, i = 0](Entity entity)mutable {
+        if (i < length) { // this is just paranoia here
+            out[i++] = (jint) entity.getId();
+        }
+    });
+    env->ReleaseIntArrayElements(outArray, (jint*) out, 0);
+    return JNI_TRUE;
+}

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

@@ -27,11 +27,10 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_SwapChain_nSetFrameCompletedCallback(JNIEnv* env, jclass,
         jlong nativeSwapChain, jobject handler, jobject runnable) {
     SwapChain* swapChain = (SwapChain*) nativeSwapChain;
-    auto *callback = JniCallback::make(env, handler, runnable);
-    swapChain->setFrameCompletedCallback([](void* user) {
-        JniCallback* callback = (JniCallback*)user;
+    auto* callback = JniCallback::make(env, handler, runnable);
+    swapChain->setFrameCompletedCallback(nullptr, [callback](SwapChain* swapChain) {
         JniCallback::postToJavaAndDestroy(callback);
-    }, callback);
+    });
 }
 
 extern "C" JNIEXPORT jboolean JNICALL

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

@@ -511,9 +511,7 @@ public:
 
 private:
     void* mData = nullptr;
-    jobject mBitmap = nullptr;
-    jobject mHandler = nullptr;
-    jobject mCallback = nullptr;
+    jobject mBitmap{};
     AndroidBitmapInfo mInfo{};
 };
 

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

@@ -18,142 +18,139 @@
 
 #include <filament/TextureSampler.h>
 
+#include <utils/algorithm.h>
+
 using namespace filament;
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nCreateSampler(JNIEnv *env, jclass type, jint min,
+namespace filament::JniUtils {
+
+jlong to_long(TextureSampler const& sampler) noexcept {
+    return jlong(utils::bit_cast<uint32_t>(sampler.getSamplerParams()));
+}
+
+TextureSampler from_long(jlong params) noexcept {
+    return TextureSampler{
+            utils::bit_cast<backend::SamplerParams>(
+                    static_cast<uint32_t>(params))};
+}
+
+} // namespace filament::JniUtils
+
+using namespace JniUtils;
+
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nCreateSampler(JNIEnv *, jclass, jint min,
         jint max, jint s, jint t, jint r) {
-    return TextureSampler(static_cast<TextureSampler::MinFilter>(min),
-            static_cast<TextureSampler::MagFilter>(max), static_cast<TextureSampler::WrapMode>(s),
-            static_cast<TextureSampler::WrapMode>(t),
-            static_cast<TextureSampler::WrapMode>(r)).getSamplerParams().u;
+    TextureSampler sampler(static_cast<TextureSampler::MinFilter>(min),
+                           static_cast<TextureSampler::MagFilter>(max),
+                           static_cast<TextureSampler::WrapMode>(s),
+                           static_cast<TextureSampler::WrapMode>(t),
+                           static_cast<TextureSampler::WrapMode>(r));
+    return to_long(sampler);
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nCreateCompareSampler(JNIEnv *env, jclass type,
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nCreateCompareSampler(JNIEnv *, jclass,
         jint mode, jint function) {
-    return TextureSampler(static_cast<TextureSampler::CompareMode>(mode),
-            static_cast<TextureSampler::CompareFunc>(function)).getSamplerParams().u;
+    TextureSampler sampler(static_cast<TextureSampler::CompareMode>(mode),
+                           static_cast<TextureSampler::CompareFunc>(function));
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetMinFilter(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getMinFilter());
+Java_com_google_android_filament_TextureSampler_nGetMinFilter(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getMinFilter());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetMinFilter(JNIEnv *env, jclass type,
-        jint sampler_, jint filter) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetMinFilter(JNIEnv *, jclass, jlong sampler_, jint filter) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setMinFilter(static_cast<TextureSampler::MinFilter>(filter));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetMagFilter(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getMagFilter());
+Java_com_google_android_filament_TextureSampler_nGetMagFilter(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getMagFilter());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetMagFilter(JNIEnv *env, jclass type,
-        jint sampler_, jint filter) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetMagFilter(JNIEnv *, jclass, jlong sampler_, jint filter) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setMagFilter(static_cast<TextureSampler::MagFilter>(filter));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetWrapModeS(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getWrapModeS());
+Java_com_google_android_filament_TextureSampler_nGetWrapModeS(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getWrapModeS());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetWrapModeS(JNIEnv *env, jclass type,
-        jint sampler_, jint mode) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetWrapModeS(JNIEnv *, jclass, jlong sampler_, jint mode) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setWrapModeS(static_cast<TextureSampler::WrapMode>(mode));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetWrapModeT(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getWrapModeT());
+Java_com_google_android_filament_TextureSampler_nGetWrapModeT(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getWrapModeT());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetWrapModeT(JNIEnv *env, jclass type,
-        jint sampler_, jint mode) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetWrapModeT(JNIEnv *, jclass, jlong sampler_, jint mode) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setWrapModeT(static_cast<TextureSampler::WrapMode>(mode));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetWrapModeR(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getWrapModeR());
+Java_com_google_android_filament_TextureSampler_nGetWrapModeR(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getWrapModeR());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetWrapModeR(JNIEnv *env, jclass type,
-        jint sampler_, jint mode) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetWrapModeR(JNIEnv *, jclass, jlong sampler_, jint mode) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setWrapModeR(static_cast<TextureSampler::WrapMode>(mode));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetCompareMode(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getCompareMode());
+Java_com_google_android_filament_TextureSampler_nGetCompareMode(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getCompareMode());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetCompareMode(JNIEnv *env, jclass type,
-        jint sampler_, jint mode) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetCompareMode(JNIEnv *, jclass, jlong sampler_, jint mode) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setCompareMode(static_cast<TextureSampler::CompareMode>(mode),
             sampler.getCompareFunc());
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nGetCompareFunction(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return static_cast<jint>(sampler.getCompareFunc());
+Java_com_google_android_filament_TextureSampler_nGetCompareFunction(JNIEnv *, jclass, jlong sampler) {
+    return static_cast<jint>(from_long(sampler).getCompareFunc());
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetCompareFunction(JNIEnv *env, jclass type,
-        jint sampler_, jint function) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetCompareFunction(JNIEnv *, jclass, jlong sampler_, jint function) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setCompareMode(sampler.getCompareMode(),
             static_cast<TextureSampler::CompareFunc>(function));
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }
 
 extern "C" JNIEXPORT jfloat JNICALL
-Java_com_google_android_filament_TextureSampler_nGetAnisotropy(JNIEnv *env, jclass type,
-        jint sampler_) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
-    return sampler.getAnisotropy();
+Java_com_google_android_filament_TextureSampler_nGetAnisotropy(JNIEnv *, jclass, jlong sampler) {
+    return from_long(sampler).getAnisotropy();
 }
 
-extern "C" JNIEXPORT jint JNICALL
-Java_com_google_android_filament_TextureSampler_nSetAnisotropy(JNIEnv *env, jclass type,
-        jint sampler_, jfloat anisotropy) {
-    TextureSampler &sampler = reinterpret_cast<TextureSampler &>(sampler_);
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_TextureSampler_nSetAnisotropy(JNIEnv *, jclass, jlong sampler_, jfloat anisotropy) {
+    TextureSampler sampler{from_long(sampler_)};
     sampler.setAnisotropy(anisotropy);
-    return sampler.getSamplerParams().u;
+    return to_long(sampler);
 }

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

@@ -47,6 +47,11 @@ Java_com_google_android_filament_ToneMapper_nCreateFilmicToneMapper(JNIEnv*, jcl
     return (jlong) new FilmicToneMapper();
 }
 
+extern "C" JNIEXPORT jlong JNICALL
+Java_com_google_android_filament_ToneMapper_nCreateAgxToneMapper(JNIEnv*, jclass, jint look) {
+    return (jlong) new AgxToneMapper(AgxToneMapper::AgxLook(look));
+}
+
 extern "C" JNIEXPORT jlong JNICALL
 Java_com_google_android_filament_ToneMapper_nCreateGenericToneMapper(JNIEnv*, jclass,
         jfloat contrast, jfloat midGrayIn, jfloat midGrayOut, jfloat hdrMax) {

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

@@ -282,7 +282,7 @@ Java_com_google_android_filament_View_nSetSSCTOptions(JNIEnv *, jclass, jlong na
 extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetBloomOptions(JNIEnv*, jclass,
         jlong nativeView, jlong nativeTexture,
-        jfloat dirtStrength, jfloat strength, jint resolution, jfloat anamorphism, jint levels,
+        jfloat dirtStrength, jfloat strength, jint resolution, jint levels,
         jint blendMode, jboolean threshold, jboolean enabled, jfloat highlight,
         jboolean lensFlare, jboolean starburst, jfloat chromaticAberration, jint ghostCount,
         jfloat ghostSpacing, jfloat ghostThreshold, jfloat haloThickness, jfloat haloRadius,
@@ -294,7 +294,6 @@ Java_com_google_android_filament_View_nSetBloomOptions(JNIEnv*, jclass,
             .dirtStrength = dirtStrength,
             .strength = strength,
             .resolution = (uint32_t)resolution,
-            .anamorphism = anamorphism,
             .levels = (uint8_t)levels,
             .blendMode = (View::BloomOptions::BlendMode)blendMode,
             .threshold = (bool)threshold,
@@ -317,8 +316,9 @@ extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetFogOptions(JNIEnv *, jclass , jlong nativeView,
         jfloat distance, jfloat maximumOpacity, jfloat height, jfloat heightFalloff, jfloat cutOffDistance,
         jfloat r, jfloat g, jfloat b, jfloat density, jfloat inScatteringStart,
-        jfloat inScatteringSize, jboolean fogColorFromIbl, jboolean enabled) {
+        jfloat inScatteringSize, jboolean fogColorFromIbl, jlong skyColorNativeObject, jboolean enabled) {
     View* view = (View*) nativeView;
+    Texture* skyColor = (Texture*) skyColorNativeObject;
     View::FogOptions options = {
              .distance = distance,
              .cutOffDistance = cutOffDistance,
@@ -330,6 +330,7 @@ Java_com_google_android_filament_View_nSetFogOptions(JNIEnv *, jclass , jlong na
              .inScatteringStart = inScatteringStart,
              .inScatteringSize = inScatteringSize,
              .fogColorFromIbl = (bool)fogColorFromIbl,
+             .skyColor = skyColor,
              .enabled = (bool)enabled
     };
     view->setFogOptions(options);
@@ -479,6 +480,17 @@ Java_com_google_android_filament_View_nIsStencilBufferEnabled(JNIEnv *, jclass,
     return view->isStencilBufferEnabled();
 }
 
+extern "C"
+JNIEXPORT void JNICALL
+Java_com_google_android_filament_View_nSetStereoscopicOptions(JNIEnv *, jclass, jlong nativeView,
+        jboolean enabled) {
+    View* view = (View*) nativeView;
+    View::StereoscopicOptions options {
+        .enabled = (bool) enabled
+    };
+    view->setStereoscopicOptions(options);
+}
+
 extern "C"
 JNIEXPORT void JNICALL
 Java_com_google_android_filament_View_nSetGuardBandOptions(JNIEnv *, jclass,

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

@@ -111,6 +111,8 @@ public class Engine {
 
     private long mNativeObject;
 
+    private Config mConfig;
+
     @NonNull private final TransformManager mTransformManager;
     @NonNull private final LightManager mLightManager;
     @NonNull private final RenderableManager mRenderableManager;
@@ -150,16 +152,219 @@ public class Engine {
         FEATURE_LEVEL_0,
         /** OpenGL ES 3.0 features (default) */
         FEATURE_LEVEL_1,
+        /** OpenGL ES 3.1 features + 16 textures units + cubemap arrays */
+        FEATURE_LEVEL_2,
         /** OpenGL ES 3.1 features + 31 textures units + cubemap arrays */
-        FEATURE_LEVEL_2
+        FEATURE_LEVEL_3,
     };
 
-    private Engine(long nativeEngine) {
+    /**
+     * Constructs <code>Engine</code> objects using a builder pattern.
+     */
+    public static class Builder {
+        @SuppressWarnings({"FieldCanBeLocal", "UnusedDeclaration"})
+        private final BuilderFinalizer mFinalizer;
+        private final long mNativeBuilder;
+        private Config mConfig;
+
+        public Builder() {
+            mNativeBuilder = nCreateBuilder();
+            mFinalizer = new BuilderFinalizer(mNativeBuilder);
+        }
+
+        /**
+         * Sets the {@link Backend} for the Engine.
+         *
+         * @param backend Driver backend to use
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder backend(Backend backend) {
+            nSetBuilderBackend(mNativeBuilder, backend.ordinal());
+            return this;
+        }
+
+        /**
+         * Sets a sharedContext for the Engine.
+         *
+         * @param sharedContext  A platform-dependant OpenGL context used as a shared context
+         *                       when creating filament's internal context. On Android this parameter
+         *                       <b>must be</b> an instance of {@link android.opengl.EGLContext}.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder sharedContext(Object sharedContext) {
+            if (Platform.get().validateSharedContext(sharedContext)) {
+                nSetBuilderSharedContext(mNativeBuilder,
+                        Platform.get().getSharedContextNativeHandle(sharedContext));
+                return this;
+            }
+            throw new IllegalArgumentException("Invalid shared context " + sharedContext);
+        }
+
+        /**
+         * Configure the Engine with custom parameters.
+         *
+         * @param config A {@link Config} object
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder config(Config config) {
+            mConfig = config;
+            nSetBuilderConfig(mNativeBuilder, config.commandBufferSizeMB,
+                    config.perRenderPassArenaSizeMB, config.driverHandleArenaSizeMB,
+                    config.minCommandBufferSizeMB, config.perFrameCommandsSizeMB,
+                    config.jobSystemThreadCount, config.stereoscopicEyeCount);
+            return this;
+        }
+
+        /**
+         * Sets the initial featureLevel for the Engine.
+         *
+         * @param featureLevel The feature level at which initialize Filament.
+         * @return A reference to this Builder for chaining calls.
+         */
+        public Builder featureLevel(FeatureLevel featureLevel) {
+            nSetBuilderFeatureLevel(mNativeBuilder, featureLevel.ordinal());
+            return this;
+        }
+
+        /**
+         * Creates an instance of Engine
+         *
+         * @return A newly created <code>Engine</code>, or <code>null</code> if the GPU driver couldn't
+         *         be initialized, for instance if it doesn't support the right version of OpenGL or
+         *         OpenGL ES.
+         *
+         * @exception IllegalStateException can be thrown if there isn't enough memory to
+         * allocate the command buffer.
+         */
+        public Engine build() {
+            long nativeEngine = nBuilderBuild(mNativeBuilder);
+            if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
+            return new Engine(nativeEngine, mConfig);
+        }
+
+        private static class BuilderFinalizer {
+            private final long mNativeObject;
+
+            BuilderFinalizer(long nativeObject) {
+                mNativeObject = nativeObject;
+            }
+
+            @Override
+            public void finalize() {
+                try {
+                    super.finalize();
+                } catch (Throwable t) { // Ignore
+                } finally {
+                    nDestroyBuilder(mNativeObject);
+                }
+            }
+        }
+    }
+
+    /**
+     * Parameters for customizing the initialization of {@link Engine}.
+     */
+    public static class Config {
+
+        // #defines in Engine.h
+        private static final long FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB = 3;
+        private static final long FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB = 2;
+        private static final long FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB = 1;
+        private static final long FILAMENT_COMMAND_BUFFER_SIZE_IN_MB =
+                FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB * 3;
+
+        /**
+         * Size in MiB of the low-level command buffer arena.
+         *
+         * Each new command buffer is allocated from here. If this buffer is too small the program
+         * might terminate or rendering errors might occur.
+         *
+         * This is typically set to minCommandBufferSizeMB * 3, so that up to 3 frames can be
+         * batched-up at once.
+         *
+         * This value affects the application's memory usage.
+         */
+        public long commandBufferSizeMB = FILAMENT_COMMAND_BUFFER_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the per-frame data arena.
+         *
+         * This is the main arena used for allocations when preparing a frame.
+         * e.g.: Froxel data and high-level commands are allocated from this arena.
+         *
+         * If this size is too small, the program will abort on debug builds and have undefined
+         * behavior otherwise.
+         *
+         * This value affects the application's memory usage.
+         */
+        public long perRenderPassArenaSizeMB = FILAMENT_PER_RENDER_PASS_ARENA_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the backend's handle arena.
+         *
+         * Backends will fallback to slower heap-based allocations when running out of space and
+         * log this condition.
+         *
+         * If 0, then the default value for the given platform is used
+         *
+         * This value affects the application's memory usage.
+         */
+        public long driverHandleArenaSizeMB = 0;
+
+        /**
+         * Minimum size in MiB of a low-level command buffer.
+         *
+         * This is how much space is guaranteed to be available for low-level commands when a new
+         * buffer is allocated. If this is too small, the engine might have to stall to wait for
+         * more space to become available, this situation is logged.
+         *
+         * This value does not affect the application's memory usage.
+         */
+        public long minCommandBufferSizeMB = FILAMENT_MIN_COMMAND_BUFFERS_SIZE_IN_MB;
+
+        /**
+         * Size in MiB of the per-frame high level command buffer.
+         *
+         * This buffer is related to the number of draw calls achievable within a frame, if it is
+         * too small, the program will abort on debug builds and have undefined behavior otherwise.
+         *
+         * It is allocated from the 'per-render-pass arena' above. Make sure that at least 1 MiB is
+         * left in the per-render-pass arena when deciding the size of this buffer.
+         *
+         * This value does not affect the application's memory usage.
+         */
+        public long perFrameCommandsSizeMB = FILAMENT_PER_FRAME_COMMANDS_SIZE_IN_MB;
+
+        /**
+         * Number of threads to use in Engine's JobSystem.
+         *
+         * Engine uses a utils::JobSystem to carry out paralleization of Engine workloads. This
+         * value sets the number of threads allocated for JobSystem. Configuring this value can be
+         * helpful in CPU-constrained environments where too many threads can cause contention of
+         * CPU and reduce performance.
+         *
+         * The default value is 0, which implies that the Engine will use a heuristic to determine
+         * the number of threads to use.
+         */
+        public long jobSystemThreadCount = 0;
+
+        /**
+         * The number of eyes to render when stereoscopic rendering is enabled. Supported values are
+         * between 1 and Engine#getMaxStereoscopicEyes() (inclusive).
+         *
+         * @see View#setStereoscopicOptions
+         * @see Engine#getMaxStereoscopicEyes
+         */
+        public long stereoscopicEyeCount = 2;
+    }
+
+    private Engine(long nativeEngine, Config config) {
         mNativeObject = nativeEngine;
         mTransformManager = new TransformManager(nGetTransformManager(nativeEngine));
         mLightManager = new LightManager(nGetLightManager(nativeEngine));
         mRenderableManager = new RenderableManager(nGetRenderableManager(nativeEngine));
         mEntityManager = new EntityManager(nGetEntityManager(nativeEngine));
+        mConfig = config;
     }
 
     /**
@@ -177,9 +382,7 @@ public class Engine {
      */
     @NonNull
     public static Engine create() {
-        long nativeEngine = nCreateEngine(0, 0);
-        if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-        return new Engine(nativeEngine);
+        return new Builder().build();
     }
 
     /**
@@ -199,9 +402,9 @@ public class Engine {
      */
     @NonNull
     public static Engine create(@NonNull Backend backend) {
-        long nativeEngine = nCreateEngine(backend.ordinal(), 0);
-        if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-        return new Engine(nativeEngine);
+        return new Builder()
+            .backend(backend)
+            .build();
     }
 
     /**
@@ -223,13 +426,9 @@ public class Engine {
      */
     @NonNull
     public static Engine create(@NonNull Object sharedContext) {
-        if (Platform.get().validateSharedContext(sharedContext)) {
-            long nativeEngine = nCreateEngine(0,
-                    Platform.get().getSharedContextNativeHandle(sharedContext));
-            if (nativeEngine == 0) throw new IllegalStateException("Couldn't create Engine");
-            return new Engine(nativeEngine);
-        }
-        throw new IllegalArgumentException("Invalid shared context " + sharedContext);
+        return new Builder()
+            .sharedContext(sharedContext)
+            .build();
     }
 
     /**
@@ -296,17 +495,23 @@ public class Engine {
     }
 
     /**
-     * Activate all features of a given feature level. By default FeatureLevel::FEATURE_LEVEL_1 is
-     * active. The selected feature level must not be higher than the value returned by
-     * getActiveFeatureLevel() and it's not possible lower the active feature level.
+     * Activate all features of a given feature level. If an explicit feature level is not specified
+     * at Engine initialization time via {@link Builder#featureLevel}, the default feature level is
+     * {@link FeatureLevel#FEATURE_LEVEL_0} on devices not compatible with GLES 3.0; otherwise, the
+     * default is {@link FeatureLevel::FEATURE_LEVEL_1}. The selected feature level must not be
+     * higher than the value returned by {@link #getActiveFeatureLevel} and it's not possible lower
+     * the active feature level. Additionally, it is not possible to modify the feature level at all
+     * if the Engine was initialized at {@link FeatureLevel#FEATURE_LEVEL_0}.
      *
-     * @param featureLevel the feature level to activate. If featureLevel is lower than
-     *                     getActiveFeatureLevel(), the current (higher) feature level is kept.
-     *                     If featureLevel is higher than getSupportedFeatureLevel(), an exception
-     *                     is thrown, or the program is terminated if exceptions are disabled.
+     * @param featureLevel the feature level to activate. If featureLevel is lower than {@link
+     *                     #getActiveFeatureLevel}, the current (higher) feature level is kept. If
+     *                     featureLevel is higher than {@link #getSupportedFeatureLevel}, or if the
+     *                     engine was initialized at feature level 0, an exception is thrown, or the
+     *                     program is terminated if exceptions are disabled.
      *
      * @return the active feature level.
      *
+     * @see Builder#featureLevel
      * @see #getSupportedFeatureLevel
      * @see #getActiveFeatureLevel
      */
@@ -352,6 +557,37 @@ public class Engine {
         return nIsAutomaticInstancingEnabled(getNativeObject());
     }
 
+    /**
+     * Retrieves the configuration settings of this {@link Engine}.
+     *
+     * This method returns the configuration object that was supplied to the Engine's {@link
+     * Builder#config} method during the creation of this Engine. If the {@link Builder::config}
+     * method was not explicitly called (or called with null), this method returns the default
+     * configuration settings.
+     *
+     * @return a {@link Config} object with this Engine's configuration
+     * @see Builder#config
+     */
+    @NonNull
+    public Config getConfig() {
+        if (mConfig == null) {
+            mConfig = new Config();
+        }
+        return mConfig;
+    }
+
+    /**
+     * 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
+     * Engine#Config#stereoscopicEyeCount} setting.
+     *
+     * @return the max number of stereoscopic eyes supported
+     * @see Engine#Config#stereoscopicEyeCount
+     */
+    public long getMaxStereoscopicEyes() {
+        return nGetMaxStereoscopicEyes(getNativeObject());
+    }
+
 
     // SwapChain
 
@@ -449,6 +685,141 @@ public class Engine {
         swapChain.clearNativeObject();
     }
 
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidRenderer(@NonNull Renderer object) {
+        return nIsValidRenderer(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidView(@NonNull View object) {
+        return nIsValidView(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidScene(@NonNull Scene object) {
+        return nIsValidScene(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidFence(@NonNull Fence object) {
+        return nIsValidFence(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidStream(@NonNull Stream object) {
+        return nIsValidStream(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidIndexBuffer(@NonNull IndexBuffer object) {
+        return nIsValidIndexBuffer(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidVertexBuffer(@NonNull VertexBuffer object) {
+        return nIsValidVertexBuffer(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidSkinningBuffer(@NonNull SkinningBuffer object) {
+        return nIsValidSkinningBuffer(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidIndirectLight(@NonNull IndirectLight object) {
+        return nIsValidIndirectLight(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidMaterial(@NonNull Material object) {
+        return nIsValidMaterial(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidSkybox(@NonNull Skybox object) {
+        return nIsValidSkybox(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidColorGrading(@NonNull ColorGrading object) {
+        return nIsValidColorGrading(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidTexture(@NonNull Texture object) {
+        return nIsValidTexture(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidRenderTarget(@NonNull RenderTarget object) {
+        return nIsValidRenderTarget(getNativeObject(), object.getNativeObject());
+    }
+
+    /**
+     * Returns whether the object is valid.
+     * @param object Object to check for validity
+     * @return returns true if the specified object is valid.
+     */
+    public boolean isValidSwapChain(@NonNull SwapChain object) {
+        return nIsValidSwapChain(getNativeObject(), object.getNativeObject());
+    }
+
     // View
 
     /**
@@ -753,6 +1124,18 @@ public class Engine {
         nFlushAndWait(getNativeObject());
     }
 
+    /**
+     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) but does not wait
+     * for commands to be either executed or the hardware finished.
+     *
+     * <p>This is typically used after creating a lot of objects to start draining the command
+     * queue which has a limited size.</p>
+     */
+    public void flush() {
+        nFlush(getNativeObject());
+    }
+
+
     @UsedByReflection("TextureHelper.java")
     public long getNativeObject() {
         if (mNativeObject == 0) {
@@ -779,23 +1162,22 @@ public class Engine {
         }
     }
 
-    private static native long nCreateEngine(long backend, long sharedContext);
     private static native void nDestroyEngine(long nativeEngine);
     private static native long nGetBackend(long nativeEngine);
     private static native long nCreateSwapChain(long nativeEngine, Object nativeWindow, long flags);
     private static native long nCreateSwapChainHeadless(long nativeEngine, int width, int height, long flags);
     private static native long nCreateSwapChainFromRawPointer(long nativeEngine, long pointer, long flags);
-    private static native boolean nDestroySwapChain(long nativeEngine, long nativeSwapChain);
     private static native long nCreateView(long nativeEngine);
-    private static native boolean nDestroyView(long nativeEngine, long nativeView);
     private static native long nCreateRenderer(long nativeEngine);
-    private static native boolean nDestroyRenderer(long nativeEngine, long nativeRenderer);
     private static native long nCreateCamera(long nativeEngine, int entity);
     private static native long nGetCameraComponent(long nativeEngine, int entity);
     private static native void nDestroyCameraComponent(long nativeEngine, int entity);
     private static native long nCreateScene(long nativeEngine);
-    private static native boolean nDestroyScene(long nativeEngine, long nativeScene);
     private static native long nCreateFence(long nativeEngine);
+
+    private static native boolean nDestroyRenderer(long nativeEngine, long nativeRenderer);
+    private static native boolean nDestroyView(long nativeEngine, long nativeView);
+    private static native boolean nDestroyScene(long nativeEngine, long nativeScene);
     private static native boolean nDestroyFence(long nativeEngine, long nativeFence);
     private static native boolean nDestroyStream(long nativeEngine, long nativeStream);
     private static native boolean nDestroyIndexBuffer(long nativeEngine, long nativeIndexBuffer);
@@ -808,8 +1190,25 @@ public class Engine {
     private static native boolean nDestroyColorGrading(long nativeEngine, long nativeColorGrading);
     private static native boolean nDestroyTexture(long nativeEngine, long nativeTexture);
     private static native boolean nDestroyRenderTarget(long nativeEngine, long nativeTarget);
+    private static native boolean nDestroySwapChain(long nativeEngine, long nativeSwapChain);
+    private static native boolean nIsValidRenderer(long nativeEngine, long nativeRenderer);
+    private static native boolean nIsValidView(long nativeEngine, long nativeView);
+    private static native boolean nIsValidScene(long nativeEngine, long nativeScene);
+    private static native boolean nIsValidFence(long nativeEngine, long nativeFence);
+    private static native boolean nIsValidStream(long nativeEngine, long nativeStream);
+    private static native boolean nIsValidIndexBuffer(long nativeEngine, long nativeIndexBuffer);
+    private static native boolean nIsValidVertexBuffer(long nativeEngine, long nativeVertexBuffer);
+    private static native boolean nIsValidSkinningBuffer(long nativeEngine, long nativeSkinningBuffer);
+    private static native boolean nIsValidIndirectLight(long nativeEngine, long nativeIndirectLight);
+    private static native boolean nIsValidMaterial(long nativeEngine, long nativeMaterial);
+    private static native boolean nIsValidSkybox(long nativeEngine, long nativeSkybox);
+    private static native boolean nIsValidColorGrading(long nativeEngine, long nativeColorGrading);
+    private static native boolean nIsValidTexture(long nativeEngine, long nativeTexture);
+    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 void nFlush(long nativeEngine);
     private static native long nGetTransformManager(long nativeEngine);
     private static native long nGetLightManager(long nativeEngine);
     private static native long nGetRenderableManager(long nativeEngine);
@@ -817,7 +1216,19 @@ public class Engine {
     private static native long nGetEntityManager(long nativeEngine);
     private static native void nSetAutomaticInstancingEnabled(long nativeEngine, boolean enable);
     private static native boolean nIsAutomaticInstancingEnabled(long nativeEngine);
+    private static native long nGetMaxStereoscopicEyes(long nativeEngine);
     private static native int nGetSupportedFeatureLevel(long nativeEngine);
     private static native int nSetActiveFeatureLevel(long nativeEngine, int ordinal);
     private static native int nGetActiveFeatureLevel(long nativeEngine);
+
+    private static native long nCreateBuilder();
+    private static native void nDestroyBuilder(long nativeBuilder);
+    private static native void nSetBuilderBackend(long nativeBuilder, long backend);
+    private static native void nSetBuilderConfig(long nativeBuilder, long commandBufferSizeMB,
+            long perRenderPassArenaSizeMB, long driverHandleArenaSizeMB,
+            long minCommandBufferSizeMB, long perFrameCommandsSizeMB, long jobSystemThreadCount,
+            long stereoscopicEyeCount);
+    private static native void nSetBuilderFeatureLevel(long nativeBuilder, int ordinal);
+    private static native void nSetBuilderSharedContext(long nativeBuilder, long sharedContext);
+    private static native long nBuilderBuild(long nativeBuilder);
 }

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

@@ -258,6 +258,7 @@ public class LightManager {
          * shadows that are too far and wouldn't contribute to the scene much, improving
          * performance and quality. This value is always positive.
          * Use 0.0f to use the camera far distance.
+         * This only affect directional lights.
          */
         public float shadowFar = 0.0f;
 
@@ -368,6 +369,17 @@ public class LightManager {
          * enabled. (2cm by default).
          */
         public float shadowBulbRadius = 0.02f;
+
+        /**
+         * Transforms the shadow direction. Must be a unit quaternion.
+         * The default is identity.
+         * Ignored if the light type isn't directional. For artistic use. Use with caution.
+         * The quaternion is stored as the imaginary part in the first 3 elements and the real
+         * part in the last element of the transform array.
+         */
+        @NonNull
+        @Size(min = 4, max = 4)
+        public float[] transform = { 0.0f, 0.0f, 0.0f, 1.0f };
     }
 
     public static class ShadowCascades {
@@ -506,7 +518,7 @@ public class LightManager {
                     options.polygonOffsetConstant, options.polygonOffsetSlope,
                     options.screenSpaceContactShadows,
                     options.stepCount, options.maxShadowDistance,
-                    options.elvsm, options.blurWidth, options.shadowBulbRadius);
+                    options.elvsm, options.blurWidth, options.shadowBulbRadius, options.transform);
             return this;
         }
 
@@ -1169,7 +1181,7 @@ public class LightManager {
              boolean stable, boolean lispsm,
              float polygonOffsetConstant, float polygonOffsetSlope,
              boolean screenSpaceContactShadows, int stepCount, float maxShadowDistance,
-             boolean elvsm, float blurWidth, float shadowBulbRadius);
+             boolean elvsm, float blurWidth, float shadowBulbRadius, float[] transform);
     private static native void nBuilderCastLight(long nativeBuilder, boolean enabled);
     private static native void nBuilderPosition(long nativeBuilder, float x, float y, float z);
     private static native void nBuilderDirection(long nativeBuilder, float x, float y, float z);

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

@@ -18,9 +18,11 @@ package com.google.android.filament;
 
 import androidx.annotation.IntRange;
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 import androidx.annotation.Size;
 
 import com.google.android.filament.proguard.UsedByNative;
+import com.google.android.filament.Engine.FeatureLevel;
 
 import java.nio.Buffer;
 import java.util.ArrayList;
@@ -46,6 +48,8 @@ public class Material {
         static final BlendingMode[] sBlendingModeValues = BlendingMode.values();
         static final RefractionMode[] sRefractionModeValues = RefractionMode.values();
         static final RefractionType[] sRefractionTypeValues = RefractionType.values();
+        static final ReflectionMode[] sReflectionModeValues = ReflectionMode.values();
+        static final FeatureLevel[] sFeatureLevelValues = FeatureLevel.values();
         static final VertexDomain[] sVertexDomainValues = VertexDomain.values();
         static final CullingMode[] sCullingModeValues = CullingMode.values();
         static final VertexBuffer.VertexAttribute[] sVertexAttributeValues =
@@ -181,6 +185,18 @@ public class Material {
         THIN
     }
 
+    /**
+     * Supported reflection modes
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/lighting:reflections">
+     * Lighting: reflections</a>
+     */
+    public enum ReflectionMode {
+        DEFAULT,
+        SCREEN_SPACE
+    }
+
     /**
      * Supported types of vertex domains
      *
@@ -223,6 +239,31 @@ public class Material {
         FRONT_AND_BACK
     }
 
+    public enum CompilerPriorityQueue {
+        HIGH,
+        LOW
+    }
+
+    public static class UserVariantFilterBit {
+        /** Directional lighting */
+        public static int DIRECTIONAL_LIGHTING = 0x01;
+        /** Dynamic lighting */
+        public static int DYNAMIC_LIGHTING = 0x02;
+        /** Shadow receiver */
+        public static int SHADOW_RECEIVER = 0x04;
+        /** Skinning */
+        public static int SKINNING = 0x08;
+        /** Fog */
+        public static int FOG = 0x10;
+        /** Variance shadow maps */
+        public static int VSM = 0x20;
+        /** Screen-space reflections */
+        public static int SSR = 0x40;
+        /** Instanced stereo rendering */
+        public static int STE = 0x80;
+        public static int ALL = 0xFF;
+    }
+
     @UsedByNative("Material.cpp")
     public static class Parameter {
         private static final Type[] sTypeValues = Type.values();
@@ -337,6 +378,55 @@ public class Material {
         }
     }
 
+
+    /**
+     * Asynchronously ensures that a subset of this Material's variants are compiled. After issuing
+     * several compile() calls in a row, it is recommended to call {@link Engine#flush}
+     * such that the backend can start the compilation work as soon as possible.
+     * The provided callback is guaranteed to be called on the main thread after all specified
+     * variants of the material are compiled. This can take hundreds of milliseconds.
+     *<p>
+     * If all the material's variants are already compiled, the callback will be scheduled as
+     * soon as possible, but this might take a few dozen millisecond, corresponding to how
+     * many previous frames are enqueued in the backend. This also varies by backend. Therefore,
+     * it is recommended to only call this method once per material shortly after creation.
+     *</p>
+     *<p>
+     * If the same variant is scheduled for compilation multiple times, the first scheduling
+     * takes precedence; later scheduling are ignored.
+     *</p>
+     *<p>
+     * caveat: A consequence is that if a variant is scheduled on the low priority queue and later
+     * scheduled again on the high priority queue, the later scheduling is ignored.
+     * Therefore, the second callback could be called before the variant is compiled.
+     * However, the first callback, if specified, will trigger as expected.
+     *</p>
+     *<p>
+     * The callback is guaranteed to be called. If the engine is destroyed while some material
+     * variants are still compiling or in the queue, these will be discarded and the corresponding
+     * callback will be called. In that case however the Material pointer passed to the callback
+     * is guaranteed to be invalid (either because it's been destroyed by the user already, or,
+     * because it's been cleaned-up by the Engine).
+     *</p>
+     *<p>
+     * {@link UserVariantFilterBit#ALL} should be used with caution. Only variants that an application
+     * needs should be included in the variants argument. For example, the STE variant is only used
+     * for stereoscopic rendering. If an application is not planning to render in stereo, this bit
+     * should be turned off to avoid unnecessary material compilations.
+     *</p>
+     * @param priority      Which priority queue to use, LOW or HIGH.
+     * @param variants      Variants to include to the compile command.
+     * @param handler       An {@link java.util.concurrent.Executor Executor}. On Android this can also be a {@link android.os.Handler Handler}.
+     * @param callback      callback called on the main thread when the compilation is done on
+     *                      by backend.
+     */
+    public void compile(@NonNull CompilerPriorityQueue priority,
+                        int variants,
+                        @Nullable Object handler,
+                        @Nullable Runnable callback) {
+        nCompile(getNativeObject(), priority.ordinal(), variants, handler, callback);
+    }
+
     /**
      * Creates a new instance of this material. Material instances should be freed using
      * {@link Engine#destroyMaterialInstance(MaterialInstance)}.
@@ -437,6 +527,28 @@ public class Material {
         return EnumCache.sRefractionTypeValues[nGetRefractionType(getNativeObject())];
     }
 
+    /**
+     * Returns the reflection mode of this material.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/lighting:reflections">
+     * Lighting: reflections</a>
+     */
+    public ReflectionMode getReflectionMode() {
+        return EnumCache.sReflectionModeValues[nGetReflectionMode(getNativeObject())];
+    }
+
+    /**
+     * Returns the minimum required feature level for this material.
+     *
+     * @see
+     * <a href="https://google.github.io/filament/Materials.html#materialdefinitions/materialblock/general:featurelevel">
+     * General: featureLevel</a>
+     */
+    public FeatureLevel getFeatureLevel() {
+        return EnumCache.sFeatureLevelValues[nGetFeatureLevel(getNativeObject())];
+    }
+
     /**
      * Returns the vertex domain of this material.
      *
@@ -916,6 +1028,7 @@ public class Material {
     private static native long nCreateInstanceWithName(long nativeMaterial, @NonNull String name);
     private static native long nGetDefaultInstance(long nativeMaterial);
 
+    private static native void nCompile(long nativeMaterial, int priority, int variants, Object handler, Runnable runnable);
     private static native String nGetName(long nativeMaterial);
     private static native int nGetShading(long nativeMaterial);
     private static native int nGetInterpolation(long nativeMaterial);
@@ -932,6 +1045,8 @@ public class Material {
     private static native float nGetSpecularAntiAliasingThreshold(long nativeMaterial);
     private static native int nGetRefractionMode(long nativeMaterial);
     private static native int nGetRefractionType(long nativeMaterial);
+    private static native int nGetReflectionMode(long nativeMaterial);
+    private static native int nGetFeatureLevel(long nativeMaterial);
 
 
     private static native int nGetParameterCount(long nativeMaterial);

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

@@ -625,6 +625,15 @@ public class MaterialInstance {
         nSetDepthCulling(getNativeObject(), enable);
     }
 
+    /**
+     * Sets the depth comparison function (default is {@link TextureSampler.CompareFunction#GE}).
+     *
+     * @param func the depth comparison function
+     */
+    public void setDepthFunc(TextureSampler.CompareFunction func) {
+        nSetDepthFunc(getNativeObject(), func.ordinal());
+    }
+
     /**
      * Returns whether depth culling is enabled.
      */
@@ -632,6 +641,13 @@ public class MaterialInstance {
         return nIsDepthCullingEnabled(getNativeObject());
     }
 
+    /**
+     * Returns the depth comparison function.
+     */
+    public TextureSampler.CompareFunction getDepthFunc() {
+        return TextureSampler.EnumCache.sCompareFunctionValues[nGetDepthFunc(getNativeObject())];
+    }
+
     /**
      * Sets the stencil comparison function (default is {@link TextureSampler.CompareFunction#ALWAYS}).
      *
@@ -884,7 +900,7 @@ public class MaterialInstance {
             @IntRange(from = 0) int offset, @IntRange(from = 1) int count);
 
     private static native void nSetParameterTexture(long nativeMaterialInstance,
-            @NonNull String name, long nativeTexture, int sampler);
+            @NonNull String name, long nativeTexture, long sampler);
 
     private static native void nSetScissor(long nativeMaterialInstance,
             @IntRange(from = 0) int left, @IntRange(from = 0) int bottom,
@@ -908,6 +924,7 @@ public class MaterialInstance {
     private static native void nSetDepthWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetStencilWrite(long nativeMaterialInstance, boolean enable);
     private static native void nSetDepthCulling(long nativeMaterialInstance, boolean enable);
+    private static native void nSetDepthFunc(long nativeMaterialInstance, long function);
 
     private static native void nSetStencilCompareFunction(long nativeMaterialInstance,
             long function, long face);
@@ -939,4 +956,5 @@ public class MaterialInstance {
     private static native boolean nIsDepthWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsStencilWriteEnabled(long nativeMaterialInstance);
     private static native boolean nIsDepthCullingEnabled(long nativeMaterialInstance);
+    private static native int nGetDepthFunc(long nativeMaterialInstance);
 }

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

@@ -81,8 +81,6 @@ public class RenderTarget {
         /**
          * Sets a texture to a given attachment point.
          *
-         * <p>All RenderTargets must have a non-null <code>COLOR</code> attachment.</p>
-         *
          * @param attachment The attachment point of the texture.
          * @param texture The associated texture object.
          * @return A reference to this Builder for chaining calls.

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

@@ -16,6 +16,7 @@
 
 package com.google.android.filament;
 
+import androidx.annotation.NonNull;
 import androidx.annotation.Nullable;
 
 /**
@@ -146,18 +147,29 @@ public class Scene {
     }
 
     /**
-     * Returns the number of {@link RenderableManager} components in the <code>Scene</code>.
+     * Returns the total number of Entities in the <code>Scene</code>, whether alive or not.
      *
-     * @return number of {@link RenderableManager} components in the <code>Scene</code>..
+     * @return the total number of Entities in the <code>Scene</code>.
+     */
+    public int getEntityCount() {
+        return nGetEntityCount(getNativeObject());
+    }
+
+    /**
+     * Returns the number of active (alive) {@link RenderableManager} components in the
+     * <code>Scene</code>.
+     *
+     * @return number of {@link RenderableManager} components in the <code>Scene</code>.
      */
     public int getRenderableCount() {
         return nGetRenderableCount(getNativeObject());
     }
 
     /**
-     * Returns the number of {@link LightManager} components in the <code>Scene</code>.
+     * Returns the number of active (alive) {@link LightManager} components in the
+     * <code>Scene</code>.
      *
-     * @return number of {@link LightManager} components in the <code>Scene</code>..
+     * @return number of {@link LightManager} components in the <code>Scene</code>.
      */
     public int getLightCount() {
         return nGetLightCount(getNativeObject());
@@ -179,6 +191,52 @@ public class Scene {
         return mNativeObject;
     }
 
+    /**
+     * Returns the list of all entities in the Scene. If outArray is provided and large enough,
+     * it is used to store the list and returned, otherwise a new array is allocated and returned.
+     * @param outArray an array to store the list of entities in the scene.
+     * @return outArray if it was used or a newly allocated array.
+     * @see #getEntityCount
+     */
+    public int[] getEntities(@Nullable int[] outArray) {
+        int c = getEntityCount();
+        if (outArray == null || outArray.length < c) {
+            outArray = new int[c];
+        }
+        boolean success = nGetEntities(getNativeObject(), outArray, outArray.length);
+        if (!success) {
+            throw new IllegalStateException("Error retriving Scene's entities");
+        }
+        return outArray;
+    }
+
+    /**
+     * Returns the list of all entities in the Scene in a newly allocated array.
+     * @return an array containing the list of all entities in the scene.
+     * @see #getEntityCount
+     */
+    public int[] getEntities() {
+        return getEntities(null);
+    }
+
+    public interface EntityProcessor {
+        void process(@Entity int entity);
+    }
+
+    /**
+     * Invokes user functor on each entity in the scene.
+     *
+     * It is not allowed to add or remove an entity from the scene within the functor.
+     *
+     * @param entityProcessor User provided functor called for each entity in the scene
+     */
+    public void forEach(@NonNull EntityProcessor entityProcessor) {
+        int[] entities = getEntities(null);
+        for (int entity : entities) {
+            entityProcessor.process(entity);
+        }
+    }
+
     void clearNativeObject() {
         mNativeObject = 0;
     }
@@ -189,7 +247,9 @@ public class Scene {
     private static native void nAddEntities(long nativeScene, int[] entities);
     private static native void nRemove(long nativeScene, int entity);
     private static native void nRemoveEntities(long nativeScene, int[] entities);
+    private static native int nGetEntityCount(long nativeScene);
     private static native int nGetRenderableCount(long nativeScene);
     private static native int nGetLightCount(long nativeScene);
     private static native boolean nHasEntity(long nativeScene, int entity);
+    private static native boolean nGetEntities(long nativeScene, int[] outArray, int length);
 }

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

@@ -103,6 +103,31 @@ public class SwapChain {
      */
     public static final long CONFIG_SRGB_COLORSPACE = 0x10;
 
+    /**
+     * Indicates that this SwapChain should allocate a stencil buffer in addition to a depth buffer.
+     *
+     * This flag is necessary when using View::setStencilBufferEnabled and rendering directly into
+     * the SwapChain (when post-processing is disabled).
+     *
+     * The specific format of the stencil buffer depends on platform support. The following pixel
+     * formats are tried, in order of preference:
+     *
+     * Depth only (without CONFIG_HAS_STENCIL_BUFFER):
+     * - DEPTH32F
+     * - DEPTH24
+     *
+     * Depth + stencil (with CONFIG_HAS_STENCIL_BUFFER):
+     * - DEPTH32F_STENCIL8
+     * - DEPTH24F_STENCIL8
+     *
+     * Note that enabling the stencil buffer may hinder depth precision and should only be used if
+     * necessary.
+     *
+     * @see View#setStencilBufferEnabled
+     * @see View#setPostProcessingEnabled
+     */
+    public static final long CONFIG_HAS_STENCIL_BUFFER = 0x20;
+
     SwapChain(long nativeSwapChain, Object surface) {
         mNativeObject = nativeSwapChain;
         mSurface = surface;
@@ -137,10 +162,6 @@ public class SwapChain {
      * </p>
      *
      * <p>
-     * The FrameCompletedCallback is guaranteed to be called on the main Filament thread.
-     * </p>
-     *
-     * <p>
      * Warning: Only Filament's Metal backend supports frame callbacks. Other backends ignore the
      * callback (which will never be called) and proceed normally.
      * </p>

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

@@ -849,6 +849,10 @@ public class Texture {
         public static final int SAMPLEABLE = 0x10;
         /** Texture can be used as a subpass input */
         public static final int SUBPASS_INPUT = 0x20;
+        /** Texture can be used the source of a blit() */
+        public static final int BLIT_SRC = 0x40;
+        /** Texture can be used the destination of a blit() */
+        public static final int BLIT_DST = 0x80;
         /** by default textures are <code>UPLOADABLE</code> and <code>SAMPLEABLE</code>*/
         public static final int DEFAULT = UPLOADABLE | SAMPLEABLE;
     }

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

@@ -126,7 +126,7 @@ public class TextureSampler {
         NEVER
     }
 
-    int mSampler = 0; // bit field used by native
+    long mSampler = 0; // bit field used by native
 
     /**
      * Initializes the <code>TextureSampler</code> with default values.
@@ -342,26 +342,26 @@ public class TextureSampler {
         }
     }
 
-    private static native int nCreateSampler(int min, int max, int s, int t, int r);
-    private static native int nCreateCompareSampler(int mode, int function);
+    private static native long nCreateSampler(int min, int max, int s, int t, int r);
+    private static native long nCreateCompareSampler(int mode, int function);
 
-    private static native int nGetMinFilter(int sampler);
-    private static native int nSetMinFilter(int sampler, int filter);
-    private static native int nGetMagFilter(int sampler);
-    private static native int nSetMagFilter(int sampler, int filter);
+    private static native int nGetMinFilter(long sampler);
+    private static native long nSetMinFilter(long sampler, int filter);
+    private static native int nGetMagFilter(long sampler);
+    private static native long nSetMagFilter(long sampler, int filter);
 
-    private static native int nGetWrapModeS(int sampler);
-    private static native int nSetWrapModeS(int sampler, int mode);
-    private static native int nGetWrapModeT(int sampler);
-    private static native int nSetWrapModeT(int sampler, int mode);
-    private static native int nGetWrapModeR(int sampler);
-    private static native int nSetWrapModeR(int sampler, int mode);
+    private static native int nGetWrapModeS(long sampler);
+    private static native long nSetWrapModeS(long sampler, int mode);
+    private static native int nGetWrapModeT(long sampler);
+    private static native long nSetWrapModeT(long sampler, int mode);
+    private static native int nGetWrapModeR(long sampler);
+    private static native long nSetWrapModeR(long sampler, int mode);
 
-    private static native int nGetCompareMode(int sampler);
-    private static native int nSetCompareMode(int sampler, int mode);
-    private static native int nGetCompareFunction(int sampler);
-    private static native int nSetCompareFunction(int sampler, int function);
+    private static native int nGetCompareMode(long sampler);
+    private static native long nSetCompareMode(long sampler, int mode);
+    private static native int nGetCompareFunction(long sampler);
+    private static native long nSetCompareFunction(long sampler, int function);
 
-    private static native float nGetAnisotropy(int sampler);
-    private static native int nSetAnisotropy(int sampler, float anisotropy);
+    private static native float nGetAnisotropy(long sampler);
+    private static native long nSetAnisotropy(long sampler, float anisotropy);
 }

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

@@ -100,6 +100,45 @@ public class ToneMapper {
         }
     }
 
+    /**
+     * AgX tone mapping operator.
+     */
+    public static class Agx extends ToneMapper {
+
+        public enum AgxLook {
+            /**
+             * Base contrast with no look applied
+             */
+            NONE,
+
+            /**
+             * A punchy and more chroma laden look for sRGB displays
+             */
+            PUNCHY,
+
+            /**
+             * A golden tinted, slightly washed look for BT.1886 displays
+             */
+            GOLDEN
+        }
+
+        /**
+         * Builds a new AgX tone mapper with no look applied.
+         */
+        public Agx() {
+            this(AgxLook.NONE);
+        }
+
+        /**
+         * Builds a new AgX tone mapper.
+         *
+         * @param look: an optional creative adjustment to contrast and saturation
+         */
+        public Agx(AgxLook look) {
+            super(nCreateAgxToneMapper(look.ordinal()));
+        }
+    }
+
     /**
      * Generic tone mapping operator that gives control over the tone mapping
      * curve. This operator can be used to control the aesthetics of the final
@@ -194,6 +233,7 @@ public class ToneMapper {
     private static native long nCreateACESToneMapper();
     private static native long nCreateACESLegacyToneMapper();
     private static native long nCreateFilmicToneMapper();
+    private static native long nCreateAgxToneMapper(int look);
     private static native long nCreateGenericToneMapper(
             float contrast, float midGrayIn, float midGrayOut, float hdrMax);
 

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

@@ -27,6 +27,8 @@ import static com.google.android.filament.Asserts.assertFloat3In;
 import static com.google.android.filament.Asserts.assertFloat4In;
 import static com.google.android.filament.Colors.LinearColor;
 
+import com.google.android.filament.proguard.UsedByNative;
+
 /**
  * Encompasses all the state needed for rendering a {@link Scene}.
  *
@@ -73,6 +75,7 @@ public class View {
     private AmbientOcclusionOptions mAmbientOcclusionOptions;
     private BloomOptions mBloomOptions;
     private FogOptions mFogOptions;
+    private StereoscopicOptions mStereoscopicOptions;
     private RenderTarget mRenderTarget;
     private BlendMode mBlendMode;
     private DepthOfFieldOptions mDepthOfFieldOptions;
@@ -902,7 +905,7 @@ public class View {
         mBloomOptions = options;
         nSetBloomOptions(getNativeObject(), options.dirt != null ? options.dirt.getNativeObject() : 0,
                 options.dirtStrength, options.strength, options.resolution,
-                options.anamorphism, options.levels, options.blendMode.ordinal(),
+                options.levels, options.blendMode.ordinal(),
                 options.threshold, options.enabled, options.highlight,
                 options.lensFlare, options.starburst, options.chromaticAberration,
                 options.ghostCount, options.ghostSpacing, options.ghostThreshold,
@@ -966,6 +969,7 @@ public class View {
                 options.color[0], options.color[1], options.color[2],
                 options.density, options.inScatteringStart, options.inScatteringSize,
                 options.fogColorFromIbl,
+                options.skyColor == null ? 0 : options.skyColor.getNativeObject(),
                 options.enabled);
     }
 
@@ -1029,7 +1033,8 @@ public class View {
      * </p>
      *
      * <p>
-     * Post-processing must be enabled in order to use the stencil buffer.
+     * If post-processing is disabled, then the SwapChain must have the CONFIG_HAS_STENCIL_BUFFER
+     * flag set in order to use the stencil buffer.
      * </p>
      *
      * <p>
@@ -1051,6 +1056,51 @@ public class View {
         return nIsStencilBufferEnabled(getNativeObject());
     }
 
+    /**
+     * Sets the stereoscopic rendering options for this view.
+     *
+     * <p>
+     * Currently, only one type of stereoscopic rendering is supported: side-by-side.
+     * Side-by-side stereo rendering splits the viewport into two halves: a left and right half.
+     * Eye 0 will render to the left half, while Eye 1 will render into the right half.
+     * </p>
+     *
+     * <p>
+     * Currently, the following features are not supported with stereoscopic rendering:
+     * - post-processing
+     * - shadowing
+     * - punctual lights
+     * </p>
+     *
+     * <p>
+     * Stereo rendering depends on device and platform support. To check if stereo rendering is
+     * supported, use {@link Engine#isStereoSupported()}. If stereo rendering is not supported, then
+     * the stereoscopic options have no effect.
+     * </p>
+     *
+     * @param options The stereoscopic options to use on this view
+     * @see #getStereoscopicOptions
+     */
+    public void setStereoscopicOptions(@NonNull StereoscopicOptions options) {
+        mStereoscopicOptions = options;
+        nSetStereoscopicOptions(getNativeObject(), options.enabled);
+    }
+
+    /**
+     * Gets the stereoscopic options.
+     *
+     * @return options Stereoscopic options currently set.
+     * @see #setStereoscopicOptions
+     */
+    @NonNull
+    public StereoscopicOptions getStereoscopicOptions() {
+        if (mStereoscopicOptions == null) {
+            mStereoscopicOptions = new StereoscopicOptions();
+        }
+        return mStereoscopicOptions;
+    }
+
+
     /**
      * A class containing the result of a picking query
      */
@@ -1095,10 +1145,29 @@ public class View {
         nPick(getNativeObject(), x, y, handler, internalCallback);
     }
 
+    @UsedByNative("View.cpp")
     private static class InternalOnPickCallback implements Runnable {
+        private final OnPickCallback mUserCallback;
+        private final PickingQueryResult mPickingQueryResult = new PickingQueryResult();
+
+        @UsedByNative("View.cpp")
+        @Entity
+        int mRenderable;
+
+        @UsedByNative("View.cpp")
+        float mDepth;
+
+        @UsedByNative("View.cpp")
+        float mFragCoordsX;
+        @UsedByNative("View.cpp")
+        float mFragCoordsY;
+        @UsedByNative("View.cpp")
+        float mFragCoordsZ;
+
         public InternalOnPickCallback(OnPickCallback mUserCallback) {
             this.mUserCallback = mUserCallback;
         }
+
         @Override
         public void run() {
             mPickingQueryResult.renderable = mRenderable;
@@ -1108,13 +1177,6 @@ public class View {
             mPickingQueryResult.fragCoords[2] = mFragCoordsZ;
             mUserCallback.onPick(mPickingQueryResult);
         }
-        private final OnPickCallback mUserCallback;
-        private final PickingQueryResult mPickingQueryResult = new PickingQueryResult();
-        @Entity int mRenderable;
-        float mDepth;
-        float mFragCoordsX;
-        float mFragCoordsY;
-        float mFragCoordsZ;
     }
 
     /**
@@ -1201,9 +1263,10 @@ public class View {
     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);
     private static native void nSetSSCTOptions(long nativeView, float ssctLightConeRad, float ssctStartTraceDistance, float ssctContactDistanceMax, float ssctIntensity, float v, float v1, float v2, float ssctDepthBias, float ssctDepthSlopeBias, int ssctSampleCount, int ssctRayCount, boolean ssctEnabled);
-    private static native void nSetBloomOptions(long nativeView, long dirtNativeObject, float dirtStrength, float strength, int resolution, float anamorphism, int levels, int blendMode, boolean threshold, boolean enabled, float highlight,
+    private static native void nSetBloomOptions(long nativeView, long dirtNativeObject, float dirtStrength, float strength, int resolution, int levels, int blendMode, boolean threshold, boolean enabled, float highlight,
             boolean lensFlare, boolean starburst, float chromaticAberration, int ghostCount, float ghostSpacing, float ghostThreshold, float haloThickness, float haloRadius, float haloThreshold);
-    private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, boolean enabled);
+    private static native void nSetFogOptions(long nativeView, float distance, float maximumOpacity, float height, float heightFalloff, float cutOffDistance, float v, float v1, float v2, float density, float inScatteringStart, float inScatteringSize, boolean fogColorFromIbl, long skyColorNativeObject, boolean enabled);
+    private static native void nSetStereoscopicOptions(long nativeView, boolean enabled);
     private static native void nSetBlendMode(long nativeView, int blendMode);
     private static native void nSetDepthOfFieldOptions(long nativeView, float cocScale, float maxApertureDiameter, boolean enabled, int filter,
             boolean nativeResolution, int foregroundRingCount, int backgroundRingCount, int fastGatherRingCount, int maxForegroundCOC, int maxBackgroundCOC);
@@ -1338,8 +1401,6 @@ public class View {
      * blendMode:   Whether the bloom effect is purely additive (false) or mixed with the original
      *              image (true).
      *
-     * anamorphism: Bloom's aspect ratio (x/y), for artistic purposes.
-     *
      * threshold:   When enabled, a threshold at 1.0 is applied on the source image, this is
      *              useful for artistic reasons and is usually needed when a dirt texture is used.
      *
@@ -1377,13 +1438,9 @@ public class View {
         /**
          * resolution of vertical axis (2^levels to 2048)
          */
-        public int resolution = 360;
+        public int resolution = 384;
         /**
-         * bloom x/y aspect-ratio (1/32 to 32)
-         */
-        public float anamorphism = 1.0f;
-        /**
-         * number of blur levels (3 to 11)
+         * number of blur levels (1 to 11)
          */
         public int levels = 6;
         /**
@@ -1403,6 +1460,17 @@ public class View {
          * limit highlights to this value before bloom [10, +inf]
          */
         public float highlight = 1000.0f;
+        /**
+         * Bloom quality level.
+         * LOW (default): use a more optimized down-sampling filter, however there can be artifacts
+         *      with dynamic resolution, this can be alleviated by using the homogenous mode.
+         * MEDIUM: Good balance between quality and performance.
+         * HIGH: In this mode the bloom resolution is automatically increased to avoid artifacts.
+         *      This mode can be significantly slower on mobile, especially at high resolution.
+         *      This mode greatly improves the anamorphic bloom.
+         */
+        @NonNull
+        public QualityLevel quality = QualityLevel.LOW;
         /**
          * enable screen-space lens flare
          */
@@ -1518,9 +1586,31 @@ public class View {
         /**
          * The fog color will be sampled from the IBL in the view direction and tinted by `color`.
          * Depending on the scene this can produce very convincing results.
-         * This simulate a more anisotropic phase-function.
+         *
+         * This simulates a more anisotropic phase-function.
+         *
+         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         *
+         * @see skyColor
          */
         public boolean fogColorFromIbl = false;
+        /**
+         * skyTexture must be a mipmapped cubemap. When provided, the fog color will be sampled from
+         * this texture, higher resolution mip levels will be used for objects at the far clip plane,
+         * and lower resolution mip levels for objects closer to the camera. The skyTexture should
+         * typically be heavily blurred; a typical way to produce this texture is to blur the base
+         * level with a strong gaussian filter or even an irradiance filter and then generate mip
+         * levels as usual. How blurred the base level is somewhat of an artistic decision.
+         *
+         * This simulates a more anisotropic phase-function.
+         *
+         * `fogColorFromIbl` is ignored when skyTexture is specified.
+         *
+         * @see Texture
+         * @see fogColorFromIbl
+         */
+        @Nullable
+        public Texture skyColor = null;
         /**
          * Enable or disable large-scale fog
          */
@@ -1887,6 +1977,7 @@ public class View {
          * PCF with soft shadows and contact hardening
          */
         PCSS,
+        PCFd,
     }
 
     /**
@@ -1949,4 +2040,11 @@ public class View {
          */
         public float penumbraRatioScale = 1.0f;
     }
+
+    /**
+     * Options for stereoscopic (multi-eye) rendering.
+     */
+    public static class StereoscopicOptions {
+        public boolean enabled = false;
+    }
 }

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

@@ -22,17 +22,35 @@ import com.google.android.filament.Fence;
 public class FilamentHelper {
 
     /**
-     * Wait for all pending frames to be processed before returning. This is to
-     * avoid a race between the surface being resized before pending frames are
-     * rendered into it. This is typically called from {@link UiHelper.RendererCallback#onResized},
-     * {@link android.view.SurfaceHolder.Callback#surfaceChanged} or
-     * {@link android.view.TextureView.SurfaceTextureListener#onSurfaceTextureSizeChanged}.
+     * Wait for all pending frames to be processed before returning. This is to avoid a race
+     * between the surface being resized before pending frames are rendered into it.
+     * <p>
+     * For {@link android.view.TextureView} this must be called before the texture's size is
+     * reconfigured, which unfortunately is done by the Android framework before
+     * {@link UiHelper} listeners are invoked. Therefore <code>synchronizePendingFrames</code>
+     * cannot be called from
+     * {@link android.view.TextureView.SurfaceTextureListener#onSurfaceTextureSizeChanged}; instead
+     * a subclass of {@link android.view.TextureView} must be used in order to call it from
+     * {@link android.view.TextureView#onSizeChanged}:
+     * </p>
+     * <pre>
+     * public class MyTextureView extends TextureView {
+     *     private Engine engine;
+     *     protected void onSizeChanged(int w, int h, int oldw, int oldh) {
+     *         FilamentHelper.synchronizePendingFrames(engine);
+     *         super.onSizeChanged(w, h, oldw, oldh);
+     *     }
+     * }
+     * </pre>
+     *
+     * Otherwise, this is typically called from {@link UiHelper.RendererCallback#onResized},
+     * {@link android.view.SurfaceHolder.Callback#surfaceChanged}.
      *
      * @param engine Filament engine to synchronize
      *
      * @see UiHelper.RendererCallback#onResized
      * @see android.view.SurfaceHolder.Callback#surfaceChanged
-     * @see android.view.TextureView.SurfaceTextureListener#onSurfaceTextureSizeChanged
+     * @see android.view.TextureView#onSizeChanged
      */
     static public void synchronizePendingFrames(Engine engine) {
         Fence fence = engine.createFence();

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

@@ -182,28 +182,85 @@ public class UiHelper {
         void detach();
     }
 
-    private static class SurfaceViewHandler implements RenderSurface {
-        private final SurfaceView mSurfaceView;
+    private class SurfaceViewHandler implements RenderSurface, SurfaceHolder.Callback {
+        @NonNull private final SurfaceView mSurfaceView;
 
-        SurfaceViewHandler(SurfaceView surface) {
-            mSurfaceView = surface;
+        SurfaceViewHandler(@NonNull SurfaceView surfaceView) {
+            mSurfaceView = surfaceView;
+
+            @NonNull SurfaceHolder holder = surfaceView.getHolder();
+            holder.addCallback(this);
+
+            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
+            }
+
+            // in case the SurfaceView's surface already existed
+            final Surface surface = holder.getSurface();
+            if (surface != null && surface.isValid()) {
+                surfaceCreated(holder);
+                // there is no way to retrieve the actual PixelFormat, since it is not used
+                // in the callback, we can use whatever we want.
+                surfaceChanged(holder, PixelFormat.RGBA_8888,
+                    holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
+            }
         }
 
         @Override
         public void resize(int width, int height) {
-            mSurfaceView.getHolder().setFixedSize(width, height);
+            @NonNull SurfaceHolder holder = mSurfaceView.getHolder();
+            holder.setFixedSize(width, height);
         }
 
         @Override
         public void detach() {
+            @NonNull SurfaceHolder holder = mSurfaceView.getHolder();
+            holder.removeCallback(this);
+        }
+
+        @Override
+        public void surfaceCreated(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
+            createSwapChain(holder.getSurface());
+        }
+
+        @Override
+        public void surfaceChanged(
+            @NonNull SurfaceHolder holder, int format, int width, int height) {
+            // Note: this is always called at least once after surfaceCreated()
+            if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
+            if (mRenderCallback != null) {
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void surfaceDestroyed(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
+            destroySwapChain();
         }
     }
 
-    private static class SurfaceHolderHandler implements RenderSurface {
+    private class SurfaceHolderHandler implements RenderSurface, SurfaceHolder.Callback {
         private final SurfaceHolder mSurfaceHolder;
 
-        SurfaceHolderHandler(SurfaceHolder surface) {
-            mSurfaceHolder = surface;
+        SurfaceHolderHandler(@NonNull SurfaceHolder holder) {
+            mSurfaceHolder = holder;
+            holder.addCallback(this);
+
+            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
+            }
+
+            // in case the SurfaceHolder's surface already existed
+            final Surface surface = holder.getSurface();
+            if (surface != null && surface.isValid()) {
+                surfaceCreated(holder);
+                // there is no way to retrieve the actual PixelFormat, since it is not used
+                // in the callback, we can use whatever we want.
+                surfaceChanged(holder, PixelFormat.RGBA_8888,
+                    holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
+            }
         }
 
         @Override
@@ -213,30 +270,127 @@ public class UiHelper {
 
         @Override
         public void detach() {
+            mSurfaceHolder.removeCallback(this);
+        }
+
+        @Override
+        public void surfaceCreated(@NonNull SurfaceHolder holder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
+            createSwapChain(holder.getSurface());
+        }
+
+        @Override
+        public void surfaceChanged(@NonNull SurfaceHolder holder, int format, int width, int height) {
+            // Note: this is always called at least once after surfaceCreated()
+            if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
+            if (mRenderCallback != null) {
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void surfaceDestroyed(@NonNull SurfaceHolder surfaceHolder) {
+            if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
+            destroySwapChain();
         }
     }
 
-    private class TextureViewHandler implements RenderSurface {
+    private class TextureViewHandler implements RenderSurface, TextureView.SurfaceTextureListener {
         private final TextureView mTextureView;
         private Surface mSurface;
 
-        TextureViewHandler(TextureView surface) { mTextureView = surface; }
+        TextureViewHandler(@NonNull TextureView view) {
+            mTextureView = view;
+            mTextureView.setSurfaceTextureListener(this);
+            // in case the View's SurfaceTexture already existed
+            if (view.isAvailable()) {
+                SurfaceTexture surfaceTexture = view.getSurfaceTexture();
+                if (surfaceTexture != null) {
+                    this.onSurfaceTextureAvailable(surfaceTexture,
+                        mDesiredWidth, mDesiredHeight);
+                }
+            }
+        }
 
         @Override
         public void resize(int width, int height) {
             if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
-                mTextureView.getSurfaceTexture().setDefaultBufferSize(width, height);
+                final SurfaceTexture surfaceTexture = mTextureView.getSurfaceTexture();
+                if (surfaceTexture != null) {
+                    surfaceTexture.setDefaultBufferSize(width, height);
+                }
+            }
+            if (mRenderCallback != null) {
+                // the call above won't cause TextureView.onSurfaceTextureSizeChanged()
+                mRenderCallback.onResized(width, height);
             }
-            // the call above won't cause TextureView.onSurfaceTextureSizeChanged()
-            mRenderCallback.onResized(width, height);
         }
 
         @Override
         public void detach() {
+            mTextureView.setSurfaceTextureListener(null);
             setSurface(null);
         }
 
-        void setSurface(Surface surface) {
+
+        @Override
+        public void onSurfaceTextureAvailable(
+            @NonNull SurfaceTexture surfaceTexture, int width, int height) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureAvailable()");
+
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
+                if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                    surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
+                }
+            }
+
+            final Surface surface = new Surface(surfaceTexture);
+            setSurface(surface);
+            createSwapChain(surface);
+
+            if (mRenderCallback != null) {
+                // Call this the first time because onSurfaceTextureSizeChanged()
+                // isn't called at initialization time
+                mRenderCallback.onResized(width, height);
+            }
+        }
+
+        @Override
+        public void onSurfaceTextureSizeChanged(
+            @NonNull SurfaceTexture surfaceTexture, int width, int height) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureSizeChanged()");
+            if (mRenderCallback != null) {
+                if (mDesiredWidth > 0 && mDesiredHeight > 0) {
+                    surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
+                    mRenderCallback.onResized(mDesiredWidth, mDesiredHeight);
+                } else {
+                    mRenderCallback.onResized(width, height);
+                }
+                // We must recreate the SwapChain to guarantee that it sees the new size.
+                // More precisely, for an EGL client, the EGLSurface must be recreated. For
+                // a Vulkan client, the SwapChain must be recreated. Calling
+                // onNativeWindowChanged() will accomplish that.
+                // This requirement comes from SurfaceTexture.setDefaultBufferSize()
+                // documentation.
+                final Surface surface = getSurface();
+                if (surface != null) {
+                    mRenderCallback.onNativeWindowChanged(surface);
+                }
+            }
+        }
+
+        @Override
+        public boolean onSurfaceTextureDestroyed(@NonNull SurfaceTexture surfaceTexture) {
+            if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureDestroyed()");
+            destroySwapChain();
+            return true;
+        }
+
+        @Override
+        public void onSurfaceTextureUpdated(@NonNull SurfaceTexture surface) { }
+
+
+        private void setSurface(@Nullable Surface surface) {
             if (surface == null) {
                 if (mSurface != null) {
                     mSurface.release();
@@ -244,6 +398,10 @@ public class UiHelper {
             }
             mSurface = surface;
         }
+
+        private Surface getSurface() {
+            return mSurface;
+        }
     }
 
     /**
@@ -294,7 +452,6 @@ public class UiHelper {
 
     /**
      * Checks whether we are ready to render into the attached surface.
-     *
      * Using OpenGL ES when this returns true, will result in drawing commands being lost,
      * HOWEVER, GLES state will be preserved. This is useful to initialize the engine.
      *
@@ -339,7 +496,6 @@ public class UiHelper {
     /**
      * Controls whether the render target (SurfaceView or TextureView) is opaque or not.
      * The render target is considered opaque by default.
-     *
      * Must be called before calling {@link #attachTo(SurfaceView)}, {@link #attachTo(TextureView)},
      * or {@link #attachTo(SurfaceHolder)}.
      *
@@ -362,10 +518,8 @@ public class UiHelper {
      * positioned above other surfaces but below the activity's surface. This property
      * only has an effect when used in combination with {@link #setOpaque(boolean) setOpaque(false)}
      * and does not affect TextureView targets.
-     *
      * Must be called before calling {@link #attachTo(SurfaceView)}
      * or {@link #attachTo(TextureView)}.
-     *
      * Has no effect when using {@link #attachTo(SurfaceHolder)}.
      *
      * @param overlay Indicates whether the render target should be rendered below the activity's
@@ -386,7 +540,6 @@ public class UiHelper {
 
     /**
      * Associate UiHelper with a SurfaceView.
-     *
      * As soon as SurfaceView is ready (i.e. has a Surface), we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
@@ -401,163 +554,32 @@ public class UiHelper {
                 view.setZOrderOnTop(translucent);
             }
 
-            int format = isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT;
-            view.getHolder().setFormat(format);
-
+            view.getHolder().setFormat(isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT);
             mRenderSurface = new SurfaceViewHandler(view);
-
-            final SurfaceHolder.Callback callback = new SurfaceHolder.Callback() {
-                @Override
-                public void surfaceCreated(SurfaceHolder holder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(
-                        SurfaceHolder holder, int format, int width, int height) {
-                    // Note: this is always called at least once after surfaceCreated()
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void surfaceDestroyed(SurfaceHolder holder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
-                    destroySwapChain();
-                }
-            };
-
-            SurfaceHolder holder = view.getHolder();
-            holder.addCallback(callback);
-            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
-            }
-
-            // in case the SurfaceView's surface already existed
-            final Surface surface = holder.getSurface();
-            if (surface != null && surface.isValid()) {
-                callback.surfaceCreated(holder);
-                callback.surfaceChanged(holder, format,
-                        holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
-            }
         }
     }
 
     /**
      * Associate UiHelper with a TextureView.
-     *
      * As soon as TextureView is ready (i.e. has a buffer), we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
     public void attachTo(@NonNull TextureView view) {
         if (attach(view)) {
             view.setOpaque(isOpaque());
-
             mRenderSurface = new TextureViewHandler(view);
-
-            TextureView.SurfaceTextureListener listener = new TextureView.SurfaceTextureListener() {
-                @Override
-                public void onSurfaceTextureAvailable(
-                        SurfaceTexture surfaceTexture, int width, int height) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureAvailable()");
-
-                    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.ICE_CREAM_SANDWICH_MR1) {
-                        if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                            surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
-                        }
-                    }
-
-                    Surface surface = new Surface(surfaceTexture);
-                    TextureViewHandler textureViewHandler = (TextureViewHandler) mRenderSurface;
-                    textureViewHandler.setSurface(surface);
-
-                    createSwapChain(surface);
-
-                    // Call this the first time because onSurfaceTextureSizeChanged()
-                    // isn't called at initialization time
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void onSurfaceTextureSizeChanged(
-                        SurfaceTexture surfaceTexture, int width, int height) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureSizeChanged()");
-                    if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                        surfaceTexture.setDefaultBufferSize(mDesiredWidth, mDesiredHeight);
-                        mRenderCallback.onResized(mDesiredWidth, mDesiredHeight);
-                    } else {
-                        mRenderCallback.onResized(width, height);
-                    }
-                }
-
-                @Override
-                public boolean onSurfaceTextureDestroyed(SurfaceTexture surfaceTexture) {
-                    if (LOGGING) Log.d(LOG_TAG, "onSurfaceTextureDestroyed()");
-                    destroySwapChain();
-                    return true;
-                }
-
-                @Override
-                public void onSurfaceTextureUpdated(SurfaceTexture surface) { }
-            };
-
-            view.setSurfaceTextureListener(listener);
-
-            // in case the View's SurfaceTexture already existed
-            if (view.isAvailable()) {
-                SurfaceTexture surfaceTexture = view.getSurfaceTexture();
-                listener.onSurfaceTextureAvailable(surfaceTexture, mDesiredWidth, mDesiredHeight);
-            }
         }
     }
 
     /**
      * Associate UiHelper with a SurfaceHolder.
-     *
      * As soon as a Surface is created, we'll create the
      * EGL resources needed, and call user callbacks if needed.
      */
     public void attachTo(@NonNull SurfaceHolder holder) {
         if (attach(holder)) {
-            int format = isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT;
-            holder.setFormat(format);
-
+            holder.setFormat(isOpaque() ? PixelFormat.OPAQUE : PixelFormat.TRANSLUCENT);
             mRenderSurface = new SurfaceHolderHandler(holder);
-
-            final SurfaceHolder.Callback callback = new SurfaceHolder.Callback() {
-                @Override
-                public void surfaceCreated(SurfaceHolder surfaceHolder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceCreated()");
-                    createSwapChain(holder.getSurface());
-                }
-
-                @Override
-                public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
-                    // Note: this is always called at least once after surfaceCreated()
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceChanged(" + width + ", " + height + ")");
-                    mRenderCallback.onResized(width, height);
-                }
-
-                @Override
-                public void surfaceDestroyed(SurfaceHolder surfaceHolder) {
-                    if (LOGGING) Log.d(LOG_TAG, "surfaceDestroyed()");
-                    destroySwapChain();
-                }
-            };
-
-            holder.addCallback(callback);
-            if (mDesiredWidth > 0 && mDesiredHeight > 0) {
-                holder.setFixedSize(mDesiredWidth, mDesiredHeight);
-            }
-
-            // in case the SurfaceHolder's surface already existed
-            final Surface surface = holder.getSurface();
-            if (surface != null && surface.isValid()) {
-                callback.surfaceCreated(holder);
-                callback.surfaceChanged(holder, format,
-                        holder.getSurfaceFrame().width(), holder.getSurfaceFrame().height());
-            }
         }
     }
 
@@ -575,7 +597,9 @@ public class UiHelper {
     }
 
     private void createSwapChain(@NonNull Surface surface) {
-        mRenderCallback.onNativeWindowChanged(surface);
+        if (mRenderCallback != null) {
+            mRenderCallback.onNativeWindowChanged(surface);
+        }
         mHasSwapChain = true;
     }
 
@@ -583,7 +607,9 @@ public class UiHelper {
         if (mRenderSurface != null) {
             mRenderSurface.detach();
         }
-        mRenderCallback.onDetachedFromSurface();
+        if (mRenderCallback != null) {
+            mRenderCallback.onDetachedFromSurface();
+        }
         mHasSwapChain = false;
     }
 }

android/filament-utils-android/build.gradle

@@ -12,9 +12,6 @@ android {
         }
     }
 
-    defaultConfig {
-        missingDimensionStrategy 'functionality', 'full'
-    }
     packagingOptions {
         // No need to package up the following shared libs, which arise as a side effect of our
         // externalNativeBuild dependencies. When clients pick and choose from project-level gradle

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

@@ -17,6 +17,8 @@
 // Operators +, *, / based on http://half.sourceforge.net/ by Christian Rau
 // and licensed under MIT
 
+@file:Suppress("NOTHING_TO_INLINE")
+
 package com.google.android.filament.utils
 
 import com.google.android.filament.utils.Half.Companion.POSITIVE_INFINITY

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

@@ -191,7 +191,7 @@ class ModelViewer(
         asset = assetLoader.createAsset(buffer)
         asset?.let { asset ->
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.getInstance().animator
+            animator = asset.instance.animator
             asset.releaseSourceData()
         }
     }
@@ -214,7 +214,7 @@ class ModelViewer(
                 resourceLoader.addResourceData(uri, resourceBuffer)
             }
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.getInstance().animator
+            animator = asset.instance.animator
             asset.releaseSourceData()
         }
     }
@@ -311,7 +311,7 @@ class ModelViewer(
         var count = 0
         val popRenderables = { count = asset.popRenderables(readyRenderables); count != 0 }
         while (popRenderables()) {
-            for (i in 0..count - 1) {
+            for (i in 0 until count) {
                 val ri = rcm.getInstance(readyRenderables[i])
                 rcm.setScreenSpaceContactShadows(ri, true)
             }
@@ -371,7 +371,7 @@ class ModelViewer(
                 resourceLoader.addResourceData(uri, buffer)
             }
             resourceLoader.asyncBeginLoad(asset)
-            animator = asset.getInstance().animator
+            animator = asset.instance.animator
             asset.releaseSourceData()
         }
     }

android/gltfio-android/CMakeLists.txt

@@ -52,6 +52,7 @@ set(GLTFIO_SRCS
         ${GLTFIO_DIR}/include/gltfio/FilamentInstance.h
         ${GLTFIO_DIR}/include/gltfio/MaterialProvider.h
         ${GLTFIO_DIR}/include/gltfio/NodeManager.h
+        ${GLTFIO_DIR}/include/gltfio/TrsTransformManager.h
         ${GLTFIO_DIR}/include/gltfio/ResourceLoader.h
         ${GLTFIO_DIR}/include/gltfio/TextureProvider.h
         ${GLTFIO_DIR}/include/gltfio/math.h
@@ -69,10 +70,12 @@ set(GLTFIO_SRCS
         ${GLTFIO_DIR}/src/FilamentAsset.cpp
         ${GLTFIO_DIR}/src/FilamentInstance.cpp
         ${GLTFIO_DIR}/src/FNodeManager.h
+        ${GLTFIO_DIR}/src/FTrsTransformManager.h
         ${GLTFIO_DIR}/src/GltfEnums.h
         ${GLTFIO_DIR}/src/Ktx2Provider.cpp
         ${GLTFIO_DIR}/src/MaterialProvider.cpp
         ${GLTFIO_DIR}/src/NodeManager.cpp
+        ${GLTFIO_DIR}/src/TrsTransformManager.cpp
         ${GLTFIO_DIR}/src/ResourceLoader.cpp
         ${GLTFIO_DIR}/src/StbProvider.cpp
         ${GLTFIO_DIR}/src/TangentsJob.cpp

android/gltfio-android/build.gradle

@@ -1,12 +1,6 @@
 android {
     namespace 'com.google.android.filament.gltfio'
 
-    flavorDimensions "functionality"
-    productFlavors {
-        full {
-            dimension "functionality"
-        }
-    }
     packagingOptions {
         // No need to package up the following shared libs, which arise as a side effect of our
         // externalNativeBuild dependencies. When clients pick and choose from project-level gradle
@@ -18,7 +12,7 @@ android {
     }
 
     publishing {
-        singleVariant("fullRelease") {
+        singleVariant("release") {
             withSourcesJar()
             withJavadocJar()
         }
@@ -36,9 +30,9 @@ apply from: rootProject.file('gradle/gradle-mvn-push.gradle')
 afterEvaluate { project ->
     publishing {
         publications {
-            fullRelease(MavenPublication) {
+            release(MavenPublication) {
                 artifactId = POM_ARTIFACT_ID_FULL
-                from components.fullRelease
+                from components.release
             }
         }
     }

android/gradle.properties

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

android/samples/README.md

@@ -87,9 +87,9 @@ compile Filament's native library and Filament's AAR for this project. The easie
 is to install all the required dependencies and to run the following commands at the root of the
 source tree:
 
-```
-$ ./build.sh -p desktop -i release
-$ ./build.sh -p android release
+```shell
+./build.sh -p desktop -i release
+./build.sh -p android release
 ```
 
 This will build all the native components and the AAR required by this sample application.
@@ -100,8 +100,8 @@ distribution/install directory for desktop (produced by make/ninja install). Thi
 contain `bin/matc` and `bin/cmgen`.
 
 Example:
-```
-$ ./gradlew -Pfilament_tools_dir=../../dist-release assembleDebug
+```shell
+./gradlew -Pfilament_tools_dir=../../dist-release assembleDebug
 ```
 
 ## Important: SDK location
@@ -110,14 +110,24 @@ Either ensure your `ANDROID_HOME` environment variable is set or make sure the r
 contains a `local.properties` file with the `sdk.dir` property pointing to your installation of
 the Android SDK.
 
-## Android Studio
+## Compiling
+
+### Android Studio
 
 You must use the latest stable release of Android Studio. To open the project, point Studio to the
 `android` folder. After opening the project and syncing to gradle, select the sample of your choice
 using the drop-down widget in the toolbar.
 
-## Compiling
-
 To compile and run each sample make sure you have selected the appropriate build variant
 (arm7, arm8, x86 or x86_64). If you are not sure you can simply select the "universal"
 variant which includes all the other ones.
+
+### Command Line
+
+From the `android` directory in the project root:
+
+```shell
+./gradlew :samples:sample-hello-triangle:installDebug
+```
+
+Replace `sample-hello-triangle` with your preferred project.

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

@@ -32,7 +32,6 @@ android {
         applicationId "com.google.android.filament.gltf"
         minSdkVersion 19
         targetSdkVersion versions.targetSdk
-        missingDimensionStrategy 'functionality', 'full'
     }
 
     // NOTE: This is a workaround required because the AGP task collectReleaseDependencies

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

@@ -26,8 +26,10 @@ import android.widget.TextView
 import android.widget.Toast
 import com.google.android.filament.Fence
 import com.google.android.filament.IndirectLight
+import com.google.android.filament.Material
 import com.google.android.filament.Skybox
 import com.google.android.filament.View
+import com.google.android.filament.View.OnPickCallback
 import com.google.android.filament.utils.*
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -56,7 +58,9 @@ class MainActivity : Activity() {
     private lateinit var modelViewer: ModelViewer
     private lateinit var titlebarHint: TextView
     private val doubleTapListener = DoubleTapListener()
+    private val singleTapListener = SingleTapListener()
     private lateinit var doubleTapDetector: GestureDetector
+    private lateinit var singleTapDetector: GestureDetector
     private var remoteServer: RemoteServer? = null
     private var statusToast: Toast? = null
     private var statusText: String? = null
@@ -77,6 +81,7 @@ class MainActivity : Activity() {
         choreographer = Choreographer.getInstance()
 
         doubleTapDetector = GestureDetector(applicationContext, doubleTapListener)
+        singleTapDetector = GestureDetector(applicationContext, singleTapListener)
 
         modelViewer = ModelViewer(surfaceView)
         viewerContent.view = modelViewer.view
@@ -88,6 +93,7 @@ class MainActivity : Activity() {
         surfaceView.setOnTouchListener { _, event ->
             modelViewer.onTouchEvent(event)
             doubleTapDetector.onTouchEvent(event)
+            singleTapDetector.onTouchEvent(event)
             true
         }
 
@@ -229,6 +235,7 @@ class MainActivity : Activity() {
                 modelViewer.scene.skybox = sky
                 modelViewer.scene.indirectLight = ibl
                 viewerContent.indirectLight = ibl
+
             }
         }
     }
@@ -337,6 +344,11 @@ class MainActivity : Activity() {
         remoteServer?.close()
     }
 
+    override fun onBackPressed() {
+        super.onBackPressed()
+        finish()
+    }
+
     fun loadModelData(message: RemoteServer.ReceivedMessage) {
         Log.i(TAG, "Downloaded model ${message.label} (${message.buffer.capacity()} bytes)")
         clearStatusText()
@@ -381,6 +393,36 @@ class MainActivity : Activity() {
                     Log.i(TAG, "The Filament backend took $total ms to load the model geometry.")
                     modelViewer.engine.destroyFence(it)
                     loadStartFence = null
+
+                    val materials = mutableSetOf<Material>()
+                    val rcm = modelViewer.engine.renderableManager
+                    modelViewer.scene.forEach {
+                        val entity = it
+                        if (rcm.hasComponent(entity)) {
+                            val ri = rcm.getInstance(entity)
+                            val c = rcm.getPrimitiveCount(ri)
+                            for (i in 0 until c) {
+                                val mi = rcm.getMaterialInstanceAt(ri, i)
+                                val ma = mi.material
+                                materials.add(ma)
+                            }
+                        }
+                    }
+                    materials.forEach {
+                        it.compile(
+                            Material.CompilerPriorityQueue.HIGH,
+                            Material.UserVariantFilterBit.DIRECTIONAL_LIGHTING or
+                            Material.UserVariantFilterBit.DYNAMIC_LIGHTING or
+                            Material.UserVariantFilterBit.SHADOW_RECEIVER,
+                            null, null)
+                        it.compile(
+                            Material.CompilerPriorityQueue.LOW,
+                            Material.UserVariantFilterBit.FOG or
+                            Material.UserVariantFilterBit.SKINNING or
+                            Material.UserVariantFilterBit.SSR or
+                            Material.UserVariantFilterBit.VSM,
+                            null, null)
+                    }
                 }
             }
 
@@ -425,4 +467,19 @@ class MainActivity : Activity() {
             return super.onDoubleTap(e)
         }
     }
+
+    // Just for testing purposes
+    inner class SingleTapListener : GestureDetector.SimpleOnGestureListener() {
+        override fun onSingleTapUp(event: MotionEvent): Boolean {
+            modelViewer.view.pick(
+                event.x.toInt(),
+                surfaceView.height - event.y.toInt(),
+                surfaceView.handler, {
+                    val name = modelViewer.asset!!.getName(it.renderable)
+                    Log.v("Filament", "Picked ${it.renderable}: " + name)
+                },
+            )
+            return super.onSingleTapUp(event)
+        }
+    }
 }

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

@@ -20,6 +20,8 @@ import android.animation.ValueAnimator
 import android.app.Activity
 import android.opengl.Matrix
 import android.os.Bundle
+import android.os.Handler
+import android.os.Looper
 import android.view.Choreographer
 import android.view.Surface
 import android.view.SurfaceView
@@ -110,7 +112,7 @@ class MainActivity : Activity() {
     }
 
     private fun setupFilament() {
-        engine = Engine.create()
+        engine = Engine.Builder().featureLevel(Engine.FeatureLevel.FEATURE_LEVEL_0).build()
         renderer = engine.createRenderer()
         scene = engine.createScene()
         view = engine.createView()
@@ -120,13 +122,8 @@ class MainActivity : Activity() {
     private fun setupView() {
         scene.skybox = Skybox.Builder().color(0.035f, 0.035f, 0.035f, 1.0f).build(engine)
 
-        if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
-            // post-processing is not supported at feature level 0
-            view.isPostProcessingEnabled = false
-        } else {
-            // NOTE: Try to disable post-processing (tone-mapping, etc.) to see the difference
-            // view.isPostProcessingEnabled = false
-        }
+        // post-processing is not supported at feature level 0
+        view.isPostProcessingEnabled = false
 
         // Tell the view which camera we want to use
         view.camera = camera
@@ -160,12 +157,16 @@ class MainActivity : Activity() {
     }
 
     private fun loadMaterial() {
-        var name = "materials/baked_color.filamat"
-        if (engine.activeFeatureLevel == Engine.FeatureLevel.FEATURE_LEVEL_0) {
-            name = "materials/baked_color_es2.filamat"
-        }
-        readUncompressedAsset(name).let {
+        readUncompressedAsset("materials/baked_color.filamat").let {
             material = Material.Builder().payload(it, it.remaining()).build(engine)
+            material.compile(
+                Material.CompilerPriorityQueue.HIGH,
+                Material.UserVariantFilterBit.ALL,
+                Handler(Looper.getMainLooper())) {
+                        android.util.Log.i("hellotriangle",
+                            "Material " + material.name + " compiled.")
+            }
+            engine.flush()
         }
     }
 

android/samples/sample-hello-triangle/src/main/materials/baked_color.mat

@@ -17,7 +17,8 @@ material {
     ],
 
     // This material disables all lighting
-    shadingModel : unlit
+    shadingModel : unlit,
+    featureLevel : 0
 }
 
 fragment {

android/samples/sample-hello-triangle/src/main/materials/baked_color_es2.mat

@@ -1,33 +0,0 @@
-// Simple unlit material that uses the colors associated with each vertex.
-//
-// This source material must be compiled to a binary material using the matc tool.
-// The command used to compile this material is:
-// matc -p mobile -a opengl -o app/src/main/assets/baked_color.filamat app/src/materials/baked_color.mat
-//
-// See build.gradle for an example of how to compile materials automatically
-// Please refer to the documentation for more information about matc and the materials system.
-
-material {
-    name : baked_color,
-
-    // Lists the required vertex attributes
-    // Here we only need a color (RGBA)
-    requires : [
-        color
-    ],
-
-    // This material disables all lighting
-    shadingModel : unlit,
-    featureLevel : 0
-}
-
-fragment {
-    void material(inout MaterialInputs material) {
-        // You must always call the prepareMaterial() function
-        prepareMaterial(material);
-
-        // We set the material's color to the color interpolated from
-        // the model's vertices
-        material.baseColor = getColor();
-    }
-}

android/samples/sample-image-based-lighting/src/main/java/com/google/android/filament/ibl/MainActivity.kt

@@ -118,9 +118,10 @@ class MainActivity : Activity() {
     }
 
     private fun setupView() {
-        val ssaoOptions = view.ambientOcclusionOptions
-        ssaoOptions.enabled = true
-        view.ambientOcclusionOptions = ssaoOptions
+        // ambient occlusion is the cheapest effect that adds a lot of quality
+        view.ambientOcclusionOptions = view.ambientOcclusionOptions.apply {
+            enabled = true
+        }
 
         // NOTE: Try to disable post-processing (tone-mapping, etc.) to see the difference
         // view.isPostProcessingEnabled = false

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

@@ -32,13 +32,6 @@ android {
         targetSdkVersion versions.targetSdk
     }
 
-    // The filamat library has two variants: full and lite. Here we default to the "full" variant.
-    // Replace "full" with "lite" to use the filamat-lite variant, which has a smaller binary size
-    // but comes with certain restrictions. See "Filamat Lite" in libs/filamat/README.md.
-    defaultConfig {
-        missingDimensionStrategy 'functionality', 'full'
-    }
-
     // NOTE: This is a workaround required because the AGP task collectReleaseDependencies
     //       is not configuration-cache friendly yet; this is only useful for Play publication
     dependenciesInfo {

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

@@ -33,7 +33,6 @@ android {
         applicationId "com.google.android.filament.textured"
         minSdkVersion versions.minSdk
         targetSdkVersion versions.targetSdk
-        missingDimensionStrategy 'functionality', 'full'
     }
 
     // NOTE: This is a workaround required because the AGP task collectReleaseDependencies

android/samples/sample-textured-object/src/main/java/com/google/android/filament/textured/MainActivity.kt

@@ -231,7 +231,7 @@ class MainActivity : Activity() {
         animator.repeatCount = ValueAnimator.INFINITE
         animator.addUpdateListener { a ->
             val v = (a.animatedValue as Float)
-            camera.lookAt(cos(v) * 4.5, 1.5, sin(v) * 4.5, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0)
+            camera.lookAt(cos(v) * 5.5, 1.5, sin(v) * 5.5, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0)
         }
         animator.start()
     }
@@ -253,7 +253,7 @@ class MainActivity : Activity() {
 
         // Stop the animation and any pending frame
         choreographer.removeFrameCallback(frameScheduler)
-        animator.cancel();
+        animator.cancel()
 
         // Always detach the surface before destroying the engine
         uiHelper.detach()

android/samples/sample-transparent-view/src/main/java/com/google/android/filament/transparentrendering/MainActivity.kt

@@ -140,9 +140,9 @@ class MainActivity : Activity() {
         camera = engine.createCamera(engine.entityManager.create())
 
         // clear the swapchain with transparent pixels
-        val options = renderer.clearOptions
-        options.clear = true
-        renderer.clearOptions = options
+        renderer.clearOptions = renderer.clearOptions.apply {
+            clear = true
+        }
     }
 
     private fun setupView() {

book.toml

@@ -0,0 +1,13 @@
+[book]
+authors = ["Eliza Velasquez"]
+language = "en"
+multilingual = false
+src = "mdbook"
+title = "Filament"
+
+[build]
+build-dir = "docs"
+create-missing = false
+
+[output.html]
+mathjax-support = true

build.sh

@@ -90,8 +90,8 @@ function print_help {
     echo "    Desktop matc target, release build:"
     echo "        \$ ./$self_name release matc"
     echo ""
-    echo "    Build gltf_viewer then immediately run it with no arguments:"
-    echo "        \$ ./$self_name release run_gltf_viewer"
+    echo "    Build gltf_viewer:"
+    echo "        \$ ./$self_name release gltf_viewer"
     echo ""
  }
 
@@ -172,8 +172,6 @@ MATOPT_GRADLE_OPTION=""
 
 ASAN_UBSAN_OPTION=""
 
-FGDBG_OPTION="-DFILAMENT_ENABLE_FGDBG=OFF"
-
 IOS_BUILD_SIMULATOR=false
 BUILD_UNIVERSAL_LIBRARIES=false
 
@@ -193,6 +191,7 @@ function build_clean {
     rm -Rf android/filamat-android/build android/filamat-android/.externalNativeBuild android/filamat-android/.cxx
     rm -Rf android/gltfio-android/build android/gltfio-android/.externalNativeBuild android/gltfio-android/.cxx
     rm -Rf android/filament-utils-android/build android/filament-utils-android/.externalNativeBuild android/filament-utils-android/.cxx
+    rm -f compile_commands.json
 }
 
 function build_clean_aggressive {
@@ -212,13 +211,10 @@ function build_desktop_target {
     echo "Building ${lc_target} in out/cmake-${lc_target}..."
     mkdir -p "out/cmake-${lc_target}"
 
-    cd "out/cmake-${lc_target}"
+    pushd "out/cmake-${lc_target}" > /dev/null
 
-    # On macOS, set the deployment target to 10.15.
     local lc_name=$(echo "${UNAME}" | tr '[:upper:]' '[:lower:]')
     if [[ "${lc_name}" == "darwin" ]]; then
-        local deployment_target="-DCMAKE_OSX_DEPLOYMENT_TARGET=10.15"
-
         if [[ "${BUILD_UNIVERSAL_LIBRARIES}" == "true" ]]; then
             local architectures="-DCMAKE_OSX_ARCHITECTURES=arm64;x86_64"
         fi
@@ -235,10 +231,10 @@ function build_desktop_target {
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${ASAN_UBSAN_OPTION} \
-            ${FGDBG_OPTION} \
-            ${deployment_target} \
             ${architectures} \
             ../..
+        ln -sf "out/cmake-${lc_target}/compile_commands.json" \
+           ../../compile_commands.json
     fi
     ${BUILD_COMMAND} ${build_targets}
 
@@ -250,12 +246,13 @@ function build_desktop_target {
     if [[ -d "../${lc_target}/filament" ]]; then
         if [[ "${ISSUE_ARCHIVES}" == "true" ]]; then
             echo "Generating out/filament-${lc_target}-${LC_UNAME}.tgz..."
-            cd "../${lc_target}"
+            pushd "../${lc_target}" > /dev/null
             tar -czvf "../filament-${lc_target}-${LC_UNAME}.tgz" filament
+            popd > /dev/null
         fi
     fi
 
-    cd ../..
+    popd > /dev/null
 }
 
 function build_desktop {
@@ -273,7 +270,7 @@ function build_webgl_with_target {
 
     echo "Building WebGL ${lc_target}..."
     mkdir -p "out/cmake-webgl-${lc_target}"
-    cd "out/cmake-webgl-${lc_target}"
+    pushd "out/cmake-webgl-${lc_target}" > /dev/null
 
     if [[ ! "${BUILD_TARGETS}" ]]; then
         BUILD_TARGETS=${BUILD_CUSTOM_TARGETS}
@@ -293,6 +290,8 @@ function build_webgl_with_target {
             -DCMAKE_INSTALL_PREFIX="../webgl-${lc_target}/filament" \
             -DWEBGL=1 \
             ../..
+        ln -sf "out/cmake-webgl-${lc_target}/compile_commands.json" \
+           ../../compile_commands.json
         ${BUILD_COMMAND} ${BUILD_TARGETS}
         )
     fi
@@ -310,17 +309,17 @@ function build_webgl_with_target {
 
         if [[ "${ISSUE_ARCHIVES}" == "true" ]]; then
             echo "Generating out/filament-${lc_target}-web.tgz..."
-            cd web/filament-js
+            pushd web/filament-js > /dev/null
             tar -cvf "../../../filament-${lc_target}-web.tar" filament.js
             tar -rvf "../../../filament-${lc_target}-web.tar" filament.wasm
             tar -rvf "../../../filament-${lc_target}-web.tar" filament.d.ts
-            cd -
+            popd > /dev/null
             gzip -c "../filament-${lc_target}-web.tar" > "../filament-${lc_target}-web.tgz"
             rm "../filament-${lc_target}-web.tar"
         fi
     fi
 
-    cd ../..
+    popd > /dev/null
 }
 
 function build_webgl {
@@ -351,7 +350,7 @@ function build_android_target {
     echo "Building Android ${lc_target} (${arch})..."
     mkdir -p "out/cmake-android-${lc_target}-${arch}"
 
-    cd "out/cmake-android-${lc_target}-${arch}"
+    pushd "out/cmake-android-${lc_target}-${arch}" > /dev/null
 
     if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then
         cmake \
@@ -363,15 +362,16 @@ function build_android_target {
             -DCMAKE_TOOLCHAIN_FILE="../../build/toolchain-${arch}-linux-android.cmake" \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
-            ${FGDBG_OPTION} \
             ${VULKAN_ANDROID_OPTION} \
             ../..
+        ln -sf "out/cmake-android-${lc_target}-${arch}/compile_commands.json" \
+           ../../compile_commands.json
     fi
 
     # We must always install Android libraries to build the AAR
     ${BUILD_COMMAND} install
 
-    cd ../..
+    popd > /dev/null
 }
 
 function build_android_arch {
@@ -392,9 +392,9 @@ function archive_android {
     if [[ -d "out/android-${lc_target}/filament" ]]; then
         if [[ "${ISSUE_ARCHIVES}" == "true" ]]; then
             echo "Generating out/filament-android-${lc_target}-${LC_UNAME}.tgz..."
-            cd "out/android-${lc_target}"
+            pushd "out/android-${lc_target}" > /dev/null
             tar -czvf "../filament-android-${lc_target}-${LC_UNAME}.tgz" filament
-            cd ../..
+            popd > /dev/null
         fi
     fi
 }
@@ -472,7 +472,7 @@ function build_android {
         archive_android "Release"
     fi
 
-    cd android
+    pushd android > /dev/null
 
     if [[ "${ISSUE_DEBUG_BUILD}" == "true" ]]; then
         ./gradlew \
@@ -502,13 +502,13 @@ function build_android {
 
         if [[ "${INSTALL_COMMAND}" ]]; then
             echo "Installing out/filamat-android-debug.aar..."
-            cp filamat-android/build/outputs/aar/filamat-android-full-debug.aar ../out/filamat-android-debug.aar
+            cp filamat-android/build/outputs/aar/filamat-android-debug.aar ../out/filamat-android-debug.aar
 
             echo "Installing out/filament-android-debug.aar..."
             cp filament-android/build/outputs/aar/filament-android-debug.aar ../out/
 
             echo "Installing out/gltfio-android-debug.aar..."
-            cp gltfio-android/build/outputs/aar/gltfio-android-full-debug.aar ../out/gltfio-android-debug.aar
+            cp gltfio-android/build/outputs/aar/gltfio-android-debug.aar ../out/gltfio-android-debug.aar
 
             echo "Installing out/filament-utils-android-debug.aar..."
             cp filament-utils-android/build/outputs/aar/filament-utils-android-debug.aar ../out/filament-utils-android-debug.aar
@@ -551,14 +551,13 @@ function build_android {
 
         if [[ "${INSTALL_COMMAND}" ]]; then
             echo "Installing out/filamat-android-release.aar..."
-            cp filamat-android/build/outputs/aar/filamat-android-lite-release.aar ../out/
-            cp filamat-android/build/outputs/aar/filamat-android-full-release.aar ../out/filamat-android-release.aar
+            cp filamat-android/build/outputs/aar/filamat-android-release.aar ../out/filamat-android-release.aar
 
             echo "Installing out/filament-android-release.aar..."
             cp filament-android/build/outputs/aar/filament-android-release.aar ../out/
 
             echo "Installing out/gltfio-android-release.aar..."
-            cp gltfio-android/build/outputs/aar/gltfio-android-full-release.aar ../out/gltfio-android-release.aar
+            cp gltfio-android/build/outputs/aar/gltfio-android-release.aar ../out/gltfio-android-release.aar
 
             echo "Installing out/filament-utils-android-release.aar..."
             cp filament-utils-android/build/outputs/aar/filament-utils-android-release.aar ../out/filament-utils-android-release.aar
@@ -573,7 +572,7 @@ function build_android {
         fi
     fi
 
-    cd ..
+    popd > /dev/null
 }
 
 function build_ios_target {
@@ -584,7 +583,7 @@ function build_ios_target {
     echo "Building iOS ${lc_target} (${arch}) for ${platform}..."
     mkdir -p "out/cmake-ios-${lc_target}-${arch}"
 
-    cd "out/cmake-ios-${lc_target}-${arch}"
+    pushd "out/cmake-ios-${lc_target}-${arch}" > /dev/null
 
     if [[ ! -d "CMakeFiles" ]] || [[ "${ISSUE_CMAKE_ALWAYS}" == "true" ]]; then
         cmake \
@@ -598,8 +597,9 @@ function build_ios_target {
             -DCMAKE_TOOLCHAIN_FILE=../../third_party/clang/iOS.cmake \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
-            ${FGDBG_OPTION} \
             ../..
+        ln -sf "out/cmake-ios-${lc_target}-${arch}/compile_commands.json" \
+           ../../compile_commands.json
     fi
 
     ${BUILD_COMMAND}
@@ -609,7 +609,7 @@ function build_ios_target {
         ${BUILD_COMMAND} ${INSTALL_COMMAND}
     fi
 
-    cd ../..
+    popd > /dev/null
 }
 
 function archive_ios {
@@ -618,9 +618,9 @@ function archive_ios {
     if [[ -d "out/ios-${lc_target}/filament" ]]; then
         if [[ "${ISSUE_ARCHIVES}" == "true" ]]; then
             echo "Generating out/filament-${lc_target}-ios.tgz..."
-            cd "out/ios-${lc_target}"
+            pushd "out/ios-${lc_target}" > /dev/null
             tar -czvf "../filament-${lc_target}-ios.tgz" filament
-            cd ../..
+            popd > /dev/null
         fi
     fi
 }
@@ -679,14 +679,14 @@ function build_web_docs {
 
     mkdir -p out/web-docs
     cp -f docs/web-docs-package.json out/web-docs/package.json
-    cd out/web-docs
+    pushd out/web-docs > /dev/null
 
     npm install > /dev/null
 
     # Generate documents
     npx markdeep-rasterizer ../../docs/Filament.md.html ../../docs/Materials.md.html  ../../docs/
 
-    cd ../..
+    popd > /dev/null
 }
 
 function validate_build_command {
@@ -759,6 +759,19 @@ function run_tests {
     fi
 }
 
+function check_debug_release_build {
+    if [[ "${ISSUE_DEBUG_BUILD}" == "true" || \
+          "${ISSUE_RELEASE_BUILD}" == "true" || \
+          "${ISSUE_CLEAN}" == "true" || \
+          "${ISSUE_WEB_DOCS}" == "true" ]]; then
+        "$@";
+    else
+        echo "You must declare a debug or release target for $@ builds."
+        echo ""
+        exit 1
+    fi
+}
+
 # Beginning of the script
 
 pushd "$(dirname "$0")" > /dev/null
@@ -767,7 +780,7 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
     case ${opt} in
         h)
             print_help
-            exit 1
+            exit 0
             ;;
         a)
             ISSUE_ARCHIVES=true
@@ -783,7 +796,6 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
             PRINT_MATDBG_HELP=true
             MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_BUILD_FILAMAT=ON"
             MATDBG_GRADLE_OPTION="-Pcom.google.android.filament.matdbg"
-            FGDBG_OPTION="-DFILAMENT_ENABLE_FGDBG=ON"
             ;;
         f)
             ISSUE_CMAKE_ALWAYS=true
@@ -804,7 +816,7 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
             platforms=$(echo "${OPTARG}" | tr ',' '\n')
             for platform in ${platforms}
             do
-                case ${platform} in
+                case $(echo "${platform}" | tr '[:upper:]' '[:lower:]') in
                     desktop)
                         ISSUE_DESKTOP_BUILD=true
                     ;;
@@ -823,6 +835,12 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
                         ISSUE_DESKTOP_BUILD=true
                         ISSUE_WEBGL_BUILD=false
                     ;;
+                    *)
+                        echo "Unknown platform ${platform}"
+                        echo "Platform must be one of [desktop|android|ios|webgl|all]"
+                        echo ""
+                        exit 1
+                    ;;    
                 esac
             done
             ;;
@@ -835,7 +853,7 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
             abis=$(echo "${OPTARG}" | tr ',' '\n')
             for abi in ${abis}
             do
-                case ${abi} in
+                case $(echo "${abi}" | tr '[:upper:]' '[:lower:]') in
                     armeabi-v7a)
                         ABI_ARMEABI_V7A=true
                     ;;
@@ -854,6 +872,12 @@ while getopts ":hacCfgijmp:q:uvslwtedk:b" opt; do
                         ABI_X86=true
                         ABI_X86_64=true
                     ;;
+                    *)
+                        echo "Unknown abi ${abi}"
+                        echo "ABI must be one of [armeabi-v7a|arm64-v8a|x86|x86_64|all]"
+                        echo ""
+                        exit 1
+                    ;;
                 esac
             done
             ;;
@@ -917,9 +941,9 @@ fi
 shift $((OPTIND - 1))
 
 for arg; do
-    if [[ "${arg}" == "release" ]]; then
+    if [[ $(echo "${arg}" | tr '[:upper:]' '[:lower:]') == "release" ]]; then
         ISSUE_RELEASE_BUILD=true
-    elif [[ "${arg}" == "debug" ]]; then
+    elif [[ $(echo "${arg}" | tr '[:upper:]' '[:lower:]') == "debug" ]]; then
         ISSUE_DEBUG_BUILD=true
     else
         BUILD_CUSTOM_TARGETS="${BUILD_CUSTOM_TARGETS} ${arg}"
@@ -937,19 +961,19 @@ if [[ "${ISSUE_CLEAN_AGGRESSIVE}" == "true" ]]; then
 fi
 
 if [[ "${ISSUE_DESKTOP_BUILD}" == "true" ]]; then
-    build_desktop
+    check_debug_release_build build_desktop
 fi
 
 if [[ "${ISSUE_ANDROID_BUILD}" == "true" ]]; then
-    build_android
+    check_debug_release_build build_android
 fi
 
 if [[ "${ISSUE_IOS_BUILD}" == "true" ]]; then
-    build_ios
+    check_debug_release_build build_ios
 fi
 
 if [[ "${ISSUE_WEBGL_BUILD}" == "true" ]]; then
-    build_webgl
+    check_debug_release_build build_webgl
 fi
 
 if [[ "${ISSUE_WEB_DOCS}" == "true" ]]; then

build/common/bump-version.sh

@@ -2,6 +2,11 @@
 
 set -e
 
+case "$(uname -s)" in
+    Darwin*) IS_DARWIN=1;;
+    *) ;;
+esac
+
 function print_help {
     local SELF_NAME
     SELF_NAME=$(basename "$0")
@@ -45,7 +50,11 @@ function replace {
     FIND_STR="${1//\{\{VERSION\}\}/${VERSION_REGEX}}"
     REPLACE_STR="${1//\{\{VERSION\}\}/${NEW_VERSION}}"
     local FILE_NAME="$2"
-    sed -i '' -E "s/${FIND_STR}/${REPLACE_STR}/" "${FILE_NAME}"
+    if [ IS_DARWIN == 1 ]; then
+        sed -i '' -E "s/${FIND_STR}/${REPLACE_STR}/" "${FILE_NAME}"
+    else
+        sed -i -E "s/${FIND_STR}/${REPLACE_STR}/" "${FILE_NAME}"
+    fi
 }
 
 # The following are the canonical locations where the Filament version number is referenced.

build/common/test_list.txt

@@ -5,7 +5,6 @@ libs/math/test_math
 libs/image/test_image compare libs/image/tests/reference/
 libs/utils/test_utils
 libs/filamat/test_filamat
-libs/filamat/test_filamat_lite
 tools/matc/test_matc
 tools/cmgen/test_cmgen compare
 tools/glslminifier/test_glslminifier

docs/.nojekyll

@@ -0,0 +1 @@
+This file makes sure that Github Pages doesn't process mdBook's output.

docs/404.html

@@ -1,73 +1,234 @@
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us" lang="en-us">
-<head>
-  <link href="//gmpg.org/xfn/11" rel="profile">
-  <link href="https://google.github.io/filament/favicon.png" rel="icon" type="image/x-icon" />
-  <meta http-equiv="content-type" content="text/html; charset=utf-8">
-  <meta name="generator" content="Hugo 0.72.0" />
-
-  
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-
-  <title>404 Page not found &middot; Filament</title>
-
-  
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/print.css" media="print">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/poole.css">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/syntax.css">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/hyde.css">
-  <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700|Tangerine:700|Inconsolata" rel="stylesheet">
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Page not found - Filament</title>
+        <base href="/">
 
 
-  
-  <link rel="apple-touch-icon-precomposed" sizes="144x144" href="/apple-touch-icon-144-precomposed.png">
-  <link rel="shortcut icon" href="/favicon.png">
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
 
-  
-  <link href="" rel="alternate" type="application/rss+xml" title="Filament" />
+        <link rel="icon" href="favicon.svg">
+        <link rel="shortcut icon" href="favicon.png">
+        <link rel="stylesheet" href="css/variables.css">
+        <link rel="stylesheet" href="css/general.css">
+        <link rel="stylesheet" href="css/chrome.css">
+        <link rel="stylesheet" href="css/print.css" media="print">
 
-  
-</head>
+        <!-- Fonts -->
+        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="fonts/fonts.css">
 
-  <body class="theme-base-0d ">
-  <aside class="sidebar">
-    <div class="container sidebar-sticky">
-        <div class="sidebar-about">
-            <a href="https://google.github.io/filament/">
-                
-                <div style="width:100%; height:150px">
-                <img src="https://google.github.io/filament/images/filament_logo_small.png" class="lightbulb" />
-                </div>
-                
-            </a>
-            <p class="lead">
-                
-            </p>
-        </div>
-        <nav>
-            <ul class="sidebar-nav">
-                <li>
-                    <a href="https://github.com/google/filament"> GitHub Project </a>
-                    
-                </li><li>
-                    <a href="/filament/documentation/"> Core Documentation </a>
-                    
-                </li><li>
-                    <a href="/filament/ios/"> iOS Tutorials </a>
-                    
-                </li><li>
-                    <a href="/filament/webgl/"> Web Docs / Demos </a>
-                    
-                </li>
-            </ul>
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="highlight.css">
+        <link rel="stylesheet" href="tomorrow-night.css">
+        <link rel="stylesheet" href="ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded "><a href="core.html"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
         </nav>
-    </div>
-</aside>
 
-    <main class="content container">
-    <h1>404: Page not found</h1>
-<p class="lead">Sorry, we've misplaced that URL or it's pointing to something that doesn't exist. <a href="https://google.github.io/filament/">Head back home</a> to try finding it again.</p>
-    </main>
-    
-  </body>
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="document-not-found-404"><a class="header" href="#document-not-found-404">Document not found (404)</a></h1>
+<p>This URL is invalid, sorry. Please use the navigation bar or search to continue.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+
+            </nav>
+
+        </div>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr.min.js"></script>
+        <script src="mark.min.js"></script>
+        <script src="searcher.js"></script>
+
+        <script src="clipboard.min.js"></script>
+        <script src="highlight.js"></script>
+        <script src="book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
 </html>

docs/Materials.md.html

@@ -1139,7 +1139,8 @@ Type
 :    array of `string`
 
 Value
-:     Each entry must be any of `dynamicLighting`, `directionalLighting`, `shadowReceiver`,`skinning` or `ssr`.
+:     Each entry must be any of `dynamicLighting`, `directionalLighting`, `shadowReceiver`,
+      `skinning`, `ssr`, or `stereo`.
 
 Description
 :     Used to specify a list of shader variants that the application guarantees will never be
@@ -1158,6 +1159,7 @@ Description of the variants:
 - `fog`, used when global fog is applied to the scene
 - `vsm`, used when VSM shadows are enabled and the object is a shadow receiver
 - `ssr`, used when screen-space reflections are enabled in the View
+- `stereo`, used when stereoscopic rendering is enabled in the View
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ JSON
 material {
@@ -2593,4 +2595,26 @@ pre-multiplied ahead of time. On Android, any texture uploaded from a
 [Bitmap](https://developer.android.com/reference/android/graphics/Bitmap.html) will be
 pre-multiplied by default.
 
+# Sampler usage in Materials
+
+The number of usable sampler parameters (e.g.: type is `sampler2d`) in materials is limited and
+depends on the material properties, shading model, feature level and variant filter.
+
+## Feature level 1 and 2
+
+`unlit` materials can use up to 12 samplers by default.
+
+`lit` materials can use up to 9 samplers by default, however if `refractionMode` or `reflectionMode`
+is set to `screenspace` that number is reduced to 8.
+
+Finally if `variantFilter` contains the `fog` filter, an extra sampler is made available, such that
+`unlit` materials can use up to 13 and `lit` materials up to 10 samplers by default.
+
+## Feature level 3
+
+16 samplers are available.
+
+!!! TIP: external samplers
+               Be aware that `external` samplers account for 2 regular samplers.
+
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="../third_party/markdeep/markdeep.min.js"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

docs/Vulkan.md.html

@@ -0,0 +1,279 @@
+<meta charset="utf-8">
+<link href="https://fonts.googleapis.com/css?family=Montserrat" rel="stylesheet">
+<style>
+    img { max-width: 100px !important }
+    .md, body, .md h1, .md div.title, .md a  {
+        font-family: "Montserrat", sans-serif;
+        color: #555;
+    }
+    .md div.title { color: #a55 }
+    .md a  { color: #55a }
+</style>
+
+**Vulkan Backend**
+          *Last updated: 26 October 2022*
+
+![](./images/filament_logo.png)
+
+-----
+
+This document is a high-level "state of the union" for Filament's Vulkan backend. Some of the
+details may be out of date by the time you read it, but we hope to keep it reasonably well
+maintained, which is why it lives as a markdown document in our source tree.
+
+# Architecture
+
+At a high level, the Vulkan backend is composed of the **driver**, a set of **helpers**, and
+a set of **handle types**.
+
+The driver is responsible for implementing all `DriverAPI` entry points, as well as managing a
+single `VkDevice` and `VkInstance`.
+
+************************************************************************************************
+*                                                                                              *
+*   .---------------------------------------.                                                  *
+*  |            Client Application           |                                                 *
+*   '------------------+--------------------'                                                  *
+*                      |                                                                       *
+*                      v                                                                       *
+*   .----------------------------------------.     .--------------------------------------.    *
+*  |        Filament Rendering Engine         |   |          filament::SwapChain           |   *
+*   '------------------+---------------------'     '------------------+-------------------'    *
+*                      |                                              |                        *
+*                      v                                              v                        *
+*   .----------------------------------------.     .---------------------------------------.   *
+*  |                                          |   |                                         |  *
+*  |       VulkanDriver : DriverBase          |   |     VulkanSwapChain : HwSwapChain       |  *
+*  |                                          |   |                                         |  *
+*  |------------------------------------------|   |-----------------------------------------|  *
+*  |                                          |   |                                         |  *
+*  |    Helpers            VulkanContext      |   |    VulkanTexture    VulkanTexture       |  *
+*  |  .--------------.    .---------------.   |   |   .----------------+----------------.   |  *
+*  |  | PipelineCache|   | VkDevice        |  |   |  | VkImage         | VkImage         |  |  *
+*  |  +--------------+   | VkInstance      |  |   |  | VkImageView     | VkImageView     |  |  *
+*  |  | Disposer     |   | VulkanCommands  |  |   |  |                 |                 |  |  *
+*  |  +--------------+    '---------------'   |   |   '----------------+----------------'   |  *
+*  |  | FboCache     |                        |   |                                         |  *
+*  |  +--------------+                        |   |                                         |  *
+*  |  | SamplerCache |                        |   |                                         |  *
+*  |  +--------------+                        |   |                                         |  *
+*  |  | StagePool    |                        |    '---------------------------------------'   *
+*  |  '--------------'                        |                                                *
+*  |                                          |                                                *
+*  |                                          |                                                *
+*  |                                          |                                                *
+*   '----------------------------------------'                                                 *
+*                                                                                              *
+************************************************************************************************
+
+# Overview
+
+## VulkanDriver and VulkanContext
+
+The `VulkanDriver` class is the bridge between the backend and the Filament engine, and is kept as
+minimal as possible. Most of the actual logic is contained in methods in `VulkanContext` and in the
+handle types rather than directly in `VulkanDriver`.
+
+In a self-imposed design constraint, we have decided that every method in `VulkanDriver` must be an
+override; it should have no private methods other than the handle allocators. This reins in
+complexity because it must implement every method in `DriverAPI` while dealing with Vulkan itself,
+which has an extremely low-level API.
+
+## Command buffers
+
+The `VulkanCommands` class creates command buffers on the fly and maintains a chain of semaphores
+to ensure that submitted command buffers are executed serially.
+
+## Handle types
+
+This sole purpose of `VulkanHandles.h` is to declare structs that descend from the hardware handles
+that are defined in `DriverBase.h`.
+
+Most of the handle types do not contain much logic, but they often do more than mere wrapping of
+Vk objects. Notably, `VulkanRenderTarget` does not have a straightforward mapping to any one Vk
+object. See its class comment for details. Also, `VulkanTexture` and `VulkanSwapChain` have their
+own cpps file because of complexity around layouts and subresources.
+
+VulkanProgram
+: Descends from `HwProgram`, owns a pair of `VkShaderModule`.
+
+VulkanRenderTarget
+: Descends from `HwRenderTarget`, contains references to `VulkanTexture` objects.
+
+VulkanSwapChain
+: Descends from `HwSwapChain`, has a reference to `VkSurfaceKHR` and `VkSwapchainKHR`.
+
+VulkanVertexBuffer
+: Descends from `HwVertexBuffer`, owns a set of `VkBuffer`.
+
+VulkanIndexBuffer
+: Descends from `HwIndexBuffer`, owns a `VkBuffer`.
+
+VulkanSamplerGroup
+: Descends from `HwSamplerGroup`, does not own Vk objects.
+
+VulkanTexture
+: Descends from `HwTexture`, owns a `VkImage` and a set of `VkImageLayout`.
+
+VulkanRenderPrimitive
+: Descends from `HwRenderPrimitive`, does not own Vk objects.
+
+One special case is `VulkanBuffer`, which is not a handle class. It encapulates functionality shared
+between `VulkanIndexBuffer` and `VulkanVertexBuffer`.
+
+## Helpers
+
+`VulkanDriver` owns one instance of each helper. They are not part of a class hierarchy but
+they do follow a common set of conventions. For example, most of them implement a `gc()` method
+that is called once per frame to free unused objects.
+
+VulkanPipelineCache
+: Cache of VkDescriptorSet, VkPipeline, and VkPipelineLayout.
+
+VulkanDisposer
+: Holds reference counts to Vulkan objects in order to defer their destruction.
+
+VulkanFboCache
+: Cache of VkRenderPass and VkFramebuffer. Contains weak references to VkImage handles, but does not
+  own any pixel data. The cache key for render passes is quite complex because it needs to include
+  image layout information in a compact way. For details see the comments in the `RenderPassKey`
+  declaration.
+
+VulkanStagePool
+: Pool of VkBuffer objects that can be memory mapped (shared between host and device).
+
+VulkanSamplerCache
+: This is our simplest cache object because Vulkan samplers are fairly lightweight and re-usable.
+
+## Folder layout and namespacing
+
+With the exception of BlueVK, all Vulkan-specific code lives in `backend/src/vulkan`, which has
+no subfolders. All backend-specific types and functions live directly in the `filament::backend`
+namespace, and we simply prefix our names with "Vulkan" when necessary to avoid ambiguation with
+OpenGL.
+
+# Image Layout Strategy
+
+Adhering to a coherent strategy for image layout transitions is crucial. Without this, validation
+errors (and actual black screens with some GPU vendors) occur far too easily and can feel like
+whack-a-mole.
+
+Vulkan provides several mechanisms for transitioning layout (render passes, barriers) so the
+strategy outlined below specifies which mechanism should be used in various scenarios.
+
+The current image layouts are tracked at the subresource level in `VulkanTexture` using a
+specialized STL-ish container that we designed for this purpose:
+[RangeMap](https://github.com/google/filament/blob/main/libs/utils/include/utils/RangeMap.h).
+
+In the past we tried to avoid tracking since it theoritically duplicates state that exists in the
+GPU vendor's driver. However in practice this was impossible to manage, because complex logic was
+required to deduce the current layout. Also, tracking lets us use `assert_invariant` in many places
+to ensure that the behavior described in this document is implemented properly.  It is much easier
+to catch errors with asserts than with validation.
+
+As of this writing, the current rules are:
+
+(1) **Read-Only Color Textures**
+
+These should be created in an UNDEFINED state and stay that way until data gets uploaded into them,
+at which point the appropriate subresources are transitioned to TRANSFER_DST_OPTIMAL for the upload,
+then to SHADER_READ_ONLY_OPTIMAL, both times using a barrier.  Note that a subresource might be
+updated several times; each time it undergoes these two transitions.
+
+If a shader samples from a texture whose mipmaps are only partially loaded, we might see validation
+warnings about how some subresources are in an UNDEFINED layout.  However if we are properly using
+the `setMinMaxLevels` driver API, then the Vulkan backend will not bind those particular
+subresources, so validation should not complain.
+
+(2) **Writeable Color Textures**
+
+During construction of the HwTexture, these are transitioned to GENERAL using a barrier.
+
+GENERAL layout is not recommended by AMD best practices but in our case we wish to avoid thrashing
+the layout between COLOR_ATTACHMENT_OPTIMAL and SHADER_READ_ONLY_OPTIMAL for post-processing
+effects.  Moreover we do not have a priori knowledge about blitting and read pixels usage.
+
+(3) **Depth Textures**
+
+During construction of the HwTexture, these are transitioned to GENERAL using a barrier.
+
+Note that some post-processing passes (e.g. SSAO) sample from the depth buffer while also enabling
+depth testing. Using GENERAL makes this legal.
+
+(4) **Swap Chain Textures**
+
+During construction, these are transitioned to GENERAL using a barrier. They are then transitioned
+to PRESENT at the end of the frame using a barrier, and transitioned back to GENERAL using the first
+render pass of the frame.
+
+Note that we transition to PRESENT using a barrier, but with some GPU vendors it might be preferable
+to transition them using the last render pass. However we have no way of knowing ahead of time which
+pass is last.
+
+Note that Filament allows swap chains to be used as blit targets and blit sources (e.g. for
+ReadPixels). Using GENERAL makes this easier to manage.
+
+(5) **Headless Swap Chain Textures**
+
+These follow the same rules as writeable color texture and depth textures.
+
+# VulkanPipelineCache
+
+Uniforms, samplers, and shaders are not directly bindable in Vulkan; instead they are bound through
+indirection layers called *pipelines* and *descriptor sets*. The `VulkanPipelineCache` class allows
+the driver to call methods that are conceptually simple like `bindUniformBuffer`, even though no
+such function exists in the low-level Vulkan API.
+
+Although it is actually just another cache manager, `VulkanPipelineCache` has a fairly rich set of
+public methods. See its header file for details.
+
+The pipeline cache also manages the *layout objects*, which constrain the number of uniform buffers
+and samplers that can be bound simultaneously (see `VkDescriptorSetLayout` and `VkPipelineLayout`).
+
+# Memory Allocation
+
+Some architectures (e.g. Adreno) only allow a small number of `VkDeviceMemory` objects to exist at
+once, so we consolidate these using a simple third-party library
+([vk_mem_alloc](https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator)). This library is
+used each time the backend needs to create a `VkBuffer` or `VkImage`. See `VulkanStagePool` for a
+usage example.
+
+# BlueVK
+
+BlueVK loads in functions for all Vulkan entry points and supported extensions. On Android, this
+is not absolutely necessary since core functionality is available through static linking. However,
+we found that in practice it is simpler to use BlueVK across all platforms because of its ability
+to load extensions.
+
+The BlueVK C++ source is generated from a Python script that consumes `vk.xml`. This XML file is an
+API specification maintained by Khronos on GitHub.
+
+None of the source files in the  Vulkan backend include `vulkan.h` directly,  instead they include
+the BlueVK header, which in turn includes the Vulkan headers.
+
+!!! Note
+    Each time we update BlueVK by feeding it the latest `vk.xml`, we should also update the
+    Vulkan headers that are checked in to `libs/bluevk/include/vulkan`. If BlueVK and the Vulkan
+    headers are not updated concurrently, this will cause build errors.
+
+# Top Issues
+
+Here we list some of the most significant issues and to-be-done items for the Vulkan backend.
+
+- Improve the UBO strategy
+    - Currently we use staging buffers and perform lots of copies (host-to-host, then host-to-device)
+    - Consider an approach similar to MetalDriver, which effectively implements double-buffering
+      using a pool of shared mem buffers
+- Consider using subpasses for the depth prepass
+- We lazily create pipeline objects
+        1. This is notoriously slow in Vulkan
+        2. We do lots of state hashing for this
+        3. Vulkan has special pipeline cache objects that we aren't using yet, but...
+        4. It might be better to enhance our driver API to allow a priori construction
+- We need more automated testing
+- We don't *quite* have feature parity with the OpenGL backend
+    - No support for streaming camera texture yet
+        - This is possible, even in Android O, just haven't gotten around to it yet
+
+<script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
+<script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

docs/api.html

@@ -0,0 +1,250 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>API Reference - Filament</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="favicon.svg">
+        <link rel="shortcut icon" href="favicon.png">
+        <link rel="stylesheet" href="css/variables.css">
+        <link rel="stylesheet" href="css/general.css">
+        <link rel="stylesheet" href="css/chrome.css">
+        <link rel="stylesheet" href="css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="highlight.css">
+        <link rel="stylesheet" href="tomorrow-night.css">
+        <link rel="stylesheet" href="ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded "><a href="core.html"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html" class="active"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="api-reference"><a class="header" href="#api-reference">API Reference</a></h1>
+<p>Refer to the following for a complete reference to the Filament API.</p>
+<ul>
+<li><a href="TODO">C++</a></li>
+<li><a href="TODO">Java</a></li>
+<li><a href="TODO">JavaScript</a></li>
+</ul>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="core-materials.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="ios.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="core-materials.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="ios.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr.min.js"></script>
+        <script src="mark.min.js"></script>
+        <script src="searcher.js"></script>
+
+        <script src="clipboard.min.js"></script>
+        <script src="highlight.js"></script>
+        <script src="book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
+</html>

docs/ayu-highlight.css

@@ -0,0 +1,78 @@
+/*
+Based off of the Ayu theme
+Original by Dempfi (https://github.com/dempfi/ayu)
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  background: #191f26;
+  color: #e6e1cf;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: #5c6773;
+  font-style: italic;
+}
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-attr,
+.hljs-regexp,
+.hljs-link,
+.hljs-selector-id,
+.hljs-selector-class {
+  color: #ff7733;
+}
+
+.hljs-number,
+.hljs-meta,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+  color: #ffee99;
+}
+
+.hljs-string,
+.hljs-bullet {
+  color: #b8cc52;
+}
+
+.hljs-title,
+.hljs-built_in,
+.hljs-section {
+  color: #ffb454;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-symbol {
+  color: #ff7733;
+}
+
+.hljs-name {
+    color: #36a3d9;
+}
+
+.hljs-tag {
+    color: #00568d;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}
+
+.hljs-addition {
+  color: #91b362;
+}
+
+.hljs-deletion {
+  color: #d96c75;
+}

docs/book.js

@@ -0,0 +1,697 @@
+"use strict";
+
+// Fix back button cache problem
+window.onunload = function () { };
+
+// Global variable, shared between modules
+function playground_text(playground, hidden = true) {
+    let code_block = playground.querySelector("code");
+
+    if (window.ace && code_block.classList.contains("editable")) {
+        let editor = window.ace.edit(code_block);
+        return editor.getValue();
+    } else if (hidden) {
+        return code_block.textContent;
+    } else {
+        return code_block.innerText;
+    }
+}
+
+(function codeSnippets() {
+    function fetch_with_timeout(url, options, timeout = 6000) {
+        return Promise.race([
+            fetch(url, options),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
+        ]);
+    }
+
+    var playgrounds = Array.from(document.querySelectorAll(".playground"));
+    if (playgrounds.length > 0) {
+        fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
+            headers: {
+                'Content-Type': "application/json",
+            },
+            method: 'POST',
+            mode: 'cors',
+        })
+        .then(response => response.json())
+        .then(response => {
+            // get list of crates available in the rust playground
+            let playground_crates = response.crates.map(item => item["id"]);
+            playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
+        });
+    }
+
+    function handle_crate_list_update(playground_block, playground_crates) {
+        // update the play buttons after receiving the response
+        update_play_button(playground_block, playground_crates);
+
+        // and install on change listener to dynamically update ACE editors
+        if (window.ace) {
+            let code_block = playground_block.querySelector("code");
+            if (code_block.classList.contains("editable")) {
+                let editor = window.ace.edit(code_block);
+                editor.addEventListener("change", function (e) {
+                    update_play_button(playground_block, playground_crates);
+                });
+                // add Ctrl-Enter command to execute rust code
+                editor.commands.addCommand({
+                    name: "run",
+                    bindKey: {
+                        win: "Ctrl-Enter",
+                        mac: "Ctrl-Enter"
+                    },
+                    exec: _editor => run_rust_code(playground_block)
+                });
+            }
+        }
+    }
+
+    // updates the visibility of play button based on `no_run` class and
+    // used crates vs ones available on https://play.rust-lang.org
+    function update_play_button(pre_block, playground_crates) {
+        var play_button = pre_block.querySelector(".play-button");
+
+        // skip if code is `no_run`
+        if (pre_block.querySelector('code').classList.contains("no_run")) {
+            play_button.classList.add("hidden");
+            return;
+        }
+
+        // get list of `extern crate`'s from snippet
+        var txt = playground_text(pre_block);
+        var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
+        var snippet_crates = [];
+        var item;
+        while (item = re.exec(txt)) {
+            snippet_crates.push(item[1]);
+        }
+
+        // check if all used crates are available on play.rust-lang.org
+        var all_available = snippet_crates.every(function (elem) {
+            return playground_crates.indexOf(elem) > -1;
+        });
+
+        if (all_available) {
+            play_button.classList.remove("hidden");
+        } else {
+            play_button.classList.add("hidden");
+        }
+    }
+
+    function run_rust_code(code_block) {
+        var result_block = code_block.querySelector(".result");
+        if (!result_block) {
+            result_block = document.createElement('code');
+            result_block.className = 'result hljs language-bash';
+
+            code_block.append(result_block);
+        }
+
+        let text = playground_text(code_block);
+        let classes = code_block.querySelector('code').classList;
+        let edition = "2015";
+        if(classes.contains("edition2018")) {
+            edition = "2018";
+        } else if(classes.contains("edition2021")) {
+            edition = "2021";
+        }
+        var params = {
+            version: "stable",
+            optimize: "0",
+            code: text,
+            edition: edition
+        };
+
+        if (text.indexOf("#![feature") !== -1) {
+            params.version = "nightly";
+        }
+
+        result_block.innerText = "Running...";
+
+        fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
+            headers: {
+                'Content-Type': "application/json",
+            },
+            method: 'POST',
+            mode: 'cors',
+            body: JSON.stringify(params)
+        })
+        .then(response => response.json())
+        .then(response => {
+            if (response.result.trim() === '') {
+                result_block.innerText = "No output";
+                result_block.classList.add("result-no-output");
+            } else {
+                result_block.innerText = response.result;
+                result_block.classList.remove("result-no-output");
+            }
+        })
+        .catch(error => result_block.innerText = "Playground Communication: " + error.message);
+    }
+
+    // Syntax highlighting Configuration
+    hljs.configure({
+        tabReplace: '    ', // 4 spaces
+        languages: [],      // Languages used for auto-detection
+    });
+
+    let code_nodes = Array
+        .from(document.querySelectorAll('code'))
+        // Don't highlight `inline code` blocks in headers.
+        .filter(function (node) {return !node.parentElement.classList.contains("header"); });
+
+    if (window.ace) {
+        // language-rust class needs to be removed for editable
+        // blocks or highlightjs will capture events
+        code_nodes
+            .filter(function (node) {return node.classList.contains("editable"); })
+            .forEach(function (block) { block.classList.remove('language-rust'); });
+
+        code_nodes
+            .filter(function (node) {return !node.classList.contains("editable"); })
+            .forEach(function (block) { hljs.highlightBlock(block); });
+    } else {
+        code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
+    }
+
+    // Adding the hljs class gives code blocks the color css
+    // even if highlighting doesn't apply
+    code_nodes.forEach(function (block) { block.classList.add('hljs'); });
+
+    Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) {
+
+        var lines = Array.from(block.querySelectorAll('.boring'));
+        // If no lines were hidden, return
+        if (!lines.length) { return; }
+        block.classList.add("hide-boring");
+
+        var buttons = document.createElement('div');
+        buttons.className = 'buttons';
+        buttons.innerHTML = "<button class=\"fa fa-eye\" title=\"Show hidden lines\" aria-label=\"Show hidden lines\"></button>";
+
+        // add expand button
+        var pre_block = block.parentNode;
+        pre_block.insertBefore(buttons, pre_block.firstChild);
+
+        pre_block.querySelector('.buttons').addEventListener('click', function (e) {
+            if (e.target.classList.contains('fa-eye')) {
+                e.target.classList.remove('fa-eye');
+                e.target.classList.add('fa-eye-slash');
+                e.target.title = 'Hide lines';
+                e.target.setAttribute('aria-label', e.target.title);
+
+                block.classList.remove('hide-boring');
+            } else if (e.target.classList.contains('fa-eye-slash')) {
+                e.target.classList.remove('fa-eye-slash');
+                e.target.classList.add('fa-eye');
+                e.target.title = 'Show hidden lines';
+                e.target.setAttribute('aria-label', e.target.title);
+
+                block.classList.add('hide-boring');
+            }
+        });
+    });
+
+    if (window.playground_copyable) {
+        Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
+            var pre_block = block.parentNode;
+            if (!pre_block.classList.contains('playground')) {
+                var buttons = pre_block.querySelector(".buttons");
+                if (!buttons) {
+                    buttons = document.createElement('div');
+                    buttons.className = 'buttons';
+                    pre_block.insertBefore(buttons, pre_block.firstChild);
+                }
+
+                var clipButton = document.createElement('button');
+                clipButton.className = 'fa fa-copy clip-button';
+                clipButton.title = 'Copy to clipboard';
+                clipButton.setAttribute('aria-label', clipButton.title);
+                clipButton.innerHTML = '<i class=\"tooltiptext\"></i>';
+
+                buttons.insertBefore(clipButton, buttons.firstChild);
+            }
+        });
+    }
+
+    // Process playground code blocks
+    Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
+        // Add play button
+        var buttons = pre_block.querySelector(".buttons");
+        if (!buttons) {
+            buttons = document.createElement('div');
+            buttons.className = 'buttons';
+            pre_block.insertBefore(buttons, pre_block.firstChild);
+        }
+
+        var runCodeButton = document.createElement('button');
+        runCodeButton.className = 'fa fa-play play-button';
+        runCodeButton.hidden = true;
+        runCodeButton.title = 'Run this code';
+        runCodeButton.setAttribute('aria-label', runCodeButton.title);
+
+        buttons.insertBefore(runCodeButton, buttons.firstChild);
+        runCodeButton.addEventListener('click', function (e) {
+            run_rust_code(pre_block);
+        });
+
+        if (window.playground_copyable) {
+            var copyCodeClipboardButton = document.createElement('button');
+            copyCodeClipboardButton.className = 'fa fa-copy clip-button';
+            copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
+            copyCodeClipboardButton.title = 'Copy to clipboard';
+            copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
+
+            buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
+        }
+
+        let code_block = pre_block.querySelector("code");
+        if (window.ace && code_block.classList.contains("editable")) {
+            var undoChangesButton = document.createElement('button');
+            undoChangesButton.className = 'fa fa-history reset-button';
+            undoChangesButton.title = 'Undo changes';
+            undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
+
+            buttons.insertBefore(undoChangesButton, buttons.firstChild);
+
+            undoChangesButton.addEventListener('click', function () {
+                let editor = window.ace.edit(code_block);
+                editor.setValue(editor.originalCode);
+                editor.clearSelection();
+            });
+        }
+    });
+})();
+
+(function themes() {
+    var html = document.querySelector('html');
+    var themeToggleButton = document.getElementById('theme-toggle');
+    var themePopup = document.getElementById('theme-list');
+    var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
+    var stylesheets = {
+        ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
+        tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
+        highlight: document.querySelector("[href$='highlight.css']"),
+    };
+
+    function showThemes() {
+        themePopup.style.display = 'block';
+        themeToggleButton.setAttribute('aria-expanded', true);
+        themePopup.querySelector("button#" + get_theme()).focus();
+    }
+
+    function updateThemeSelected() {
+        themePopup.querySelectorAll('.theme-selected').forEach(function (el) {
+            el.classList.remove('theme-selected');
+        });
+        themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected');
+    }
+
+    function hideThemes() {
+        themePopup.style.display = 'none';
+        themeToggleButton.setAttribute('aria-expanded', false);
+        themeToggleButton.focus();
+    }
+
+    function get_theme() {
+        var theme;
+        try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
+        if (theme === null || theme === undefined) {
+            return default_theme;
+        } else {
+            return theme;
+        }
+    }
+
+    function set_theme(theme, store = true) {
+        let ace_theme;
+
+        if (theme == 'coal' || theme == 'navy') {
+            stylesheets.ayuHighlight.disabled = true;
+            stylesheets.tomorrowNight.disabled = false;
+            stylesheets.highlight.disabled = true;
+
+            ace_theme = "ace/theme/tomorrow_night";
+        } else if (theme == 'ayu') {
+            stylesheets.ayuHighlight.disabled = false;
+            stylesheets.tomorrowNight.disabled = true;
+            stylesheets.highlight.disabled = true;
+            ace_theme = "ace/theme/tomorrow_night";
+        } else {
+            stylesheets.ayuHighlight.disabled = true;
+            stylesheets.tomorrowNight.disabled = true;
+            stylesheets.highlight.disabled = false;
+            ace_theme = "ace/theme/dawn";
+        }
+
+        setTimeout(function () {
+            themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
+        }, 1);
+
+        if (window.ace && window.editors) {
+            window.editors.forEach(function (editor) {
+                editor.setTheme(ace_theme);
+            });
+        }
+
+        var previousTheme = get_theme();
+
+        if (store) {
+            try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
+        }
+
+        html.classList.remove(previousTheme);
+        html.classList.add(theme);
+        updateThemeSelected();
+    }
+
+    // Set theme
+    var theme = get_theme();
+
+    set_theme(theme, false);
+
+    themeToggleButton.addEventListener('click', function () {
+        if (themePopup.style.display === 'block') {
+            hideThemes();
+        } else {
+            showThemes();
+        }
+    });
+
+    themePopup.addEventListener('click', function (e) {
+        var theme;
+        if (e.target.className === "theme") {
+            theme = e.target.id;
+        } else if (e.target.parentElement.className === "theme") {
+            theme = e.target.parentElement.id;
+        } else {
+            return;
+        }
+        set_theme(theme);
+    });
+
+    themePopup.addEventListener('focusout', function(e) {
+        // e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
+        if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
+            hideThemes();
+        }
+    });
+
+    // Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
+    document.addEventListener('click', function(e) {
+        if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
+            hideThemes();
+        }
+    });
+
+    document.addEventListener('keydown', function (e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (!themePopup.contains(e.target)) { return; }
+
+        switch (e.key) {
+            case 'Escape':
+                e.preventDefault();
+                hideThemes();
+                break;
+            case 'ArrowUp':
+                e.preventDefault();
+                var li = document.activeElement.parentElement;
+                if (li && li.previousElementSibling) {
+                    li.previousElementSibling.querySelector('button').focus();
+                }
+                break;
+            case 'ArrowDown':
+                e.preventDefault();
+                var li = document.activeElement.parentElement;
+                if (li && li.nextElementSibling) {
+                    li.nextElementSibling.querySelector('button').focus();
+                }
+                break;
+            case 'Home':
+                e.preventDefault();
+                themePopup.querySelector('li:first-child button').focus();
+                break;
+            case 'End':
+                e.preventDefault();
+                themePopup.querySelector('li:last-child button').focus();
+                break;
+        }
+    });
+})();
+
+(function sidebar() {
+    var body = document.querySelector("body");
+    var sidebar = document.getElementById("sidebar");
+    var sidebarLinks = document.querySelectorAll('#sidebar a');
+    var sidebarToggleButton = document.getElementById("sidebar-toggle");
+    var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
+    var firstContact = null;
+
+    function showSidebar() {
+        body.classList.remove('sidebar-hidden')
+        body.classList.add('sidebar-visible');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', 0);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', true);
+        sidebar.setAttribute('aria-hidden', false);
+        try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
+    }
+
+
+    var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
+
+    function toggleSection(ev) {
+        ev.currentTarget.parentElement.classList.toggle('expanded');
+    }
+
+    Array.from(sidebarAnchorToggles).forEach(function (el) {
+        el.addEventListener('click', toggleSection);
+    });
+
+    function hideSidebar() {
+        body.classList.remove('sidebar-visible')
+        body.classList.add('sidebar-hidden');
+        Array.from(sidebarLinks).forEach(function (link) {
+            link.setAttribute('tabIndex', -1);
+        });
+        sidebarToggleButton.setAttribute('aria-expanded', false);
+        sidebar.setAttribute('aria-hidden', true);
+        try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
+    }
+
+    // Toggle sidebar
+    sidebarToggleButton.addEventListener('click', function sidebarToggle() {
+        if (body.classList.contains("sidebar-hidden")) {
+            var current_width = parseInt(
+                document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
+            if (current_width < 150) {
+                document.documentElement.style.setProperty('--sidebar-width', '150px');
+            }
+            showSidebar();
+        } else if (body.classList.contains("sidebar-visible")) {
+            hideSidebar();
+        } else {
+            if (getComputedStyle(sidebar)['transform'] === 'none') {
+                hideSidebar();
+            } else {
+                showSidebar();
+            }
+        }
+    });
+
+    sidebarResizeHandle.addEventListener('mousedown', initResize, false);
+
+    function initResize(e) {
+        window.addEventListener('mousemove', resize, false);
+        window.addEventListener('mouseup', stopResize, false);
+        body.classList.add('sidebar-resizing');
+    }
+    function resize(e) {
+        var pos = (e.clientX - sidebar.offsetLeft);
+        if (pos < 20) {
+            hideSidebar();
+        } else {
+            if (body.classList.contains("sidebar-hidden")) {
+                showSidebar();
+            }
+            pos = Math.min(pos, window.innerWidth - 100);
+            document.documentElement.style.setProperty('--sidebar-width', pos + 'px');
+        }
+    }
+    //on mouseup remove windows functions mousemove & mouseup
+    function stopResize(e) {
+        body.classList.remove('sidebar-resizing');
+        window.removeEventListener('mousemove', resize, false);
+        window.removeEventListener('mouseup', stopResize, false);
+    }
+
+    document.addEventListener('touchstart', function (e) {
+        firstContact = {
+            x: e.touches[0].clientX,
+            time: Date.now()
+        };
+    }, { passive: true });
+
+    document.addEventListener('touchmove', function (e) {
+        if (!firstContact)
+            return;
+
+        var curX = e.touches[0].clientX;
+        var xDiff = curX - firstContact.x,
+            tDiff = Date.now() - firstContact.time;
+
+        if (tDiff < 250 && Math.abs(xDiff) >= 150) {
+            if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
+                showSidebar();
+            else if (xDiff < 0 && curX < 300)
+                hideSidebar();
+
+            firstContact = null;
+        }
+    }, { passive: true });
+})();
+
+(function chapterNavigation() {
+    document.addEventListener('keydown', function (e) {
+        if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
+        if (window.search && window.search.hasFocus()) { return; }
+        var html = document.querySelector('html');
+
+        function next() {
+            var nextButton = document.querySelector('.nav-chapters.next');
+            if (nextButton) {
+                window.location.href = nextButton.href;
+            }
+        }
+        function prev() {
+            var previousButton = document.querySelector('.nav-chapters.previous');
+            if (previousButton) {
+                window.location.href = previousButton.href;
+            }
+        }
+        switch (e.key) {
+            case 'ArrowRight':
+                e.preventDefault();
+                if (html.dir == 'rtl') {
+                    prev();
+                } else {
+                    next();
+                }
+                break;
+            case 'ArrowLeft':
+                e.preventDefault();
+                if (html.dir == 'rtl') {
+                    next();
+                } else {
+                    prev();
+                }
+                break;
+        }
+    });
+})();
+
+(function clipboard() {
+    var clipButtons = document.querySelectorAll('.clip-button');
+
+    function hideTooltip(elem) {
+        elem.firstChild.innerText = "";
+        elem.className = 'fa fa-copy clip-button';
+    }
+
+    function showTooltip(elem, msg) {
+        elem.firstChild.innerText = msg;
+        elem.className = 'fa fa-copy tooltipped';
+    }
+
+    var clipboardSnippets = new ClipboardJS('.clip-button', {
+        text: function (trigger) {
+            hideTooltip(trigger);
+            let playground = trigger.closest("pre");
+            return playground_text(playground, false);
+        }
+    });
+
+    Array.from(clipButtons).forEach(function (clipButton) {
+        clipButton.addEventListener('mouseout', function (e) {
+            hideTooltip(e.currentTarget);
+        });
+    });
+
+    clipboardSnippets.on('success', function (e) {
+        e.clearSelection();
+        showTooltip(e.trigger, "Copied!");
+    });
+
+    clipboardSnippets.on('error', function (e) {
+        showTooltip(e.trigger, "Clipboard error!");
+    });
+})();
+
+(function scrollToTop () {
+    var menuTitle = document.querySelector('.menu-title');
+
+    menuTitle.addEventListener('click', function () {
+        document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
+    });
+})();
+
+(function controllMenu() {
+    var menu = document.getElementById('menu-bar');
+
+    (function controllPosition() {
+        var scrollTop = document.scrollingElement.scrollTop;
+        var prevScrollTop = scrollTop;
+        var minMenuY = -menu.clientHeight - 50;
+        // When the script loads, the page can be at any scroll (e.g. if you reforesh it).
+        menu.style.top = scrollTop + 'px';
+        // Same as parseInt(menu.style.top.slice(0, -2), but faster
+        var topCache = menu.style.top.slice(0, -2);
+        menu.classList.remove('sticky');
+        var stickyCache = false; // Same as menu.classList.contains('sticky'), but faster
+        document.addEventListener('scroll', function () {
+            scrollTop = Math.max(document.scrollingElement.scrollTop, 0);
+            // `null` means that it doesn't need to be updated
+            var nextSticky = null;
+            var nextTop = null;
+            var scrollDown = scrollTop > prevScrollTop;
+            var menuPosAbsoluteY = topCache - scrollTop;
+            if (scrollDown) {
+                nextSticky = false;
+                if (menuPosAbsoluteY > 0) {
+                    nextTop = prevScrollTop;
+                }
+            } else {
+                if (menuPosAbsoluteY > 0) {
+                    nextSticky = true;
+                } else if (menuPosAbsoluteY < minMenuY) {
+                    nextTop = prevScrollTop + minMenuY;
+                }
+            }
+            if (nextSticky === true && stickyCache === false) {
+                menu.classList.add('sticky');
+                stickyCache = true;
+            } else if (nextSticky === false && stickyCache === true) {
+                menu.classList.remove('sticky');
+                stickyCache = false;
+            }
+            if (nextTop !== null) {
+                menu.style.top = nextTop + 'px';
+                topCache = nextTop;
+            }
+            prevScrollTop = scrollTop;
+        }, { passive: true });
+    })();
+    (function controllBorder() {
+        function updateBorder() {
+            if (menu.offsetTop === 0) {
+                menu.classList.remove('bordered');
+            } else {
+                menu.classList.add('bordered');
+            }
+        }
+        updateBorder();
+        document.addEventListener('scroll', updateBorder, { passive: true });
+    })();
+})();

docs/categories/index.html

@@ -1,74 +0,0 @@
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us" lang="en-us">
-<head>
-  <link href="//gmpg.org/xfn/11" rel="profile">
-  <link href="https://google.github.io/filament/favicon.png" rel="icon" type="image/x-icon" />
-  <meta http-equiv="content-type" content="text/html; charset=utf-8">
-  <meta name="generator" content="Hugo 0.72.0" />
-
-  
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-
-  <title>Categories &middot; Filament</title>
-
-  
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/print.css" media="print">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/poole.css">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/syntax.css">
-  <link type="text/css" rel="stylesheet" href="https://google.github.io/filament/css/hyde.css">
-  <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700|Tangerine:700|Inconsolata" rel="stylesheet">
-
-
-  
-  <link rel="apple-touch-icon-precomposed" sizes="144x144" href="/apple-touch-icon-144-precomposed.png">
-  <link rel="shortcut icon" href="/favicon.png">
-
-  
-  <link href="https://google.github.io/filament/categories/index.xml" rel="alternate" type="application/rss+xml" title="Filament" />
-
-  
-</head>
-
-  <body class="theme-base-0d ">
-  <aside class="sidebar">
-    <div class="container sidebar-sticky">
-        <div class="sidebar-about">
-            <a href="https://google.github.io/filament/">
-                
-                <div style="width:100%; height:150px">
-                <img src="https://google.github.io/filament/images/filament_logo_small.png" class="lightbulb" />
-                </div>
-                
-            </a>
-            <p class="lead">
-                
-            </p>
-        </div>
-        <nav>
-            <ul class="sidebar-nav">
-                <li>
-                    <a href="https://github.com/google/filament"> GitHub Project </a>
-                    
-                </li><li>
-                    <a href="/filament/documentation/"> Core Documentation </a>
-                    
-                </li><li>
-                    <a href="/filament/ios/"> iOS Tutorials </a>
-                    
-                </li><li>
-                    <a href="/filament/webgl/"> Web Docs / Demos </a>
-                    
-                </li>
-            </ul>
-        </nav>
-    </div>
-</aside>
-
-    <main class="content container">
-    <ul class="posts">
-
-</ul>
-    </main>
-    
-  </body>
-</html>

docs/categories/index.xml

@@ -1,14 +0,0 @@
-<?xml version="1.0" encoding="utf-8" standalone="yes"?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
-  <channel>
-    <title>Categories on Filament</title>
-    <link>https://google.github.io/filament/categories/</link>
-    <description>Recent content in Categories on Filament</description>
-    <generator>Hugo -- gohugo.io</generator>
-    <language>en-us</language>
-    
-	<atom:link href="https://google.github.io/filament/categories/index.xml" rel="self" type="application/rss+xml" />
-    
-    
-  </channel>
-</rss>

docs/cocoapods.html

@@ -0,0 +1,685 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>CocoaPods Hello Triangle - Filament</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="favicon.svg">
+        <link rel="shortcut icon" href="favicon.png">
+        <link rel="stylesheet" href="css/variables.css">
+        <link rel="stylesheet" href="css/general.css">
+        <link rel="stylesheet" href="css/chrome.css">
+        <link rel="stylesheet" href="css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="highlight.css">
+        <link rel="stylesheet" href="tomorrow-night.css">
+        <link rel="stylesheet" href="ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded "><a href="core.html"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html" class="active"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="cocoapods-hello-triangle"><a class="header" href="#cocoapods-hello-triangle">CocoaPods Hello Triangle</a></h1>
+<p>As of release 1.8.0, you can install Filament in your iOS application using
+CocoaPods.</p>
+<p>This guide will walk you through creating a basic &quot;hello triangle&quot; iOS
+application using Filament and the Metal backend.</p>
+<p><img src="./cocoapods/rotating-triangle.gif" alt="a rotating triangle" /></p>
+<p>The full source for this example is
+<a href="https://github.com/google/filament/tree/main/ios/samples/HelloCocoaPods">here</a>.
+If you're just looking to get something up and running quickly, download the
+project, <code>pod install</code>, build, and run.</p>
+<p>We'll be walking through 7 steps to get the rotating triangle up and running.
+All of the code we'll be writing will be in a single ViewController.mm file, and
+you can follow along
+<a href="https://github.com/google/filament/blob/main/ios/samples/HelloCocoaPods/HelloCocoaPods/ViewController.mm">here</a>.</p>
+<ol>
+<li><a href="#creating-a-boilerplate-app-with-filament">Creating a Boilerplate App</a></li>
+<li><a href="#instantiating-the-filament-engine">Instantiating Filament</a></li>
+<li><a href="#creating-a-swapchain">Creating a SwapChain</a></li>
+<li><a href="#clearing-the-screen">Clearing the Screen</a></li>
+<li><a href="#drawing-a-triangle">Drawing a Triangle</a></li>
+<li><a href="#compiling-a-custom-material">Compiling a Custom Material</a></li>
+<li><a href="#animating-the-triangle">Animating the Triangle</a></li>
+</ol>
+<h2 id="creating-a-boilerplate-app-with-filament"><a class="header" href="#creating-a-boilerplate-app-with-filament">Creating a Boilerplate App with Filament</a></h2>
+<p>We'll start fresh by creating a new Single View App in Xcode.</p>
+<p><img src="./cocoapods/single-view-app.png" alt="create a single view app in Xcodde" /></p>
+<p>Give your app a name, and use the default options.</p>
+<p><img src="./cocoapods/default-options.png" alt="use the default options in Xcode" /></p>
+<p>If you haven't used CocoaPods before, I recommend watching
+<a href="https://www.youtube.com/watch?v=iEAjvNRdZa0">this Route 85 video</a> to help you
+get set up.</p>
+<p>Create a Podfile in the Xcode project directory with the following:</p>
+<pre><code class="language-text">platform :ios, '11.0'
+
+target 'HelloCocoaPods' do
+    pod 'Filament'
+end
+</code></pre>
+<p>Then run:</p>
+<pre><code class="language-shell">pod install
+</code></pre>
+<p>Close the project and then re-open the newly created HelloCocoaPods.xcworkspace
+file.</p>
+<h2 id="instantiating-the-filament-engine"><a class="header" href="#instantiating-the-filament-engine">Instantiating the Filament Engine</a></h2>
+<p>Before we do anything with Filament, we first need to include the appropriate
+headers. Filament exposes a C++ API, so any files that include Filament headers
+need to be compiled in a variant of C++. We'll be using Objective-C++.</p>
+<p>You should be able to simply change the extension of the default ViewController
+from .m to .mm, though I've found Xcode to be buggy with this on occasion. To
+make sure Xcode recognizes it as an Objective-C++ file, check that the type of
+file is &quot;Objective-C++ Source&quot;.</p>
+<p><img src="./cocoapods/obj-cpp.png" alt="change the type of ViewController.m to Objective-C++" /></p>
+<p>Then, add the following to the top of ViewController.</p>
+<pre><code class="language-obj-c">#include &lt;filament/Engine.h&gt;
+
+using namespace filament;
+</code></pre>
+<p>We'll need to keep track of a few Filament objects, so let's add a section for
+private instance variables and add a pointer for our <code>Engine</code> instance.</p>
+<pre><code class="language-obj-c">@implementation Viewcontroller {
+     Engine* _engine;
+}
+</code></pre>
+<p>The Filament <code>Engine</code> is our main entrypoint into Filament. We start by
+instantiating it inside <code>viewDidLoad</code>.</p>
+<pre><code class="language-obj-c">- (void)viewDidLoad {
+    [super viewDidLoad];
+
+    _engine = Engine::create(Engine::Backend::METAL);
+}
+</code></pre>
+<p>We specify <code>Engine::Backend::METAL</code> to select the Metal backend. Filament also
+supports OpenGL on iOS, but we strongly recommend sticking to Metal.</p>
+<p>Every Filament object we create must also be destroyed. Add the <code>dealloc</code> method
+and the following:</p>
+<pre><code class="language-obj-c">- (void)dealloc {
+    _engine-&gt;destroy(&amp;_engine);
+}
+</code></pre>
+<p>If you compile and run the app now you should see output similar to the
+following:</p>
+<pre><code>FEngine (64 bits) created at 0x10ab94000 (threading is enabled)
+FEngine resolved backend: Metal
+</code></pre>
+<h2 id="creating-a-swapchain"><a class="header" href="#creating-a-swapchain">Creating a SwapChain</a></h2>
+<p>Before we can render anything, we'll first need to create a <code>SwapChain</code>. The
+<code>SwapChain</code> represents a platform-specific surface that can be rendered into. On
+iOS with Metal, it's a
+<a href="https://developer.apple.com/documentation/quartzcore/cametallayer"><code>CAMetalLayer</code></a>.</p>
+<p>We could set up our own <code>CAMetalLayer</code> if we wanted to, but Apple provides a
+<code>MTKView</code> that is already backed by a <code>CAMetalLayer</code>. It also has a delegate
+protocol with some methods that will make things easier for us.</p>
+<p>Inside Main.storyboard, change the type of ViewController's view to a <code>MTKView</code>.</p>
+<p><img src="./cocoapods/view.png" alt="ViewController view" /></p>
+<p><img src="./cocoapods/mtkview.gif" alt="change type of MTKView" /></p>
+<p>Include the SwapChain.h and MTKView.h headers and make the <code>ViewController</code>
+conform to the <code>MTKViewDelegate</code> protocol.</p>
+<pre><code class="language-obj-c">#include &lt;filament/SwapChain.h&gt;
+
+#import &lt;MetalKit/MTKView.h&gt;
+
+@interface ViewController () &lt;MTKViewDelegate&gt;
+
+@end
+</code></pre>
+<p>Add a new private var:</p>
+<pre><code class="language-obj-c">SwapChain* _swapChain;
+</code></pre>
+<p>Inside <code>viewDidLoad</code>, we'll set our <code>ViewController</code> as the <code>MTKView</code> delegate
+and instantiate our <code>SwapChain</code>. To instantiate the <code>SwapChain</code>, we pass in
+<code>view.layer</code> which, because we set our <code>View</code> to a <code>MTKView</code>, will be a
+<code>CAMetalLayer</code>. Filament's API is platform-agnostic, which is why we need to
+cast the layer to a <code>void*</code>.</p>
+<pre><code class="language-obj-c">MTKView* mtkView = (MTKView*) self.view;
+mtkView.delegate = self;
+_swapChain = _engine-&gt;createSwapChain((__bridge void*) mtkView.layer);
+</code></pre>
+<p>The <code>SwapChain</code> needs to be destroyed in our <code>dealloc</code> function. We'll destroy
+the objects in the reverse order we created them; the <code>Engine</code> object should
+always be the the last object we destroy.</p>
+<pre><code class="language-obj-c">_engine-&gt;destroy(_swapChain);
+_engine-&gt;destroy(&amp;_engine);
+</code></pre>
+<p>Finally, add stubs for some <code>MTKViewDelegate</code> methods, which we'll fill in
+later.</p>
+<pre><code class="language-obj-c">- (void)mtkView:(nonnull MTKView*)view drawableSizeWillChange:(CGSize)size {
+    // todo
+}
+
+- (void)drawInMTKView:(nonnull MTKView*)view {
+    // todo
+}
+</code></pre>
+<h2 id="clearing-the-screen"><a class="header" href="#clearing-the-screen">Clearing The Screen</a></h2>
+<p>We now have a Filament <code>Engine</code> and <code>SwapChain</code> set up. We'll need a few more
+objects before we can render anything.</p>
+<p>A Filament <code>Renderer</code> gives us an API to render frames into the <code>SwapChain</code>. It
+takes a <code>View</code>, which defines a <code>Viewport</code>, <code>Scene</code> and <code>Camera</code> for rendering.
+The <code>Camera</code> represents a vantage point into a <code>Scene</code>, which contains
+references to all the entities we want to render.</p>
+<p>Creating these are objects is straightforward. First, include the appropriate
+headers</p>
+<pre><code class="language-c++">#include &lt;filament/Renderer.h&gt;
+#include &lt;filament/View.h&gt;
+#include &lt;filament/Camera.h&gt;
+#include &lt;filament/Scene.h&gt;
+#include &lt;filament/Viewport.h&gt;
+
+#include &lt;utils/Entity.h&gt;
+#include &lt;utils/EntityManager.h&gt;
+
+using namespace utils;
+</code></pre>
+<p>add the following private vars</p>
+<pre><code class="language-obj-c">Renderer* _renderer;
+View* _view;
+Scene* _scene;
+Camera* _camera;
+Entity _cameraEntity;
+</code></pre>
+<p>and then instantiate them</p>
+<pre><code class="language-obj-c">_renderer = _engine-&gt;createRenderer();
+_view = _engine-&gt;createView();
+_scene = _engine-&gt;createScene();
+</code></pre>
+<p>The camera is a bit special. Filament uses an entity-component system, so we'll
+first need to create an <code>Entity</code> which we then attach a <code>Camera</code> component to.</p>
+<pre><code class="language-obj-c">_cameraEntity = EntityManager::get().create();
+_camera = _engine-&gt;createCamera(_cameraEntity);
+</code></pre>
+<p>Let's also inform our <code>Renderer</code> to clear to a light blue clear color, so we can
+know everything is working.</p>
+<pre><code class="language-obj-c">_renderer-&gt;setClearOptions({
+    .clearColor = {0.25f, 0.5f, 1.0f, 1.0f},
+    .clear = true
+});
+</code></pre>
+<p>The <code>Camera</code> and <code>Scene</code> need to be wired up to the <code>View</code>.</p>
+<pre><code class="language-obj-c">_view-&gt;setScene(_scene);
+_view-&gt;setCamera(_camera);
+</code></pre>
+<p>Our newly created objects get cleaned up inside <code>dealloc</code>.</p>
+<pre><code class="language-obj-c">_engine-&gt;destroyCameraComponent(_cameraEntity);
+EntityManager::get().destroy(_cameraEntity);
+_engine-&gt;destroy(_scene);
+_engine-&gt;destroy(_view);
+_engine-&gt;destroy(_renderer);
+</code></pre>
+<p>We need to set the <code>Viewport</code> on our <code>View</code>, which we want to do whenever the
+size of our <code>SwapChain</code> changes. We'll also update the projection matrix on our
+camera.</p>
+<p>Let's create a new method, <code>resize:</code>, which will update the <code>Viewport</code> on our
+<code>View</code> to a given size. We'll call it in the <code>mtkView:drawableSizeWillChange:</code>
+delegate method, and at the end of <code>viewDidLoad</code>:</p>
+<pre><code class="language-obj-c">- (void)resize:(CGSize)size {
+    _view-&gt;setViewport({0, 0, (uint32_t) size.width, (uint32_t) size.height});
+
+    const double aspect = size.width / size.height;
+    const double left   = -2.0 * aspect;
+    const double right  =  2.0 * aspect;
+    const double bottom = -2.0;
+    const double top    =  2.0;
+    const double near   =  0.0;
+    const double far    =  1.0;
+    _camera-&gt;setProjection(Camera::Projection::ORTHO, left, right, bottom, top, near, far);
+}
+
+- (void)viewDidLoad {
+    ...
+
+    // Give our View a starting size based on the drawable size.
+    [self resize:mtkView.drawableSize];
+}
+
+- (void)mtkView(nonnull MTKView*)view drawableSizeWillChange:(CGSize)size {
+    [self resize:size];
+}
+</code></pre>
+<p>Lastly, in order to render, we'll call a few Filament API methods inside the
+<code>drawInMTKView:</code> method:</p>
+<pre><code class="language-obj-c">- (void)drawInMTKView:(nonnull MTKView*)view {
+    if (_renderer-&gt;beginFrame(_swapChain)) {
+        _renderer-&gt;render(_view);
+        _renderer-&gt;endFrame();
+    }
+}
+</code></pre>
+<p>The <code>beginFrame</code> method instructs Filament to start rendering to our specific
+<code>SwapChain</code> instance. It returns <code>true</code> if the engine is ready for another
+frame. It returns <code>false</code> to signal us to skip this frame, which could happen if
+we're sending frames down too quickly for the GPU to process.</p>
+<p>At this point, you should be able to build and run the app, and you'll see a
+blue screen.</p>
+<p><img src="./cocoapods/blue-screen.png" alt="blue screen after clearing" /></p>
+<h2 id="drawing-a-triangle"><a class="header" href="#drawing-a-triangle">Drawing a Triangle</a></h2>
+<p>In order to draw a triangle, we need to create vertex and index buffers to
+define its geometry. We'll then create a <code>Renderable</code> component.</p>
+<p>We'll start by including some additional headers and adding a few new private
+vars:</p>
+<pre><code class="language-obj-c">#include &lt;filament/VertexBuffer.h&gt;
+#include &lt;filament/IndexBuffer.h&gt;
+#include &lt;filament/RenderableManager.h&gt;
+
+...
+
+VertexBuffer* _vertexBuffer;
+IndexBuffer* _indexBuffer;
+Entity _triangle;
+</code></pre>
+<p>First, we'll define the data for a single vertex.</p>
+<pre><code class="language-obj-c">struct Vertex {
+    math::float2 position;
+    math::float3 color;
+};
+</code></pre>
+<p>Creating a <code>VertexBuffer</code> and <code>IndexBuffer</code> is a matter of giving Filament a
+pointer to the data, along with information on its layout and size. Filament
+uses <code>BufferDescriptors</code> to accomplish this.</p>
+<p>Inside <code>viewDidLoad</code>, we'll statically define some verticies and indices and
+create a <code>BufferDescriptor</code> for each.</p>
+<pre><code class="language-obj-c">static const Vertex TRIANGLE_VERTICES[3] = {
+    { { 0.867, -0.500}, {1.0, 0.0, 0.0} },
+    { { 0.000,  1.000}, {0.0, 1.0, 0.0} },
+    { {-0.867, -0.500}, {0.0, 0.0, 1.0} },
+};
+static const uint16_t TRIANGLE_INDICES[3] = { 0, 1, 2 };
+
+VertexBuffer::BufferDescriptor vertices(TRIANGLE_VERTICES, sizeof(Vertex) * 3, nullptr);
+IndexBuffer::BufferDescriptor indices(TRIANGLE_INDICES, sizeof(uint16_t) * 3, nullptr);
+</code></pre>
+<p>The last argument is an optional callback function, which will be called after
+Filament is done uploading the data to the GPU. Inside the callback, you'd
+typically release the memory of any buffers via a <code>free</code> or <code>delete</code> call. We
+pass <code>nullptr</code> because we don't need a callback as our vertex and index buffer
+memory is static.</p>
+<p>Now we can instantiate our <code>VertexBuffer</code> and <code>IndexBuffer</code>.</p>
+<pre><code class="language-obj-c">using Type = VertexBuffer::AttributeType;
+
+const uint8_t stride = sizeof(Vertex);
+_vertexBuffer = VertexBuffer::Builder()
+    .vertexCount(3)
+    .bufferCount(1)
+    .attribute(VertexAttribute::POSITION, 0, Type::FLOAT2, offsetof(Vertex, position), stride)
+    .attribute(VertexAttribute::COLOR,    0, Type::FLOAT3, offsetof(Vertex, color),    stride)
+    .build(*_engine);
+
+_indexBuffer = IndexBuffer::Builder()
+    .indexCount(3)
+    .bufferType(IndexBuffer::IndexType::USHORT)
+    .build(*_engine);
+
+_vertexBuffer-&gt;setBufferAt(*_engine, 0, std::move(vertices));
+_indexBuffer-&gt;setBuffer(*_engine, std::move(indices));
+</code></pre>
+<p>We first create an <code>Entity</code> like we did for our camera. This time, we're
+attaching a <code>Renderable</code> component to the entity. The <code>Renderable</code> component
+takes geometry defined by our vertex and index buffers, and makes the entity
+visible in our scene.</p>
+<pre><code class="language-obj-c">_triangle = utils::EntityManager::get().create();
+
+using Primitive = RenderableManager::PrimitiveType;
+RenderableManager::Builder(1)
+    .geometry(0, Primitive::TRIANGLES, _vertexBuffer, _indexBuffer, 0, 3)
+    .culling(false)
+    .receiveShadows(false)
+    .castShadows(false)
+    .build(*_engine, _triangle);
+
+// Add the triangle to the scene.
+_scene-&gt;addEntity(_triangle);
+</code></pre>
+<p>Destroy the entity and buffers in <code>dealloc</code>.</p>
+<pre><code class="language-obj-c">_engine-&gt;destroy(_triangle);
+EntityManager::get().destroy(_triangle);
+_engine-&gt;destroy(_indexBuffer);
+_engine-&gt;destroy(_vertexBuffer);
+</code></pre>
+<p>If you build and run the app now, you should see a plain white triangle. When we
+created the renderable, we didn't specify any specific <code>Material</code> to use, so
+Filament used a default, white material. Let's create a custom material to color
+the triangle.</p>
+<p><img src="./cocoapods/white-triangle.png" alt="a white triangle" /></p>
+<h2 id="compiling-a-custom-material"><a class="header" href="#compiling-a-custom-material">Compiling a Custom Material</a></h2>
+<p>For simplicity, we're going to compile a custom material at runtime. For
+production, we recommend using our matc tool to compile materials offline. You
+can download it as part of one of our
+<a href="https://github.com/google/filament/releases">releases</a>.</p>
+<p>First, add a few more headers. We'll be using Filament's filamat library to
+compile a custom material.</p>
+<pre><code class="language-c++">#include &lt;filament/Material.h&gt;
+#include &lt;filament/MaterialInstance.h&gt;
+
+#include &lt;filamat/MaterialBuilder.h&gt;
+</code></pre>
+<p>We'll store our material in a new private var. We'll also need one to store a
+material <em>instance</em>. You can think of a material as a &quot;template&quot;, where a
+material instance is an instantiation of the template (similar to OOP classes
+and instances). For more information on Filament materials, read the
+<a href="https://google.github.io/filament/Materials.html">Filament Materials Guide</a>.</p>
+<pre><code class="language-obj-c">Material* _material;
+MaterialInstance* _materialInstance;
+</code></pre>
+<p>We'll use the filamat library to compile a material into a package, which we can
+then load into Filament. The material will be simple; it will load the
+interpolated color attribute and set it as the <code>baseColor</code>.</p>
+<p>Make sure to insert this code into <code>viewDidLoad</code> <em>before</em> we create our
+<code>Renderable</code>.</p>
+<pre><code class="language-obj-c">// init must be called before we can build any materials.
+filamat::MaterialBuilder::init();
+
+// Compile a custom material to use on the triangle.
+filamat::Package pkg = filamat::MaterialBuilder()
+    // The material name, only used for debugging purposes.
+    .name(&quot;Triangle material&quot;)
+    // Use the unlit shading mode, because we don't have any lights in our scene.
+    .shading(filamat::MaterialBuilder::Shading::UNLIT)
+    // Expose the COLOR attribute visible to our shader code.
+    .require(VertexAttribute::COLOR)
+    // Custom GLSL fragment shader
+    .material(&quot;void material (inout MaterialInputs material) {&quot;
+              &quot;  prepareMaterial(material);&quot;
+              &quot;  material.baseColor = getColor();&quot;
+              &quot;}&quot;)
+    // Compile for Metal on mobile platforms.
+    .targetApi(filamat::MaterialBuilder::TargetApi::METAL)
+    .platform(filamat::MaterialBuilder::Platform::MOBILE)
+    .build();
+assert(pkg.isValid());
+
+// shutdown should be called after all materials are built.
+filamat::MaterialBuilder::shutdown();
+</code></pre>
+<p>Now that we have a <code>filamat::Package</code> representing the material, we can use it
+to instantiate a Filament <code>Material</code>. Note that again, we recommend using the
+matc command-line tool to compile material packages during your app's
+compilation phase if possible, instead of at run-time.</p>
+<pre><code class="language-obj-c">// Create a Filament material from the Package.
+_material = Material::Builder()
+    .package(pkg.getData(), pkg.getSize())
+    .build(*_engine);
+_materialInstance = _material-&gt;getDefaultInstance();
+</code></pre>
+<p>Now we can use the <code>MaterialInstance</code> when creating our <code>Renderable</code>.</p>
+<pre><code class="language-obj-c">// Create a renderable using our geometry and material.
+using Primitive = RenderableManager::PrimitiveType;
+RenderableManager::Builder(1)
+    .geometry(0, Primitive::TRIANGLES, _vertexBuffer, _indexBuffer, 0, 3)
+    // Use the MaterialInstance we just created.
+    .material(0, _materialInstance)
+    .culling(false)
+    .receiveShadows(false)
+    .castShadows(false)
+    .build(*_engine, _triangle);
+</code></pre>
+<p>Lastly, we make sure to destroy everything inside <code>dealloc</code>.</p>
+<pre><code class="language-obj-c">_engine-&gt;destroy(_materialInstance);
+_engine-&gt;destroy(_material);
+</code></pre>
+<p>Build and run. You should see the same triangle, but with colors.</p>
+<p><img src="./cocoapods/colored-triangle.png" alt="the triangle with our custom material" /></p>
+<h2 id="animating-the-triangle"><a class="header" href="#animating-the-triangle">Animating the Triangle</a></h2>
+<p>We'll do this by animating a transform on our triangle entity. First, include a
+new header.</p>
+<pre><code class="language-obj-c">#include &lt;filament/TransformManager.h&gt;
+</code></pre>
+<p>When we create our triangle entity, we'll also attach a transform component.
+We've already seen two other components: <code>Renderable</code> and <code>Camera</code>. The
+<code>Transform</code> component allows us to set world-space transformations on entities.</p>
+<p>Inside <code>viewDidLoad</code>, after we create the triangle entity's <code>Renderable</code>
+component, we'll also attach a <code>Transform</code> component.</p>
+<pre><code class="language-obj-c">// Add a Transform component to the triangle, so we can animate it.
+_engine-&gt;getTransformManager().create(_triangle);
+</code></pre>
+<p>Create a new function, <code>update</code>, and add call it inside the <code>drawInMTKView:</code>
+method.</p>
+<pre><code class="language-obj-c">- (void)update {
+    auto&amp; tm = _engine-&gt;getTransformManager();
+    auto i = tm.getInstance(_triangle);
+    const auto time = CACurrentMediaTime();
+    tm.setTransform(i, math::mat4f::rotation(time, math::float3 {0.0, 0.0, 1.0}));
+}
+
+- (void)drawInMTKView:(nonnull MTKView*)view {
+    [self update];
+    if (_renderer-&gt;beginFrame(_swapChain)) {
+        _renderer-&gt;render(_view);
+        _renderer-&gt;endFrame();
+    }
+}
+</code></pre>
+<p>Now we should see the triangle rotate around its z axis.</p>
+<p><img src="./cocoapods/rotating-triangle.gif" alt="a rotating triangle" /></p>
+<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
+<p>In this guide we've covered how to install Filament with CocoaPods and get
+rendering using the Metal backend. We also compiled a custom material. Again,
+here's the
+<a href="https://github.com/google/filament/tree/main/ios/samples/HelloCocoaPods">complete sample code</a>
+for the app. If you're interesting in learning more, check out Filament's
+additional
+<a href="https://github.com/google/filament/tree/main/ios/samples">iOS samples</a>. If you
+have any problems, feel free to open an
+<a href="https://github.com/google/filament/issues">issue</a>.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="ios.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="web.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="ios.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="web.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr.min.js"></script>
+        <script src="mark.min.js"></script>
+        <script src="searcher.js"></script>
+
+        <script src="clipboard.min.js"></script>
+        <script src="highlight.js"></script>
+        <script src="book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
+</html>

docs/core-design.html

@@ -0,0 +1,246 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Filament Design - Filament</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="favicon.svg">
+        <link rel="shortcut icon" href="favicon.png">
+        <link rel="stylesheet" href="css/variables.css">
+        <link rel="stylesheet" href="css/general.css">
+        <link rel="stylesheet" href="css/chrome.css">
+        <link rel="stylesheet" href="css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="highlight.css">
+        <link rel="stylesheet" href="tomorrow-night.css">
+        <link rel="stylesheet" href="ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded "><a href="core.html"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html" class="active"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="filament-design"><a class="header" href="#filament-design">Filament Design</a></h1>
+<p>The <a href="./Filament.html">Filament Design</a> doc gives a high level overview of the
+PBR rendering techniques used in Filament.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+                            <a rel="prev" href="core.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                                <i class="fa fa-angle-left"></i>
+                            </a>
+
+                            <a rel="next prefetch" href="core-materials.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+                    <a rel="prev" href="core.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+                        <i class="fa fa-angle-left"></i>
+                    </a>
+
+                    <a rel="next prefetch" href="core-materials.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr.min.js"></script>
+        <script src="mark.min.js"></script>
+        <script src="searcher.js"></script>
+
+        <script src="clipboard.min.js"></script>
+        <script src="highlight.js"></script>
+        <script src="book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
+</html>

docs/core.html

@@ -0,0 +1,266 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Core Documentation - Filament</title>
+
+
+        <!-- Custom HTML head -->
+        
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="favicon.svg">
+        <link rel="shortcut icon" href="favicon.png">
+        <link rel="stylesheet" href="css/variables.css">
+        <link rel="stylesheet" href="css/general.css">
+        <link rel="stylesheet" href="css/chrome.css">
+        <link rel="stylesheet" href="css/print.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
+        <link rel="stylesheet" href="fonts/fonts.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" href="highlight.css">
+        <link rel="stylesheet" href="tomorrow-night.css">
+        <link rel="stylesheet" href="ayu-highlight.css">
+
+        <!-- Custom theme stylesheets -->
+
+        <!-- MathJax -->
+        <script async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
+    </head>
+    <body class="sidebar-visible no-js">
+    <div id="body-container">
+        <!-- Provide site root to javascript -->
+        <script>
+            var path_to_root = "";
+            var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
+        </script>
+
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                var theme = localStorage.getItem('mdbook-theme');
+                var sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            var theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            var html = document.querySelector('html');
+            html.classList.remove('light')
+            html.classList.add(theme);
+            var body = document.querySelector('body');
+            body.classList.remove('no-js')
+            body.classList.add('js');
+        </script>
+
+        <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            var body = document.querySelector('body');
+            var sidebar = null;
+            var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+            }
+            sidebar_toggle.checked = sidebar === 'visible';
+            body.classList.remove('sidebar-visible');
+            body.classList.add("sidebar-" + sidebar);
+        </script>
+
+        <nav id="sidebar" class="sidebar" aria-label="Table of contents">
+            <div class="sidebar-scrollbox">
+                <ol class="chapter"><li class="chapter-item expanded "><a href="core.html" class="active"><strong aria-hidden="true">1.</strong> Core Documentation</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="core-design.html"><strong aria-hidden="true">1.1.</strong> Filament Design</a></li><li class="chapter-item expanded "><a href="core-materials.html"><strong aria-hidden="true">1.2.</strong> Materials Overview</a></li></ol></li><li class="chapter-item expanded "><a href="api.html"><strong aria-hidden="true">2.</strong> API Reference</a></li><li class="chapter-item expanded "><a href="ios.html"><strong aria-hidden="true">3.</strong> iOS</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="cocoapods.html"><strong aria-hidden="true">3.1.</strong> CocoaPods Hello Triangle</a></li></ol></li><li class="chapter-item expanded "><a href="web.html"><strong aria-hidden="true">4.</strong> Web</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorials.html"><strong aria-hidden="true">4.1.</strong> Tutorials</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="web-tutorial-triangle.html"><strong aria-hidden="true">4.1.1.</strong> Triangle Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-redball.html"><strong aria-hidden="true">4.1.2.</strong> Redball Tutorial</a></li><li class="chapter-item expanded "><a href="web-tutorial-suzanne.html"><strong aria-hidden="true">4.1.3.</strong> Suzanne Tutorial</a></li></ol></li></ol></li><li class="chapter-item expanded "><a href="dev.html"><strong aria-hidden="true">5.</strong> Developing Filament</a></li><li><ol class="section"><li class="chapter-item expanded "><a href="dev-debugging.html"><strong aria-hidden="true">5.1.</strong> Filament Debugging</a></li><li class="chapter-item expanded "><a href="dev-spirv-debugging.html"><strong aria-hidden="true">5.2.</strong> Investigating SPIRV Issues</a></li><li class="chapter-item expanded "><a href="dev-versioning.html"><strong aria-hidden="true">5.3.</strong> Versioning</a></li><li class="chapter-item expanded "><a href="dev-vulkan.html"><strong aria-hidden="true">5.4.</strong> Vulkan Backend</a></li></ol></li></ol>
+            </div>
+            <div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
+        </nav>
+
+        <!-- Track and set sidebar scroll position -->
+        <script>
+            var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
+            sidebarScrollbox.addEventListener('click', function(e) {
+                if (e.target.tagName === 'A') {
+                    sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
+                }
+            }, { passive: true });
+            var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
+            sessionStorage.removeItem('sidebar-scroll');
+            if (sidebarScrollTop) {
+                // preserve sidebar scroll position when navigating via links within sidebar
+                sidebarScrollbox.scrollTop = sidebarScrollTop;
+            } else {
+                // scroll sidebar to current active section when navigating via "next/previous chapter" buttons
+                var activeSection = document.querySelector('#sidebar .active');
+                if (activeSection) {
+                    activeSection.scrollIntoView({ block: 'center' });
+                }
+            }
+        </script>
+
+        <div id="page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                                <div id="menu-bar-hover-placeholder"></div>
+                <div id="menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
+                            <i class="fa fa-bars"></i>
+                        </label>
+                        <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
+                            <i class="fa fa-paint-brush"></i>
+                        </button>
+                        <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
+                        </ul>
+                        <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
+                            <i class="fa fa-search"></i>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">Filament</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <i id="print-button" class="fa fa-print"></i>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="search-wrapper" class="hidden">
+                    <form id="searchbar-outer" class="searchbar-outer">
+                        <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
+                    </form>
+                    <div id="searchresults-outer" class="searchresults-outer hidden">
+                        <div id="searchresults-header" class="searchresults-header"></div>
+                        <ul id="searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="content" class="content">
+                    <main>
+                        <h1 id="core-documentation"><a class="header" href="#core-documentation">Core Documentation</a></h1>
+<h2 id="about"><a class="header" href="#about">About</a></h2>
+<p>Filament is a real-time physically based rendering engine for Android, iOS,
+Linux, macOS, Windows, and WebGL. It is designed to be as small as possible and
+as efficient as possible on Android.</p>
+<p>This book contains demos, tutorials, and links to important reference materials
+for developing software with Filament.</p>
+<p>In addition to the contents in this book, the following external resources are
+also available.</p>
+<ul>
+<li>
+<p><a href="https://github.com/google/filament">GitHub Project</a></p>
+<p>Contains build instructions, instructions for contributors, etc.</p>
+</li>
+<li>
+<p><a href="./Material%20Properties.pdf">Materials Ref Sheet</a></p>
+<p>A visual guide that demonstrates the effects of tweaking various PBR
+parameters.</p>
+</li>
+</ul>
+<p>To report errors in this book, please refer to the Filament project's
+<a href="https://github.com/google/filament/issues">issue tracker</a>.</p>
+<h2 id="authors"><a class="header" href="#authors">Authors</a></h2>
+<ul>
+<li><a href="https://github.com/romainguy">Romain Guy</a>,
+<a href="https://twitter.com/romainguy">@romainguy</a></li>
+<li><a href="https://github.com/pixelflinger">Mathias Agopian</a>,
+<a href="https://twitter.com/darthmoosious">@darthmoosious</a></li>
+</ul>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+
+                            <a rel="next prefetch" href="core-design.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                                <i class="fa fa-angle-right"></i>
+                            </a>
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+
+                    <a rel="next prefetch" href="core-design.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+                        <i class="fa fa-angle-right"></i>
+                    </a>
+            </nav>
+
+        </div>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr.min.js"></script>
+        <script src="mark.min.js"></script>
+        <script src="searcher.js"></script>
+
+        <script src="clipboard.min.js"></script>
+        <script src="highlight.js"></script>
+        <script src="book.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+    </div>
+    </body>
+</html>

docs/css/chrome.css

@@ -0,0 +1,587 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+html {
+    scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+    color: var(--links);
+}
+
+/*
+    body-container is necessary because mobile browsers don't seem to like
+    overflow-x on the body tag when there is a <meta name="viewport"> tag.
+*/
+#body-container {
+    /*
+        This is used when the sidebar pushes the body content off the side of
+        the screen on small screens. Without it, dragging on mobile Safari
+        will want to reposition the viewport in a weird way.
+    */
+    overflow-x: clip;
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+    z-index: 101;
+    margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+    position: relative;
+    display: flex;
+    flex-wrap: wrap;
+    background-color: var(--bg);
+    border-block-end-color: var(--bg);
+    border-block-end-width: 1px;
+    border-block-end-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+    position: -webkit-sticky;
+    position: sticky;
+    top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+    position: sticky;
+    position: -webkit-sticky;
+    top: 0;
+    height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+    border-block-end-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+    position: relative;
+    padding: 0 8px;
+    z-index: 10;
+    line-height: var(--menu-bar-height);
+    cursor: pointer;
+    transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+    #menu-bar i, #menu-bar .icon-button {
+        padding: 0 5px;
+    }
+}
+
+.icon-button {
+    border: none;
+    background: none;
+    padding: 0;
+    color: inherit;
+}
+.icon-button i {
+    margin: 0;
+}
+
+.right-buttons {
+    margin: 0 15px;
+}
+.right-buttons a {
+    text-decoration: none;
+}
+
+.left-buttons {
+    display: flex;
+    margin: 0 5px;
+}
+.no-js .left-buttons button {
+    display: none;
+}
+
+.menu-title {
+    display: inline-block;
+    font-weight: 200;
+    font-size: 2.4rem;
+    line-height: var(--menu-bar-height);
+    text-align: center;
+    margin: 0;
+    flex: 1;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+.js .menu-title {
+    cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+    color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+    color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    margin: 0;
+    max-width: 150px;
+    min-width: 90px;
+
+    display: flex;
+    justify-content: center;
+    align-content: center;
+    flex-direction: column;
+
+    transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+    text-decoration: none;
+    background-color: var(--theme-hover);
+    transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+    margin-block-start: 50px;
+    display: none;
+}
+
+.mobile-nav-chapters {
+    font-size: 2.5em;
+    text-align: center;
+    text-decoration: none;
+    width: 90px;
+    border-radius: 5px;
+    background-color: var(--sidebar-bg);
+}
+
+/* Only Firefox supports flow-relative values */
+.previous { float: left; }
+[dir=rtl] .previous { float: right; }
+
+/* Only Firefox supports flow-relative values */
+.next {
+    float: right;
+    right: var(--page-padding);
+}
+[dir=rtl] .next {
+    float: left;
+    right: unset;
+    left: var(--page-padding);
+}
+
+/* Use the correct buttons for RTL layouts*/
+[dir=rtl] .previous i.fa-angle-left:before {content:"\f105";}
+[dir=rtl] .next i.fa-angle-right:before { content:"\f104"; }
+
+@media only screen and (max-width: 1080px) {
+    .nav-wide-wrapper { display: none; }
+    .nav-wrapper { display: block; }
+}
+
+/* sidebar-visible */
+@media only screen and (max-width: 1380px) {
+    #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
+    #sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+    display: inline;
+    padding: 0.1em 0.3em;
+    border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+    color: var(--inline-code-color);
+    overflow-x: initial;
+}
+
+a:hover > .hljs {
+    text-decoration: underline;
+}
+
+pre {
+    position: relative;
+}
+pre > .buttons {
+    position: absolute;
+    z-index: 100;
+    right: 0px;
+    top: 2px;
+    margin: 0px;
+    padding: 2px 0px;
+
+    color: var(--sidebar-fg);
+    cursor: pointer;
+    visibility: hidden;
+    opacity: 0;
+    transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+    visibility: visible;
+    opacity: 1
+}
+pre > .buttons :hover {
+    color: var(--sidebar-active);
+    border-color: var(--icons-hover);
+    background-color: var(--theme-hover);
+}
+pre > .buttons i {
+    margin-inline-start: 8px;
+}
+pre > .buttons button {
+    cursor: inherit;
+    margin: 0px 5px;
+    padding: 3px 5px;
+    font-size: 14px;
+
+    border-style: solid;
+    border-width: 1px;
+    border-radius: 4px;
+    border-color: var(--icons);
+    background-color: var(--theme-popup-bg);
+    transition: 100ms;
+    transition-property: color,border-color,background-color;
+    color: var(--icons);
+}
+@media (pointer: coarse) {
+    pre > .buttons button {
+        /* On mobile, make it easier to tap buttons. */
+        padding: 0.3rem 1rem;
+    }
+}
+pre > code {
+    padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+   positioning within the code block which breaks padding. The only solution I
+   can think of is to move the padding to the outer pre tag (or insert a div
+   wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+  padding: 0rem 0rem;
+}
+
+pre > .result {
+    margin-block-start: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+    text-decoration: none;
+}
+
+mark {
+    border-radius: 2px;
+    padding-block-start: 0;
+    padding-block-end: 1px;
+    padding-inline-start: 3px;
+    padding-inline-end: 3px;
+    margin-block-start: 0;
+    margin-block-end: -1px;
+    margin-inline-start: -3px;
+    margin-inline-end: -3px;
+    background-color: var(--search-mark-bg);
+    transition: background-color 300ms linear;
+    cursor: pointer;
+}
+
+mark.fade-out {
+    background-color: rgba(0,0,0,0) !important;
+    cursor: auto;
+}
+
+.searchbar-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+}
+
+#searchbar {
+    width: 100%;
+    margin-block-start: 5px;
+    margin-block-end: 0;
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    padding: 10px 16px;
+    transition: box-shadow 300ms ease-in-out;
+    border: 1px solid var(--searchbar-border-color);
+    border-radius: 3px;
+    background-color: var(--searchbar-bg);
+    color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+    box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+    font-weight: bold;
+    font-size: 1em;
+    padding-block-start: 18px;
+    padding-block-end: 0;
+    padding-inline-start: 5px;
+    padding-inline-end: 0;
+    color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+    border-block-end: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+    list-style: none;
+    padding-inline-start: 20px;
+}
+ul#searchresults li {
+    margin: 10px 0px;
+    padding: 2px;
+    border-radius: 2px;
+}
+ul#searchresults li.focus {
+    background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+    display: block;
+    clear: both;
+    margin-block-start: 5px;
+    margin-block-end: 0;
+    margin-inline-start: 20px;
+    margin-inline-end: 0;
+    font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+    font-weight: bold;
+    font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+    position: fixed;
+    left: 0;
+    top: 0;
+    bottom: 0;
+    width: var(--sidebar-width);
+    font-size: 0.875em;
+    box-sizing: border-box;
+    -webkit-overflow-scrolling: touch;
+    overscroll-behavior-y: contain;
+    background-color: var(--sidebar-bg);
+    color: var(--sidebar-fg);
+}
+[dir=rtl] .sidebar { left: unset; right: 0; }
+.sidebar-resizing {
+    -moz-user-select: none;
+    -webkit-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
+}
+.no-js .sidebar,
+.js:not(.sidebar-resizing) .sidebar {
+    transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+    line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+    overflow-y: auto;
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+    position: absolute;
+    cursor: col-resize;
+    width: 0;
+    right: 0;
+    top: 0;
+    bottom: 0;
+}
+[dir=rtl] .sidebar .sidebar-resize-handle { right:  unset; left: 0; }
+.js .sidebar .sidebar-resize-handle {
+    cursor: col-resize;
+    width: 5px;
+}
+/* sidebar-hidden */
+#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(calc(0px - var(--sidebar-width)));
+    z-index: -1;
+}
+[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
+    transform: translateX(var(--sidebar-width));
+}
+.sidebar::-webkit-scrollbar {
+    background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+    background: var(--scrollbar);
+}
+
+/* sidebar-visible */
+#sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(var(--sidebar-width));
+}
+[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+    transform: translateX(calc(0px - var(--sidebar-width)));
+}
+@media only screen and (min-width: 620px) {
+    #sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+        margin-inline-start: var(--sidebar-width);
+    }
+    [dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
+        transform: none;
+    }
+}
+
+.chapter {
+    list-style: none outside none;
+    padding-inline-start: 0;
+    line-height: 2.2em;
+}
+
+.chapter ol {
+    width: 100%;
+}
+
+.chapter li {
+    display: flex;
+    color: var(--sidebar-non-existant);
+}
+.chapter li a {
+    display: block;
+    padding: 0;
+    text-decoration: none;
+    color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+    color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+    color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+    cursor: pointer;
+    display: block;
+    margin-inline-start: auto;
+    padding: 0 10px;
+    user-select: none;
+    opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+    transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+    display: none;
+}
+
+.chapter li.chapter-item {
+    line-height: 1.5em;
+    margin-block-start: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+    transform: rotate(90deg);
+}
+
+.spacer {
+    width: 100%;
+    height: 3px;
+    margin: 5px 0px;
+}
+.chapter .spacer {
+    background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+    .chapter li a { padding: 5px 0; }
+    .spacer { margin: 10px 0; }
+}
+
+.section {
+    list-style: none outside none;
+    padding-inline-start: 20px;
+    line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+    position: absolute;
+    left: 10px;
+    top: var(--menu-bar-height);
+    z-index: 1000;
+    border-radius: 4px;
+    font-size: 0.7em;
+    color: var(--fg);
+    background: var(--theme-popup-bg);
+    border: 1px solid var(--theme-popup-border);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    display: none;
+    /* Don't let the children's background extend past the rounded corners. */
+    overflow: hidden;
+}
+[dir=rtl] .theme-popup { left: unset;  right: 10px; }
+.theme-popup .default {
+    color: var(--icons);
+}
+.theme-popup .theme {
+    width: 100%;
+    border: 0;
+    margin: 0;
+    padding: 2px 20px;
+    line-height: 25px;
+    white-space: nowrap;
+    text-align: start;
+    cursor: pointer;
+    color: inherit;
+    background: inherit;
+    font-size: inherit;
+}
+.theme-popup .theme:hover {
+    background-color: var(--theme-hover);
+}
+
+.theme-selected::before {
+    display: inline-block;
+    content: "✓";
+    margin-inline-start: -14px;
+    width: 14px;
+}

docs/css/general.css

@@ -0,0 +1,234 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+    /* Browser default font-size is 16px, this way 1 rem = 10px */
+    font-size: 62.5%;
+    color-scheme: var(--color-scheme);
+}
+
+html {
+    font-family: "Open Sans", sans-serif;
+    color: var(--fg);
+    background-color: var(--bg);
+    text-size-adjust: none;
+    -webkit-text-size-adjust: none;
+}
+
+body {
+    margin: 0;
+    font-size: 1.6rem;
+    overflow-x: hidden;
+}
+
+code {
+    font-family: var(--mono-font) !important;
+    font-size: var(--code-font-size);
+    direction: ltr !important;
+}
+
+/* make long words/inline code not x overflow */
+main {
+    overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+    overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+    font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-block-start: 2.5em; }
+h4, h5 { margin-block-start: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+    margin-block-start: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+    display: inline-block;
+    content: "»";
+    margin-inline-start: -30px;
+    width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+   in Safari Technology Preview 117 which I think will be Safari 14.2.
+   https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+    /* Safari does not support logical properties */
+    scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+    outline: 0;
+    padding: 0 var(--page-padding);
+    margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+    box-sizing: border-box;
+    background-color: var(--bg);
+}
+.no-js .page-wrapper,
+.js:not(.sidebar-resizing) .page-wrapper {
+    transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+[dir=rtl] .js:not(.sidebar-resizing) .page-wrapper {
+    transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+    overflow-y: auto;
+    padding: 0 5px 50px 5px;
+}
+.content main {
+    margin-inline-start: auto;
+    margin-inline-end: auto;
+    max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+    color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+    text-decoration: none;
+}
+
+table {
+    margin: 0 auto;
+    border-collapse: collapse;
+}
+table td {
+    padding: 3px 20px;
+    border: 1px var(--table-border-color) solid;
+}
+table thead {
+    background: var(--table-header-bg);
+}
+table thead td {
+    font-weight: 700;
+    border: none;
+}
+table thead th {
+    padding: 3px 20px;
+}
+table thead tr {
+    border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+    background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+    margin: 20px 0;
+    padding: 0 20px;
+    color: var(--fg);
+    background-color: var(--quote-bg);
+    border-block-start: .1em solid var(--quote-border);
+    border-block-end: .1em solid var(--quote-border);
+}
+
+.warning {
+    margin: 20px;
+    padding: 0 20px;
+    border-inline-start: 2px solid var(--warning-border);
+}
+
+.warning:before {
+    position: absolute;
+    width: 3rem;
+    height: 3rem;
+    margin-inline-start: calc(-1.5rem - 21px);
+    content: "ⓘ";
+    text-align: center;
+    background-color: var(--bg);
+    color: var(--warning-border);
+    font-weight: bold;
+    font-size: 2rem;
+}
+
+blockquote .warning:before {
+    background-color: var(--quote-bg);
+}
+
+kbd {
+    background-color: var(--table-border-color);
+    border-radius: 4px;
+    border: solid 1px var(--theme-popup-border);
+    box-shadow: inset 0 -1px 0 var(--theme-hover);
+    display: inline-block;
+    font-size: var(--code-font-size);
+    font-family: var(--mono-font);
+    line-height: 10px;
+    padding: 4px 5px;
+    vertical-align: middle;
+}
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+    margin-block-start: 2em;
+}
+.footnote-definition {
+    font-size: 0.9em;
+    margin: 0.5em 0;
+}
+.footnote-definition p {
+    display: inline;
+}
+
+.tooltiptext {
+    position: absolute;
+    visibility: hidden;
+    color: #fff;
+    background-color: #333;
+    transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+    left: -8px; /* Half of the width of the icon */
+    top: -35px;
+    font-size: 0.8em;
+    text-align: center;
+    border-radius: 6px;
+    padding: 5px 8px;
+    margin: 5px;
+    z-index: 1000;
+}
+.tooltipped .tooltiptext {
+    visibility: visible;
+}
+
+.chapter li.part-title {
+    color: var(--sidebar-fg);
+    margin: 5px 0px;
+    font-weight: bold;
+}
+
+.result-no-output {
+    font-style: italic;
+}

docs/css/hyde.css

@@ -1,283 +0,0 @@
-/*
- *  __                  __
- * /\ \                /\ \
- * \ \ \___   __  __   \_\ \     __
- *  \ \  _ `\/\ \/\ \  /'_` \  /'__`\
- *   \ \ \ \ \ \ \_\ \/\ \_\ \/\  __/
- *    \ \_\ \_\/`____ \ \___,_\ \____\
- *     \/_/\/_/`/___/> \/__,_ /\/____/
- *                /\___/
- *                \/__/
- *
- * Designed, built, and released under MIT license by @mdo. Learn more at
- * https://github.com/poole/hyde.
- */
-
-
-/*
- * Contents
- *
- * Global resets
- * Sidebar
- * Container
- * Reverse layout
- * Themes
- */
-
-
-/*
- * Global resets
- *
- * Update the foundational and global aspects of the page.
- */
-
-html {
-  font-family: "Open Sans", Helvetica, Arial, sans-serif;
-}
-@media (min-width: 48em) {
-  html {
-    font-size: 16px;
-  }
-}
-@media (min-width: 58em) {
-  html {
-    font-size: 20px;
-  }
-}
-
-
-/*
- * Sidebar
- *
- * Flexible banner for housing site name, intro, and "footer" content. Starts
- * out above content in mobile and later moves to the side with wider viewports.
- */
-
-.sidebar {
-  text-align: center;
-  padding: 2rem 1rem;
-  color: rgba(255,255,255,.5);
-  background-color: #202020;
-}
-@media (min-width: 48em) {
-  .sidebar {
-    position: fixed;
-    top: 0;
-    left: 0;
-    bottom: 0;
-    width: 18rem;
-    text-align: left;
-  }
-}
-
-/* Sidebar links */
-.sidebar a {
-  color: #fff;
-}
-
-/* About section */
-.sidebar-about h1 {
-  color: #fff;
-  margin-top: 0;
-  font-family: "Abril Fatface", serif;
-  font-size: 3.25rem;
-}
-
-/* Sidebar nav */
-.sidebar-nav {
-  padding-left: 0;
-  list-style: none;
-}
-.sidebar-nav-item {
-  display: block;
-}
-a.sidebar-nav-item:hover,
-a.sidebar-nav-item:focus {
-  text-decoration: underline;
-}
-.sidebar-nav-item.active {
-  font-weight: bold;
-}
-
-/* Sticky sidebar
- *
- * Add the `sidebar-sticky` class to the sidebar's container to affix it the
- * contents to the bottom of the sidebar in tablets and up.
- */
-
-@media (min-width: 48em) {
-  .sidebar-sticky {
-    position: absolute;
-    right:  1rem;
-    bottom: 1rem;
-    left:   1rem;
-  }
-}
-
-
-/* Container
- *
- * Align the contents of the site above the proper threshold with some margin-fu
- * with a 25%-wide `.sidebar`.
- */
-
-.content {
-  padding-top:    4rem;
-  padding-bottom: 4rem;
-}
-
-@media (min-width: 48em) {
-  .content {
-    max-width: 50rem;
-    margin-left: 20rem;
-    margin-right: 2rem;
-  }
-}
-
-@media (min-width: 64em) {
-  .content {
-    margin-left: 22rem;
-    margin-right: 4rem;
-  }
-}
-
-
-/*
- * Reverse layout
- *
- * Flip the orientation of the page by placing the `.sidebar` on the right.
- */
-
-@media (min-width: 48em) {
-  .layout-reverse .sidebar {
-    left: auto;
-    right: 0;
-  }
-  .layout-reverse .content {
-    margin-left: 2rem;
-    margin-right: 20rem;
-  }
-}
-
-@media (min-width: 64em) {
-  .layout-reverse .content {
-    margin-left: 4rem;
-    margin-right: 22rem;
-  }
-}
-
-
-
-/*
- * Themes
- *
- * As of v1.1, Hyde includes optional themes to color the sidebar and links
- * within blog posts. To use, add the class of your choosing to the `body`.
- */
-
-/* Base16 (http://chriskempson.github.io/base16/#default) */
-
-/* Red */
-.theme-base-08 .sidebar {
-  background-color: #ac4142;
-}
-.theme-base-08 .content a,
-.theme-base-08 .related-posts li a:hover {
-  color: #ac4142;
-}
-
-/* Orange */
-.theme-base-09 .sidebar {
-  background-color: #d28445;
-}
-.theme-base-09 .content a,
-.theme-base-09 .related-posts li a:hover {
-  color: #d28445;
-}
-
-/* Yellow */
-.theme-base-0a .sidebar {
-  background-color: #f4bf75;
-}
-.theme-base-0a .content a,
-.theme-base-0a .related-posts li a:hover {
-  color: #f4bf75;
-}
-
-/* Green */
-.theme-base-0b .sidebar {
-  background-color: #90a959;
-}
-.theme-base-0b .content a,
-.theme-base-0b .related-posts li a:hover {
-  color: #90a959;
-}
-
-/* Cyan */
-.theme-base-0c .sidebar {
-  background-color: #75b5aa;
-}
-.theme-base-0c .content a,
-.theme-base-0c .related-posts li a:hover {
-  color: #75b5aa;
-}
-
-/* Light Gray */
-.theme-base-0d .sidebar {
-  background-color: #d0d0d0;
-}
-.theme-base-0d .content a,
-.theme-base-0d .related-posts li a:hover {
-  color: #7080d0;
-}
-
-.theme-base-0d .lead {
-  color: black;
-}
-
-.theme-base-0d .sidebar a {
-  color: #34a;
-}
-
-.content.container {
-  padding-top: 32px;
-}
-
-.lightbulb {
-    max-height: 100%;
-    display: inline;
-}
-
-@media (min-width: 48em) {
-    .lightbulb {
-        margin-left: -10px;
-    }
-}
-
-iframe {
-  border: 0;
-  width: 100%;
-  margin-bottom: 15px;
-}
-
-/* Magenta */
-.theme-base-0e .sidebar {
-  background-color: #aa759f;
-}
-.theme-base-0e .content a,
-.theme-base-0e .related-posts li a:hover {
-  color: #aa759f;
-}
-
-/* Brown */
-.theme-base-0f .sidebar {
-  background-color: #8f5536;
-}
-.theme-base-0f .content a,
-.theme-base-0f .related-posts li a:hover {
-  color: #8f5536;
-}
-
-.post li {
-    list-style-type: none;
-}

docs/css/poole.css

@@ -1,403 +0,0 @@
-/*
- *                        ___
- *                       /\_ \
- *  _____     ___     ___\//\ \      __
- * /\ '__`\  / __`\  / __`\\ \ \   /'__`\
- * \ \ \_\ \/\ \_\ \/\ \_\ \\_\ \_/\  __/
- *  \ \ ,__/\ \____/\ \____//\____\ \____\
- *   \ \ \/  \/___/  \/___/ \/____/\/____/
- *    \ \_\
- *     \/_/
- *
- * Designed, built, and released under MIT license by @mdo. Learn more at
- * https://github.com/poole/poole.
- */
-
-
-/*
- * Contents
- *
- * Body resets
- * Custom type
- * Messages
- * Container
- * Masthead
- * Posts and pages
- * Pagination
- * Reverse layout
- * Themes
- */
-
-
-/*
- * Body resets
- *
- * Update the foundational and global aspects of the page.
- */
-
-* {
-  -webkit-box-sizing: border-box;
-     -moz-box-sizing: border-box;
-          box-sizing: border-box;
-}
-
-html,
-body {
-  margin: 0;
-  padding: 0;
-}
-
-html {
-  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
-  font-size: 16px;
-  line-height: 1.5;
-}
-@media (min-width: 38em) {
-  html {
-    font-size: 20px;
-  }
-}
-
-body {
-  color: #515151;
-  background-color: #fff;
-  -webkit-text-size-adjust: 100%;
-      -ms-text-size-adjust: 100%;
-}
-
-/* No `:visited` state is required by default (browsers will use `a`) */
-a {
-  color: #268bd2;
-  text-decoration: none;
-}
-/* `:focus` is linked to `:hover` for basic accessibility */
-a:hover,
-a:focus {
-  text-decoration: underline;
-}
-
-/* Headings */
-h1, h2, h3, h4, h5, h6 {
-  margin-bottom: .5rem;
-  font-weight: bold;
-  line-height: 1.25;
-  color: #313131;
-  text-rendering: optimizeLegibility;
-}
-h1 {
-  font-size: 2rem;
-}
-h2 {
-  margin-top: 1rem;
-  font-size: 1.5rem;
-}
-h3 {
-  margin-top: 1.5rem;
-  font-size: 1.25rem;
-}
-h4, h5, h6 {
-  margin-top: 1rem;
-  font-size: 1rem;
-}
-
-/* Body text */
-p {
-  margin-top: 0;
-  margin-bottom: 1rem;
-}
-
-strong {
-  color: #303030;
-}
-
-
-/* Lists */
-ul, ol, dl {
-  margin-top: 0;
-  margin-bottom: 1rem;
-}
-
-dt {
-  font-weight: bold;
-}
-dd {
-  margin-bottom: .5rem;
-}
-
-/* Misc */
-hr {
-  position: relative;
-  margin: 1.5rem 0;
-  border: 0;
-  border-top: 1px solid #eee;
-  border-bottom: 1px solid #fff;
-}
-
-abbr {
-  font-size: 85%;
-  font-weight: bold;
-  color: #555;
-  text-transform: uppercase;
-}
-abbr[title] {
-  cursor: help;
-  border-bottom: 1px dotted #e5e5e5;
-}
-
-/* Code */
-code,
-pre {
-  font-family: Menlo, Monaco, "Courier New", monospace;
-}
-code {
-  padding: .25em .5em;
-  font-size: 85%;
-  color: #bf616a;
-  background-color: #f9f9f9;
-  border-radius: 3px;
-}
-pre {
-  display: block;
-  margin-top: 0;
-  margin-bottom: 1rem;
-  padding: 1rem;
-  font-size: .8rem;
-  line-height: 1.4;
-  white-space: pre;
-  white-space: pre-wrap;
-  word-break: break-all;
-  word-wrap: break-word;
-  background-color: #f9f9f9;
-}
-pre code {
-  padding: 0;
-  font-size: 100%;
-  color: inherit;
-  background-color: transparent;
-}
-.highlight {
-  margin-bottom: 1rem;
-  border-radius: 4px;
-}
-.highlight pre {
-  margin-bottom: 0;
-}
-
-/* Quotes */
-blockquote {
-  padding: .5rem 1rem;
-  margin: .8rem 0;
-  color: #7a7a7a;
-  border-left: .25rem solid #e5e5e5;
-}
-blockquote p:last-child {
-  margin-bottom: 0;
-}
-@media (min-width: 30em) {
-  blockquote {
-    padding-right: 5rem;
-    padding-left: 1.25rem;
-  }
-}
-
-img {
-  display: block;
-  margin: 0 0 1rem;
-  border-radius: 5px;
-  max-width: 100%;
-}
-
-/* Tables */
-table {
-  margin-bottom: 1rem;
-  width: 100%;
-  border: 1px solid #e5e5e5;
-  border-collapse: collapse;
-}
-td,
-th {
-  padding: .25rem .5rem;
-  border: 1px solid #e5e5e5;
-}
-tbody tr:nth-child(odd) td,
-tbody tr:nth-child(odd) th {
-  background-color: #f9f9f9;
-}
-
-
-/*
- * Custom type
- *
- * Extend paragraphs with `.lead` for larger introductory text.
- */
-
-.lead {
-  font-size: 1.25rem;
-  font-weight: 300;
-}
-
-
-/*
- * Messages
- *
- * Show alert messages to users. You may add it to single elements like a `<p>`,
- * or to a parent if there are multiple elements to show.
- */
-
-.message {
-  margin-bottom: 1rem;
-  padding: 1rem;
-  color: #717171;
-  background-color: #f9f9f9;
-}
-
-
-/*
- * Container
- *
- * Center the page content.
- */
-
-.container {
-  max-width: 38rem;
-  padding-left:  1rem;
-  padding-right: 1rem;
-  margin-left:  auto;
-  margin-right: auto;
-}
-
-
-/*
- * Masthead
- *
- * Super small header above the content for site name and short description.
- */
-
-.masthead {
-  padding-top:    1rem;
-  padding-bottom: 1rem;
-  margin-bottom: 3rem;
-}
-.masthead-title {
-  margin-top: 0;
-  margin-bottom: 0;
-  color: #505050;
-}
-.masthead-title a {
-  color: #505050;
-}
-.masthead-title small {
-  font-size: 75%;
-  font-weight: 400;
-  color: #c0c0c0;
-  letter-spacing: 0;
-}
-
-
-/*
- * Posts and pages
- *
- * Each post is wrapped in `.post` and is used on default and post layouts. Each
- * page is wrapped in `.page` and is only used on the page layout.
- */
-
-.page,
-.post {
-  margin-bottom: 4em;
-}
-
-/* Blog post or page title */
-.page-title,
-.post-title,
-.post-title a {
-  color: #303030;
-}
-.page-title,
-.post-title {
-  margin-top: 0;
-}
-
-/* Meta data line below post title */
-.post-date {
-  display: block;
-  margin-top: -.5rem;
-  margin-bottom: 1rem;
-  color: #9a9a9a;
-}
-
-/* Related posts */
-.related {
-  padding-top: 2rem;
-  padding-bottom: 2rem;
-  border-top: 1px solid #eee;
-}
-.related-posts {
-  padding-left: 0;
-  list-style: none;
-}
-.related-posts h3 {
-  margin-top: 0;
-}
-.related-posts li small {
-  font-size: 75%;
-  color: #999;
-}
-.related-posts li a:hover {
-  color: #268bd2;
-  text-decoration: none;
-}
-.related-posts li a:hover small {
-  color: inherit;
-}
-
-
-/*
- * Pagination
- *
- * Super lightweight (HTML-wise) blog pagination. `span`s are provide for when
- * there are no more previous or next posts to show.
- */
-
-.pagination {
-  overflow: hidden; /* clearfix */
-  margin-left: -1rem;
-  margin-right: -1rem;
-  font-family: "Open Sans", Helvetica, Arial, sans-serif;
-  color: #ccc;
-  text-align: center;
-}
-
-/* Pagination items can be `span`s or `a`s */
-.pagination-item {
-  display: block;
-  padding: 1rem;
-  border: 1px solid #eee;
-}
-.pagination-item:first-child {
-  margin-bottom: -1px;
-}
-
-/* Only provide a hover state for linked pagination items */
-a.pagination-item:hover {
-  background-color: #f5f5f5;
-}
-
-@media (min-width: 30em) {
-  .pagination {
-    margin: 3rem 0;
-  }
-  .pagination-item {
-    float: left;
-    width: 50%;
-  }
-  .pagination-item:first-child {
-    margin-bottom: 0;
-    border-top-left-radius:    4px;
-    border-bottom-left-radius: 4px;
-  }
-  .pagination-item:last-child {
-    margin-left: -1px;
-    border-top-right-radius:    4px;
-    border-bottom-right-radius: 4px;
-  }
-}