SoPath(3)

📦 version 2.5.0, in fedora 43, fedora 44

💖 SoPath(3) — Library Functions Manual 💖

okay so bestie, this is the SoPath manual page, and it's literally the container class for traversal path descriptions. Part 1, so buckle up. ✨

🌸 NAME 🌸

SoPath — The SoPath class is a container class for traversal path descriptions.

🎀 SYNOPSIS 🎀

#include <Inventor/SoPath.h>

Inherits SoBase.

Inherited by SoFullPath, and SoNodeKitPath.

✨ Public Member Functions ✨

  • SoPath (const int approxlength=4)
  • SoPath (SoNode *const head)
  • SoPath (const SoPath &rhs)
  • SoPath & operator= (const SoPath &rhs)
  • virtual SoType getTypeId (void) const
  • void setHead (SoNode *const head)
  • SoNode * getHead (void) const
  • void append (const int childindex)
  • void append (SoNode *const node)
  • void append (const SoPath *const frompath)
  • void push (const int childindex)
  • void pop (void)
  • SoNode * getTail (void) const
  • SoNode * getNode (const int index) const
  • SoNode * getNodeFromTail (const int index) const
  • int getIndex (const int index) const
  • int getIndexFromTail (const int index) const
  • int getLength (void) const
  • void truncate (const int length)
  • int findFork (const SoPath *const path) const
  • int findNode (const SoNode *const node) const
  • SbBool containsNode (const SoNode *const node) const
  • SbBool containsPath (const SoPath *const path) const
  • SoPath * copy (const int startfromnodeindex=0, int numnodes=0) const
  • void insertIndex (SoNode *const parent, const int newindex)
  • void removeIndex (SoNode *const parent, const int oldindex)
  • void replaceIndex (SoNode *const parent, const int index, SoNode *const newchild)
  • SbBool isRelevantNotification (SoNotList *const l) const
  • virtual void write (SoWriteAction *action)

🫶 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)
  • virtual void startNotify (void)
  • virtual void notify (SoNotList *l)
  • void addAuditor (void *const auditor, const SoNotRec::Type type)
  • void removeAuditor (void *const auditor, const SoNotRec::Type type)
  • const SoAuditorList & getAuditors (void) const
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=0)
  • SbBool shouldWrite (void)
  • void assertAlive (void) const

👑 Static Public Member Functions 👑

  • static void initClass (void)
  • static SoType getClassTypeId (void)
  • static SoPath * getByName (const SbName name)
  • static int getByName (const SbName name, SoPathList &l)

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

🧚 Protected Member Functions 🧚

  • virtual ~SoPath ()
  • void auditPath (const SbBool flag)

💜 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

🍓 Friends 🍓

  • class SoFullPath
  • class SoNodeKitPath
  • class SoAction
  • class SoTempPath
  • SbBool operator== (const SoPath &lhs, const SoPath &rhs)
  • SbBool operator!= (const SoPath &lhs, const SoPath &rhs)

⭐ Additional Inherited Members ⭐

Protected Types inherited from SoBase

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

Static Protected Member Functions inherited from SoBase

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

💅 Detailed Description 💅

The SoPath class is a container class for traversal path descriptions.

So like, SoPath objects are holding a list of SoNode pointers and a list of child indices. The indices are there because sometimes a node uses the same node as a child multiple times, and we gotta disambiguate that situation. Periodt.

Paths can be exported and imported to/from file, just like other SoBase derived objects. If you wanna know the file format, go read the docs on the write() method. That's where the tea is.

🎀 Constructor & Destructor Documentation 🎀

SoPath::SoPath (const int approxlength = 4)

The default constructor, hey. approxlength is you telling it ahead of time how long the path is gonna be, so it doesn't have to reallocate a million times. Lowkey helpful.

Referenced by SoNodeKitPath::append(), append(), containsPath(), copy(), findFork(), getByName(), getByName(), getLength(), operator!=, operator=(), operator==, SoNodeKitPath::SoNodeKitPath(), and SoPath().

SoPath::SoPath (SoNode *const head)

A constructor. The argument is set as the head (and only) node of the path. Slay.

References setHead().

SoPath::SoPath (const SoPath & rhs)

Copy constructor. Not part of the original Open Inventor API.

References operator=(), and SoPath().

SoPath::~SoPath (void ) [protected], [virtual]

The destructor is protected as destruction of SoPath instances happens through unref() (as for all objects derived from classes inheriting SoBase). So don't just delete it, bestie.

References truncate().

