Path that points to a list of hierarchical nodes. More...

#include <Inventor/SoPath.h>

Inheritance diagram for SoPath:

Public Member Functions
	SoPath ()
	Constructs an empty path.

	SoPath (int approxLength)
	Constructs a path with a hint to length (number of nodes in chain).

	SoPath (SoNode *node)
	Constructs a path and sets the head node to the given node.

void	setHead (SoNode *node)
	Sets head node (first node in chain).

void	append (int childIndex)
	Adds node to end of chain; the node is the childIndex'th child of the current tail node.

void	append (SoNode *childNode)
	Adds node to end of chain; uses the first occurrence of childNode as child of current tail node.

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.

void	push (int childIndex)
	The push() and pop() methods 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.

void	pop ()
	The push() and pop() methods 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 *	getHead () const
	Returns the first node in a path chain.

SoNode *	getTail () const
	Returns the last node in a path chain.

SoNode *	getNode (int i) const
	Returns the i'th node (within its parent) in the chain.

SoNode *	getNode (const SoType type, int &i) const
	Returns the first node and its index, from the head of the given type in the chain.

SoNode *	getNodeFromTail (int i) const
	Returns the i'th node (within its parent) in the chain, counting backward from the tail node.

int	getIndex (int i) const
	Returns the index of the i'th node (within its parent) in the chain.

int	getInstanceIndex (int i) const
	Returns the index of the instance inside the parent SoMultipleInstance, SoMultipleCopy or SoArray group.

int	getIndexFromTail (int i) const
	Returns the index of the i'th node (within its parent) in the chain, counting backward from the tail node.

int	getInstanceIndexFromTail (int i) const
	Returns the index of the i'th node instance (within its parent, if it is a SoMultipleInstance, SoMultipleCopy or SoArray group in the chain, counting backward from the tail node.

int	getLength () const
	Returns length of path chain (number of nodes).

void	truncate (int start)
	Truncates the path chain, removing all nodes from index start on.

SbBool	containsNode (const SoNode *node) const
	Returns TRUE if the node is found anywhere in the path chain.

SbBool	containsNode (const SoType type) const
	Returns TRUE if the node type is found anywhere in the path chain.

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.

int	findFork (const SoPath *path) const
	If the two paths have different head nodes, this returns -1.

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.

virtual SoType	getTypeId () const
	Returns type identifier for path instance.

Public Member Functions inherited from SoBase
virtual void	touch ()
	Marks an instance as modified, simulating a change to it.

virtual SbName	getName () const
	Returns the name of an instance.

virtual void	setName (const SbName &name)
	Sets the name of an instance.

void	setSynchronizable (const bool b)
	Sets this to be a ScaleViz synchronizable object.

bool	isSynchronizable () const
	Gets the ScaleViz synchronizable state of this object.

Public Member Functions inherited from SoRefCounter
void	ref () const
	Adds a reference to an instance.

void	unref () const
	Removes a reference from an instance.

void	unrefNoDelete () const
	unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.

int	getRefCount () const
	Returns current reference count.

void	lock () const
	lock this instance.

void	unlock () const
	unlock this instance.

Public Member Functions inherited from SoTypedObject
SbBool	isOfType (const SoType &type) const
	Returns TRUE if this object is of the type specified in type or is derived from that type.

template<typename TypedObjectClass >
SbBool	isOfType () const
	Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.

Static Public Member Functions
static SoType	getClassTypeId ()
	Returns type identifier for SoPath class.

static SoPath *	getByName (const SbName &name)
	Method to return a path with a given name.

static int	getByName (const SbName &name, SoPathList &list)
	Method to return paths with a given name.

Static Public Member Functions inherited from SoBase
static SoType	getClassTypeId ()
	Returns type identifier for this class.

Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.

Friends
class	SoFullPath

class	SoTempPath

class	SoAction

class	SoPathNoRef

class	SoTraversalPassImpl

int	operator== (const SoPath &p1, const SoPath &p2)
	Returns TRUE if all nodes in the two path chains are identical.

std::ostream &	operator<< (std::ostream &os, const SoPath &path)
	Writes the path to the specified output stream.

