@meimu/mutracer 0.1.5 → 0.3.0

package/docs/progressive-rendering.md

@@ -17,6 +17,7 @@ edits start final immediately; consecutive changes without explicit sync activit
 hold preview for idleMs (default 150 ms). When interaction ends, final starts after
 the current preview completes; its fallback remains visible until final completes a sample.
 With intermediate denoising enabled, it stays visible until the first filtered final image is ready.
+To keep the GPU busy while the view is still, enable [sample batching](#sample-batching) on final.
 
 ```ts
 loop.select = ({changing}) => changing || slider.dragging ? 'preview' : 'final';
@@ -84,6 +85,68 @@ it runs, object edits and scene/camera replacement have no effect on tracing.
 Call it once after updating your scene and controls, even when several renders
 are refined that frame. See [scene updates](updates.md) for notifications.
 
+## Sample batching
+
+Without batching, 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 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 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.
+
+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
 
 A fixed-size render does not need to be displayed. Its camera defaults to the
@@ -136,7 +199,8 @@ lower preview's scale; resizing the display canvas affects both.
 
 Call `render.setDenoiser({ type: 'jnlm', schedule: 'converged' })` with JNLM or an OIDN
 configuration. The schedules are `converged` (default), `progressive` (first
-sample, then 4, 8, 16, … with a ten-second limit), and `every-sample`. Same-engine
+sample, then doubling counts at least 500 ms apart; see [scheduling](./denoising.md#scheduling)),
+and `every-sample`. Same-engine
 renders share equal filter configurations and OIDN weight downloads. The engine
 releases a network when its last render lease is released. OIDN is ignored with
 a warning on WebGL; JNLM works on both backends.
@@ -150,6 +214,14 @@ final sample does not render the fallback. `present` selects the requested
 complete image, then its complete fallback, and otherwise leaves the canvas
 unchanged. It never traces.
 
+Sample batching on WebGPU needs GPU timestamps; without them, a call traces one
+sample, and between-frame refines are WebGPU-only. A larger `timeBudgetMs`
+batches more per call, but an edit made just after waits for that work before its
+preview starts. Batching keeps the GPU at full speed until `maxSamples`, which
+draws more power than one sample per frame. `stop()` ends between-frame refines
+at once, though submitted work still finishes; a manual `tick()` refines between
+frames only until the next display frame.
+
 `prepare(nextScene)` performs optional CPU BVH preparation without disturbing
 the current GPU scene. Setting `engine.scene` and calling `update` commits a
 scene switch for every render. Only one GPU scene resides in an engine.

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/threejs.md

@@ -45,6 +45,10 @@ 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.
 
+For a library-generated sky, pass `environment: new ProceduralSky()` in the
+conversion or sync options. See [ProceduralSky](./api.md#proceduralsky) for
+configuration and backend limits.
+
 ## What is converted
 
 | Three.js | MuTracer |
@@ -69,7 +73,7 @@ then call `loop.tick()`. With first-layer frame control, call `sync.update()`,
 | `RectAreaLight` | `RectLight` |
 | `AmbientLight` | `AmbientLight` |
 | `scene.environment` (equirectangular float `DataTexture`, e.g. from `HDRLoader`/`RGBELoader`) | `EnvironmentLight`; orientation follows Three.js, so a `DataTexture` with `flipY = false` has its first row at the bottom |
-| `scene.background` color / texture | Background; the environment itself when `background === environment` |
+| `scene.background` color / texture | Explicit background, independent of environment lighting |
 
 Three.js `opacity` maps to `geometryOpacity`; thin-shell choices map to
 `geometryThinWalled`. Metadata accepts the five [canonical and compatibility
@@ -95,10 +99,15 @@ Material textures preserve independent `wrapS` and `wrapT`: repeat,
 clamp-to-edge and mirrored repeat. UV repeat and offset apply before wrapping;
 later wrap edits synchronize automatically. Displacement uses the same modes.
 
-`scene.environmentIntensity` controls environment lighting, including zero;
-`scene.environmentRotation` rotates it using the source Euler order. Both
-synchronize automatically. They do not change ambient lights or an explicitly
-assigned `scene.background` texture.
+`scene.environmentIntensity` scales environment lighting (`0` disables it);
+ambient lights and explicit backgrounds keep their own brightness.
+`scene.backgroundIntensity` scales an explicit texture background; colors are
+unaffected. `scene.environmentRotation` and `scene.backgroundRotation`
+independently rotate environment lighting and explicit texture backgrounds. All
+of these synchronize automatically; rotations preserve Euler order. An unset
+background follows the environment. `mutracerGroundedSkybox` uses only its own
+`rotation` (default `0`) and `intensity` (default `1`), ignoring
+`scene.backgroundRotation` and `scene.backgroundIntensity`.
 
 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

package/docs/updates.md

@@ -114,10 +114,54 @@ 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
+or BVHs. Emission edits also refresh light-sampling state. With atlas bindings,
+texture edits rebuild the texture atlas. With [bindless bindings](./api.md#texture-bindings),
+UV assignments, wrap and color-space edits update sampling metadata, while pixel edits
+upload the changed images. Dimension, budget or shared storage-precision changes
+can require more images to be uploaded. `Texture.markUpdated()` invalidates image
+pixels as well as in-place UV edits. Displacement settings that move geometry require a
 [full mesh update](#full-mesh-updates).
 
+WebGPU can compile a new path-tracing shader for the following changes. Feature
+presence is scene-wide: adding another material or light that uses an already
+supported feature does not by itself need another variant.
+
+Within compatible transport settings and data layouts, WebGPU retains prepared
+material, texture and lighting support for later edits. Turning a feature off
+and back on can reuse that support. The base shader supports diffuse, dielectric
+and metal materials: changing `baseMetalness` between 0 and 1 does not itself
+require another shader. Coat and fuzz are prepared together on the first use of
+either: switching between them or combining them does not itself require another
+shader. Transmission, thin film and subsurface are prepared as needed; dispersion
+and other transport/layout changes below can still require compilation.
+
+| Change | When a different shader variant is needed |
+| --- | --- |
+| Material, texture or lighting features | Newly required support is not covered by a prepared shader: coat/fuzz, thin film, subsurface, transmission, shadow catchers, a texture type, an analytic-light type, sampled emissive triangles or environment illumination |
+| Transport and transparency | Enabling/disabling medium or dispersion support, changing whether any non-opaque material exists, or changing whether deterministic primary BLEND splitting is needed |
+| Shading and geometry structure | Changing required UV/tangent/coat-normal frames, displacement or material-bevel support, vertex/BVH layouts or required traversal capacity |
+| Render settings | Changing `samplingPattern`, `bevelSamples`, or `alphaBlendStrategy` while BLEND materials exist |
+| Texture capacity | Atlas: increasing the texture count beyond the current capacity. Both modes: first use or last removal of UV1 texture sampling also changes the shader |
+
+With `alphaMode: 'auto'`, opacity, cutoff or alpha-map edits can change the
+resolved transparency mode. Texture edits can also enable independent coat-normal
+or anisotropy frames. These count as structural changes above.
+
+Within an unchanged feature/structure combination, colors, roughness, metalness,
+existing layer weights, light transforms/intensity, texture pixels and camera/output size
+do not recompile the path tracer. Neither do changes to `bounces`,
+`directLightCandidates`, clamping, `dispersionWavelengths` (1 or 3), the render's
+bevel switch, sample count or seed. Data uploads, atlas/BVH work and accumulation
+restarts may still be needed.
+
+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
+post-processing passes have their own shaders and initialization costs.
+
 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.

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

@@ -5,6 +5,11 @@ Open **Examples → MuTracer collection** for models curated for this viewer, or
 [glTF Research Scenes](https://github.com/ErfanMo77/gltf-research-scenes) collection.
 Scenes download on demand from GitHub; cards show approximate download sizes
 and link to each scene's source and license. Large scenes need more memory.
+glTF Research Scenes load with **Ground shadow** off; you can enable it in Lighting.
+
+On desktop, choose **Pin to right panel** in Examples to keep the collection
+open while loading models. **Unpin examples** returns it to the popover.
+The pinned layout is saved in this browser.
 
 glTF/GLB imports include directional, point and spot lights and emissive meshes.
 Benchmark scenes also load their sunlight and available environment maps.
@@ -16,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.
 
-When an imported glTF/GLB contains cameras, a toast offers **Apply camera** to
-use its first camera.
-Dismiss the toast to keep the Orbit view. 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.
+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.
@@ -49,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.d.ts

@@ -1,3 +1,5 @@
+import { type AovIdComponent } from './renderer/aovDisplay.js';
+export type { AovIdComponent } from './renderer/aovDisplay.js';
 import type Render from './Render.js';
 import type { ToneMapping, DisplayChannel } from './renderer/RenderingPipeline.js';
 import type { ColorRGB } from './types.js';
@@ -21,7 +23,11 @@ export interface DisplaySettings {
     /** 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;
+    /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel?: DisplayChannel;
+    /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange?: readonly [number, number];
+    /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale?: number;
+    /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale?: number;
+    /** Stable ID lane to colorize. Default object. */ aovIdComponent?: AovIdComponent;
     /** Linear shadow-catcher color. Default black. */ shadowCatcherColor?: ColorRGB;
     /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha?: number;
 }
@@ -52,12 +58,17 @@ export default class Display {
     /** 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;
+    /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel: DisplayChannel;
+    /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange: readonly [number, number];
+    /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale: number;
+    /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale: number;
+    /** Stable ID lane to colorize. Default object. */ aovIdComponent: AovIdComponent;
     /** 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 _filterSettings;
     private readonly settings;
     private readonly _postProcesses;
     private _warnedPostProcess;

package/lib/Display.js

@@ -1,5 +1,6 @@
+import { displayAovKind, validateAovDisplay } from './renderer/aovDisplay.js';
 import { createCanvas } from './util/canvas.js';
-import { displaySettingsKey, applyDisplaySettings } from './settings/display.js';
+import { displaySettingsKey, displayFilterSettingsKey, applyDisplaySettings } from './settings/display.js';
 /** Canvas presentation and shared display settings; obtained from engine.display. */
 export default class Display {
     engine;
@@ -15,7 +16,11 @@ export default class Display {
     /** Bloom luminance threshold. Default 1. */ bloomThreshold = 1;
     /** Bloom radius in 0–1. Default 0.6. */ bloomRadius = 0.6;
     /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled = false;
-    /** Display image channel. Default final. */ channel = 'final';
+    /** Display image channel. Default final. AOV channels require explicit Render.aovs. */ channel = 'final';
+    /** Finite float32 scene-unit depths mapped to black/white; 0 <= near < far. Default [0, 10]. */ aovDepthRange = [0, 10];
+    /** Finite positive float32 scene-unit half-range around the origin for position RGB. Default 1. */ aovPositionScale = 1;
+    /** Finite positive float32 input-pixel displacement mapped to full motion brightness. Default 16. */ aovMotionScale = 16;
+    /** Stable ID lane to colorize. Default object. */ aovIdComponent = 'object';
     /** Linear shadow-catcher color. Default black. */ shadowCatcherColor = [0, 0, 0];
     /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha = 1;
     constructor(engine, canvas) {
@@ -34,6 +39,7 @@ export default class Display {
         if (this.canvas.height !== height)
             this.canvas.height = height;
     }
+    _filterSettings = new WeakMap();
     settings = new WeakMap();
     /** @internal */ _configure(render) {
         if (render._engine !== this.engine)
@@ -41,12 +47,20 @@ export default class Display {
         const target = render._output;
         if (!target)
             return;
+        const kind = displayAovKind(this.channel);
+        if (!kind && !['final', 'normal', 'albedo', 'shadow', 'shadowCatcher'].includes(this.channel))
+            throw new RangeError('Unknown display channel');
+        if (kind && !render.aovs.includes(kind))
+            throw new Error(`AOV ${kind} is not enabled on the selected render`);
+        validateAovDisplay({ depthRange: this.aovDepthRange, positionScale: this.aovPositionScale, motionScale: this.aovMotionScale, idComponent: this.aovIdComponent });
         const key = displaySettingsKey(this);
+        const filterKey = displayFilterSettingsKey(this);
         const previous = this.settings.get(render);
         if (previous !== key) {
             this.settings.set(render, key);
-            if (previous !== undefined)
+            if (previous !== undefined && this._filterSettings.get(render) !== filterKey)
                 render._displayChanged();
+            this._filterSettings.set(render, filterKey);
         }
         target.activate();
         applyDisplaySettings(this, target);
@@ -72,7 +86,14 @@ export default class Display {
         if (render._engine !== this.engine)
             throw new Error('Render belongs to another engine.');
         const target = render._output;
-        if (!target?.presentationComplete)
+        if (!target)
+            return;
+        const kind = displayAovKind(this.channel);
+        if (!kind && !target.presentationComplete)
+            return;
+        if (kind && !render.aovs.includes(kind))
+            throw new Error(`AOV ${kind} is not enabled on the selected render`);
+        if (kind && target.aovReady && !target.aovReady(kind))
             return;
         this._configure(render);
         target.drawPostProcess();
@@ -90,9 +111,9 @@ export default class Display {
     present(render) {
         if (render._engine !== this.engine)
             throw new Error('Render belongs to another engine.');
-        const ready = this.channel === 'final' && render.fallback ? render._presentable : render._complete;
+        const ready = this.channel === 'final' && render.fallback ? render._presentable : render._completeFor(this.channel);
         const fallback = render.fallback;
-        const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._complete) ? fallback : undefined;
+        const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._completeFor(this.channel)) ? fallback : undefined;
         if (!selected)
             return;
         const target = this.compose(selected);
@@ -106,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 {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, 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. */ channel?: DisplayChannel;\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. */ channel: DisplayChannel = 'final';\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 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 key = displaySettingsKey(this);\n    const previous = this.settings.get(render);\n    if (previous !== key) {\n      this.settings.set(render, key);\n      if (previous !== undefined) render._displayChanged();\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?.presentationComplete) 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._complete;\n    const fallback = render.fallback;\n    const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._complete) ? 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":"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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 = 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"]}