Dr Sly's Technical Ramblings

Pre-requisites

A few things are needed before we can begin. I'll point out the Ogre Wiki has a page that may have useful information. The information here is based on the Wiki and my own personal experiences. We start with a fresh machine with Windows 7 and Visual Studio 2015 Community Edition installed.

CMake

CMake is a cross-platform build system. It's a good tool for projects that target different platforms/compilers. With CMake, the project build configuration is defined in configuration files, which CMake uses to generate compiler specific project files targeting any supported platform. It's powerful, great when it works, but does come with a steep learning curve.

We will need CMake to generate the project files to build Ogre3D, visit https://cmake.org/download/ and get the latest version, currently 3.4.1.

DirectX

You will want the DirectX 9 SDK (required for Ogre 1.x), and newer (ie DirectX 11) versions now bundled with the Windows 8.x SDK.

Newer Ogre versions (2.1) may still want the DirectX 9 SDK, read this for more.

Download and install the DirectX 9 SDK (DXSDK_Jun10.exe) from http://www.microsoft.com/en-us/download/details.aspx?id=6812

The DirectX 9 SDK installs itself by default to C:\Program Files (x86)\Microsoft DirectX SDK (June 2010). Remember this location as you will want to reference it from your projects!

If the DirectX 9 SDK installation fails with error code S1023, (which it almost certainly will, and gets me every single time), it is because your system has a newer version of the Visual C++ 2010 Redistributable installed. You need to uninstall all versions of the Visual C++ 2010 Redistributable before installing the June 2010 DirectX 9 SDK, then re-install the most current version of the Visual C++ 2010 Redistributable Package (I didn't bother with that, guess I'll find out if its really needed). See https://support.microsoft.com/en-us/kb/2728613 for more details.

As of Windows 8, DirectX has been rolled into the Windows 8.x SDK. Actually I found in my system already has this installed. Have a look in C:\Program Files (x86)\Windows Kits. My system had three versions v8.0, v8.1 and v10 already installed.

Boost

Boost is an optional dependency. Certain components of Ogre are able to make use of Boost libraries for threading. I'm not entirely sure what advantages there are, if any, to using Boost, but since I have it built already I will enable it. I have covered how to build boost in a previous article.

Build Ogre dependencies

I wish the Ogre Wiki was clearer about the Ogre dependencies. They vary between Ogre version, platform and compiler. For Windows (mscv) users, there is a repository available to download at https://bitbucket.org/cabalistic/ogredeps/downloads, which as far as I can tell is meant for every (recent?) version of Ogre. MinGW users are directed to use a pre-compiled version found elsewhere, though that is most likely due to incompatibilities between Microsoft and gcc compilers. If anyone has any information about Ogre dependencies please leave a comment below.

Now we have the fun stuff (and rants!) out of the way, we can begin. First we need to download and build the Ogre dependencies. Go to https://bitbucket.org/cabalistic/ogredeps/downloads and download the dependencies repository. The file will be called cabalistic-ogredeps-eb18d4651ec7.zip or something similar. Extract the file to a directory of your choice; I store my source in /lib_source/ and build output to /lib_msvc14/

Start the CMake GUI and populate the text boxes:

Where is the source code: C:/lib_source/cabalistic-ogredeps-eb18d4651ec7

Where to build the binaries: C:/lib_msvc14/ogredeps_1_9

Click Configure. CMake will prompt you for the build generator. Select Visual Studio 14 2015 and 'Use default native compilers'.

Click Finish and let CMake will do its magic.

If you get a message "Error in configuration process, project files may be invalid", review the message in the status box at the bottom, and also look in the log file it mentions. In our case the error is due to SDL missing from the dependencies: C:/lib_source/cabalistic-ogredeps-eb18d4651ec7/src/SDL2 is not an existing non-empty directory.

There are two ways to fix this. The easiest way is to not build SDL - according to this post it's not required for Ogre 1.9. You can do this in CMake by unchecking the option OGREDEPS_BUILD_SDL2.

If for some reason you do need SDL, go back to the cabalistic ogredeps downloads page, go to the source section, navigate to ogredeps / SDL2 (you will end up here). Click on the 'zip' link at the top section of the page, this will download a file named SDL-e82bfd942409.zip or similar. You will want to extract this file to your dependencies source directory - in my case /lib_msvc14/ogredeps_1_9/src/ and make sure the top level folder is renamed from SDL-e82bfd942409 to SDL2. The folder structure should look like this screenshot.

I experienced issues building SDL and was forced to give up. Microsoft have made breaking changes to their C runtimes, and the CMake configurations need updating to handle it. The linker complains of unresolved external symbols. I tried adding libraries as suggested in this thread but "it did not work for me". There is a good chance someone has fixed this in a branch of the repository by now, and various forum posts have suggested workarounds. All I can say for sure is previous versions of MSVC worked out of the box.

