Cesium-Prequel/Source/Scene/TweenCollection.js

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;