1. Getting Started

1.1 What Is Three.js?

Hello, and welcome to 3D in the browser with three.js. A tuts+ course with me, Stuart Memo. In this course we'll be learning about the popular client side JavaScript library, three.js. Three.js's aim is to help developers create 3D graphics in the browser by simplifying the more complicated WebGL API. It provides a nice API and some developer friendly concepts to help you create shapes, lights, cameras and everything else you need for a 3D world. So you heard me mention WebGL, let's start with that and see how it fits into what we'll do. WebGL is a JavaScript API for rendering 3D computer graphics in a web browser without the use of plug-ins. And more importantly, WebGL is integrated completely into the web standards of the browser, allowing GPU accelerated usage of physics and image processing and effects as part of the web page canvas. This is great news as it means that the browser will offload any drawing calculations to the graphics processor unit, meaning your code will run a lot smoother. So, sounds great. Why do we need to bother with three? Well, take a look at this code here. This is the amount of code needed to create a cube with a texture in WebGL, hundreds of lines. Now look at the amount of code it takes to do the same thing in three. Three removes all that complexity and gives us a much simpler API to work with. When we write code that uses three, we're still using WebGL, but three's doing the donkey work, making those more complicated calls for us. Makes sense, okay let's get started.

1.2 What You Need

Three.js is designed to work in your web browser. So to begin we'll need a webpage. Create a directory in your computer for your project, then create a bare bones HTML file called index.html. We'll need all the standard bits and bobs like so. Okay, we've got our HTML element, a head, a title, body. Looks good. Let's open the page in a browser and take a look. If we inspect using the browser's developer tools, you'll learn that by default there was an 8 pixel margin around the body element. Let's get rid of that so we have the whole browser window for our masterpiece. Back in our HTML just open a style tag. And inside specify the body element and give a margin of 0. And while we're at it, our 3D drawing will be rendered to the HTML canvas element. And by default this element is inline which means we'll end up with a scroll bar. Let's just change that to display block. Super. Let's just check that. Okay, great. Now we'll head over to threejs.org. So you may be tempted to hit the download button here which is fine but not actually what we're going to be using. This link here downloads a huge 150 megabyte ZIP file with codes, documentation, and examples. But all we want just now is the library, nothing else. So click the GitHub link, and in the readme you can see we can download the minified library. Save this to the root directory of your project. Now we'll add a little script tag to reference the downloaded library. Put this just before the closing body tag, so we know all the elements in the page are there before we do anything. So that's the library added, what about error code? Where is that going to go? Let's create a JavaScript file just for that. Let's create one in the same location three.js and call it main.js. Inside we'll just play a basic hello log message. We'll have to reference this file in our HTML. We want to have access to the three library so let's add another script tag underneath it, like so. If we save that then open the browser and then open the JavaScript console we should see our message. There it is, perfect. We're ready to start making something. Well, not quite actually. We need an empty DOM element so that three has somewhere to put the canvas element it creates. Just create an empty div and give it an id of container. Now we're really ready.