@meimu/mutracer 0.1.5 → 0.3.0

package/lib/Render.d.ts

@@ -1,3 +1,4 @@
+import type { AovKind } from './renderer/aov.js';
 import type Engine from './Engine.js';
 import type Camera from './scene/Camera.js';
 import type { AlphaBlendStrategy } from './renderer/RenderingPipeline.js';
@@ -13,6 +14,12 @@ export interface SampleEvent {
 }
 /** State of one independent accumulation. Default preparing. */
 export type RenderStatus = 'preparing' | 'compiling' | 'converging' | 'denoising' | 'finished' | 'error';
+/** Execution overrides for one refine call; accumulated samples are retained. */
+export interface RefineOptions {
+    /** Batch several samples in this call. Default this render's batchSamples. */ batchSamples?: boolean;
+    /** @deprecated Use refineUntil; this option will be removed in a later release. Positive finite WebGPU queue budget in milliseconds; capped by timeBudgetMs, ignored on WebGL. Default timeBudgetMs. */ targetBatchTimeMs?: number;
+    /** @deprecated Use refineUntil; this option will be removed in a later release. Leave the displayed image unchanged, for calls between display frames; the next presentation or pixel read updates it once with every new sample. Ignored on WebGL. Default false. */ deferResolve?: boolean;
+}
 /** When a render filters its complete samples. Default converged. */
 export type DenoiseSchedule = 'converged' | 'progressive' | 'every-sample';
 /** Caller-owned WebGPU filter. Render/Engine never dispose it; calls on one engine are serialized. */
@@ -23,7 +30,7 @@ export interface Denoiser {
         width: number;
         height: number;
     }): Promise<void>;
