Merge branch 'main' into pf/renderdiff-update-golden

BUILDING.md

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

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.15.zip > emsdk.zip
+curl -L https://github.com/emscripten-core/emsdk/archive/refs/tags/3.1.60.zip > emsdk.zip
 unzip emsdk.zip ; mv emsdk-* emsdk ; cd emsdk
 ./emsdk install latest
 ./emsdk activate latest

docs_src/.gitignore

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

docs_src/README.md

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

docs_src/book.toml

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

docs_src/build/duplicates.json

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

docs_src/build/install_mdbook.sh

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