Installing Ogre

From EQUIS Lab Wiki

Jump to: navigation, search

Ogre can be tricky to install. For this reason, the EQUIS lab has adopted a standard Ogre platform and standard deployment infrastructure.

Contents

Platform

We use:

  • Ogre 1.0.6
  • Microsoft Windows XPsp2
  • Microsoft Visual Studio 2005 (v8)

Ogre does work with other platforms, and every effort should be made to retain the portability of Ogre-based applications developed in the lab. Installation instructions for other operating systems or development environments can be found here, but these instructions are not necessarily up to date.

Installing Ogre

Ogre itself can be installed in SDK or source form. These instructions cover source installation.

Downloads

You require two zip files for the Ogre installation:

If your computer does not have the DirectX SDK installed, you will require it as well:

Installation

These steps will install Ogre and allow you to compile and run the sample programs.

Installing the DirectX SDK

First install the DirectX SDK, if necessary:

  • Install the SDK that you downloaded

After installing the SDK, you need to direct Visual C++ to find the DirectX include and library files:

  • Open Tools|Options|Projects|VC++ Directories
  • Under library files, set the appropriate library directory for the SDK. E.g.,
C:\Program Files\Microsoft DirectX SDK (December 2005)\Lib\x86
  • Under include files, set the appropriate include directory for the SDK. E.g.,
C:\Program Files\Microsoft DirectX SDK (December 2005)\Include

Installing Ogre

First, select a directory for the Ogre distribution. This will not be the directory where you create your own programs, but the sample programs will be located here.

  • Create a directory for the Ogre distribution, such as C:\Ogre\Ogre-1.0.6. We will refer to this directory as Dir

Extract the downloaded archives:

  • Extract the Ogre source archive into Dir
  • Extract the Ogre dependencies into Dir\ogrenew

Create an environment variable referencing Ogre's main directory:

  • Open your Control Panel, and select System|Advanced|Environment Variables
  • Add a new System Variable with the name OGRE_HOME and the value Dir\ogrenew

Add necessary directories to your path:

  • Add the following to your Path System Variable:
    •  %OGRE_HOME%\OgreMain\lib\debug; %OGRE_HOME%\OgreMain\lib\release; %OGRE_HOME%\Samples\Common\bin\Debug; %OGRE_HOME%\Samples\Common\bin\Release; %OGRE_HOME%\Samples\Common\CEGUIRenderer\lib

Compiling Ogre and the Samples

In this step, you will use VC++ to compile the Ogre distribution and the sample programs. This is straightforward, but with one minor glitch: the latest DirectX SDK (which you just downloaded) no longer supports DirectX version 7. As we will see below, to get Ogre to compile and run properly, you have to remove this from the project.

Open the project:

  • Open the folder Dir\ogrenew
  • Double-click Ogre_vc8.sln to open the Ogre distribution.

Delete the DirectX 7 project

  • Right-click the project entitled RenderSystem_Direct3D7 and select remove

Build the project:

  • Open Build|Batch Build
  • Click the Select All button (do not skip this step)
  • Click Build

The build may take 15 minutes or more, depending on the speed of your computer.

Once the build has completed, try running the samples to ensure that everything was successful. Before running the samples, you need to remove references to DirectX 7. Edit the files:

  • Dir\ogrenew\Samples\Common\bin\Debug\Plugins.cfg
  • Dir\ogrenew\Samples\Common\bin\Release\Plugins.cfg

In both, remove the line

  • Plugin=RenderSystem_Direct3D7

Creating a New Project

For consistency and portability, our Ogre projects follow a standard directory layout. This layout is originally described here, and this discussion is adapted from that text.

Creating the Application Folder

Create a new folder wherever you would like your application to reside. We will refer to this folder as AppDir. Within AppDir, create the folders:

  • include for your .h files
  • src for your .cpp files
  • scripts for your materials and fragment/vertex programs
  • bin\Debug for your debug-mode binaries
  • bin\Release for your release-mode binaries

