SoSeparator(3)

📦
version 4.0.10 · 4 versions
, in fedora 43, fedora 44

💖 SoSeparator(3) 💖

Coin documentation, but make it a group chat. Welcome bestie, you're reading the manual page for SoSeparator — yes, the SoSeparator(3) one, the icon herself. Sit down, hydrate, let's go. 🦋

✨ NAME ✨

SoSeparator — okay so the SoSeparator class is a state-preserving group node. That's it, that's the whole job description, and she does it flawlessly. 💅

🌸 SYNOPSIS 🌸

#include <Inventor/nodes/SoSeparator.h>

Inherits SoGroup.

Inherited by SoAnnotation, SoGeoSeparator, SoLocateHighlight, SoSelection, and SoShadowGroup.

👑 Public Types 👑

  • enum CacheEnabled { OFF, ON, AUTO }

🧬 Public Types inherited from SoNode

enum NodeType { INVENTOR = 0x0000, VRML1 = 0x0001, VRML2 = 0x0002,
    INVENTOR_1 = 0x0004, INVENTOR_2_0 = 0x0008, INVENTOR_2_1 = 0x0010,
    INVENTOR_2_5 = 0x0020, INVENTOR_2_6 = 0x0040, COIN_1_0 = 0x0080,
    COIN_2_0 = 0x0100, EXTENSION = 0x0200, COIN_2_2 = 0x0400, COIN_2_3 =
    0x0800, COIN_2_4 = 0x1000, INVENTOR_5_0 = 0x2000, COIN_2_5 = 0x4000,
    COIN_3_0 = 0x8000, INVENTOR_6_0 = 0x10000, COIN_4_0 = 0x20000 }

🫶 Public Member Functions 🫶

The main character's own moves, in order, no skips:

  • virtual SoType getTypeId (void) const
  • SoSeparator (void)
  • SoSeparator (const int nchildren)
  • virtual void doAction (SoAction *action)
  • virtual void GLRender (SoGLRenderAction *action)
  • virtual void GLRenderBelowPath (SoGLRenderAction *action)
  • virtual void GLRenderInPath (SoGLRenderAction *action)
  • virtual void GLRenderOffPath (SoGLRenderAction *action)
  • virtual void callback (SoCallbackAction *action)
  • virtual void getBoundingBox (SoGetBoundingBoxAction *action)
  • virtual void getMatrix (SoGetMatrixAction *action)
  • virtual void handleEvent (SoHandleEventAction *action)
  • virtual void rayPick (SoRayPickAction *action)
  • virtual void search (SoSearchAction *action)
  • virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action)
  • virtual void audioRender (SoAudioRenderAction *action)
  • virtual void notify (SoNotList *nl)
  • virtual SbBool affectsState (void) const

💜 Public Member Functions inherited from SoGroup

  • SoGroup (void)
  • SoGroup (int nchildren)
  • virtual void addChild (SoNode *node)
  • virtual void insertChild (SoNode *child, int newchildindex)
  • virtual SoNode * getChild (int index) const
  • virtual int findChild (const SoNode *node) const
  • virtual int getNumChildren (void) const
  • virtual void removeChild (int childindex)
  • virtual void removeChild (SoNode *child)
  • virtual void removeAllChildren (void)
  • virtual void replaceChild (int index, SoNode *newchild)
  • virtual void replaceChild (SoNode *oldchild, SoNode *newchild)
  • virtual void pick (SoPickAction *action)
  • virtual void write (SoWriteAction *action)
  • virtual SoChildList * getChildren (void) const
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)

🌈 Public Member Functions inherited from SoNode

  • void setOverride (const SbBool state)
  • SbBool isOverride (void) const
  • void setNodeType (const NodeType type)
  • NodeType getNodeType (void) const
  • virtual SoNode * copy (SbBool copyconnections=FALSE) const
  • virtual void grabEventsSetup (void)
  • virtual void grabEventsCleanup (void)
  • virtual void startNotify (void)
  • SbUniqueId getNodeId (void) const
  • virtual void writeInstance (SoOutput *out)
  • virtual SoNode * addToCopyDict (void) const
  • virtual SoFieldContainer * copyThroughConnection (void) const

