material: fix depth variant leak

The default material does not cover all of the depth variants,
and so for the client material's depth variants (with no custom
depth shader), we need to check if the program is allocated for
the material or if it is actually part of the default material.

.github/workflows/presubmit.yml

@@ -86,7 +86,7 @@ jobs:
       - uses: ./.github/actions/ubuntu-apt-add-src
       - name: Run script
         run: |
-          source ./build/linux/ci-common.sh && bash test/renderdiff/test.sh
+          source ./build/linux/ci-common.sh && bash test/renderdiff_tests.sh
       - uses: actions/upload-artifact@v4
         with:
           name: presubmit-renderdiff-result

BUILDING.md

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

CMakeLists.txt

@@ -525,14 +525,11 @@ else()
     option(FILAMENT_BUILD_FILAMAT "Build filamat and JNI buildings" OFF)
 endif()
 
-# By default, link in matdbg/fgviewer for Desktop + Debug only since it pulls in filamat and a web server.
+# By default, link in matdbg for Desktop + Debug only since it pulls in filamat and a web server.
 if (CMAKE_BUILD_TYPE STREQUAL "Debug" AND IS_HOST_PLATFORM)
     option(FILAMENT_ENABLE_MATDBG "Enable the material debugger" ON)
-    # TODO: Uncomment below when fgviewer is ready
-    # option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" ON)
 else()
     option(FILAMENT_ENABLE_MATDBG "Enable the material debugger" OFF)
-    option(FILAMENT_ENABLE_FGVIEWER "Enable the frame graph viewer" OFF)
 endif()
 
 # Only optimize materials in Release mode (so error message lines match the source code)
@@ -781,11 +778,6 @@ if (FILAMENT_BUILD_FILAMAT OR IS_HOST_PLATFORM)
     if (FILAMENT_ENABLE_MATDBG OR IS_HOST_PLATFORM)
         add_subdirectory(${LIBRARIES}/matdbg)
     endif()
-
-    # TODO: Uncomment below when fgviewer is ready
-    # if (FILAMENT_ENABLE_FGVIEWER OR IS_HOST_PLATFORM)
-    #     add_subdirectory(${LIBRARIES}/fgviewer)
-    # endif()
 endif()
 
 if (FILAMENT_SUPPORTS_VULKAN)

NEW_RELEASE_NOTES.md

@@ -7,3 +7,4 @@ for next branch cut* header.
 appropriate header in [RELEASE_NOTES.md](./RELEASE_NOTES.md).
 
 ## Release notes for next branch cut
+- vk: fix stage pool gc logic

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.56.7'
+    implementation 'com.google.android.filament:filament-android:1.56.0'
 }
 ```
 
@@ -51,7 +51,7 @@ Here are all the libraries available in the group `com.google.android.filament`:
 iOS projects can use CocoaPods to install the latest release:
 
 ```shell
-pod 'Filament', '~> 1.56.7'
+pod 'Filament', '~> 1.56.0'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,26 +7,6 @@ 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.56.7
-
-
-## v1.56.6
-
-fix crash: the 'target_node' of Animation Channel may be nullpointer.
-
-## v1.56.5
-
-
-## v1.56.4
-
-
-## v1.56.3
-
-
-## v1.56.2
-
-- vk: fix stage pool gc logic
-
 ## v1.56.1
 
 ## v1.56.0

android/build.gradle

@@ -11,9 +11,6 @@
 // com.google.android.filament.exclude-vulkan
 //     When set, support for Vulkan will be excluded.
 //
-// com.google.android.filament.fgviewer
-//     When set, enables fgviewer
-//
 // com.google.android.filament.matdbg
 //     When set, enables matdbg
 //
