Setting Up An Application With Visual Studio |
Introduction
This set of instructions will walk you through setting up a Visual Studio C++ project from scratch. An alternative to this tutorial is to use the Ogre Application Wizard instead. This tutorial is still useful if you wish to understand what the Application Wizard does for you. When you have finished this tutorial you will be able to compile a working Ogre Application and you will be ready to start the Basic Tutorials.
Table of contents
Guide for setting up an Ogre application using Visual Studio 2010 (VC10).
Prerequisites
- Visual Studio 2010 must be installed. Express and higher.
- The Ogre SDK version 1.7 or greater must be installed.
- Installing the Ogre SDK: Installing the Ogre SDK
- Build Ogre from source with CMake: CMake Quick Start Guide If you are building Ogre from source, you must build the debug and release targets and execute the Install script for both targets as well. This will create a directory structure that is identical to the binary install structure.
Setting Up an Application for Visual Studio 2010
Environment Variables
Run setx OGRE_HOME path_to_ogre_sdk in a command console (cmd.exe):
Alternatively, create this handy batch script:
setx OGRE_HOME %CD% pause
Save it as OGRE_HOME.bat and put it in the root directory of the Ogre SDK.
Run it, and the OGRE_HOME environment variable points to that directory.
Handy when you switch between several Ogre SDKs.
New Project
Create a new Win32 project (File -> New -> Project):
Make sure that Windows Application is selected and Empty Project is checked:
Tutorial Framework
Download the Ogre Wiki Tutorial Framework.
Add Existing Items to Project:
Select Files:
Project Configuration
Project Properties:
Common Settings
Switching to All Configurations:
General Configuration Properties
Set Character Set to Use Multi-Byte Character Set on the General Configuration Properties page:
Debugging Configuration Properties
Command:
$(OGRE_HOME)\Bin\$(Configuration)\$(ProjectName).exe
Working Directory:
$(OGRE_HOME)\Bin\$(Configuration)
Configuration Properties - C/C++ - General - Additional Include Directories
$(OGRE_HOME)\include $(OGRE_HOME)\include\OIS $(OGRE_HOME)\include\OGRE $(OGRE_HOME)\Samples\Common\include $(OGRE_HOME)\boost
Note: If you are using Ogre >1.9 also add "$(OGRE_HOME)\include\OGRE\Overlay"
Configuration Properties - Linker - General - Additional Library Directories
$(OGRE_HOME)\lib\$(Configuration) $(OGRE_HOME)\boost\lib
Configuration Properties - Build Events - Post-Build Event - Command Line
copy "$(OutDir)\$(TargetFileName)" "$(OGRE_HOME)\Bin\$(Configuration)"
Configuration Specific Settings
Switch configuration to "Active(Debug)".
Configuration Properties - Linker - Input - Additional Dependencies - Debug
Add input libraries for debug:
OgreMain_d.lib OIS_d.lib
Note: If you are using Ogre >1.9, also add "OgreOverlay_d.lib".
Configuration Properties - Linker - Input - Additional Dependencies - Release
Switch configuration from "Active(Debug)" to "Active(Release)".
Add input libraries for release:
OgreMain.lib OIS.lib
Note: If you are using Ogre >1.9, also add " OgreOverlay.lib".
That's it!
You've set up an Ogre project succesfully.
All that remains is to build and run it. ๐
Note: If you are running Ogre 1.9 and are getting a runtime error saying: "Cannot locate resource shadows.glsl in resource group Popular or any...", you have to edit "resources_d.cfg" and "resources.cfg" and add "FileSystem=../../media/materials/programs/GLSL" to the files. See this troubleshooting guide if you can not find the files.
If you are getting errors like: "The program can't start because d3dx9_43.dll (or d3dcompiler_43.dll) is missing from your computer...." try to install the DXSDK_Jun10.exe, if you want to use a DirectX renderer. If you only want to use the OpenGL-renderer, edit the "plugins_d.cfg" and "plugins.cfg" files, and edit out the lines
Plugin=RenderSystem_Direct3D9_d
Plugin=RenderSystem_Direct3D11_d
(Put a # in front of them, or delete them!)
Make sure you optimize your build time with Precompiled headers
ogre.cfg
Render System=Direct3D9 Rendering Subsystem [Direct3D9 Rendering Subsystem] Allow NVPerfHUD=No FSAA=0 Floating-point mode=Fastest Full Screen=No Rendering Device=NVIDIA GeForce FX 5200 VSync=No Video Mode=800 x 600 @ 32-bit colour [OpenGL Rendering Subsystem] Colour Depth=32 Display Frequency=60 FSAA=0 Full Screen=Yes RTT Preferred Mode=FBO VSync=No Video Mode=1024 x 768
Note: If you hear your graphics card squealing when showing the Ogre head, turn Vsync to "yes" in ogre.cfg! Your graphics card will squeal when there are too many frames per second being rendered.
Troubleshooting
If you're still having problems building an application, then check Setting Up An Application to make sure your compiler is set up properly. You can also search the forums. It is likely that another user has already solved a similar problem. You can also look in the Ogre.log file in your 'dist/bin' directory for more detailed information about a failed build. This information can be very helpful when posting to the Help Forum.
This troubleshooting will not be provided in later tutorials. Make sure you get things running smoothly before moving on.
MessageBox Unicode Error
If you are using Visual Studio with unicode support turned on, then you may encounter this error:
error C2664: 'MessageBoxW' : cannot convert parameter 2 from 'const char *' to 'LPCWSTR' Types pointed to are unrelated; conversion requires reinterpret_cast, C-style cast or function-style cast
The problem is that the MessageBox function is expecting unicode input, and we are giving it an ANSI string. To fix this, find the following line:
MessageBox(NULL, e.what(), "An exception has occurred!", MB_OK | MB_IConerror | MB_TASKMODAL);
And change it to this:
MessageBoxA(NULL, e.what(), "An exception has occurred!", MB_OK | MB_IConerror | MB_TASKMODAL);
We are now calling MessageBoxA instead of MessageBox. The reason for this is that MessageBox is automatically either resolved to MessageBoxA (ANSI) or MessageBoxW (Wide/Unicode), depending on the project configuration. We fix the error by explicitly calling the ANSI function.
Missing DLLs or Configuration Files
If your application has missings DLLs or .cfg files, then you probably need to copy them over from the OgreSDK folder.
In Visual Studio, when you build your application in release mode, it puts the release executable in the '\bin\release' folder and the debug executable in the '\bin\debug' folder. You must copy all of the DLL and .cfg files from the OgreSDK into the appropriate folders. You would copy the files from '[OgreSDK]\bin\release' into '\bin\release' in your project. You will also need to edit the resources.cfg file to point to the correct paths. See the next section for more information on this.
Problems With Resources Or Plugins
First, make sure you have 'plugins.cfg' and 'resources.cfg' in the same directory as your exectuable. The 'plugins.cfg' file tells Ogre which rendering libraries are available (Direct3D9, OpenGL, etc.). The 'resources.cfg' file is used to specify the locations of textures, meshes, scripts, and other resources. Both are simple text files. Open them up and make sure they contain the correct paths. Otherwise, you might get errors that look something like this:
Description: ../../Media/packs/OgreCore.zip - error whilst opening archive: Unable to read zip file
If this is the case, then open up 'resources.cfg' and correct the paths and make sure the resource actually exists. Note: You can't use environment variables such as ${OGRE_HOME} in these paths.
IDE Won't Launch Application
One reason this may be happening is that Ogre expects certain files to be in the same directory as the executable. If we do not set the working directory for our IDE to the location of these files, then it won't see that they exist because it expects them to be in the working directory. So we must make sure to get our working directory set up correctly.
Visual Studio
The exact solution will vary based on which version of Visual Studio you are using, but the basic steps should be similar. Right click on your project in the solution explorer (not the solution itself), and go to the properties. Somewhere in the configuration properties should be options for "Debugging". Then look for a field called "Working Directory". This should be set to the location of your executable file.
If you are having trouble figuring out what to put there, try to mimic the "Command" field, which should be in the debugging options. For example, in Visual C++ 2003, the "Command" field should be something like "..\..\bin\$(ConfigurationName)\$(TargetFileName)". For the Working Directory, we need to remove the TargetFileName part. In this case, the working directory would be "..\..\bin\$(ConfigurationName)". The exact string you have to put there may vary based on your version of Visual C++ and your build environment. Be sure to check what the Command field is before doing this. Make sure to change the Working Directory for both the Release and Debug configuration.
In Visual C++ 2005 it will probably be something different entirely. I've found the "..\..\bin\$(ConfigurationName)" directory a good thing to try first, if it still does not work you may have to play with it some, or get help on the Ogre forums.