It's a big world, but someone has to make it rotate!

Day 4:HTML5 Animation using Three.js

Three.js is a lightweight JavaScript 3D library with a very low level of complexity. It supports canvas, svg and WebGL renderers. Browser support for WebGL renderers is still a little spotty, particularly on Mobile, so for example if you wanted to run a WebGL 3D project on the IPad or some older Android phones, it wouldn’t work, however canvas based animations in Three.js would work on an iPad.

The process of getting the Three.js lib into your project is the same as it was for JQuery which was covered in Day 3: HTML5 Animation using JQuery.

Getting Started
All 3D libs are fairly similar. If you are familiar with Flash back in 2008 or so there was a popular 3D library called Papervision. Well think of Three.js as Papervision for JavaScript. It provides the same functionality and the ability to import 3D models into your project and move them around or create your own mesh’s using the tools in the lib.

Creating a Scene
In a 3D world, you will always need the same 3 things:

A Scene

A Camera

A Renderer

All 3D libs are similar in this way. You’re going to put objects in your scene, view them thru the camera and render it in real-time. Rendering is kind of like an update function that will re-render the scene to show the updates in real time. The camera is necessary to the application so you know what view to render the scene from.

3D rotating cube using WebGL
Whenever I’m using a new 3D library, I always like to start out by making a cube, rotate it and maybe add a texture map. In this particular case, if we wanted to add a texture map, we’ll have to host our project online. Due to security issues we can’t load the texture locally. There is a work around for it, but for the purposes of this tutorial we’ll just host our sample. You can see a sample here.

If you test this in your browser you will likely see a black cube rotating without textures, because of the security issue I spoke about however if you hosted the sample folder, you’d see the texture. It should look like the image below.

I’ll go over it line by line below.

Line 9 we import our Three.js scripts (as described in Day2 of this series)

Line 13 is our requestAnimFrame . using requestAnimFrame instead of a setTimeout because this method is optimized by the browser particularly for animation. The browser doesn’t know what your intentions are with setTimeout, but with requestAnimFrame your browser knows what you are trying to do and will assist you.

Line 46 window.onload = function() {} if you remember from previous days lessons is how we wait for all the HTML to be loaded before we call JavaScript.

Inside the anonymous function we set a couple of vars, angularSpeed and lastTime. angularSpeed is revolutions per second and lastTime is derived from the computer clock and is a way to make sure the animations are smooth and there is no render lag.

Line 52 We create the renderer
Line 57 We create the camera

Line 62 we create the scene

Line 65 we create the materials or texture map

Line 71 we create the cube

Line 75 we rite the ambient light

Line 80 we create a directional light

Line 85 we create a wrapper or container that holds all the objects and inside we set the vars for the renderer, camera, scene and cube.

Line 90 we load a texture by creating a Image class. When the image loads we call an anonymous function and in there we call the animate function, passing in 4 params, lastTime, angular speed, three and this. We’ll cover these params as we go along. The important takeaway from this paragraph is that we don’t start our animation until the texture is loaded.

Line 26 we call the animate function and pass it three params lastTime, angularSpeed and three). basically current time, speed and the wrapper

The most important things we’re doing here is setting up smooth animation with date, time and timeDiff. This is done the same way in Flash and other rendering engines, we use the computer’s internal clock to get the current time and use that to make sure we don’t get any elasticity or rubber banding in our animation. I’m not going to get into the date, time, timeDiff variables too much in this tutorial.

The most important math being done here is angleChange. this is where we use a lot of math to come up with basically a rotation speed.

on Line 33 we rotate our cube using angleChange.

on Line 37 we have our container renderer rener the scene and pass in the scene and the camera as params.

on line 40 we call requestAnimFrame and pass in an anonymous function to call animate again. This creates a continous loop that essentially fires off animate over and over again. Animate calls render and that is how we update our geometry in real time.

Thats it for a simple cube with texture using WebGL. I will hopefully do some more tutorials in the future using Three.js to cover how to import a collada or how to output a model in Blender to JSON Three.js format as well as using Canvas to create 3D animations instead of WebGL.