@meimu/mutracer 0.0.0-stage → 0.1.1

package/docs/threejs.md

@@ -0,0 +1,274 @@
+# Three.js integration
+
+Build or load a Three.js scene, then bind it and its camera with THREESync.
+RenderLoop calls the sync automatically. Three.js is an optional peer dependency
+(`npm install three`).
+
+```ts
+import * as THREE from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import { Engine, RenderLoop, THREESync } from '@meimu/mutracer';
+const scene = new THREE.Scene();
+scene.add((await new GLTFLoader().loadAsync('model.glb')).scene);
+const camera = new THREE.PerspectiveCamera(40, canvas.width / canvas.height, .1, 100);
+camera.position.set(0, 2, 6);
+const controls = new OrbitControls(camera, canvas);
+const engine = new Engine({canvas});
+const sync = new THREESync(engine, {scene, camera, controls});
+const loop = new RenderLoop(engine, {sync});
+loop.start();
+```
+
+## Keeping scenes in sync
+
+Edit Three.js transforms, membership, lights, backgrounds and materials directly.
+Material edits are converted automatically; color and roughness
+edits do not require `material.needsUpdate`. Buffer and pixel edits need the
+usual flags:
+
+| Edit | Flag |
+| --- | --- |
+| Attribute or index array elements | `attribute.needsUpdate = true` (`attribute.data.needsUpdate` for interleaved) |
+| Texture pixels or canvas | `texture.needsUpdate = true` |
+| Instance matrices / colors | `instanceMatrix.needsUpdate` / `instanceColor.needsUpdate = true` |
+
+```ts
+threeMesh.rotation.y += .01;
+threeMaterial.roughness = .6;
+geometry.attributes.position.setX(0, .5);
+geometry.attributes.position.needsUpdate = true;
+// The next loop tick synchronizes and commits these edits.
+```
+
+For an application-owned animation frame, update the animation mixer first,
+then call `loop.tick()`. With first-layer frame control, call `sync.update()`,
+`engine.update()`, `render.refine()` and `engine.display.present(render)` in order.
+
+## What is converted
+
+| Three.js | MuTracer |
+| --- | --- |
+| `Mesh` with `MeshStandardMaterial` / `MeshPhysicalMaterial` | `Mesh` + `OpenPBRMaterial` (color, metalness, roughness, maps, normal map, emissive, transmission, attenuation, IOR, clearcoat, sheen, iridescence, anisotropy, alpha) |
+| `Mesh` with `MeshBasicMaterial` (glTF `KHR_materials_unlit`) | Unlit emissive material |
+| `MeshPhysicalMaterial.clearcoat`, `.clearcoatRoughness` (glTF `KHR_materials_clearcoat`) | `coatWeight`, `coatRoughness`, with `coatIor = 1.5` and `coatDarkening = 0` for Three.js compatibility; explicit `userData.mutracerOpenPBR.coatDarkening` overrides the imported value |
+| `MeshPhysicalMaterial.sheen`, `.sheenColor`, `.sheenRoughness` | `fuzzWeight`, `fuzzColor`, `fuzzRoughness`; explicit `userData.mutracerOpenPBR.fuzzRoughness` overrides imported roughness |
+| `MeshPhysicalMaterial.iridescenceThicknessMap`, `.iridescenceThicknessRange` | `thinFilmMap` with `thinFilmMapChannel = 'g'`; both nm endpoints are divided by 1000 into `thinFilmThicknessMinimum` / `thinFilmThickness`; without a map only the maximum is used |
+| `MeshPhysicalMaterial.clearcoatMap`, `.clearcoatRoughnessMap` | `coatWeightMap` (linear R), `coatRoughnessMap` (linear G) |
+| `MeshPhysicalMaterial.clearcoatNormalMap`, `.clearcoatNormalScale` | `coatNormalMap` (linear RGB), independent `coatNormalScale`; see [coat normals](./materials.md#coat-normals) |
+| `MeshPhysicalMaterial.sheenColorMap`, `.sheenRoughnessMap` | `fuzzColorMap` (sRGB RGB), `fuzzRoughnessMap` (linear A) |
+| `MeshPhysicalMaterial.specularIntensityMap`, `.specularColorMap` | `specularWeightMap` (linear A), `specularColorMap` (sRGB RGB) |
+| `MeshPhysicalMaterial.anisotropy`, `.anisotropyRotation`, `.anisotropyMap` | Source strength, rotation and direction texture; see [anisotropy source conversion](#anisotropy-source-conversion) |
+| `SkinnedMesh` / mesh with morph targets | CPU-deformed dynamic geometry |
+| `InstancedMesh` | One InstancedMesh per material group, with native colors, sharing geometry and BLAS |
+| Multi-material groups | One MuTracer mesh per group |
+| `DirectionalLight` | `DirectionalLight` |
+| `PointLight` | `SphereLight` (radius `userData.mutracerRadius`, default 0.25) |
+| `SpotLight` | `SpotLight` (radius `userData.mutracerRadius`, default 0.01; `penumbra` sets the inner angle) |
+| `RectAreaLight` | `RectLight` |
+| `AmbientLight` | `AmbientLight` |
+| `scene.environment` (equirectangular float `DataTexture`, e.g. from `HDRLoader`/`RGBELoader`) | `EnvironmentLight` |
+| `scene.background` color / texture | Background; the environment itself when `background === environment` |
+
+Three.js `opacity` maps to `geometryOpacity`; thin-shell choices map to
+`geometryThinWalled`. Metadata accepts the five [canonical and compatibility
+names](./materials.md#compatibility-names), using the constructor's equal-value
+or conflict rule. These overrides apply after standard conversion; alpha mode
+still follows the source material flags and resolved coverage. Naming does not
+change transmission, volume or anisotropy conversion semantics.
+
+Thin-film ranges keep their endpoint order, including minimum greater than
+maximum, and retain the converter's 0–20 µm endpoint clamp. The converter uses
+Three.js's actual range defaults. `mutracerOpenPBR` may explicitly override the
+range, channel and map after conversion; its map accepts a MuTracer `Texture`
+or a source `THREE.Texture`. `THREESync` converts parameter edits without
+rewriting texture pixels. The iridescence strength texture is not supported;
+`thinFilmMap` represents thickness only.
+
+The six layer maps reuse the texture conversion cache, source UV channel,
+scale, offset and flipY. `mutracerOpenPBR` can override them with a MuTracer
+`Texture` or `THREE.Texture`; explicit `null` clears an imported map, while
+unknown JSON objects are ignored. `THREESync` follows texture edits without
+copying pixels. General `KHR_texture_transform` rotation remains unsupported.
+Clearcoat normals are deferred to the independent coat-frame implementation.
+Anisotropy direction and source-model mapping are described [below](#anisotropy-source-conversion). The conversion preserves OpenPBR layering: glTF sheen
+layer order differs, and specular weight/color also affect metals in OpenPBR;
+these imports do not imply identical glTF BRDFs.
+
+Invisible objects are skipped. Other material types are skipped with a console
+warning unless `convertMaterial` supplies an OpenPBR material. `BatchedMesh`, instanced morph targets (`morphTexture`) and skinned
+instancing are unsupported: each source object warns once per converter and is
+converted as an ordinary mesh, without per-instance matrices or colors.
+
+Meshes without UVs get automatic triplanar texture and displacement
+projection; explicit
+`mutracerUvProjection` settings take precedence.
+
+## Skinning and morph targets
+
+The initial conversion and each `sync.update()` evaluate morph targets and
+skinning on the CPU. The sync calls `skeleton.update()` itself, so a preceding
+Three.js render is unnecessary. Relative and absolute morph targets affect
+positions and normals; skinning transforms positions, normals and supplied
+tangents in local space. Missing tangents are generated from the deformed
+positions, normals and UVs. The mesh's world transform remains an instance
+transform.
+
+Each deforming source mesh owns its MuTracer geometry, even when several
+SkinnedMesh objects share a Three.js BufferGeometry; deformation is computed
+once per source mesh and copied to each material group. These geometries are
+[dynamic](./updates.md#dynamic-geometry).
+
+An unchanged pose (bones, binding matrices, morph weights and attribute
+versions) skips deformation. A changed pose updates the arrays in place, and
+rendering refits only that geometry's BLAS and instances. CPU cost grows with
+vertices, bone influences and material groups. Displaced deforming meshes need
+a full mesh update on every pose change.
+
+Try the procedural [animation example](../examples/animation.html). Pause the
+animation to accumulate samples; changing a pose restarts accumulation.
+
+## Instanced meshes
+
+`THREE.InstancedMesh.count` converts to a MuTracer `InstancedMesh` per material
+group. Local Float32 matrices and colors are copied in source
+index order within each batch; the retained double-precision `source.matrixWorld`
+is the batch transform. Each world matrix remains `source.matrixWorld * instanceMatrix[i]`.
+
+- **Matrices**: set `instanceMatrix.needsUpdate = true` after edits. The converter
+  checks values and notifies changed batches; unchanged batches retain their
+  matrix arrays and versions. Both backends refit the instance hierarchy.
+- **Count**: the surviving source prefix retains its transforms and batch
+  identities. Shrinking removes the tail; increasing reads it again from the
+  source buffer. Membership changes rebuild the top-level BVH and reuse vertices
+  and BLASes where packing permits ([scene updates](./updates.md#adding-removing-and-reassigning-meshes)).
+- **Colors**: `instanceColor` is copied into the batch's native `colors` array in
+  source order; removing it restores undefined (white). Set
+  `instanceColor.needsUpdate = true` after edits. Only changed values notify the
+  batch, and colors do not create material variants or extra batches. See
+  [color semantics and updates](./updates.md#instanced-meshes).
+- **Callbacks**: `onMeshConverted` runs once per visible group on each update.
+  It receives `Mesh | InstancedMesh`; edit shared materials as usual, or notify
+  batch array element edits as described in [scene updates](./updates.md).
+
+Unsupported instanced deformation keeps the ordinary-mesh fallback described
+above. [Native instancing](./updates.md#instanced-meshes) uses the same primitive
+without Three.js.
+
+## `userData` keys
+
+Renderer-specific settings without a Three.js equivalent:
+
+| Key | On | Description |
+| --- | --- | --- |
+| `mutracerShadowCatcher: true` | material | Shadow-catcher ground |
+| `mutracerOpenPBR: { ... }` | material | OpenPBR inputs without a Three.js equivalent: `baseWeight`, `baseDiffuseRoughness`, `specularWeight`, `specularColor`, `coat*`, `fuzz*`, `thinFilm*`, `thinWalled`, `subsurface*`, `transmissionScatter*`, `transmissionDispersion*` |
+| `mutracerBevelSize` | material | Shader bevel radius |
+| `mutracerUvProjection`, `mutracerUvProjectionScale`, `mutracerUvReferenceLength` | material | Procedural UV projection |
+| `mutracerDisplacement*` | material | Displacement settings, same names as the `OpenPBRMaterial` fields; projection scale is `mutracerDisplacementUvProjectionScale` |
+| `mutracerThinFilmMap` | material | Native R thickness texture with minimum 0; takes precedence over `iridescenceThicknessMap` |
+| `mutracerRadius` | point / spot light | Emitter radius |
+| `mutracerIesProfile`, `mutracerIesRotation` | spot light | `IESProfile` instance; rotation becomes local-Z transform rotation |
+| `mutracerGroundedSkybox: { texture, height, radius, groundHeight?, center? }` | scene | Grounded skybox background |
+| `mutracerHiddenBackground: true` | scene | Transparent background while keeping environment lighting |
+
+Directional and spot lights use their world position and target to build a
+MuTracer transform; source rotation alone does not specify their direction.
+
+## Options
+
+`new THREESync(engine, options?)` accepts these optional sources and settings:
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `scene` | undefined | Three.js scene; omitted leaves engine.scene untouched |
+| `camera` | undefined | Perspective or orthographic camera; omitted leaves engine.camera untouched |
+| `controls` | undefined | Controls with update and start/end events, such as OrbitControls |
+| `updateControls` | true | Calls controls.update; false leaves updating to the application |
+| `convertMaterial` | undefined | `(sourceMaterial)` → OpenPBRMaterial, null to skip every mesh using it, undefined for built-in conversion |
+| `convertLight` | undefined | `(sourceLight)` → SceneLight, null to skip the light, undefined for built-in conversion |
+| `onMeshConverted` | undefined | `(mesh, source, group, groupIndex)` on every visible mesh/group during update |
+
+Construction subscribes to control events. The first update converts and writes
+sources to the engine. `scene` exposes the retained converted scene, or undefined
+when no source was supplied. A camera-only sync preserves a MuTracer-built scene.
+`active` covers start/end interaction, camera movement, damping and changing
+skinned/morph poses. OrbitControls damping stays consistent across render frame
+rates, and final refinement resumes when motion settles. Use
+`updateControls: false` when your application already updates the controls.
+
+`fromTHREEScene(scene, options?)` and `fromTHREECamera(camera, options?)` remain
+available for one-shot conversions. Each call reruns conversion hooks and creates fresh default objects; custom
+objects are kept by identity.
+Call `camera.updateProjectionMatrix()` after changing aspect or fov. A perspective
+camera's focus and film height become MuTracer focus distance and sensor height;
+pass `{fStop: 2.8}` to `fromTHREECamera` to enable depth of field.
+
+### Custom conversion
+
+Both `fromTHREEScene` and `THREESync` accept the conversion hooks:
+
+```ts
+import { OpenPBRMaterial, SphereLight } from '@meimu/mutracer';
+const customMaterial = new OpenPBRMaterial({baseColor: [0.2, 0.4, 0.8]});
+const customLight = new SphereLight({radius: 0.1, intensity: 3});
+const sync = new THREESync(engine, {
+  scene,
+  convertMaterial(source) {
+    if (source.type === 'ShaderMaterial') return customMaterial;
+    if (source.userData.skipPathTracing) return null;
+    return undefined;
+  },
+  convertLight(source) {
+    if (source.userData.customEmitter) return customLight;
+    return undefined;
+  },
+});
+// Edit the returned MuTracer material directly after initial conversion.
+customMaterial.baseColor = [0.8, 0.4, 0.2];
+```
+
+The sync caches each hook result (including null and undefined) by source
+identity and `version`. The material hook receives only the source material,
+so a shared material converts once for every mesh using it; use distinct
+source materials for per-mesh conversion. Set `threeMaterial.needsUpdate = true` to advance its version and
+rerun the hook. Returned objects are used by identity and are caller-owned;
+`engine.update()` detects edits to them. Automatic UV
+projection derives retained variants from the returned material; these refresh
+when its identity or parameters change.
+
+Three.js lights have no built-in `version`, so the light hook runs once. To
+rerun it, set a numeric `light.userData.mutracerVersion` and increment it. An undefined hook result keeps normal built-in material/light
+synchronization, including parameter edits that do not change the source
+version. A null material result skips every group/instance of its mesh.
+The environment texture follows the built-in conversion and is not a
+`THREE.Light` hook source.
+
+## Coat normal conversion
+
+`clearcoatNormalMap` uses the shared texture conversion cache and preserves its UV channel, scale, offset and `flipY`; `clearcoatNormalScale` is copied separately from `normalScale`. Explicit `mutracerOpenPBR.coatNormalMap` accepts a MuTracer Texture or Three.js Texture, and `null` clears the imported map. `coatNormalScale` metadata overrides the imported pair; unrelated metadata retains the imported anisotropy source convention. Arbitrary JSON objects are not interpreted as texture images. `THREESync` propagates map and scale edits.
+
+## Caveats
+
+THREESync updates world/bone matrices and retains unchanged meshes, materials,
+textures, lights, backgrounds and membership arrays. MuTracer transforms use
+Three.js matrixWorld, preserving double precision. Skinning and morphs run on the
+CPU, updating retained geometry in place. Other changed buffers replace geometry
+and require a [full mesh update](./updates.md#full-mesh-updates).
+
+`sync.dispose()` removes control subscriptions and conversion caches; it leaves
+the last converted scene usable. Updating a disposed sync throws. RenderLoop does
+not dispose supplied syncs or renders; see [ownership](./progressive-rendering.md#options-and-ownership).
+
+
+Native `mutracerOpenPBR` metadata can set `anisotropyMap` (a MuTracer or Three.js Texture, or null to clear), `specularAnisotropyRotation` and `coatAnisotropyRotation` (radians, default zero). Imported geometry preserves a tangent's optional W handedness.
+
+## Anisotropy source conversion
+
+`MeshPhysicalMaterial.anisotropy`, `anisotropyRotation` and `anisotropyMap` import as source strength, base rotation (radians) and the linear RG/B direction map, with `specularAnisotropyModel = 'gltf'`. Roughness and its maps retain source values. `GLTFLoader` supplies the extension defaults and texture coordinates; `THREESync` propagates later strength, rotation, texture and metadata edits without rewriting pixels. Nonphysical materials retain native semantics.
+
+For sampled source roughness r and strength a, u = r², A = u + (1 - u)a² and B = u. The native anisotropy is 1 - B/A (clamped to [0, 1] against Float32 roundoff) and native roughness is ((A² + B²)/2)^(1/4). A = B = 0 resolves to zero. Strength zero returns the original roughness directly. Conversion occurs after roughness/metallic-roughness sampling and the anisotropy blue multiplier, followed by the existing OpenPBR coat roughening. CPU conversion before multiplying maps would give different alpha axes and is not used. The coat's anisotropy is independent.
+
+Metadata overriding `specularAnisotropy` or `specularRoughnessAnisotropy` defaults back to `'openpbr'` and clears the automatically imported direction map/rotation to undefined/zero. Explicit metadata direction values can replace or restore them; explicit `specularAnisotropyModel: 'gltf'` retains source semantics and the imported directions. An unrelated override such as baseColor preserves the imported model. Texture overrides accept MuTracer/Three.js textures, and null clears a texture. Invalid model names throw.
+
+This is an alpha-parameter match, with approximation differences from the renderer's Fresnel, masking, energy compensation and layer model. Zero roughness with nonzero strength reaches the existing alpha minimum; this numerical endpoint does not reproduce a singular zero-width distribution. General KHR texture-transform rotation remains the adapter limitation documented above.

package/docs/todo.md

@@ -0,0 +1,61 @@
+# TODO
+
+Follow-ups deferred during the Engine / Display / Render API redesign. Each
+item says why it was deferred. None of them changes the current public API;
+the ones marked additive would only add to it.
+
+## Rendering and denoising
+
+- **HDR-stage post-process hooks.** `display.addPostProcess` runs after display
+  composition only. The built-in JNLM and OIDN filters denoise the composed
+  display-linear image and cache the result, so an HDR-stage hook would feed
+  the denoiser input and leave stale results whenever the hook changes. This
+  needs an invalidation rule first, for example restarting denoising when the
+  hook list or a hook revision changes.
+- **Shadow-catcher shadows with custom denoisers.** `DenoiseInput` provides only
+  color, albedo and normal. Catcher shadow masks are composited after filtering
+  and keep their noise. The built-in filters do filter these shadows. One option
+  is an optional mask buffer on `DenoiseInput` (additive).
+- **`readPixels('denoised')` depends on the filter.** Built-in filters return
+  display-linear values because they filter after tone mapping. Custom filters
+  return linear HDR. This is documented in TSDoc; consider a single contract.
+- **Unused alpha post-filter.** `WGPURenderingPipeline` keeps an OIDN alpha
+  post-filter (the `alphaDenoiser` parameter), but `Render` always passes
+  `undefined`. Expose it or remove it; removing an image-quality mechanism is
+  a maintainer decision.
+
+## Performance and memory
+
+- **Dirty ranges for `InstancedMesh`.** `markTransformsUpdated(start, count)` / `markColorsUpdated(start, count)`
+  validates its range, but a commit still copies the whole changed `transforms`
+  or `colors` array. Transform edits refit the whole TLAS; color edits only
+  upload instance records. Unchanged updates are already cheap (100,000
+  instances: about 10.6 ms down to 0.0025 ms per `engine.update()`); frames
+  that change transforms are not optimized.
+- **Camera allocation in `THREESync`.** Every `update()` creates a temporary
+  `Camera` with `fromTHREECamera` and copies it into the retained camera
+  (`src/util/fromTHREE.ts`). Update the retained camera in place instead.
+- **Render target memory.** A WebGPU render target uses about 110 bytes per
+  pixel. Check which buffers can be shared between renders or use narrower
+  formats.
+
+## Additive capabilities
+
+- **Multiple canvases.** `engine.createDisplay(canvas)` on WebGPU. WebGL
+  contexts cannot share resources, so WebGL keeps a single display.
+- **Several resident scenes.** `new Render(engine, {scene, camera})` would
+  override the engine's scene and camera per render. Today one scene is
+  resident on the GPU, and `engine.prepare(otherScene)` prepares CPU data only.
+
+## Viewer
+
+- **Device loss status.** Show device loss and recovery in the status bar,
+  using the engine's `devicelost` event. The library already recovers.
+
+## Decided against
+
+- **A scene graph.** Path tracing consumes a flat instance list. Hierarchy stays
+  in Three.js or the application, which computes each world `transform`.
+- **Open material or light type extension.** Every new type needs shader support
+  in both backends. Keep a closed set and maintain it through the internal
+  field tables.

package/docs/updates.md

@@ -0,0 +1,208 @@
+# Scene updates and animation
+
+This page is the reference for editing a scene that is already rendering.
+Keep the same scene, arrays and resources and edit them in place. Call
+`engine.update()` once per frame to detect and commit changes. Every Render
+uses that committed snapshot until the next update; editing or replacing the
+external scene/camera without calling update has no effect on tracing.
+Changes restart each render at its next refine. See
+[progressive rendering](./progressive-rendering.md) for preview selection.
+
+## What to do after a change
+
+`engine.update()` compares the scene with its last commit. It detects every
+property assignment, membership change and small value such as matrices,
+material parameters, light parameters and background fields. It does not read
+the contents of large arrays or images, so in-place edits to them need a
+notification first:
+
+| Edited in place | Notification |
+| --- | --- |
+| Texture pixels or UV-array elements | `texture.markUpdated()` |
+| Vertex attributes; indices and `materialIndex` unchanged | `geometry.markVerticesUpdated()` |
+| Indices, `materialIndex` or other geometry data | `geometry.markUpdated()` |
+| `instancedMesh.transforms` elements | `instancedMesh.markTransformsUpdated(start?, count?)` |
+| `instancedMesh.colors` elements | `instancedMesh.markColorsUpdated(start?, count?)` |
+| Both instance matrices and colors | `instancedMesh.markUpdated()` |
+
+Everything else, including the camera, `scene.meshes`, `mesh.transform`,
+replaced geometry, materials, textures or arrays, and `instancedMesh.count`,
+needs only `engine.update()`. Engine BVH settings also take effect at the next
+update; see [BVH](./bvh.md).
+
+```ts
+mesh.transform[12] += 0.1;           // detected
+material.specularRoughness = 0.6;    // detected
+// ...edit texture pixels...
+texture.markUpdated();               // pixels: notify
+engine.update(); final.refine(); engine.display.present(final);
+```
+
+With RenderLoop, edit sources before the next tick; the loop calls sync.update
+and engine.update. THREESync sends resource notifications for you. See
+[Three.js](./threejs.md#keeping-scenes-in-sync).
+
+## Transforms
+
+Edit `mesh.transform` in place while retaining the mesh objects and the
+`scene.meshes` array. Both WebGPU and WebGL 2 refit the top-level BVH over the
+changed instances and upload only the affected ranges.
+
+## Instanced meshes
+
+Use `InstancedMesh` for many copies of the same geometry and materials:
+
+```ts
+const batch = new InstancedMesh(geometry, material, {count: 1000});
+// Omitted transforms initialize every local matrix to identity.
+for (let i = 0; i < batch.count; i++) batch.transforms[i * 16 + 12] = i * 2;
+batch.markTransformsUpdated();
+scene.meshes.push(batch);
+engine.update();
+
+batch.transforms[16 + 12] += 1;
+batch.markTransformsUpdated(1, 1); // start/count are in instances, not floats
+engine.update();
+```
+
+`transforms` contains column-major Float32 matrices; the constructor retains a
+supplied array. Each world matrix is `batch.transform * transforms[i]`, so the
+inherited `position` and `lookAt` move the whole batch. Every instance uses the
+same material list, selected by the geometry's `materialIndex` exactly as for Mesh.
+
+`count` selects an active prefix and must be a nonnegative integer within the
+transforms and colors array capacity. Shrinking it retains the stored matrices; increase it again to
+reactivate that prefix. To grow beyond capacity, assign a larger Float32Array
+with the previous prefix copied. The default count and capacity come from the
+constructor. Empty batches are supported.
+
+Optional `colors` contains linear RGB multipliers, three Float32 values per
+instance; omitted colors are white. The array is retained and must hold at least
+`3 * count` values. All materials of an instance share its color. Colors multiply
+baseColor after texture sampling, and emissionColor only for unlit materials.
+They do not affect alpha, other layer colors, non-unlit emission or light sampling.
+Values are not clamped; results for nonfinite colors are undefined.
+
+```ts
+batch.colors = new Float32Array(batch.count * 3).fill(1); // replacement: detected
+batch.colors.set([0.2, 0.6, 1], 3);
+batch.markColorsUpdated(1, 1);
+engine.update();
+```
+
+After editing both matrices and colors, call `batch.markUpdated()` to notify
+both for all active instances. This does not notify geometry or material edits.
+For edits to just one array, use the dedicated notification (default range: all
+active instances):
+
+| Notification | Work avoided compared with `markUpdated()` |
+| --- | --- |
+| `markTransformsUpdated(start?, count?)` | Copying unchanged instance colors |
+| `markColorsUpdated(start?, count?)` | Copying instance matrices and refitting or rebuilding BVHs; only instance colors are uploaded |
+
+Each notification advances the read-only `version` once, initially zero.
+Replacing either array, removing colors, and changing count are detected automatically.
+Arrays are copied into the engine snapshot on their own version or storage change;
+unnotified edits remain uncommitted even when another scene resource changes. Call
+`engine.update()` before refining or converging.
+
+Caveats: individual instances have no names, transforms or materials as JS
+objects. Use separate batches for distinct material sets. Nonfinite world
+matrices are excluded, as with Mesh.
+The notification range is validated.
+
+## Materials, textures and lights
+
+Material parameter edits repack material parameters without touching geometry
+or BVHs. Emission edits also refresh light-sampling state, and texture edits
+rebuild the texture atlas. Displacement settings that move geometry require a
+[full mesh update](#full-mesh-updates).
+
+Analytic-light edits keep the environment map. Ambient and environment edits
+rebuild it. Rect-light texture edits require a full mesh update, because those
+textures live in the material atlas.
+
+## Geometry
+
+Choose the notification that matches the edit:
+
+| Edit | Notification | Effect |
+| --- | --- | --- |
+| Vertex attributes only; indices and `materialIndex` unchanged | `geometry.markVerticesUpdated()` | Advances `version`; keeps `topologyVersion`. Allows vertex updates and BLAS refits |
+| Indices, `materialIndex`, or any other geometry change | `geometry.markUpdated()` | Advances `version` and `topologyVersion`. Rebuilds the affected BLAS |
+
+```ts
+geometry.dynamic = true;               // for frequent deformation
+geometry.position.array[0] += 0.1;
+geometry.markVerticesUpdated();
+// The next engine.update commits this geometry and every mesh that uses it.
+```
+
+- Neither method recalculates normals or tangents. Update them before
+  notifying the renderer.
+- `markUpdated()` is valid for vertex edits too, but it can rebuild the BLAS
+  unnecessarily.
+- Keep the attribute arrays, their lengths and item sizes. Then both backends
+  update only the edited geometry's ranges and BLAS, and refit every instance
+  that shares it. Vertex, transform and material edits can be combined in one
+  frame.
+- Replaced arrays, changed lengths or item sizes, and displaced geometry
+  require a [full mesh update](#full-mesh-updates), whichever method you call.
+
+### Dynamic geometry
+
+Set `geometry.dynamic = true` (default `false`) for geometry that deforms
+every frame. Dynamic geometry always uses the built-in builder and the binary
+`'bvh2'` layout, whatever `engine.bvhBuilder` and `engine.bvhLayout` say,
+so its BLAS can be refitted. A refitted BLAS is rebuilt once its total node
+surface area exceeds twice the total of its last build, which limits quality
+loss during long deformations. Non-dynamic geometry refits layouts that
+support it and rebuilds the others.
+
+Refits and rebuilds run synchronously during committed GPU uploads. Three.js skinning
+and morph targets set `dynamic` automatically; try the
+[animation example](../examples/animation.html).
+
+## Adding, removing and reassigning meshes
+
+Adding, removing or reordering meshes, or replacing a mesh's material, is
+cheap when every mesh uses a single material and geometry that is already on
+the GPU: the renderer rebuilds the top-level BVH and instance data and reuses
+vertex data and BLASes. Otherwise, for example with new geometry, displacement
+or a `materialIndex` attribute, it needs a full mesh update.
+
+## Full mesh updates
+
+A full mesh update repacks and uploads all mesh data, and its cost grows with
+the whole scene rather than with the edit. It happens when:
+
+- attribute or index arrays are replaced, or their lengths or item sizes change;
+- displaced geometry or its displacement settings change;
+- a rect-light texture changes;
+- a mesh gets geometry that is not yet on the GPU, or meshes with displaced
+  or multi-material geometry are added, removed or reassigned.
+
+Avoid these in per-frame animation.
+
+## Preview and animation
+
+Create a cheaper preview Render and use it during motion. Give the final render
+`fallback: preview`; it transitions when its first complete sample is ready.
+Selection and coalescing of continuous animation changes belong to the
+application. Render.refine only executes the chosen settings, and samples
+always count that render's complete samples. For fixed-quality animation, use
+converge on each frame with disjoint sequence offsets.
+
+
+## Implementation notes
+
+Material detection compares each distinct material once per engine.update,
+however many meshes share it; cost grows with the number of distinct materials.
+
+On a version or storage change, the engine copies the full transforms or colors
+array; start/count validation does not limit the copied elements. In scenes
+containing batches, a transform update regenerates all instance records and
+refits the top-level BVH. World matrices keep double precision until GPU
+packing, matching Three.js world-matrix and inverse calculations. Instances
+share BLAS and vertices unless explicit materialIndex packing or displacement
+requires a distinct vertex region.

package/lib/Display.d.ts

@@ -0,0 +1,72 @@
+import type Render from './Render.js';
+import type { ToneMapping, DisplayChannel } from './renderer/RenderingPipeline.js';
+import type { ColorRGB } from './types.js';
+/** Display image channels. Default final. */
+export type { DisplayChannel } from './renderer/RenderingPipeline.js';
+/** Image encoding options for Display.toBlob. */
+export interface BlobOptions {
+    /** Browser image MIME type. Default image/png. */ type?: string;
+    /** Encoder quality in 0–1. Default undefined uses the browser default. */ quality?: number;
+}
+/** Optional shared display settings; defaults match Display. */
+export interface DisplaySettings {
+    /** Tone mapping transform. Default agx. */ toneMapping?: ToneMapping;
+    /** Linear exposure multiplier. Default 1. */ toneMappingExposure?: number;
+    /** Contrast multiplier. Default 1. */ contrast?: number;
+    /** Saturation multiplier. Default 1. */ saturation?: number;
+    /** White balance temperature shift in -1–1. Default 0. */ temperature?: number;
+    /** Green/magenta tint in -1–1. Default 0. */ tint?: number;
+    /** Vignette strength in 0–1. Default 0. */ vignette?: number;
+    /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity?: number;
+    /** Bloom luminance threshold. Default 1. */ bloomThreshold?: number;
+    /** Bloom radius in 0–1. Default 0.6. */ bloomRadius?: number;
+    /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled?: boolean;
+    /** Display image channel. Default final. */ channel?: DisplayChannel;
+    /** Linear shadow-catcher color. Default black. */ shadowCatcherColor?: ColorRGB;
+    /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha?: number;
+}
+/** Borrowed WebGPU images for one synchronous display pass. */
+export interface PostProcessContext {
+    /** Engine device; may change after recovery. */ device: GPUDevice;
+    /** Record commands here; the library finishes and submits it. */ encoder: GPUCommandEncoder;
+    /** Read-only composed display image, top row first; no additional color conversion. */ input: GPUTexture;
+    /** Fully write this image. Same format and dimensions as input; supports render, storage and copy writes. */ output: GPUTexture;
+    /** Actual render width. */ width: number;
+    /** Actual render height. */ height: number;
+    /** Selected complete render, including a selected fallback. */ render: Render;
+}
+/** Synchronous display pass. Images and encoder are borrowed only during the call; do not retain or destroy them. */
+export type PostProcess = (context: PostProcessContext) => void;
+/** Canvas presentation and shared display settings; obtained from engine.display. */
+export default class Display {
+    private readonly engine;
+    /** Display canvas. Default the supplied Engine canvas, or a new canvas (OffscreenCanvas without document). */ readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+    /** Tone mapping transform. Default agx. */ toneMapping: ToneMapping;
+    /** Linear exposure multiplier. Default 1. */ toneMappingExposure: number;
+    /** Contrast multiplier. Default 1. */ contrast: number;
+    /** Saturation multiplier. Default 1. */ saturation: number;
+    /** White balance temperature shift in -1–1. Default 0. */ temperature: number;
+    /** Green/magenta tint in -1–1. Default 0. */ tint: number;
+    /** Vignette strength in 0–1. Default 0. */ vignette: number;
+    /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity: number;
+    /** Bloom luminance threshold. Default 1. */ bloomThreshold: number;
+    /** Bloom radius in 0–1. Default 0.6. */ bloomRadius: number;
+    /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled: boolean;
+    /** Display image channel. Default final. */ channel: DisplayChannel;
+    /** Linear shadow-catcher color. Default black. */ shadowCatcherColor: ColorRGB;
+    /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha: number;
+    private constructor();
+    /** Resizes the drawing buffer; scale-based renders resize at their next refine. */
+    setSize(width: number, height: number): void;
+    private readonly settings;
+    private readonly _postProcesses;
+    private _warnedPostProcess;
+    /** Registers a display pass in order and returns an idempotent removal function. Default no passes. WebGPU only; WebGL skips passes with one warning. Runs after composition on every present/toBlob, without tracing or invalidating denoising. A thrown error discards the whole chain, presents the original image and emits engine error. */
+    addPostProcess(pass: PostProcess): () => void;
+    private warnPostProcess;
+    private compose;
+    /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */
+    present(render: Render): Render | undefined;
+    /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */
+    toBlob(render: Render, options?: BlobOptions): Promise<Blob>;
+}