Ogre3D SDK 1.7.3 for Apple iPhone iOS HOWTO

Welcome to my third installment for Ogre3D on the Mac platform. This tutorial will describe the steps to installing the Ogre3D SDK version 1.7.3 Apple iPhone iOS release on Mac OS X. I’ll also go over installing the Ogre Xcode iPhone Template for generating a default iOS project and building the Ogre Samples Browser project. Although this sounds like a lot of information to cover, much of the groundwork was explained in my first guide for Mac OS X Ogre SDK and my second one outlining how to build the Ogre Samples Browser. I highly recommend reading those before continuing any further with these instructions because I won’t discuss installing Xcode, the NVIDIA Cg Toolkit, or CMake. My two prior Ogre tutorials can be found below.

• Guide to Installing Ogre3D on Mac OS X (Xcode + Ogre SDK 1.7.3)
• Building the Ogre3D SDK Samples on Mac OS X

Step 1 – Download & Install Ogre SDK 1.7.3 for iPhone & iOS Dependencies

Much like my OSX Ogre tutorial, I’m sticking to the prebuilt release of the Ogre SDK for iPhone. Perhaps in the future I’ll write up a doc on building the Ogre SDK from source, but now is not the time. First thing is we’ll do is download the Ogre SDK for iPhone. This guide is written for the version 1.7.3 of Ogre3D which is the current release at this time. Visit the Ogre website to download the Ogre 1.7.3 SDK for iPhone. Follow the link for the Ogre iPhone SDK. Download the iPhone SDK to your computer (it’ll be a DMG disk image called OgreSDK_iOS_v1-7-3.dmg) and mount it (double-click it).

After the disk image mounts, a mock iPhone window appears. There is a folder called OgreSDK that you’ll need to copy to your hard drive. This contains [almost] everything you need to build iPhone Ogre apps. In this tutorial we’ll drop the Ogre SDK into the hard drive root. Now if you followed my Ogre Mac OSX tutorial then we’ll have a name conflict because there is already a /OgreSDK, so copy the OgreSDK folder from the iPhone window to somewhere like your Desktop. Rename it to OgreSDK_iOS and move it to /OgreSDK_iOS (i.e. open a Finder window and drag it over to the hard drive root). So now we have the Ogre iOS SDK installed, the next step is to install the Ogre SDK iPhone iOS Dependencies.

The Ogre iOS dependencies DMG file can be found at SourceForge. Follow the ogre-dependencies-mac -> 1.7 path to get to the Ogre iOS precompiled dependencies DMG file. Download Ogre_iOS_4.3_Dependencies_20110411.dmg and mount the disk image. You’ll see a iPhoneDependencies folder. Copy it and paste it inside of the iPhone SDK folder /OgreSDK_iOS.

That’s all there is to getting the Ogre SDK for iPhone set up on Mac OS X. The next task we’ll move on to is building the Ogre iPhone Samples Browser and running it in the iPhone iOS Simulator.

Step 2 – Generate a Xcode Project for the iPhone Samples Browser

Building the Ogre Samples Browser for the iPhone is very similar to how it’s built for OSX. Both procedures utilize CMake to create a new [working] copy of a Xcode project. However, in regards to making a new Xcode iPhone project, we do have to add one extra step to the CMake process, and that’s adding a new boolean name/value property called OGRE_BUILD_PLATFORM_IPHONE.

Fire up CMake. Set the location of the Ogre iOS SDK with the Browse Source button (/OgreSDK_iOS) and set the location of where to build the binaries with the Browse Build button (/OgreSDK_iOS). Click the Configure button, set the project generator as Xcode, and choose Use default native compilers. Once the process has finished you’ll see a lot of red. Click the Add Entry button up top. In the Add Cache Entry dialog box, for the Name field enter OGRE_BUILD_PLATFORM_IPHONE, set the Type to BOOL, and make sure Value is checked, then click OK. Finally, click Configure twice (once after each configuration process completes) and then the Generate button. The new Xcode project OGRE.xcodeproj for building the Ogre iOS SDK Samples Browser is ready to use.

Step 3 – Build the Ogre SDK iPhone Samples Browser Project in Xcode

With our Ogre iOS project in hand we’re ready to build the Samples Browser. The Ogre Xcode project for iPhone is located in the root of your OgreSDK iOS install directory (/OgreSDK_iOS). It’s called OGRE.xcodeproj (same as the OSX version of the project). Launch Xcode and open the project or just double-click the .xcodeproj file. Unlike the OSX project where we had to make some changes to compile without error, the Ogre iPhone project works out of the box without modification. Click the Build and Run icon in the toolbar (or click the Build menu and select Build and Run). It’ll take some time for the Ogre iPhone Project to compile. Once it’s done compiling the iOS Simulator will open and the Ogre iPhone Samples Browser demo will launch.

To the right is a screenshot of one the demo samples from the project. Using the demo from the simulator is somewhat difficult. To return back to the main screen, click on the Hardware menu and select Shake Gesture. Pat yourself on the back, you’ve made your first Ogre iPhone application. Our last task for this tutorial will be to modify the Xcode iPhone project template so we can have a basic framework available for when we want to start new Ogre SDK projects for the iPhone iOS platform.

