SoSeparator(3)

📦 version 2.5.0, in fedora 43, fedora 44

🦋 NAME 🦋

okay so bestie, this is the page for SoSeparator from the Library Functions Manual (section 3, iykyk 💅).

The SoSeparator class is a state-preserving group node. that's the whole vibe. she groups things AND she protects the state while she does it. main character energy fr fr. ✨

🌸 SYNOPSIS 🌸

#include <Inventor/nodes/SoSeparator.h>

Inherits SoGroup.

Inherited by SoAnnotation, SoGeoSeparator, SoLocateHighlight, SoSelection, and SoShadowGroup. (she's got a whole friend group 🫶)

🎀 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
    }

💖 Public Member Functions 💖

  • 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

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=0) const
  • virtual void grabEventsSetup (void)
  • virtual void grabEventsCleanup (void)
  • virtual void startNotify (void)
  • uint32_t 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=0)
  • 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 *in)
  • void get (SbString &fielddata, SoOutput *out)
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval)
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=0)
  • SbBool getIsBuiltIn (void) 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
  • 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)
  • 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)

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)
  • static void initClasses (void)
  • static uint32_t 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)
  • static SoType getClassTypeId (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)
  • static SoType getClassTypeId (void)
  • 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 *in, SoBase *&base, SoType expectedtype)
  • static void setInstancePrefix (const SbString &c)
  • static void setTraceRefs (SbBool trace)
  • static SbBool getTraceRefs (void)
  • static SbBool connectRoute (SoInput *in, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
  • static SbBool readRoute (SoInput *in)

💅 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)

Protected Member Functions inherited from SoNode

  • SoNode (void)
  • virtual ~SoNode ()

Protected Member Functions inherited from SoFieldContainer

  • SoFieldContainer (void)
  • ~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)

🫶 Additional Inherited Members 🫶

  • 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: uint32_t uniqueId
  • Protected Attributes inherited from SoFieldContainer: SbBool isBuiltIn
  • Static Protected Attributes inherited from SoNode: static uint32_t nextUniqueId = 0, static int nextActionMethodIndex = 0

💜 Detailed Description 💜

The SoSeparator class is a state-preserving group node. 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. like she's literally holding the door open and then closing it behind you, no mess left in the hallway. iconic behaviour tbh. ✨

