WPE UI Framework

WPE UI Framework is a javascript 2d graphics rendering and animation library using (Web)GL. It's geared towards developing animated User Interfaces that run nicely on low-performance (embedded) devices. The framework has been optimized for high performance and low CPU/memory usage, and has been carefully tested for memory leaks.

The framework provides a rendering tree that can be modified using a very simple API. The rendering tree consists of components that have properties that define where and how it is rendered (x, y, rotation, alpha, etc). An image or rendered text can be attached to a component, which is then rendered immediately on the screen.

UI Framework runs in a any modern web browser using WebGL and in Node.js (version 4 or higher) on several targets including (desktop) Linux, OSX, Windows and the Raspberry PI.

Installation instructions

Browser

Include the script dist/wpe.js or dist/wpe.min.js. These files can be re-generated from source using the command:

grunt wpe-browser

Node.js:

For Node.js, this module depends on node-canvas for image loading and text creation, and node-wpe-webgl for providing a WebGL interface to the native hardware. Install the dependencies and follow the installation instructions of node-canvas (https://github.com/Automattic/node-canvas) and node-wpe-webgl (https://github.com/WebPlatformForEmbedded/node-wpe-webgl).

Tutorial

This section describes how to initialize and use the framework step-by-step.

Initialization

For a web browser:

var options = {w: 600, h: 600, glClearColor: 0xFF000000};
var stage = new Stage(options);
 
document.body.appendChild(stage.getCanvas());

This initializes a new stage. The stage creates a canvas of the specified width and height for drawing, and uses the specified background color (in ARGB hexadecimal format). You should then get it using stage.getCanvas() add it to the DOM tree. You can also supply your own canvas object by using the reuseCanvas option.

For Node.js:

var Stage = require('wpe-uiframework');
 
var options = {w: 600, h: 600, glClearColor: 0xFF000000, window: {title: "Example", fullscreen: false}};
var stage = new Stage(options);

This is similar as for the web browser, but node-wpe-webgl is used as OpenGL rendering target. This module allows some options for initialization that can be set in the window property. See https://github.com/WebPlatformForEmbedded/node-wpe-webgl#options.

Check the API for a list of all initialisation options.

Tree Definition

The stage.root property is the root of the rendering tree. You can add other new components to this tree to define what should be rendered within the stage. All of the nodes in the rendering tree are of the Component type, and based on their property settings they can be images, rectangles, texts or containers.

Example:

stage.root.add([
    {tag: 'bg', rect: true, x: 20, y: 20, w: 560, h: 560, colorTop: 0xFFFF0000, colorBottom: 0xFFFF6666, children: [
        {tag: 'hello', text: {text: "hello world", fontSize: 100}, x: 280, y: 170, mountX: 0.5, mountY: 0.5, alpha: 0.5},
        {tag: 'bunnies', x: 30, y: 30, w: 500, h: 500, clipping: true, borderWidth: 10, borderColor: 0xFF000000, children: [
            {src: basePath + 'bunny.png', x: 20, y: 400, scale: 8, rotation: 0.3},
            {src: basePath + 'bunny.png', x: 480, y: 400, scale: 8, rotation: -0.3}
        ]}
    ]}
]);

https://jsfiddle.net/basvanmeurs/4qy5j7am/

Check the API for a list of all component properties.

Dynamic Changes

You can dynamically change the rendering tree by accessing components using their tags:

// Get a single component by tag, and modify properties.
var bunniesCtr = stage.root.tag('bunnies');
bunniesCtr.borderWidth -= 5;
 
// You can access the component's children directly.
var bunnies = bunniesCtr.children;
bunnies.forEach(function(b) {
  // Set properties using a JSON object.
  b.set({alpha: 0.5, scale:8});
 
  // Add tag for later use.
  b.addTag('bunny');
});
 
// Use the just added tags, and clear the tags using a setting.
bunniesCtr.stag('bunny', {borderWidth: 1, tags: []});
 
// Because tags were just removed, this does nothing.
bunniesCtr.stag('bunny', {borderWidth: 0});
 
// Set by complex tag (set components tagged 'hello' that have an ancestor tagged 'bg').
stage.root.stag('bg.hello', {text: {text: "Hello World"}, alpha: 1});

https://jsfiddle.net/basvanmeurs/m2z8ctu7/

You can also create, add and remove components dynamically:

// Add new branch.
stage.root.tag('bunnies').add({tag: 'stuff', w: 400, h: 60, x: 50, y: 10, rect: true, color: 0xAAFFFFFF, borderWidth: 2, borderColor: 0xFF000000, children: [
    {src: basePath + 'bunny.png', x: 10, y: 30, mountY: 0.5},
  {text: {text: "this is a demo showing you how to define a branch of components via json and how to add that to the render branch.", fontSize: 12, lineHeight: 14, fontFace: ["Verdana", "Sans-Serif"], wordWrapWidth: 330}, x: 50, y:10, color: 0xFF000000}
]});
 
var c;
setTimeout(function() {
  // Remove the bunny.
  c = stage.root.tag('stuff').children[0];
    stage.root.tag('stuff').removeChild(c);
 
  setTimeout(function() {
    // Re-add the bunny, this time to the stage root.
    stage.root.addChild(c);
  }, 1000);
}, 1000);

https://jsfiddle.net/basvanmeurs/r0hkamd7/

You can also hook into the frame loop event, which runs at 60fps:

stage.on('frameStart', function(dt) {
    stage.root.tag('left').scaleX += stage.dt * 10;
    stage.root.tag('right').rotation += stage.dt * 1;
    stage.root.tag('hello').x += 30 * stage.dt;
});

https://jsfiddle.net/basvanmeurs/c4f7kh70/

Transitions

In a UI, in most situations a gradual transition looks nicer than setting a property directly. That's why this framework provides transitions in a very simple API:

var t = stage.root.tag('bunnies').transition('rotation', {delay: 2, duration: 8, timingFunction: 'ease'});
t.on('finish', function() {
    stage.root.tag('bunnies').x = 400;
});
stage.root.tag('bunnies').transition('x', {delay: 2, duration: 5, timingFunction: 'linear'});
stage.root.tag('bunnies').rotation = 2 * Math.PI * 8;

Check the API for a list of all transition properties and events.

https://jsfiddle.net/basvanmeurs/3eakcyrh/

You can remove a previously set transition like this:

setTimeout(function() {
  stage.root.tag('bunnies').transition('rotation', null);
}, 3000);

https://jsfiddle.net/basvanmeurs/4sukLurc/

Every property of the Component type that can be used in a transition has a 'normal' value and a final value, which is represented by the upper case property name. So, for example, the property component.rotation has a final equivalent component.ROTATION. If no transition is active, setting component.rotation automatically also sets component.ROTATION. If a transition is active, it will change the component.ROTATION property every frame. The component.ROTATION property is the one that's actually being used when rendering the tree. It is good to know about this distinction, because sometimes you may wish to adjust something in the rendering tree based on the final value rather than the normal value, as in the following example, in which the text is kept aligned with the container box:

var t = stage.root.tag('box').transition('x', {delay: 0.5, duration: 2, timingFunction: 'ease'});
stage.root.tag('box').x = -300;
t.on('progress', function(p) {
  var x = stage.root.tag('box').X;
  if (x < 0) {
     stage.root.tag('hello').x = Math.min(150, 10 - x);
  } else {
     stage.root.tag('hello').x = 10;
  }
});
 
t.on('finish', function() {
  stage.root.tag('box').x = Math.random() * 1000 - 500;
});

https://jsfiddle.net/basvanmeurs/4sukLurc/

Sometimes you may want to fast-forward a transition. You can do this using the Component.fastForward method:

setTimeout(function() {
  // If you set the final property value and then the property value to the same value,
  // the transition will automatically skip to the end.
  stage.root.tag('bunnies').fastForward('rotation');
}, 3000);

Notice that, when fast-forwarding, the finish event is emitted, whereas when removing the transition it is not.

https://jsfiddle.net/basvanmeurs/2cttjrhw/

Check the API for a list of all transition methods, properties and events.

Animations

WPE UI Framework provides a standardized way of specifying and using animations. Animations are a collection of actions (property settings) that take place at the particular point in time. An animation has a subject Component, on which (or one of its descendants) the actions are applied.

The following example shows how to define and start a complex animation:

var a = stage.root.tag('notification-ctr').animation({duration: 1, actions: [
  {t: '', p: 'visible', v: true, rv: false},
  {t: 'notification', p: 'x', v: {0: 600, 0.6: 200}},
  {t: 'notification', p: 'h', v: {0.6: 50, 1: 190}},
  {t: 'bg-overlay', p: 'alpha', v: {0: 0, 0.5: 1}}
]});
 
a.start();

https://jsfiddle.net/basvanmeurs/56dpqoks/

In the actions property, you can define the things that should happen during the animation. All component properties can be used, as well as all text properties (defined as "text.fontSize", etc) and texture clipping properties ("texture.x").

The values that are numeric are by default 'smoothened' using cubic bezier splines. If you'd prefer to have linear actions, you can do that as follows:

var a = stage.root.tag('notification-ctr').animation({duration: 1, actions: [
  {t: '', p: 'visible', v: true, rv: false},
  {t: 'notification', p: 'x', v: {0: {v:600,sm:0}, 0.6: {v:200,sm:0}}},
  {t: 'notification', p: 'h', v: {0.6: {v:50,sm:0}, 1: {v:190,sm:0}}},
  {t: 'bg-overlay', p: 'alpha', v: {0: {v:0,sm:0}, 0.5: {v:1,sm:0}}}
]});

https://jsfiddle.net/basvanmeurs/bhdstyem/

Notice that the values are now encapsulated in objects with the v property. The sm value defines the smoothness around that point. By setting it to 0 the value transition becomes linear, while 1 it gets smoothened a lot. Check the API for other options on how to tune the auto smoothness.

You can also provide your own value function, which takes the (spline) progress from 0 to 1 and returns the value to be set to the property.

Stopping animations

After an animation has finished, the finally set property values will remain until you manually change them. Alternatively, you can stop an animation, which resets the values to some specified state. Usually, it just sets them to the values specified as defined in the action value property at the animation start. Example:

setTimeout(function() {
  a.stop();
}, 5000)

https://jsfiddle.net/basvanmeurs/mh50egcx/

As you can see, the default is to 'fade' the animation settings back to the original values gradually within one second. You affect this transition by setting the stopMethodOptions. Some other stop methods:

Check the API for a list of all animation methods, properties and events.

Development Tools

There is a handy tool available for inspection of rendered compontents. It keeps a 'real' HTML DOM rendering tree syncronized with the WPE UI Framework rendering tree, so that you are able to use the browser's web inspector to check on the layout of your rendering tree. You can even change the properties on the fly and see the result reflected in your stage!

To use it, include the script browser/inspect.js script after the wpe.js source file.

As an example, open the following jsfiddle and try the inspector on the graphics output:

https://jsfiddle.net/basvanmeurs/pybm5r9b/

Other helpful commands are the component.getLocationString() and component.toString() methods. They provide information about the tree location and the component branch.

Cleaning Up

When you want to gracefully stop your Node.js application (or want to completely remove the stage from your webpage), you must call stage.destroy(). This will make sure that all resources are freed, and will stop the render loop, allowing Node.js to quit.

API

Stage

Initialisation options

Usage: new Stage({w: 600, h: 600, ...}).

Methods

Events

Component

Properties

All of these properties can be set directly (using component.pivotX = 0.5) or via the set or stag method: component.set({pivotX: 0.5}).

Text sub object properties:

Methods

Events

Transition

Properties

Events

Animation

Methods

Properties

Action sub object properties

Action value item sub object properties

Events