root/OpenSceneGraph/trunk/README.txt @ 13369

Revision 12680, 9.0 kB (checked in by robert, 6 years ago)

Merged the OSG-3.0 branch versions of into svn/trunk.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1Welcome to the OpenSceneGraph (OSG).
2
3For up-to-date information on the project, in-depth details on how to
4compile and run libraries and examples, see the documentation on the
5OpenSceneGraph website:
6
7    http://www.openscenegraph.org
8 
9For support subscribe to our public mailing list:
10
11    http://www.openscenegraph.org/projects/osg/wiki/MailingLists
12
13or forum:
14
15    http://forum.openscenegraph.org/
16
17For the impatient, we've included quick build instructions below, these
18are are broken down is three parts:
19
20  1) General notes on building the OpenSceneGraph
21  2) OSX release notes
22  3) iOS release notes
23
24If details below are not sufficient then head over to the openscenegraph.org
25to the Documentation/GettingStarted and Documentation/PlatformSpecifics sections for
26more indepth instructions.
27
28Robert Osfield.
29Project Lead.
3028th June 2011.
31
32--
33
34Section 1. How to build the OpenSceneGraph
35==========================================
36
37The OpenSceneGraph uses the CMake build system to generate a
38platform-specific build environment.  CMake reads the CMakeLists.txt
39files that you'll find throughout the OpenSceneGraph directories,
40checks for installed dependenciesand then generates the appropriate
41build system.
42
43If you don't already have CMake installed on your system you can grab
44it from http://www.cmake.org, use version 2.4.6 or later.  Details on the
45OpenSceneGraph's CMake build can be found at:
46
47    http://www.openscenegraph.org/projects/osg/wiki/Build/CMake
48
49Under unices (i.e. Linux, IRIX, Solaris, Free-BSD, HP-Ux, AIX, OSX)
50use the cmake or ccmake command-line utils, or use the included tiny
51configure script that'll run cmake for you.  The configure script
52simply runs 'cmake . -DCMAKE_BUILD_TYPE=Release' to ensure that you
53get the best performance from your final libraries/applications.
54 
55    cd OpenSceneGraph
56    ./configure
57    make
58    sudo make install
59 
60Alternatively, you can create an out-of-source build directory and run
61cmake or ccmake from there. The advantage to this approach is that the
62temporary files created by CMake won't clutter the OpenSceneGraph
63source directory, and also makes it possible to have multiple
64independent build targets by creating multiple build directories. In a
65directory alongside the OpenSceneGraph use:
66
67    mkdir build
68    cd build
69    cmake ../OpenSceneGraph -DCMAKE_BUILD_TYPE=Release
70    make
71    sudo make install
72
73Under Windows use the GUI tool CMakeSetup to build your VisualStudio
74files. The following page on our wiki dedicated to the CMake build
75system should help guide you through the process:
76
77    http://www.openscenegraph.org/projects/osg/wiki/Support/PlatformSpecifics/VisualStudio
78
79Under OSX you can either use the CMake build system above, or use the
80Xcode projects that you will find in the OpenSceneGraph/Xcode
81directory. See release notes on OSX CMake build below.
82
83For further details on compilation, installation and platform-specific
84information read "Getting Started" guide:
85
86    http://www.openscenegraph.org/projects/osg/wiki/Support/GettingStarted
87   
88   
89Section 2. Release notes on OSX build, by Eric Sokolowsky, August 5, 2008
90=========================================================================
91
92There are several ways to compile OpenSceneGraph under OSX.  The
93recommended way is to use CMake 2.6 to generate Xcode projects, then use
94Xcode to build the library. The default project will be able to build
95Debug or Release libraries, examples, and sample applications. Here are
96some key settings to consider when using CMake:
97
98BUILD_OSG_EXAMPLES - By default this is turned off. Turn this setting on
99to compile many great example programs.
100
101CMAKE_OSX_ARCHITECTURES - Xcode can create applications, executables,
102libraries, and frameworks that can be run on more than one architecture.
103Use this setting to indicate the architectures on which to build OSG.
104Possibilities include ppc, ppc64, i386, and x86_64. Building OSG using
105either of the 64-bit options (ppc64 and x86_64) has its own caveats
106below.
107
108OSG_BUILD_APPLICATION_BUNDLES - Normally only executable binaries are
109created for the examples and sample applications. Turn this option on if
110you want to create real OSX .app bundles. There are caveats to creating
111.app bundles, see below.
112
113OSG_WINDOWING_SYSTEM - You have the choice to use Carbon or X11 when
114building applications on OSX. Under Leopard and later, X11 applications,
115when started, will automatically launch X11 when needed. However,
116full-screen X11 applications will still show the menu bar at the top of
117the screen. Since many parts of the Carbon user interface are not
11864-bit, X11 is the only supported option for OSX applications compiled
119for ppc64 or x86_64.
120
121There is an Xcode directory in the base of the OSG software
122distribution, but its future is limited, and will be discontinued once
123the CMake project generator completely implements its functionality.
124
125
126APPLICATION BUNDLES (.app bundles)
127
128The example programs when built as application bundles only contain the
129executable file. They do not contain the dependent libraries as would a
130normal bundle, so they are not generally portable to other machines.
131They also do not know where to find plugins. An environmental variable
132OSG_LIBRARY_PATH may be set to point to the location where the plugin
133.so files are located. OSG_FILE_PATH may be set to point to the location
134where data files are located. Setting OSG_FILE_PATH to the
135OpenSceneGraph-Data directory is very useful when testing OSG by running
136the example programs.
137
138Many of the example programs use command-line arguments. When
139double-clicking on an application (or using the equivalent "open"
140command on the command line) only those examples and applications that
141do not require command-line arguments will successfully run. The
142executable file within the .app bundle can be run from the command-line
143if command-line arguments are needed.
144
145
14664-BIT APPLICATION SUPPORT
147
148OpenSceneGraph will not compile successfully when OSG_WINDOWING_SYSTEM is
149Carbon and either x86_64 or ppc64 is selected under CMAKE_OSX_ARCHITECTURES,
150as Carbon is a 32bit only API. A version of the osgviewer library written in
151Cocoa is needed. However, OSG may be compiled under 64-bits if the X11
152windowing system is selected. However, Two parts of the OSG default
153distribution will not work with 64-bit X11: the osgviewerWX example
154program and the osgdb_qt (Quicktime) plugin. These must be removed from
155the Xcode project after Cmake generates it in order to compile with
15664-bit architectures. The lack of the latter means that images such as
157jpeg, tiff, png, and gif will not work, nor will animations dependent on
158Quicktime. A new ImageIO-based plugin is being developed to handle the
159still images, and a QTKit plugin will need to be developed to handle
160animations.
161
162
163Section 3. Release notes on iOS build, by Thomas Hoghart
164=========================================================
165
166* Run CMake with either OSG_BUILD_PLATFORM_IPHONE or OSG_BUILD_PLATFORM_IPHONE_SIMULATOR set:
167  $ mkdir build-iOS ; cd build-iOS
168  $ ccmake -DOSG_BUILD_PLATFORM_IPHONE_SIMULATOR=YES -G Xcode ..
169* Check that CMAKE_OSX_ARCHITECTURE is i386 for the simulator or armv6;armv7 for the device
170* Disable DYNAMIC_OPENSCENEGRAPH, DYNAMIC_OPENTHREADS
171  This will give us the static build we need for iPhone.
172* Disable OSG_GL1_AVAILABLE, OSG_GL2_AVAILABLE, OSG_GL3_AVAILABLE,
173  OSG_GL_DISPLAYLISTS_AVAILABLE, OSG_GL_VERTEX_FUNCS_AVAILABLE
174* Enable OSG_GLES1_AVAILABLE *OR* OSG_GLES2_AVAILABLE
175* Ensure OSG_WINDOWING_SYSTEM is set to IOS
176* Change FREETYPE include and library paths to an iPhone version
177  (OpenFrameworks has one bundled with its distribution)
178* Ensure that CMake_OSX_SYSROOT points to your iOS SDK.
179* Generate the Xcode project
180* Open the Xcode project
181  $ open OpenSceneGraph.xcodeproj
182* Under Sources -> osgDB, select FileUtils.cpp and open the 'Get Info' panel, change File Type
183  to source.cpp.objcpp
184
185Here's an example for the command-line:
186$ cmake -G Xcode \
187-D OSG_BUILD_PLATFORM_IPHONE:BOOL=ON \
188-D CMAKE_CXX_FLAGS:STRING="-ftree-vectorize -fvisibility-inlines-hidden -mno-thumb -arch armv6 -pipe -no-cpp-precomp -miphoneos-version-min=3.1 -mno-thumb" \
189-D BUILD_OSG_APPLICATIONS:BOOL=OFF \
190-D OSG_BUILD_FRAMEWORKS:BOOL=OFF \
191-D OSG_WINDOWING_SYSTEM:STRING=IOS \
192-D OSG_BUILD_PLATFORM_IPHONE:BOOL=ON \
193-D CMAKE_OSX_ARCHITECTURES:STRING="armv6;armv7" \
194-D CMAKE_OSX_SYSROOT:STRING=/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS4.2.sdk \
195-D OSG_GL1_AVAILABLE:BOOL=OFF \
196-D OSG_GL2_AVAILABLE:BOOL=OFF \
197-D OSG_GLES1_AVAILABLE:BOOL=ON \
198-D OSG_GL_DISPLAYLISTS_AVAILABLE:BOOL=OFF \
199-D OSG_GL_FIXED_FUNCTION_AVAILABLE:BOOL=ON \
200-D OSG_GL_LIBRARY_STATIC:BOOL=OFF \
201-D OSG_GL_MATRICES_AVAILABLE:BOOL=ON \
202-D OSG_GL_VERTEX_ARRAY_FUNCS_AVAILABLE:BOOL=ON \
203-D OSG_GL_VERTEX_FUNCS_AVAILABLE:BOOL=OFF \
204-D DYNAMIC_OPENSCENEGRAPH:BOOL=OFF \
205-D DYNAMIC_OPENTHREADS:BOOL=OFF .
206
207
208Known issues:
209* When Linking final app against ive plugin, you need to add -lz to
210  the 'Other linker flags' list.
211* Apps and exes don't get created
212* You can only select Simulator, or Device projects. In the XCode
213  project you will see both types but the sdk they link will
214  be the same.
Note: See TracBrowser for help on using the browser.