What is WebGL?

WebGL is a Javascript API used to render 3D graphics to the screen in a browser. The WebGL API can be complicated and messy, but there are libraries that simplify this. One such library is Three.js. Three.js is a lightweight 3D library that hides a lot of the WebGL complexities and makes it very simple to do 3D programming on the web. Three.js can be downloaded from github or the three.js website, where you will also find links to documentation and examples.

Getting started

The source code for this tutorial and my others can be found here. If you want to implement this tutorial, you will need to get the three-scene-tut.html, all associated javascript, images, and models. For this tutorial, I’m going to talk about the code located here. If you’ve read my past tutorials, then you will notice that most of the code here is not new. You’ll see the init function at the beginning. In this function we create the scene object, add a perspective camera, create a directional light, and finally create a WebGL renderer. You will also notice that in the init function we make a call to two other functions that are new, the loadSkyBox function and the addSceneElements function. It’s these two functions that I’m going to focus on. Let’s begin with the skybox.

function loadSkyBox() {

 // Load the skybox images and create list of materials
 var materials = [
 createMaterial( 'images/skyX55+x.png' ), // right
 createMaterial( 'images/skyX55-x.png' ), // left
 createMaterial( 'images/skyX55+y.png' ), // top
 createMaterial( 'images/skyX55-y.png' ), // bottom
 createMaterial( 'images/skyX55+z.png' ), // back
 createMaterial( 'images/skyX55-z.png' ) // front
 ];
 // Create a large cube
 var mesh = new THREE.Mesh( new THREE.BoxGeometry( 100, 100, 100, 1, 1, 1 ), new THREE.MeshFaceMaterial( materials ) );
 // Set the x scale to be -1, this will turn the cube inside out
 mesh.scale.set(-1,1,1);
 scene.add( mesh ); 
}
function createMaterial( path ) {
 var texture = THREE.ImageUtils.loadTexture(path);
 var material = new THREE.MeshBasicMaterial( { map: texture, overdraw: 0.5 } );
return material; 
}

In the first line of code we create an array of materials. The materials are created by the createMaterial function, where you can see we first load the image at the given path, then create the material. After creating the six materials needed for our skybox, we then create a box with the dimensions of 100 wide, 100 tall, and 100 deep. We create the box using a MeshFaceMaterial. This will map each material to a face of the box. Next, you will notice that we set the scale of the box to -1 along the x axis. Why do this? Well, the standard box geometry that we are using faces outwards, but we want our images to be mapped to the inside of the box. By setting the scale to -1 along one of the axis, it doesn’t matter which one, we then invert the box so that it now faces inward.

The next thing I’m going to go over is the addSceneElements function. In this function we do two things: we load an externally created model along with all its textures, and we create the ground.   

Loading Models

To load an external model we need to use one of the many loaders that have been written for Three.js. The loader you will use will depend on what file format your model is saved as. A list of all the loaders can be found in the Three.js github repo.  

The model format we are using for this example is OBJ. The OBJ format uses a separate file to store the material information for the model, an MTL file. Let’s take a look at the code:

Since we have both an OBJ file and an MTL file we use the OBJMTLoader. In the first line we create an instance of the loader. In the second line we call the load function. The load function takes up to five parameters. The first is the path to your model and the second is the path to the material file. The third function is a callback function for when the model is loaded. The last two parameters are also callback functions. One is to track progress and the other is used to capture any errors that may occur while fetching the model. As you can see we’ve defined our load callback function inline. In it we simply give our loaded object a name so that we can easily reference later if needed. Next we set its position, and finally add it to the scene. Pretty simple and straightforward. One thing to note, the MTL file format specifies the location of the images used for textures. You may need to modify this path to load properly. The location of the textures is defined as relative to the MTL file. You can use any text editor to edit the MTL file.

In the second part of the addSceneElements function we create a ground to place our car on.

Next we tell Three.js that we are going to tile this texture across our plane by setting its wrap settings to RepeatWrapping:

var groundBump = THREE.ImageUtils.loadTexture('images/wet-sand-normal.jpg');
groundBump.wrapS = THREE.RepeatWrapping;
groundBump.wrapT = THREE.RepeatWrapping;