@meimu/mutracer 0.0.0-stage → 0.1.1

package/lib/Display.js

@@ -0,0 +1,123 @@
+import { createCanvas } from './util/canvas.js';
+import { displaySettingsKey, applyDisplaySettings } from './settings/display.js';
+/** Canvas presentation and shared display settings; obtained from engine.display. */
+export default class Display {
+    engine;
+    /** Display canvas. Default the supplied Engine canvas, or a new canvas (OffscreenCanvas without document). */ canvas;
+    /** Tone mapping transform. Default agx. */ toneMapping = 'agx';
+    /** Linear exposure multiplier. Default 1. */ toneMappingExposure = 1;
+    /** Contrast multiplier. Default 1. */ contrast = 1;
+    /** Saturation multiplier. Default 1. */ saturation = 1;
+    /** White balance temperature shift in -1–1. Default 0. */ temperature = 0;
+    /** Green/magenta tint in -1–1. Default 0. */ tint = 0;
+    /** Vignette strength in 0–1. Default 0. */ vignette = 0;
+    /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity = 0;
+    /** Bloom luminance threshold. Default 1. */ bloomThreshold = 1;
+    /** Bloom radius in 0–1. Default 0.6. */ bloomRadius = 0.6;
+    /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled = false;
+    /** Display image channel. Default final. */ channel = 'final';
+    /** Linear shadow-catcher color. Default black. */ shadowCatcherColor = [0, 0, 0];
+    /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha = 1;
+    constructor(engine, canvas) {
+        this.engine = engine;
+        this.canvas = canvas;
+    }
+    /** @internal */ static _create(engine, canvas) { return new Display(engine, canvas); }
+    /** Resizes the drawing buffer; scale-based renders resize at their next refine. */
+    setSize(width, height) {
+        if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1)
+            throw new Error('Display dimensions must be positive.');
+        width = Math.round(width);
+        height = Math.round(height);
+        if (this.canvas.width !== width)
+            this.canvas.width = width;
+        if (this.canvas.height !== height)
+            this.canvas.height = height;
+    }
+    settings = new WeakMap();
+    /** @internal */ _configure(render) {
+        if (render._engine !== this.engine)
+            throw new Error('Render belongs to another engine.');
+        const target = render._output;
+        if (!target)
+            return;
+        const key = displaySettingsKey(this);
+        const previous = this.settings.get(render);
+        if (previous !== key) {
+            this.settings.set(render, key);
+            if (previous !== undefined)
+                render._displayChanged();
+        }
+        target.activate();
+        applyDisplaySettings(this, target);
+    }
+    _postProcesses = [];
+    _warnedPostProcess = false;
+    /** Registers a display pass in order and returns an idempotent removal function. Default no passes. WebGPU only; WebGL skips passes with one warning. Runs after composition on every present/toBlob, without tracing or invalidating denoising. A thrown error discards the whole chain, presents the original image and emits engine error. */
+    addPostProcess(pass) {
+        const entry = { pass };
+        this._postProcesses.push(entry);
+        if (this.engine.backend === 'webgl')
+            this.warnPostProcess();
+        return () => { const index = this._postProcesses.indexOf(entry); if (index >= 0)
+            this._postProcesses.splice(index, 1); };
+    }
+    warnPostProcess() {
+        if (!this._warnedPostProcess) {
+            this._warnedPostProcess = true;
+            console.warn('Display post-processing requires WebGPU; passes are ignored on WebGL.');
+        }
+    }
+    compose(render) {
+        if (render._engine !== this.engine)
+            throw new Error('Render belongs to another engine.');
+        const target = render._output;
+        if (!target?.presentationComplete)
+            return;
+        this._configure(render);
+        target.drawPostProcess();
+        if (this._postProcesses.length && this.engine.backend === 'webgl')
+            this.warnPostProcess();
+        try {
+            target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render);
+        }
+        catch (error) {
+            this.engine._notifyError(error);
+        }
+        return target;
+    }
+    /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */
+    present(render) {
+        if (render._engine !== this.engine)
+            throw new Error('Render belongs to another engine.');
+        const ready = this.channel === 'final' && render.fallback ? render._presentable : render._complete;
+        const fallback = render.fallback;
+        const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._complete) ? fallback : undefined;
+        if (!selected)
+            return;
+        const target = this.compose(selected);
+        if (!target)
+            return;
+        this.engine._present(target);
+        return selected;
+    }
+    /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */
+    async toBlob(render, options = {}) {
+        const target = this.compose(render);
+        if (!target)
+            throw new Error('Render has no complete image.');
+        const image = await target.readPresentation();
+        const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);
+        const context = canvas.getContext('2d');
+        if (!context)
+            throw new Error('The image encoding context is not available.');
+        const bytes = new Uint8ClampedArray(image.data.length);
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.round(Math.min(1, Math.max(0, image.data[i])) * 255);
+        context.putImageData(new ImageData(bytes, image.width, image.height), 0, 0);
+        if ('convertToBlob' in canvas)
+            return canvas.convertToBlob({ type: options.type ?? 'image/png', quality: options.quality });
+        return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error('The image could not be encoded')), options.type ?? 'image/png', options.quality));
+    }
+}
+//# sourceMappingURL=Display.js.map

