@meimu/mutracer 0.1.0 → 0.1.2

package/docs/materials.md

@@ -198,13 +198,33 @@ start.
 
 ## Displacement
 
-`displacementMap` (red channel) with `displacementScale` (local units)
-ray-marches the height field in the shader. `displacementStepSize` controls the
-ray-marching step (default `0.01`). No extra triangles are generated.
-`displacementUvProjection` (default `'none'`) and `displacementUvProjectionScale`
-(default `1`) control height-map coordinates.
-
-The remaining `displacement*` properties are documented in the type declarations.
+Assign a `displacementMap` and adjust `displacementScale` (height) and
+`displacementBias`. The red channel supplies linear height; the offset along
+the normal is `red × displacementScale + displacementBias`. Bias defaults to
+`0`, so black leaves the surface in place and white uses the full height.
+For centered displacement, use a bias of `-displacementScale / 2`. Displacement
+requires WebGPU; WebGL 2 renders the original surface. No extra triangles are
+generated.
+
+`displacementScale` defaults to `0.1`; both height and bias use mesh-local
+units. Height `0` removes map variation while bias still offsets the surface;
+set both to `0` or remove the map to disable displacement. The offset follows
+the mesh transform, like Three.js displacement or Blender's Object Space mode:
+scaling an object also scales its displacement.
+Baking a scale into vertex positions requires scaling both `displacementScale`
+and `displacementBias` by the same amount to preserve the result.
+
+`displacementStepSize` defaults to `0`, which automatically uses 1/32 of the
+absolute displacement height. A positive value sets a fixed step in mesh-local
+units. Smaller steps capture finer detail at a higher rendering cost; set
+`0.01` explicitly to retain the previous fixed-step default. When baking an
+object scale into vertices, scale an explicit step by the same amount; an
+automatic step follows the height. `displacementUvProjection` (default `'none'`)
+and `displacementUvProjectionScale` (default `1`) control height-map coordinates.
+
+Choose the height for your model's local dimensions. The library does not infer
+physical units or resize the model. Changing displacement settings can trigger
+an expensive [full mesh update](updates.md#full-mesh-updates).
 
 ## Known limitations
 

package/docs/progressive-rendering.md

@@ -14,8 +14,9 @@ loop.start();
 Each tick updates syncs and commits engine inputs, then calls select, refines the
 selected render and presents it. Active syncs select preview by default. Isolated
 edits start final immediately; consecutive changes without explicit sync activity
-hold preview for idleMs (default 150 ms). When interaction ends, final starts in
-that tick and its ready fallback remains visible until final completes a sample.
+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.
 
 ```ts
 loop.select = ({changing}) => changing || slider.dragging ? 'preview' : 'final';
@@ -24,20 +25,28 @@ loop.on('sample', ({samples, frameTimeMs}) => updateSamples(samples));
 ```
 
 Loop status is previewing when the displayed target is preview, including fallback
-presentation. Preview samples never emit loop sample events or count toward loop
+presentation and the wait for the first complete final image. Starting to trace
+final tiles does not change that status until final is actually presented.
+Preview samples never emit loop sample events or count toward loop
 samples. Intermediate final filtering reports converging; only terminal filtering
 reports denoising. After finishing, unchanged ticks update syncs and the engine
 without GPU submissions. Display or render settings edits resume necessary work.
 
+During interaction, the loop finishes the current preview sample before applying
+the latest scene/camera edits, keeping previews responsive during continuous input.
+
 start pauses on hidden pages; stop preserves images. Use tick with your own frame
 loop, or start, which ignores manual tick calls with one warning. loop.converge
 pauses interactive ticks, converges/presents final and resumes if still started.
 
 coalesceSceneUpdates defaults to false. When enabled, preview inference defers
-engine commits while syncs keep collecting edits. Completed inference is presented
+engine commits while syncs keep collecting edits. The last presented image stays
+visible until the next filtered preview is ready. Completed inference is presented
 before the latest camera/scene is committed together. Interaction ending during
 inference waits for that result before final starts. With it disabled, changes
-immediately invalidate old inference. Render.denoising includes intermediate
+immediately invalidate old inference. Once final is available, unused fallback
+inference does not delay it or switch presentation back to preview.
+Render.denoising includes intermediate
 inference without changing status semantics. Denoising does not enable preview;
 preview: false always disables it.
 
@@ -54,7 +63,8 @@ engine.scene = scene;
 engine.camera = camera;
 const preview = new Render(engine, {
   resolutionScale: .5,
-  adaptiveResolution: { targetFrameMs: 20, minScale: .25 },
+  timeBudgetMs: 80,
+  adaptiveResolution: { targetFrameMs: 80, minScale: .125 },
   bounces: 2, bevel: false, dispersionWavelengths: 1,
   directLightCandidates: 2,
 });
@@ -106,9 +116,11 @@ usable.
   fallback and denoiser. `transmissiveOutputAlphaMin` belongs to Render because
   it is evaluated along individual paths, so changing it restarts that render.
 
-RenderLoop creates a half-resolution preview with adaptive scale .25–.5,
-20 ms target, 2 bounces, no bevel, one wavelength and two light candidates;
+RenderLoop creates a half-resolution preview with adaptive scale .125–.5,
+80 ms budget, 2 bounces, no bevel, one wavelength and two light candidates;
 other settings use Render defaults. Pass preview settings, a Render or false.
+Preview resolution drops when interaction is slow and recovers gradually when
+performance improves. Final resolution stays independent of preview adaptation.
 Pass final settings or a Render; newly created finals use preview as fallback.
 Supplied Render/Sync objects must belong to this engine. loop.dispose releases
 only renders it created; dispose supplied renders, syncs and controls yourself.
@@ -118,6 +130,10 @@ provide both fixed width and height at construction; fixed dimensions cannot be
 changed through `resolutionScale`. `width` and `height` report the actual GPU
 image, including WebGPU's 16-pixel alignment. See [API options](api.md).
 
+Keep the display canvas at the viewport's drawing-buffer size and set
+`resolutionScale` on each render independently. Lowering final's scale does not
+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

package/docs/threejs.md

@@ -104,6 +104,16 @@ Meshes without UVs get automatic triplanar texture and displacement
 projection; explicit
 `mutracerUvProjection` settings take precedence.
 
+Three.js `displacementScale` and `displacementBias` retain their local-unit
+semantics. Without a displacement map, Three.js's inactive default height of `1`
+is replaced by MuTracer's default `0.1`; other explicitly configured heights
+are preserved. `userData.mutracerOpenPBR.displacementScale` can explicitly set
+any height, including `1`, before a map is assigned; `displacementBias` in the
+same metadata overrides the Three.js bias. The same metadata object's
+`displacementStepSize` overrides marching quality: `0` uses automatic steps,
+and a positive value is a fixed local-unit step. See
+[displacement](materials.md#displacement) for scaling and cost.
+
 ## Skinning and morph targets
 
 The initial conversion and each `sync.update()` evaluate morph targets and
@@ -192,9 +202,11 @@ MuTracer transform; source rotation alone does not specify their direction.
 Construction subscribes to control events. The first update converts and writes
 sources to the engine. `scene` exposes the retained converted scene, or undefined
 when no source was supplied. A camera-only sync preserves a MuTracer-built scene.
-`active` covers start/end interaction, camera movement, damping and changing
-skinned/morph poses. The damping tail ends when movement and zoom fall below
-0.05% of view distance, allowing final refinement in that same tick.
+`active` covers gestures once the camera moves, damping and changing
+skinned/morph poses. Clicking or holding a stationary view preserves accumulated
+samples. OrbitControls damping stays consistent across render frame
+rates, and final refinement resumes when motion settles. Use
+`updateControls: false` when your application already updates the controls.
 
 `fromTHREEScene(scene, options?)` and `fromTHREECamera(camera, options?)` remain
 available for one-shot conversions. Each call reruns conversion hooks and creates fresh default objects; custom

package/docs/viewer.md

@@ -0,0 +1,53 @@
+# Sharing viewer settings
+
+Add settings to a viewer link to override the recipient's saved preferences.
+For example, open the viewer with HDR output enabled:
+
+```text
+https://mutracer.meimu-studio.com/viewer/?hdrOutputEnabled=true
+```
+
+Combine settings with `&`, and use `#model=…` to choose an example:
+
+```text
+https://mutracer.meimu-studio.com/viewer/?hdrOutputEnabled=true&maxSamples=128#model=dragon
+```
+
+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`.
+
+## Options
+
+Parameter names match the viewer settings and are case-sensitive:
+
+| Group | Parameters |
+| --- | --- |
+| Lighting | `lighting`, `studioPreset`, `studioIntensity`, `studioRotation`, `studioSize`, `studioAmbient`, `studioAmbientColor`, `envId`, `envIntensity`, `envRotation`, `envResolution` |
+| Background and ground | `background`, `backgroundColor`, `groundedHeight`, `groundedRadius`, `groundShadow`, `groundOpacity` |
+| Quality | `maxSamples`, `bounces`, `resolutionScale`, `samplingPattern`, `bvhBuilder`, `clamping`, `previewEnabled`, `previewMaxResolutionScale` |
+| Denoising | `denoise`, `denoiseModel`, `denoiseWhileConverging`, `jnlmStrength`, `jnlmSearchRadius`, `jnlmPatchRadius`, `jnlmAlbedoBandwidth`, `jnlmNormalBandwidth`, `jnlmIterations`, `oidnModel`, `oidnMaxTileSize` |
+| Display | `hdrOutputEnabled`, `toneMapping`, `exposure`, `contrast`, `saturation`, `temperature`, `tint`, `bloomIntensity`, `bloomThreshold`, `bloomRadius`, `vignette`, `output` |
+
+Booleans accept `true`/`false` or `1`/`0`. Numbers must be finite and within
+the setting's supported range. Colors use URL-encoded hex, for example
+`backgroundColor=%232a2b30`. Use `null` for automatic `groundedHeight` or
+`groundedRadius`. Choices use the setting's value, for example
+`toneMapping=agx`, `envResolution=2k` or `denoiseModel=jnlm`.
+
+Valid query parameters take priority over hash parameters, then saved local
+preferences, then defaults. Unknown parameters and invalid values are ignored.
+Explicit defaults such as `hdrOutputEnabled=false` remain in the link so they
+can override a recipient's different preference. When the viewer updates the
+address, settings move into the hash; unrelated query parameters, including
+`?webgl`, are preserved.
+
+## Caveats
+
+HDR output requires WebGPU, an HDR display and a compatible browser. Unsupported
+devices fall back to SDR. `?webgl` forces WebGL 2, which does not support HDR output.
+
+Links do not include uploaded models or environments, camera state, material
+edits, object visibility or panel layout. Camera state continues to follow the
+locally saved view for the current model. URL settings are applied on page load;
+reload after editing parameters in the address bar.

package/lib/Display.d.ts

@@ -65,7 +65,7 @@ export default class Display {
     addPostProcess(pass: PostProcess): () => void;
     private warnPostProcess;
     private compose;
-    /** Presents a complete render or its fallback. Does not trace; leaves canvas unchanged if neither is ready. */
+    /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */
     present(render: Render): Render | undefined;
     /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */
     toBlob(render: Render, options?: BlobOptions): Promise<Blob>;

package/lib/Display.js

@@ -86,11 +86,13 @@ export default class Display {
         }
         return target;
     }
-    /** Presents a complete render or its fallback. Does not trace; leaves canvas unchanged if neither is ready. */
+    /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */
     present(render) {
         if (render._engine !== this.engine)
             throw new Error('Render belongs to another engine.');
-        const selected = render._complete ? render : render.fallback?._complete ? render.fallback : undefined;
+        const ready = this.channel === 'final' && render.fallback ? render._presentable : render._complete;
+        const fallback = render.fallback;
+        const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._complete) ? fallback : undefined;
         if (!selected)
             return;
         const target = this.compose(selected);

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 render or its fallback. Does not trace; leaves canvas unchanged if neither is ready. */\n  present(render: Render): Render | undefined {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const selected = render._complete ? render : render.fallback?._complete ? render.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 {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"]}

package/lib/Render.d.ts

@@ -197,6 +197,12 @@ export default class Render {
     private _adaptiveScale;
     private _lastScale;
     private _frameTime;
+    private _sampleStart?;
+    private _frameStart?;
+    private _sampleScale;
+    private _frameScale;
+    private _adaptiveFrames;
+    private _adaptiveFastFrames;
     private _events;
     /** Owning engine. */ get engine(): Engine;
     /** Whether inference is queued or running, including intermediate updates. Default false. */ get denoising(): boolean;
@@ -225,6 +231,9 @@ export default class Render {
     private _size;
     private _settings;
     private _synchronize;
+    private _trace;
+    private _adaptResolution;
+    private _cancelAdaptiveFrames;
     /** Accumulates within this frame's budget. Rejects calls during converge or after disposal. */
     refine(): RenderStatus;
     private _refine;

package/lib/Render.js

@@ -3,6 +3,7 @@ import { cameraSnapshot } from './renderer/cameraSnapshot.js';
 import { collectTraceSettings, imageSettingsKey } from './settings/render.js';
 import { DEFAULT_JNLM_OPTIONS, createJNLMDenoiser } from './renderer/jnlm.js';
 import { nextPreviewScale } from './renderer/util.js';
+import { scheduleFrame } from './util/frame.js';
 let oidnModule;
 const loadOIDN = () => oidnModule ??= import('./renderer/oidnNetwork.js');
 function validateDenoiserOptions(options) {
@@ -121,6 +122,8 @@ export default class Render {
             throw new Error('Fixed-size renders cannot use resolutionScale.');
         if (!Number.isFinite(value) || value <= 0)
             throw new Error('resolutionScale must be positive.');
+        if (value !== this._resolutionScale)
+            this._cancelAdaptiveFrames();
         this._resolutionScale = value;
     }
     _fallback = null;
@@ -170,6 +173,12 @@ export default class Render {
     _adaptiveScale = 1;
     _lastScale = 1;
     _frameTime = 0;
+    _sampleStart;
+    _frameStart;
+    _sampleScale = 1;
+    _frameScale = 1;
+    _adaptiveFrames = new Set();
+    _adaptiveFastFrames = 0;
     _events = new Events();
     /** Owning engine. */ get engine() { return this._engine; }
     /** Whether inference is queued or running, including intermediate updates. Default false. */ get denoising() { return !!this._denoisePending; }
@@ -220,6 +229,7 @@ export default class Render {
     }
     get _current() { const inputs = this._engine._inputs; return inputs.scene === this._input.scene && inputs.camera === this._input.camera && !this._disposed; }
     /** @internal */ get _complete() { return this._current && !!this._target?.presentationComplete && !this._target.isFirstFrame() && this.samples > 0; }
+    /** @internal */ get _presentable() { return this._complete && (!this._denoisePending || this._denoisedSamples > 0 || (this._schedule() === 'converged' && this.maxSamples > 1)); }
     /** @internal */ get _output() { if (this._disposed)
         throw new Error('Render is disposed.'); return this._target; }
     _validate() {
@@ -259,12 +269,65 @@ export default class Render {
                 this._offlineCamera = false;
             this._cancelDenoise();
             target.restartSamples();
+            this._sampleStart = this._frameStart = undefined;
+            this._frameTime = 0;
             target.setSize(size.width, size.height);
             this._input = { scene: inputs.scene, camera: inputs.camera, settings: key };
         }
-        target.setOnSampleRendered((samples, isFirstFrame, frameTimeMs) => { this._frameTime = frameTimeMs; this._events.emit('sample', { samples, isFirstFrame, frameTimeMs }); });
+        target.setOnSampleRendered((samples, isFirstFrame, frameTimeMs) => {
+            // A preview's latency includes every tile, not just its last dispatch.
+            this._frameTime = Math.max(frameTimeMs, this._sampleStart === undefined ? 0 : performance.now() - this._sampleStart);
+            this._frameStart = this._sampleStart;
+            this._frameScale = this._sampleScale;
+            this._sampleStart = undefined;
+            this._events.emit('sample', { samples, isFirstFrame, frameTimeMs });
+        });
         return target;
     }
+    _trace(target, limit) {
+        if (this._sampleStart === undefined) {
+            this._sampleStart = performance.now();
+            this._sampleScale = this._adaptiveScale;
+        }
+        const compiling = target.trace(this._engine._inputs.value, limit);
+        if (compiling)
+            this._sampleStart = undefined;
+        return compiling;
+    }
+    _adaptResolution() {
+        if (!this._busy && this.adaptiveResolution && this._frameTime > 0 && this.samples > 0) {
+            const { targetFrameMs, minScale } = this.adaptiveResolution;
+            const start = this._frameStart, time = this._frameTime, scale = this._frameScale, maxScale = this._resolutionScale;
+            const { width, height } = this._engine.display.canvas;
+            this._frameTime = 0;
+            // Observe the following display frame too: GPU submissions and WebGL
+            // filters can return long before their work reaches the screen.
+            const cancel = scheduleFrame(() => {
+                this._adaptiveFrames.delete(cancel);
+                const adaptive = this.adaptiveResolution, canvas = this._engine.display.canvas;
+                if (this._disposed || this._busy || !adaptive || adaptive.targetFrameMs !== targetFrameMs || adaptive.minScale !== minScale ||
+                    this._resolutionScale !== maxScale || canvas.width !== width || canvas.height !== height)
+                    return;
+                const elapsed = Math.max(time, start === undefined ? 0 : performance.now() - start);
+                const next = nextPreviewScale(scale, elapsed, targetFrameMs, maxScale, this._adaptiveScale, minScale);
+                if (next > this._adaptiveScale) {
+                    if (++this._adaptiveFastFrames < 4)
+                        return;
+                    this._adaptiveScale = Math.min(next, this._adaptiveScale * 1.25);
+                }
+                else
+                    this._adaptiveScale = next;
+                this._adaptiveFastFrames = 0;
+            });
+            this._adaptiveFrames.add(cancel);
+        }
+    }
+    _cancelAdaptiveFrames() {
+        for (const cancel of this._adaptiveFrames)
+            cancel();
+        this._adaptiveFrames.clear();
+        this._adaptiveFastFrames = 0;
+    }
     /** Accumulates within this frame's budget. Rejects calls during converge or after disposal. */
     refine() {
         if (this._busy)
@@ -305,10 +368,10 @@ export default class Render {
         target.activate();
         if (this._denoisePending)
             return this._status = this.converged ? 'denoising' : 'converging';
-        target.setPreserveDenoisedOutput?.(!!this._filter && this._schedule() === 'progressive');
+        target.setPreserveDenoisedOutput?.(!!this._filter && this._schedule() !== 'converged');
         const limit = this._nextSampleTarget();
         if (this.samples < limit) {
-            if (target.trace(this._engine._inputs.value, limit))
+            if (this._trace(target, limit))
                 return this._status = 'compiling';
         }
         this._maybeDenoise(false, limit);
@@ -316,8 +379,7 @@ export default class Render {
             return this._status = this.converged ? 'denoising' : 'converging';
         if (this._filterPending && this.converged)
             return this._status = 'preparing';
-        if (this.adaptiveResolution && this._frameTime > 0 && this.samples > 0)
-            this._adaptiveScale = nextPreviewScale(this._adaptiveScale, this._frameTime, this.adaptiveResolution.targetFrameMs, this._resolutionScale, this.adaptiveResolution.minScale);
+        this._adaptResolution();
         return this._status = this.converged ? 'finished' : 'converging';
     }
     _refineOne() {
@@ -329,8 +391,10 @@ export default class Render {
             return;
         target.activate();
         if (this.samples < 1)
-            this._status = target.trace(this._engine._inputs.value, 1) ? 'compiling' : 'converging';
+            this._status = this._trace(target, 1) ? 'compiling' : 'converging';
         this._maybeDenoise();
+        if (!this._denoisePending)
+            this._adaptResolution();
     }
     _schedule() { return this._denoiserOptions?.schedule ?? 'converged'; }
     _nextSampleTarget() {
@@ -422,6 +486,7 @@ export default class Render {
     /** @internal */ _inputsChanged(resetTiming = false) { this._cancelDenoise(); if (resetTiming)
         this._target?.invalidateTiming?.(); }
     /** @internal */ _deviceLost(recovering) {
+        this._cancelAdaptiveFrames();
         this._cancelDenoise();
         this._filterRevision++;
         this._filter = undefined;
@@ -443,7 +508,7 @@ export default class Render {
         this._engine.display._configure(this);
         target.activate();
         target.drawPostProcess();
-        const revision = ++this._denoiseRevision, samples = this.samples;
+        const revision = ++this._denoiseRevision, samples = this.samples, frameStart = this._frameStart;
         const controller = this._denoiseController = new AbortController();
         // One shared scratch lease across all renders; queued stale jobs do no GPU work.
         const task = this._engine._enqueueDenoise(async () => {
@@ -467,15 +532,20 @@ export default class Render {
                 target.drawPostProcess();
                 this._denoisedSamples = samples;
                 this._lastDenoiseTime = performance.now();
+                if (frameStart !== undefined)
+                    this._frameTime = Math.max(this._frameTime, this._lastDenoiseTime - frameStart);
             }
         });
         this._denoisePending = task;
         void task.catch(error => { if (revision === this._denoiseRevision && !this._disposed)
-            this._engine._notifyError(error); }).finally(() => { if (this._denoisePending === task) {
-            this._denoiseController = undefined;
-            this._denoisePending = undefined;
-            this._status = this.converged ? 'finished' : 'converging';
-        } });
+            this._engine._notifyError(error); }).finally(() => {
+            if (this._denoisePending === task) {
+                this._denoiseController = undefined;
+                this._denoisePending = undefined;
+                this._status = this.converged ? 'finished' : 'converging';
+                this._adaptResolution();
+            }
+        });
     }
     /** Reads native RGBA float32, top row first. Default hdr. Custom denoised output is resolved linear HDR ray color before display background/catcher composition; built-ins retain their native display-space output. Unavailable denoised output falls back to hdr. */
     async readPixels(kind = 'hdr') {
@@ -502,7 +572,7 @@ export default class Render {
     }
     /** Discards only this render's accumulation and pending denoising. */
     restart() { if (this._disposed)
-        throw new Error('Render is disposed.'); this._cancelDenoise(); this._target?.restartSamples(); this._status = 'converging'; }
+        throw new Error('Render is disposed.'); this._cancelDenoise(); this._cancelAdaptiveFrames(); this._sampleStart = this._frameStart = undefined; this._frameTime = 0; this._target?.restartSamples(); this._status = 'converging'; }
     /** Releases only this render's image resources and denoiser. */
     dispose() {
         if (this._disposed)
@@ -511,6 +581,7 @@ export default class Render {
         this._events.clear();
         this._filterRevision++;
         this._cancelDenoise();
+        this._cancelAdaptiveFrames();
         if (this._target)
             this._engine._releaseTarget(this._target);
         if (this._filter && this._filter.kind !== 'custom')