2011-12-04-jsQuickStart.html

---
layout: default
desc: A guide to Processing.js for JavaScript developers
title: JavaScript Quick Start
permalink: /articles/jsQuickStart.html
---
<div>
    <h3>
        Processing.js Quick Start - JavaScript Developer Edition</h3>
    <h4>
        Introduction</h4>
    <p>
        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.</p>
    <h4>
        Index</h4>
    <ol>
        <li style="margin-bottom: 0px;"><a href="#quickstart">For the Impatient</a></li>
        <li style="margin-bottom: 0px;"><a href="#whyprocessingjs">Why Processing.js?</a>
            <ol>
                <li style="margin-bottom: 0px;"><a href="#whatisprocessing">What is Processing?</a></li>
                <li style="margin-bottom: 0px;"><a href="#whatdoesprocessingbrintotheweb">What does Processing bring to the web?</a></li>
                <li style="margin-bottom: 0px;"><a href="#learnprocessing">How much work is it to learn Processing?</a></li>
            </ol>
        </li>
        <li style="margin-bottom: 0px;"><a href="#waystouseprocessingjs">Ways to use Processing.js</a>
            <ol>
                <li style="margin-bottom: 0px;"><a href="#writingpureprocessingcode">Writing Pure Processing Code</a></li>
                <li style="margin-bottom: 0px;"><a href="#processingcodetojavascript">Pre-compiling Processing code to JavaScript</a></li>
                <li style="margin-bottom: 0px;"><a href="#javascriptonlyprocessingcode">Writing JavaScript-only Processing.js code</a></li>
                <li style="margin-bottom: 0px;"><a href="#combineprocessingandjavascript">Writing Documents that Combine Processing and JavaScript Code</a>
                    <ol>
                        <li style="margin-bottom: 0px;"><a href="#accessingjsobjectsfrompjs">Accessing JavaScript Objects from Processing</a></li>
                        <li style="margin-bottom: 0px;"><a href="#mixingjsandprocessing">Mixing JavaScript and Processing</a></li>
                        <li style="margin-bottom: 0px;"><a href="#accessingprocessingfromjs">Accessing Processing from JavaScript</a></li>
                    </ol>
                </li>
            </ol>
        </li>
        <li style="margin-bottom: 0px;"><a href="#thingstoknowusingpjs">Things to Know as a JavaScript Developer using Processing.js</a>
            <ol>
                <li style="margin-bottom: 0px;"><a href="#externalsproperty">Processing.js provides access to various DOM/JavaScript objects via the externals property</a></li>
                <li style="margin-bottom: 0px;"><a href="#explicitcasting">Division which is expected to produce an integer might need explicit casting</a></li>
                <li style="margin-bottom: 0px;"><a href="#nochartype">JavaScript, and as such Processing.js, has no "char" datatype</a></li>
                <li style="margin-bottom: 0px;"><a href="#synchronousIO">Processing.js has to cheat to simulate Processing's synchronous I/O</a></li>
                <li style="margin-bottom: 0px;"><a href="#variablenamingcare">Processing.js requires more care with variable naming than Processing</a></li>
                <li style="margin-bottom: 0px;"><a href="#methodoverriding">Processing.js needs your help when overriding overloaded superclass methods</a></li>
                <li style="margin-bottom: 0px;"><a href="#processingcodeinwebpage">It is possible to put Processing code directly in your web page</a></li>
            </ol>
        </li>
    </ol>
    <h4>
        <b><a name="quickstart">For the Impatient</a></b></h4>
    <p>
        If you're in a rush, here's what you need to know:</p>
    <ol>
        <li>Processing.js converts Processing code to JavaScript and runs it in the browser,
            using &lt;canvas&gt; for a drawing surface.</li>
        <li>To use it, download Processing.js here: <a href="http://processingjs.org/download">
            downloads</a></li>
        <li>Make your Processing *.pde files as you normally would, for example hello-web.pde</li>
        <li>Create a web page that includes Processing.js as well as a &lt;canvas&gt; with info
            about where to get your sketch file (you can specify multiple *.pde files, separating
            them with spaces):</li>
    </ol>

