Setting Up An Application - First Application         Your First Application

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.