Mogre Basic Tutorial 0

From Ogre Wiki

Basic Tutorial 0: Setting up a Mogre Application

Original version by Clay Culver.

Contents 1 Getting Started 1.1 Prerequisites 1.2 Introduction 2 Installation 2.1 Downloading Mogre 2.2 Downloading MogreFramework 2.3 Setting Your PATH Variable 3 Building Your First Mogre Application 3.1 Creating a Project 3.2 Adding Configuration Files 3.3 Testing Your Application 4 Troubleshooting 4.1 Checklist 4.2 Getting Help 5 Exception Handling With Mogre 6 Final Note

Getting Started

Note:

• This site is outdated. For depencies of Mogre 1.6.4 look here.
• If you have problems, use this forum thread.

Prerequisites

This tutorial assumes you have knowledge of C# programming and are able to setup and compile a standard C# application. You should have Visual C# 8.0 installed (the free Express Version will work fine).

Introduction

In this tutorial we will be going over how to install Mogre and how to setup and run an Mogre application. We will also go over some of the pitfalls of Mogre and how to avoid them, as well as proper Ogre exception handling. If you have questions about this tutorial, or Mogre in general, you should ask the question in the Mogre Forums.

Installation

Downloading Mogre

You can download the latest version of Mogre from the Mogre SourceForge project page. I suggest downloading the prebuilt SDK instead of the source code zip file. When you install the SDK, you will be given the choice of installation locations. This tutorial will assume you have installed the MogreSDK in default location (C:\MogreSDK).

You will also need vcredist_x86.exe; check it out in the same URL above. Some users reported that applications executed correctly after installation (e.g.: Visual Studio 2005, Team Edition, Version 8.0.50727-42).

