@meimu/mutracer 0.0.0-stage → 0.1.0

package/lib/Render.js

@@ -0,0 +1,671 @@
+import { Events } from './util/events.js';
+import { cameraSnapshot } from './renderer/cameraSnapshot.js';
+import { collectTraceSettings, imageSettingsKey } from './settings/render.js';
+import { DEFAULT_JNLM_OPTIONS, createJNLMDenoiser } from './renderer/jnlm.js';
+import { nextPreviewScale } from './renderer/util.js';
+let oidnModule;
+const loadOIDN = () => oidnModule ??= import('./renderer/oidnNetwork.js');
+function validateDenoiserOptions(options) {
+    if (!options || typeof options !== 'object' || (options.type !== 'jnlm' && options.type !== 'oidn' && options.type !== 'custom'))
+        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']
+            : ['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))
+            throw new Error(`Denoiser field ${key} does not belong to ${options.type}.`);
+    if (options.schedule !== undefined && !['converged', 'progressive', 'every-sample'].includes(options.schedule))
+        throw new Error('Unknown denoise schedule.');
+    if (options.type === 'jnlm')
+        createJNLMDenoiser(options);
+    else if (options.type === 'custom') {
+        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.');
+    }
+    else {
+        if (options.weightsUrl !== undefined) {
+            if (options.model !== undefined || options.weightsBaseUrl !== undefined)
+                throw new Error('weightsUrl is mutually exclusive with model and weightsBaseUrl.');
+        }
+        else if (options.aux !== undefined || options.hdr !== undefined || options.hdrTransfer !== undefined)
+            throw new Error('aux, hdr and hdrTransfer require weightsUrl.');
+        for (const key of ['weightsUrl', 'weightsBaseUrl'])
+            if (options[key] !== undefined && !isURL(options[key]))
+                throw new Error(`${key} must be a nonempty string or URL.`);
+        if (options.auxiliaryModelUrls !== undefined) {
+            const urls = options.auxiliaryModelUrls;
+            if (!urls || !isURL(urls.albedo) || !isURL(urls.normal) || Object.keys(urls).some(key => !['albedo', 'normal'].includes(key)))
+                throw new Error('auxiliaryModelUrls requires only albedo and normal URLs.');
+        }
+        for (const [key, values] of [['engine', ['auto', 'wgsl', 'webnn']], ['precision', ['auto', 'fp32', 'fp16']], ['hdrTransfer', ['pu', 'log']]]) {
+            if (options[key] !== undefined && !values.includes(options[key]))
+                throw new Error(`Unknown OIDN ${key}.`);
+        }
+        for (const key of ['aux', 'hdr'])
+            if (options[key] !== undefined && typeof options[key] !== 'boolean')
+                throw new Error(`${key} must be boolean.`);
+        if (options.dynamicTile !== undefined && typeof options.dynamicTile !== 'boolean') {
+            if (!options.dynamicTile || typeof options.dynamicTile !== 'object')
+                throw new Error('dynamicTile must be boolean or tile settings.');
+            for (const [key, value] of Object.entries(options.dynamicTile)) {
+                if (!['minTileSize', 'initialTileSize', 'targetTileTimeMs', 'adjustmentStep'].includes(key) || (value !== undefined && (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)))
+                    throw new Error(`Invalid dynamicTile ${key}.`);
+            }
+        }
+        if (options.model !== undefined && !['standard', 'small', 'cleanAuxLarge'].includes(options.model))
+            throw new Error('Unknown OIDN model.');
+        if (options.maxTileSize !== undefined && (!Number.isInteger(options.maxTileSize) || options.maxTileSize < 1))
+            throw new Error('maxTileSize must be a positive integer.');
+    }
+}
+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 !== 'oidn')
+        return Object.freeze({ ...options });
+    const next = { ...options };
+    if (options.weightsBaseUrl !== undefined)
+        next.weightsBaseUrl = String(options.weightsBaseUrl);
+    if (options.weightsUrl !== undefined)
+        next.weightsUrl = String(options.weightsUrl);
+    if (options.auxiliaryModelUrls !== undefined)
+        next.auxiliaryModelUrls = Object.freeze({ albedo: String(options.auxiliaryModelUrls.albedo), normal: String(options.auxiliaryModelUrls.normal) });
+    if (typeof options.dynamicTile === 'object')
+        next.dynamicTile = Object.freeze({ ...options.dynamicTile });
+    return Object.freeze(next);
+}
+function denoiserKey(options) {
+    if (options.type === 'custom')
+        return options.denoiser;
+    if (options.type === 'jnlm')
+        return JSON.stringify({ type: 'jnlm', ...Object.fromEntries(Object.entries(DEFAULT_JNLM_OPTIONS).map(([key, value]) => [key, options[key] ?? value])) });
+    const tile = options.dynamicTile;
+    return JSON.stringify({ type: 'oidn',
+        ...(options.weightsUrl === undefined ? { model: options.model ?? 'standard', weightsBaseUrl: options.weightsBaseUrl?.toString() } : { weightsUrl: String(options.weightsUrl), aux: options.aux ?? true, hdr: options.hdr ?? true, hdrTransfer: options.hdrTransfer ?? 'pu' }),
+        auxiliaryModelUrls: options.auxiliaryModelUrls && { albedo: String(options.auxiliaryModelUrls.albedo), normal: String(options.auxiliaryModelUrls.normal) },
+        maxTileSize: options.maxTileSize, engine: options.engine ?? 'auto', precision: options.precision ?? 'auto',
+        dynamicTile: tile === false ? false : { minTileSize: typeof tile === 'object' ? tile.minTileSize ?? 256 : 256,
+            initialTileSize: typeof tile === 'object' ? tile.initialTileSize ?? 432 : 432,
+            targetTileTimeMs: typeof tile === 'object' ? tile.targetTileTimeMs ?? 16 : 16,
+            adjustmentStep: typeof tile === 'object' ? tile.adjustmentStep ?? 16 : 16 }
+    });
+}
+/** One independently configured image and its accumulation, owned by an engine. */
+export default class Render {
+    /** Maximum complete samples. Default 2048. */ maxSamples = 2048;
+    /**
+     * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * 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.
+     * Default 3.
+     */ bounces = 3;
+    /** Per-sample radiance clamp; 0 disables it. Default 0. */ clamping = 0;
+    /** Sampling sequence. Default sobol. */ samplingPattern = 'sobol';
+    /** 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;
+    /** Dispersion wavelengths per sample. Default 3. */ dispersionWavelengths = 3;
+    /** 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;
+    /** Adaptive resolution controller, or false. Default false. */ adaptiveResolution = false;
+    _resolutionScale = 1;
+    /** Canvas-relative scale. Default 1; cannot be assigned on a fixed-size render. */
+    get resolutionScale() { return this._resolutionScale; }
+    set resolutionScale(value) {
+        if (this._fixed)
+            throw new Error('Fixed-size renders cannot use resolutionScale.');
+        if (!Number.isFinite(value) || value <= 0)
+            throw new Error('resolutionScale must be positive.');
+        this._resolutionScale = value;
+    }
+    _fallback = null;
+    /** Single-level fallback on this engine. Default null; chains and cycles are rejected. */
+    get fallback() { return this._fallback; }
+    set fallback(value) {
+        if (value && (value._engine !== this._engine || value === this || value.fallback))
+            throw new Error('Fallback must be a render on the same engine with no fallback.');
+        if (value && this._dependents.size)
+            throw new Error('Fallback renders cannot have their own fallback.');
+        this._fallback?._dependents.delete(this);
+        this._fallback = value;
+        value?._dependents.add(this);
+    }
+    _dependents = new Set();
+    _denoiserOptions = null;
+    /** Frozen configuration snapshot. Default null. Change it with {@link Render.setDenoiser}. */
+    get denoiser() { return this._denoiserOptions; }
+    /**
+     * Replaces the denoising configuration; null disables denoising. Invalid options throw synchronously
+     * before replacing any state. Resolves when the filter is ready to use (after OIDN weights load) or this
+     * configuration is replaced; rejects when loading fails. An equal configuration returns the current
+     * promise without reloading.
+     */
+    setDenoiser(options) {
+        if (options !== null)
+            validateDenoiserOptions(options);
+        const next = options ? snapshotDenoiserOptions(options) : null;
+        const current = this._denoiserOptions;
+        if (current === null && next === null)
+            return this._denoiserReady;
+        if (next && current && denoiserKey(next) === denoiserKey(current)
+            && next.schedule === current.schedule && (next.type !== 'oidn' ||
+            (current.type === 'oidn' && next.signal === current.signal)))
+            return this._denoiserReady;
+        this._denoiserOptions = next;
+        return this._refreshDenoiser() ?? this._denoiserReady;
+    }
+    _denoiserReady = Promise.resolve();
+    _fixed;
+    _target;
+    _status = 'preparing';
+    _disposed = false;
+    _busy = false;
+    _offlineCamera = false;
+    _input = { scene: -1, camera: -1, settings: '' };
+    _adaptiveScale = 1;
+    _lastScale = 1;
+    _frameTime = 0;
+    _events = new Events();
+    /** Owning engine. */ get engine() { return this._engine; }
+    /** Whether inference is queued or running, including intermediate updates. Default false. */ get denoising() { return !!this._denoisePending; }
+    /** Subscribes to every complete sample on this render; returns unsubscribe. */
+    on(event, listener) { return this._events.on(event, listener); }
+    _filter;
+    _filterKey = '';
+    _warnedWebGPUFilter = false;
+    _denoiseController;
+    _filterRevision = 0;
+    _filterPending;
+    _denoiseRevision = 0;
+    _denoisePending;
+    _denoisedSamples = 0;
+    _lastDenoiseTime = 0;
+    _warnedDenoisedReadback = false;
+    /** @internal */ _engine;
+    constructor(engine, options = {}) {
+        this._engine = engine;
+        if (options.denoiser != null)
+            validateDenoiserOptions(options.denoiser);
+        if ('width' in options || 'height' in options) {
+            if ('resolutionScale' in options || !Number.isInteger(options.width) || !Number.isInteger(options.height) || options.width < 1 || options.height < 1)
+                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;
+        Object.assign(this, settings);
+        if (resolutionScale !== undefined)
+            this.resolutionScale = resolutionScale;
+        this._adaptiveScale = this._resolutionScale;
+        this._lastScale = this._resolutionScale;
+        this._validate();
+        this.fallback = fallback ?? null;
+        engine._register(this);
+        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. */
+    get samples() { return this._current ? this._target?.getTotalSamplesRendered() ?? 0 : 0; }
+    /** Whether complete 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';
+        return this._status;
+    }
+    get _current() { const inputs = this._engine._inputs; return inputs.scene === this._input.scene && inputs.camera === this._input.camera && !this._disposed; }
+    /** @internal */ get _complete() { return this._current && !!this._target?.presentationComplete && !this._target.isFirstFrame() && this.samples > 0; }
+    /** @internal */ get _output() { if (this._disposed)
+        throw new Error('Render is disposed.'); return this._target; }
+    _validate() {
+        if (!Number.isFinite(this.maxSamples) || this.maxSamples < 1)
+            throw new Error('maxSamples must be positive.');
+        if (this.dispersionWavelengths !== 1 && this.dispersionWavelengths !== 3)
+            throw new Error('dispersionWavelengths must be 1 or 3.');
+        const adaptive = this.adaptiveResolution;
+        if (adaptive && (this._fixed || !Number.isFinite(adaptive.targetFrameMs) || adaptive.targetFrameMs <= 0 || !Number.isFinite(adaptive.minScale) || adaptive.minScale <= 0 || adaptive.minScale > this._resolutionScale))
+            throw new Error('adaptiveResolution requires a scale-based render with positive targetFrameMs and minScale <= resolutionScale.');
+    }
+    _size() {
+        if (this._fixed)
+            return this._fixed;
+        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)) };
+    }
+    _settings(sampleCap = this.maxSamples) {
+        return collectTraceSettings(this, sampleCap);
+    }
+    _synchronize(sampleCap = this.maxSamples, offline = false) {
+        this._validate();
+        if (this._lastScale !== this._resolutionScale) {
+            this._adaptiveScale = this._resolutionScale;
+            this._lastScale = this._resolutionScale;
+        }
+        const target = this._target ??= this._engine._createTarget();
+        if (!target)
+            return;
+        const settings = this._settings(sampleCap), size = this._size();
+        const key = imageSettingsKey(settings, size);
+        const inputs = this._engine._inputs;
+        target.configure(settings);
+        target.activate();
+        if ((!offline && this._offlineCamera) || inputs.scene !== this._input.scene || inputs.camera !== this._input.camera || key !== this._input.settings) {
+            if (!offline)
+                this._offlineCamera = false;
+            this._cancelDenoise();
+            target.restartSamples();
+            target.setSize(size.width, size.height);
+            this._input = { scene: inputs.scene, camera: inputs.camera, settings: key };
+        }
+        target.setOnSampleRendered((samples, isFirstFrame, frameTimeMs) => { this._frameTime = frameTimeMs; this._events.emit('sample', { samples, isFirstFrame, frameTimeMs }); });
+        return target;
+    }
+    /** Accumulates within this frame's budget. Rejects calls during converge or after disposal. */
+    refine() {
+        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();
+        try {
+            return this._refine();
+        }
+        catch (error) {
+            this._engine._setRenderError(this._engine._notifyError(error));
+            return this._status = 'error';
+        }
+        finally {
+            this._engine._reportShaderProgress();
+        }
+    }
+    _refine() {
+        if (this._engine._initializationError)
+            throw this._engine._initializationError;
+        this._reloadDenoiser();
+        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 target = this._synchronize();
+        if (!target)
+            return this._status = 'preparing';
+        if (this._fallback && this.samples === 0 && !target.canCompleteSampleWithin(this.timeBudgetMs) && !this._fallback._complete)
+            this._fallback._refineOne();
+        target.activate();
+        if (this._denoisePending)
+            return this._status = this.converged ? 'denoising' : 'converging';
+        target.setPreserveDenoisedOutput?.(!!this._filter && this._schedule() === 'progressive');
+        const limit = this._nextSampleTarget();
+        if (this.samples < limit) {
+            if (target.trace(this._engine._inputs.value, limit))
+                return this._status = 'compiling';
+        }
+        this._maybeDenoise(false, limit);
+        if (this._denoisePending)
+            return this._status = this.converged ? 'denoising' : 'converging';
+        if (this._filterPending && this.converged)
+            return this._status = 'preparing';
+        if (this.adaptiveResolution && this._frameTime > 0 && this.samples > 0)
+            this._adaptiveScale = nextPreviewScale(this._adaptiveScale, this._frameTime, this.adaptiveResolution.targetFrameMs, this._resolutionScale, this.adaptiveResolution.minScale);
+        return this._status = this.converged ? 'finished' : 'converging';
+    }
+    _refineOne() {
+        if (this._busy || this._disposed || !this._engine._ready)
+            return;
+        this._reloadDenoiser();
+        const target = this._synchronize();
+        if (!target)
+            return;
+        target.activate();
+        if (this.samples < 1)
+            this._status = target.trace(this._engine._inputs.value, 1) ? 'compiling' : 'converging';
+        this._maybeDenoise();
+    }
+    _schedule() { return this._denoiserOptions?.schedule ?? 'converged'; }
+    _nextSampleTarget() {
+        if (!this._filter)
+            return this.maxSamples;
+        if (this._schedule() === 'every-sample')
+            return Math.min(this.maxSamples, this.samples + 1);
+        if (this._schedule() === 'converged')
+            return this.maxSamples;
+        if (this._denoisedSamples === 0)
+            return 1;
+        if (performance.now() - this._lastDenoiseTime >= 10000)
+            return Math.min(this.maxSamples, this.samples + 1);
+        return Math.min(this.maxSamples, Math.max(4, this._denoisedSamples * 2));
+    }
+    /** Reloads a filter dropped by device recovery; failures report through engine errors. */
+    _reloadDenoiser() { void this._refreshDenoiser()?.catch(error => this._engine._notifyError(error)); }
+    /** Starts loading the configured filter; returns its readiness when a new configuration was applied. */
+    _refreshDenoiser() {
+        if (this._disposed)
+            return;
+        const options = this._denoiserOptions;
+        const key = options ? denoiserKey(options) : '';
+        if (key === this._filterKey)
+            return;
+        this._filterKey = key;
+        const revision = ++this._filterRevision;
+        this._cancelDenoise();
+        if (this._filter && this._filter.kind !== 'custom')
+            this._engine._releaseDenoiser(this._filter);
+        this._target?.invalidateDenoisedOutput();
+        this._filter = undefined;
+        this._filterPending = undefined;
+        if (!options)
+            return this._denoiserReady = Promise.resolve();
+        if (options.type === 'jnlm') {
+            this._filter = this._engine._retainDenoiser(`jnlm:${key}`, () => ({ kind: 'jnlm', denoiser: createJNLMDenoiser(options) }));
+            return this._denoiserReady = Promise.resolve();
+        }
+        const task = (async () => {
+            await this._engine.init();
+            if (this._engine.backend !== 'webgpu') {
+                if (revision === this._filterRevision && !this._warnedWebGPUFilter) {
+                    this._warnedWebGPUFilter = true;
+                    console.warn('This denoiser requires WebGPU; denoising is disabled for this render.');
+                }
+                return;
+            }
+            if (revision !== this._filterRevision || this._disposed)
+                return;
+            if (options.type === 'custom') {
+                this._filter = { kind: 'custom', denoiser: options.denoiser };
+                return;
+            }
+            const { loadOIDNNetwork } = await loadOIDN();
+            const filter = await this._engine._acquireDenoiser(key, async () => ({ kind: 'oidn', denoiser: await loadOIDNNetwork(this._engine, options) }));
+            if (revision !== this._filterRevision || this._disposed) {
+                this._engine._releaseDenoiser(filter);
+                return;
+            }
+            this._filter = filter;
+            this._warmDenoiser();
+        })();
+        this._filterPending = task;
+        // Superseded or disposed loads resolve instead of reporting obsolete failures.
+        return this._denoiserReady = task.catch(error => { if (revision === this._filterRevision && !this._disposed)
+            throw error; })
+            .finally(() => { if (this._filterPending === task)
+            this._filterPending = undefined; });
+    }
+    _warmDenoiser() {
+        const filter = this._filter, revision = this._filterRevision;
+        if (!filter || filter.kind !== 'oidn')
+            return;
+        const network = filter.denoiser;
+        const filters = [network, network.auxiliaryDenoisers?.albedo, network.auxiliaryDenoisers?.normal];
+        const width = this.width, height = this.height;
+        const task = this._engine._enqueueDenoise(async () => {
+            if (revision !== this._filterRevision || filter !== this._filter || this._disposed)
+                return;
+            await Promise.all(filters.map(network => network?.prepareForImage?.(width, height, { tileOverlap: this._schedule() === 'converged' ? undefined : 80 })));
+        });
+        void task.catch(error => {
+            if (revision === this._filterRevision && filter === this._filter && !this._disposed)
+                this._engine._notifyError(error);
+        });
+    }
+    _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)
+        this._target?.invalidateTiming?.(); }
+    /** @internal */ _deviceLost(recovering) {
+        this._cancelDenoise();
+        this._filterRevision++;
+        this._filter = undefined;
+        this._filterPending = undefined;
+        this._filterKey = '';
+        this._target = undefined;
+        this._input = { scene: -1, camera: -1, settings: '' };
+        this._status = recovering ? 'preparing' : 'error';
+    }
+    /** @internal */ _displayChanged() { 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)
+            return;
+        if (!force && this._schedule() === 'converged' && !this.converged)
+            return;
+        if (!force && this._schedule() === 'progressive' && this.samples < sampleTarget)
+            return;
+        this._engine.display._configure(this);
+        target.activate();
+        target.drawPostProcess();
+        const revision = ++this._denoiseRevision, samples = this.samples;
+        const controller = this._denoiseController = new AbortController();
+        // One shared scratch lease across all renders; queued stale jobs do no GPU work.
+        const task = this._engine._enqueueDenoise(async () => {
+            if (revision !== this._denoiseRevision || this._disposed)
+                return;
+            target.activate();
+            this._engine.display._configure(this);
+            if (revision !== this._denoiseRevision || this._disposed)
+                return;
+            target.drawPostProcess();
+            if (filter.kind === 'custom') {
+                await this._engine._prepareCustomDenoiser(filter.denoiser, this.width, this.height);
+                if (controller.signal.aborted || revision !== this._denoiseRevision || this._disposed)
+                    return;
+            }
+            const complete = await target.performDenoise?.(filter, undefined, this._schedule(), controller.signal);
+            if (revision !== this._denoiseRevision || this._disposed)
+                return;
+            if (complete) {
+                target.activate();
+                target.drawPostProcess();
+                this._denoisedSamples = samples;
+                this._lastDenoiseTime = performance.now();
+            }
+        });
+        this._denoisePending = task;
+        void task.catch(error => { if (revision === this._denoiseRevision && !this._disposed)
+            this._engine._notifyError(error); }).finally(() => { if (this._denoisePending === task) {
+            this._denoiseController = undefined;
+            this._denoisePending = undefined;
+            this._status = this.converged ? 'finished' : 'converging';
+        } });
+    }
+    /** 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)
+            return { width: 0, height: 0, data: new Float32Array(0) };
+        if (kind === 'denoised' && this._denoisedSamples === 0) {
+            if (!this._warnedDenoisedReadback) {
+                this._warnedDenoisedReadback = true;
+                console.warn('Denoised output is not ready; reading HDR samples instead.');
+            }
+            kind = 'hdr';
+        }
+        target.activate();
+        return 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')
+            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._target?.restartSamples(); this._status = 'converging'; }
+    /** Releases only this render's image resources and denoiser. */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._events.clear();
+        this._filterRevision++;
+        this._cancelDenoise();
+        if (this._target)
+            this._engine._releaseTarget(this._target);
+        if (this._filter && this._filter.kind !== 'custom')
+            this._engine._releaseDenoiser(this._filter);
+        this._target = undefined;
+        this._filter = undefined;
+        this._engine._unregister(this);
+        this._fallback?._dependents.delete(this);
+        for (const dependent of this._dependents)
+            dependent._fallback = null;
+        this._dependents.clear();
+    }
+    /** Deterministically renders this image. Rejects on abort/timeout/input revision changes and blocks refine on this render. */
+    async converge(options) {
+        if (this._busy)
+            throw new Error('Converge is already running on this render.');
+        if (this._disposed)
+            throw new Error('Render is disposed.');
+        const inputs = this._engine._inputs;
+        const deviceGeneration = this._engine._deviceGeneration;
+        if (!inputs.value)
+            throw new Error('Commit engine.scene and engine.camera with engine.update() before converge.');
+        const camera = cameraSnapshot(options.camera ?? inputs.value);
+        const samples = Math.max(1, Math.round(options.samples));
+        if (!Number.isFinite(samples))
+            throw new Error('samples must be finite and positive.');
+        const batchLimit = Math.max(1, Math.round(options.samplesPerBatch ?? 8));
+        const sequenceOffset = Math.max(0, Math.round(options.sampleSequenceOffset ?? 0));
+        const timeout = Math.max(1, options.timeoutMs ?? 600000);
+        const check = () => {
+            if (this._disposed)
+                throw new Error('Render is disposed.');
+            if (this._engine._deviceGeneration !== deviceGeneration)
+                throw this._engine._lostError;
+            if (options.signal?.aborted)
+                throw options.signal.reason ?? new DOMException('Convergence aborted', 'AbortError');
+            const current = this._engine._inputs;
+            if (current.scene !== inputs.scene || current.camera !== inputs.camera)
+                throw new Error('Engine inputs changed during converge.');
+        };
+        this._busy = true;
+        const abortConverge = () => this._cancelDenoise();
+        options.signal?.addEventListener('abort', abortConverge, { once: true });
+        let target;
+        const start = performance.now();
+        try {
+            await this._engine._awaitDevice(this._engine.init());
+            check();
+            while (!this._engine._ready) {
+                check();
+                if (performance.now() - start > timeout)
+                    throw new Error('Timed out preparing convergence.');
+                await new Promise(resolve => setTimeout(resolve, 0));
+            }
+            target = this._synchronize(samples, true);
+            this._offlineCamera = !!options.camera;
+            if (!target)
+                throw new Error('The render target is not ready.');
+            this._cancelDenoise();
+            target.restartSamples();
+            this._reloadDenoiser();
+            await this._engine._awaitDevice(Promise.resolve(this._filterPending));
+            check();
+            const stage = async (cap, name, offset) => {
+                check();
+                this._cancelDenoise();
+                target.activate();
+                target.restartSamples();
+                target.configure({ ...this._settings(cap), allowMultipleSamplesPerFrame: true });
+                let batch = options.targetBatchTimeMs && this._engine.device ? 1 : Math.min(batchLimit, cap);
+                let previous = -1, lastPreview = performance.now();
+                const started = performance.now();
+                for (;;) {
+                    check();
+                    if (performance.now() - started > timeout)
+                        throw new Error(`Timed out rendering the offline ${name} pass.`);
+                    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';
+                    const count = target.getTotalSamplesRendered();
+                    if (count !== previous) {
+                        previous = count;
+                        options.onProgress?.({ stage: name, samples: Math.min(count, cap), targetSamples: cap });
+                        if (name === 'final' && options.previewIntervalMs !== undefined && count > 0 && count < cap && performance.now() - lastPreview >= options.previewIntervalMs) {
+                            target.drawPostProcess();
+                            lastPreview = performance.now();
+                        }
+                    }
+                    if (count >= cap)
+                        break;
+                    if (count > before && this._engine.device)
+                        await this._engine._awaitDevice(this._engine.device.queue.onSubmittedWorkDone());
+                    else
+                        await new Promise(resolve => setTimeout(resolve, 0));
+                    if (options.targetBatchTimeMs && this._engine.device && count > before) {
+                        const desired = Math.max(1, Math.min(batchLimit, Math.round(options.targetBatchTimeMs * (count - before) / Math.max(1, performance.now() - batchStarted))));
+                        batch = desired > batch ? Math.min(desired, batch * 2) : desired;
+                    }
+                }
+                await this._engine._awaitDevice(Promise.resolve(this._engine.device?.queue.onSubmittedWorkDone()));
+                check();
+            };
+            let result = { samples, averageSamplesPerPixel: samples, pilotSamples: 0, adaptiveSampling: false };
+            if (options.adaptiveSampling && this._engine.device) {
+                const pilotSamples = Math.min(samples, Math.max(2, Math.round(options.adaptiveSampling.pilotSamples ?? 8)));
+                target.activate();
+                target.setVarianceMoments(true);
+                target.setAdaptiveSamplingTargets(undefined);
+                await stage(pilotSamples, 'pilot', sequenceOffset);
+                target.activate();
+                const plan = await this._engine._awaitDevice(target.prepareOfflineAdaptiveSampling({ ...options.adaptiveSampling, maxSamples: samples }));
+                if (plan) {
+                    target.activate();
+                    target.setVarianceMoments(false);
+                    await stage(plan.maximumTarget, 'final', sequenceOffset + pilotSamples);
+                    result = { samples: plan.maximumTarget, averageSamplesPerPixel: plan.averageTarget, pilotSamples, varianceHistory: plan.history, adaptiveSampling: true };
+                }
+                else {
+                    target.setVarianceMoments(false);
+                    target.setAdaptiveSamplingTargets(undefined);
+                    await stage(samples, 'final', sequenceOffset);
+                }
+            }
+            else {
+                target.activate();
+                target.setVarianceMoments(false);
+                target.setAdaptiveSamplingTargets(undefined);
+                await stage(samples, 'final', sequenceOffset);
+            }
+            if (this._filter) {
+                options.onProgress?.({ stage: 'denoising', samples: result.samples, targetSamples: result.samples });
+                this._status = 'denoising';
+                this._maybeDenoise(true);
+                await this._engine._awaitDevice(Promise.resolve(this._denoisePending));
+                check();
+            }
+            this._status = 'finished';
+            return result;
+        }
+        catch (error) {
+            if (this._engine._deviceGeneration === deviceGeneration)
+                this._status = 'error';
+            throw error;
+        }
+        finally {
+            if (target && !this._disposed && this._engine._deviceGeneration === deviceGeneration) {
+                target.activate();
+                target.setVarianceMoments(false);
+                target.setAdaptiveSamplingTargets(undefined);
+                target.setOfflineRenderOptions({ samplesPerBatch: 0, deferPostProcess: false, sampleSequenceOffset: 0 });
+            }
+            options.signal?.removeEventListener('abort', abortConverge);
+            this._busy = false;
+        }
+    }
+}
+//# sourceMappingURL=Render.js.map