Open Inventor Release 2023.2.2
 
Loading...
Searching...
No Matches
SoAction Class Reference

Abstract base class for all actions. More...

#include <Inventor/actions/SoAction.h>

+ Inheritance diagram for SoAction:

Public Types

enum  DistribMode {
  LOCAL_ONLY ,
  CLUSTER_ONLY ,
  ALL
}
 This is used to define the way an action is distributed across a cluster. More...
 
enum  AppliedCode {
  NODE ,
  PATH ,
  PATH_LIST
}
 This enum is used to determine what the action is being applied to. More...
 
enum  PathCode {
  NO_PATH ,
  IN_PATH ,
  BELOW_PATH ,
  OFF_PATH
}
 This enum may be used during traversal of nodes to indicate where the node is with respect to the path being traversed. More...
 

Public Member Functions

virtual ~SoAction ()
 Destructor.
 
virtual void apply (SoNode *node)
 Initiates an action on the graph defined by a node.
 
virtual void apply (SoPath *path)
 Initiates an action on the graph defined by a path.
 
virtual void apply (const SoPathList &pathList, SbBool obeysRules=FALSE)
 Initiates an action on the graph defined by a list of paths.
 
virtual void clearApplyResult ()
 When applied, an action may reference nodes or create objects (e.g.
 
virtual void invalidateState ()
 Invalidates the current traversal state in the action, forcing it to be recreated when the action is next applied.
 
void stopActionInBranch ()
 This function stops the action in the current Scene Graph branch.
 
SbBool getContinueActionInBranchFlag () const
 This function indicates if the action must stop in the current branch.
 
void resetContinueActionInBranchFlag ()
 This function resets the continue action flag.
 
void useAlternateRep (const SbBool enable)
 Tell the action to use alternate representations during traversal when available.
 
SbBool isUsingAlternateRep () const
 Returns TRUE if current action is using alternate representations.
 
void setSceneManager (SoSceneManager *mgr)
 Set the scene manager associated with this action (if any ).
 
SoSceneManagergetSceneManager () const
 Return the SoSceneManager associated with this action.
 
virtual void forwardTraversal (SoNode *node)
 Traverse a node that is not part of the current scenegraph.
 
virtual void forwardTraversal (SoPath *path)
 Traverse a path that is not part of the current scenegraph.
 
DistribMode getDistribMode () const
 Returns the distribution mode of this action across a cluster (ScaleViz-Cluster only).
 
AppliedCode getWhatAppliedTo () const
 Returns code indicating what action is being applied to.
 
SoNodegetNodeAppliedTo () const
 Returns the node the action is being applied to.
 
SoPathgetPathAppliedTo () const
 Returns the path the action is being applied to.
 
const SoPathListgetPathListAppliedTo () const
 Returns the path list the action is being applied to.
 
const SoPathListgetOriginalPathListAppliedTo () const
 Returns the original path list the action is being applied to.
 
SbBool isLastPathListAppliedTo () const
 Returns TRUE if the current list is the last one from the original.
 
PathCode getPathCode (int &numIndices, const int *&indices)
 Returns path code based on where current node (the node at the end of the current path) lies with respect to the path(s) the action is being applied to.
 
PathCode getPathCodeMI (int &numIndices, const int *&indices, const int *&instanceIndices)
 Extender API: available to programmers who wish to extend the toolkit
 
void traverse (SoNode *node)
 Does traversal of a graph rooted by a node.
 
SbBool hasTerminated () const
 Returns TRUE if the traversal has reached a termination condition.
 
const SoPathgetCurPath ()
 Returns the path accumulated during traversal, i.e., the chain of nodes from the root of the traversed graph to the current node being traversed.
 
SoStategetState () const
 Gets the state from the action.
 
virtual void setUpState ()
 Creates state if it is NULL or it is no longer valid because new elements have been enabled since it was created.
 
virtual const SoEnabledElementsList & getEnabledElements () const
 Returns the list of enabled elements for a given action subclass.
 
void setPipeId (int id)
 Sets pipe identifier in the range [1..N] associated to this render action while running a ScaleViz Multipipe configuration.
 
int getPipeId () const
 Gets pipe identifier in the range [1..N] associated to this render action while running a ScaleViz Multipipe configuration.
 
bool isBeingApplied ()
 Returns TRUE if this action is currently being applied.
 
virtual bool preDelayedTraversal ()
 Method called by SoMultiPassManager before delayed pass traversals.
 
virtual void postDelayedTraversal ()
 Method called by SoMultiPassManager after delayed pass traversals.
 
- Public Member Functions inherited from SoTypedObject
virtual SoType getTypeId () const =0
 Returns the type identifier for a specific instance.
 
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 the type identifier for this class.
 
static void nullAction (SoAction *, SoNode *)
 Null action method that can be stored in lookup table when desired.
 
- Static Public Member Functions inherited from SoTypedObject
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 

Deprecated

class SoDB
 Traverse a node that is not part of the current scenegraph.
 
class SoMultiPassElement
 Traverse a node that is not part of the current scenegraph.
 

Detailed Description

Abstract base class for all actions.

SoAction is the base class for all actions. Classes derived from SoAction define operations to be applied at each node encountered during traversal of a scene graph. The function that gets called to implement the action for a particular node type is determined by a lookup table in the global database.

An action may be applied to a node (SoNode), a path (SoPath) or a list of paths (SoPathList).

Reference counting:

Warning: Most actions call ref() on the node (or path) before traversing the scene graph, then call unref() after traversal. If the node (or path) has a reference count of zero (the default), the call to apply() will cause it to be destroyed! A warning message is posted in this case when using a debug build of Open Inventor.

Hidden references:

Some actions, e.g. SoSearchAction and SoRayPickAction, create one or more SoPath objects when they are applied to the scene graph. The SoPath object calls ref() on each node in the path. This reference will prevent the node from being destroyed for as long as the SoPath object exists. These SoPath objects are stored internally in the action and exist until the action object itself is destroyed or reset.

SEE ALSO

SoNode, SoPath, SoPathList, SoCallbackAction, SoGLRenderAction, SoGetBoundingBoxAction, SoGetMatrixAction, SoHandleEventAction, SoPickAction, SoRayPickAction, SoSearchAction, SoWriteAction

Definition at line 132 of file SoAction.h.

Member Enumeration Documentation

◆ AppliedCode

This enum is used to determine what the action is being applied to.

Extender API: available to programmers who wish to extend the toolkit

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

Definition at line 313 of file SoAction.h.

◆ DistribMode

This is used to define the way an action is distributed across a cluster.

Extender API: available to programmers who wish to extend the toolkit

Enumerator
LOCAL_ONLY 

Action is only applied by the application.

CLUSTER_ONLY 

Action is only applied by OIRU of the cluster.

ALL 

Both application and cluster apply the action.

Definition at line 286 of file SoAction.h.

◆ PathCode

This enum may be used during traversal of nodes to indicate where the node is with respect to the path being traversed.

Extender API: available to programmers who wish to extend the toolkit

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

Definition at line 327 of file SoAction.h.

Constructor & Destructor Documentation

◆ ~SoAction()

virtual SoAction::~SoAction ( )
virtual

Destructor.

Member Function Documentation

◆ apply() [1/3]

virtual void SoAction::apply ( const SoPathList pathList,
SbBool  obeysRules = FALSE 
)
virtual

Initiates an action on the graph defined by a list of paths.

TRUE can be passed for the obeysRules flag if the given path list has the following 4 properties:

  1. All paths have the same head node.
  2. Paths are sorted in traversal order.
  3. If one path ends at node A, no other path continues through A.
  4. No two paths are the same.

These rules will be obeyed by path lists returned by picking and by searches for non-group nodes.

Reimplemented in SoGlobalSimplifyAction, SoReorganizeAction, SoShapeSimplifyAction, SoSplitGeometryAction, SoToHTMLAction, SoToU3DAction, SoVectorizeAction, SoBevelAction, SoGLRenderAction, SoRayPickAction, SoIntersectionDetectionAction, and SoSTLWriteAction.

◆ apply() [2/3]

virtual void SoAction::apply ( SoNode node)
virtual

Initiates an action on the graph defined by a node.

Warning: Most actions call ref() on the node before traversing the scene graph, then call unref() after traversal. If the node's reference count was zero (the default), the call to apply() will cause it to be destroyed.

Reimplemented in SoToU3DAction, SoVectorizeAction, SoBevelAction, SoBoxHighlightRenderAction, SoGlobalSimplifyAction, SoGLRenderAction, SoHighlightRenderAction, SoRayPickAction, SoReorganizeAction, SoShapeSimplifyAction, SoSplitGeometryAction, SoIntersectionDetectionAction, SoSTLWriteAction, and SoToHTMLAction.

◆ apply() [3/3]

virtual void SoAction::apply ( SoPath path)
virtual

Initiates an action on the graph defined by a path.

Warning: Most actions call ref() on the path before traversing the scene graph, then call unref() after traversal. If the path's reference count was zero (the default), the call to apply() will cause it to be destroyed.

Reimplemented in SoToU3DAction, SoVectorizeAction, SoBevelAction, SoGlobalSimplifyAction, SoGLRenderAction, SoRayPickAction, SoReorganizeAction, SoShapeSimplifyAction, SoSplitGeometryAction, SoToHTMLAction, SoIntersectionDetectionAction, and SoSTLWriteAction.

◆ clearApplyResult()

virtual void SoAction::clearApplyResult ( )
inlinevirtual

When applied, an action may reference nodes or create objects (e.g.

SoPath) that reference nodes. This is especially true for SoSearchAction and SoRayPickAction. These references will prevent the nodes from being destroyed and so may appear to be a "memory leak".

All references are cleared when the action is destroyed or re-applied. However it may be useful to clear them explicitly to remove references to nodes.

Reimplemented in SoGlobalSimplifyAction, SoHandleEventAction, SoHighlightRenderAction, SoRayPickAction, and SoSearchAction.

Definition at line 189 of file SoAction.h.

◆ forwardTraversal() [1/2]

virtual void SoAction::forwardTraversal ( SoNode node)
virtual

Traverse a node that is not part of the current scenegraph.

Like an SoNodeKit, the contents of the specified sub-scenegraph won't be visible as an SoPath. Casting the path to a SoFullPath allows access to the whole path.

This method can be used to delegate an action to an internal/private scene graph. So a node can have an internal scene graph without actually being a "group" node. This is a convenient way to implement "composite" nodes that create their behavior using other Open Inventor nodes.

The node parameter can be of any type. Sensors may still be attached directly to nodes and fields in the internal scene graph.

This method must not be called from a node derived from SoGroup or SoBaseKit. This method should not be called on nodes that are part of the public/visible scene graph.

Reimplemented in SoToU3DAction.

◆ forwardTraversal() [2/2]

virtual void SoAction::forwardTraversal ( SoPath path)
virtual

Traverse a path that is not part of the current scenegraph.

Similar to forwardTraversal(SoNode*) but for paths.

Reimplemented in SoToU3DAction.

◆ getClassTypeId()

static SoType SoAction::getClassTypeId ( )
static

Returns the type identifier for this class.

◆ getContinueActionInBranchFlag()

SbBool SoAction::getContinueActionInBranchFlag ( ) const
inline

This function indicates if the action must stop in the current branch.

Returns
TRUE if the action must continue for this branch.

Definition at line 212 of file SoAction.h.

◆ getCurPath()

const SoPath * SoAction::getCurPath ( )

Returns the path accumulated during traversal, i.e., the chain of nodes from the root of the traversed graph to the current node being traversed.

Extender API: available to programmers who wish to extend the toolkit

◆ getDistribMode()

DistribMode SoAction::getDistribMode ( ) const
inline

Returns the distribution mode of this action across a cluster (ScaleViz-Cluster only).

Default is LOCAL_ONLY. Extender API: available to programmers who wish to extend the toolkit

Definition at line 300 of file SoAction.h.

◆ getEnabledElements()

virtual const SoEnabledElementsList & SoAction::getEnabledElements ( ) const
virtual

Returns the list of enabled elements for a given action subclass.

Extender API: available to programmers who wish to extend the toolkit

◆ getNodeAppliedTo()

SoNode * SoAction::getNodeAppliedTo ( ) const
inline

Returns the node the action is being applied to.

Returns NULL if the action is not being applied to the appropriate class. Extender API: available to programmers who wish to extend the toolkit

Definition at line 349 of file SoAction.h.

◆ getOriginalPathListAppliedTo()

const SoPathList * SoAction::getOriginalPathListAppliedTo ( ) const
inline

Returns the original path list the action is being applied to.

Returns NULL if the action is not being applied to the appropriate class.

Note
A single path list may be split into several, one for each different head node. This method allows subclasses to determine the original path list. Extender API: available to programmers who wish to extend the toolkit

Definition at line 377 of file SoAction.h.

◆ getPathAppliedTo()

SoPath * SoAction::getPathAppliedTo ( ) const
inline

Returns the path the action is being applied to.

Returns NULL if the action is not being applied to the appropriate class. Extender API: available to programmers who wish to extend the toolkit

Definition at line 356 of file SoAction.h.

◆ getPathCode()

PathCode SoAction::getPathCode ( int &  numIndices,
const int *&  indices 
)
inline

Returns path code based on where current node (the node at the end of the current path) lies with respect to the path(s) the action is being applied to.

If this returns IN_PATH, indices is set to point to an array of indices corresponding to the children that must be traversed for a correct traversal of all the paths to which the action is being applied. numIndices is set to the number of such children. Extender API: available to programmers who wish to extend the toolkit

Definition at line 402 of file SoAction.h.

◆ getPathCodeMI()

PathCode SoAction::getPathCodeMI ( int &  numIndices,
const int *&  indices,
const int *&  instanceIndices 
)
inline

◆ getPathListAppliedTo()

const SoPathList * SoAction::getPathListAppliedTo ( ) const
inline

Returns the path list the action is being applied to.

Returns NULL if the action is not being applied to the appropriate class.

Note
A single path list may be split into several, one for each different head node. This method allows subclasses to determine the current path list. Extender API: available to programmers who wish to extend the toolkit

Definition at line 366 of file SoAction.h.

◆ getPipeId()

int SoAction::getPipeId ( ) const
inline

Gets pipe identifier in the range [1..N] associated to this render action while running a ScaleViz Multipipe configuration.

Extender API: available to programmers who wish to extend the toolkit

Definition at line 483 of file SoAction.h.

◆ getSceneManager()

SoSceneManager * SoAction::getSceneManager ( ) const
inline

Return the SoSceneManager associated with this action.

Definition at line 248 of file SoAction.h.

◆ getState()

SoState * SoAction::getState ( ) const
inline

Gets the state from the action.

Note
Will return NULL if action has not been applied to anything or if invalidateState has been called. Extender API: available to programmers who wish to extend the toolkit

Definition at line 446 of file SoAction.h.

◆ getWhatAppliedTo()

AppliedCode SoAction::getWhatAppliedTo ( ) const
inline

Returns code indicating what action is being applied to.

Extender API: available to programmers who wish to extend the toolkit

Definition at line 342 of file SoAction.h.

◆ hasTerminated()

SbBool SoAction::hasTerminated ( ) const
inline

Returns TRUE if the traversal has reached a termination condition.

Extender API: available to programmers who wish to extend the toolkit

Definition at line 430 of file SoAction.h.

◆ invalidateState()

virtual void SoAction::invalidateState ( )
virtual

Invalidates the current traversal state in the action, forcing it to be recreated when the action is next applied.

This is typically unnecessary in most applications.

Reimplemented in SoGLRenderAction.

◆ isBeingApplied()

bool SoAction::isBeingApplied ( )
inline

Returns TRUE if this action is currently being applied.

Extender API: available to programmers who wish to extend the toolkit

Definition at line 490 of file SoAction.h.

◆ isLastPathListAppliedTo()

SbBool SoAction::isLastPathListAppliedTo ( ) const
inline

Returns TRUE if the current list is the last one from the original.

Note
A single path list may be split into several, one for each different head node. This method allows subclasses to determine whether the current list is the last one from the original. Extender API: available to programmers who wish to extend the toolkit

Definition at line 387 of file SoAction.h.

◆ isUsingAlternateRep()

SbBool SoAction::isUsingAlternateRep ( ) const

Returns TRUE if current action is using alternate representations.

Default is FALSE.

◆ nullAction()

static void SoAction::nullAction ( SoAction ,
SoNode  
)
static

Null action method that can be stored in lookup table when desired.

Extender API: available to programmers who wish to extend the toolkit

◆ postDelayedTraversal()

virtual void SoAction::postDelayedTraversal ( )
inlinevirtual

Method called by SoMultiPassManager after delayed pass traversals.

Overriding this method can be useful for actions that want to apply some post processing after all delayed pass traversals. Since Open Inventor 9.1 Extender API: available to programmers who wish to extend the toolkit

Definition at line 509 of file SoAction.h.

◆ preDelayedTraversal()

virtual bool SoAction::preDelayedTraversal ( )
inlinevirtual

Method called by SoMultiPassManager before delayed pass traversals.

Overriding this method can be useful for actions that want to skip the traversal of all delayed passes. Returning false skips the delayed pass traversals. Since Open Inventor 9.1 Extender API: available to programmers who wish to extend the toolkit

Definition at line 499 of file SoAction.h.

◆ resetContinueActionInBranchFlag()

void SoAction::resetContinueActionInBranchFlag ( )
inline

This function resets the continue action flag.

Definition at line 218 of file SoAction.h.

◆ setPipeId()

void SoAction::setPipeId ( int  id)
inline

Sets pipe identifier in the range [1..N] associated to this render action while running a ScaleViz Multipipe configuration.

Extender API: available to programmers who wish to extend the toolkit

Definition at line 475 of file SoAction.h.

◆ setSceneManager()

void SoAction::setSceneManager ( SoSceneManager mgr)
inline

Set the scene manager associated with this action (if any ).

When appropriate, this allows the action to query information like the OpenGL rendering context. The SoSCeneManager class calls this method automatically for the actions that it creates (SoHandleEventAction, SoRayPickAction, etc).

Definition at line 242 of file SoAction.h.

◆ setUpState()

virtual void SoAction::setUpState ( )
virtual

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. Extender API: available to programmers who wish to extend the toolkit

◆ stopActionInBranch()

void SoAction::stopActionInBranch ( )
inline

This function stops the action in the current Scene Graph branch.

Note: It doesn't mean we kill the action!

It is mainly used to stop the GetBoundingBox action in the SoBBox node.

Definition at line 204 of file SoAction.h.

◆ traverse()

void SoAction::traverse ( SoNode node)

Does traversal of a graph rooted by a node.

Extender API: available to programmers who wish to extend the toolkit

◆ useAlternateRep()

void SoAction::useAlternateRep ( const SbBool  enable)

Tell the action to use alternate representations during traversal when available.


See SoNode::getAternateRep(). Default is FALSE. When true, it is the responsibility of each SoNode derived object to choose to provide or not an alternate representation for a given action.

Friends And Related Symbol Documentation

◆ SoDB

friend class SoDB
friend

Traverse a node that is not part of the current scenegraph.

Like an SoNodeKit, the contents of the specified sub-scenegraph won't be visible as an SoPath. Casting the path to a SoFullPath allows access to the whole path.

This method can be used to delegate an action to an internal/private scene graph. So a node can have an internal scene graph without actually being a "group" node. This is a convenient way to implement "composite" nodes that create their behavior using other Open Inventor nodes.

The node parameter can be of any type. Sensors may still be attached directly to nodes and fields in the internal scene graph.

This method must not be called from a node derived from SoGroup or SoBaseKit. This method should not be called on nodes that are part of the public/visible scene graph.

Definition at line 800 of file SoAction.h.

◆ SoMultiPassElement

friend class SoMultiPassElement
friend

Traverse a node that is not part of the current scenegraph.

Like an SoNodeKit, the contents of the specified sub-scenegraph won't be visible as an SoPath. Casting the path to a SoFullPath allows access to the whole path.

This method can be used to delegate an action to an internal/private scene graph. So a node can have an internal scene graph without actually being a "group" node. This is a convenient way to implement "composite" nodes that create their behavior using other Open Inventor nodes.

The node parameter can be of any type. Sensors may still be attached directly to nodes and fields in the internal scene graph.

This method must not be called from a node derived from SoGroup or SoBaseKit. This method should not be called on nodes that are part of the public/visible scene graph.

Definition at line 801 of file SoAction.h.


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