@meimu/mutracer 0.1.5 → 0.3.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,9 +99,12 @@ 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).
+     * Complete caustic light-to-camera paths can be longer than this depth.
      * Total path events, including transmission and alpha skips, are capped at 20
      * and at three times this depth. Intel Mac WebGL uses min(depth, 3), doubled
      * for scenes with transmission or alpha, with its existing early termination.
@@ -104,6 +112,7 @@ export default class Render {
      */ bounces = 3;
     /** Per-sample radiance clamp; 0 disables it. Default 0. */ clamping = 0;
     /** Sampling sequence. Default sobol. */ samplingPattern = 'sobol';
+    /** Caustic estimators. Default undefined (all disabled). */ caustics;
     /** WebGPU light candidates per vertex; ignored on WebGL. Default 4. */ directLightCandidates = 4;
     /** Rounded material edges. Default true. */ bevel = true;
     /** Bevel probes, clamped to 1–32. Default 8. */ bevelSamples = 8;
@@ -111,8 +120,11 @@ export default class Render {
     /** WebGPU primary-ray alpha policy; ignored on WebGL. Default stochastic. */ alphaBlendStrategy = 'stochastic';
     /** 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;
+    /** Maximum tile grid size per sample, rounded up to a rectangular grid. Fewer tiles make each tile larger; this does not cap work per frame or refine call. Default Infinity. */ maxTiles = Infinity;
+    /** Let one refine submit several samples within an estimated timeBudgetMs; one sample or tile can exceed it. 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 +168,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 +181,8 @@ export default class Render {
     _status = 'preparing';
     _disposed = false;
     _busy = false;
+    _refineOptions;
+    _refillController;
     _offlineCamera = false;
     _input = { scene: -1, camera: -1, settings: '' };
     _adaptiveScale = 1;
@@ -205,8 +220,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;
@@ -217,11 +234,11 @@ export default class Render {
         if (denoiser)
             void this.setDenoiser(denoiser).catch(error => this._engine._notifyError(error));
     }
-    /** 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. */
+    /** Output width: exact for fixed renders; otherwise the target width, or the requested width before allocation. */ get width() { return this._fixed?.width ?? (this._target?.getMemory().width || this._size().width); }
+    /** Output height: exact for fixed renders; otherwise the target height, or the requested height before allocation. */ get height() { return this._fixed?.height ?? (this._target?.getMemory().height || this._size().height); }
+    /** 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 +249,79 @@ 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; }
+    /** @deprecated Use refineUntil for custom frame loops; this will be removed in a later release. Latest WebGPU full beauty sample estimate in milliseconds, extrapolated from tile GPU time when tiled. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
+    get gpuSampleTimeMs() { return this._gpuSampleTimeMs; }
+    /** @internal Latest WebGPU full beauty sample estimate in milliseconds; with tiling, extrapolated from tile GPU time. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
+    get _gpuSampleTimeMs() { return !this._busy && this._current ? this._target?.getRealtimeSampleTime?.() : undefined; }
+    /** @internal Latest WebGPU beauty tile estimate in milliseconds, including amortized caustic work; equal to the sample estimate without tiling. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
+    get gpuTileTimeMs() { return !this._busy && this._current ? this._target?.getRealtimeTileTime?.() : undefined; }
+    /**
+     * @deprecated Use refineUntil; this will be removed in a later release. Waits for the
+     * next release of WebGPU sampling queue capacity and returns true when sampling was
+     * queued. Returns false immediately with no queued sampling, on WebGL, or for only
+     * denoising, display or offline convergence work. Does not submit work. Throws after
+     * disposal.
+     */
+    whenReadyToRefine() { return this._whenReadyToRefine(); }
+    /** @internal Waits for the next release of WebGPU sampling queue capacity and returns true
+     * when sampling was queued. Returns false immediately with no queued sampling,
+     * on WebGL, or for only denoising, display or offline convergence work.
+     * Does not submit work. Throws after disposal.
+     */
+    _whenReadyToRefine() {
+        if (this._disposed)
+            throw new Error('Render is disposed.');
+        return !this._busy ? this._target?.whenTraceAvailable?.() ?? Promise.resolve(false) : Promise.resolve(false);
+    }
+    /** 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._targetCamera(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)
@@ -247,8 +336,51 @@ export default class Render {
         const scale = this.adaptiveResolution ? Math.min(this._adaptiveScale, this._resolutionScale) : this._resolutionScale;
         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)) };
     }
+    /**
+     * Backends may round targets up. A fixed render widens the view over the extra
+     * pixels so the requested centered rectangle keeps its framing and square pixels.
+     */
+    _targetCamera(camera) {
+        const memory = this._target?.getMemory(), fixed = this._fixed;
+        if (!memory || !fixed || (memory.width === fixed.width && memory.height === fixed.height))
+            return camera;
+        const scaleX = memory.width / fixed.width, scaleY = memory.height / fixed.height;
+        const widened = camera.clone();
+        widened.transform = camera.transform;
+        if (camera.projection === 'perspective') {
+            widened.fov = Math.atan(Math.tan(camera.fov * Math.PI / 360) * scaleY) * 360 / Math.PI;
+            widened.aspect = (camera.aspect ?? fixed.width / fixed.height) * scaleX / scaleY;
+            // Keeps the lens focal length, and with it depth of field.
+            widened.sensorHeight = camera.sensorHeight * scaleY;
+        }
+        else {
+            const x = (camera.left + camera.right) / 2, y = (camera.bottom + camera.top) / 2;
+            widened.left = x + (camera.left - x) * scaleX;
+            widened.right = x + (camera.right - x) * scaleX;
+            widened.bottom = y + (camera.bottom - y) * scaleY;
+            widened.top = y + (camera.top - y) * scaleY;
+        }
+        return widened;
+    }
+    /** @internal Crops a target-sized RGBA image to a fixed render's requested rectangle. */
+    _cropOutput(image) {
+        const fixed = this._fixed;
+        if (!fixed || !image.width || (image.width === fixed.width && image.height === fixed.height))
+            return image;
+        const { width, height } = fixed, data = new image.data.constructor(width * height * 4);
+        const left = (image.width - width) >> 1, top = (image.height - height) >> 1;
+        for (let y = 0; y < height; y++) {
+            const start = ((y + top) * image.width + left) * 4;
+            data.set(image.data.subarray(start, start + width * 4), y * width * 4);
+        }
+        return { width, height, data };
+    }
     _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 +396,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;
@@ -289,13 +423,13 @@ export default class Render {
             this._sampleStart = performance.now();
             this._sampleScale = this._adaptiveScale;
         }
-        const compiling = target.trace(this._engine._inputs.value, limit);
+        const compiling = target.trace(this._targetCamera(this._engine._inputs.value), limit);
         if (compiling)
             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,24 +462,118 @@ 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();
         }
     }