Creating a Basic Source File

For this example, create the most basic source file for starting an OGRE application. Copy/paste this into a .cpp file in <yourfolder>\src:

#include "ExampleApplication.h"

#if OGRE_PLATFORM == OGRE_PLATFORM_WIN32
#define WIN32_LEAN_AND_MEAN
#include "windows.h"
#endif


class MyListener : public ExampleFrameListener
{
public:
	MyListener(RenderWindow* win, Camera* cam)
		: ExampleFrameListener(win, cam)
	{
	}

	bool frameStarted(const FrameEvent& evt)
	{
		return ExampleFrameListener::frameStarted(evt);        
	}

	bool frameEnded(const FrameEvent& evt)
	{
		return ExampleFrameListener::frameEnded(evt);        
	}

};

class MyApplication : public ExampleApplication
{
public:
    MyApplication() {}
	
protected:

    void createScene(void)
    {
        // put your scene creation in here
    }

    // Create new frame listener
    void createFrameListener(void)
    {
        mFrameListener = new MyListener(mWindow, mCamera);
        mRoot->addFrameListener(mFrameListener);
    }
};

#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
    MyApplication app;

    try {
        app.go();
    } catch( 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();
#endif
    }

    return 0;
}

#ifdef __cplusplus
}
#endif

Creating a Project

One way to create a Visual C++ OGRE application is to use the Ogre Application Wizard, a Visual Studio wizard that sets up the directory trees and project options for you. We have not tested this locally, so caveat emptor.

To set up a project manually, follow these steps.

  1. Start up VC++ and Click the New Project button
  2. Select Visual C++ and 'Win32 Project' as the type
  3. Set your AppDir as the location
    1. Click Ok, and select the 'Application Settings' tab
    2. Check 'Empty project' and click Finish
  4. In the Solution Explorer, right-click on 'Source Files' and click Add|Add Existing Item...
  5. Select the .cpp file you created above and click 'Ok'
  6. Save the project

Setting the Project Options in Visual C++

Modify your project options by right-clicking on the project name in the Solution Explorer and selecting 'Properties'. Follow the appropriate instructions depending on whether you set up the source release or the SDK release.

Setting up Project Options for Ogre Source Release

Under the Debug tab, set the following options:

Configuration Properties|Debugging|Working Directory = ..\bin\Debug
C/C++|Code Generation|Use runtime library            = Multithreaded Debug DLL
Linker|General|Output File                           = ..\bin\Debug\[appname].exe
Linker|General|Additional Library Directories        = $(OGRE_HOME)\OgreMain\Lib\Debug
Linker|Input|Additional Dependencies                 += OgreMain_d.lib

Under the Release tab, set the following options:

Configuration Properties|Debugging|Working Directory = ..\bin\Release
C/C++|Code Generation|Use runtime library            = Multithreaded DLL
Linker|General|Output File                           = ..\bin\Release\[appname].exe
Linker|General|Additional Library Directories        = $(OGRE_HOME)\OgreMain\Lib\Release
Linker|Input|Additional Dependencies                 += OgreMain.lib

Under the All Configurations tab, set the following options:

C/C++|General|Additional Include Directories         = ..\include;$(OGRE_HOME)\OgreMain\include;$(OGRE_HOME)\Samples\Common\Include

Setting up Project Options for Ogre SDK Release

Under the Debug tab, set the following options:

Configuration Properties|Debugging|Working Directory = ..\bin\Debug
C/C++|Code Generation|Use runtime library            = Multithreaded Debug DLL
Linker|General|Output File                           = ..\bin\Debug\[appname].exe
Linker|General|Additional Library Directories        = $(OGRE_HOME)\lib
Linker|Input|Additional Dependencies                 += OgreMain_d.lib

Under the Release tab, set the following options:

Configuration Properties|Debugging|Working Directory = ..\bin\Release
C/C++|Code Generation|Use runtime library            = Multithreaded DLL
Linker|General|Output File                           = ..\bin\Release\[appname].exe
Linker|General|Additional Library Directories        = $(OGRE_HOME)\OgreMain\Lib\Release
Linker|Input|Additional Dependencies                 += OgreMain.lib

Under the All Configurations tab, set the following options:

C/C++|General|Additional Include Directories         = ..\include;$(OGRE_HOME)\OgreMain\include

Setting up Files Required for Runtime

Here we list the runtime dependencies you'll need to fulfil to run your OGRE-based application. Where we've put something in square brackets (e.g. OgreMain[_d]) it means it's only applicable for the debug build.

Application Extras

Every application requires the following configuration files:

  • resources.cfg (if you're using the ExampleApplication resource setup)
  • plugins.cfg
  • All the plugin libraries listed in plugins.cfg
resources.cfg File

A file resources.cfg should be placed in your bin\Debug and bin\release folders. The minimal resources.cfg should have the following content, in which you must replace 'C:/Ogre/Ogre-current' by the path to your 'ogrenew' directory:

# Resource locations to be added to the 'boostrap' path
# This also contains the minimum you need to use the Ogre example framework
[Bootstrap]
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/OgreCore.zip

# Resource locations to be added to the default path
[General]
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/fonts
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/materials/programs
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/materials/scripts
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/materials/textures
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/models
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/overlays
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/particle
FileSystem=C:/Ogre/Ogre-current/ogrenew/Samples/Media/gui
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/cubemap.zip
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/cubemapsJS.zip
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/dragon.zip
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/fresneldemo.zip
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/ogretestmap.zip
Zip=C:/Ogre/Ogre-current/ogrenew/Samples/Media/packs/skybox.zip
plugins.cfg File

A file plugins.cfg should be placed in your bin\Debug folder. The minimal plugins.cfg should have the following content, in which you must replace 'C:/Ogre/Ogre-current' by the path to your 'ogrenew' directory:

# Defines plugins to load

# Define plugin folder
PluginFolder=C:/Ogre/Ogre-current/ogrenew/Samples/Common/bin/Debug

# Define plugins
Plugin=RenderSystem_Direct3D7
Plugin=RenderSystem_Direct3D9
Plugin=RenderSystem_GL
Plugin=Plugin_ParticleFX
Plugin=Plugin_BSPSceneManager
Plugin=Plugin_OctreeSceneManager
Plugin=Plugin_CgProgramManager

Similarly, a file plugins.cfg should be placed in your bin\Release folder. The minimal plugins.cfg should have the following content, in which you must replace 'C:/Ogre/Ogre-1.0.1' by the path to your 'ogrenew' directory:

# Defines plugins to load

# Define plugin folder
PluginFolder=C:/Ogre/Ogre-current/ogrenew/Samples/Common/bin/Release

# Define plugins
Plugin=RenderSystem_Direct3D7
Plugin=RenderSystem_Direct3D9
Plugin=RenderSystem_GL
Plugin=Plugin_ParticleFX
Plugin=Plugin_BSPSceneManager
Plugin=Plugin_OctreeSceneManager
Plugin=Plugin_CgProgramManager

VC7.1 Build Problems

This space will be used to list problems encountered with using the MS Visual C++ build system with our toolset, and their solutions.

LNK2019: Unresolved external symbol

You can get the following error if, when you are creating a new OGRE application, you choose Win32 Console Project as the project type instead of Win32 Project:

Linking...
MSVCRTD.lib(crtexe.obj) : error LNK2019: 
unresolved external symbol _main referenced in function _mainCRTStartup
fatal error LNK1120: 1 unresolved externals

To resolve the problem, make sure that

Configuration Properties | C/C++ | Preprocessor | Preprocessor Definitions

contains _WINDOWS and not _CONSOLE, and that

Configuration Properties | Linker | System | SubSystem

is set to Windows, not Console.