Irrlicht Engine Tutorial

Tutorial 1.HelloWorld
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. The result of this example will look like this:

Setting up the IDE
To use the engine, we will have to include the header file <irrlicht.h>, which can be found in the Irrlicht Engine SDK directory \include. To let the compiler find this header file, the directory where it is located should be specified somewhere. This is different for every IDE and compiler. I will explain how to do this in Microsoft Visual Studio C++ 6.0 and .NET: 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 \include directory of the Irrlicht Engine folder to the list of directories. Now the compiler will find the Irrlicht.h header file. We also need the location of irrlicht.lib to be listed, so select the 'Libraries' tab and add the \lib\VisualStudio directory. 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 \include directory of the Irrlicht Engine folder to the list of directories so the compiler will find the Irrlicht.h header file. We also need the irrlicht.lib to be found, so select 'show directories for Library files' and add the \lib\VisualStudio directory.

Lets start!
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 into our code.
    #include <irrlicht.h>
In the Irrlicht Engine, everything can be found in the namespace 'irr'. So if you want to use a class of the engine, you'll have to type an irr:: before the name of the class. For example, to use the IrrlichtDevice, write: irr::IrrlichtDevice. To avoid having to put irr:: before of the name of every class, we tell the compiler that we use that namespace.
    using namespace irr;
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'. To keep this example simple, we don't want to have to specify the name spaces, Hence:
    using namespace core;
    using namespace scene;
    using namespace video;
    using namespace io;
    using namespace gui;
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:
    #pragma comment(lib, "Irrlicht.lib")
Now the main method: to keep this example simple we use int main(), which can be used on any platform. However, on Windows platforms, we could also use the WinMain method if we would want to get rid of the console window which pops up when starting a program with main().
    int main()
    {
The most important function of the engine is the 'createDevice' function. The Irrlicht Device, which is the root object for doing everything with the engine, can be created with it. createDevice() has 7 parameters: deviceType: Type of the device. This can currently be the Null device, the Software device, Direct3D8, Direct3D9, or OpenGL. In this example we use EDT_SOFTWARE, but, to try them out, you might want to change it to EDT_NULL, EDT_DIRECT3D8, EDT_DIRECT3D9 or EDT_OPENGL. windowSize: Size of the window or full screen mode to be created. In this example we use 512x384. bits: Number of bits per pixel when in full screen mode. This should be 16 or 32. This parameter is ignored when running in windowed mode. fullscreen: Specifies if we want the device to run in full screen mode or not. stencilbuffer: Specifies if we want to use the stencil buffer for drawing shadows. vsync: Specifies if we want to have vsync enabled. This is only useful in full screen mode. eventReceiver: An object to receive events. We do not want to use this parameter here, and set it to 0.
    IrrlichtDevice *device =
    		createDevice(EDT_SOFTWARE, dimension2d<s32>(512, 384), 16,
    			false, false, false, 0);
Now we set the caption of the window to some nice text. Note that there is a 'L' in front of the string: the Irrlicht Engine uses wide character strings when displaying text.
    device->setWindowCaption(L"Hello World! - Irrlicht Engine Demo");
Now we store a pointer to the video driver, the SceneManager, and the graphical user interface environment so that we do not always have to write device->getVideoDriver(), device->getSceneManager(), and device->getGUIEnvironment().
    IVideoDriver* driver = device->getVideoDriver();
    ISceneManager* smgr = device->getSceneManager();
    IGUIEnvironment* guienv = device->getGUIEnvironment();
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 (200,22) as lower right corner.
    guienv->addStaticText(L"Hello World! This is the Irrlicht Software engine!",
    	 rect<s32>(10,10,200,22), true);
To display 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(). Instead of loading a Quake2 file (.md2), it is also possible to load a Maya object file (.obj), a complete Quake3 map (.bsp), or a Milshape file (.ms3d). By the way, that cool Quake 2 model called sydney.md2 was modelled by Brian Collins.
    IAnimatedMesh* mesh = smgr->getMesh("../../media/sydney.md2");
    IAnimatedMeshSceneNode* node = smgr->addAnimatedMeshSceneNode( mesh );
To make the mesh look a little bit nicer, we change its material a little bit: we disable lighting because we do not have a dynamic light in here and the mesh would be totally black. Then we set the frame loop so that the animation is looped between the frames 0 and 310. Then, at last, we apply a texture to the mesh. Without it the mesh would be drawn using only a solid color.
    if (node)
    {
    	node->setMaterialFlag(EMF_LIGHTING, false);
    	node->setFrameLoop(0, 310);
    	node->setMaterialTexture( 0, driver->getTexture("../../media/sydney.bmp") );
    }
To look at the mesh, we place a camera into 3d space at the position (0, 10, -40). The camera looks from there to (0,5,0).
    smgr->addCameraSceneNode(0, vector3df(0,30,-40), vector3df(0,5,0));
Ok. Now that we have set up the scene, let's 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 in Windows.
    while(device->run())
    {
Everything must be drawn between a beginScene() and an endScene() call. The beginScene clears the screen with a color and also 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.
    	driver->beginScene(true, true, SColor(255,100,101,140));

    	smgr->drawAll();
    	guienv->drawAll();
    	driver->endScene();
    }
After we are finished, we have to delete the Irrlicht Device created earlier with createDevice(). With the Irrlicht Engine, you should delete all objects you created with a method or function that starts with 'create'. The object is deleted simply by calling ->drop(). See the documentation for more information.
    	device->drop();
     return 0;
    }
That's it. Compile and run.

Possible Errors or Problems
Visual Studio While trying to compile the tutorial, if you get the error:
fatal error C1083: Cannot open include file: 'irrlicht.h': No such file or directory
Solution: You may have set the include directory improperly in the Visual Studio options. See above for information on setting it.
LINK : LNK6004: HelloWorld.exe not found or not built by the last incremental link; performing full link LINK : fatal error LNK1104: cannot open file "Irrlicht.lib" Error executing link.exe
Solution: You may have set the library directory improperly. See above for information on setting it. Compiler independent problems If the tutorial compiles successfully but gives the error:
This application has failed to start because Irrlicht.dll was not found. Re-installing the application may fix this problem
Solution: You may have forgotten to copy the Irrlicht.dll file from Irrlicht\bin\VisualStudio to the directory the tutorial's project file is in. If the tutorial compiles and runs successfully but produces errors in the console like:
Could not load mesh, because file could not be opened.: ../media/sydney.md2
Or:
Could not open file of texture: stones.jpg Could not load texture: stones.jpg
Solution: The file listed in the error message cannot be found. Ensure that the directory specified in the main.cpp exists and is where the file is located.