Tutorial Introduction In this tutorial we will be introducing you to the most basic Ogre constructs: SceneManager, SceneNode, and Entity objects. We will not cover a large amount of code; instead we will be focusing on the general concepts for you to begin learning Ogre. As you go through the tutorial you should be slowly adding code to your own project and watching the results as we build it. There is no substitute for actual programming to get familiar with these concepts! Resist the urge to simply read along.

Any problems you encounter while working with this tutorial should be posted to the Help Forum.

Prerequisites

• This tutorial assumes you have knowledge of C++ programming and are able to setup and compile an Ogre application.
• This tutorial also assumes that you have created a project using the Ogre Wiki Tutorial Framework, either manually, using CMake or the Ogre AppWizard - see Setting Up An Application for instructions.

Getting Started

Initial Code

We will be using a pre-constructed code base for this tutorial. You should ignore all of the code except for what we will be adding to the createScene method. In a later tutorial we will go in depth explaining how Ogre applications work, but for now we will be starting at the most basic level.

Read Setting up an Application to learn how to create the initial project and source files for your particular IDE and environment.

Create a project named the project Tutorial.

Add the tutorial application framework to it:

BaseApplication.h
BaseApplication.cpp
TutorialApplication.h
TutorialApplication.cpp

TutorialApplication.cpp is the only file that we will be using for this tutorial and we will only be working with createScene() member function.

TutorialApplication.cpp should contain the following code. I have removed the only header comments to keep the clutter down.

#include "TutorialApplication.h"
 
TutorialApplication::TutorialApplication(void)
{
}
 
TutorialApplication::~TutorialApplication(void)
{
}
 
//-------------------------------------------------------------------------------------
void TutorialApplication::createScene(void)
{
    Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");
 
    Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode();
    headNode->attachObject(ogreHead);
 
    // Set ambient light
    mSceneMgr->setAmbientLight(Ogre::ColourValue(0.5, 0.5, 0.5));
 
    // Create a light
    Ogre::Light* l = mSceneMgr->createLight("MainLight");
    l->setPosition(20,80,50);
}
 
 
 
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
#define WIN32_LEAN_AND_MEAN
#include "windows.h"
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
    INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, INT )
#else
    int main(int argc, char *argv[])
#endif
    {
        // Create application object
        TutorialApplication app;
 
        try 
        {
            app.go();
        } catch( Ogre::Exception& e ) {
#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
            MessageBox( NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR| MB_TASKMODAL);
#else
            std::cerr << "An exception has occured: " << e.getFullDescription().c_str() << std::endl;
#endif
        }
 
        return 0;
    }
 
#ifdef __cplusplus
}
#endif

Go ahead and compile and run this program to make sure that your environment is set up correctly. Once the program is working, use the WASD keys to move, and the mouse to look around. The Escape key exits the program.

Troubleshooting

If you have problems, check Setting Up An Application to setup your compiler properly, or look in the Ogre.log file for more detailed information. If you need further help, search the forums. It is likely your problem has happened to others many times. If this is a new issue, read the forum rules then ask away. Make sure to provide relevant details from your Ogre.log, exceptions, error messages, and/or debugger back traces.

Note that later tutorials will not contain this troubleshooting information, so please pay special attention to the following sections if you are having problems.

Message Box Trouble

If you are using Visual Studios with Unicode support turned on for the project you may encounter this error:

error C2664: 'MessageBoxW' : cannot convert parameter 2 from 'const char *' to 'LPCWSTR'
         Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or  function-style cast

MessageBox( NULL, e.what(), "An exception has occured!", MB_OK |   MB_IConerror  | MB_TASKMODAL);

MessageBoxA( NULL, e.what(), "An exception has occured!", MB_OK |   MB_IConerror  | MB_TASKMODAL);

The reason for this is that "MessageBox" is automatically resolved to either MessageBoxA (ANSI) or MessageBoxW (Wide/Unicode), depending on the project configuration. We fix the error by being explicit about it using ANSI.

