.TH "Scene Graph Profiling" 3 "Wed May 23 2012" "Version 3.1.3" "Coin" \" -*- nroff -*- .ad l .nh .SH NAME Scene Graph Profiling \- .SS "Classes" .in +1c .ti -1c .RI "class \fBSbProfilingData\fP" .br .RI "\fIData structure for gathering scene graph traversal profiling information\&. \fP" .ti -1c .RI "class \fBSoProfiler\fP" .br .RI "\fIMain static class for initializing the scene graph profiling subsystem\&. \fP" .ti -1c .RI "class \fBSoProfilerElement\fP" .br .RI "\fIThe \fBSoProfilerElement\fP element class is for registering statistics during scene graph traversals\&. \fP" .ti -1c .RI "class \fBSoProfilerStats\fP" .br .RI "\fIThe \fBSoProfilerStats\fP class is a node for exposing profiling results gathered by \fI\fBSoProfilerElement\fP\fP\&. \fP" .ti -1c .RI "class \fBSoProfilingReportGenerator\fP" .br .RI "\fIConvenience report generator functionality\&. \fP" .in -1c .SS "Variables" .in +1c .ti -1c .RI "EnvironmentVariable \fBCOIN_PROFILER\fP" .br .ti -1c .RI "EnvironmentVariable \fBCOIN_PROFILER_OVERLAY\fP" .br .in -1c .SH "Detailed Description" .PP 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\&. .PP 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\&. .PP \fBSince:\fP .RS 4 Coin 3\&.0 .RE .PP .SS "Enabling profiling in Coin" .PP To enable profiling in Coin, use the environment variable \fBCOIN_PROFILER\fP\&. When profiling is enabled, Coin will gather profiling data during every scene graph traversal by any action\&. .PP .SS "Enabling the default profiling display" .PP To get some profiling data shown on the screen, you also need to use the \fBCOIN_PROFILER_OVERLAY\fP environment variable\&. .PP 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\&. .PP .SS "Read the profiling data" .PP The \fBSoProfilerStats\fP 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 \fBSoGLRenderAction\fP is applied to the scene graph, with profiling data gathered from every traversal through the scene graph since the last \fBSoGLRenderAction\fP, up to the point where \fBSoProfilerStats\fP 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 \fBSoProfilerStats\fP\&. .SH "Variable Documentation" .PP .SS "EnvironmentVariable COIN_PROFILER" This variable should be a set of profiler settings keywords, separated by ':' characters\&. .PP The keywords are: .IP "\(bu" 2 \fCon\fP .IP "\(bu" 2 \fCoff\fP .IP "\(bu" 2 \fCsyncgl\fP .PP .PP The \fCon\fP keyword just enables the profiling element so profiling data is recorded\&. .PP The \fCoff\fP 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\&. .PP The \fCsyncgl\fP 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 \fCsyncgl\fP keyword implies the \fCon\fP keyword\&. .PP \fBOld\fP \fBUsage:\fP When this was first implemented, just setting this environment variable to \fC'1'\fP 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 \fC'1'\fP is the same thing as setting it to \fC'on'\fP\&. .SS "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\&. .PP .IP "\(bu" 2 \fCautoredraw=\fP .IP "\(bu" 2 \fCstdout\fP .IP "\(bu" 2 \fCstderr\fP .IP "\(bu" 2 \fCclear\fP .IP "\(bu" 2 \fCheader\fP .IP "\(bu" 2 \fClines=\fP .IP "\(bu" 2 \fCaction=\fP .IP "\(bu" 2 \fCcategory=\fP .PP .PP The \fCautoredraw=\fP option sets up the GL display to automatically redraw the display after a delay of \fC\fP seconds\&. Example: \fCredraw=0\&.2\fP gives you somewhere below 5 redraws a second, depending on how fast each frame is drawn\&. .PP The \fCstdout\fP keyword causes the profiling data to be sent to stdout instead of being overlayed on the GL view\&. .PP The \fCstderr\fP keyword causes the profiling data to be sent to stderr instead of being overlayed on the GL view\&. .PP The \fCclear\fP keyword works with \fCstdout\fP and \fCstderr\fP, 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\&. .PP The \fCheader\fP keyword makes the profiling output be preceded by a header line that explains what each column means\&. It only works with \fCstdout\fP and \fCstderr\fP\&. .PP The \fClines=\fP option lets you select the number of lines to output\&. The default is 20\&. This option only works with \fCstdout\fP and \fCstderr\fP\&. .PP The \fCaction=\fP option lets you select which action is to be profiled\&. The default is of course the \fBSoGLRenderAction\fP\&. This only works with \fCstdout\fP and \fCstderr\fP\&. .PP The \fCcategory=\fP option lets you specify which view you should have on the profiling data\&. A \fCnodes\fP view will give you one entry in the list for each node\&. A \fCtypes\fP view will summarize over each type and present one entry per node type\&. A \fInames\fP view will group nodes that belong under the same named node together and presents that summary as one entry\&. .PP \fBOld\fP \fBUsage:\fP Setting this environment variable to \fC'1'\fP (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\&. .PP /* FIXME: document all variables\&. pederb, 2004-03-22 .PP UPDATE: a good way to do this, imho, would be to set them up as SoDBP::EnvVars members, as is done for a few already, and document them one-by-one through Doxygen\&. 20071106 mortene\&. .SH "Author" .PP Generated automatically by Doxygen for Coin from the source code\&.