History: Mogre Basic Tutorial 1

Source of version: 14 (current)

{TRANSCLUDE(page="tutbox")}In this tutorial we will be introducing you to the most basic Ogre/Mogre constructs: ((-SceneManager|SceneManager)), ((-SceneNode|SceneNode)), and ((-Entity|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. {TRANSCLUDE}

If you find any errors in this tutorial please send a private message to [http://www.ogre3d.org/addonforums/ucp.php?i=pm&mode=compose&u=14838|amirabiri].

!Prerequisites
*This tutorial assumes you have knowledge of C# or VB.NET programming and are able to setup and compile a ((Mogre)) application.
*This tutorial also assumes that you have created a project using the ((Mogre Wiki Tutorial Framework)).

{maketoc}

!Getting Started
Download the ((Mogre Wiki Tutorial Framework)) that is suitable to your environment. Open the archive somewhere (keep the unmodified .zip file as you will want to use it again in subsequent tutorials). Inside the archive you will find a Visual Studio solution ready to be used. Load it, compile and run. You should see a blank screen with nothing inside (press ESC to exit).

Now open the file ''tutorial.cs'' or ''tutorial.vb'' (depending on the version of the framework you downloaded) which should look like this:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
using Mogre;
using Mogre.TutorialFramework;
using System;



namespace Mogre.Tutorials
{
    class Tutorial : BaseApplication
    {
        public static void Main()
        {
            new Tutorial().Go();
        }

        protected override void CreateScene()
        {
        }
    }
}
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
Imports Mogre
Imports Mogre.TutorialFramework
Imports System



Namespace Mogre.Tutorials
    Class Tutorial
        Inherits BaseApplication

        Shared Sub Main()
            Dim tutorial = New Tutorial()
            tutorial.Go()
        End Sub

        Protected Overrides Sub CreateScene()
        End Sub
    End Class
End Namespace
{CODE}
{VERSIONS}

This is a minimal tutorial application built against the tutorial framework. Notice that the tutorials framework does everything for you and hides away the complexity of setting up Mogre.

The framework defines several virtual methods that can be overridden to add or modify functionality. Throughout the tutorials we will be overriding such methods and adding code to them. In the first tutorial we will __only be adding code to the ''CreateScene'' method__.

!Ogre vs Mogre Properties and Functions
Throughout this series of tutorials we will be linking to the [http://www.ogre3d.org/docs/api/html/|Ogre API] reference. You should keep in mind that Mogre is a .NET binding of the C++ Ogre graphics engine, and as such the methods have been changed to match the .NET coding standards. Methods begin with an initial caps instead of lower case letters. Get and set methods have been removed entirely in favor of properties. For example, the C++ functions ''setAmbientLight'' and ''getAmbientLight'' have been changed to just be the ''AmbientLight'' property. When in doubt, use intellisense to figure out what a method call should be.

!How Ogre/Mogre Work
A broad topic. We will start with ((-SceneManager|SceneManagers)) and work our way to ((-Entity|Entities)) and ((-SceneNode|SceneNodes)). These three classes are the fundamental building blocks of Ogre/Mogre 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 ((-Camera|Cameras)) to view the ((-Scene|scene)) (which we will cover in a later tutorial) the SceneManager keeps track of them. When you create planes, ((-Billboard|billboards)), ((-Light|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|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 ((-Light|Lights)), ((-Billboard|billboards)), ((-Particle|Particles)), ((-Camera|Cameras)), etc would not be ((-Entity|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|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.

!You First Mogre Application
Now go back to the code we created earlier. Find the ''CreateScene'' method. We will only be manipulating the contents of this method 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. Add this line to ''CreateScene'':

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
mSceneMgr.AmbientLight = new ColourValue(1, 1, 1);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
mSceneMgr.AmbientLight = New ColourValue(1, 1, 1)
{CODE}
{VERSIONS}

The next thing we need to do is create an Entity. We do this by calling the SceneManager's '''CreateEntity'' method: 

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
Entity ent = mSceneMgr.CreateEntity("Head", "ogrehead.mesh");
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
Dim ent As Entity = mSceneMgr.CreateEntity("Head", "ogrehead.mesh")
{CODE}
{VERSIONS}

Okay, several questions should pop up. First of all, where did ''mSceneMgr'' come from, and what are the parameters we are calling the method with? The ''mSceneMgr'' variable contains the current SceneManager object which has already been set up by the tutorial framework. 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 ''ogrehead.mesh'' parameter specifies the mesh we want to use for the Entity. ''ogrehead.mesh'' is a resource which comes with the Mogre SDK and the tutorial framework. Resource loading will be covered in a later tutorial as will meshes. For now we are using the resource loading capabilities of the tutorial framework 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: 

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
SceneNode node = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode");
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
Dim node As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode")
{CODE}
{VERSIONS}

This statement first gets the ((-RootSceneNode|RootSceneNode)) of the current SceneManager, and 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. We can omit the name parameter for SceneNodes if we choose to do so, and a default name will be assigned to the node. 

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

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
node.AttachObject(ent);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
node.AttachObject(ent)
{CODE}
{VERSIONS}

And that's it! Compile and run your application. You should see an Ogre's head on your screen. 

!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.

{IMG(src="display1921",alt="Cartesian coordinate system on a computer screen")}{IMG}

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 that the Ogre's head is located at the position (0,0,0) and that our view of it is from in front. 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/Mogre make 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 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/Mogre have default parameters for them. For example, the [http://www.ogre3d.org/docs/api/html/classOgre_1_1SceneNode.html#Ogre_1_1SceneNodea26|SceneNode.CreateChildSceneNode] method in Ogre/Mogre 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:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
Entity ent2 = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh");
SceneNode node2 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
node2.AttachObject(ent2);
{CODE}
---(VB.NET)--
{CODE(wrap="1", colors="vbnet")}
Dim ent2  As Entity    = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh")
Dim node2 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
node2.AttachObject(ent2)
{CODE}
{VERSIONS}

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 something slightly different. The second thing we have done is specified that the starting position will be 100 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 Ogre heads side-by-side. You may have to move back using the 'S' key or the down arrow to see both heads. 

!Entities more in Depth
The [/docs/api/html/classOgre_1_1Entity.html|Entity class] is very extensive, and we will not be covering how to use every portion of it here...just enough to get you started. However there are a few immediately useful methods and properties in Entity that we'd like to point out.

The first is [/docs/api/html/classOgre_1_1MovableObject.html#a8b0ab29b6a7e94169e2b3fde0be7cf10|Entity::Visible]. You can set any Entity to be visible or not by simply setting this property to true or false. If you need to hide an Entity, but later display it, then use 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 [/docs/api/html/classOgre_1_1Node.html#a3bca2aaf4e01a1447a4aaf4e03a79c18|Name] property returns the name of Entity, and the [/docs/api/html/classOgre_1_1SceneNode.html#a454706e093c4ac83b2bb79a66c3c6bfb|ParentSceneNode] property returns the SceneNode that the Entity is attached to.

!SceneNodes more in Depth
The [/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 using the [/docs/api/html/classOgre_1_1Node.html#ab39c7a80773f87fca7a2a714760eaca3|Position] property (this is always relative to the parent SceneNode). You can move the object relative to its current position by adding and subtracting [/docs/api/html/classOgre_1_1Vector3.html|Vectors] from this Property or using the [/docs/api/html/classOgre_1_1Node.html#a4c147221e3963295853affdc2cd06c81|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 [/docs/api/html/classOgre_1_1Node.html#a76b6c58ff14ff8c401e773dcb400b7fa|Scale] method. You can use the [/docs/api/html/classOgre_1_1Node.html#ac7d3de1c197a805dd692f775fbbeb022|Pitch], [/docs/api/html/classOgre_1_1Node.html#af0d40ab6711058fa41ec905888587b32|Yaw], and [/docs/api/html/classOgre_1_1Node.html#aeb62b05fce457b8509cb95517154425f|Roll] methods to rotate objects. You can use [/docs/api/html/classOgre_1_1Node.html#a04a385c69650ee62def0cfee923d1ea4|ResetOrientation] to reset all rotations done to the object. You can also use the [/docs/api/html/classOgre_1_1Node.html#a412b900632a24e3e8a90c25a5d78d84c|Orientation] property and the [/docs/api/html/classOgre_1_1Node.html#aef3cc09979efbff06a37974c17fa54ab|Rotate] method for more advanced rotations. We will not be covering Quaternions until a much later tutorial though.

You have already seen the [/docs/api/html/classOgre_1_1SceneNode.html#a51052c58747a77a6cf7451b700e7eb87|AttachObject] function. These related functions and properties are also useful if you are looking to manipulate the objects that are attached to a SceneNode: [/docs/api/html/classOgre_1_1SceneNode.html#ac440aafa5cb9356e1f4feb17c9fa0cb6|NumAttachedObjects], [/docs/api/html/classOgre_1_1SceneNode.html#af890d36d827ac01b125c10c8d2b7c8b3|GetAttachedObject] (there are multiple versions of this function), [/docs/api/html/classOgre_1_1SceneNode.html#af52d04c1d2aa341f7e02daeb7355372b|DetachObject] (also multiple versions), [/docs/api/html/classOgre_1_1SceneNode.html#a064b81e279b10a488ba018d1ac87abb5|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:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
mSceneMgr.AmbientLight = new ColourValue(1, 1, 1);

Entity    ent  = mSceneMgr.CreateEntity("Head", "ogrehead.mesh");
SceneNode node = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode");
node.AttachObject(ent);

Entity    ent2  = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh");
SceneNode node2 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
node2.AttachObject(ent2);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
mSceneMgr.AmbientLight = New ColourValue(1, 1, 1)

Dim ent  As Entity    = mSceneMgr.CreateEntity("Head", "ogrehead.mesh")
Dim node As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode")
node.AttachObject(ent)

Dim ent2  As Entity    = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh")
Dim node2 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
node2.AttachObject(ent2)
{CODE}
{VERSIONS}

If we change the 6th line from this:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
SceneNode node2 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
Dim node2 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
{CODE}
{VERSIONS}

To this:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
SceneNode node2 = node.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
Dim node2 As SceneNode = node.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
{CODE}
{VERSIONS}

Then we have made __node2__ a child of __node__. Moving __node__ will move __node2__ along with it, but moving __node2__ will not affect __node__. For example this code would move only node2:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
node2.Position += new Vector3(10, 0, 10);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
node2.Position += New Vector3(10, 0, 10)
{CODE}
{VERSIONS}

The following code would move __node__, and since __node2__ is a child of __node__, __node2__ would be moved as well:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
node.Position += new Vector3(25, 0, 0);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
node.Position += New Vector3(25, 0, 0)
{CODE}
{VERSIONS}

If you are having trouble with this, the easiest thing to do is to start at the root SceneNode and go downwards. Let's say (as in this case), we started __node__ at (0, 0, 0) and translated it by (25, 0, 0), thus __node__'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 its parent.

Now let's figure out where these things really are. Start at the root SceneNode. Its position is always (0, 0, 0). Now, __node__'s position is (root + node): (0, 0, 0) + (25, 0, 0) = (25, 0, 0). Not surprising. Now, __node2__ is a child of __node__, so its position is (root + node + 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 [/docs/api/html/classOgre_1_1SceneManager.html#a8c3389aea8f436037850ddc64f6d1d7d|GetSceneNode] and [/docs/api/html/classOgre_1_1SceneManager.html#a0d7e8374bd4774284ec6adfbd286ddbc|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 objects 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 [/docs/api/html/classOgre_1_1Node.html#a76b6c58ff14ff8c401e773dcb400b7fa|Scale] method in SceneNode. Try changing the values in ''Scale'' and see what you get:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
mSceneMgr.AmbientLight = new ColourValue(1, 1, 1);

Entity    ent  = mSceneMgr.CreateEntity("Head", "ogrehead.mesh");
SceneNode node = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode");
node.AttachObject(ent);

node.Scale(0.5f, 1, 2);
 
Entity    ent2  = mSceneMgr.CreateEntity( "Head2", "ogrehead.mesh" );
SceneNode node2 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
node2.AttachObject(ent2);

node2.Scale(1, 2, 1);
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
mSceneMgr.AmbientLight = New ColourValue(1, 1, 1)

Dim ent  As Entity    = mSceneMgr.CreateEntity("Head", "ogrehead.mesh")
Dim node As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode")
node.AttachObject(ent)

node.Scale(0.5F, 1, 2)

Dim ent2  As Entity    = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh")
Dim node2 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
node2.AttachObject(ent2)

node2.Scale(1, 2, 1)
{CODE}
{VERSIONS}

!!Rotations
{img src="img/wiki_up/YawPitchRoll_5b_200px.png" alt="" align="center"}

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.

{img fileId="1636" width="61" align="left"}
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

{DIV(align="left",float="none",clear="both")}{DIV}

Try changing the Degree amount and combining multiple transforms:

{VERSIONS(nav="y",default="C#")}
{CODE(wrap="1", colors="c#")}
mSceneMgr.AmbientLight = new ColourValue(1, 1, 1);

Entity    ent  = mSceneMgr.CreateEntity("Head", "ogrehead.mesh");
SceneNode node = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode");
node.AttachObject(ent);

node.Yaw(new Degree(-90));

Entity    ent2  = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh");
SceneNode node2 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", new Vector3(100, 0, 0));
node2.AttachObject(ent2);

node2.Pitch(new Degree(-90));

Entity    ent3  = mSceneMgr.CreateEntity("Head3", "ogrehead.mesh");
SceneNode node3 = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode3", new Vector3(200, 0, 0));
node3.AttachObject(ent3);

node3.Roll(new Degree(-90));
{CODE}
---(VB.NET)---
{CODE(wrap="1", colors="vbnet")}
mSceneMgr.AmbientLight = New ColourValue(1, 1, 1)

Dim ent  As Entity    = mSceneMgr.CreateEntity("Head", "ogrehead.mesh")
Dim node As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode")
node.AttachObject(ent)

node.Yaw(New Degree(-90))

Dim ent2  As Entity    = mSceneMgr.CreateEntity("Head2", "ogrehead.mesh")
Dim node2 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode2", New Vector3(100, 0, 0))
node2.AttachObject(ent2)

node2.Pitch(New Degree(-90))

Dim ent3 As Entity = mSceneMgr.CreateEntity("Head3", "ogrehead.mesh")
Dim node3 As SceneNode = mSceneMgr.RootSceneNode.CreateChildSceneNode("HeadNode3", New Vector3(200, 0, 0))
node3.AttachObject(ent3)

node3.Roll(New Degree(-90))
{CODE}
{VERSIONS}

!The Ogre/Mogre Environment
Most of the files (.DLL and .CFG) referred to in this section (and throughout the tutorials) can be found in the Mogre SDK or the tutorial downloaded project "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.

!!DLLs and Plugins
Now that we have played with the Ogre/Mogre environment a bit, let's explain how the Ogre/Mogre 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. Mogre in turn __only wraps around the main library__ (more on that below).

!!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 by itself does not require any other .dll. It does require the [http://www.microsoft.com/downloads/en/details.aspx?FamilyID=9b2da534-3e03-4391-8a4d-074b9f2bc1bf&displaylang=en|Microsoft Visual C++ 2008 Redistributable Package]. But if you have Visual Studio installed on your machine than you should have these files available already. You will however need to install or bundle them with your application.

The Mogre wrapper for the main Ogre library is Mogre.dll (i.e Mogre.dll relies on OgreMain.dll). These DLLs must be included with every Mogre 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.

Bare in mind that __Mogre does not wrap around these__, it only exposes the Ogre methods that allow you to load them. The loading and using of these libraries in turn is entirely an Ogre thing and no managed code is involved in this process.

!!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. __Mogre itself does not wrap around these libraries__, but __other managed wrappers__ for them exist.

The Ogre/Mogre demos and SDK include 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, which MOIS is a managed wrapper for contained in MOIS.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/MOIS, then you shouldn't bother including the Cg and the CgProgramManager DLLs, but you must include the OIS and MOIS dlls or your application will not run.

!!Mogre and the .NET Framework
Since Mogre is a .NET wrapper of Ogre, there are some additional points to consider on top of those related to Ogre when using it.

The first and most important thing to keep in mind is that the OgreMain.dll is compiled against a particular CPU architecture. In most cases this is x86 but you could compile 64bit version if you wanted to. In either case - __your .NET projects must be limited to the platform of your OgreMain.dll__. You cannot use the "Any CPU" architecture. The reason for that is simple: on 64bit machines the .NET JIT will try to create 64bit machine code, which then cannot load an x86 dll, and your application will fail to load as Mogre.dll(64bit) will not be able to load OgreMain.dll(x86). If you keep your project platform target to x86 you will be fine.

The other important note about Mogre and .NET is that there are __two__ versions of Mogre available - one for .NET 3.5 and below, targeted at the Visual Studio 2008 environment. The other is for .NET 4.0 targeted at the Visual Studio 2010 environment. During the tutorials you will have the choice of downloading both depending on which version of Visual Studio you prefer to use. However when you deploy your application you need to take this into account and decide which .NET version you are targeting.

!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. These files are __not mandatory__ and their functions can be done __programatically__. 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.

In Mogre you have to load this file semi-manually. For now the Mogre tutorials framework takes care of that for you.

!!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/Mogre manipulates directly. The Mogre tutorials framework uses only plugins.cfg and resources.cfg. However Mogre itself does not really require these configuration files - you can do everything programatically if you wish. 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 methods that we've introduced. Since these are the most basic objects, we will be using them very often. You will get more familiar with them as you work through the next few tutorials.

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

---

Proceed to ((Mogre Basic Tutorial 2)) ''Cameras, Lights, and Shadows''

---
History: Mogre Basic Tutorial 1

Source of version: 14 (current)

Search by Tags

Latest Changes

Search

Online Users
