Coin: SoAction Class Reference

| Coin3D is Free Software, published under the BSD 3-clause license. | https://coin3d.github.io https://www.kongsberg.com/en/kogt/

SoAction Class Referenceabstract
Action Classes

The SoAction class is the base class for all traversal actions. More...

`#include <Inventor/actions/SoAction.h>`

Inheritance diagram for SoAction:

## Public Types
enum | AppliedCode { NODE = 0 , PATH = 1 , PATH_LIST = 2 }
enum | PathCode { NO_PATH = 0 , IN_PATH = 1 , BELOW_PATH = 2 , OFF_PATH = 3 }

## Public Member Functions
virtual | ~SoAction (void)
virtual SoType | getTypeId (void) const =0
virtual SbBool | isOfType (SoType type) const
virtual void | apply (SoNode *root)
virtual void | apply (SoPath *path)
virtual void | apply (const SoPathList &pathlist, SbBool obeysrules=FALSE)
void | apply (SoAction *beingApplied)
virtual void | invalidateState (void)
AppliedCode | getWhatAppliedTo (void) const
SoNode * | getNodeAppliedTo (void) const
SoPath * | getPathAppliedTo (void) const
const SoPathList * | getPathListAppliedTo (void) const
const SoPathList * | getOriginalPathListAppliedTo (void) const
SbBool | isLastPathListAppliedTo (void) const
PathCode | getPathCode (int &numindices, const int *&indices)
void | traverse (SoNode *const node)
SbBool | hasTerminated (void) const
const SoPath * | getCurPath (void)
SoState * | getState (void) const
PathCode | getCurPathCode (void) const
virtual SoNode * | getCurPathTail (void)
void | usePathCode (int &numindices, const int *&indices)
void | pushCurPath (const int childindex, SoNode *node=NULL)
void | popCurPath (const PathCode prevpathcode)
void | pushCurPath (void)
void | popPushCurPath (const int childindex, SoNode *node=NULL)
void | popCurPath (void)
void | switchToPathTraversal (SoPath *path)
void | switchToNodeTraversal (SoNode *node)

## Static Public Member Functions
static void | initClass (void)
static void | initClasses (void)
static SoType | getClassTypeId (void)
static void | nullAction (SoAction *action, SoNode *node)

## Protected Member Functions
| SoAction (void)
virtual void | beginTraversal (SoNode *node)
virtual void | endTraversal (SoNode *node)
void | setTerminated (const SbBool flag)
virtual const SoEnabledElementsList & | getEnabledElements (void) const
virtual SbBool | shouldCompactPathList (void) const

## Static Protected Member Functions
static SoEnabledElementsList * | getClassEnabledElements (void)
static SoActionMethodList * | getClassActionMethods (void)

## Protected Attributes
SoState * | state
SoActionMethodList * | traversalMethods

## Detailed Description

The SoAction class is the base class for all traversal actions.

Applying actions is the basic mechanism in Coin for executing various operations on scene graphs or paths within scene graphs, including search operations, rendering, interaction through picking, etc.

The basic operation is to instantiate an action, set it up with miscellaneous parameters if necessary, then call its apply() method on the root node of the scene graph (or subgraph of a scene graph). The action then traverses the scene graph from the root node, depth-first and left-to-right, applying its specific processing at the nodes where it is applicable.

(The SoAction and its derived classes in Coin is an implementation of the design pattern commonly known as the "Visitor" pattern.)

Here's a simple example that shows how to use the SoWriteAction to dump a scene graph in the Inventor format to a file:

int write_scenegraph(const char * filename, SoNode * root)
{
SoOutput output;
if (!output.openFile(filename)) return 0;
// This is where the action is. ;-)
SoWriteAction wa(&output);
wa.apply(root);
return 1;
}
SoNode
The SoNode class is the base class for nodes used in scene graphs.
Definition SoNode.h:56
SoOutput
The SoOutput class is an abstraction of an output stream.
Definition SoOutput.h:51
SoOutput::openFile
virtual SbBool openFile(const char *const fileName)
Definition SoOutput.cpp:413
SoWriteAction
The SoWriteAction class writes a scene graph to file.
Definition SoWriteAction.h:42

