profiler(3)

💖 profiler — Scene Graph Profiling 💖

okay bestie, welcome to profiler(3) from the Library Functions Manual — this is the whole vibe of Coin's scene graph profiling situation, and honestly? it's giving ✨developer tooling✨. let's get into it 🫶

---

🌸 SYNOPSIS 🌸

🎀 Classes

• class SbProfilingData — the lil data structure that holds onto scene graph traversal profiling info. it's literally where the numbers live 💅
• class SoProfiler — the main static class, aka the one in charge of booting up the whole scene graph profiling subsystem. main character energy fr 👑
• class SoProfilerElement — this element class is the one that registers statistics while scene graph traversals are happening. it's the note-taker of the group chat 📝
• class SoProfilerStats — a node whose whole job is exposing the profiling results that SoProfilerElement gathered. the messenger, the gossip relay 🦋
• class SoProfilingReportGenerator — convenience report generator functionality, because sometimes you just want the receipts handed to you 🧾

🦋 Variables

• EnvironmentVariable COIN_PROFILER
• EnvironmentVariable COIN_PROFILER_OVERLAY

---

✨ Detailed Description ✨

Coin includes some scene graph profiling functionality, no cap. the whole point of it is to be used while you're developing an application, so you can clock the performance bottlenecks in Coin-based apps — both the ones caused by how you're using Coin, and the ones caused by how Coin itself is implemented. it's a vibe check on your whole render pipeline 🔥

here's the cute part: the profiling code can be enabled in existing Coin applications without adding any code at all, just by flipping on some environment variables. iconic behaviour honestly.

BUT — and this is the real tea — for particular profiling needs, the default behaviour you can trigger through environment variables might not work that well. maybe you've got a specialized render pipeline that causes the output to be garbled, or maybe you need it to focus on specific info (the full application might add noise to the system that Coin won't separate out). in those cases, programmatic access to the profiling subsystem is gonna be necessary to get the better results. so: env vars for the quick look, programmatic access when you're being serious 💅

Since

Coin 3.0

profiling_intro

---

🌈 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. every single one. it's watching 👀

---

🍓 Enabling the default profiling display

to get some profiling data actually shown on the screen, you also need to use the COIN_PROFILER_OVERLAY environment variable. two variables, bestie, that's the price of admission.

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 📈
• a scene graph navigator for closer scene graph inspection 🔍

it's a whole dashboard and it's honestly kind of a serve.

---

💜 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 on 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.

(yes, the original says "connect the the fields" — we keep the lore exact, no notes 😌)

---

👑 Variable Documentation 👑

🌟 EnvironmentVariable COIN_PROFILER

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

the keywords are:

• on
• off
• syncgl

on — just enables the profiling element so profiling data is recorded. simple, does what it says 💖

off — just disables the profiling subsystem. there is really no need for specifying this, since it's off by default, but you can use it to override settings already in the environment at launch-time. it's the "actually, never mind" of keywords 🙈

syncgl — makes 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. we are not exaggerating. the rock drop is real. 💀

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 a new scheme was needed 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>

autoredraw=<float> — 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. (yes, the option is autoredraw and the example says redraw — we report it exactly as the ancestors wrote it, no cap 🙏)

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

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

clear — 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. your terminal mileage may vary, bestie 🫶

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

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

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

category=<keyword> — 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.

📌 there's a note left in the source that we're keeping verbatim, because respecting the historical record is the whole point:

/* FIXME: document all variables. pederb, 2004-03-22

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.

---

🌈 Author 🌈

Generated automatically by Doxygen for Coin from the source code. so technically the author is a robot and the robot ate ✨

---

and that's the whole page, bestie!! this was Coin, Version 3.1.3, profiler(3) — mwah, go profile something and slay 💅💖🎀