@zephyr3d/scene 0.9.22 → 0.9.24

package/dist/material/mixins/pbr/common.js

@@ -25,12 +25,16 @@ import { mixinPBRBRDF } from './brdf.js';
     let FEATURE_IRIDESCENCE = 0;
     const EMISSIVE_COLOR_UNIFORM = S.defineInstanceUniform('emissiveColor', 'rgb', 'EmissiveColor');
     const EMISSIVE_STRENGTH_UNIFORM = S.defineInstanceUniform('emissiveStrength', 'float', 'EmissiveStrength');
+    const EMISSIVE_LUMINANCE_UNIFORM = S.defineInstanceUniform('emissiveLuminance', 'float', 'EmissiveLuminance');
+    const EMISSIVE_EXPOSURE_WEIGHT_UNIFORM = S.defineInstanceUniform('emissiveExposureWeight', 'float', 'EmissiveExposureWeight');
     const RECT_SPECULAR_SCALE_UNIFORM = S.defineInstanceUniform('rectSpecularScale', 'float', 'RectSpecularScale');
     const cls = class extends S {
         static pbrCommonMixed = true;
         _f0;
         _emissiveColor;
         _emissiveStrength;
+        _emissiveLuminance;
+        _emissiveExposureWeight;
         _occlusionStrength;
         _rectSpecularScale;
         _sheenFactor;
@@ -46,6 +50,11 @@ import { mixinPBRBRDF } from './brdf.js';
             this._occlusionStrength = 1;
             this._emissiveColor = new Vector3(0, 0, 0);
             this._emissiveStrength = 1;
+            // 1000 cd/m² is a lit-display-class emitter: clearly visible at interior exposures and still
+            // readable under the Sunny-16 default, unlike the 1 nit that `emissiveStrength` would mean.
+            this._emissiveLuminance = 1000;
+            // Default 1: emissive is a photometric luminance that follows camera exposure, like Filament.
+            this._emissiveExposureWeight = 1;
             this._rectSpecularScale = 1;
             this._sheenFactor = Vector4.zero();
             this._clearcoatFactor = new Vector4(0, 0, 1, 0);
@@ -70,6 +79,8 @@ import { mixinPBRBRDF } from './brdf.js';
             this.rectSpecularScale = other.rectSpecularScale;
             this.emissiveColor = other.emissiveColor;
             this.emissiveStrength = other.emissiveStrength;
+            this.emissiveLuminance = other.emissiveLuminance;
+            this.emissiveExposureWeight = other.emissiveExposureWeight;
             this.transmission = other.transmission;
             this.iridescence = other.iridescence;
             this.clearcoat = other.clearcoat;
@@ -171,7 +182,14 @@ import { mixinPBRBRDF } from './brdf.js';
                 this.uniformChanged();
             }
         }
-        get rectSpecularScale() {
+        /**
+     * Artistic multiplier on the rect-light specular term.
+     *
+     * @remarks
+     * 1 is neutral. Physical lighting normalizes the LTC integral by `1/(2*pi)`, which is the
+     * reference implementation's factor, so the default needs no calibration fudge there. Legacy
+     * keeps its historical weighting, where existing scenes may have tuned this value.
+     */ get rectSpecularScale() {
             return this._rectSpecularScale;
         }
         set rectSpecularScale(val) {
@@ -189,7 +207,15 @@ import { mixinPBRBRDF } from './brdf.js';
                 this.uniformChanged();
             }
         }
-        get emissiveStrength() {
+        /**
+     * Display-referred multiplier on {@link emissiveColor}, used by legacy lighting.
+     *
+     * @remarks
+     * This is the glTF authoring quantity (`KHR_materials_emissive_strength`) and is unitless: the
+     * product with {@link emissiveColor} lands directly in the render target. Physical lighting
+     * ignores it and uses {@link emissiveLuminance} instead, exactly as a light's unitless
+     * `intensity` gives way to its photometric counterpart.
+     */ get emissiveStrength() {
             return this._emissiveStrength;
         }
         set emissiveStrength(val) {
@@ -198,6 +224,67 @@ import { mixinPBRBRDF } from './brdf.js';
                 this.uniformChanged();
             }
         }