{% highlight html linenos %}
<script src="processing-1.3.6.min.js"></script>
<canvas data-processing-sources="hello-web.pde"></canvas>
{% endhighlight %}

    <p>
        Load your web page, and it will parse, translate, and run your sketch in the browser.</p>
    <h3>
        <a name="whyprocessingjs">Why Processing.js?</a></h3>
    <h4>
        <b><a name="whatisprocessing">What is Processing?</a></b></h4>
    <p>
        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.</p>
    <h4>
        <b><a name="whatdoesprocessingbrintotheweb">What does Processing bring to the web?</a></b></h4>
    <p>
        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 too slow.</p>
    <p>
        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 &lt;canvas&gt;
        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, simplifying
        the use of the 2D and 3D canvas operations.</p>
    <h4>
        <b><a name="learnprocessing">How much work is it to learn Processing?</a></b></h4>
    <p>
        The Processing language was designed to be small but complete, and easy to learn.
        This document does not attempt to teach you Processing, and you are encouraged to
        seek out Processing specific tutorials, books, and examples. Any Processing code
        or concepts should map to Processing.js (the exceptions are listed below). You can
        also use pure JavaScript to work with the Processing drawing API, skipping the Java
        syntax of Processing in favour of JavaScript.</p>
    <h3>
        <a name="waystouseprocessingjs">Ways to Use Processing.js</a></h3>
    <p>
        Processing.js was originally created in order to allow existing Processing developers
        and existing Processing code (often referred to as <i>sketches</i>) 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.</p>
    <p>
        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. NOTE: Processing.js
        is first and foremost a port of Processing to the open web, with design decisions
        favouring compatibility with Processing. It was not designed as a general purpose
        HTML drawing library. Having said that, it can be used as a high-level drawing API
        for canvas.</p>
    <p>
        Below we discuss the various methods for using Processing.js in your web pages.</p>
    <h4>
        <b><a name="writingpureprocessingcode">Writing Pure Processing Code</a></b></h4>
    <p>
        This is the preferred method for using Processing.js, and has been dealt with at
        length in the <a href="http://processingjs.org/reference/articles/p5QuickStart">Processing.js
            for Processing Devs quick start guide</a>. To summarize:</p>
    <ol>
        <li>Download Processing.js from <a href="http://processingjs.org/download">here</a></li>
        <li>Create a separate Processing file or files, naming them whatever you want, as long as they have a
            *.pde extension.</li>
        <li>Create a web page that includes Processing.js as well as a &lt;canvas&gt; 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:</li>
    </ol>

{% highlight html linenos %}
<!DOCTYPE html>
<html>
<head>
  <title>Hello Web - Processing.js Test</title>
  <script src="processing-1.3.6.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>
{% endhighlight %}

    <p>
        Processing.js will automatically scan the document on page load for &lt;canvas&gt;
        elements with <b>data-processing-sources</b> attributes, download the files using
        XMLHTTPRequest, and feed them to the Processing-to-JavaScript translator. The resulting
        JavaScript is run using eval.</p>
    <h4>
        <b><a name="processingcodetojavascript">Pre-compiling Processing code to JavaScript</a></b></h4>
    <p>
        Processing.js automatically downloads and converts any Processing code to JavaScript.
        It does this using the Processing.compile() method, and those interested in building
        tools or utilities for Processing.js can do the same.</p>
    <p>
        In order to obtain "compiled" code (i.e., JavaScript suitable for use by the Processing.js
        runtime) from Processing code, do the following:</p>

{% highlight javascript linenos %}
// hard-coded Processing code, text from an HTML widget, downloaded text, etc.
var processingCode = "...";
var jsCode = Processing.compile(processingCode).sourceCode;
{% endhighlight %}

    <p>
        For example, converting the following Processing code produces the "compiled" JavaScript
        underneath:</p>

{% highlight javascript linenos %}
// Processing code
void setup() {
  size(200, 200);
  background(100);
  stroke(255);
  ellipse(50, 50, 25, 25);
  println("hello web!");
}

// "Comiled" JavaScript code
// this code was autogenerated from PJS
(function(processing, $constants) {
  function setup() {
    processing.size(200, 200);
    processing.background(100);
    processing.stroke(255);
    processing.ellipse(50, 50, 25, 25);
    processing.println("hello web!");
  }
  processing.setup = setup;
})
{% endhighlight %}

    <h4>
        <b><a name="javascriptonlyprocessingcode">Writing JavaScript-only Processing.js code</a></b></h4>
    <p>
        Since 1.4.9, this is not supported any more. <br>
        To write Javascript code, you can use 1.4.8 or other libraries like <a href="http://p5js.org/" target="_blank">p5js</a>.</p>
    <del>
    <p>
        The previous method produced JavaScript code from Processing, but you can also write
        JavaScript on its own. The Processing.js parser turns Processing code into a JavaScript
        function, then runs it. As a result, it's possible to skip the Processing code altogether,
        and simply write a JavaScript function, passing this to your Processing instance.
        Here's an example:</p>

