@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/camera/camera.js

@@ -1,12 +1,11 @@
-import { halton23, Matrix4x4, Vector4, DEPTH_CLEAR_VALUE, DRef, Vector2, REVERSE_Z, Vector3, Ray, Frustum } from '@zephyr3d/base';
+import { halton23, Matrix4x4, Vector4, DEPTH_CLEAR_VALUE, DRef, Vector2, DEBUG_VIEWS, REVERSE_Z, Vector3, Ray, Frustum } from '@zephyr3d/base';
 import { SceneNode } from '../scene/scene_node.js';
 import { Compositor } from '../posteffect/compositor.js';
 import { TAA } from '../posteffect/taa.js';
 import { SSGI } from '../posteffect/ssgi.js';
 import { SSR } from '../posteffect/ssr.js';
 import { SSS } from '../posteffect/sss.js';
-import { SkinSSS } from '../posteffect/skinsss.js';
-import { SubsurfaceProfile } from '../material/subsurfaceprofile.js';
+import { PostSSS } from '../posteffect/postsss.js';
 import { Tonemap } from '../posteffect/tonemap.js';
 import { FXAA } from '../posteffect/fxaa.js';
 import { Bloom } from '../posteffect/bloom.js';
@@ -20,6 +19,7 @@ import { WeightedBlendedOIT } from '../render/weightedblended_oit.js';
 import { DualDepthPeelingOIT } from '../render/dualdepthpeeling_oit.js';
 import { RGHistoryResources } from '../render/rendergraph/history_resources.js';
 import { calculateEV100, calculatePhysicalExposure } from '../utility/physical.js';
+import { checkDebugViews } from '../render/debug_views.js';
 
 const SSGI_QUALITY_PRESET_SETTINGS = {
     quality: {
@@ -123,9 +123,13 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     /** @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 Scale of mesh level of detail screen sizes. */ _lodDistanceScale;
+    /** @internal Whether meshes are drawn as wireframes in this view. */ _wireframe;
+    /** @internal Whether meshes are colored by their level of detail in this view. */ _lodColoration;
     /** @internal Hi-Z acceleration enable (primarily for SSR). */ _HiZ;
     _HiZNearest;
     /** @internal Screen-space shadow mask enable (Forward+ deferred shadows). */ _screenSpaceShadowMask;
+    /** @internal */ _contactShadows;
     /** @internal If true, a float point backbuffer will be used. The default value is true */ _HDR;
     /** @internal Tonemap enable flag (via post effect). */ _toneMap;
     /** @internal Tonemap post effect reference. */ _postEffectTonemap;
@@ -200,19 +204,8 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     /** @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 Skin SSS enable flag (via post effect). */ _skinSSS;
-    /** @internal Skin SSS post effect reference. */ _postEffectSkinSSS;
-    /** @internal Skin SSS final blend strength. */ _skinSSSStrength;
-    /** @internal Skin SSS mask opacity bias. */ _skinSSSOpacity;
-    /** @internal Skin SSS maximum blur tap spacing in pixels. */ _skinSSSSampleStep;
-    /** @internal Skin SSS world-space scatter radius. */ _skinSSSScatterRadius;
-    /** @internal Skin SSS smoothing ("beauty filter") amount. */ _skinSSSSmoothness;
-    /** @internal Skin SSS depth rejection scale. */ _skinSSSDepthScale;
-    /** @internal Skin SSS blurred multiplier boost. */ _skinSSSColorBoost;
-    _skinSSSGlow;
-    _skinSSSProfilePreset;
-    _skinSSSProfile;
-    _skinSSSScatterTint;
+    /** @internal Skin SSS post effect reference. */ _postEffectPostSSS;
+    _SSSDebugOutput;
     /** @internal SSAO enable flag (via post effect). */ _SSAO;
     /** @internal SSAO post effect reference. */ _postEffectSSAO;
     /** @internal SSAO scale (sampling radius multiplier). */ _SSAOOcclusionRadius;
@@ -274,6 +267,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         this._HiZ = false;
         this._HiZNearest = false;
         this._screenSpaceShadowMask = true;
+        this._contactShadows = true;
         this._HDR = true;
         this._toneMap = true;
         this._postEffectTonemap = new DRef();
@@ -359,19 +353,8 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         };
         this.updateSSSResolvedSettings();
         this._sssDebugView = 'none';
-        this._skinSSS = false;
-        this._postEffectSkinSSS = new DRef();
-        this._skinSSSStrength = 1;
-        this._skinSSSOpacity = 0.18;
-        this._skinSSSSampleStep = 2;
-        this._skinSSSScatterRadius = 0.02;
-        this._skinSSSSmoothness = 0;
-        this._skinSSSDepthScale = 80;
-        this._skinSSSColorBoost = 1;
-        this._skinSSSGlow = 0;
-        this._skinSSSProfilePreset = 'skin_default';
-        this._skinSSSProfile = null;
-        this._skinSSSScatterTint = new Vector4(1, 1, 1, 1);
+        this._postEffectPostSSS = new DRef();
+        this._SSSDebugOutput = 'none';
         this._SSAO = false;
         this._postEffectSSAO = new DRef();
         this._SSAOOcclusionRadius = 0.25;
@@ -380,6 +363,9 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         this._SSAOBlurDepthCutoff = 2;
         this._pickResult = null;
         this._commandBufferReuse = true;
+        this._lodDistanceScale = 1;
+        this._wireframe = false;
+        this._lodColoration = false;
         this._jitteredVPMatrix = new Matrix4x4();
         this._jitteredInvVPMatrix = new Matrix4x4();
         this._jitterValue = new Vector2(0, 0);
@@ -457,7 +443,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
    * Materials that query it - water's shoreline foam - turn it on by themselves,
    * the way a transmissive material turns on the scene colour copy, so this only
    * has to be set to force the channel on for something the renderer cannot see
-   * coming. Ignored on WebGL1, which has no pyramid at all.
+   * coming.
    */ get HiZNearest() {
         return this._HiZNearest;
     }
@@ -478,6 +464,18 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         this._screenSpaceShadowMask = !!val;
     }
     /**
+   * Whether lights with a non-zero {@link PunctualLight.contactShadowLength}
+   * trace contact shadows.
+   *
+   * Contact shadows are traced inside the screen-space shadow mask, so they
+   * also require {@link Camera.screenSpaceShadowMask}.
+   */ get contactShadows() {
+        return this._contactShadows;
+    }
+    set contactShadows(val) {
+        this._contactShadows = !!val;
+    }
+    /**
    * Render path used by the scene renderer.
    */ get renderPath() {
         return this._renderPath;
@@ -635,7 +633,8 @@ const SSS_QUALITY_PRESET_SETTINGS = {
    *
    * @remarks
    * See {@link Bloom.karisAverage}. On by default; costs a little halo reach in exchange for
-   * stability on high-frequency speculars.
+   * stability on high-frequency speculars. Legacy lighting only: physical lighting always averages
+   * linearly.
    */ get bloomKarisAverage() {
         return this._bloomKarisAverage;
     }
@@ -920,7 +919,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this.invalidateSSGIHistory();
         }
     }