+        /**
+     * Multiplier on {@link emissiveColor} used by physical lighting. Legacy ignores it and uses
+     * {@link emissiveStrength}.
+     *
+     * @remarks
+     * The physical counterpart of {@link emissiveStrength}, mirroring how
+     * {@link DirectionalLight.illuminance} and {@link RectLight.luminance} shadow a light's unitless
+     * `intensity`. Keeping the two separate means switching {@link Scene.lightingMode} never
+     * reinterprets one authored number as two different quantities.
+     *
+     * **Its unit depends on {@link emissiveExposureWeight}**, because the shaded value is
+     * `emissiveColor * emissiveLuminance * mix(1, cameraExposure, emissiveExposureWeight)`:
+     *
+     * - At weight 1 (the constructor default) this is a photometric luminance in cd/m² (nit).
+     *   Anchors: an office display is 200-1000, a lit interior wall a few hundred, an overcast sky
+     *   ~2000, a neon sign 5,000-20,000. The default is 1000. Values around 1 are genuinely
+     *   invisible, since a sunlit white surface is ~25,000 cd/m².
+     * - At weight 0 the camera exposure cancels out and this is a display-referred multiplier
+     *   landing straight in the render target, so the useful range is around [0, 1] and 1 is very
+     *   bright. **Materials imported from glTF/FBX are in this state**: the importer writes weight 0
+     *   to preserve glTF's display-referred emissive, matching Filament's gltfio. Raise the weight
+     *   to 1 (and rescale to nits) to author such a material photometrically.
+     */ get emissiveLuminance() {
+            return this._emissiveLuminance;
+        }
+        set emissiveLuminance(val) {
+            const luminance = Math.max(0, val);
+            if (this._emissiveLuminance !== luminance) {
+                this._emissiveLuminance = luminance;
+                this.uniformChanged();
+            }
+        }
+        /**
+     * How strongly the emissive term follows the camera exposure, in [0, 1].
+     *
+     * @remarks
+     * Mirrors Filament's `emissive.w`: the emitter is attenuated by
+     * `mix(1, cameraExposure, emissiveExposureWeight)`.
+     *
+     * At 1, the constructor default, {@link emissiveLuminance} is read as the cd/m² value it claims
+     * to be: a neon sign keeps a constant real-world brightness and darkens as the camera stops
+     * down, like every other lit surface.
+     *
+     * At 0 the exposure cancels out of the product and {@link emissiveLuminance} becomes a
+     * display-referred multiplier instead — bright at 1, and completely unresponsive to aperture,
+     * shutter and ISO. That is what a UI-like overlay wants, and what glTF content expects, so
+     * {@link Model} writes 0 on every imported material (Filament's gltfio writes `emissive.w = 0`
+     * for the same reason). Keep this in mind when an imported emitter looks far brighter than an
+     * authored one at the same {@link emissiveLuminance}.
+     *
+     * Has no effect in legacy lighting, where the pre-exposure is always 1.
+     */ get emissiveExposureWeight() {
+            return this._emissiveExposureWeight;
+        }
+        set emissiveExposureWeight(val) {
+            const weight = Math.max(0, Math.min(1, val));
+            if (this._emissiveExposureWeight !== weight) {
+                this._emissiveExposureWeight = weight;
+                this.uniformChanged();
+            }
+        }
         get transmission() {
             return this.featureUsed(FEATURE_TRANSMISSION);
         }
@@ -265,6 +352,8 @@ import { mixinPBRBRDF } from './brdf.js';
             if (this.needFragmentColor() && this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING) {
                 scope.$outputs.zEmissiveColor = this.getInstancedUniform(scope, EMISSIVE_COLOR_UNIFORM);
                 scope.$outputs.zEmissiveStrength = this.getInstancedUniform(scope, EMISSIVE_STRENGTH_UNIFORM);
+                scope.$outputs.zEmissiveLuminance = this.getInstancedUniform(scope, EMISSIVE_LUMINANCE_UNIFORM);
+                scope.$outputs.zEmissiveExposureWeight = this.getInstancedUniform(scope, EMISSIVE_EXPOSURE_WEIGHT_UNIFORM);
                 scope.$outputs.zRectSpecularScale = this.getInstancedUniform(scope, RECT_SPECULAR_SCALE_UNIFORM);
             }
         }
