This is the readme for the entire OpenThreads/Producer/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 1.1 release.\
The source code is available at {\field{\*\fldinst{HYPERLINK "http://www.openscenegraph.org/"}}{\fldrslt http://www.openscenegraph.org/}}\
Our patches are included in this package.\
\
Also included is a framework for GDAL. You can get the source code and the full GDAL package at {\field{\*\fldinst{HYPERLINK "http://www.gdal.org/"}}{\fldrslt http://www.gdal.org/}}\
\f1\b0 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 and Deployment\
targets. If you do not need this and want to save build time, you should change the architecture option\
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 OpenThreads and \
Producer as well. (Quick tip: You can delete the modified (boldfaced) option by clicking on the - button.)\
\
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. (Volunteers?)\
\
There are two new convenience scripts (ArrangeDMG.sh and FindOSGData.pl) in the Misc section\
of the Xcode section of the source code. These are mainly to help binary distribution. However, if\
you're interested in seeing some command-line Spotlight (mdfind) in action, you can look at the \
FindOSGData.pl script.\
\
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.\
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).\
\
\
\
\f0\b Acknowledgments:
\f1\b0 \
\
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 native Aqua Producer, 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\'9abe (web site design, documentation reviewer and formatter)\
(And for the curious) Eric Wing (Xcode projects and frameworks, patches, documentation)\
\
\
\
\f0\b Installation:
\f1\b0 \
\
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\
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.)\
\
\
\f0\b Running the examples:
\f1\b0 \
\
Now that Producer 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 computer. \
\
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 locations.\
\
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:\
\
YourProgram.app/\
Contents/\
Frameworks/ (all the frameworks you depend on go in here)\
osg.framework\
osgDB.framework\
Producer.framework\
...\
PlugIns/ (the plugins you need go in here)\
osgdb_freetype.so\
...\
Resources/ (the data files you need go in here)\
logo.jpg\
arial.ttf\
model.md2\
...\
\
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:\
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 megabytes.\
\
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 the binaries.\
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. \
\ls3\ilvl0\cf0 {\listtext \'a5 }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. \
{\listtext \'a5 }The -mtune=G4 is has been tested more under Xcode 1.5 than -mtune=G5. \
{\listtext \'a5 }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. \
There is one known serious bug that appears sometimes. With Xcode 2.0 and 2.1, in some cases when you build OpenThreads/Producer/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 native Aqua back-end (AGL based) for Producer continues to improve, but it is not as rigorously tested as the X11 back-end. With the included examples, AGL Producer seems to work well enough. There has been one report of crashing with a dual screen setup using a Radeon 9800 in the release candidate phase which may or may not be fixed by the final OSG release. But if you are experiencing problems and you think the AGL implementation might be suspect, you should try swapping in the X11 back-end for comparison. However, for releasable products, you are strongly discouraged from basing your application around the X11 back-end as there are known limitations and critical bugs in Apple's X11 implementation itself which could potentially derail your entire project. Apple's X11 is only intended to help initial porting to OS X and is not intended as a final destination.\
\
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
\f3\fs22 -fvisibility=hidden
\f1\fs24 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
\f3\fs22 -fvisibility-inlines-hidden
\f1\fs24 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.\
\
\f0\b Misc:
\f1\b0 \
\
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.\
