History: MOGRE Tutorial 1

Source of version: 3 (current)

__Beginner Tutorial 1: The SceneNode, Entity, and SceneManager constructs__

Original version by [http://www.idleengineer.net|Clay Culver] 

Initial C# edits by DigitalCyborg & ElectricBliss

Adapted to MOGRE by ((User:Adis|Adis))

__Note:__ This was written for Ogre 1.2.0 and MOGRE 0.1.7, and is known to compile against it. Any problems you encounter while working with this tutorial should be posted to the [http://www.ogre3d.org/phpBB2addons/viewforum.php?f=8|MOGRE Help Forum].

{maketoc}

!!Prerequisites
This tutorial assumes you have knowledge of C# programming and that you have the [http://prdownloads.sourceforge.net/mogre/Mogre0.1.7-OgreSDKSetup1.2.3_VC80.exe?download|MOGRE SDK]installed. Also a compiler capable of compiling .Net 2.0 code is needed. NO knowledge of Ogre is assumed for this tutorial outside of what is contained in the setup guide.

!!Introduction
In this tutorial I 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 I 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.

Before we start this tutorial you must first find the "Mogre Samples" solution in your "C:\OgreSDK\Mogre Samples" folder , open it in VS2005 an compile in both debug and release modes.

!!Getting Started
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. Create a project in the compiler of your choice for this project, then add the MOGRE.dll and the Mogre.Demo.ExampleApplication.dll(they should both be in the bin\release and the bin\debug folder of your Ogre instalation after you have compiled the MOGRE samples solution) as references to your project and add a source file which contains this code:

{CODE(wrap="1", colors="c#")} using System;
 using Mogre;
 using Demo.ExampleApplication;
 
 namespace WikiTut
 {
     class Program : Example
     {
         public override void CreateScene()
         {
         }
 
         static void Main(string[] args)
         {
             try
             {
                 Program app = new Program();
                 app.Go();
             }
             catch
             {
                 if (OgreException.IsThrown)
                     Example.ShowOgreException();
                 else
                     throw;
             }
         }
     }
 }
{CODE}
You should also add the following line to your project's post-build event box :
{CODE(wrap="1", colors="c#")} 
 copy "$(TargetPath)" "C:\OgreSdk\bin\$(ConfigurationName)" 
{CODE}
and for both release and debug configurations set the working directory to the respective folder in the ''OgreSDk\bin\'' folder. This way you can start the application from the IDE and also debug it.

Be sure you can compile and run this code before continuing to the next section, though nothing other than a blank screen with a framerate box will show up until we add things later in the tutorial.

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 recieve an error on your screen or in Ogre.log that looks something like this:

{CODE(wrap="1", colors="c#")} Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file
{CODE}
If you have problems, [http://www.ogre3d.org/phpBB2/search.php|search the forums]. It is likely your problem has happened to others many times. If this is a new issue, read [http://www.ogre3d.org/phpBB2/viewtopic.php?t=11886|the forum rules] then [http://www.ogre3d.org/phpBB2/viewforum.php?f=2|ask away]. Make sure to provide relevant details from your Ogre.log, exceptions, error messages, and/or debugger back traces.

__NOTE:__ C# users, if you need help, the best place to go is the [http://www.ogre3d.org/phpBB2addons/viewforum.php?f=8|MOGRE Forum].

Once the program is working, use the WASD keys to move, and the mouse to look around. The Escape key exits the program.

!!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 ((SceneManagersFAQ|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 an Entity.

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 ever rendered on the scene until you attach it to a SceneNode. Similarly, 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 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 setting the AmbientLight property 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, but here we will just use static fields that have a predefined value. Add this line to CreateScene:

{CODE(wrap="1", colors="c#")}         base.sceneMgr.AmbientLight = ColourValue.White;
{CODE}
The next thing we need to do is create an Entity. We do this by calling the SceneManager's CreateEntity member function:

{CODE(wrap="1", colors="c#")}         Entity ent1 = base.sceneMgr.CreateEntity("robot", "robot.mesh");
{CODE}
Ok several questions should pop up. First of all, where did sceneMgr come from, and what are the parameters we are calling the function with? The sceneMgr variable contains the current SceneManager object (this is done for us by the Example class). The first parameter to CreateEntity is the name of the Entity we are creating. __All entities must have a unique name.__ You will get an error if you try to create two entities with the same name. The "robot.mesh" parameter specifies the mesh we want to use for the Entity. Again, the mesh that we are using has been preloaded for us by the Example class.

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:

{CODE(wrap="1", colors="c#")}         SceneNode node1 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode"); 
{CODE}
This long statement first gets the RootSceneNode of the current SceneManager. Then it calls the CreateChildSceneNode method of the root SceneNode. The parameter to CreateChildSceneNode is the name of the SceneNode we are creating. Like the Entity class, no two SceneNodes can have the same name.

Finally, we need to attach the Entity to the SceneNode so that the Robot has a location to be rendered at:

{CODE(wrap="1", colors="c#")}         node1.AttachObject(ent1);
{CODE}
And that's it! Compile and run your application. You should see a robot standing on the screen.

NOTE: Robot.mesh is not in OgreCore.zip. Following the tutorials to this point your app may 
run but come up empty. I found adding the following to the resources.cfg and adding the 
appropriate directories got the application to work.

{CODE(wrap="1", colors="c#")} FileSystem=../../media/materials/programs
 FileSystem=../../media/materials/scripts
 FileSystem=../../media/materials/textures
 FileSystem=../../media/materials/models
 FileSystem=../../media/models
{CODE}
!!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 Robot is facing along the positive x direction? This is a property of the mesh itself, and how it was designed. 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 [http://en.wikipedia.org/wiki/Vector_%28spatial%29|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 that we have written, nowhere did we specify the exact location that we want our Robot to appear at. A large majority of the functions in Ogre have default parameters for them. For example, the [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea26|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). Lets create another SceneNode, but this time we'll specify the starting location to be something other than the origin:

{CODE(wrap="1", colors="c#")}         Entity ent2 = base.sceneMgr.CreateEntity("robot2", "robot.mesh");
         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
         node2.AttachObject(ent2);
{CODE}
This should look familiar. We have done the exact same thing as before, with two exceptions. First of all, we have named the Entity and SceneNode to something slightly different. The second thing we have done is specified that the starting position will be 50 units in the x direction away from the root SceneNode (remember that all SceneNode positions are relative to their parents). Compile and run the demo. Now there are two robots side-by-side.

!!Entities more in Depth
The [http://www.ogre3d.org/docs/api/html/classOgre_1_1Entity.html|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.Visible and [http://www.ogre3d.org/docs/api/html/classOgre_1_1MovableObject.html#Ogre_1_1WireBoundingBoxa25|Entity.isVisible]. You can set any Entity to be visible or not by simply setting this property. If you need to hide an Entity, but later display it, then set this property 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 Name property returns the name of Entity, and the ParentSceneNode property returns the SceneNode that the Entity is attached to.

!!SceneNodes more in Depth
The [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html|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 the Position property (always relative to the parent SceneNode). You can move the object relative to its current position by using the [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa37|Translate] method.

SceneNodes not only set position, but they also manage scale and rotation of the object as well. You can set the scale of an object with [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa35|Scale] function. You can use the [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea29|Yaw], [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa41|Roll], and [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa42|Pitch] functions to rotate objects. You can use [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa26|ResetOrientation] to reset all rotations done to the object. You can also use the Orientation property, and [http://www.ogre3d.org/docs/api/html/classOgre_1_1Node.html#Ogre_1_1TagPointa44|Rotate] functions for more advanced rotations. We will not be covering Quaternions until a much later tutorial though.

You have already seen the [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea3|AttachObject] function. These related functions are also useful if you are looking to manipulate the objects that are attached to a SceneNode: [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea4|NumAttachedObjects], [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea5|GetAttachedObject] (there are multiple versions of this function), [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea7|DetachObject] (also multiple versions), [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea10|DetachAllObjects]. There are also a whole set of functions for dealing with parent and child SceneNodes as well.

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

{CODE(wrap="1", colors="c#")}         Entity ent1 = base.sceneMgr.CreateEntity("robot", "robot.mesh");
         SceneNode node1 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode");
         node1.AttachObject(ent1);

         Entity ent2 = base.sceneMgr.CreateEntity("robot2", "robot.mesh");
         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
         node2.AttachObject(ent2);
{CODE}
If we change the 6th line from this:

{CODE(wrap="1", colors="c#")}         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
{CODE}
To this:

{CODE(wrap="1", colors="c#")}         SceneNode node2 = node1.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
{CODE}
Then we have made robotNode2 a child of robotNode. Moving node1 will move node2 along with it, but moving node2 will not affect node1. For example this code would move only robotNode2:

{CODE(wrap="1", colors="c#")}         node2.Translate(50, 0, 0); 
{CODE}
The following code would move robotNode, and since robotNode2 is a child of robotNode, robotNode2 would be moved as well:

{CODE(wrap="1", colors="c#")}         node1.Translate(25, 0, 0); 
{CODE}
If you are having trouble with this, the easiest thing to do is to start at the root SceneNode and go downwards. Lets say (as in this case), we started node1 and (0, 0, 0) and translated it by (25, 0, 0), thus node1's position is (25, 0, 0) relative to its parent. node2 started at (50, 0, 0) and we translated it by (10, 0, 10), so its new position is (60, 0, 10) relative to it's parent.

Now lets figure out where these things really are. Start at the root SceneNode. It's position is always (0, 0, 0). Now, node1's position is (root + node1): (0, 0, 0) + (25, 0, 0) = (25, 0, 0). Not surprising. Now, node2 is a child of node1, so its position is (root + node1 + node2): (0, 0, 0) + (25, 0, 0) + (60, 0, 10) = (85, 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 [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneManager.html#Ogre_1_1TerrainSceneManagera82|GetSceneNode] and [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneManager.html#Ogre_1_1TerrainSceneManagera85|GetEntity] methods of the SceneManager, so you don't have to keep a reference 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:

{CODE(wrap="1", colors="c#")}         Entity ent1 = base.sceneMgr.CreateEntity("robot", "robot.mesh");
         SceneNode node1 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode");
         node1.AttachObject(ent1);
         node1.Scale(.5f, 1f, 2f);
 
         Entity ent2 = base.sceneMgr.CreateEntity("robot2", "robot.mesh");
         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
         node2.AttachObject(ent2);
         node2.Scale(1.0f, 2.0f, 1.0f);
{CODE}
!!!Rotations


You can rotate the object by using the yaw, pitch, and roll methods using either Degree or Radian objects. Try changing the Degree amount and combining multiple transforms:

{CODE(wrap="1", colors="c#")}         Entity ent1 = base.sceneMgr.CreateEntity("robot", "robot.mesh");
         SceneNode node1 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode");
         node1.AttachObject(ent1);
 
         node1.Yaw(-90);
 
         Entity ent2 = base.sceneMgr.CreateEntity("robot2", "robot.mesh");
         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode2", new Vector3(50, 0, 0));
         node2.AttachObject(ent2);
 
         node2.Pitch(-90);
 
         Entity ent2 = base.sceneMgr.CreateEntity("robot3", "robot.mesh");
         SceneNode node2 = base.sceneMgr.RootSceneNode.CreateChildSceneNode("robotNode3", new Vector3(50, 0, 0));
         node2.AttachObject(ent2);
 
         node3.Roll(-90);
{CODE}
!!Conclusions


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 given reference to. 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.

!!What do you think?
This tutorial was designed to help out anyone who is completely new to Ogre get started. If you find something that is not clear, needs more explanation, or if you want to leave a comment about the tutorial, please post in [http://www.ogre3d.org/phpBB2addons/viewforum.php?f=8|this forum].

Thanks!
Clay
History: MOGRE Tutorial 1

Source of version: 3 (current)

Search by Tags

Latest Changes

Search

Online Users
