Scene Graph Profiling -
Data structure for gathering scene graph traversal profiling
Main static class for initializing the scene graph profiling
The SoProfilerElement element class is for registering statistics
during scene graph traversals.
The SoProfilerStats class is a node for exposing profiling results
gathered by SoProfilerElement.
Convenience report generator functionality.
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.
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
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.
EnvironmentVariable COIN_PROFILER This variable should be a set of profiler
settings keywords, separated by ’:’ characters.
The keywords are:
The on keyword just enables the profiling element so profiling data is
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
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.
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
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
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.
Generated automatically by Doxygen for Coin from the source code.