wiki:Tutorial/OpenSG2/Introduction

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 itself is a very thin layer above the graphics hardware and is designed as a state machine. This means it has no knowledge about the whole scene, it is only aware of the triangle just being calculated and drawn, without 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 and CPUs 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 and Mac OS X. If you are using Windows you need the Microsoft Visual Studio compiler version 7 or above (i.e. Visual Studio .Net 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

Right now there is just one choice, but we hope to expand these a bit soon and offer source tarballs as well as binaries.

Note that there has been no release of OpenSG 2.0 yet, so at this point the SVN trunk is your best bet and since a number of people actually use it for their day to day work (the developers among them ;) ) it is pretty stable. If you don't want to continuously upgrade your OpenSG libraries you can pick a fixed revision number and use that until an official release is being made. If you want to stay up-to-date with the latest developments and features, using the SVN source is the best way to do that. Here is how:

Open a terminal and enter the following command

svn co http://www.opensg.org/svn_repo/trunk

This will obtain the sources from the SVN repository and place them in a directory trunk inside the current directory.

As of this writing there are no binary packages of OpenSG 2.0 available, you have to compile it from the sources. To do this you need CMake version 2.6 or later and the boost libraries version 1.33.1 or later. Depending on what features you want or need some additional libraries may be necessary as well. Most of these provide image file loading capabilities for different formats (they are optional, but for many cases you probably want to have them):

  • glut
  • libjpeg
  • libpng
  • libtiff
  • zlib

Some larger packages that provide additional features, but are entirely optional:

Installation on Windows

Building the OpenSG libraries on windows is normally not a big problem thanks to CMake, however it is in general more tedious to get all the dependencies compiled and installed as you can not rely on them to come with the system (as they normally do for e.g. linux distributions). If you do not need OpenSG debug libraries you can get precompiled and packaged libs from the gnuwin32 project, but again these are only linked against the release runtime, so if you need versions that work with the debug runtime you will first have to compile these libraries.

Instructions on for how to do the actual build of OpenSG can be found here.

Installation on Linux

Most of the dependencies are available on any distribution, but make sure that you also have the development packages installed (they are usually named like the library package with an appendend '-dev' or '-devel'):

Instructions on for how to do the actual build of OpenSG can be found here.

Using OpenSG in your own application

After you have run make install or build the INSTALL target from your favorite IDE the OpenSG libraries will be in a lib or lib64 directory below the path you gave as CMAKE_INSTALL_PREFIX (or the default, if you did not specify anything), while the headers are in CMAKE_INSTALL_PREFIX/include/OpenSG. In order to write and compile an application that uses the headers/libraries you need to tell your build system where to find them. If you are using CMake that is generally very easy as OpenSG comes with a FindOpenSG.cmake module that can locate the libs and set up the necessary variables for your project.

On windows there is one additional step you need to take, otherwise the system will not be able to find the OpenSG DLL files. Windows searches for DLLs in a few system directories, the current working directory as well as directories listed in the PATH environment variable. So the easiest way to make sure the DLLs are found is to add the CMAKE_INSTALL_PREFIX/lib directory to the PATH. To do this go to 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"

While you are there, you also should consider adding a new environment variable OSG_LOAD_LIBS and set its value to OSGFileIO;OSGImageFileIO. This makes sure that the OSGFileIO.dll and OSGImageFileIO.dll are always loaded when OpenSG starts up and all the scene and image file formats are available for loading.

Details: Setting OSG_LOAD_LIBS is necessary because the listed libraries provide components that only register themselves with a factory object so there is no direct dependency from the other OpenSG libraries nor the application to these DLLs and the linker decides that they are not used. However, then of course the loaders have no chance to register themselves with the system and are not available to the application. Setting the environment variables always loads the file and image file io libraries, if you want to have more control over which application includes these libraries, you can insert the following calls before the call to osgInit() in the application:

OSG::preloadSharedObject("OSGFileIO");
OSG::preloadSharedObject("OSGImageFileIO");

If you are using a different build system (or an IDE with its own build management) you need to add CMAKE_INSTALL_PREFIX/include to the include file search path and CMAKE_INSTALL_PREFIX/lib to the library search path (see also osg2-config below).

Example CMakeLists.txt