Missing a Configuration File or DLLs

If you try to launch your freshly built application but the program complains of missing DLLs or configuration files (*.cfg), then you probably did not copy them over from the OgreSDK folder. In Visual Studios, when you build your application in release mode, it puts the release executable in the [ProjectFolder]\bin\release folder, and the debug executable in the [ProjectFolder]\bin\debug folder. You must copy all the ".dll" and ".cfg" files over from the OgreSDK into the appropriate folders. That is, copy the files from [OgreSDK]\bin\release to [ProjectFolder]\bin\release and [OgreSDK]\bin\debug to [ProjectFolder]\bin\debug. You will also need to edit the resources.cfg file to point at the correct paths. See the next section for more information on this.

Resources or Plugin Problems

Make sure you have a plugins.cfg and a resources.cfg in the same directory as the executable. Plugins.cfg tells OGRE which rendering libraries are available (Direct3D9, OpenGL, etc). Resources.cfg is used by the ExampleApplication and specifies paths to textures, meshes and scripts. Both are text files, so edit them and make sure the paths are correct. Otherwise your OGRE setup dialog box may not have any rendering libraries in it, or you may receive an error on your screen or in Ogre.log that looks something like this:

Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file

Cannot Launch the Application in Visual Studio or Code::Blocks

If you are using Visual Studio or Visual C++ to create the application and are having trouble launching it from the environment, the problem is most likely due to the debugger settings. If you press the play button (or go to the Start Debugging menu item) and you get an exception saying that a configuration file (*.cfg) cannot be found, then the Working Directory has probably not been set.

The exact instructions for fixing this will vary based on which version of Visual C++ you are using, so I cannot give you a direct walk through, but the basic steps should be the same. Right click on your project in the solution explorer (not the solution itself) and go to properties. Somewhere in the configuration properties should be options for "Debugging". In the debugging options there should be a field for "Working Directory". This should be set to the location that the executable file for your project is being placed.

If you are having trouble figuring out what to put there, try to mimic the "Command" field which should also be in the debugging options. For example, in Visual C++ 2003, the "Command" field should be something similar to "..\..\bin\$(ConfigurationName)\$(TargetFileName)". For the Working Directory, we need to remove the portion of the command which is the target file name (the executable). In this case, the working directory would be "..\..\bin\$(ConfigurationName)". The exact string you have to put there may vary based on your version of Visual C++ and on your build environment, so be sure to check what the Command field is before doing this. Be sure to change the Working Directory for both the Release and Debug configuration.

In Visual C++ 2005 it will probably be something different entirely. I've found the "..\..\bin\$(ConfigurationName)" directory a good thing to try first, if it still does not work you may have to play with it some, or consult some help from the Ogre forums.

If you are using Code::Blocks then you need to do the same, please right click in your project and select "Properties...", now go to "Build Targets" then change the field "Execution working dir:" to the same directory you are placing the executable of your program.

The reason we have to do this is that Ogre expects certain files to be in the same directory as the executable, and without setting the working directory to be a directory with these files in it, it will not work.

Once you have successfully run the program, go ahead and remove the code from inside the createScene() function but do not remove the function itself. We will be place code back into this function and examining it line by line.

How Ogre Works

A broad topic. We will start with SceneManagers and work our way to Entities and SceneNodes. These three classes are the fundamental building blocks of Ogre applications.

SceneManager Basics

Everything that appears on the screen is managed by the SceneManager (fancy that). When you place objects in the scene, the SceneManager is the class which keeps track of their locations. When you create Cameras to view the scene (which we will cover in a later tutorial) the SceneManager keeps track of them. When you create planes, billboards, lights...and so on, the SceneManager keeps track of them.

