%prevogre%

Microsoft Visual C++ 6 (SP3+)

Ogre does not provide support for VC6. It's from 1998, and rather old. It does not support ISO C++. It will only cause you pain.

It's recommended to use Visual C++ 2005 Express (also called VC8) instead.

If you absolutely must use that ancient thing, proceed on your own. You are not going to receive any support, other than people telling you to upgrade.

Microsoft Visual C++ .NET

Important:

If you use Visual Studio 2005 (VC8) make sure to get service pack #1 to go with it.

Note: If you are using VC++ .NET 2003 or later, you can use the Ogre Application Wizard and you are ready to create OGRE apps - feel free to skip down to the code section, as the application wizard will set up the project for you. Also see The Complete Blanks Guide To Using The OGRE SDK AppWizard - Shoggoth.

Otherwise, to manually configure the IDE, follow these steps:

1. Create a new project
   
   
   
2. Choose 'Visual C++ Projects' / 'Win32' then 'Win32 Project'.
   
   
   
3. Enter a name for your project and change the location to point to a work directory (separate from the runtime directory).
4. Select 'Windows Application' and 'Empty project' when prompted for the type of project to create.
   
   
   
   
5. Create a new source file by selecting 'Project -> Add New Item...'. Make sure the file is in the work directory. This step must be performed before editing project properties (otherwise the 'C/C++' page will be unavailable).
6. Save the project.

If you named your project "Testproject" and selected a location like C:\Work, and checked the box called "Create directory for solution", with a solution name of "Testsolution", then the directory structure will be: C:\Work\Testsolution\Testproject. If you do not create a directory for the solution, the structure will simply be: C:\Work\Testproject.

To clarify where the DLL files should be, an easy way is to copy the \bin folder (containing \debug and \release) and the \media folder from the OGRE installation directory to your Testproject folder (note: in this case you might be copying DLLs that won't be needed, but it's the hassle-free way). If you follow the convention presented above and you created folders for the header, scripts and source files, you have the following folders under \Testproject (excluding subfolders): 'bin', 'include', 'media', 'testsolution', 'scripts', and 'src'. However, if you don't want to copy them while running your Testproject from Visual Studio just add the path to OGRE's DLL files to the %PATH% global environment variable like this:

Debugging : Environment                             = PATH=%PATH%;%OGRE_HOME%\bin\debug

and for the release version

Debugging : Environment                             = PATH=%PATH%;%OGRE_HOME%\bin\release

This will not modify the %PATH% environment variable permanently, just for the given run, so its safer. You could modify it globally for all windows applications like this:

My Computer -> Properties -> Advanced -> Environment Variables -> System Variables -> Path    += ;%OGRE_HOME%\bin\debug

or

My Computer -> Properties -> Advanced -> Environment Variables -> System Variables -> Path    += ;%OGRE_HOME%\bin\release

but this could lead to confusion if working with different Ogre versions and is not recommended.

If you follow the next few steps carefully, your project should compile without errors.

Configure your project with the following settings. All of these are for the Debug configuration. To set up the Release configuration just change the directories from '\Debug\' to '\Release\'. Select "project properties" and under "configuration properties" add the following:

Debugging : Command                                 = $(OutDir)\$(ProjectName).exe
 Debugging : Working Directory                       = $(OutDir)
 C/C++ : Preprocessor : Preprocessor Definitions += _STLP_DEBUG (only in Debug mode, not needed for .Net 2003 and 2005)
 C/C++ : Code Generation : Use runtime library      = Multithreaded Debug DLL (Multithreaded DLL in Release)
 Linker : General : Output File                            = ..\bin\Debug\[appname].exe
 Linker : Input : Additional Dependencies                += OgreMain_d.lib OIS_d.lib  (OgreMain.lib OIS.lib in Release)

If you also use CEGUI, you need to tell Visual Studio to link the libs by doing this:

Linker : Input : Additional Dependencies                += CEGUIBase_d.lib OgreGUIRenderer_d.lib  (CEGUIBase.lib OgreGUIRenderer.lib in Release)

And, for those using the SDK:

C/C++ : General : Additional Include Directories      = ..\include;$(OGRE_HOME)\include;$(OGRE_HOME)\samples\include
 Linker : General : Additional Library Directories         = $(OGRE_HOME)\lib

Or, for those using the source release:

C/C++ : General : Additional Include Directories      = ..\include;$(OGRE_SRC)\OgreMain\include;$(OGRE_SRC)\Samples\Common\Include
 Linker : General : Additional Library Directories         = $(OGRE_SRC)\OgreMain\Lib\Debug

Additional hints on getting your application to run from within the IDE:<br \>

Visual Studio Debugging Settings - Shoggoth

Code::Blocks & MinGW 3.4.5 & STLPort 5.0

Have a look at the build options for Demo_CameraTrack, most of the demos use the same build options.

Note: with MinGW gcc 3.4.5 you can link directly against dll's built by gcc 3.4.5 and do not require an import lib. This is the same setup on Linux where you link directly to the shared object (.so). This is why the SDK does not come with import libs for Ogre. You don't need them.

Build options that you should use:

Normally you will have two targets: Debug and Release.

To create a new target:

1. Right click on the project in the Management window and select Properties in the popup and this will open up the properties window for your project.
2. Select the Target tab.
3. Select Add to define a new target.
4. Type in the target name ie Debug.
5. Select OK.

Select Build Options to modify build options for a target.

Project build options

will be used for both Debug and Release target build options:

ensure Selected compiler is: GNU GCC Compiler

• Compiler
  • Other options
    • -mthreads
    • -fmessage-length=0
    • -fexceptions
    • -fident
  • '#defines'
    • _STLP_NO_CUSTOM_IO

If your app does not define any custom IO templates then this define will speed up compiles.

• _STLP_USE_DYNAMIC_LIB

this ensures that the DLL version of STLPort is used.

• Linker
  • Other linker options:
    • -Wl,--enable-auto-image-base
    • -Wl,--add-stdcall-alias
• Directories
  • Compiler
    • $(OGRE_HOME)\stlport\stlport

VERY IMPORTANT: The stlport include directory has to be first in the include directories. If it is not then headers used for libstdc++ could get included which will cause conflicts with stlport during the link stage. You will most likely get undefined reference error messages with member methods saying they require std::string (method parameters). You should never see std:: in an error message and if you do then it means that the STLPort headers were not found and libstdc++ headers were used instead. If you do end up in this scenerio, after you correct the directory problem you must do a rebuild so that everything gets recompiled with the proper headers. Selecting build won't do it since CB will just attempt to do the link stage again since it doesn't detect any changes in the source and will fail again.

• $(OGRE_HOME)\include
• Your project include directories
• Linker
  • $(OGRE_HOME)\bin\$(TARGET_NAME)

this is the path to OgreMain.dll or OgreMain_d.dll along with stlport.5.0.dll or stlportstlg.5.0.dll depending on TARGET_NAME state. $(TARGET_NAME) is a built in

Code::Blocks

macro that you can use in your project settings. It gives you the active project target build name.

Debug build target options:

ensure Selected compiler is: GNU GCC Compiler
set Policy to 'Append target options to project options'

• Compiler
  • '#defines'
    • WIN32
    • _DEBUG
    • _WINDOWS
    • _STLP_DEBUG

this tells STLPort to use the special debug build version of the dll

• Linker
  • Link libraries:
    • Your project dll's or static libs (.a)
    • OgreMain_d

this is the name of the debug build of OgreMain dll.

• stlportstlg.5.0

this must be the last entry

Release build target options:

ensure Selected compiler is: GNU GCC Compiler
set Policy to 'Append target options to project options'

• Compiler
  • '#defines'
    • WIN32
    • NDEBUG
    • _WINDOWS
• Linker
  • Link libraries:
    • Your project dll's or static libs (.a)
    • OgreMain

this is the name of the release build of OgreMain dll.

• stlport.5.0

this must be the last entry

Note: OGRE_HOME is a pre-defined environment variable setup by the SDK installer. OGRE_HOME points to the directory where the SDK is installed. You can use $(OGRE_HOME) within your build options when setting up paths to specific directories with the SDK that you will need to access.

WARNING Do not mix dll and static object builds using different STL implementations. Here is an example: You build a dll using stdlibc++ but your exe is built using STLPort. Everything that is c++ must be built using STLPort. This does not apply to C static libs and dll's.

---

Getting Help

