@meimu/mutracer 0.1.4 → 0.2.0

package/lib/Render.js

@@ -1,3 +1,5 @@
+import { aovMask } from './renderer/aov.js';
+import { displayAovKind } from './renderer/aovDisplay.js';
 import { Events } from './util/events.js';
 import { cameraSnapshot } from './renderer/cameraSnapshot.js';
 import { collectTraceSettings, imageSettingsKey } from './settings/render.js';
@@ -11,7 +13,7 @@ function validateDenoiserOptions(options) {
         throw new Error('Denoiser type must be jnlm, oidn or custom.');
     const allowed = options.type === 'jnlm'
         ? ['type', 'schedule', ...Object.keys(DEFAULT_JNLM_OPTIONS)]
-        : options.type === 'custom' ? ['type', 'schedule', 'denoiser']
+        : options.type === 'custom' ? ['type', 'schedule', 'denoiser', 'aovs']
             : ['type', 'schedule', 'model', 'weightsBaseUrl', 'weightsUrl', 'aux', 'hdr', 'hdrTransfer', 'auxiliaryModelUrls', 'engine', 'precision', 'dynamicTile', 'maxTileSize', 'signal'];
     for (const key of Object.keys(options))
         if (!allowed.includes(key))
@@ -21,6 +23,7 @@ function validateDenoiserOptions(options) {
     if (options.type === 'jnlm')
         createJNLMDenoiser(options);
     else if (options.type === 'custom') {
+        aovMask(options.aovs ?? []);
         if (!options.denoiser || typeof options.denoiser !== 'object' || typeof options.denoiser.denoise !== 'function' || (options.denoiser.prepare !== undefined && typeof options.denoiser.prepare !== 'function'))
             throw new Error('Custom denoiser must implement denoise and optional prepare.');
     }
@@ -63,6 +66,8 @@ function validateDenoiserOptions(options) {
 function isURL(value) { return (typeof value === 'string' && value.length > 0) || value instanceof URL; }
 // Snapshot nested values too, so application edits cannot silently change a cache key.
 function snapshotDenoiserOptions(options) {
+    if (options.type === 'custom')
+        return Object.freeze({ ...options, aovs: Object.freeze([...(options.aovs ?? [])]) });
     if (options.type !== 'oidn')
         return Object.freeze({ ...options });
     const next = { ...options };
@@ -94,6 +99,8 @@ function denoiserKey(options) {
 }
 /** One independently configured image and its accumulation, owned by an engine. */
 export default class Render {
+    /** Enabled surface outputs. Default []; readPixels rejects outputs not enabled here. */ aovs = [];
+    /** Independent AOV sample cap. Default 16. */ aovSamples = 16;
     /** Maximum complete samples. Default 2048. */ maxSamples = 2048;
     /**
      * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
@@ -112,7 +119,10 @@ export default class Render {
     /** Minimum transmissive path alpha. Default 1. Changing it restarts this render. */ transmissiveOutputAlphaMin = 1;
     /** Execution budget in milliseconds. Default 21. */ timeBudgetMs = 21;
     /** Maximum tiles per frame. Default Infinity. */ maxTiles = Infinity;
-    /** Allow several samples per frame when possible. Default false. */ allowMultipleSamplesPerFrame = false;
+    /** Let one refine submit several samples within timeBudgetMs; WebGPU requires GPU timestamps. Default false. */ batchSamples = false;
+    /** @deprecated Use batchSamples; this alias will be removed in a later release. Default false. */
+    get allowMultipleSamplesPerFrame() { return this.batchSamples; }
+    set allowMultipleSamplesPerFrame(value) { this.batchSamples = value; }
     /** Adaptive resolution controller, or false. Default false. */ adaptiveResolution = false;
     _resolutionScale = 1;
     /** Canvas-relative scale. Default 1; cannot be assigned on a fixed-size render. */
@@ -156,6 +166,7 @@ export default class Render {
         if (current === null && next === null)
             return this._denoiserReady;
         if (next && current && denoiserKey(next) === denoiserKey(current)
+            && (next.type !== 'custom' || current.type === 'custom' && aovMask(next.aovs ?? []) === aovMask(current.aovs ?? []))
             && next.schedule === current.schedule && (next.type !== 'oidn' ||
             (current.type === 'oidn' && next.signal === current.signal)))
             return this._denoiserReady;
@@ -168,6 +179,7 @@ export default class Render {
     _status = 'preparing';
     _disposed = false;
     _busy = false;
+    _refineOptions;
     _offlineCamera = false;
     _input = { scene: -1, camera: -1, settings: '' };
     _adaptiveScale = 1;
@@ -205,8 +217,10 @@ export default class Render {
                 throw new Error('Provide positive integer width and height, or resolutionScale, exclusively.');
             this._fixed = { width: options.width, height: options.height };
         }
-        const { width: _width, height: _height, resolutionScale, fallback, denoiser, ...settings } = options;
+        const { width: _width, height: _height, resolutionScale, fallback, denoiser, allowMultipleSamplesPerFrame, ...settings } = options;
         Object.assign(this, settings);
+        if (settings.batchSamples === undefined && allowMultipleSamplesPerFrame !== undefined)
+            this.batchSamples = allowMultipleSamplesPerFrame;
         if (resolutionScale !== undefined)
             this.resolutionScale = resolutionScale;
         this._adaptiveScale = this._resolutionScale;
@@ -219,9 +233,9 @@ export default class Render {
     }
     /** Actual target width; before allocation uses the requested dimensions. */ get width() { return this._target?.getMemory().width || this._size().width; }
     /** Actual target height; before allocation uses the requested dimensions. */ get height() { return this._target?.getMemory().height || this._size().height; }
-    /** Complete samples since the last restart; stale engine inputs report 0. Default 0. */
+    /** Complete beauty samples since the last restart; stale engine inputs report 0. Default 0. */
     get samples() { return this._current ? this._target?.getTotalSamplesRendered() ?? 0 : 0; }
-    /** Whether complete samples reached maxSamples. Default false. */ get converged() { return this.samples >= this.maxSamples; }
+    /** Whether complete beauty samples reached maxSamples. Default false. */ get converged() { return this.samples >= this.maxSamples; }
     /** Current execution state. Default preparing. */ get status() {
         if (!this._current && this._status !== 'error')
             return this._engine._ready ? 'converging' : 'preparing';
@@ -232,7 +246,63 @@ export default class Render {
     /** @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; }
+    /** Latest WebGPU full beauty sample estimate in milliseconds. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
+    get gpuSampleTimeMs() { return !this._busy && this._current ? this._target?.getRealtimeSampleTime?.() : undefined; }
+    /** Waits for the next release of WebGPU sampling queue capacity. Resolves immediately if no sampling is queued or on WebGL; does not submit work. Throws after disposal. */
+    whenReadyToRefine() {
+        if (this._disposed)
+            throw new Error('Render is disposed.');
+        return this._target?.whenTraceAvailable?.() ?? Promise.resolve();
+    }
+    /** Complete surface-output samples since restart; stale inputs report 0. Independent of beauty samples. Default 0. */
+    get aovSamplesRendered() { return this._current ? this._target?.getAovSamples?.() ?? 0 : 0; }
+    /** @internal */
+    _completeFor(channel) {
+        const kind = displayAovKind(channel);
+        return kind && this.aovs.includes(kind) && this._target?.aovReady
+            ? this._current && this._target.aovReady(kind) : this._complete;
+    }
+    /** @internal */
+    _restartAovs() {
+        this._target?.activate();
+        this._target?.restartAovs?.();
+        this._status = 'converging';
+    }
+    _refineAov(kind) {
+        if (this._engine._initializationError)
+            throw this._engine._initializationError;
+        if (!this.aovs.includes(kind))
+            throw new Error(`AOV ${kind} is not enabled`);
+        if (!this._engine._ready) {
+            const generation = this._engine._deviceGeneration;
+            void this._engine.init().catch(error => {
+                if (this._disposed || generation !== this._engine._deviceGeneration)
+                    return;
+                this._status = 'error';
+                this._engine._notifyError(error);
+            });
+            return this._status = 'preparing';
+        }
+        const started = performance.now();
+        const target = this._synchronize();
+        if (!target)
+            return this._status = 'preparing';
+        const before = target.getAovSamples?.() ?? 0;
+        const limit = kind === 'id' || kind === 'motion' ? 1 : Math.min(this.maxSamples, this.aovSamples);
+        if (!target.refineAovs?.(this._engine._inputs.value, Math.min(limit, (target.getAovSamples?.() ?? 0) + 1)))
+            return this._status = 'compiling';
+        if ((target.getAovSamples?.() ?? 0) > before) {
+            this._frameTime = Math.max(.001, performance.now() - started);
+            this._frameStart = started;
+            this._frameScale = this._adaptiveScale;
+            this._adaptResolution(true);
+        }
+        return this._status = (target.getAovSamples?.() ?? 0) >= limit ? 'finished' : 'converging';
+    }
     _validate() {
+        aovMask(this.aovs);
+        if (!Number.isInteger(this.aovSamples) || this.aovSamples < 1)
+            throw new Error('aovSamples must be a positive integer.');
         if (!Number.isFinite(this.maxSamples) || this.maxSamples < 1)
             throw new Error('maxSamples must be positive.');
         if (this.dispersionWavelengths !== 1 && this.dispersionWavelengths !== 3)
@@ -248,7 +318,11 @@ export default class Render {
         return { width: Math.max(1, Math.round(this._engine.display.canvas.width * scale)), height: Math.max(1, Math.round(this._engine.display.canvas.height * scale)) };
     }
     _settings(sampleCap = this.maxSamples) {
-        return collectTraceSettings(this, sampleCap);
+        const settings = collectTraceSettings(this, sampleCap);
+        settings.batchSamples = this._refineOptions?.batchSamples ?? settings.batchSamples;
+        if (this._denoiserOptions?.type === 'custom')
+            settings.aovs = [...new Set([...this.aovs, ...(this._denoiserOptions.aovs ?? [])])];
+        return settings;
     }
     _synchronize(sampleCap = this.maxSamples, offline = false) {
         this._validate();
@@ -264,6 +338,8 @@ export default class Render {
         const inputs = this._engine._inputs;
         target.configure(settings);
         target.activate();
+        target.setRealtimeBatchBudget?.(this._refineOptions?.targetBatchTimeMs ?? Infinity);
+        target.setRealtimeDeferPostProcess?.(!!this._refineOptions?.deferResolve);
         if ((!offline && this._offlineCamera) || inputs.scene !== this._input.scene || inputs.camera !== this._input.camera || key !== this._input.settings) {
             if (!offline)
                 this._offlineCamera = false;
@@ -294,8 +370,8 @@ export default class Render {
             this._sampleStart = undefined;
         return compiling;
     }
-    _adaptResolution() {
-        if (!this._busy && this.adaptiveResolution && this._frameTime > 0 && this.samples > 0) {
+    _adaptResolution(surfaceOnly = false) {
+        if (!this._busy && this.adaptiveResolution && this._frameTime > 0 && (surfaceOnly ? this.aovSamplesRendered > 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;
@@ -328,21 +404,26 @@ export default class Render {
         this._adaptiveFrames.clear();
         this._adaptiveFastFrames = 0;
     }
-    /** Accumulates within this frame's budget. Rejects calls during converge or after disposal. */
-    refine() {
+    /** Accumulates within this frame's budget. Default undefined traces beauty and requested AOVs. Pass an enabled AOV kind to refine surface outputs only, without beauty or denoising; progress is aovSamplesRendered. Options default to this render's execution settings. Rejects calls during converge or after disposal. */
+    refine(channel, options) {
         if (this._busy)
             throw new Error('Cannot refine a render while converge is running.');
         if (this._disposed)
             throw new Error('Render is disposed.');
         this._engine._setRenderError();
+        const previous = this._refineOptions;
+        this._refineOptions = options;
         try {
-            return this._refine();
+            if (options?.targetBatchTimeMs !== undefined && (!Number.isFinite(options.targetBatchTimeMs) || options.targetBatchTimeMs <= 0))
+                throw new RangeError('targetBatchTimeMs must be positive and finite.');
+            return channel === undefined ? this._refine() : this._refineAov(channel);
         }
         catch (error) {
             this._engine._setRenderError(this._engine._notifyError(error));
             return this._status = 'error';
         }
         finally {
+            this._refineOptions = previous;
             this._engine._reportShaderProgress();
         }
     }
@@ -374,6 +455,9 @@ export default class Render {
             if (this._trace(target, limit))
                 return this._status = 'compiling';
         }
+        else if (target.refineAovs && !target.refineAovs(this._engine._inputs.value)) {
+            return this._status = 'compiling';
+        }
         this._maybeDenoise(false, limit);
         if (this._denoisePending)
             return this._status = this.converged ? 'denoising' : 'converging';
@@ -406,8 +490,13 @@ export default class Render {
             return this.maxSamples;
         if (this._denoisedSamples === 0)
             return 1;
-        if (performance.now() - this._lastDenoiseTime >= 10000)
+        const sinceUpdate = performance.now() - this._lastDenoiseTime;
+        if (sinceUpdate >= 10000)
             return Math.min(this.maxSamples, this.samples + 1);
+        // Batched sampling doubles the count within a few frames. Without a floor,
+        // most filtering would go to images replaced almost at once.
+        if (sinceUpdate < 500)
+            return this.maxSamples;
         return Math.min(this.maxSamples, Math.max(4, this._denoisedSamples * 2));
     }
     /** Reloads a filter dropped by device recovery; failures report through engine errors. */
@@ -446,7 +535,7 @@ export default class Render {
             if (revision !== this._filterRevision || this._disposed)
                 return;
             if (options.type === 'custom') {
-                this._filter = { kind: 'custom', denoiser: options.denoiser };
+                this._filter = { kind: 'custom', denoiser: options.denoiser, aovs: options.aovs };
                 return;
             }
             const { loadOIDNNetwork } = await loadOIDN();
@@ -547,12 +636,21 @@ export default class Render {
             }
         });
     }
-    /** 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') {
         if (this._disposed)
             throw new Error('Render is disposed.');
         const target = this._target;
-        if (!target)
+        if (['depth', 'position', 'roughness', 'diffuseAlbedo', 'specularAlbedo', 'id', 'motion'].includes(kind)) {
+            const aov = kind;
+            aovMask(this.aovs);
+            if (!this.aovs.includes(aov))
+                throw new Error(`AOV ${aov} is not enabled`);
+            if (!target?.readAov)
+                throw new Error('AOV output is not ready');
+            target.activate();
+            return target.readAov(aov);
+        }
+        if (!target || this.samples === 0)
             return { width: 0, height: 0, data: new Float32Array(0) };
         if (kind === 'denoised' && this._denoisedSamples === 0) {
             if (!this._warnedDenoisedReadback) {
@@ -566,7 +664,7 @@ export default class Render {
     }
     /** Borrows a read-only WebGPU texture; undefined on WebGL or before a complete sample. Kind is required. HDR is native resolved linear ray color before denoising/display composition, with DenoiseInput.color normalization and coverage. Display is the latest compose, including filters and display passes. Valid only until this render's next refine/converge, display present/setSize, restart/dispose or device loss; never retain, write or destroy it. */
     getOutputTexture(kind) {
-        if (!this._complete || this._engine.backend !== 'webgpu')
+        if (this._engine.backend !== 'webgpu' || (kind === 'hdr' ? !this._complete : !this._current || !this._target?.presentationComplete || (!this._complete && !this._target.getAovSamples?.())))
             return;
         return this._target?.getOutputTexture?.(kind);
     }
@@ -650,7 +748,7 @@ export default class Render {
                 this._cancelDenoise();
                 target.activate();
                 target.restartSamples();
-                target.configure({ ...this._settings(cap), allowMultipleSamplesPerFrame: true });
+                target.configure({ ...this._settings(cap), batchSamples: true });
                 let batch = options.targetBatchTimeMs && this._engine.device ? 1 : Math.min(batchLimit, cap);
                 let previous = -1, lastPreview = performance.now();
                 const started = performance.now();