General

I have no idea what OpenSceneGraph is, can you give me a short description?

It is a 3D graphics library for C++ programmers. A SceneGraph library allows you to represent objects in a scene with a graph data structure which allows you to group related objects that share some properties together so you can specify common properties for the whole group in one place. OpenSceneGraph can then be used to automatically manage things like the level of detail necessary to draw the scene faithfully but without unnecessary detail which slows down the graphics hardware drawing the scene.

What is the difference between your Open Scene Graph and the one from www.opensg.org?

They are different scenegraph libraries, although OpenSG also seems to use an "OSG" prefix for their code, which might be source of some confusion. Differences in goals and capabilities between the two:

OpenSceneGraph has support for reading many 3D and image file formats, while OpenSG supports far fewer

OpenSceneGraph is more actively developed (at least, judging by the number of releases of OpenSG) and probably has a more active user community

OpenSG has better support for performing multi-threaded scene graph operations, as this was one of the original design goals

OpenSG has better support for clustered rendering, although building your own support for OpenSceneGraph isn't terribly difficult

Documentation

Are there any books available about OSG?

The books are constantly under revision to keep up with changes in OSG. Purchasing the books helps fund this effort. More OSG books, not just revisions, are planned for the future.

Where is the reference manual for the .osg file format? I searched all the project's "documentation" folders.

There is no documentation (yet) for the scene description language. The OSG source code is the definite reference on the format (UseTheSourceLuke!), specifically the files under the src/osgPlugins/osg directory in the source distribution.

For anyone with knowledge of OpenGL and the OSG classes the .osg format should be readable though.

Are there tutorials available?

Wiki

How can I edit a wiki page?

This wiki requires a login (See Community/WikiLogIn). Note that some pages can only be edited by the Wiki administrator. This includes the main page, project news and all pages in the Downloads section.

How can I add a new wiki-page?

One can add a new page by first creating a wiki link [wiki:mycategory/mynewpage] to the new page. This can be done in the text of another page or in the menu seen at the top right of the window. There is a separate edit option for the menu available, but don't clutter the menu with many small pages. Select an appropriate category for adding a new page. See links to other pages for existing categories.

For wiki formatting see WikiFormatting or have a look at the examples in the SandBox and experiment there.

Building/Installation

Are there binary distributions available?

Yes, but only for Windows. For Linux you will have to build OSG yourself or check if your Linux distribution has packages for OSG. On Mac OS/X you will have to build OSG yourself.

Can I get CVS or Subversion access so I can keep up to date with the latest development sources?

Yes. The OSG sources are available through Subversion. See the documentation on how to set up SVN access to the development version of the OpenSceneGraph

I'm not using MS Visual Studio. Does OpenSceneGraph support other Compilers, like mingw32?

There is a build in the distribution for Cygwin and Mingw, but they are primarily supported by folks on the osg-users mailing list.

Help! VisualStudio won't load the OSG project files

If you're getting the message "This makefile was not generated by Developer Studio", then the .dsp files were somehow saved with Unix style endlines. You can fix this any number of ways. Suggestions include: Open and Save the .dsp in Wordpad, use the cygwin utility unix2dos, or open the daily tarball in Winzip (after checking "TAR File Smart CR/LF conversion" in Options->Configuration->Miscellaneous).

Everything is compiled, but there are linking problems OR When I run my OSG application it crashes

On Linux, try a "make clean", then "make". On Windows do a clean build. This problem is sometimes caused by a change in the api or a project setting/library has been changed. Doing a clean recompile of everything from scratch can fix the problem.

Linking errors are also often caused by omitting libraries in Visual Studio. Go to Project->Settings and under the Link tab check to see that for every .dll you want to use, the equivalent .lib file is listed under "Object/library Modules" For example, in order to link to the core debug library osgd.dll, osgd.lib should be listed. The search path for these libraries is under Tools->Options->Directories.

