@meimu/mutracer 0.3.0 → 0.3.1

package/docs/api.md

@@ -127,6 +127,7 @@ other sequences retain their completed samples.
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `maxSamples` | `2048` | Complete sample budget |
+| `aovResolution` | `'render'` | `'display'` traces AOVs at canvas size on WebGPU, capped at 4 samples regardless of `aovSamples`; requires a scale-based render. WebGL falls back with one warning |
 | `aovs` / `aovSamples` | `[]` / `16` | Optional [surface outputs](#surface-outputs) / independent positive integer sample cap |
 | `bounces` / `clamping` | `3` / `0` | Scattering depth / per-sample radiance clamp; 0 disables clamping |
 | `samplingPattern` | `'sobol'` | Sobol, ZSobol or random; see [sampling](./sampling.md) |
@@ -144,8 +145,9 @@ other sequences retain their completed samples.
 | `fallback` | `null` | Single-level Render on the same engine |
 | `denoiser` | `null` | Per-render configuration; read back through the frozen `denoiser` getter and change with `setDenoiser()`; see [denoising](./denoising.md) |
 
-`bounces` is rounded and clamped to [1, 20] in both backends; NaN becomes 1.
-Paths allow at most `min(bounces * 3, 20)` events, including transmission,
+`bounces` is rounded and clamped to [1, 50] on WebGPU or [1, 20] on WebGL;
+NaN becomes 1. Paths allow at most `min(bounces * 3, 50)` events on WebGPU
+or `min(bounces * 3, 20)` on WebGL, including transmission,
 alpha skips and escape checks. Opaque paths also terminate at their scattering
 limit. The event budget can truncate deep transparent paths before the requested
 scattering depth. On Intel Mac WebGL, the event limit is `min(bounces, 3)`, doubled
@@ -350,9 +352,20 @@ const depth = await render.readPixels('depth'); // Float32Array, RGBA
 const ids = await render.readPixels('id');      // Uint32Array, RGBA
 ```
 
-You can change `render.aovs` or `render.aovSamples` after sampling. Continue
+You can change `render.aovs`, `render.aovSamples` or `render.aovResolution` after sampling. Continue
 calling `refine()` to regenerate AOVs for the current view; beauty samples and
-completed denoising are preserved. AOV accumulation restarts when either changes.
+completed denoising are preserved. AOV accumulation restarts when any of them changes.
+
+To keep beauty at reduced resolution while reading or displaying full-resolution
+surface outputs, set `aovResolution: 'display'` on a scale-based render. The
+default is `'render'`. AOV readbacks and visualization use their own dimensions;
+beauty and denoiser guides keep the render dimensions. Both modes stop at
+`min(samples, aovSamples)`; display mode also caps at 4, follows canvas resizes,
+and rejects fixed-size renders. During tracing, display mode starts after the first
+beauty sample and adds one AOV sample per frame; the frame that reaches
+`maxSamples` completes the rest. WebGL falls back to render dimensions and warns
+once per render. Each kind has the same meaning in both modes.
+Custom denoiser AOV inputs require `'render'` resolution.
 
 | Kind | RGBA contents |
 | --- | --- |
@@ -361,13 +374,14 @@ completed denoising are preserved. AOV accumulation restarts when either changes
 | `roughness` | Specular roughness, metalness, unsupported-reflectance fraction, coverage |
 | `diffuseAlbedo` | Directional-hemispherical diffuse reflectance RGB, valid coverage |
 | `specularAlbedo` | Directional-hemispherical specular reflectance RGB, valid coverage |
+| `diffuseColor` | Diffuse texture color: base weight × base color × (1 − metalness), tinted by coat color; valid coverage |
+| `specularColor` | Specular texture color: metal base color plus dielectric specular color × F0, tinted by coat color; valid coverage |
 | `id` | Object, local instance (0 for ordinary meshes), material, source triangle index; background is `0xFFFFFFFF` in all channels |
 | `motion` | Previous position minus current position in pixels, x right and y down; z = 0, alpha = 3 for valid history or 0 otherwise |
 
-Depth, position, roughness and reflectance average independent jittered primary
-rays, including depth of field, up to `min(samples, aovSamples)`. RGB values use
-hit-count normalization; alpha is hit coverage over all AOV samples. Reflectance
-uses only supported hits for both normalization and valid coverage. A blank pixel
+Depth, position, roughness, reflectance and color average independent jittered primary
+rays, including depth of field. RGB values use hit-count normalization; alpha is hit coverage over all AOV samples. Reflectance
+and color use only supported hits for both normalization and valid coverage. A blank pixel
 is zero. These passes preserve beauty samples but do not sample the same paths.
 Alpha holes use the first surface with alpha ≥ 0.5, skipping shadow catchers,
 with at most 32 layers.
@@ -392,14 +406,23 @@ Reflectance outputs are separate from the existing OIDN `albedo` guide.
 Coat, fuzz, anisotropy, subsurface/volume scattering, bevel, thin film,
 dispersion, partial alpha and nonstandard materials are unsupported by this
 reflectance estimate. Such hits contribute to `roughness.b` and have zero
-reflectance validity. Reflectance uses expensive BSDF quadrature; request it
-only when needed.
+reflectance validity. Reflectance tracing can be expensive; request it only when needed.
+
+`diffuseColor` and `specularColor` read resolved material inputs without
+integrating the BSDF, so they are cheap. They support coat, fuzz and anisotropic
+surfaces; transmission, partial alpha, media and nonstandard materials have zero
+color validity. A render can request `diffuseAlbedo` or `diffuseColor`, not both;
+the same applies to `specularAlbedo` and `specularColor`.
 
 Reading a kind absent from `render.aovs` rejects. A custom denoiser can request
 its own [AOV inputs](./denoising.md#custom-denoisers). With neither request there
-are no AOV allocations or passes. Enabling any kind costs about 128 GPU bytes
-per pixel on WebGPU or 192 on WebGL, plus scene identity/history data; each
-custom denoiser AOV snapshot adds 16 bytes per pixel. A render may retain one
+are no AOV allocations or passes. Enabling any kind normally costs about 128 GPU bytes
+per AOV pixel on WebGPU or 192 on WebGL, plus scene identity/history data.
+WebGPU display mode requesting only `depth`, `diffuseColor` and/or `specularColor` costs
+24 bytes per pixel plus small scene metadata; borrowing all three GPU textures
+adds another 24 bytes per pixel (about 288 MB total at 6 MP). Its color
+accumulation has half precision. Other AOV selections use the full allocation;
+each custom denoiser AOV snapshot adds 16 bytes per pixel. A render may retain one
 reusable snapshot per kind between denoising calls. Readback adds a CPU copy.
 WebGPU dimensions remain subject to device buffer limits. A full-frame AOV
 sample runs independently of tile/adaptive sampling and may exceed the render's
@@ -421,7 +444,7 @@ const png = await engine.display.toBlob(render);
 | `depth` | Black at the near depth, white at the far depth, clamped outside the range |
 | `position` | World xyz mapped to RGB; origin is 0.5 and ±position scale maps to 0/1 |
 | `roughness` | RGB = roughness, metalness, unsupported-reflectance fraction |
-| `diffuseAlbedo`, `specularAlbedo` | Linear reflectance RGB clamped to [0, 1], then sRGB encoded |
+| `diffuseAlbedo`, `specularAlbedo`, `diffuseColor`, `specularColor` | Linear RGB clamped to [0, 1], then sRGB encoded |
 | `id` | Stable pseudocolor for the selected uint32 ID component; colors can collide |
 | `motion` | Direction as hue (+x is red, +y is yellow-green), displacement/scale as brightness |
 
@@ -598,10 +621,14 @@ see [denoising](./denoising.md#custom-oidn-networks). The main entry exports
 ## GPU output and display passes
 
 `render.getOutputTexture(kind)` borrows native HDR or the latest display image;
-`display.addPostProcess(pass)` returns unregister and runs on every present/export.
-Both are WebGPU-only. Textures are rounded up to multiples of 16 pixels, so a
-fixed render's texture can include extra pixels around the requested image. See
-[formats, lifecycle and overlay example](./post-processing.md).
+`render.getAovTexture('diffuseColor' | 'specularColor' | 'depth')` borrows raw
+linear AOV textures at their own resolution after sampling; WebGL returns undefined.
+`display.addPostProcess(pass, options?)` returns unregister and runs on every present/export.
+Both are WebGPU-only. `options.outputSize` defaults to preserving input dimensions;
+the final display texture and export can differ from the render size. Fixed renders
+are cropped to their requested rectangle before export passes. HDR textures can
+include extra pixels around a fixed render's requested image. See
+[formats, lifecycle, EASU upscale and overlay examples](./post-processing.md).
 
 Anisotropy direction options: `anisotropyMap` (default `undefined`) reads linear RG as a tangent direction and B as a multiplier for base specular strength. `specularAnisotropyRotation` (default `0`) rotates that direction counter-clockwise in radians; `coatAnisotropyRotation` (default `0`) rotates the coat relative to the geometry tangent. See [materials](./materials.md#anisotropy-directions) for frame and fallback conventions.
 

package/docs/materials.md

@@ -51,12 +51,14 @@ the textures they reference still share atlas space.
 
 Units: `transmissionDepth` and `subsurfaceRadius` are in scene units;
 `thinFilmThickness` is in micrometres (`0.45` = 450 nm).
+Subsurface materials with short scattering radii may appear darker than in earlier releases.
 
 `baseWeight` scales diffuse reflection and the metallic normal-incidence color
 (`baseWeight * baseColor`). Dielectric specular, transmission and subsurface
 retain their own strengths. For metals, `specularColor` tints the F82 Fresnel
 curve near grazing angles and `specularWeight` scales the entire reflection,
 including thin-film reflection. At their default values, F82 reduces to Schlick.
+Low-roughness metals may appear slightly darker under broad lighting than in earlier releases.
 
 Native `specularRoughnessAnisotropy` and `coatRoughnessAnisotropy` use the OpenPBR GGX mapping:
 `alphaT = roughness² * sqrt(2 / (1 + (1 - anisotropy)²))` and
@@ -129,7 +131,7 @@ an alternate serialization format.
 | --- | --- | --- |
 | `map` | RGB (sRGB), A | Multiplies `baseColor`; alpha use set by `mapAlphaUsage` |
 | `alphaMap` | G | Opacity, as in Three.js |
-| `normalMap`, `normalScale` | RGB | Tangent space; tangents are generated when missing |
+| `normalMap`, `normalScale` | RGB | Tangent space; uses triangle UV derivatives |
 | `metallicRoughnessMap` | G = roughness, B = metalness | glTF convention |
 | `roughnessMap` | G | |
 | `metalnessMap` | B | |
@@ -288,6 +290,6 @@ Set `specularAnisotropyRotation` or provide `anisotropyMap` to orient the base s
 
 `coatAnisotropyRotation` defaults to zero and uses the geometry tangent independently of the base map. Base and coat use their respective directions and [normals](#coat-normals). Zero anisotropy strength ignores the direction.
 
-Provided tangent XYZ and optional W handedness are preserved. For XYZ tangents the sign comes from triangle UV derivatives. Missing or degenerate tangents use UV derivatives and then a stable orthonormal fallback; missing tangents produce one diagnostic per geometry. The direction texture's selected UV set is used for derivative fallback, including UV1. A provided XYZW tangent remains authoritative. Directions are reorthogonalized against the final shading normal, including normal maps and back faces, and instance transforms preserve mirrored handedness. UV scale, offset and flipY affect texel lookup; they do not rotate the encoded direction.
+Provided tangent XYZ and optional W handedness are preserved. Missing tangents are generated from primary UVs only when a material using the geometry needs anisotropy or an active coat normal map; adding such a material prepares them automatically. For XYZ tangents the sign comes from triangle UV derivatives. Missing UVs or degenerate tangents use UV derivatives where available and then a stable orthonormal fallback. The direction texture's selected UV set is used for derivative fallback, including UV1. A provided XYZW tangent remains authoritative. Directions are reorthogonalized against the final shading normal, including normal maps and back faces, and instance transforms preserve mirrored handedness. UV scale, offset and flipY affect texel lookup; they do not rotate the encoded direction.
 
 The direction and strength inputs use native OpenPBR semantics by default. For imported glTF/Three.js strength, select `specularAnisotropyModel: 'gltf'`; the same roughness and strength properties then retain source values. Source scalar inputs are clamped to [0, 1] before texture factors; non-finite source roughness/strength fall back to 0.3/0. Native scalar handling is unchanged. Zero source strength preserves the original roughness path. The conversion matches the GGX alpha axes before existing minimum-alpha clamping; Fresnel, masking, multiple scattering and OpenPBR coating remain the library's model. See [the conversion rules](./threejs.md#anisotropy-source-conversion).

package/docs/performance.md

@@ -38,6 +38,13 @@ A tuning checklist. Each item links to the page with the details.
 - Textures share an atlas bounded by `textureAtlasBudgetBytes`; larger textures
   are downscaled. Check `engine.getDiagnostics()?.textureAtlas`.
 
+WebGPU quantizes vertex normal and tangent directions; scenes with displacement
+retain full normal precision. Vertex RGB values in
+`[0, 1]` have at most `1/510` absolute error per channel; scenes containing
+negative or HDR vertex colors retain float32 RGB instead. Positions and UV
+coordinates retain float32 precision. Large scenes still depend on the device's
+buffer limits and the browser's available CPU memory.
+
 ## Animation and editing
 
 See [scene updates](./updates.md) for the cost of each kind of edit.

package/docs/post-processing.md

@@ -18,8 +18,9 @@ remove(); // Safe to call again.
 
 Passes run in registration order on every `present()` and `toBlob()`, after
 composition and denoising. They receive the selected complete render, including
-fallbacks, at its actual dimensions. Export uses the same chain without resizing
-or changing the display canvas. `readPixels()` never runs these passes.
+fallbacks, at its actual dimensions. Export uses the same chain without changing
+the display canvas; fixed-size renders are cropped to their requested size before
+entering the chain. `readPixels()` never runs these passes.
 
 For a complete overlay implementation, see
 [`createCrosshairPass`](../examples/shared/crosshairPass.ts). It loads the input
@@ -35,12 +36,55 @@ A changing overlay can read application state in its callback. `RenderLoop`
 stops presenting after convergence, so explicitly call `display.present(final)`
 when that state changes. This refreshes the overlay without tracing more samples.
 
+For edge-adaptive enlargement without sharpening:
+
+```ts
+import {createEasuPass} from '@meimu/mutracer';
+const pass = createEasuPass();
+const removeUpscale = engine.display.addPostProcess(pass, {
+  outputSize: (_, display) => display
+});
+```
+
+Register the upscale before overlays that should stay at canvas resolution. An
+input that already has the output size is copied unchanged and a larger one is
+area-averaged, so one registration can serve a full-resolution or supersampled
+final render and a reduced-resolution preview.
+
+To recover texture detail, enable `diffuseColor`, `specularColor` and `depth`
+on a scale-based render with `aovResolution: 'display'`, and create the pass with
+`createEasuPass({albedoDetail: true})`. Keep beauty at the desired reduced
+`resolutionScale`. Unregister the pass, then call `pass.dispose()` when finished
+to release its scratch images.
+
+EASU works on display-encoded RGB after tone mapping, including extended-range
+output, and preserves alpha. EASU alone cannot recover missing texture detail.
+Albedo compensation recovers supported surface texture detail but cannot recover
+reflection, refraction or geometric detail. It maps the displayed image back
+through the display transform, estimates locally how much radiance follows albedo,
+and changes only that part, so specular highlights mostly keep their brightness.
+Clipped highlights cannot be recovered. Transmission, cutouts, background, low
+coverage and depth boundaries receive EASU alone. With detail, a present costs about
+2.6 ms at 6 MP on an Apple M4 Max, compared with about 0.5 ms for EASU alone.
+
 ## Options and image semantics
 
 `getOutputTexture(kind)` requires `'hdr'` or `'display'`; both return undefined
 on WebGL, before a complete sample or after disposal. There are no passes by
 default. `addPostProcess(pass)` returns an idempotent unregister function.
-`PostProcess` and `PostProcessContext` are exported types.
+`PostProcess`, `PostProcessContext` and `PostProcessOptions` are exported types.
+
+Use `addPostProcess(pass, {outputSize: (input, display) => display})` to output
+at canvas resolution. The default preserves the input dimensions. Each callback
+receives the previous pass's dimensions and the current canvas dimensions, also
+for `toBlob()`. A chain can change size more than once. Return positive integer
+width and height within `device.limits.maxTextureDimension2D`; invalid dimensions
+discard the whole chain and emit an engine error, as callback exceptions do.
+
+`ctx.width` and `ctx.height` remain the actual render dimensions. Read
+`ctx.input.width/height` and `ctx.output.width/height` for the pass dimensions.
+`toBlob()` exports the final chain dimensions; `getOutputTexture('display')`
+borrows that actual-sized image, which may differ from the render size.
 
 | Image | Meaning |
 | --- | --- |
@@ -59,6 +103,21 @@ by primary-hit coverage for partially hit pixels, restoring the per-sample
 average. Thus that CPU readback can differ from the borrowed native HDR texture.
 See [custom denoiser image semantics](./denoising.md#custom-denoisers).
 
+`createEasuPass()` defaults to EASU alone. `albedoDetail` defaults to `false`.
+When the displayed render lacks those AOVs or display resolution, the pass warns
+once and upscales without detail; frames whose AOVs are not ready yet or differ
+from the output size also use EASU alone. The optional AOVs add tracing and
+memory cost; see [surface outputs](./api.md#surface-outputs).
+
+`render.getAovTexture(kind)` borrows enabled `diffuseColor`, `specularColor` or
+`depth` outputs after an AOV sample completes, only on WebGPU. Colors use
+`rgba8unorm-srgb`, which loads as linear values in [0, 1], with valid coverage in
+alpha; depth uses `rg32float`, with
+camera-forward depth in red and hit coverage in green. These raw textures follow
+the same borrowing lifetime as `getOutputTexture()` and have the AOV dimensions.
+Each is resolved from the accumulation when its samples change, and the first
+call for a kind also creates its pipeline.
+
 ## Caveats
 
 Textures are borrowed and read-only. Do not retain, write or destroy returned
@@ -79,9 +138,3 @@ discards the chain's recorded commands, displays the original composed image
 and emits the engine `error` event. GPU validation errors remain WebGPU errors;
 the callback must record valid commands.
 
-## Implementation notes
-
-The composed image is kept separately, so a thrown callback cannot leave a
-partly processed result.
-Display passes do not enter denoiser inputs, change samples or invalidate cached
-filter results. HDR-stage callbacks are outside this API.

package/docs/progressive-rendering.md

@@ -146,6 +146,9 @@ camera edits discard an unfinished sample and restart against the new inputs.
 `maxTiles` caps the sample's tile grid (rounded up to a rectangular grid), so a
 smaller value makes larger tiles. It does not cap work per frame or per call;
 use `timeBudgetMs` and the between-frame deadline to control queued work.
+With GPU timing available, WebGPU can keep tiles above `timeBudgetMs` when the
+budget cannot be reached or further subdivision brings little speedup. This limits
+extra offline rendering cost while allowing longer pauses between updates.
 
 ## Reading and exporting
 

package/docs/sampling.md

@@ -23,6 +23,10 @@ render.samplingPattern = 'zsobol';
   `sampleSequenceOffset`. Use disjoint offset ranges for animation frames.
 - **Backends**: WebGPU and WebGL 2 can differ in floating-point rounding even
   with identical sequence points.
+- **Dispersion**: on WebGPU, `dispersionWavelengths: 3` with
+  `directLightCandidates > 1` can need more samples in individual RGB channels
+  under strongly colored lighting and materials. Lower overall noise does not
+  guarantee lower noise in every channel.
 - **Fireflies**: very narrow specular lobes under directional lights can
   produce rare, large contributions with any pattern. Sampling does not clamp
   them; use `render.clamping` if needed.

package/docs/technical/acceleration.md

@@ -0,0 +1,52 @@
+# Acceleration structures
+
+The renderer traces a two-level hierarchy: one bottom-level BVH (BLAS) per geometry
+and a top-level BVH (TLAS) over mesh instances. Builders, layouts and preparation
+are documented in the [BVH guide](../bvh.md); this note records the choices behind
+the defaults and the alternatives that were measured. The code is
+`src/renderer/bvhAccel.ts` and `binnedSahBvh.ts`.
+
+## TLAS
+
+- **Builder.** The TLAS always uses the built-in binned SAH builder, a JavaScript
+  port of TinyBVH's `BVH::Build`, built and refitted on the calling thread.
+- **Bins.** The web TLAS uses 64 SAH bins (`WEB_TLAS_BINS`); native keeps 8. More
+  bins separate overlapping static instances in scenes with many instances.
+  Higher instance costs, exact SAH and forced fallbacks were compared and not
+  adopted. The rebuilt tree can pick a different object at coincident faces, which
+  changes `id` AOVs there; other AOVs matched, and HDR differed only by rounding.
+- **Instance bounds.** Each instance's world bounds, padded by displacement, are
+  stored after the TLAS. Leaf traversal tests them before transforming the ray
+  into the BLAS's space, so a ray that misses an instance skips the transform and
+  the BLAS root test. Both web backends and the caustic kernel use them.
+
+## BLAS
+
+- **Defaults.** The BVH2 layout with spatial splits off stays the default after a
+  matrix of builder, layout and split settings. CWBVH was slower on the measured
+  scenes despite its smaller nodes. Spatial splits help some scenes at three to
+  five times the build time, so they stay opt-in.
+- **Traversal tweaks.** Changes to box tests and stack handling showed no reliable
+  gain and were not adopted.
+
+## Static merge prototype
+
+A prototype merged static instances into one world-space BLAS, with world-space
+triangle bounds and vertex tests in local space. It was faster on a heavy
+many-instance scene, but:
+
+- coincident geometry needs the old tree as a fallback to keep object identity,
+  which costs memory and cold build time;
+- HDR and legacy guides differ by rare rounding, and subsurface scattering, alpha
+  random streams, instance colors and picking were not verified;
+- incremental updates and the choice of which instances count as static are
+  undesigned.
+
+It is not in production. Pursuing it needs both web layouts, an update strategy and
+those verifications, then a native port and comparison.
+
+## Changing this code
+
+- TLAS and BLAS changes affect `id` AOVs and picking at ties; compare those as well
+  as HDR.
+- Keep native's TLAS parameters unless native is aligned in a separate change.

package/docs/technical/aovs.md

@@ -0,0 +1,79 @@
+# Surface color AOVs
+
+MuTracer has two pairs of surface color outputs. `diffuseAlbedo` and
+`specularAlbedo` report how much light a surface reflects. `diffuseColor` and
+`specularColor` report the material colors that produce it. Usage and the exact
+definitions are in [surface outputs](../api.md#surface-outputs); this note explains
+why both pairs exist, how they are named and how they are stored.
+
+## Reflectance and color
+
+The albedo kinds are directional-hemispherical reflectance: the fraction of
+uniform incident light that the prepared OpenPBR BSDF reflects toward the view
+direction. They integrate the BSDF by quadrature (`aovReflectance*.wgsl.ts` and
+`.glsl.ts`), so they cost more than the other outputs and support only materials
+the quadrature models. Coat, fuzz, anisotropy and similar hits are marked
+unsupported.
+
+The color kinds read resolved material inputs without integration:
+
+- diffuse: base weight × base color × (1 − metalness)
+- specular: metalness × base weight × base color + (1 − metalness) ×
+  specular weight × specular color × F0, with F0 from the specular IOR
+
+Both are multiplied by the coat color, weighted by the coat weight. Transmission,
+partial alpha, media and nonstandard materials have zero validity.
+
+EASU detail recovery needs the color kinds, not reflectance. It compares
+display-resolution colors with their average over each render pixel and scales
+the part of the upscaled radiance that follows color by that ratio. Layer factors
+that are uniform across a surface, such as coat or fuzz, cancel in the ratio, so
+the cheap estimate covers more surfaces than the quadrature does. Reflectance
+remains the right input for compositing and other uses that need reflected energy.
+
+## Names
+
+Renderers use "albedo" for both quantities:
+
+| Renderer | Integrated reflectance | Material color |
+| --- | --- | --- |
+| [MoonRay](https://docs.openmoonray.org/user-reference/how-to-guides/render-outputs/material-aovs/) | `albedo`: response to unoccluded white light from all directions | `color` |
+| [Mitsuba 3](https://mitsuba.readthedocs.io/en/stable/src/generated/plugins_integrators.html) | `albedo`: diffuse reflectance, approximate for some materials | none |
+| [Arnold](https://help.autodesk.com/cloudhelp/ENU/AR-Core/files/ac-output-aovs/arnold_user_guide_ac_output_aovs_ac_aovs_html.html) | none | `diffuse_albedo`, `specular_albedo`: colors without lighting |
+| [Cycles](https://docs.blender.org/manual/en/latest/render/layers/passes.html) | none | `Diffuse Color`, `Glossy Color`: BSDF color weights |
+| V-Ray, Redshift | none | `Diffuse Filter` |
+
+MuTracer's names match MoonRay: albedo for integrated reflectance, color for
+material inputs. Albedo for reflectance also matches Mitsuba and the
+"directional albedo" of energy compensation work. Arnold uses albedo for colors,
+so documentation always states the definition next to the name. No surveyed
+renderer names an AOV "reflectance"; the viewer uses it only in labels.
+
+These outputs are separate from the OIDN `albedo` guide, which follows its own
+path rules for denoising.
+
+## Storage
+
+The WebGPU accumulation has four `vec4f` lanes per pixel (`AOV_LAYOUT`):
+depth with roughness, position with hit count, diffuse and specular. A lobe's
+albedo and color share its lane, selected per kind by mask bits 3–4 and 7–8, so a
+render may request only one of them per lobe. Resolve, display and snapshot shaders
+see a color kind as the albedo kind of its lane (`aovLaneKind`), so they need no
+color-specific code. Separate lanes would add 32 bytes per pixel to every AOV
+render. If both are ever needed together, adding lanes lifts the restriction
+without changing the API.
+
+Display-resolution renders requesting only `depth`, `diffuseColor` and
+`specularColor` use a compact 24-byte layout: float depth and hit count, plus two
+colors in half precision. It skips the center pass, so it has no ID or motion.
+Half-precision sums lose precision as the sample count grows, which is acceptable
+only because display resolution stops at 4 samples (`DISPLAY_AOV_SAMPLE_CAP`).
+For detail recovery, 4 jittered samples matched 16 within measurement noise.
+Render resolution keeps the full layout for any request.
+
+## Native
+
+Native shares `aovTraceDisplay.wgsl.ts` but still requests display-resolution
+colors through the albedo bits with the `AOV_DISPLAY` override. The web build never
+sets that override. Native should adopt the color kinds when it is next aligned
+with web AOVs.

package/docs/technical/caustics.md

@@ -0,0 +1,109 @@
+# Caustic estimators
+
+Path tracing finds caustics only when a BSDF sample happens to hit the light
+through a smooth surface, because shadow rays treat glass as an occluder. MuTracer
+adds two WebGPU estimators for those paths: light tracing and progressive photon
+mapping. Usage, costs and limits are in the [caustics guide](../caustics.md); this
+note explains how the paths are divided and how the estimators work.
+
+## Path partition
+
+A surface is *smooth* when `isCausticSpecular` holds: no diffuse, subsurface, fuzz
+or coat weight, and specular roughness at most `CAUSTIC_ROUGHNESS_MAX` (0.1). The
+test depends only on the material, never on the lobe a sample chose, so every
+estimator classifies a vertex the same way (`src/renderer/caustics.ts`).
+
+Counting from the light, the *receiver* is the first non-smooth surface vertex, k is
+the number of smooth vertices between the light and the receiver, and the *camera
+prefix* is the path from the camera to the receiver. Surfaces skipped through alpha
+are not vertices.
+
+| Paths | Estimator |
+| --- | --- |
+| k = 0 | Path tracing, unchanged |
+| k ≥ 1, empty camera prefix (the camera sees the receiver directly), light tracing on | Light tracing |
+| Other k ≥ 1, photon mapping on | Photon mapping |
+| Anything else | Path tracing's BSDF hits |
+
+Path tracing tracks the smooth chain length and whether the receiver is the first
+visible surface. When it hits a light on a path that an enabled estimator owns, the
+contribution is zero. Each path is therefore counted by exactly one estimator.
+When an estimator is off or unsupported (WebGL 2), its rows fall back to path
+tracing, so every configuration has the same expected image and differs only in
+noise. Scenes whose smooth casters use stochastic blend coverage turn both
+estimators off, because their photon transport does not yet match path-tracing
+energy.
+
+## Casters and emission
+
+The renderer collects caster meshes and instances automatically from smooth
+materials, with one conservative world-space sphere per instance. Photons are
+emitted only toward caster spheres: a path whose first surface from the light is
+not smooth belongs to path tracing, so restricting emission loses no estimator's
+paths. Emission samples the full light surface, then accepts directions toward
+the caster mixture; the direction PDF accounts for overlapping cones
+(`casterDirectionPdf`). Lights are chosen by a separate power PMF, not the NEE
+selection table (`causticEmission.ts`). Directional and environment light emit
+from a mixture of projected caster disks.
+
+## Light tracing
+
+Light tracing is BDPT's t = 1 strategy. Photons follow smooth vertices with adjoint
+BSDF corrections. At the receiver, the pass samples a lens point, connects to the
+camera, tests visibility and splats into the pixel with float32 compare-and-swap
+atomics. It runs once per sample batch, after the last tile, in its own pass and
+bind group, because the main integrator already uses the baseline eight storage
+buffers. The result accumulates separately; resolve adds it to the path-traced
+radiance, so readback, denoising and display see the combined image. Adaptive
+sampling measures variance only on the path-traced part.
+
+## Photon mapping
+
+Photon mapping uses probabilistic progressive photon mapping (Knaus and Zwicker
+2011). Each sample batch emits a new photon map on the first tile, which later tiles
+reuse. The gather radius shrinks as r_i = r_1 · i^((α − 1)/2) with α = 2/3
+(`photonRadius`). The first radius is `initialRadius`, or 3% of the caster sphere
+radius. At the first non-smooth camera vertex the radius is further limited to
+about two projected pixels (`photonVisibleRadius`); mirror prefixes use an
+approximate footprint, and deeper vertices use the global radius. The pixel cap
+reduces blotches after denoising, at the cost of grainier raw output.
+
+Photons are stored at the first non-smooth surface after at least one smooth
+vertex, whatever camera prefix will later find them; queries at directly visible
+receivers skip them when light tracing owns those paths. Camera paths query at every non-smooth vertex within `bounces`, with a
+normal-consistent surface kernel.
+
+Each photon takes 20 bytes: float32 position and RGBE8 flux, and two octahedral
+directions (incident direction and normal). Two hash-grid layers with different
+cell sizes, one for first visible receivers and one for deeper queries, each sort
+only a 4-byte index, for 28 bytes per photon. Grids are rebuilt every batch with a
+count, a two-level parallel prefix sum and a scatter; bucket counts are powers of
+two up to 262144. Batches are reduced to fit device limits and a 128 MiB budget.
+
+Quantized flux and directions limit precision. More batches shrink the radius
+but do not remove that error, so photon mapping is consistent only up to storage
+precision.
+
+## Rejected and paused work
+
+- **MNEE and SMS** (manifold next-event estimation and specular manifold sampling)
+  are paused and excluded from builds. Behind a wavy refractive surface, each
+  receiver can have dozens of manifold roots; Newton's method finds one, and SMS
+  with its 64-trial cap covered only part of their weight, so neither converged
+  to an unbiased result. The code remains in
+  `src/research/mnee/`, registered explicitly by tests and research scripts. A
+  restart should address multiple roots, for example with manifold path guiding
+  (Fan et al. 2023).
+- **Separate photon denoising**, filtering photon contributions apart from path
+  tracing, increased error in comparisons and is not used.
+- **Photon-count radius scaling**, per-caster radii and larger shrinking screen
+  radii remain internal diagnostics (`causticDiagnostics.ts`). None improved
+  equal-error time on every test scene.
+
+## Changing this code
+
+- The partition runs in WGSL. WebGL traces plain paths and needs no zeroing; its
+  GLSL chain state exists only for the paused MNEE research path.
+- Native shares the WGSL and exposes the same two estimators.
+- Compare raw HDR, not denoised output, when judging energy; see the guide's
+  limits for denoiser artifacts.

package/docs/technical/continuous-spectrum.md

@@ -53,6 +53,35 @@ Photon gathering filters photon flux by the camera path's channel. This splits R
 across the camera paths and applies no second spectral weight, so energy is shared
 between path tracing and caustics the same way as without dispersion.
 
+## Shared prefixes
+
+With `dispersionWavelengths: 3`, the three channel paths of a pixel sample are
+identical until the first wavelength-dependent IOR: they use the same random numbers
+and carry full RGB until then. The integrators trace that prefix once, checkpoint
+the path, material, auxiliary outputs and random-stream state at the first
+dispersive interaction, and replay only the wavelength-specific suffix for each
+channel. RGB results completed before any dispersion are reused for all three.
+WGSL replays the suffixes inside the flat, alpha, volume and guide paths; GLSL
+traces all three in one fragment invocation (`spectralPrefix.glsl.ts`). Images are
+the same as with independent paths; only the work is shared. MNEE keeps independent
+paths, because its connection solver can disperse before the camera boundary.
+
+Tracing three suffixes in one WebGL draw makes that draw about three times longer.
+See [WebGL 2 backend](./webgl.md) for the timeout risk this adds on large images.
+
+## Direct-light resampling
+
+Direct lighting selects among `directLightCandidates` light samples by resampled
+importance sampling. When the three channel paths share a prefix, they share one
+reservoir, so the target cannot depend on the channel a path carries. The target
+is the full RGB contribution with equal channel weights; only the final estimator
+keeps the path's channel (`sampleMaterial.wgsl.ts`). A luminance target would
+underweight saturated red and blue light and raise their noise. Equal weights reduce
+that, but a strongly colored region can still converge more slowly in one channel
+than with independent per-channel paths; [sampling](../sampling.md) documents this
+caveat. Single-wavelength previews and non-dispersive renders keep the luminance
+target. WebGL draws one light candidate and has no reservoir.
+
 ## Short-wavelength IOR limit
 
 Cauchy IOR rises quickly at short wavelengths. At strong dispersion scales, violet