package/lib/Display.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Display.js","sourceRoot":"","sources":["../src/Display.ts"],"names":[],"mappings":"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","sourcesContent":["import {createCanvas} from './util/canvas.js';\nimport type Engine from './Engine.js';\nimport type Render from './Render.js';\nimport type { ToneMapping, DisplayChannel } from './renderer/RenderingPipeline.js';\nimport type { ColorRGB } from './types.js';\nimport { displaySettingsKey, applyDisplaySettings } from './settings/display.js';\n/** Display image channels. Default final. */\nexport type {DisplayChannel} from './renderer/RenderingPipeline.js';\n/** Image encoding options for Display.toBlob. */\nexport interface BlobOptions {\n  /** Browser image MIME type. Default image/png. */ type?: string;\n  /** Encoder quality in 0–1. Default undefined uses the browser default. */ quality?: number;\n}\n/** Optional shared display settings; defaults match Display. */\nexport interface DisplaySettings {\n  /** Tone mapping transform. Default agx. */ toneMapping?: ToneMapping;\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure?: number;\n  /** Contrast multiplier. Default 1. */ contrast?: number;\n  /** Saturation multiplier. Default 1. */ saturation?: number;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature?: number;\n  /** Green/magenta tint in -1–1. Default 0. */ tint?: number;\n  /** Vignette strength in 0–1. Default 0. */ vignette?: number;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity?: number;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold?: number;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius?: number;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled?: boolean;\n  /** Display image channel. Default final. */ channel?: DisplayChannel;\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor?: ColorRGB;\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha?: number;\n}\n/** Borrowed WebGPU images for one synchronous display pass. */\nexport interface PostProcessContext {\n  /** Engine device; may change after recovery. */ device: GPUDevice;\n  /** Record commands here; the library finishes and submits it. */ encoder: GPUCommandEncoder;\n  /** Read-only composed display image, top row first; no additional color conversion. */ input: GPUTexture;\n  /** Fully write this image. Same format and dimensions as input; supports render, storage and copy writes. */ output: GPUTexture;\n  /** Actual render width. */ width: number;\n  /** Actual render height. */ height: number;\n  /** Selected complete render, including a selected fallback. */ render: Render;\n}\n/** Synchronous display pass. Images and encoder are borrowed only during the call; do not retain or destroy them. */\nexport type PostProcess = (context: PostProcessContext) => void;\n/** Canvas presentation and shared display settings; obtained from engine.display. */\nexport default class Display {\n  /** Display canvas. Default the supplied Engine canvas, or a new canvas (OffscreenCanvas without document). */ readonly canvas: HTMLCanvasElement | OffscreenCanvas;\n  /** Tone mapping transform. Default agx. */ toneMapping: ToneMapping = 'agx';\n  /** Linear exposure multiplier. Default 1. */ toneMappingExposure = 1;\n  /** Contrast multiplier. Default 1. */ contrast = 1;\n  /** Saturation multiplier. Default 1. */ saturation = 1;\n  /** White balance temperature shift in -1–1. Default 0. */ temperature = 0;\n  /** Green/magenta tint in -1–1. Default 0. */ tint = 0;\n  /** Vignette strength in 0–1. Default 0. */ vignette = 0;\n  /** Bloom intensity; 0 disables it. Default 0. */ bloomIntensity = 0;\n  /** Bloom luminance threshold. Default 1. */ bloomThreshold = 1;\n  /** Bloom radius in 0–1. Default 0.6. */ bloomRadius = 0.6;\n  /** Extended-range WebGPU presentation, ignored on WebGL. Default false. */ hdrOutputEnabled = false;\n  /** Display image channel. Default final. */ channel: DisplayChannel = 'final';\n  /** Linear shadow-catcher color. Default black. */ shadowCatcherColor: ColorRGB = [0, 0, 0];\n  /** Shadow-catcher opacity multiplier. Default 1. */ shadowCatcherAlpha = 1;\n  private constructor(private readonly engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { this.canvas = canvas; }\n  /** @internal */ static _create(engine: Engine, canvas: HTMLCanvasElement | OffscreenCanvas) { return new Display(engine, canvas); }\n  /** Resizes the drawing buffer; scale-based renders resize at their next refine. */\n  setSize(width: number, height: number) {\n    if (!Number.isFinite(width) || !Number.isFinite(height) || width < 1 || height < 1) throw new Error('Display dimensions must be positive.');\n    width = Math.round(width); height = Math.round(height);\n    if (this.canvas.width !== width) this.canvas.width = width;\n    if (this.canvas.height !== height) this.canvas.height = height;\n  }\n  private readonly settings = new WeakMap<Render, string>();\n  /** @internal */ _configure(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target) return;\n    const key = displaySettingsKey(this);\n    const previous = this.settings.get(render);\n    if (previous !== key) {\n      this.settings.set(render, key);\n      if (previous !== undefined) render._displayChanged();\n    }\n    target.activate();\n    applyDisplaySettings(this, target);\n  }\n  private readonly _postProcesses: {pass: PostProcess}[] = [];\n  private _warnedPostProcess = false;\n  /** Registers a display pass in order and returns an idempotent removal function. Default no passes. WebGPU only; WebGL skips passes with one warning. Runs after composition on every present/toBlob, without tracing or invalidating denoising. A thrown error discards the whole chain, presents the original image and emits engine error. */\n  addPostProcess(pass: PostProcess): () => void {\n    const entry = {pass};\n    this._postProcesses.push(entry);\n    if (this.engine.backend === 'webgl') this.warnPostProcess();\n    return () => { const index = this._postProcesses.indexOf(entry); if (index >= 0) this._postProcesses.splice(index, 1); };\n  }\n  private warnPostProcess() {\n    if (!this._warnedPostProcess) { this._warnedPostProcess = true; console.warn('Display post-processing requires WebGPU; passes are ignored on WebGL.'); }\n  }\n  private compose(render: Render) {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const target = render._output;\n    if (!target?.presentationComplete) return;\n    this._configure(render);\n    target.drawPostProcess();\n    if (this._postProcesses.length && this.engine.backend === 'webgl') this.warnPostProcess();\n    try { target.applyPostProcesses?.(this._postProcesses.map(entry => entry.pass), render); }\n    catch (error) { this.engine._notifyError(error); }\n    return target;\n  }\n  /** Presents a complete image or fallback. Keeps fallback visible until the first intermediate filter finishes. Does not trace. */\n  present(render: Render): Render | undefined {\n    if (render._engine !== this.engine) throw new Error('Render belongs to another engine.');\n    const ready = this.channel === 'final' && render.fallback ? render._presentable : render._complete;\n    const fallback = render.fallback;\n    const selected = ready ? render : fallback && (this.channel === 'final' ? fallback._presentable : fallback._complete) ? fallback : undefined;\n    if (!selected) return;\n    const target = this.compose(selected);\n    if (!target) return;\n    this.engine._present(target);\n    return selected;\n  }\n  /** Encodes this render at its actual dimensions using these settings; leaves the display canvas unchanged. */\n  async toBlob(render: Render, options: BlobOptions = {}): Promise<Blob> {\n    const target = this.compose(render);\n    if (!target) throw new Error('Render has no complete image.');\n    const image = await target.readPresentation();\n    const canvas = createCanvas(image.width, image.height, 'convertToBlob' in this.canvas);\n    const context = canvas.getContext('2d') as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;\n    if (!context) throw new Error('The image encoding context is not available.');\n    const bytes = new Uint8ClampedArray(image.data.length);\n    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.round(Math.min(1, Math.max(0, image.data[i])) * 255);\n    context.putImageData(new ImageData(bytes, image.width, image.height), 0, 0);\n    if ('convertToBlob' in canvas) return canvas.convertToBlob({type: options.type ?? 'image/png', quality: options.quality});\n    return new Promise((resolve, reject) => canvas.toBlob(blob => blob ? resolve(blob) : reject(new Error('The image could not be encoded')), options.type ?? 'image/png', options.quality));\n  }\n}\n"]}