🎀 Public Member Functions inherited from SoFieldContainer

  • void setToDefaults (void)
  • SbBool hasDefaultValues (void) const
  • SbBool fieldsAreEqual (const SoFieldContainer *container) const
  • void copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE)
  • SbBool set (const char *const fielddata)
  • void get (SbString &fielddata)
  • virtual int getFields (SoFieldList &l) const
  • virtual int getAllFields (SoFieldList &l) const
  • virtual SoField * getField (const SbName &name) const
  • virtual SoField * getEventIn (const SbName &name) const
  • virtual SoField * getEventOut (const SbName &name) const
  • SbBool getFieldName (const SoField *const field, SbName &name) const
  • SbBool enableNotify (const SbBool flag)
  • SbBool isNotifyEnabled (void) const
  • SbBool set (const char *fielddata, SoInput *input)
  • void get (SbString &fielddata, SoOutput *out)
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval)
  • SbBool getIsBuiltIn (void) const
  • virtual void getFieldsMemorySize (size_t &managed, size_t &unmanaged) const
  • void setUserData (void *userdata) const
  • void * getUserData (void) const

🦋 Public Member Functions inherited from SoBase

  • void ref (void) const
  • void unref (void) const
  • void unrefNoDelete (void) const
  • int32_t getRefCount (void) const
  • void touch (void)
  • SbBool isOfType (SoType type) const — hands back TRUE if the type of this object is either the same type as type, or inherited from type. like, "do you know her? is she family?" energy.
  • virtual SbName getName (void) const
  • virtual void setName (const SbName &newname)
  • void addAuditor (void *const auditor, const SoNotRec::Type type)
  • void removeAuditor (void *const auditor, const SoNotRec::Type type)
  • const SoAuditorList & getAuditors (void) const
  • SbBool shouldWrite (void)
  • void assertAlive (void) const

⭐ Static Public Member Functions ⭐

  • static SoType getClassTypeId (void)
  • static void initClass (void) — sets up the initialization for data that's common to all instances of this class, like submitting necessary information to the Coin type system. the pre-game ritual, basically. 💅
  • static void setNumRenderCaches (const int howmany)
  • static int getNumRenderCaches (void)

💖 Static Public Member Functions inherited from SoGroup

  • static SoType getClassTypeId (void)
  • static void initClass (void) — sets up the initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.

✨ Static Public Member Functions inherited from SoNode

  • static uint32_t getCompatibilityTypes (const SoType &nodetype)
  • static SoType getClassTypeId (void)
  • static SoNode * getByName (const SbName &name)
  • static int getByName (const SbName &name, SoNodeList &l)
  • static void initClass (void) — sets up the initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
  • static void initClasses (void)
  • static SbUniqueId getNextNodeId (void)
  • static int getActionMethodIndex (const SoType type)
  • static void getBoundingBoxS (SoAction *action, SoNode *node)
  • static void GLRenderS (SoAction *action, SoNode *node)
  • static void callbackS (SoAction *action, SoNode *node)
  • static void getMatrixS (SoAction *action, SoNode *node)
  • static void handleEventS (SoAction *action, SoNode *node)
  • static void pickS (SoAction *action, SoNode *node)
  • static void rayPickS (SoAction *action, SoNode *node)
  • static void searchS (SoAction *action, SoNode *node)
  • static void writeS (SoAction *action, SoNode *node)
  • static void audioRenderS (SoAction *action, SoNode *node)
  • static void getPrimitiveCountS (SoAction *action, SoNode *node)

