/ Generating an iOS XCode Project

OpenSceneGraph

iOS

Generating an iOS XCode Project

What you'll need

 

Simulator or Device

When building for iOS you have to target either the Device or the Simulator. So before running CMake we need to edit the CMakeLists.txt file in the root of the OSG source. Open CMakeLists.txt search for OSG_BUILD_PLATFORM_IPHONE and you should find the following two lines

    OPTION(OSG_BUILD_PLATFORM_IPHONE "Enable IPhoneSDK Device support" OFF)
    OPTION(OSG_BUILD_PLATFORM_IPHONE_SIMULATOR "Enable IPhoneSDK Simulator support" OFF)

Set one of these to ON to buld for that platform then save the file. In the below example we would be building for device

    OPTION(OSG_BUILD_PLATFORM_IPHONE "Enable IPhoneSDK Device support" ON)
    OPTION(OSG_BUILD_PLATFORM_IPHONE_SIMULATOR "Enable IPhoneSDK Simulator support" OFF) 

 

Start CMake

So now we're ready to run CMake, fire it up and set the OSG source folder for the "Where is the source" and "Where to build the binaries" paths. Then hit configure and select XCode for the generator.

 

Platform SDK and Min Version

CMake uses the CMAKE_OSX_SYSROOT variable to know where the iOS sdk is located. OSG will automatically set this to

    /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.1.sdk

If you use a different sdk or your sdk is installed in a different location change CMAKE_OSX_SYSROOT to point to the correct location

You can also specify a different sdk number as the minimum requirement, this is set via the -miphoneos-version-min option in the CMAKE_CXX_FLAGS, by default this is set to 4.0. If using the CMake GUI you may need to tick 'Advanced' in order to see the CMAKE_CXX_FLAGS setting.

 

Specify Static Build

iOS requires that we link to OSG as a static library, so we must specify in CMake that we want OSG configured as a static library. To do this find and set the following options

    DYNAMIC_OPENSCENEGRAPH = OFF
    DYNAMIC_OPENTHREADS = OFF

GLES1 or GLES2

iOS devices from the 3GS onward support GLES1 and GLES2, the later supporting programmable shaders. In order to build one of these we must set the relevant options in CMake.

GLES1

    OSG_GL1_AVAILABLE = OFF
    OSG_GL2_AVAILABLE = OFF
    OSG_GL3_AVAILABLE = OFF
    OSG_GLES1_AVAILABLE = ON
    OSG_GLES2_AVAILABLE = OFF
    OSG_GL_LIBRARY_STATIC = OFF 
    OSG_GL_DISPLAYLISTS_AVAILABLE = OFF
    OSG_GL_MATRICES_AVAILABLE = ON
    OSG_GL_VERTEX_FUNCS_AVAILABLE = ON
    OSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE = ON
    OSG_GL_FIXED_FUNCTION_AVAILABLE  = ON

GLES2

    OSG_GL1_AVAILABLE  = OFF
    OSG_GL2_AVAILABLE = OFF
    OSG_GL3_AVAILABLE = OFF
    OSG_GLES1_AVAILABLE = OFF
    OSG_GLES2_AVAILABLE = ON
    OSG_GL_LIBRARY_STATIC = OFF
    OSG_GL_DISPLAYLISTS_AVAILABLE = OFF
    OSG_GL_MATRICES_AVAILABLE = OFF
    OSG_GL_VERTEX_FUNCS_AVAILABLE = OFF
    OSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE = OFF
    OSG_GL_FIXED_FUNCTION_AVAILABLE = OFF

 

Plugins

This is now the point that you should set any plugin library paths, it is recommended to at least add the freetype plugin for ttf font support. A universal iOS build of the freetype library is avaliable on Stephan Hubers IPhone git hub branch https://github.com/stmh/osg/tree/iphone/IPhone_Project/3rdParty

 

Applications and Examples

Currently OSGs CMake system (and I believe CMake in general) is not able to generate application targets. So it is recommended that you disable the generation of the OSG applications and examples by setting the following options to off.

    BUILD_OSG_APPLICATIONS=OFF
    BUILD_OSG_EXAMPLES=OFF

If you leave either of these on the XCode project will still generate but the targets will produce errors when you try to build them in XCode.

 

Generate the XCode Project

You can now go ahead and 'Generate' your XCode project. Once this is done you should find a OpenSceneGraph.xcodeproj in your OSG source root. 

You can now build OSG via the BUILD_ALL target or build each library individually.

 

Build tips

Once opened you will see there are a lot of plugins, most of which you won't need at first, so it is recommended to create a new aggregate target. This will allow you to build a smaller selection of the targets with a single build command. To do this follow these steps:

-Select OpenSceneGraph project in the Project Navigator on the left

-Select Add new target

-Select "Aggregate" under the "Other" section and name it (I name it MinBuild to indicate it builds only the libs I need)

-Select the target from your targets list then in the 'Build Phases' section select add (+) and select the targets you require

I tend to select the following

    OpenThreads
    osg
    osgUtil
    osgDB
    osgViewer
    osgGA
    osgText
    osgAnimation
    osgdb_osg
    osgdb_serializers_osg  (for .osgt .osgb .osgx files)
    osgdb_serializers_osgAnimation (for osgAnimation in above files)
    osgdb_deprecated_osg (for .osg files)
    osgdb_deprecated_osgAnimation (for osgAnimation in .osg files)
    osgdb_freetype (for .ttf font support with osgText)
    osgdb_imageio (for image loading support)