Developing for iPhone using openFrameworks and ofxiPhone (2009)

Note: Everytime I mention iPhone, I am in fact referring to iPhone & iPod Touch running OS 2+.

Update 29/03/2009

Just posted a simple example application source code and walk-through which can be found here.

Update 27/03/2009

openFrameworks 006 is now officially released! You can download a fat package for your system from www.openframeworks.cc, mac/linux/windows and now iPhone. I do recommend you keep an eye on the ofxiPhone SVN for updates and fixes.

What is this and what does it do?

ofxiPhone (along with ofxMultitouch & ofxAccelerometer) are addons for openFrameworks 006+ that allow you to develop for iPhone in plain old C/C++ just as you would on a normal desktop (mac, linux, windows). This means using the normal testApp.h, testApp.cpp, main.cpp; setup(), update(), draw(), mousePressed(), ofImage, ofTexture etc. and any other C++ classes you may have created. It also means that you can reuse your exact same code running on your desktop (mac osx, windows, linux) unchanged on the iPhone by just copying across your testApp.h, testApp.cpp, main.cpp and other source or resource files you may be using.

Of course needless to say there are still maaany limitations due to hardware difference. Chances are if you do just copy across your code and resources it may run out of memory or crawl to a halt. The job of ofxiPhone is to just make sure your openFrameworks code compiles and runs, it’s up to you to make sure the iPhone can handle it ;) Just imagine that you are developing with openFrameworks for an old desktop computer that fits in your pocket, with very little memory, a tiny screen, not very powerful cpu, and pretty old graphics card and you’ll get the picture…

Objective C++ – the old and the new, in sweet harmony, let’s come together

If you want to do very iPhone specific stuff like loading nibs, using views, controllers, core animation etc you will still need to delve into Objective C. The beauty of it though, is you can mix Objective C with C++ very easily (called Objective C++). So in your testApp.h you can give your C++ class a property such as UIWindow* window. And from

1
2
3
4
your testApp::setup() you can write:
void testApp::setup() {
window = [[UIApplication sharedApplication] keyWindow];
}

This potentially could get a bit messy so best to use it sparingly (i.e. try to minimize the number of source files which do mix) but it can be done and is essential if you want to communicate between classes of different languages – e.g. if you want to use the normal iPhone UIControls and UIViewControllers, and want them to affect variables or call methods in testApp or any other C++ class. Very powerful stuff and all the apps you see at memo.tv/tags/iphone were created using Objective C++. I’ll post some tuts on that later.

How does it work? Break it down

ofxiPhone – glut replacement and iPhone OS level functionality

Versions 005 and earlier of openFrameworks were built on top of glut and there was no way of changing that without some serious hacking at the core. Glut is very easy to setup and use, and is generally quite cool, but being locked to glut did have its limitations.

Together with Lee Byron, Damian StewartZach Gage (and of course the core OF team Zach, Theo and Arturo) we’ve been working on making the openFrameworks 006+ core non glut dependent. Now there is the ability to externally (without touching the core) remove glut dependency and plug in something else to handle all the OS specific stuff. This is very cool. There already is (or is being developed) a glfw addon, and I’m sure others will follow. To make openFrameworks 006 work on iPhone there is ofxiPhone. ofxiPhone is an addon to openFrameworks 006+ which provides the glut replacement windowing / drawing / loop / event management / general OS functionality etc.

ofxMultitouch – handling multitouch

In addition to ofxiPhone, you will also need ofxMultitouch addon. This is a general cross-platform interface defintion for handling multitouch capabilities. It does not have any multi-touch implementation itself, it simply provides an interface for any multitouch device to use. The goal being if you write multitouch code for the iPhone using ofxMultitouch, you can use the exact same application code for a multitouch table, or lemur or any other multitouch device where someone has adopted the ofxMultitouch interface. The iPhone specific ofxMultitouch implementation is in the ofxiPhone addon.

ofxAccelerometer – handling accelerometer data

If you want to use the iPhone’s accelerometer, you will want ofxAccelerometer addon. Similar to ofxMultitouch, this is a general cross-platform interface definition for reading accelerometer data, calculating orientation direction and matrix etc. The iPhone specific implementation is in the ofxiPhone addon. If and when someone wraps up the Apple Sudden Motion Sensor library with ofxAccelerometer, you can run the same app code on an iPhone and on a macbook and the app will respond to the accelerometer the same way.

openFrameworks dependencies

openFrameworks uses other opensources libraries to handle various tasks. Luckily they can be/have been compiled/ported to iPhone and can be included during compiling & linking. Currently these are gluiPhonefreeimageand freetype.

If you download the iPhone FAT from www.openframeworks.cc this will have all the necessary libs in it. Alternatively Robert Carlsen has a great tutorial on how to build these libs for iPhone if you are interested.

Setup

So to recap you will need

  • openFrameworks 006. There is no special version of openFrameworks for iPhone. The version
    of openFrameworks you need is the same as used for desktop (minimum v006). You can
    download it from www.openframeworks.cc.
  • ofxiPhone – This is what enables you to create a functioning app on iPhone and is essential.
  • ofxMultitouch – this contains the multitouch interface definition and is essential (even if you don’t want to use multitouch functionality, you can disable it).
  • ofxAccelerometer – this is not essential, but if you want to use accelerometer data you will need it.
  • iPhone versions of the libraries that openFrameworks uses (gluiPhonefreeimage and freetype).
  • An XCode project setup with all the right stuff. (You can of course create your own xcode project but it’s way quicker to just duplicate an existing project, rename and go straight into messing about).

The folder structure you need is identical to that of a normal openFrameworks setup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
some_folder_of_your_choice
addons
ofxiPhone
ofxMultitouch
ofxAccelerometer
place other addons here, e.g.
ofxVectorMath
ofxMSASpline
desktop addons should work on iPhone too (depending on what they do)
apps
examples
place your apps in folders here. e.g:
My Project 1
My Project 2
or create folders here. e.g:
My Work
and place app folders in here. e.g.
My Project 1
My Project 2
libs
freeimage (headers + iphone lib for freeimage)
freetype (headers + iphone lib for freetype)
gluiphone (headers + iphone lib for gluiphone)
openframeworks (this is the normal openframeworks codebase)

There are a couple of example projects included in the zip. Most of these are standard openFrameworks examples and do not show any iPhone specific usage (multitouch or accelerometer). They just show a normal testApp working on iPhone (at the moment key events are ignored and first finger events are sent as mouse messages for backwards compatibility).

There is also a Touch+Accel example. This does use multitouch and accelerometer capabilities. The source code should be commented and (hopefully) pretty self explanatory. I’ll try and get some more documentation on each of the addons up soon.

 

Creating and running an application

Initial Setup

Once you have the above setup, and the examples are working, you can start creating your own applications. Quickest way to start a new project is just duplicate one of the existing project folders. What I do is:

  1. Duplicate an existing folder (e.g. select “iPhone Touch+Accel Example” and press CMD+D)
  2. Rename the new folder e.g. “My Project”
  3. Rename the xcodeproject in the folder. e.g. “My Project.xcodeproj” (this is optional, but makes the “file >> recent projects” and “window >> open projects” more usable)
  4. Delete the “build” folder in “My Project” (this is optional, just saves space).

Customizing

  1. Set the executable name:
    1. Launch your new xcode project
    2. Select “Project” menu >> “Edit Project Settings” (or CMD + ALT + E)
    3. If it isn’t already selected, select the “Build” tab
    4. From the “Configuration” dropdown select “All Configurations”
    5. Scroll down till you see “Packaging >> Product Name” (the default examples will have this set to oF iPhone).
    6. Double-click on that to change it to something you like (this will be the visible name of the application).
  2. In the “My Projects/data” folder change the Icon.png and Default.png. The former is the application icon, the latter is the image you see while the application is being loaded. These files are used and included in the project by default. You can use Photoshop or anything else to just save normal pngs over these. More info can be found in the Apple docs.

Provisioning for running on iPhone

This can be quite straightforward, it can also suck you into a world of pain. I’m not going to go into all possible scenarios but am just going to mention a few tips:

  • Remember to select your Developer Profile in Project Settings >> Build > Code Signing (or Distribution Profile when building the Distribution version).
  • Remember to set the Bundle Identifier in info.plist to whatever you created your Developer Profile with. e.g. com.yourcompany.*
  • Remember to Build >> Clean All Targets and then Build after changing any of the above.

 

Todo

Most of the openframeworks core (and most addons) have now been made cross-platform and iphone compatible, tested and confirmed to be working are:

  • drawing shapes (ofGraphics)
  • handling opengl textures (ofTexture)
  • handling images (ofImage)
  • handling fonts (ofTrueTypeFont, ofBitmapFont)
  • Sound buffers (ofSoundStream)
  • VectorMath (ofxVectorMath)
  • Network communication (ofxNetwork)
  • OSC communication (ofxOsc)
  • OpenCv (ofxOpenCv)
  • ofxMSAFluid
  • ofxMSAPhysics
  • ofxMSAShape3D
  • ofxMSASpline
  • probably loads more

Areas which have not yet been ported are:

  • Video (ofVideoGrabber, ofVideoPlayer), these weren’t possible with OS2.x, hopefully with OS3.0 they will come soon
  • Sound (ofSoundPlayer), this is coming soon (in the meantime you can use Zach Gage’s openAL wrapper
  • OF006 event system and poco (ofEvent). Poco has been compiled for iphone, and there is a working version of openframeworks with poco on iphone, but the official release is coming soon.

ofxiPhone (along with ofxMultitouch & ofxAccelerometer) are addons for openFrameworks 006+ that allow you to develop for iPhone in plain old C/C++ just as you would on a normal desktop (mac, linux, windows).

Related keywords

iphone, open source, openframeworks, tutorial