Note: What we have done is build the iPhone project so it works on the iOS Simulator. If you try to deploy to an actual iPhone device, you’ll receive an error message [Code Sign error: The identity 'iPhone Developer' doesn't match any valid certificate/private key pair in the default keychain]. Deploying your app(s) to an iPhone requires signing up for the Apple iOS Developer Program which costs $99/yr. The alternative would be to jail-break our iPhone, but I wouldn’t recommend that. I don’t have an iPhone so I won’t be able to go into the details of deploying to a physical device, however there are plenty of resources on the Internet that explain the steps. If I do get an iPhone in the future, I’ll revisit this topic and post a follow-up tutorial.

Step 4 – Install & Edit the Ogre Xcode Project Template for iPhone iOS

If you followed my tutorial for the Ogre SDK on Mac OS X then you’ll already have the Ogre Xcode Templates installed and can skip the next two paragraphs. To install the Xcode templates, you’ll need to download and install a package found on SourceForge.

Download the Ogre_Xcode_Templates_20101211.pkg.zip file to your Desktop or some other location on your Mac, extract the Ogre Xcode Templates Package from the zip file, and launch the installer by double-clicking on the package.

On Step 5 of the installer you’ll be asked for the paths to the OSX and iOS Ogre SDK locations. Ignore the OS X portion of the screen and choose the Find Ogre button for the iPhone option. Point to the /OgreSDK_iOS path (or to the location where you decided to install the Ogre SDK for iPhone). Finish the installation by clicking Continue and finally Close.

To edit the Ogre iPhone Xcode template, we need to modify the file project.pbxproj. We’ll need root privileges to do this so we’ll need sudo and it’ll be easier to do it through the Terminal using nano rather than the Text Editor. Open a Terminal window (commonly found under Applications -> Utilities). Issue the following commands.

computer:~ tony$ cd /Library/Application\ Support/Developer/Shared/Xcode/Project\ Templates/Ogre/iPhone\ OS/
computer:~ tony$ cd ___PROJECTNAME___.xcodeproj/
computer:~ tony$ sudo nano project.pbxproj

There are two changes we’ll be making to the to the project.pbxproj settings file, just in many different locations. It’s a good thing nano has search & replace otherwise this could because extremely tedious. To use the search & replace feature,
press ctrl-\ [ Control-Backslash ]

We’re going to search for the string _OGRESDK_ROOT_ and replace it with the location of where our Ogre iOS SDK is installed (/OgreSDK_iOS). So after pressing ctrl-\ [ Control-Backslash ], in the first prompt enter _OGRESDK_ROOT_ and press enter, then enter /OgreSDK_iOS (or wherever you put your Ogre iOS SDK) for the second prompt. You can press the ‘y’ key (Yes) to replace each instance one at a time or press the ‘a’ key (All) to do them all at once. Here are the line numbers that the changes occur on.
[ Lines 43-50, 52-54, 263-272, 276-279, 295-304, 308-311 ]

Next we need to add a linker flag to both our Debug & Release configurations so after compilation our Ogre iPhone program gets linked against a specific dynamic library (otherwise you’ll get linker errors for undefined symbols such as “_inflateInit_” “_inflateEnd” “_inflate” and others). Scroll down to line number 323 (you can press ctrl-c [ Control-C ] to determine what line number you’re on in nano).

Add a new line and enter the text OTHER_LDFLAGS = /usr/lib/libz.dylib; then scroll to line number 335 and a new line and enter that same text again. You can see how the changes look in the screenshot to the right. Save the Ogre Xcode Template project.pbxproj settings file by pressing ctrl-o [ Control-O ]. Exit with ctrl-x [ Control-X ].

Step 5 – Build & Run a Demo Project from the Ogre Xcode iPhone Template

The end of this Ogre iPhone SDK tutorial is here. There’s just one last thing to do – build and run a demo from our Xcode iPhone template. Open Xcode and create a new project, choose Ogre under User Templates, and click on the iPhone OS option. Click the Choose button and give your project a name (e.g. OgreDemo_iPhone). Click the Build and Run button from the toolbar or use the Build menu if you prefer.

If all goes well (which it should) your demo project from the Xcode iPhone template will be running in the iOS iPhone Simulator (as can be seen to the right). It’ll look exactly like the demo project as found in the Mac OS X version (a Green Ogre Head enclosed by the Space Skybox). You can rotate the camera view by click-holding down your mouse on the screen and moving it around. Good job! You’ve built an Ogre iPhone application and viewed it in the iOS Simulator.

In conclusion, you’ve learned how to install the Ogre 1.7.3 SDK for iPhone on Mac OSX and built the Samples Browser that comes with the SDK by using CMake. Expanding upon that you also learned how to install the Ogre Xcode Templates, tweaked the iPhone settings file for your development machine, and built a demo project from that iPhone OS version. Now that you’re familiar with setting up Ogre on a Mac the next thing would be to learn how to make some custom Ogre apps. I recommend checking out the tutorials on the Ogre3D website since you now have a working Ogre development environment.