SoPath.h

/*=======================================================================
 * Copyright 1991-1996, Silicon Graphics, Inc.
 * ALL RIGHTS RESERVED
 *
 * UNPUBLISHED -- Rights reserved under the copyright laws of the United
 * States.   Use of a copyright notice is precautionary only and does not
 * imply publication or disclosure.
 *
 * U.S. GOVERNMENT RESTRICTED RIGHTS LEGEND:
 * Use, duplication or disclosure by the Government is subject to restrictions
 * as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights
 * in Technical Data and Computer Software clause at DFARS 252.227-7013 and/or
 * in similar or successor clauses in the FAR, or the DOD or NASA FAR
 * Supplement.  Contractor/manufacturer is Silicon Graphics, Inc.,
 * 2011 N. Shoreline Blvd. Mountain View, CA 94039-7311.
 *
 * THE CONTENT OF THIS WORK CONTAINS CONFIDENTIAL AND PROPRIETARY
 * INFORMATION OF SILICON GRAPHICS, INC. ANY DUPLICATION, MODIFICATION,
 * DISTRIBUTION, OR DISCLOSURE IN ANY FORM, IN WHOLE, OR IN PART, IS STRICTLY
 * PROHIBITED WITHOUT THE PRIOR EXPRESS WRITTEN PERMISSION OF SILICON
 * GRAPHICS, INC.
**=======================================================================*/
/*=======================================================================
** Author      : Paul S. Strauss (MMM yyyy)
** Modified by : Nick Thompson (MMM yyyy)
** Modified by : Alan Norton (MMM yyyy)
**=======================================================================*/
/*=======================================================================
 *** THE CONTENT OF THIS WORK IS PROPRIETARY TO FEI S.A.S, (FEI S.A.S.),            ***
 ***              AND IS DISTRIBUTED UNDER A LICENSE AGREEMENT.                     ***
 ***                                                                                ***
 ***  REPRODUCTION, DISCLOSURE,  OR USE,  IN WHOLE OR IN PART,  OTHER THAN AS       ***
 ***  SPECIFIED  IN THE LICENSE ARE  NOT TO BE  UNDERTAKEN  EXCEPT WITH PRIOR       ***
 ***  WRITTEN AUTHORIZATION OF FEI S.A.S.                                           ***
 ***                                                                                ***
 ***                        RESTRICTED RIGHTS LEGEND                                ***
 ***  USE, DUPLICATION, OR DISCLOSURE BY THE GOVERNMENT OF THE CONTENT OF THIS      ***
 ***  WORK OR RELATED DOCUMENTATION IS SUBJECT TO RESTRICTIONS AS SET FORTH IN      ***
 ***  SUBPARAGRAPH (C)(1) OF THE COMMERCIAL COMPUTER SOFTWARE RESTRICTED RIGHT      ***
 ***  CLAUSE  AT FAR 52.227-19  OR SUBPARAGRAPH  (C)(1)(II)  OF  THE RIGHTS IN      ***
 ***  TECHNICAL DATA AND COMPUTER SOFTWARE CLAUSE AT DFARS 52.227-7013.             ***
 ***                                                                                ***
 ***                   COPYRIGHT (C) 1996-2024 BY FEI S.A.S,                        ***
 ***                        BORDEAUX, FRANCE                                        ***
 ***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/
/*=======================================================================
** Modified by : VSG (MMM YYYY)
**=======================================================================*/
 
 
#ifndef  _SO_PATH_
#define  _SO_PATH_
 
#include <Inventor/misc/SoBase.h>
#include <Inventor/nodes/SoNode.h>
#include <Inventor/SoLists.h>
#include <Inventor/lists/NodeIndex.h>
#include <Inventor/STL/iostream>
#include <Inventor/SbEventHandler.h>
 
class SoTempPath;

//
//  Class: SoPath
//
//  A SoPath represents a scene graph or subgraph. It contains
//  pointers to a chain of nodes, each of which is a child of the
//  previous. The child index of each node is also stored, to
//  disambiguate cases where a node appears more than once as a child
//  of the same group.
//
//  The graph defined by the path consists of all of the nodes in the
//  path, all nodes below the last node in the chain, and any other
//  nodes that have an effect on these nodes.
//
 
class SoPathList;
class SoWriteAction;

class  SoPath : public SoBase {
 
 public:

  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 { return (SoNode*)(nodes.get(0)); }

  SoNode* getTail() const;

  SoNode* getNode(int i) const;

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

  SoNode* getNodeFromTail(int i) const;

  int getIndex(int i) const;

  int getInstanceIndex(int i) const;

  int getIndexFromTail(int i) const;

  int getInstanceIndexFromTail(int i) const;