🍓 Static Public Member Functions inherited from SoFieldContainer

  • static void initClass (void) — sets up the initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
  • static SoType getClassTypeId (void) — this static method returns the SoType object associated with objects of this class. it's giving "who is she" but answered.
  • static void cleanupClass (void)
  • static void initCopyDict (void)
  • static void addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy)
  • static SoFieldContainer * checkCopy (const SoFieldContainer *orig)
  • static SoFieldContainer * findCopy (const SoFieldContainer *orig, const SbBool copyconnections)
  • static void copyDone (void)

🧚 Static Public Member Functions inherited from SoBase

  • static void initClass (void) — sets up the initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
  • static SoType getClassTypeId (void) — this static method returns the SoType object associated with objects of this class.
  • static void addName (SoBase *const base, const char *const name)
  • static void removeName (SoBase *const base, const char *const name)
  • static void incrementCurrentWriteCounter (void)
  • static void decrementCurrentWriteCounter (void)
  • static SoBase * getNamedBase (const SbName &name, SoType type)
  • static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
  • static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype)
  • static void setInstancePrefix (const SbString &c)
  • static void setTraceRefs (SbBool trace)
  • static SbBool getTraceRefs (void)
  • static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
  • static SbBool readRoute (SoInput *input)

🌸 Public Attributes 🌸

  • SoSFEnum renderCaching
  • SoSFEnum boundingBoxCaching
  • SoSFEnum renderCulling
  • SoSFEnum pickCulling

🔒 Protected Member Functions 🔒

  • virtual const SoFieldData * getFieldData (void) const
  • virtual ~SoSeparator ()
  • virtual SbBool cullTest (SoState *state)
  • virtual SbBool cullTest (SoGLRenderAction *action, int &cullresults)
  • virtual SbBool readInstance (SoInput *in, unsigned short flags)

💜 Protected Member Functions inherited from SoGroup

  • virtual ~SoGroup ()
  • virtual SbBool readChildren (SoInput *in)
  • virtual void copyContents (const SoFieldContainer *from, SbBool copyconnections)
  • virtual SoNotRec createNotRec (void)
  • void setOperation (const SoNotRec::OperationType opType=SoNotRec::UNSPECIFIED, const SoNode *cc=NULL, const SoNode *pc=NULL, const int ci=-1)

🌈 Protected Member Functions inherited from SoNode

  • SoNode (void)
  • virtual ~SoNode ()

🎀 Protected Member Functions inherited from SoFieldContainer

  • SoFieldContainer (void)
  • virtual ~SoFieldContainer ()

🦋 Protected Member Functions inherited from SoBase

  • SoBase (void)
  • virtual ~SoBase ()
  • virtual void destroy (void)
  • SbBool hasMultipleWriteRefs (void) const
  • SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
  • void writeFooter (SoOutput *out) const
  • virtual const char * getFileFormatName (void) const

🔥 Static Protected Member Functions 🔥

  • static const SoFieldData ** getFieldDataPtr (void)

⭐ Static Protected Member Functions inherited from SoGroup

  • static const SoFieldData ** getFieldDataPtr (void)

💖 Static Protected Member Functions inherited from SoNode

  • static const SoFieldData ** getFieldDataPtr (void)
  • static void setNextActionMethodIndex (int index)
  • static int getNextActionMethodIndex (void)
  • static void incNextActionMethodIndex (void)
  • static void setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask)

🍓 Static Protected Member Functions inherited from SoBase

  • static uint32_t getCurrentWriteCounter (void)
  • static void staticDataLock (void)
  • static void staticDataUnlock (void)

okay that's the whole roster for this part, and there's more coming so don't go anywhere bestie 🫶

🌸 Additional Inherited Members 🌸

okay so before we get into the juicy stuff, here's all the stuff this class just... inherits, no questions asked 💅

Protected Types inherited from SoBase

enum BaseFlags { IS_ENGINE = 0x01, IS_GROUP = 0x02 }

Protected Attributes inherited from SoGroup

  • SoChildList * children

Protected Attributes inherited from SoNode

  • SbUniqueId uniqueId

Protected Attributes inherited from SoFieldContainer

  • SbBool isBuiltIn

