/ Debugging Tips


Debugging Tips

1 Read the available documentation.
a) Buy (download) the OSG Quick Start Guide.
There is a color version, a black and white version (which is cheaper than the color version), a PDF (which is free), and a Chinese version.
b) Become familiar with the OSG website. It has a very informative FAQ.
c) Search the forum or the mailing list archives
If you're a beginner, your question has probably been discussed and answered multiple times.

2 Use the source code
You are a software engineer and you have the OSG source code. Use it. Step through it in a debugger. This is the most reliable source of information about OSG. The code doesn’t lie.
Read the function comments in the header files for functions you use. This will help you avoid the accidental use of deprecated functions (like Geometry::setVertexIndices()) that are inefficient (but remain in OSG for compatibility reasons).

3 Read the function comments
Read the function comments in the header files for functions you use. This will help you avoid the accidental use of deprecated functions (such as Geometry::setVertexIndices()) that are inefficient, but remain in OSG for compatibility reasons.

4 Inspect the OpenGL calls
For simple rendering problems, use a OpenGL call inspection tool. BuGLe, glIntercept, glTrace, gDEBugger
If you know OpenGL, this is a great way to track down why things don't render correctly. If you don't know OpenGL, buy the red book and learn it, in order to code OSG effectively.

5 Use debug printing
Set OSG_NOTIFY_LEVEL to either INFO or DEBUG and examine the output. OSG might be trying to well you why things are going wrong.

6 Output your scenegraph to a .osg file
Write (a portion of your) scenegraph to an .osg file and examine it in a text editor. This allows you to examine the structure of your scene graph and its data.

7 Use the Optimizer
Run the osgUtil::Optimizer on your scene graph with the CHECK_GEOMETRY flag (to check for simple mistakes like not having enough colors in your color array when using BIND_PER_VERTEX). With OSG_NOTIFY_LEVEL set verbose enough, the Optimizer will display warnings if it encounters these types of issues.

8 Become familiar with osgconv.
For example, if you wrote your scene graph to an .osg file (tip #6) and turned up OSG_NOTIFY_LEVEL (tip #5), osgconv runs the Optimizer with the CHECK_GEOMETRY flag (tip #7), so you can look for warnings in the console output.

9 Become familiar with osgviewer
Its key commands, its statistics display, and its ability to capture and replay animation paths. The OSG Quick Start Guide (tip #1) documents these subjects.

10 Consider purchasing a support contract
If you need professional help, consider purchasing a support contract from Paul Martz or Robert Osfield, or contracting with someone else on the list for support. You are more likely to get quality help if you pay for it.