HOME

ABOUT

LAB

TUTORIALS

BLOG

INTRODUCTION
I have used Three.js for some of my experiments, and it does a really great job of abstracting away the headaches of getting going with 3D in the browser. With it you can create cameras, objects, lights, materials and more, and you have a choice of renderer, which means you can decide if you want your scene to be drawn using HTML 5's canvas, WebGL or SVG. And since it's open source you could even get involved with the project. But right now I'll focus on what I've learned by playing with it as an engine, and talk you through some of the basics. For all the awesomeness of Three.js, there can be times where you might struggle. Typically you will need to spend quite a large amount of time with the examples, reverse engineering and (in my case certainly) hunting down specific functionality and occasionally asking questions via GitHub. If you have to ask questions, by the way, you should do that on Stack Overflow !

1. THE BASICS
I will assume that you have at least a passing knowledge of 3D, and reasonable proficiency with JavaScript. If you don't it may be worth learning a bit before you try and play with this stuff, as it can get a little confusing. In our 3D world we will have some of the following, which I will guide you through the process of creating: 1. 2. 3. 4. A scene A renderer A camera An object or two (with materials)

You can, of course, do some crazy things, and my hope is that you will go on to do that and start to experiment with 3D in your browser.

2. SUPPORT
Just a quick note on support in the browsers. Google's Chrome browser is, in my experience, the best browser to work with in terms of which renderers are supported, and the speed of the underlying JavaScript engine. Chrome supports Canvas, WebGL and SVG and it's blazingly fast. Firefox is a close second; its JavaScript engine does seem to be a touch slower than Chrome's, but again its support for the render technologies is great. It's also getting faster with each version, which is handy. Opera also has WebGL support and Safari on Mac has an option to enable it. So while it has it, it's best to work on the basis that Safari only supports Canvas rendering. Internet Explorer 9+ only supports Canvas rendering right now, although you never know what the future holds.

3. SET THE SCENE

I'll assume you've chosen a browser that supports all the rendering technologies, and that you want to render with Canvas or WebGL, since they're the more standard choices. Canvas is more widely supported than WebGL, but it's worth noting that WebGL runs on your graphics card's GPU, which means that your CPU can concentrate on other non-rendering tasks like any physics or user interaction you're trying to do. Irrespective of your chosen renderer you should bear in mind that the JavaScript will need to optimised for performance. 3D isn't a lightweight task for a browser (and it's awesome that it's

even possible), so be careful to understand where any bottlenecks are in your code, and remove them if you can! So with that said, and on the assumption you have downloaded and included three.js in your HTML file, how do you go about setting up a scene? Like this:

/ /s e tt h es c e n es i z e v a rW I D T H=4 0 0 , H E I G H T=3 0 0 ; / /s e ts o m ec a m e r aa t t r i b u t e s v a rV I E W _ A N G L E=4 5 , A S P E C T=W I D T H/H E I G H T , N E A R=0 . 1 , F A R=1 0 0 0 0 ; / /g e tt h eD O Me l e m e n tt oa t t a c ht o / /-a s s u m ew e ' v eg o tj Q u e r yt oh a n d v a r$ c o n t a i n e r=$ ( ' # c o n t a i n e r ' ) ; / /c r e a t eaW e b G Lr e n d e r e r ,c a m e r a / /a n das c e n e v a rr e n d e r e r=n e wT H R E E . W e b G L R e n d e r e r ( ) ; v a rc a m e r a= n e wT H R E E . P e r s p e c t i v e C a m e r a ( V I E W _ A N G L E , A S P E C T , N E A R , F A R ) ; v a rs c e n e=n e wT H R E E . S c e n e ( ) ; / /a d dt h ec a m e r at ot h es c e n e s c e n e . a d d ( c a m e r a ) ; / /t h ec a m e r as t a r t sa t0 , 0 , 0 / /s op u l li tb a c k c a m e r a . p o s i t i o n . z=3 0 0 ; / /s t a r tt h er e n d e r e r r e n d e r e r . s e t S i z e ( W I D T H ,H E I G H T ) ; / /a t t a c ht h er e n d e r s u p p l i e dD O Me l e m e n t $ c o n t a i n e r . a p p e n d ( r e n d e r e r . d o m E l e m e n t ) ;

Not too tricky, really!

4. MAKING A MESH
So we have a scene, a camera and a renderer (I opted for a WebGL one in my sample code) but we have nothing to actually draw. Three.js actually comes with support for loading a few different standard file types, which is great if you are outputting models from Blender, Maya, Cinema4D or anything else. To keep things simple (this is about getting started after all!) I'll talk about primitives. Primitives are geometric meshes, relatively basic ones like Spheres, Planes, Cubes and Cylinders. Three.js lets you create these types of primitives easily:

/ /s e tu pt h es p h e r ev a r s v a rr a d i u s=5 0 , s e g m e n t s=1 6 , r i n g s=1 6 ; / /c r e a t ean e wm e s hw i t h / /s p h e r eg e o m e t r y-w ew i l lc o v e r / /t h es p h e r e M a t e r i a ln e x t ! v a rs p h e r e=n e wT H R E E . M e s h ( n e wT H R E E . S p h e r e G e o m e t r y ( r a d i u s , s e g m e n t s , r i n g s ) , s p h e r e M a t e r i a l ) ; / /a d dt h es p h e r et ot h es c e n e s c e n e . a d d ( s p h e r e ) ;

