Merge branch 'rc/1.56.6' into release

If the shared osmesa lib is not found, then we assume that the
library has been compile-time linked via the linker.  This is to
accommodate build frameworks where compile-time linking is
preferred.

.github/workflows/presubmit.yml

@@ -77,29 +77,16 @@ jobs:
         run: |
           cd build/web && printf "y" | ./build.sh presubmit
 
-  validate-docs:
-    name: validate-docs
-    runs-on: ubuntu-22.04-4core
-    steps:
-      - uses: actions/checkout@v4.1.6
-        with:
-          fetch-depth: 0
-      - name: Check for manual edits to /docs
-        run: |
-           echo "${{ github.event.pull_request.head.sha }} -- ${{ github.event.pull_request.head.sha }}"
-           # disable for now
-           # bash docs_src/build/presubmit_check.sh ${{ github.event.pull_request.head.sha }}
-
   test-renderdiff:
     name: test-renderdiff
-    runs-on: ubuntu-22.04-16core
+    runs-on: ubuntu-22.04-32core
 
     steps:
       - uses: actions/checkout@v4.1.6
       - uses: ./.github/actions/ubuntu-apt-add-src
       - name: Run script
         run: |
-          source ./build/linux/ci-common.sh && bash test/renderdiff/test.sh
+          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

@@ -457,19 +457,10 @@ if (NOT WEBGL)
     set(GC_SECTIONS "-Wl,--gc-sections")
 endif()
 
-# Prevents stacks from being made for executable by explicitly adding this linker flag. Otherwise,
-# it generates warnings newly introduced as of GNU LD 2.39. Modern security practices strongly
-# recommend marking the stack as non-executable using the -z noexecstack linker flag to prevent
-# stack-based buffer overflow exploits.
-# See: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=ffcf9c5700e49c0aee42dcba9a12ba21338e8136
-if (LINUX)
-    set(NO_EXEC_STACK "-Wl,-z,noexecstack")
-endif()
-
 set(B_SYMBOLIC_FUNCTIONS "-Wl,-Bsymbolic-functions")
 
 if (ANDROID)
-    set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
+set(BINARY_ALIGNMENT "-Wl,-z,max-page-size=16384")
 endif()
 
 if (APPLE)
@@ -484,7 +475,7 @@ if (APPLE)
     set(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> qc -S <TARGET> <LINK_FLAGS> <OBJECTS>")
 endif()
 
-set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS} ${NO_EXEC_STACK}")
+set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${GC_SECTIONS}")
 set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${GC_SECTIONS} ${B_SYMBOLIC_FUNCTIONS} ${BINARY_ALIGNMENT}")
 
 if (WEBGL_PTHREADS)
@@ -667,6 +658,10 @@ function(list_licenses OUTPUT MODULES)
 endfunction()
 
 set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/linux/combine-static-libs.sh")
+if (WIN32)
+    set(COMBINE_SCRIPT "${CMAKE_CURRENT_SOURCE_DIR}/build/windows/combine-static-libs.bat")
+    set(CMAKE_AR "lib.exe")
+endif()
 
 # Add a custom command to TARGET that combines the static libraries in DEPS into a single archive.
 function(combine_static_libs TARGET OUTPUT DEPS)
@@ -681,22 +676,12 @@ function(combine_static_libs TARGET OUTPUT DEPS)
         endif()
     endforeach()
 
-    if (WIN32)
-        add_custom_command(
-            TARGET ${TARGET} POST_BUILD
-            COMMAND lib.exe /nologo /out:temp.lib ${DEPS_FILES}
-            COMMAND "${CMAKE_COMMAND}" -E rename temp.lib ${OUTPUT}
-            COMMENT "Combining ${target} dependencies into single shared library"
-            VERBATIM
-        )
-    else()
-        add_custom_command(
-            TARGET ${TARGET} POST_BUILD
-            COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
-            COMMENT "Combining ${target} dependencies into single shared library"
-            VERBATIM
-        )
-    endif()
+    add_custom_command(
+        TARGET ${TARGET} POST_BUILD
+        COMMAND "${COMBINE_SCRIPT}" "${CMAKE_AR}" "${OUTPUT}" ${DEPS_FILES}
+        COMMENT "Combining ${target} dependencies into single shared library"
+        VERBATIM
+    )
 endfunction()
 
 # ==================================================================================================
@@ -767,7 +752,6 @@ add_subdirectory(${LIBRARIES}/utils)
 add_subdirectory(${LIBRARIES}/viewer)
 add_subdirectory(${FILAMENT}/filament)
 add_subdirectory(${FILAMENT}/shaders)
-add_subdirectory(${EXTERNAL}/abseil/tnt)
 add_subdirectory(${EXTERNAL}/basisu/tnt)
 add_subdirectory(${EXTERNAL}/civetweb/tnt)
 add_subdirectory(${EXTERNAL}/imgui/tnt)

CODE_STYLE.md

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

NEW_RELEASE_NOTES.md

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

README.md

