import defaultValue from "../../Core/defaultValue.js"; import defined from "../../Core/defined.js"; import DeveloperError from "../../Core/DeveloperError.js"; import Event from "../../Core/Event.js"; import JulianDate from "../../Core/JulianDate.js"; import CesiumMath from "../../Core/Math.js"; import ModelAnimation from "./ModelAnimation.js"; import ModelAnimationLoop from ".././ModelAnimationLoop.js"; import ModelAnimationState from ".././ModelAnimationState.js"; /** *
* Access a model's animations {@link Model#activeAnimations}. Do not call the constructor directly *
* * A collection of active model animations. * * @alias ModelAnimationCollection * @internalConstructor * @class * * @see Model#activeAnimations */ function ModelAnimationCollection(model) { /** * The event fired when an animation is added to the collection. This can be used, for * example, to keep a UI in sync. * * @type {Event} * @default new Event() * * @example * model.activeAnimations.animationAdded.addEventListener(function(model, animation) { * console.log(`Animation added: ${animation.name}`); * }); */ this.animationAdded = new Event(); /** * The event fired when an animation is removed from the collection. This can be used, for * example, to keep a UI in sync. * * @type {Event} * @default new Event() * * @example * model.activeAnimations.animationRemoved.addEventListener(function(model, animation) { * console.log(`Animation removed: ${animation.name}`); * }); */ this.animationRemoved = new Event(); /** * When true, the animation will play even when the scene time is paused. However, * whether animation takes place will depend on the animationTime functions assigned * to the model's animations. By default, this is based on scene time, so models using * the default will not animate regardless of this setting. * * @type {boolean} * @default false */ this.animateWhilePaused = false; this._model = model; this._runtimeAnimations = []; this._previousTime = undefined; } Object.defineProperties(ModelAnimationCollection.prototype, { /** * The number of animations in the collection. * * @memberof ModelAnimationCollection.prototype * * @type {number} * @readonly */ length: { get: function () { return this._runtimeAnimations.length; }, }, /** * The model that owns this animation collection. * * @memberof ModelAnimationCollection.prototype * * @type {Model} * @readonly */ model: { get: function () { return this._model; }, }, }); function addAnimation(collection, animation, options) { const model = collection._model; const runtimeAnimation = new ModelAnimation(model, animation, options); collection._runtimeAnimations.push(runtimeAnimation); collection.animationAdded.raiseEvent(model, runtimeAnimation); return runtimeAnimation; } /** * Creates and adds an animation with the specified initial properties to the collection. *

* This raises the {@link ModelAnimationCollection#animationAdded} event so, for example, a UI can stay in sync. *

* * @param {object} options Object with the following properties: * @param {string} [options.name] The glTF animation name that identifies the animation. Must be defined if options.index is undefined. * @param {number} [options.index] The glTF animation index that identifies the animation. Must be defined if options.name is undefined. * @param {JulianDate} [options.startTime] The scene time to start playing the animation. When this is undefined, the animation starts at the next frame. * @param {number} [options.delay=0.0] The delay, in seconds, from startTime to start playing. This will only affect the animation if options.loop is ModelAnimationLoop.NONE. * @param {JulianDate} [options.stopTime] The scene time to stop playing the animation. When this is undefined, the animation is played for its full duration. * @param {boolean} [options.removeOnStop=false] When true, the animation is removed after it stops playing. This will only affect the animation if options.loop is ModelAnimationLoop.NONE. * @param {number} [options.multiplier=1.0] Values greater than 1.0 increase the speed that the animation is played relative to the scene clock speed; values less than 1.0 decrease the speed. * @param {boolean} [options.reverse=false] When true, the animation is played in reverse. * @param {ModelAnimationLoop} [options.loop=ModelAnimationLoop.NONE] Determines if and how the animation is looped. * @param {ModelAnimation.AnimationTimeCallback} [options.animationTime=undefined] If defined, computes the local animation time for this animation. * @returns {ModelAnimation} The animation that was added to the collection. * * @exception {DeveloperError} Animations are not loaded. Wait for the {@link Model#ready} to return trues. * @exception {DeveloperError} options.name must be a valid animation name. * @exception {DeveloperError} options.index must be a valid animation index. * @exception {DeveloperError} Either options.name or options.index must be defined. * @exception {DeveloperError} options.multiplier must be greater than zero. * * @example * // Example 1. Add an animation by name * model.activeAnimations.add({ * name : 'animation name' * }); * * @example * // Example 2. Add an animation by index * model.activeAnimations.add({ * index : 0 * }); * * @example * // Example 3. Add an animation and provide all properties and events * const startTime = Cesium.JulianDate.now(); * * const animation = model.activeAnimations.add({ * name : 'another animation name', * startTime : startTime, * delay : 0.0, // Play at startTime (default) * stopTime : Cesium.JulianDate.addSeconds(startTime, 4.0, new Cesium.JulianDate()), * removeOnStop : false, // Do not remove when animation stops (default) * multiplier : 2.0, // Play at double speed * reverse : true, // Play in reverse * loop : Cesium.ModelAnimationLoop.REPEAT // Loop the animation * }); * * animation.start.addEventListener(function(model, animation) { * console.log(`Animation started: ${animation.name}`); * }); * animation.update.addEventListener(function(model, animation, time) { * console.log(`Animation updated: ${animation.name}. glTF animation time: ${time}`); * }); * animation.stop.addEventListener(function(model, animation) { * console.log(`Animation stopped: ${animation.name}`); * }); */ ModelAnimationCollection.prototype.add = function (options) { options = defaultValue(options, defaultValue.EMPTY_OBJECT); const model = this._model; //>>includeStart('debug', pragmas.debug); if (!model.ready) { throw new DeveloperError( "Animations are not loaded. Wait for Model.ready to be true." ); } //>>includeEnd('debug'); const animations = model.sceneGraph.components.animations; //>>includeStart('debug', pragmas.debug); if (!defined(options.name) && !defined(options.index)) { throw new DeveloperError( "Either options.name or options.index must be defined." ); } if (defined(options.multiplier) && options.multiplier <= 0.0) { throw new DeveloperError("options.multiplier must be greater than zero."); } if ( defined(options.index) && (options.index >= animations.length || options.index < 0) ) { throw new DeveloperError("options.index must be a valid animation index."); } //>>includeEnd('debug'); let index = options.index; if (defined(index)) { return addAnimation(this, animations[index], options); } // Find the index of the animation with the given name const length = animations.length; for (let i = 0; i < length; ++i) { if (animations[i].name === options.name) { index = i; break; } } //>>includeStart('debug', pragmas.debug); if (!defined(index)) { throw new DeveloperError("options.name must be a valid animation name."); } //>>includeEnd('debug'); return addAnimation(this, animations[index], options); }; /** * Creates and adds animations with the specified initial properties to the collection * for all animations in the model. *

* This raises the {@link ModelAnimationCollection#animationAdded} event for each model so, for example, a UI can stay in sync. *

* * @param {object} [options] Object with the following properties: * @param {JulianDate} [options.startTime] The scene time to start playing the animations. When this is undefined, the animations starts at the next frame. * @param {number} [options.delay=0.0] The delay, in seconds, from startTime to start playing. This will only affect the animation if options.loop is ModelAnimationLoop.NONE. * @param {JulianDate} [options.stopTime] The scene time to stop playing the animations. When this is undefined, the animations are played for its full duration. * @param {boolean} [options.removeOnStop=false] When true, the animations are removed after they stop playing. This will only affect the animation if options.loop is ModelAnimationLoop.NONE. * @param {number} [options.multiplier=1.0] Values greater than 1.0 increase the speed that the animations play relative to the scene clock speed; values less than 1.0 decrease the speed. * @param {boolean} [options.reverse=false] When true, the animations are played in reverse. * @param {ModelAnimationLoop} [options.loop=ModelAnimationLoop.NONE] Determines if and how the animations are looped. * @param {ModelAnimation.AnimationTimeCallback} [options.animationTime=undefined] If defined, computes the local animation time for all of the animations. * @returns {ModelAnimation[]} An array of {@link ModelAnimation} objects, one for each animation added to the collection. If there are no glTF animations, the array is empty. * * @exception {DeveloperError} Animations are not loaded. Wait for the {@link Model#readyPromise} to resolve. * @exception {DeveloperError} options.multiplier must be greater than zero. * * @example * model.activeAnimations.addAll({ * multiplier : 0.5, // Play at half-speed * loop : Cesium.ModelAnimationLoop.REPEAT // Loop the animations * }); */ ModelAnimationCollection.prototype.addAll = function (options) { options = defaultValue(options, defaultValue.EMPTY_OBJECT); const model = this._model; //>>includeStart('debug', pragmas.debug); if (!model.ready) { throw new DeveloperError( "Animations are not loaded. Wait for Model.ready to be true." ); } if (defined(options.multiplier) && options.multiplier <= 0.0) { throw new DeveloperError("options.multiplier must be greater than zero."); } //>>includeEnd('debug'); const animations = model.sceneGraph.components.animations; const addedAnimations = []; const length = animations.length; for (let i = 0; i < length; ++i) { const animation = addAnimation(this, animations[i], options); addedAnimations.push(animation); } return addedAnimations; }; /** * Removes an animation from the collection. *

* This raises the {@link ModelAnimationCollection#animationRemoved} event so, for example, a UI can stay in sync. *

*

* An animation can also be implicitly removed from the collection by setting {@link ModelAnimationCollection#removeOnStop} to * true. The {@link ModelAnimationCollection#animationRemoved} event is still fired when the animation is removed. *

* * @param {ModelAnimation} runtimeAnimation The runtime animation to remove. * @returns {boolean} true if the animation was removed; false if the animation was not found in the collection. * * @example * const a = model.activeAnimations.add({ * name : 'animation name' * }); * model.activeAnimations.remove(a); // Returns true */ ModelAnimationCollection.prototype.remove = function (runtimeAnimation) { if (!defined(runtimeAnimation)) { return false; } const animations = this._runtimeAnimations; const i = animations.indexOf(runtimeAnimation); if (i !== -1) { animations.splice(i, 1); this.animationRemoved.raiseEvent(this._model, runtimeAnimation); return true; } return false; }; /** * Removes all animations from the collection. *

* This raises the {@link ModelAnimationCollection#animationRemoved} event for each * animation so, for example, a UI can stay in sync. *

*/ ModelAnimationCollection.prototype.removeAll = function () { const model = this._model; const animations = this._runtimeAnimations; const length = animations.length; this._runtimeAnimations.length = 0; for (let i = 0; i < length; ++i) { this.animationRemoved.raiseEvent(model, animations[i]); } }; /** * Determines whether this collection contains a given animation. * * @param {ModelAnimation} runtimeAnimation The runtime animation to check for. * @returns {boolean} true if this collection contains the animation, false otherwise. */ ModelAnimationCollection.prototype.contains = function (runtimeAnimation) { if (defined(runtimeAnimation)) { return this._runtimeAnimations.indexOf(runtimeAnimation) !== -1; } return false; }; /** * Returns the animation in the collection at the specified index. Indices are zero-based * and increase as animations are added. Removing an animation shifts all animations after * it to the left, changing their indices. This function is commonly used to iterate over * all the animations in the collection. * * @param {number} index The zero-based index of the animation. * @returns {ModelAnimation} The runtime animation at the specified index. * * @example * // Output the names of all the animations in the collection. * const animations = model.activeAnimations; * const length = animations.length; * for (let i = 0; i < length; ++i) { * console.log(animations.get(i).name); * } */ ModelAnimationCollection.prototype.get = function (index) { //>>includeStart('debug', pragmas.debug); if (!defined(index)) { throw new DeveloperError("index is required."); } if (index >= this._runtimeAnimations.length || index < 0) { throw new DeveloperError( "index must be valid within the range of the collection" ); } //>>includeEnd('debug'); return this._runtimeAnimations[index]; }; const animationsToRemove = []; function createAnimationRemovedFunction( modelAnimationCollection, model, animation ) { return function () { modelAnimationCollection.animationRemoved.raiseEvent(model, animation); }; } /** * Updates the runtime animations in this collection, removing any animations * that have stopped. * * @param {FrameState} frameState The current frame state. * @returns {boolean} true if an animation played during this update, false otherwise. * * @private */ ModelAnimationCollection.prototype.update = function (frameState) { const runtimeAnimations = this._runtimeAnimations; let length = runtimeAnimations.length; if (length === 0) { this._previousTime = undefined; return false; } if ( !this.animateWhilePaused && JulianDate.equals(frameState.time, this._previousTime) ) { return false; } this._previousTime = JulianDate.clone(frameState.time, this._previousTime); let animationOccurred = false; const sceneTime = frameState.time; const model = this._model; for (let i = 0; i < length; ++i) { const runtimeAnimation = runtimeAnimations[i]; if (!defined(runtimeAnimation._computedStartTime)) { runtimeAnimation._computedStartTime = JulianDate.addSeconds( defaultValue(runtimeAnimation.startTime, sceneTime), runtimeAnimation.delay, new JulianDate() ); } if (!defined(runtimeAnimation._duration)) { runtimeAnimation._duration = runtimeAnimation.localStopTime * (1.0 / runtimeAnimation.multiplier); } const startTime = runtimeAnimation._computedStartTime; const duration = runtimeAnimation._duration; const stopTime = runtimeAnimation.stopTime; const pastStartTime = JulianDate.lessThanOrEquals(startTime, sceneTime); const reachedStopTime = defined(stopTime) && JulianDate.greaterThan(sceneTime, stopTime); // [0.0, 1.0] normalized local animation time let delta = 0.0; if (duration !== 0.0) { const seconds = JulianDate.secondsDifference( reachedStopTime ? stopTime : sceneTime, startTime ); delta = defined(runtimeAnimation._animationTime) ? runtimeAnimation._animationTime(duration, seconds) : seconds / duration; } // Play animation if // * we are after the start time or the animation is being repeated, and // * before the end of the animation's duration or the animation is being repeated, and // * we did not reach a user-provided stop time. const repeat = runtimeAnimation.loop === ModelAnimationLoop.REPEAT || runtimeAnimation.loop === ModelAnimationLoop.MIRRORED_REPEAT; const play = (pastStartTime || (repeat && !defined(runtimeAnimation.startTime))) && (delta <= 1.0 || repeat) && !reachedStopTime; if (delta === runtimeAnimation._prevAnimationDelta) { const animationStopped = runtimeAnimation._state === ModelAnimationState.STOPPED; // no change to delta, and no change to the animation state means we can // skip the update this time around. if (play !== animationStopped) { continue; } } runtimeAnimation._prevAnimationDelta = delta; // If it IS, or WAS, animating... if (play || runtimeAnimation._state === ModelAnimationState.ANIMATING) { // ...transition from STOPPED to ANIMATING if (play && runtimeAnimation._state === ModelAnimationState.STOPPED) { runtimeAnimation._state = ModelAnimationState.ANIMATING; if (runtimeAnimation.start.numberOfListeners > 0) { frameState.afterRender.push(runtimeAnimation._raiseStartEvent); } } // Truncate to [0.0, 1.0] for repeating animations if (runtimeAnimation.loop === ModelAnimationLoop.REPEAT) { delta = delta - Math.floor(delta); } else if (runtimeAnimation.loop === ModelAnimationLoop.MIRRORED_REPEAT) { const floor = Math.floor(delta); const fract = delta - floor; // When odd use (1.0 - fract) to mirror repeat delta = floor % 2 === 1.0 ? 1.0 - fract : fract; } if (runtimeAnimation.reverse) { delta = 1.0 - delta; } let localAnimationTime = delta * duration * runtimeAnimation.multiplier; // Clamp in case floating-point roundoff goes outside the animation's first or last keyframe localAnimationTime = CesiumMath.clamp( localAnimationTime, runtimeAnimation.localStartTime, runtimeAnimation.localStopTime ); runtimeAnimation.animate(localAnimationTime); if (runtimeAnimation.update.numberOfListeners > 0) { runtimeAnimation._updateEventTime = localAnimationTime; frameState.afterRender.push(runtimeAnimation._raiseUpdateEvent); } animationOccurred = true; if (!play) { // transition from ANIMATING to STOPPED runtimeAnimation._state = ModelAnimationState.STOPPED; if (runtimeAnimation.stop.numberOfListeners > 0) { frameState.afterRender.push(runtimeAnimation._raiseStopEvent); } if (runtimeAnimation.removeOnStop) { animationsToRemove.push(runtimeAnimation); } } } } // Remove animations that stopped length = animationsToRemove.length; for (let j = 0; j < length; ++j) { const animationToRemove = animationsToRemove[j]; runtimeAnimations.splice(runtimeAnimations.indexOf(animationToRemove), 1); frameState.afterRender.push( createAnimationRemovedFunction(this, model, animationToRemove) ); } animationsToRemove.length = 0; return animationOccurred; }; export default ModelAnimationCollection;