@meimu/mutracer 0.0.0-stage → 0.1.0

package/lib/Engine.js

@@ -0,0 +1,681 @@
+import { bvhConfig, engineSettingsKey, workerCount, textureBudget } from './settings/engine.js';
+import { createCanvas } from './util/canvas.js';
+import { getRecommendedDeviceDescriptor, validateDevice } from './renderer/deviceRequirements.js';
+import { cameraSnapshot } from './renderer/cameraSnapshot.js';
+import Display from './Display.js';
+import { Events } from './util/events.js';
+import { SceneChangeDetector, snapshotFields, snapshotsEqual } from './renderer/sceneChangeDetector.js';
+import { CommittedScene } from './renderer/committedScene.js';
+import { validateSceneLights } from './renderer/lightsUtil.js';
+import { ensureMeshGeometryAttributes, meshNeedsStaticBvh, getPreparedMeshGeometry } from './renderer/prepareMeshBVH.js';
+import { getGeometryBvh } from './renderer/geometryBvh.js';
+import { prepareStaticBvhs } from './renderer/staticBvhPreparation.js';
+import { canUseBvhWorker, BvhWorkerPool, resolveBvhWorkerCount } from './renderer/bvhWorkerClient.js';
+import { DEFAULT_MAX_TEXTURE_ARRAY_BYTES } from './renderer/MaterialTable.js';
+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();
+            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;
+        })();
+        globalGPURequest = request;
+        void request.finally(() => { if (globalGPURequest === request)
+            globalGPURequest = undefined; }).catch(() => { });
+    }
+    return globalGPURequest;
+}
+/** Shared device, committed scene/camera, CPU preparation and denoiser ownership. */
+export default class Engine {
+    /** Source scene, accepted only by update(). Default undefined. */ scene;
+    /** Source camera, accepted only by update(). Default undefined. */ camera;
+    /** Default canvas and display settings. */ display;
+    /** Static BLAS builder. Default builtin. */ bvhBuilder = 'builtin';
+    /** Static BLAS layout. Default bvh2; dynamic geometry uses bvh2. */ bvhLayout = 'bvh2';
+    /** Enable TinyBVH spatial splits. Default false. */ bvhSpatialSplits = false;
+    /** Material texture budget in bytes. Default 384 MiB. */ textureAtlasBudgetBytes = DEFAULT_MAX_TEXTURE_ARRAY_BYTES;
+    /** Maximum CPU BVH workers. Default auto (hardware concurrency minus one, clamped 1–4). */
+    get bvhWorkerCount() { return this._bvhWorkerCount; }
+    set bvhWorkerCount(count) { resolveBvhWorkerCount(count); this._bvhWorkerCount = count; }
+    _bvhWorkerCount = 'auto';
+    _bvhWorkerPool;
+    _bvhPreparationRevision = 0;
+    _bvhPreparation;
+    _bvhPreparationTail = Promise.resolve();
+    _tinyBvhUnavailable = false;
+    _bvhWorkerUnavailable = false;
+    _bvhPreparedGeometry = new WeakMap();
+    _lastBvhBuild;
+    _lastBvhSettings = '';
+    _lastBudget = -1;
+    _shaderProgress = '';
+    _events = new Events();
+    _pipeline;
+    _webglRenderer;
+    _gpuDevice;
+    _suppliedDevice;
+    _ownsDeviceSelection;
+    _deviceRevision = 0;
+    _lossController;
+    _deviceLossError;
+    _webglListening = false;
+    _webglLost = false;
+    _recoverWebGL = false;
+    _contextRestore;
+    _gpuAdapterInfo;
+    _backendChoice;
+    _initPromise;
+    _info;
+    _pipelineInitError;
+    _webgpuFallbackReason;
+    _reportedErrors = new WeakSet();
+    _loggedErrorMessages = new Set();
+    _sceneChangeDetector;
+    _snapshot = new CommittedScene();
+    _sourceScene;
+    _committedScene;
+    _sourceCamera;
+    _committedCamera;
+    _cameraFields = [];
+    _sceneRevision = 0;
+    _cameraRevision = 0;
+    _uploadedRevision = -1;
+    _pendingMeshes = 'full';
+    _pendingTransforms = new Set();
+    _pendingColors = new Set();
+    _pendingGeometries = new Set();
+    _pendingMaterials = new Set();
+    _pendingLights = true;
+    _pendingBackground = true;
+    _disposed = false;
+    _readingDepth = false;
+    _renders = new Set();
+    _targetCounter = 0;
+    _presented;
+    _denoisers = new Set();
+    _denoiserCache = new Map();
+    _denoiserEntries = new WeakMap();
+    _weights = new Map();
+    _customPrepared = new WeakMap();
+    _denoiseTail = Promise.resolve();
+    _lastError;
+    /** Most recent synchronous engine/render failure. Default undefined. */
+    get lastError() { return this._lastError; }
+    /** @internal */ _setRenderError(error) { this._lastError = error ?? this._pipelineInitError; }
+    constructor(params = {}) {
+        if (params.device && params.backend === 'webgl')
+            throw new Error('A supplied GPUDevice cannot use the webgl backend.');
+        this._suppliedDevice = params.device;
+        this._ownsDeviceSelection = !params.device;
+        this._backendChoice = params.device ? 'webgpu' : params.backend ?? 'auto';
+        this._sceneChangeDetector = new SceneChangeDetector();
+        this.display = Display._create(this, params.canvas ?? createCanvas());
+    }
+    /** Initializes once; concurrent/repeated calls share the result. */
+    init() {
+        return this._initPromise ??= (async () => {
+            if (this._disposed)
+                throw new Error('Engine is disposed.');
+            if (this._pipelineInitError && !this._ownsDeviceSelection)
+                throw this._pipelineInitError;
+            const revision = this._deviceRevision;
+            if (this._contextRestore)
+                await this._contextRestore.promise;
+            if (this._disposed)
+                throw new Error('Engine is disposed.');
+            await this._initPipeline(this._backendChoice !== 'webgl' && !this._recoverWebGL);
+            if (revision !== this._deviceRevision)
+                throw this._deviceLossError;
+            if (this._pipelineInitError)
+                throw this._pipelineInitError;
+            if (this._disposed) {
+                this._pipeline?.dispose();
+                throw new Error('Engine is disposed.');
+            }
+            const gl = this._webglRenderer?.gl, limits = this._gpuDevice?.limits;
+            this._info = { backend: this._gpuDevice ? 'webgpu' : 'webgl', adapterName: this._adapterName(), webgpuFallbackReason: this._webgpuFallbackReason,
+                limits: { maxTextureArrayLayers: limits?.maxTextureArrayLayers ?? gl?.getParameter(gl.MAX_ARRAY_TEXTURE_LAYERS), maxTextureDimension2D: limits?.maxTextureDimension2D ?? gl?.getParameter(gl.MAX_TEXTURE_SIZE) } };
+            this._upload();
+            return this._info;
+        })();
+    }
+    /** Initialization info. Default undefined until init resolves. */ get info() { return this._info; }
+    /** Active backend. Default undefined until initialization completes. */ get backend() { return this._info?.backend; }
+    /** GPU device. Default undefined before initialization and on WebGL. */ get device() { return this._gpuDevice; }
+    /** Subscribes to shared progress/errors/device loss; returns unsubscribe. */
+    on(event, listener) { return this._events.on(event, listener); }
+    /** The sole external edit detection/commit point. Returns whether inputs changed. */
+    update() {
+        if (this._disposed)
+            throw new Error('Engine is disposed.');
+        this._lastError = this._pipelineInitError;
+        let changed = false, resetTiming = false;
+        const cameraFields = this.camera ? snapshotFields(this.camera) : [];
+        if (this.camera !== this._sourceCamera || !snapshotsEqual(cameraFields, this._cameraFields)) {
+            this._sourceCamera = this.camera;
+            this._cameraFields = cameraFields;
+            this._committedCamera = this.camera ? cameraSnapshot(this.camera) : undefined;
+            this._cameraRevision++;
+            changed = true;
+        }
+        const bvhSettings = engineSettingsKey(this, 'bvh');
+        const force = bvhSettings !== this._lastBvhSettings || textureBudget(this) !== this._lastBudget;
+        if (this.scene !== this._sourceScene || force)
+            this._sceneChangeDetector.reset();
+        if (this.scene) {
+            validateSceneLights(this.scene.lights, error => this._notifyError(error));
+            ensureMeshGeometryAttributes(this.scene.meshes);
+            const changes = this._sceneChangeDetector.detect(this.scene);
+            resetTiming = changes.meshes === 'full' || this.scene !== this._sourceScene || force;
+            if (changes.meshes !== 'none' || changes.lights || changes.background || this.scene !== this._sourceScene || force) {
+                this._committedScene = this._snapshot.capture(this.scene, changes);
+                if (changes.meshes === 'full' || force || this.scene !== this._sourceScene)
+                    this._pendingMeshes = 'full';
+                else if (changes.meshes === 'incremental' && this._pendingMeshes !== 'full')
+                    this._pendingMeshes = 'incremental';
+                for (const mesh of changes.transforms)
+                    this._pendingTransforms.add(this._snapshot.mirror(mesh));
+                for (const mesh of changes.colors)
+                    this._pendingColors.add(this._snapshot.mirror(mesh));
+                for (const geometry of changes.geometries)
+                    this._pendingGeometries.add(this._snapshot.mirror(geometry));
+                for (const material of changes.materials)
+                    this._pendingMaterials.add(this._snapshot.mirror(material));
+                this._pendingLights ||= changes.lights;
+                this._pendingBackground ||= changes.background;
+                this._sceneRevision++;
+                changed = true;
+            }
+            this._sceneChangeDetector.commit();
+        }
+        else if (this._sourceScene) {
+            this._committedScene = undefined;
+            this._pendingMeshes = 'full';
+            this._pendingLights = true;
+            this._pendingBackground = true;
+            this._sceneRevision++;
+            changed = true;
+        }
+        this._sourceScene = this.scene;
+        this._lastBvhSettings = bvhSettings;
+        this._lastBudget = textureBudget(this);
+        if (!this._pipeline)
+            void this.init().catch(() => { });
+        if (changed)
+            for (const render of this._renders)
+                render._inputsChanged(resetTiming);
+        this._upload();
+        return changed;
+    }
+    _upload() {
+        const pipeline = this._pipeline;
+        if (!pipeline || this._disposed || this._bvhPreparation || this._uploadedRevision === this._sceneRevision)
+            return;
+        const scene = this._committedScene ?? { meshes: [], lights: [] };
+        if (this._needsBVHPreparation(scene.meshes)) {
+            const task = this.prepare(scene);
+            this._bvhPreparation = task;
+            void task.then(() => { if (this._bvhPreparation === task)
+                this._bvhPreparation = undefined; this._upload(); }, error => { if (this._bvhPreparation === task)
+                this._bvhPreparation = undefined; this._notifyError(error); });
+            return;
+        }
+        const budgetChanged = pipeline.setTextureAtlasBudget(this._lastBudget >= 0 ? this._lastBudget : textureBudget(this));
+        if (this._pendingMeshes !== 'none' || budgetChanged)
+            pipeline.setMeshes(scene.meshes, this._pendingMeshes === 'full' || budgetChanged ? undefined : {
+                transforms: [...this._pendingTransforms], colors: [...this._pendingColors], geometries: [...this._pendingGeometries], materials: [...this._pendingMaterials]
+            });
+        if (this._pendingLights)
+            pipeline.setLights(scene.lights);
+        if (this._pendingBackground)
+            pipeline.setBackground(scene.background);
+        this._pendingMeshes = 'none';
+        this._pendingLights = false;
+        this._pendingBackground = false;
+        this._pendingTransforms.clear();
+        this._pendingColors.clear();
+        this._pendingGeometries.clear();
+        this._pendingMaterials.clear();
+        this._uploadedRevision = this._sceneRevision;
+    }
+    _bvhConfig() { return bvhConfig(this); }
+    /** Builds static CPU BVHs for this scene without replacing GPU inputs. Options default undefined. */
+    prepare(scene, options = {}) {
+        const revision = this._bvhPreparationRevision;
+        const preparation = this._bvhPreparationTail.then(async () => {
+            const isCancelled = () => revision !== this._bvhPreparationRevision || options.signal?.aborted === true;
+            if (isCancelled())
+                return;
+            const meshes = scene.meshes;
+            const useWorker = canUseBvhWorker() && !this._bvhWorkerUnavailable;
+            if (useWorker) {
+                const count = workerCount(this);
+                if (this._bvhWorkerPool?.size !== count) {
+                    this._bvhWorkerPool?.dispose();
+                    this._bvhWorkerPool = new BvhWorkerPool(count);
+                }
+            }
+            const config = this._bvhConfig();
+            const result = await prepareStaticBvhs(meshes, {
+                config,
+                ...config,
+                builder: this.bvhBuilder === 'tinybvh' && !this._tinyBvhUnavailable ? 'tinybvh' : 'builtin',
+                useWorker, workerPool: this._bvhWorkerPool, isCancelled,
+                rebuild: false, onProgress: progress => {
+                    if (this._bvhPreparation === preparation)
+                        this._events.emit('progress', { stage: 'bvh', progress });
+                    options.onProgress?.(progress);
+                }
+            });
+            if (isCancelled())
+                return;
+            if (result.workerUnavailable && !this._bvhWorkerUnavailable) {
+                this._bvhWorkerUnavailable = true;
+                this._bvhWorkerPool?.dispose();
+                this._bvhWorkerPool = undefined;
+                console.warn('BVH preparation failed; falling back to the calling-thread BVH builder.');
+            }
+            if (result.tinyBvhUnavailable && !this._tinyBvhUnavailable) {
+                this._tinyBvhUnavailable = true;
+                console.warn('BVH preparation failed; falling back to the built-in BVH builder.');
+            }
+            result.failedMeshes.forEach(mesh => {
+                this._bvhPreparedGeometry.set(mesh, [mesh.geometry, mesh.geometry.version]);
+            });
+            this._lastBvhBuild = { geometryCount: result.geometryCount, bvhTimeMs: result.bvhTimeMs };
+        });
+        this._bvhPreparationTail = preparation.catch(() => undefined);
+        const signal = options.signal;
+        if (!signal)
+            return preparation;
+        return new Promise((resolve, reject) => {
+            const aborted = () => reject(signal.reason ?? new DOMException('BVH preparation aborted', 'AbortError'));
+            if (signal.aborted) {
+                aborted();
+                return;
+            }
+            signal.addEventListener('abort', aborted, { once: true });
+            preparation.then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted));
+        });
+    }
+    _needsBVHPreparation(meshes) {
+        if (this._bvhPreparation)
+            return true;
+        if ((this.bvhBuilder !== 'tinybvh' || this._tinyBvhUnavailable) &&
+            (!canUseBvhWorker() || this._bvhWorkerUnavailable)) {
+            return meshes.some(mesh => !!getGeometryBvh(getPreparedMeshGeometry(mesh)) && meshNeedsStaticBvh(mesh, this._bvhConfig()));
+        }
+        return meshes.some((mesh) => {
+            const prepared = this._bvhPreparedGeometry.get(mesh);
+            const attempted = prepared?.[0] === mesh.geometry &&
+                prepared[1] === mesh.geometry.version;
+            return !attempted && meshNeedsStaticBvh(mesh, this._bvhConfig());
+        });
+    }
+    async _initPipeline(preferWebGPU) {
+        let gpuCreated = false;
+        try {
+            this._events.emit('progress', { stage: 'device', progress: 0 });
+            this._pipelineInitError = undefined;
+            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 gpuAdapterInfo = this._suppliedDevice
+                        ? gpuDevice.adapterInfo : globalGPUAdapterInfo;
+                    if (this._disposed)
+                        return;
+                    validateDevice(gpuDevice);
+                    this._gpuAdapterInfo = gpuAdapterInfo ?? undefined;
+                    this._gpuDevice = gpuDevice;
+                    this._pipeline = makeWGPURenderTargets(this.display.canvas, gpuDevice, {
+                        presentationFormat: gpu?.getPreferredCanvasFormat() ?? 'bgra8unorm'
+                    });
+                    this._watchDevice(gpuDevice);
+                    gpuCreated = true;
+                }
+                catch (e) {
+                    if (this._backendChoice === 'webgpu')
+                        throw e;
+                    this._webgpuFallbackReason = e instanceof Error ? e.message : String(e);
+                    this._gpuDevice = undefined;
+                    this._gpuAdapterInfo = undefined;
+                }
+            }
+            if (!gpuCreated) {
+                if (this._backendChoice === 'webgpu')
+                    throw new Error('WebGPU is not available in this environment');
+                if (preferWebGPU && !this._webgpuFallbackReason) {
+                    this._webgpuFallbackReason = 'WebGPU is not available in this environment';
+                }
+                this._webglRenderer = new WebGLRenderer({
+                    canvas: this.display.canvas,
+                    alpha: true,
+                    depth: true,
+                    stencil: false,
+                    antialias: false,
+                    pixelRatio: 1,
+                    preserveDrawingBuffer: true,
+                    // PENDING
+                    premultipliedAlpha: false,
+                    parallelShaderCompile: true,
+                    powerPreference: 'high-performance'
+                });
+                this._pipeline = makeWebGLRenderTargets(this._webglRenderer);
+                if (!this._webglListening) {
+                    this._webglListening = true;
+                    this.display.canvas.addEventListener('webglcontextlost', this._onContextLost);
+                    this.display.canvas.addEventListener('webglcontextrestored', this._onContextRestored);
+                }
+                this._recoverWebGL = false;
+            }
+        }
+        catch (error) {
+            this._pipelineInitError = error instanceof Error ? error : new Error(String(error));
+            this._lastError = this._pipelineInitError;
+            this._notifyError(this._pipelineInitError);
+        }
+        finally {
+            this._events.emit('progress', { stage: 'device', progress: 1 });
+        }
+    }
+    _onContextLost = (event) => {
+        event.preventDefault();
+        if (this._disposed || this._webglLost)
+            return;
+        this._webglLost = true;
+        this._recoverWebGL = true;
+        let resolve, reject;
+        const promise = new Promise((done, fail) => { resolve = done; reject = fail; });
+        void promise.catch(() => { });
+        this._contextRestore = { promise, resolve, reject };
+        const error = new Error(`WebGL context lost: ${event.statusMessage || 'context is unavailable'}`);
+        this._invalidateDevice(error, true);
+        this._events.emit('devicelost', { reason: 'webglcontextlost', recovering: true });
+    };
+    _onContextRestored = () => {
+        if (this._disposed || !this._webglLost)
+            return;
+        this._webglLost = false;
+        const restore = this._contextRestore;
+        this._contextRestore = undefined;
+        restore?.resolve();
+    };
+    _watchDevice(device) {
+        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);
+            this._events.emit('devicelost', { reason: info.reason, recovering });
+            if (!recovering)
+                this._notifyError(error);
+        });
+    }
+    _invalidateDevice(error, recovering) {
+        this._deviceLossError = error;
+        this._deviceRevision++;
+        this._lossController?.abort(error);
+        this._lossController = undefined;
+        for (const render of this._renders)
+            render._deviceLost(recovering);
+        this._pipeline?.dispose();
+        this._pipeline = undefined;
+        this._webglRenderer?.dispose();
+        this._webglRenderer = undefined;
+        this._gpuDevice = undefined;
+        this._gpuAdapterInfo = undefined;
+        this._info = undefined;
+        this._initPromise = undefined;
+        this._pipelineInitError = recovering ? undefined : error;
+        this._lastError = error;
+        this._presented = undefined;
+        this._shaderProgress = '';
+        this._uploadedRevision = -1;
+        this._pendingMeshes = 'full';
+        this._pendingLights = true;
+        this._pendingBackground = true;
+        this._sceneRevision++;
+        this._customPrepared = new WeakMap();
+        for (const filter of [...this._denoisers]) {
+            const entry = this._denoiserEntries.get(filter);
+            if (entry)
+                entry.references = 1;
+            this._releaseDenoiser(filter);
+        }
+        this._denoiserCache.clear();
+    }
+    /** Replaces a caller-owned device after validation. Only available on engines
+     * constructed with device; the next update/refine uploads the committed scene.
+     */
+    async setDevice(device) {
+        if (this._disposed)
+            throw new Error('Engine is disposed.');
+        if (this._ownsDeviceSelection)
+            throw new Error('setDevice requires an engine constructed with device.');
+        try {
+            validateDevice(device);
+        }
+        catch (error) {
+            this._lastError = this._notifyError(error);
+            throw error;
+        }
+        if (this._gpuDevice === device && !this._pipelineInitError)
+            return;
+        this._invalidateDevice(new Error('WebGPU device replaced during converge.'), true);
+        this._suppliedDevice = device;
+    }
+    /** @internal Device loss rejects pending waits without relying on driver completion. */
+    _awaitDevice(work) {
+        const signal = (this._lossController ??= new AbortController()).signal;
+        return new Promise((resolve, reject) => {
+            const lost = () => reject(signal.reason);
+            signal.addEventListener('abort', lost, { once: true });
+            work.then(resolve, reject).finally(() => signal.removeEventListener('abort', lost));
+        });
+    }
+    /** @internal */ get _deviceGeneration() { return this._deviceRevision; }
+    /** @internal */ get _lostError() { return this._deviceLossError; }
+    _adapterName() {
+        if (this._gpuAdapterInfo)
+            return this._gpuAdapterInfo.description || this._gpuAdapterInfo.vendor || 'WebGPU';
+        const gl = this._webglRenderer?.gl, extension = gl?.getExtension('WEBGL_debug_renderer_info');
+        return extension && gl ? gl.getParameter(extension.UNMASKED_RENDERER_WEBGL) : this._webglRenderer ? 'WebGL 2' : this._gpuDevice ? 'WebGPU' : '';
+    }
+    /** @internal */ _reportShaderProgress() {
+        const compilation = this._pipeline?.getDiagnostics().shaderCompilation;
+        if (!compilation)
+            return;
+        const key = `${compilation.status}/${compilation.completedPipelineCount}/${compilation.pipelineCount}`;
+        if (key === this._shaderProgress)
+            return;
+        this._shaderProgress = key;
+        this._events.emit('progress', { stage: 'shaders', progress: compilation.pipelineCount ? compilation.completedPipelineCount / compilation.pipelineCount : 1 });
+    }
+    /** Current shared preparation and resident target statistics. Default undefined before any work. */
+    getDiagnostics() {
+        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,
+            lastError: this.lastError?.message, webgpuFallbackReason: this._webgpuFallbackReason,
+            presentedTarget: this._presented?.label, presentedComplete: this._presented?.presentationComplete ?? false };
+    }
+    /** Queries a 7×7 depth grid using the committed engine camera. Default undefined until GPU data is ready. */
+    async readDepthSamples(area) {
+        packDepthSampleArea(area, 1);
+        if (!this._ready || !this._committedCamera || this._readingDepth)
+            return;
+        this._readingDepth = true;
+        try {
+            const camera = cameraSnapshot(this._committedCamera);
+            camera.aspect ??= this.display.canvas.width / this.display.canvas.height;
+            const result = await this._pipeline.readDepthSamples(camera, area);
+            return this._disposed ? undefined : result;
+        }
+        finally {
+            this._readingDepth = false;
+        }
+    }
+    /** Releases all renders, shared resources, CPU workers and owned denoisers. */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._bvhPreparationRevision++;
+        this._contextRestore?.reject(new Error('Engine is disposed.'));
+        this._contextRestore = undefined;
+        if (this._webglListening) {
+            this.display.canvas.removeEventListener('webglcontextlost', this._onContextLost);
+            this.display.canvas.removeEventListener('webglcontextrestored', this._onContextRestored);
+        }
+        for (const render of [...this._renders])
+            render.dispose();
+        this._pipeline?.dispose();
+        this._pipeline = undefined;
+        this._webglRenderer?.dispose();
+        this._bvhWorkerPool?.dispose();
+        for (const denoiser of [...this._denoisers]) {
+            const entry = this._denoiserEntries.get(denoiser);
+            if (entry)
+                entry.references = 1;
+            this._releaseDenoiser(denoiser);
+        }
+        this._denoiserCache.clear();
+        this._weights.clear();
+        this._events.clear();
+    }
+    /** @internal */ get _initializationError() { return this._pipelineInitError; }
+    /** @internal */ get _ready() { return !!this._pipeline && this._uploadedRevision === this._sceneRevision && !!this._committedScene && !!this._committedCamera && !this._disposed; }
+    /** @internal */ get _inputs() { return { scene: this._sceneRevision, camera: this._cameraRevision, value: this._committedCamera }; }
+    /** @internal */ _register(render) { if (this._disposed)
+        throw new Error('Engine is disposed.'); this._renders.add(render); }
+    /** @internal */ _unregister(render) { this._renders.delete(render); }
+    /** @internal */ _createTarget() { return this._pipeline?.createTarget(`render-${++this._targetCounter}`); }
+    /** @internal */ _releaseTarget(target) { if (this._presented === target)
+        this._presented = undefined; this._pipeline?.releaseTarget(target); }
+    /** @internal */ _present(target) { target.activate(); target.present(); this._presented = target; }
+    /** @internal */ _notifyError(value) {
+        const error = value instanceof Error ? value : new Error(String(value));
+        if (!this._loggedErrorMessages.has(error.message)) {
+            this._loggedErrorMessages.add(error.message);
+            console.error(`Path tracing failed: ${error.message}`, error);
+        }
+        if (!this._reportedErrors.has(error)) {
+            this._reportedErrors.add(error);
+            this._events.emit('error', error);
+        }
+        return error;
+    }
+    /** @internal */ _getWeights(url, load) {
+        let pending = this._weights.get(url);
+        if (!pending) {
+            pending = load();
+            this._weights.set(url, pending);
+            void pending.catch(() => { if (this._weights.get(url) === pending)
+                this._weights.delete(url); });
+        }
+        return pending;
+    }
+    /** @internal */ _retainDenoiser(key, create) {
+        let entry = this._denoiserCache.get(key);
+        if (!entry?.value) {
+            const value = this._ownDenoiser(create());
+            const next = { key, references: 0, value };
+            this._denoiserCache.set(key, next);
+            this._denoiserEntries.set(value, next);
+            entry = next;
+        }
+        entry.references++;
+        return entry.value;
+    }
+    /** @internal */ async _acquireDenoiser(key, create) {
+        let entry = this._denoiserCache.get(key);
+        if (!entry) {
+            const next = { key, references: 0 };
+            const revision = this._deviceRevision;
+            next.pending = create().then(filter => {
+                if (revision !== this._deviceRevision) {
+                    this._disposeDenoiser(filter);
+                    throw this._deviceLossError;
+                }
+                next.value = this._ownDenoiser(filter);
+                this._denoiserEntries.set(filter, next);
+                return filter;
+            });
+            this._denoiserCache.set(key, next);
+            entry = next;
+        }
+        entry.references++;
+        try {
+            return (entry.value ?? await entry.pending);
+        }
+        catch (error) {
+            entry.references--;
+            if (this._denoiserCache.get(key) === entry)
+                this._denoiserCache.delete(key);
+            throw error;
+        }
+    }
+    /** @internal */ _ownDenoiser(denoiser) {
+        if (this._disposed) {
+            this._disposeDenoiser(denoiser);
+            throw new Error('Engine is disposed.');
+        }
+        this._denoisers.add(denoiser);
+        return denoiser;
+    }
+    /** @internal */ _releaseDenoiser(denoiser) {
+        const entry = this._denoiserEntries.get(denoiser);
+        if (entry && --entry.references > 0)
+            return;
+        if (entry && this._denoiserCache.get(entry.key) === entry)
+            this._denoiserCache.delete(entry.key);
+        this._denoiserEntries.delete(denoiser);
+        if (!this._denoisers.delete(denoiser))
+            return;
+        this._disposeDenoiser(denoiser);
+    }
+    _disposeDenoiser(denoiser) {
+        if (denoiser.kind === 'oidn') {
+            denoiser.denoiser.auxiliaryDenoisers?.albedo.dispose();
+            denoiser.denoiser.auxiliaryDenoisers?.normal.dispose();
+        }
+        denoiser.denoiser.dispose();
+    }
+    /** @internal Called only while holding the shared inference lease. */
+    async _prepareCustomDenoiser(denoiser, width, height) {
+        const device = this.device;
+        if (!device)
+            throw new Error('Custom denoising requires WebGPU.');
+        const previous = this._customPrepared.get(denoiser);
+        if (previous?.device === device && previous.width === width && previous.height === height)
+            return;
+        await denoiser.prepare?.({ device, width, height });
+        this._customPrepared.set(denoiser, { device, width, height });
+    }
+    /** @internal */ _enqueueDenoise(work) {
+        const task = this._denoiseTail.then(work);
+        this._denoiseTail = task.catch(() => { });
+        return task;
+    }
+}
+//# sourceMappingURL=Engine.js.map