@zephyr3d/scene 0.9.6 → 0.9.8

package/dist/camera/camera.js

@@ -3,6 +3,7 @@ import { SceneNode } from '../scene/scene_node.js';
 import { Compositor } from '../posteffect/compositor.js';
 import { TAA } from '../posteffect/taa.js';
 import { SSR } from '../posteffect/ssr.js';
+import { SSS } from '../posteffect/sss.js';
 import { Tonemap } from '../posteffect/tonemap.js';
 import { FXAA } from '../posteffect/fxaa.js';
 import { Bloom } from '../posteffect/bloom.js';
@@ -14,6 +15,36 @@ import { ScreenAdapter } from '../app/screen.js';
 import { ABufferOIT } from '../render/abuffer_oit.js';
 import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
 
+const SSS_DEFAULT_SETTINGS = {
+    blurScale: 11,
+    strength: 0.65,
+    transmissionStrength: 0.18,
+    transmissionPower: 2.1,
+    multiScatter: 0.08
+};
+const SSS_QUALITY_PRESET_SETTINGS = {
+    quality: {
+        halfRes: false,
+        blurKernelSize: 11,
+        blurStdDev: 3.5,
+        blurDepthCutoff: 0.24,
+        normalCutoff: 0.82
+    },
+    balanced: {
+        halfRes: false,
+        blurKernelSize: 9,
+        blurStdDev: 3,
+        blurDepthCutoff: 0.26,
+        normalCutoff: 0.78
+    },
+    performance: {
+        halfRes: true,
+        blurKernelSize: 7,
+        blurStdDev: 2.4,
+        blurDepthCutoff: 0.32,
+        normalCutoff: 0.72
+    }
+};
 /**
  * A renderable camera node that manages view/projection math, frusta,
  * input control, picking, and a post-processing chain via a compositor.
@@ -22,7 +53,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
  * - Maintains projection, view, VP, and inverse VP matrices and lazily recomputes them when invalidated.
  * - Provides world- and view-space frusta for culling and clipping.
  * - Supports perspective and orthographic projections.
- * - Integrates with post effects (Tonemap, FXAA, TAA, Bloom, SSR, SSAO, Motion Blur) through an internal `Compositor`.
+ * - Integrates with post effects (Tonemap, FXAA, TAA, Bloom, SSR, SSS, SSAO, Motion Blur) through an internal `Compositor`.
  * - Handles temporal jitter and history state when TAA or motion blur are enabled.
  * - Emits picking rays from screen coordinates and supports async GPU picking.
  * - Optional controller integration for user input handling.
@@ -34,6 +65,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
  * @public
  */ class Camera extends SceneNode {
     /** @internal Halton 2-3 sequence used for TAA jittering. */ static _halton23 = halton23(16);
+    /** @internal Per-camera history resources. */ static _historyData = new WeakMap();
     /** @internal Per-camera history resource manager. */ static _historyResourceManager = new WeakMap();
     /** @internal Screen adapter for this camera */ _screenAdapter;
     /** @internal Whether the camera is adapted */ _adapted;
@@ -60,6 +92,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     /** @internal OIT algorithm selection mode. */ _oitMode;
     /** @internal ABuffer OIT layer budget. */ _oitABufferLayers;
     /** @internal Whether to perform a depth pre-pass. */ _depthPrePass;
+    /** @internal Render path selection for scene renderer. */ _renderPath;
     /** @internal Whether command buffers may be reused for optimization. */ _commandBufferReuse;
     /** @internal Hi-Z acceleration enable (primarily for SSR). */ _HiZ;
     /** @internal If true, a float point backbuffer will be used. The default value is true */ _HDR;
@@ -87,6 +120,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     /** @internal TAA enable flag (via post effect). */ _TAA;
     /** @internal TAA post effect reference. */ _postEffectTAA;
     /** @internal TAA debug mode (implementation-defined). */ _TAADebug;
+    /** @internal Cascaded shadow debug visualization flag. */ _shadowDebugCascades;
     /** @internal SSR enable flag (via post effect). */ _SSR;
     /** @internal SSR post effect reference. */ _postEffectSSR;
     /** @internal SSR parameter vector: (maxDistance, iterations, thickness, reserved). */ _ssrParams;
@@ -98,6 +132,18 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     /** @internal SSR blur depth cutoff. */ _ssrBlurDepthCutoff;
     /** @internal SSR blur kernel size. */ _ssrBlurKernelSize;
     /** @internal SSR Gaussian blur standard deviation. */ _ssrBlurStdDev;
+    /** @internal Whether SSR temporal accumulation is enabled. */ _ssrTemporal;
+    /** @internal SSR temporal blending weight in [0, 1]. */ _ssrTemporalWeight;
+    /** @internal SSS enable flag (via post effect). */ _SSS;
+    /** @internal SSS post effect reference. */ _postEffectSSS;
+    /** @internal SSS blur scale in pixels per authored width unit. */ _sssBlurScale;
+    /** @internal High-level preset that resolves SSS blur quality controls. */ _sssQualityPreset;
+    /** @internal SSS composite strength. */ _sssStrength;
+    /** @internal SSS thin-shell transmission strength. */ _sssTransmissionStrength;
+    /** @internal SSS thin-shell transmission exponent. */ _sssTransmissionPower;
+    /** @internal SSS multi-scatter energy compensation. */ _sssMultiScatter;
+    /** @internal Cached runtime SSS settings after applying the quality preset. */ _sssResolvedSettings;
+    /** @internal SSS debug visualization mode. */ _sssDebugView;
     /** @internal SSAO enable flag (via post effect). */ _SSAO;
     /** @internal SSAO post effect reference. */ _postEffectSSAO;
     /** @internal SSAO scale (sampling radius multiplier). */ _SSAOScale;
@@ -153,6 +199,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         this._oitMode = 'none';
         this._oitABufferLayers = 20;
         this._depthPrePass = false;
+        this._renderPath = 'forward';
         this._screenAdapter = new ScreenAdapter();
         this._adapted = false;
         this._HiZ = false;
@@ -181,17 +228,38 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         this._TAA = false;
         this._postEffectTAA = new DRef();
         this._TAADebug = 0;
+        this._shadowDebugCascades = false;
         this._SSR = false;
         this._postEffectSSR = new DRef();
-        this._ssrParams = new Vector4(100, 120, 0.5, 0);
-        this._ssrMaxRoughness = 0.8;
+        this._ssrParams = new Vector4(64, 96, 0.9, 0);
+        this._ssrMaxRoughness = 0.55;
         this._ssrRoughnessFactor = 1;
-        this._ssrStride = 2;
+        this._ssrStride = 1;
         this._ssrCalcThickness = false;
-        this._ssrBlurriness = 0.01;
+        this._ssrBlurriness = 0.008;
         this._ssrBlurDepthCutoff = 2;
-        this._ssrBlurKernelSize = 10;
-        this._ssrBlurStdDev = 10;
+        this._ssrBlurKernelSize = 5;
+        this._ssrBlurStdDev = 4;
+        this._ssrTemporal = true;
+        this._ssrTemporalWeight = 0.85;
+        this._SSS = false;
+        this._postEffectSSS = new DRef();
+        this._sssBlurScale = SSS_DEFAULT_SETTINGS.blurScale;
+        this._sssQualityPreset = 'balanced';
+        this._sssStrength = SSS_DEFAULT_SETTINGS.strength;
+        this._sssTransmissionStrength = SSS_DEFAULT_SETTINGS.transmissionStrength;
+        this._sssTransmissionPower = SSS_DEFAULT_SETTINGS.transmissionPower;
+        this._sssMultiScatter = SSS_DEFAULT_SETTINGS.multiScatter;
+        const defaultSSSQualityPreset = SSS_QUALITY_PRESET_SETTINGS.balanced;
+        this._sssResolvedSettings = {
+            halfRes: defaultSSSQualityPreset.halfRes,
+            blurKernelSize: defaultSSSQualityPreset.blurKernelSize,
+            blurStdDev: defaultSSSQualityPreset.blurStdDev,
+            blurDepthCutoff: defaultSSSQualityPreset.blurDepthCutoff,
+            normalCutoff: defaultSSSQualityPreset.normalCutoff
+        };
+        this.updateSSSResolvedSettings();
+        this._sssDebugView = 'none';
         this._SSAO = false;
         this._postEffectSSAO = new DRef();
         this._SSAOScale = 10;
@@ -268,6 +336,14 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         this._HiZ = !!val;
     }
     /**
+   * Render path used by the scene renderer.
+   */ get renderPath() {
+        return this._renderPath;
+    }
+    set renderPath(_val) {
+        this._renderPath = 'forward';
+    }
+    /**
    * Whether HDR backbuffer is enabled.
    *
    * Tonemap should be disabled when not using HDR backbuffer.
@@ -443,6 +519,14 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         this._TAADebug = val;
     }
     /**
+   * Enables cascade debug visualization for directional shadows.
+   */ get shadowDebugCascades() {
+        return this._shadowDebugCascades;
+    }
+    set shadowDebugCascades(val) {
+        this._shadowDebugCascades = !!val;
+    }
+    /**
    * Gets whether Screen Space Reflections (SSR) is enabled.
    */ get SSR() {
         return this._postEffectSSR.get().enabled;
@@ -549,6 +633,85 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     set ssrBlurStdDev(val) {
         this._ssrBlurStdDev = val;
     }
+    /**
+   * Gets whether SSR temporal accumulation is enabled.
+   */ get ssrTemporal() {
+        return this._ssrTemporal;
+    }
+    set ssrTemporal(val) {
+        this._ssrTemporal = !!val;
+    }
+    /**
+   * Gets SSR temporal blending weight in [0, 1].
+   * Higher values rely more on reprojected history.
+   */ get ssrTemporalWeight() {
+        return this._ssrTemporalWeight;
+    }
+    set ssrTemporalWeight(val) {
+        this._ssrTemporalWeight = Math.max(0, Math.min(1, val ?? 0));
+    }
+    /**
+   * Gets whether Screen Space Subsurface Scattering (SSS) is enabled.
+   */ get SSS() {
+        return this._postEffectSSS.get().enabled;
+    }
+    set SSS(val) {
+        this._postEffectSSS.get().enabled = !!val;
+    }
+    /** Global blur scale for screen-space SSS. */ get sssBlurScale() {
+        return this._sssBlurScale;
+    }
+    set sssBlurScale(val) {
+        this._sssBlurScale = Math.max(0, val ?? 0);
+    }
+    /**
+   * High-level quality preset for SSS blur controls.
+   *
+   * This is the primary user-facing SSS quality control and only affects
+   * the blur sampling quality/performance tradeoff, not the authored look.
+   */ get sssQualityPreset() {
+        return this._sssQualityPreset;
+    }
+    set sssQualityPreset(val) {
+        const next = Camera.resolveSSSQualityPreset(val);
+        if (next !== this._sssQualityPreset) {
+            this._sssQualityPreset = next;
+            this.updateSSSResolvedSettings();
+        }
+    }
+    /** Final SSS composite strength. */ get sssStrength() {
+        return this._sssStrength;
+    }
+    set sssStrength(val) {
+        this._sssStrength = Math.max(0, val ?? 0);
+    }
+    /** Thin-shell transmission strength. */ get sssTransmissionStrength() {
+        return this._sssTransmissionStrength;
+    }
+    set sssTransmissionStrength(val) {
+        this._sssTransmissionStrength = Math.max(0, val ?? 0);
+    }
+    /** Thin-shell transmission exponent. */ get sssTransmissionPower() {
+        return this._sssTransmissionPower;
+    }
+    set sssTransmissionPower(val) {
+        this._sssTransmissionPower = Math.max(0.1, val ?? 0.1);
+    }
+    /** Multi-scatter energy compensation factor. */ get sssMultiScatter() {
+        return this._sssMultiScatter;
+    }
+    set sssMultiScatter(val) {
+        this._sssMultiScatter = Math.max(0, val ?? 0);
+    }
+    /** Resolved SSS blur settings after applying the quality preset. */ get sssResolvedSettings() {
+        return this._sssResolvedSettings;
+    }
+    /** Debug visualization for screen-space SSS buffers. */ get sssDebugView() {
+        return this._sssDebugView;
+    }
+    set sssDebugView(val) {
+        this._sssDebugView = val ?? 'none';
+    }
     /** @internal */ get ssrParams() {
         return this._ssrParams;
     }
@@ -617,7 +780,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     set commandBufferReuse(val) {
         this._commandBufferReuse = !!val;
     }
-    /** Whether this camera is adapted to screen settings */ get adapted() {
+    /** Whether this camera is adapted to screen settins */ get adapted() {
         return this._adapted;
     }
     set adapted(val) {
@@ -751,12 +914,10 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
    *
    * @param x - The x-component of the screen coordinates, relative to the top-left corner of the viewport.
    * @param y - The y-component of the screen coordinates, relative to the top-left corner of the viewport.
-   * @param viewportWidth - Optional width of the viewport for normalizing screen coordinates. If not provided, it will be derived from the camera's viewport or the device's viewport.
-   * @param viewportHeight - Optional height of the viewport for normalizing screen coordinates. If not provided, it will be derived from the camera's viewport or the device's viewport.
    * @returns The ray originating from the camera position and passing through the given screen coordinates.
-   */ constructRay(x, y, viewportWidth, viewportHeight) {
-        const width = viewportWidth ?? (this.viewport ? this.viewport[2] : getDevice().getViewport().width);
-        const height = viewportHeight ?? (this.viewport ? this.viewport[3] : getDevice().getViewport().height);
+   */ constructRay(x, y) {
+        const width = this.viewport ? this.viewport[2] : getDevice().getViewport().width;
+        const height = this.viewport ? this.viewport[3] : getDevice().getViewport().height;
         const ndcX = 2 * x / width - 1;
         const ndcY = 1 - 2 * y / height;
         const nearClip = new Vector4(ndcX, ndcY, -1, 1);
@@ -929,31 +1090,39 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         return this.getProjectionMatrix().isOrtho();
     }
     /**
-   * Gets the camera history resource manager for temporal effects
-   * @returns History resource manager
-   */ getHistoryResourceManager() {
-        let manager = Camera._historyResourceManager.get(this);
-        if (!manager) {
-            // Import dynamically to avoid circular dependency
-            // The actual import happens in forward_plus_builder.ts
-            return null;
+   * Gets the camera history data which is used in temporal reprojection
+   * @returns Camera history data
+   */ getHistoryData() {
+        let data = Camera._historyData.get(this);
+        if (!data) {
+            data = {
+                prevColorTex: null,
+                prevMotionVectorTex: null,
+                prevSSRReflectTex: null,
+                prevSSRMotionVectorTex: null
+            };
+            Camera._historyData.set(this, data);
         }
-        return manager;
-    }
-    /**
-   * Sets the camera history resource manager for temporal effects
-   * @internal
-   */ setHistoryResourceManager(manager) {
-        Camera._historyResourceManager.set(this, manager);
+        return data;
     }
     /**
    * Clears the camera history data which is used in temporal reprojection
    */ clearHistoryData() {
-        // Clear history resource manager
-        const manager = Camera._historyResourceManager.get(this);
-        if (manager) {
-            manager.dispose();
-            Camera._historyResourceManager.delete(this);
+        const data = Camera._historyData.get(this);
+        if (data) {
+            if (data.prevColorTex) {
+                getDevice().pool.releaseTexture(data.prevColorTex);
+            }
+            if (data.prevMotionVectorTex) {
+                getDevice().pool.releaseTexture(data.prevMotionVectorTex);
+            }
+            if (data.prevSSRReflectTex) {
+                getDevice().pool.releaseTexture(data.prevSSRReflectTex);
+            }
+            if (data.prevSSRMotionVectorTex) {
+                getDevice().pool.releaseTexture(data.prevSSRMotionVectorTex);
+            }
+            Camera._historyData.delete(this);
         }
         this._prevVPMatrix = null;
         this._prevPosition = null;
@@ -968,6 +1137,12 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
             this._postEffectSSR.set(ssr);
             this._compositor.appendPostEffect(ssr);
         }
+        if (!this._postEffectSSS.get()) {
+            const sss = new SSS();
+            sss.enabled = false;
+            this._postEffectSSS.set(sss);
+            this._compositor.appendPostEffect(sss);
+        }
         if (!this._postEffectSSAO.get()) {
             const ssao = new SAO();
             ssao.enabled = false;
@@ -1027,6 +1202,24 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
             this._compositor.appendPostEffect(bloom);
         }
     }
+    static resolveSSSQualityPreset(val) {
+        switch(val){
+            case 'quality':
+            case 'balanced':
+            case 'performance':
+                return val;
+            default:
+                return 'balanced';
+        }
+    }
+    updateSSSResolvedSettings() {
+        const source = SSS_QUALITY_PRESET_SETTINGS[this._sssQualityPreset];
+        this._sssResolvedSettings.halfRes = source.halfRes;
+        this._sssResolvedSettings.blurKernelSize = source.blurKernelSize;
+        this._sssResolvedSettings.blurStdDev = source.blurStdDev;
+        this._sssResolvedSettings.blurDepthCutoff = source.blurDepthCutoff;
+        this._sssResolvedSettings.normalCutoff = source.normalCutoff;
+    }
     /**
    * Renders a scene
    * @param scene - The scene to be rendered
@@ -1034,7 +1227,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
    */ render(scene) {
         const device = getDevice();
         //this.updatePostProcessing(device);
-        const useMotionVector = (this.TAA || this.motionBlur) && device.type !== 'webgl';
+        const useMotionVector = (this.TAA || this.motionBlur || this.SSR && this.ssrTemporal) && device.type !== 'webgl';
         const useTAA = useMotionVector && this.TAA;
         scene.dispatchEvent('startrender', scene, this, this._compositor);
         if (useMotionVector) {
@@ -1135,6 +1328,18 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
     /** @internal */ get prevPosition() {
         return this._prevPosition;
     }
+    /**
+   * Gets the camera history resource manager for temporal effects.
+   */ getHistoryResourceManager() {
+        return Camera._historyResourceManager.get(this) ?? null;
+    }
+    /**
+   * Sets the camera history resource manager for temporal effects.
+   *
+   * @internal
+   */ setHistoryResourceManager(manager) {
+        Camera._historyResourceManager.set(this, manager);
+    }
     /** @internal */ setController(controller) {
         if (this._controller !== controller) {
             if (controller && controller._getCamera() && controller._getCamera() !== this) {
@@ -1176,6 +1381,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
         this._postEffectFXAA.dispose();
         this._postEffectMotionBlur.dispose();
         this._postEffectSSAO.dispose();
+        this._postEffectSSS.dispose();
         this._postEffectSSR.dispose();
         this._postEffectTAA.dispose();
         this._postEffectTonemap.dispose();