@meimu/mutracer 0.1.4 → 0.2.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,6 +127,7 @@ 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) |
 | `directLightCandidates` | `4` | WebGPU light candidates, clamped 1–16; ignored on WebGL |
@@ -115,7 +139,7 @@ other sequences retain their completed samples.
 | `width` / `height` | undefined | Paired fixed constructor dimensions; getters report actual output dimensions |
 | `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 |
+| `batchSamples` | `false` | Let one refine submit several samples within timeBudgetMs; 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) |
 
@@ -129,13 +153,15 @@ or alpha, plus its existing early depth termination.
 
 | 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 |
 | `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` | Latest WebGPU full beauty sample estimate in ms; undefined without timestamps, for stale inputs or during converge |
+| `whenReadyToRefine()` | Wait for the next release of WebGPU sampling queue capacity; resolves immediately if none is queued or on WebGL; submits no work |
 | `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 +175,14 @@ completed filtering. Synchronous execution failures return `'error'` and set
 engine.lastError. Invalid lifecycle operations (disposed render or refine during
 converge) throw.
 
+`refine(undefined, {batchSamples, targetBatchTimeMs, deferResolve})`
+overrides batching for one call without changing render settings or discarding
+samples. The first two options default to the render's execution settings.
+`targetBatchTimeMs` must be positive and finite, defaults to `timeBudgetMs`, is
+capped by that budget and is ignored on WebGL. `deferResolve` (default false,
+WebGPU only) leaves the displayed image unchanged for calls between display
+frames; the next presentation or pixel read updates it once with every new sample.
+
 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.