package/lib/Engine.d.ts

@@ -0,0 +1,161 @@
+import Camera from './scene/Camera.js';
+import type { Scene } from './scene/Scene.js';
+import Display from './Display.js';
+import { type DepthSampleArea } from './renderer/depthQuery.js';
+import type { RenderingDiagnostics } from './renderer/RenderingPipeline.js';
+import type { TinyBvhLayout } from './tinybvh/TinyBvhBuilder.js';
+export type { DepthSampleArea } from './renderer/depthQuery.js';
+/** BLAS implementation; default builtin. */
+export type BVHBuilder = 'tinybvh' | 'builtin';
+/** Optional CPU preparation settings. */
+export interface PrepareOptions {
+    /** Completed BLAS fraction 0–1. Default undefined. */ onProgress?: (progress: number) => void;
+    /** Cancels preparation. Default undefined. */ signal?: AbortSignal;
+}
+/** Engine construction settings. */
+export interface EngineParams {
+    /** Default display canvas. Default a new HTML canvas, or OffscreenCanvas without document. */ canvas?: HTMLCanvasElement | OffscreenCanvas;
+    /** Backend selection. Default auto, with WebGL fallback. webgpu requires WebGPU. */ backend?: 'auto' | 'webgpu' | 'webgl';
+    /** Caller-owned WebGPU device. Default undefined uses a shared device. Implies webgpu; incompatible with webgl. */ device?: GPUDevice;
+}
+/** Material-atlas device limits. */
+export interface TextureAtlasLimits {
+    maxTextureArrayLayers: number;
+    maxTextureDimension2D: number;
+}
+/** Initialization result. */
+export interface EngineInfo {
+    backend: 'webgpu' | 'webgl';
+    adapterName: string;
+    webgpuFallbackReason?: string;
+    limits: TextureAtlasLimits;
+}
+/** Device and target diagnostics; Per-target GPU bytes exclude shared scene, temporary passes and driver costs. */
+export interface EngineDiagnostics extends RenderingDiagnostics {
+    backend: 'webgpu' | 'webgl' | undefined;
+    adapterName: string;
+    width: number;
+    height: number;
+    lastError?: string;
+    webgpuFallbackReason?: string;
+}
+interface EngineEvents {
+    progress: {
+        stage: 'device' | 'bvh' | 'shaders';
+        progress: number;
+    };
+    error: Error;
+    devicelost: {
+        reason: string;
+        recovering: boolean;
+    };
+}
+/** Shared device, committed scene/camera, CPU preparation and denoiser ownership. */
+export default class Engine {
+    /** Source scene, accepted only by update(). Default undefined. */ scene: Scene | undefined;
+    /** Source camera, accepted only by update(). Default undefined. */ camera: Camera | undefined;
+    /** Default canvas and display settings. */ readonly display: Display;
+    /** Static BLAS builder. Default builtin. */ bvhBuilder: BVHBuilder;
+    /** Static BLAS layout. Default bvh2; dynamic geometry uses bvh2. */ bvhLayout: TinyBvhLayout;
+    /** Enable TinyBVH spatial splits. Default false. */ bvhSpatialSplits: boolean;
+    /** Material texture budget in bytes. Default 384 MiB. */ textureAtlasBudgetBytes: number;
+    /** Maximum CPU BVH workers. Default auto (hardware concurrency minus one, clamped 1–4). */
+    get bvhWorkerCount(): number | 'auto';
+    set bvhWorkerCount(count: number | 'auto');
+    private _bvhWorkerCount;
+    private _bvhWorkerPool?;
+    private _bvhPreparationRevision;
+    private _bvhPreparation?;
+    private _bvhPreparationTail;
+    private _tinyBvhUnavailable;
+    private _bvhWorkerUnavailable;
+    private _bvhPreparedGeometry;
+    private _lastBvhBuild?;
+    private _lastBvhSettings;
+    private _lastBudget;
+    private _shaderProgress;
+    private _events;
+    private _pipeline?;
+    private _webglRenderer?;
+    private _gpuDevice?;
+    private _suppliedDevice?;
+    private readonly _ownsDeviceSelection;
+    private _deviceRevision;
+    private _lossController?;
+    private _deviceLossError?;
+    private _webglListening;
+    private _webglLost;
+    private _recoverWebGL;
+    private _contextRestore?;
+    private _gpuAdapterInfo?;
+    private _backendChoice;
+    private _initPromise?;
+    private _info?;
+    private _pipelineInitError?;
+    private _webgpuFallbackReason?;
+    private _reportedErrors;
+    private _loggedErrorMessages;
+    private _sceneChangeDetector;
+    private _snapshot;
+    private _sourceScene?;
+    private _committedScene?;
+    private _sourceCamera?;
+    private _committedCamera?;
+    private _cameraFields;
+    private _sceneRevision;
+    private _cameraRevision;
+    private _uploadedRevision;
+    private _pendingMeshes;
+    private _pendingTransforms;
+    private _pendingColors;
+    private _pendingGeometries;
+    private _pendingMaterials;
+    private _pendingLights;
+    private _pendingBackground;
+    private _disposed;
+    private _readingDepth;
+    private _renders;
+    private _targetCounter;
+    private _presented?;
+    private _denoisers;
+    private _denoiserCache;
+    private _denoiserEntries;
+    private _weights;
+    private _customPrepared;
+    private _denoiseTail;
+    private _lastError;
+    /** Most recent synchronous engine/render failure. Default undefined. */
+    get lastError(): Error | undefined;
+    constructor(params?: EngineParams);
+    /** Initializes once; concurrent/repeated calls share the result. */
+    init(): Promise<EngineInfo>;
+    /** Initialization info. Default undefined until init resolves. */ get info(): EngineInfo | undefined;
+    /** Active backend. Default undefined until initialization completes. */ get backend(): "webgpu" | "webgl" | undefined;
+    /** GPU device. Default undefined before initialization and on WebGL. */ get device(): GPUDevice | undefined;
+    /** Subscribes to shared progress/errors/device loss; returns unsubscribe. */
+    on<K extends keyof EngineEvents>(event: K, listener: (value: EngineEvents[K]) => void): () => void;
+    /** The sole external edit detection/commit point. Returns whether inputs changed. */
+    update(): boolean;
+    private _upload;
+    private _bvhConfig;
+    /** Builds static CPU BVHs for this scene without replacing GPU inputs. Options default undefined. */
+    prepare(scene: Scene, options?: PrepareOptions): Promise<void>;
+    private _needsBVHPreparation;
+    private _initPipeline;
+    private _onContextLost;
+    private _onContextRestored;
+    private _watchDevice;
+    private _invalidateDevice;
+    /** Replaces a caller-owned device after validation. Only available on engines
+     * constructed with device; the next update/refine uploads the committed scene.
+     */
+    setDevice(device: GPUDevice): Promise<void>;
+    private _adapterName;
+    /** Current shared preparation and resident target statistics. Default undefined before any work. */
+    getDiagnostics(): EngineDiagnostics | undefined;
+    /** Queries a 7×7 depth grid using the committed engine camera. Default undefined until GPU data is ready. */
+    readDepthSamples(area: DepthSampleArea): Promise<Float32Array | undefined>;
+    /** Releases all renders, shared resources, CPU workers and owned denoisers. */
+    dispose(): void;
+    private _disposeDenoiser;
+}