+    /**
+     * Calls refine() once synchronously, then keeps sampling on WebGPU until deadline.
+     * Call present() right after it; later samples appear at the next presentation.
+     * Sampling continues only with batchSamples on, the final channel displayed, a
+     * visible page and tiles that fit timeBudgetMs. It stops on abort or convergence.
+     * Preparing, compiling, denoising and the first incomplete sample advance only
+     * through the synchronous call, which is all WebGL runs. A new call ends the
+     * previous one. Asynchronous errors set status to error and resolve; synchronous
+     * errors follow refine().
+     * @param deadline End time in performance.now() milliseconds.
+     * @param options.signal Optional application cancellation; default none. An
+     * already aborted signal still permits the synchronous refine().
+     */
+    refineUntil(deadline, options) {
+        return this._refineToDeadline(deadline, options?.signal);
+    }
+    _refineToDeadline(deadline, signal, options, beforeRefill) {
+        this._refillController?.abort();
+        const controller = this._refillController = new AbortController();
+        // Keep lifecycle exceptions synchronous, just like refine(). Install the
+        // controller first so a synchronous sample listener can revoke this call.
+        try {
+            this.refine(undefined, options);
+        }
+        catch (error) {
+            controller.abort();
+            if (this._refillController === controller)
+                this._refillController = undefined;
+            throw error;
+        }
+        const device = this._engine.device;
+        const canContinue = (afterWait = false) => !controller.signal.aborted && !signal?.aborted &&
+            !this._disposed && !this._busy && device !== undefined && device === this._engine.device &&
+            (typeof document === 'undefined' || !document.hidden) && performance.now() < deadline &&
+            this.batchSamples && this.status === 'converging' && !this.denoising && this.samples > 0 &&
+            this.gpuTileTimeMs !== undefined && this.gpuTileTimeMs <= this.timeBudgetMs &&
+            this._engine.display.channel === 'final' && (!afterWait || this._engine._isPresented(this._target));
+        if (!canContinue()) {
+            if (this._refillController === controller)
+                this._refillController = undefined;
+            return Promise.resolve();
+        }
+        return (async () => {
+            let timer;
+            const abort = () => controller.abort();
+            const visibility = () => { if (document.hidden)
+                abort(); };
+            let stopped;
+            const cancelled = new Promise(resolve => { stopped = () => resolve(false); });
+            controller.signal.addEventListener('abort', stopped, { once: true });
+            signal?.addEventListener('abort', abort, { once: true });
+            if (typeof document !== 'undefined')
+                document.addEventListener('visibilitychange', visibility);
+            if (Number.isFinite(deadline))
+                timer = setTimeout(abort, Math.min(2147483647, Math.max(0, deadline - performance.now())));
+            try {
+                while (canContinue()) {
+                    if (!await Promise.race([this._whenReadyToRefine(), cancelled]))
+                        break;
+                    beforeRefill?.();
+                    if (!canContinue(true))
+                        break;
+                    this.refine(undefined, { targetBatchTimeMs: 4, deferResolve: true });
+                }
+            }
+            catch (error) {
+                if (!controller.signal.aborted && !this._disposed) {
+                    this._engine._setRenderError(this._engine._notifyError(error));
+                    this._status = 'error';
+                }
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal?.removeEventListener('abort', abort);
+                controller.signal.removeEventListener('abort', stopped);
+                if (typeof document !== 'undefined')
+                    document.removeEventListener('visibilitychange', visibility);
+                if (this._refillController === controller)
+                    this._refillController = undefined;
+            }
+        })();
+    }
+    /** @internal Whether this render currently has a between-frame lease. */
+    get _refilling() { return !!this._refillController && !this._refillController.signal.aborted; }
+    /** @internal Preserve loop-specific synchronous overrides while using refineUntil. */
+    _refineUntil(deadline, signal, options, beforeRefill) {
+        return this._refineToDeadline(deadline, signal, options, beforeRefill);
+    }
     _refine() {
         if (this._engine._initializationError)
             throw this._engine._initializationError;
@@ -374,6 +602,9 @@ export default class Render {
             if (this._trace(target, limit))
                 return this._status = 'compiling';
         }
+        else if (target.refineAovs && !target.refineAovs(this._targetCamera(this._engine._inputs.value))) {
+            return this._status = 'compiling';
+        }
         this._maybeDenoise(false, limit);
         if (this._denoisePending)
             return this._status = this.converged ? 'denoising' : 'converging';
@@ -406,8 +637,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 +682,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();
@@ -483,9 +719,10 @@ export default class Render {
         });
     }
     _cancelDenoise() { this._denoiseController?.abort(); this._denoiseController = undefined; this._denoiseRevision++; this._target?.cancelDenoise?.(); this._denoisePending = undefined; this._denoisedSamples = 0; }
