@meimu/mutracer 0.1.5 → 0.2.0

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);

package/lib/Display.js.map

@@ -1 +1 @@
-{"version":3,"file":"Display.js","sourceRoot":"","sources":["../src/Display.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAK9C,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAqCjF,qFAAqF;AACrF,MAAM,CAAC,OAAO,OAAO,OAAO;IAgBW;IAfrC,8GAA8G,CAAU,MAAM,CAAsC;IACpK,2CAA2C,CAAC,WAAW,GAAgB,KAAK,CAAC;IAC7E,6CAA6C,CAAC,mBAAmB,GAAG,CAAC,CAAC;IACtE,sCAAsC,CAAC,QAAQ,GAAG,CAAC,CAAC;IACpD,wCAAwC,CAAC,UAAU,GAAG,CAAC,CAAC;IACxD,0DAA0D,CAAC,WAAW,GAAG,CAAC,CAAC;IAC3E,6CAA6C,CAAC,IAAI,GAAG,CAAC,CAAC;IACvD,2CAA2C,CAAC,QAAQ,GAAG,CAAC,CAAC;IACzD,iDAAiD,CAAC,cAAc,GAAG,CAAC,CAAC;IACrE,4CAA4C,CAAC,cAAc,GAAG,CAAC,CAAC;IAChE,wCAAwC,CAAC,WAAW,GAAG,GAAG,CAAC;IAC3D,2EAA2E,CAAC,gBAAgB,GAAG,KAAK,CAAC;IACrG,4CAA4C,CAAC,OAAO,GAAmB,OAAO,CAAC;IAC/E,kDAAkD,CAAC,kBAAkB,GAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5F,oDAAoD,CAAC,kBAAkB,GAAG,CAAC,CAAC;IAC5E,YAAqC,MAAc,EAAE,MAA2C;QAA3D,WAAM,GAAN,MAAM,CAAQ;QAAiD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IAAC,CAAC;IAC3H,gBAAgB,CAAC,MAAM,CAAC,OAAO,CAAC,MAAc,EAAE,MAA2C,IAAI,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACpI,mFAAmF;IACnF,OAAO,CAAC,KAAa,EAAE,MAAc;QACnC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;QAC5I,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,KAAK;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;QAC3D,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,MAAM;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACjE,CAAC;IACgB,QAAQ,GAAG,IAAI,OAAO,EAAkB,CAAC;IAC1D,gBAAgB,CAAC,UAAU,CAAC,MAAc;QACxC,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,QAAQ,KAAK,GAAG,EAAE,CAAC;YACrB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC/B,IAAI,QAAQ,KAAK,SAAS;gBAAE,MAAM,CAAC,eAAe,EAAE,CAAC;QACvD,CAAC;QACD,MAAM,CAAC,QAAQ,EAAE,CAAC;QAClB,oBAAoB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IACgB,cAAc,GAA0B,EAAE,CAAC;IACpD,kBAAkB,GAAG,KAAK,CAAC;IACnC,iVAAiV;IACjV,cAAc,CAAC,IAAiB;QAC9B,MAAM,KAAK,GAAG,EAAC,IAAI,EAAC,CAAC;QACrB,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC5D,OAAO,GAAG,EAAE,GAAG,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;YAAE,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3H,CAAC;IACO,eAAe;QACrB,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;YAAC,OAAO,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;QAAC,CAAC;IAC1J,CAAC;IACO,OAAO,CAAC,MAAc;QAC5B,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM,EAAE,oBAAoB;YAAE,OAAO;QAC1C,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,CAAC,eAAe,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,KAAK,OAAO;YAAE,IAAI,CAAC,eAAe,EAAE,CAAC;QAC1F,IAAI,CAAC;YAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAAC,CAAC;QAC1F,OAAO,KAAK,EAAE,CAAC;YAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAAC,CAAC;QAClD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,kIAAkI;IAClI,OAAO,CAAC,MAAc;QACpB,IAAI,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACzF,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC;QACnG,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7I,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACtC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7B,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,8GAA8G;IAC9G,KAAK,CAAC,MAAM,CAAC,MAAc,EAAE,UAAuB,EAAE;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,eAAe,IAAI,IAAI,CAAC,MAAM,CAAC,CAAC;QACvF,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAwE,CAAC;QAC/G,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;YAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;QAC5G,OAAO,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5E,IAAI,eAAe,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC,aAAa,CAAC,EAAC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAC,CAAC,CAAC;QAC1H,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3L,CAAC;CACF","sourcesContent":["import {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 = await target.readPresentation();\n    const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);\n    const context = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;\n    if (!context) throw new Error('The image encoding context is not available.');\n    const bytes = new Uint8ClampedArray(image.data.length);\n    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.round(Math.min(1, Math.max(0, image.data[i])) * 255);\n    context.putImageData(new ImageData(bytes, image.width, image.height), 0, 0);\n    if ('convertToBlob' in canvas) return canvas.convertToBlob({type: options.type ?? 'image/png', quality: options.quality});\n    return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error('The image could not be encoded')), options.type ?? 'image/png', options.quality));\n  }\n}\n"]}

package/lib/Engine.d.ts

@@ -17,6 +17,7 @@ export interface EngineParams {
     /** Default display canvas. Default a new HTML canvas, or OffscreenCanvas without document. */ canvas?: HTMLCanvasElement | OffscreenCanvas;
     /** Backend selection. Default auto, with WebGL fallback. webgpu requires WebGPU. */ backend?: 'auto' | 'webgpu' | 'webgl';
     /** Caller-owned WebGPU device. Default undefined uses a shared device. Implies webgpu; incompatible with webgl. */ device?: GPUDevice;
+    /** Material texture bindings. Default atlas; auto tries WebGPU bindless textures and falls back to atlas when unavailable. Fixed at construction. */ textureBinding?: 'atlas' | 'auto';
 }
 /** Material-atlas device limits. */
 export interface TextureAtlasLimits {
@@ -89,6 +90,7 @@ export default class Engine {
     private _contextRestore?;
     private _gpuAdapterInfo?;
     private _backendChoice;
+    private readonly _textureBinding;
     private _initPromise?;
     private _info?;
     private _pipelineInitError?;

package/lib/Engine.js

@@ -1,6 +1,7 @@
 import { bvhConfig, engineSettingsKey, workerCount, textureBudget } from './settings/engine.js';
 import { createCanvas } from './util/canvas.js';
 import { getRecommendedDeviceDescriptor, validateDevice } from './renderer/deviceRequirements.js';
+import { probeBindless, resourceTableFeature } from './renderer/wgpuBindless.js';
 import { cameraSnapshot } from './renderer/cameraSnapshot.js';
 import Display from './Display.js';
 import { Events } from './util/events.js';
@@ -16,29 +17,41 @@ import { packDepthSampleArea } from './renderer/depthQuery.js';
 import { makeWGPURenderTargets } from './renderer/WGPURenderingPipeline.js';
 import { makeWebGLRenderTargets } from './renderer/WebGLRenderingPipeline.js';
 import { WebGLDevice as WebGLRenderer } from './renderer/webgl.js';
-let globalGPUDevice = null;
-let globalGPUAdapterInfo = null;
-let globalGPURequest;
-async function sharedDevice(gpu) {
-    if (globalGPUDevice)
-        return globalGPUDevice;
-    if (!globalGPURequest) {
-        const request = (async () => {
-            const adapter = await gpu.requestAdapter({ powerPreference: 'high-performance' }) ?? await gpu.requestAdapter();
+const sharedDevices = new Map();
+async function sharedDevice(gpu, mode) {
+    let request = sharedDevices.get(mode);
+    if (!request) {
+        request = (async () => {
+            let adapter = await gpu.requestAdapter({ powerPreference: 'high-performance' }) ?? await gpu.requestAdapter();
             if (!adapter)
                 throw new Error('No WebGPU adapter is available');
-            const device = await adapter.requestDevice(getRecommendedDeviceDescriptor(adapter));
-            globalGPUAdapterInfo = adapter.info ?? null;
-            globalGPUDevice = device;
-            void device.lost.then(() => { if (globalGPUDevice === device)
-                globalGPUDevice = null; });
-            return device;
+            const descriptor = getRecommendedDeviceDescriptor(adapter);
+            const support = mode === 'auto' ? resourceTableFeature(adapter.features) : undefined;
+            let device, fallbackReason;
+            try {
+                device = await adapter.requestDevice(support ? { ...descriptor, requiredFeatures: [...descriptor.requiredFeatures ?? [], support.feature] } : descriptor);
+            }
+            catch (error) {
+                if (!support)
+                    throw error;
+                fallbackReason = error instanceof Error ? error.message : String(error);
+                const retry = await gpu.requestAdapter({ powerPreference: 'high-performance' }) ?? await gpu.requestAdapter();
+                if (!retry)
+                    throw new Error('No WebGPU adapter is available for atlas fallback');
+                device = await retry.requestDevice(getRecommendedDeviceDescriptor(retry));
+                adapter = retry;
+            }
+            const current = request;
+            void device.lost.then(() => { if (sharedDevices.get(mode) === current)
+                sharedDevices.delete(mode); });
+            return { device, adapterInfo: adapter.info, fallbackReason };
         })();
-        globalGPURequest = request;
-        void request.finally(() => { if (globalGPURequest === request)
-            globalGPURequest = undefined; }).catch(() => { });
+        sharedDevices.set(mode, request);
+        const current = request;
+        void request.catch(() => { if (sharedDevices.get(mode) === current)
+            sharedDevices.delete(mode); });
     }
-    return globalGPURequest;
+    return request;
 }
 /** Shared device, committed scene/camera, CPU preparation and denoiser ownership. */
 export default class Engine {
@@ -79,6 +92,7 @@ export default class Engine {
     _contextRestore;
     _gpuAdapterInfo;
     _backendChoice;
+    _textureBinding;
     _initPromise;
     _info;
     _pipelineInitError;
@@ -121,6 +135,7 @@ export default class Engine {
         if (params.device && params.backend === 'webgl')
             throw new Error('A supplied GPUDevice cannot use the webgl backend.');
         this._suppliedDevice = params.device;
+        this._textureBinding = params.textureBinding ?? 'atlas';
         this._ownsDeviceSelection = !params.device;
         this._backendChoice = params.device ? 'webgpu' : params.backend ?? 'auto';
         this._sceneChangeDetector = new SceneChangeDetector();
@@ -335,16 +350,24 @@ export default class Engine {
             if (preferWebGPU && (this._suppliedDevice || (typeof navigator !== 'undefined' && navigator.gpu))) {
                 try {
                     const gpu = typeof navigator !== 'undefined' ? navigator.gpu : undefined;
-                    const gpuDevice = this._suppliedDevice ?? await sharedDevice(gpu);
+                    const shared = this._suppliedDevice ? undefined : await sharedDevice(gpu, this._textureBinding);
+                    const gpuDevice = this._suppliedDevice ?? shared.device;
                     const gpuAdapterInfo = this._suppliedDevice
-                        ? gpuDevice.adapterInfo : globalGPUAdapterInfo;
+                        ? gpuDevice.adapterInfo : shared?.adapterInfo;
+                    const materialTextures = { requested: this._textureBinding };
+                    if (this._textureBinding === 'auto') {
+                        const support = resourceTableFeature(gpuDevice.features);
+                        materialTextures.fallbackReason = shared?.fallbackReason ?? (support ? await probeBindless(gpuDevice, support) : 'Resource-table feature is not enabled on this device.');
+                        if (!materialTextures.fallbackReason)
+                            materialTextures.support = support;
+                    }
                     if (this._disposed)
                         return;
                     validateDevice(gpuDevice);
                     this._gpuAdapterInfo = gpuAdapterInfo ?? undefined;
                     this._gpuDevice = gpuDevice;
                     this._pipeline = makeWGPURenderTargets(this.display.canvas, gpuDevice, {
-                        presentationFormat: gpu?.getPreferredCanvasFormat() ?? 'bgra8unorm'
+                        presentationFormat: gpu?.getPreferredCanvasFormat() ?? 'bgra8unorm', materialTextures
                     });
                     this._watchDevice(gpuDevice);
                     gpuCreated = true;
@@ -420,8 +443,6 @@ export default class Engine {
         void device.lost.then(info => {
             if (this._disposed || this._gpuDevice !== device)
                 return;
-            if (globalGPUDevice === device)
-                globalGPUDevice = null;
             const recovering = this._ownsDeviceSelection;
             const error = new Error(`WebGPU device lost (${info.reason}): ${info.message || 'device is unavailable'}`);
             this._invalidateDevice(error, recovering);
@@ -515,7 +536,13 @@ export default class Engine {
         if (!this._pipeline && !this._lastBvhBuild)
             return;
         const values = this._pipeline?.getDiagnostics();
-        return { ...values, bvh: { ...values?.bvh, lastBuild: this._lastBvhBuild }, backend: this.backend, adapterName: this._adapterName(), width: this.display.canvas.width, height: this.display.canvas.height,
+        const materialTextures = values?.materialTextures ?? (this._pipeline ? {
+            requested: this._textureBinding, active: 'atlas',
+            fallbackReason: this._textureBinding === 'auto' ? 'Bindless textures require a supported WebGPU device.' : undefined,
+            textureCount: values?.textureAtlas?.textureCount ?? 0, estimatedBytes: values?.textureAtlas?.estimatedBytes ?? 0,
+            scale: values?.textureAtlas?.scale ?? 1, metadataBytes: 0, resourceTableCapacity: 0, retiredBytes: 0
+        } : undefined);
+        return { ...values, materialTextures, bvh: { ...values?.bvh, lastBuild: this._lastBvhBuild }, backend: this.backend, adapterName: this._adapterName(), width: this.display.canvas.width, height: this.display.canvas.height,
             lastError: this.lastError?.message, webgpuFallbackReason: this._webgpuFallbackReason,
             presentedTarget: this._presented?.label, presentedComplete: this._presented?.presentationComplete ?? false };
     }