GABRO

The best way to explore the functionality of the scene is by looking at an example. In the source code for this chapter (chapter-02), you can find the 01-basic-scene. html example. I'll use this example to explain the various functions and options that a scene has. When we open this example in the browser, the output will look something like the following screenshot:

Chapter 2

[ 39 ]

This looks pretty much like the examples that we've seen in the previous chapter. Even though the scene looks somewhat empty, it already contains a couple of objects. By looking at the following source code, we can see that we've used the Scene.add(object) function from the THREE.Scene() object to add a THREE.Mesh (the ground plane that you see), a THREE.SpotLight. and a THREE.AmbientLight object. The THREE.Camera object is added automatically by the Three.js library when you render the scene, but can also be added manually if you prefer.

var scene = new THREE.Scene();

var camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 1000); ...

var planeGeometry = new THREE.PlaneGeometry(60,40,1,1);

var planeMaterial = new THREE.MeshLambertMaterial({color: 0xffffff}); var plane = new THREE.Mesh(planeGeometry,planeMaterial);

...

scene.add(plane);

var ambientLight = new THREE.AmbientLight(0x0c0c0c);

scene.add(ambientLight);

...

var spotLight = new THREE.SpotLight( 0xffffff ); ...

scene.add( spotLight );

Before we look deeper into the THREE.Scene() object, I'll first explain what you can

do in the demonstration, and after that we'll look at some code. Open this example in your browser and look at the controls at the upper-right corner as you can see in the following screenshot:

Working with the Basic Components That Make Up a Three.js Scene

[ 40 ]

With these controls you can add a cube to the scene, remove the last added cube from the scene, and show all the current objects that the scene contains. The last entry in the control section shows the current number of objects in the scene. What you'll probably notice when you start up the scene is that there are already four objects in the scene. These are the ground plane, the ambient light, the spot light, and the camera that we had mentioned earlier. In the following code fragment, we'll look at each of the functions in the control section and start with the easiest one: the addCube() function:

this.addCube = function() {

var cubeSize = Math.ceil((Math.random() * 3)); var cubeGeometry = new

THREE.CubeGeometry(cubeSize,cubeSize,cubeSize); var cubeMaterial = new THREE.MeshLambertMaterial( {color: Math.random() * 0xffffff });

var cube = new THREE.Mesh(cubeGeometry, cubeMaterial); cube.castShadow = true;

cube.name = "cube-" + scene.children.length;

cube.position.x=-30 + Math.round( (Math.random() * planeGeometry.width)); cube.position.y= Math.round((Math.random() * 5)); cube.position.z=-20 + Math.round((Math.random() * planeGeometry.height)); scene.add(cube); this.numberOfObjects = scene.children.length; };

This piece of code should be pretty easy to read by now. Not many new concepts are introduced here. When you click on the addCube button, a new THREE.CubeGeometry instance is created with a random size between zero and three. Besides a random size, the cube also gets a random color and position in the scene.

A new thing in this piece of code is that we also give the cube a name by using the name attribute. Its name is set to cube- appended with the number of objects currently in the scene (shown by the scene.children.length property). So you'll get names like cube-1, cube-2, cube-3, and so on. A name can be useful for

debugging purposes, but can also be used to directly find an object in your scene.

If you use the Scene.getChildByName(name) function, you can directly retrieve a

specific object and, for instance, change its location. You might wonder what the last

line in the previous code snippet does. The numberOfObjects variable is used by our control GUI to list the number of objects in the scene. So whenever we add or remove an object, we set this variable to the updated count.

Chapter 2

[ 41 ]

The next function that we can call from the control GUI is removeCube and, as the name implies, clicking on this button removes the last added cube from the scene.

The following code snippet shows how this function is defined:

this.removeCube = function() { var allChildren = scene.children;

var lastObject = allChildren[allChildren.length-1]; if (lastObject instanceof THREE.Mesh) {

scene.remove(lastObject);

this.numberOfObjects = scene.children.length; }

}

To add an object to the scene we will use the add() function. To remove an object from the scene we use the not very surprising remove() function. In the given code fragment we have used the children property from the THREE.Scene() object to get the last object that was added. We also need to check whether that object is a Mesh object in order to avoid removing the camera and the lights. After we've removed the object, we will once again update the GUI property that holds the number of objects in the scene.

The final button on our GUI is labeled as outputObjects. You've probably already clicked on it and nothing seemed to happen. What this button does is print out all the objects that are currently in our scene and will output them to the web browser

Working with the Basic Components That Make Up a Three.js Scene

[ 42 ]

The code to output information to the Console log makes use of the built-in console object as shown:

this.outputObjects = function() { console.log(scene.children); }

This is great for debugging purposes; especially when you name your objects, it's

very useful for finding issues and problems with a specific object in your scene.

For instance, the properties of the cube-17 object will look like the following code snippet: __webglActive: true __webglInit: true _modelViewMatrix: THREE.Matrix4 _normalMatrix: THREE.Matrix3 _vector: THREE.Vector3 castShadow: true children: Array[0] eulerOrder: "XYZ" frustumCulled: true geometry: THREE.CubeGeometry id: 20 material: THREE.MeshLambertMaterial matrix: THREE.Matrix4 matrixAutoUpdate: true matrixRotationWorld: THREE.Matrix4 matrixWorld: THREE.Matrix4 matrixWorldNeedsUpdate: false name: "cube-17" parent: THREE.Scene position: THREE.Vector3 properties: Object quaternion: THREE.Quaternion receiveShadow: false renderDepth: null rotation: THREE.Vector3 rotationAutoUpdate: true scale: THREE.Vector3 up: THREE.Vector3 useQuaternion: false visible: true __proto__: Object

Chapter 2

[ 43 ]

So far we've seen the following scene-related functionality:

• Scene.Add(): This method adds an object to the scene

• Scene.Remove(): This removes an object from the scene

• Scene.children(): This method gets a list of all the children in the scene

• Scene.getChildByName(): This gets a specific object from the scene by using

the name attribute

These are the most important scene-related functions, and most often you won't need any more. There are, however, a couple of helper functions that could come in handy, and I'd like to show them based on the code that handles the cube rotation. As you've already seen in the previous chapter, we had used a render loop to render the scene. Let's look at the same code snippet for this example:

function render() { stats.update();

scene.traverse(function(e) {

if (e instanceof THREE.Mesh && e != plane ) { e.rotation.x+=controls.rotationSpeed; e.rotation.y+=controls.rotationSpeed; e.rotation.z+=controls.rotationSpeed; } }); requestAnimationFrame(render); renderer.render(scene, camera); }

Here we can see that the THREE.Scene.traverse() function is being used. We can pass a function as an argument to the traverse() function. This passed in function will be called for each child of the scene. In the render() function, we will use the traverse() function to update the rotation for each of the cube instances (we will explicitly ignore the ground plane). We could also have done this by iterating over the children property array by using a for loop.

Before we dive into the Mesh and Geometry object details, I'd like to show you two interesting properties that you can set on the Scene object: fog and overrideMaterial.

Working with the Basic Components That Make Up a Three.js Scene

[ 44 ]