-    /** @internal */ _inputsChanged(resetTiming = false) { this._cancelDenoise(); if (resetTiming)
+    /** @internal */ _inputsChanged(resetTiming = false) { this._refillController?.abort(); this._cancelDenoise(); if (resetTiming)
         this._target?.invalidateTiming?.(); }
     /** @internal */ _deviceLost(recovering) {
+        this._refillController?.abort();
         this._cancelAdaptiveFrames();
         this._cancelDenoise();
         this._filterRevision++;
@@ -496,7 +733,7 @@ export default class Render {
         this._input = { scene: -1, camera: -1, settings: '' };
         this._status = recovering ? 'preparing' : 'error';
     }
-    /** @internal */ _displayChanged() { this._cancelDenoise(); this._target?.invalidateDenoisedOutput(); }
+    /** @internal */ _displayChanged() { this._refillController?.abort(); this._cancelDenoise(); this._target?.invalidateDenoisedOutput(); }
     _maybeDenoise(force = false, sampleTarget = this._nextSampleTarget()) {
         const target = this._target, filter = this._filter;
         if (!target || !filter || this._denoisePending || this.samples < 1 || this._denoisedSamples === this.samples)
@@ -535,7 +772,7 @@ export default class Render {
                 if (frameStart !== undefined)
                     this._frameTime = Math.max(this._frameTime, this._lastDenoiseTime - frameStart);
             }
-        });
+        }, controller.signal);
         this._denoisePending = task;
         void task.catch(error => { if (revision === this._denoiseRevision && !this._disposed)
             this._engine._notifyError(error); }).finally(() => {
@@ -547,12 +784,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 this._cropOutput(await 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) {
@@ -562,21 +808,22 @@ export default class Render {
             kind = 'hdr';
         }
         target.activate();
-        return target.readOutput(kind);
+        return this._cropOutput(await target.readOutput(kind));
     }
     /** 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);
     }
     /** Discards only this render's accumulation and pending denoising. */
     restart() { if (this._disposed)
-        throw new Error('Render is disposed.'); this._cancelDenoise(); this._cancelAdaptiveFrames(); this._sampleStart = this._frameStart = undefined; this._frameTime = 0; this._target?.restartSamples(); this._status = 'converging'; }
+        throw new Error('Render is disposed.'); this._refillController?.abort(); 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)
             return;
+        this._refillController?.abort();
         this._disposed = true;
         this._events.clear();
         this._filterRevision++;
@@ -622,6 +869,7 @@ export default class Render {
             if (current.scene !== inputs.scene || current.camera !== inputs.camera)
                 throw new Error('Engine inputs changed during converge.');
         };
+        this._refillController?.abort();
         this._busy = true;
         const abortConverge = () => this._cancelDenoise();
         options.signal?.addEventListener('abort', abortConverge, { once: true });
@@ -650,7 +898,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();
@@ -661,7 +909,7 @@ export default class Render {
                     target.activate();
                     target.setOfflineRenderOptions({ samplesPerBatch: batch, deferPostProcess: true, sampleSequenceOffset: offset });
                     const before = target.getTotalSamplesRendered(), batchStarted = performance.now();
-                    this._status = target.trace(camera, cap) ? 'compiling' : 'converging';
+                    this._status = target.trace(this._targetCamera(camera), cap) ? 'compiling' : 'converging';
                     const count = target.getTotalSamplesRendered();
                     if (count !== previous) {
                         previous = count;