There are multiple types of SceneManagers. There are SceneManagers that render terrain, there is a SceneManager for rendering BSP maps, and so on. You can see the various types of SceneManagers listed here. We will cover more about other SceneManagers as we progress through the tutorials.

Entity Basics

An Entity is one of the types of object that you can render on a scene. You can think of an Entity as being anything that's represented by a 3D mesh. A robot would be an entity, a fish would be an entity, the terrain your characters walk on would be a very large entity. Things such as Lights, Billboards, Particles, Cameras, etc would not be entities.

One thing to note about Ogre is that it separates renderable objects from their location and orientation. This means that you cannot directly place an Entity in a scene. Instead you must attach the Entity to a SceneNode object, and this SceneNode contains the information about location and orientation.

SceneNode Basics

As already mentioned, SceneNodes keep track of location and orientation for all of the objects attached to it. When you create an Entity, it is not rendered in the scene until you attach it to a SceneNode. In addition a SceneNode is not an object that is displayed on the screen. Only when you create a SceneNode and attach an Entity (or other object) to it is something actually displayed on the screen.

SceneNodes can have any number of objects attached to them. Let's say you have a character walking around on the screen and you want to have him generate a light around him. The way you do this would be to first create a SceneNode, then create an Entity for the character and attach it to the SceneNode. Then you would create a Light object and attach it to the SceneNode. SceneNodes may also be attached to other SceneNodes which allows you to create entire hierarchies of nodes. We will cover more advanced uses of SceneNode attachment in a later tutorial.

One major concept to note about SceneNodes is that a SceneNode's position is always relative to its parent SceneNode, and each SceneManager contains a root node to which all other SceneNodes are attached.

Your first Ogre application

Now go back to the code we created earlier. Find the TutorialApplication::createScene member function. We will only be manipulating the contents of this function in this tutorial. The first thing we want to do is set the ambient light for the scene so that we can see what we are doing. We do this by calling the setAmbientLight function and specifying what color we want. Note that the ColourValue constructor expects values for red, green, and blue in the range between 0 and 1. Add this line to createScene:

mSceneMgr->setAmbientLight(Ogre::ColourValue(1.0, 1.0, 1.0));

Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");

Now that we have created the Entity, we need to create a SceneNode to attach it to. Since every SceneManager has a root SceneNode, we will be creating a child of that node:

Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("HeadNode");

Finally, we need to attach the Entity to the SceneNode to give the Ogre Head a render location:

headNode->attachObject(ogreHead);

Coordinates and Vectors

Before we go any further, we need to talk about screen coordinates and Ogre Vector objects. Ogre (like many graphics engines) uses the x and z axis as the horizontal plane, and the y axis as your vertical axis. As you are looking at your monitor now, the x axis would run from the left side to the right side of your monitor, with the right side being the positive x direction. The y axis would run from the bottom of your monitor to the top of your monitor, with the top being the positive y direction. The z axis would run into and out of your screen, with out of the screen being the positive z direction.

Notice how our Ogre Head is facing towards us along the -x direction? This is a property of the mesh and the camera position and facing. Cameras are covered in a later tutorial but for now just recognize the the Ogre's head is located at the position (0,0,0) and the our view of it is from in front a ways. The direction that the head is facing is a result of how the mesh was oriented when it was created and saved by the artist. Ogre makes no assumptions about how you orient your models. Each mesh that you load may have a different "starting direction" which it is facing.

Ogre uses the Vector class to represent both position and direction (there is no Point class). There are vectors defined for 2 (Vector2), 3 (Vector3), and 4 (Vector4) dimensions, with Vector3 being the most commonly used. If you are not familiar with Vectors, I suggest you brush up on it before doing anything serious with Ogre. The math behind Vectors will become very useful when you start working on complex programs.

Adding another Object