@@ -31,7 +31,7 @@ repositories {
 }
 
 dependencies {
-    implementation 'com.google.android.filament:filament-android:1.57.0'
+    implementation 'com.google.android.filament:filament-android:1.56.6'
 }
 ```
 
@@ -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.57.0'
+pod 'Filament', '~> 1.56.6'
 ```
 
 ## Documentation

RELEASE_NOTES.md

@@ -7,20 +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.57.1
-
-
-## v1.57.0
-
-- matdbg: Add support for debugging ESSL 1.0 shaders
-- backend: New platform API to better handle external textures [⚠️ **New Material Version**]
-
-## v1.56.8
-
-
-## v1.56.7
-
-
 ## v1.56.6
 
 fix crash: the 'target_node' of Animation Channel may be nullpointer.

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

@@ -392,11 +392,11 @@ Java_com_google_android_filament_Engine_nIsValidSwapChain(JNIEnv*, jclass,
     return (jboolean)engine->isValid((SwapChain*)nativeSwapChain);
 }
 
-extern "C" JNIEXPORT jboolean JNICALL
+extern "C" JNIEXPORT void JNICALL
 Java_com_google_android_filament_Engine_nFlushAndWait(JNIEnv*, jclass,
-        jlong nativeEngine, jlong timeout) {
+        jlong nativeEngine) {
     Engine* engine = (Engine*) nativeEngine;
-    return engine->flushAndWait((uint64_t)timeout);
+    engine->flushAndWait();
 }
 
 extern "C" JNIEXPORT void JNICALL

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

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

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

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

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

