@meimu/mutracer 0.2.0 → 0.3.1

package/docs/api.md

@@ -127,41 +127,45 @@ 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) |
+| `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 |
-| `batchSamples` | `false` | Let one refine submit several samples within timeBudgetMs; see [sample batching](./progressive-rendering.md#sample-batching). `allowMultipleSamplesPerFrame` is a deprecated alias |
+| `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.
+`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
+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(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` | 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 |
+| `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 |
@@ -175,13 +179,10 @@ 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.
+`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
@@ -206,6 +207,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
@@ -226,6 +246,7 @@ otherwise. Worker visibility and control forwarding are described in
 
 `engine`, `display`, `preview` (possibly undefined) and `final` are read-only.
 `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
@@ -251,7 +272,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.
 
@@ -331,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 |
 | --- | --- |
@@ -342,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.
@@ -373,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
@@ -402,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 |
 
@@ -579,8 +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. 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/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/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
@@ -97,10 +99,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
 
@@ -128,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 | |
@@ -287,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

@@ -87,24 +87,68 @@ 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:
+Without batching, each call advances one sample or tile, so a fast GPU can idle
+between display frames. 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.
+- **Per call.** One `refine()` may submit several samples within an estimated
+  `timeBudgetMs` of GPU work, or one longer sample or tile, 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.
+  queued, or one sample or tile if that is longer. Expensive tiled samples can
+  continue between display frames when each measured tile fits `timeBudgetMs`;
+  longer tiles wait for display frames to bound input delay. Presentation still
+  follows the display frame 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).
+Prefer RenderLoop for between-frame refilling. For a custom loop, use
+`refineUntil(deadline, {signal})`. It synchronously calls `refine()` once, so
+`present()` belongs immediately after the call. On WebGPU it then refills short
+batches until the deadline, cancellation, a hidden page or sampling/display
+conditions prevent more work. WebGL performs only the synchronous call.
+
+This example assumes `engine` and `render` are created with
+`render.batchSamples = true` and the final beauty channel selected. Adjust the
+60 Hz deadline to your application's cadence and update controls before
+`engine.update()`.
+
+<!-- own-loop-refill -->
+```js
+let refill;
+const stop = () => refill?.abort();
+for (const type of ['pointerdown', 'pointermove', 'pointerup', 'wheel', 'keydown', 'input', 'change'])
+  addEventListener(type, stop, {capture: true, passive: true});
+
+function frame(timestamp) {
+  requestAnimationFrame(frame);
+  stop();
+  engine.update();
+  refill = new AbortController();
+  void render.refineUntil(timestamp + 1000 / 60, {signal: refill.signal});
+  engine.display.present(render);
+}
+requestAnimationFrame(frame);
+```
+
+Call `stop()` before pausing, exporting or switching to another render, and skip
+`refineUntil()` while paused. A new call automatically ends the previous refill.
+The signal cancels future submissions; work already queued on the GPU completes.
+The returned Promise resolves when refilling stops, including after an
+asynchronous error (reported through `render.status` and `engine.lastError`).
+
+The library automatically continues the remaining tiles of the current sample
+between presentations. `samples` increases only after the whole sample;
+presentation keeps the previous complete sample until then. Committed scene or
+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.