import clone from '../Core/clone.js';
|
import defaultValue from '../Core/defaultValue.js';
|
import defined from '../Core/defined.js';
|
import DeveloperError from '../Core/DeveloperError.js';
|
import EasingFunction from '../Core/EasingFunction.js';
|
import getTimestamp from '../Core/getTimestamp.js';
|
import TimeConstants from '../Core/TimeConstants.js';
|
import TweenJS from '../ThirdParty/Tween.js';
|
|
/**
|
* A tween is an animation that interpolates the properties of two objects using an {@link EasingFunction}. Create
|
* one using {@link Scene#tweens} and {@link TweenCollection#add} and related add functions.
|
*
|
* @alias Tween
|
* @constructor
|
*
|
* @private
|
*/
|
function Tween(tweens, tweenjs, startObject, stopObject, duration, delay, easingFunction, update, complete, cancel) {
|
this._tweens = tweens;
|
this._tweenjs = tweenjs;
|
|
this._startObject = clone(startObject);
|
this._stopObject = clone(stopObject);
|
|
this._duration = duration;
|
this._delay = delay;
|
this._easingFunction = easingFunction;
|
|
this._update = update;
|
this._complete = complete;
|
|
/**
|
* The callback to call if the tween is canceled either because {@link Tween#cancelTween}
|
* was called or because the tween was removed from the collection.
|
*
|
* @type {TweenCollection~TweenCancelledCallback}
|
*/
|
this.cancel = cancel;
|
|
/**
|
* @private
|
*/
|
this.needsStart = true;
|
}
|
|
Object.defineProperties(Tween.prototype, {
|
/**
|
* An object with properties for initial values of the tween. The properties of this object are changed during the tween's animation.
|
* @memberof Tween.prototype
|
*
|
* @type {Object}
|
* @readonly
|
*/
|
startObject : {
|
get : function() {
|
return this._startObject;
|
}
|
},
|
|
/**
|
* An object with properties for the final values of the tween.
|
* @memberof Tween.prototype
|
*
|
* @type {Object}
|
* @readonly
|
*/
|
stopObject : {
|
get : function() {
|
return this._stopObject;
|
}
|
},
|
|
/**
|
* The duration, in seconds, for the tween. The tween is automatically removed from the collection when it stops.
|
* @memberof Tween.prototype
|
*
|
* @type {Number}
|
* @readonly
|
*/
|
duration : {
|
get : function() {
|
return this._duration;
|
}
|
},
|
|
/**
|
* The delay, in seconds, before the tween starts animating.
|
* @memberof Tween.prototype
|
*
|
* @type {Number}
|
* @readonly
|
*/
|
delay : {
|
get : function() {
|
return this._delay;
|
}
|
},
|
|
/**
|
* Determines the curve for animtion.
|
* @memberof Tween.prototype
|
*
|
* @type {EasingFunction}
|
* @readonly
|
*/
|
easingFunction : {
|
get : function() {
|
return this._easingFunction;
|
}
|
},
|
|
/**
|
* The callback to call at each animation update (usually tied to the a rendered frame).
|
* @memberof Tween.prototype
|
*
|
* @type {TweenCollection~TweenUpdateCallback}
|
* @readonly
|
*/
|
update : {
|
get : function() {
|
return this._update;
|
}
|
},
|
|
/**
|
* The callback to call when the tween finishes animating.
|
* @memberof Tween.prototype
|
*
|
* @type {TweenCollection~TweenCompleteCallback}
|
* @readonly
|
*/
|
complete : {
|
get : function() {
|
return this._complete;
|
}
|
},
|
|
/**
|
* @memberof Tween.prototype
|
*
|
* @private
|
*/
|
tweenjs : {
|
get : function() {
|
return this._tweenjs;
|
}
|
}
|
});
|
|
/**
|
* Cancels the tween calling the {@link Tween#cancel} callback if one exists. This
|
* has no effect if the tween finished or was already canceled.
|
*/
|
Tween.prototype.cancelTween = function() {
|
this._tweens.remove(this);
|
};
|
|
/**
|
* A collection of tweens for animating properties. Commonly accessed using {@link Scene#tweens}.
|
*
|
* @alias TweenCollection
|
* @constructor
|
*
|
* @private
|
*/
|
function TweenCollection() {
|
this._tweens = [];
|
}
|
|
Object.defineProperties(TweenCollection.prototype, {
|
/**
|
* The number of tweens in the collection.
|
* @memberof TweenCollection.prototype
|
*
|
* @type {Number}
|
* @readonly
|
*/
|
length : {
|
get : function() {
|
return this._tweens.length;
|
}
|
}
|
});
|
|
/**
|
* Creates a tween for animating between two sets of properties. The tween starts animating at the next call to {@link TweenCollection#update}, which
|
* is implicit when {@link Viewer} or {@link CesiumWidget} render the scene.
|
*
|
* @param {Object} [options] Object with the following properties:
|
* @param {Object} options.startObject An object with properties for initial values of the tween. The properties of this object are changed during the tween's animation.
|
* @param {Object} options.stopObject An object with properties for the final values of the tween.
|
* @param {Number} options.duration The duration, in seconds, for the tween. The tween is automatically removed from the collection when it stops.
|
* @param {Number} [options.delay=0.0] The delay, in seconds, before the tween starts animating.
|
* @param {EasingFunction} [options.easingFunction=EasingFunction.LINEAR_NONE] Determines the curve for animtion.
|
* @param {TweenCollection~TweenUpdateCallback} [options.update] The callback to call at each animation update (usually tied to the a rendered frame).
|
* @param {TweenCollection~TweenCompleteCallback} [options.complete] The callback to call when the tween finishes animating.
|
* @param {TweenCollection~TweenCancelledCallback} [options.cancel] The callback to call if the tween is canceled either because {@link Tween#cancelTween} was called or because the tween was removed from the collection.
|
* @returns {Tween} The tween.
|
*
|
* @exception {DeveloperError} options.duration must be positive.
|
*/
|
TweenCollection.prototype.add = function(options) {
|
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
|
|
//>>includeStart('debug', pragmas.debug);
|
if (!defined(options.startObject) || !defined(options.stopObject)) {
|
throw new DeveloperError('options.startObject and options.stopObject are required.');
|
}
|
|
if (!defined(options.duration) || options.duration < 0.0) {
|
throw new DeveloperError('options.duration is required and must be positive.');
|
}
|
//>>includeEnd('debug');
|
|
if (options.duration === 0.0) {
|
if (defined(options.complete)) {
|
options.complete();
|
}
|
return new Tween(this);
|
}
|
|
var duration = options.duration / TimeConstants.SECONDS_PER_MILLISECOND;
|
var delayInSeconds = defaultValue(options.delay, 0.0);
|
var delay = delayInSeconds / TimeConstants.SECONDS_PER_MILLISECOND;
|
var easingFunction = defaultValue(options.easingFunction, EasingFunction.LINEAR_NONE);
|
|
var value = options.startObject;
|
var tweenjs = new TweenJS.Tween(value);
|
tweenjs.to(clone(options.stopObject), duration);
|
tweenjs.delay(delay);
|
tweenjs.easing(easingFunction);
|
if (defined(options.update)) {
|
tweenjs.onUpdate(function() {
|
options.update(value);
|
});
|
}
|
tweenjs.onComplete(defaultValue(options.complete, null));
|
tweenjs.repeat(defaultValue(options._repeat, 0.0));
|
|
var tween = new Tween(this, tweenjs, options.startObject, options.stopObject, options.duration, delayInSeconds, easingFunction, options.update, options.complete, options.cancel);
|
this._tweens.push(tween);
|
return tween;
|
};
|
|
/**
|
* Creates a tween for animating a scalar property on the given object. The tween starts animating at the next call to {@link TweenCollection#update}, which
|
* is implicit when {@link Viewer} or {@link CesiumWidget} render the scene.
|
*
|
* @param {Object} [options] Object with the following properties:
|
* @param {Object} options.object The object containing the property to animate.
|
* @param {String} options.property The name of the property to animate.
|
* @param {Number} options.startValue The initial value.
|
* @param {Number} options.stopValue The final value.
|
* @param {Number} [options.duration=3.0] The duration, in seconds, for the tween. The tween is automatically removed from the collection when it stops.
|
* @param {Number} [options.delay=0.0] The delay, in seconds, before the tween starts animating.
|
* @param {EasingFunction} [options.easingFunction=EasingFunction.LINEAR_NONE] Determines the curve for animtion.
|
* @param {TweenCollection~TweenUpdateCallback} [options.update] The callback to call at each animation update (usually tied to the a rendered frame).
|
* @param {TweenCollection~TweenCompleteCallback} [options.complete] The callback to call when the tween finishes animating.
|
* @param {TweenCollection~TweenCancelledCallback} [options.cancel] The callback to call if the tween is canceled either because {@link Tween#cancelTween} was called or because the tween was removed from the collection.
|
* @returns {Tween} The tween.
|
*
|
* @exception {DeveloperError} options.object must have the specified property.
|
* @exception {DeveloperError} options.duration must be positive.
|
*/
|
TweenCollection.prototype.addProperty = function(options) {
|
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
|
|
var object = options.object;
|
var property = options.property;
|
var startValue = options.startValue;
|
var stopValue = options.stopValue;
|
|
//>>includeStart('debug', pragmas.debug);
|
if (!defined(object) || !defined(options.property)) {
|
throw new DeveloperError('options.object and options.property are required.');
|
}
|
if (!defined(object[property])) {
|
throw new DeveloperError('options.object must have the specified property.');
|
}
|
if (!defined(startValue) || !defined(stopValue)) {
|
throw new DeveloperError('options.startValue and options.stopValue are required.');
|
}
|
//>>includeEnd('debug');
|
|
function update(value) {
|
object[property] = value.value;
|
}
|
|
return this.add({
|
startObject : {
|
value : startValue
|
},
|
stopObject : {
|
value : stopValue
|
},
|
duration : defaultValue(options.duration, 3.0),
|
delay : options.delay,
|
easingFunction : options.easingFunction,
|
update : update,
|
complete : options.complete,
|
cancel : options.cancel,
|
_repeat : options._repeat
|
});
|
};
|
|
/**
|
* Creates a tween for animating the alpha of all color uniforms on a {@link Material}. The tween starts animating at the next call to {@link TweenCollection#update}, which
|
* is implicit when {@link Viewer} or {@link CesiumWidget} render the scene.
|
*
|
* @param {Object} [options] Object with the following properties:
|
* @param {Material} options.material The material to animate.
|
* @param {Number} [options.startValue=0.0] The initial alpha value.
|
* @param {Number} [options.stopValue=1.0] The final alpha value.
|
* @param {Number} [options.duration=3.0] The duration, in seconds, for the tween. The tween is automatically removed from the collection when it stops.
|
* @param {Number} [options.delay=0.0] The delay, in seconds, before the tween starts animating.
|
* @param {EasingFunction} [options.easingFunction=EasingFunction.LINEAR_NONE] Determines the curve for animtion.
|
* @param {TweenCollection~TweenUpdateCallback} [options.update] The callback to call at each animation update (usually tied to the a rendered frame).
|
* @param {TweenCollection~TweenCompleteCallback} [options.complete] The callback to call when the tween finishes animating.
|
* @param {TweenCollection~TweenCancelledCallback} [options.cancel] The callback to call if the tween is canceled either because {@link Tween#cancelTween} was called or because the tween was removed from the collection.
|
* @returns {Tween} The tween.
|
*
|
* @exception {DeveloperError} material has no properties with alpha components.
|
* @exception {DeveloperError} options.duration must be positive.
|
*/
|
TweenCollection.prototype.addAlpha = function(options) {
|
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
|
|
var material = options.material;
|
|
//>>includeStart('debug', pragmas.debug);
|
if (!defined(material)) {
|
throw new DeveloperError('options.material is required.');
|
}
|
//>>includeEnd('debug');
|
|
var properties = [];
|
|
for (var property in material.uniforms) {
|
if (material.uniforms.hasOwnProperty(property) &&
|
defined(material.uniforms[property]) &&
|
defined(material.uniforms[property].alpha)) {
|
properties.push(property);
|
}
|
}
|
|
//>>includeStart('debug', pragmas.debug);
|
if (properties.length === 0) {
|
throw new DeveloperError('material has no properties with alpha components.');
|
}
|
//>>includeEnd('debug');
|
|
function update(value) {
|
var length = properties.length;
|
for (var i = 0; i < length; ++i) {
|
material.uniforms[properties[i]].alpha = value.alpha;
|
}
|
}
|
|
return this.add({
|
startObject : {
|
alpha : defaultValue(options.startValue, 0.0) // Default to fade in
|
},
|
stopObject : {
|
alpha : defaultValue(options.stopValue, 1.0)
|
},
|
duration : defaultValue(options.duration, 3.0),
|
delay : options.delay,
|
easingFunction : options.easingFunction,
|
update : update,
|
complete : options.complete,
|
cancel : options.cancel
|
});
|
};
|
|
/**
|
* Creates a tween for animating the offset uniform of a {@link Material}. The tween starts animating at the next call to {@link TweenCollection#update}, which
|
* is implicit when {@link Viewer} or {@link CesiumWidget} render the scene.
|
*
|
* @param {Object} [options] Object with the following properties:
|
* @param {Material} options.material The material to animate.
|
* @param {Number} options.startValue The initial alpha value.
|
* @param {Number} options.stopValue The final alpha value.
|
* @param {Number} [options.duration=3.0] The duration, in seconds, for the tween. The tween is automatically removed from the collection when it stops.
|
* @param {Number} [options.delay=0.0] The delay, in seconds, before the tween starts animating.
|
* @param {EasingFunction} [options.easingFunction=EasingFunction.LINEAR_NONE] Determines the curve for animtion.
|
* @param {TweenCollection~TweenUpdateCallback} [options.update] The callback to call at each animation update (usually tied to the a rendered frame).
|
* @param {TweenCollection~TweenCancelledCallback} [options.cancel] The callback to call if the tween is canceled either because {@link Tween#cancelTween} was called or because the tween was removed from the collection.
|
* @returns {Tween} The tween.
|
*
|
* @exception {DeveloperError} material.uniforms must have an offset property.
|
* @exception {DeveloperError} options.duration must be positive.
|
*/
|
TweenCollection.prototype.addOffsetIncrement = function(options) {
|
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
|
|
var material = options.material;
|
|
//>>includeStart('debug', pragmas.debug);
|
if (!defined(material)) {
|
throw new DeveloperError('material is required.');
|
}
|
if (!defined(material.uniforms.offset)) {
|
throw new DeveloperError('material.uniforms must have an offset property.');
|
}
|
//>>includeEnd('debug');
|
|
var uniforms = material.uniforms;
|
return this.addProperty({
|
object : uniforms,
|
property : 'offset',
|
startValue : uniforms.offset,
|
stopValue : uniforms.offset + 1,
|
duration : options.duration,
|
delay : options.delay,
|
easingFunction : options.easingFunction,
|
update : options.update,
|
cancel : options.cancel,
|
_repeat : Infinity
|
});
|
};
|
|
/**
|
* Removes a tween from the collection.
|
* <p>
|
* This calls the {@link Tween#cancel} callback if the tween has one.
|
* </p>
|
*
|
* @param {Tween} tween The tween to remove.
|
* @returns {Boolean} <code>true</code> if the tween was removed; <code>false</code> if the tween was not found in the collection.
|
*/
|
TweenCollection.prototype.remove = function(tween) {
|
if (!defined(tween)) {
|
return false;
|
}
|
|
var index = this._tweens.indexOf(tween);
|
if (index !== -1) {
|
tween.tweenjs.stop();
|
if (defined(tween.cancel)) {
|
tween.cancel();
|
}
|
this._tweens.splice(index, 1);
|
return true;
|
}
|
|
return false;
|
};
|
|
/**
|
* Removes all tweens from the collection.
|
* <p>
|
* This calls the {@link Tween#cancel} callback for each tween that has one.
|
* </p>
|
*/
|
TweenCollection.prototype.removeAll = function() {
|
var tweens = this._tweens;
|
|
for (var i = 0; i < tweens.length; ++i) {
|
var tween = tweens[i];
|
tween.tweenjs.stop();
|
if (defined(tween.cancel)) {
|
tween.cancel();
|
}
|
}
|
tweens.length = 0;
|
};
|
|
/**
|
* Determines whether this collection contains a given tween.
|
*
|
* @param {Tween} tween The tween to check for.
|
* @returns {Boolean} <code>true</code> if this collection contains the tween, <code>false</code> otherwise.
|
*/
|
TweenCollection.prototype.contains = function(tween) {
|
return defined(tween) && (this._tweens.indexOf(tween) !== -1);
|
};
|
|
/**
|
* Returns the tween in the collection at the specified index. Indices are zero-based
|
* and increase as tweens are added. Removing a tween shifts all tweens after
|
* it to the left, changing their indices. This function is commonly used to iterate over
|
* all the tween in the collection.
|
*
|
* @param {Number} index The zero-based index of the tween.
|
* @returns {Tween} The tween at the specified index.
|
*
|
* @example
|
* // Output the duration of all the tweens in the collection.
|
* var tweens = scene.tweens;
|
* var length = tweens.length;
|
* for (var i = 0; i < length; ++i) {
|
* console.log(tweens.get(i).duration);
|
* }
|
*/
|
TweenCollection.prototype.get = function(index) {
|
//>>includeStart('debug', pragmas.debug);
|
if (!defined(index)) {
|
throw new DeveloperError('index is required.');
|
}
|
//>>includeEnd('debug');
|
|
return this._tweens[index];
|
};
|
|
/**
|
* Updates the tweens in the collection to be at the provide time. When a tween finishes, it is removed
|
* from the collection.
|
*
|
* @param {Number} [time=getTimestamp()] The time in seconds. By default tweens are synced to the system clock.
|
*/
|
TweenCollection.prototype.update = function(time) {
|
var tweens = this._tweens;
|
|
var i = 0;
|
time = defined(time) ? time / TimeConstants.SECONDS_PER_MILLISECOND : getTimestamp();
|
while (i < tweens.length) {
|
var tween = tweens[i];
|
var tweenjs = tween.tweenjs;
|
|
if (tween.needsStart) {
|
tween.needsStart = false;
|
tweenjs.start(time);
|
} else if (tweenjs.update(time)) {
|
i++;
|
} else {
|
tweenjs.stop();
|
tweens.splice(i, 1);
|
}
|
}
|
};
|
|
/**
|
* A function that will execute when a tween completes.
|
* @callback TweenCollection~TweenCompleteCallback
|
*/
|
|
/**
|
* A function that will execute when a tween updates.
|
* @callback TweenCollection~TweenUpdateCallback
|
*/
|
|
/**
|
* A function that will execute when a tween is cancelled.
|
* @callback TweenCollection~TweenCancelledCallback
|
*/
|
export default TweenCollection;
|