@@ -276,6 +365,8 @@ import { mixinPBRBRDF } from './brdf.js';
                 if (!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING)) {
                     scope.zEmissiveColor = pb.vec3().uniform(2);
                     scope.zEmissiveStrength = pb.float().uniform(2);
+                    scope.zEmissiveLuminance = pb.float().uniform(2);
+                    scope.zEmissiveExposureWeight = pb.float().uniform(2);
                     scope.zRectSpecularScale = pb.float().uniform(2);
                 }
                 if (this.occlusionTexture) {
@@ -314,6 +405,8 @@ import { mixinPBRBRDF } from './brdf.js';
                 if (!(ctx.materialFlags & MaterialVaryingFlags.INSTANCING)) {
                     bindGroup.setValue('zEmissiveColor', this._emissiveColor);
                     bindGroup.setValue('zEmissiveStrength', this._emissiveStrength);
+                    bindGroup.setValue('zEmissiveLuminance', this._emissiveLuminance);
+                    bindGroup.setValue('zEmissiveExposureWeight', this._emissiveExposureWeight);
                     bindGroup.setValue('zRectSpecularScale', this._rectSpecularScale);
                 }
                 if (this.occlusionTexture) {
@@ -455,10 +548,18 @@ import { mixinPBRBRDF } from './brdf.js';
             const instancing = !!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING);
             return instancing ? scope.$inputs.zEmissiveColor : scope.zEmissiveColor;
         }
+        getEmissiveLuminance(scope) {
+            const instancing = !!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING);
+            return instancing ? scope.$inputs.zEmissiveLuminance : scope.zEmissiveLuminance;
+        }
         getEmissiveStrength(scope) {
             const instancing = !!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING);
             return instancing ? scope.$inputs.zEmissiveStrength : scope.zEmissiveStrength;
         }
