@babylonjs/core 9.4.1 → 9.5.1

package/Materials/PBR/openpbrMaterial.d.ts

@@ -180,6 +180,11 @@ export declare class OpenPBRMaterialDefines extends OpenPBRMaterialDefines_base
      * Number of samples to use for the fuzz IBL lighting calculations
      */
     FUZZ_IBL_SAMPLES: number;
+    /**
+     * Enables the 4-tap rotated-grid kernel for refractive background blur.
+     * When false, a single dithered sample is used instead.
+     */
+    REFRACTION_HIGH_QUALITY_BLUR: boolean;
     /**
      * Tells the shader to enable the fuzz layer
      */
@@ -205,6 +210,15 @@ export declare class OpenPBRMaterialDefines extends OpenPBRMaterialDefines_base
      * Enables the use of screen-space irradiance texture for scattering
      */
     USE_IRRADIANCE_TEXTURE_FOR_SCATTERING: boolean;
+    /**
+     * Number of samples used by the screen-space SSS convolution kernel.
+     */
+    SSS_SAMPLE_COUNT: number;
+    /**
+     * Indicates that the irradiance texture is from the legacy GeometryBufferRenderer.
+     * We use this to handle direct lights which don't render in the legacy GBuffer irradiance.
+     */
+    USE_IRRADIANCE_TEXTURE_FOR_SCATTERING_GBUFFER: boolean;
     /**
      * Enables transmission slab
      */