@@ -64,11 +61,6 @@ buildscript {
             .gradleProperty("com.google.android.filament.exclude-vulkan")
             .isPresent()
 
-    // TODO: Uncomment below when fgviewer is ready
-    // def fgviewer = providers
-    //         .gradleProperty("com.google.android.filament.fgviewer")
-    //         .isPresent()
-
     def matdbg = providers
             .gradleProperty("com.google.android.filament.matdbg")
             .isPresent()
@@ -123,8 +115,6 @@ buildscript {
         "-DANDROID_STL=c++_static",
         "-DFILAMENT_DIST_DIR=${filamentPath}".toString(),
         "-DFILAMENT_SUPPORTS_VULKAN=${excludeVulkan ? 'OFF' : 'ON'}".toString(),
-        // TODO: Uncomment below when fgviewer is ready
-        // "-DFILAMENT_ENABLE_FGVIEWER=${fgviewer ? 'ON' : 'OFF'}".toString(),
         "-DFILAMENT_ENABLE_MATDBG=${matdbg ? 'ON' : 'OFF'}".toString(),
         "-DFILAMENT_DISABLE_MATOPT=${matnopt ? 'ON' : 'OFF'}".toString()
     ]

android/filament-android/CMakeLists.txt

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

android/filament-android/src/main/cpp/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/IndirectLight.cpp

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

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

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

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

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

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

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

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

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

android/gradle.properties

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

build.sh

@@ -23,8 +23,6 @@ function print_help {
     echo "        This is sometimes needed instead of -c (which still misses some clean steps)."
     echo "    -d"
     echo "        Enable matdbg."
-    echo "    -t"
-    echo "        Enable fgviewer."
     echo "    -f"
     echo "        Always invoke CMake before incremental builds."
     echo "    -g"
@@ -127,27 +125,6 @@ function print_matdbg_help {
     echo ""
 }
 
-function print_fgviewer_help {
-    echo "fgviewer is enabled in the build, but some extra steps are needed."
-    echo ""
-    echo "FOR DESKTOP BUILDS:"
-    echo ""
-    echo "Please set the port environment variable before launching. e.g., on macOS do:"
-    echo "   export FILAMENT_FGVIEWER_PORT=8085"
-    echo ""
-    echo "FOR ANDROID BUILDS:"
-    echo ""
-    echo "1) For Android Studio builds, make sure to set:"
-    echo "       -Pcom.google.android.filament.fgviewer"
-    echo "   option in Preferences > Build > Compiler > Command line options."
-    echo ""
-    echo "2) The port number is hardcoded to 8085 so you will need to do:"
-    echo "       adb forward tcp:8085 tcp:8085"
-    echo ""
-    echo "3) Be sure to enable INTERNET permission in your app's manifest file."
-    echo ""
-}
-
 # Unless explicitly specified, NDK version will be selected as highest available version within same major release chain
 FILAMENT_NDK_VERSION=${FILAMENT_NDK_VERSION:-$(cat `dirname $0`/build/android/ndk.version | cut -f 1 -d ".")}
 
@@ -195,7 +172,6 @@ VULKAN_ANDROID_GRADLE_OPTION=""
 EGL_ON_LINUX_OPTION="-DFILAMENT_SUPPORTS_EGL_ON_LINUX=OFF"
 
 MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=OFF"
-FGVIEWER_OPTION="-DFILAMENT_ENABLE_FGVIEWER=OFF"
 MATDBG_GRADLE_OPTION=""
 
 MATOPT_OPTION=""
@@ -264,7 +240,6 @@ function build_desktop_target {
             -DCMAKE_BUILD_TYPE="$1" \
             -DCMAKE_INSTALL_PREFIX="../${lc_target}/filament" \
             ${EGL_ON_LINUX_OPTION} \
-            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${ASAN_UBSAN_OPTION} \
@@ -401,7 +376,6 @@ function build_android_target {
             -DFILAMENT_NDK_VERSION="${FILAMENT_NDK_VERSION}" \
             -DCMAKE_INSTALL_PREFIX="../android-${lc_target}/filament" \
             -DCMAKE_TOOLCHAIN_FILE="../../build/toolchain-${arch}-linux-android.cmake" \
-            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${VULKAN_ANDROID_OPTION} \
@@ -639,7 +613,6 @@ function build_ios_target {
             -DPLATFORM_NAME="${platform}" \
             -DIOS=1 \
             -DCMAKE_TOOLCHAIN_FILE=../../third_party/clang/iOS.cmake \
-            ${FGVIEWER_OPTION} \
             ${MATDBG_OPTION} \
             ${MATOPT_OPTION} \
             ${STEREOSCOPIC_OPTION} \
@@ -829,7 +802,7 @@ function check_debug_release_build {
 
 pushd "$(dirname "$0")" > /dev/null
 
-while getopts ":hacCfgijmp:q:uvslwedtk:bx:S:X:" opt; do
+while getopts ":hacCfgijmp:q:uvslwedk:bx:S:X:" opt; do
     case ${opt} in
         h)
             print_help
@@ -850,12 +823,6 @@ while getopts ":hacCfgijmp:q:uvslwedtk:bx:S:X:" opt; do
             MATDBG_OPTION="-DFILAMENT_ENABLE_MATDBG=ON, -DFILAMENT_BUILD_FILAMAT=ON"
             MATDBG_GRADLE_OPTION="-Pcom.google.android.filament.matdbg"
             ;;
-        t)
-            # TODO: Uncomment below when fgviewer is ready
-            # PRINT_FGVIEWER_HELP=true
-            # FGVIEWER_OPTION="-DFILAMENT_ENABLE_FGVIEWER=ON"
-            #FGVIEWER_GRADLE_OPTION="-Pcom.google.android.filament.fgviewer"
-            ;;
         f)
             ISSUE_CMAKE_ALWAYS=true
             ;;
@@ -1060,7 +1027,3 @@ fi
 if [[ "${PRINT_MATDBG_HELP}" == "true" ]]; then
     print_matdbg_help
 fi
-
-if [[ "${PRINT_FGVIEWER_HELP}" == "true" ]]; then
-    print_fgviewer_help
-fi

build/linux/combine-static-libs.sh

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

build/web/ci-common.sh

@@ -13,7 +13,7 @@ chmod +x ninja
 export PATH="$PWD:$PATH"
 
 # Install emscripten.
-curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.15.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 ./emsdk install latest
 ./emsdk activate latest

docs/Materials.html

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

docs_src/.gitignore

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

docs_src/README.md

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

docs_src/book.toml

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

docs_src/build/duplicates.json

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

docs_src/build/install_mdbook.sh

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

docs_src/build/run.py

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

docs_src/build/utils.py

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

docs_src/markdeep/README.md

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

docs_src/src/SUMMARY.md

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

docs_src/src/dup/README.txt

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