SOPATH(3iv)

💖 SoPath 💖

okay so bestie, welcome to the SoPath(3IV) manual page, aka the glow-up guide to the class that knows exactly where everything is in your scene graph. this is the whole page, no skips, no cuts, we're reading all of it. periodt. ✨

---

🌸 NAME 🌸

SoPath — a path that points to a list of hierarchical nodes. it's giving "I know a guy, and the guy knows a guy, and eventually we get to the thing you actually want." 💅

---

🦋 INHERITS FROM 🦋

SoBase > SoPath

so yeah, it's a SoBase baby, it's got all the SoBase genes. 🧬

---

✨ SYNOPSIS ✨

#include <Inventor/SoPath.h>

   Methods from class SoPath:

                  SoPath()
                  SoPath(int approxLength)
                  SoPath(SoNode *node)
void                setHead(SoNode *node)
void                append(int childIndex)
void                append(SoNode *childNode)
void                append(const SoPath *fromPath)
void                push(int childIndex)
void                pop()
SoNode *            getHead() const
SoNode *            getTail() const
SoNode *            getNode(int i) const
int                 getIndex(int i) const
SoNode *            getNodeFromTail(int i) const
int                 getIndexFromTail(int i) const
int                 getLength() const
void                truncate(int start)
SbBool              containsNode(const SoNode *node) const
SbBool              containsPath(const SoPath *path) const
int                 findFork(const SoPath *path) const
SoPath *            copy(int startFromNodeIndex = 0, int numNodes = 0)
                         const
friend int          operator ==(const SoPath &p1, const SoPath &p2)
static SoPath *     getByName(const SbName &name)
static int          getByName(const SbName &name, SoPathList &list)

   Methods from class SoBase:

void                ref()
void                unref() const
void                unrefNoDelete() const
void                touch()
static SoType       getClassTypeId()
virtual SoType      getTypeId() const
SbBool              isOfType(SoType type) const
virtual void        setName(const SbName &name)
virtual SbName      getName() const

---

👑 DESCRIPTION 👑

A path represents a scene graph or subgraph. it's literally a list of pointers to nodes forming a chain from some root all the way down to some descendent. every node in the chain is a child of the previous node — like a little family tree where everybody's holding hands down the line. 🫶 Paths are used to refer to some object in a scene graph precisely and unambiguously, even if there are many instances of that object. so it's the "no actually, THAT one" of data structures. and that's exactly why paths are returned by both the SoRayPickAction and the SoSearchAction. iconic behaviour, honestly. ✨

When an action is applied to a path, only the nodes in the subgraph defined by the path are traversed. and what counts? lemme list it bestie:

• the nodes in the path chain
• all nodes (if any) below the last node in the path
• and all nodes whose effects are inherited by any of these nodes

SoPath attempts to maintain consistency of paths even when the structure of the scene graph changes. she's adaptive, she's flexible, she's main character energy:

• removing a child from its parent when both are in a path chain cuts the path chain at that point, leaving the top part intact
• removing the node to the left of a node in a path adjusts the index for that node
• replacing a child of a node when both the parent and the child are in the chain replaces the child in the chain with the new child, truncating the path below the new child

lowkey important: only public children of nodes are accessible from an SoPath. nodes like node kits that limit access to their children may provide other ways to get more information — for example, by using the SoNodeKitPath class. iykyk. 🔥

---

💅 METHODS 💅

SoPath()

Constructs an empty path. it's giving blank canvas, empty notebook, fresh start. 🎀

SoPath(int approxLength)

Constructs a path with a hint to length (number of nodes in chain). just a lil heads-up so she can plan accordingly. 🌸

SoPath(SoNode *node)

Constructs a path and sets the head node to the given node. boom, instant head. 💅

void setHead(SoNode *node)

Sets head node (first node in chain). the head node must be set before the append() or push() methods may be called. no head, no chain, no exceptions. 😭

void append(int childIndex)

Adds node to end of chain; the node is the childIndex'th child of the current tail node. very "you're coming with us" energy. ✨