@@ -191,7 +225,7 @@ 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.
 `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
@@ -228,10 +262,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 +299,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 +318,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 +467,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`),
@@ -333,7 +490,8 @@ one. See [thin-film textures](./materials.md#textures) for range behavior.
 `undefined`. Channels and color decoding are listed in [material textures](./materials.md#textures).
 They follow the existing material/texture update mechanism.
 
-`coatNormalMap` defaults to `undefined`, retaining the shared shading normal. With a map, linear RGB supplies an independent coat normal; `coatNormalScale` defaults to `[1, 1]` and scales its decoded XY. See [coat normals](./materials.md#coat-normals) for frame, sampling and update behavior.
+`coatNormalMap` defaults to `undefined`; `coatNormalScale` defaults to `[1, 1]`.
+See [coat normals](./materials.md#coat-normals) for independent base and coat normal mapping.
 
 Raw texture sources contain exactly `width * height * 4` RGBA values, with
 rows ordered from top to bottom. `Uint8Array` and `Uint8ClampedArray` store
@@ -361,6 +519,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 |
@@ -372,7 +563,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`,

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

@@ -186,7 +186,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) |
 
@@ -260,41 +260,32 @@ with coat, and the finite path-event budget can truncate deep glass paths.
 ## Coat normals
 
 Set `coatNormalMap` to give the coat a tangent-space normal independently of
-`normalMap`. The renderer decodes linear RGB as `2 * RGB - 1`, multiplies XY
-by `coatNormalScale`, then normalizes. The scale defaults to `[1, 1]` and can
-be negative or zero. A missing map (the default), zero coat weight or zero sampled coat coverage retains the existing shared
-shading normal, including the base normal map.
-
-The coat TBN starts from the interpolated geometry normal before base normal
-mapping. It uses the coat texture's UV0/UV1 selection and geometric
-tangent handedness; generated tangents use UV1 differentials when that set is
-selected. Degenerate frames and zero decoded vectors use stable fallbacks.
-The texture's scale, offset and `flipY` follow the ordinary atlas sampling
-rules. As with other slots, sharing an image never changes its color space.
-
-Base lobes keep their base frame. Coat reflection, its sampling PDF, directional
-albedo and passage absorption use the coat frame; the renderer combines their
-responses and densities for the same world direction. Each frame is corrected
-against the geometric/view hemisphere independently. Triangle normals still
-control reflection versus transmission, medium boundaries and ray offsets.
-A coat reflection can contribute below the base shading hemisphere when it
-remains above the coat and geometric hemispheres. As before, solid interior
-hits omit coat reflection; thin surfaces are treated as exterior hits.
+`normalMap`. Without a coat map (the default), the coat uses the interpolated
+surface normal before base normal mapping. A bumpy base can therefore have a
+smooth coat. Assign the same texture to both maps to perturb both layers.
 
-Strongly tilted shading normals lose some lobe support when clipped to the
-geometric hemisphere. A unit white environment can therefore render below
-unit radiance; the renderer does not renormalize the clipped lobes.
+The map decodes linear RGB as `2 * RGB - 1`, multiplies XY by
+`coatNormalScale`, then normalizes. The scale defaults to `[1, 1]` and can be
+negative or zero. UV0/UV1 selection, scale, offset and `flipY` follow the
+ordinary texture rules. Zero coat weight or zero sampled coat coverage
+disables the coat without changing the base normal.
 
 Replacing the map or editing its scale is detected by `engine.update()`. Call
 `texture.markUpdated()` after pixel or UV-array element edits; see [scene updates](./updates.md).
-These edits update material parameters/textures without rebuilding geometry. Normal maps do not alter
-emission's existing normal-incidence absorption or light-selection proposals.
+
+Coat reflections can remain visible where the base normal points away from
+the light. Solid interior hits omit coat reflection; thin surfaces are
+treated as exterior hits.
+
+Strongly tilted shading normals lose some lobe support when clipped to the
+geometric hemisphere. A unit white environment can therefore render below
+unit radiance; the renderer does not renormalize the clipped lobes.
 
 ## Anisotropy directions
 
 Set `specularAnisotropyRotation` or provide `anisotropyMap` to orient the base specular lobe. The map reads linear `2 * RG - 1`, normalizes the direction, multiplies strength by B, and then applies the rotation. A decoded squared length at or below `1e-4` falls back to `(1, 0)` before rotation (including the two central RGBA8 codes). Without a map the direction is `(1, 0)` and the strength multiplier is one. The rotation defaults to zero; the map defaults to undefined.
 
-`coatAnisotropyRotation` defaults to zero and uses the geometry tangent independently of the base map. Base and coat evaluation, sampling and PDF use their respective directions. The coat uses the shared shading normal unless `coatNormalMap` selects an [independent normal](#coat-normals). Zero strength ignores the new direction and retains the original isotropic path.
+`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.
 

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.
 

package/docs/progressive-rendering.md

@@ -17,6 +17,7 @@ edits start final immediately; consecutive changes without explicit sync activit
 hold preview for idleMs (default 150 ms). When interaction ends, final starts after
 the current preview completes; its fallback remains visible until final completes a sample.
 With intermediate denoising enabled, it stays visible until the first filtered final image is ready.
+To keep the GPU busy while the view is still, enable [sample batching](#sample-batching) on final.
 
 ```ts
 loop.select = ({changing}) => changing || slider.dragging ? 'preview' : 'final';
@@ -84,6 +85,27 @@ it runs, object edits and scene/camera replacement have no effect on tracing.
 Call it once after updating your scene and controls, even when several renders
 are refined that frame. See [scene updates](updates.md) for notifications.
 
+## Sample batching
+
+Without batching, a still image gets one sample per display frame, so a fast GPU
+idles for most of each frame. With `batchSamples`, sampling works on two levels:
+
+- **Per call.** One `refine()` may submit several samples while at most
+  `timeBudgetMs` of GPU work is queued, and returns without waiting for them.
+  Without `batchSamples`, a call traces one sample or tile.
+- **Between frames.** RenderLoop also refines its final render each time the GPU
+  finishes queued work, until the next display frame. It keeps about 4 ms of work
+  queued, or one sample if that is longer, so a camera edit waits behind at most
+  that much work at any refresh rate.
+
+Batching is off by default. Enable it on the loop's final render with
+`final: {batchSamples: true}`, or on a Render you supply. RenderLoop stops
+batching while the view is changing.
+
+In your own loop, `batchSamples` gives the first level. For the second, call
+`render.refine(undefined, {targetBatchTimeMs: 4, deferResolve: true})` after each
+`await render.whenReadyToRefine()` until your next frame; see [Render](./api.md#render).
+
 ## Reading and exporting
 
 A fixed-size render does not need to be displayed. Its camera defaults to the
@@ -136,7 +158,8 @@ lower preview's scale; resizing the display canvas affects both.
 
 Call `render.setDenoiser({ type: 'jnlm', schedule: 'converged' })` with JNLM or an OIDN
 configuration. The schedules are `converged` (default), `progressive` (first
-sample, then 4, 8, 16, … with a ten-second limit), and `every-sample`. Same-engine
+sample, then doubling counts at least 500 ms apart; see [scheduling](./denoising.md#scheduling)),
+and `every-sample`. Same-engine
 renders share equal filter configurations and OIDN weight downloads. The engine
 releases a network when its last render lease is released. OIDN is ignored with
 a warning on WebGL; JNLM works on both backends.
@@ -150,6 +173,14 @@ final sample does not render the fallback. `present` selects the requested
 complete image, then its complete fallback, and otherwise leaves the canvas
 unchanged. It never traces.
 
+Sample batching on WebGPU needs GPU timestamps; without them, a call traces one
+sample, and between-frame refines are WebGPU-only. A larger `timeBudgetMs`
+batches more per call, but an edit made just after waits for that work before its
+preview starts. Batching keeps the GPU at full speed until `maxSamples`, which
+draws more power than one sample per frame. `stop()` ends between-frame refines
+at once, though submitted work still finishes; a manual `tick()` refines between
+frames only until the next display frame.
+
 `prepare(nextScene)` performs optional CPU BVH preparation without disturbing
 the current GPU scene. Setting `engine.scene` and calling `update` commits a
 scene switch for every render. Only one GPU scene resides in an engine.