SoPath(3IV)NAMESoPath (SoPath) - path that points to a list of hierarchical nodes
INHERITS FROM
SoBase > SoPathSYNOPSIS
#include <Inventor_c/SoPath.h>
Functions from class SoPath:
SoPath * SoPathCreate()SoPath * SoPathCreateLen(int approxLength)
SoPath * SoPathCreateNode(SoNode *node)
void SoPathSetHead(SoPath *this, SoNode *node)
void SoPathAppendInd(SoPath *this, int childIndex)
void SoPathAppendNode(SoPath *this, SoNode *childNode)
void SoPathAppendPath(SoPath *this, const SoPath
*fromPath)
void SoPathPush(SoPath *this, int childIndex)
void SoPathPop(SoPath *this)
SoNode * SoPathGetHead(const SoPath *this)
SoNode * SoPathGetTail(const SoPath *this)
SoNode * SoPathGetNode(const SoPath *this, int i)
int SoPathGetInd(const SoPath *this, int i)
SoNode * SoPathGetNodeFromTail(const SoPath *this, int i)
int SoPathGetIndFromTail(const SoPath *this, int i)
int SoPathGetLen(const SoPath *this)
void SoPathTruncate(SoPath *this, int start)
SbBool SoPathContainsNode(const SoPath *this, const SoNode
*node)
SbBool SoPathContainsPath(const SoPath *this, const SoPath
*path)
int SoPathFindFork(const SoPath *this, const SoPath
*path)
SoPath * SoPathCopy(const SoPath *this, int startFromNodeIndex
= 0, int numNodes = 0)
int SoPathIsEq(SoPath *this, const SoPath *p1, const
SoPath *p2)
SoPath * SoPathGetByName(const char *name)
int SoPathGetByNameList(const char *name, SoPathList
*list)
Functions from class SoBase:
void SoPathRef(SoPath *this)
void SoPathUnref(const SoPath *this)
void SoPathUnrefNoDelete(const SoPath *this)
void SoPathTouch(SoPath *this)
SoType SoPathGetClassTypeId()
SoType SoPathGetTypeId(const SoPath *this)
Page 1SoPath(3IV)
SbBool SoPathIsOfType(const SoPath *this, SoType type)
void SoPathSetName(SoPath *this, const char *name)
SbName SoPathGetName(const SoPath *this)
DESCRIPTION
A path represents a scene graph or subgraph. It contains a list of
pointers to nodes forming a chain from some root to some descendent. Each
node in the chain is a child of the previous node. Paths are used to
refer to some object in a scene graph precisely and unambiguously, even
if there are many instances of the object. Therefore, paths are returned
by both the SoRayPickAction and SoSearchAction.
When an action is applied to a path, only the nodes in the subgraph
defined by the path are traversed. These include: 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. For example, 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.
Note that 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, such as by using the SoNodeKitPath
class.
FUNCTIONSSoPath * SoPathCreate()
Constructs an empty path.
SoPath * SoPathCreateLen(int approxLength)
Constructs a path with a hint to length (number of nodes in chain).
SoPath * SoPathCreateNode(SoNode *node)
Constructs a path and sets the head node to the given node.
void SoPathSetHead(SoPath *this, SoNode *node)
Sets head node (first node in chain). The head node must be set
before the SoPathAppend() or SoPathPush() functions may be called.
void SoPathAppendInd(SoPath *this, int childIndex)
Adds node to end of chain; the node is the childIndex'th child of
the current tail node.
void SoPathAppendNode(SoPath *this, SoNode *childNode)
Adds node to end of chain; uses the first occurrence of childNode as
child of current tail node. If the path is empty, this is equivalent
Page 2SoPath(3IV)
to SoPathSetHead(childNode).
void SoPathAppendPath(SoPath *this, 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.
void SoPathPush(SoPath *this, int childIndex)
void SoPathPop(SoPath *this)
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.
SoNode * SoPathGetHead(const SoPath *this)
SoNode * SoPathGetTail(const SoPath *this)
These return the first and last nodes in a path chain.
SoNode * SoPathGetNode(const SoPath *this, int i)
int SoPathGetInd(const SoPath *this, int i)
These return a pointer to the i'th node or the index of the i'th
node (within its parent) in the chain. Calling SoPathGetNode(path,
0) is equivalent to calling SoPathGetHead(path).
SoNode * SoPathGetNodeFromTail(const SoPath *this, int i)
int SoPathGetIndFromTail(const SoPath *this, int i)
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.
int SoPathGetLen(const SoPath *this)
Returns length of path chain (number of nodes).
void SoPathTruncate(SoPath *this, int start)
Truncates the path chain, removing all nodes from index start on.
Calling SoPathTruncate(0) empties the path entirely.
SbBool SoPathContainsNode(const SoPath *this, const SoNode
*node)
Returns TRUE if the node is found anywhere in the path chain.
SbBool SoPathContainsPath(const SoPath *this, const SoPath
*path)
Returns TRUE if the nodes in the chain in the passed path are
contained (in consecutive order) in this path chain.
int SoPathFindFork(const SoPath *this, const SoPath
*path)
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.
SoPath * SoPathCopy(const SoPath *this, int startFromNodeIndex
= 0, int numNodes = 0)
Page 3SoPath(3IV)
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.
int SoPathIsEq(SoPath *this, const SoPath *p1, const
SoPath *p2)
Returns TRUE if all node pointers in the two path chains are
identical.
SoPath * SoPathGetByName(const char *name)
int SoPathGetByNameList(const char *name, SoPathList
*list)
These methods lookup and return paths with a given name. Paths are
named by calling their SoPathSetName() function (defined by the
SoBase class). The first form returns the last path that was given
that name, either by SoPathSetName() 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.
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.
SEE ALSO
SoNode, SoRayPickAction, SoSearchAction, SoNodeKitPath
Page 4
