Processing.js for JavaScript Devs
Processing.js Quick Start - JavaScript Developer Edition
Introduction
This quick start guide is written from the standpoint of a JavaScript developer. The document assumes you know JavaScript and web programming, but only very basic Processing knowledge is assumed.
For the Impatient
If you're in a rush, here's what you need to know:
- Processing.js converts Processing code to JavaScript and runs it in the browser, using <canvas> for a drawing surface.
- To use it, download Processing.js here: http://processingjs.org/download
- Make your Processing *.pde files as you normally would, for example hello-web.pde
- Create a web page that includes Processing.js as well as a <canvas> with info about where to get your sketch file:
<script src="processing-0.9.7.min.js"></script> <canvas data-processing-sources="hello-web.pde"></canvas>
Load your web page, and it will parse, translate, and run your sketch in the browser.
Why Processing.js?
What is Processing?
The Processing language was originally created at MIT as part of the Media lab and Aesthetics and Computation group. They needed a way to bridge the gap between software developers, artists, data visualizers, etc., and to do so in a way that allowed new programmers (or non-programmers) to do complex visual work easily. Processing was built using Java, and can be thought of as a simplified Java, with a simplified Java API for drawing and graphics.
What does Processing bring to the web?
Processing has a large and vibrant community, who are good at creating 2D and 3D graphics, visualizing data sets, audio, video, etc. With HTML5 the web gained <canvas>, <audio>, and <video>--things which had previously only been available via plugins like Flash or Java. At the same time, advances in JavaScript engines, have made it possible to do things in script that were previously unthinkable.
By porting the Processing language to the web, both the Processing and web communities benefit. For Processing, this means that code which used to only work on the desktop now "just works" in the browser. For the web, this means that a new but mature and full-featured approach to graphics programming becomes available. The <canvas> element is too low-level for most developers to use directly--JavaScript libraries are necessary. Processing.js can be thought of as just such a library.
How much work is it to learn Processing?
The Processing language was designed to be small but complete, and easy to learn. Having said that, it is
...todo....
- processing.js is not really a general purpose JS canvas library--it is a port of Processing.js.
Ways to Use Processing.js
Processing.js was originally created in order to allow existing Processing developers and existing Processing code (often referred to as sketches) to work unmodified on the web. As a result, the recommend way to use Processing.js is to write Processing code, and have Processing.js convert it to JavaScript before running it.
Over time, many web developers have begun using Processing.js, and asked that we design a way for the API to be used separate from the Processing language itself. Therefore, we have provided a way for JavaScript developers to write pure JavaScript code and still use the Processing.js functions and objects.
Below we discuss the various methods for using Processing.js in your web pages.
Writing Pure Processing Code
This is the preferred method for using Processing.js, and has been dealt with at length in the Processing.js for Processing Devs quick start guide. To summarize:
- Download Processing.js here: http://processingjs.org/download
- Create a separate Processing file or files, naming them whatever you want, but usually *.pde or *.pjs.
- Create a web page that includes Processing.js as well as a <canvas> with info about where to get your sketch file(s), and include Processing filenames as a space-separated list in a data-processing-sources attribute on the canvas:
<!DOCTYPE html>
<html>
<head>
<title>Hello Web - Processing.js Test</title>
<script src="processing-0.9.7.min.js"></script>
</head>
<body>
<h1>Processing.js Test</h1>
<p>This is my first Processing.js web-based sketch:</p>
<canvas data-processing-sources="hello-web.pde"></canvas>
</body>
</html>
Processing.js will automatically scan the document on page load for <canvas> elements with data-processing-sources, download the files using XMLHTTPRequest, and feed them to the Processing-to-JavaScript translator. The resulting JavaScript is run using eval.
Writing Documents that Combine Processing and JavaScript Code
One of the first questions people ask with Processing.js is whether they can read values from the document in which the Processing sketch is running, or vice versa. The answer is yes.
Processing.js converts Processing code into JavaScript contained in a function closure. The variables and functions you create are not attached to the global object (i.e., window). However, you can still get access to them.
Accessing JavaScript Objects from Processing
Since Processing code gets converted to JavaScript and run like any other function, all Processing code has access to the global object. This means that if you create a variable or function in a global script block, they are automatically accessible to Processing. Consider this example:
First the Processing file, mixing.pde:
String processingString = "Hello from Processing!";
void setup() {
printMessage(jsString + " " + processingString);
}
Next the web page:
<!DOCTYPE html>
<html>
<head>
<title>Hello Web - Accessing JavaScript from Processing</title>
<script src="processing-0.9.7.min.js"></script>
</head>
<body>
<div id="msg"></div>
<canvas data-processing-sources="mixing.pde"></canvas>
<script type="application/javascript">
var jsString = "Hello from JavaScript!";
var printMessage = function(msg) {
document.getElementById('msg').innerHTML = "Message: " + msg;
};
</script>
</body>
</html>
Here Processing.js allows the use of a variable and function declared outside the Processing code.
Mixing JavaScript and Processing
The previous example kept a clean separation between the JavaScript and Processing code, while loosening the boundary between the two. Because Processing.js converts Processing code to JavaScript, it's also possible to mix them directly. The Processing.js parser will leave JavaScript it finds within the Processing code unaltered, allowing developers to write a hybrid of Processing and JavaScript. Here is the previous example rewritten using this method:
var jsString = "Hello from JavaScript!";
var printMessage = function(msg) {
document.getElementById('msg').innerHTML = "Message: " + msg;
};
String processingString = "Hello from Processing!";
void setup() {
printMessage(jsString + " " + processingString);
}
There is some JavaScript syntax that can't be easily mixed this way (e.g., regex literals). In those cases you can simply move your pure JavaScript to a <script> block and access it using the method described above.
Accessing Processing from JavaScript
Reaching out from the Processing code to JavaScript is easier than going the other way, since the JavaScript created by the Processing.js parser is not exposed directly on the global object. Instead, you gain access using the Processing.instances property.
The Processing constructor keeps track of instances it creates, and makes them available using the getInstanceById() method. By default, when a <canvas> has a data-processing-sources attribute, its id is used as a unique identifier for the Processing instance. If no id attribute is provided, you can use Processing.instances[0].
After you have a reference to the appropriate Processing instance, you can call into it like so:
<!DOCTYPE html>
<html>
<head>
<title>Hello Web - Controlling Processing from JavaScript</title>
<script src="processing-0.9.7.min.js"></script>
</head>
<body>
<div id="msg"></div>
<canvas id="sketch" data-processing-sources="controlling.pde"></canvas>
<button onclick="startSketch();">Start</button>
<button onclick="stopSketch();">Stop</button>
<script type="application/javascript">
var processingInstance;
function startSketch() {
switchSketchState(true);
}
function stopSketch() {
switchSketchState(false);
}
function switchSketchState(on) {
if (!processingInstance) {
processingInstance = Processing.getInstanceById(sketch);
}
if (on) {
processingInstance.loop(); // call Processing loop() function
} else {
processingInstance.noLoop(); // stop animation, call noLoop()
}
}
</script>
</body>
</html>
Things to Know as a Processing Developer using Processing.js
While Processing.js is compatible with Processing, Java is not JavaScript, and canvas has some differences from Java's graphics classes. Here are some tricks and tips as you start working on more complex sketches in Processing.js.
Processing.js has no data directory
Processing uses the concept of a data directory, where images and other resources are located. Processing.js does not include this. As a result, you should always provide file pages (e.g., images) that are relative to your web page, which is the norm on the web.
Processing.js implements Processing, but not all of Java
Processing.js is compatible with Processing, but is not, and will never be, fully compatible with Java. If your sketch uses functions or classes not defined as part of Processing, they are unlikely to work with Processing.js. Similarly, libraries that are written for Processing, which are written in Java instead of Processing, will most likely not work.
Division which is expected to produce an integer might need explicit casting
There are a class of bugs that arise when converting Processing code to Processing.js that involve integer vs. floating point division. What was straight-up integer division in Processing code, when converted to Processing.js, can sometimes become problematic, as numbers become doubles, and introduce a fractional part. The fix is to explicitly cast any division to an integer that exhibits this behaviour:
// before int g = mouseX / i; // after int g = (int)(mouseX / i);
Processing.js has to cheat to simulate Processing's synchronous I/O
Processing uses a synchronous I/O model, which means that functions like loadImage() take time to execute, and while they are running, nothing else happens: the program waits until loadImage() is done before moving on to the next statement. This means that you can count on the value returned by a function like loadImage() being usable in the next line of code.
Web browsers don't work like this. The web uses an asynchronous I/O model, which means that functions which load external resources can't make the program wait until they finish. In order to replicate Processing's load* functions, you have to use a special Processing.js Directive.
The Processing.js Directives are hints to the browser that are written in comments rather than in the Processing code itself. Here's a typical Processing sketch that loads an image synchronously and then draws it:
PImage img;
void setup() {
img = loadImage("picture.jpg");
image(img, 0, 0);
}
This code will not work in the browser with Processing.js, because the call to image() will happen before the file picture.jpg has been downloaded. The fix is to ask Processing.js to download the image before the sketch starts, and cache it--a technique known as preloading. Here is the modified code:
/* @pjs preload="picture.jpg"; */
PImage img;
void setup() {
img = loadImage("picture.jpg");
image(img, 0, 0);
}
Notice the extra comment line at the top of the code. The @pjs directive is for Processing.js, and not the developer. Think of it as an extra in of code that will be executed before the program begins.
If you have multiple images to load, use a list like so:
/* @pjs preload="picture.jpg,picture2.jpg,picture3.png"; */
Processing.js requires more care with variable naming than Processing
One of the powerful features of JavaScript is its dynamic, typeless nature. Where typed languages like Java, and therefore Processing, can reuse names without fear of ambiguity (e.g., method overloading), Processing.js cannot. Without getting into the inner-workings of JavaScript, the best advice for Processing developers is to not use function/class/etc. names from Processing as variable names. For example, a variable named line might seem reasonable, but it will cause issues with the similarly named line() function built-into Processing and Processing.js.
It is possible to put Processing code directly in your web page
Using the data-processing-sources attribute on the canvas, and having Processing.js load an external file is the preferred and recommend way to include scripts in a web page. However, it is also possible to write in-line Processing code.
A few changes are necessary to make the example above work with inline Processing code:
<script src="processing-0.9.7.min.js"></script>
<script type="application/javascript">
/*
* This code searches for all the <script type="application/processing" target="canvasid">
* in your page and loads each script in the target canvas with the proper id.
* It is useful to smooth the process of adding Processing code in your page and starting
* the Processing.js engine.
*/
if (window.addEventListener) {
window.addEventListener("load", function() {
var scripts = document.getElementsByTagName("script");
var canvasArray = Array.prototype.slice.call(document.getElementsByTagName("canvas"));
var canvas;
for (var i = 0, j = 0; i < scripts.length; i++) {
if (scripts[i].type == "application/processing") {
var src = scripts[i].getAttribute("target");
if (src && src.indexOf("#") > -1) {
canvas = document.getElementById(src.substr(src.indexOf("#") + 1));
if (canvas) {
new Processing(canvas, scripts[i].text);
for (var k = 0; k< canvasArray.length; k++)
{
if (canvasArray[k] === canvas) {
// remove the canvas from the array so we dont override it in the else
canvasArray.splice(k,1);
}
}
}
} else {
if (canvasArray.length >= j) {
new Processing(canvasArray[j], scripts[i].text);
}
j++;
}
}
}
}, false);
}
</script>
<script type="application/processing" target="processing-canvas">
void setup() {
size(200, 200);
background(100);
stroke(255);
ellipse(50, 50, 25, 25);
println('hello web!');
}
</script>
<canvas id="processing-canvas"></canvas>
This code is more complex because it has to figure out which canvas goes with which script (i.e., you can have multiple Processing sketches living in the same page, and therefore, multiple canvses). Also note that the scripts include a type attribute, which distinguishes between JavaScript and Processing code (the browser will ignore Processing scripts). Finally, note the use of the id and target attributes to connect the Processing script with the associated canvas.
Portions of the code above are from the Processing.js project's init.js file, see http://github.com/annasob/processing-js/blob/0.9.8/examples/init.js. This file will likely be going away in the future, and happen automatically as part of Processing.js initialization.
Whatever you can do with the web, you can do with Processing.js
Now that your sketch is working, and you have a basic web page, you'll probably start getting ideas about how to make this look more beautiful, how to better integrate your sketch with the surrounding web page or site, and how to mix data from various web services and APIs. Is it possible to mix images on Flickr and a Processing.js sketch? Yes. Is it possible to link Twitter to Processing.js? Yes. Anything the web can do, your Processing.js sketch can do.
This is an important idea, and is worth restating: Processing.js turned your once Java-based code into JavaScript, and your graphics into <canvas>. As a result, anything you read on the web about dynamic web programming, AJAX, other JavaScript libraries or APIs, all of it applies to your sketch now. You aren't running code in a box, cut-off from the rest of the web. Your code is a first-class member of the web, even though you didn't write it that way.
If you're feeling adventurous and want to go learn more about how to do other thing with HTML, JavaScript, CSS, etc. remember that everything they say applies to you and your sketches.