Static Protected Attributes inherited from SoNode

  • static SbUniqueId nextUniqueId = 1
  • static int nextActionMethodIndex = 0

💖 Detailed Description 💖

bestie. listen. The SoSeparator class is a state-preserving group node. That's the whole vibe, that's the assignment, periodt. ✨

Subgraphs parented by SoSeparator nodes will not affect the state, because they push and pop the traversal state before and after traversal of its children. So your kids can do whatever chaotic little thing they want in there and the state outside stays completely unbothered. main character energy tbh 🎀

SoSeparator nodes also provides options for traversal optimization through the use of caching. lowkey iconic, it's literally doing the most so your scene graph doesn't have to 🦋

FILE FORMAT/DEFAULTS:

Separator {
    renderCaching AUTO
    boundingBoxCaching AUTO
    renderCulling AUTO
    pickCulling AUTO
}

See also

  • SoTransformSeparator

👑 Member Enumeration Documentation 👑

⭐ enum SoSeparator::CacheEnabled ⭐

Enumeration of flags for the fields deciding which optimizations to do in SoSeparator nodes. There are two types of settings available: caching policies or culling policies. See documentation of fields.

Enumerator

  • OFF — No caching. none. zero. nada. we're rawdogging this traversal fr fr 😭
  • ON — Always try to cache state. just cache it, always, no thoughts head empty, committed 💚
  • AUTO — Use heuristics to try to figure out the optimal caching policy. the node is doing detective work on itself, we love a self-aware queen 🔥

🎀 Constructor & Destructor Documentation 🎀

SoSeparator::SoSeparator (void )

Default constructor. the no-args serve, the classic, the one everybody knows 🫶

SoSeparator::SoSeparator (const int nchildren)

Constructor.

The argument should be the approximate number of children which is expected to be inserted below this node. The number need not be exact, as it is only used as a hint for better memory resource allocation. it's giving "just a heads up bestie, not a contract" 💅

SoSeparator::~SoSeparator () [protected], [virtual]

Destructor. Frees resources used to implement caches. cleaning up after herself, as she should 🌸

💅 Member Function Documentation 💅

Okay bestie, this is the big one. Every single method this class has, laid out one by one. Buckle up. 🎀

🌟 SoType SoSeparator::getClassTypeId (void ) [static]

Static method, no instance needed. It hands you back the SoType object that's associated with objects of this class. That's it, that's the whole job. ✨

🦋 SoType SoSeparator::getTypeId (void ) const [virtual]

This one gives you the type identification of an object derived from a class that inherits SoBase. What's it for? Runtime type checking and "downward" casting. iykyk. 👑

Reimplemented from SoGroup.

Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, SoSelection, SoShadowGroup, and SoWWWAnchor.

🔒 const SoFieldData ** SoSeparator::getFieldDataPtr (void ) [static], [protected]

Heads up: this API member is considered internal to the library, because it's not likely to be of interest to the application programmer. So like… not for you, unless you're doing deep library stuff. 🙈

Returns the SoFieldData class which holds information about fields in this node.

🧚 const SoFieldData * SoSeparator::getFieldData (void ) const [protected], [virtual]

Returns a pointer to the class-wide field data storage object for this instance. And if there are no fields present? It returns NULL. Simple as. 💜

Reimplemented from SoGroup.

Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, SoSelection, SoShadowGroup, and SoWWWAnchor.

✨ void SoSeparator::doAction (SoAction * action) [virtual]

This function performs the typical operation of a node for any action. Any action. All of them. Versatile queen. 💅

Reimplemented from SoGroup.

🌈 void SoSeparator::GLRender (SoGLRenderAction * action) [virtual]

Action method for the SoGLRenderAction.

This gets called during rendering traversals. Any node that influences the rendering state in any way, or wants to throw geometry primitives at OpenGL, overrides this method.

Reimplemented from SoGroup.

Reimplemented in SoAnnotation.

🔥 void SoSeparator::GLRenderBelowPath (SoGLRenderAction * action) [virtual]