-    /** Pixel stride used by the WebGL linear ray marcher. */ get ssgiStride() {
+    /** Pixel stride of the linear ray marcher, used when no Hi-Z pyramid is available. */ get ssgiStride() {
         return this._ssgiStride;
     }
     set ssgiStride(val) {
@@ -940,7 +939,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this.invalidateSSGIHistory();
         }
     }
-    /** Whether SSGI temporal accumulation is enabled. Has no effect on WebGL1, which has no motion vectors. */ get ssgiTemporal() {
+    /** Whether SSGI temporal accumulation is enabled. */ get ssgiTemporal() {
         return this._ssgiTemporal;
     }
     set ssgiTemporal(val) {
@@ -1146,143 +1145,34 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     set sssDebugView(val) {
         this._sssDebugView = val ?? 'none';
     }
-    /** Gets whether the dedicated Skin SSS post effect is enabled. */ get skinSSS() {
-        return this._postEffectSkinSSS.get().enabled;
-    }
-    set skinSSS(val) {
-        this._postEffectSkinSSS.get().enabled = !!val;
-    }
-    /** Final blend strength for the dedicated Skin SSS post effect. */ get skinSSSStrength() {
-        return this._skinSSSStrength;
-    }
-    set skinSSSStrength(val) {
-        this._skinSSSStrength = Math.max(0, val ?? 0);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().strength = this._skinSSSStrength;
-        }
-    }
-    /** Bias subtracted from the blurred skin mask before compositing. */ get skinSSSOpacity() {
-        return this._skinSSSOpacity;
-    }
-    set skinSSSOpacity(val) {
-        this._skinSSSOpacity = Math.max(0, Math.min(1, val ?? 0));
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().opacity = this._skinSSSOpacity;
-        }
-    }
-    /** Maximum pixel spacing between blur taps. Caps the projected scatter radius for close-ups. */ get skinSSSSampleStep() {
-        return this._skinSSSSampleStep;
-    }
-    set skinSSSSampleStep(val) {
-        this._skinSSSSampleStep = Math.max(0.25, val ?? 0.25);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().sampleStep = this._skinSSSSampleStep;
-        }
-    }
-    /** World-space scatter radius. The blur width shrinks with distance to keep this constant. */ get skinSSSScatterRadius() {
-        return this._skinSSSScatterRadius;
-    }
-    set skinSSSScatterRadius(val) {
-        this._skinSSSScatterRadius = Math.max(0, val ?? 0);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().scatterRadius = this._skinSSSScatterRadius;
-        }
-    }
-    /** Skin smoothing ("beauty filter") amount for the dedicated Skin SSS post effect. */ get skinSSSSmoothness() {
-        return this._skinSSSSmoothness;
-    }
-    set skinSSSSmoothness(val) {
-        this._skinSSSSmoothness = Math.max(0, Math.min(1, val ?? 0));
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().smoothness = this._skinSSSSmoothness;
-        }
-    }
-    /** Depth rejection scale. The reference shader uses 80. */ get skinSSSDepthScale() {
-        return this._skinSSSDepthScale;
-    }
-    set skinSSSDepthScale(val) {
-        this._skinSSSDepthScale = Math.max(0, val ?? 0);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().depthScale = this._skinSSSDepthScale;
-        }
-    }
-    /** Multiplier applied to the blurred skin lighting multiplier before compositing. */ get skinSSSColorBoost() {
-        return this._skinSSSColorBoost;
-    }
-    set skinSSSColorBoost(val) {
-        this._skinSSSColorBoost = Math.max(0, val ?? 0);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().colorBoost = this._skinSSSColorBoost;
-        }
-    }
-    /**
-   * Additive, deliberately non-conserving bleed for the Skin SSS post effect.
-   *
-   * @remarks
-   * 0 (the default) keeps the effect energy conserving: light added to the dark
-   * side of the terminator is light removed from the lit side. Raising it adds
-   * the diffused term again without subtracting anything, for skin that reads as
-   * lit from within; around 1 approximates the look the effect had before it
-   * conserved energy.
-   */ get skinSSSGlow() {
-        return this._skinSSSGlow;
-    }
-    set skinSSSGlow(val) {
-        this._skinSSSGlow = Math.max(0, val ?? 0);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().glow = this._skinSSSGlow;
-        }
-    }
     /**
-   * Subsurface profile preset driving the Skin SSS per-channel scatter radii.
+   * Switches the skin diffusion on or off for the coming frame.
    *
    * @remarks
-   * The ratio between the red, green and blue radii is what gives a scattering
-   * surface its character - red travels furthest in skin, which is the
-   * red-to-yellow gradient at the terminator. Switching presets changes that
-   * ratio, so `wax` and `jade` are the same code path rather than special cases;
-   * {@link Camera.skinSSSScatterRadius} still sets how far the light reaches.
+   * Driven by the render graph from whether the frame actually draws a skin
+   * material, not by the application: an effect with nothing to scatter would
+   * only cost a blit.
    *
-   * Applies to the whole pass. Per-material profiles need the profile-slot path
-   * used by {@link SSS} instead.
-   */ get skinSSSProfilePreset() {
-        return this._skinSSSProfilePreset;
-    }
-    set skinSSSProfilePreset(val) {
-        this._skinSSSProfilePreset = val ?? 'skin_default';
-        if (this._skinSSSProfile) {
-            this._skinSSSProfile.preset = this._skinSSSProfilePreset;
-        }
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().profile = this.getSkinSSSProfile();
-        }
-    }
-    /**
-   * The profile object backing {@link Camera.skinSSSProfilePreset}, created on
-   * first use so that cameras which never enable Skin SSS do not consume one of
-   * the 255 global profile slots.
    * @internal
-   */ getSkinSSSProfile() {
-        if (!this._skinSSSProfile) {
-            this._skinSSSProfile = new SubsurfaceProfile();
-            this._skinSSSProfile.preset = this._skinSSSProfilePreset;
+   */ setPostSSSActive(active) {
+        const effect = this._postEffectPostSSS.get();
+        if (effect) {
+            effect.enabled = active;
         }
-        return this._skinSSSProfile;
     }
     /**
-   * Tint applied to the light the Skin SSS post effect redistributes.
+   * Intermediate Skin SSS quantity to visualize instead of the shaded result.
    *
    * @remarks
-   * White (the default) leaves the effect energy conserving. Because it
-   * multiplies only the difference between the diffused and original diffuse, a
-   * warm tint colors the terminator without washing the whole surface.
-   */ get skinSSSScatterTint() {
-        return this._skinSSSScatterTint;
+   * `'none'` renders normally. Use this to tell an input problem from a kernel
+   * problem when the diffusion does not look right.
+   */ get SSSDebugOutput() {
+        return this._SSSDebugOutput;
     }
-    set skinSSSScatterTint(val) {
-        this._skinSSSScatterTint.set(val);
-        if (this._postEffectSkinSSS.get()) {
-            this._postEffectSkinSSS.get().scatterTint = this._skinSSSScatterTint;
+    set SSSDebugOutput(val) {
+        this._SSSDebugOutput = val ?? 'none';
+        if (this._postEffectPostSSS.get()) {
+            this._postEffectPostSSS.get().debugOutput = this._SSSDebugOutput;
         }
     }
     /** @internal */ get ssrParams() {
@@ -1350,6 +1240,41 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     set commandBufferReuse(val) {
         this._commandBufferReuse = !!val;
     }
+    /**
+   * Scale of the mesh level of detail switch sizes in this view: above 1 meshes switch to
+   * coarser levels closer to the camera, below 1 farther away. Default 1.
+   */ get lodDistanceScale() {
+        return this._lodDistanceScale;
+    }
+    set lodDistanceScale(val) {
+        this._lodDistanceScale = Math.max(0, Number(val) || 0);
+    }
+    /**
+   * Whether everything in this view is drawn as the edges of its triangles, at the level of detail
+   * in use, to inspect geometry; shadows and picking keep the triangles. A debug view, see
+   * DEBUG_VIEWS, not saved with the camera. Default false.
+   */ get wireframe() {
+        return DEBUG_VIEWS && this._wireframe;
+    }
+    set wireframe(val) {
+        if (val) {
+            checkDebugViews('Camera.wireframe');
+        }
+        this._wireframe = !!val;
+    }
+    /**
+   * Whether every mesh of this view is shaded in the color of the level of detail it is drawn at,
+   * white, red, green, blue, yellow, fuchsia, cyan and purple for levels 0 to 7. A debug view, not
+   * saved with the camera; meshes are not batched while it is on. Default false.
+   */ get lodColoration() {
+        return DEBUG_VIEWS && this._lodColoration;
+    }
+    set lodColoration(val) {
+        if (val) {
+            checkDebugViews('Camera.lodColoration');
+        }
+        this._lodColoration = !!val;
+    }
     /** Whether this camera is adapted to screen settins */ get adapted() {
         return this._adapted;
     }
@@ -1740,21 +1665,12 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectSSS.set(sss);
             this._compositor.appendPostEffect(sss);
         }
-        if (!this._postEffectSkinSSS.get()) {
-            const skinSSS = new SkinSSS();
-            skinSSS.enabled = false;
-            skinSSS.strength = this._skinSSSStrength;
-            skinSSS.opacity = this._skinSSSOpacity;
-            skinSSS.sampleStep = this._skinSSSSampleStep;
-            skinSSS.scatterRadius = this._skinSSSScatterRadius;
-            skinSSS.smoothness = this._skinSSSSmoothness;
-            skinSSS.depthScale = this._skinSSSDepthScale;
-            skinSSS.colorBoost = this._skinSSSColorBoost;
-            skinSSS.glow = this._skinSSSGlow;
-            skinSSS.profile = this.getSkinSSSProfile();
-            skinSSS.scatterTint = this._skinSSSScatterTint;
-            this._postEffectSkinSSS.set(skinSSS);
-            this._compositor.appendPostEffect(skinSSS);
+        if (!this._postEffectPostSSS.get()) {
+            const postSSS = new PostSSS();
+            postSSS.enabled = false;
+            postSSS.debugOutput = this._SSSDebugOutput;
+            this._postEffectPostSSS.set(postSSS);
+            this._compositor.appendPostEffect(postSSS);
         }
         if (!this._postEffectSSAO.get()) {
             const ssao = new SAO();
@@ -1977,9 +1893,19 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         return this._pickPosY;
     }
     /**
-   * Updates the controller state
-   */ updateController() {
-        this._controller?.update();
+   * Updates the controller state.
+   *
+   * The scene calls this for its main camera twice per frame, once per phase;
+   * the controller is updated only in the phase it declares. Called without a
+   * phase, the controller is updated unconditionally.
+   *
+   * @param deltaTime - Time since the last frame in seconds; defaults to the device's frame time.
+   * @param phase - Only update a controller whose `updatePhase` is this.
+   */ updateController(deltaTime, phase) {
+        const controller = this._controller;
+        if (controller && (!phase || controller.updatePhase === phase)) {
+            controller.update(deltaTime);
+        }
     }
     /**
    * Reset the controller
@@ -2077,7 +2003,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         this._postEffectMotionBlur.dispose();
         this._postEffectSSAO.dispose();
         this._postEffectSSS.dispose();
-        this._postEffectSkinSSS.dispose();
+        this._postEffectPostSSS.dispose();
         this._postEffectSSGI.dispose();
         this._postEffectSSR.dispose();
         this._postEffectTAA.dispose();