+        getEmissiveExposureWeight(scope) {
+            const instancing = !!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING);
+            return instancing ? scope.$inputs.zEmissiveExposureWeight : scope.zEmissiveExposureWeight;
+        }
         getRectSpecularScale(scope) {
             const instancing = !!(this.drawContext.materialFlags & MaterialVaryingFlags.INSTANCING);
             return instancing ? scope.$inputs.zRectSpecularScale : scope.zRectSpecularScale;
@@ -471,11 +572,18 @@ import { mixinPBRBRDF } from './brdf.js';
         }
         calculateEmissiveColor(scope) {
             const pb = scope.$builder;
-            if (this.emissiveTexture) {
-                return pb.mul(this.sampleEmissiveTexture(scope).rgb, this.getEmissiveColor(scope), this.getEmissiveStrength(scope));
-            } else {
-                return pb.mul(this.getEmissiveColor(scope), this.getEmissiveStrength(scope));
-            }
+            // Legacy multiplies by the unitless emissiveStrength, physical by the cd/m² emissiveLuminance.
+            // Same split as a light's `intensity` vs `illuminance`/`luminance`, so switching lightingMode
+            // never reinterprets one authored number as two different quantities. Safe to branch here
+            // because emissive is only evaluated in the light pass, whose program hash includes
+            // lightingMode (see LightPass._getGlobalBindGroupHash).
+            const strength = this.drawContext.scene.lightingMode === 'physical' ? this.getEmissiveLuminance(scope) : this.getEmissiveStrength(scope);
+            const base = this.emissiveTexture ? pb.mul(this.sampleEmissiveTexture(scope).rgb, this.getEmissiveColor(scope), strength) : pb.mul(this.getEmissiveColor(scope), strength);
+            // Filament's emissive attenuation: mix(1, exposure, exposureWeight). Lights are pre-exposed on
+            // the CPU, but a material-authored emitter is not, so it is exposed here. In legacy the
+            // pre-exposure is 1, which leaves this a no-op regardless of the weight.
+            const attenuation = pb.mix(pb.float(1), ShaderHelper.getPreExposureUniform(scope), this.getEmissiveExposureWeight(scope));
+            return pb.mul(base, attenuation);
         }
         getSheenAlbedoScaling(scope, Ndot, sheenColor, sheenRoughness) {
             const pb = scope.$builder;
@@ -748,7 +856,10 @@ import { mixinPBRBRDF } from './brdf.js';
         directRectLight(scope, worldPos, normal, viewVec, commonData, posRange, axisX, axisY, colorIntensity, outColor) {
             const pb = scope.$builder;
             const that = this;
-            const funcName = 'Z_PBRRectLight';
+            const physical = this.drawContext.scene.lightingMode === 'physical';
+            // The two modes normalize the LTC integral differently, so they must not share a cached
+            // function body under one name.
+            const funcName = physical ? 'Z_PBRRectLightPhysical' : 'Z_PBRRectLight';
             const LUT_SIZE = 64;
             const LUT_SCALE = (LUT_SIZE - 1) / LUT_SIZE;
             const LUT_BIAS = 0.5 / LUT_SIZE;
@@ -939,8 +1050,17 @@ import { mixinPBRBRDF } from './brdf.js';
                         this.$l.lightColor = pb.mul(this.colorIntensity.rgb, this.colorIntensity.a, this.falloff);
                         this.$l.baseF0 = this.data.f0.rgb;
                         this.$l.rectSpecularScale = that.getRectSpecularScale(this);
-                        this.$l.specularLtc = pb.mul(this.spec, pb.add(pb.mul(this.baseF0, this.t2.x), pb.mul(pb.sub(pb.vec3(1), this.baseF0), this.t2.y)), this.data.specularWeight, this.rectSpecularScale);
-                        this.$l.diffuseLtc = pb.mul(this.diff, pb.div(this.data.diffuse.rgb, Math.PI));
+                        // Z_LTCEvaluateRect returns the raw edge sum; the reference implementation normalizes
+                        // it by 1/(2*pi). Physical applies that so the authored luminance (cd/m²) is
+                        // reproduced and diffuse/specular keep their correct ratio -- previously diffuse was
+                        // divided by pi and specular by nothing, leaving specular pi times too strong.
+                        //
+                        // Legacy deliberately keeps the historical (unnormalized) weighting: its rect
+                        // intensity is unitless and existing scenes are calibrated against it.
+                        const ltcNormalization = physical ? 1 / (2 * Math.PI) : 1;
+                        const diffuseNormalization = physical ? 1 / (2 * Math.PI) : 1 / Math.PI;
+                        this.$l.specularLtc = pb.mul(this.spec, pb.add(pb.mul(this.baseF0, this.t2.x), pb.mul(pb.sub(pb.vec3(1), this.baseF0), this.t2.y)), this.data.specularWeight, this.rectSpecularScale, ltcNormalization);
+                        this.$l.diffuseLtc = pb.mul(this.diff, pb.mul(this.data.diffuse.rgb, diffuseNormalization));
                         this.outColor = pb.add(this.outColor, pb.mul(this.lightColor, pb.add(this.diffuseLtc, this.specularLtc)));
                     });
                 });
@@ -1077,6 +1197,7 @@ import { mixinPBRBRDF } from './brdf.js';
             const pb = scope.$builder;
             const that = this;
             const ctx = that.drawContext;