Okay so this one has lore. SGI Open Inventor v2.1 obsoleted support for SoGLRenderAction::addMethod(). Instead, GLRender() might be called directly, and to optimize traversal, the SoSeparator node calls GLRenderBelowPath whenever the path code is BELOW_PATH or NO_PATH (because the path code is guaranteed not to change). To stay compatible with SGI's Inventor (and thereby also TGS'), they chose to follow their implementation in this respect. Respect the ancestors. 🫶

SoSeparator::GLRenderBelowPath() does not traverse its children using SoChildList::traverse(), but calls GLRenderBelowPath() directly for all its children.

Reimplemented from SoNode.

Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, and SoShadowGroup.

🍓 void SoSeparator::GLRenderInPath (SoGLRenderAction * action) [virtual]

Implements the SoAction::IN_PATH traversal method for the rendering action.

Reimplemented from SoNode.

Reimplemented in SoAnnotation, SoGeoSeparator, SoLocateHighlight, and SoShadowGroup.

💀 void SoSeparator::GLRenderOffPath (SoGLRenderAction * action) [virtual]

Implements the SoAction::OFF_PATH traversal method for the rendering action.

Reimplemented from SoNode.

Reimplemented in SoAnnotation.

🎀 void SoSeparator::callback (SoCallbackAction * action) [virtual]

Action method for SoCallbackAction.

It simply updates the state according to how the node behaves for the render action, so the application programmer can use the SoCallbackAction for extracting information about the scene graph. Lowkey a spy tool, highkey useful. 👀

Reimplemented from SoGroup.

Reimplemented in SoGeoSeparator.

📦 void SoSeparator::getBoundingBox (SoGetBoundingBoxAction * action) [virtual]

Action method for the SoGetBoundingBoxAction.

It calculates the bounding box and center coordinates for the node, and modifies the values of the action to encompass the bounding box for this node, and to shift the center point for the scene more towards the one for this node.

Nodes that influence how geometry nodes calculate their bounding box also override this method to change the relevant state variables.

Reimplemented from SoGroup.

Reimplemented in SoGeoSeparator.

🧮 void SoSeparator::getMatrix (SoGetMatrixAction * action) [virtual]

Action method for SoGetMatrixAction.

It updates the action by accumulating with the transformation matrix of this node (if there is any).

Reimplemented from SoGroup.

Reimplemented in SoGeoSeparator.

🖱️ void SoSeparator::handleEvent (SoHandleEventAction * action) [virtual]

Action method for SoHandleEventAction.

It inspects the event data from action, and processes it if it's something this node should react to.

Nodes that influence relevant state variables for how event handling is done also override this method.

Reimplemented from SoGroup.

Reimplemented in SoExtSelection, SoLocateHighlight, SoSelection, and SoWWWAnchor.

⭐ void SoSeparator::rayPick (SoRayPickAction * action) [virtual]

Action method for SoRayPickAction.

It checks the ray specification of the action and tests for intersection with the data of the node.

Nodes that influence relevant state variables for how picking is done also override this method.

Reimplemented from SoNode.

Reimplemented in SoGeoSeparator.

🔍 void SoSeparator::search (SoSearchAction * action) [virtual]

Action method for SoSearchAction.

It compares the search criteria from the action to see if this node is a match. Searching is done by matching up all criteria set up in the SoSearchAction — and if any of the requested criteria is a miss, the search is not deemed successful for the node. All-or-nothing, periodt. 💅

See also: SoSearchAction

Reimplemented from SoGroup.

🧸 void SoSeparator::getPrimitiveCount (SoGetPrimitiveCountAction * action) [virtual]

Action method for the SoGetPrimitiveCountAction.

It calculates the number of triangle, line segment and point primitives for the node and adds these to the counters of the action. Counting the little guys. 🥹

Nodes that influence how geometry nodes calculate their primitive count also override this method to change the relevant state variables.

Reimplemented from SoGroup.

Reimplemented in SoGeoSeparator.

🔊 void SoSeparator::audioRender (SoAudioRenderAction * action) [virtual]

