IMPORTANT: This guide is meant to be used with old releases of Ogre. For Ogre >= 1.10, rather use a CMake based setup.

ee402630.VisualStudio_lg.png

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.

Prerequisites

  • Visual Studio 2008 must be installed. Visual Studio Downloads
  • 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.

Tutorial

Creating a new project

  • Start Visual Studio 2008
  • Create a new project: File | New | Project
  • Under project types select Visual C++ then under Templates select Win32 Project.
  • Navigate to the location in which your project will be located by clicking the Browse button. It should not be in either the SDK directory or in the source files for Ogre.
    VC2008_Window_NewProject
  • Click the OK button and the Win32 Application Wizard will be displayed.
    VC2008 Win32 AppWizard Page 1.jpg
  • Click the Next Button.
  • Select 'Windows Application' and 'Empty project' when prompted for the type of project to create.
    VC2008 Win32 AppWizard Page 2.jpg
  • Click the Finish button.

Creating the directory structure and adding files

Download and extract the Ogre Wiki Tutorial Framework into your project directory and add them to the project.
VC2008 Solution Explorer Default.jpg

  • If you hover over the second button in the Solution Explorer's toolbar, you will see that it says "Show all files" It should not currently be toggled so you should click on it to toggle it. Now you will see this display of Solution Explorer.
    VC2008 Solution Explorer with Folders.jpg

  • Open each of the folders by clicking on the + signs to the left of each folders name.
    VC2008 Solution Explorer Files Not Added.jpg
  • Right click on the each of the files and select Include In Project.
    VC2008 Solution Explorer Files Added.jpg
  • Select File|Save All from the Visual Studio menu.

Setting up the environment

  • Right click on the project OgreTemplate and select properties. The following screen will be displayed.
    VC2008 Property Pages.jpg

The Properties Pages are arranged in a hierarchy.
By default, Visual Studio creates two configurations. The project is created with two configurations: Debug and Release. You will notice in the upper left corner of the last screen shot that the "Debug" configuration is currently the active configuration. You can change which configuration is being shown by selecting the arrow in that drop-down box. There is an additional value in that drop-down box that indicates that you wish to change a property in all configurations called, surprisingly enough, All Configurations.
This tutorial assumes that the operating system environment variable OGRE_HOME has been set up to point to the SDK directory.

  • Select the All Configurations Configuration by selecting the Configuration drop-down box and selecting "All configurations". Set the variables according to the following chart. You should click Apply after each group of properties.
    General | Output Directory          : bin\$(ConfigurationName)
    General | Intermediate Directory    : obj\$(ConfigurationName)
    General | Character Set             : Use Multi-Byte Character Set
    
    Debugging | Command                 : bin\$(ConfigurationName)\$(ProjectName).exe
    Debugging | Working Directory       : bin\$(ConfigurationName)
    Debugging | Environment             : path=$(OGRE_HOME)\Bin\$(ConfigurationName)
    
    C/C++ | General | Additional Include Directories : include;$(OGRE_HOME)\include;$(OGRE_HOME)\include\OIS;$(OGRE_HOME)\include\OGRE;$(OGRE_HOME)\boost
    
    Linker | General | Additional Library Directories : $(OGRE_HOME)\lib\$(ConfigurationName);$(OGRE_HOME)\boost\lib
  • Select the Debug Configuration by selecting the Configuration drop-down box and selecting "Debug". Set the properties according to the following chart.
    Linker | Input | Additional Dependencies            : OgreMain_d.lib OIS_d.lib
    Linker | Debugging | Generate Debug Info            : Yes (/DEBUG)
  • Select the Release Configuration by selecting the Configuration drop-down box and selecting "Release". Set the properties according to the following chart.
    Linker | Input | Additional Dependencies : OgreMain.lib OIS.lib
    Linker | Debugging | Generate Debug Info : No

Building the project

  • Choose the Debug Solution Configuration.
  • Right click on the project OgreTemplate and select Build Project.

There should be no compile or link errors.

Build Output-Debug.jpg
  • Choose the Release Solution Configuration.
  • Right click on the project OgreTemplate and select Build Project.

There should be no compile or link errors.

Build Output-Release.jpg

Make sure you optimize your build time with Precompiled headers

Copying the config files from OGRE_HOME to the project

