GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SOPATH (3)

NAME

SoPath — path that points to a list of hierarchical nodes

CONTENTS

Inherits From
Synopsis
Description
Methods
File Format/defaults
See Also

INHERITS FROM

SoBase > SoPath

SYNOPSIS

#include <Inventor/SoPath.h>

Methods from class SoPath:

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

Methods from class SoBase:

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

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.

METHODS

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

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

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

    void    
                    
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    
                    
void                 push(int childIndex)    
void    
                    
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.

    SoNode *    
                    
SoNode *             getHead() const    
SoNode *    
                    
SoNode *             getTail() const
These return the first and last nodes in a path chain.

    SoNode *    
                    
SoNode *             getNode(int i) const    
int    
                    
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. Calling getNode(0) is equivalent to calling getHead().

    SoNode *    
                    
SoNode *             getNodeFromTail(int i) const    
int    
                    
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.

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

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

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

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

    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.

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

    static SoPath *    
                    
static SoPath *      getByName(const SbName &name)    
static int    
                    
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.

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

Search for    or go to Top of page |  Section 3 |  Main Index


SOPATH(3IV) (-->)

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.