@@ -1271,28 +1271,7 @@ public class Engine {
      * {@link  android.view.SurfaceHolder.Callback#surfaceDestroyed surfaceDestroyed}.</p>
      */
     public void flushAndWait() {
-        boolean unused = flushAndWait(Fence.WAIT_FOR_EVER);
-    }
-
-    /**
-     * Kicks the hardware thread (e.g. the OpenGL, Vulkan or Metal thread) and blocks until
-     * all commands to this point are executed. Note that does guarantee that the
-     * hardware is actually finished.
-     *
-     * A timeout can be specified, if for some reason this flushAndWait doesn't complete before the timeout, it will
-     * return false, true otherwise.
-     *
-     * <p>This is typically used right after destroying the <code>SwapChain</code>,
-     * in cases where a guarantee about the <code>SwapChain</code> destruction is needed in a
-     * timely fashion, such as when responding to Android's
-     * <code>android.view.SurfaceHolder.Callback.surfaceDestroyed</code></p>
-     *
-     * @param timeout A timeout in nanoseconds
-     * @return true if successful, false if flushAndWait timed out, in which case it wasn't successful and commands
-     * might still be executing on both the CPU and GPU sides.
-     */
-    public boolean flushAndWait(long timeout) {
-        return nFlushAndWait(getNativeObject(), timeout);
+        nFlushAndWait(getNativeObject());
     }
 
     /**
@@ -1458,7 +1437,7 @@ public class Engine {
     private static native boolean nIsValidRenderTarget(long nativeEngine, long nativeTarget);
     private static native boolean nIsValidSwapChain(long nativeEngine, long nativeSwapChain);
     private static native void nDestroyEntity(long nativeEngine, int entity);
-    private static native boolean nFlushAndWait(long nativeEngine, long timeout);
+    private static native void nFlushAndWait(long nativeEngine);
     private static native void nFlush(long nativeEngine);
     private static native boolean nIsPaused(long nativeEngine);
     private static native void nSetPaused(long nativeEngine, boolean paused);

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

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

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

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

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

@@ -1420,10 +1420,10 @@ public class View {
         /**
          * Upscaling quality
          * LOW:    bilinear filtered blit. Fastest, poor quality
-         * MEDIUM: Qualcomm Snapdragon Game Super Resolution (SGSR) 1.0
+         * MEDIUM: AMD FidelityFX FSR1 w/ mobile optimizations
          * HIGH:   AMD FidelityFX FSR1 w/ mobile optimizations
          * ULTRA:  AMD FidelityFX FSR1
-         *      FSR1 and SGSR require a well anti-aliased (MSAA or TAA), noise free scene. Avoid FXAA and dithering.
+         *      FSR1 require a well anti-aliased (MSAA or TAA), noise free scene.
          *
          * The default upscaling quality is set to LOW.
          */

android/gradle.properties

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

build/linux/ci-common.sh

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

build/linux/combine-static-libs.sh

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

build/web/ci-common.sh

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

build/windows/combine-static-libs.bat

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

docs_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/checks.py

@@ -1,140 +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.
-
-# This script contains several checks on the current commit, each corresponds to `possible_conditions`
-# in the main function below
-#   - Direct (non-filamentbot) edits of /docs
-#   - Edits to sources of READMEs that are duplicated to /docs
-#       or edits to /docs_src sources
-#   - Commit message has DOCS_BYPASS
-#   - Commit message has DOCS_FORCE
-#   - Commit message has DOCS_ALLOW_DIRECT_EDITS
-
-import json
-import sys
-import os
-
-from utils import execute, ArgParseImpl
-
-CUR_DIR = os.path.dirname(os.path.abspath(__file__))
-ROOT_DIR = os.path.join(CUR_DIR, '../../')
-
-def get_last_commit_hash():
-  res, ret = execute('git rev-parse HEAD', cwd=ROOT_DIR)
-  assert res == 0, 'Failed to get the last commit hash'
-  return ret.strip()
-
-def get_edited_files(commit_hash):
-  INSERT = '#####?????'
-  res, ret = execute(f'git show --name-only --pretty=%b{INSERT} {commit_hash}')
-  assert res == 0, 'Failed to get edited filed'
-  files = []
-  _, after = ret.split(INSERT)
-  for r in filter(lambda a: len(a) > 0, after.split('\n')):
-    if r.startswith('commit'):
-      break
-    files.append(r)
-  return files
-
-# Returns True if there were no direct edits to '/docs'
-def check_no_direct_edits(commit_hash, printing=True):
-  bad = [f'\t{f}' for f in get_edited_files(commit_hash) if f.startswith('docs/')]
-  if printing and len(bad) > 0:
-    print(f'Found edits to /docs:\n' + '\n'.join(bad))
-  return len(bad) == 0
-
-# Returns True if docs sources have been modified
-def check_has_source_edits(commit_hash, printing=True):
-  config = {}
-  with open(f'{CUR_DIR}/duplicates.json') as config_txt:
-    config = json.loads(config_txt.read())
-  source_files = set(config.keys())
-  edited_files = set(get_edited_files(commit_hash))
-  overlap = [f'\t{f}' for f in list(source_files & edited_files)]
-  if printing and len(overlap) > 0:
-    print(f'Found edited source files:\n' + '\n'.join(overlap))
-  return len(overlap) > 0
-
-# Returns true in a given TAG is found in the commit msg
-def commit_msg_has_tag(commit_hash, tag, printing=True):
-  res, ret = execute(f'git log --pretty=%B {commit_hash}', cwd=ROOT_DIR)
-  for l in ret.split('\n'):
-    if tag == l.strip():
-      if printing:
-        print(f'Found tag={tag} in commit message')
-      return True
-  return False
-
-if __name__ == "__main__":
-  parser = ArgParseImpl()
-
-  TAG_DOCS_BYPASS = 'DOCS_BYPASS'
-  TAG_DOCS_FORCE = 'DOCS_FORCE'
-  TAG_DOCS_ALLOW_DIRECT_EDITS = 'DOCS_ALLOW_DIRECT_EDITS'
-
-  possible_conditions = {
-      'no_direct_edits':
-          check_no_direct_edits,
-      'source_edits':
-          check_has_source_edits,
-      'commit_docs_bypass':
-          lambda h: commit_msg_has_tag(h, TAG_DOCS_BYPASS),
-      'commit_docs_force':
-          lambda h: commit_msg_has_tag(h, TAG_DOCS_FORCE),
-      'commit_docs_allow_direct_edits':
-          lambda h: commit_msg_has_tag(h, TAG_DOCS_ALLOW_DIRECT_EDITS),
-  }
-
-  possible_str = ', '.join(list(possible_conditions.keys()))
-  parser.add_argument(
-      '--do-and',
-      type=str,
-      help=(
-          f'A conjunction of boolean conditions. Possible values are={possible_str}. '
-          'Negation is done with `-`'
-      )
-  )
-  parser.add_argument(
-      '--do-or',
-      type=str,
-      help=(
-          f'A disjunction of boolean conditions. Possible values are={possible_str}. '
-          'Negation is done with `-`'
-      )
-  )
-
-  args, _ = parser.parse_known_args(sys.argv[1:len(sys.argv) - 1])
-  commit_hash = sys.argv[-1]
-
-  assert not (args.do_and and args.do_or), "Must not supply both '--do-and' and '--do-or'"
-  assert args.do_and or args.do_or, "Must supply argument '--do-and' or '--do-or'"
-  conds = args.do_and.split(',') if args.do_and else args.do_or.split(',')
-  conds = [c.strip() for c in conds]
-  assert all(
-    [c in possible_conditions.keys() for c in
-     [(c.replace('-', '') if c.startswith('-') else c) for c in conds]]),\
-     f"Not all conditions are valid names. Only {possible_str} are accepted"
-
-  res = []
-  for cond in conds:
-    if cond.startswith('-'):
-      f = lambda: not possible_conditions[cond.replace('-', '')]()
-    else:
-      f = possible_conditions[cond]
-    res.append(f(commit_hash))
-
-  if args.do_and:
-    exit(0 if all(res) else 1)
-  else:
-    exit(0 if any(res) else 1)

docs_src/build/duplicates.json

@@ -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/presubmit_check.sh

@@ -1,19 +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.
-
-COMMIT_HASH=$1
-python3 docs_src/build/checks.py --do-or="no_direct_edits,commit_docs_allow_direct_edits" $COMMIT_HASH ||\
-    (echo "Direct edits to /docs are not allowed. Please see /docs_src/README.md if you need to bypass this check." && exit 1)

docs_src/build/run.py

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