Now that you understand how the coordinate systems work, we can go back to our code. In the three lines we wrote, nowhere did we specify the exact location where we wanted our Ogre head to appear. A large majority of the functions in Ogre have default parameters for them. For example, the SceneNode::createChildSceneNode member function in Ogre has three parameters: the name of the SceneNode, the position of the SceneNode, and the initial rotation (orientation) the SceneNode is facing. The position, as you can see, has been set for us to the coordinates (0, 0, 0). Let's create another SceneNode, but this time we'll specify the starting location to be something other than the origin:

Ogre::Entity* ogreHead2 = mSceneMgr->createEntity( "Head2", "ogrehead.mesh" );
Ogre::SceneNode* headNode2 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );
headNode2->attachObject( ogreHead2 );

Entities more in Depth

The Entity class is very extensive, and I will not be covering how to use every portion of the object here...just enough to get you started. There are a few immediately useful member functions in Entity that I'd like to point out.

The first is Entity::setVisible and Entity::isVisible. You can set any Entity to be visible or not by simply calling this function. If you need to hide an Entity, but later display it, then call this function instead of destroying the Entity and later recreating it. Note that you don't need to "pool" Entities up. Only one copy of any object's mesh and texture are ever loaded into memory, so you are not saving yourself much by trying to save them. The only thing you really save is the creation and destruction costs for the Entity object itself, which is relatively low.

The getName function returns the name of Entity, and the getParentSceneNode function returns the SceneNode that the Entity is attached to.

SceneNodes more in Depth

The SceneNode class is very complex. There are a lot of things that can be done with a SceneNode, so we'll only cover some of the most useful.

You can get and set the position of a SceneNode with getPosition and setPosition (always relative to the parent SceneNode). You can move the object relative to its current position by using the translate method.

SceneNodes not only set position, but they also manage the scale and rotation of the object. You can set the scale of an object with the scale function. You can use the pitch, yaw, and roll functions to rotate objects. You can use resetOrientation to reset all rotations done to the object. You can also use the setOrientation, getOrientation, and rotate functions for more advanced rotations. We will not be covering Quaternions until a much later tutorial though.

You have already seen the attachObject function. These related functions are also useful if you are looking to manipulate the objects that are attached to a SceneNode: numAttachedObjects, getAttachedObject (there are multiple versions of this function), detachObject (also multiple versions), detachAllObjects. There are also a whole set of functions for dealing with parent and child SceneNodes as well.

Since all positioning and translating is done relative to the parent SceneNode, we can make two SceneNodes move together very easily. We currently have this code in the application:

mSceneMgr->setAmbientLight(Ogre::ColourValue(1.0, 1.0, 1.0));
 
Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");
Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("HeadNode");
headNode->attachObject(ogreHead);
 
Ogre::Entity* ogreHead2 = mSceneMgr->createEntity( "Head2", "ogrehead.mesh" );
Ogre::SceneNode* headNode2 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );
headNode2->attachObject( ogreHead2 );

Ogre::SceneNode* headNode2 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );

Ogre::SceneNode* headNode2 = headNode->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );

headNode2->translate( Vector3( 10, 0, 10 ) );

headNode->translate( Vector3( 25, 0, 0 ) );

Now let's figure out where these things really are. Start at the root SceneNode. Its position is always (0, 0, 0). Now, node1's position is (root + headNode): (0, 0, 0) + (25, 0, 0) = (25, 0, 0). Not surprising. Now, headNode2 is a child of node1, so its position is (root + headNode + headNode2): (0, 0, 0) + (25, 0, 0) + (110, 0, 10) = (135, 0, 10). This is just an example to explain how to think about SceneNode position inheritance. You will rarely ever need to calculate the absolute position of your nodes.

Lastly, note that you can get both SceneNodes and Entities by their name by calling getSceneNode and getEntity methods of the SceneManager, so you don't have to keep a pointer to every SceneNode you create. You should hang on to the ones you use often though.

Things to Try

By now you should have a basic grasp of Entities, SceneNodes, and the SceneManager. I suggest starting with the code above and adding and removing Robots from the scene. Once you have done that, clear all the contents out of the createScene method, and play with each of the following code segments:

