docs: make docs more consistent and complete (#9620)

- Add documentation for specgen along with proper math rendering
- Adjust the heading size, capitalization of various READMEs.
- Add backend test README to the doc
- Rename the CI related tests to have prefix "CI:"

BUILDING.md

@@ -1,6 +1,6 @@
-## Building Filament
+# Building Filament
 
-### Prerequisites
+## Prerequisites
 
 To build Filament, you must first install the following tools:
 
@@ -18,7 +18,7 @@ To build Filament for Android you must also install the following:
 - Android NDK 25.1 or higher
 - Java 17
 
-### Environment variables
+## Environment variables
 
 To build Filament for Android, make sure the environment variable `ANDROID_HOME` points to the
 location of your Android SDK.
@@ -30,7 +30,7 @@ When building for WebGL, you'll also need to set `EMSDK`. See [WebAssembly](#web
 We recommend using CLion to develop for Filament. Simply open the root directory's CMakeLists.txt
 in CLion to obtain a usable project.
 
-### Easy build
+## Easy build
 
 Once the required OS specific dependencies listed below are installed, you can use the script
 located in `build.sh` to build Filament easily on macOS and Linux.
@@ -67,7 +67,7 @@ For more specialized options, please also consider the following pages:
  - `-t`: [`fgviewer`](https://google.github.io/filament/dup/fgviewer.html)
  - `-b` and `-y`: [ASAN/UBSAN builds](https://google.github.io/filament/notes/asan_ubsan.html)
 
-### Filament-specific CMake Options
+## Filament-specific CMake Options
 
 The following CMake options are boolean options specific to Filament:
 
@@ -89,7 +89,7 @@ cmake . -DOPTION=ON       # Replace OPTION with the option name, set to ON / OFF
 
 Options can also be set with the CMake GUI.
 
-### Linux
+## Linux
 
 Make sure you've installed the following dependencies:
 
@@ -148,7 +148,7 @@ ninja
 
 This will build Filament, its tests and samples, and various host tools.
 
-### macOS
+## macOS
 
 To compile Filament you must have the most recent version of Xcode installed and you need to
 make sure the command line tools are setup by running:
@@ -169,7 +169,7 @@ cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../release/fila
 ninja
 ```
 
-### iOS
+## iOS
 
 The easiest way to build Filament for iOS is to use `build.sh` and the
 `-p ios` flag. For instance to build the debug target:
@@ -180,9 +180,9 @@ The easiest way to build Filament for iOS is to use `build.sh` and the
 
 See [ios/samples/README.md](./ios/samples/README.md) for more information.
 
-### Windows
+## Windows
 
-#### Building on Windows with Visual Studio 2019 or later
+### Building on Windows with Visual Studio 2019 or later
 
 Install the following components:
 
@@ -225,7 +225,7 @@ You can also use CMake to invoke the build without opening Visual Studio. For ex
 cmake --build . --target gltf_viewer --config Release
 ```
 
-### Android
+## Android
 
 Before building Filament for Android, make sure to build Filament for your host. Some of the
 host tools are required to successfully build for Android.
@@ -242,13 +242,13 @@ foremost for `arm64-v8a`.
 
 To build Android on Windows machines, see [android/Windows.md](android/Windows.md).
 
-#### Important: SDK location
+### Important: SDK location
 
 Either ensure your `ANDROID_HOME` environment variable is set or make sure the root project
 contains a `local.properties` file with the `sdk.dir` property pointing to your installation of
 the Android SDK.
 
-#### Easy Android build
+### Easy Android build
 
 The easiest way to build Filament for Android is to use `build.sh` and the
 `-p android` flag. For instance to build the release target:
@@ -266,7 +266,7 @@ The output APK can be found in `android/samples/sample-hello-triangle/build/outp
 
 Run `build.sh -h` for more information.
 
-#### Android Studio
+### Android Studio
 
 You must use the latest stable release of Android Studio.
 
@@ -296,7 +296,7 @@ device's architecture. So if you are targeting a new Pixel phone, make sure that
 an emulator on a Linux machine with an x86 64-bit chipset, you would indicate (`-q x86_64`) in the above step.
 
 
-#### Manual builds
+### Manual builds
 
 Invoke CMake in a build directory of your choice, inside of filament's directory. The commands
 below show how to build Filament for ARM 64-bit (`aarch64`).
@@ -324,7 +324,7 @@ This will generate Filament's Android binaries in `out/android-release`. This lo
 to build the Android Studio projects located in `filament/android`. After install, the library
 binaries should be found in `out/android-release/filament/lib/arm64-v8a`.
 
-#### AAR
+### AAR
 
 Before you attempt to build the AAR, make sure you've compiled and installed the native libraries
 as explained in the sections above. You must have the following ABIs built in
@@ -356,7 +356,7 @@ Alternatively you can build the AAR from the command line by executing the follo
 The `-Pcom.google.android.filament.dist-dir` can be used to specify a different installation
 directory (it must match the CMake install prefix used in the previous steps).
 
-#### Using Filament's AAR
+### Using Filament's AAR
 
 Create a new module in your project and select _Import .JAR or .AAR Package_ when prompted. Make
 sure to add the newly created module as a dependency to your application.
@@ -397,7 +397,7 @@ productFlavors {
 }
 ```
 
-### WebAssembly
+## WebAssembly
 
 The core Filament library can be cross-compiled to WebAssembly from either macOS or Linux. To get
 started, follow the instructions for building Filament on your platform ([macOS](#macos) or

docs_src/build/duplicates.json

@@ -82,16 +82,22 @@
     "tools/specular-color/README.md": {
         "dest": "dup/specular_color.md"
     },
+    "tools/specgen/README.md": {
+        "dest": "dup/specgen.md"
+    },
     "docs_src/README.md": {
         "dest": "dup/docs.md"
     },
     "test/renderdiff/README.md": {
-        "dest": "dup/test_renderdiff.md",
+        "dest": "dup/test_ci_renderdiff.md",
         "link_transforms": {
             "docs/images/": "../images/"
         }
     },
     "test/backend/README.md": {
-        "dest": "dup/test_backend.md"
+        "dest": "dup/test_ci_backend.md"
+    },
+    "filament/backend/test/README.md": {
+        "dest": "dup/backend_test.md"
     }
 }

docs_src/src_mdbook/book.toml

@@ -20,3 +20,6 @@ enable = false
 
 [output.html.fold]
 enable = false
+
+[output.html.mathjax]
+enable = true

docs_src/src_mdbook/src/SUMMARY.md

@@ -30,8 +30,9 @@
     - [Performance analysis](./notes/performance_analysis.md)
   - [Framegraph](./notes/framegraph.md)
   - [Tests](./notes/tests.md)
-    - [backend](./dup/test_backend.md)
-    - [renderdiff](./dup/test_renderdiff.md)
+    - [backend](./dup/backend_test.md)
+    - [CI: backend](./dup/test_ci_backend.md)
+    - [CI: renderdiff](./dup/test_ci_renderdiff.md)
   - [Libraries](./notes/libs.md)
     - [bluegl](./dup/bluegl.md)
     - [bluevk](./dup/bluevk.md)
@@ -46,9 +47,10 @@
     - [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)
+    - [mipgen](./dup/mipgen.md)
+    - [normal-blending](./dup/normal_blending.md)
     - [roughness-prefilter](./dup/roughness_prefilter.md)
+    - [specgen](./dup/specgen.md)
     - [specular-color](./dup/specular_color.md)
     - [zbloat](./dup/zbloat.md)

libs/bluevk/README.md

@@ -1,3 +1,5 @@
+# bluevk
+
 ## Updating Vulkan headers
 
 To update the Vulkan headers, perform the following steps.

libs/gltfio/README.md

@@ -1,4 +1,4 @@
-# Description
+# gltfio
 
 `gltfio` is a loader library that consumes `gltf` or `glb` content and produces Filament
 objects. For usage details, see the docstring for `AssetLoader`.

libs/uberz/README.md

@@ -1,7 +1,4 @@
-- [Ubershader Archive Files](#ubershader-archive-files)
-- [Ubershader Spec Files](#ubershader-spec-files)
-
-# Ubershader Archive Files
+# uberz
 
 An ubershader archive provides a way to bundle up a set of `filamat` files along with some metadata
 that conveys which glTF features each material can handle. It is a file that has been compressed

tools/filamesh/README.md

@@ -1,4 +1,4 @@
-# Filamesh
+# filamesh
 
 `filamesh` converts any mesh file supported by `assimp` (as configured in this source tree) into a
 custom binary file format. The goal of this binary file format is to allow test applications to

tools/matinfo/README.md

@@ -1,4 +1,4 @@
-# Matinfo
+# matinfo
 
 `matinfo` lists the content of a compiled material as output by `matc`. This tool is meant to be
 used for debug purpose only.

tools/specgen/README.md

@@ -0,0 +1,87 @@
+# SPECGEN: Spectral Integration Matrix Generator for Real-Time Dispersion
+
+## Theoretical Background
+
+### 1. Spectral Rendering in RGB
+
+Real-time rendering typically operates in a tristimulus color space (like sRGB). However, physical phenomena like dispersion (refraction splitting light by wavelength) are inherently spectral. To simulate this in an RGB pipeline, we approximate the continuous spectral integration using a finite sum of weighted samples.
+
+The fundamental equation for perceived color \\(C\\) is:
+
+$$ C = \int L(\lambda) \cdot r(\lambda) d\lambda $$
+
+where:
+*   \\(L(\lambda)\\) is the spectral radiance reaching the eye.
+*   \\(r(\lambda)\\) is the sensor response function (e.g., CIE 1931 \\(\bar{x}, \bar{y}, \bar{z}\\) matching functions).
+
+### 2. Basis Transformation Strategy
+
+We assume the input light is defined in linear sRGB. To process it spectrally:
+
+1.  Convert sRGB to CIE XYZ (D65 white point).
+2.  Assume the spectral distribution of the light is a sum of impulses or narrow bands weighted by the XYZ components (or simplified directly from sRGB).
+3.  Apply spectral effects (like wavelength-dependent refraction).
+4.  Integrate back to XYZ using the CIE Color Matching Functions (CMFs).
+5.  Convert final XYZ back to sRGB.
+
+This tool pre-calculates a set of matrices (\\(K_n\\)) that combine these steps. For a set of \\(N\\) sample wavelengths \\(\{ \lambda_0, \dots, \lambda_{N-1} \}\\), the final color is:
+
+$$ C_{final} = \sum_{n=0}^{N-1} (K_n \cdot C_{input}) $$
+
+Each matrix \\(K_n\\) represents the contribution of the \\(n\\)-th spectral sample to the final image, accounting for the conversion to/from XYZ and the spectral weight of that sample.
+
+**Derivation of \\(K_n\\):**
+
+$$ K_n = M_{XYZ \to sRGB} \cdot \text{Diag}(W_n) \cdot M_{sRGB \to XYZ} $$
+
+where \\(W_n\\) is the "spectral weight" vector \\((x, y, z)\\) for wavelength \\(\lambda_n\\):
+
+$$ W_n = \text{CMF}(\lambda_n) \cdot \text{weight}_n $$
+
+### 3. Normalization (Energy Conservation)
+
+To ensure that a white input \\((1, 1, 1)\\) results in a white output \\((1, 1, 1)\\) when no dispersion occurs (i.e., all samples land on the same pixel), we must normalize the weights.
+
+We require: \\(\sum K_n = I\\)
+
+This implies:
+
+$$ \sum ( M_{XYZ \to sRGB} \cdot \text{Diag}(W_n) \cdot M_{sRGB \to XYZ} ) = I $$
+$$ M_{XYZ \to sRGB} \cdot \sum \text{Diag}(W_n) \cdot M_{sRGB \to XYZ} = I $$
+$$ \sum \text{Diag}(W_n) = M_{sRGB \to XYZ} \cdot I \cdot M_{XYZ \to sRGB} $$
+$$ \sum \text{Diag}(W_n) = I $$
+*(since \\(M \cdot M^{-1} = I\\))*
+
+Therefore, we normalize \\(W_n\\) such that:
+
+$$ \sum W_{n,x} = 1.0, \quad \sum W_{n,y} = 1.0, \quad \sum W_{n,z} = 1.0 $$
+
+**Note:** We do **NOT** normalize to the D65 white point \\((0.95047, 1.0, 1.08883)\\). The \\(M_{sRGB \to XYZ}\\) matrix already handles the conversion from linear sRGB \\((1, 1, 1)\\) to D65 XYZ. If we normalized \\(W_n\\) to D65, we would effectively be applying the white point twice, resulting in a tinted image. By normalizing \\(\sum W_n\\) to \\((1, 1, 1)\\), we ensure that the energy is conserved through the spectral transformation pipeline.
+
+In practice, we calculate the raw sum of \\(W_n\\) from the quadrature weights and CMFs, then compute a correction factor:
+
+$$ \text{Correction} = \frac{1.0}{\sum W_{n,raw}} $$
+$$ W_{n,final} = W_{n,raw} \cdot \text{Correction} $$
+
+### 4. Dispersion and IOR Offsets
+
+The Index of Refraction (IOR) varies with wavelength. We use the Abbe number (\\(V_d\\)) to parameterize this variation relative to a base IOR (\\(n_D\\)) at 589.3nm.
+
+**Cauchy Dispersion Model:**
+
+$$ n(\lambda) = A + \frac{B}{\lambda^2} $$
+
+Using the definition of Abbe number \\(V_d = \frac{n_D - 1}{n_F - n_C}\\), we can derive:
+
+$$ n(\lambda) = n_D + \frac{n_D - 1}{V_d} \cdot \text{Offset}(\lambda) $$
+
+Where \\(\text{Offset}(\lambda)\\) is pre-calculated by this tool:
+
+$$ \text{Offset}(\lambda) = \frac{ \frac{1}{\lambda^2} - \frac{1}{\lambda_D^2} }{ \frac{1}{\lambda_F^2} - \frac{1}{\lambda_C^2} } $$
+
+This allows the shader to compute the specific IOR for each sample efficiently:
+
+```glsl
+float ior_n = baseIOR + dispersionFactor * offsets[n];
+```
+