SoAction.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 : Gavin Bell (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-2023 BY FEI S.A.S,                        ***
 ***                        BORDEAUX, FRANCE                                        ***
 ***                      ALL RIGHTS RESERVED                                       ***
**=======================================================================*/
/*=======================================================================
** Modified by : VSG (MMM YYYY)
**=======================================================================*/
 
 
#ifndef  _SO_ACTION_
#define  _SO_ACTION_
 
#include <Inventor/SoLists.h>
#include <Inventor/SoTypedObject.h>
#include <Inventor/SoPath.h>
#include <Inventor/STL/cassert>
#include <SoDeprecationRules.h>
#include <Inventor/misc/SoTempPath.h>
#include <Inventor/misc/SoCompactPathList.h>
 
class SoEnabledElementsList;
class SoActionMethodList;
class SoSceneManager;
class SoMultiPassManager;
class SoTraversalPass;
class SoActionImpl;
 
#ifdef _WIN32
#pragma warning(push)
#pragma warning(disable:4251)
#endif

class  SoAction: public SoTypedObject {
 
 public:
  virtual ~SoAction();

  static SoType       getClassTypeId();

  virtual void        apply(SoNode *node);

  virtual void        apply(SoPath *path);

  virtual void        apply(const SoPathList &pathList,
                            SbBool obeysRules = FALSE);

  virtual void clearApplyResult() {};

  virtual void        invalidateState();

  void stopActionInBranch()
  { m_continueInBranchFlag = FALSE; }

  SbBool getContinueActionInBranchFlag() const
  { return m_continueInBranchFlag; }

  void resetContinueActionInBranchFlag()
  { m_continueInBranchFlag = TRUE; }

  void useAlternateRep(const SbBool enable);

  SbBool isUsingAlternateRep() const;

  void setSceneManager(SoSceneManager* mgr)
  { m_sceneManager = mgr; }

  SoSceneManager* getSceneManager() const
  { return m_sceneManager; }

  virtual void forwardTraversal( SoNode* node );

  virtual void forwardTraversal( SoPath* path );
 
  // SoEXTENDER section: the following methods are dedicated to extend the toolkit only
  public:

  enum DistribMode {
    LOCAL_ONLY,
    CLUSTER_ONLY,
    ALL
  };

  DistribMode getDistribMode() const
  { return m_distribMode; }

  static void         nullAction(SoAction *, SoNode *);

  enum AppliedCode {
    NODE,
    PATH,
    PATH_LIST
  };

  enum PathCode {
    NO_PATH,
    IN_PATH,
    BELOW_PATH,
    OFF_PATH
  };

  AppliedCode         getWhatAppliedTo() const   { return appliedTo.code; }

  SoNode *            getNodeAppliedTo() const  { return appliedTo.node.ptr(); }

  SoPath *            getPathAppliedTo() const  { return appliedTo.path.ptr(); }

  const SoPathList *  getPathListAppliedTo() const
    { return appliedTo.pathList; }

  const SoPathList *  getOriginalPathListAppliedTo() const
    { return appliedTo.origPathList; }

  SbBool              isLastPathListAppliedTo() const
    { return appliedTo.isLastPathList; }

  PathCode    getPathCode(int &numIndices, const int *&indices)
    {   if (appliedTo.curPathCode == IN_PATH) {
      usePathCode(numIndices, indices);
    }
    return appliedTo.curPathCode;
    }

  PathCode    getPathCodeMI(int &numIndices, const int *&indices, const int *&instanceIndices)
  {
    if (appliedTo.curPathCode == IN_PATH) {
      usePathCodeMI(numIndices, indices, instanceIndices);
    }
    return appliedTo.curPathCode;
  }

  void                traverse(SoNode *node);

  SbBool              hasTerminated() const   { return terminated; }

  const SoPath *      getCurPath();

  SoState* getState() const
  { return m_state; }
 
  // Changed to virtual so that derived actions that need to do
  // things to the state such as the GLRenderAction. This action
  // needs to change the value of whatChanged to ALL if the state has
  // been recreated because the number of elements has changed.

  virtual void                setUpState();

  virtual const SoEnabledElementsList & getEnabledElements() const;

  void setPipeId( int id )
  {  m_pipeId = id; }

  int getPipeId() const
  { return m_pipeId; }

  bool isBeingApplied() { return m_isBeingApplied; }

  virtual bool preDelayedTraversal()
  { return true; }

  virtual void postDelayedTraversal()
  {}
 
 private:
  static void         initClass();
  static void         exitClass();
 
  // Initialize ALL Inventor action classes
  static void         initClasses();
  static void         exitClasses();

  virtual bool isEnabledElement( const SoType& ) const;
 
  // These methods maintain the current path accumulated so far
  // during traversal. The action needs to know whether this path is
  // a subset of the path being applied to; it saves this info in
  // the onPath variable. Before a node is pushed onto the current
  // path, call getOnPath() to determine the current setting. The
  // value of this flag should be passed in to popCurPath() so the
  // onPath variable can be restored.
  PathCode            getCurPathCode() const { return appliedTo.curPathCode;}
  // lastFound is an inout parameter that contains the last indices found in the compactPathList
  // for the current separator. When iterating over children of a separator it
  // should be set to 0 on first call then the returned result has to be reused until the last
  // call for the separator.
  void                pushCurPath(int childIndex, int &lastFound);
  // lastFound is an inout parameter that contains the last indices found in the compactPathList
  // for the current separator. When iterating over children of a separator it
  // should be set to 0 on first call then the returned result has to be reused until the last
  // call for the separator.
  void                pushCurPathMI(int childIndex, int &lastFound, int instanceIndex);
  void                popCurPath(PathCode prevPathCode);
  // This is virtual, so that SoCallbackAction can use current node.
  virtual SoNode *    getCurPathTail();
 
  // ask if action is currently forward traversed
  bool isForwardTraversing() const { return appliedTo.isForwardTraversing;  }
 
  // get the public node if action is forward traversed
  SoNode* getForwardTraversalCaller() const { return appliedTo.forwardTraversalCaller.ptr(); }
 
  // called by inline getPathCode:
  void                usePathCode(int &numIndices, const int *&indices);
  // called by inline getPathCode:
  void                usePathCodeMI(int &numIndices, const int *&indices, const int *&instanceIndices);
 
  // Optimized versions of push/pop when we know path codes won't
  // change:
  void                pushCurPath()
    { curPath.append(-1); }
  void                popPushCurPath(int childIndex)
    { curPath.setTail(childIndex);}
  // generalization for multi-instancing
  void                popPushCurPathMI(int childIndex, int instanceIndex)
  { curPath.setTail(childIndex, instanceIndex);}
  void                popCurPath()
    { curPath.pop(); }
 
  // Returns true if the state has been reset since action traversal startup
  // ie. setupState recreated the state because of some new elements enabled.
  SbBool hasChangedState() const
  { return m_hasStateChanged; }
#if 1             SoDEPRECATED
  virtual void switchToNodeTraversal( SoNode* node );
SoDEPRECATED
  void switchToPathTraversal( SoPath* path )
  {
    forwardTraversal( path );
  }
#endif 
 
 
  DistribMode getDistribMode() { return m_distribMode; }
 
 
  // Enter critical section for this action
  inline void lock()
  { m_criticalSection->lock(); }
 
  // Exit critical section for this action
  inline void unlock()
  { m_criticalSection->unlock(); }
 

  inline bool isAbortable() const
  { return m_isAbortable; }

  inline void setAbortable(bool flag)
  { m_isAbortable = flag; }

  bool shouldAbort() const;

  void abort();

  bool isAborted() const;
 
 private:
  // Constructor
  SoAction();
 
  // WARNING : Copy constructor should never be called.
  // WARNING : Implemented here only to add a debug message to derived class.
  SoAction(const SoAction&);
 
  // Begins traversal of an action at the given node. The default
  // method just calls traverse(node). This is virtual to allow
  // subclasses to do extra work before or after traversing the node.
  virtual void        beginTraversal(SoNode *node);
 
  // Ends traversal of an action at the given node. By default
  // nothing is gone
  virtual void        endTraversal(SoNode *) { ; }
 
  // Allows subclass instance to indicate that traversal has reached
  // a termination condition
  void                setTerminated(SbBool flag)      { terminated = flag; }
 
  // This method is used when applying an action to an SoPathList.
  // It returns TRUE if the action should create a compact version
  // of the path list before applying itself to it. The default
  // method returns TRUE, since the compact version is more
  // efficient. Some actions may choose to return FALSE; for
  // example, the SoWriteAction applies itself to each path
  // separately, so it doesn't need the extra overhead of compacting
  // the list.
  virtual SbBool      shouldCompactPathLists() const;

  void setDistribMode(DistribMode mode )
  { m_distribMode = mode; }
 
SoINTERNAL private:
 
  // Holds list of enabled elements for the SoAction class
  static SoEnabledElementsList *enabledElements;
 
  // ... and the methods
  static SoActionMethodList *methods;
 
  SoLightPath* getCurLightPath()
  { return &curPath; }
 
 private:
 
  virtual SoActionMethodList* getActionMethods();
  SbBool getUseAlternateRep() const
  { return m_useAlternatRep; }
 
  SbBool isForcedUseAlternateRep() const
  { return m_forceUseAlternateRep; }
 
  SoMultiPassManager* getMultiPassManager() const
  { return m_multiPassManager; }
 
  bool isApplyingDelayed() const;
 
  SoActionImpl* getImpl() { return m_impl; }
 
 private:
  // Current Traversal state
  SoState* m_state;
 
  // Type identifier
  static SoType      classTypeId;
  static bool s_defaultAlternateRepUsage;
 
  // Critical section use in multi-thread to protect the action state
  SbThreadMutex* m_criticalSection;
 
  // This indicates if we must stop this action in the current Scene Graph branch
  SbBool m_continueInBranchFlag;
 
  // This is the current path through the graph the action is being applied to
  SoLightPath curPath;
 
  SbBool m_hasStateChanged;
 
  // Current Distribution mode (ScaleViz Cluster)
  DistribMode m_distribMode;
 
  // This structure holds the necessary information about what the
  // action is being applied to. It allows this information to be
  // saved and restored when necessary.
  struct AppliedTo {
    AppliedCode code;
    SoRef<SoNode> node;             // If code is NODE
    SoRef<SoPath> path;             // If code is PATH
    const SoPathList *pathList;       // If code is PATH_LIST
    const SoPathList *origPathList;
    SoRef<SoCompactPathList> compactPathList;
    int isLastPathList;
    PathCode curPathCode;
    bool isForwardTraversing;  // true if the action is inside a forward traversal
    SoRef<SoNode> forwardTraversalCaller; // node that call forwardTraversal, if any.
 
    // Default Constructor
    AppliedTo();
  } appliedTo;
 
  // This is set to TRUE while the action is being applied, so we
  // can tell if the action is being applied recursively.
  bool m_isBeingApplied;
 
  // Indicate if we should ask for alternate representation or not
  // default is FALSE.
  SbBool m_useAlternatRep;
 
  // Indicate if we force for using alternate representation or not
  // default is FALSE.
  SbBool m_forceUseAlternateRep;
 
  // This holds the current path (nodes and childindices) whenever
  // action->getCurPath is called:
  SoRef<SoTempPath>       tempPath;
 
 
  // Holds enabled-elements counter when state is created; used to
  // determine whether list of enabled elements is up to date.
  int                 enabledElementsCounter;
 
  // This is TRUE if the action has reached a termination condition
  SbBool              terminated;
 
  // Stores next index in path being applied to so a pointer to it
  // can be returned
  int                 index;
 
 
  // Cleans up after an action is done
  void                cleanUp();
 
  // Splits a sorted path list based on head nodes, then applies to each
  void                splitPathList(const SoPathList &sortedList,
                                    const SoPathList &origPathList);
 
  // Applies action to sorted path list
  void                apply(const SoPathList &sortedList,
                            const SoPathList &origPathList,
                            SbBool isLastPathList);
 
  int m_pipeId;   // this render action pipe id
 
  SoSceneManager* m_sceneManager;
 
  SoMultiPassManager* m_multiPassManager;
 
  bool m_isAbortable;
 
  SoActionImpl* m_impl;
 
  friend class SoDB;
  friend class SoMultiPassElement;
};
 
#ifndef HIDDEN_FROM_DOC
//
//  Classes can use this macro to enable a specific element class
//  within a specific action class. E.g.:
//
//      SO_ENABLE(SoGetBoundingBoxAction, SoModelMatrixElement);
//
 
#define SO_ENABLE(actionClass, elementClass)                            \
  if ( elementClass::getClassTypeId().isBad() )                         \
          elementClass::initClass();                                    \
        actionClass::enableElement(elementClass::getClassTypeId(),      \
                                   elementClass::getClassStackIndex())
 
//
 
#include <Inventor/lists/SoActionMethodList.h>
#include <Inventor/lists/SoEnabledElementsList.h>
 
#endif // HIDDEN_FROM_DOC
 
#ifdef _WIN32
#pragma warning(pop)
#endif
 
#endif /* _SO_ACTION_ */