void append(SoNode *childNode)

Adds node to end of chain; uses the first occurrence of childNode as child of current tail node. and if the path is empty, this is equivalent to setHead(childNode). two birds, one method. 🦋

void append(const SoPath *fromPath)

Adds all nodes in fromPath's chain to end of chain; the head node of fromPath must be the same as or a child of the current tail node. so they gotta be related, bestie, this isn't a blind date. 🙈

void push(int childIndex) and void pop()

These allow a path to be treated as a stack; they push a node at the end of the chain and pop the last node off. stack girlies rise up. 📚

SoNode *getHead() const and SoNode *getTail() const

These return the first and last nodes in a path chain. head and tail, the alpha and the omega, the beginning and the end. 👑

SoNode *getNode(int i) const and int getIndex(int i) const

These return a pointer to the i'th node or the index of the i'th node (within its parent) in the chain. and heads up: calling getNode(0) is equivalent to calling getHead(). 💜

SoNode *getNodeFromTail(int i) const and int getIndexFromTail(int i) const

These return a pointer to the i'th node or the index of the i'th node (within its parent) in the chain, counting backward from the tail node. passing 0 for i returns the tail node or its index. it's the same thing but in reverse, we love a remix. 🔄

int getLength() const

Returns length of path chain (number of nodes). the count, the receipts, the total. ⭐

void truncate(int start)

Truncates the path chain, removing all nodes from index start on. and calling truncate(0) empties the path entirely. full reset, no crumbs left. 💀

SbBool containsNode(const SoNode *node) const

Returns TRUE if the node is found anywhere in the path chain. anywhere. she's thorough. 🔍

SbBool containsPath(const SoPath *path) const

Returns TRUE if the nodes in the chain in the passed path are contained (in consecutive order) in this path chain. consecutive, bestie, no skipping. 🌈

int findFork(const SoPath *path) const

If the two paths have different head nodes, this returns -1. otherwise, it returns the path chain index of the last node (starting at the head) that is the same for both paths. it's the "where do we split" detector. 🍴

SoPath *copy(int startFromNodeIndex = 0, int numNodes = 0) const

Creates and returns a new path that is a copy of some or all of this path. copying starts at the given index (default is 0, which is the head node). a numNodes of 0 (the default) means copy all nodes from the starting index to the end. Returns NULL on error. it's a clone, it's a twin, it's a dupe in the best way. 🧚

friend int operator ==(const SoPath &p1, const SoPath &p2)

Returns TRUE if all node pointers in the two path chains are identical. not "similar vibes" — identical. no cap. 💯

static SoPath *getByName(const SbName &name) and static int getByName(const SbName &name, SoPathList &list)

These methods lookup and return paths with a given name. paths are named by calling their setName() method (defined by the SoBase class). the first form returns the last path that was given that name, either by setName() or by reading in a named path from a file. if there is no path with the given name, NULL will be returned. the second form appends all paths with the given name to the given path list and returns the number of paths that were added. if there are no paths with the given name, zero will be returned and nothing will be added to the list. name-based finder, but make it thorough. 🎀

---

🍓 FILE FORMAT/DEFAULTS 🍓

SoPath {
   [head node]
   [number of remaining indices]
   [index]
   ...
   [index]
}

Note that the indices in a written path are adjusted based on the nodes that are actually written to a file. since nodes in the graph that have no effect on the path (such as some separator nodes) are not written, the siblings of such nodes must undergo index adjustment when written. the actual nodes in the graph remain unchanged. so like, the file gets a lil reshuffle but the real graph is untouched. we respect the original. 💖

---

🔥 SEE ALSO 🔥

• SoNode
• SoRayPickAction
• SoSearchAction
• SoNodeKitPath

---

and that's the whole page, bestie!! ✨💖✨ this was the SoPath page from the SoPath(3IV) manual — and honestly the footer's source/version and date slots are literally empty (SoPath(3IV)()), so there's nothing to date-stamp, it's just ✨timeless✨. go forth and traverse. 💅🎀🦋