Scene Graph Profiling

Classes
class	SbProfilingData
	Data structure for gathering scene graph traversal profiling information. More...
class	SoProfiler
	Main static class for initializing the scene graph profiling subsystem. More...
class	SoProfilerElement
	The SoProfilerElement element class is for registering statistics during scene graph traversals. More...
class	SoProfilerStats
	The SoProfilerStats class is a node for exposing profiling results gathered by SoProfilerElement. More...
class	SoProfilingReportGenerator
	Convenience report generator functionality. More...

Variables
EnvironmentVariable	COIN_PROFILER
EnvironmentVariable	COIN_PROFILER_OVERLAY

Detailed Description

Coin includes some scene graph profiling functionality. This functionality is intended for use during application development for identifying performance bottlenecks in Coin-based applications with regards to how Coin is being used and with regards to problems with how Coin is implemented.

The profiling code can be enabled in existing Coin applications without the need of adding any code by enabling it through the use of some environment variables. For particular profiling needs, the default behaviour you can trigger through environment variables might not work that well (you might have a specialized render pipeline that causes the output to be garbled) or focus on the information you need (the full application might perhaps add noise to the system that Coin won't separate out). In such cases, programmatic access to the profiling subsystem will be necessary to get the better results.

Since

Coin 3.0

Enabling profiling in Coin

To enable profiling in Coin, use the environment variable COIN_PROFILER. When profiling is enabled, Coin will gather profiling data during every scene graph traversal by any action.

Enabling the default profiling display

To get some profiling data shown on the screen, you also need to use the COIN_PROFILER_OVERLAY environment variable.This will give you the default profiling graphics, which shows a top-list of node timings categorized by node types, a scrolling graph of action traversal timings, and a scene graph navigator for closer scene graph inspection.

Read the profiling data

The SoProfilerStats node can be used to fetch the profiling data in the scene graph. If it is positioned anywhere in the scene graph, the fields of the node will be updated every time SoGLRenderAction is applied to the scene graph, with profiling data gathered from every traversal through the scene graph since the last SoGLRenderAction, up to the point where SoProfilerStats is located. Depending of how you wish to use the data, either attach sensors to the fields, or connect the the fields on other coin nodes to the fields on SoProfilerStats.

Variable Documentation

EnvironmentVariable COIN_PROFILER

This variable should be a set of profiler settings keywords, separated by ":" characters.

The keywords are:

• on
• off
• syncgl

The on keyword just enables the profiling element so profiling data is recorded.

The off keyword just disables the profiling subsystem. There is really no need for specifying this as it is off by default, but can for instance be used to override settings already in the environment at launch-time.

The syncgl keyword will make GL rendering flush the GL pipeline between each node, so that the profiling data will better reflect which nodes actually cause work for Open GL. Note however that the GL rendering performance drops like a rock when enabling this. The syncgl keyword implies the on keyword.

Old Usage: When this was first implemented, just setting this environment variable to "1" or any positive integer value turned on the live scene graph profiling feature in Coin. This usage is still supported, but as the number of options grew, it was obvious that we needed a new scheme rather than one variable for each feature. The positive integer approach can not be combined with using keywords, and setting the value to "1" is the same thing as setting it to "on".

EnvironmentVariable COIN_PROFILER_OVERLAY

This variable enables some default profiler statistics output techniques. It should be a set of profiler overlay settings keywords, separated by ":" characters.

• autoredraw=<float>
• stdout
• stderr
• clear
• header
• lines=<int>
• action=<actionclass>
• category=<nodes|types|names>

The autoredraw=<float> option sets up the GL display to automatically redraw the display after a delay of <float> seconds. Example: redraw=0.2 gives you somewhere below 5 redraws a second, depending on how fast each frame is drawn.

The stdout keyword causes the profiling data to be sent to stdout instead of being overlayed on the GL view.

The stderr keyword causes the profiling data to be sent to stderr instead of being overlayed on the GL view.

The clear keyword works with stdout and stderr, and makes Coin attempt to clear the console between each time it dumps profiling data. It just uses the ANSI console escape sequence for clearing, which may not work on all types of terminals.

The header keyword makes the profiling output be preceded by a header line that explains what each column means. It only works with stdout and stderr.

The lines=<int> option lets you select the number of lines to output. The default is 20. This option only works with stdout and stderr.

The action=<actionclass> option lets you select which action is to be profiled. The default is of course the SoGLRenderAction. This only works with stdout and stderr.

The category=<keyword> option lets you specify which view you should have on the profiling data. A nodes view will give you one entry in the list for each node. A types view will summarize over each type and present one entry per node type. A names view will group nodes that belong under the same named node together and presents that summary as one entry.

Old Usage: Setting this environment variable to "1" (or any positive integer) turns on the live scene graph (primarily) profiling overlay feature in Coin, the way it was in the beginning of implementing this functionality. This still works but just gives you one default view. It can not be combined with using keywords.