View source

[[Category:Gaming]][[Category:Index]][[Category:CISC 864]]Ogre can be tricky to install. For this reason, the EQUIS lab has adopted a standard Ogre platform and standard deployment infrastructure.

== 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 [http://www.ogre3d.org/wiki/index.php/The_absolute_newbies_guide_to_OGRE 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:
* [http://www.ogre3d.org/index.php?option=com_remository&Itemid=74&func=fileinfo&filecatid=9&parent=category The Ogre source]
* [http://www.ogre3d.org/index.php?option=com_remository&Itemid=74&func=selectcat&cat=4 Ogre dependencies]
If your computer does not have the DirectX SDK installed, you will require it as well:
* [http://msdn.microsoft.com/directx Microsoft DirectX SDK]

=== 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 [http://www.ogre3d.org/wiki/index.php/SettingUpAnApplication 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 [http://www.ogre3d.org/phpBB2/viewtopic.php?t=10543 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.
# Start up VC++ and Click the New Project button
# Select Visual C++ and 'Win32 Project' as the type
# Set your ''AppDir'' as the location
## Click Ok, and select the 'Application Settings' tab
## Check 'Empty project' and click Finish
# In the Solution Explorer, right-click on 'Source Files' and click Add|Add Existing Item...
# Select the .cpp file you created above and click 'Ok'
# 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 <tt>_WINDOWS</tt> and not <tt>_CONSOLE</tt>, and that

 Configuration Properties | Linker | System | SubSystem

is set to <tt>Windows</tt>, not <tt>Console</tt>.