{% highlight javascript linenos %}
function sketchProc(processing) {
  // Override draw function, by default it will be called 60 times per second
  processing.draw = function() {
    // determine center and max clock arm length
    var centerX = processing.width / 2, centerY = processing.height / 2;
    var maxArmLength = Math.min(centerX, centerY);

    function drawArm(position, lengthScale, weight) {
      processing.strokeWeight(weight);
      processing.line(centerX, centerY,
        centerX + Math.sin(position * 2 * Math.PI) * lengthScale * maxArmLength,
        centerY - Math.cos(position * 2 * Math.PI) * lengthScale * maxArmLength);
    }

    // erase background
    processing.background(224);

    var now = new Date();

    // Moving hours arm by small increments
    var hoursPosition = (now.getHours() % 12 + now.getMinutes() / 60) / 12;
    drawArm(hoursPosition, 0.5, 5);

    // Moving minutes arm by small increments
    var minutesPosition = (now.getMinutes() + now.getSeconds() / 60) / 60;
    drawArm(minutesPosition, 0.80, 3);

    // Moving hour arm by second increments
    var secondsPosition = now.getSeconds() / 60;
    drawArm(secondsPosition, 0.90, 1);
  };
}

var canvas = document.getElementById("canvas1");
// attaching the sketchProc function to the canvas
var processingInstance = new Processing(canvas, sketchProc);
{% endhighlight %}

    <p>
        Here a sketch function is created, similar to what the parser would produce. This
        function should take 1 argument, a reference to a processing object (i.e., the Processing
        runtime), which will be created by the Processing constructor. Any Processing functions
        or objects are accessible as properties of this object.</p>
    <p>
        Once that function is complete, pass it, along with a reference to a canvas, to
        the Processing constructor (remember to use <i>new</i>).</p></del>
    <h4>
        <b><a name="combineprocessingandjavascript">Writing Documents that Combine Processing and JavaScript Code</a></b></h4>
    <p>
        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.</p>
    <p>
        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.</p>
    <h4>
        <a name="accessingjsobjectsfrompjs">Accessing JavaScript Objects from Processing</a></h4>
    <p>
        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:</p>
    <p>
        First the Processing file, mixing.pde:</p>

{% highlight java linenos %}
String processingString = "Hello from Processing!";

void setup() {
  printMessage(jsString + " " + processingString);
}
{% endhighlight %}

    <p>
        Next the web page:</p>

{% highlight html linenos %}
<!DOCTYPE html>
<html>
<head>
    <title>Hello Web - Accessing JavaScript from Processing</title>
    <script src="processing-1.3.6.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>
{% endhighlight %}

    <p>
        Here Processing.js allows the use of a variable and function declared outside the
        Processing code.</p>
    <h4>
        <a name="mixingjsandprocessing">Mixing JavaScript and Processing</a></h4>
    <p>
        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 (NOTE: this is why we
        don't use a pure Processing parser approach in processing.js). Here is the previous
        example rewritten using this method:</p>

{% highlight javascript linenos %}
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);
}
{% endhighlight %}
    <p>
        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 &lt;script&gt;
        block and access it using the method described above.</p>
    <h4>
        <a name="accessingprocessingfromjs">Accessing Processing from JavaScript</a></h4>
    <p>
        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.</p>
    <p>
        The Processing constructor keeps track of instances it creates, and makes them available
        using the getInstanceById() method. By default, when a &lt;canvas&gt; 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].</p>
    <p>
        After you have a reference to the appropriate Processing instance, you can call
        into it like so:</p>

{% highlight html linenos %}
<!DOCTYPE html>
<html>
<head>
    <title>Hello Web - Controlling Processing from JavaScript</title>
    <script src="processing-1.3.6.min.js"></script>
</head>
<body>
    <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>
{% endhighlight %}

    <p>
        Here two buttons in the DOM are used to allow the user to start or stop a running
        Processing sketch. They control the Processing instance (you might have several
        in a page, or hidden in divs) directly from JavaScript, calling Processing functions:
        loop() and noLoop(). The Processing functions are well documented elsewhere.</p>
    <h3>
        <a name="thingstoknowusingpjs">Things to Know as a JavaScript Developer using Processing.js</a></h3>
    <p>
        While Processing.js tries to be fully compatible with Processing, there are some
        things which are different or require workarounds. We have also added some web-specific
        features to make Processing.js easier to use. Here are some tricks and tips as you
        start working on more complex sketches in Processing.js.</p>
    <h4>
        <b><a name="externalsproperty">Processing.js provides access to various DOM/JavaScript objects via the externals
            property</a></b></h4>
    <p>
        Each Processing instance (i.e., Processing.instances) has an <b>externals</b> property,
        which is an object containing references to various non-Processing DOM/JavaScript
        objects that can be useful. For example:</p>
    <ul>
        <li>canvas - the canvas to which the sketch is bound</li>
        <li>context - the canvas' context</li>
        <li>onblur and onfocus - event handlers</li>
    </ul>
    <h4>
        <b><a name="explicitcasting">Division which is expected to produce an integer might need explicit casting</a></b></h4>
    <p>
        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:</p>

{% highlight java linenos %}
// before
int g = mouseX / i;

