SoPath(3)

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

🦋 SoPath(3) — Coin's traversal-path queen 🦋

okay so bestie, this is the SoPath(3) page from the Coin manual, and it's giving iconic path-container energy. Buckle up, because this one is long and it comes in parts. Part 1 starts right here. 💖

🎀 NAME 🎀

SoPath — the SoPath class is a container class for traversal path descriptions. periodt.

🌈 SYNOPSIS 🌈

#include <Inventor/SoPath.h>

Inherits SoBase.

Inherited by SoFullPath, and SoNodeKitPath.

💅 Public Member Functions 💅

  • SoPath (const int approxlength=4) — constructor, with a little pre-sizing hint.
  • SoPath (SoNode *const head) — constructor from a head node.
  • SoPath (const SoPath &rhs) — copy constructor.
  • SoPath & operator= (const SoPath &rhs) — assignment operator.
  • virtual SoType getTypeId (void) const — Returns the type identification of an object derived from a class inheriting SoBase. This is used for runtime type checking and downward"casting. (yes, that quote is literally in there, no cap)
  • void setHead (SoNode *const head) — set the head node.
  • SoNode * getHead (void) const — get the head node.
  • void append (const int childindex) — append a child index.
  • void append (SoNode *const node) — append a node.
  • void append (const SoPath *const frompath) — append from another path.
  • void push (const int childindex) — push a child index.
  • void pop (void) — pop the last bit off.
  • SoNode * getTail (void) const — get the tail node.
  • SoNode * getNode (const int index) const — get the node at an index.
  • SoNode * getNodeFromTail (const int index) const — get a node counting from the tail.
  • int getIndex (const int index) const — get the index at an index.
  • int getIndexFromTail (const int index) const — get an index counting from the tail.
  • int getLength (void) const — get the length.
  • void truncate (const int length) — cut it down to length.
  • int findFork (const SoPath *const path) const — find where two paths fork.
  • int findNode (const SoNode *const node) const — find a node in the path.
  • SbBool containsNode (const SoNode *const node) const — does it contain this node?
  • SbBool containsPath (const SoPath *const path) const — does it contain this path?
  • SoPath * copy (const int startfromnodeindex=0, int numnodes=0) const — make a copy, optionally from a starting index and for a number of nodes.
  • void insertIndex (SoNode *const parent, const int newindex) — insert an index under a parent.
  • void removeIndex (SoNode *const parent, const int oldindex) — remove an index under a parent.
  • void replaceIndex (SoNode *const parent, const int index, SoNode *const newchild) — replace an index under a parent with a new child.
  • SbBool isRelevantNotification (SoNotList *const l) const — is this notification relevant?
  • virtual void write (SoWriteAction *action) — write it out.

🌸 Public Member Functions inherited from SoBase 🌸

  • void ref (void) const — bump the ref count.
  • void unref (void) const — drop the ref count.
  • void unrefNoDelete (void) const — drop the ref count without deleting.
  • int32_t getRefCount (void) const — how many refs?
  • void touch (void) — touch it, make it notify.
  • SbBool isOfType (SoType type) const — Returns TRUE if the type of this object is either of the same type or inherited from type.
  • virtual SbName getName (void) const — get the name.
  • virtual void setName (const SbName &newname) — set the name.
  • virtual void startNotify (void) — start the notification party.
  • virtual void notify (SoNotList *l) — notify.
  • void addAuditor (void *const auditor, const SoNotRec::Type type) — add an auditor.
  • void removeAuditor (void *const auditor, const SoNotRec::Type type) — remove an auditor.
  • const SoAuditorList & getAuditors (void) const — get the auditor list.
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE) — add a write reference.
  • SbBool shouldWrite (void) — should this be written?
  • void assertAlive (void) const — assert it's alive.

✨ Static Public Member Functions ✨

  • static void initClass (void) — Sets up 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 SoPath * getByName (const SbName name) — look one up by name.
  • static int getByName (const SbName name, SoPathList &l) — look some up by name into a list.

💜 Static Public Member Functions inherited from SoBase 💜

  • static void initClass (void) — Sets up 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) — add a name.
  • static void removeName (SoBase *const base, const char *const name) — remove a name.
  • static void incrementCurrentWriteCounter (void) — bump the current write counter.
  • static void decrementCurrentWriteCounter (void) — drop the current write counter.
  • static SoBase * getNamedBase (const SbName &name, SoType type) — get a named base.
  • static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type) — get named bases into a list.
  • static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype) — read one in.
  • static void setInstancePrefix (const SbString &c) — set the instance prefix.
  • static void setTraceRefs (SbBool trace) — turn ref tracing on or off.
  • static SbBool getTraceRefs (void) — is ref tracing on?
  • static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname) — connect a route.
  • static SbBool readRoute (SoInput *input) — read a route.