✨ Member Function Documentation ✨

SoPath & SoPath::operator= (const SoPath & rhs)

Assignment operator, copies the rhs path into this. Not part of the original Open Inventor API.

References SoChildList::addPathAuditor(), SoPath(), and SoBase::startNotify().

Referenced by append(), and SoPath().

SoType SoPath::getTypeId (void ) const [virtual]

Returns the type identification of an object derived from a class inheriting SoBase. This is used for run-time type checking and "downward" casting. It's basically the vibe check for types.

Usage example:

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

For application programmers wanting to extend the library with new nodes, engines, nodekits, draggers or others: this method needs to be overridden in all subclasses. This is typically done as part of setting up the full type system for extension classes, which is usually 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.

For more information on writing Coin extensions, see the class documentation of the toplevel superclasses for the various class groups.

Implements SoBase.

Referenced by SoChildList::removePathAuditor().

void SoPath::setHead (SoNode *const node)

This method sets the head of the path to node. If the object already has a path set, it will be truncated. Bye old path.

References append(), and truncate().

Referenced by SoNodeKitPath::append(), append(), and SoPath().

SoNode * SoPath::getHead (void ) const

This method returns the head of the path, or NULL if the path is empty.

Referenced by append(), SoPathSensor::attach(), SoSelection::findPath(), isRelevantNotification(), SoMFPath::notify(), SoSFEngine::referencesCopy(), SoSFNode::referencesCopy(), SoSFPath::referencesCopy(), SoShape::shouldGLRender(), and write().

void SoPath::append (const int childindex)

This function appends the childindex child of the path's tail to the end of the path. It can only be used after the head is set. Set that head first, bestie.

References append(), SbPList::getLength(), and SoDebugError::post().

Referenced by SoNodeKitPath::append(), append(), append(), append(), copy(), SoBaseKit::createPathToAnyPart(), push(), replaceIndex(), and setHead().

void SoPath::append (SoNode *const node)

This function adds node to the end if it is a child of the current tail. If path is empty, this is equivalent to calling setHead().