+            const useReprojectedSSGI = !!(ctx.SSGI && ctx.SSGIIrradianceHistoryTexture && ctx.SSGISurfaceHistoryTexture && (ctx.device.type !== 'webgpu' || ctx.motionVectorTexture));
             const funcName = 'Z_PBRIndirectLighting';
             pb.func(funcName, [
                 pb.vec3('normal'),
@@ -1097,10 +1218,13 @@ import { mixinPBRBRDF } from './brdf.js';
                 const envLightSpecularStrength = ShaderHelper.getEnvLightSpecularStrength(this);
                 if (that.occlusionTexture) {
                     const occlusionSample = that.sampleOcclusionTexture(this).r;
-                    this.$l.occlusion = pb.mul(pb.add(pb.mul(this.zOcclusionStrength, pb.sub(occlusionSample, 1)), 1), envLightStrength);
+                    this.$l.ambientOcclusion = pb.add(pb.mul(this.zOcclusionStrength, pb.sub(occlusionSample, 1)), 1);
+                    this.$l.occlusion = pb.mul(this.ambientOcclusion, envLightStrength);
                 } else {
+                    this.$l.ambientOcclusion = pb.float(1);
                     this.$l.occlusion = envLightStrength;
                 }
+                this.$l.diffuseOcclusion = useReprojectedSSGI ? this.ambientOcclusion : this.occlusion;
                 this.$l.NoV = pb.clamp(pb.dot(this.normal, this.viewVec), 0.0001, 1);
                 if (that.sheen) {
                     this.$l.sheenLutSample = pb.clamp(pb.textureSampleLevel(this.zSheenLut, pb.clamp(pb.vec2(this.NoV, this.data.sheenRoughness), pb.vec2(0), pb.vec2(1)), 0), pb.vec4(0), pb.vec4(1));
@@ -1127,13 +1251,24 @@ import { mixinPBRBRDF } from './brdf.js';
                     }
                     if (outRoughness) {
                         this.outRoughness = pb.vec4(this.specularFactor /*this.data.f0.rgb*/ , this.data.roughness);
-                    } else if (ctx.env.light.envLight.hasRadiance()) {
+                    }
+                    // Skip specular IBL only when the roughness target exists, since SSR
+                    // is its only requester and resolves the reflection from it; adding
+                    // it here too would count it twice. `outRoughness` alone is not that
+                    // signal: SSGI requests the scene normal target and materials raise
+                    // the roughness and normal flags together, so an SSGI-only frame
+                    // wrote outRoughness with nobody to resolve the reflection, which
+                    // silently dropped specular highlights. Keyed on the flag rather
+                    // than ctx.SSR because the flag is part of the light pass shader
+                    // hash, so cached programs cannot outlive a change here.
+                    const ssrResolvesSpecular = !!(ctx.materialFlags & MaterialVaryingFlags.SCENE_STORE_ROUGHNESS);
+                    if (!ssrResolvesSpecular && ctx.env.light.envLight.hasRadiance()) {
                         this.$l.radiance = ctx.env.light.envLight.getRadiance(this, pb.reflect(pb.neg(this.viewVec), this.normal), this.data.roughness);
                         this.outColor = pb.add(this.outColor, pb.mul(this.radiance, this.specularFactor, envLightSpecularStrength));
                     }
                 }
                 if (ctx.env.light.envLight.hasIrradiance()) {
-                    this.$l.irradiance = ctx.env.light.envLight.getIrradiance(this, this.normal);
+                    this.$l.irradiance = ctx.env.light.envLight.getIrradiance(this, this.normal, ctx);
                     if (that.iridescence) {
                         this.$l.iridescenceF0Max = pb.vec3(pb.max(pb.max(this.data.iridescenceF0.r, this.data.iridescenceF0.g), this.data.iridescenceF0.b));
                         this.$l.mixedF0 = pb.mix(this.data.f0.rgb, this.iridescenceF0Max, this.data.iridescenceFactor.x);
@@ -1147,7 +1282,7 @@ import { mixinPBRBRDF } from './brdf.js';
                     this.$l.F_avg = pb.mul(pb.add(this.mixedF0, pb.div(pb.sub(pb.vec3(1), this.mixedF0), 21)), this.data.specularWeight);
                     this.$l.FmsEms = pb.div(pb.mul(this.FssEss, this.F_avg, this.Ems), pb.sub(pb.vec3(1), pb.mul(this.F_avg, this.Ems)));
                     this.$l.k_D = pb.mul(this.data.diffuse.rgb, pb.add(pb.sub(pb.vec3(1), this.FssEss), this.FmsEms));
-                    this.$l.iblDiffuse = pb.mul(pb.add(this.FmsEms, this.k_D), this.irradiance, this.occlusion);
+                    this.$l.iblDiffuse = pb.mul(pb.add(this.FmsEms, this.k_D), this.irradiance, this.diffuseOcclusion);
                     if (that.clearcoat) {
                         this.$if(pb.greaterThan(this.data.ccFactor.x, 0), function() {
                             this.iblDiffuse = pb.mul(this.iblDiffuse, pb.clamp(pb.sub(1, pb.mul(this.data.ccFresnel, this.data.ccFactor.x)), 0, 1));