3
<title>Irrlicht Engine Tutorial</title>
4
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
7
<body bgcolor="#FFFFFF" leftmargin="0" topmargin="0" marginwidth="0" marginheight="0">
9
<table width="90%" border="0" cellspacing="0" cellpadding="2" align="center">
11
<td bgcolor="#666699"> <b><font color="#FFFFFF">Tutorial 1.HelloWorld</font></b></td>
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>
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
33
<td height="90" bgcolor="#F7F3F7"> <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>
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>
55
<img src="../../media/vc6optionsdir.jpg" width="231" height="172" align="middle"> <img src="../../media/vc6include.jpg" width="231" height="159" align="middle"><br>
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>
69
<img src="../../media/vcnetinclude.jpg" width="256" height="160">
78
<br> <table width="90%" border="0" cellspacing="0" cellpadding="2" align="center">
80
<td bgcolor="#666699"> <font color="#FFFFFF"><b>Lets start!</b></font></td>
84
<td height="90" bgcolor="#F7F3F7" valign="top"> <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">
93
<td> <pre>#include <irrlicht.h></pre> </td>
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">
106
<td> <pre>using namespace irr;</pre> </td>
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">
118
<td> <pre>using namespace core;<br>using namespace scene;<br>using namespace video;<br>using namespace io;<br>using namespace gui;</pre> </td>
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">
128
<td> <pre>#pragma comment(lib, "Irrlicht.lib")</pre> </td>
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
138
<table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center">
140
<td> <pre>int main()<br>{</pre> </td>
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>
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>
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>
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>
170
<div align="left">fullscreen: Specifies if we want
171
the device to run in full screen mode or not.</div>
173
<li>stencilbuffer: Specifies if we want to use the stencil
174
buffer for drawing shadows.</li>
176
<li>vsync: Specifies if we want to have vsync enabled.
177
This is only useful in full screen mode.</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>
184
<table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center">
186
<td> <pre>IrrlichtDevice *device =<br> createDevice(EDT_SOFTWARE, dimension2d<s32>(512, 384), 16,<br> false, false, false, 0);</pre> </td>
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
194
<table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center">
196
<td> <pre>device->setWindowCaption(L"Hello World! - Irrlicht Engine Demo");</pre> </td>
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">
206
<td> <pre>IVideoDriver* driver = device->getVideoDriver();<br>ISceneManager* smgr = device->getSceneManager();<br>IGUIEnvironment* guienv = device->getGUIEnvironment();</pre> </td>
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
214
<table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center">
216
<td> <pre>guienv->addStaticText(L"Hello World! This is the Irrlicht Software engine!",<br> rect<s32>(10,10,200,22), true);</pre> </td>
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">
231
<td> <pre>IAnimatedMesh* mesh = smgr->getMesh("../../media/sydney.md2");<br>IAnimatedMeshSceneNode* node = smgr->addAnimatedMeshSceneNode( mesh );</pre> </td>
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
243
<table width="95%" border="0" cellspacing="2" cellpadding="0" bgcolor="#CCCCCC" align="center">
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>
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">
255
<td> <pre>smgr->addCameraSceneNode(0, vector3df(0,30,-40), vector3df(0,5,0));</pre> </td>
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">
265
<td> <pre>while(device->run())<br>{</pre> </td>
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">
278
<td> <pre> driver->beginScene(true, true, SColor(255,100,101,140));<br>
280
guienv->drawAll();</pre>
281
<pre> driver->endScene();
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">
295
<td> <pre> device->drop();<br> return 0;
300
<p>That's it. Compile and run. </p>
309
<table width="90%" border="0" cellspacing="0" cellpadding="2" align="center">
311
<td bgcolor="#666699"> <b><font color="#FFFFFF">Possible Errors
312
or Problems</font></b></td>
315
<td height="90" bgcolor="#F7F3F7"> <div align="left">
318
<p><strong>Visual Studio</strong><br>
320
While trying to compile the tutorial, if you get the
322
<table width="90%" border="0" align="center" cellpadding="0" cellspacing="0">
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>
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>
333
<table width="90%" border="0" align="center" cellpadding="0" cellspacing="0">
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>
342
<p> Solution: You may have set the library directory improperly.
343
See <a href="#settingup">above</a> for information on
348
<p><strong>Compiler independent problems<br>
349
</strong>If the tutorial compiles successfully but gives
351
<table width="90%" border="0" align="center" cellpadding="0" cellspacing="0">
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>
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>
366
<table width="90%" border="0" align="center" cellpadding="0" cellspacing="0">
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>
375
<table width="90%" border="0" align="center" cellpadding="0" cellspacing="0">
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>
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>
added
removed
examples/01.HelloWorld/tutorial.html
