Mogre Basic Tutorial VB 5        

Basic Tutorial 5: The Ogre startup sequence

Original version by Clay Culver

Ported to VB.NET by Aeauseth

Any problems you encounter while working with this tutorial should be posted to the Mogre Forums.


This tutorial assumes you have knowledge of VB.NET programming and are able to setup and compile an Mogre application (if you have trouble setting up your application, see Mogre Basic Tutorial VB 0 for a detailed setup walkthrough).


In this tutorial I will be walking you through how to setup ogre in your own environment. Ogre has a very specific order in which you need to understand before you can write your own Ogre application from scratch. Most of the previous tutorials provided starting code, which include various Ogre statemetens which were glossed over. In this tutorail we will discuss these sections in more detail.

As you go through the tutorial you should be slowly adding code to your own project and watching the results as we build it.

Getting Started

This time around we will start with just a code framework:

 <font color='blue'>Imports</font> Mogre
 <font color='blue'>Module</font> Module1
     <font color='blue'>Sub</font> Main()
         <font color='blue'>Try
 </font>            <font color='green'>'Creating the Root Object 
 </font>            <font color='green'>'Defining the Resources 
 </font>            <font color='green'>'Setting up the RenderSystem
 </font>            <font color='green'>'Creating the Render Window
 </font>            <font color='green'>'Initializing Resource Groups
 </font>            <font color='green'>'Creating the Scene
 </font>            <font color='green'>'The Render Loop
 </font>        <font color='blue'>Catch</font> ex <font color='blue'>As</font> System.Runtime.InteropServices.SEHException
             <font color='blue'>If</font> OgreException.IsThrown <font color='blue'>Then
 </font>                MsgBox(OgreException.LastException.FullDescription, MsgBoxStyle.Critical, _
                      <font color='darkred'>"An Ogre  exception has occured!"</font>)
             <font color='blue'>Else
 </font>                MsgBox(ex.ToString, <font color='darkred'>"An error has occured"</font>)
             <font color='blue'>End</font> <font color='blue'>If
 </font>        <font color='blue'>End</font> <font color='blue'>Try
 </font>    <font color='blue'>End</font> <font color='blue'>Sub
 End</font> <font color='blue'>Module</font>

Make sure you can compile and run the application before continuing. If you are having difficulty, refer to the project setup guide or post to the forums. Note that this program should do nothing until we add code to it.

Creating the Root Object

The first thing that any Ogre application needs to do is to create the Root object. Add the following line of code:

      <font color='green'>'Creating the Root Object</font>
      <font color='blue'>Dim</font> myRoot <font color='blue'>As</font> Root = <font color='blue'>New</font> Root(<font color='darkred'>"Plugins.cfg"</font>, <font color='darkred'>"ogre.cfg"</font>, <font color='darkred'>"ogre.log"</font>)

That's it. Note that the Root's constructor takes in three parameters. The first is the name of the plugin file, the second is the config file name, and the last is the log file name. I have shown you the default values for clarity.

Defining the Resources

