Changelog:
6th January 2010
- Updated application walkthrough for Ogre 1.7.

Overview

Howdy! This is my little FAQ and troubleshooting guide for anyone new to the Ogre engine. I will be expanding it over time to cover as many problems and questions as possible. The following assumes that you are using Visual Studio C++ 2005/2008 and have built the latest Ogre.

If you haven’t yet built Ogre, see my Building Ogre with Visual Studio guide.

Can you walk me through setting up an Ogre application?

Sure!

  1. Open up Visual Studio C++.
  2. File -> New -> Project…
  3. Make sure the project type is “Win32″ and the templated “Win32 Console Application” is highlighted.
  4. Enter the name and location of your project in the respective fields. I named mine “OgreTestProject”.
  5. An application wizard will pop up. Click “Application Settings” and check “Empty project” then click finish.
  6. Right click the “Source Files” folder in the Solution Explorer. Then Add -> New Item…
  7. Select “C++ File (.cpp)” and enter “main” in the Name field. Add “\src” to the end of the Location field value.
  8. Go to Project -> Properties.
  9. In the top left hand corner of the Properties window change the Configuration to “All Configurations”.
  10. Select General in the Configuration Properties. Copy the “Output Directory”. Select Debugging and paste this in the “Working Directory” field.
  11. Expand C/C++ -> General
  12. In the “Additional Include Directories” click the “…” button and a dialog should pop up. Again, click the “…” button, navigate to YourOgreRoot/YourBuildDir/sdk/include and select the subfolder “OGRE”. Click ok twice.
  13. Change the Configuration drop-down in the top left to “Debug”
  14. Expand Linker -> General
  15. In the “Additional Library Directories” navigate to YourOgreRoot/YourBuildDir/sdk/lib and select the subfolder “Debug”.
  16. Go to Linker -> Input
  17. In “Additional Dependencies” add “OgreMain_d.lib”.
  18. Change the Configuration drop-down in the top left to “Release”
  19. Go to Linker -> General
  20. In the “Additional Library Directories” navigate to YourOgreRoot/YourBuildDir/sdk/lib and select the subfolder “Release”.
  21. Go to Linker -> Input
  22. In “Additional Dependencies” add “OgreMain.lib”.
  23. Click ok.
  24. Enter the following code in main.cpp:


    25. #include <Ogre.h>

    int main(int argc, char* argv[])
    {
        Ogre::Root* root = new Ogre::Root("plugins.cfg", "ogre.cfg", "Ogre.log");
        delete root;
        return 0;
    }

  25. In the toolbar at the top next to the green arrow is a drop-down list. Make sure this is set to “Debug”.
  26. Click the green arrow.
  27. Oh no! You got “This application failed to start because OgreMain_d.dll was not found. Re-installing the application may fix this problem”.
  28. Navigate to the location of your Ogre SDK and head to the bin folder, then the debug folder. Copy “OgreMain_d.dll”.
  29. Go to your project directory, there should be a new folder named “Debug” paste “OgreMain_d.dll” in there.
  30. Press the green arrow in Visual Studio again.
  31. Congratulations! You just ran your first Ogre application!

Why did my application crash?

So you’ve managed to get your application to compile, but something is wrong, it crashes when you run it! Here’s a step-by-step process to help you through it:

  1. Make sure your Working Directory (Project -> Properties -> Debugging -> Working Directory) is the same as your Output Directory (Properties -> General). This is a common cause of confusion, because without it set, Visual Studio cannot see any local files. This means it cannot find plugins.cfg or resources.cfg, so you might get resource or DLL not found errors.
  2. Make sure the compiler is set to “Debug” (the drop-down next to the green compile button in the top bar)
  3. The compiler will generate Debug and Release directories according to where and how your Output Directory (Project -> Properties -> General) is set (for example “.\bin\$(ConfigurationName)”). In your Debug folder you should have debug DLLs, and in the release folder you should have release DLLs. Debug DLLs commonly have the suffix _d at the end of the filename. Likewise, check that in your Debug configuration you are linking to Debug libraries with a _d suffix (Properties -> Linker -> Input -> Additional Dependencies).
  4. Run the application through Visual Studio (by clicking the green “Start Debugging” icon in the toolbar). Don’t run it by clicking on the exe.
  5. If something is wrong with your code, usually Visual Studio will point to the line that caused the crash. If this is the case, a yellow arrow pointing directly at the line means that it is that very line which caused the crash. If it is a green arrow, that means Visual Studio could only trace the crash up to that point, and the root of the crash is deeper.
  6. Check your stack trace. This is in a box on the bottom right named “Call Stack”. This shows the last lines the application stepped through before a crash. (Sometimes people will ask for this if you need help with a crash)
  7. Check the Ogre.log file for any abnormal messages like errors. This is generated in your application directory by default. Lines starting with OGRE_EXCEPTION are ones to look out for especially.
  8. Do you have all the required DLLs? Ogre on it’s own requires OgreMain(_d).dll, but there may be other libraries that you are linking to which the application requires. For example, if you’re using any CG shaders, make sure you have cg.dll, AND load the Plugin_CgProgramManager(_d).dll. You may use CEGUI, which requires the following: CEGUIBase(_d).dll, CEGUIExpatParser(_d).dll, CEGUIFalagardWRBase(_d).dll and OgreGUIRenderer(_d).dll. If you’re using OIS for input, you’ll need OIS(_d).dll.
  9. Search the Ogre forums, or Google, to see if anyone has had a similar problem.
  10. Post your problem in the Ogre forums. We’re happy to help. :)

Other things to check:

  • Are the contents of your plugins.cfg and resources.cfg correct? Make sure the paths are correct.
  • Do you have any referenced but undeclared pointers? The compiler is blind to this problem. If you have not initialised the pointer, and try to reference it, the application will crash at runtime. See here.

I get errors when compiling!

error: SomeHeader.h: No such file or directory
The compiler cannot find the header file(s) you specified. If these are library headers that it cannot find, you need to tell Visual Studio where to find them. Go to: Project -> Properties -> C/C++ -> General -> Additional Include Directories and add the include directories where the headers can be found. (In Ogre’s case that would be C:\OgreSDK\include)

fatal error LNK1104: cannot open file “SomeLibrary.lib”
Similarly, Visual Studio cannot find the file you’re trying to link against. Go to: Project -> Properties -> Linker -> General -> Additional Library Directories and add the directory where the library can be found.

error LNK2001: unresolved external symbol
These are a pain for beginners, and they look daunting. What it means is that the compiler cannot find the implementation of a function (.cpp) that was specified in a header file (.h). Your application may build fine, but when the compiler starts to pull all of the application together (linking), it spits out those errors. Almost ALWAYS, this is to do with not linking a certain library. According to what the unresolved external errors are suggesting, is the library that you need to link to. e.g. if it’s a load of Ogre functions, that means you haven’t linked to OgreMain.lib. Go to Project -> Properties -> Linker -> Input -> Additional Dependencies and add it.