🫶 Protected Member Functions 🫶

  • virtual ~SoPath () — the destructor.
  • void auditPath (const SbBool flag) — set the audit-path flag.

💖 Protected Member Functions inherited from SoBase 💖

  • SoBase (void) — constructor.
  • virtual ~SoBase () — destructor.
  • virtual void destroy (void) — destroy.
  • SbBool hasMultipleWriteRefs (void) const — does it have multiple write refs?
  • SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const — write the header.
  • void writeFooter (SoOutput *out) const — write the footer.
  • virtual const char * getFileFormatName (void) const — get the file format name.
  • virtual SoNotRec createNotRec (void) — create a notification record.

🌈 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) — get the current write counter.
  • static void staticDataLock (void) — lock the static data.
  • static void staticDataUnlock (void) — unlock the static data.

🔥 Detailed Description 🔥

The SoPath class is a container class for traversal path descriptions. she's literally just holding the receipts of how you got somewhere.

SoPath objects contain a list of SoNode pointers and a list of child indices. Indices are necessary to disambiguate situations where a node uses the same node as a child multiple times. (yes, the same child twice — that's the whole reason the index list exists, bestie)

Paths can be export and imported to/from file, like other SoBase derived objects. Read the documentation on the write() method to see how the file format is.

IMPORTANT VIBE CHECK: It's important to know the difference between this class and SoFullPath when working with paths. SoPath::getTail() will return the first node in the path that doesn't inherit SoGroup, and getLength() returns the number of nodes down to this node.

If you need the actual path length, or the actual tail node, you need to cast the path to SoFullPath. no shortcuts, no cap.

👑 Constructor & Destructor Documentation 👑

💅 SoPath::SoPath (const int approxlength = 4) 💅

The default constructor. approxlength is used to indicate in advance the length of the path to minimize the number of reallocations. she's pre-gaming the memory, we love a prepared queen.

🎀 SoPath::SoPath (SoNode *const head) 🎀

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

🦋 SoPath::SoPath (const SoPath & rhs) 🦋

Copy constructor. Not part of the original Open Inventor API. it's a Coin exclusive, iykyk.

💜 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 come for her with delete, she goes out through unref() like the rest of the SoBase girlies.

okay that's part 1 bestie, part 2 is coming, don't go anywhere 💖

✨ Member Function Documentation ✨

Okay bestie, deep breath — this is the long one. Every single member function of SoPath, one by one, no skipping, no "you get the idea". You will get the idea, because I'm telling you all of it. 🎀

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

Assignment operator, periodt. It copies the rhs path into this, and that's the whole vibe. 💅

Heads up: this one is not part of the original Open Inventor API. It's a Coin addition, so don't go looking for it in the OI docs, you'll just be confused. 🙈

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

This gives you back the type identification of any object derived from a class that inherits SoBase. What's it for? Runtime type checking, and "downward" casting — i.e. "I have a pointer to a base, but I need to know what it actually is before I do anything spicy with it." 💖

Usage example, verbatim, no cap:

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

Now — application programmers who wanna extend the library with new nodes, engines, nodekits, draggers or whatever else: you must override this method in all subclasses. That's not optional, bestie. It's typically done as part of setting up the full type system for your extension classes, and you usually pull that off with the predefined macros you get 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. 🌈

Want more on writing Coin extensions? Go read the class documentation of the top level superclasses for the various class groups. 📚

Implements SoBase.

void SoPath::setHead (SoNode *const node)

Sets the head of the path to node. If the object already has a path set, it gets truncated — like, gone, bye. 🌸

SoNode * SoPath::getHead (void ) const

Returns the head of the path. If the path is empty, you get NULL. That's it, that's the function. 💜

void SoPath::append (const int childindex)

Appends the childindex child of the path's tail to the end of the path. Important: you can only use this after the head is set. No head, no append. 🫶

void SoPath::append (SoNode *const node)

Adds node to the end — but only if it's actually a child of the current tail. And if the path is empty? Then this is equivalent to calling setHead(). Convenient. ✨

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

Appends frompath to the end of the path, provided the head of frompath is either the tail of the path or a child of the path's tail. And here's the little detail you don't wanna miss: if the head of frompath is used multiple times as a child of the path tail, the lowest child index is the one that gets used. 🦋

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

Pushes the child at childindex on the tail on the path. Short and sweet. 💫

void SoPath::pop (void ) [inline]

Pops the tail off the path. 🎀

SoNode * SoPath::getTail (void ) const

Returns the tail node of the path. But wait — read this carefully, bestie: this method only considers group nodes without hidden children (nodes inheriting SoGroup) when it's finding the tail. 👑

If you want the real tail node — the one that also goes below node kits and VRML nodes with hidden children — you have to use SoFullPath::getTail(). And the best part? You don't have to create an SoFullPath instance to do it. Just cast your SoPath instance to SoFullPath before grabbing the tail node:

SoNode * tail = static_cast<SoFullPath*>(path)->getTail();

Slay. 💅

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

Returns the node at index in the path, counted from 0 at the head. Zero-indexed, like a civilized data structure. 😌

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

Returns the node at index in the path, but counting from the tail this time. The index argument should be zero or positive — don't come at it with negatives. 🙈

int SoPath::getIndex (const int index) const

Returns the child index of the node at index in the path. 🔍

int SoPath::getIndexFromTail (const int index) const

Returns the child index of the node at index in the path, counting from the tail. Same deal: index should be zero or positive. 🍓

int SoPath::getLength (void ) const

Returns the number of nodes in the path. But — plot twist — only the "visible" nodes get counted. Hidden nodes of, say, nodekits are not included. 🧚

If you need the actual path length, you need to cast your path to SoFullPath and use SoFullPath::getLength(). That's the real number. 💖

void SoPath::truncate (const int length)

Truncates the path to the given length. Meaning: all nodes in the path list from index length and onwards get removed from the path list. Snip snip. ✂️

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

Returns the index of the last node that is the same for both paths. And if the paths don't even start on the same node? You get -1. They're not even on speaking terms. 💀

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

Returns the index of node if it's found in the full path — and yes, that includes the normally hidden parts — or -1 otherwise. 🔎

Note that this method is not part of the original Open Inventor API. Coin exclusive, iykyk. 💅

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

Returns TRUE if node is contained somewhere in the full path (possibly also in the normally hidden parts), and FALSE otherwise. Simple as. ✅

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

Returns TRUE if path is contained in the path, and FALSE otherwise. Pathception. 🌀

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

Returns a copy of the path starting at startfromnodeindex with length numnodes. If numnodes is 0 (the default) the path gets copied all the way to the end. 🎁

Big important warning, bestie, do not skip this: the returned SoPath instance will have an initial reference count of 0. It is the caller's responsibility to ref() and unref() it according to use. Nobody's gonna do it for you. 😭

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

A static method for retrieving an SoPath by its name. You get the last registered SoPath with the given name — or NULL if no SoPath by that name exists. ✨

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

Another static method — this one's for finding all the paths with a given name and appending them to the l list. It returns the number of SoPath instances with that name that were found. Collect them all. 🌈

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

This one gets called when a node in the path chain has a child added, so the index of its child can be updated. 🧵

newindex is the index of the child which was inserted. And if newindex is lower than the index value of the child node stored in the path, the path is updated accordingly. Math is math. 💅

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

Called when a node in the path chain has a child removed, so the index of its child can be updated. 🗑️

oldindex was the index of the removed child. And if oldindex is lower than or equal to the index value of the child node stored in the path, the path is updated accordingly. Note the "or equal to" — it's not the same rule as insertIndex(), so don't mix them up. 🙈

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 which has been replaced. Switcheroo. 🔄

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

Returns TRUE if the notification chain l will affect the path. And l will affect the path in either of two cases: if the notification is in the path (the notification started on a field in a node in the path), or off the path (the notification started in a non-separator node that is left of the path's node). Two ways to matter. 💖

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

This method is used to write the contents of an SoPath. 📝

A path is written as:

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).]

Okay so here's the thing — 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 a 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 have vanished, as they were not important for the part per se, and not written as part of it. 😭 Poof. Gone. Not the vibe.

This is why we do full subgraph export for head nodes in paths. Problem solved, bestie. 💅

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

Sets whether or not to audit the nodes in the path to detect changes. Protected, so it's an internal-kitchen situation. 👑

🌸 Author 🌸

Generated automatically by Doxygen for Coin from the source code. Yes, a robot wrote this, and honestly? It ate. 🤖✨

That's the whole page, bestie — SoPath(3), Version 4.0.10, dated Thu Jun 25 2026 00:00:00. Go forth and cast your paths, and remember: ref() and unref() that copy() result or it will haunt you. 💖🦋💅

📦 where this page comes from