The goal of this section is to give a brief introduction to three.js.
Usage
The Three.js library is a single JavaScript file. It can be included within a web page by linking to a local or remote copy.
<script
src
=
"js/three.min.js"
></script>
HTML Code
Before you can use three.js, you need somewhere to display it. Save the following HTML to a file on your computer, along with a copy of three.js in the js/ directory, and open it in your browser.
<!DOCTYPE html>
<html>
<head>
<meta
charset
=
"utf-8">
<title>
Creating a scene
</title>
<style>
body
{
margin
:
0;
}
canvas
{
display
:
block;
}
</style>
</head>
<body>
<script src =
"js/three.min.js"
></script>
<script>
// Our Javascript will go here
[js/scene.js].
</script>
</body>
</html>
That's all. All the code below goes into the empty js/scene.js tag.
Creating the scene
To actually be able to display anything with three.js, we need three things: scene, camera and renderer, so that we can render the scene with camera.
var scene
=
new
THREE.Scene();
var
camera
=
new
THREE.PerspectiveCamera
(75,
window.innerWidth
/
window.innerHeight
,
0.1, 1000);
var
renderer
= new
THREE.WebGLRenderer();
renderer.setSize(window.innerWidth
, window.innerHeight);
document.body.appendChild(renderer
.domElement);
We have now set up the scene, our camera and the renderer.
There are a few different cameras in three.js (e.g. Perspective and Orthographic camera). For now, let's use a Perspective camera.
The first attribute is the field of view (FOV). FOV is the extent of the scene that is seen on the display at any given moment. The value is in degrees.
The second one is the aspect ratio. You almost always want to use the width of the element divided by the height, or you'll get the same result as when you play old movies on a widescreen TV - the image looks squished.
The next two attributes are the near and far clipping plane. What that means, is that objects further away from the camera than the value of far or closer than near won't be rendered. You don't have to worry about this now, but you may want to use other values in your apps to get better performance.
Figure 1: A Perspective camera defines its frustum based on 4 properties(fov, near, far and aspect ratio).
Next up is the renderer. This is where the magic happens. In addition to the WebGLRenderer we use here, three.js comes with a few others, often used as fallbacks for users with older browsers or for those who don't have WebGL support for some reason.
In addition to creating the renderer instance, we also need to set the size at which we want it to render our app. It's a good idea to use the width and height of the area we want to fill with our app − in this case, the width and height of the browser window. For performance intensive apps, you can also give setSize smaller values, like window.innerWidth/2 and window.innerHeight/2, which will make the app render at half size.
If you wish to keep the size of your app but render it at a lower resolution, you can do so by calling setSize with false as updateStyle (the third argument). For example, setSize(window.innerWidth/2, window.innerHeight/2, false) will render your app at half resolution, given that your canvas has 100% width and height.
Rendering the scene
If you copied the code from above into the HTML file we created earlier, you wouldn't be able to see anything. This is because we're not actually rendering anything yet. For that, we need what's called a render or animate loop.
function animate ();
{
requestAnimationFrame(animate);
renderer.render(scene, camera
);
}
animate();
This will create a loop that causes the renderer to draw the scene every time the screen is refreshed (on a typical screen this means 60 times per second). If you're new to writing games in the browser, you might say "why don't we just create a setInterval?" The thing is − we could, but requestAnimationFrame has a number of advantages. Perhaps the most important one is that it pauses when the user navigates to another browser tab, hence not wasting their precious processing power and battery life.
Result
Congratulations! You have now completed your first three.js application. It's simple, you have to start somewhere.
Project download canvas.zip