Chapter Overview

  1. Introduction
    1. What is OpenSG
    2. What is OpenSG not?
    3. Installation
      1. Where to get OpenSG
      2. Installation on Linux
      3. Installation on Cygwin
        1. Installing Necessary Libraries
        2. Configuring
        3. Executing the Tutorials
      4. Installation on a Macintosh PowerPC
      5. Installation on Windows
    4. Making and executing the tutorials
    5. Compilation of Own Applications
      1. Projects on Windows
      2. Projects on Linux
    6. Exercises

Tutorial Overview

Next Chapter: First Appliction

Introduction

What is OpenSG

OpenSG is an Open Source real-time rendering system based on a scenegraph metaphor on top of OpenGL. But

what is the actual difference compared to OpenGL? OpenGL is a very thin layer above the graphics hardware and is designed as a state machine, which means it does not know

anything about the whole scene. It is only aware of the triangle just being calculated and drawn, it

has no knowledge about the past nor the future. Here comes the strength of a scenegraph system into play.

OpenSG stores the whole scene in a graph (now you see where the name comes from) and thus can optimize

the way data is passed to the graphics hardware. With that it is possible (and extremly useful) to check if

parts of the scene are not visible, like everything behind the user. The entire rendering for such parts can be

skipped completely, resulting in a great increase of performance depending on the scene.

Of course OpenSG is not the only scenegraph based system. Libraries like OpenSceneGraph, Performer, Open Inventor 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.

What is OpenSG not?

OpenSG is not a full application on it's own, it is a library which can help you developing graphics intensive applications so you do

not need to implement your own scenegraph. Altough OpenSG can do more than displaying graphics on your monitor,

you will in most cases not use OpenSG all alone. Often you will need a VR System, capable of handling your

input devices like a tracker. VRJuggler and Open Tracker are VR Systems

working well together with OpenSG.

Installation

Where to get OpenSG

There are three different possibilites to choose from:

  • Download a binary installer
  • Download the source code
  • Download the source code via CVS

Binary installers are available for Suse 8.0, Suse 8.1, Redhat 8.0, Windows with Microsoft Visual Studio 2002/2003 and Windows with Visual Studio 6 and the

Intel Compiler. If you are using another operating system, this is no option for you, you have to compile OpenSG yourself. If you choose (or have to 'choose')

Option one or two, you can download the latest released version from the OpenSG Download Page.

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 impatient as I am, download the source tarball from the OpenSG

dailybuild page as mentioned above.

Installation on Linux

If you are using one of the major Linux distributions you can download a binary installer from the

OpenSG Download Page. Currently there are precompiled

packages for Suse 8.0, Suse 8.1, as well as Redhat 8.0. The older Suse version is compiled with gcc 2.95.3 and the

others with the new gcc 3.2. You can choose between an optimized and a debug version. The latter on is a whole lot bigger

and not that fast, although the difference is not big enough to make it useless. However the debug version is better for debugging ;-)

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 \ref 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/library and so on.

The default installation path of OpenSG is /usr/local. Of course you can change that by adding

--prefix=/the/path/you/like to 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 installation 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/dbg

You 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".

Installation on Cygwin

Cygwin is a set of little programs that allows you to run UNIX-commands on Windows. You can get it from the Cygwin Homepage. Just download and run the installer. When the list of packages is shown click "View" to go to "Full" alphabetical mode. To compile OpenSG you need the preselected packages and the following ones: bison, flex, make, perl, sed and tar. Cygwin will create an icon on the desktop that opens a standard shell, just like Unix.

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

where a lot of important files lie. You might adjust the path to your current Version (this applies to .NET 2002 and maybe also 2003).

Installing Necessary Libraries

If you have not installed GLUT before you need to do so now. The easiest way is to visit Nate Robins page where you can get his port of GLUT for Win32. Download the precompiled zip file. There is no need to compile it yourself, however if OpenSG is not enough terminal hacking, you can do so, of course ;-). After the download has finished open the zip package and copy the following files to these locations 

//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

Configuring

Unless you are using the old version 5.0 of the Intel compiler you also need to add the following parameter to your configure line: 

