Inventor/actions/SoAction.h

Go to the documentation of this file.

/*=======================================================================
 * 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-2020 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 __hpux
#  undef IN_PATH
#endif

#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; }

  enum DistribMode {
    LOCAL_ONLY,
    CLUSTER_ONLY,
    ALL
  };

  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 );

 private:

  // Null action method that can be stored in lookup table when desired
  static void         nullAction(SoAction *, SoNode *);

  // This enum is used to determine what the action is being applied to
  enum AppliedCode {
    NODE,                   // Applied to graph rooted by a node
    PATH,                   // Applied to graph defined by a path
    PATH_LIST               // Applied to graphs defined by list of paths
  };

  // This enum may be used during traversal of nodes to indicate
  // where the node is with respect to the path being traversed
  enum PathCode {
    NO_PATH,                // Not traversing a path
    IN_PATH,                // In middle of path chain (not tail node)
    BELOW_PATH,             // Tail node of path or below tail node
    OFF_PATH                // None of the above (Probably to the left)
  };

  // Returns code indicating what action is being applied to
  AppliedCode         getWhatAppliedTo() const   { return appliedTo.code; }

  // These returns a pointer to the node, path, or path list the
  // action is being applied to. Each returns NULL if the action is
  // not being applied to the appropriate class.
  SoNode *            getNodeAppliedTo() const  { return appliedTo.node.ptr(); }
  SoPath *            getPathAppliedTo() const  { return appliedTo.path.ptr(); }
  // A single path list may be split into several, one for each
  // different head node. These methods allow subclasses to
  // determine the current path list, the original path list, and
  // whether the current list is the last one from the original
  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;
  }

  // Does traversal of a graph rooted by a node
  // now defined in the .cxx
  void                traverse(SoNode *node);


  // Returns TRUE if the traversal has reached a termination condition
  SbBool              hasTerminated() const   { return terminated; }

  // Returns a pointer to the path accumulated during traversal,
  // i.e., the chain of nodes from the root of the traversed graph
  // to the current node being traversed.
  const SoPath *      getCurPath();

  // Get the state from the action
  // Note: Will return NULL if action has not been applied to anything
  //       or if invalidateState has been called.
  SoState *           getState() const        { return 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.

  // Creates state if it is NULL or it is no longer valid because new
  // elements have been enabled since it was created.  Automatically
  // called by the apply() methods, but can be useful for application
  // to get a non-null state pointer to "pre-load" certain elements.
  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(); }

  // added two switch..Traversal functions for SoRenderList
  //  Switches traversal to path, without calling beginTraversal.
  //  This allows a node during traversal to stop the current traversal
  //  method and start rendering a path.  The head of the path needs
  //  to be the currently traversed node, or a child.
  void                switchToPathTraversal(SoPath *path);

#if 1             SoDEPRECATED
  virtual void switchToNodeTraversal( SoNode* node );
#endif 
  SbBool hasChangedState() { return m_hasStateChanged; }

  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;

SoINTERNAL private:
  SoState             *state;         // Traversal state

  // 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;

  // Holds list of enabled elements for the SoAction class
  static SoEnabledElementsList *enabledElements;

  // ... and the methods
  static SoActionMethodList *methods;

  SbBool m_hasStateChanged;

  virtual bool mustTraverseDepth() { return false; }

  DistribMode m_distribMode;

 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:

  // Type identifier
  static SoType      classTypeId;
  static bool s_defaultAlternateRepUsage;

  SbThreadMutex* m_criticalSection;

  // 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_ */

---

Open Inventor Toolkit reference manual, generated on 12 Feb 2024
Copyright © Thermo Fisher Scientific All rights reserved. http://www.openinventor.com/