All good, but what about the material for the sphere? In the code we've used a variable sphereMaterial but we've not defined it yet. First we need to talk about materials in a bit more detail.

5. MATERIALS
Without doubt this is one of the most useful parts of Three.js. It provides for you a number of common (and very handy) materials to apply to your meshes: 1. Basic, which just means that it renders 'unlit' 2. Lambert 3. Phong There are more, but again in the interests of simplicity I'll let you discover those for yourself. In the case of WebGL particularly these materials can be a life-saver. Why? Well because in WebGL you have to write shaders for everything being rendered. Shaders are a huge topic in themselves, but in short they are written in GLSL (OpenGL Shader Language), which tells the GPU how something should look. This means you need to mimic the maths of lighting, reflection and so on. It can get very complicated very quickly. Thanks to Three.js you don't have to do this if you don't want to because it abstracts that away for you. If you want to write shaders, however, you can do that too with a MeshShaderMaterial, so it's a flexible setup. For now, however, let's apply a lambert material to the sphere:

/ /c r e a t et h es p h e r e ' sm a t e r i a l v a rs p h e r e M a t e r i a l= n e wT H R E E . M e s h L a m b e r t M a t e r i a l ( { c o l o r :0 x C C 0 0 0 0 } ) ;

It's worth pointing out as well that there are other properties you can specify when you create a material besides the colour, such as smoothing or environment maps. You should check out the docs for the various properties you can set on the materials and, in fact, any object that the engine provides for you.

6. LIGHTS!
If you were to render the scene right now you'd see a red circle. Even though we have a Lambert material applied there's no light in the scene so by default Three.js will revert to a full ambient light, which is the same as flat colouring. Let's fix that with a simple point of light:

/ /c r e a t eap o i n tl i g h t v a rp o i n t L i g h t= n e wT H R E E . P o i n t L i g h t ( 0 x F F F F F F ) ; / /s e ti t sp o s i t i o n p o i n t L i g h t . p o s i t i o n . x=1 0 ; p o i n t L i g h t . p o s i t i o n . y=5 0 ; p o i n t L i g h t . p o s i t i o n . z=1 3 0 ; / /a d dt ot h es c e n e s c e n e . a d d ( p o i n t L i g h t ) ;

7. RENDER LOOP
We now actually have everything set up to render, remarkably. But we actually need to go ahead and do just that:

/ /d r a w ! r e n d e r e r . r e n d e r ( s c e n e ,c a m e r a ) ;

You're probably going to want to render more than once, though, so if you're going to do a loop you should really use requestAnimationFrame; it's by far the smartest way of handling animation in the browser. It's not fully supported as yet, so I'd totally recommend that you take a look at Paul Irish's shim .

8. COMMON OBJECT PROPERTIES

If you take time to look through the code for Three.js you'll see a lot of objects "inherit" from Object3D. This is a base object which contains some very useful properties, such as the position, rotation and scale information. In particular our Sphere is a Mesh which inherits from Object3D, to which it adds its own properties: geometry and materials. Why do I mention these? Well it's unlikely you're going to want to just have a sphere on your screen that does nothing, and these properties are worth investigating as they allow you to manipulate the underlying details of the meshes and materials on the fly.

/ /s p h e r eg e o m e t r y s p h e r e . g e o m e t r y / /w h i c hc o n t a i n st h ev e r t i c e sa n df a c e s s p h e r e . g e o m e t r y . v e r t i c e s/ /a na r r a y s p h e r e . g e o m e t r y . f a c e s/ /a l s oa na r r a y / /i t sp o s i t i o n s p h e r e . p o s i t i o n/ /c o n t a i n sx ,ya n dz s p h e r e . r o t a t i o n/ /s a m e s p h e r e . s c a l e/ /. . .s a m e

9. DIRTY LITTLE SECRETS

I just wanted to quickly point out a quick gotcha for Three.js, which is that if you modify, for example, the vertices of a mesh, you will notice in your render loop that nothing changes. Why? Well because Three.js (as far as I can tell) caches the data for a mesh as something of an optimisation. What you actually need to do is to flag to Three.js that something has changed so it can recalculate whatever it needs to. You do this with the following:

/ /s e tt h eg e o m e t r yt od y n a m i c / /s ot h a ti ta l l o wu p d a t e s s p h e r e . g e o m e t r y . d y n a m i c=t r u e ; / /c h a n g e st ot h ev e r t i c e s s p h e r e . g e o m e t r y . v e r t i c e s N e e d U p d a t e=t r u e ; / /c h a n g e st ot h en o r m a l s s p h e r e . g e o m e t r y . n o r m a l s N e e d U p d a t e=t r u e ;

Again there are more, but those two I've found are the most useful. You should obviously only flag the things that have changed to avoid unnecessary calculations.

CONCLUSION
Well I hope you've found this brief introduction to Three.js helpful. There's nothing quite like actually getting your hands dirty and trying something, and I can't recommend it highly enough. 3D running natively in the browser is a lot of fun, and using an engine like Three.js takes away a lot of the headaches for you and lets you get to making some seriously cool stuff. To help you out a bit I've wrapped up the source code in this lab article, so you can use that as a reference. If you've enjoyed this let me know via Google+ or Twitter, it's always good to say hello!

AFTER THE NONESENSE COMES THE OBLIGATORY FOOTER

Heroes and Villains
Tom Know les Karl Stanton Hakim El Hattab Justin Windle Paul Irish Brendan Kenny Cameron Adams