1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Irrlicht 3D Engine: Tutorial 1: HelloWorld</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
$(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="irrlichtlogo.png"/></td>
<td style="padding-left: 0.5em;">
<div id="projectname">Irrlicht 3D Engine
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.5.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="dynsections.js"></script>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
initNavTree('example001.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Tutorial 1: HelloWorld </div> </div>
</div>
<div class="contents">
<div class="textblock"><div class="image">
<img src="001shot.jpg" alt="001shot.jpg"/>
</div>
<p>This Tutorial shows how to set up the IDE for using the Irrlicht Engine and how to write a simple HelloWorld program with it. The program will show how to use the basics of the VideoDriver, the GUIEnvironment, and the SceneManager. Microsoft Visual Studio is used as an IDE, but you will also be able to understand everything if you are using a different one or even another operating system than windows.</p>
<p>You have to include the header file <<a class="el" href="irrlicht_8h.html" title="Main header file of the irrlicht, the only file needed to include.">irrlicht.h</a>> in order to use the engine. The header file can be found in the Irrlicht Engine SDK directory <code>include</code>. To let the compiler find this header file, the directory where it is located has to be specified. This is different for every IDE and compiler you use. Let's explain shortly how to do this in Microsoft Visual Studio:</p>
<ul>
<li>If you use Version 6.0, select the Menu Extras -> Options. Select the directories tab, and select the 'Include' Item in the combo box. Add the <code>include</code> directory of the irrlicht engine folder to the list of directories. Now the compiler will find the <a class="el" href="irrlicht_8h.html" title="Main header file of the irrlicht, the only file needed to include.">Irrlicht.h</a> header file. We also need the irrlicht.lib to be found, so stay in that dialog, select 'Libraries' in the combo box and add the <code>lib/VisualStudio</code> directory. <div class="image">
<img src="vc6optionsdir.jpg" alt="vc6optionsdir.jpg"/>
</div>
<div class="image">
<img src="vc6include.jpg" alt="vc6include.jpg"/>
</div>
</li>
</ul>
<ul>
<li>If your IDE is Visual Studio .NET, select Tools -> Options. Select the projects entry and then select VC++ directories. Select 'show directories for include files' in the combo box, and add the <code>include</code> directory of the irrlicht engine folder to the list of directories. Now the compiler will find the <a class="el" href="irrlicht_8h.html" title="Main header file of the irrlicht, the only file needed to include.">Irrlicht.h</a> header file. We also need the irrlicht.lib to be found, so stay in that dialog, select 'show directories for Library files' and add the <code>lib/VisualStudio</code> directory. <div class="image">
<img src="vcnetinclude.jpg" alt="vcnetinclude.jpg"/>
</div>
</li>
</ul>
<p>That's it. With your IDE set up like this, you will now be able to develop applications with the Irrlicht Engine.</p>
<p>Lets start!</p>
<p>After we have set up the IDE, the compiler will know where to find the Irrlicht Engine header files so we can include it now in our code. </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="irrlicht_8h.html" title="Main header file of the irrlicht, the only file needed to include.">irrlicht.h</a>></span>
</pre></div><p>In the Irrlicht Engine, everything can be found in the namespace 'irr'. So if you want to use a class of the engine, you have to write irr:: before the name of the class. For example to use the IrrlichtDevice write: <a class="el" href="classirr_1_1_irrlicht_device.html" title="The Irrlicht device. You can create it with createDevice() or createDeviceEx().">irr::IrrlichtDevice</a>. To get rid of the irr:: in front of the name of every class, we tell the compiler that we use that namespace from now on, and we will not have to write irr:: anymore. </p>
<div class="fragment"><pre class="fragment"><span class="keyword">using namespace </span>irr;
</pre></div><p>There are 5 sub namespaces in the Irrlicht Engine. Take a look at them, you can read a detailed description of them in the documentation by clicking on the top menu item 'Namespace List' or by using this link: <a href="http://irrlicht.sourceforge.net/docu/namespaces.html">http://irrlicht.sourceforge.net/docu/namespaces.html</a> Like the irr namespace, we do not want these 5 sub namespaces now, to keep this example simple. Hence, we tell the compiler again that we do not want always to write their names. </p>
<div class="fragment"><pre class="fragment"><span class="keyword">using namespace </span>core;
<span class="keyword">using namespace </span>scene;
<span class="keyword">using namespace </span>video;
<span class="keyword">using namespace </span>io;
<span class="keyword">using namespace </span>gui;
</pre></div><p>To be able to use the Irrlicht.DLL file, we need to link with the Irrlicht.lib. We could set this option in the project settings, but to make it easy, we use a pragma comment lib for VisualStudio. On Windows platforms, we have to get rid of the console window, which pops up when starting a program with main(). This is done by the second pragma. We could also use the WinMain method, though losing platform independence then. </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#ifdef _IRR_WINDOWS_</span>
<span class="preprocessor"></span><span class="preprocessor">#pragma comment(lib, "Irrlicht.lib")</span>
<span class="preprocessor"></span><span class="preprocessor">#pragma comment(linker, "/subsystem:windows /ENTRY:mainCRTStartup")</span>
<span class="preprocessor">#endif</span>
</pre></div><p>This is the main method. We can now use main() on every platform. </p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> main()
{
</pre></div><p>The most important function of the engine is the <a class="el" href="namespaceirr.html#abaf4d8719cc26b0d30813abf85e47c76" title="Creates an Irrlicht device. The Irrlicht device is the root object for using the engine.">createDevice()</a> function. The IrrlichtDevice is created by it, which is the root object for doing anything with the engine. <a class="el" href="namespaceirr.html#abaf4d8719cc26b0d30813abf85e47c76" title="Creates an Irrlicht device. The Irrlicht device is the root object for using the engine.">createDevice()</a> has 7 parameters:</p>
<ul>
<li>deviceType: Type of the device. This can currently be the Null-device, one of the two software renderers, D3D8, D3D9, or OpenGL. In this example we use EDT_SOFTWARE, but to try out, you might want to change it to EDT_BURNINGSVIDEO, EDT_NULL, EDT_DIRECT3D8, EDT_DIRECT3D9, or EDT_OPENGL.</li>
</ul>
<ul>
<li>windowSize: Size of the Window or screen in FullScreenMode to be created. In this example we use 640x480.</li>
</ul>
<ul>
<li>bits: Amount of color bits per pixel. This should be 16 or 32. The parameter is often ignored when running in windowed mode.</li>
</ul>
<ul>
<li>fullscreen: Specifies if we want the device to run in fullscreen mode or not.</li>
</ul>
<ul>
<li>stencilbuffer: Specifies if we want to use the stencil buffer (for drawing shadows).</li>
</ul>
<ul>
<li>vsync: Specifies if we want to have vsync enabled, this is only useful in fullscreen mode.</li>
</ul>
<ul>
<li>eventReceiver: An object to receive events. We do not want to use this parameter here, and set it to 0.</li>
</ul>
<p>Always check the return value to cope with unsupported drivers, dimensions, etc. </p>
<div class="fragment"><pre class="fragment"> IrrlichtDevice *device =
<a class="code" href="namespaceirr.html#abaf4d8719cc26b0d30813abf85e47c76" title="Creates an Irrlicht device. The Irrlicht device is the root object for using the engine.">createDevice</a>( <a class="code" href="namespaceirr_1_1video.html#ae35a6de6d436c76107ad157fe42356d0a1598cd235a1a6bd052e2011b559e8995" title="The Irrlicht Engine Software renderer.">video::EDT_SOFTWARE</a>, dimension2d<u32>(640, 480), 16,
<span class="keyword">false</span>, <span class="keyword">false</span>, <span class="keyword">false</span>, 0);
<span class="keywordflow">if</span> (!device)
<span class="keywordflow">return</span> 1;
</pre></div><p>Set the caption of the window to some nice text. Note that there is an 'L' in front of the string. The Irrlicht Engine uses wide character strings when displaying text. </p>
<div class="fragment"><pre class="fragment"> device->setWindowCaption(L<span class="stringliteral">"Hello World! - Irrlicht Engine Demo"</span>);
</pre></div><p>Get a pointer to the VideoDriver, the SceneManager and the graphical user interface environment, so that we do not always have to write device->getVideoDriver(), device->getSceneManager(), or device->getGUIEnvironment(). </p>
<div class="fragment"><pre class="fragment"> IVideoDriver* driver = device->getVideoDriver();
ISceneManager* smgr = device->getSceneManager();
IGUIEnvironment* guienv = device->getGUIEnvironment();
</pre></div><p>We add a hello world label to the window, using the GUI environment. The text is placed at the position (10,10) as top left corner and (260,22) as lower right corner. </p>
<div class="fragment"><pre class="fragment"> guienv->addStaticText(L<span class="stringliteral">"Hello World! This is the Irrlicht Software renderer!"</span>,
rect<s32>(10,10,260,22), <span class="keyword">true</span>);
</pre></div><p>To show something interesting, we load a Quake 2 model and display it. We only have to get the Mesh from the Scene Manager with getMesh() and add a SceneNode to display the mesh with addAnimatedMeshSceneNode(). We check the return value of getMesh() to become aware of loading problems and other errors.</p>
<p>Instead of writing the filename sydney.md2, it would also be possible to load a Maya object file (.obj), a complete Quake3 map (.bsp) or any other supported file format. By the way, that cool Quake 2 model called sydney was modelled by Brian Collins. </p>
<div class="fragment"><pre class="fragment"> IAnimatedMesh* mesh = smgr->getMesh(<span class="stringliteral">"../../media/sydney.md2"</span>);
<span class="keywordflow">if</span> (!mesh)
{
device->drop();
<span class="keywordflow">return</span> 1;
}
IAnimatedMeshSceneNode* node = smgr->addAnimatedMeshSceneNode( mesh );
</pre></div><p>To let the mesh look a little bit nicer, we change its material. We disable lighting because we do not have a dynamic light in here, and the mesh would be totally black otherwise. Then we set the frame loop, such that the predefined STAND animation is used. And last, we apply a texture to the mesh. Without it the mesh would be drawn using only a color. </p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (node)
{
node->setMaterialFlag(<a class="code" href="namespaceirr_1_1video.html#a8a3bc00ae8137535b9fbc5f40add70d3acea597a2692b8415486a464a7f954d34" title="Will this material be lighted? Default: true.">EMF_LIGHTING</a>, <span class="keyword">false</span>);
node->setMD2Animation(<a class="code" href="namespaceirr_1_1scene.html#a08d4a84966e1d2886d0d57e4acbb4f19a35893ae58423c41dace23ad13e262e2c">scene::EMAT_STAND</a>);
node->setMaterialTexture( 0, driver->getTexture(<span class="stringliteral">"../../media/sydney.bmp"</span>) );
}
</pre></div><p>To look at the mesh, we place a camera into 3d space at the position (0, 30, -40). The camera looks from there to (0,5,0), which is approximately the place where our md2 model is. </p>
<div class="fragment"><pre class="fragment"> smgr->addCameraSceneNode(0, <a class="code" href="namespaceirr_1_1core.html#a06f169d08b5c429f5575acb7edbad811" title="Typedef for a f32 3d vector.">vector3df</a>(0,30,-40), <a class="code" href="namespaceirr_1_1core.html#a06f169d08b5c429f5575acb7edbad811" title="Typedef for a f32 3d vector.">vector3df</a>(0,5,0));
</pre></div><p>Ok, now we have set up the scene, lets draw everything: We run the device in a while() loop, until the device does not want to run any more. This would be when the user closes the window or presses ALT+F4 (or whatever keycode closes a window). </p>
<div class="fragment"><pre class="fragment"> <span class="keywordflow">while</span>(device->run())
{
</pre></div><p>Anything can be drawn between a beginScene() and an endScene() call. The beginScene() call clears the screen with a color and the depth buffer, if desired. Then we let the Scene Manager and the GUI Environment draw their content. With the endScene() call everything is presented on the screen. </p>
<div class="fragment"><pre class="fragment"> driver->beginScene(<span class="keyword">true</span>, <span class="keyword">true</span>, SColor(255,100,101,140));
smgr->drawAll();
guienv->drawAll();
driver->endScene();
}
</pre></div><p>After we are done with the render loop, we have to delete the Irrlicht Device created before with <a class="el" href="namespaceirr.html#abaf4d8719cc26b0d30813abf85e47c76" title="Creates an Irrlicht device. The Irrlicht device is the root object for using the engine.">createDevice()</a>. In the Irrlicht Engine, you have to delete all objects you created with a method or function which starts with 'create'. The object is simply deleted by calling ->drop(). See the documentation at <a class="el" href="classirr_1_1_i_reference_counted.html#afb169a857e0d2cdb96b8821cb9bff17a" title="Drops the object. Decrements the reference counter by one.">irr::IReferenceCounted::drop()</a> for more information. </p>
<div class="fragment"><pre class="fragment"> device->drop();
<span class="keywordflow">return</span> 0;
}
</pre></div><p>That's it. Compile and run. </p>
</div></div>
</div>
<div id="nav-path" class="navpath">
<ul>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Friends</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<li class="footer">
<a href="http://irrlicht.sourceforge.net" target="_blank">Irrlicht
Engine</a> Documentation © 2003-2012 by Nikolaus Gebhardt. Generated on Tue Nov 6 2012 11:06:01 for Irrlicht 3D Engine by
<a href="http://www.doxygen.org/index.html" target="_blank">Doxygen</a> 1.7.5.1 </li>
</ul>
</div>
</body>
</html>
|
