diff options
Diffstat (limited to 'libraries/irrlicht-1.8/examples/01.HelloWorld/tutorial.html')
-rw-r--r-- | libraries/irrlicht-1.8/examples/01.HelloWorld/tutorial.html | 394 |
1 files changed, 394 insertions, 0 deletions
diff --git a/libraries/irrlicht-1.8/examples/01.HelloWorld/tutorial.html b/libraries/irrlicht-1.8/examples/01.HelloWorld/tutorial.html new file mode 100644 index 0000000..e46c954 --- /dev/null +++ b/libraries/irrlicht-1.8/examples/01.HelloWorld/tutorial.html | |||
@@ -0,0 +1,394 @@ | |||
1 | <html> | ||
2 | <head> | ||
3 | <title>Irrlicht Engine Tutorial</title> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | ||
5 | </head> | ||
6 | |||
7 | <body bgcolor="#FFFFFF" leftmargin="0" topmargin="0" marginwidth="0" marginheight="0"> | ||
8 | <br> | ||
9 | <table width="90%" border="0" cellspacing="0" cellpadding="2" align="center"> | ||
10 | <tr> | ||
11 | <td bgcolor="#666699"> <b><font color="#FFFFFF">Tutorial 1.HelloWorld</font></b></td> | ||
12 | |||
13 | </tr> | ||
14 | <tr> | ||
15 | <td height="90" bgcolor="#F7F3F7"> <div align="left"> | ||
16 | <p>This Tutorial shows how to set up the IDE for using the | ||
17 | Irrlicht Engine and how to write a simple HelloWorld program | ||
18 | with it. The program will show how to use the basics of | ||
19 | the VideoDriver, the GUIEnvironment and the SceneManager.<br> | ||
20 | The result of this example will look like this:</p> | ||
21 | <p align="center"><img src="../../media/001shot.jpg" width="259" height="204"><br> | ||
22 | </p> | ||
23 | </div></td> | ||
24 | |||
25 | </tr> | ||
26 | </table> | ||
27 | <br> <table width="90%" border="0" cellspacing="0" cellpadding="2" align="center"> | ||
28 | <tr> <a name="settingup"></a> | ||
29 | <td bgcolor="#666699"> <b><font color="#FFFFFF">Setting up the | ||
30 | IDE</font></b></td> | ||
31 | </tr> | ||
32 | <tr> | ||
33 | <td height="90" bgcolor="#F7F3F7"> <div align="left"> | ||
34 | <div align="left"> | ||
35 | <p align="left">To use the engine, we will have to include | ||
36 | the header file <irrlicht.h>, which can be found | ||
37 | in the Irrlicht Engine SDK directory \include. To let | ||
38 | the compiler find this header file, the directory where | ||
39 | it is located should be specified somewhere. This is different | ||
40 | for every IDE and compiler. I will explain how to do this | ||
41 | in Microsoft Visual Studio C++ 6.0 and .NET:</p> | ||
42 | |||
43 | </div> | ||
44 | <ul> | ||
45 | <li> | ||
46 | <div align="left">If you use Version 6.0, select the Menu | ||
47 | Extras -> Options. Select the directories tab, and | ||
48 | select the 'Include' Item in the combo box. Add the | ||
49 | \include directory of the Irrlicht Engine folder to | ||
50 | the list of directories. Now the compiler will find | ||
51 | the Irrlicht.h header file. We also need the location | ||
52 | of irrlicht.lib to be listed, so select the 'Libraries' | ||
53 | tab and add the \lib\VisualStudio directory.<br> | ||
54 | <br> | ||
55 | <img src="../../media/vc6optionsdir.jpg" width="231" height="172" align="middle"> <img src="../../media/vc6include.jpg" width="231" height="159" align="middle"><br> | ||
56 | <br> | ||
57 | |||
58 | </div> | ||
59 | </li> | ||
60 | <li>If your IDE is Visual Studio .NET, select Tools -> | ||
61 | Options. Select the Projects entry and then select VC++ | ||
62 | directories. Select 'show directories for include files' | ||
63 | in the combo box, and add the \include directory of the | ||
64 | Irrlicht Engine folder to the list of directories so the | ||
65 | compiler will find the Irrlicht.h header file. We also | ||
66 | need the irrlicht.lib to be found, so select 'show directories | ||
67 | for Library files' and add the \lib\VisualStudio directory.<br> | ||
68 | <br> | ||
69 | <img src="../../media/vcnetinclude.jpg" width="256" height="160"> | ||
70 | <br> | ||
71 | </li> | ||
72 | </ul> | ||
73 | |||
74 | <p> </p> | ||
75 | </div></td> | ||
76 | </tr> | ||
77 | </table> | ||
78 | <br> <table width="90%" border="0" cellspacing="0" cellpadding="2" align="center"> | ||
79 | <tr> | ||
80 | <td bgcolor="#666699"> <font color="#FFFFFF"><b>Lets start!</b></font></td> | ||
81 | </tr> | ||
82 | |||
83 | <tr> | ||
84 | <td height="90" bgcolor="#F7F3F7" valign="top"> <div align="left"> | ||
85 | <div align="left"> | ||
86 | <div align="left"> | ||
87 | <div align="left"> | ||
88 | <p>After we have set up the IDE, the compiler will know | ||
89 | where to find the Irrlicht Engine header files so | ||
90 | we can include it now into our code.</p> | ||
91 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
92 | <tr> | ||
93 | <td> <pre>#include <irrlicht.h></pre> </td> | ||
94 | |||
95 | </tr> | ||
96 | </table> | ||
97 | <p>In the Irrlicht Engine, everything can be found in | ||
98 | the namespace 'irr'. So if you want to use a class | ||
99 | of the engine, you'll have to type an irr:: before | ||
100 | the name of the class. For example, to use the IrrlichtDevice, | ||
101 | write: irr::IrrlichtDevice. To avoid having to put | ||
102 | irr:: before of the name of every class, we tell the | ||
103 | compiler that we use that namespace.</p> | ||
104 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
105 | <tr> | ||
106 | <td> <pre>using namespace irr;</pre> </td> | ||
107 | </tr> | ||
108 | |||
109 | </table> | ||
110 | <p>There are 5 sub-namespaces in the Irrlicht Engine. | ||
111 | Take a look at them: you can read a detailed description | ||
112 | of them in the documentation by clicking on the top | ||
113 | menu item '<a href="http://irrlicht.sourceforge.net/docu/namespaces.html">Namespace | ||
114 | List</a>'. To keep this example simple, we don't want | ||
115 | to have to specify the name spaces, Hence:</p> | ||
116 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
117 | <tr> | ||
118 | <td> <pre>using namespace core;<br>using namespace scene;<br>using namespace video;<br>using namespace io;<br>using namespace gui;</pre> </td> | ||
119 | |||
120 | </tr> | ||
121 | </table> | ||
122 | <p>To be able to use the Irrlicht.DLL file, we need | ||
123 | to link with the Irrlicht.lib. We could set this option | ||
124 | in the project settings, but to make it easy we use | ||
125 | a pragma comment:</p> | ||
126 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
127 | <tr> | ||
128 | <td> <pre>#pragma comment(lib, "Irrlicht.lib")</pre> </td> | ||
129 | |||
130 | </tr> | ||
131 | </table> | ||
132 | <p>Now the main method: to keep this example simple | ||
133 | we use int main(), which can be used on any platform. | ||
134 | However, on Windows platforms, we could also use the | ||
135 | WinMain method if we would want to get rid of the | ||
136 | console window which pops up when starting a program | ||
137 | with main().</p> | ||
138 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
139 | <tr> | ||
140 | <td> <pre>int main()<br>{</pre> </td> | ||
141 | </tr> | ||
142 | |||
143 | </table> | ||
144 | <p>The most important function of the engine is the | ||
145 | 'createDevice' function. The Irrlicht Device, which | ||
146 | is the root object for doing everything with the engine, | ||
147 | can be created with it. createDevice() has 7 parameters:</p> | ||
148 | </div> | ||
149 | <ul> | ||
150 | <li> | ||
151 | |||
152 | <div align="left"> deviceType: Type of the device. This can currently | ||
153 | be the Null device, the Software device, Direct3D8, Direct3D9, | ||
154 | or OpenGL. In this example we use EDT_SOFTWARE, but, to try | ||
155 | them out, you might want to change it to EDT_NULL, EDT_DIRECT3D8, | ||
156 | EDT_DIRECT3D9 or EDT_OPENGL. </div> | ||
157 | </li> | ||
158 | <li> | ||
159 | <div align="left">windowSize: Size of the window or | ||
160 | full screen mode to be created. In this example | ||
161 | we use 512x384.</div> | ||
162 | |||
163 | </li> | ||
164 | <li> | ||
165 | <div align="left">bits: Number of bits per pixel when | ||
166 | in full screen mode. This should be 16 or 32. This | ||
167 | parameter is ignored when running in windowed mode.</div> | ||
168 | </li> | ||
169 | <li> | ||
170 | <div align="left">fullscreen: Specifies if we want | ||
171 | the device to run in full screen mode or not.</div> | ||
172 | </li> | ||
173 | <li>stencilbuffer: Specifies if we want to use the stencil | ||
174 | buffer for drawing shadows.</li> | ||
175 | |||
176 | <li>vsync: Specifies if we want to have vsync enabled. | ||
177 | This is only useful in full screen mode.</li> | ||
178 | <li> | ||
179 | <div align="left">eventReceiver: An object to receive | ||
180 | events. We do not want to use this parameter here, | ||
181 | and set it to 0.</div> | ||
182 | </li> | ||
183 | </ul> | ||
184 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
185 | <tr> | ||
186 | <td> <pre>IrrlichtDevice *device =<br> createDevice(EDT_SOFTWARE, dimension2d<s32>(512, 384), 16,<br> false, false, false, 0);</pre> </td> | ||
187 | |||
188 | </tr> | ||
189 | </table> | ||
190 | <p>Now we set the caption of the window to some nice text. | ||
191 | Note that there is a 'L' in front of the string: the | ||
192 | Irrlicht Engine uses wide character strings when displaying | ||
193 | text.</p> | ||
194 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
195 | <tr> | ||
196 | <td> <pre>device->setWindowCaption(L"Hello World! - Irrlicht Engine Demo");</pre> </td> | ||
197 | |||
198 | </tr> | ||
199 | </table> | ||
200 | <p>Now we store a pointer to the video driver, the SceneManager, | ||
201 | and the graphical user interface environment so that | ||
202 | we do not always have to write device->getVideoDriver(), | ||
203 | device->getSceneManager(), and device->getGUIEnvironment().</p> | ||
204 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
205 | <tr> | ||
206 | <td> <pre>IVideoDriver* driver = device->getVideoDriver();<br>ISceneManager* smgr = device->getSceneManager();<br>IGUIEnvironment* guienv = device->getGUIEnvironment();</pre> </td> | ||
207 | |||
208 | </tr> | ||
209 | </table> | ||
210 | <p> We add a hello world label to the window using the | ||
211 | GUI environment. The text is placed at the position | ||
212 | (10,10) as top left corner and (200,22) as lower right | ||
213 | corner.</p> | ||
214 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
215 | <tr> | ||
216 | <td> <pre>guienv->addStaticText(L"Hello World! This is the Irrlicht Software engine!",<br> rect<s32>(10,10,200,22), true);</pre> </td> | ||
217 | |||
218 | </tr> | ||
219 | </table> | ||
220 | <p>To display something interesting, we load a Quake 2 | ||
221 | model and display it. We only have to get the Mesh from | ||
222 | the Scene Manager with getMesh() and add a SceneNode | ||
223 | to display the mesh with addAnimatedMeshSceneNode(). | ||
224 | Instead of loading a Quake2 file (.md2), it is also | ||
225 | possible to load a Maya object file (.obj), a complete | ||
226 | Quake3 map (.bsp), or a Milshape file (.ms3d).<br> | ||
227 | By the way, that cool Quake 2 model called sydney.md2 | ||
228 | was modelled by Brian Collins.</p> | ||
229 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
230 | <tr> | ||
231 | <td> <pre>IAnimatedMesh* mesh = smgr->getMesh("../../media/sydney.md2");<br>IAnimatedMeshSceneNode* node = smgr->addAnimatedMeshSceneNode( mesh );</pre> </td> | ||
232 | |||
233 | </tr> | ||
234 | </table> | ||
235 | <p>To make the mesh look a little bit nicer, we change | ||
236 | its material a little bit: we disable lighting because | ||
237 | we do not have a dynamic light in here and the mesh | ||
238 | would be totally black. Then we set the frame loop so | ||
239 | that the animation is looped between the frames 0 and | ||
240 | 310. Then, at last, we apply a texture to the mesh. | ||
241 | Without it the mesh would be drawn using only a solid | ||
242 | color.</p> | ||
243 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
244 | <tr> | ||
245 | <td> <pre>if (node)<br>{<br> node->setMaterialFlag(EMF_LIGHTING, false);<br> node->setFrameLoop(0, 310); <br> node->setMaterialTexture( 0, driver->getTexture("../../media/sydney.bmp") );<br>}</pre> | ||
246 | </td> | ||
247 | |||
248 | </tr> | ||
249 | </table> | ||
250 | <p>To look at the mesh, we place a camera into 3d space | ||
251 | at the position (0, 10, -40). The camera looks from | ||
252 | there to (0,5,0).</p> | ||
253 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
254 | <tr> | ||
255 | <td> <pre>smgr->addCameraSceneNode(0, vector3df(0,30,-40), vector3df(0,5,0));</pre> </td> | ||
256 | </tr> | ||
257 | |||
258 | </table> | ||
259 | <p>Ok. Now that we have set up the scene, let's draw everything: | ||
260 | we run the device in a while() loop until the device | ||
261 | does not want to run any more. This would be when the | ||
262 | user closes the window or presses ALT+F4 in Windows.</p> | ||
263 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
264 | <tr> | ||
265 | <td> <pre>while(device->run())<br>{</pre> </td> | ||
266 | </tr> | ||
267 | |||
268 | </table> | ||
269 | <p> Everything must be drawn between a beginScene() and | ||
270 | an endScene() call. The beginScene clears the screen | ||
271 | with a color and also the depth buffer, if desired. | ||
272 | Then we let the Scene Manager and the GUI environment | ||
273 | draw their content. With the endScene() call, everything | ||
274 | is presented on the screen.</p> | ||
275 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
276 | <tr> | ||
277 | |||
278 | <td> <pre> driver->beginScene(true, true, SColor(255,100,101,140));<br> | ||
279 | smgr->drawAll(); | ||
280 | guienv->drawAll();</pre> | ||
281 | <pre> driver->endScene(); | ||
282 | }</pre> </td> | ||
283 | |||
284 | </tr> | ||
285 | </table> | ||
286 | <p>After we are finished, we have to delete the Irrlicht | ||
287 | Device created earlier with createDevice(). With the | ||
288 | Irrlicht Engine, you should delete all objects you created | ||
289 | with a method or function that starts with 'create'. | ||
290 | The object is deleted simply by calling ->drop(). | ||
291 | See the <a href="http://irrlicht.sourceforge.net/docu/classirr_1_1IUnknown.html#a3" target="_blank">documentation</a> | ||
292 | for more information.</p> | ||
293 | <table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center"> | ||
294 | <tr> | ||
295 | <td> <pre> device->drop();<br> return 0; | ||
296 | }</pre> </td> | ||
297 | |||
298 | </tr> | ||
299 | </table> | ||
300 | <p>That's it. Compile and run. </p> | ||
301 | <p> </p> | ||
302 | </div> | ||
303 | </div> | ||
304 | </div></td> | ||
305 | </tr> | ||
306 | |||
307 | </table> | ||
308 | <br> | ||
309 | <table width="90%" border="0" cellspacing="0" cellpadding="2" align="center"> | ||
310 | <tr> | ||
311 | <td bgcolor="#666699"> <b><font color="#FFFFFF">Possible Errors | ||
312 | or Problems</font></b></td> | ||
313 | </tr> | ||
314 | <tr> | ||
315 | <td height="90" bgcolor="#F7F3F7"> <div align="left"> | ||
316 | <div align="left"> | ||
317 | <div align="left"> | ||
318 | <p><strong>Visual Studio</strong><br> | ||
319 | |||
320 | While trying to compile the tutorial, if you get the | ||
321 | error: </p> | ||
322 | <table width="90%" border="0" align="center" cellpadding="0" cellspacing="0"> | ||
323 | <tr> | ||
324 | <td bgcolor="#CCCCCC"><font face="Courier New, Courier, mono">fatal | ||
325 | error C1083: Cannot open include file: 'irrlicht.h': | ||
326 | No such file or directory</font></td> | ||
327 | </tr> | ||
328 | </table> | ||
329 | <p>Solution: You may have set the include directory improperly | ||
330 | in the Visual Studio options. See <a href="#settingup">above</a> | ||
331 | for information on setting it. </p> | ||
332 | |||
333 | <table width="90%" border="0" align="center" cellpadding="0" cellspacing="0"> | ||
334 | <tr> | ||
335 | <td bgcolor="#CCCCCC"><font face="Courier New, Courier, mono">LINK | ||
336 | : LNK6004: HelloWorld.exe not found or not built | ||
337 | by the last incremental link; performing full link<br> | ||
338 | LINK : fatal error LNK1104: cannot open file "Irrlicht.lib"<br> | ||
339 | Error executing link.exe</font></td> | ||
340 | </tr> | ||
341 | </table> | ||
342 | <p> Solution: You may have set the library directory improperly. | ||
343 | See <a href="#settingup">above</a> for information on | ||
344 | setting it. <br> | ||
345 | |||
346 | <br> | ||
347 | </p> | ||
348 | <p><strong>Compiler independent problems<br> | ||
349 | </strong>If the tutorial compiles successfully but gives | ||
350 | the error: </p> | ||
351 | <table width="90%" border="0" align="center" cellpadding="0" cellspacing="0"> | ||
352 | <tr> | ||
353 | <td bgcolor="#CCCCCC"><font face="Courier New, Courier, mono">This | ||
354 | application has failed to start because Irrlicht.dll | ||
355 | was not found. Re-installing the application may | ||
356 | fix this problem</font></td> | ||
357 | </tr> | ||
358 | |||
359 | </table> | ||
360 | <p>Solution: You may have forgotten to copy the Irrlicht.dll | ||
361 | file from Irrlicht\bin\VisualStudio to the directory | ||
362 | the tutorial's project file is in. </p> | ||
363 | If the tutorial compiles and runs successfully but produces | ||
364 | errors in the console like:<br> | ||
365 | <br> | ||
366 | <table width="90%" border="0" align="center" cellpadding="0" cellspacing="0"> | ||
367 | <tr> | ||
368 | <td bgcolor="#CCCCCC"><font face="Courier New, Courier, mono">Could | ||
369 | not load mesh, because file could not be opened.: | ||
370 | ../media/sydney.md2</font></td> | ||
371 | </tr> | ||
372 | |||
373 | </table> | ||
374 | <p> Or:</p> | ||
375 | <table width="90%" border="0" align="center" cellpadding="0" cellspacing="0"> | ||
376 | <tr> | ||
377 | <td bgcolor="#CCCCCC"><em><font face="Courier New, Courier, mono">Could | ||
378 | not open file of texture: stones.jpg</font></em><font face="Courier New, Courier, mono"><b><br> | ||
379 | </b><em>Could not load texture: stones.jpg </em></font></td> | ||
380 | </tr> | ||
381 | |||
382 | </table> | ||
383 | <p>Solution: The file listed in the error message cannot | ||
384 | be found. Ensure that the directory specified in the | ||
385 | main.cpp exists and is where the file is located. <br> | ||
386 | </p> | ||
387 | </div> | ||
388 | </div> | ||
389 | </div></td> | ||
390 | </tr> | ||
391 | </table> | ||
392 | <p> </p> | ||
393 | </body> | ||
394 | </html> | ||