References append(), SbPList::find(), SoNode::getChildren(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::post(), and setHead().

void SoPath::append (const SoPath *const frompath)

This method appends the path to the end of the path if the head of frompath is either the tail of the path or a child of the path's tail. If the head of frompath is used multiple times as a child of the path tail, the lowest child index is used.

References append(), SoNode::getChildren(), getHead(), SbPList::getLength(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), operator=(), SoDebugError::post(), and SoPath().

void SoPath::push (const int childindex) [inline]

This method pushes the child at childindex on the tail on the path.

References append().

void SoPath::pop (void ) [inline]

This method pops the tail off the path.

References truncate().

SoNode * SoPath::getTail (void ) const

This method returns the tail node of the path.

References getLength(), and SoDebugError::postWarning().

Referenced by SoBoxHighlightRenderAction::apply(), SoLineHighlightRenderAction::apply(), SoClipPlaneManip::replaceNode(), SoDirectionalLightManip::replaceNode(), SoPointLightManip::replaceNode(), SoSpotLightManip::replaceNode(), and SoTransformManip::replaceNode().

SoNode * SoPath::getNode (const int index) const

This method returns the node at index in the path, counted from 0 at the head.

References SoDebugError::post().

Referenced by SoAction::apply(), SoBaseKit::getPartString(), isRelevantNotification(), and SoAction::switchToPathTraversal().

SoNode * SoPath::getNodeFromTail (const int index) const

This method returns the node at index in the path, counting from the tail. The index argument should be zero or positive.

References getLength(), and SoDebugError::post().

int SoPath::getIndex (const int index) const

This method returns the child index of the node at index in the path.

References SoDebugError::post().

Referenced by isRelevantNotification(), and SoAction::usePathCode().

int SoPath::getIndexFromTail (const int index) const

This method returns the child index of the node at index in the path, counting from the tail. The index argument should be zero or positive.

References getLength(), and SoDebugError::post().

int SoPath::getLength (void ) const

Bestie, this one hands you the number of nodes in the path. But heads up 👀 — only the "visible" nodes get counted. Hidden nodes like the ones inside nodekits? Not invited to this party, they don't count. 💅

Refs it leans on: SoPath()

Who leans on it: SoAction::apply(), getIndexFromTail(), getNodeFromTail(), and getTail().

void SoPath::truncate (const int length)

This chops the path down to length, okay? So literally everything in the path list from index length and onwards gets yeeted out of the path list. Gone. Bye. 🫶

Refs it leans on: truncate()

Who leans on it: SoFullPath::pop(), SoNodeKitPath::pop(), pop(), removeIndex(), replaceIndex(), setHead(), SoNodeKitPath::truncate(), truncate(), and ~SoPath().

int SoPath::findFork (const SoPath *const path) const

Returns the index of the last node that's identical in both paths ✨. And if the two paths don't even start on the same node? You get -1. Not compatible, not slay, no overlap. 💀

Refs it leans on: SbList< Type >::getArrayPtr(), and SoPath()

Who leans on it: SoPathList::uniquify().

int SoPath::findNode (const SoNode *const node) const

Gives you the index of node if it's found in the full path — and yes, that includes the normally hidden parts too 🙈 — or -1 if it's just not there.

Ngl, this method is not part of the original Open Inventor API. She's a Coin exclusive, iykyk.

Who leans on it: containsNode(), containsPath(), SoSelection::copyFromThis(), SoHandleBoxDragger::dragStart(), SoTabPlaneDragger::dragStart(), SoTrackballDragger::dragStart(), SoTransformerDragger::dragStart(), SoBaseKit::getPartString(), SoSelection::handleEvent(), insertIndex(), SoSelection::performToggleSelection(), removeIndex(), replaceIndex(), and SoDragger::updateDraggerCache().

SbBool SoPath::containsNode (const SoNode *const node) const

Returns TRUE if node is somewhere in the full path (hidden parts absolutely included, we don't gatekeep 🙌), and FALSE if it isn't.

Refs it leans on: findNode()

Who leans on it: SoNodeKitPath::containsNode(), SoBaseKit::createPathToAnyPart(), and SoBaseKit::rayPick().

SbBool SoPath::containsPath (const SoPath *const path) const

Returns TRUE if path is contained inside the path, FALSE if it's not. Simple as that, periodt. 💖

Refs it leans on: findNode(), SbList< Type >::getArrayPtr(), and SoPath()

Who leans on it: SoGetBoundingBoxAction::checkResetAfter(), SoGetBoundingBoxAction::checkResetBefore(), SoEventCallback::handleEvent(), SoLocateHighlight::handleEvent(), SoVRMLDragSensor::handleEvent(), SoVRMLTouchSensor::handleEvent(), SoAction::pushCurPath(), SoDragger::shouldGrabBasedOnSurrogate(), and SoAction::usePathCode().

SoPath * SoPath::copy (const int startfromnodeindex = 0, int numnodes = 0) const

Returns a copy of the path, starting at startfromnodeindex with length numnodes. And if numnodes is 0 (which is the default), the whole thing gets copied to the end. 🎀

CRITICAL, bestie, listen: the returned SoPath instance comes with an initial reference count of 0. It is the caller's responsibility to ref() and unref() it according to use. Do not forget this, I am begging 😭

Refs it leans on: append(), SoDebugError::post(), and SoPath()

Who leans on it: SoSelection::copyFromThis(), SoBaseKit::createPathToAnyPart(), SoMFPath::fixCopy(), SoSFPath::fixCopy(), SoAnnotation::GLRenderBelowPath(), SoExtSelection::GLRenderBelowPath(), SoAnnotation::GLRenderInPath(), SoLocateHighlight::handleEvent(), SoVRMLDragSensor::handleEvent(), SoVRMLTouchSensor::handleEvent(), SoNode::search(), SoEventCallback::setPath(), SoPickedPoint::SoPickedPoint(), and SoSurroundScale::updateMySurroundParams().

SoPath * SoPath::getByName (const SbName name) [static]

A static method for retrieving an SoPath by its name 💫. You get back the last registered SoPath with that name — or NULL if no SoPath by that name exists. No path, no vibes.

Refs it leans on: SoBase::getNamedBase(), SoBase::SoBase(), and SoPath().

int SoPath::getByName (const SbName name, SoPathList & l) [static]

Also static, but this one's the collector ✨ — it finds all the paths with a given name and appends them to the l list. The return value is the number of SoPath instances with that name that got found. Obsessed with the efficiency honestly.

Refs it leans on: SoPathList::append(), SoBase::getNamedBases(), and SoPath().

void SoPath::insertIndex (SoNode *const parent, const int newindex)

This gets called when a node in the path chain has a child added, so it can update the index of that child. 🦋

newindex is the index of the child that was inserted. And if newindex is lower than the index value of the child node stored in the path, the path gets updated accordingly. Adaptive queen.

Refs it leans on: findNode(), and SoDebugError::postInfo().

void SoPath::removeIndex (SoNode *const parent, const int oldindex)

Called when a node in the path chain has a child removed, so it can update the index of that child too. 💅

oldindex was the index of the removed child. If oldindex is lower than or equal to the index value of the child node stored in the path, the path gets updated accordingly.

Refs it leans on: findNode(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::post(), SoDebugError::postInfo(), and truncate().

void SoPath::replaceIndex (SoNode *const parent, const int index, SoNode *const newchild)

Called when a node newchild replaces a node in the path 🔁. index is the position of the child that got replaced. New node, same slot, main character energy.

Refs it leans on: append(), findNode(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::postInfo(), and truncate().

SbBool SoPath::isRelevantNotification (SoNotList *const l) const

Returns TRUE if the notification chain l is gonna affect the path, and here's the tea on when that happens ☕: l affects the path either in the path (the notification started on a field in a node that's in the path), or off the path (the notification started in a non-separator node that's to the left of the path's node). Either way, it matters. 🫶

Refs it leans on: SbPList::find(), SoNotRec::getBase(), SoNode::getChildren(), getHead(), getIndex(), SoNotList::getLastRec(), getNode(), SoNotRec::getPrevious(), SoNotRec::getType(), SoBase::isOfType(), and SoBase::SoBase().

void SoPath::write (SoWriteAction * action) [virtual]

This method writes out the contents of an SoPath. ✍️

A path gets written like this:

Path {
  HEAD-NODE-OF-SUBGRAPH
  NUMBER-OF-INDICES
  INDEX0
  INDEX1
  ...
}
[The rest of the documentation for this method only explains the reason behind a mismatch in behavior between the original Open Inventor and Coin. Don't read it if you're not taking a particular interest. (Short version: we do SoPath export in a somewhat more inefficient way to avoid the potential for bugs).]

Note that unlike Open Inventor, we write the complete subgraph below the head node. Only writing the parts of the subgraph affecting the state for nodes within the path is error prone if a subgraph is written out as part of path before it is written out "properly". 💀

Consider writing a scene graph which looks like this (in memory):

DEF top_sep Separator {
  Cone { }
  DEF a_sphere Sphere { }
  Cube { }
}
DEF path_switch PathSwitch {
  path Path {
    ...path from "top_sep" to "a_sphere"...
  }
}

..if we now do:

SoSeparator * root = new SoSeparator;
root->addChild([ptr to path_switch]);
root->addChild([ptr to top_sep]);
SoWriteAction wa;
wa.apply(root);

..we would get the scene graph exported like this:

Separator {
  DEF path_switch PathSwitch {
    path Path {
      DEF top_sep Separator {
        DEF a_sphere Sphere {
        }
      }
      1
      0
    }
  }
  USE top_sep
}

..and as you can see, both the Cone and the Cube nodes has vanished, as they was not important for the part per se, and not written as part of it. 😭 Not the glow-up they deserved.

This is why we do full subgraph export for head nodes in paths. 💅

Refs it leans on: SoBase::addWriteReference(), SoWriteAction::continueToApply(), getHead(), SoWriteAction::getOutput(), SoOutput::getStage(), SoBase::hasMultipleWriteRefs(), SoOutput::indent(), SoOutput::isBinary(), SoOutput::write(), SoBase::writeFooter(), and SoBase::writeHeader().

void SoPath::auditPath (const SbBool flag) [protected]

Sets whether or not to audit the nodes in the path to detect changes. 🔍 Protected, so she's for the internal girlies only.

SbBool operator== (const SoPath & lhs, const SoPath & rhs) [friend]

Compares the contents of path lhs and path rhs, and returns TRUE if they're equal. Twin flames detected 💖✨

Refs it leans on: SbList< Type >::getArrayPtr(), operator==, and SoPath()

Who leans on it: operator==.

SbBool operator!= (const SoPath & lhs, const SoPath & rhs) [friend]

Returns TRUE if paths lhs and rhs do not contain the same nodes in the same order. Different order, different nodes, different path, bestie. 🙈

Refs it leans on: operator!=, and SoPath()

Who leans on it: operator!=.

👑 Author 👑

Generated automatically by Doxygen for Coin from the source code. She was born this way, no cap. 🤖💅

Okay that's the whole page, we ate and left absolutely no crumbs 🍓✨. This lil masterpiece comes from Coin, Version 2.5.0, and it's filed under SoPath(3). Go forth and slay your scene graphs, bestie 💖🎀🦋

📦 where this page comes from