Action method for SoAudioRenderAction.

It does the common processing for SoAudioRenderAction action instances.

Reimplemented from SoGroup.

📣 void SoSeparator::notify (SoNotList * l) [virtual]

Notifies all auditors for this instance when changes are made. It's the group chat announcement of the class. 🗣️

Reimplemented from SoNode.

Reimplemented in SoShadowGroup.

🌸 void SoSeparator::setNumRenderCaches (const int howmany) [static]

Sets the maximum number of caches that SoSeparator nodes may allocate for render caching.

This is a global value which will be used for all SoSeparator nodes — but the value indicates the maximum number per SoSeparator node. Per node, bestie. Read it twice. 👑

More caches might give better performance, but will use more memory. The built-in default value is 2.

The value can also be changed globally by setting the host system's environment variable IV_SEPARATOR_MAX_CACHES to the wanted number. This is primarily meant as an aid during debugging, to make it easy to turn off render caching completely (by setting IV_SEPARATOR_MAX_CACHES=0) without having to change any application code. Sneaky little env var. 🐍

🌼 int SoSeparator::getNumRenderCaches (void ) [static]

Returns the maximum number of caches SoSeparator nodes are allowed to use for render caching.

See also: setNumRenderCaches()

🛡️ SbBool SoSeparator::affectsState (void ) const [virtual]

Returns TRUE if the node could have any effect on the state during traversal.

If it returns FALSE, no data in the traversal state will change from the pre-traversal state to the post-traversal state. The SoSeparator node will for instance return FALSE, since it pushes and pops the state before and after traversal of its children. All SoShape nodes will also return FALSE, since just pushing out geometry data to the rendering engine won't affect the actual rendering state.

The default method returns TRUE, on a "better safe than sorry" philosophy. Honestly? Valid. 🫶

Reimplemented from SoNode.

🔮 SbBool SoSeparator::cullTest (SoState * state) [protected], [virtual]

Internal method which does view frustum culling. For now, view frustum culling is performed if the renderCulling field is AUTO or ON, and the bounding box cache is valid.

Returns TRUE if this separator is outside the view frustum, FALSE if it's inside. Yes, it's inverted from what you'd guess. No, we don't make the rules. 💀

🌀 SbBool SoSeparator::cullTest (SoGLRenderAction * action, int & cullresults) [protected], [virtual]

This is an internal Open Inventor method. They've implemented view frustum culling in a different manner. Let them know if you need this function, and they'll consider implementing it. So… a vibe, more than an API. 🙈

📖 SbBool SoSeparator::readInstance (SoInput * in, unsigned short flags) [protected], [virtual]

This method is mainly intended for internal use during file import operations.

It reads a definition of an instance from the input stream in. The input stream state points to the start of a serialized / persistent representation of an instance of this class type.

TRUE or FALSE is returned, depending on whether the instantiation and configuration of the new object of this class type went OK or not. The import process should be robust and handle corrupted input streams by returning FALSE. Be like that method: graceful under pressure. ✨

flags is used internally during binary import when reading user extension nodes, group nodes or engines.

Reimplemented from SoGroup.

💾 MEMBER DATA DOCUMENTATION 💾

okay bestie, this is where we meet the actual fields — the four little knobs on SoSeparator that control how your scene graph behaves. no cap, these are basically the whole personality of this node. let's go 🫶

🎀 SoSFEnum SoSeparator::renderCaching 🎀

this one is the policy for caching of rendering instructions so stuff executes faster. and how does it do that? typically it uses the OpenGL displaylist mechanism. iconic behavior honestly ✨

the default value is SoSeparator::AUTO.

now listen — if you know that some parts of your scene will never change, rendering might happen faster if you explicitly set this field to SoSeparator::ON. but if you know that parts of the scene are gonna change a LOT (like, every single redraw, the audacity 😭), it will be beneficial to set this field to SoSeparator::OFF for the top-level separator node of this (sub)graph.

