Chapter Overview
| >What is OpenSG >What is OpenSG not? >Installation >Making and executing the tutorials >Compilation of Own Applications >Exercises |
Of course OpenSG is not the only scenegraph based system. Libraries like Performer, OpenInventor and Java3D, to name a few, are all based on the same idea. As always every system has its own advantages and disadvantages. In case of OpenSG the biggest advantages are the ability to handle a cluster and multithreaded data structures in a very easy and still efficient way. In addition to that it works seamlessly on heterogeneous networks, so multiple computers with different graphic cards can drive one and the same application. Another big advantage is its accessibility which makes it very easy to extend. Compared to the other scenegraph systems mentioned, OpenSG has only few disadvantages. Some have more build-in functionality due to their much earlier date of release, but this will vanish as OpenSG hits version 1.3 and above. In my personal opinion the biggest problem with OpenSG was the lack of a good documentation, because the learning curve was very steep at the beginning. This makes it especially difficult for new users to get started. It is my goal to fight this disadvantage by writing the online tutorial you are reading right now ;-)
Some last words in general : OpenSG runs on various Unix systems as well as on Windows. If you are using Windows you need the Microsoft Visual Studio compiler version 7 or above (i.e. Visual Studio .Net or above), or the Intel compiler version 6 or above. On Unix you only need the gcc compiler (3.x +) and a few libraries like GLUT or Qt and some image libraries which are installed on most Unix systems by default. For more detailed instructions, see Installation
Note that the latest release has been quite a while ago, so a number of features have been added. It is therefore recommended to use a more current version. The most current version is the CVS source, but only slightly older versions are available as source, compiled snapshot and binary installer. OpenSG has a daily build system that checks out the current CVS every night on a number of different platforms, automatically compiles them and creates a binary installer. These can be accessed on the Dailybuild Page.
If you want to change the code and still stay up-to-date, using the CVS source is the best way to do that. Here is how:
Open a terminal and enter the two following commands
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/opensg login
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/opensg co OpenSG
Attention : If you are prompted for a password, just hit enter. As you are downloading from a UNIX Server, you have to pay special attention to the case of the letters. The path must be specified using lowercase characters (i.e. /cvsroot/opensg), where as "co OpenSG" must be specified exactly as it is.
The first command connects you to the SourceForge server, while the second tells the server that you want to download the module called "OpenSG". The parameter "-z3" enables compression during data transfer and is considered optional but useful. The servers of SourceForge are sometimes down (as I personally discovered), so if you get an error message or a timeout again and again it is most likely not your fault. Just try again later or if you are as unpatient as I am, download the source tarball from the OpenSG dailybuild page as mentioned above.
The installation of any of these binary packages is as easy as any other. Just download and install it and there you go!
If you are using any other Linux distribution or if you like to compile things yourself, you have to get the source code. The source code from the CVS is the bleeding edge of the OpenSG library, which has a lot more features compared to the latest official release version 1.2.0. On the other hand it is possible that the CVS version does not work at all. Maybe it does not compile or it runs not stable - so it is your choice, but because of much more features in the CVS version, I would recommend using that version, if you do not mind some compiling.
In either case you should now have a new directory called "OpenSG" or "OpenSG-1.2.0", depending on how you downloaded the source code. Now we need to configure and compile the library. Here is a "default" installation, which is good for most purposes.
If you want to use QT have a look at Appendix B - OpenSG with QT, because you need some different configure options.
cd OpenSG
//replace with your OpenSG folder if necessary
./configure --enable-glut --enable-tif --enable-png --enable-jpg
make
// you need root privileges for that
sudo make install
Attention: Typing make will compile the debug version of OpenSG. If you like the optimized version replace make with "make opt"
The compilation of OpenSG may take quite some time - the author recommends watching an episode of Star Trek The Next Generation (or two if you have a slow computer) ;-)
Warning: Be very careful when writing the --enable-... options! There is no typo checking done on these, so don't be surprised if nothing happens after typing
--enable-tiff --enable-jpeg
Hopefully you finished the compilation without errors. If you had errors during compilation, the reason is a missing library in most cases. Check if you correctly have installed glut and the image libraries. If you have all required libraries already installed and they are not found by the configure script anyway it is possibly because they are not installed on default locations. You can explicitly point to these locations by appending this to your configure command
--with-tif=/path/to/tif/library --with-jpg=/path/to/jpg/libraryand so on.
The default installation path of OpenSG is "/usr/local". Of course you can change that by adding
--prefix=/the/path/you/liketo your configure command.
You can get an overview of all possible options by typing :
./configure --help
In order to run OpenSG powered programs, you have to specify where the library files can found at.
For bash/ksh users this is
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:prefix/lib/{dbg/opt} where prefix is your installation prefix (the default is "/usr/local/"). 'dbg' is used by the debug version and 'opt' by the optimized one. If you were using default parameters during installtion you should type export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/usr/local/lib/dbg If you are using a csh/tcsh shell, the line is nearly the same:
setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/prefix/lib/dbgYou need to set the LD_LIBRARY_PATH every time you open a new terminal! Because that would be very annoying, there is, of course, a better way. Instead of typing that command every time you can add it to your profile file. That file lies within your homefolder and is called ".bash_profile", ".bashrc", ".profile" or ".tcsh_profile" or something similar to that depending on the type of shell and operating system you are using. Please do not miss that dot, it is necessary. This file is sourced every time you open a new shell, so you have to open a new terminal for it to take effect. In the remainder of this document we will refer to this file just as ".profile".
The installation on cygwin is almost indentical to the Linux installation procedure, but there are some different prerequisites. It is recommended to have the Intel or Visual Studio Compiler installed at their default locations (i.e. c:\program files\), otherwise it is possible that the configure script can not find them. In addition to that I supplied the path to some Visual Studio .dll by extending the Windows path variable by :
c:\program files\Microsoft Visual Studio .NET\Common7\IDE
//replace 'Windows' with your Windows base directory (possibly 'WinNT') glut.dll -> C:\Windows\System //again, adjust the path corresponding to your installation //this applies to default installation of VS .NET 2002 glut32.lib -> C:\Program Files\Microsoft Visual Studio .NET\Vc7\lib glut.h -> C:\Program Files\Microsoft Visual Studio .NET\Vc7\include\GL
That should do it, however if you need more information on the installation of GLUT, have a look at Nate Robins Readme file.
If you don't want to write into your System directories you can also put all the supporting libraries into another place, but then you will have to tell the configure script where you put them.
Most likely you will also need the library files for the different image formats. You could search the internet for these libs, there is an easier way. Open the following folder: your_OpenSG_Folder\dist\win. There open the zip package 'supportlibs.zip' and there you will find libjpeg.lib, libpng.lib and tif32.lib - copy these files to the same location as glut32.lib file (i.e. ...\Microsoft Visual Studio .NET\Vc7\lib)
Now you have all the libraries needed for a typical OpenSG installation
./configure [--all-options-you-want] --with-compiler={icl60, icl70, cl.net}
Choose the compiler corresponding to your version of the Intel compiler/Visual Studio.
Note:
OpenSG does not work with the Visual Studio 6 compiler! You can use the VS6 IDE, but you have to have a supported version of the Intel compiler for that. It doesn't work with VS 7 (.Net) and up.
The compiler also needs to know the location of some platform dependent include files and libraries. These can be made accessible by the following commands. I'd recommend adding these to your .profile file, which is useful if you intend to compile the library more that just once. Otherwise just adding them in the shell works, too.
export INCLUDE="C:\Program Files\Microsoft Visual Studio .NET\ Vc7\Include;C:\Program Files\Microsoft Visual Studio.NET\ Vc7\PlatformSDK\Include" export LIB="C:\Program Files\Microsoft Visual Studio .NET\Vc7\Lib;C:\Program Files\Microsoft Visual Studio .NET\Vc7\PlatformSDK\Lib"
Both commands have to be on a single line, they may not contain line breaks.
Note:
Depending on your language version of Windows and also depending on your version of Visual Studio .NET you might have to adjust the path!
This is necessary when you get errors like "The dynamic link library mspdb70.dll could not be found in the specified path ...". The name of library might change, but this is the first one you get on VS.NET.
To resolve this problem you need to add the path where that library resides to your PATH environment variable in your .profile:
Note that this should be a Unix/Cygwin path, i.e. using "/" instead of "\" and using "/cygdrive/c/" instead of "C:".export PATH="/cygdrive/c/Program Files/Microsoft Visual Studio .NET/Common7/IDE:$PATH"
Alternatively you can use the GUI approach described below. In that case you should use the Windows version of the path.
If you are one of the GUI-clickers, you also can add both paths in the environment variables panel found in System Preferences>System>Extended>Environment Variables. (The actual words may differ, as I own only the german Windows version). The following image shows the corresponding window for setting environment variables
Setting up Windows environment variables
If you open a new cygwin bash shell, all Windows environment variables are recognized by cygwin! Note that this does not apply to shells already running.
One last important thing: as on windows some things are quite... well, "different" you will need an additional configure command in nearly all cases
--enable-win-localstorage
Finally,
assuming that you have set the environment variables correctly, here is an example configure call for Visual Studio .NET 2002
./configure --enable-glut --enable-jpg --enable-tif --enable-png
--enable-win-localstorage --with-compiler=cl.net
After a successfull configuration, call 'make' or 'make opt'. Hopefully the compilation process will finish without any errors...
If you put your support libraries some place other than the System directories, you need to add the
--with-jpg=/path/to/jpg/libraryetc. options to the configure call.
/usr/local/lib
Regardless of which variant you choose, you should now be able to make all tutorials and to execute them! Remember if you are calling the complied .exe files from within the cygwin shell, you have to call them by typing './01hello.exe' and NOT '01hello.exe'
If you know about improvements or some additions (for other windows versions than XP) about the installation procedure, please send me an mail. At the moment i have only access to a single, old stupid Windows XP box, so my testing abilities with other Visual Studio versions or different Windows versions are limited.
Installation on Linux/ppc needs a bit extra effort, but the actual problem might be installing Linux itself on a Mac. At least you are rewarded with a fully functional and performant OpenSG. I tried Yellow Dog Linux (YDL) and Gentoo Linux on my Powerbook and the latter also on my G5. In both cases it worked find, after I solved some riddles. However installing Gentoo is not very easy, if you are not an experienced Linux user. In that case I would recommend using YDL. YDL is actually a port of Red Hat, but it is available for the PowerPC architecture only. You can find the distributions at
http://www.yellowdoglinux.com and http://www.gentoo.org
Regardless of which Linux you actually use, you will of course need OpenGL (i.e. Mesa) development packages installed, as well as the GLUT package, if you would like to use it. Furthermore the appropriate packages for the image libraries are needed. You can simply install imagemagick, for example, because all image libraries needed by OpenSG are also installed with imagemagick and furthermore, if you want to build the documentation yourself from source you need it anyway.
However there is still one thing to do before you start compiling, because your system will be identified as powerpc-unknown-linux-gnu.
Well, this is a bit quick and dirty but it works well, so open the "OSGConfig.h" which can be found in your_openg_folder/Source/Base/Base.
// locate the following lines that say // (the are located after the first comment block) #ifndef _OSGCONFIG_H #define _OSGCONFIG_H // and add the following line here #define __linux
Note on Gentoo There is an additional step to take if compiling on a Gentoo based systems. For some reasons, I do not understand, OpenSG will complain about an unknown GNU major version - which is not correct, as this version is 3.80 as supported by OpenSG. You can check this by running
make --versionAnyway, we will simply trick OpenSG again by opening "commonBuildDetect.mk" found in your_opensg_folder/Common. At the end of that file locate the lines that say
MAKEMAJOR := $(strip $(MAKEMAJOR)) MAKEMINOR := $(strip $(MAKEMINOR))
MAKEMAJOR := 3 MAKEMINOR := 80
Your system will now be identified as linux throughout OpenSG. Now, just run the configure and make command as you would normally on Linux based systems. If you are encountering any problems during compilation make sure you have all the needed libraries (and the appropriate devel packages) installed.
If you want to run applications, don't forget do edit your .profile file as explained above for Linux on a PC.
NOTE: If you have just installed a new linux on your Mac, the hardware acceleration of your graphic cards is most likely not activated. I can not explain how to activate it as this is not our concern here, but if you need help, the direct rendering infrastructure page would be a good point to start off: dri.sf.net. This will only help you out if you have an ATI based graphics board (including some other, older chipsets), but not if you have an NVidia card. I am very sorry, but as NVidia develops their own closed source drivers for x86 only, there is currently no way to get 3D hardware acceleration to your Mac!
Notice:
The download page offers two different versions of OpenSG for Windows. One is using the Microsoft's STL and the other is using the STLPort. I would recommend the STLPort in any case, because it is much faster! Especially if you are loading VRML files from disk or you are manipulating big parts of geometry data the STLPort is quite often more than two times faster! The necessary header files are also automatically installed, so you do not have to download it yourself.
If you decide to use STLport, you will also have to add the STLport library stlport_vc7.lib (inluded in the OpenSG distribution) to the list of linked libraries, otherwise you will get many undefined symbol errors involving STL-based classes like vectors and strings.
In all other cases you first have to build the tutorials, but that is as easy as clicking in Windows
cd OpenSG\Tutorials make //after finishing, execute them .\01hello .\02move // and so on
The following picture shows what you should see if you type (assuming you are still in the Tutorials folder):
./10loading Data/tie.wrl
The legendary Tie Fighter loaded from VRML by OpenSG!
If you get an error like
error while loading shared libraries: libOSGSystem.so: cannot open shared object file: No such file or directorywhen you are executing one of the tutorials you should check if you have correctly specified the LD_LIBRARY_PATH or the PATH variable, depending on your platform.
Windows users need not to compile the tutorials on their own as they are precompiled, but my advise is to open one Visual Studio project file and try to compile that tutorial. By doing this you can see if everything is working fine.
When I started writing the online tutorial it was planned to have a MFC example. However this made it not into the tutorial as I am not used to MFC and I had not enough time to work into it, so I decided it would be more useful to all of us, if I focus on other important topics which I am more comfortable with. However, in the next version of this documentation there may be an MFC example... If you want to have a GUI, there still is another possibility: you can use a passive window which can be integrated seamlessly into any window manager. See section Windows for more on passive windows and/or section Passive Window with QT / Plain OpenGL Code for an passive window example application.
If you do not like terminal hacking you can, of course, also use your favorite integrated development environment. I will show you what is necessary to set up an project using kdevelop 3.0. First create a simple new C++ project like shown in the next picture
Setup new simple C++ project
Replace the "hello world" code with your OpenSG program. If you want to try this, before you have any knowledge of OpenSG itself, you can simply copy the contents of some tutorial. Now we need to specify some configure commands - click on "Project" in the menu bar and choose "Project Options". On the left hand side click on "Configure Options". The following image shows what you should see
Project Options
The red circles indicate where you need to make changes. These fields are empty on your screen, but you need to provide quite a lot of arguments here. Ready your copy and paste shortcut...
C/C++ preprocessor flags (CPPFLAGS)
-D_GNU_SOURCE -DQT_CLEAN_NAMESPACE -DOSG_WITH_GLUT -DOSG_WITH_QT -DOSG_WITH_JPG -DOSG_WITH_PNG -D_OSG_HAVE_CONFIGURED_H_ -DQT_NO_XINERAMA -DQT_NO_XRENDER -DQT_NO_XFTFREETYPE -DQT_NO_XKB -DQT_NO_SM_SUPPORT -DQT_NO_IMAGEIO_MNG -DQT_NO_IMAGEIO_JPEG -DQT_NO_STYLE_AQUA -DQT_NO_STYLE_MAC -DQT_NO_STYLE_INTERLACE -DQT_NO_STYLE_COMPACT -use_readonly_const -ftemplate-depth-100 -I/usr/local/include -I/usr/qt/3/include -march=athlon -Wno-deprecated
and
Linker Flags (LDFLAGS)
-L/usr/local/lib/dbg -lOSGWindowGLUT -lOSGSystem -lOSGBase -lglut -lGLU -lGL -lXmu -lXi -lXt -lqt -lpthread -ldl -L/usr/qt/3/lib -L/usr/X11R6/lib
Important Notes: I used (Gentoo) default paths (i.e. -I/ust/qt/3/include) - you possibly have to adjust some values.
These settings are for the current version of OpenSG. To get them for the version you find the command osg-config and call it asosg-config --cflags --dbg Base System GLUT QT
for the preprocessor flags and asosg-config --libs --dbg Base System GLUT QT
for the linker flags. Leave out the QT if you didn't configure it.
Next Chapter : First Application
1.4.3