-    /** Write all output RGB, then resolve after submitting GPU work. Abort on input changes, restart, replacement or disposal; aborted results are discarded even if this resolves. Buffers are borrowed until settlement; do not retain or destroy them. */
+    /** Write all output RGB, then resolve after submitting GPU work. Abort on input changes, restart, replacement or disposal; aborted results are discarded even if this resolves. Settle within 10 seconds of an abort, or later denoising continues without waiting. Buffers are borrowed until settlement; do not retain or destroy them. */
     denoise(input: DenoiseInput, context: {
         signal: AbortSignal;
         schedule: DenoiseSchedule;
@@ -31,6 +38,7 @@ export interface Denoiser {
 }
 /** Borrowed, tightly packed rgba32float buffers, top row first, width*height*16 bytes of image data. */
 export interface DenoiseInput {
+    /** Requested primary-surface buffers, top row first; id is rgba32uint, others rgba32float. Default undefined. Borrowed until denoise settles. */ aovs?: Readonly<Partial<Record<AovKind, GPUBuffer>>>;
     /** Engine WebGPU device; may change after device loss/recovery. */ device: GPUDevice;
     /** Actual internal width, including backend alignment. */ width: number;
     /** Actual internal height, including backend alignment. */ height: number;
@@ -41,6 +49,7 @@ export interface DenoiseInput {
 }
 /** Third-party WebGPU filter; ignored with one warning on WebGL. */
 export interface CustomDenoiserOptions {
+    /** Optional AOV inputs; automatically enables their passes for this render. Default []. */ aovs?: readonly AovKind[];
     /** Required implementation selector. */ type: 'custom';
     /** Required caller-owned instance, keyed by object identity; never serialized or released by Render/Engine. */ denoiser: Denoiser;
     /** When to filter complete samples. Default converged. */ schedule?: DenoiseSchedule;
@@ -58,7 +67,7 @@ interface OIDNSettings {
     /** Execution backend. Default auto (native WGSL unless WebNN is selected). */ engine?: OIDNEngine;
     /** WGSL precision. Default auto (fp16 when shader-f16 is available). */ precision?: OIDNPrecision;
     /** Adaptive tile controller. Default enabled with minTileSize 256, initialTileSize 432, targetTileTimeMs 16, adjustmentStep 16. */ dynamicTile?: OIDNDynamicTileSetting;
-    /** Maximum OIDN tile size. Default chosen by oidn-web. */ maxTileSize?: number;
+    /** Maximum OIDN output tile edge in pixels. Default `512`. */ maxTileSize?: number;
     /** Abort weight downloads. Default undefined; does not distinguish cached networks. */ signal?: AbortSignal;
 }
 /** OIDN configuration on WebGPU: choose a packaged model or an explicit network URL. */
@@ -79,11 +88,29 @@ export type OIDNDenoiserOptions = OIDNSettings & ({
 });
 /** Assign a complete configuration, or null to disable denoising. The type selector is required. */
 export type DenoiserOptions = JNLMDenoiserOptions | OIDNDenoiserOptions | CustomDenoiserOptions;
+/** Optional caustic estimators. All are disabled by default. Both fall back to path tracing when a smooth caster has stochastic blend coverage. */
+export interface CausticSettings {
+    /** WebGPU progressive photon mapping; ignored on WebGL. Used alone, it can reduce denoising blotches on directly visible receivers, with noisier raw output. Default `false`. */
+    photonMapping?: boolean | {
+        /** Emitted photons per batch; 28 bytes per photon plus up to 13 MiB of overhead. Positive finite values are rounded to at least 1 and reduced to fit device limits and a 128 MiB batch budget; other values use the default. Default pixel count / 4, at most 262144. */ photonsPerSample?: number;
+        /** Positive first-batch gather radius in scene units, independent of photonsPerSample; shrinks as batches accumulate. Default 3% of the caster bounding sphere radius. */ initialRadius?: number;
+    };
+    /**
+     * WebGPU light tracing for directly visible caustic paths; ignored on WebGL.
+     * Default `false`.
+     */ lightTracing?: boolean | {
+        /** Emitted photons per sample, rounded to a positive integer and capped by the device dispatch limit. Default pixel count / 4. */
+        photonsPerSample?: number;
+    };
+}
 /** Optional per-render execution and image-quality settings. */
 export interface RenderSettings {
+    /** Optional surface outputs. Default []; disabled outputs allocate no AOV resources. */ aovs?: readonly AovKind[];
+    /** Independent AOV sample cap, positive integer. Default 16. */ aovSamples?: number;
     /** Maximum complete samples. Default 2048. */ maxSamples?: number;
     /**
      * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * Complete caustic light-to-camera paths can be longer than this depth.
      * Total path events, including transmission and alpha skips, are capped at 20
      * and at three times this depth. Intel Mac WebGL uses min(depth, 3), doubled
      * for scenes with transmission or alpha, with its existing early termination.
@@ -91,15 +118,17 @@ export interface RenderSettings {
      */ bounces?: number;
     /** Radiance clamp; 0 disables it. Default 0. */ clamping?: number;
     /** Sampling sequence. Default sobol. */ samplingPattern?: SamplingPattern;
+    /** Caustic estimators. All are disabled by default. */ caustics?: CausticSettings;
     /** Light candidates per vertex; WebGPU only, ignored on WebGL. Default 4. */ directLightCandidates?: number;
     /** Rounded material edges. Default true. */ bevel?: boolean;
     /** Bevel neighborhood probes, clamped to 1–32. Default 8. */ bevelSamples?: number;
-    /** Wavelengths per dispersion sample. Default 3; 1 selects one random wavelength. */ dispersionWavelengths?: 1 | 3;
+    /** Wavelength paths per dispersion sample, each carrying one RGB channel. Default 3; 1 selects one random channel. */ dispersionWavelengths?: 1 | 3;
     /** Primary-ray alpha blend strategy; WebGPU only. Default stochastic. */ alphaBlendStrategy?: AlphaBlendStrategy;
     /** Minimum transmissive path alpha, using path depth. Default 1. Changes restart this accumulation. */ transmissiveOutputAlphaMin?: number;
     /** Tile execution budget in milliseconds. Default 21. */ timeBudgetMs?: number;
-    /** Maximum tiles per frame. Default Infinity. */ maxTiles?: number;
-    /** Accumulate multiple samples when frame time permits. Default false. */ allowMultipleSamplesPerFrame?: boolean;
+    /** Maximum tile grid size per sample, rounded up to a rectangular grid. Fewer tiles make each tile larger; this does not cap work per frame or refine call. Default Infinity. */ maxTiles?: number;
+    /** Let one refine submit several samples within an estimated timeBudgetMs; one sample or tile can exceed it. WebGPU requires GPU timestamps. RenderLoop also batches between display frames when individual tiles fit the budget. Default false. */ batchSamples?: boolean;
+    /** @deprecated Use batchSamples; this alias will be removed in a later release. Default false. */ allowMultipleSamplesPerFrame?: boolean;
     /** Adapt scale to frame timing; minScale must not exceed resolutionScale. Default false. */ adaptiveResolution?: {
         targetFrameMs: number;
         minScale: number;
@@ -144,9 +173,12 @@ export interface ConvergeResult {
 }
 /** One independently configured image and its accumulation, owned by an engine. */
 export default class Render {
+    /** Enabled surface outputs. Default []; readPixels rejects outputs not enabled here. */ aovs: readonly AovKind[];
+    /** Independent AOV sample cap. Default 16. */ aovSamples: number;
     /** Maximum complete samples. Default 2048. */ maxSamples: number;
     /**
      * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * Complete caustic light-to-camera paths can be longer than this depth.
      * Total path events, including transmission and alpha skips, are capped at 20
      * and at three times this depth. Intel Mac WebGL uses min(depth, 3), doubled
      * for scenes with transmission or alpha, with its existing early termination.
@@ -154,6 +186,7 @@ export default class Render {
      */ bounces: number;
     /** Per-sample radiance clamp; 0 disables it. Default 0. */ clamping: number;
     /** Sampling sequence. Default sobol. */ samplingPattern: SamplingPattern;
+    /** Caustic estimators. Default undefined (all disabled). */ caustics?: CausticSettings;
     /** WebGPU light candidates per vertex; ignored on WebGL. Default 4. */ directLightCandidates: number;
     /** Rounded material edges. Default true. */ bevel: boolean;
     /** Bevel probes, clamped to 1–32. Default 8. */ bevelSamples: number;
@@ -161,8 +194,11 @@ export default class Render {
     /** WebGPU primary-ray alpha policy; ignored on WebGL. Default stochastic. */ alphaBlendStrategy: AlphaBlendStrategy;
     /** Minimum transmissive path alpha. Default 1. Changing it restarts this render. */ transmissiveOutputAlphaMin: number;
     /** Execution budget in milliseconds. Default 21. */ timeBudgetMs: number;
-    /** Maximum tiles per frame. Default Infinity. */ maxTiles: number;
-    /** Allow several samples per frame when possible. Default false. */ allowMultipleSamplesPerFrame: boolean;
+    /** Maximum tile grid size per sample, rounded up to a rectangular grid. Fewer tiles make each tile larger; this does not cap work per frame or refine call. Default Infinity. */ maxTiles: number;
+    /** Let one refine submit several samples within an estimated timeBudgetMs; one sample or tile can exceed it. WebGPU requires GPU timestamps. Default false. */ batchSamples: boolean;
+    /** @deprecated Use batchSamples; this alias will be removed in a later release. Default false. */
+    get allowMultipleSamplesPerFrame(): boolean;
+    set allowMultipleSamplesPerFrame(value: boolean);
     /** Adaptive resolution controller, or false. Default false. */ adaptiveResolution: {
         targetFrameMs: number;
         minScale: number;
@@ -192,6 +228,8 @@ export default class Render {
     private _status;
     private _disposed;
     private _busy;
+    private _refineOptions?;
+    private _refillController?;
     private _offlineCamera;
     private _input;
     private _adaptiveScale;
@@ -220,22 +258,57 @@ export default class Render {
     private _lastDenoiseTime;
     private _warnedDenoisedReadback;
     constructor(engine: Engine, options?: RenderOptions);
-    /** Actual target width; before allocation uses the requested dimensions. */ get width(): number;
-    /** Actual target height; before allocation uses the requested dimensions. */ get height(): number;
-    /** Complete samples since the last restart; stale engine inputs report 0. Default 0. */
+    /** Output width: exact for fixed renders; otherwise the target width, or the requested width before allocation. */ get width(): number;
+    /** Output height: exact for fixed renders; otherwise the target height, or the requested height before allocation. */ get height(): number;
+    /** Complete beauty samples since the last restart; stale engine inputs report 0. Default 0. */
     get samples(): number;
-    /** Whether complete samples reached maxSamples. Default false. */ get converged(): boolean;
+    /** Whether complete beauty samples reached maxSamples. Default false. */ get converged(): boolean;
     /** Current execution state. Default preparing. */ get status(): RenderStatus;
     private get _current();
+    /** @deprecated Use refineUntil for custom frame loops; this will be removed in a later release. Latest WebGPU full beauty sample estimate in milliseconds, extrapolated from tile GPU time when tiled. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
+    get gpuSampleTimeMs(): number | undefined;
+    /**
+     * @deprecated Use refineUntil; this will be removed in a later release. Waits for the
+     * next release of WebGPU sampling queue capacity and returns true when sampling was
+     * queued. Returns false immediately with no queued sampling, on WebGL, or for only
+     * denoising, display or offline convergence work. Does not submit work. Throws after
+     * disposal.
+     */
+    whenReadyToRefine(): Promise<boolean>;
+    /** Complete surface-output samples since restart; stale inputs report 0. Independent of beauty samples. Default 0. */
+    get aovSamplesRendered(): number;
+    private _refineAov;
     private _validate;
     private _size;
+    /**
+     * Backends may round targets up. A fixed render widens the view over the extra
+     * pixels so the requested centered rectangle keeps its framing and square pixels.
+     */
+    private _targetCamera;
     private _settings;
     private _synchronize;
     private _trace;
     private _adaptResolution;
     private _cancelAdaptiveFrames;
-    /** Accumulates within this frame's budget. Rejects calls during converge or after disposal. */
-    refine(): RenderStatus;
+    /** Accumulates within this frame's budget. Default undefined traces beauty and requested AOVs. Pass an enabled AOV kind to refine surface outputs only, without beauty or denoising; progress is aovSamplesRendered. Options default to this render's execution settings. Rejects calls during converge or after disposal. */
+    refine(channel?: AovKind, options?: RefineOptions): RenderStatus;
+    /**
+     * Calls refine() once synchronously, then keeps sampling on WebGPU until deadline.
+     * Call present() right after it; later samples appear at the next presentation.
+     * Sampling continues only with batchSamples on, the final channel displayed, a
+     * visible page and tiles that fit timeBudgetMs. It stops on abort or convergence.
+     * Preparing, compiling, denoising and the first incomplete sample advance only
+     * through the synchronous call, which is all WebGL runs. A new call ends the
+     * previous one. Asynchronous errors set status to error and resolve; synchronous
+     * errors follow refine().
+     * @param deadline End time in performance.now() milliseconds.
+     * @param options.signal Optional application cancellation; default none. An
+     * already aborted signal still permits the synchronous refine().
+     */
+    refineUntil(deadline: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private _refineToDeadline;
     private _refine;
     private _refineOne;
     private _schedule;
@@ -247,11 +320,21 @@ export default class Render {
     private _warmDenoiser;
     private _cancelDenoise;
     private _maybeDenoise;
-    /** 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. */
-    readPixels(kind?: 'hdr' | 'denoised' | 'albedo' | 'normal'): Promise<{
+    /** Reads native RGBA, top row first; id uses uint32, other kinds float32. Default hdr. Beauty/guide reads are empty until a beauty sample completes. AOV reads require explicit aovs enablement. 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. */
+    readPixels(kind: 'id'): Promise<{
+        width: number;
+        height: number;
+        data: Uint32Array;
+    }>;
+    readPixels(kind?: 'hdr' | 'denoised' | 'albedo' | 'normal' | Exclude<AovKind, 'id'>): Promise<{
+        width: number;
+        height: number;
         data: Float32Array;
+    }>;
+    readPixels(kind: 'hdr' | 'denoised' | 'albedo' | 'normal' | AovKind): Promise<{
         width: number;
         height: number;
+        data: Float32Array | Uint32Array;
     }>;
     /** 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: 'hdr' | 'display'): GPUTexture | undefined;