// after
int g = (int)(mouseX / i);
{% endhighlight %}

    <p>
        See <a href="https://processing-js.lighthouseapp.com/projects/41284/tickets/532-drawing-artifacts-in-processingjs-not-in-processing-with-this-code">
            lighthouse bug</a></p>


    <h4 id="nochartype"><b>JavaScript, and as such Processing.js, has no "char" datatype</b></h4>
    <p> JavaScript only knows about numbers, and strings, unlike Java, which also knows about "char"
        data types. The char is a 16 bit unsigned integer value, that can also pretend to be a letter
        (from the ISO8859-1 codepage for the first 256 numbers, and basically magic after that).
        Unfortunately, as JavaScript has no equivalent, relying on char comparisons to be either numbers
        or letters is quite likely to cause problems. If you have Processing code where you're comparing
        chars, you will either have to perform int casting, or string casting, using the <b>int()</b>
        and <b>str()</b> functions, so that you know you're explicitly comparing datatypes that
        JavaScript can deal with.</p>


    <h4><b><a name="synchronousIO">Processing.js has to cheat to simulate Processing's synchronous I/O</a></b></h4>
    <p>
        Processing uses a synchronous I/O model, which means that functions like <b>loadImage()</b>
        take time to execute, and while they are running, nothing else happens: the program
        waits until <b>loadImage()</b> is done before moving on to the next statement. This
        means that you can count on the value returned by a function like <b>loadImage()</b>
        being usable in the next line of code.</p>
    <p>
        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.</p>
    <p>
        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:</p>

{% highlight java linenos %}
PImage img;

void setup() {
  img = loadImage("picture.jpg");
  image(img, 0, 0);
}
{% endhighlight %}

    <p>
        This code will not work in the browser with Processing.js, because the call to <b>image()</b>
        will happen before the file <b>picture.jpg</b> 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:</p>

{% highlight java linenos %}
/* @pjs preload="picture.jpg"; */
PImage img;

void setup() {
  img = loadImage("picture.jpg");
  image(img, 0, 0);
}
{% endhighlight %}

    <p>
        Notice the extra comment line at the top of the code. The <b>@pjs</b> directive
        is for Processing.js, and not the developer. Think of it as an extra line of code
        that will be executed before the program begins.</p>
    <p>
        If you have multiple images to load, use a list like so:</p>

{% highlight java linenos %}
/* @pjs preload="picture.jpg,picture2.jpg,picture3.png"; */
{% endhighlight %}

    <h4>
        <b><a name="variablenamingcare">Processing.js requires more care with variable naming than Processing</a></b></h4>
    <p>
        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 <b>line</b> might seem reasonable, but it will cause issues with
        the similarly named <b>line()</b> function built-into Processing and Processing.js.</p>

    <h4>
      <b><a name="methodoverriding">Processing.js needs your help when overriding overloaded superclass methods</a></b></h4>
    <p>
        If your code uses subclasses that override one or more overloaded methods in the superclass, you
        will need "dummy" overrides for every method signature that you'd normally leave untouched:</p>

{% highlight java linenos %}
class X
{
  void doSomething()
  {
    ...
  }

  void doSomething(float x, float y)
  {
    ...
  }
}

class Y extends X
{
  void doSomething()
  {
    // different code from compared to the super class
  }

  // even though we don't override this method,
  // its signature must be added to prevent Pjs
  // from getting the method chain wrong:
  void doSomething(float x, float y)
  {
    super.doSomething(x,y);
  }
}
{% endhighlight %}

    <p>
        Even though in Processing you will not need to implement the fallthrough method for doSomethign with a
        (float,float) signature, doing so is almost always necessary to make sure Processing.js doesn't get
        confused about which class's method to call.</p>

    <h4>
        <b><a name="processingcodeinwebpage">It is possible to put Processing code directly in your web page</a></b></h4>
    <p>
        Using the data-processing-sources attribute on the canvas, and having Processing.js
        load an external file is the preferred and recommended way to include scripts in
        a web page. However, it is also possible to write in-line Processing code.</p>
    <p>
        A few changes are necessary to make the example above work with inline Processing
        code:</p>

{% highlight html linenos %}
<script src="processing-1.3.6.min.js"></script>
<script type="application/processing" data-processing-target="pjs">
void setup() {
  size(200, 200);
  background(100);
  stroke(255);
  ellipse(50, 50, 25, 25);
  println('hello web!');
}
</script>
<canvas id="pjs"> </canvas>
{% endhighlight %}

    <p>
        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 canvases). Also note that the scripts include a <b>type</b>
        attribute, which distinguishes between JavaScript and Processing code (the browser
        will ignore Processing scripts). Finally, note the use of the <b>id</b> and <b>target</b>
        attributes to connect the Processing script with the associated canvas.</p>
</div>