additween

Additive tweening implementation for smooth animations.

It combines concurrent animations of the same object into one smooth continuous animation.

How to install

npm install additween --save

Why the name?

In short, additween = Additive + tweening.

Speaking about animation, inbetweening or tweening is the process of generating intermediate frames between two states to give the appearance that the first state evolves smoothly into the second state.

Additive algorithm ensures that if some animation process starts while there are some processes still in progress, all these process will be combined to produce a single animation process.

Additive animation algorithm is described here or in this video.

Usage Example

Let's move the span smooth vertically. Create animation object and provide the options. You need to provide at least onRender callback:

var additween = require("additween");

var mySpan = document.getElementById("mySpan");

function onRender(state) {
  mySpan.style.top = state.top;
}

var anim = new additween.AdditiveTweening({
  onRender: onRender,
});

Now call tween method to start animation:

var fromState = { top: 0 };
var toState = { top: 1000 };
var duration = 1000;

anim.tween(fromState, toState, duration);

To add new animation with another final state, just call it again:

fromState = { top: parseInt(mySpan.style.top) };
toState = { top: 2000 };

anim.tween(fromState, toState, duration);

API

anim = new AdditiveTweening(options)

Creates animation object. Possible options:

Name	Signature	Description
onRender	function(state)	(required) a callback for rendering current animation state.
onFinish	function(finalState)	Fires after the last animation is completed.
onCancel	function()	Fires if animation is canceled.
stateReducer	IStateReducer	An object, which provides clone() and reduce() methods thus implementing IStateReducer interface.

State reducers

State reducer is an object, which provides clone() and reduce() methods thus implementing IStateReducer interface.

interface IStateReducer<T> {
  clone: (state: T) => T;
  reduce: (targetState: T, toState: T, fromState: T, pos: number) => T;
}

clone() method is called once per each animation frame in order to get full clone of the target animation state.

reduce() method is called at least once per each animation frame in order to get animation state for the given tweening position pos - a number from [0,1] interval. targetState - is the current animation state.

If there are more than one tweening processes in progress, reduce() will be called once for each tweening process during single animation frame.

The default state reducer is called and exported as PlainObjectReducer. Its implementation is below:

var PlainObjectReducer = {
  clone: function (obj) {
    var target = {},
      key;
    for (key in obj) {
      target[key] = obj[key];
    }
    return target;
  },

  reduce: function (targetState, toState, fromState, pos) {
    var key;
    for (key in targetState) {
      targetState[key] -= (toState[key] - fromState[key]) * pos;
    }
    return targetState;
  },
};

It can be used to animate states which are plain JavaScript objects with numeric values, such as { width: 10, height: 20 }.

anim.tween(fromState, toState, duration, easing)

Animates object state. fromState and toState are expected to be the objects with number values, e.g. { x: 100, y: 200 }. duration is animation duration in milliseconds.

easing is a function used for easing. It could be one of functions described here: https://gist.github.com/gre/1650294) or your own function (assuming it's input and output values are in range [0, 1]). Linear easing is the default.

anim.isTweening()

Returns true if animation process is currently in progress.

anim.cancel()

Cancels current animation.

anim.finish()

Puts animation into the last state.

Mocks

See additween-mocks

Browser support

This will work for all browsers with requestAnimationFrame support (see here).

For the other browsers you will need to polyfill requestAnimationFrame. raf package provides a good one.

Thanks

Thanks to @alexkuz for the original implementation.

License

MIT (http://www.opensource.org/licenses/mit-license.php)