The next thing we need to do is to parse the resource config file and load resources into Ogre. Adding a resource location to ogre is done through a call to a single function (don't add this code to your project):

     ResourceGroupManager.Singleton.AddResourceLocation(archName, typeName, secName)

The first parameter of this function is the location of the resource on disk (file/directory name). The second parameter is the type of resource which is generally either "FileSystem" (for a directory) or "Zip" (for a zip file). The last paramter is the resource group to add the resource to.

Ogre provides a convenient way of dealing with resources. There is a config file parser class which allows you to place all of your resources into one file. Find the DefineResources function and add this code to it:

         <font color='green'>'Defining the Resources 
 </font>        <font color='blue'>Dim</font> cf <font color='blue'>As</font> <font color='blue'>New</font> ConfigFile
         cf.Load(<font color='darkred'>"resources.cfg"</font>, vbTab + <font color='darkred'>":="</font>, <font color='blue'>True</font>)
         <font color='blue'>Dim</font> seci <font color='blue'>As</font> ConfigFile.SectionIterator = cf.GetSectionIterator
         <font color='blue'>Dim</font> secName <font color='blue'>As</font> <font color='blue'>String</font>, typeName <font color='blue'>As</font> <font color='blue'>String</font>, archName <font color='blue'>As</font> <font color='blue'>String
 </font>        <font color='blue'>While</font> (seci.MoveNext())
             secName = seci.CurrentKey
             <font color='blue'>Dim</font> settings <font color='blue'>As</font> ConfigFile.SettingsMultiMap = seci.Current
             <font color='blue'>For</font> <font color='blue'>Each</font> pair <font color='blue'>As</font> KeyValuePair(<font color='blue'>Of</font> <font color='blue'>String</font>, <font color='blue'>String</font>) <font color='blue'>In</font> settings
                 typeName = pair.Key
                 archName = pair.Value
                 ResourceGroupManager.Singleton.AddResourceLocation(archName, typeName, secName)
             <font color='blue'>Next
 </font>        <font color='blue'>End</font> <font color='blue'>While</font>

This is the standard way of parsing the resources.cfg file to populate the ResourceGroupManager. Note that the AddResourceLocation function only tells Ogre where resources are located and what resource groups they are in. This does not parse the scripts and load resources. We will be loading these resources shortly.

Setting up the RenderSystem

Ogre offers a configuration dialog to set the graphics settings for your application. Find the SetupRenderSystem method and add the following code to it:

             <font color='blue'>If</font> <font color='blue'>Not</font> myRoot.ShowConfigDialog <font color='blue'>Then
 </font>                <font color='blue'>Throw</font> <font color='blue'>New</font> Exception(<font color='darkred'>"The user cancled the configuration dialog."</font>)
             <font color='blue'>End</font> <font color='blue'>If</font>

Alternatively you can manually setup the RenderSystem this way (don't add this code to your project):

             <font color='blue'>Dim</font> myRenderSystem <font color='blue'>As</font> RenderSystem = myRoot.GetRenderSystemByName( _
                  <font color='darkred'>"Direct3D9 Rendering Subsystem"</font>)
                  <font color='green'>'or use "OpenGL Rendering Subsystem"</font>
             myRoot.RenderSystem = myRenderSystem
             myRenderSystem.SetConfigOption(<font color='darkred'>"Full Screen"</font>, <font color='darkred'>"No"</font>)
             myRenderSystem.SetConfigOption(<font color='darkred'>"Video Mode"</font>, <font color='darkred'>"800 x 600 @ 32-bit colour"</font>)

Creating the Render Window

Ogre can create the window in which we are rendering for us, or we can do it manually. Add the following code:

             <font color='green'>'Creating the Render Window
 </font>            <font color='blue'>Dim</font> MyWindow <font color='blue'>As</font> RenderWindow = myRoot.Initialise(<font color='blue'>True</font>, <font color='darkred'>"Ogre RenderWindow"</font>)

The Initialise function is actually a misnomer. This function creates a window to render Ogre in with the second parameter setting the window text.

If we are trying to embed Ogre into a window which has already been created, we need to use the windows handle which contains it. Assuming we have a windows forms control <font color='blue'>myControl</font>, this would be how you create the RenderWindow (do not add this code to the project):

             <font color='blue'>Dim</font> misc <font color='blue'>As</font> NameValuePairList = <font color='blue'>New</font> NameValuePairList()
             misc(<font color='darkred'>"parentWindowHandle"</font>) = myControl.Handle.ToString
             misc(<font color='darkred'>"outerDimensions"</font>) = <font color='darkred'>"True"
 </font>            MyWindow = myRoot.CreateRenderWindow(<font color='darkred'>"Ogre RenderWindow"</font>, _
                 myControl.Width, myControl.Height, <font color='blue'>False</font>, misc.ReadOnlyInstance)

Initializing Resource Groups

Before we can create the scene and place objects into it, we must first intialize the resources groups which contain our textures, materials, and models. In the LoadResources function, we told Ogre where all of the resources for the program are. Now we need to actually parse those scripts and resources. Failing to call IntializeAllResourceGroups (or InitializeResourceGroup) will result in your program not being able to find the meshes, textures, etc which your program uses.

Before we intialize the resourses we will set the default number of mipmaps which Ogre uses for the textures it loads. Find the InitializeResourceGroups function and add the following code:

             <font color='green'>'Initializing Resource Groups
 </font>            TextureManager.Singleton.DefaultNumMipmaps = 5

You can individually initialize each resource group in your application only when it's needed to save startup time and a little memory (use the InitializeResourceGroup function to do this). However, this is not the common approach in most Ogre applications. Note that when you initialize a resource group, it parses and loads scripts, but does not actually load the resources (such as models and textures) into memory until the program actually needs to use it.

You can change this behavior by pre-loading resource groups which you know you will be using. You can do this by calling the LoadResourceGroup, UnloadResourceGroup, and UnloadUnreferencedResourcesInGroup methods. By carefully selecting which resource groups to place scripts and models in (and manually loading and unloading resources), it's possible to drastically reduce the amount of memory ogre consumes.

For most commons uses of Ogre calling InitializeAllResourceGroups (and not manually Loading/Unloading resource groups) should be sufficient. If your program is using too much memory or if you are working with a very large scale application/game which uses a very large set of meshes, textures, scripts, and so on, you may want to actually plan out a strategy to deal with your resource allocation.

Creating the Scene

After the RenderWindow is created, we then need to create the SceneManagers, Viewports, and Cameras which the scene uses. We will create a simple scene to view for this tutorial. Add the following code to the CreateScene function:

             <font color='green'>'Creating the Scene
 </font>            <font color='blue'>Dim</font> myScene <font color='blue'>As</font> -SceneManager = myRoot.CreateSceneManager(SceneType.ST_GENERIC)
             <font color='blue'>Dim</font> myCamera <font color='blue'>As</font> Camera = myScene.CreateCamera(<font color='darkred'>"Camera"</font>)
             <font color='blue'>Dim</font> myNinja <font color='blue'>As</font> Entity = myScene.CreateEntity(<font color='darkred'>"ninja"</font>, <font color='darkred'>"ninja.mesh"</font>)
             myCamera.Position = <font color='blue'>New</font> Vector3(0, 200, -400)

The Render Loop

In games (and other applications), it is very common to have Ogre render as fast as the computer can handle (creating the highest FPS possible). Ogre provides a function which will do just that: Root's StartRendering method. This will keep rendering the scene until a frame listener returns false. Find the StartRenderingLoop method and add the following code:

             <font color='green'>'The Render Loop
 </font>            myRoot.StartRendering()

That's it. You may now run the program and see the results.

We can also have Ogre render a single frame by calling the RenderOneFrame method. This will return false when a single frame listener has returned false. A common approach to this would be something like this (do not add this code to your project):

             <font color='blue'>While</font> myRoot.RenderOneFrame
                 <font color='green'>'Do other things here, such as seleep for a short period of time
 </font>            <font color='blue'>End</font> <font color='blue'>While</font>

This allows you to perform other incremental actions, such as sleeping for a short time to lower the frames per second to a maximum amount (like 60fps).


In this tutorial we have gone over the basics of getting Ogre started as a stand-alone application. You may have noticed that there are no input routines. We discussed those in previous tutorials and I didn't want to complicate things here.

Proceed to Basic Tutorial 6 Overlay's and Publishing