Back to CMake, you may as well have a look at the list of CMake options, new items wil appear in red. You should see CMake has located various library directories and has options to turn various settings on and off. If you tick the Advanced check box you will see additional options for setting compiler parameters and all sorts of things. I told you CMake was powerful. You can adjust any settings if you wish, but for now let's leave their defaults. Click Configue again.

This time there should be no errors and the message in the status window will end with 'Configuring done'.

Click 'Generate'. This will create OGREDEPS.sln in the destination directory (Where to build the binaries).

Fix conflicting definition of snprintf

Open the solution in Visual Studio. Before we can build the dependencies we need to fix one file in FreeImage.

As of VS 2015, there exists a definition for snprintf. Previous versions of Microsoft's compiler did not. We need to remove any conflicting definitions. Find the following line in tif_config.h:

#define snprintf _snprintf

Change it to:

#if (defined(_MSC_VER) && (_MSC_VER < 1900))
#define snprintf _snprintf
#endif

Now for the moment of truth! Build the solution (F7). Make sure to build both Debug and Release targets. The output status should end with the following:

========== Build: 7 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Now right click on the 'INSTALL' project and choose 'Build' to create the folder structure needed by Ogre. Do this for both Debug and Release targets. You will end up with a folder named ogredeps containing a bin, include and lib folder:

Build Ogre3D

Download the Ogre repository from https://bitbucket.org/sinbad/ogre/downloads. You will want to click on the 'Branches' tab in the downloads section where you can select the branch you want. I chose v1-9 (commit 55e89ae). The download file is named sinbad-ogre-55e89ae88219.zip or similar. Extract the file to a directory of your choice; again I use /lib_source/

Run CMake, as before:

Where is the source code: C:/lib_source/sinbad-ogre-55e89ae88219

Where to build the binaries: C:/lib_msvc14/ogre_1_9

Click Configure and select the Visual Studio 14 2015 generator, then click Finish.

We need to tell CMake the location of the Ogre dependencies we built. Set option OGRE_DEPENDENCIES_DIR to C:/lib_msvc14/ogredeps_1_9/ogredeps, or wherever you happen to have your output from the previous step.

Click Configure again. Before going any further, check the 'Advanced' check box and confirm CMake has correctly picked up locations to all dependencies - DirectX, FreeImage, Freetype, OIS, zlib, zziplib, and boost (if you have elected to use boost).

If using Boost make sure option OGRE_USE_BOOST has been ticked.

If Boost is not detected make sure you have properly set environment variables Boost_DIR and BOOST_ROOT to the location of your Boost build. You will need to re-start CMake after setting environment variables for changes to take effect.

Click Generate. CMake will do it's magic and generate project files for you.

Open the solution OGRE.sln in the destination directory. I found the ALL_BUILD project would cause my system to run out of memory and crash, as Visual Studio tried to build projects in parallel, so build each project (except INSTALL and PACKAGE) one by one, starting with OgreMain. When you get to the Sample projects, build SampleBrowser, which will build all the sample projects as dependencies (no need to build samples one-by-one). Remember to build both Debug and Release configurations.

Dealing with unresolved external symbol __vsnprintf error in Direct3D9 RenderSystem

You might experience linker errors when building the Direct3D9 Renderer, due to Microsoft deprecating support for DxErr lib. If so the fix is to edit the file RenderSystems/Direct3D9/include/OgreD3D9Prerequisites.h

At line 75 comment out 
#include <DxErr.h>

Replace with the following:

#ifdef UNICODE
static std::wstring DXGetErrorDescription(HRESULT hr)
#else
static std::string DXGetErrorDescription(HRESULT hr)
#endif
{
    // First try to see if FormatMessage knows this hr
    const DWORD size = 1024;

#ifdef UNICODE
    WCHAR buffer[size];
    DWORD result = FormatMessageW(FORMAT_MESSAGE_FROM_SYSTEM, nullptr, hr,
#else
    CHAR buffer[size];
    DWORD result = FormatMessageA(FORMAT_MESSAGE_FROM_SYSTEM, nullptr, hr,
#endif
        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), buffer, size, nullptr);

    if (result)
        return buffer;
#ifdef UNICODE
    return std::wstring();
#else
    return std::string();
#endif
}

Final steps

Congratulations, you're nearly done! Build the INSTALL project (Debug and Release targets) to create the appropriate directory structure. A folder sdk will be generated contiaining folders named bin, CMake, include, lib and media:

Lastly, create a new environment variable, OGRE_HOME, pointing to the sdk folder, in my case C:\lib_msvc14\ogre_1_9\sdk

You're all set to create your own 3D graphic projects using this wonderful, open-source graphics engine! Wasn't so bad, was it? Check out the section 'Using Ogre' at http://www.ogre3d.org/tikiwiki/tiki-index.php?page=Home for FAQ's, documentation and tutorials.

Further reading

• Ogre3D thread about Visual Studio 2015
• Using CMake in your Ogre projects
• Ogre Basic Tutorials