  int getLength() const;

  void truncate(int start);

  SbBool containsNode(const SoNode *node) const;

  SbBool containsNode(const SoType type) 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);

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

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

  virtual SoType getTypeId() const;

  static SoType getClassTypeId();

 
  static SoPath *getByName(const SbName &name);
  static int getByName(const SbName &name, SoPathList &list);
 
 
 private:
  // Initializes path class
  static void initClass();
  static void exitClass();

  SbEventHandler<SoPath*> m_onPathChange;

  friend bool operator <(const SoPath &p1, const SoPath &p2);
 
  // This is called when a node in the path chain has a child added.
  // The passed index is the index of the new child
  void insertIndex(SoNode *parent, int newIndex);
 
  // This is called when a node in the path chain has a child removed.
  // The passed index is the index of the child to be removed
  void removeIndex(SoNode *parent, int oldIndex);
 
  // This is called when a node in the path chain replaces a child.
  // The passed index is the index of the child to be removed
  void replaceIndex(SoNode *parent, int index, SoNode *newChild);
 
  // Writes path using given write action
  virtual void write(SoWriteAction *writeAction) const;
 
  // Returns TRUE if the given notification list involves a change
  // to a node that affects the path. It is assumed that the last
  // (most recent) node in the list is the head node of the path.
  SbBool isRelevantNotification(SoNotList *list) const;
 
  void setNumPublic(int num);
 
  // Appends the given node and index to the lists, updating
  // numPublic as appropriate
  void append(SoNode *node, int index);
 
  // Appends the given node and index to the lists, updating
  // numPublic as appropriate
  void appendMI(SoNode *node, int index, int instanceIndex);
 
  // like copy but let user copy path in a temp path (if temp == true)
  SoPath *copy_(int startFromNodeIndex = 0, int numNodes = 0, bool createTempPath = false) const;
 
  // Returns this path hash value
  inline const size_t& getHash() const
  {
    if ( m_pathHash != static_cast< size_t >(-1) )
      return m_pathHash; // No need to update... just return value.
    return computeHash();
  }
 
  // Really does a truncate. Flag indicates whether to notify.
  void truncate(int start, SbBool doNotify);
 
  // Get nodes in a unsecured way: Only returns the found value without
  // checking out-of-array access.
  SoNode* u_getHead() const              { return (SoNode*)(const_cast<SoNodeList*>(&nodes)->getArray()[0]); }
  SoNode* u_getTail() const              { return (SoNode*)(const_cast<SoNodeList*>(&nodes)->getArray()[getLength() - 1]); }
  SoNode* u_getNode(int i) const         { return (SoNode*)(const_cast<SoNodeList*>(&nodes)->getArray()[i]); }
  SoNode* u_getNodeFromTail(int i) const { return (SoNode*)(const_cast<SoNodeList*>(&nodes)->getArray()[getLength() - 1 - i]); }
  int u_getIndex(int i) const            { return (int)indices[i].index; }
  int u_getIndexFromTail(int i) const    { return (int)indices[getLength() - 1 - i].index; }
  int u_getInstanceIndex(int i) const    { return (int)indices[i].instanceIndex; }
 
  // Multiple instance API see SoMultipleInstance, SoMultipleCopy, SoArray

  void setHeadMI(SoNode *node, int instanceIndex);

  void appendMI(int childIndex, int instanceIndex);

  void appendMI(SoNode *childNode, int instanceIndex);

  void pushMI(int childIndex, int instanceIndex);
 
  bool isForwardTraversing() const;
 
 private:
  // Allows internal SoTempPath subclass to forego auditor overhead
  void auditPath(SbBool flag) { doAuditors = flag; }
 
  // Reads stuff into instance of SoPath. Returns FALSE on error.
  virtual SbBool readInstance(SoInput *in, unsigned short flags);
 
  virtual ~SoPath();
 
 private:
   const size_t& computeHash() const;
 
  SoNodeList nodes;          // Pointers to nodes
  std::vector<inventor::NodeIndex> indices;      // Child indices
  mutable int numPublic;             // How many children are public
  mutable int minNumPublic;          // Minimum we KNOW are public
  SbBool doAuditors;         // TRUE if auditors to be maintained
  static SoType classTypeId; // TypeId of paths
 
  // Returns real length of path, including hidden children
  int getFullLength() const
    { return nodes.getLength(); }
 
  // Returns new SoPath; called by SoType::createInstance()
  static void* createInstance(SoType* dynamicType = NULL);
 
  // This path hash value
  mutable size_t m_pathHash;
 
  friend class SoFullPath;
  friend class SoTempPath;
  friend class SoAction;
  friend class SoPathNoRef;
  friend class SoTraversalPassImpl;
 
};

