@zephyr3d/scene 0.9.25 → 0.9.26

package/dist/camera/camera.js

@@ -6,6 +6,7 @@ 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 { Tonemap } from '../posteffect/tonemap.js';
 import { FXAA } from '../posteffect/fxaa.js';
 import { Bloom } from '../posteffect/bloom.js';
@@ -89,7 +90,9 @@ const SSS_QUALITY_PRESET_SETTINGS = {
  *
  * @public
  */ class Camera extends SceneNode {
-    /** @internal Halton 2-3 sequence used for TAA jittering. */ static _halton23 = halton23(16);
+    /** @internal Halton 2-3 sequence used for TAA jittering. An 8-phase cycle
+   * repeats faster than the history accumulation window, so residual jitter
+   * ripple is attenuated further than with a 16-phase cycle. */ static _halton23 = halton23(8);
     /** @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;
@@ -141,6 +144,8 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     /** @internal Bloom threshold. */ _bloomThreshold;
     /** @internal Bloom threshold knee (soft thresholding). */ _bloomThresholdKnee;
     /** @internal Bloom intensity. */ _bloomIntensity;
+    /** @internal */ _bloomFilterRadius;
+    /** @internal */ _bloomKarisAverage;
     /** @internal Color adjustment enable flag (via post effect). */ _colorAdjustEnabled;
     /** @internal Color adjustment post effect reference. */ _postEffectColorAdjust;
     /** @internal Color adjustment saturation. */ _colorAdjustSaturation;
@@ -196,9 +201,15 @@ const SSS_QUALITY_PRESET_SETTINGS = {
     /** @internal Skin SSS post effect reference. */ _postEffectSkinSSS;
     /** @internal Skin SSS final blend strength. */ _skinSSSStrength;
     /** @internal Skin SSS mask opacity bias. */ _skinSSSOpacity;
-    /** @internal Skin SSS blur tap spacing in pixels. */ _skinSSSSampleStep;
+    /** @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 SSAO enable flag (via post effect). */ _SSAO;
     /** @internal SSAO post effect reference. */ _postEffectSSAO;
     /** @internal SSAO scale (sampling radius multiplier). */ _SSAOScale;
@@ -279,6 +290,8 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         this._bloomThreshold = 0.8;
         this._bloomThresholdKnee = 0;
         this._bloomIntensity = 1;
+        this._bloomFilterRadius = 1;
+        this._bloomKarisAverage = true;
         this._colorAdjustEnabled = false;
         this._postEffectColorAdjust = new DRef();
         this._colorAdjustSaturation = 1;
@@ -346,8 +359,14 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         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._SSAO = false;
         this._postEffectSSAO = new DRef();
         this._SSAOScale = 10;
@@ -542,6 +561,48 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectBloom.get().intensity = val;
         }
     }
+    /**
+   * Radius of the tent filter used to upsample the bloom pyramid, in source texels.
+   *
+   * @remarks
+   * See {@link Bloom.filterRadius}. 1 is the natural width; raising it softens the halo but past
+   * ~2 the tent's taps stop overlapping and a grid pattern reappears.
+   */ get bloomFilterRadius() {
+        return this._bloomFilterRadius;
+    }
+    set bloomFilterRadius(val) {
+        this._bloomFilterRadius = Math.max(0, val);
+        if (this._postEffectBloom.get()) {
+            this._postEffectBloom.get().filterRadius = this._bloomFilterRadius;
+        }
+    }
+    /**
+   * Whether the first bloom downsample uses the Karis average to suppress fireflies.
+   *
+   * @remarks
+   * See {@link Bloom.karisAverage}. On by default; costs a little halo reach in exchange for
+   * stability on high-frequency speculars.
+   */ get bloomKarisAverage() {
+        return this._bloomKarisAverage;
+    }
+    set bloomKarisAverage(val) {
+        this._bloomKarisAverage = !!val;
+        if (this._postEffectBloom.get()) {
+            this._postEffectBloom.get().karisAverage = this._bloomKarisAverage;
+        }
+    }
+    /**
+   * Whether tone mapping dithers its result before the 8-bit write.
+   *
+   * @remarks
+   * See {@link Tonemap.dither}. On by default; removes the banding shallow gradients such as bloom
+   * halos otherwise show once quantized. Turn it off for reproducible pixel captures.
+   */ get toneMapDither() {
+        return this._postEffectTonemap.get().dither;
+    }
+    set toneMapDither(val) {
+        this._postEffectTonemap.get().dither = !!val;
+    }
     /** Whether color adjustment is enabled. */ get colorAdjust() {
         return this._postEffectColorAdjust.get().enabled;
     }
@@ -825,7 +886,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this.invalidateSSGIHistory();
         }
     }
-    /** Whether WebGPU SSGI temporal accumulation is enabled. */ get ssgiTemporal() {
+    /** Whether SSGI temporal accumulation is enabled. Has no effect on WebGL1, which has no motion vectors. */ get ssgiTemporal() {
         return this._ssgiTemporal;
     }
     set ssgiTemporal(val) {
@@ -1055,7 +1116,7 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectSkinSSS.get().opacity = this._skinSSSOpacity;
         }
     }
