SoPath(3)

📦 version 3.1.3, in fedora 43, fedora 44

okay so bestie, pull up a chair, grab ur iced coffee 🧋, because we're about to get into SoPath(3) — yes, the manual page, section 3, library functions, and she is iconic. If you've ever been like "wait, how do I even describe a route through a scene graph??" — girl, same, and this class is literally the answer. let's go 💅

🌸 NAME 🌸

SoPath — the container class for traversal path descriptions. that's it, that's the whole vibe. she holds paths, she describes traversals, she slays 🦋

✨ 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=FALSE)
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 *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)

💜 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

👑 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 🦋

okay so the tea ☕: SoPath is a container class for traversal path descriptions. that's the whole point of her existence and honestly? she ate.

Here's the lore: an SoPath object holds a list of SoNode pointers and a list of child indices. and bestie, why do we need the indices too? because sometimes a node is being used as a child multiple times by the same parent, and without those indices you literally cannot tell which one we mean. so the indices are the disambiguators. they keep it clear. no cap 💅

Also: paths can be exported and imported to/from file, just like every other object that derives from SoBase. So if you wanna know how the file format actually goes down, go read the documentation on the write() method. it's all in there, iykyk 🔥

🎀 CONSTRUCTOR & DESTRUCTOR DOCUMENTATION 🎀

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

The default constructor, bestie. the approxlength param is u telling her in advance how long the path is gonna be — and that's a flex because it minimizes the number of reallocations. future-proofing ur memory, periodt ✨

⭐ SoPath::SoPath (SoNode *const head)

A constructor, and this one's simple: whatever node u pass in gets set as the head — and the only node — of the path. one node, head position, done 🫶

⭐ SoPath::SoPath (const SoPath & rhs)

Copy constructor. heads up though: this one is not part of the original Open Inventor API. so like, she's here, she works, but she's an extra. an addition. a little bonus moment 💀

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

The destructor is protected — and that's on purpose! destruction of SoPath instances happens through unref(), just like for all objects derived from classes that inherit SoBase. so no, u don't just delete her, u unref() her. that's the way 💅

lowkey important: protected destructor means the compiler will yell at u if u try to delete one of these directly. it's not a bug, it's a boundary. respect it 🚫

and that's where part 1 wraps, but bestie we are not done — there's more SoPath(3) coming ur way 👀💖

💅 Member Function Documentation 💅

okay bestie, this is the big one — every single member function, no skips, no cap. let's get into it 💖

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

Assignment operator energy ✨ it copies the rhs path into this. Not part of the original Open Inventor API, just so you know.

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

Returns the type ID of an object derived from a class that inherits SoBase. This is the whole vibe for run-time type checking and "downward" casting, bestie.

Usage example:

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

If you're an application programmer wanting to extend the library with new nodes, engines, nodekits, draggers or whatever — this method needs to be overridden in all subclasses. That's usually part of setting up the full type system for extension classes, and it's typically done with the pre-defined macros available through e.g. 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 info on writing Coin extensions, check the class documentation of the toplevel 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. bye old path 👋

SoNode * SoPath::getHead (void ) const

Returns the head of the path, or NULL if the path is empty. simple as that.

void SoPath::append (const int childindex)

Appends the childindex child of the path's tail to the end of the path. You can only use this after the head is set, bestie.

void SoPath::append (SoNode *const node)

Adds node to the end if it's a child of the current tail. If the path is empty, this is equivalent to calling setHead(). cute.

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

Appends frompath to the end of this 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.

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

Pushes the child at childindex on the tail on the path. ✨

void SoPath::pop (void ) [inline]

Pops the tail off the path. byeeeee 👑

SoNode * SoPath::getTail (void ) const

Returns the tail node of the path. But please note: this method only considers group nodes without hidden children (nodes inheriting SoGroup) when finding the tail.

If you want the real tail node (also below node kits and VRML nodes with hidden children), you have to use SoFullPath::getTail(). You don't have to create an SoFullPath instance to do this — just cast the SoPath instance to SoFullPath before getting the tail node:

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

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

Returns the node at index in the path, counted from 0 at the head. zero-indexed girlies rise up 💅

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

Returns the node at index in the path, counting from the tail. The index argument should be zero or positive, no negative vibes.

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. The index argument should be zero or positive.

int SoPath::getLength (void ) const

Returns the number of nodes in the path. Only the "visible" nodes are counted, so hidden nodes of e.g. nodekits are not included.

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, or -1 if the paths don't even start on the same node. it's giving fork in the road 💀

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

Returns the index of node if found in the full path (possibly also in the normally hidden parts), or -1 otherwise.

Note that this method is not part of the original Open Inventor API.

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.

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

Returns TRUE if path is contained in this path, and FALSE otherwise.

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 will be copied to the end.

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. so don't forget, bestie 😭

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

This static method retrieves an SoPath by its name. The last registered SoPath with the given name is returned, or NULL if no SoPath by that name exists.

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

This static method finds all the paths with a given name and appends them to the l list. The number of SoPath instances with that name found is returned. slay.

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

Called when a node in the path chain has a child added, to update the index of its child.

newindex is the index of the child which was inserted. If newindex is lower than the index value of the child node stored in the path, the path is updated accordingly.

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

Called when a node in the path chain has a child removed, to update the index of its child.

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 is updated accordingly.

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. glow up 💅

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

Returns TRUE if the notification chain l will affect the path. l will affect the path either 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).

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

Used to write the contents of an SoPath.

A path is written as:

Path {
  HEAD-NODE-OF-SUBGRAPH
  NUMBER-OF-INDICES
  INDEX0
  INDEX1
  ...
}
lowkey, the rest of this method's documentation only explains why Coin and original Open Inventor behave differently. skip it if you're not curious. (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"...
  }
}

SoSeparator * root = new SoSeparator;
root->addChild([ptr to path_switch]);
root->addChild([ptr to top_sep]);
SoWriteAction wa;
wa.apply(root);
Separator {
  DEF path_switch PathSwitch {
    path Path {
      DEF top_sep Separator {
        DEF a_sphere Sphere {
        }
      }
      1
      0
    }
  }
  USE top_sep
}

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

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

Set whether or not to audit the nodes in the path to detect changes. protected vibes only.

👑 Author 👑

Generated automatically by Doxygen for Coin from the source code. so iconic of Doxygen tbh.

okay bestie, that's the whole page! from Coin, version 3.1.3, for SoPath(3). love u, bye 💖✨🎀🦋

📦 where this page comes from