tutorial.html 23 KB

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