As a final step we need to copy some additional files that will be needed to run this project. The build steps just performed created a folder in the project folder called bin and underneath that folder two folders called release and debug. Each of these folders acts as the working directory for their respective configurations when Ogre runs. The Ogre framework will be looking in the working directory for some configuration files and they will be slightly different depending on whether a debug or release version is being run. The configuration files that you will need to run each version are located in $(OGRE_HOME)\bin\debug and $(OGRE_HOME)\bin\release. Copy the *.cfg files from the OGRE_HOME directory to the corresponding project directory.

Running the project

  • Run each version of the Project. If it all works correctly, you will the following screen:
    The rendering engine selection screen.

  • Select a rendering subsystem from the select box in the middle of the window and click 'Ok'. You should see the following:
    The tutorial application rendering an empty scene.
  • If not, go back and verify that you entered all the project properties correctly. You are now ready to move on to the Basic Tutorials.

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.

<HR>
Creative Commons Copyright -- Some rights reserved.


THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED.

BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENSE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS.

1. Definitions

  • "Collective Work" means a work, such as a periodical issue, anthology or encyclopedia, in which the Work in its entirety in unmodified form, along with a number of other contributions, constituting separate and independent works in themselves, are assembled into a collective whole. A work that constitutes a Collective Work will not be considered a Derivative Work (as defined below) for the purposes of this License.
  • "Derivative Work" means a work based upon the Work or upon the Work and other pre-existing works, such as a translation, musical arrangement, dramatization, fictionalization, motion picture version, sound recording, art reproduction, abridgment, condensation, or any other form in which the Work may be recast, transformed, or adapted, except that a work that constitutes a Collective Work will not be considered a Derivative Work for the purpose of this License. For the avoidance of doubt, where the Work is a musical composition or sound recording, the synchronization of the Work in timed-relation with a moving image ("synching") will be considered a Derivative Work for the purpose of this License.
  • "Licensor" means the individual or entity that offers the Work under the terms of this License.
  • "Original Author" means the individual or entity who created the Work.
  • "Work" means the copyrightable work of authorship offered under the terms of this License.
  • "You" means an individual or entity exercising rights under this License who has not previously violated the terms of this License with respect to the Work, or who has received express permission from the Licensor to exercise rights under this License despite a previous violation.
  • "License Elements" means the following high-level license attributes as selected by Licensor and indicated in the title of this License: Attribution, ShareAlike.

2. Fair Use Rights

Nothing in this license is intended to reduce, limit, or restrict any rights arising from fair use, first sale or other limitations on the exclusive rights of the copyright owner under copyright law or other applicable laws.

3. License Grant

Subject to the terms and conditions of this License, Licensor hereby grants You a worldwide, royalty-free, non-exclusive, perpetual (for the duration of the applicable copyright) license to exercise the rights in the Work as stated below:

  • to reproduce the Work, to incorporate the Work into one or more Collective Works, and to reproduce the Work as incorporated in the Collective Works;
  • to create and reproduce Derivative Works;
  • to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission the Work including as incorporated in Collective Works;
  • to distribute copies or phonorecords of, display publicly, perform publicly, and perform publicly by means of a digital audio transmission Derivative Works.
  • For the avoidance of doubt, where the work is a musical composition:
    • Performance Royalties Under Blanket Licenses. Licensor waives the exclusive right to collect, whether individually or via a performance rights society (e.g. ASCAP, BMI, SESAC), royalties for the public performance or public digital performance (e.g. webcast) of the Work.
    • Mechanical Rights and Statutory Royalties. Licensor waives the exclusive right to collect, whether individually or via a music rights society or designated agent (e.g. Harry Fox Agency), royalties for any phonorecord You create from the Work ("cover version") and distribute, subject to the compulsory license created by 17 USC Section 115 of the US Copyright Act (or the equivalent in other jurisdictions).
    • Webcasting Rights and Statutory Royalties. For the avoidance of doubt, where the Work is a sound recording, Licensor waives the exclusive right to collect, whether individually or via a performance-rights society (e.g. SoundExchange), royalties for the public digital performance (e.g. webcast) of the Work, subject to the compulsory license created by 17 USC Section 114 of the US Copyright Act (or the equivalent in other jurisdictions).


The above rights may be exercised in all media and formats whether now known or hereafter devised. The above rights include the right to make such modifications as are technically necessary to exercise the rights in other media and formats. All rights not expressly granted by Licensor are hereby reserved.

4. Restrictions