After traversal, some action types have stored information about the (sub-)scene graph that was traversed, which you can then inquire about through methods like SoGetBoundingBoxAction::getBoundingBox(), SoRayPickAction::getPickedPoint(), SoGetPrimitiveCountAction::getTriangleCount(), etc.

See the various built-in actions for further information (i.e. the subclasses of this class), or look at the example code applications of the Coin library to see how actions are generally used.

For extending the Coin library with your own classes, we strongly recommend that you make yourself acquainted with the excellent «The Inventor Toolmaker» book (ISBN 0-201-62493-1), which describes the tasks involved in detail. This book was written by the original SGI Inventor designers and explains many of the underlying design ideas, as well as having lots of hands-on examples on how to extend the Coin toolkit in ways that are true to the fundamental design ideas. («The Inventor Toolmaker» is also available at SGI's online library, at no cost. See Download The Inventor Toolmaker.) Reading the source code of the built-in classes in Coin should also prove very helpful.
The following example shows the basic outline on how to set up your own extension action class:

// This is sample code on how you can get progress indication on Coin
// export operations by extending the library with your own action
// class. The new class inherits SoWriteAction. The code is presented
// as a standalone example.
//
// The general technique is to inherit SoWriteAction and override its
// "entry point" into each node of the scene graph. The granularity of
// the progress callbacks is on a per node basis, which should usually
// be good enough.
#include <Inventor/SoDB.h>
#include <Inventor/actions/SoWriteAction.h>
#include <Inventor/nodes/SoSeparator.h>
class MyWriteAction : public SoWriteAction {
SO_ACTION_HEADER(SoWriteAction);
public:
MyWriteAction(SoOutput * out);
virtual ~MyWriteAction();
static void initClass(void);
protected:
virtual void beginTraversal(SoNode * node);
private:
static void actionMethod(SoAction *, SoNode *);
int nrnodes;
int totalnrnodes;
};
SO_ACTION_SOURCE(MyWriteAction);
MyWriteAction::MyWriteAction(SoOutput * out)
: SoWriteAction(out)
{
SO_ACTION_CONSTRUCTOR(MyWriteAction);
}
MyWriteAction::~MyWriteAction()
{
}
void
MyWriteAction::initClass(void)
{
SO_ACTION_INIT_CLASS(MyWriteAction, SoWriteAction);
SO_ACTION_ADD_METHOD(SoNode, MyWriteAction::actionMethod);
}
void
MyWriteAction::beginTraversal(SoNode * node)
{
this->nrnodes = 0;
this->totalnrnodes = 0;
SoWriteAction::beginTraversal(node);
}
void
MyWriteAction::actionMethod(SoAction * a, SoNode * n)
{
// To abort the export process in mid-writing, we could just avoid
// calling in to the SoNode::writeS() method.
SoNode::writeS(a, n);
MyWriteAction * mwa = (MyWriteAction *)a;
SoOutput * out = mwa->getOutput();
if (out->getStage() == SoOutput::COUNT_REFS) {
mwa->totalnrnodes++;
}
else { // (out->getStage() == SoOutput::WRITE)
mwa->nrnodes++;
SbString s;
s.sprintf(" # wrote node %p (%d/%d) \n", n, mwa->nrnodes, mwa->totalnrnodes);
out->write(s.getString());
}
}
int
main(int argc, char ** argv)
{
if (argc < 2) {
(void)fprintf(stderr, "\n\nUsage: %s <filename>\n\n", argv[0]);
exit(1);
}
SoDB::init();
MyWriteAction::initClass();
SoInput in;
if (!in.openFile(argv[1])) { exit(1); }
SoSeparator * root = SoDB::readAll(&in);
if (!root) { exit(1); }
root->ref();
SoOutput out;
MyWriteAction mwa(&out);
mwa.apply(root);
root->unref();
return 0;
}
SbString
The SbString class is a string class with convenience functions for string operations.
Definition SbString.h:52
SbString::sprintf
SbString & sprintf(const char *formatstr,...)
Definition SbString.h:118
SbString::getString
const char * getString(void) const
Definition SbString.h:84
SoAction
The SoAction class is the base class for all traversal actions.
Definition SoAction.h:77
SoAction::SoAction
SoAction(void)
Definition SoAction.cpp:337
SoBase::unref
void unref(void) const
Definition SoBase.cpp:530
SoBase::ref
void ref(void) const
Definition SoBase.cpp:478
SoDB::readAll
static SoSeparator * readAll(SoInput *input)
Definition SoDB.cpp:682
SoDB::init
static void init(void)
Definition SoDB.cpp:200
SoInput
The SoInput class is an abstraction of file import functionality.
Definition SoInput.h:61
SoInput::openFile
virtual SbBool openFile(const char *fileName, SbBool okIfNotFound=FALSE)
Definition SoInput.cpp:495
SoNode::writeS
static void writeS(SoAction *action, SoNode *node)
Definition SoNode.cpp:1266
SoOutput::getStage
Stage getStage(void) const
Definition SoOutput.cpp:757
SoOutput::write
virtual void write(const char c)
Definition SoOutput.cpp:770
SoOutput::COUNT_REFS
@ COUNT_REFS
Definition SoOutput.h:53
SoSeparator
The SoSeparator class is a state-preserving group node.
Definition SoSeparator.h:44
SoWriteAction::beginTraversal
virtual void beginTraversal(SoNode *node)
Definition SoWriteAction.cpp:232
SoWriteAction::initClass
static void initClass(void)
Definition SoWriteAction.cpp:132

## Member Enumeration Documentation

## ◆ AppliedCode

enum SoAction::AppliedCode

Enumerated values for what the action was applied to.

## ◆ PathCode

enum SoAction::PathCode

Enumerated values for how the action is applied to a scene graph.

## Constructor & Destructor Documentation

## ◆ ~SoAction()

SoAction::~SoAction | ( | void |  | ) |
| virtual

Destructor, free resources.

## ◆ SoAction()

SoAction::SoAction | ( | void |  | ) |
| protected

Default constructor, does all necessary top level initialization.

## Member Function Documentation

## ◆ initClass()

void SoAction::initClass | ( | void |  | ) |
| static

Initializes the runtime type system for this class, and sets up the enabled elements and action method list.

## ◆ initClasses()

void SoAction::initClasses | ( | void |  | ) |
| static

Initialize all the SoAction subclasses. Automatically called from SoAction::initClass().

## ◆ getClassTypeId()

SoType SoAction::getClassTypeId | ( | void |  | ) |
| static

Returns the runtime type object associated with instances of this class.

## ◆ getTypeId()

virtual SoType SoAction::getTypeId | ( | void |  | ) | const
| pure virtual

Returns the type identification of an action derived from a class inheriting SoAction. This is used for runtime type checking and "downward" casting.

Usage example:

void bar(SoAction * action)
{
if (action->getTypeId() == SoGLRenderAction::getClassTypeId()) {
// safe downward cast, know the type
SoGLRenderAction * glrender = (SoGLRenderAction *)action;
}
return; // ignore if not render action
}
SoAction::getTypeId
virtual SoType getTypeId(void) const =0
SoGLRenderAction
The SoGLRenderAction class renders the scene graph with OpenGL calls.
Definition SoGLRenderAction.h:50
SoGLRenderAction::getClassTypeId
static SoType getClassTypeId(void)
Definition SoGLRenderAction.cpp:631

For application programmers wanting to extend the library with new actions: this method needs to be overridden in all subclasses. This is typically done as part of setting up the full type system for extension classes, which is usually accomplished by using the predefined macros available through Inventor/nodes/SoSubAction.h: SO_ACTION_SOURCE, SO_ACTION_INIT_CLASS and SO_ACTION_CONSTRUCTOR.

For more information on writing Coin extensions, see the SoAction class documentation.

Returns the actual type id of an object derived from a class inheriting SoAction. Needs to be overridden in all subclasses.

Implemented in SoAudioRenderAction, SoBoxHighlightRenderAction, SoCallbackAction, SoGetBoundingBoxAction, SoGetMatrixAction, SoGetPrimitiveCountAction, SoGlobalSimplifyAction, SoGLRenderAction, SoHandleEventAction, SoIntersectionDetectionAction, SoLineHighlightRenderAction, SoPickAction, SoRayPickAction, SoReorganizeAction, SoSearchAction, SoShapeSimplifyAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, SoVectorizeAction, SoVectorizePSAction, and SoWriteAction.

## ◆ isOfType()

SbBool SoAction::isOfType | ( | SoType | type | ) | const
| virtual

Returns `TRUE` if the type of this object is either of the same type or a subclass of type.

## ◆ apply() [1/4]

void SoAction::apply | ( | SoNode * | root | ) |
| virtual

Applies the action to the scene graph rooted at root.

Note that you should not apply an action to a node with a zero reference count. The behavior in that case is undefined.

Reimplemented in SoBoxHighlightRenderAction, SoIntersectionDetectionAction, SoLineHighlightRenderAction, SoReorganizeAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, and SoVectorizeAction.

## ◆ apply() [2/4]

void SoAction::apply | ( | SoPath * | path | ) |
| virtual

Applies the action to the parts of the graph defined by path.

Note that an SoPath will also contain all nodes that may influence e.g. geometry nodes in the path. So for instance applying an SoGLRenderAction on an SoPath will render that path as expected in the view, where geometry will get its materials, textures, and other appearance settings correctly.

If the path ends in an SoGroup node, the action will also traverse the tail node's children.

Reimplemented in SoBoxHighlightRenderAction, SoIntersectionDetectionAction, SoLineHighlightRenderAction, SoReorganizeAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, and SoVectorizeAction.

## ◆ apply() [3/4]

void SoAction::apply | ( | const SoPathList & | pathlist,
|  | SbBool | obeysrules = FALSE )
| virtual

Applies action to the graphs defined by pathlist. If obeysrules is set to `TRUE`, pathlist must obey the following four conditions (which is the case for path lists returned from search actions for non-group nodes and path lists returned from picking actions):

All paths must start at the same head node. All paths must be sorted in traversal order. The paths must be unique. No path can continue through the end point of another path.

See also
  SoAction::apply(SoPath * path)

Reimplemented in SoBoxHighlightRenderAction, SoIntersectionDetectionAction, SoLineHighlightRenderAction, SoReorganizeAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, and SoVectorizeAction.

## ◆ apply() [4/4]

void SoAction::apply | ( | SoAction * | beingApplied | ) |

Applies this action object to the same as beingApplied is being applied to.

This function is an extension for Coin, and it is not available in the original SGI Open Inventor v2.1 API.

Since
  Coin 2.1

## ◆ invalidateState()

void SoAction::invalidateState | ( | void |  | ) |
| virtual

Invalidates the state, forcing it to be recreated at the next apply() invocation.

Reimplemented in SoGLRenderAction.

## ◆ nullAction()

void SoAction::nullAction | ( | SoAction * | action,
|  | SoNode * | node )
| static

This method is used for filling up the lookup tables with void methods.

## ◆ getWhatAppliedTo()

SoAction::AppliedCode SoAction::getWhatAppliedTo | ( | void |  | ) | const

Returns a code indicating what (node, path, or path list) the action instance is being applied to.

## ◆ getNodeAppliedTo()

SoNode * SoAction::getNodeAppliedTo | ( | void |  | ) | const

Returns a pointer to the node the action is being applied to.

If action is not being applied to a node (but a path or a path list), the method returns `NULL`.

## ◆ getPathAppliedTo()

SoPath * SoAction::getPathAppliedTo | ( | void |  | ) | const

Returns the pointer to the path the action is being applied to. The path is managed by the action instance and should not be destroyed or modified by the caller.

If action is not being applied to a path (but a node or a path list), the method returns `NULL`.

## ◆ getPathListAppliedTo()

const SoPathList * SoAction::getPathListAppliedTo | ( | void |  | ) | const

Returns the pointer to the path list the action is currently being applied to. The path list is managed by the action instance and should not be destroyed or modified by the caller.

If action is not being applied to a path list (but a node or a path), the method returns `NULL`.

The returned path list pointer need not be equal to the list apply() was called with, as the action may have reorganized the path list for efficiency reasons.

See also
  void SoAction::apply(const SoPathList &, SbBool)

## ◆ getOriginalPathListAppliedTo()

const SoPathList * SoAction::getOriginalPathListAppliedTo | ( | void |  | ) | const

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

If the action is not being applied to a path list (but a node or a path), the method returns `NULL`.

## ◆ isLastPathListAppliedTo()

SbBool SoAction::isLastPathListAppliedTo | ( | void |  | ) | const

This method is not supported in Coin. It should probably have been private in OIV.

## ◆ getPathCode()

SoAction::PathCode SoAction::getPathCode | ( | int & | numindices,
|  | const int *& | indices )

Returns a code that indicates where the current node lies with respect to the path(s) the action is being applied to. The arguments indices and numindices are only set if the method returns `IN_PATH`.

## ◆ traverse()

void SoAction::traverse | ( | SoNode *const | node | ) |

Traverses a scene graph rooted at node, invoking the action methods of the nodes in the graph.

## ◆ hasTerminated()

SbBool SoAction::hasTerminated | ( | void |  | ) | const

Returns `TRUE` if the action was prematurely terminated.

Note that the termination flag will be `FALSE` if the action simply completed its run over the scene graph in the "ordinary" fashion, i.e. was not explicitly aborted from any of the nodes in the graph.

See also
  setTerminated()

## ◆ getCurPath()

const SoPath * SoAction::getCurPath | ( | void |  | ) |

Returns a pointer to the path generated during traversal, from the root of the traversed graph to the current node.

## ◆ getState()

SoState * SoAction::getState | ( | void |  | ) | const

Returns a pointer to the state of the action instance. The state contains the current set of elements used during traversal.

## ◆ getCurPathCode()

SoAction::PathCode SoAction::getCurPathCode | ( | void |  | ) | const
| inline

Returns the current traversal path code.

## ◆ getCurPathTail()

SoNode * SoAction::getCurPathTail | ( | void |  | ) |
| virtual

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.

Reimplemented in SoCallbackAction.

## ◆ usePathCode()

void SoAction::usePathCode | ( | int & | numindices,
|  | const int *& | indices )

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.

## ◆ pushCurPath() [1/2]

void SoAction::pushCurPath | ( | const int | childindex,
|  | SoNode * | node = NULL )

Get ready to traverse the childindex'th child. Use this method if the path code might change as a result of this.

This method is very internal. Do not use unless you know what you're doing.

## ◆ popCurPath() [1/2]

void SoAction::popCurPath | ( | const PathCode | prevpathcode | ) |

Pops the current path, and sets the path code to prevpathcode.

This method is very internal. Do not use unless you know what you're doing.

## ◆ pushCurPath() [2/2]

void SoAction::pushCurPath | ( | void |  | ) |

Pushes a NULL node onto the current path. Use this before traversing all children when you know that the path code will not change while traversing children.

This method is very internal. Do not use unless you know what you're doing.

## ◆ popPushCurPath()

void SoAction::popPushCurPath | ( | const int | childindex,
|  | SoNode * | node = NULL )

Get ready to traverse the childindex'th child. Use this method if you know the path code will not change as a result of this.

This method is very internal. Do not use unless you know what you're doing.

## ◆ popCurPath() [2/2]

void SoAction::popCurPath | ( | void |  | ) |

Pops of the last child in the current path. Use this if you know the path code hasn't changed since the current path was pushed.

This method is very internal. Do not use unless you know what you're doing.

## ◆ switchToPathTraversal()

void SoAction::switchToPathTraversal | ( | SoPath * | path | ) |

Store our state, traverse the given path, restore our state and continue traversal.

## ◆ switchToNodeTraversal()

void SoAction::switchToNodeTraversal | ( | SoNode * | node | ) |

Store our state, traverse the subgraph rooted at the given node, restore our state and continue traversal.

## ◆ beginTraversal()

void SoAction::beginTraversal | ( | SoNode * | node | ) |
| protectedvirtual

This virtual method is called from SoAction::apply(), and is the entry point for the actual scene graph traversal.

It can be overridden to initialize the action at traversal start, for specific initializations in the action subclasses inheriting SoAction.

Default method just calls traverse(), which any overridden implementation of the method must do too (or call SoAction::beginTraversal()) to trigger the scene graph traversal.

Reimplemented in SoAudioRenderAction, SoCallbackAction, SoGetBoundingBoxAction, SoGetMatrixAction, SoGetPrimitiveCountAction, SoGlobalSimplifyAction, SoGLRenderAction, SoHandleEventAction, SoPickAction, SoRayPickAction, SoReorganizeAction, SoSearchAction, SoShapeSimplifyAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, and SoWriteAction.

## ◆ endTraversal()

void SoAction::endTraversal | ( | SoNode * | node | ) |
| protectedvirtual

This virtual method can be overridden to execute code after the scene graph traversal. Default method does nothing.

Reimplemented in SoGLRenderAction.

## ◆ setTerminated()

void SoAction::setTerminated | ( | const SbBool | flag | ) |
| protected

Set the termination flag.

Typically set to TRUE from nodes upon special conditions being met during scene graph traversal – like the correct node being found when doing SoSearchAction traversal or when grabbing the event from an SoHandleEventAction.

See also
  hasTerminated()

## ◆ getEnabledElements()

const SoEnabledElementsList & SoAction::getEnabledElements | ( | void |  | ) | const
| protectedvirtual

Returns a list of the elements used by action instances of this class upon traversal operations.

Reimplemented in SoAudioRenderAction, SoBoxHighlightRenderAction, SoCallbackAction, SoGetBoundingBoxAction, SoGetMatrixAction, SoGetPrimitiveCountAction, SoGlobalSimplifyAction, SoGLRenderAction, SoHandleEventAction, SoIntersectionDetectionAction, SoLineHighlightRenderAction, SoPickAction, SoRayPickAction, SoReorganizeAction, SoSearchAction, SoShapeSimplifyAction, SoSimplifyAction, SoToVRML2Action, SoToVRMLAction, SoVectorizeAction, SoVectorizePSAction, and SoWriteAction.

## ◆ shouldCompactPathList()

SbBool SoAction::shouldCompactPathList | ( | void |  | ) | const
| protectedvirtual

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.

## ◆ getClassEnabledElements()

SoEnabledElementsList * SoAction::getClassEnabledElements | ( | void |  | ) |
| staticprotected

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
This method not available in the original OIV API, see SoSubAction.h for explanation.

## ◆ getClassActionMethods()

SoActionMethodList * SoAction::getClassActionMethods | ( | void |  | ) |
| staticprotected

This API member is considered internal to the library, as it is not likely to be of interest to the application programmer.
This method not available in the original OIV API, see SoSubAction.h for explanation.

## Member Data Documentation

## ◆ state

SoState* SoAction::state
| protected

Pointer to the traversal state instance of the action.

## ◆ traversalMethods

SoActionMethodList* SoAction::traversalMethods
| protected

Stores the list of "nodetype to actionmethod" mappings for the particular action instance.

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

- SoAction.h
- SoAction.cpp