//
//  Class: SoFullPath
//
//  This 
//  children in paths. SoPath allows access from the head node down to
//  the first node with hidden children, but no further. Casting an
//  SoPath to an SoFullPath (which is always guaranteed to be safe)
//  allows you to get at hidden children. SoFullPath overrides some of
//  the methods defined on paths to make this possible.
//

class  SoFullPath : public SoPath {
 
 public:
  //
  // Override methods that normally stop at last public child:
  //
  void pop()
    { truncate(getFullLength() - 1); }

  SoNode *getTail() const
    { return (nodes[getFullLength() - 1]); }

  SoNode *getNodeFromTail(int i) const
    { return (nodes[getFullLength() - 1 - i]); }

  int getIndexFromTail(int i) const
  {
    return indices[getFullLength() - 1 - i].index;
  }

  int getInstanceIndexFromTail(int i) const
  {
    return indices[getFullLength() - 1 - i].instanceIndex;
  }

  int getLength() const
    { return getFullLength(); }
 
 private:
  SoFullPath(int approxLength) : SoPath(approxLength) {}
  virtual ~SoFullPath();
 
  friend class SoTempPath;
};
 
#ifndef HIDDEN_FROM_DOC

//
//  SoINTERNAL Class: SoLightPath
//
//  A SoLightPath is a light-weight version of an SoTempPath, intended to
//  be used just to keep track of the current path during traversal.
//  Eventually it is intended to replace SoTempPath (when appropriate
//  modifications are made to SoDraggers).
//  Unlike SoPath, it keeps only a chain of childIndices and a headnode.
//  The methods implemented are only those needed for traversal.
//
 
 
class  SoLightPath {
 
 private:
 
  // Constructor given approximate number of nodes in chain
  SoLightPath(int approxLength=0);
 
  SoLightPath(const SoLightPath& other);
 
  // Sets head node (first node in chain)
  // Resulting path has only one node.
  void                setHead(SoNode *node);
 
  // Adds node specified by child index to end of chain.
  void                append(int childIndex)
  { indices.push_back(inventor::NodeIndex(childIndex, inventor::NodeIndex::NODE));}
 
  // Adds node specified by child index along with its instanceIndex to end of chain.
  void                appendMI(int childIndex, int instanceIndex)
  { indices.push_back(inventor::NodeIndex(childIndex, instanceIndex)); }
 
 
  // Allows path to be treated as a stack: push a node at the end of
  // the chain and pop the last node off
  void                push(int childIndex)    { append(childIndex); }
  void                pushMI(int childIndex, int instanceIndex)    { appendMI(childIndex, instanceIndex); }
  void                push()                  { append(-1);}
  void                pop()           { truncate(getFullLength() - 1); }
 
  void setTail(int childIndex)
  {
    setTail(childIndex, inventor::NodeIndex::NODE);
  }
 
  void setTail(int childIndex, int instanceIndex)
  {
    setTail(inventor::NodeIndex(childIndex, instanceIndex));
  }
 
  void setTail(const inventor::NodeIndex& index)
  {
    size_t tailPos = (size_t)(getFullLength()-1);
    if ( tailPos >= indices.size() )
      indices.resize(tailPos+1);
    indices[tailPos] = index;
  }
 
  SoNode *            getTail(){
    return getNode(getFullLength()-1);
  }
 
  // Returns the first node in a path chain.
  SoNode *            getHead() const { return headNode; }
 
  // Returns pointer to ith node in chain
  SoNode *            getNode(int i) const;
 
  // BA - added getIndex
  // Returns index of ith node in chain
  int                 getIndex(int i) const
  {    
    return indices[i].index;
  }
 
  // Returns index of ith node in chain
  int                 getInstanceIndex(int i) const
  { return indices[i].instanceIndex; }
 
 
  // Returns full length of path chain (number of nodes)
  // note that public/private distinction is ignored.
  int                 getFullLength() const {return (int) indices.size();}
 
  // Removes all nodes from indexed node on
  void                truncate(int start)
  {
    indices.resize(start > 0 ? start : 0);
  }
 
 
  // fills in nodes for a TempPath that is represented by this
  // SoLightPath.  Called by SoAction::getCurPath();
  void                makeTempPath(SoTempPath *) const;
 
  SoLightPath& operator=(const SoLightPath& other);
 
 private:
 
  ~SoLightPath();
  SoNode *            headNode;       // Pointer to headnode
  mutable std::vector<inventor::NodeIndex> indices;        // Child indices
 
 
  friend class SoAction;
};
 
#endif // HIDDEN_FROM_DOC

 std::ostream& operator << (std::ostream& os, const SoPath& path);
 
#endif /* _SO_PATH_ */