The license granted in Section 3 above is expressly made subject to and limited by the following restrictions:

  • You may distribute, publicly display, publicly perform, or publicly digitally perform the Work only under the terms of this License, and You must include a copy of, or the Uniform Resource Identifier for, this License with every copy or phonorecord of the Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Work that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder. You may not sublicense the Work. You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Work itself to be made subject to the terms of this License. If You create a Collective Work, upon notice from any Licensor You must, to the extent practicable, remove from the Collective Work any credit as required by clause 4(c), as requested. If You create a Derivative Work, upon notice from any Licensor You must, to the extent practicable, remove from the Derivative Work any credit as required by clause 4(c), as requested.
  • You may distribute, publicly display, publicly perform, or publicly digitally perform a Derivative Work only under the terms of this License, a later version of this License with the same License Elements as this License, or a Creative Commons iCommons license that contains the same License Elements as this License (e.g. Attribution-ShareAlike 2.5 Japan). You must include a copy of, or the Uniform Resource Identifier for, this License or other license specified in the previous sentence with every copy or phonorecord of each Derivative Work You distribute, publicly display, publicly perform, or publicly digitally perform. You may not offer or impose any terms on the Derivative Works that alter or restrict the terms of this License or the recipients' exercise of the rights granted hereunder, and You must keep intact all notices that refer to this License and to the disclaimer of warranties. You may not distribute, publicly display, publicly perform, or publicly digitally perform the Derivative Work with any technological measures that control access or use of the Work in a manner inconsistent with the terms of this License Agreement. The above applies to the Derivative Work as incorporated in a Collective Work, but this does not require the Collective Work apart from the Derivative Work itself to be made subject to the terms of this License.
  • If you distribute, publicly display, publicly perform, or publicly digitally perform the Work or any Derivative Works or Collective Works, You must keep intact all copyright notices for the Work and provide, reasonable to the medium or means You are utilizing: (i) the name of the Original Author (or pseudonym, if applicable) if supplied, and/or (ii) if the Original Author and/or Licensor designate another party or parties (e.g. a sponsor institute, publishing entity, journal) for attribution in Licensor's copyright notice, terms of service or by other reasonable means, the name of such party or parties; the title of the Work if supplied; to the extent reasonably practicable, the Uniform Resource Identifier, if any, that Licensor specifies to be associated with the Work, unless such URI does not refer to the copyright notice or licensing information for the Work; and in the case of a Derivative Work, a credit identifying the use of the Work in the Derivative Work (e.g., "French translation of the Work by Original Author," or "Screenplay based on original Work by Original Author"). Such credit may be implemented in any reasonable manner; provided, however, that in the case of a Derivative Work or Collective Work, at a minimum such credit will appear where any other comparable authorship credit appears and in a manner at least as prominent as such other comparable authorship credit.

5. Representations, Warranties and Disclaimer

UNLESS OTHERWISE AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE MATERIALS, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU.

6. Limitation on Liability.

EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

7. Termination

  • This License and the rights granted hereunder will terminate automatically upon any breach by You of the terms of this License. Individuals or entities who have received Derivative Works or Collective Works from You under this License, however, will not have their licenses terminated provided such individuals or entities remain in full compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will survive any termination of this License.
  • Subject to the above terms and conditions, the license granted here is perpetual (for the duration of the applicable copyright in the Work). Notwithstanding the above, Licensor reserves the right to release the Work under different license terms or to stop distributing the Work at any time; provided, however that any such election will not serve to withdraw this License (or any other license that has been, or is required to be, granted under the terms of this License), and this License will continue in full force and effect unless terminated as stated above.

8. Miscellaneous

  • Each time You distribute or publicly digitally perform the Work or a Collective Work, the Licensor offers to the recipient a license to the Work on the same terms and conditions as the license granted to You under this License.
  • Each time You distribute or publicly digitally perform a Derivative Work, Licensor offers to the recipient a license to the original Work on the same terms and conditions as the license granted to You under this License.
  • If any provision of this License is invalid or unenforceable under applicable law, it shall not affect the validity or enforceability of the remainder of the terms of this License, and without further action by the parties to this agreement, such provision shall be reformed to the minimum extent necessary to make such provision valid and enforceable.
  • No term or provision of this License shall be deemed waived and no breach consented to unless such waiver or consent shall be in writing and signed by the party to be charged with such waiver or consent.
  • This License constitutes the entire agreement between the parties with respect to the Work licensed here. There are no understandings, agreements or representations with respect to the Work not specified here. Licensor shall not be bound by any additional provisions that may appear in any communication from You. This License may not be modified without the mutual written agreement of the Licensor and You.