@babylonjs/core 9.2.1 → 9.3.0

package/Particles/gpuParticleSystem.js

@@ -30,6 +30,15 @@ import { CreateConeEmitter, CreateCylinderEmitter, CreateDirectedCylinderEmitter
  * @see https://www.babylonjs-playground.com/#PU4WYI#4
  */
 export class GPUParticleSystem extends BaseParticleSystem {
+    /**
+     * Whether the particle buffer needs to store the initial emission direction.
+     * True when particles are not billboarded (they orient by direction) or when
+     * using stretched-local billboard mode (stretches along initial direction).
+     * @internal
+     */
+    get _needsInitialDirection() {
+        return !this._isBillboardBased || this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL;
+    }
     /**
      * Gets a boolean indicating if the GPU particles can be rendered on current browser
      */
@@ -286,6 +295,28 @@ export class GPUParticleSystem extends BaseParticleSystem {
         this._stopped = false;
         this._actualFrame = 0;
         this._preWarmDone = false;
+        // Reset emit gradient so it acts the same on every start
+        if (this._emitRateGradients) {
+            if (this._emitRateGradients.length > 0) {
+                this._currentEmitRateGradient = this._emitRateGradients[0];
+                this._currentEmitRate1 = this._currentEmitRateGradient.getFactor();
+                this._currentEmitRate2 = this._currentEmitRate1;
+            }
+            if (this._emitRateGradients.length > 1) {
+                this._currentEmitRate2 = this._emitRateGradients[1].getFactor();
+            }
+        }
+        // Reset start size gradient so it acts the same on every start
+        if (this._startSizeGradients) {
+            if (this._startSizeGradients.length > 0) {
+                this._currentStartSizeGradient = this._startSizeGradients[0];
+                this._currentStartSize1 = this._currentStartSizeGradient.getFactor();
+                this._currentStartSize2 = this._currentStartSize1;
+            }
+            if (this._startSizeGradients.length > 1) {
+                this._currentStartSize2 = this._startSizeGradients[1].getFactor();
+            }
+        }
         // Animations
         if (this.beginAnimationOnStart && this.animations && this.animations.length > 0 && this._scene) {
             this._scene.beginAnimation(this, this.beginAnimationFrom, this.beginAnimationTo, this.beginAnimationLoop);
@@ -584,35 +615,34 @@ export class GPUParticleSystem extends BaseParticleSystem {
         return this;
     }
     /**
-     * Not supported by GPUParticleSystem
-     * @returns the current particle system
-     */
-    addEmitRateGradient() {
-        // Do nothing as emit rate is not supported by GPUParticleSystem
-        return this;
-    }
-    /**
-     * Not supported by GPUParticleSystem
-     * @returns the current particle system
-     */
-    removeEmitRateGradient() {
-        // Do nothing as emit rate is not supported by GPUParticleSystem
-        return this;
-    }
-    /**
-     * Not supported by GPUParticleSystem
+     * Adds a new start size gradient (please note that this will only work if you set the targetStopDuration property)
+     * @param gradient defines the gradient to use (between 0 and 1)
+     * @param factor defines the start size factor to affect to the specified gradient
+     * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
      * @returns the current particle system
      */
-    addStartSizeGradient() {
-        // Do nothing as start size is not supported by GPUParticleSystem
+    addStartSizeGradient(gradient, factor, factor2) {
+        if (!this._startSizeGradients) {
+            this._startSizeGradients = [];
+        }
+        const hadGradients = this._startSizeGradients.length > 0;
+        this._addFactorGradient(this._startSizeGradients, gradient, factor, factor2);
+        if (!hadGradients) {
+            this._resetEffect();
+        }
         return this;
     }
     /**
-     * Not supported by GPUParticleSystem
+     * Remove a specific start size gradient
+     * @param gradient defines the gradient to remove
      * @returns the current particle system
      */
-    removeStartSizeGradient() {
-        // Do nothing as start size is not supported by GPUParticleSystem
+    removeStartSizeGradient(gradient) {
+        const hadGradients = this._startSizeGradients && this._startSizeGradients.length > 0;
+        this._removeFactorGradient(this._startSizeGradients, gradient);
+        if (hadGradients && (!this._startSizeGradients || this._startSizeGradients.length === 0)) {
+            this._resetEffect();
+        }
         return this;
     }
     /**
@@ -683,19 +713,34 @@ export class GPUParticleSystem extends BaseParticleSystem {
         //Not supported by GPUParticleSystem
     }
     /**
-     * Not supported by GPUParticleSystem
+     * Adds a new life time gradient (please note that this will only work if you set the targetStopDuration property)
+     * @param gradient defines the gradient to use (between 0 and 1)
+     * @param factor defines the life time factor to affect to the specified gradient
+     * @param factor2 defines an additional factor used to define a range ([factor, factor2]) with main value to pick the final value from
      * @returns the current particle system
      */
-    addLifeTimeGradient() {
-        //Not supported by GPUParticleSystem
+    addLifeTimeGradient(gradient, factor, factor2) {
+        if (!this._lifeTimeGradients) {
+            this._lifeTimeGradients = [];
+        }
+        const hadGradients = this._lifeTimeGradients.length > 0;
+        this._addFactorGradient(this._lifeTimeGradients, gradient, factor, factor2);
+        if (!hadGradients) {
+            this._resetEffect();
+        }
         return this;
     }
     /**
-     * Not supported by GPUParticleSystem
+     * Remove a specific life time gradient
+     * @param gradient defines the gradient to remove
      * @returns the current particle system
      */
-    removeLifeTimeGradient() {
-        //Not supported by GPUParticleSystem
+    removeLifeTimeGradient(gradient) {
+        const hadGradients = this._lifeTimeGradients && this._lifeTimeGradients.length > 0;
+        this._removeFactorGradient(this._lifeTimeGradients, gradient);
+        if (hadGradients && (!this._lifeTimeGradients || this._lifeTimeGradients.length === 0)) {
+            this._resetEffect();
+        }
         return this;
     }
     /**
@@ -729,6 +774,18 @@ export class GPUParticleSystem extends BaseParticleSystem {
         this._actualFrame = 0;
         this._rawTextureWidth = 256;
         this._rebuildingAfterContextLost = false;
+        // Emit rate gradient caching (mirrors ThinParticleSystem)
+        this._currentEmitRateGradient = null;
+        this._currentEmitRate1 = 0;
+        this._currentEmitRate2 = 0;
+        // Start size gradient caching (mirrors ThinParticleSystem)
+        this._currentStartSizeGradient = null;
+        this._currentStartSize1 = 0;
+        this._currentStartSize2 = 0;
+        this._startSizeGradientFactor = 1.0;
+        // Life time gradient factor range for per-particle randomization in shader
+        this._lifeTimeGradientMin = 1.0;
+        this._lifeTimeGradientMax = 1.0;
         /**
          * Specifies if the particle system should be serialized
          */
@@ -861,7 +918,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
         renderVertexBuffers["life"] = renderBuffer.createVertexBuffer("life", offset, 1, this._attributesStrideSize, true);
         offset += 1;
         offset += 4; // seed
-        if (this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED) {
+        if (this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED || this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL) {
             renderVertexBuffers["direction"] = renderBuffer.createVertexBuffer("direction", offset, 3, this._attributesStrideSize, true);
         }
         offset += 3; // direction
@@ -878,7 +935,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
             renderVertexBuffers["color"] = renderBuffer.createVertexBuffer("color", offset, 4, this._attributesStrideSize, true);
             offset += 4;
         }
-        if (!this._isBillboardBased) {
+        if (this._needsInitialDirection) {
             renderVertexBuffers["initialDirection"] = renderBuffer.createVertexBuffer("initialDirection", offset, 3, this._attributesStrideSize, true);
             offset += 3;
             if (this._platform.alignDataInBuffer) {
@@ -934,7 +991,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 this._attributesStrideSize += 1;
             }
         }
-        if (!this.isBillboardBased) {
+        if (this._needsInitialDirection) {
             this._attributesStrideSize += 3;
             if (this._platform.alignDataInBuffer) {
                 this._attributesStrideSize += 1;
@@ -1016,7 +1073,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 data.push(0.0);
                 offset += 4;
             }
-            if (!this.isBillboardBased) {
+            if (this._needsInitialDirection) {
                 // initialDirection
                 data.push(0.0);
                 data.push(0.0);
@@ -1081,6 +1138,12 @@ export class GPUParticleSystem extends BaseParticleSystem {
         this._sourceBuffer = this._buffer0;
         this._targetBuffer = this._buffer1;
     }
+    /**
+     * Forces the update effect to be recreated on the next render.
+     */
+    _resetEffect() {
+        this._cachedUpdateDefines = "";
+    }
     /** @internal */
     _recreateUpdateEffect() {
         this._createColorGradientTexture();
@@ -1091,7 +1154,11 @@ export class GPUParticleSystem extends BaseParticleSystem {
         this._createDragGradientTexture();
         let defines = this.particleEmitterType ? this.particleEmitterType.getEffectDefines() : "";
         if (this._isBillboardBased) {
-            defines += "\n#define BILLBOARD";
+            // Stretched local needs initialDirection in the buffer, which requires !BILLBOARD in the update shader.
+            // The render shader still uses BILLBOARD — that's handled separately in fillDefines().
+            if (this.billboardMode !== ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL) {
+                defines += "\n#define BILLBOARD";
+            }
         }
         if (this._colorGradientsTexture) {
             defines += "\n#define COLORGRADIENTS";
@@ -1133,6 +1200,12 @@ export class GPUParticleSystem extends BaseParticleSystem {
         if (this._emitRateControl) {
             defines += "\n#define EMITRATECTRL";
         }
+        if (this._startSizeGradients && this._startSizeGradients.length > 0) {
+            defines += "\n#define STARTSIZEGRADIENTS";
+        }
+        if (this._lifeTimeGradients && this._lifeTimeGradients.length > 0) {
+            defines += "\n#define LIFETIMEGRADIENTS";
+        }
         if (this._platform.isUpdateBufferCreated() && this._cachedUpdateDefines === defines) {
             return this._platform.isUpdateBufferReady();
         }
@@ -1172,7 +1245,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
     /**
      * @internal
      */
-    static _GetAttributeNamesOrOptions(hasColorGradients = false, isAnimationSheetEnabled = false, isBillboardBased = false, isBillboardStretched = false) {
+    static _GetAttributeNamesOrOptions(hasColorGradients = false, isAnimationSheetEnabled = false, isBillboardBased = false, isBillboardStretched = false, isBillboardStretchedLocal = false) {
         const attributeNamesOrOptions = [VertexBuffer.PositionKind, "age", "life", "size", "angle"];
         if (!hasColorGradients) {
             attributeNamesOrOptions.push(VertexBuffer.ColorKind);
@@ -1180,7 +1253,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
         if (isAnimationSheetEnabled) {
             attributeNamesOrOptions.push("cellIndex");
         }
-        if (!isBillboardBased) {
+        if (!isBillboardBased || isBillboardStretchedLocal) {
             attributeNamesOrOptions.push("initialDirection");
         }
         if (isBillboardStretched) {
@@ -1238,6 +1311,10 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 case ParticleSystem.BILLBOARDMODE_STRETCHED:
                     defines.push("#define BILLBOARDSTRETCHED");
                     break;
+                case ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL:
+                    defines.push("#define BILLBOARDSTRETCHED");
+                    defines.push("#define BILLBOARDSTRETCHED_LOCAL");
+                    break;
                 case ParticleSystem.BILLBOARDMODE_ALL:
                     defines.push("#define BILLBOARDMODE_ALL");
                     break;
@@ -1266,7 +1343,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
      * @param samplers Samplers array to fill
      */
     fillUniformsAttributesAndSamplerNames(uniforms, attributes, samplers) {
-        attributes.push(...GPUParticleSystem._GetAttributeNamesOrOptions(!!this._colorGradientsTexture, this._isAnimationSheetEnabled, this._isBillboardBased, this._isBillboardBased && this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED));
+        attributes.push(...GPUParticleSystem._GetAttributeNamesOrOptions(!!this._colorGradientsTexture, this._isAnimationSheetEnabled, this._isBillboardBased, this._isBillboardBased && (this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED || this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL), this.billboardMode === ParticleSystem.BILLBOARDMODE_STRETCHED_LOCAL));
         uniforms.push(...GPUParticleSystem._GetEffectCreationOptions(this._isAnimationSheetEnabled, this.useLogarithmicDepth, this.applyFog));
         samplers.push("diffuseSampler", "colorGradientSampler");
         if (this._imageProcessingConfiguration) {
@@ -1491,6 +1568,12 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 }
             }
         }
+        if (this._startSizeGradients && this._startSizeGradients.length > 0) {
+            this._updateBuffer.setFloat("startSizeGradientFactor", this._startSizeGradientFactor);
+        }
+        if (this._lifeTimeGradients && this._lifeTimeGradients.length > 0) {
+            this._updateBuffer.setFloat2("lifeTimeGradientRange", this._lifeTimeGradientMin, this._lifeTimeGradientMax);
+        }
         this._platform.updateParticleBuffer(this._targetIndex, this._targetBuffer, this._currentActiveCount);
         // Switch VAOs
         this._targetIndex++;
@@ -1535,6 +1618,48 @@ export class GPUParticleSystem extends BaseParticleSystem {
         }
         // Get everything ready to render
         this._initialize();
+        // Compute effective emit rate, applying emit rate gradients if set
+        let effectiveEmitRate = this.emitRate;
+        if (this._emitRateGradients && this._emitRateGradients.length > 0 && this.targetStopDuration) {
+            const ratio = this._actualFrame / this.targetStopDuration;
+            GradientHelper.GetCurrentGradient(ratio, this._emitRateGradients, (currentGradient, nextGradient, scale) => {
+                if (currentGradient !== this._currentEmitRateGradient) {
+                    this._currentEmitRate1 = this._currentEmitRate2;
+                    this._currentEmitRate2 = nextGradient.getFactor();
+                    this._currentEmitRateGradient = currentGradient;
+                }
+                effectiveEmitRate = Lerp(this._currentEmitRate1, this._currentEmitRate2, scale);
+            });
+        }
+        // Compute start size and life time gradient factors for shader uniforms
+        if (this.targetStopDuration) {
+            const ratio = this._actualFrame / this.targetStopDuration;
+            if (this._startSizeGradients && this._startSizeGradients.length > 0) {
+                GradientHelper.GetCurrentGradient(ratio, this._startSizeGradients, (currentGradient, nextGradient, scale) => {
+                    if (currentGradient !== this._currentStartSizeGradient) {
+                        this._currentStartSize1 = this._currentStartSize2;
+                        this._currentStartSize2 = nextGradient.getFactor();
+                        this._currentStartSizeGradient = currentGradient;
+                    }
+                    this._startSizeGradientFactor = Lerp(this._currentStartSize1, this._currentStartSize2, scale);
+                });
+            }
+            else {
+                this._startSizeGradientFactor = 1.0;
+            }
+            if (this._lifeTimeGradients && this._lifeTimeGradients.length > 0) {
+                GradientHelper.GetCurrentGradient(ratio, this._lifeTimeGradients, (currentGradient, nextGradient, scale) => {
+                    const current = currentGradient;
+                    const next = nextGradient;
+                    this._lifeTimeGradientMin = Lerp(current.factor1, next.factor1, scale);
+                    this._lifeTimeGradientMax = Lerp(current.factor2 ?? current.factor1, next.factor2 ?? next.factor1, scale);
+                });
+            }
+            else {
+                this._lifeTimeGradientMin = 1.0;
+                this._lifeTimeGradientMax = 1.0;
+            }
+        }
         if (this._emitRateControl) {
             // Emit-rate-controlled mode: limits active particles to ~emitRate * maxLifeTime,
             // matching CPU particle behavior with circular buffer recycling.
@@ -1544,7 +1669,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 this.manualEmitCount = 0;
             }
             else if (!this._stopped) {
-                this._accumulatedCount += this.emitRate * this._timeDelta;
+                this._accumulatedCount += effectiveEmitRate * this._timeDelta;
             }
             // Convert accumulated fractional count into whole particles to emit this frame.
             // The fractional remainder carries over to the next frame.
@@ -1559,7 +1684,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
             // When emitRate is 0 but manualEmitCount is used, the rate-based steady state
             // would be 0, blocking buffer growth. Use newParticles as a floor so manual
             // emissions can always allocate slots.
-            const steadyStateCount = Math.min(Math.max(Math.ceil(this.emitRate * this.maxLifeTime), newParticles), this._maxActiveParticleCount);
+            const steadyStateCount = Math.min(Math.max(Math.ceil(effectiveEmitRate * this.maxLifeTime), newParticles), this._maxActiveParticleCount);
             // During ramp-up, grow the active buffer size by adding new slots.
             // Once _currentActiveCount reaches steadyStateCount, no new slots are added —
             // existing slots are recycled instead (handled by _emitIndex below).
@@ -1588,7 +1713,7 @@ export class GPUParticleSystem extends BaseParticleSystem {
                 this.manualEmitCount = 0;
             }
             else {
-                this._accumulatedCount += this.emitRate * this._timeDelta;
+                this._accumulatedCount += effectiveEmitRate * this._timeDelta;
             }
             if (this._accumulatedCount >= 1) {
                 const intPart = this._accumulatedCount | 0;