animation-timer

Animation Timer

Low level animation / LFO module suitable for graphics, games development and audio processing. It uses Tick as a central controller, giving the ability to pause and resume individual or all animations currently in progress.

Animation Timer literally does nothing but supply you with a normalised, abstract 'percentage time elapsed' value.

• Create a new timer and set a duration
• Set your tick event handler
• play, reverse, loop, loop reverse or bounce the animation
• Stop it, Pause it, Resume it.
• Tick handler gets a value between 0 and 1

This module works extremely well with Functional Easing which can wrap your tick handlers with easing functions so that you get eased time values instead of raw linear time elapsed values. It's cool. Not bow-tie cool, but pretty pretty cool. Together they pretty much eliminate most of the tediously repetitive math around dealing with animations and easing and let you concentrate on your actual functionality.

Example

// some dependencies...
var quat = require('gl-matrix-quat');
var mat4 = require('gl-matrix-mat4');
var Easer = require('functional-easing').Easer;

// animation timer module...
var AnimationTimer = require('animation-timer').AnimationTimer;

// making two quaternions.
var q1 = quat.fromValues(0.5, 0.3, 1.0, 1.0);
var q2 = quat.fromValues(0.1, 0.9, 0.2, 1.0);

// make an easing function..
var easer = new Easer().using('in-cubic');

var animation = new AnimationTimer()
  .duration('5s')
  // wrap our tick handler with our easing function...
  .on('tick', easer(function (percent){

    var out = quat.create();
    quat.slerp(out, q1, q2, percent);

    // do something with our new quaternion... 

  }));

animation.bounce();

Installation

Browserify/NPM

    $ npm install --save animation-timer

  var AnimationTimer = require('animation-timer').AnimationTimer;

API

Core

new AnimationTimer()

Creates a new instance of AnimationTimer;

var animation = new AnimationTimer();

animation.duration( duration )

Specifies how long a single iteration of the animation should last for. Can be given in miliseconds or as a string, '200ms', '2s', '1m' etc.

When the tick handler fires, the value passed as a parameter is the percentage time elapsed (between 0 and 1) since the animation began.

• Animations started with play or reverse will go from 0 to 1 over the duration.
• Animations started with loop or loopReverse will loop every duration, each cycle behaving like play or reverse
• Animations started with bounce will toggle between play and reverse every duration.

// create a triangle wave LFO for the Web Audio API, toggling direction every beat
var ani = new AnimationTimer()
  .duration(500)
  .on('tick', function(percent){
    filter.frequency.value = lerp(200,500, percent);
  })
  .loop();

Events

animation.on(event, callback)

Subscribe to an event. The built in events are:

.on('tick', func)

Subscribe to the tick event.

• Fires every animationFrame while the animation is running
• func is passed percent as a parameter. This is value between 0 and 1

.on('stop', func)

This handler can be used to do any processing work required after an animation is concluded.

• Fires when .play() or .reverse() animations are finished
• Fires when the animation is manually stopped
• func is passed the current time

.on('loop', function)

This handler can be used in leui of a tick handler in order to trigger events that occur every duration.

• Fires when .loop() or .loopReverse() animations are about to start the next iteration
• func is passed the current time

.on('bounce', function)

This handler can be used in leui of a tick handler in order to trigger events that occur every duration.

• Fires when .bounce() animations are about to toggle direction.
• func is passed the current time

.trigger(event, args)

Technically you can trigger any event manually, including any custom events you so desire.

Playing Animations

animation.play(start)

Fires a tick handler every animationFrame until the duration has elapsed, at which point it stops.

By default it begins immediately but optionally an absolute start time can be specified.

• time in the tick handler climbs from 0 to 1, representing the percentage duration elapsed.

animation
  .duration(1000)
  .on('tick', function(time){
    console.log(time);
  })
  .play();

animation.loop()

Fires a tick handler every animationFrame indefinitely.

By default it begins immediately but optionally an absolute start time can be specified.

• time in the tick handler climbs from 0 to 1, representing the percentage duration elapsed.
• Each duration, time loops back to 0 and starts again
• Sawtooth LFO

animation
  .duration(1000)
  .on('tick', function(time){
    console.log(time);
  })
  .loop();

animation.bounce()

Fires a tick handler every animationFrame indefinitely.

By default it begins immediately but optionally an absolute start time can be specified.

• time in the tick handler climbs from 0 to 1, then 1 to 0, then 0 to 1 and so on.
• Each duration, time toggles between climbing and falling.
• Triangle LFO

animation
  .duration(1000)
  .on('tick', function(time){
    console.log(time);
  })
  .bounce();

animation.reverse()

Fires a tick handler every animationFrame until the duration has elapsed, at which point it stops.

By default it begins immediately but optionally an absolute start time can be specified.

• time in the tick handler falls from 1 to 0, representing the inverted percentage duration elapsed.

animation
  .duration(1000)
  .on('tick', function(time){
    console.log(time);
  })
  .reverse();

animation.loopReverse()

Fires a tick handler every animationFrame indefinitely

By default it begins immediately but optionally an absolute start time can be specified.

• time in the tick handler falls from 1 to 0, representing the inverted percentage duration elapsed.
• Each duration, time loops back to 0 and starts again
• Reverse Sawtooth LFO

animation
  .duration(1000)
  .on('tick', function(time){
    console.log(time);
  })
  .loopReverse();

## Control

animation.stop()

Immediately stops the running animation. Stopped animations cannot be resumed, only restarted.

animation.stop();

animation.pause()

Pauses the animation.

animation.pause();

animation.resume()

Resumes an animation

animation.resume();

Tests

Assuming you have grunt-cli already installed, and you've cloned the repo:

# Just the once...
$ npm install

grunt test

Background

This module is intended to replaced my much loved Tween module which, while incredibly useful has proven to be the wrong abstraction and difficult to use once stepping outside the realm of {left : 10, top : 15}. I needed a more abstract, flexible module that would give me the crucial time information and actually run animations, but not be involved in actual tweening or anything like that, making it less cumbersome and inefficent when changing vectors, matricies, quarternions etc over time.

Roadmap

There is no roadmap as much, although possible useful functions would be 'stopBeforeLooping()' for looping and bouncing animations. Debating with myself whether to support 'playAt(tick.now() + delay)' or 'stopAt(tick.now() + delay)' or whether a separate scheduling module would be more appropriate.

License

MIT