bool	operator< (const SoPath &p1, const SoPath &p2)
	Returns TRUE is p1 strictly less than p2: to provide a total order operation for SoPath.

Detailed Description

Path that points to a list of hierarchical nodes.

A path represents a scene graph or subgraph. It contains a list of nodes forming a chain from some root to some descendant. 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.

Hidden children

Note that only public children of nodes are accessible from an SoPath. Nodes like node kits limit access to their children and these "hidden children" will not be visible using the SoPath methods.

For example, if your application does picking and gets a path from SoRayPickAction, the actual last node in the path (tail) will normally be a shape node. But if that shape is part of a node kit, then the getTail() method will return the node kit, not the shape node. To access all hidden children in the path, simply cast the path object to SoFullPath before calling get methods. To access hidden node kit children (but not all children) in the path, cast the path object to SoNodeKitPath before calling get methods.

[C++] Reference counting:

This is a reference counted object, similar to a node. It can only be destroyed by incrementing and decrementing the reference count. The initial reference count is 0. You may use the ref() and unref() methods or the SoRef "smart pointer" template.
SoPath automatically calls ref() when a node is added to the path and unref() when the node is removed from the path or the path object is destroyed. This additional ref() will prevent nodes from being destroyed as long as the path object exists.
Actions that return an SoPath, for example SoSearchAction and SoRayPickAction, automatically call ref() when the path is created and unref() when the action is reset or destroyed. The application does not need to explicitly destroy these paths. But be aware that as long as the action is not reset or destroyed, the path is not destroyed and so the nodes referenced by the path cannot be destroyed. See the SoAction method clearApplyResult().

FILE FORMAT/DEFAULT

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.

SoPath is not able to write "per instance" information to a file for instancing nodes like SoMultipleInstance and SoMultipleCopy. The saved path will reference the whole set of instances under SoMultipleInstance or SoMulitpleCopy node.

Constructor & Destructor Documentation

◆ SoPath() [1/3]

SoPath::SoPath ( )

Constructs an empty path.

◆ SoPath() [2/3]

SoPath::SoPath ( int approxLength )

Constructs a path with a hint to length (number of nodes in chain).

◆ SoPath() [3/3]

SoPath::SoPath ( SoNode * node )

Constructs a path and sets the head node to the given node.

Member Function Documentation

◆ append() [1/3]

void SoPath::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.

◆ append() [2/3]

void SoPath::append ( int childIndex )

Adds node to end of chain; the node is the childIndex'th child of the current tail node.

◆ append() [3/3]