A simple CMakeLists.txt file to set up an application looks like this (it is slightly adapted from Examples/Simple/CMakeLists.standalone.txt):

    CMAKE_MINIMUM_REQUIRED(VERSION 2.6)

    PROJECT(OpenSGApplication)

    # set this to where the FindOpenSG.cmake module is
    SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "/opt/opensg-2.0/usr/share/OpenSG")

    #############################################################################
    # find sources

    # we glob for sources, you can also just list them here as is traditional for CMake
    FILE(GLOB SRCFILES "*.cpp")

    #############################################################################
    # get dependencies

    # OSG_COMPONENTS holds all OpenSG libraries you want to use
    SET(OSG_COMPONENTS OSGBase OSGCluster OSGDrawable OSGFileIO OSGGroup OSGState OSGSystem OSGUtil OSGWindow)

    # These variables collect all dependencies for the application
    SET(DEP_INCLUDE_DIRS)
    SET(DEP_LIBRARY_DIRS)
    SET(DEP_LIBRARIES)

    #############
    #### Collada (optional, depending on how OpenSG was built)

    FIND_PACKAGE(Collada)

    IF(COLLADA_FOUND)
	LIST(APPEND DEP_INCLUDE_DIRS ${COLLADA_INCLUDE_DIRS})
	LIST(APPEND DEP_LIBRARIES ${COLLADA_LIBRARIES})
    ENDIF(COLLADA_FOUND)

    #############
    #### Boost

    SET(Boost_USE_MULTITHREAD ON)
    SET(Boost_STATIC_LIBS OFF)

    IF(COLLADA_FOUND)
	SET(Boost_COMPONENTS filesystem)
	FIND_PACKAGE(Boost COMPONENTS ${Boost_COMPONENTS} REQUIRED)
    ELSE(COLLADA_FOUND)
	FIND_PACKAGE(Boost REQUIRED)
    ENDIF(COLLADA_FOUND)

    FIND_PACKAGE(Boost COMPONENTS ${Boost_COMPONENTS} REQUIRED)

    # with boost 1.35.0 and newer boost filesystem depends on boost system
    IF(Boost_FOUND AND Boost_MINOR_VERSION GREATER "34")
	SET(Boost_COMPONENTS system ${Boost_COMPONENTS})

	FIND_PACKAGE(Boost COMPONENTS ${Boost_COMPONENTS} REQUIRED)
    ENDIF(Boost_FOUND AND Boost_MINOR_VERSION GREATER "34")

    IF(Boost_FOUND)
	LIST(APPEND DEP_INCLUDE_DIRS ${Boost_INCLUDE_DIRS})
	LIST(APPEND DEP_LIBRARIES ${Boost_LIBRARIES})
    ENDIF(Boost_FOUND)

    #############
    #### OpenSG

    FIND_PACKAGE(OpenSG REQUIRED COMPONENTS ${OSG_COMPONENTS})

    #############################################################################
    # build executable

    SET(EXE ${PROJECT_NAME})

    # add include diretories for OpenSG and dependency headers
    INCLUDE_DIRECTORIES(${OpenSG_INCLUDE_DIRS})
    INCLUDE_DIRECTORIES(${DEP_INCLUDE_DIRS})

    # add library search paths for OpenSG and depdency headers
    LINK_DIRECTORIES(${OpenSG_LIBRARY_DIRS})
    LINK_DIRECTORIES(${DEP_LIBRARY_DIRS})

    ADD_EXECUTABLE(${EXE} ${SRC_FILES})

    # link against libraries
    TARGET_LINK_LIBRARIES(${EXE} ${OpenSG_LIBRARIES})
    TARGET_LINK_LIBRARIES(${EXE} ${DEP_LIBRARIES})

osg2-config

During the build OpenSG also writes a small python script osg2-config that you can call with various parameters and it will print information about the libraries just built. This is quite handy to use with e.g. classic Makefiles or while setting up project files to find the right information to put in the various dialogs. The script is installed to CMAKE_INSTALL_PREFIX/bin/osg2-config and is directly executable on linux, on windows you need to call it like this (assuming python is in your PATH):

python osg2-config --help

The two most common options are --cflags and --libs which will print the necessary paths/flags for the compiler and linker respectively. For most options you also should pass the list of OpenSG libraries you want to use (the script will augment that list with more libraries to satisfy dependecies between the OpenSG libs):

python osg2-config --cflags OSGDrawable OSGWindow

python osg2-config --libs OSGDrawable OSGWindow

Take care to pass the same list of libraries to both invocations otherwise you may get inconsistent answers. The --help option also prints a list of OpenSG libraries at the end.

Building and Running the Tutorial programs

This tutorial is accompanied by a number of small programs that demonstrate the system in action and hopefully encourage you to play with it while you learn; the code can be found in Examples/Tutorial. There is a CMakeLists.txt file in the directory as well that should make it relatively straightforward to build the programs:

Building Tutorial programs

  • Create a build directory and change the current dir to it:
cd Examples/Tutorial
mkdir build
cd build
  • Run cmake pointing it to your installation of OpenSG and the boost libraries you used when compiling the libs:
cmake -DOPENSG_ROOT=<CMAKE_INSTALL_PREFIX> -DBOOST_ROOT=<boost> ..
  • This will generate the build system for the tutorial programs which you then can compile:
on Linux
make -jN
on Windows
Open the solution file OpenSGExamplesTutorial.sln that was generated in the build directory and build the BUILD_ALL project.

Running Tutorial programs

To run the tutorial programs you need to make sure the necessary runtime libraries (.so/.dll files) can be found.

on Linux
export LD_LIBRARY_PATH=<CMAKE_INSTALL_PREFIX>/lib:${LD_LIBRARY_PATH}

# or for csh/tcsh:
setenv LD_LIBRARY_PATH <CMAKE_INSTALL_PREFIX>/lib:${LD_LIBRARY_PATH}
on Windows
Add the CMAKE_INSTALL_PREFIX/lib directory to the PATH environment variable (see above).

With these preparations you are ready to run the tutorial programs (make sure to restart your IDE if you use one, so that it can pick up the changes to the environment):

on Linux
./firstapp
on Windows
You should be able to run the programs straight out of the IDE, though it may complain that you can not really debug the program if you are running in release mode. Just running the program should work anyways though.

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 >>
Last modified 7 years ago Last modified on 01/30/10 13:35:47