Scale

You can scale the mesh by calling the scale method in SceneNode. Try changing the values in scale and see what you get:

mSceneMgr->setAmbientLight(Ogre::ColourValue(1.0, 1.0, 1.0));
 
Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");
Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("HeadNode");
headNode->attachObject(ogreHead);
 
headNode->scale( .5, 1, 2 ); 
 
Ogre::Entity* ogreHead2 = mSceneMgr->createEntity( "Head2", "ogrehead.mesh" );
Ogre::SceneNode* headNode2 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );
headNode2->attachObject( ogreHead2 );
 
headNode2->scale( 1, 2, 1 );

Rotations

You can rotate the object by using the yaw, pitch, and roll methods using either Degree or Radian objects. Pitch is rotation around the x axis, yaw is around the y axis, and roll is around the z axis. Using your right hand as a guide: point your thumb in the direction of an axis, curl your remaining fingers. The direction of the curl matches the positive rotation around that axis:

Try changing the Degree amount and combining multiple transforms:

mSceneMgr->setAmbientLight(Ogre::ColourValue(1.0, 1.0, 1.0));
 
Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");
Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("HeadNode");
headNode->attachObject(ogreHead);
 
headNode->yaw( Degree( -90 ) );
 
Ogre::Entity* ogreHead2 = mSceneMgr->createEntity( "Head2", "ogrehead.mesh" );
Ogre::SceneNode* headNode2 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode2", Ogre::Vector3( 100, 0, 0 ) );
headNode2->attachObject( ogreHead2 );
 
headNode2->pitch( Degree( -90 ) );
 
Ogre::Entity* ogreHead3 = mSceneMgr->createEntity( "Head3", "ogrehead.mesh" );
Ogre::SceneNode* headNode3 = mSceneMgr->getRootSceneNode()->createChildSceneNode( "HeadNode3", Ogre::Vector3( 200, 0, 0 ) );
headNode3->attachObject( ogreHead3 );
 
headNode3->roll( Degree( -90 ) );

In Microsoft Visual Studio 2010, a problem may be found that 'Degree' is an undeclared identifier.
This can be fixed by calling the function as 'Ogre::Degree', allowing the compiling with rotation.

The Ogre Environment

Most of the files (.DLL and .CFG) referred to in this section (and throughout the tutorials) can be found in the OgreSDK "bin" folder under either debug or release. Debug programs which you create should use the files in the debug OgreSDK folder, and release programs should use the files in the release folder.

Note that a lot of this section discusses Windows specific monikers. Under a Linux the same information basically applies, but the shared libraries end in .so and reside in another location, and some things may be slightly different. If you have problems, be sure to post your question to the Ogre help forums.

DLLs and Plugins

Now that we have played with the Ogre environment a bit, I'd like to explain how the Ogre library works in general to make your life easier when working with it.

Ogre is divided into 3 large shared library groups: The main library, the plugins, and the third-party libraries.

Main library

The first group consists of the library itself and the shared libraries it relies on. The Ogre library is contained, in its entirety in OgreMain.dll. This dll requires a few other libraries such as cg.dll. These DLLs must be included with every Ogre application without exception.

Plugins

The second group of shared libraries are the plugins. Ogre pushes a good portion of functionality out into shared libraries so that they may be turned on or off depending on the needs of your application. The basic plugins included with Ogre have filenames which start with the "Plugin_" prefix. You can create new plugins yourself if your application needs them, but we will not be covering this in any tutorial. Ogre also uses plugins for the render systems (such as OpenGL, DirectX, etc). These plugins start with the "RenderSystem_" prefix. These plugins exist so that you can add or remove render systems from your application. This can be especially useful if you write shaders or something which is specific to (for example) OpenGL and you need turn off the ability to run the program in DirectX, you can simply remove the appropriate RenderSystem plugin and it will be unavailable. Additionally if you are targeting a non-standard platform, you can write your own RenderSystem plugin, though this will not be covered in the tutorial. We will cover how to remove plugins in the next section.

