@meimu/mutracer 0.1.5 → 0.3.0

package/docs/api.md

@@ -5,7 +5,7 @@ See [progressive rendering](./progressive-rendering.md) for complete examples.
 
 ## Engine
 
-`new Engine({canvas?, backend?, device?})` manages the device and one GPU
+`new Engine({canvas?, backend?, device?, textureBinding?})` manages the device and one GPU
 scene. `scene` and `camera` default to undefined. Assign them and call
 `update()` to commit edits before rendering; see [updates](./updates.md).
 
@@ -14,6 +14,7 @@ scene. `scene` and `camera` default to undefined. Assign them and call
 | `canvas` | new HTML canvas, or OffscreenCanvas without document | Accepts either canvas type; default `engine.display.canvas` |
 | `device` | undefined | Caller-owned WebGPU device; see [requirements](#device-requirements) |
 | `backend` | `'auto'` | Automatic WebGPU/WebGL selection; `'webgpu'` requires WebGPU; `'webgl'` forces WebGL 2 |
+| `textureBinding` | `'atlas'` | Constructor-only; `'auto'` tries experimental WebGPU bindless textures, with atlas fallback; see [texture bindings](#texture-bindings) |
 | `bvhBuilder` | `'builtin'` | JavaScript or `'tinybvh'` WebAssembly |
 | `bvhWorkerCount` | `'auto'` | Hardware concurrency minus one, clamped 1–4; or positive integer |
 | `bvhLayout` | `'bvh2'` | Static TinyBVH layout; see [BVH](./bvh.md) |
@@ -41,6 +42,28 @@ Events are `progress` (`{stage: 'device' | 'bvh' | 'shaders', progress}`),
 is reported once; console errors are deduplicated by message. Invalid light
 values are clamped and reported while rendering continues.
 
+### Texture bindings
+
+Use `new Engine({textureBinding: 'auto'})` to try bindless material textures
+on WebGPU. The default `'atlas'` uses the existing texture atlas. This option
+is fixed at construction. Check `engine.getDiagnostics()?.materialTextures`
+for the active mode, fallback reason, scale and estimated texture bytes.
+
+Bindless requires a resource-table feature enabled on the device and sufficient
+device limits. Chrome currently exposes an experimental implementation behind
+Unsafe WebGPU Support. Devices without it, including WebGL 2, use atlas textures.
+Caller-owned devices must enable `sampling-resource-table` or
+`chromium-experimental-sampling-resource-table` when available;
+`getRecommendedDeviceDescriptor()` does not request these experimental features.
+
+`textureAtlasBudgetBytes` applies to both modes. Bindless keeps independent
+textures and scales them together to fit the estimated pixel budget, preserving
+the current LOD 0 filtering and color rules. GPU allocation overhead, resource
+tables and metadata add memory beyond that estimate. Replacing textures can
+temporarily retain the previous GPU resources. Benefits depend on scene texture
+sizes and editing patterns; bindless does not guarantee faster rendering.
+See [texture updates](./updates.md#materials-textures-and-lights).
+
 ### Device requirements
 
 `EngineParams.device` defaults to undefined (the library's shared device). A
@@ -104,38 +127,43 @@ other sequences retain their completed samples.
 | Option | Default | Meaning |
 | --- | --- | --- |
 | `maxSamples` | `2048` | Complete sample budget |
+| `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) |
+| `caustics` | `undefined` | Optional caustics; all estimators default to off. See [caustics](#caustics) |
 | `directLightCandidates` | `4` | WebGPU light candidates, clamped 1–16; ignored on WebGL |
 | `bevel` / `bevelSamples` | `true` / `8` | Bevel shading / probes, clamped 1–32 |
-| `dispersionWavelengths` | `3` | 3 wavelengths, or one randomly chosen wavelength |
+| `dispersionWavelengths` | `3` | One continuous wavelength per RGB channel, or one randomly chosen channel |
 | `alphaBlendStrategy` | `'stochastic'` | WebGPU primary BLEND policy; ignored on WebGL |
 | `transmissiveOutputAlphaMin` | `1` | Path-depth alpha rule over transparent backgrounds; changes restart this render |
 | `resolutionScale` | `1` | Relative to display canvas; exclusive with fixed width/height |
-| `width` / `height` | undefined | Paired fixed constructor dimensions; getters report actual output dimensions |
+| `width` / `height` | undefined | Paired fixed constructor dimensions; `toBlob`, `readPixels` and the getters return exactly this size |
 | `adaptiveResolution` | `false` | `{targetFrameMs, minScale}` for scale-based renders; both required, positive, minScale ≤ resolutionScale |
-| `timeBudgetMs` / `maxTiles` | `21` / `Infinity` | Tile time budget / tiles per call |
-| `allowMultipleSamplesPerFrame` | `false` | Add multiple samples when time permits |
+| `timeBudgetMs` / `maxTiles` | `21` / `Infinity` | Target tile time / maximum tile grid size per sample (rounded up to a rectangular grid); fewer tiles make larger tiles, without limiting work per frame or call |
+| `batchSamples` | `false` | Let one refine submit several samples within an estimated timeBudgetMs; one sample or tile can exceed it; see [sample batching](./progressive-rendering.md#sample-batching). `allowMultipleSamplesPerFrame` is a deprecated alias |
 | `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.
-The path loop allows at most `min(bounces * 3, 20)` events, including transmission,
-alpha skips and escape checks. Opaque paths also have their own scattering-depth
-termination. This event budget can truncate deep transparent paths even when
-the requested scattering depth is larger. Intel Mac WebGL retains its driver
-workaround: `min(bounces, 3)` loop events, doubled for scenes with transmission
-or alpha, plus its existing early depth termination.
+Paths allow at most `min(bounces * 3, 20)` events, 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
+for scenes with transmission or alpha, with earlier scattering termination.
+See [caustic path-length limits](./caustics.md#limits) when comparing renderers.
 
 | Method / property | Meaning |
 | --- | --- |
-| `refine()` | Trace within this render's budget; returns status |
+| `refine(channel?, options?)` | Trace beauty or an enabled AOV within this render's budget; returns status |
+| `refineUntil(deadline, {signal}?)` | For custom frame loops: refine once synchronously, then keep sampling until the `performance.now()` deadline or cancellation; returns `Promise<void>`; see [sample batching](progressive-rendering.md#sample-batching) |
 | `converge(options)` | Deterministic offline image; see below |
 | `readPixels(kind = 'hdr')` | Read this render; see [pixel outputs](#pixel-outputs) |
 | `engine` | Owning engine |
 | `denoising` | Queued/running inference, including intermediate updates; default false |
 | `on('sample', listener)` | Complete samples: `{samples, isFirstFrame, frameTimeMs}`; returns unsubscribe |
 | `samples` | Complete samples since restart; stale engine inputs report 0 |
+| `gpuSampleTimeMs` | Deprecated; use `refineUntil` for custom frame loops. Latest WebGPU full beauty sample estimate in ms, extrapolated from tile GPU time when tiled; undefined without timestamps, for stale inputs or during converge |
+| `whenReadyToRefine()` | Deprecated; use `refineUntil`. Wait for WebGPU sampling capacity and return `true` if sampling was queued; return `false` immediately with no sampling, on WebGL, or for only denoising, display or offline convergence work; submits no work; throws after disposal |
 | `converged` | `samples >= maxSamples`, independently of filtering |
 | `status` | Preparing, compiling, converging, denoising, finished or error |
 | `setDenoiser(options)` | Replace the denoiser configuration; resolves when the filter is ready |
@@ -149,6 +177,11 @@ completed filtering. Synchronous execution failures return `'error'` and set
 engine.lastError. Invalid lifecycle operations (disposed render or refine during
 converge) throw.
 
+`refine(undefined, {batchSamples})` overrides batching for one call without
+changing render settings or discarding samples; it defaults to the render's
+`batchSamples`. The `targetBatchTimeMs` and `deferResolve` refine options are
+deprecated; use `refineUntil`.
+
 A fallback gets one sample when the requested render cannot finish its first
 sample within budget and the fallback has no current complete image. A ready
 fallback is not traced again. Fallback chains and cycles are rejected.
@@ -172,6 +205,25 @@ Resolves `{samples, averageSamplesPerPixel, pilotSamples, adaptiveSampling,
 varianceHistory?}` after filtering. It rejects if engine input revisions change.
 The same render cannot refine concurrently; other renders remain usable.
 
+### Caustics
+
+```ts
+render.caustics = {lightTracing: {photonsPerSample: 32768}};
+render.caustics = undefined; // Disable every estimator.
+```
+
+Changing any caustic option restarts accumulation. All estimators are experimental;
+see the [caustics guide](./caustics.md) for choosing estimators, supported paths,
+rendering cost and image-quality limitations.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `lightTracing` | `false` | `true` or an object enables directly visible caustic light paths on WebGPU; ignored on WebGL 2 |
+| `lightTracing.photonsPerSample` | pixel count / 4 | Emitted photons per sample, rounded to a positive integer and capped by the device dispatch limit |
+| `photonMapping` | `false` | `true` or an object enables progressive caustic photon mapping on WebGPU; ignored on WebGL 2. See [PM-only denoising limits](./caustics.md#limits) |
+| `photonMapping.photonsPerSample` | pixel count / 4, at most 262144 | Emitted photons per batch; 28 bytes each plus up to 13 MiB of overhead. Positive finite values are rounded to at least 1 and reduced to fit device limits and a 128 MiB batch budget; other values use the default |
+| `photonMapping.initialRadius` | 3% of the caster bounding sphere radius | Positive first-batch gather radius in scene units, independent of `photonsPerSample`; shrinks as batches accumulate. Smaller radii preserve detail but require more photons |
+
 ## RenderLoop and Sync
 
 `start()` uses requestAnimationFrame when available and a 16 ms setTimeout
@@ -191,7 +243,8 @@ otherwise. Worker visibility and control forwarding are described in
 | `coalesceSceneUpdates` | false | Defer commits during preview inference, then commit latest camera/scene |
 
 `engine`, `display`, `preview` (possibly undefined) and `final` are read-only.
-`changing` defaults false; `samples` counts final only and reports 0 during preview; `status` starts preparing.
+`changing` defaults false; `samples` counts final beauty samples and reports 0 during preview; `status` starts preparing.
+An exception during a tick, such as from a sync, sets `status` to error and `lastError`; the next successful tick clears them.
 `select({changing})` defaults to changing ? preview : final. `addSync`/`removeSync`
 manage integrations without disposing them. `tick` executes a manual frame;
 `start`/`stop` manage animation frames. `converge` accepts the same options as
@@ -217,7 +270,7 @@ Use `engine.display`; creation of additional displays is outside this API.
 their next refine; fixed renders retain their dimensions.
 `present(render)` only presents: it returns the render or its ready fallback,
 or undefined without changing the canvas when neither is ready.
-`toBlob(render, {type?, quality?})` composes that render at its actual dimensions,
+`toBlob(render, {type?, quality?})` composes that render at its output dimensions,
 without resizing or changing the current canvas. MIME defaults to image/png;
 quality defaults to the browser encoder value.
 
@@ -228,10 +281,16 @@ quality defaults to the browser encoder value.
 | `temperature`, `tint`, `vignette` | `0` |
 | `bloomIntensity`, `bloomThreshold`, `bloomRadius` | `0`, `1`, `0.6` |
 | `hdrOutputEnabled` | `false`; WebGPU only |
-| `channel: DisplayChannel` | `'final'`; also albedo, normal, shadow, shadowCatcher |
+| `channel: DisplayChannel` | `'final'`; also albedo, normal, shadow, shadowCatcher and the seven [AOV kinds](#aov-visualization) |
+| `aovDepthRange` | `[0, 10]`; finite scene-unit black/white depths, `0 <= near < far` |
+| `aovPositionScale` | `1`; finite positive scene-unit half-range around the origin |
+| `aovMotionScale` | `16`; finite positive pixel displacement for full brightness |
+| `aovIdComponent: AovIdComponent` | `'object'`; also instance, material, primitive |
 | `shadowCatcherColor`, `shadowCatcherAlpha` | `[0, 0, 0]`, `1` |
 
 All display settings apply at composition and retain accumulated samples.
+AOV mapping numbers must remain finite in float32; depth endpoints must remain
+distinct after conversion.
 Use the exported `DisplaySettings` type for a partial batch:
 
 ```ts
@@ -259,9 +318,11 @@ semantics are documented in [Custom denoisers](./denoising.md#custom-denoisers).
 
 ### Pixel outputs
 
-`readPixels(kind = 'hdr')` returns `{ width, height, data: Float32Array }`,
-RGBA with the top row first. Dimensions describe the internal render texture,
-which WebGPU rounds up to multiples of 16. Before a pipeline exists, it returns an empty image.
+`readPixels(kind = 'hdr')` returns `{ width, height, data }`. `data` is a
+`Uint32Array` for `id` and a `Float32Array` for every other kind.
+Pixels are RGBA with the top row first. Dimensions describe the internal render
+texture, which WebGPU rounds up to multiples of 16. Before a pipeline exists,
+beauty and OIDN-guide reads return an empty image; AOV reads reject.
 
 | Kind | Values |
 | --- | --- |
@@ -276,6 +337,120 @@ existing pipeline semantics. If no denoiser is attached or denoising has not
 completed, `denoised` returns `hdr` and warns once per render. The method
 makes a CPU copy and can be costly; avoid calling it every animation frame.
 
+### Surface outputs
+
+Request only the surface outputs you need on each render:
+
+```ts
+const render = new Render(engine, {
+  aovs: ['depth', 'position', 'id', 'motion'], aovSamples: 16
+});
+await render.converge({samples: 64});
+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
+calling `refine()` to regenerate AOVs for the current view; beauty samples and
+completed denoising are preserved. AOV accumulation restarts when either changes.
+
+| Kind | RGBA contents |
+| --- | --- |
+| `depth` | Camera-forward distance in scene units, 0, 0, coverage |
+| `position` | World position xyz, coverage |
+| `roughness` | Specular roughness, metalness, unsupported-reflectance fraction, coverage |
+| `diffuseAlbedo` | Directional-hemispherical diffuse reflectance RGB, valid coverage |
+| `specularAlbedo` | Directional-hemispherical specular reflectance RGB, 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
+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.
+
+ID and motion use the unjittered pixel center without depth of field. `Mesh.aovId`
+and `OpenPBRMaterial.aovId` default to process-unique integers. Explicit values
+must be integers from 0 through `0xFFFFFFFE`, unique among the scene's objects
+or materials respectively. Commit changes with `engine.update()`. Keep identities
+stable and avoid reusing an ID for a different object while history is live.
+Instance IDs are local indices; primitive IDs refer to the geometry's original
+triangle order. A ray exactly on a shared edge can select either adjacent
+triangle; host/GPU rounding can choose different IDs at that boundary.
+
+Motion history belongs to each render and advances when it produces an AOV
+frame. Camera pose and rigid object transforms can reproject across updates.
+The first frame, changed dimensions or projection, missing identities, changed
+topology or vertex positions, and failed visibility correspondence invalidate
+motion. Device recovery also clears history. Deformed vertices have no motion
+estimate; validity 0 must not be treated as a stationary surface.
+
+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.
+
+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
+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
+time budget at large resolutions. WebGL requires `EXT_color_buffer_float`.
+
+### AOV visualization
+
+Select an enabled surface output on Display to present or export it:
+
+```ts
+engine.display.channel = 'depth'; // render.aovs must include 'depth'
+engine.display.aovDepthRange = [0, 20];
+engine.display.present(render);
+const png = await engine.display.toBlob(render);
+```
+
+| Channel | Display mapping |
+| --- | --- |
+| `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 |
+| `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 |
+
+AOV channels bypass tone mapping, grading, bloom, vignette and denoising;
+registered display passes still run. Background and invalid reflectance or
+motion are transparent; accumulated outputs use their coverage as alpha. Zero valid motion
+is opaque black. The first frame's invalid motion is transparent.
+Selecting a kind absent from `render.aovs` rejects, even if a custom denoiser
+requests it. An enabled output awaiting sampling keeps the current canvas;
+export rejects until that output is ready. Display selection alone does not enable tracing.
+Changing the channel or mapping preserves beauty samples, raw AOV values and completed denoising.
+With `RenderLoop`, selecting an enabled AOV traces surface outputs without
+advancing beauty or running a denoiser, including after camera or scene edits.
+When viewing motion, the loop refreshes once inputs settle so stationary surfaces
+return to black. Switching between preview and final first displays zero motion;
+subsequent camera or object changes show motion from that view.
+ID and motion need one center sample; other AOVs stop at the smaller of
+`maxSamples` and `aovSamples`. Loop status can be `finished` while beauty
+`samples` remains zero. Switching back to Final resumes beauty for the current
+view. Direct `render.refine()` and `converge()` still trace beauty and requested
+AOVs together. Use `render.refine(kind)` for a surface-only step and
+`render.aovSamplesRendered` for its progress. The existing `normal` and `albedo` channels keep their OIDN-guide meaning.
+
+These mappings also apply to PNG export. Raw `render.readPixels(kind)` retains
+the [surface formats](#surface-outputs) above. WebGPU HDR presentation decodes
+the mapped colors to linear light; the visualization stays within SDR white.
+Visualization retains an extra 8 GPU bytes per render pixel on WebGPU or 4 on
+WebGL until the AOV resources are resized or disposed.
+
 ### Depth sampling
 
 After rendering the current scene and camera, call
@@ -311,11 +486,12 @@ Public spatial values use `Vec2` (`[number, number] | Float32Array`), `Vec3` (`[
 | `Geometry`, `GeometryAttribute` | Triangle data: required `position`; optional `normal` and `indices` are generated at construction; `vertexCount` / `triangleCount` getters; optional `uv`, `uv1`, `tangent`, `color`, `materialIndex` (raw per-vertex indices, itemSize 1; all three corners of each triangle must match; invalid indices fall back to material 0 with one warning); `dynamic` (default `false`) for [deforming geometry](./updates.md#dynamic-geometry) |
 | `OpenPBRMaterial` | `new OpenPBRMaterial(params?)`; see [materials](./materials.md) |
 | `Texture` | HTMLImageElement, HTMLCanvasElement, ImageBitmap, OffscreenCanvas or `{ data, width, height }`; `colorSpace`: `'srgb'` or `'linear'`; default undefined uses sRGB for images/bytes and linear for `Float32Array`/`Int32Array`; independent `wrapS` / `wrapT`: `'repeat'` (default), `'clamp-to-edge'`, `'mirrored-repeat'`, applied after UV scale/offset for material textures |
+| `ProceduralSky`, `ProceduralSkyOptions` | Clear-sky environment texture; [usage and options](#proceduralsky) |
 | `Camera` | `new Camera({ projection: 'perspective', ... })` or orthographic; `position`, `lookAt()`, `copy(source)`, `clone()`; aspect defaults to automatic; depth of field with `fStop`, `focusDistance`, `sensorHeight`, `metersPerUnit` ([details](./getting-started.md#depth-of-field)) |
 | `RectLight`, `SphereLight`, `SpotLight`, `DirectionalLight`, `EnvironmentLight`, `AmbientLight` | Parameter-object constructors; analytic lights use `transform`, `position`, `lookAt()` and rigid axes. See [lights](./getting-started.md#lights) |
 | `EnvironmentLight` | `new EnvironmentLight({map, intensity?})`; `intensity` defaults to `1`, scales environment radiance, and accepts `0` to disable lighting. Ambient lights and explicit background textures retain their own brightness. `transform` rotates the environment from local to world space (identity by default); translation and positive axis scale are ignored. An explicit background texture keeps its own orientation |
 | `IESProfile`, `parseIESProfile(text)` | Photometric profiles for `SpotLight` |
-| `SceneBackground` | `[r, g, b, a]`, `Texture` or `GroundedSkyboxBackground`; grounded backgrounds accept `rotation` around +Y in radians (default `0`) and `intensity` (default `1`). These affect only the background; the ground stays level and alpha is preserved |
+| `SceneBackground` | `[r, g, b, a]`, `Texture`, `EquirectBackground` (`{type: 'Equirect', map, transform?, intensity?}`) or `GroundedSkyboxBackground`. Equirect `transform`: column-major map-to-world rotation (default identity); translation and positive axis scale are ignored. Grounded `rotation`: radians around +Y (default `0`). `intensity` on either: nonnegative RGB multiplier, default `1`. These affect only the background; ground stays level and alpha is preserved |
 
 `OpenPBRMaterial` accepts canonical `specularRoughnessAnisotropy` (default `0`),
 `coatRoughnessAnisotropy` (`0`), `subsurfaceScatterAnisotropy` (`0`),
@@ -362,6 +538,39 @@ and `markUpdated(): this`. `Geometry` also has the read-only `topologyVersion`
 (initially `0`) and `markVerticesUpdated(): this`, which advances only
 `version`. See [scene updates](./updates.md) for when to call each.
 
+### ProceduralSky
+
+Use the sky as an environment map, an explicit background, or the map of a
+`GroundedSkyboxBackground`:
+
+```ts
+import { ProceduralSky, EnvironmentLight } from '@meimu/mutracer';
+
+const sky = new ProceduralSky({ resolution: [2048, 1024], time: 15 });
+scene.lights.push(new EnvironmentLight({ map: sky }));
+// With no explicit scene.background, the environment is also the background.
+sky.time = 9;
+engine.update();
+```
+
+| Option / property | Default | Behavior |
+| --- | --- | --- |
+| `resolution` | `[2048, 1024]` | Positive integer equirectangular width and height; assign a new pair to resize |
+| `time` | `15` | Local solar time in hours, from `0` to `24`, for an equinox at latitude 40° |
+
+Time and resolution assignments follow the normal [scene update rules](./updates.md).
+Use `EnvironmentLight.intensity` and `transform` for brightness and rotation.
+With Three.js, pass the sky as the `environment` option to `THREESync` or
+`fromTHREEScene`; the Three.js scene still supplies intensity and rotation.
+
+Higher resolutions use more memory and can exceed device limits. Frequent
+time edits can be slower with WebGL 2. Dispose the engine when finished;
+`ProceduralSky` needs no separate disposal.
+
+This is a clear atmosphere without clouds, stars, moonlight or artificial
+light. Very low resolutions can blur or miss the small sun disk. Use the sky
+for environments and backgrounds, not material texture slots.
+
 ## Helpers
 
 | Export | Description |
@@ -373,7 +582,7 @@ and `markUpdated(): this`. `Geometry` also has the read-only `topologyVersion`
 | `THREESync` | Keeps a `THREE.Scene` in sync: `new THREESync(engine, {scene?, camera?, controls?, updateControls?})`; RenderLoop calls update; dispose when done; conversion hooks `convertMaterial` / `convertLight`; see [Three.js](./threejs.md#custom-conversion) |
 | `fromTHREECamera(camera, options?)` | Converts a Three.js camera; one-shot conversion; THREESync retains and updates cameras. Reads `focus` and the film height; `FromTHREECameraOptions` sets `fStop` (default `0`), `focusDistance` and `metersPerUnit` (default `1`) |
 | `fromTHREEScene` | One-shot Three.js scene conversion with FromTHREESceneOptions conversion hooks; every call reruns hooks and creates fresh default objects |
-| `FromTHREESceneOptions` | Optional `onMeshConverted(mesh, source, group, groupIndex)` callback; default: none |
+| `FromTHREESceneOptions` | Optional `environment` overrides the Three.js environment with a MuTracer `Texture` or `ProceduralSky` (default undefined); optional `onMeshConverted(mesh, source, group, groupIndex)` callback; default: none |
 | `VERSION` | Library version |
 
 `@meimu/mutracer/oidn` exports weight constants (`OIDN_MODEL_FILENAMES`,
@@ -390,7 +599,9 @@ see [denoising](./denoising.md#custom-oidn-networks). The main entry exports
 
 `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. See [formats, lifecycle and overlay example](./post-processing.md).
+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).
 
 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/caustics.md

@@ -0,0 +1,80 @@
+# Caustics
+
+Enable caustics on the render that needs them:
+
+```ts
+render.caustics = {lightTracing: true, photonMapping: true};
+```
+
+Choose the estimators for the visible receiver:
+
+| Scene | Settings |
+| --- | --- |
+| Glass or metal casting onto a directly visible surface | `{lightTracing: true}` |
+| Water or glass between the camera and the caustic receiver | `{photonMapping: true}` |
+| A mixture of direct, indirect and glass-covered receivers | `{lightTracing: true, photonMapping: true}` |
+
+Light tracing preserves narrow, directly visible caustics without a gather
+radius. Photon mapping covers indirect caustics and surfaces seen through glass,
+with additional memory and gather cost. Combined estimators assign path coverage
+automatically. The viewer's Cornell caustic preset enables both estimators.
+
+Set `render.caustics = undefined` to disable every estimator. See
+[API options and defaults](./api.md#caustics).
+
+## Options and cost
+
+```ts
+render.caustics = {
+  lightTracing: {photonsPerSample: 32768},
+  photonMapping: {photonsPerSample: 32768, initialRadius: 0.1}
+};
+```
+
+Both estimators require WebGPU; WebGL ignores those options. HDR readback,
+display and denoising include the combined result. Changes to any option restart
+accumulation. The native SDK provides the same choices through Rust
+`CausticSettings` and the C `MT_CAUSTIC_*` flags.
+
+More emitted photons can reduce noise but cost more time and memory. Photon-map
+storage adds 28 bytes per emitted photon plus up to 13 MiB of overhead. Requests
+above the device limits or the 128 MiB batch budget use fewer photons. Photon
+batches cover the full image even when path tracing uses tiles or adaptive
+sampling. Their time counts toward the frame budget, but adaptive variance measures
+only the path-traced component.
+
+## Limits
+
+Light tracing follows surfaces with no diffuse, subsurface, fuzz or coat
+contribution and specular roughness at most 0.1. It supports emissive triangles,
+rectangles, spheres, spotlights, directional lights and environment lighting,
+perspective and orthographic cameras, depth of field and dispersion. Photon
+mapping adds caustics throughout the allowed camera path. Volume scattering
+events and shadow catchers remain with ordinary path tracing.
+
+Complete caustic light-to-camera paths can be longer than `bounces`. Align total
+path-length limits when comparing radiance with another renderer.
+
+Photon mapping starts blurred and shrinks its radius as samples accumulate. A
+small initial radius can be noisy; a large one can blur nearby surfaces and details.
+Distant smooth casters enlarge the automatic radius, so set `initialRadius` if deep
+caustics look too blurred. At the first diffuse surface, the gather radius is capped
+to about two projected pixels to reduce patches after denoising; reflections and
+refractions use an approximate footprint. More photons can help, but not every
+batch improves the image, and more samples do not remove the precision loss in
+stored photon data.
+
+With photon mapping alone, directly visible receivers can show fewer cloud-like
+OIDN blotches but grainier raw images. Receivers seen through reflection or
+refraction can still show blotches. Enable light tracing as well for the cleanest
+directly visible receivers.
+
+A denoiser can soften narrow caustic lines, so compare raw HDR with denoised output
+when judging detail. Use raw HDR for energy comparisons: displayed or denoised
+brightness can differ even when regional HDR energy agrees.
+
+Both estimators fall back to path tracing for the whole scene when a smooth caster
+uses stochastic blend coverage. Cutout coverage remains supported. Environment
+caustics follow path tracing's visible-background behavior through the first smooth
+transmission; an explicit black background suppresses that contribution.
+Quantitative energy agreement with other renderers is not guaranteed.

package/docs/denoising.md

@@ -6,7 +6,7 @@ albedo and normal guides.
 - **JNLM**: a built-in joint non-local means filter, on WebGPU and
   WebGL 2. It needs no weight download.
 - **OIDN**: [Intel Open Image Denoise](https://www.openimagedenoise.org/)
-  networks, run through [`oidn-web`](https://www.npmjs.com/package/oidn-web),
+  networks, run through [`oidn-webgpu`](https://github.com/pissang/oidn-webgpu),
   WebGPU only. They take longer and need weights, but are cleaner at one or
   two samples per pixel, for example for denoising while the camera moves.
 
@@ -17,16 +17,17 @@ final.setDenoiser({type: 'oidn', model: 'standard'});
 final.setDenoiser(null); // disable
 ```
 
-`type` is required: use `jnlm` or `oidn`. `render.denoiser` returns a frozen
-copy of the configuration; call `setDenoiser` again to change it. Unknown types,
+`type` is required: use `jnlm`, `oidn`, or a [custom denoiser](#custom-denoisers).
+`render.denoiser` returns a frozen copy of the configuration; call `setDenoiser`
+again to change it. Unknown types,
 foreign fields and invalid JNLM settings throw synchronously, preserving the
-active network and output. Equal implementation settings share the network;
+active filter and output. Equal built-in settings reuse the loaded network;
 changing only `schedule` preserves active inference, and passing an identical
 configuration does nothing.
 Each render has its own configuration and scheduling. Converge waits for its
 configured filter; intermediate progressive inference reports converging and
-final inference reports denoising. Engine caches equal network configurations
-and weights, releasing the network after its last render lease is released.
+final inference reports denoising. Built-in networks and weights are shared
+within an engine and released when no render uses them.
 
 `setDenoiser` returns a promise that resolves when the filter is ready, which
 for OIDN means its weights have loaded, and rejects when loading fails. A
@@ -67,7 +68,7 @@ network prewarm results are discarded.
 | `model` | OIDN network: `'standard'` (default), `'small'` or `'cleanAuxLarge'` |
 | `weightsBaseUrl` | Directory containing the OIDN `.tza` files |
 | `schedule` | `'converged'` (default), `'progressive'`, or `'every-sample'` |
-| `maxTileSize` | Maximum OIDN tile size; chosen by oidn-web by default |
+| `maxTileSize` | Maximum output tile edge in pixels; default `512` |
 | `signal` | `AbortSignal` for the OIDN weight download; default undefined |
 | `weightsUrl` | Explicit custom network; mutually exclusive with model/base directory |
 | `aux`, `hdr`, `hdrTransfer` | Custom network metadata only; defaults true, true, `'pu'` |
@@ -112,8 +113,11 @@ preview.setDenoiser({type: 'oidn', model: 'small', schedule: 'every-sample'});
 ```
 
 Converged filters the final sample budget. Progressive filters sample 1,
-then 4, 8, 16, … and the final budget, with a ten-second limit between
-updates. Every-sample filters every complete sample of its render. Coalescing
+then the first count that is at least double the previous update (and at
+least 4) and comes 500 ms or more after it, and finally the sample budget.
+Updates come at least every ten seconds. With [sample batching](./progressive-rendering.md#sample-batching),
+counts grow faster, so the 500 ms floor skips intermediate doublings.
+Every-sample filters every complete sample of its render. Coalescing
 continuous scene/camera edits is application loop policy; the engine accepts
 edits only when update is called. See [progressive rendering](./progressive-rendering.md).
 
@@ -175,7 +179,7 @@ experimental WebNN path. `precision` defaults to `'auto'` (FP16 when
 shader-f16 is available), with `'fp32'` and `'fp16'` overrides. `dynamicTile`
 defaults to `true`; use `false` for fixed tiles or an object with
 `minTileSize` (256), `initialTileSize` (432), `targetTileTimeMs` (16) and
-`adjustmentStep` (16). Tile sizes are clamped/aligned by oidn-web.
+`adjustmentStep` (16).
 
 All implementation settings participate in the network cache key; `schedule`
 and download `signal` do not. Renders with different signals share a pending
@@ -204,7 +208,10 @@ const copy: Denoiser = {
     device.queue.submit([encoder.finish()]);
   }
 };
-final.setDenoiser({type: 'custom', denoiser: copy, schedule: 'converged'});
+final.setDenoiser({
+  type: 'custom', denoiser: copy, schedule: 'converged',
+  aovs: ['depth', 'motion']
+});
 ```
 
 The required `type` and `denoiser` choose this branch; `schedule` defaults to
@@ -219,13 +226,21 @@ render sizes is prepared again. `DenoiseInput` contains these buffers:
 | `albedo` | Linear RGB albedo averaged over complete samples; alpha is primary-hit coverage |
 | `normal` | Resolved world-space normal averaged and encoded as `normal*.5+.5`, without renormalization; alpha 1 for valid surface data, otherwise zero RGBA |
 | `output` | Write all linear HDR RGB; output alpha is ignored and the input path coverage is preserved |
+| `aovs` | Optional map of the requested surface-output buffers, such as `input.aovs?.depth`; absent by default |
 
-All four are tightly packed RGBA float32, top row first, exactly
-`width * height * 16` bytes, with STORAGE, COPY_SRC and COPY_DST usages.
+Color, albedo, normal and output are tightly packed RGBA float32, top row first,
+exactly `width * height * 16` bytes, with STORAGE, COPY_SRC and COPY_DST usages.
 Dimensions describe the actual internal image (WebGPU rounds up to 16).
+`CustomDenoiserOptions.aovs` defaults to `[]`. Requests enable the corresponding
+passes automatically; `render.aovs` is needed only for direct pixel readback.
+Each AOV buffer is top row first, exactly `width * height * 16` bytes: `id` is
+RGBA uint32 and the others RGBA float32. Values, validity and sampling limits
+follow [surface outputs](./api.md#surface-outputs). These are immutable snapshots
+of this invocation and cost 16 additional GPU bytes per pixel per requested kind.
+
 Input buffers are read-only. Buffers are borrowed until the promise settles;
-do not retain or destroy them. Resolve after submitting every output write;
-MuTracer copies the result, waits for GPU work, then releases its queue lease.
+do not retain or destroy them. Resolve after submitting every output write.
+
 Custom `readPixels('denoised')` returns the filtered native HDR ray color,
 with input path coverage. Display settings then follow the ordinary compose
 path: flat backgrounds retain their display-space treatment and catcher

package/docs/materials.md

@@ -97,10 +97,11 @@ the substrate through the attenuation term.
 **Interior media.** Transmission describes a homogeneous volume:
 `transmissionColor` is the color that survives one `transmissionDepth`, and
 `transmissionScatter` is the scattering albedo. With `transmissionDepth = 0`
-the tint is applied at the surface. Subsurface is a separate layer driven by its
-color and per-channel radius. When both are active, their coefficients combine
-into one volume. Dispersion (`transmissionDispersionScale > 0`) samples
-wavelengths spectrally.
+the tint is applied at the surface. Subsurface has its own color and per-channel
+radius. A positive `transmissionDispersionScale` enables
+wavelength-dependent refraction; values above `1` increase color separation,
+and `0` disables it. Lower `transmissionDispersionAbbeNumber` values also
+increase color separation.
 
 ## Compatibility names
 
@@ -186,7 +187,7 @@ selects `blend`. With none of these inputs, `auto` selects `opaque`.
 
 | Property | Description |
 | --- | --- |
-| `shadowCatcher` | Invisible ground that only receives shadows; composite over a transparent background |
+| `shadowCatcher` | Invisible ground that only receives shadows of the environment and analytic lights, not of emissive meshes; composite over a transparent background |
 | `unlit` | Shows emission without scattering or lighting other surfaces |
 | `bevelSize` | Rounded-edge shading radius in scene units; `0` disables (see below) |
 

package/docs/performance.md

@@ -18,8 +18,11 @@ A tuning checklist. Each item links to the page with the details.
 - Use a preview Render with cheaper quality and optional adaptiveResolution:
   `{targetFrameMs: 20, minScale: .25}`, plus resolutionScale .5. Choose it during
   motion and configure final.fallback once; see [progressive rendering](./progressive-rendering.md).
-- timeBudgetMs (default 21) bounds each render's tile cost. Raise it for exports.
-- allowMultipleSamplesPerFrame adds several samples per refine when time permits.
+- `timeBudgetMs` (default 21) targets each render's tile cost. Raise it for exports.
+- `batchSamples` lets a still render use the whole GPU instead of one sample per
+  display frame; enable it with `RenderLoop({final: {batchSamples: true}})`. In your
+  own loop, a larger `timeBudgetMs` batches more per call but delays the first
+  preview after an edit. See [sample batching](./progressive-rendering.md#sample-batching).
 - For exports, `render.converge` with `targetBatchTimeMs` adapts batch sizes
   to the GPU; omit `previewIntervalMs` for maximum throughput.