SoSeparator nodes also provides options for traversal optimalization through the use of caching. (yes bestie, "optimalization" — that's how it's spelled here, we don't edit the original 😌)

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 optimalizations to do in SoSeparator nodes. There are two types of settings available: caching policies or culling policies. See doumentation of fields. (again — "doumentation" is what the original says, we're keeping it exactly, no cap 🙈)

Enumerator

  • OFF — No caching.
  • ON — Always try to cache state.
  • AUTO — Use heuristics to try to figure out the optimal caching policy.

💖 Constructor & Destructor Documentation 💖

🌸 SoSeparator::SoSeparator (void) 🌸

Bestie, this is the default constructor. That's it, that's the whole vibe. It just... exists. Iconic behaviour, honestly.

Referenced by getFieldData().

🌸 SoSeparator::SoSeparator (const int nchildren) 🌸

Okay so this is the constructor where you get to say something. The argument nchildren should be the approximate number of children you're expecting to insert below this node.

And before you come for me — the number does not need to be exact. It's literally just a lil hint so the memory resource allocation can be cuter and more efficient about it. It's giving "reserve a table, we might bring friends." 🍓

References SoGroup::SoGroup().

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

The destructor, protected and virtual, as the ancestors intended. It frees the resources used to implement caches. Clean up your mess, queen. 🧚

✨ Member Function Documentation ✨

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

Returns the type identification of an object derived from a class inheriting SoBase. This is what makes run-time type checking and "downward" casting possible. iykyk.

Usage example, no cap:

void foo(SoNode * node)
{
  if (node->getTypeId() == SoFile::getClassTypeId()) {
    SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
  }
  else if (node->getTypeId().isOfType(SoGroup::getClassTypeId())) {
    SoGroup * group = (SoGroup *)node;  // safe downward cast, knows the type
  }
}

Now for the application programmers out there who wanna extend the library with new nodes, engines, nodekits, draggers or whatever else — listen up: this method needs to be overridden in all subclasses. That's usually done as part of setting up the full type system for extension classes, which is normally accomplished by using the pre-defined macros available through, for instance, Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h (for engine classes) and so on. Slay.

Want more info on writing Coin extensions? Go read the class documentation of the toplevel superclasses for the various class groups. Periodt.

  • Reimplemented from SoGroup.
  • Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, SoSelection, SoShadowGroup, and SoWWWAnchor.
  • Referenced by GLRenderBelowPath().

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

Hands you back a pointer to the class-wide field data storage object for this instance. And if there are no fields present? It returns NULL. Respect the honesty. 💅

  • Reimplemented from SoGroup.
  • Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, SoSelection, SoShadowGroup, and SoWWWAnchor.
  • References SoSeparator().

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

This function performs the typical operation of a node for any action. It's the main character doing main character things. ✨

  • Reimplemented from SoGroup.
  • References SoGroup::doAction(), SoAction::getState(), SoState::pop(), and SoState::push().
  • Referenced by audioRender(), getPrimitiveCount(), handleEvent(), rayPick(), and search().

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

Action method for the SoGLRenderAction.

This one gets called during rendering traversals. Nodes that influence the rendering state in any way, or that wanna throw geometry primitives at OpenGL, override this method. Go off, geometry. 🔥

  • Reimplemented from SoGroup.
  • Reimplemented in SoAnnotation.
  • References SoAction::getCurPathCode(), GLRenderBelowPath(), and GLRenderInPath().

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

Okay so history lesson, bestie: 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 (path code is guaranteed not to change). To be compatible with SGI's Inventor (and thereby also TGS') we have chosen to follow their implementation in this respect. Living in the past but make it functional. 😭

And here's the tea: SoSeparator::GLRenderBelowPath() does not traverse its children using SoChildList::traverse(). Nope — it calls GLRenderBelowPath() directly for all its children. Cutting out the middleman, as she should.

  • Reimplemented from SoNode.
  • Reimplemented in SoAnnotation, SoExtSelection, SoGeoSeparator, SoLocateHighlight, and SoShadowGroup.
  • References SoGLRenderAction::abortNow(), AUTO, SoGroup::children, cullTest(), SoBase::getName(), getNumRenderCaches(), SoAction::getState(), getTypeId(), SoNode::GLRenderBelowPath(), SoAction::hasTerminated(), SoState::isCacheOpen(), OFF, SoState::pop(), SoAction::popCurPath(), SoAction::popPushCurPath(), SoDebugError::post(), SoDebugError::postInfo(), SoState::push(), SoAction::pushCurPath(), renderCaching, and SoNode::SoNode().
  • Referenced by GLRender(), SoAnnotation::GLRenderBelowPath(), SoGeoSeparator::GLRenderBelowPath(), SoLocateHighlight::GLRenderBelowPath(), and GLRenderInPath().

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

Implements the SoAction::IN_PATH traversal method for the rendering action. Very "I know my way around" energy. 🫶

  • Reimplemented from SoNode.
  • Reimplemented in SoAnnotation, SoGeoSeparator, SoLocateHighlight, and SoShadowGroup.
  • References SoGLRenderAction::abortNow(), SoNode::affectsState(), SoGroup::children, SoAction::getPathCode(), SoAction::getState(), GLRenderBelowPath(), SoNode::GLRenderInPath(), SoNode::GLRenderOffPath(), SoAction::hasTerminated(), SoState::pop(), SoAction::popCurPath(), SoState::push(), SoAction::pushCurPath(), and SoNode::SoNode().
  • Referenced by GLRender(), SoAnnotation::GLRenderInPath(), SoGeoSeparator::GLRenderInPath(), and SoLocateHighlight::GLRenderInPath().

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

Implements the SoAction::OFF_PATH traversal method for the rendering action. She's off the path but still working, and that's the dedication we love to see. 🌈

  • 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. Free info, bestie, take it. 🎀

  • Reimplemented from SoGroup.
  • Reimplemented in SoGeoSeparator.
  • References SoGroup::callback(), cullTest(), SoAction::getState(), SoState::pop(), and SoState::push().
  • Referenced by SoGeoSeparator::callback().

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

Action method for the SoGetBoundingBoxAction.

Calculates 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. Basically: "this is my space, and here's the middle of it." 💜

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.
  • References boundingBoxCaching, SoGetBoundingBoxAction::extendBy(), SoGroup::getBoundingBox(), SoGetBoundingBoxAction::getCenter(), SoAction::getCurPathCode(), SoAction::getState(), SoGetBoundingBoxAction::getXfBoundingBox(), SoGetBoundingBoxAction::isCenterSet(), SbBox3f::isEmpty(), SoGetBoundingBoxAction::isInCameraSpace(), SoGetBoundingBoxAction::isResetPath(), SbBox3f::makeEmpty(), OFF, SoState::pop(), SoState::push(), SoGetBoundingBoxAction::resetCenter(), and SoGetBoundingBoxAction::setCenter().
  • Referenced by SoGeoSeparator::getBoundingBox().

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

Action method for SoGetMatrixAction.

Updates the action by accumulating with the transformation matrix of this node (if any). If there's no matrix, well, nothing to accumulate. 🙈

  • Reimplemented from SoGroup.
  • Reimplemented in SoGeoSeparator.
  • References SoGroup::children, SoAction::getPathCode(), SoAction::getState(), SoState::pop(), and SoState::push().

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

Action method for SoHandleEventAction.

Inspects the event data from action, and processes it if it's something which this node should react to. Not everything is about you, node. But when it is, you handle it. 💅

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.
  • References doAction().
  • Referenced by SoExtSelection::handleEvent(), SoLocateHighlight::handleEvent(), and SoSelection::handleEvent().

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

Action method for SoRayPickAction.

Checks the ray specification of the action and tests for intersection with the data of the node. Like a vibe check but for rays. ⭐

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

  • Reimplemented from SoNode.
  • Reimplemented in SoGeoSeparator.
  • References doAction(), SoAction::getState(), SoRayPickAction::hasWorldSpaceRay(), OFF, and pickCulling.
  • Referenced by SoGeoSeparator::rayPick().

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

Action method for SoSearchAction.

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 — if any of the requested criteria is a miss, the search is not deemed successful for the node. All or nothing, babe. No partial credit.

See also: SoSearchAction

  • Reimplemented from SoGroup.
  • References doAction(), SoSearchAction::isFound(), and SoNode::search().

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

Action method for the SoGetPrimitiveCountAction.

Calculates the number of triangle, line segment and point primitives for the node and adds these to the counters of the action. Math but make it fashionable. 🍓

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.
  • References doAction().
  • Referenced by SoGeoSeparator::getPrimitiveCount().

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

Action method for SoAudioRenderAction.

Does common processing for SoAudioRenderAction action instances. Serving looks and sound. 🎧

  • Reimplemented from SoGroup.
  • References SoGroup::doAction(), doAction(), SoAction::getPathCode(), SoAction::getState(), SoState::pop(), and SoState::push().

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

Notifies all auditors for this instance when changes are made. She's telling everyone, and honestly? They should know. 📣

  • Reimplemented from SoNode.
  • Reimplemented in SoShadowGroup.
  • References SoFieldContainer::notify().
  • Referenced by SoShadowGroup::notify().

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

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

Heads up: this is a global value which will be used for all SoSeparator nodes, but the value indicates the maximum number per SoSeparator node. Global setting, local meaning. Make it make sense. 💀

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

okay so you can also flip that value globally — no code changes, no rebuild, nothing — just set the host system's environment variable IV_SEPARATOR_MAX_CACHES to whatever number you're feeling. It's primarily meant as a debugging aid, so it's super easy to turn rendercaching all the way off (just set IV_SEPARATOR_MAX_CACHES=0) without touching a single line of application code. 🎀

int SoSeparator::getNumRenderCaches(void) [static]

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

See also: setNumRenderCaches()

Referenced by GLRenderBelowPath().

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

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

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

The default method returns TRUE, working on a "better safe than sorry" philosophy. 🙈

Reimplemented from SoNode.

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

Internal method that does view frustum culling. As it stands right now, view frustum culling happens 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. 🦋

References SbBox3f::isEmpty(), OFF, and renderCulling.

Referenced by callback(), and GLRenderBelowPath().

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

This one is an internal Open Inventor method. In Coin we've implemented view frustum culling in a different manner, so this is basically not the vibe we went with. If you need this function for real, let us know and we'll consider implementing it. 💜

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 / persistant representation of an instance of this class type.

You get TRUE or FALSE back, depending on whether the instantiation and configuration of the new object of this class type went okay or not. The import process should be robust and handle corrupted input streams by returning FALSE. 😭

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

Reimplemented from SoGroup.

References SoGroup::readInstance().

✨ MEMBER DATA DOCUMENTATION ✨

SoSFEnum SoSeparator::renderCaching

Policy for caching of rendering instructions so execution goes faster. This will typically use the OpenGL displaylist mechanism. 🔥

Default value is SoSeparator::AUTO.

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. If, on the other hand, you know that parts of the scene will change a lot (like, every single redraw), then it's actually 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. The advantages you can get from setting SoSeparator::renderCaching to ON are:

  • 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 via some heuristics whether or not to enable it. That makes rendering a tiny bit slower right after start-up than it would be with renderCaching set to ON.

(The slow-down should hardly be noticeable though, so we don't advise 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's an internal threshold for how many primitives a node can contain before we don't do caching when SoSeparator::renderCaching is set to AUTO.

The reason we do this is because OpenGL renderlists can potentially suck up a lot of memory resources on the graphics card. 💀

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

(We don't advise 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.) 🙏

There are good reasons for setting renderCaching to OFF, like when you know the geometry will be changing a lot. Still, Coin should work fairly well without even this optimization. (If renderCaching is AUTO over a sub-graph 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.)

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 trangles, it is disabled, to avoid spending too much of the on-board graphics card's memory resources. 💸
  • For shapes with between 100 and 1000 shapes, displaylist 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 displaylist caching takes precedence over enabling, so if you have an SoSeparator with a shape with more than 1000 triangles and a shape with fewer than 100 triangles, caching will be disabled for the SoSeparator.

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.

Referenced by GLRenderBelowPath().

SoSFEnum SoSeparator::boundingBoxCaching

Policy for caching bounding box calculations. Default value is SoSeparator::AUTO. 📦

See also: documentation for SoSeparator::renderCaching.

Referenced by getBoundingBox().

SoSFEnum SoSeparator::renderCulling

Policy for doing viewport culling during rendering traversals. Default value is SoSeparator::AUTO. 👀

When the render culling is turned off for Coin, it'll 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 you set this field to SoSeparator::ON.

See also: documentation for SoSeparator::renderCaching.

Referenced by cullTest().

SoSFEnum SoSeparator::pickCulling

Policy for doing viewport culling during pick traversals. Default value is SoSeparator::AUTO. 🫶

See documentation for SoSeparator::renderCulling.

Referenced by rayPick().

✨ AUTHOR ✨

Generated automatically by Doxygen for Coin from the source code. 🤖

and that's the whole page bestie — this was Coin, Version 2.5.0, page SoSeparator(3), and yes it was auto-generated by Doxygen straight from the source code. slay. 💅✨

📦 where this page comes from