@onerjs/core 8.56.3 → 9.0.0

package/Animations/animationGroup.pure.js

@@ -171,7 +171,13 @@ export class AnimationGroup {
         if (this._speedRatio === value) {
             return;
         }
+        if (this._animatables[0]) {
+            this._retainedCurrentFrame = this._animatables[0].masterFrame;
+        }
+        this._updateVirtualFrame();
         this._speedRatio = value;
+        this._virtualFrameStart = this._virtualFrame;
+        this._virtualFrameStartTime = this._scene._animationTime;
         for (let index = 0; index < this._animatables.length; index++) {
             const animatable = this._animatables[index];
             animatable.speedRatio = this._speedRatio;
@@ -334,6 +340,17 @@ export class AnimationGroup {
         this._to = -Number.MAX_VALUE;
         this._speedRatio = 1;
         this._loopAnimation = false;
+        this._virtualFrame = 0;
+        this._virtualFrameStart = 0;
+        this._virtualFrameStartTime = 0;
+        this._virtualFrameRate = 60;
+        this._virtualFrameDirection = 1;
+        this._virtualFrameInitial = 0;
+        this._virtualFrameEnd = 0;
+        this._virtualSamplingObserver = null;
+        this._usesVirtualSampling = false;
+        this._retainedCurrentFrame = 0;
+        this._isStopping = false;
         this._isAdditive = false;
         this._weight = -1;
         this._playOrder = 0;
@@ -492,10 +509,47 @@ export class AnimationGroup {
      * @returns the current animation group
      */
     start(loop = false, speedRatio = 1, from, to, isAdditive, predicate) {
+        return this._start(loop, speedRatio, from, to, isAdditive, false, predicate);
+    }
+    /**
+     * Starts all animations using an unbounded requested timeline mapped to the animation's
+     * effective keyframe range.
+     * @param loop defines if animations must loop
+     * @param speedRatio defines the ratio to apply to animation speed
+     * @param from defines the requested start frame
+     * @param to defines the requested end frame
+     * @param isAdditive defines the additive state for the resulting animatables
+     * @returns the current animation group
+     */
+    startWithVirtualTimeline(loop = false, speedRatio = 1, from, to, isAdditive) {
+        return this._start(loop, speedRatio, from, to, isAdditive, true);
+    }
+    _start(loop, speedRatio, from, to, isAdditive, useVirtualTimeline, predicate) {
         if (this._isStarted || this._targetedAnimations.length === 0) {
             return this;
         }
         this._loopAnimation = loop;
+        const effectiveFrom = from ?? this._from;
+        const effectiveTo = to ?? this._to;
+        this._virtualFrame = effectiveFrom;
+        this._virtualFrameStart = effectiveFrom;
+        this._virtualFrameStartTime = this._scene._animationTime;
+        this._virtualFrameRate = this._targetedAnimations[0]?.animation.framePerSecond ?? 60;
+        this._virtualFrameDirection = effectiveTo < effectiveFrom ? -1 : 1;
+        this._virtualFrameInitial = effectiveFrom;
+        this._virtualFrameEnd = effectiveTo;
+        const effectiveSamplingFrom = useVirtualTimeline ? this._mapVirtualFrame(effectiveFrom) : effectiveFrom;
+        const effectiveSamplingTo = useVirtualTimeline
+            ? Number.isFinite(effectiveTo)
+                ? this._mapVirtualFrame(effectiveTo)
+                : effectiveTo < effectiveFrom
+                    ? 0
+                    : this._to
+            : effectiveTo;
+        this._retainedCurrentFrame = effectiveSamplingFrom;
+        this._usesVirtualSampling = useVirtualTimeline && (effectiveSamplingFrom !== effectiveFrom || effectiveSamplingTo !== effectiveTo);
+        const samplingFrom = this._usesVirtualSampling ? (this._virtualFrameDirection > 0 ? 0 : this._to) : effectiveSamplingFrom;
+        const samplingTo = this._usesVirtualSampling ? (this._virtualFrameDirection > 0 ? this._to : 0) : effectiveSamplingTo;
         this._shouldStart = false;
         this._animationLoopCount = 0;
         this._animationLoopFlags.length = 0;
@@ -504,7 +558,7 @@ export class AnimationGroup {
             if (predicate && !predicate(targetedAnimation)) {
                 continue;
             }
-            const animatable = this._scene.beginDirectAnimation(targetedAnimation.target, [targetedAnimation.animation], from !== undefined ? from : this._from, to !== undefined ? to : this._to, loop, speedRatio, undefined, undefined, isAdditive !== undefined ? isAdditive : this._isAdditive);
+            const animatable = this._scene.beginDirectAnimation(targetedAnimation.target, [targetedAnimation.animation], samplingFrom, samplingTo, this._usesVirtualSampling || loop, speedRatio, undefined, undefined, isAdditive !== undefined ? isAdditive : this._isAdditive);
             animatable.weight = this._weight;
             animatable.playOrder = this._playOrder;
             animatable.onAnimationEnd = () => {
@@ -513,12 +567,20 @@ export class AnimationGroup {
             };
             this._processLoop(animatable, targetedAnimation, index);
             this._animatables.push(animatable);
+            if (this._usesVirtualSampling && this._isTargetRetainedByMask(animatable.target)) {
+                animatable.goToFrame(effectiveSamplingFrom);
+            }
         }
         this.syncWithMask();
         this._scene.sortActiveAnimatables();
         this._speedRatio = speedRatio;
         this._isStarted = true;
         this._isPaused = false;
+        if (this._usesVirtualSampling) {
+            this._virtualSamplingObserver = this._scene.onAfterAnimationsObservable.add(() => {
+                this._sampleVirtualTimeline();
+            });
+        }
         this.onAnimationGroupPlayObservable.notifyObservers(this);
         return this;
     }
@@ -530,6 +592,7 @@ export class AnimationGroup {
         if (!this._isStarted) {
             return this;
         }
+        this._updateVirtualFrame();
         this._isPaused = true;
         for (let index = 0; index < this._animatables.length; index++) {
             const animatable = this._animatables[index];
@@ -573,6 +636,13 @@ export class AnimationGroup {
             const animatable = this._animatables[index];
             animatable.reset();
         }
+        this._virtualFrame = this._usesVirtualSampling ? this._virtualFrameInitial : (this._animatables[0]?.fromFrame ?? 0);
+        this._virtualFrameStart = this._virtualFrame;
+        this._virtualFrameStartTime = this._scene._animationTime;
+        if (this._usesVirtualSampling) {
+            this._retainedCurrentFrame = this._mapVirtualFrame(this._virtualFrame);
+            this._goToFrameWithMask(this._retainedCurrentFrame);
+        }
         return this;
     }
     /**
@@ -588,6 +658,8 @@ export class AnimationGroup {
             animatable.restart();
         }
         this.syncWithMask();
+        this._virtualFrameStart = this._virtualFrame;
+        this._virtualFrameStartTime = this._scene._animationTime;
         this._isPaused = false;
         this.onAnimationGroupPlayObservable.notifyObservers(this);
         return this;
@@ -601,6 +673,12 @@ export class AnimationGroup {
         if (!this._isStarted) {
             return this;
         }
+        if (this._animatables[0]) {
+            this._retainedCurrentFrame = this._animatables[0].masterFrame;
+        }
+        this._updateVirtualFrame();
+        this._removeVirtualSamplingObserver();
+        this._isStopping = true;
         const list = this._animatables.slice();
         for (let index = 0; index < list.length; index++) {
             list[index].stop(undefined, undefined, true, skipOnAnimationEnd);
@@ -621,6 +699,8 @@ export class AnimationGroup {
         }
         this._scene._activeAnimatables.length = curIndex;
         this._isStarted = false;
+        this._isStopping = false;
+        this._usesVirtualSampling = false;
         return this;
     }
     /**
@@ -670,12 +750,113 @@ export class AnimationGroup {
         return this;
     }
     /**
-     * Helper to get the current frame. This will return 0 if the AnimationGroup is not running, and it might return wrong results if multiple animations are running in different frames.
+     * Helper to get the current frame. This returns 0 when the AnimationGroup is
+     * not running and might be inaccurate when animations use different frames.
      * @returns current animation frame.
      */
     getCurrentFrame() {
         return this.animatables[0]?.masterFrame || 0;
     }
+    /**
+     * Gets the last effective frame, retaining it after the group stops.
+     * @returns current or retained effective animation frame
+     */
+    getRetainedCurrentFrame() {
+        if (this.animatables[0]) {
+            this._retainedCurrentFrame = this.animatables[0].masterFrame;
+        }
+        return this._retainedCurrentFrame;
+    }
+    /**
+     * Gets the current frame on the unbounded timeline requested by the caller.
+     * Unlike {@link getCurrentFrame}, this value is not clamped or wrapped by the
+     * animation's keyframe range and is retained after the group stops.
+     * @returns the current virtual animation frame
+     */
+    getVirtualCurrentFrame() {
+        this._updateVirtualFrame();
+        return this._virtualFrame;
+    }
+    /**
+     * Returns whether the virtual timeline crossed the requested frame.
+     * @param frame virtual frame to test
+     * @returns true when the frame was reached in the playback direction
+     */
+    isVirtualFrameReached(frame) {
+        const current = this.getVirtualCurrentFrame();
+        return this._virtualFrameDirection > 0 ? current >= frame : current <= frame;
+    }
+    /**
+     * Returns whether a frame is inside the requested start/end interval.
+     * The end frame is excluded because natural completion takes precedence.
+     * @param frame virtual frame to test
+     * @returns true when a scheduled stop may occur at the frame
+     */
+    isValidVirtualStopFrame(frame) {
+        return this._virtualFrameDirection > 0
+            ? frame >= this._virtualFrameInitial && frame < this._virtualFrameEnd
+            : frame <= this._virtualFrameInitial && frame > this._virtualFrameEnd;
+    }
+    /**
+     * Snaps both retained playheads to an exact virtual timeline position.
+     * @param frame virtual frame to retain
+     */
+    setVirtualCurrentFrame(frame) {
+        this._virtualFrame = frame;
+        this._virtualFrameStart = frame;
+        this._virtualFrameStartTime = this._scene._animationTime;
+        this._retainedCurrentFrame = this._mapVirtualFrame(frame);
+        this._goToFrameWithMask(this._retainedCurrentFrame);
+    }
+    _updateVirtualFrame() {
+        if (!this._isStarted || this._isPaused) {
+            return;
+        }
+        const elapsedSeconds = (this._scene._animationTime - this._virtualFrameStartTime) / 1000;
+        this._virtualFrame = this._virtualFrameStart + elapsedSeconds * this._virtualFrameRate * this._speedRatio * this._virtualFrameDirection;
+    }
+    _sampleVirtualTimeline() {
+        this._updateVirtualFrame();
+        const reachedEnd = !this._loopAnimation &&
+            Number.isFinite(this._virtualFrameEnd) &&
+            (this._virtualFrameDirection > 0 ? this._virtualFrame >= this._virtualFrameEnd : this._virtualFrame <= this._virtualFrameEnd);
+        if (reachedEnd) {
+            this.setVirtualCurrentFrame(this._virtualFrameEnd);
+            this._removeVirtualSamplingObserver();
+            this.stop();
+            return;
+        }
+        this._retainedCurrentFrame = this._mapVirtualFrame(this._virtualFrame);
+        this._goToFrameWithMask(this._retainedCurrentFrame);
+    }
+    _goToFrameWithMask(frame) {
+        for (let index = 0; index < this._animatables.length; index++) {
+            const animatable = this._animatables[index];
+            if (this._isTargetRetainedByMask(animatable.target)) {
+                animatable.goToFrame(frame);
+            }
+        }
+    }
+    _isTargetRetainedByMask(target) {
+        return !this._mask || this._mask.disabled || this._mask.retainsTarget(target.name);
+    }
+    _removeVirtualSamplingObserver() {
+        if (this._virtualSamplingObserver) {
+            this._scene.onAfterAnimationsObservable.remove(this._virtualSamplingObserver);
+            this._virtualSamplingObserver = null;
+        }
+    }
+    _mapVirtualFrame(frame) {
+        const maximum = this._to;
+        if (maximum === 0) {
+            return 0;
+        }
+        if (!Number.isFinite(frame) || !Number.isFinite(maximum) || maximum < 0) {
+            return frame;
+        }
+        const iteration = frame > 0 ? Math.ceil((frame - maximum) / maximum) : Math.floor(frame / maximum);
+        return frame - iteration * maximum;
+    }
     /**
      * Dispose all associated resources
      */
@@ -704,6 +885,10 @@ export class AnimationGroup {
         this._isDisposed = true;
     }
     _checkAnimationGroupEnded(animatable, skipOnAnimationEnd = false) {
+        this._updateVirtualFrame();
+        if (!skipOnAnimationEnd && !this._isStopping) {
+            this._retainedCurrentFrame = animatable.masterFrame;
+        }
         // animatable should be taken out of the array
         const idx = this._animatables.indexOf(animatable);
         if (idx > -1) {
@@ -711,6 +896,10 @@ export class AnimationGroup {
         }
         // all animatables were removed? animation group ended!
         if (this._animatables.length === this._targetedAnimations.length - this._numActiveAnimatables) {
+            if (!skipOnAnimationEnd && !this._isStopping && Number.isFinite(this._virtualFrameEnd)) {
+                this._virtualFrame = this._virtualFrameEnd;
+                this._retainedCurrentFrame = this._mapVirtualFrame(this._virtualFrameEnd);
+            }
             this._isStarted = false;
             if (!skipOnAnimationEnd) {
                 this.onAnimationGroupEndObservable.notifyObservers(this);