Version 2 (modified by paulm, 9 years ago)



Here is a list of Frequently Asked Questions.

More FAQs about OSG may be found at 3drealtimesimulation.

Note at the bottom of page there links to the previous two Wiki FAQ's which have now been ported across to this FAQ.


  1. General
    1. What platforms does the OpenSceneGraph support?
    2. Where can I get more info on OpenSceneGraph?
    3. What is the difference between your Open Scene Graph and the one from …
  2. Documentation
    1. Are there any books available about OSG?
    2. Where is the reference manual for the .osg file format? I searched all …
    3. Are there tutorials available?
  3. Wiki
    1. How can I edit a wiki page?
    2. How can I add a new wiki-page?
  4. Building/Installation
    1. Are there binary distributions available?
    2. Can I get CVS or Subversion access so I can keep up to date with the …
    3. I'm not using MS Visual Studio. Does OpenSceneGraph support other …
    4. Help! VisualStudio won't load the OSG project files
    5. Everything is compiled, but there are linking problems OR When I run it …
  5. Functionality/Features
  6. Development - General
  7. Development - Windows-specific
    1. When I try to save a node to file, OSG crashes. I'm using Windows. OR STL …
    2. I get a lot of warnings along the lines of... `warning C4541: …
  8. Problems
  9. Other
  10. Older versions of OpenSceneGraph


=== 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 platforms does the OpenSceneGraph support?

Microsoft Windows (2000, XP, Vista), GNU/Linux and MacOS/X are currently the best supported ones. Your mileage may vary on Solaris, IRIX, ...

Where can I get more info on OpenSceneGraph?

Try these locations:

What is the difference between your Open Scene Graph and the one from

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

The OpenSG website also provides a comparison between the two:


Are there any books available about OSG?

Yes, see

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?

Yes, see here.


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.


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 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/ and run ldconfig, or set your LD_LIBRARY_PATH to include the location where you installed the OSG libraries.


=== Q 9: Where is the camera class for OpenSceneGraph? == A: You have three options:

  1. (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.
  1. Use osgUtil::SceneView and osg::Matrix.
  2. Make your own class.

=== Q 11: How do I render terrain in OSG? == A: The OpenSceneGraph now has the osgTerrain NodeKit for generation large paged geospatial databases.

If you wish to use a continous level of details approach to terrain see Demeter ( and the Virtual Terrain Project ( for detailed open source approaches.

=== Q 12: I can't get GLUT working, or GLUT doesn't provide feature X == A: You're better off using wxWidgets ( or Simple Direct Media Layer ( Both are OpenSource and provide the OpenGL renderpanes for OSG to work on.

=== Q 19: How do I do skeletal animation? == A: Check out osgCal which integrates the OSG with Cal3D -

=== Q 24: What file formats are supported by OpenSceneGraph? == A: File input and output is supported through the plugins in the src/osgPlugins directory of the source distribution.

See Support/UserGuides/Plugins for an overview of available plugins and the extensions they support.

Some additional file formats are also supported by Demeter ( or the Virtual Terrain Project (

=== Q 36: Can I use OpenGL commands directly in OSG ? == A: Yes. See the osgteapot example included in the source distribution.

Development - General

=== Q 25: Why do the OSG header files not have a .h or .hpp extension? == A: The short answer is that this is the Standard C++ way of naming headers. For more information see these posts on the osg-users mailing list:

=== Q 26: What can I do to make my editor recognize OSG headers as C++ files? == A: 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
  • 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.

=== Q 28: How do I increase the verbosity of my program for debugging purposes? == A: 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):


=== Q 38: How can I contribute to the OpenSceneGraph? == A: 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 ( 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".


=== Q 13: Is it possible to render a scene in 2D? == A: 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.

=== Q 14: How do I move models around once they are in the scene? == A: Add the Node in question to a 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 a MatrixTransform? to create a mirror image of a model.

=== Q 15: How come the mountain in the hanglider demo is completely white with no shading? == A: 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.

=== Q 20. Why does OSG seem to ignore my near/far clipping planes? == A: 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.

You can override this behavior by calling:


If you are using osgProducer::viewer use:


=== Q 21. If I let OpenSceneGraph calculate my near and far clipping planes, how do I get the computed values? == A: This info is available through the cull visitor, so:


=== Q 27: I am trying to run OpenSceneGraph example programs under Mac OSX, but no window appears! What can I do? == A: 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.

=== Q 29: Qt and other GUI frameworks have adapters available in the contribs. Is there one for Gnome/GTK+? == A: Take a look into the OSGEdit sources ( 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).

=== Q 30: Hey, this particle system is cool, but looks strange when I position it in my scene. What's up? == A: 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)

There is a diagram, description and source code to do this here:

=== Q 31: 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? == A: 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:

osg::CullStack::CullingMode cullingMode = sceneview->getCullingMode();
cullingMode &= ~(osg::CullStack::SMALL_FEATURE_CULLING);
sceneview->setCullingMode( cullingMode );

You can also control the size of the screen space that is used to cull small features with

sceneview->setSmallFeatureCullingPixelSize( minimumSize );

=== Q 32: When I apply a scaling factor in a MatrixTransform, my models are displayed washed out or dark. What's up? == A: The model's normals are scaled along with its vertices. To keep normals normalized, set the OpenGL attribute GL_RESCALE_NORMALS on the appropriate stateset:

stateSet->setMode( GL_RESCALE_NORMAL, osg::StateAttribute::ON );

=== Q 33: How do I insert comments in a .osg file? Or, how do I comment out a block within a .osg file? == A: Due to the nature of the .osg parser, which allows extensions, one can simply insert a comment in a .osg file by doing this:

Comment {
        This file is proprietary and you shoudn't be reading it.
        Please close your editor now!

Also, if you want to comment out a section of a file:

Comment {
        TexGen {
                UniqueID TexGen_4
                DataVariance? STATIC
                mode SPHERE_MAP=]

=== Q 34: Can I use OSG within an existing renderer? == A: 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.

The setup of these two objects will look something like this:

unsigned int frameNumber = 0;
osg::Timer timer;
osg::Timer_t start_tick = timer.tick();
osg::ref_ptr<osgUtil::SceneView> sceneViewer = new osgUtil::SceneView();
osg::ref_ptr<osg::FrameStamp> frameStamp = new osg::FrameStamp();

sceneViewer->setComputeNearFarMode( osgUtil::CullVisitor::DO_NOT_COMPUTE_NEAR_FAR );
sceneViewer->setSceneData( rootNode );

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 );


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:

glPushAttrib=]( GL_ALL_ATTRIB_BITS );

your code here...


The next important thing for using SceneView is that you need to tell it about your pre-existing viewport and projection and modelview matrices. The code to do that looks like this:

GLint viewParams[4];
glGetIntegerv( GL_VIEWPORT, viewParams );
sceneViewer->setViewport(viewParams[0], viewParams[1], viewParams[2], viewParams[3]);

GLfloat glMat[16];
osg::Matrix osgMat;

glGetFloatv( GL_PROJECTION_MATRIX, glMat );
osgMat.set( glMat );
sceneViewer->getProjectionMatrix().set( osgMat );

glGetFloatv( GL_MODELVIEW_MATRIX, glMat );
osgMat.set( glMat );
sceneViewer->getViewMatrix().set( osgMat );

The next step is to update your FrameStamp object (if you are using your own):

double time_since_start = timer.delta_s( start_tick, timer.tick() );
frameStamp->setReferenceTime( time_since_start );
frameStamp->setFrameNumber( frameNumber++ );
sceneViewer->setFrameStamp( frameStamp.get() );

Lastly, you need to make the actual calls to the SceneView object:

sceneViewer->update ();
sceneViewer->cull ();
sceneViewer->draw ();

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.

=== Q 35: I have derived a class from osg::Drawable, but its drawImplementation() method is called only once! == A: 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.

=== Q 39: How can I get the BoundingBox for a loaded Node or 3D model? == A: 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:

 BoundingBox bb;

=== Q 40: When using multiple viewers and/or multiple rendering windows, I get weird results and my textures don't display correctly. == A: 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:

  1. for each window, get the associated osgUtil::SceneView object
  2. for each SceneView object, get the associated osg::State object
  3. call State::setContextID() on each State, passing a unique number to identify that context.

After contracting the SceneView?'s:

// this will automatically create the osg::State amoung other operations
// now set the ID to 0 (this is the default, just set here for clarity


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.

=== Q 41: 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? == A: 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.

Like this:

  leftSceneView->getCullVisitor()->setTraversalMask( 0x1);
  rightSceneView->getCullVisitor()->setTraversalMask( 0x2 );


=== Q 42: On previous question - Yeah but.... it didn't work! == A: 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):

    osgProducer::Viewer::SceneHandlerList shl = viewer.getSceneHandlerList();
    osgProducer::Viewer::SceneHandlerList::iterator p;
    unsigned int n = 0;
    for( p = shl.begin(); p != shl.end(); p++ )
        int inheritanceMask = (*p)->getSceneView()->getInheritanceMask();
        inheritanceMask &= ~(osg::CullSettings::CULL_MASK);
        (*p)->getSceneView()->setInheritanceMask( inheritanceMask );
        (*p)->getSceneView()->setCullMask( 1<<(n));

=== Q 43: How do I capture a screengrab? == A:
Producer example from ViewerEventHandler.cpp ViewerEventHandler::SnapImageDrawCallback:

int x,y;
unsigned int width,height;
osg::ref_ptr<osg::Image> image = new osg::Image;
image->readPixels(x,y,width,height, GL_RGB,GL_UNSIGNED_BYTE);

GLUT example from the SST Project:

osg::ref_ptr<osg::Image>image = new osg::Image;
unsigned int w = glutGet(GLUT_WINDOW_WIDTH);
unsigned int h = glutGet(GLUT_WINDOW_HEIGHT);
image->allocateImage(w, h, 1, GL_RGB, GL_UNSIGNED_BYTE);
image->readPixels(0, 0, w, h, GL_RGB, GL_UNSIGNED_BYTE);

=== Q 47: Why does my framerate drop when rendering point sprites to an FBO/pbuffer? == A: Short answer: Change the coordinate origin mode of the PointSprite attribute to LOWER_LEFT:

osg::PointSprite *ps = new osg::PointSprite;

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.

=== Q 48: Why does my geometry renders opaque while I have transparent colors and/or materials attached to it ? == A: You need to activate OpenGL blending by setting the GL_BLEND mode on the geometry's stateset (or that of a parent node).

stateSet->setMode( GL_BLEND, osg::StateAttribute::ON );

Or in a .osg file:

file geom.osg

  Geometry {
    StateSet {
    PrimitiveSets 1


=== Q 18: I have a matrix math question... == A: Check the Matrix and Quaternion FAQ at

Older versions of OpenSceneGraph

=== Q 23: During compile I get errors about Producer/*: No such file or directory. Why? - happens with daily builds and 0.9.4-2 official. == A: First build and install OpenProducer.

=== Q 37: Can I use OSG without Producer, and/or with already created MFC or WxWindow windows ? == A: 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:

osgProducer::Viewer viewer;
viewer.getCamera(0)->getRenderSurface()->setWindow( myWindow );

The variable 'myWindow' is an X11 Window, or a win32 HWND.

See : for even more details.

=== Q 44 : How can I change the Producer icon at run-time? == A: In Microsoft Windows and Visual Studio 7.x:

First add an icon to your solution (Project/Add Recource/Icon).

After viewer->realize() do the following:

Producer::Window wnd = viewer->getCamera(0)->getRenderSurface()->getWindow();
HICON h1 = LoadIcon(GetModuleHandle(0), "YOUR_ICON");
DWORD dw = SetClassLongPtr(wnd, GCL_HICON, (LONG_PTR)h1);

The string "YOUR_ICON" should refer to the icon name in your resource file(.rc).