OpenSceneGraph on Mac OS X
This is the readme for the entire OpenThreads/OpenSceneGraph distribution for the OS
X frameworks and Xcode projects. This readme was originally written for the binary
distribution, but there is a lot of useful information in here so it has also been included
with the source code in the Xcode section. This was sync'd with the OSG 2.2 release.
The source code is available at http://www.openscenegraph.org/
Screencasts of how to install and get going with OSG for Mac OS X can be found here:
Special Notes for Leopard:
.5 for up-to-date information.)
Broken Binary Compatibility:
Apple has broken binary compatibility in a limited way between 10.4 and 10.5 when
using OpenGL and C++. Under 32-bit, the GLenum type was changed from long (in
10.4 and before) to int (in 10.5).
Under 32-bit, sizeof(long) == sizeof(int) == 4-bytes.
(In 64-bit, sizeof(long) == 8-bytes, sizeof(int) == 4-bytes)
So in C 32-bit, binary compatibility is preserved.
But under C++, even though both types are 4-bytes under 32-bits, C++ name mangling
rules treat int and long as fundamentally different types. Thus binary compatibility is
broken if you try linking two pieces of code that use different types for GLenum.
1) If you have a 10.4 SDK (or before) built OSG framework, you cannot build an
application using the 10.5 SDK or you will get strange undefined symbol errors if
GLenum is used. This means don't develop against the 10.5 SDK on Leopard.
2) You cannot use a 10.5 SDK built OSG framework to build an application using the
10.4 SDK, otherwise this will also give you undefined symbol errors. This means don't
develop with 10.5 built OSG frameworks when using the 10.4u SDK on Leopard or
developing on 10.4 itself.
3) If you have a 10.4 SDK built OSG framework and a 10.4 SDK built application that
uses it, this does *not* present a binary compatibility problem and you may be able to
run on 10.5 (ignoring any different compatibility issues).
4) Similarly to #3, if you have a 10.5 SDK built framework and a 10.5 SDK built
application that uses it, this does *not* present a binary compatibility problem and you
may be able to run on 10.4 presuming there are no specific 10.5 dependencies. (But it
is safer to build against the 10.4 SDK if you plan on deploying to 10.4 and use no 10.5
Basically, this means you can't intermix 10.4 and 10.5 frameworks.
You can slip around this problem if you manage to avoid the use of any code that uses
GLenum. And pure C is not affected.
OSG 10.4 and 10.5 SDKs:
Xcode 3.0 introduces formal support for SDKs created by 3rd parties (like us). Since we
now have binary incompatible frameworks, developing binaries for both 10.4 and 10.5
on the same system is a pain. Having a separate OSG 10.4 and 10.5 SDK may help
minimize that pain.
Stay tuned for the SDKs and instructions.
X11 Link problems:
Another common problem developers might experience is:
ld: cycle in dylib re-exports with /usr/X11R6/lib/libGL.dylib
collect2: ld returned 1 exit status
Apple has a posted a Technical Q&A (QA1567) on this entitled "Compiling X11 /
OpenGL applications on Mac OS X v.10.5 Leopard"
Some people have reported a problem similar to this and/or used the solution posted in
this Q&A to resolve a problem building the osgdb_freetype plugin. However, I believe
this is the wrong solution to this specific problem. In the osgdb_freetype case, the
problem was one of two things:
1) The wrong libfreetype.dylib was being used (wrong SDK)
2) The libfreetype.dylib was not found (wrong path)
For #1, the Xcode project was linking to /usr/X11R6/lib, but we should have been linking
to $(SDKROOT)/usr/X11R6/lib. You would normally experience this problem when
compiling against the 10.4u SDK on 10.5.
For #2, the problem was usually experienced by people building against the 10.5 SDK
(on 10.5). The problem here is that Leopard has moved from XFree86.org to X.org and
the path is now /usr/X11/lib instead of X11R6. Within the SDK, there is no X11R6 path,
so the library was not found.
The solution is quite simple and change the link path line to:
-L$(SDKROOT)/usr/X11/lib -L$(SDKROOT)/usr/X11R6/lib in the Other Linker Flags for
the osgdb_freetype plugin.
This is now fixed in the Xcode project in Subversion.
The CMake/OSG build system is still not quite ready for prime time. CMake has some
general Leopard issues and the OS X/CMake community is trying to work through SDK
support issues as the SDKs have become a more prominent part of building on OS X
correctly. Framework support is still lacking in the CMake/OSG build system, though
CMake CVS is gradually adding/fixing this feature to its code base.
OSG for OS X 64-bit is now 64bit ready.
If you are using CMake:
set OSG_WINDOWING_SYSTEM to Cocoa
set OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX to imageio
this will instruct CMake to use the Cocoa backend and the imageio-plugin for images.
The quicktime-plugin (which is not 64bit ready) will be discarded.
If you are using the XCode-projects:
Open the project-settings: use the build configuration "Development 64bit Cocoa" or
"Deployment 64bit Cocoa". This will set
USE_DARWIN_COCOA_IMPLEMENTATION to 1 and compile the cocoa-backend.
Xcode Project Templates:
Xcode 3.0 has moved things around. The old location was:
/Library/Application Support/Apple/Developer Tools/Project Templates/Application
The new scheme is:
Specifying 3.0 will restrict them to only be available in Xcode 3.0, specifying Shared will
make them available to 2.5, 3.0 and beyond.
I believe our templates will work in both, so Shared is a good location:
/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
Also note you may place it in per-user locations, e.g.
~/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
What's New in this release (2.2):
(Sorry, no OS X specific notes.)
Notes for 2.0 release:
OpenThreads now uses Subversion 'externals' to make it look like part of the OSG
Producer has been removed from the distribution. osgViewer is supposed to replace
it. The Mac OS X backend is currently Carbon based.
GDAL has been removed as it is no longer a dependency.
osgviewerCocoa (previously osgsimpleviewerCocoa in CVS) is an example program
demonstrating tight integration between OpenSceneGraph and Cocoa. It
demonstrates many of the things you should consider in building a first-class OS
X application that uses OSG.
Dwarf debugging format
OSG has changed its versioning number scheme. 2.0 is the stable release following
Producer has been removed from the distribution with osgViewer as its intended
GDAL has also been removed from the distribution as it is no longer a dependency.
OSG is in the process to moving to a new CMake based build system. Once the
remaining Mac OS X support needed is implemented in CMake, the Xcode projects will
be removed in favor of the new unified CMake system.
With Leopard on the horizon, the need to deal with 64-bit readiness and deprecated
APIs is becoming more critical. In a nutshell, we need a Cocoa based version of
osgViewer, and the QuickTime plugin needs to be replaced. Currently, there is a new
ImageIO based plugin to assume the image reading/writing duties of the old qt plugin.
We are in need of a QTKit based plugin to assume the movie responsibilities of the old
plugin. And we are in need of volunteers to write the Cocoa osgViewer backend.
Currently, the example osgviewerCocoa demonstrates a lot of similar functionality and
could be used as a reference. However, the example needs to be turned 'inside-out'.
The example is an NSView class that contains OSG classes; the osgViewer needs to
be the opposite where the OSG class needs to contain the NSView class.
Notes for 1.2 release:
1.2 was originally intended as a bug fix release for 1.1 (going for 1.1.1), but OSG broke
ABI again so the number was bumped to 1.2. There are no significant changes to the
Xcode projects or significant OS X specific changes.
Since the 1.1 release, we have learned of serious problems (freezing of the window
manager) on the (Intel) MacBook Pros using osgText. We believe the problem is with a
serious driver bug for ATI in OS X 10.4.7. We believe the bug affects the ATI Radeon
X1600. (You can get this string by calling glGetString(GL_RENDERER) when you have
a valid OpenGL Context. The string returned to us on affected MacBook Pros is "ATI
Radeon X1600 OpenGL Engine".)
Robert Osfield says:
osgText subloads small glyphs one by one rather than the whole image, so I'd
suspect it is this that is broken. There is a path way in osgText::Font for
uploading the whole image at once, which original was specifically implement as
a work around for an Octane driver bug, but for 1.1 I enabled this pathway to be
selectable via an env var to see if OSX users could work around the OSX driver
To set the environmental variable through the shell:
setenv OSG_TEXT_INCREMENTAL_SUBLOADING OFF
If you launch through Xcode, you may also set environment variables. In the Groups &
Files panel, go to the section called "Executables" and expand the disclosure triangle.
Find your application in the list and bring up the Info inspector. Click on the tab called
"Arguments" and there are two tables in the display. The lower table will let you enter
James Hopper suggests another solution that doesn't require you to launch through a
you can set environement variables that work with applications by creating a file
~/.MacOSX/.environment.plist and put them in there. easiest way is to use the
preference pane called RCEnvironment at
For deployed application's, environmental variables are tricker. James Hopper's
suggestion will work, but you obviously need to figure out how to install the .plist to user
accounts. So another solution is to set things directly in your code. You can set
environmental variables in C using putenv or setenv. (Use the man pages for more
To detect the OS X version number, the only API I know of that can do this Gestalt()
which is a Carbon API. (If there are others, please let me know.) The code will look
something like this (untested):
if (Gestalt(gestaltSystemVersion, &MacVersion) == noErr)
// For 10.4.7
if (MacVersion == 0x1047)
// Test for the specific video cards giving problems and set the proper
environment variables if needed.
// I believe you need an initialized GL context to call glGetString (or any GL
command) or will crash.
// If a bad video driver, then call
// For 10.4.8
else if (MacVersion <= 0x1048)
// Do we assume the problem is still broken or do we assume it's fixed?
// By the way, did things work okay in 10.4.6?
Don't forget to link against Carbon (-framework Carbon) if you use Gestalt.
If you are affected by this, please file a bug report at https://bugreport.apple.com. Apple
lives and dies by the bug report system. If anything is to get done, it must be in the bug
reporter. And they keep count of how many people file the same bug, so duplicates are
(Note: We believe this has been fixed in 10.4.8)
Notes for 1.1 release:
We are now distributing Universal Binaries. These binaries were built using Xcode 2.3
and gcc 4.0.1.
The Xcode projects are also set to build as Universal Binaries for both Development
targets. If you do not need this and want to save build time, you should change the
to your desired setting (most likely to $(NATIVE_ARCH)). It is overridden in the top-level
"OpenSceneGraph" project in the Group & Files panel. Don't forget to change
as well. (Quick tip: You can delete the modified (boldfaced) option by clicking on the -
Apple documented the behavior of -Os in the Xcode 2.3 release, so we have changed
the compiler optimizations (back) from -O3 to -Os. The hope was to shrink the binary
size, but it didn't seem to have a large effect. Benchmarking still has not been done.
There are two new convenience scripts (ArrangeDMG.sh and FindOSGData.pl) in the
of the Xcode section of the source code. These are mainly to help binary distribution.
you're interested in seeing some command-line Spotlight (mdfind) in action, you can
look at the
New to Xcode 2.3 is the Dwarf debugging format. It is off by default to retain
compatibility with Xcode
2.1/2.2. However, for your own development you may see drastic improvements in
many things if you
enable it. File size alone shrunk from about 500MB for the frameworks to under 100MB.
And for the
PlugIns, the file size shrunk from about 1GB to about 100MB.
We have stopped maintaining the Xcode 1.5/2.0 projects.
Notes for 1.0 release:
These projects were primarily developed with gcc 4.0.1 under Tiger 10.4.3 using Xcode
2.2. Starting with gcc 4.0, Apple no longer statically links in the C++ runtime. Apple has
made available the g++ 4.0 dynamic runtime for Panther under the 10.3.9 release. To
run under Panther, your system must have this update (or you must recompile the
binaries for your system).
With gcc 4.0, serious bugs have been fixed from gcc 3.3 and new features are available
to us so we have experimented with more aggressive optimizations. For these binaries
we have enabled -O3 optimization and -mtune=G5. We have also enabled
autovectorization. We also enabled -fvisibility-inlines-hidden which is expected to shrink
the binary sizes, but noticed very little difference. (There may be something wrong.) We
have not done the proper benchmarking with these options, so feedback is welcome.
Because of the changes to OSG from the last version and our different optimization
options, we needed to redo the prebinding addresses. (See below) The new addresses
will hopefully have enough wiggle room so future OSG releases might still be able to
use the same addresses if you use compile options that make smaller binaries.
With Apple's announcement of the Intel transition, Xcode 2.1 was released to help
developers prepare for the migration. Unfortunately, Xcode 2.1 projects are
incompatible with previous Xcode versions. So we have included both Xcode 2.0
(should work with 1.5) and Xcode 2.1/2.2 project files. This will likely be our last release
of Xcode 2.0 projects as we move forward. It is also likely our next release will be built
as a Universal Binary (this version is not). Prebinding will be dropped in future when this
happens (because Tiger doesn't really need prebinding any more and Xcode ignores
the option when compiling as Universal).
Many thanks should be given to the people that have helped make these projects
possible and for their contributions to make OSG run well on OS X through the
multiyear run-up to 1.0. I unfortunately don't have a comprehensive list as many
contributions have been submitted directly to OpenSceneGraph, but I wanted to give
mention to these specific people I've had the pleasure of working with in trying to make
this corner of the universe work.
James Hopper (work on Xcode templates, GDAL frameworks)
David Guthrie (various patches, testing, Xcode project compiler options refinement)
Jeremy Bell (original comprehensive discussion on OS X frameworks, patches)
Stephen Travis Pope (provider of the OSG on OS X website)
Markus Stöbe (web site design, documentation reviewer and formatter)
(And for the curious) Eric Wing (Xcode projects and frameworks, patches,
To "Install" the Frameworks, copy the Frameworks inside the
frameworks folder to a standard location.
~/Library/Frameworks (for a single user)
/Library/Frameworks (for system wide installation)
/Network/Library/Frameworks (for those who understand when this should be used)
Or you may place them inside your application bundle e.g.
YourApp.app/Contents/Frameworks (best for distributing your app)
Simply drag and drop the frameworks to the desired location.
To "Install" the osgPlugins, copy the Plugins to one of the following
YourApp.app/Contents/PlugIns (best for distributing your app)
Note that the search order is:
1) Application Bundle
That's it! Just remember to link using -framework instead of -l, e.g.
-framework osg -framework osgUtil -framework OpenThreads
-losg -losgUtil -lOpenThreads
Also be aware that if using the 10.4 Universal SDK, you may have to explicitly set the
Framework search paths (its an option/field in the build settings for your Target) due to
the way Apple modifies the standard search paths when using an SDK. (Please see the
Universal Binaries section.)
Running the examples:
Now that osgViewer supports a native Window manager, we have attempted to provide
double clickable .app bundles. We cheat a little to keep the download size smaller by
symbolically linking the Frameworks, PlugIns, and Resources directories for each .app
bundle instead of giving each its own copy. This allows the apps to find their resources
when trying to run directly from the .dmg without having to copy anything to your
If you copy these examples out of .dmg, be aware that these symbolic links may or may
not be able to find all the dependencies depending on factors such as retaining the
directory structure of the .dmg, copying everything over, or what you installed to system
If you want to build stand-alone, completely self-contained OSG apps that require no
user installation, follow the standard Apple guidelines for Application Bundles. It might
look something like this:
Frameworks/ (all the frameworks you depend on go in here)
PlugIns/ (the plugins you need go in here)
Resources/ (the data files you need go in here)
Some of these examples will run if you double click them, but others will not because
they were written expecting command line arguments. To run these you must run from
the command line. However, you may now use Terminal.app instead of X11.app if you
choose. You would run like:
./osgreflect.app/Contents/MacOS/osgreflect <arguments here>
Also remember that OSG will still respond to standard OSG environmental variables.
These are now obsolete. Prebinding is now disabled. The old addresses were:
OpenThreads -seg1addr 0x1FF00000
osg -seg1addr 0x1FF10000
osgUtil -seg1addr 0x20230000
osgDB -seg1addr 0x20380000
osgText -seg1addr 0x2040a000
osgParticle -seg1addr 0x20443000
osgGA -seg1addr 0x2049a000
osgIntrospection -seg1addr 0x204fd000
osgSim -seg1addr 0x205f4000
osgFX -seg1addr 0x20690000
osgViweer -seg1addr 0x20700000
gdal -seg1addr 0x207d0000
osgTerrain -seg1addr 0x20c40000
The Xcode Projects are now included as part of the official OpenSceneGraph
Xcode 2.1+ projects have the extension .xcodeproj.
Xcode 2.0 and below have the extension .xcode (no longer maintained)
We have included a "New Project" template for OpenSceneGraph projects. We
recommend you place the "OSG Application" folder into either:
Xcode 2.4 and before:
/Library/Application Support/Apple/Developer Tools/Project Templates/Appllcation (for
~/Library/Application Support/Apple/Developer Tools/Project Templates/Appllcation (for
/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
(both 2.5 and 3.0)
/Library/Application Support/Developer/3.0/Xcode/Project Templates/Application (3.0
/Library/Application Support/Developer/2.5/Xcode/Project Templates/Application (2.5
~/Library/Application Support/Developer/Shared/Xcode/Project Templates/Application
(both 2.5 and 3.0)
~/Library/Application Support/Developer/3.0/Xcode/Project Templates/Application (3.0
~/Library/Application Support/Developer/2.5/Xcode/Project Templates/Application (2.5
After doing this, when doing a File->New Project, you will see "OSG Application" under
the Application category. Selecting this will create a simple OSG project with some
sample source code already in place which currently renders 2 colored tetrahedrons.
All the OSG related frameworks are listed already, though gdal and osgTerrain are not
checked by default. To link against them, you must check their checkboxes to enable
them. Feel free to uncheck or remove frameworks you don't need.
The OSGTemplate target defines __USE_OSX_AGL_IMPLEMENTATION__ as a
Preprocessor macro already for you.
A prefix header file has been included which lists all the OSG headers. This will take
some additional time to compile your first time. If you don't need all the headers, you
may remove them as you see fit.
You are encouraged to setup a "Copy Files Build Phase" for your project to
automatically bundle the OSG frameworks and PlugIns. (And of course, use the "Bundle
Resources" to include your Resources. We did not set this up automatically for you
because if you use the development frameworks, they can be several hundred
To learn more about Framework bundling, a good demonstration video and sample
project exists here:
Finally, there may still be issues with Zerolink. If you have problems seeing the sample
code render an image, try rerunning the program or try disabling zerolink.
The binaries are built using gcc 4.0.1 under Tiger 10.4.7. These binaries also will run
under Panther 10.3.9 (which has the needed C++ runtime library).
Remember that the C++ ABI breaks with every new version of gcc. This generally
means you shouldn't mix and match C++ code built under different versions of gcc
unless you know what you're doing. The promise of gcc 4.0 is that the ABI will finally be
stable and this problem will go away in the future. It is highly recommended that you use
gcc 4.0 if possible. (There are also many additional reasons to use gcc 4.0 separate
from this issue.) If you are running under Panther and must write new code that links to
OpenSceneGraph, you might have problems (unverified) since Panther's default
compiler is gcc 3.3 and not 4.0. It is highly recommended that you do your development
work and building in Tiger under gcc 4.0 and then simply test and reuse the same
binaries from Tiger which will avoid the ABI issues with gcc 3.3. If this is not possible for
you to do, or must support older gcc versions, you will need to recompile all the osg
frameworks with your targeted gcc version.
Also keep in mind that the prebinding addresses are finicky. Changing the compiler
version or the build options can change the binary sizes enough to invalidate our
addresses. It is recommended you compile with Xcode 2.1+ and gcc 4.0. If you need to
work on other versions, you may need to redo the addresses yourself. Remember that
versions prior to gcc 3.3 statically link in the C++ runtime which increases the sizes of
If you are compiling under Xcode 1.5 and are using our Xcode 1.5/2.0 projects, there
have been reports of problems I have been unable to reproduce. If you do encounter
these problems, please try the following.
I have more rigorously tested the Deployment build style than the Development build
style so use the Deployment build style. Make sure you are compiling using -Os
or -O0 optimization. -O3 is known to have problems under gcc 3.3.
The -mtune=G4 is has been tested more under Xcode 1.5 than -mtune=G5.
I noticed that for some reason, Xcode has problems compiling the Carbon header with
the OpenThreads framework when autovectorization and precompiled headers
were enabled. You might try disabling precompiled headers if it is not already. If
the problem persists, you may also need to delete the entry that enables
autovectorization. In the Groups and Files panel (left side panel), open the Info
inspector for the project (top item) and click on the Build tab. Scroll down to the
bottom, and remove the autovectorization option.
Be aware, when building you're own Universal Binaries and you use the 10.4 SDK, you
list the search path to the frameworks in the project options. It seems that using any
SDK will cause
the standard places like /Library/Frameworks to not be searched.
There is one known serious bug that appears sometimes. With Xcode 2.0 and 2.1, in
some cases when you build OpenThreads/OSG from scratch, when you run the
examples, they will crash on load. The workaround seems to be to delete just the
OpenThreads framework after everything is built. Then rebuild just the OpenThreads
framework. Bug reports have been filed with Apple, but the root cause remains to be a
mystery. (We have some guesses, but nothing substantial.) I have not yet seen this
issue emerge with Xcode 2.2, so maybe the problem is fixed.
The osgdb_geo plugin is not big endian safe. The Makefile system does not build it for
OS X. We have added it for the Xcode projects, but you probably shouldn't use it unless
you're on Intel.
Do not use the -fvisibility=hidden flag unless you know what you're doing. In some
cases, Xcode 2.2 seems to enable this by default in the project settings. You should
verify your project settings and make sure this is disabled. Among other things, this flag
will hide RTTI information causing dynamic_cast<> operations to fail. Since parts of
OSG are dependent on RTTI, this option should remain off. The flag
-fvisibility-inlines-hidden may be safe to use. (This is actually enabled in our
Xcode projects. If there are problems, please let us know.)
Finally, there may still be issues with Zerolink. In the Project Template, we defer to the
default for this option and in current Xcode versions, the default is on. The OSG Xcode
projects themselves have explicitly disabled Zerolink. In the worst cases, scenes will not
render correctly or the application may crash. The worst thing about this is that the
problems are so strange, you may not realize Zerolink is the problem. To see this for
yourself (we tried in Xcode 2.2), you might try comparing the osgdelaunay example with
and without Zerolink, toggling through all values of 'n'. With Zerolink certain objects do
not even appear and it crashes. So you are probably should disable this to be safe.
However, for the daring, Zerolink does seem to work for some projects though we do
not fully understand the criteria for this. Furthermore, Apple constantly works on
improving this feature so maybe one day it will all just work right.
Included with the OSG Xcode projects are some of the little scripts I used to help put
everything together. The build script might be of interest to those who wish to produce
their own automated nightly builds.
We're still looking for volunteers to help us write a new CMake based build system.
Please contact me
or the list if you are interested in helping implement the thing.
If you are developing with Leopard under the Apple software seed program, some areas
of OpenSceneGraph are not 64-bit ready/clean. If you can help, please contact me.
On a similar note, a Cocoa back end would be very nice (and would avoid most of the
64-bit issues). Nothing on this end is being done currently, but if you have an interest in
implementing such a thing, please contact me.
On the topic of feature requests, another potentially useful thing to have is a osgtext
plugin that can load glyphs rendered by Apple instead of Freetype.
ewing . public - at - gmail (in the commercial domain)