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:


#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.

For the most part, we haven’t had much to show or talk about since the last post. We’ve been hard at work writing code since our change of plans with TidalEngine, which I’ll explain below. That said, there’s been plenty of interesting stuff going on recently, so here’s a roundup of what we’ve been up to since.

TidalEngine
TidalEngine is being developed alongside Project Utopia. We decided to transform it into a generic game engine that can be reused for other projects. It was a tough move, and has reduced development speed drastically. But hopefully the hard work will pay off.

We designed it to be extensible, using a modular and add-on architecture. It is multi-tiered depending on what you need. At the bottom level is the utilities – math, events, templates etc. which can be used for pretty much any application. Next is the core engine which abstracts graphics input, GUI, physics etc. Standalone it can be used to create a wide range of offline games. It uses a plugin system, allowing dependencies to be hot-swapped. For example, we have an OpenAL and FMOD plugin – either can be loaded at runtime. At the highest level is networking. This is where all the online operations will be handled.

Mobile Gaming
For a long time we have been carefully planning our pursuit of mobile development. Recently we started to put these plans into practice. We bought a brand new 24″ iMac especially for iPhone development. It will be a steep learning curve, as we’re PC junkies, but this is where most of our attention will be focused for the next few months. We plan on developing multiple titles, each increasingly challenging and complex. That’s about all we can say for now; we also put up a new page.

Websites
We have a number of clients in discussions for possible websites, and a couple more which we’re beavering away at. I’m pleased with the positive response we’ve received until now, so fingers crossed! We’re actively trying to expand our portfolio, so if you have a project in mind let us know!

TidalWare.com
Since my last blog post, I also took the opportunity to redesign our own website. It looked fine already, but until I’m 110% happy, I’m not happy. So back to the drawing board it was, and I came up with something even more minimalistic, and a better menu system to squeeze in our increasing number of pages.

Shortly after, I submitted it to CSS Design Yorkshire, and what do you know, it got featured! :D (There’s quite a few, so just search for ‘tidalware’ or ‘June 08, 2009′)

Conclusion
As you can tell, we’re always busy! If you want day-to-day updates of what we’re up to, be sure to follow us on Twitter. In the meantime I will try my best to blog more often. We removed the news page, so now every TidalWare news tidbit will be posted here.