gm-easing

Easing / gm-easing

Fluent Easing function provider with built in Bezier Curve based easing functions and exact clones of CSS3 transition built-ins, plus the ability to use your own custom easing functions.

This module can be used for animations, audio and games and anything else.

Easing functions take a time value, t between 0 and 1 and return an eased time value.

Installation

Browserify/NPM

    $ npm install --save gm-easing

  var Easer = require('gm-easing').Easer;

API

.Easer()

// generate an easing function...
var easer = new Easer().using("ease-in");
 
// pass your delta (a value between 0 and 1) to the easer to get your eased value.
var easedDelta = easer( delta );

.generateAllSamples() Optimisation Considerations

CSS3 transition curve emulation relies on pre-generated samples. By default, after a CSS curve is used the first time, the samples are then cached. This could, on slower devices, cause a slight delay which can be avoided by generating the samples at some other time when your applications is not otherwise under any particular load.

// browserify:
require('gm-easing').generateAllSamples();
// component:
require('easing').generateAllSamples();

.presets

Returns the list of available presets.

.isPreset( name )

Returns true if name is a valid preset.

Easer API

Easer().using( "preset" )

Returns a function which takes an input ratio of 0 to 1 and returns the eased output ratio.

Use an easing preset. Choices are:

• linear
• ease - Replicates CSS3 default
• ease-in - Replicates CSS3 ease-in
• ease-out - Replicates CSS3 ease-out
• ease-in-out - Replicates CSS3 ease-in-out
• ease-in-back
• ease-out-back
• ease-in-out-back
• ease-in-expo
• ease-out-expo
• ease-in-cubic
• ease-out-cubic

var easer = new Easer().using('ease-in');
easer(0); // 0
easer(1); // 1
easer(0.5); // 0.3147198334560001

new Easer().usingCSS3Curve( c2.x, c2.y, c3.x, c3.y [, samples])

Creates an easing function which emulates the behaviour of a custom CSS3 easing curve. Any CSS3 curve generator can generate compatible values for this, for example Ceaser.

Note that computing "y at x(t)" requires the building of a lookup table, although only once for any given curve. For the best performance it is better to generate an easing function using the same custom curve long before you intend to use it in an actual animation.

Optionally you can specify the number of samples required. By default 10,000 samples are generated which serves for most purposes but if you notice jerky movement for extremely long running animations then either use more samples (at the expense of more memory), use a Bezier Curve directly (without samples), or use a custom easing function.

var easer = new Easer().usingCSS3Curve(0.33,-0.305, 0.715,-0.155);
easer(0); // 0
easer(1); // 1
easer(0.5); // -0.06145341884495001

Note that, as with CSS3 transition-timing-functions, x must stay between 0 and 1 along the curve. It'll still run but it's kinda glitchy. In testing, real CSS3 transitions glitch out in exactly the same way.

new Easer().usingCustomCurve( curve )

An easing function can be generated directly from any arbitrary Bezier Curve where the C1 and C4 are not limited to 0,0 and 1,1 respectively.

There is an important difference between this and using CSS3Curves: No samples are generated. Eased values are generated by computing the value of y at time on every call to the easing function. The x value is ignored.

The effects tend to be more subtle, but it is more efficent in terms of memory usage and there is no delay while samples are precomputed.

Curve data should be structured as an object containing and vector arrays: { c1 : [x, y], c2 : [x, y], c3 : [x, y], c4 : [x,y]}

var easer = new Easer().usingCustomCurve({ c1 : [0,0], c2 : [0.075,0.61], c3 : [0.36,0.93], c4 : [1,1]});
easer(0); // 0
easer(1); // 1
easer(0.5); //0.7025
 
### new Easer().usingCustomEaser( function )
 
Easer allows you to use your own easing functions. Any function will do, so long as it takes a value between 0 and 1 and returns some value useful to you. 
Mostly this is support implementations like [gm-tween](https://github.com/charlottegore/tween) that rely on a consistent easing interface but occasionally
want to offer developers the ability to implement their own easing functions.
 
```js
var easer = new Easer().usingCustomEaser( function (t){
  return 1 - t;
});
easer(0); // 1
easer(1); // 0
easer(0.5); // 0.5

License

MIT