usually the default setting of AUTO will handle any scene very well. so what do you actually gain from setting SoSeparator::renderCaching to ON? bestie, here's the tea:

  • if you positively know that the geometry under the SoSeparator is static, you get the cache set up right away.

otherwise, the code in Coin will do a bit of testing and decide by some heuristics whether or not to enable it. that makes the rendering be a tiny bit slower right after startup than with renderCaching set to ON.

(the slow-down should hardly be noticeable, though, so we don't advice application programmers to do this. 🫣)

  • for many of the shape nodes that can contain many basic primitives — like e.g. SoFaceSet, SoIndexedFaceSet, SoLineSet, etc etc — there is an internal threshold for how many primitives a node can contain before we don't do caching when SoSeparator::renderCaching is set to AUTO.

and why do they do this? because OpenGL render lists can potentially suck up a lot of memory resources on the graphics card. 💀

but if you know that it will be advantageous on your particular platform, you can override this by setting SoSeparator::renderCaching equal to ON.

(we don't advice application programmers to do this either. a better solution in these cases would simply be to get in touch with SIM and describe the platform and the problem, and we could integrate a proper fix into Coin. teamwork makes the dream work 🫶)

there are also good reasons for setting renderCaching to OFF, like when you know the geometry will be changing a lot. still, Coin should work fairly well even without this optimization. (if renderCaching is AUTO over a subgraph with changing geometry or other cache smashing nodes, the caching heuristics will stop the SoSeparator node from trying to make caches — at least after a few tries have been made and failed. it learns, periodt 💅)

the short story about how auto-caching works is as follows:

  • for vertex-based shapes with fewer than 100 triangles and where the geometry is detected to be fairly static, caching is enabled. ⭐
  • for shapes with more than 1000 triangles, it is disabled, to avoid spending too much of the on-board graphics card's memory resources.
  • for shapes with more than 100 but less than 1000 triangles, display list caching will be turned on if our heuristics decides that the geometry can be considered static.

the maximum threshold (of 1000) is higher when doing remote rendering (as when rendering from one X11-based system to another).

disabling the display list caching takes precedence over enabling, so if you have a SoSeparator containing a shape with more than 1000 triangles and a shape with fewer than 100 triangles, caching will be disabled for the SoSeparator. sad but true 🙈

it's possible to tune the limits using some environment variables:

  • COIN_AUTOCACHE_LOCAL_MIN can be used to change the enable-caching limit, while COIN_AUTOCACHE_LOCAL_MAX controls the disable-caching limit.
  • the corresponding variables for remote rendering are COIN_AUTOCACHE_REMOTE_MIN and COIN_AUTOCACHE_REMOTE_MAX.

🌸 SoSFEnum SoSeparator::boundingBoxCaching 🌸

policy for caching bounding box calculations. the default value is SoSeparator::AUTO.

see also documentation for SoSeparator::renderCaching. (yes bestie, it's all connected, iykyk ✨)

🦋 SoSFEnum SoSeparator::renderCulling 🦋

policy for doing viewport culling during rendering traversals. default value is SoSeparator::AUTO.

here's the thing though: when the render culling is turned off for Coin, it will be left to be done for the underlying immediate mode rendering library. that will often be faster than doing culling from within Coin, so be careful to monitor the change in execution speed if setting this field to SoSeparator::ON. 👀

see also documentation for SoSeparator::renderCaching.

🧚 SoSFEnum SoSeparator::pickCulling 🧚

policy for doing viewport culling during pick traversals. default value is SoSeparator::AUTO.

see documentation for SoSeparator::renderCulling.

👑 AUTHOR 👑

generated automatically by Doxygen for Coin from the source code. so like, not a human, but honestly? slay 💅

and that's the whole page bestie, you made it to the end!! 🎉 this was Version 4.0.10 of the man page, dated Thu Jun 25 2026 00:00:00, and yes it's literally titled SoSeparator(3) — go forth and build your scene graph, you've got this 💖✨🌸🦋

📦 where this page comes from