Welcome!

Welcome to the official BlackBerry Support Community Forums.

This is your resource to discuss support topics with your peers, and learn from each other.

inside custom component

Web and WebWorks Development

Sample Application - Using HTML5 Web Workers

by Administrator on ‎02-04-2011 03:18 PM - edited on ‎02-04-2011 03:18 PM by BlackBerry Development Advisor (9,870 Views)

Introduction

 

HTML5 brings with it a number of interesting and useful advances in web technology and its support is one of the major advances offered by the new BlackBerry® 6.0 browser.

 

The focus of this sample application is web workers. This is the name given in HTML 5 to the new constructs which allow code written in JavaScript® to be executed in a background thread. The ability to fire off background threads offers the dual benefits of improved performance and a more responsive UI, with potentially long running calculations for example, decoupled from the UI itself.

 

HTML 5 also introduces the Canvas element. This is a 2D drawing surface which can be updated using a range of graphics operations from within JavaScript.

 

In this sample, we combine both web workers and the Canvas class to produce a multi-threaded animation web application based around the idea of a “PolySquiggle”. A PolySquiggle is a wireframe object consisting of a randomly generated number of vertices, topology and geometry. PolySquiggle objects can rotate in 3D about either one of the x, y or z axes. The sample application provides a web page within which, up to four completely independent PolySquiggle objects can be created. When the user clicks a “create” hyperlink, the PolySquiggle is generated and immediately starts to rotate. Clicking on the PolySquiggle causes it change the axis of rotation.

 

 

workers.png

Figure 1: PolySquiggle sample application

 

 

 

Solution Walkthrough

 

The index.html page contains a table which has 4 rows. Each row contains:

 

A canvas element <canvas id="canvas0" width="100" height="100" onclick="changeAxis(0)">
A link which controls the animation for this row’s canvas. Note that the link changes according to the state of the animation and will offer either a create or stop function. <a href="javascript&colon;create('0')">create<a/>
A status message area <td id="Status()"></td>

 

Note that each PolySquiggle has a numeric ID of 0-3 and this is reflected in the HTML id names used for the canvas and status area and in the parameter passed to the start/stop function calls.

 

JavaScript

 

JavaScript appears in two parts of the application. There is an embedded <script> element in index.html and there is an external JavaScript file called actions/animator.js.

 

The script in index.html is concerned with the creation and startup of a PolySquiggle and with actually drawing lines on the relevant Canvas element. We’ll refer to this as the parent script.

 

The script in animator.js is primarily concerned with calculating co-ordinates of line segments and applying rotation transformations to those segments, every 50ms. Note that web workers cannot update the DOM and therefore it is not possible to write to the Canvas elements from within the web workers. Therefore the web workers perform calculation work and hand the results of their calculations back to the parent JavaScript for use in canvas operations. How this is achieved is explained below.

 

In index.html, the most important part of the embedded parent JavaScript is the start(id) function. This function uses an array called worker_active[id] to track which of the four PolySquiggles is running. If appropriate, it creates a new Worker object to run a new PolySquiggle. The Worker class is the JavaScript class which implements the new web workers functionality and it is this class which you use to run a JavaScript *file* in the background. When creating a Worker, it is common to create a callback function called onmessage in-line:

 

 

worker.onmessage = function(event) {
// ... logic that processes messages sent from the Worker
};

 

The onmessage function provides the means by which communication between the main UI thread and its child web workers can take place. Invocation of an onmessage function is achieved by using the JavaScript postMessage function and it is also the only way in which parameters can be passed between the parent script and a worker script. For example, in animator.js we can see that the web worker’s own onmessage function makes callbacks to the code in index.html to provide a status message. It also uses postMessage from within the animationLoop(id) functions to send a list of co-ordinate pairs between which lines must be drawn on the canvas.

 

 

The following snippet shows how a message is passed back to the parent JavaScript in index.html. The Message class is defined as having a type, as relating to a particular PolySquiggle ID and optionally, having some specific content. Here we pass the status message “Rotation about…” and the name of the axis which the PolySquiggle has begin rotating around:

 

 

message = new Message(MESSAGE_TYPE_STATUS, id, "Rotation about" + getAxisName());
postMessage(message);

 

The animate(id) function initiates the animation.  Here we see that the animationLoop is called once at the very start and then it is called every 50ms after that:

 

 

function animate(id) 
{
// rotate and call back for drawing every 100ms
animationLoop(id);
setInterval(function() { animationLoop(id); }, 50);
}

 

The animationLoop method, which exists within the Worker object, performs the animation of the Polysquiggle object.  As shown in the following code sample, a rotation transformation is applied to the PolySquiggle data using basic trigonometry functions and that this data is then used to “trace a path” for subsequent drawing onto the canvas. Remember that it is not possible to update the DOM from within our worker and consequently “tracing a path” involves preparing an array of Line objects, each of which contains the co-ordinates of a line start and end point. We post this array back to the parent script with postMessage and it is there, in the MESSAGE_TYPE_DRAW case for the switch statement, that the actual graphics operations which draw the lines onto the canvas element takes place:

 

 

function animationLoop(id) {
rotate(axis, angle);
di = tracePath();
message = new Message(MESSAGE_TYPE_DRAW, id, di);
postMessage(message);
}

 

 

Support:

 

HTML5 Web Workers are supported by the BlackBerry 6 and BlackBerry® Tablet OS browser rendering engine, powered by WebKit.  Content that uses web workers can be rendered directly from the browser application, or from within applications created using the BlackBerry WebWorks Application Platform.

 

Attached are two versions of the sample application, formatted as Projects for the BlackBerry® WebWorks™ Plug-in for Eclipse® and the BlackBerry® WebWorks™ Plug-in for Microsoft® Visual Studio® 2008.

 

Links:

 

Known Issues:

  • Early versions of the BlackBerry Smartphone Simulator may not render progressive frames of the animation effect demonstrated in this sample.  The first frame will be drawn, and subsequent frames may only refresh when the user clicks on the canvas element.  This behavior does not occur on live BlackBerry Smartphones.
Contributors