Alternatively you can install the SP1 for your IDE (Visual Studio, C# Express, etc.) So you also can use the debug version of DLL files.

Downloading MogreFramework

The series of tutorials which follows this one will use a .Net assembly called the MogreFramework. Before getting started, you will need the file MogreFramework.dll.

Download:

• MogreFramework.dll - precompiled version for Mogre 1.4.8
• Source code - for Mogre 1.4.8; updated by Smiley80 in January 2009

Put the file MogreFramework.dll in both of these directories:

• C:\MogreSDK\bin\debug
• C:\MogreSDK\bin\release

Note:

• For each Mogre version a related MogreFramework file is needed. Maybe you have to recompile it.
• For Mogre 1.6.x look to this forum thread.

Setting Your PATH Variable

Ogre itself includes a large number of DLLs which we will need to include in Windows PATH variable. To do this, go to the Control Panel and open System. Click on "Advanced" tab, then click on the "Environment Variables" button. Under "System Variables", find the PATH Variable and click on it. Now click on the "Edit" button. At the end of the "Variable Value" field, add ";C:\MogreSDK\bin\release;C:\MogreSDK\bin\debug", and then click OK. Exit out of the System Properties and the Control Panel.

Note: You may need to restart your computer before these changes will take effect.

Building Your First Mogre Application

Creating a Project

Open up Visual Studios and create a new project. Be sure to select the "Windows Application" template, give the program a name, then hit OK. Visual C# creates a default form for you, called Form1. Delete that out of the project.

Now that we have a project created, we need to add references to it. Right click on "References" in the project, and select "Add Reference". Click on the "Browse" tab, and change the directory to "C:\MogreSDK\bin\release". Select both Mogre.dll and MogreFramework.dll and click "OK".

Adding Configuration Files

Before we can actually use the project, we have to add three configuration files to our project. In windows, navigate to the C:\MogreSDK\bin\release directory and copy all files with the ".cfg" extention into your project's bin\debug, and bin\release folders (you may have to create the folders). Finally, open up the resources.cfg files you added to your project. You will notice it contains a relative path for the directories. We will have to set this manually to the absolute path. Replace all occurances of "../../" in the document with "C:/MogreSDK/". You must do this for all relative directories, "including PluginFolder=." in Plugins.cfg.

Testing Your Application

Now that the project is fully setup and ready to be used, open up "program.cs" and replace the code with the following:

using System;
using System.Collections.Generic;
using System.Windows.Forms;
using Mogre;
using MogreFramework;

namespace Test
{
    static class Program
    {
        [STAThread]
        static void Main()
        {
            OgreWindow win = new OgreWindow();
           
            try
            {
                win.Go();
            }
            catch (System.Runtime.InteropServices.SEHException)
            {
                if (OgreException.IsThrown)
                    MessageBox.Show(OgreException.LastException.FullDescription,
                                    "An Ogre exception has occurred!");
                else
                    throw;
            }
        }
    }
}

Run the application by pressing F5. You should see a splash screen showing you the startup process and then a blank window with a black background. If so, congratulations! You have just successfully created your first Ogre project. We will be doing more with this later.

NOTE: If you get a line 80 or a line 100 exception after build, try to copy your build exe into the appropiate Debug or Release folder in your MogreSDK library (default: C:\MogreSDK\bin\(Debug or Release) and run it.

Troubleshooting

Checklist

If you have problems getting started, check the following things first:

• Did you install the Mogre SDK and NOT the standard OgreSDK? The Mogre SDK can be obtained from the [1]. The Mogre SDK will include Mogre.dll in the C:\OgreSDK\bin\debug and C:\OgreSDK\bin\release directories.
• Did you download and install the MogreFramework? This assembly is NOT required to use Mogre, but it will be used in all Mogre tutorials.
• Is your PATH variable properly set so that Ogre can find them?
• Did you add references to "Mogre.dll" AND "MogreFramework.dll" in your project?
• Did you copy the Ogre configuration files from the SDK directory to your project's output directories? (They should be placed in YourProjectsDirectory\bin\debug and YourProjectsDirectory\bin\release.)
• Did you modify the config files in BOTH the release and debug directories to have the absolute path to the media files?
• To use the Direct3D9-Renderer you need to install the DirectX Redistributables from November 2007 or newer.

Getting Help

If you have checked these things, feel free to post the problem you are having to the Mogre forums. Be sure to include a detailed description of the problem, the things you have tried to fix it, and paste the error messages from the Ogre.log file if there are any (this file is located in the project's output directory).

Exception Handling With Mogre

Before wrapping up this tutorial, I'd like to breifly mention how to handle exceptions which originate from Ogre itself. Mogre and C# can handle C++ exceptions, but they do not act as you would expect them to. If you ever see a message which states "Runtime Error! ... This application has requested the Runtime to terminate in an unusual way..." then you probably encountered an error in Ogre somewhere.

To properly handle an exception thrown by the C++ Ogre library, you need to catch an exception of the type System.Runtime.InteropServices.SEHException. After catching this exception, you can see if it's an Ogre exception (instead of just a crash) by checking the static OgreException.IsThrown property. If that property is true, then you handle the exception. For example, here is a chunk of code to catch and display an Ogre exception:

try
{
    ...
}
catch (System.Runtime.InteropServices.SEHException)
{
    if (OgreException.IsThrown)
        MessageBox.Show(OgreException.LastException.FullDescription,
                        "An Ogre exception has occurred!");
    else
        throw;
}

Wrapping your main method with a try block such as this one can save you lots of headaches down the line when you are debugging your application. Notice we have not added a catch block to catch a generic Exception object. This way when we are debugging the application, Visual Studios can insert a breakpoint for an unhandled C# exception, whereas Visual Studios cannot do this for C++ exceptions.

Final Note

By this point you should be able to create and run an empty Mogre project. All subsequent tutorials will assume you can successfully set up an Mogre project.

Also, a possible way to speed up the creation of new Mogre projects is to create a new Templete. An example templete is available here: BasicMogreSetup. NOTE- this templete is only able to be used with Visual Studios 2008 C#. A tutorial on how to create a templete is available here: How to Create a Templete in VSC# 2008.

Proceed to Mogre Basic Tutorial 1 The SceneNode, Entity, and SceneManager constructs