@meimu/mutracer 0.2.0 → 0.3.0

package/docs/api.md

@@ -130,38 +130,40 @@ other sequences retain their completed samples.
 | `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.
+Paths allow at most `min(bounces * 3, 20)` events, including transmission,
+alpha skips and escape checks. Opaque paths also terminate at their scattering
+limit. The event budget can truncate deep transparent paths before the requested
+scattering depth. On Intel Mac WebGL, the event limit is `min(bounces, 3)`, doubled
+for scenes with transmission or alpha, with earlier scattering termination.
+See [caustic path-length limits](./caustics.md#limits) when comparing renderers.
 
 | Method / property | Meaning |
 | --- | --- |
 | `refine(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 +177,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 +205,25 @@ Resolves `{samples, averageSamplesPerPixel, pilotSamples, adaptiveSampling,
 varianceHistory?}` after filtering. It rejects if engine input revisions change.
 The same render cannot refine concurrently; other renders remain usable.
 
+### Caustics
+
+```ts
+render.caustics = {lightTracing: {photonsPerSample: 32768}};
+render.caustics = undefined; // Disable every estimator.
+```
+
+Changing any caustic option restarts accumulation. All estimators are experimental;
+see the [caustics guide](./caustics.md) for choosing estimators, supported paths,
+rendering cost and image-quality limitations.
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `lightTracing` | `false` | `true` or an object enables directly visible caustic light paths on WebGPU; ignored on WebGL 2 |
+| `lightTracing.photonsPerSample` | pixel count / 4 | Emitted photons per sample, rounded to a positive integer and capped by the device dispatch limit |
+| `photonMapping` | `false` | `true` or an object enables progressive caustic photon mapping on WebGPU; ignored on WebGL 2. See [PM-only denoising limits](./caustics.md#limits) |
+| `photonMapping.photonsPerSample` | pixel count / 4, at most 262144 | Emitted photons per batch; 28 bytes each plus up to 13 MiB of overhead. Positive finite values are rounded to at least 1 and reduced to fit device limits and a 128 MiB batch budget; other values use the default |
+| `photonMapping.initialRadius` | 3% of the caster bounding sphere radius | Positive first-batch gather radius in scene units, independent of `photonsPerSample`; shrinks as batches accumulate. Smaller radii preserve detail but require more photons |
+
 ## RenderLoop and Sync
 
 `start()` uses requestAnimationFrame when available and a 16 ms setTimeout
@@ -226,6 +244,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 +270,7 @@ Use `engine.display`; creation of additional displays is outside this API.
 their next refine; fixed renders retain their dimensions.
 `present(render)` only presents: it returns the render or its ready fallback,
 or undefined without changing the canvas when neither is ready.
-`toBlob(render, {type?, quality?})` composes that render at its actual dimensions,
+`toBlob(render, {type?, quality?})` composes that render at its output dimensions,
 without resizing or changing the current canvas. MIME defaults to image/png;
 quality defaults to the browser encoder value.
 
@@ -580,7 +599,9 @@ see [denoising](./denoising.md#custom-oidn-networks). The main entry exports
 
 `render.getOutputTexture(kind)` borrows native HDR or the latest display image;
 `display.addPostProcess(pass)` returns unregister and runs on every present/export.
-Both are WebGPU-only. See [formats, lifecycle and overlay example](./post-processing.md).
+Both are WebGPU-only. Textures are rounded up to multiples of 16 pixels, so a
+fixed render's texture can include extra pixels around the requested image. See
+[formats, lifecycle and overlay example](./post-processing.md).
 
 Anisotropy direction options: `anisotropyMap` (default `undefined`) reads linear RG as a tangent direction and B as a multiplier for base specular strength. `specularAnisotropyRotation` (default `0`) rotates that direction counter-clockwise in radians; `coatAnisotropyRotation` (default `0`) rotates the coat relative to the geometry tangent. See [materials](./materials.md#anisotropy-directions) for frame and fallback conventions.
 

package/docs/caustics.md

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

package/docs/materials.md

@@ -97,10 +97,11 @@ the substrate through the attenuation term.
 **Interior media.** Transmission describes a homogeneous volume:
 `transmissionColor` is the color that survives one `transmissionDepth`, and
 `transmissionScatter` is the scattering albedo. With `transmissionDepth = 0`
-the tint is applied at the surface. Subsurface is a separate layer driven by its
-color and per-channel radius. When both are active, their coefficients combine
-into one volume. Dispersion (`transmissionDispersionScale > 0`) samples
-wavelengths spectrally.
+the tint is applied at the surface. Subsurface has its own color and per-channel
+radius. A positive `transmissionDispersionScale` enables
+wavelength-dependent refraction; values above `1` increase color separation,
+and `0` disables it. Lower `transmissionDispersionAbbeNumber` values also
+increase color separation.
 
 ## Compatibility names
 

package/docs/progressive-rendering.md

@@ -87,24 +87,65 @@ 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.
 
 ## Reading and exporting
 

package/docs/technical/continuous-spectrum.md

@@ -0,0 +1,93 @@
+# Continuous-wavelength dispersion
+
+MuTracer renders dispersion with continuous wavelengths inside an RGB renderer.
+Wavelength decides how light refracts and how its energy divides between RGB
+channels. Lights, materials and media stay RGB, so this is not spectral rendering.
+The implementation is in `src/renderer/spectrum.ts`, and it runs only when a material
+has `transmissionDispersionScale > 0`.
+
+## Spectral response
+
+`spectrumRgb` converts a wavelength in 400–700 nm to linear sRGB weights:
+
+1. Evaluate the CIE 1931 matching functions with the multi-lobe fit from Wyman, Sloan
+   and Shirley, "Simple Analytic Approximations to the CIE XYZ Color Matching
+   Functions", JCGT 2(2), 2013.
+2. Convert XYZ to linear sRGB and clamp negative values to zero.
+3. Scale each channel so its mean over a uniform wavelength is 1.
+
+The scale keeps white light white on average. The clamp keeps out-of-gamut colors
+saturated instead of colorimetrically exact, and it leaves red with a small violet
+lobe, which is why the short end of a rainbow looks violet instead of blue.
+
+## Sampling
+
+Both integrators sample from 5 nm inverse CDF tables. They use different estimators
+because they carry different quantities.
+
+| | Camera paths | Caustic photons |
+|---|---|---|
+| Distribution | The response of the path's RGB channel | The sum of the RGB responses |
+| Carries | One RGB channel | RGB flux |
+| Energy weight | None; the distribution is the response | `spectrumRgb(λ) / (pdf(λ) · 300)` |
+| Random number | `CAMERA_WAVELENGTH`, shared by a sample's three paths | Photon emission dimension 69 |
+
+Camera paths evaluate no response, so their effective response is a 5 nm histogram of
+the fit. Photons apply the weight exactly. Sharing one random number across a camera
+sample's channels keeps their error correlated with the other common random numbers.
+
+`dispersionWavelengths: 3` traces one path per channel in each sample. With
+`dispersionWavelengths: 1`, a dispersive primary hit selects one channel at random
+and multiplies the result by 3; other primary hits trace full RGB. This is not hero
+wavelength sampling, which carries several wavelengths along one path and combines
+them with MIS.
+
+## Channels and gathering
+
+A path stores its channel and its refracting wavelength separately:
+`spectralChannel` selects the radiance it keeps, and `wavelength` only drives
+`sampling_cauchy_ior`. A channel of 0 keeps full RGB. Red paths can sample violet, so
+the channel cannot be derived from the wavelength.
+
+Photon gathering filters photon flux by the camera path's channel. This splits RGB
+across the camera paths and applies no second spectral weight, so energy is shared
+between path tracing and caustics the same way as without dispersion.
+
+## Short-wavelength IOR limit
+
+Cauchy IOR rises quickly at short wavelengths. At strong dispersion scales, violet
+light reaches IORs that reflect or trap much of it, and wide caustics turn yellow.
+`spectrumIorWavelength` therefore eases the refracting wavelength below 500 nm toward
+475 nm, while color keeps the sampled wavelength. The mapping is monotonic and
+continuous, so the gradient has no hard edge.
+
+This limit is an artistic choice and not physically based. It narrows the violet end
+of the spectrum, and strong dispersion scales still lose some blue.
+
+## Differences from spectral rendering
+
+| Area | Spectral rendering | MuTracer |
+|---|---|---|
+| Lights | Emission varies with wavelength | RGB, with an implicit broad spectrum; a sodium lamp still disperses into a full rainbow |
+| Materials and textures | Reflectance varies with wavelength, often upsampled from RGB | RGB, so metamerism cannot appear |
+| Media | Absorption and scattering vary with wavelength | Three RGB coefficients |
+| Thin film | Interference is integrated over wavelength | Evaluated at 620, 540 and 450 nm |
+| Refractive index | Often measured curves or Sellmeier equations | Cauchy from IOR and Abbe number, with the short-wavelength limit |
+| Wavelengths per path | Often several, combined with MIS | One per path or photon |
+| Output color | Integrated from the spectrum into the output color space | Fixed clamped sRGB weights, normalized per channel |
+
+These differences matter most for narrow-band lights, colored absorption over long
+paths, metamerism and predictive color. Clear glass and crystal under broad lights are
+closer to the spectral result, because their color comes mainly from refraction.
+
+Full spectral rendering would change the light, material, texture and medium data
+models, and requires RGB-to-spectrum upsampling in both shader backends and native.
+
+## Changing this code
+
+- Update WGSL and GLSL together. Both are generated from `spectrum.ts`; caustics are
+  WGSL only.
+- `spectralChannel` must be set wherever a path's wavelength is set.
+- `tests/unit/spectrum.test.ts` covers white balance, weight bounds, channel
+  distributions and the IOR limit. Check the image result on a real GPU in both
+  backends, as described in `AGENTS.md`.

package/docs/updates.md

@@ -154,7 +154,9 @@ do not recompile the path tracer. Neither do changes to `bounces`,
 bevel switch, sample count or seed. Data uploads, atlas/BVH work and accumulation
 restarts may still be needed.
 
-Returning to a cached compatible combination reuses its pipeline. Prepared
+A render waiting for a shader keeps its samples and image, and other renders keep
+sampling. Returning to a cached compatible combination reuses its pipeline, even
+while another combination is still compiling. Prepared
 combinations may be discarded after many different edits; recreating the Engine
 or recovering a lost device also requires preparing shaders again. Compilation time depends
 on the feature combination, BVH layout, browser and GPU driver. Denoising and

package/docs/viewer-checklist.md

@@ -0,0 +1,65 @@
+# Viewer feature checklist
+
+Use this checklist with the [Web viewer](https://mutracer.meimu-studio.com/viewer/)
+and [native viewer](../native/viewer/README.md). Start with material spheres,
+then use a glTF with nested objects, cameras, lights and animation. A checked
+item means you exercised the behavior in the version being reviewed; it does
+not promise identical rendered pixels between devices or backends.
+
+## Workflow
+
+| Check | Action and expected result |
+| --- | --- |
+| [ ] Open | Open a GLB, a glTF with external buffers/images, a folder and a model URL; geometry and textures load. Drop files on the viewport. On Web, a fresh load uses the collection's curated view or the file's first camera, including orthographic cameras; restoring a saved view takes precedence. Failed or cancelled loads leave the previous scene usable. |
+| [ ] Examples | Open **Examples** in the toolbar; switch between MuTracer collection and glTF Research Scenes, load a thumbnail and check its camera and authored lighting. |
+| [ ] Scene | Search objects or materials and expand nested groups and meshes; select a material child to open its editor. Select an object from the tree or viewport; selection reveals its ancestors. Hide/show a mesh and a group. Select an authored camera. |
+| [ ] Navigation | Drag to orbit, right-drag to pan, scroll to zoom, **F** to fit. Moving an authored camera continues in Orbit. |
+| [ ] History | Undo/redo material, visibility, lighting and render edits; one continuous drag is one step. Reset all restores defaults. On Web, it also restores the example's render choices and initial camera, or fits the model when no camera is provided. |
+| [ ] Panels | **1–4** opens Lighting, Material, Camera, Render respectively. **[**, **]** toggle scene/inspector; click the active rail tab to close it. **H** hides the interface. Text input must not trigger shortcuts. |
+| [ ] Playback | **Space** plays/pauses animation when present, otherwise pauses/resumes rendering. Choose another clip and seek the timeline. |
+| [ ] Render dock | Change sample target, viewport resolution and denoising; pause/resume and inspect sample progress, elapsed time and completion. **D** toggles denoising. |
+| [ ] Export | **E** opens a preview; save the displayed viewport PNG. Render Viewport/1080p/2K/4K/Square PNG with a separate sample budget, denoising and optional transparency. Cancel an export and continue using the original image. |
+| [ ] Code/help | Open Code and copy a setup for the corresponding SDK; open keyboard help. **⌘O / Ctrl+O** opens files. |
+
+## Lighting, materials, camera and rendering
+
+| Check | Controls and expected result |
+| --- | --- |
+| [ ] Environment | Switch HDRI / Studio and model lighting where available. Load a local HDR or browse Poly Haven; change HDR resolution, intensity and rotation. Failed downloads keep the previous lighting. |
+| [ ] Studio | Choose each rig; adjust intensity, rotation, size, ambient strength and color. |
+| [ ] Background | Switch environment, color, transparent and grounded modes where offered. Adjust projection height/radius; verify auto values and transparency in exported PNG. |
+| [ ] Ground | Enable ground shadow and change opacity; inspect contact with the model. |
+| [ ] Material selection | Pick a mesh/material, check shared-material edits, apply a preset and reset to loaded values. |
+| [ ] Material layers | Exercise base color/weight, metalness, roughness, diffuse roughness, IOR/specular, anisotropy, transmission/volume/thin wall, subsurface, coat, fuzz, thin film, emission, opacity/alpha and double-sided/unlit controls where offered. |
+| [ ] Textures | Upload, replace and remove each exposed slot; change Wrap S/T and Repeat S/T, including negative repeats. Apply a Poly Haven set with optional displacement; cancel/replace downloads and switch materials during download. |
+| [ ] Displacement | Change scale, bias, subdivision and smoothing; verify silhouettes and return to zero displacement. |
+| [ ] MaterialX (Web) | Import a .zip package or .mtlx with images; check converted layers and textures. |
+| [ ] Camera | Switch Perspective/Orthographic, adjust FOV, auto-rotate and Fit. Authored cameras keep their projection/FOV until Orbit resumes. |
+| [ ] Depth of field | Enable DOF, adjust f-number, area autofocus and focus frame; move the frame, manually edit focus or pick a point; choose automatic or explicit scene units. Orthographic views disable DOF. |
+| [ ] Quality | Change max samples, bounces, resolution, sampling pattern and clamping. Web also offers a BVH builder. |
+| [ ] Caustics | Toggle light tracing and photon mapping; compare each alone and together on a glass scene. Web's master Caustics switch gates both. |
+| [ ] Denoiser | Toggle JNLM/OIDN; adjust JNLM strength, search/patch radius, albedo/normal tolerance and passes; choose OIDN Standard/Small/Large and tile size. Reset selected parameters. |
+| [ ] Color | Change AgX/ACES/Cineon/Reinhard/Linear, exposure, contrast, saturation, temperature and tint; verify exported colors. |
+| [ ] Effects | Enable bloom, threshold/radius and vignette; turn them off and verify the image returns. |
+| [ ] Debug | Expand/collapse Debug; inspect Final, Albedo, Normal, Depth, Position, Roughness, Diffuse/Specular reflectance, ID and Motion. Adjust channel ranges and ID component; toggle interactive preview and max preview scale. Overlay gestures must not orbit/select the scene. |
+| [ ] Window size | Check wide and narrow windows, hidden panels and long names; controls remain readable and the viewport remains usable. Web also provides the mobile bottom sheet. |
+
+## Platform options and limits
+
+| Area | Web | Native |
+| --- | --- | --- |
+| Rendering device | WebGPU; WebGL 2 fallback reloads the page | HWRT / Software BVH; device availability is reported in the UI |
+| Denoising | WebGL 2 supports JNLM; OIDN needs WebGPU | JNLM/OIDN; optional Windows DLSS RR build |
+| HDR display | WebGPU plus compatible browser/display; falls back to SDR | Viewer window is SDR; HDR toggle is disabled |
+| BVH builder | tinybvh / builtin | No builder selector |
+| MaterialX import | .zip or .mtlx with images | No MaterialX import UI |
+| Caustics controls | Master switch plus two methods; methods require WebGPU | Independent method switches; both off disables caustics |
+| File access | Multi-file/folder picker; URLs need CORS | File/folder picker; folder Open selects a top-level glTF/GLB; resources resolve beside the model |
+| Code | JavaScript setup | Rust SDK setup |
+| Examples browser | Popover with optional pinned panel | Toolbar opens a docked panel |
+| Extra native controls | — | Fixed-pixel render sizes, directional key light |
+| Small screens | Mobile sheet and responsive toolbar | Desktop panels; scene list hides when space is limited |
+
+Native and Web use different UI toolkits and fonts. Check icon meaning,
+label order, alignment and control availability; file dialogs, window controls,
+font rasterization and responsive behavior follow each platform.

package/docs/viewer.md

@@ -21,17 +21,17 @@ resampled to at most 2K width. If a source map is missing, the model still opens
 and the Lighting panel explains which map is unavailable; choose an environment
 there to replace it.
 
-glTF Research Scenes automatically use their first camera when available.
-For other glTF/GLB imports with cameras, a toast offers **Apply camera** to
-use the first camera; dismiss it to keep the Orbit view. You can select any
+MuTracer collection examples open with a curated view, under the procedural
+sky or a Poly Haven HDRI. A few also set their own tone mapping and bloom, which
+return to the defaults when you leave them. Other models with cameras open in their
+first camera. You can select any
 imported camera in the separate camera toolbar at the bottom right; it appears
 only for models with cameras. Drag, pan or zoom after selecting a camera to
 continue in **Orbit** from that view.
 Hover over a camera in the scene tree and click its camera action to apply it
 directly. **Fit to model** in the bottom toolbar (or **F**) returns to Orbit
 and frames the model.
-Reloading the current model restores your saved camera selection without
-showing the prompt again.
+Reloading the current model restores your saved camera selection.
 
 Picking an object in the viewport reveals it in the scene tree and scrolls it
 into view. Material rows start collapsed; expand a mesh to see its materials.
@@ -54,6 +54,8 @@ https://mutracer.meimu-studio.com/viewer/?hdrOutputEnabled=true&maxSamples=128#m
 The viewer updates the URL as lighting, render and display settings change.
 Copy the address bar to share those settings and the selected example model.
 Settings also work in the hash, such as `#model=dragon&hdrOutputEnabled=true`.
+A link with only `#model=…` opens the example with its own render settings, as
+the Examples menu does. Settings in a link win over the example's.
 
 ### Options
 

package/lib/Display.js

@@ -127,7 +127,7 @@ export default class Display {
         const target = this.compose(render);
         if (!target)
             throw new Error('Render has no complete image.');
-        const image = await target.readPresentation();
+        const image = render._cropOutput(await target.readPresentation());
         const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);
         const context = canvas.getContext('2d');
         if (!context)

package/lib/Display.js.map

@@ -1 +1 @@
-{"version":3,"file":"Display.js","sourceRoot":"","sources":["../src/Display.ts"],"names":[],"mappings":"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","sourcesContent":["import {displayAovKind, validateAovDisplay, type AovIdComponent} from './renderer/aovDisplay.js';\nexport type {AovIdComponent} from './renderer/aovDisplay.js';\nimport {createCanvas} from './util/canvas.js';\nimport type Engine from './Engine.js';\nimport type Render from './Render.js';\nimport type { ToneMapping, DisplayChannel } from './renderer/RenderingPipeline.js';\nimport type { ColorRGB } from './types.js';\nimport { displaySettingsKey, displayFilterSettingsKey, applyDisplaySettings } from './settings/display.js';\n/** Display image channels. Default final. */\nexport type {DisplayChannel} from './renderer/RenderingPipeline.js';\n/** Image encoding options for Display.toBlob. */\nexport interface BlobOptions {\n  /** Browser image MIME type. Default image/png. */ type?: string;\n  /** Encoder quality in 0–1. Default undefined uses the browser default. */ quality?: number;\n}\n/** Optional shared display settings; defaults match Display. */\nexport interface DisplaySettings {\n  /** Tone mapping transform. Default agx. */ toneMapping?: ToneMapping;\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure?: number;\n  /** Contrast multiplier. Default 1. */ contrast?: number;\n  /** Saturation multiplier. Default 1. */ saturation?: number;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature?: number;\n  /** Green/magenta tint in -1–1. Default 0. */ tint?: number;\n  /** Vignette strength in 0–1. Default 0. */ vignette?: number;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity?: number;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold?: number;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius?: number;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled?: boolean;\n  /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel?: DisplayChannel;\n  /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange?: readonly [number, number];\n  /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale?: number;\n  /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale?: number;\n  /** Stable ID lane to colorize. Default object. */ aovIdComponent?: AovIdComponent;\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor?: ColorRGB;\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha?: number;\n}\n/** Borrowed WebGPU images for one synchronous display pass. */\nexport interface PostProcessContext {\n  /** Engine device; may change after recovery. */ device: GPUDevice;\n  /** Record commands here; the library finishes and submits it. */ encoder: GPUCommandEncoder;\n  /** Read-only composed display image, top row first; no additional color conversion. */ input: GPUTexture;\n  /** Fully write this image. Same format and dimensions as input; supports render, storage and copy writes. */ output: GPUTexture;\n  /** Actual render width. */ width: number;\n  /** Actual render height. */ height: number;\n  /** Selected complete render, including a selected fallback. */ render: Render;\n}\n/** Synchronous display pass. Images and encoder are borrowed only during the call; do not retain or destroy them. */\nexport type PostProcess = (context: PostProcessContext) => void;\n/** Canvas presentation and shared display settings; obtained from engine.display. */\nexport default class Display {\n  /** Display canvas. Default the supplied Engine canvas, or a new canvas (OffscreenCanvas without document). */ readonly canvas: HTMLCanvasElement | OffscreenCanvas;\n  /** Tone mapping transform. Default agx. */ toneMapping: ToneMapping = 'agx';\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure = 1;\n  /** Contrast multiplier. Default 1. */ contrast = 1;\n  /** Saturation multiplier. Default 1. */ saturation = 1;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature = 0;\n  /** Green/magenta tint in -1–1. Default 0. */ tint = 0;\n  /** Vignette strength in 0–1. Default 0. */ vignette = 0;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity = 0;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold = 1;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius = 0.6;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled = false;\n  /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel: DisplayChannel = 'final';\n  /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange: readonly [number, number] = [0, 10];\n  /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale = 1;\n  /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale = 16;\n  /** Stable ID lane to colorize. Default object. */ aovIdComponent: AovIdComponent = 'object';\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor: ColorRGB = [0, 0, 0];\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha = 1;\n  private constructor(private readonly engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { this.canvas = canvas; }\n  /** @internal */ static _create(engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { return new Display(engine, canvas); }\n  /** Resizes the drawing buffer; scale-based renders resize at their next refine. */\n  setSize(width: number, height: number) {\n    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) throw new Error('Display dimensions must be positive.');\n    width = Math.round(width); height = Math.round(height);\n    if (this.canvas.width !== width) this.canvas.width = width;\n    if (this.canvas.height !== height) this.canvas.height = height;\n  }\n  private readonly _filterSettings = new WeakMap<Render, string>();\n  private readonly settings = new WeakMap<Render, string>();\n  /** @internal */ _configure(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target) return;\n    const kind = displayAovKind(this.channel);\n    if (!kind && !['final','normal','albedo','shadow','shadowCatcher'].includes(this.channel)) throw new RangeError('Unknown display channel');\n    if (kind && !render.aovs.includes(kind)) throw new Error(`AOV ${kind} is not enabled on the selected render`);\n    validateAovDisplay({depthRange: this.aovDepthRange, positionScale: this.aovPositionScale, motionScale: this.aovMotionScale, idComponent: this.aovIdComponent});\n    const key = displaySettingsKey(this);\n    const filterKey = displayFilterSettingsKey(this);\n    const previous = this.settings.get(render);\n    if (previous !== key) {\n      this.settings.set(render, key);\n      if (previous !== undefined && this._filterSettings.get(render) !== filterKey) render._displayChanged();\n      this._filterSettings.set(render, filterKey);\n    }\n    target.activate();\n    applyDisplaySettings(this, target);\n  }\n  private readonly _postProcesses: {pass: PostProcess}[] = [];\n  private _warnedPostProcess = false;\n  /** 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. */\n  addPostProcess(pass: PostProcess): () => void {\n    const entry = {pass};\n    this._postProcesses.push(entry);\n    if (this.engine.backend === 'webgl') this.warnPostProcess();\n    return () => { const index = this._postProcesses.indexOf(entry); if (index >= 0) this._postProcesses.splice(index, 1); };\n  }\n  private warnPostProcess() {\n    if (!this._warnedPostProcess) { this._warnedPostProcess = true; console.warn('Display post-processing requires WebGPU; passes are ignored on WebGL.'); }\n  }\n  private compose(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target) return;\n    const kind = displayAovKind(this.channel);\n    if (!kind && !target.presentationComplete) return;\n    if (kind && !render.aovs.includes(kind)) throw new Error(`AOV ${kind} is not enabled on the selected render`);\n    if (kind && target.aovReady && !target.aovReady(kind)) return;\n    this._configure(render);\n    target.drawPostProcess();\n    if (this._postProcesses.length && this.engine.backend === 'webgl') this.warnPostProcess();\n    try { target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render); }\n    catch (error) { this.engine._notifyError(error); }\n    return target;\n  }\n  /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */\n  present(render: Render): Render | undefined {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const ready = this.channel === 'final' && render.fallback ? render._presentable : render._completeFor(this.channel);\n    const fallback = render.fallback;\n    const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._completeFor(this.channel)) ? fallback : undefined;\n    if (!selected) return;\n    const target = this.compose(selected);\n    if (!target) return;\n    this.engine._present(target);\n    return selected;\n  }\n  /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */\n  async toBlob(render: Render, options: BlobOptions = {}): Promise<Blob> {\n    const target = this.compose(render);\n    if (!target) throw new Error('Render has no complete image.');\n    const image = await target.readPresentation();\n    const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);\n    const context = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;\n    if (!context) throw new Error('The image encoding context is not available.');\n    const bytes = new Uint8ClampedArray(image.data.length);\n    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.round(Math.min(1, Math.max(0, image.data[i])) * 255);\n    context.putImageData(new ImageData(bytes, image.width, image.height), 0, 0);\n    if ('convertToBlob' in canvas) return canvas.convertToBlob({type: options.type ?? 'image/png', quality: options.quality});\n    return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error('The image could not be encoded')), options.type ?? 'image/png', options.quality));\n  }\n}\n"]}
+{"version":3,"file":"Display.js","sourceRoot":"","sources":["../src/Display.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAE,kBAAkB,EAAsB,MAAM,0BAA0B,CAAC;AAEjG,OAAO,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAK9C,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAyC3G,qFAAqF;AACrF,MAAM,CAAC,OAAO,OAAO,OAAO;IAoBW;IAnBrC,8GAA8G,CAAU,MAAM,CAAsC;IACpK,2CAA2C,CAAC,WAAW,GAAgB,KAAK,CAAC;IAC7E,6CAA6C,CAAC,mBAAmB,GAAG,CAAC,CAAC;IACtE,sCAAsC,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpD,wCAAwC,CAAC,UAAU,GAAG,CAAC,CAAC;IACxD,0DAA0D,CAAC,WAAW,GAAG,CAAC,CAAC;IAC3E,6CAA6C,CAAC,IAAI,GAAG,CAAC,CAAC;IACvD,2CAA2C,CAAC,QAAQ,GAAG,CAAC,CAAC;IACzD,iDAAiD,CAAC,cAAc,GAAG,CAAC,CAAC;IACrE,4CAA4C,CAAC,cAAc,GAAG,CAAC,CAAC;IAChE,wCAAwC,CAAC,WAAW,GAAG,GAAG,CAAC;IAC3D,2EAA2E,CAAC,gBAAgB,GAAG,KAAK,CAAC;IACrG,uFAAuF,CAAC,OAAO,GAAmB,OAAO,CAAC;IAC1H,gGAAgG,CAAC,aAAa,GAA8B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACpJ,mGAAmG,CAAC,gBAAgB,GAAG,CAAC,CAAC;IACzH,qGAAqG,CAAC,cAAc,GAAG,EAAE,CAAC;IAC1H,kDAAkD,CAAC,cAAc,GAAmB,QAAQ,CAAC;IAC7F,kDAAkD,CAAC,kBAAkB,GAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5F,oDAAoD,CAAC,kBAAkB,GAAG,CAAC,CAAC;IAC5E,YAAqC,MAAc,EAAE,MAA2C;QAA3D,WAAM,GAAN,MAAM,CAAQ;QAAiD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IAAC,CAAC;IAC3H,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,MAAc,EAAE,MAA2C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACpI,mFAAmF;IACnF,OAAO,CAAC,KAAa,EAAE,MAAc;QACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC5I,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QAC3D,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACjE,CAAC;IACgB,eAAe,GAAG,IAAI,OAAO,EAAkB,CAAC;IAChD,QAAQ,GAAG,IAAI,OAAO,EAAkB,CAAC;IAC1D,gBAAgB,CAAC,UAAU,CAAC,MAAc;QACxC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,OAAO,EAAC,QAAQ,EAAC,QAAQ,EAAC,QAAQ,EAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,MAAM,IAAI,UAAU,CAAC,yBAAyB,CAAC,CAAC;QAC3I,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,wCAAwC,CAAC,CAAC;QAC9G,kBAAkB,CAAC,EAAC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,aAAa,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,EAAE,IAAI,CAAC,cAAc,EAAE,WAAW,EAAE,IAAI,CAAC,cAAc,EAAC,CAAC,CAAC;QAC/J,MAAM,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,SAAS,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS;gBAAE,MAAM,CAAC,eAAe,EAAE,CAAC;YACvG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC9C,CAAC;QACD,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IACgB,cAAc,GAA0B,EAAE,CAAC;IACpD,kBAAkB,GAAG,KAAK,CAAC;IACnC,iVAAiV;IACjV,cAAc,CAAC,IAAiB;QAC9B,MAAM,KAAK,GAAG,EAAC,IAAI,EAAC,CAAC;QACrB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC5D,OAAO,GAAG,EAAE,GAAG,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;YAAE,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3H,CAAC;IACO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAAC,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;QAAC,CAAC;IAC1J,CAAC;IACO,OAAO,CAAC,MAAc;QAC5B,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB;YAAE,OAAO;QAClD,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,wCAAwC,CAAC,CAAC;QAC9G,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,OAAO;QAC9D,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,CAAC,eAAe,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1F,IAAI,CAAC;YAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAAC,CAAC;QAC1F,OAAO,KAAK,EAAE,CAAC;YAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,kIAAkI;IAClI,OAAO,CAAC,MAAc;QACpB,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpH,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC9J,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,8GAA8G;IAC9G,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,UAAuB,EAAE;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,MAAM,CAAC,gBAAgB,EAAE,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,eAAe,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;QACvF,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAwE,CAAC;QAC/G,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAC5G,OAAO,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5E,IAAI,eAAe,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC,aAAa,CAAC,EAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAC,CAAC,CAAC;QAC1H,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3L,CAAC;CACF","sourcesContent":["import {displayAovKind, validateAovDisplay, type AovIdComponent} from './renderer/aovDisplay.js';\nexport type {AovIdComponent} from './renderer/aovDisplay.js';\nimport {createCanvas} from './util/canvas.js';\nimport type Engine from './Engine.js';\nimport type Render from './Render.js';\nimport type { ToneMapping, DisplayChannel } from './renderer/RenderingPipeline.js';\nimport type { ColorRGB } from './types.js';\nimport { displaySettingsKey, displayFilterSettingsKey, applyDisplaySettings } from './settings/display.js';\n/** Display image channels. Default final. */\nexport type {DisplayChannel} from './renderer/RenderingPipeline.js';\n/** Image encoding options for Display.toBlob. */\nexport interface BlobOptions {\n  /** Browser image MIME type. Default image/png. */ type?: string;\n  /** Encoder quality in 0–1. Default undefined uses the browser default. */ quality?: number;\n}\n/** Optional shared display settings; defaults match Display. */\nexport interface DisplaySettings {\n  /** Tone mapping transform. Default agx. */ toneMapping?: ToneMapping;\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure?: number;\n  /** Contrast multiplier. Default 1. */ contrast?: number;\n  /** Saturation multiplier. Default 1. */ saturation?: number;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature?: number;\n  /** Green/magenta tint in -1–1. Default 0. */ tint?: number;\n  /** Vignette strength in 0–1. Default 0. */ vignette?: number;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity?: number;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold?: number;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius?: number;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled?: boolean;\n  /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel?: DisplayChannel;\n  /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange?: readonly [number, number];\n  /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale?: number;\n  /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale?: number;\n  /** Stable ID lane to colorize. Default object. */ aovIdComponent?: AovIdComponent;\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor?: ColorRGB;\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha?: number;\n}\n/** Borrowed WebGPU images for one synchronous display pass. */\nexport interface PostProcessContext {\n  /** Engine device; may change after recovery. */ device: GPUDevice;\n  /** Record commands here; the library finishes and submits it. */ encoder: GPUCommandEncoder;\n  /** Read-only composed display image, top row first; no additional color conversion. */ input: GPUTexture;\n  /** Fully write this image. Same format and dimensions as input; supports render, storage and copy writes. */ output: GPUTexture;\n  /** Actual render width. */ width: number;\n  /** Actual render height. */ height: number;\n  /** Selected complete render, including a selected fallback. */ render: Render;\n}\n/** Synchronous display pass. Images and encoder are borrowed only during the call; do not retain or destroy them. */\nexport type PostProcess = (context: PostProcessContext) => void;\n/** Canvas presentation and shared display settings; obtained from engine.display. */\nexport default class Display {\n  /** Display canvas. Default the supplied Engine canvas, or a new canvas (OffscreenCanvas without document). */ readonly canvas: HTMLCanvasElement | OffscreenCanvas;\n  /** Tone mapping transform. Default agx. */ toneMapping: ToneMapping = 'agx';\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure = 1;\n  /** Contrast multiplier. Default 1. */ contrast = 1;\n  /** Saturation multiplier. Default 1. */ saturation = 1;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature = 0;\n  /** Green/magenta tint in -1–1. Default 0. */ tint = 0;\n  /** Vignette strength in 0–1. Default 0. */ vignette = 0;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity = 0;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold = 1;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius = 0.6;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled = false;\n  /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel: DisplayChannel = 'final';\n  /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange: readonly [number, number] = [0, 10];\n  /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale = 1;\n  /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale = 16;\n  /** Stable ID lane to colorize. Default object. */ aovIdComponent: AovIdComponent = 'object';\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor: ColorRGB = [0, 0, 0];\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha = 1;\n  private constructor(private readonly engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { this.canvas = canvas; }\n  /** @internal */ static _create(engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { return new Display(engine, canvas); }\n  /** Resizes the drawing buffer; scale-based renders resize at their next refine. */\n  setSize(width: number, height: number) {\n    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) throw new Error('Display dimensions must be positive.');\n    width = Math.round(width); height = Math.round(height);\n    if (this.canvas.width !== width) this.canvas.width = width;\n    if (this.canvas.height !== height) this.canvas.height = height;\n  }\n  private readonly _filterSettings = new WeakMap<Render, string>();\n  private readonly settings = new WeakMap<Render, string>();\n  /** @internal */ _configure(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target) return;\n    const kind = displayAovKind(this.channel);\n    if (!kind && !['final','normal','albedo','shadow','shadowCatcher'].includes(this.channel)) throw new RangeError('Unknown display channel');\n    if (kind && !render.aovs.includes(kind)) throw new Error(`AOV ${kind} is not enabled on the selected render`);\n    validateAovDisplay({depthRange: this.aovDepthRange, positionScale: this.aovPositionScale, motionScale: this.aovMotionScale, idComponent: this.aovIdComponent});\n    const key = displaySettingsKey(this);\n    const filterKey = displayFilterSettingsKey(this);\n    const previous = this.settings.get(render);\n    if (previous !== key) {\n      this.settings.set(render, key);\n      if (previous !== undefined && this._filterSettings.get(render) !== filterKey) render._displayChanged();\n      this._filterSettings.set(render, filterKey);\n    }\n    target.activate();\n    applyDisplaySettings(this, target);\n  }\n  private readonly _postProcesses: {pass: PostProcess}[] = [];\n  private _warnedPostProcess = false;\n  /** 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. */\n  addPostProcess(pass: PostProcess): () => void {\n    const entry = {pass};\n    this._postProcesses.push(entry);\n    if (this.engine.backend === 'webgl') this.warnPostProcess();\n    return () => { const index = this._postProcesses.indexOf(entry); if (index >= 0) this._postProcesses.splice(index, 1); };\n  }\n  private warnPostProcess() {\n    if (!this._warnedPostProcess) { this._warnedPostProcess = true; console.warn('Display post-processing requires WebGPU; passes are ignored on WebGL.'); }\n  }\n  private compose(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target) return;\n    const kind = displayAovKind(this.channel);\n    if (!kind && !target.presentationComplete) return;\n    if (kind && !render.aovs.includes(kind)) throw new Error(`AOV ${kind} is not enabled on the selected render`);\n    if (kind && target.aovReady && !target.aovReady(kind)) return;\n    this._configure(render);\n    target.drawPostProcess();\n    if (this._postProcesses.length && this.engine.backend === 'webgl') this.warnPostProcess();\n    try { target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render); }\n    catch (error) { this.engine._notifyError(error); }\n    return target;\n  }\n  /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */\n  present(render: Render): Render | undefined {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const ready = this.channel === 'final' && render.fallback ? render._presentable : render._completeFor(this.channel);\n    const fallback = render.fallback;\n    const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._completeFor(this.channel)) ? fallback : undefined;\n    if (!selected) return;\n    const target = this.compose(selected);\n    if (!target) return;\n    this.engine._present(target);\n    return selected;\n  }\n  /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */\n  async toBlob(render: Render, options: BlobOptions = {}): Promise<Blob> {\n    const target = this.compose(render);\n    if (!target) throw new Error('Render has no complete image.');\n    const image = render._cropOutput(await target.readPresentation());\n    const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);\n    const context = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;\n    if (!context) throw new Error('The image encoding context is not available.');\n    const bytes = new Uint8ClampedArray(image.data.length);\n    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.round(Math.min(1, Math.max(0, image.data[i])) * 255);\n    context.putImageData(new ImageData(bytes, image.width, image.height), 0, 0);\n    if ('convertToBlob' in canvas) return canvas.convertToBlob({type: options.type ?? 'image/png', quality: options.quality});\n    return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error('The image could not be encoded')), options.type ?? 'image/png', options.quality));\n  }\n}\n"]}

package/lib/Engine.d.ts

@@ -67,6 +67,8 @@ export default class Engine {
     private _bvhWorkerPool?;
     private _bvhPreparationRevision;
     private _bvhPreparation?;
+    private _bvhPreparationController?;
+    private _bvhFailedRevision;
     private _bvhPreparationTail;
     private _tinyBvhUnavailable;
     private _bvhWorkerUnavailable;