-    /** Pixel spacing between blur taps. The reference shader uses 2. */ get skinSSSSampleStep() {
+    /** Maximum pixel spacing between blur taps. Caps the projected scatter radius for close-ups. */ get skinSSSSampleStep() {
         return this._skinSSSSampleStep;
     }
     set skinSSSSampleStep(val) {
@@ -1064,6 +1125,24 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             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;
     }
@@ -1082,6 +1161,76 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             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.
+   *
+   * @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.
+   *
+   * 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;
+        }
+        return this._skinSSSProfile;
+    }
+    /**
+   * Tint applied to the light the Skin SSS post effect redistributes.
+   *
+   * @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;
+    }
+    set skinSSSScatterTint(val) {
+        this._skinSSSScatterTint.set(val);
+        if (this._postEffectSkinSSS.get()) {
+            this._postEffectSkinSSS.get().scatterTint = this._skinSSSScatterTint;
+        }
+    }
     /** @internal */ get ssrParams() {
         return this._ssrParams;
     }
@@ -1546,8 +1695,13 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             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);
         }
@@ -1562,6 +1716,22 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectSSAO.set(ssao);
             this._compositor.appendPostEffect(ssao);
         }
+        // Every effect from here down shares the `end` layer, and appendPostEffect keeps insertion
+        // order within a layer, so the chain is TAA -> MotionBlur -> Bloom -> Tonemap -> ColorAdjust
+        // -> FXAA.
+        //
+        // The resolve leads because everything after it spreads energy -- Bloom spatially, MotionBlur
+        // along the velocity field -- and doing that to an unconverged frame turns the per-frame
+        // brightness swing of a sub-pixel specular highlight into a pulsing halo that no later pass can
+        // take back: the halo is low frequency, so the 3x3 neighbourhood TAA's history clip is built
+        // from pulses in step with it and admits the pulsing value as valid.
+        //
+        // The display chain sits in `end` rather than `transparent` specifically so that TAA does not
+        // have to move. Effects in the transparent layer read the linear depth from before the
+        // TransmissionDepth pass rewrites it with the full scene depth, and TAA dilates its velocities
+        // by that depth; run there, it reads opaque-only depth and picks up its neighbours' motion on
+        // any geometry the prepass never saw (alpha-blended hair, most visibly). None of the display
+        // effects read depth at all, so moving them instead is free.
         if (!this._postEffectTAA.get()) {
             const taa = new TAA();
             taa.enabled = false;
@@ -1575,6 +1745,23 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectMotionBlur.set(motionBlur);
             this._compositor.appendPostEffect(motionBlur);
         }
+        // Bloom is created before Tonemap because it must see scene-linear radiance:
+        // its threshold, its blur and its additive compose are all only meaningful in linear light.
+        // Running it after the ACES curve compressed everything into [0, 1] flattened the emitter range
+        // (a 100x brighter emitter produced the same halo) and made the compose hard-clip.
+        if (!this._postEffectBloom.get()) {
+            const bloom = new Bloom();
+            bloom.enabled = false;
+            bloom.maxDownsampleLevel = this._bloomMaxDownsampleLevels;
+            bloom.downsampleLimit = this._bloomDownsampleLimit;
+            bloom.threshold = this._bloomThreshold;
+            bloom.thresholdKnee = this._bloomThresholdKnee;
+            bloom.intensity = this._bloomIntensity;
+            bloom.filterRadius = this._bloomFilterRadius;
+            bloom.karisAverage = this._bloomKarisAverage;
+            this._postEffectBloom.set(bloom);
+            this._compositor.appendPostEffect(bloom);
+        }
         if (!this._postEffectTonemap.get()) {
             const tonemap = new Tonemap();
             tonemap.enabled = true;
@@ -1598,17 +1785,6 @@ const SSS_QUALITY_PRESET_SETTINGS = {
             this._postEffectFXAA.set(fxaa);
             this._compositor.appendPostEffect(fxaa);
         }
-        if (!this._postEffectBloom.get()) {
-            const bloom = new Bloom();
-            bloom.enabled = false;
-            bloom.maxDownsampleLevel = this._bloomMaxDownsampleLevels;
-            bloom.downsampleLimit = this._bloomDownsampleLimit;
-            bloom.threshold = this._bloomThreshold;
-            bloom.thresholdKnee = this._bloomThresholdKnee;
-            bloom.intensity = this._bloomIntensity;
-            this._postEffectBloom.set(bloom);
-            this._compositor.appendPostEffect(bloom);
-        }
     }
     /** @internal */ syncPostProcessingMode(scene) {
         const tonemap = this._postEffectTonemap.get();
@@ -1617,15 +1793,11 @@ const SSS_QUALITY_PRESET_SETTINGS = {
         // keeps its plain exposure multiplier.
         const usePhysicalExposure = scene.lightingMode === 'physical';
         tonemap.exposure = usePhysicalExposure ? 1 : this._tonemapExposure;
-        const bloom = this._postEffectBloom.get();
+        // The chain order no longer depends on the lighting mode: Bloom always precedes Tonemap, so it
+        // always works on scene-linear radiance. Only the SSGI histories still care about the switch.
         if (this._postProcessingLightingMode !== scene.lightingMode) {
             // SSGI histories contain scene-linear radiance. Never reuse them across lighting unit models.
             this.invalidateSSGIHistory();
-            if (scene.lightingMode === 'physical') {
-                this._compositor.movePostEffectBefore(bloom, tonemap);
-            } else {
-                this._compositor.movePostEffectAfter(bloom, this._postEffectFXAA.get());
-            }
             this._postProcessingLightingMode = scene.lightingMode;
         }
     }