./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 does 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 than 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: 

  export PATH="/cygdrive/c/Program Files/Microsoft Visual Studio .NET/Common7/IDE:$PATH"

Note that this should be a Unix/Cygwin path, i.e. using / instead of \ and using /cygdrive/c/ instead of C:.

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

If you omit this parameter, you will most likely get several errors telling you that 'thread data may not have dll interface'.

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 successful 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 <PRE>—with-jpg=/path/to/jpg/library</PRE> etc. options to the configure call.

Executing the Tutorials

Before you can run any OpenSG powered applications you need to add the path where the OpenSG libraries lie to the environment varibales. All these files can be found at 

/usr/local/lib

be careful, this is different from the linux version (i.e. /usr/local/lib/dbg). You can add the path by editing your .bash_profile in your home directory or again by editing your windows environment variables. If you are very lazy and are not concerned about wasting your hard disk space, you can also copy all lib files in the tutorials folder.

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 a Macintosh PowerPC

Installing OpenSG on a Macintosh was, and still is, not a very easy task at all. Currently there is somebody working on a improved port, but unfortunately this port is not finished yet. However, it is possible to run it on a Mac with either some missing features on Mac OS or full features on Linux on Mac.

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 fine, 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 --version.

Anyway, 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))

and replace them with 

    MAKEMAJOR := 3
 
    MAKEMINOR := 80

this will tell OpenSG the correct version of GNU make. You can now continue as normal.

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: http://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!

Installation on Windows

In order to use OpenSG on the Windows platform you need either the Intel compiler for Visual Studio 6 or you need Visual Studio 7 (aka .NET) or above.

If you do not want to use cygwin you should download the binary installer. After installation, the PATH variable is automatically set as needed and you can find the standard tutorials in your start menu. There are ready to use project files for Visual Studio for every tutorial that comes with OpenSG. These tutorials are the ones that shipped with OpenSG ever since, and have nothing to do with the tutorials we develop beginning with the next chapter!

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.

Making and executing the tutorials

The fist thing to do with your fresh installation of OpenSG is most likely to test whether the tutorial programs are working or not. If you just installed the binary version on windows you need only to point and click on start button > OpenSG > Tutorials>…

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 directory

when 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.

Compilation of Own Applications

After compiling and executing your tutorials you are ready to start right off with your first own application! In the next chapter I will introduce a first tutorial where you can get used to some core aspects of OpenSG. But at this point I want to start with some more general words about compiling OpenSG Projects.

Projects on Windows

If you want to save yourself a lot of time and trouble, do not try to start a new project from within Visual Studio. There is a template project file provided. Use this template or simply change the code of an existing tutorial that you will find in the Tutorials folder. Of course all those settings can be done by hand, but you should only do that, if you have no other choice (i.e. extend an existing project with OpenSG Functionality)

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 PassiveWindow which can be integrated seamlessly into any window manager. See section Windows for more on passive windows and/or section Passive Window? for an passive window example application.

Projects on Linux

Often Linux users have more trouble with setting up stuff compared to Mac or Windows. However, this time it is quite easy, if you know what to do. If you are

comfortable with Makefiles you can write your own one or use the sample Makefile I'll provide in the next chapter. This sample assumes that every OpenSG application consists of one file only (which is really sufficient for us right now) and that each .cpp filename is starting with a two digit number like 00framework.cpp. Also those files found will compile into an application with the same name. If you want to or need to write your own makefile you can peek into the sample one, to get an idea what is needed.

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 as `osg-config

—cflags —dbg Base System GLUT QT for the preprocessor flags and as osg-config —libs —dbg Base System GLUT QT` for the linker flags.

Leave out the QT if you didn't configure it.

Exercises

1) Compile OpenSG

Compile the optimized (not debug) version of OpenSG for your platform. GLUT, tif, png and jpg support have to be enabled.

2) Compile the tutorials

Compile all tutorials found in the OpenSG/Tutorials folder. Please notice that these tutorials are not related to

the tutorials I will present throughout theses pages! Execute some (or all) of the tutorials, after compilation has finished.

Tutorial Overview

Next Chapter: First Application

Attachments