@@ -812,6 +826,20 @@ export declare class OpenPBRMaterial extends OpenPBRMaterialBase {
      */
     ambientOcclusionTexture: Nullable<BaseTexture>;
     private _ambientOcclusionTexture;
+    /** SSS convolution uses 8 samples. */
+    static readonly SSS_QUALITY_LOW = 0;
+    /** SSS convolution uses 16 samples (default). */
+    static readonly SSS_QUALITY_MEDIUM = 1;
+    /** SSS convolution uses 32 samples. */
+    static readonly SSS_QUALITY_HIGH = 2;
+    private _sssQuality;
+    /**
+     * Controls the sample count of the screen-space SSS convolution kernel.
+     * Use the SSS_QUALITY_LOW / MEDIUM / HIGH constants (8 / 16 / 32 samples).
+     * Higher quality reduces noise at the cost of GPU time. Default: MEDIUM.
+     */
+    get sssQuality(): number;
+    set sssQuality(value: number);
     private _sssIrradianceTexture;
     /**
      * Defines the irradiance texture used for subsurface scattering.
@@ -834,6 +862,12 @@ export declare class OpenPBRMaterial extends OpenPBRMaterialBase {
     set sssDepthTexture(value: Nullable<ThinTexture>);
     private _propertyList;
     private _uniformsList;
+    /**
+     * Flat array view of `_uniformsList`, populated once at construction. Used
+     * by the per-frame bind loop to avoid `Object.values()` allocation and
+     * closure creation on every submesh binding.
+     */
+    private _uniformsArray;
     private _samplersList;
     private _samplerDefines;
     private static _noiseTextures;
@@ -1175,6 +1209,14 @@ export declare class OpenPBRMaterial extends OpenPBRMaterialBase {
      */
     get backgroundRefractionTexture(): Nullable<BaseTexture>;
     set backgroundRefractionTexture(texture: Nullable<BaseTexture>);
+    private _refractionHighQualityBlur;
+    /**
+     * When true, uses a 4-tap rotated-grid kernel for refractive background blur,
+     * eliminating bilinear block artifacts at the cost of 3 extra texture samples.
+     * When false, a single dithered sample is used. Default: true.
+     */
+    get refractionHighQualityBlur(): boolean;
+    set refractionHighQualityBlur(value: boolean);
     /**
      * Force the shader to compute irradiance in the fragment shader in order to take normal mapping into account.
      * @internal

package/Materials/PBR/openpbrMaterial.js

@@ -1,7 +1,7 @@
 import { __decorate } from "../../tslib.es6.js";
 /* eslint-disable @typescript-eslint/naming-convention */
 import { serialize, expandToProperty, addAccessorsForMaterialProperty } from "../../Misc/decorators.js";
-import { GetEnvironmentBRDFTexture, GetEnvironmentFuzzBRDFTexture } from "../../Misc/brdfTextureTools.js";
+import { GetEnvironmentFuzzBRDFTexture, GetOpenPBREnvironmentBRDFTexture } from "../../Misc/brdfTextureTools.js";
 import { Color3 } from "../../Maths/math.color.js";
 import { ImageProcessingConfiguration } from "../imageProcessingConfiguration.js";
 import { Texture } from "../Textures/texture.js";
@@ -56,6 +56,13 @@ class Uniform {
     }
     constructor(name, componentNum) {
         this.linkedProperties = {};
+        /**
+         * Cached key of the first entry of `linkedProperties`, set when the first
+         * property is linked. Used by the per-frame bind loop to avoid an
+         * `Object.keys(linkedProperties)[0]` allocation when reading scalar
+         * uniforms.
+         */
+        this.firstLinkedKey = "";
         this.name = name;
         this.numComponents = componentNum;
     }
@@ -73,8 +80,11 @@ class Property {
      * @param targetUniformComponentNum The number of components in the target uniform. All properties that are
      * packed into the same uniform must agree on the size of the target uniform.
      * @param targetUniformComponentOffset The offset in the uniform where this property will be packed.
+     * @param requiredDefine Optional define name. When provided, the per-frame
+     *  bind loop will skip pushing the owning uniform to the UBO unless
+     *  `defines[requiredDefine]` is true.
      */
-    constructor(name, defaultValue, targetUniformName, targetUniformComponentNum, targetUniformComponentOffset = 0) {
+    constructor(name, defaultValue, targetUniformName, targetUniformComponentNum, targetUniformComponentOffset = 0, requiredDefine) {
         // public includeAlphaFromProp: string = "";
         /**
          * If not given a type, there will be no uniform defined for this property and
@@ -88,6 +98,7 @@ class Property {
         this.value = defaultValue;
         this.targetUniformComponentNum = targetUniformComponentNum;
         this.targetUniformComponentOffset = targetUniformComponentOffset;
+        this.requiredDefine = requiredDefine;
     }
     /**
      * Returns the number of components of the property based on its default value type.
@@ -217,6 +228,11 @@ export class OpenPBRMaterialDefines extends ImageProcessingDefinesMixin(OpenPBRM
          * Number of samples to use for the fuzz IBL lighting calculations
          */
         this.FUZZ_IBL_SAMPLES = 6;
+        /**
+         * Enables the 4-tap rotated-grid kernel for refractive background blur.
+         * When false, a single dithered sample is used instead.
+         */
+        this.REFRACTION_HIGH_QUALITY_BLUR = false;
         /**
          * Tells the shader to enable the fuzz layer
          */
@@ -242,6 +258,15 @@ export class OpenPBRMaterialDefines extends ImageProcessingDefinesMixin(OpenPBRM
          * Enables the use of screen-space irradiance texture for scattering
          */
         this.USE_IRRADIANCE_TEXTURE_FOR_SCATTERING = false;
+        /**
+         * Number of samples used by the screen-space SSS convolution kernel.
+         */
+        this.SSS_SAMPLE_COUNT = 16;
+        /**
+         * Indicates that the irradiance texture is from the legacy GeometryBufferRenderer.
+         * We use this to handle direct lights which don't render in the legacy GBuffer irradiance.
+         */
+        this.USE_IRRADIANCE_TEXTURE_FOR_SCATTERING_GBUFFER = false;
         /**
          * Enables transmission slab
          */
@@ -377,6 +402,20 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
     set geometryCoatTangentAngle(value) {
         this.geometryCoatTangent = new Vector2(Math.cos(value), Math.sin(value));
     }
+    /**
+     * Controls the sample count of the screen-space SSS convolution kernel.
+     * Use the SSS_QUALITY_LOW / MEDIUM / HIGH constants (8 / 16 / 32 samples).
+     * Higher quality reduces noise at the cost of GPU time. Default: MEDIUM.
+     */
+    get sssQuality() {
+        return this._sssQuality;
+    }
+    set sssQuality(value) {
+        if (this._sssQuality !== value) {
+            this._sssQuality = value;
+            this.markAsDirty(1);
+        }
+    }
     /**
      * Defines the irradiance texture used for subsurface scattering.
      * If it's not provided, the irradiance will be looked for in the scene.geometryBufferRenderer.
@@ -480,6 +519,20 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
         this._backgroundRefractionTexture = texture;
         this._markAllSubMeshesAsTexturesDirty();
     }
+    /**
+     * When true, uses a 4-tap rotated-grid kernel for refractive background blur,
+     * eliminating bilinear block artifacts at the cost of 3 extra texture samples.
+     * When false, a single dithered sample is used. Default: true.
+     */
+    get refractionHighQualityBlur() {
+        return this._refractionHighQualityBlur;
+    }
+    set refractionHighQualityBlur(value) {
+        if (this._refractionHighQualityBlur !== value) {
+            this._refractionHighQualityBlur = value;
+            this.markAsDirty(1);
+        }
+    }
     /**
      * Enables realtime filtering on the texture.
      */
@@ -554,14 +607,14 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
         this._transmissionDispersionScale = new Property("transmission_dispersion_scale", 0.0, "vTransmissionDispersionScale", 1, 0);
         this._transmissionDispersionScaleTexture = new Sampler("transmission_dispersion_scale", "transmissionDispersionScale", "TRANSMISSION_DISPERSION_SCALE");
         this._transmissionDispersionAbbeNumber = new Property("transmission_dispersion_abbe_number", 20.0, "vTransmissionDispersionAbbeNumber", 1, 0);
-        this._subsurfaceWeight = new Property("subsurface_weight", 0.0, "vSubsurfaceWeight", 1, 0);
+        this._subsurfaceWeight = new Property("subsurface_weight", 0.0, "vSubsurfaceWeight", 1, 0, "SUBSURFACE_SLAB");
         this._subsurfaceWeightTexture = new Sampler("subsurface_weight", "subsurfaceWeight", "SUBSURFACE_WEIGHT");
-        this._subsurfaceColor = new Property("subsurface_color", new Color3(0.8, 0.8, 0.8), "vSubsurfaceColor", 3, 0);
+        this._subsurfaceColor = new Property("subsurface_color", new Color3(0.8, 0.8, 0.8), "vSubsurfaceColor", 3, 0, "SUBSURFACE_SLAB");
         this._subsurfaceColorTexture = new Sampler("subsurface_color", "subsurfaceColor", "SUBSURFACE_COLOR");
-        this._subsurfaceRadius = new Property("subsurface_radius", 1.0, "vSubsurfaceRadius", 1, 0);
-        this._subsurfaceRadiusScale = new Property("subsurface_radius_scale", new Color3(1, 0.5, 0.25), "vSubsurfaceRadiusScale", 3, 0);
+        this._subsurfaceRadius = new Property("subsurface_radius", 0.1, "vSubsurfaceRadius", 1, 0, "SUBSURFACE_SLAB");
+        this._subsurfaceRadiusScale = new Property("subsurface_radius_scale", new Color3(1, 0.5, 0.25), "vSubsurfaceRadiusScale", 3, 0, "SUBSURFACE_SLAB");
         this._subsurfaceRadiusScaleTexture = new Sampler("subsurface_radius_scale", "subsurfaceRadiusScale", "SUBSURFACE_RADIUS_SCALE");
-        this._subsurfaceScatterAnisotropy = new Property("subsurface_scatter_anisotropy", 0.0, "vSubsurfaceScatterAnisotropy", 1, 0);
+        this._subsurfaceScatterAnisotropy = new Property("subsurface_scatter_anisotropy", 0.0, "vSubsurfaceScatterAnisotropy", 1, 0, "SUBSURFACE_SLAB");
         this._coatWeight = new Property("coat_weight", 0.0, "vCoatWeight", 1, 0);
         this._coatWeightTexture = new Sampler("coat_weight", "coatWeight", "COAT_WEIGHT");
         this._coatColor = new Property("coat_color", Color3.White(), "vCoatColor", 3, 0);
@@ -605,9 +658,16 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
         this._thinFilmThicknessTexture = new Sampler("thin_film_thickness", "thinFilmThickness", "THIN_FILM_THICKNESS");
         this._thinFilmIor = new Property("thin_film_ior", 1.4, "vThinFilmIor", 1, 0);
         this._ambientOcclusionTexture = new Sampler("ambient_occlusion", "ambientOcclusion", "AMBIENT_OCCLUSION");
+        this._sssQuality = OpenPBRMaterial.SSS_QUALITY_MEDIUM;
         this._sssIrradianceTexture = null;
         this._sssDepthTexture = null;
         this._uniformsList = {};
+        /**
+         * Flat array view of `_uniformsList`, populated once at construction. Used
+         * by the per-frame bind loop to avoid `Object.values()` allocation and
+         * closure creation on every submesh binding.
+         */
+        this._uniformsArray = [];
         this._samplersList = {};
         this._samplerDefines = {};
         /**
@@ -909,6 +969,7 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
          */
         this._environmentFuzzBRDFTexture = null;
         this._backgroundRefractionTexture = null;
+        this._refractionHighQualityBlur = true;
         /**
          * Force the shader to compute irradiance in the fragment shader in order to take normal mapping into account.
          * @internal
@@ -995,7 +1056,7 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
             this._callbackPluginEventFillRenderTargetTextures(this._eventInfo);
             return this._renderTargets;
         };
-        this._environmentBRDFTexture = GetEnvironmentBRDFTexture(this.getScene());
+        this._environmentBRDFTexture = GetOpenPBREnvironmentBRDFTexture(this.getScene());
         this._environmentFuzzBRDFTexture = GetEnvironmentFuzzBRDFTexture(this.getScene());
         this.prePassConfiguration = new PrePassConfiguration();
         // Build the internal property list that can be used to generate and update the uniform buffer
@@ -1014,13 +1075,23 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
             let uniform = this._uniformsList[prop.targetUniformName];
             if (!uniform) {
                 uniform = new Uniform(prop.targetUniformName, prop.targetUniformComponentNum);
+                uniform.requiredDefine = prop.requiredDefine;
                 this._uniformsList[prop.targetUniformName] = uniform;
             }
             else if (uniform.numComponents !== prop.targetUniformComponentNum) {
                 Logger.Error(`Uniform ${prop.targetUniformName} already exists of size ${uniform.numComponents}, but trying to set it to ${prop.targetUniformComponentNum}.`);
             }
+            else if (uniform.requiredDefine !== prop.requiredDefine) {
+                // Properties packed into the same uniform must share the same gating
+                // define, otherwise we cannot safely skip the per-frame UBO update.
+                uniform.requiredDefine = undefined;
+            }
+            if (uniform.firstLinkedKey === "") {
+                uniform.firstLinkedKey = prop.name;
+            }
             uniform.linkedProperties[prop.name] = prop;
         });
+        this._uniformsArray = Object.values(this._uniformsList);
         // Build the internal list of samplers
         this._samplersList = {};
         for (const key of Object.getOwnPropertyNames(this)) {
@@ -1505,7 +1576,7 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
                             BindTextureMatrix(sampler.value, ubo, sampler.samplerPrefix);
                         }
                     }
-                    if (this.geometryNormalTexture) {
+                    if (this.geometryNormalTexture || this.geometryCoatNormalTexture) {
                         if (scene._mirroredCameraPosition) {
                             ubo.updateFloat2("vTangentSpaceParams", this._invertNormalMapX ? 1.0 : -1.0, this._invertNormalMapY ? 1.0 : -1.0);
                         }
@@ -1519,7 +1590,16 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
                 if (this.pointsCloud) {
                     ubo.updateFloat("pointSize", this.pointSize);
                 }
-                Object.values(this._uniformsList).forEach((uniform) => {
+                const uniformsArray = this._uniformsArray;
+                for (let i = 0, len = uniformsArray.length; i < len; i++) {
+                    const uniform = uniformsArray[i];
+                    // Skip uniforms whose define is currently inactive. The shader only
+                    // reads them inside the same #ifdef block, so the UBO bytes can stay
+                    // stale. The full update will happen on the next bind once the
+                    // define becomes active again.
+                    if (uniform.requiredDefine !== undefined && !defines[uniform.requiredDefine]) {
+                        continue;
+                    }
                     // If the property actually defines a uniform, update it.
                     if (uniform.numComponents === 4) {
                         uniform.populateVectorFromLinkedProperties(TmpVectors.Vector4[0]);
@@ -1534,9 +1614,9 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
                         ubo.updateFloat2(uniform.name, TmpVectors.Vector2[0].x, TmpVectors.Vector2[0].y);
                     }
                     else if (uniform.numComponents === 1) {
-                        ubo.updateFloat(uniform.name, uniform.linkedProperties[Object.keys(uniform.linkedProperties)[0]].value);
+                        ubo.updateFloat(uniform.name, uniform.linkedProperties[uniform.firstLinkedKey].value);
                     }
-                });
+                }
                 // Misc
                 this._lightingInfos.x = this.directIntensity;
                 this._lightingInfos.y = this.emissionLuminance;
@@ -1693,7 +1773,7 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
     dispose(forceDisposeEffect, forceDisposeTextures) {
         this._breakShaderLoadedCheck = true;
         if (forceDisposeTextures) {
-            if (this._environmentBRDFTexture && this.getScene().environmentBRDFTexture !== this._environmentBRDFTexture) {
+            if (this._environmentBRDFTexture && this.getScene().openPBREnvironmentBRDFTexture !== this._environmentBRDFTexture) {
                 this._environmentBRDFTexture.dispose();
             }
             if (this._environmentFuzzBRDFTexture && this.getScene().environmentFuzzBRDFTexture !== this._environmentFuzzBRDFTexture) {
@@ -2022,6 +2102,7 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
                 }
                 if (this.hasTransparency) {
                     defines.REFRACTED_BACKGROUND = !!this._backgroundRefractionTexture && MaterialFlags.RefractionTextureEnabled;
+                    defines.REFRACTION_HIGH_QUALITY_BLUR = this._refractionHighQualityBlur;
                     defines.REFRACTED_LIGHTS = true;
                     const radianceTexture = this._getRadianceTexture();
                     if (radianceTexture) {
@@ -2105,22 +2186,30 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
         defines.IRIDESCENCE = this.thinFilmWeight > 0.0;
         defines.DISPERSION = this.transmissionDispersionScale > 0.0;
         defines.SCATTERING = this.hasScattering;
+        const _sssSampleCounts = [8, 16, 32];
+        defines.SSS_SAMPLE_COUNT = _sssSampleCounts[this._sssQuality] ?? 16;
         defines.TRANSMISSION_SLAB = this.transmissionWeight > 0;
         defines.TRANSMISSION_SLAB_VOLUME = this.transmissionWeight > 0 && this.transmissionDepth > 0;
         defines.SUBSURFACE_SLAB = this.subsurfaceWeight > 0;
         // Determine whether we should use the prepass irradiance texture for scattering.
         // If this IS a prepass, we don't want to use the irradiance texture as it won't be available yet.
         if (!defines.PREPASS && (defines.SUBSURFACE_SLAB || defines.TRANSMISSION_SLAB_VOLUME)) {
+            let usingGBuffer = false;
             if (!this.sssIrradianceTexture && scene.geometryBufferRenderer) {
                 const irradianceTextureIndex = scene.geometryBufferRenderer.getTextureIndex(GeometryBufferRenderer.IRRADIANCE_TEXTURE_TYPE);
                 this.sssIrradianceTexture = scene.geometryBufferRenderer.getGBuffer().textures[irradianceTextureIndex];
+                usingGBuffer = true;
             }
             if (!this.sssDepthTexture && scene.geometryBufferRenderer) {
                 const depthIndex = scene.geometryBufferRenderer.getTextureIndex(GeometryBufferRenderer.SCREENSPACE_DEPTH_TEXTURE_TYPE);
                 this.sssDepthTexture = scene.geometryBufferRenderer.getGBuffer().textures[depthIndex];
+                usingGBuffer = true;
             }
             if (this.sssIrradianceTexture && this.sssDepthTexture) {
                 defines.USE_IRRADIANCE_TEXTURE_FOR_SCATTERING = true;
+                if (usingGBuffer) {
+                    defines.USE_IRRADIANCE_TEXTURE_FOR_SCATTERING_GBUFFER = true;
+                }
             }
         }
         defines.FUZZ = this.fuzzWeight > 0 && MaterialFlags.ReflectionTextureEnabled;
@@ -2156,6 +2245,12 @@ export class OpenPBRMaterial extends OpenPBRMaterialBase {
         this._callbackPluginEventPrepareDefines(this._eventInfo);
     }
 }
+/** SSS convolution uses 8 samples. */
+OpenPBRMaterial.SSS_QUALITY_LOW = 0;
+/** SSS convolution uses 16 samples (default). */
+OpenPBRMaterial.SSS_QUALITY_MEDIUM = 1;
+/** SSS convolution uses 32 samples. */
+OpenPBRMaterial.SSS_QUALITY_HIGH = 2;
 OpenPBRMaterial._noiseTextures = {};
 /**
  * Force all the PBR materials to compile to glsl even on WebGPU engines.