On Linux you may need to add an entry to /etc/ld.so.conf.d/ and run ldconfig, or set your LD_LIBRARY_PATH to include the location where you installed the OSG libraries.

Functionality/Features

Q 9: Where is the camera class for OpenSceneGraph?

You have three options:

(Recommended) Use osgViewer. The osgviewer application and almost all the example programs demonstrate how to hook up a scene, an osgViewer object and a manipulator that controls the camera in response to user input.

Use osgUtil::SceneView and osg::Matrix.

Make your own class.

How do I render terrain in OSG?

The OpenSceneGraph now has the osgTerrainNodeKit for generation large paged geospatial databases.

=== What can I do to make my editor recognize OSG headers as C++ files? ==

The means depends upon your editor and platform:

VisualStudio: The OSG source includes a file called LANGEXT.DAT in the OSG/VisualStudio directory. Read the instructions there for how to use it.

VIm: can be made to recognize the mode string, "-*-c++-*-", at the beginning of each header file. Start vim. type ":set runtimepath" to see where vim looks for scripts. You can make a file in any of these directories (for example, ~/.vim on Linux). Make the directory if it doesn't already exist, and make a file called scripts.vim in that directory. Here are the contents of that file:

if getline(1) =~ '-*-c++-*-'
set filetype=cpp
endif

Emacs: should recognize the mode string right out of the box.

Nedit: can be told to treat files as C++ based on their location in an include directory

Dev-C++: In Tools/Editor Options/General there is an option "Use Syntax Highlighting". In the box below add ;;. The final line will look like this: c;cpp;h;hpp;;. This will enable syntax highlighting in all files without extension.

=== How do I increase the verbosity of my program for debugging purposes? ==

You can use the OSG_NOTIFY_LEVEL environment variable to specify a certain level of debug info. Here are the levels, from low to high (taken from include/osg/Notify):

ALWAYS
FATAL
WARN
NOTICE
INFO
DEBUG_INFO
DEBUG_FP

XXX The default level is ...

=== How can I contribute to the OpenSceneGraph? ==

Send changes as whole files to the osg-submissions mailing list along with an explanation of the changes. Do not send diffs or copy and paste extracts in emails, these will be simply disgarded, as they are too unreliable for review and merging.

Alternatively you can post changes or submissions under the Community section of this website. This is particularly appropriate for complete new functionality such as NodeKits and plugins. After uploading your things to the website inform the osg-users or osg-submissions list of your entry.

Development - Windows-specific

When I try to save a node to file, OSG crashes. I'm using Windows. OR STL is playing up for me in VisualStudio.