Probably the top two problems people have with Ogre are not being able to compile or a missing dependency. For the first, you are going to need to learn how to use your compiler. If you barely know C++ then expect a challenge, but don't give up! Thousands of people have successfully gotten Ogre to work with both the GCC and MSVC compilers, so look in the wiki and forums for what they have done that you haven't. For missing dependencies, these are libraries that aren't installed, that aren't linked against your program, or that aren't in your runtime path. Other dependencies are incorrect rendering plugins in your plugins.cfg file or incorrect paths in your resources.cfg file, or missing one of the files all together.

If you have problems reread this page as well as Installing An SDK - Shoggoth and Building From Source - Shoggoth and look in the Ogre.log file. You may also find your problem answered in the Build FAQ. If you need further help, search the forums. It is likely your problem has happened to others many times. If this is a new issue, read the forum rules then ask away. Make sure to provide relevant details from your Ogre.log, exceptions, error messages, and/or debugger back traces. Be specific and people will be more able to help you.

Your First Application

Now we will create a basic source file for starting an OGRE application. This program, like the included samples, uses the example framework.

Copy the following code and include it as a new file in your project settings. Following our conventions, you'd put it in work_dir/src and name it SampleApp.cpp. Since this is dependent upon ExampleApplication.h and ExampleFrameListener.h make sure these files are accessible by your project. Our convention would have you put them in work_dir/include. You can copy them from the Samples directory.

#include "ExampleApplication.h"
 
 ''// Declare a subclass of the ExampleFrameListener class''
 '''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);        
     }
 };
 
 ''// Declare a subclass of the ExampleApplication class''
 '''class''' SampleApp : '''public''' ExampleApplication 
 {
 '''public''':
    SampleApp() 
    {
    }
 
 '''protected''':
    ''// Define what is in the scene
    '''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 
 #define WIN32_LEAN_AND_MEAN 
 #include "windows.h" 
 '''INT''' WINAPI WinMain(HINSTANCE hInst, HINSTANCE, LPSTR strCmdLine, '''INT''') 
 #else 
 '''int''' main('''int''' argc, '''char''' **argv) 
 #endif 
 {
     ''// Instantiate our subclass''
     SampleApp myApp;
 
     '''try''' {
         ''// ExampleApplication provides a go method, which starts the rendering.''
         myApp.go();
     }
     '''catch''' (Ogre::Exception& e) {
 #if OGRE_PLATFORM == OGRE_PLATFORM_WIN32 
         MessageBoxA(NULL, e.getFullDescription().c_str(), "An exception has occured!", MB_OK | MB_ICONERROR | MB_TASKMODAL);
 #else
         std::cerr << "Exception:\n";
         std::cerr << e.getFullDescription().c_str() << "\n";
 #endif
         '''return''' 1;
     }
 
 '''return''' 0;
 }
 
 #ifdef __cplusplus
 }
 #endif

Compile this code now. However before running the program, make sure you have a plugins.cfg and a resources.cfg in the same directory as the executable. Review the Prerequisites section for the purpose of these files. Edit them and make sure the paths are correct. Otherwise your OGRE setup dialog box may not have any rendering libraries in it, or you may recieve an error on your screen or in Ogre.log that looks something like this:

Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file

When the program starts it will display the OGRE setup dialog and start the application with a blank, black screen containing little more than the OGRE logo and an FPS (frame per second) display. We haven't added anything to this scene yet, as evidenced by the empty createScene method. Press ESC to quit the application.

If you didn't get this, something is not right in your setup. See the Prerequisites and the Getting Help sections to review your installation.

The ExampleApplication framework will boot the OGRE system, displaying a configuration dialog, create a window, setup a camera and respond to the standard mouselook & WSAD controls. All you have to do is to fill in the 'createScene' implementation. If you want to do more advanced things like adding extra controls, choosing a different scene manager, setting up different resource locations, etc, you will need to override more methods of ExampleApplication and maybe introduce a subclass of ExampleFrameListener.

As mentioned before, you don't have to use the ExampleApplication and ExampleFrameListener base classes. Use them to work through the tutorials and to test things out. For larger projects you'll want to write your own framework, or use one of the frameworks or engines available on Projects using OGRE.

Note for American readers

:

Sinbad the lead developer and creator of OGRE, is British. Naturally he uses British spellings such as "Colour", "Initialise" and "Normalise". Watch out for these spellings in the API.

See below to learn about your resources for getting help. Then your next step is to work through the Ogre Tutorials.