Load your web page, and it will parse, translate, and run your sketch in the browser.

Why Processing.js?

The Web: from Java to JavaScript

Processing is built using Java. It was created at much the same time that the web
was starting. At this time the choice of the Java language, and Java Runtime, as
implementation targets for Processing made a lot of sense. In the mid-1990s, Java
was poised to become the language of the web, with Applets and other Java technologies
being used broadly on the client-side. Even Netscape, who created the language which
would eventually become the lingua franca of the web with JavaScript, named their
language so as to align themselves with the growing hype around Java.

In the end, Java became an important server side technology, receding from the client-side
and browser. Today, most web browsers still support Java Applets, by means of a
binary plugin. However, few web developers deploy Java-based web applications now,
due to long load and startup times and difficulties relying on Java (or compatible
Java versions) being installed. This trend is not isolated to Java, but is happening
to all browser plugins (e.g., Flash), which are becoming less popular as issues
of security, installation, deployment, etc. make them inconvenient or risky.

Another reason that plugins like Java and Flash have fallen out of favour is that
recent advances in standard web technologies, specifically HTML5 and JavaScript,
have made it possible to do things that previously depended on native (i.e., faster,
compiled) code. Companies like Google, with GMail and Google Docs, or Scribd (see
Scribd-in-HTML5)
have shown that HTML, CSS, and JavaScript alone are enough to build fast, full featured
web applications.

Processing.js uses Modern Web Standards

Processing.js is built using JavaScript and HTML5. Processing.js is really two things:
a Processing-to-JavaScript translator; and an implementation of the Processing API
(e.g., functions like line(), stroke(), etc.) written in JavaScript instead of Java.
It might seem odd at first to imagine your Processing sketches running in a browser,
usually without modification. But this is exactly what Processing.js enables.

Processing.js automatically converts your Processing code to JavaScript. This means
that you don't have to learn JavaScript in order to run your code in a browser.
You can, quite literally, write your code using the Processing IDE like you always
have, and follow the steps below to get it running on the web. There's nothing new
to learn, beyond getting a simple web page created.

Under the hood, Processing.js uses the new HTML5 canvas element to create your sketch's
graphics. The canvas element is a new feature of the web, and is either implemented
or will be implemented by all major web browsers. All Processing drawing features
have been reimplemented in Processing.js to use canvas, so any browser that supports
canvas will also support Processing.js.

Here's a sample of a Processing.js sketch running in the browser. If you can see
it working, your browser supports everything you need already, and you can move
on to instructions below.

Writing a Processing.js Sketch

There's nothing you should do differently to write sketches for Processing.js: you
write your Processing.js code exactly like Processing. For most people, this will
mean using the Processing IDE, which has the nice benefit of letting you write,
run, and test your code all in once place. Remember, any valid Processing sketch
should also be a valid Processing.js sketch.

If you want to experiment with web-based Processing.js code editors, you can also
try these:

Obtaining Processing.js

Processing.js is a JavaScript library that is meant to be included in a web page.
You don't have to compile it, tell your web server about it, etc. It simply has
to be included in a web page, and the browser will do the rest.

You can download Processing.js at the download
page. The library comes in a number of forms, for example:

processing-1.0.0.js (note that 1.0.0 is just the version, the number might be higher
when you look at this)

processing-1.0.0.min.js

The version numbers may be different as you read this, but note the file extensions.
Both end in .js, but one also has .min. The .min version is Processing.js in a minified
form, which means it will be smaller to download (minified JavaScript uses tricks
like removing whitespace and renaming long variable names to single letters). File
sizes, and download times, matter on the web in a way they don't with normal Processing
sketches.

Creating a Processing.js Web Page

It's easy to get overwhelmed with the amount there is to learn about modern web
technologies. But there's a secret: you can ignore 95% of it as you start, and add
more later as you have time and interest. Unlike compilers or programming languages,
web browsers are designed to accept almost any input you throw at them, whether
valid or not, whether complete or not. Here's your first Processing.js web page:

That's it! No <html> or <body> tags, no title, no CSS, just the processing.js
script, and a canvas. While there isn't much here, it's important to understand
what is. First, the script tag has a src attribute, which is the file to
load. This could be a full url or a relative path. In this case the browser is going
to look for a file named processing-1.0.0.min.js in the same directory as
your web page.

The second thing in this web page is a <canvas&gt tag. Notice that it too has
an attribute, data-processing-sources. This is a list of filenames (or just
one filename if you only have 1 file) separated by spaces (filenames and URLs on
the web can't include spaces, so space is a safe choice for separating lists). In
this case, the browser is going to look for a file named hello-web.pde located
in the same directory as your page page.

How does the browser know how to load a Processing *.pde file? Processing.js takes
care of this, and will download, parse (i.e., translate to JavaScript), then run
it automatically when the page is loaded.

And that's it! Save this file to the same directory as hello-web.pde and
processing-1.0.0.min.js and call it hello-web.html.

If you're the kind of person who doesn't like taking shortcuts, here's what a more
complete web page might look like:

Both ways work, and you shouldn't let yourself get burdened by HTML and other web
syntax until you feel you want to do other things with your web pages.

Running your Processing.js Web Page

In case it isn't obvious, you run your hello-web.pde sketch by loading your
hello-web.html web page in a compatible browser. Web browsers will provide
you a way to load a local file, usually using the File menu and then Open File....
If you've saved the files above on a web server, you can use the remote URL instead.

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.

Processing.js only has two rendering modes

Processing has many rendering modes to choose from, depending on the desired quality
and speed for graphics (e.g., OPENGL, P3D, JAVA2D, etc.). Processing.js uses <canvas>
which provides either a 2D drawing context or a 3D context based on WebGL (a version
of OpenGL for the web). Therefore, whatever you choose, you will end-up with either
the 2D or 3D context.

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:

JavaScript, and as such Processing.js, has no "char" datatype

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 int()
and str() functions, so that you know you're explicitly comparing datatypes that
JavaScript can deal with.

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:

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:

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 line of code
that will be executed before the program begins.

If you have multiple images to load, use a list like so:

1/* @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.
This is equally true for built-in functions and functions you create. A good rule-
of-thumb is: avoid having a variable foo in the same sketch as a function
foo();.

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:

1classX 2{ 3voiddoSomething() 4{ 5... 6} 7 8voiddoSomething(floatx,floaty) 9{10...11}12}1314classYextendsX15{16voiddoSomething()17{18// different code from compared to the super class19}2021// even though we don't override this method,22// its signature must be added to prevent Pjs23// from getting the method chain wrong:24voiddoSomething(floatx,floaty)25{26super.doSomething(x,y);27}28}

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.

Also in the class of integer vs. floating point issues, color(number) and color(number, number)
may not behave quite as expected. In native Processing, color(int) and color(float) behave
differently in that the first is used for full color integers. Calling color(#FF0000) and
color(16711680) are the same call, so they produce a red color. However, when using float
values the color()/1 function treats the input as gray values, between 0 and the max indicated
value (255, by default). Any value lower than 0 or higher than max is simply capped. Because of
the integer vs. floating point issues with JavaScript, Processing.js does not perform any capping,
and so even though the following code will show a black and a white line in Processing, it will
show a yellow line, and an "invisible" line in Processing.js instead.

We recommend you always sanitize your inputs for color if you need colors to be "in range", and only use hex colors, using color(#RRGGBB), or rgb/rgba colors, using color(r,g,b) and color(r,g,b,a)

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 recommended 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:

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 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.

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.