void SoPath::append ( 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 to setHead(childNode) .

◆ containsNode() [1/2]

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

Returns TRUE if the node is found anywhere in the path chain.

◆ containsNode() [2/2]

SbBool SoPath::containsNode ( const SoType type ) const

Returns TRUE if the node type is found anywhere in the path chain.

◆ containsPath()

SbBool SoPath::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.

◆ copy()

SoPath * 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.

◆ findFork()

int SoPath::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.

◆ getByName() [1/2]

static SoPath * SoPath::getByName ( const SbName & name )

static

Method to return a path with a given name.

Paths are named by calling their setName() method (defined by the SoBase class). This method returns the last path that was given the specified 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.

◆ getByName() [2/2]

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

static

Method to return paths with a given name.

Paths are named by calling their setName() method (defined by the SoBase class). This method 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.

◆ getClassTypeId()

static SoType SoPath::getClassTypeId ( )

static

Returns type identifier for SoPath class.

◆ getHead()

SoNode * SoPath::getHead ( ) const

inline

Returns the first node in a path chain.

Definition at line 246 of file SoPath.h.

◆ getIndex()

int SoPath::getIndex ( int i ) const

Returns the index of the i'th node (within its parent) in the chain.

◆ getIndexFromTail()

int SoPath::getIndexFromTail ( int i ) const

Returns 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 index of the tail node.

◆ getInstanceIndex()

int SoPath::getInstanceIndex ( int i ) const

Returns the index of the instance inside the parent SoMultipleInstance, SoMultipleCopy or SoArray group.

The returned value is -1 for other parent nodes.

◆ getInstanceIndexFromTail()

int SoPath::getInstanceIndexFromTail ( int i ) const

Returns the index of the i'th node instance (within its parent, if it is a SoMultipleInstance, SoMultipleCopy or SoArray group in the chain, counting backward from the tail node.

Passing 0 for i returns the instance index of the tail node.

◆ getLength()

int SoPath::getLength ( ) const

Returns length of path chain (number of nodes).

◆ getNode() [1/2]

SoNode * SoPath::getNode	(	const SoType	type,
		int &	i
	)		const

Returns the first node and its index, from the head of the given type in the chain.

NULL is returned and the index is set to -1 if no node of the given type is found.

◆ getNode() [2/2]

SoNode * SoPath::getNode ( int i ) const

Returns the i'th node (within its parent) in the chain.

Calling getNode(0) is equivalent to calling getHead().

◆ getNodeFromTail()

SoNode * SoPath::getNodeFromTail ( int i ) const

Returns the i'th node (within its parent) in the chain, counting backward from the tail node.

Passing 0 for i returns the tail node.

◆ getTail()

SoNode * SoPath::getTail ( ) const

Returns the last node in a path chain.

◆ getTypeId()

virtual SoType SoPath::getTypeId ( ) const

virtual

Returns type identifier for path instance.

Implements SoTypedObject.

◆ pop()

void SoPath::pop ( )

The push() and pop() methods 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.

◆ push()

void SoPath::push ( int childIndex )

The push() and pop() methods 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.

◆ setHead()

void SoPath::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.

◆ truncate()

void SoPath::truncate ( int start )

Truncates the path chain, removing all nodes from index start on.

Calling truncate(0) empties the path entirely.

Friends And Related Symbol Documentation

◆ operator<

bool operator<	(	const SoPath &	p1,
		const SoPath &	p2
	)

friend

Returns TRUE is p1 strictly less than p2: to provide a total order operation for SoPath.

◆ operator<<

std::ostream & operator<<	(	std::ostream &	os,
		const SoPath &	path
	)

friend

Writes the path to the specified output stream.

◆ operator==

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

friend

Returns TRUE if all nodes in the two path chains are identical.

◆ SoAction

friend class SoAction

friend

Definition at line 522 of file SoPath.h.

◆ SoFullPath

friend class SoFullPath

friend

Definition at line 520 of file SoPath.h.

◆ SoPathNoRef

friend class SoPathNoRef

friend

Definition at line 523 of file SoPath.h.

◆ SoTempPath

friend class SoTempPath

friend

Definition at line 521 of file SoPath.h.

◆ SoTraversalPassImpl

friend class SoTraversalPassImpl

friend

Definition at line 524 of file SoPath.h.

The documentation for this class was generated from the following file:

Inventor/SoPath.h

Open Inventor Release 2024.1.3

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

FILE FORMAT/DEFAULT

SEE ALSO

Constructor & Destructor Documentation

◆ SoPath() [1/3]

◆ SoPath() [2/3]

◆ SoPath() [3/3]

Member Function Documentation

◆ append() [1/3]

◆ append() [2/3]

◆ append() [3/3]

◆ containsNode() [1/2]

◆ containsNode() [2/2]

◆ containsPath()

◆ copy()

◆ findFork()

◆ getByName() [1/2]

◆ getByName() [2/2]

◆ getClassTypeId()

◆ getHead()

◆ getIndex()

◆ getIndexFromTail()

◆ getInstanceIndex()

◆ getInstanceIndexFromTail()

◆ getLength()

◆ getNode() [1/2]

◆ getNode() [2/2]

◆ getNodeFromTail()

◆ getTail()

◆ getTypeId()

◆ pop()

◆ push()

◆ setHead()

◆ truncate()

Friends And Related Symbol Documentation

◆ operator<

◆ operator<<

◆ operator==

◆ SoAction

◆ SoFullPath

◆ SoPathNoRef

◆ SoTempPath

◆ SoTraversalPassImpl