Third party libraries and helper libraries

The third group of shared libraries are the third party libraries and helper libraries. Ogre itself is just a graphics rendering library. It does not include things such as GUI systems, input control, physics engines, and so on.
You will have to use other libraries to do these things.

The Ogre demos and SDK includes a few of these third party helper libraries.
Keyboard and mouse input is accomplished through OIS (an input system). This is contained in OIS.dll.
Cg (C for Graphics) is used by the CgProgramManager, and is contained in Cg.dll.
There are also other libraries (not included with the SDK) which give more functionality (such as sound and physics) which you can find more information about in other places such as on the Wiki and in the forums.

The Moral of the Story

The moral of the story is that when you are testing your application locally, you can leave everything "turned on" (that is, don't remove anything) to test with.
When you are ready to distribute your application, you will need to build it in Release mode, and include all of the release DLLs that your application uses, and you should remove the DLLs that you do not use.
If your program doesn't use the Cg ProgramManager but does use OIS, then you shouldn't bother including the Cg and the CgProgramManager DLLs, but you must include the OIS dll or your application will not run.

Configuration Files

Ogre runs off of several configuration files. They control which plugins are loaded, where the application's resources are located, and so on. We will briefly look at each of the configuration files and what they do. If you have more specific questions, you should direct them to the Ogre help forums.

plugins.cfg This file contains which plugins your application uses. If you want to add or remove a plugin in application, you will need to modify this file. To remove a plugin, simply remove the appropriate line, or comment it out by putting a # at the beginning of the line. To add a plugin, you will need to add a line like "Plugin=[PluginName]". Note that you do not put .DLL at the end of the plugin name. Your plugin also does not have to start with "RenderSystem_" or "Plugin_". You can also define the location that Ogre looks for plugins by changing the "PluginFolder" variable. You can use both absolute and relative paths, but you cannot use environment variables like $(SomeVariable).

resources.cfg This file contains a list of directories which Ogre should scan to look for resources. Resources include scripts, meshes, textures, and so on. You can use both absolute and relative paths, but you cannot use environment variables like $(SomeVariable). Note that Ogre will not scan subfolders, so you must manually enter them if you have multiple levels. For example, if you have a directory tree like "res\meshes" and "res\meshes\small", you will have to add two entries to the resources file containing both of these paths.

media.cfg This file tells Ogre more detailed information about some of the resources. It is unlikely that you will need to modify this file at this time, so I will skip over the details. More information can be found in the Manual and in the Ogre forums.

ogre.cfg This file is generated by Ogre's configuration screen. This file will be specific to your individual computer and graphics setup. You should not distribute this file to other people when you share your application, as they are likely to have different settings than you do. Note you should not edit this file directly, instead use the configuration screen.

quake3settings.cfg This file is used with the BSPSceneManager. You will not need this file unless you are using this scene manager (which you are not using at this point), so ignore it. You should not distribute this file with your application unless, again, you are using the BSPSceneManager, and even then it will likely be completely different depending on the needs of your program.

These are all of the configuration files that Ogre manipulates directly. Ogre must be able to find "plugins.cfg", "resources.cfg", and "media.cfg" to run properly. In a later tutorial we will cover more about these files and how to change their location and manipulate them to do more advanced things.

Conclusion

By this point you should have a very basic grasp of the SceneManager, SceneNode, and Entity classes. You do not have to be familiar with all of the functions that I have introduced. Since these are the most basic objects, we will be using them very often. You will get more familiar with them after working through the next few tutorials.

You should also be familiar with setting up a working Ogre environment for your projects.

Proceed to Basic Tutorial 2 Cameras, Lights, and Shadows

Alias: Basic_Tutorial_1