Starting with Ogre3D on Mac OS X 10.9.2 and Xcode 5.1.1

Comments

Ogre3D is one of the most popular open-source graphics rendering engines. One of the powerful advantages it offers is abstraction of rendering engine. It can run same code ("game") on OpenGL, Direct3D9,Direct3D10 or Direct3D11 by just changing application configuration file. Above all it abstracts very efficiently many of the core game concepts like loading models, composing scenes, working with cameras etc. What attracted me in particular to Ogre is it's portability. Ogre can be compiled and is available as cross-platform SDK, available on Windows, OS X and some Linux distributions. I've got up to speed with Ogre with this excellent book. Even though book says it is platform independent and you can use any c++ compiler you want it is in essence very much tied to Windows and Visual Studio. Ogre has great wiki with a lot of examples and help pages to get you started but I had a ruff first encounter on OS X platform getting SDK and samples even to compile. In essence there are couple of prerequisites before you even compile and information about those is a bit scattered.

My idea here is simple "Hello World" or in this case "Hello Sinbad" example application from ground up. From downloading and installing prerequisites to actually writing and compiling code with Xcode.

At the time of writing current stable SDK version is 1.9. Even though it says stable it would not compile with Xcode because some include paths are not correctly set. It’s probably easy fix but for sake of keeping things simple and because the only good beginner book out there “OGRE 3D 1.7 Beginner's Guide” is using version 1.7 I will use it too. OS X is version 10.9.2 Mavericks with Xcode 5.1.1.

Installing prerequisites

CMake for OS X – Used for compiling SDK and sample code. You can download it here. At the end of the setup you should allow installation to place aliases in /usr/bin because SDK build will use Cmake from .sh scripts and effectively calling “cmake” without absolute path to your /Applications folder where Cmake will be installed.
Nvidia CG Toolkit - Installs Cg framework system wide and can be downloaded here.

Downloading and compiling Ogre3D SDK

Go to ogre3d.org and download OS X SDK version 1.7 or just click here. After downloading and mounting SDK .dmg file you should see content similar as shown on this picture. Simply copy entire OgreSDK to your local folder where you have read and write permissions. Important thing to notice when you are copying SDK locally is that you should not have spaces in your path to “OgreSDK”. In my case I had folder structure something like this: /Users/bbizic/Projects/3D Project/Ogre3D/OgreSDK. This one space in “3D Projects” caused SDK build to fails so beware of that when copying SDK files.

Next step is to compile Ogre SDK. As OS X user I was expecting like with other projects simple ./configre make steps but that’s not how it works here. From Terminal/shell navigate to your OgreSDK folder and execute following command.

cmake -GXcode

After this step navigate to your OgreSDK local folder and open OGRE.xcodeproj. You should see similar structure as this.

I will be using debug version of libraries so make sure from Product –> Edit Scheme debug version was set and as scheme “ALL_BUILD” is checked. After that just click Product –> Build. It will take a while until all the projects are complied.

Notice: Ogre3D uses Boost libraries for threading. If for some reason SDK fails to compile boost libraries as part of the SDK build the reason could be that boost is targeting lover version OS X SDK, namely OS X 10.5. To be able to compile against and for older versions of OS X Xcode/gcc must have copy of OS X SDK either under /Applciations/Xcode.app/Contents/Developer/Platforms/MacOSX.Platform/Developer/SDKs/MacOSX10.5.sdk and/or under /Develper/SDKs/MacOSX10.5.sdk. Let me know if you have problems I will write more details about it.

Sample Hello Sinbad World Example

Finally it’s time to build sample application. Fire up Xcode –> New Project and choose Command Line Tool.

On next screen give some project name and as type choose C++. We could of gone with Cocoa application to make use of built in bundling system but for sake of simplicity we will build only our executable with correct libraries and then we will make use of SampleBrowser application which we built when we first time build the OgreSDK. In runtime Ogre needs to access it’s libraries from correct location and also few configuration files are needed to be properly set up. To avoid the hustle of configuration we will simple replace SampleBrowser executable with our new one.

Place project in folder next to OgreSDK so it will simplify search paths for include and lib files. Once project was created add new C++ file named main.cpp. and place following content in. You can omit my comments.

//
//  main.cpp
//  HelloSinbad
//
//  Created by Bojan Bizic on 12/05/14.
//  Copyright (c) 2014 BojanBizic. All rights reserved.
//

#include "Ogre/ExampleApplication.h"

class Example1 : public ExampleApplication
{
public:
    void createScene()
    {
        // Set the scene's ambient light
        mSceneMgr->setAmbientLight(Ogre::ColourValue(0.5f, 0.5f, 0.5f));
        
        // Create an Entity
        Ogre::Entity* ogreHead = mSceneMgr->createEntity("Head", "ogrehead.mesh");
        
        // Create a SceneNode and attach the Entity to it
        Ogre::SceneNode* headNode = mSceneMgr->getRootSceneNode()->createChildSceneNode("HeadNode");
        headNode->attachObject(ogreHead);
        
        headNode->setPosition(0.0, 0.0, 400.0);
        
        // Create a Light and set its position
        Ogre::Light* light = mSceneMgr->createLight("MainLight");
        light->setPosition(20.0f, 80.0f, 500.0f);
    }
};

int main(void)
{

    // Create application object
    Example1 app;
    
    try
    {
        app.go();
    } catch( Ogre::Exception& e ) {
        std::cerr << "An exception has occured: " << e.getFullDescription().c_str() << std::endl;
    }
    
    return 0;
}

Next step is to configure project settings namely include and library paths. First we need to make Boost happy and disable C++11.

Next, header search paths.

You need to add path to OgreSDK/include , OdreSDK/boost_1_46_1 and in case of our Mac OSX OgreSDK/include/OGRE/OSX otherwise compiler want be able to find macUtils.h file.

Next step, library search paths.

We need OgreSDK/lib/ and OgreSDK/boost_1_46_1/lib.

Framework paths is also need because on Mac OS X Ogre is bundled as framework and should be referenced as such. Picture below shows setting on my system.

In next step switch over to the Build Phases tab and references as show on image below.

If everything was setup correctly as shown above you should be able to compile at this point. Only thing left to do now is to copy our “HelloSinbad” (in my case this is the name of the project) and copy it to OgreSDK/bin/Debug/SampleBrowser/Content/MacOS and start it from there.

Final result

You can open up SampleBrowser app by right clicking on it and then on “Show Package Content” and place your executable in MacOS folder. Double clicking on executable should bring up Ogre configuration window.

Since we are on Mac OS X on available rendering Subsystem shown should be OpenGL. On Windows we would also see options for Direct3D. By clicking on OK button settings are saved in Resources/ogre.cfg file and our Sinbad is finally shown on screen.

That was it. Not so straight forward as on Windows but on other hand not less rewarding. Most of the work lies on setup and deployment of Ogre SDK files. Coding part was pretty simple and short. Writing similar application which loads model, sets up lighting and cameras with lower level abstractions such as OpenGL or Direct3D would involve at least thousand lines of C++ code plus GLSL/HLSL counter parts for Shader pipelines, not to mention problems with portability.

Hope this helps and if you have questions regarding this post please post it in comments bellow I will be more then happy to answer them.