source: other-projects/playing-in-the-street/summer-2013/trunk/Playing-in-the-Street-WPF/Content/Web/mrdoob-three.js-4862f5f/docs/manual/introduction/Creating-a-scene.html@ 28897

Last change on this file since 28897 was 28897, checked in by davidb, 10 years ago

GUI front-end to server base plus web page content
File size: 8.4 KB
Line 
1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <script src="../../list.js"></script>
6 <script src="../../page.js"></script>
7 <link type="text/css" rel="stylesheet" href="../../page.css" />
8 </head>
9 <body>
10 <h1>[name]</h1>
11
12 <div>The goal of this section is to give a brief introduction to Three.js. We will start by setting up a scene, with a spinning cube. A working example is provided at the bottom of the page, if you get stuck, and need help.</div>
13
14 <h2>What is Three.js?</h2>
15
16 <div>If you're reading this, you probably have some understanding of what Three.js is, and what it helps you with, but let's try to describe it briefly anyway.</div>
17
18 <div>Three.js is a library that makes WebGL - 3D in the browser - very easy. While a simple cube in raw WebGL would turn out hundreds of lines of Javascript and shader code, a Three.js equivalent is only a fraction of that.</div>
19
20 <h2>Before we start</h2>
21 <div>Before you can use Three.js, you need somewhere to display it. Save the following HTML to a file on your computer, and open it in your browser.</div>
22
23 <code>
24 &lt;html&gt;
25 &lt;head&gt;
26 &lt;title&gt;My first Three.js app&lt;/title&gt;
27 &lt;style&gt;canvas { width: 100%; height: 100% }&lt;/style&gt;
28 &lt;/head&gt;
29 &lt;body&gt;
30 &lt;script src="https://rawgithub.com/mrdoob/three.js/master/build/three.js"&gt;&lt;/script&gt;
31 &lt;script&gt;
32 // Our Javascript will go here.
33 &lt;/script&gt;
34 &lt;/body&gt;
35 &lt;/html&gt;
36 </code>
37
38 <div>That's all. All the code below goes into the empty &lt;script&gt; tag.</div>
39
40 <h2>Creating the scene</h2>
41
42 <div>To actually be able to display anything with Three.js, we need three things: A scene, a camera, and a renderer so we can render the scene with the camera.</div>
43
44 <code>
45 var scene = new THREE.Scene();
46 var camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );
47
48 var renderer = new THREE.WebGLRenderer();
49 renderer.setSize( window.innerWidth, window.innerHeight );
50 document.body.appendChild( renderer.domElement );
51 </code>
52
53 <div>Let's take a moment to explain what's going on here. We have now set up the scene, our camera and the renderer. There are a few different cameras in Three.js, but we'll go more into that later. For now, let's use a PerspectiveCamera. The first attribute is the <strong>field of view</strong>.</div>
54
55 <div>The second one is the <strong>aspect ratio</strong>. 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.</div>
56
57 <div>The next two attributes are the <strong>near</strong> and <strong>far</strong> clipping plane. What that means, is that objects further away from the camera than the value of <strong>far</strong> or closer than <strong>near</strong> won't be rendered. You don't have to worry about this now, but you may want to use other values in your games to get better performance.</div>
58
59 <div>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.</div>
60
61 <div>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 game - in this case, the width and height of the browser window. For performance intensive games, you can also give <strong>setSize</strong> smaller values, like <strong>window.innerWidth/2</strong> and <strong>window.innerHeight/2</strong>, for half the resolution. This does not mean that the game will only fill half the window, but rather look a bit blurry and scaled up.</div>
62
63 <div>Last but not least, we add the <strong>renderer</strong> element to our HTML document. This is a &lt;canvas&gt; element the renderer uses to display the scene to us.</div>
64
65 <div><em>"That's all good, but where's that cube you promised?"</em> Let's add it now.</div>
66
67 <code>
68 var geometry = new THREE.CubeGeometry(1,1,1);
69 var material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
70 var cube = new THREE.Mesh( geometry, material );
71 scene.add( cube );
72
73 camera.position.z = 5;
74 </code>
75
76 <div>To create a cube, we need a <strong>CubeGeometry</strong>. This is an object that contains all the points (<strong>vertices</strong>) and fill (<strong>faces</strong>) of the cube. We'll explore this more in the future.</div>
77
78 <div>In addition to the geometry, we need a material to color it. Three.js comes with several materials, but we'll stick to the <strong>MeshBasicMaterial</strong> for now. All materials take an object of properties which will be applied to them. To keep things very simple, we only supply a color attribute of <strong>0x00ff00</strong>, which is green. This works the same way that colors work in CSS or Photoshop (<strong>hex colors</strong>).</div>
79
80 <div>The third thing we need is a <strong>Mesh</strong>. A mesh is an object that takes a geometry, and applies a material to it, which we then can insert to our scene, and move freely around.</div>
81
82 <div>By default, when we call <strong>scene.add()</strong>, the thing we add will be added to the coordinates <strong>(0,0,0)</strong>. This would cause both the camera and the cube to be inside each other. To avoid this, we simply move the camera out a bit.</div>
83
84 <h2>Rendering the scene</h2>
85
86 <div>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 <strong>render loop</strong>.</div>
87
88 <code>
89 function render() {
90 requestAnimationFrame(render);
91 renderer.render(scene, camera);
92 }
93 render();
94 </code>
95
96 <div>This will create a loop that causes the renderer to draw the scene 60 times per second. If you're new to writing games in the browser, you might say "why don't we just create a <strong>setInterval</strong>? The thing is - we could, but <strong>requestAnimationFrame</strong> 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.</div>
97
98 <h2>Animating the cube</h2>
99
100 <div>If you insert all the code above into the file you created before we began, you should see a green box. Let's make it all a little more interesting by rotating it.</div>
101
102 <div>Add the following right above the <strong>renderer.render</strong> call in your <strong>render</strong> function:</div>
103
104 <code>
105 cube.rotation.x += 0.1;
106 cube.rotation.y += 0.1;
107 </code>
108
109 <div>This will be run every frame (60 times per second), and give the cube a nice rotation animation. Basically, anything you want to move or change while the game / app is running has to go through the render loop. You can of course call other functions from there, so that you don't end up with a <strong>render</strong> function that's hundreds of lines.
110 </div>
111
112 <h2>The result</h2>
113 <div>Congratulations! You have now completed your first Three.js application. It's simple, you have to start somewhere.</div>
114
115 <div>The full code is available below. Play around with it to get a better understanding of how it works.</div>
116
117 <code>
118 &lt;html&gt;
119 &lt;head&gt;
120 &lt;title&gt;My first Three.js app&lt;/title&gt;
121 &lt;style&gt;canvas { width: 100%; height: 100% }&lt;/style&gt;
122 &lt;/head&gt;
123 &lt;body&gt;
124 &lt;script src="three.min.js"&gt;&lt;/script&gt;
125 &lt;script&gt;
126 var scene = new THREE.Scene();
127 var camera = new THREE.PerspectiveCamera(75, window.innerWidth/window.innerHeight, 0.1, 1000);
128
129 var renderer = new THREE.WebGLRenderer();
130 renderer.setSize(window.innerWidth, window.innerHeight);
131 document.body.appendChild(renderer.domElement);
132
133 var geometry = new THREE.CubeGeometry(1,1,1);
134 var material = new THREE.MeshBasicMaterial({color: 0x00ff00});
135 var cube = new THREE.Mesh(geometry, material);
136 scene.add(cube);
137
138 camera.position.z = 5;
139
140 var render = function () {
141 requestAnimationFrame(render);
142
143 cube.rotation.x += 0.1;
144 cube.rotation.y += 0.1;
145
146 renderer.render(scene, camera);
147 };
148
149 render();
150 &lt;/script&gt;
151 &lt;/body&gt;
152 &lt;/html&gt;
153 </code>
154 </body>
155</html>
Note: See TracBrowser for help on using the repository browser.