@meimu/mutracer 0.3.0 → 0.3.1

package/lib/Render.d.ts

@@ -1,4 +1,4 @@
-import type { AovKind } from './renderer/aov.js';
+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';
@@ -106,13 +106,16 @@ export interface CausticSettings {
 /** 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;
+    /** AOV dimensions. Default render; display traces AOVs at the canvas size with at most 4 samples (aovSamples above 4 have no effect) on WebGPU, falls back with one warning on WebGL, and rejects fixed-size renders. Output definitions do not depend on this setting. */ aovResolution?: 'render' | 'display';
+    /** Independent AOV sample cap, positive integer. Default 16; display-resolution AOVs stop at 4. */ aovSamples?: number;
     /** Maximum complete samples. Default 2048. */ maxSamples?: number;
     /**
-     * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * Maximum scattering depth, rounded and clamped to [1, 50] on WebGPU or
+     * [1, 20] on WebGL (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
+     * Total path events, including transmission and alpha skips, are capped at 50
+     * on WebGPU or 20 on WebGL, 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?: number;
@@ -174,13 +177,17 @@ 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;
+    /** AOV dimensions. Default render; display traces AOVs at the canvas size with at most 4 samples on WebGPU, falls back on WebGL, and rejects fixed-size renders. Output definitions do not depend on this setting. */ aovResolution: 'render' | 'display';
+    private _warnedAovResolution;
+    /** Independent AOV sample cap. Default 16; display-resolution AOVs stop at 4. */ aovSamples: number;
     /** Maximum complete samples. Default 2048. */ maxSamples: number;
     /**
-     * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * Maximum scattering depth, rounded and clamped to [1, 50] on WebGPU or
+     * [1, 20] on WebGL (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
+     * Total path events, including transmission and alpha skips, are capped at 50
+     * on WebGPU or 20 on WebGL, 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: number;
@@ -320,7 +327,7 @@ export default class Render {
     private _warmDenoiser;
     private _cancelDenoise;
     private _maybeDenoise;
-    /** 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. */
+    /** 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 and use the AOV dimensions. 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;
@@ -336,7 +343,9 @@ export default class Render {
         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. */
+    /** Borrows a raw linear primary-surface texture at the AOV resolution, top row first; default undefined until an enabled AOV has samples. WebGPU only. Colors use rgba8unorm-srgb (loads as linear [0,1]) with validity coverage in alpha; depth uses rg32float (depth, hit coverage). The texture is resolved from the accumulation when its samples change; the first call per kind also creates its pipeline. Borrowing follows getOutputTexture's lifetime rules; restart invalidates it. */
+    getAovTexture(kind: 'diffuseColor' | 'specularColor' | 'depth'): GPUTexture | undefined;
+    /** 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; its dimensions may differ from this render. 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;
     /** Discards only this render's accumulation and pending denoising. */
     restart(): void;

package/lib/Render.js

@@ -1,3 +1,4 @@
+import { AOV_KINDS, DISPLAY_AOV_SAMPLE_CAP } from './renderer/aov.js';
 import { aovMask } from './renderer/aov.js';
 import { displayAovKind } from './renderer/aovDisplay.js';
 import { Events } from './util/events.js';
@@ -100,13 +101,17 @@ function denoiserKey(options) {
 /** One independently configured image and its accumulation, owned by an engine. */
 export default class Render {
     /** Enabled surface outputs. Default []; readPixels rejects outputs not enabled here. */ aovs = [];
-    /** Independent AOV sample cap. Default 16. */ aovSamples = 16;
+    /** AOV dimensions. Default render; display traces AOVs at the canvas size with at most 4 samples on WebGPU, falls back on WebGL, and rejects fixed-size renders. Output definitions do not depend on this setting. */ aovResolution = 'render';
+    _warnedAovResolution = false;
+    /** Independent AOV sample cap. Default 16; display-resolution AOVs stop at 4. */ aovSamples = 16;
     /** Maximum complete samples. Default 2048. */ maxSamples = 2048;
     /**
-     * Maximum scattering depth, rounded and clamped to [1, 20] (NaN becomes 1).
+     * Maximum scattering depth, rounded and clamped to [1, 50] on WebGPU or
+     * [1, 20] on WebGL (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
+     * Total path events, including transmission and alpha skips, are capped at 50
+     * on WebGPU or 20 on WebGL, 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;
@@ -247,6 +252,7 @@ export default class Render {
     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 _presentable() { return this._complete && (!this._denoisePending || this._denoisedSamples > 0 || (this._schedule() === 'converged' && this.maxSamples > 1)); }
+    /** @internal Fixed export crop, applied before display passes. */ get _exportCrop() { return this._fixed; }
     /** @internal */ get _output() { if (this._disposed)
         throw new Error('Render is disposed.'); return this._target; }
     /** @deprecated Use refineUntil for custom frame loops; this will be removed in a later release. Latest WebGPU full beauty sample estimate in milliseconds, extrapolated from tile GPU time when tiled. Default undefined; also undefined for stale inputs, during converge or without GPU timestamps. */
@@ -307,7 +313,7 @@ export default class Render {
         if (!target)
             return this._status = 'preparing';
         const before = target.getAovSamples?.() ?? 0;
-        const limit = kind === 'id' || kind === 'motion' ? 1 : Math.min(this.maxSamples, this.aovSamples);
+        const limit = kind === 'id' || kind === 'motion' ? 1 : Math.min(this.maxSamples, this.aovSamples, this.aovResolution === 'display' && this._engine.backend === 'webgpu' ? DISPLAY_AOV_SAMPLE_CAP : Infinity);
         if (!target.refineAovs?.(this._targetCamera(this._engine._inputs.value), Math.min(limit, (target.getAovSamples?.() ?? 0) + 1)))
             return this._status = 'compiling';
         if ((target.getAovSamples?.() ?? 0) > before) {
@@ -320,6 +326,12 @@ export default class Render {
     }
     _validate() {
         aovMask(this.aovs);
+        if (this.aovResolution !== 'render' && this.aovResolution !== 'display')
+            throw new Error('Unknown aovResolution.');
+        if (this.aovResolution === 'display' && this._fixed)
+            throw new Error('aovResolution display requires a scale-based render.');
+        if (this.aovResolution === 'display' && this._denoiserOptions?.type === 'custom' && this._denoiserOptions.aovs?.length)
+            throw new Error('Custom denoiser AOV inputs require aovResolution render.');
         if (!Number.isInteger(this.aovSamples) || this.aovSamples < 1)
             throw new Error('aovSamples must be a positive integer.');
         if (!Number.isFinite(this.maxSamples) || this.maxSamples < 1)
@@ -377,6 +389,13 @@ export default class Render {
     }
     _settings(sampleCap = this.maxSamples) {
         const settings = collectTraceSettings(this, sampleCap);
+        if (this.aovResolution === 'display' && this._engine.backend === 'webgl') {
+            settings.aovResolution = 'render';
+            if (!this._warnedAovResolution) {
+                this._warnedAovResolution = true;
+                console.warn('Display-resolution AOVs require WebGPU; using render resolution.');
+            }
+        }
         settings.batchSamples = this._refineOptions?.batchSamples ?? settings.batchSamples;
         if (this._denoiserOptions?.type === 'custom')
             settings.aovs = [...new Set([...this.aovs, ...(this._denoiserOptions.aovs ?? [])])];
@@ -788,7 +807,7 @@ export default class Render {
         if (this._disposed)
             throw new Error('Render is disposed.');
         const target = this._target;
-        if (['depth', 'position', 'roughness', 'diffuseAlbedo', 'specularAlbedo', 'id', 'motion'].includes(kind)) {
+        if (AOV_KINDS.includes(kind)) {
             const aov = kind;
             aovMask(this.aovs);
             if (!this.aovs.includes(aov))
@@ -810,7 +829,13 @@ export default class Render {
         target.activate();
         return this._cropOutput(await target.readOutput(kind));
     }
-    /** Borrows a read-only WebGPU texture; undefined on WebGL or before a complete sample. Kind is required. HDR is native resolved linear ray color before denoising/display composition, with DenoiseInput.color normalization and coverage. Display is the latest compose, including filters and display passes. Valid only until this render's next refine/converge, display present/setSize, restart/dispose or device loss; never retain, write or destroy it. */
+    /** Borrows a raw linear primary-surface texture at the AOV resolution, top row first; default undefined until an enabled AOV has samples. WebGPU only. Colors use rgba8unorm-srgb (loads as linear [0,1]) with validity coverage in alpha; depth uses rg32float (depth, hit coverage). The texture is resolved from the accumulation when its samples change; the first call per kind also creates its pipeline. Borrowing follows getOutputTexture's lifetime rules; restart invalidates it. */
+    getAovTexture(kind) {
+        if (this._engine.backend !== 'webgpu' || !this._current || !this.aovs.includes(kind) || !this.aovSamplesRendered)
+            return;
+        return this._target?.getAovTexture?.(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; its dimensions may differ from this render. 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._engine.backend !== 'webgpu' || (kind === 'hdr' ? !this._complete : !this._current || !this._target?.presentationComplete || (!this._complete && !this._target.getAovSamples?.())))
             return;