tslerp
v2.0.0
Published
Typescript library for lerping single and multi-sample data sets over time
Downloads
2,707
Readme
tslerp
Typescript library for lerping single and multi-sample data sets over time across a variety of styles and transitions.
Build Status
Master Branch
Develop Branch
End User Documentation
Installation
- Add the package to your 'dependencies' list in
package.json
and runnpm install
"tslerp": "^2.0.0"
Optionally, you can manually install the package using the npm command line
npm install tslerp --save
- Add tslerp to both your
map
andpackages
structures insystemjs.config.js
var map = {
...
'tslerp': 'node_modules/tslerp'
};
var packages = {
...
'tslerp': { main: 'index.js', defaultExtension: 'js' },
};
- Optionally, add the
rootDir
option totsconfig.json
to make sure TypeScript's default root path algorithm doesn't pull in thenode_modules
folder
Usage
Examples of using tslerp can also be found in the tslerp test packages in lerp.spec.ts
Triggering a simple lerp
// Import the lerp class from tslerp
import { TsLerp } from 'tslerp';
class ClassToLerpSomething {
// Define our lerp object
private tsLerp: TsLerp = new TsLerp();
// Starts a transition using TsLerp
public startTransition() {
// Define the properties of the lerp, this can contain a single set of
// points to lerp between, or multiple data points
// The format of the function is define([ [start, end], ...], duration);
// The following defines two data sets, one to lerp between 0 and 10, and one
// to lerp between 30 and 50. Both sets will take 10 seconds to complete
this.tsLerp.define([ [0, 10], [30, 50] ], 10);
// Trigger the lerp, providing a callback that will be called constantly
// as the lerp progresses from start to finish
// This callback will be called every 33 milliseconds providing a constent
// 30 FPS on stable systems. For none stable systems, the transition is
// framerate independent to will always take the defined amount of time to finish
this.tsLerp.lerp((results: number[], time: number) => {
this.lerpCallback(results, time);
});
}
// Function called from TsLerp.lerp every 33 milliseconds
private lerpCallback(results: number[], time: number) {
// This callback is passed
// - results: An array of values containing the current lerp values of the data
// sets passed through in TsLerp.define. The order of the results
// is guarenteed to be the same order as originally defined.
// - time: The current passage of time in the range [0..1]. When time is
// 1, the lerp has completed and the callback will cease to be called.
}
}
Chaining lerp sequences
// Import the lerp class from tslerp
import { TsLerp } from 'tslerp';
class ClassToLerpSomething {
...
// Lerp callback containing the results of the current lerp process
private lerpCallback(results: number[], time: number) {
// It is perfectly acceptable to request an a new set of lerp values
// during a current lerp. In the following example, when the first
// set of lerp values has completed, a sequential set of lerp values
// is initiated.
// Note that calling TsLerp.define will reset the current lerp values
// which means triggering a new set of lerp points in the middle of
// a current lerp sequence may result in unwanted results.
// Call this when the current lerp has finished
if (time === 1) {
// Define a lerp between [10..100] over 5 seconds
this.tsLerp.define([ [10, 100] ], 5);
// We can use the same callback or a different callback depending on
// the expected results. Note in this case, we're creating an infinite
// loop of lerp events, something you probably don't want to do...
this.tsLerp.lerp((results: number[], time: number) => {
this.lerpCallback(results, time);
});
}
}
}
Controlling an in-progress lerp
It is possible to pause or delay an in-progress lerp in response to external events
// Import the lerp class from tslerp
import { TsLerp } from 'tslerp';
class ClassToLerpSomething {
...
// Generic event indicating the page or animation needs to pause
private onSomeEventToPause() {
// You can call TsLerp.pause to stop the current transition
// This will stop the lerp from progressing and stop all calls
// to the user provided callback in TsLerp.lerp.
this.tsLerp.pause(true);
...
}
// Generic event indicating the page or animation can continue
private onSomeEventToResume() {
// You can call TsLerp.pause to resume the current transition
// This will start the progression of the lerp again and resume
// calls to the user provided callback in TsLerp.lerp.
this.tsLerp.pause(false);
...
}
// Generic event indicating the transition needs to terminate
private onSomeEventToStop() {
// You can call TsLerp.stop to cancel the current lerp and
// stop all calls to the user defined callback in tsLerp.lerp
this.tsLerp.stop()
...
}
}
Styling a lerp transition
TsLerp.define
allows you to specify the kind of transition and style the lerp will travel.
// Import the lerp types from tslerp
import { TsLerp, TsLerpTransition, TsLerpStyle } from 'tslerp';
class ClassToLerpSomething {
...
// Starts a transition using TsLerp
public startTransition() {
// Define a lerp that eases out of the transition using a quadratic path
this.tsLerp.define([ [0, 10], [30, 50] ], 10, TsLerpTransition.EaseOut, TsLerpStyle.Quadratic);
...
}
// Lerp callback containing the results of the current lerp process
private lerpCallback(results: number[], time: number) {
// Regardless of the type of style or transition used for the lerp, the
// time value of the callback will always increment in a linear manner.
}
}
The following animations show the various transitions and styles available, samples over a 1 second period. All animations were captured from Easing Equations by Robert Penner
Style: Linear
Note that the TsLerpTransition
option is ignored when choosing a Linear style
Style: Quadratic
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Style: Sine
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Cubic
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Style: Exponential
Transition: Ease In
Transition: Ease Out
Transition: Ease In and Out
Change Log
2.0.0
- Removed Typings dependency
1.0.5
- Updated project to latest TypeScript (v2.3.2) and fixed resultant errors
1.0.4
- Documentation update stating Typings as a Dependency
1.0.3
- Updated package requirements to Typescript ^2.0.0 plus related package upgrades
1.0.2
- Minor readme updates
1.0.1
- Updated correct acknowledgment for Easing Equations by Robert Penner
1.0.0
- Added support for Linear, Sine, Cubic and Exponential styles
- Added support for Ease In, Out and In/Out transitions for all styles
0.0.1
- Initial release
- Support for Ease In Quadratic lerps only
Contribution Guidelines
Requirements
- node.js and npm
- Typescript 2.6.2+
Optional
- Visual Studio Code
- Recommended VS Code Extensions are included in the workspace
Development
- Branch from */develop
- Browse to /development and run
npm install
- Compile by running
tsc
(by default this will watch for changes) - Run tests in watch mode by running
npm run-script testdev
Merging Back
- Raise a pull request which will run a set of Travis-CI tests
- Once passed, the change will be squashed into develop if approved