This is a known problem with the Microsoft implementation of STL. The current solution is to use STLport (http://www.stlport.org/) and make sure you have the latest service pack for VS. If problems persist, make sure you clean your original OpenSceneGraph build and recompile from scratch. The next version of VC++ (dot net, version 7) has a fixed STL implementation, so you wont need STLport after that.

I get a lot of warnings along the lines of... warning C4541: 'dynamic_cast' used on polymorphic type 'class osg::Object' with /GR-

You need to enable run-time type identification. For VisualStudio, you can put /GR in the project options. Or find this option in the development environment, click Settings on the Project menu. Then click the C/C++ tab, and click C++ Language in the Category box. There's a checkbox right there for "Enable RTTI".

Problems

Is it possible to render a scene in 2D?

For a code sample have a look at examples/osghud/osghud.cpp. This example creates a subgraph for viewing a 3D scene, and a second subgraph which sits along side it with osg::Projection & osg::MatrixTransform nodes to set up the orthographic views for drawing the 2D scene over the 3D one.

How do I move models around once they are in the scene?

Add the Node in question to an osg::Transform (as a child). This allows you to move your model around the scene by changing the Transform. Take a look at the osgreflect example, which uses an osg::MatrixTransform? to create a mirror image of a model.

How come the mountain in the hanglider demo is completely white with no shading?

There are two likely causes:

1. The plugin to read the .rgb file format (osgdb_rgb) can't be found or wasn't compiled.
You need to compile the rgb plugin.

2. The program can't find the data files it requires (textures).
Make sure that you have downloaded the demo datafiles archive and extracted them. Make sure that the environment variables in the INSTALL file are set correctly, as these tell the viewer where to find the data. As of writing they were OSGHOME, OSGDATA and OSGFILEPATH. To set the environment variables in Windows go to control panel->system->advanced->environment variables.

Why does OSG seem to ignore my near/far clipping planes?

When using osgUtil::SceneView (or the newer osgViewer::Viewer), near and far clipping planes are recomputed on-the-fly based on the current eye point and viewable scene. This is by design to optimize the near/far range of the depth buffer, which might otherwise result in "z-fighting" artifacts if near and far are set to unreasonably small or large values.

If I let OpenSceneGraph calculate my near and far clipping planes, how do I get the computed values?

I am trying to run OpenSceneGraph example programs under Mac OSX, but no window appears! What can I do?

You need to set the following environment variable before launching the program:

tcsh:

setenv DYLD_BIND_AT_LAUNCH 1

bash:

export DYLD_BIND_AT_LAUNCH=1

If you get dyld "can't open library" errors when running OSG programs under OSX, you may also need to set your DYLD_LIBRARY_PATH environment variable to point to the OSG libraries and/or plugins.

Qt and other GUI frameworks have adapters available in the contribs. Is there one for Gnome/GTK+?

Take a look into the OSGEdit sources (http://www.sf.net/projects/osgedit). It contains a GTK Event Adaptor (a C++ class implemented within the OSGEdit application source code that adapts events from GTK+ to the osgGA generic event framework).

Hey, this particle system is cool, but looks strange when I position it in my scene. What's up?

You are probably rotating both the particle systems and the particle emitters. The tranform above the particle system(s) should match your world's (absolute) coordinate frame, or the reference frame that "contains" the particles (for example, an airplane or a car). To transform a particle system inside this reference frame you should transform only the emitters, not the ParticleSystem drawables. If you apply a transform above "fountain.osg" you actually apply a translation/rotation to both emitters and particle systems; to get a correct behavior you should traverse the scene graph and avoid applying the transform to any geodes containing ParticleSystem drawables. (answer courtesy Marco Jez)

I'm having a problem using a PrimitiveSet to represent a single point, OR my geometry seems to dissapear as it gets very far away. What's wrong?

By default the OSG uses small feature culling to cull out objects that occupy less than a predetermined screen size. This is a valuable feature for models with many details which do not contribute to the visual quality of the model when viewed from a distance. You can completely disable small feature culling by changing the cullingMode on osgUtil::SceneView with:

Can I use OSG within an existing renderer?

XXX Split off in separate page

It takes a little work, but it is entirely possible to use OSG within a pre-existing rendering system.

First of all, the central object you should know about is osgUtil::SceneView. This class will manage the OSG specific rendering tasks. If you want to take advantage of OSG's animation capabilities, you will also want to maintain your own FrameStamp object.

Note, just replace rootNode with your actual root node for you OSG models.

NOTE: The call to setComputeNearFarMode is very important. If you don't do this, then OSG will use a different near and far plane when rendering its objects, and they will have different values in the depth-buffer than the rest of your scene. This can lead to very odd effects.

If you want to use lighting that is different from what the rest of your renderer is using, you might want to call either:

sceneViewer->setLightingMode( osgUtil::SceneView::SKY_LIGHT );

or

sceneViewer->setLightingMode( osgUtil::SceneView::HEADLIGHT );

That's basically it for setup.

Now you just need to call SceneView for rendering, and this requires a little extra work.

First off, it is recommended that you call glPushAttribs( GL_ALL_ATTRIB_BITS ) and glPushMatrix for each of the modelview, projection and texture matrices before calling your other OpenGL code, and the corresponding pop fuctions afterwards, and do the same with OSG. This prevents OSG and your other OpenGL code from interfering with each other. For example:

If you do all of that, you should be able to successfully use OSG within your pre-existing rendering system, thereby gaining many of the advantages of OSG, without having to scrap your existing system.

I have derived a class from osg::Drawable, but its drawImplementation() method is called only once

Try disabling the use of display lists for this class.

drawable->setUseDisplayList( false );

Otherwise a display list will be created once and this will be called for drawing your drawable next time instead of your drawImplementation.

How can I get the BoundingBox for a loaded Node or 3D model?

For performance reasons the OSG stores osg::BoundingSphere's for all internal nodes, and osg::BoundingBox's for the Drawable leaves.

If you wish to use a BoundingBox of a node then you can convert the
BoundingSphere to a BoundingBox by doing something like:

Each rendering window has its own OpenGL context which is separate from all other contexts. Since OSG doesn't know how you have set up your windowing environment, you need to ensure that each osg::State object is tied to a unique OpenGL context. To do that you should:

for each window, get the associated osgUtil::SceneView object

for each SceneView object, get the associated osg::State object

call State::setContextID() on each State, passing a unique number to identify that context.

// this will automatically create the osg::State amoung other operations
sceneview0->setDefaults();
// now set the ID to 0 (this is the default, just set here for clarity
sceneview0->getState()->setContextID(0);
sceneview1->setDefaults();
sceneview1->getState()->setContextID(1);

NOTE: context IDs are used as indices in vectors that grow automatically, so please avoid setting large numbers. Start counting from 0 and then increment by one each time.

I have two or more views sharing a scene graph, but I want to limit what part of the scene graph is shown in one or more of the views. How do I do that?

What is drawn in a view depends on the results of the Cull Traversal. Each view will have a unique osgUtil::SceneView and a each osgUtil::SceneView will have a unique CullVisitor. You can set a traversal mask on each CullVisitor (or sceneView's cullSettings), which it will apply (as a bitwise AND) to each of the nodes it traverses. On each node, then, you can set a CullMask that corresponds to the view you want that sub-graph to be displayed in.

On previous question - Yeah but.... it didn't work!

XXX references osgProducer::Viewer

When using osgProducer::Viewer, convenience functions are set up to allow attributes to be set globally for all Cameras and SceneHandler (including SceneViews) in an OsgCameraGroup. This includes traversal masks for CullVisitors, which will all be set to 0xFFFFFFFF by default. Before setting the TraversalMask on the unique [=CullVisitors?=], you need to make them immune to imposition of global settings with this (CullSettings are applied to CullVisitors on traversal):

Why does my framerate drop when rendering point sprites to an FBO/pbuffer?

Long answer: Read the section on Point Sprites in the nVidia OpenGL 2.0 Support document. It states the following:

When rendering to pixel buffers (commonly called pbuffers) or frame buffer objects
(commonly called FBOs), change the GL_POINT_SPRITE_COORD_ORIGIN state set to
GL_LOWER_LEFT setting for fully hardware accelerated rendering. Using GL_UPPER_LEFT
with pbuffer and FBO rendering will force points to be transformed on the CPU.

Why does my geometry renders opaque while I have transparent colors and/or materials attached to it ?

You need to activate OpenGL blending by setting the GL_BLEND mode on the geometry's stateset (or that of a parent node).

During compile I get errors about Producer/*: No such file or directory. Why? - happens with daily builds and 0.9.4-2 official.

Can I use OSG without Producer, and/or with already created MFC or WxWindow windows ?

You can use OSG with or without Producer, even if you are creating your
own windows. See the osgsimple example for an example of using OSG with a
generic windowing environment. OSG itself is windowing system agnostic,
so setting up the window and OpenGL graphics context will be up to your
application. osgsimple uses Producer, but is written in a way to provide
you the skeleton to use your own windowing system.

Alternatively, you can use Producer in your own windowing environment as
well by setting each Camera's RenderSurface to the window you've created.
Like this: