Provided by: libcoin80-doc_3.1.4~abc9f50-4ubuntu2_all bug

NAME

       SoCallbackAction -

       The SoCallbackAction class invokes callbacks at specific nodes.

       This action has mechanisms for tracking traversal position and traversal state. In
       combination with the ability to pass geometry primitives to callback actions set by the
       user, this does for instance make it rather straightforward to extract the geometry of a
       scene graph.

SYNOPSIS

       #include <Inventor/actions/SoCallbackAction.h>

       Inherits SoAction.

   Public Types
       enum Response { CONTINUE, ABORT, PRUNE }
       typedef Response SoCallbackActionCB (void *userdata, SoCallbackAction *action, const
           SoNode *node)

   Public Member Functions
       virtual SoType getTypeId (void) const
       SoCallbackAction (void)
       SoCallbackAction (const SbViewportRegion &vp)
       virtual ~SoCallbackAction (void)
       void setViewportRegion (const SbViewportRegion &vp)
       void addPreCallback (const SoType type, SoCallbackActionCB *cb, void *userdata)
       void addPostCallback (const SoType type, SoCallbackActionCB *cb, void *userdata)
       void addPreTailCallback (SoCallbackActionCB *cb, void *userdata)
       void addPostTailCallback (SoCallbackActionCB *cb, void *userdata)
       void addTriangleCallback (const SoType type, SoTriangleCB *cb, void *userdata)
       void addLineSegmentCallback (const SoType type, SoLineSegmentCB *cb, void *userdata)
       void addPointCallback (const SoType type, SoPointCB *cb, void *userdata)
       SoDecimationTypeElement::Type getDecimationType (void) const
       float getDecimationPercentage (void) const
       float getComplexity (void) const
       SoComplexity::Type getComplexityType (void) const
       int32_t getNumCoordinates (void) const
       const SbVec3f & getCoordinate3 (const int index) const
       const SbVec4f & getCoordinate4 (const int index) const
       SoDrawStyle::Style getDrawStyle (void) const
       unsigned short getLinePattern (void) const
       float getLineWidth (void) const
       float getPointSize (void) const
       const SbName & getFontName (void) const
       float getFontSize (void) const
       SoLightModel::Model getLightModel (void) const
       const SbVec3f & getLightAttenuation (void) const
       void getMaterial (SbColor &ambient, SbColor &diffuse, SbColor &specular, SbColor
           &emission, float &shininess, float &transparency, const int index=0) const
       SoMaterialBinding::Binding getMaterialBinding (void) const
       uint32_t getNumNormals (void) const
       const SbVec3f & getNormal (const int index) const
       SoNormalBinding::Binding getNormalBinding (void) const
       int32_t getNumProfileCoordinates (void) const
       const SbVec2f & getProfileCoordinate2 (const int index) const
       const SbVec3f & getProfileCoordinate3 (const int index) const
       const SoNodeList & getProfile (void) const
       SoShapeHints::VertexOrdering getVertexOrdering (void) const
       SoShapeHints::ShapeType getShapeType (void) const
       SoShapeHints::FaceType getFaceType (void) const
       float getCreaseAngle (void) const
       int32_t getNumTextureCoordinates (void) const
       const SbVec2f & getTextureCoordinate2 (const int index) const
       const SbVec3f & getTextureCoordinate3 (const int index) const
       const SbVec4f & getTextureCoordinate4 (const int index) const
       SoTextureCoordinateBinding::Binding getTextureCoordinateBinding (void) const
       const SbColor & getTextureBlendColor (void) const
       const unsigned char * getTextureImage (SbVec2s &size, int &numcomps) const
       const unsigned char * getTextureImage (SbVec3s &size, int &numcomps) const
       const SbMatrix & getTextureMatrix (void) const
       SoTexture2::Model getTextureModel (void) const
       SoTexture2::Wrap getTextureWrapS (void) const
       SoTexture2::Wrap getTextureWrapT (void) const
       SoTexture2::Wrap getTextureWrapR (void) const
       const SbMatrix & getModelMatrix (void) const
       SoUnits::Units getUnits (void) const
       float getFocalDistance (void) const
       const SbMatrix & getProjectionMatrix (void) const
       const SbMatrix & getViewingMatrix (void) const
       const SbViewVolume & getViewVolume (void) const
       const SbViewportRegion & getViewportRegion (void) const
       SoPickStyle::Style getPickStyle (void) const
       int32_t getSwitch (void) const
       Response getCurrentResponse (void) const
       void invokePreCallbacks (const SoNode *const node)
       void invokePostCallbacks (const SoNode *const node)
       void invokeTriangleCallbacks (const SoShape *const shape, const SoPrimitiveVertex *const
           v1, const SoPrimitiveVertex *const v2, const SoPrimitiveVertex *const v3)
       void invokeLineSegmentCallbacks (const SoShape *const shape, const SoPrimitiveVertex
           *const v1, const SoPrimitiveVertex *const v2)
       void invokePointCallbacks (const SoShape *const shape, const SoPrimitiveVertex *const v)
       SbBool shouldGeneratePrimitives (const SoShape *shape) const
       virtual SoNode * getCurPathTail (void)
       void setCurrentNode (SoNode *const node)
       void setCallbackAll (SbBool callbackall)
       SbBool isCallbackAll (void) const

   Static Public Member Functions
       static SoType getClassTypeId (void)
       static void addMethod (const SoType type, SoActionMethod method)
       static void enableElement (const SoType type, const int stackindex)
       static void initClass (void)

   Protected Member Functions
       virtual const
           SoEnabledElementsList & getEnabledElements (void) const "
       virtual void beginTraversal (SoNode *node)

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

   Additional Inherited Members

Detailed Description

       The SoCallbackAction class invokes callbacks at specific nodes.

       This action has mechanisms for tracking traversal position and traversal state. In
       combination with the ability to pass geometry primitives to callback actions set by the
       user, this does for instance make it rather straightforward to extract the geometry of a
       scene graph.

       You should be able to use this action for most of your 'simple' traversal needs, instead
       of cooking up your own code, as the SoCallbackAction is rather flexible.

       A common use of this action is to extract geometry of non-primitive shapes as triangles. A
       full-fledged example that demonstrates this on a scenegraph with two spheres follows:

       #include <Inventor/SoDB.h>
       #include <Inventor/SoPrimitiveVertex.h>
       #include <Inventor/actions/SoCallbackAction.h>
       #include <Inventor/nodes/SoCoordinate3.h>
       #include <Inventor/nodes/SoIndexedFaceSet.h>
       #include <Inventor/nodes/SoSeparator.h>
       #include <Inventor/nodes/SoShape.h>
       #include <Inventor/nodes/SoSphere.h>
       #include <Inventor/nodes/SoTranslation.h>

       static SoCoordinate3 * coord3 = NULL;
       static SoIndexedFaceSet * ifs = NULL;

       static int coord3idx = 0;

       static void
       triangle_cb(void * userdata, SoCallbackAction * action,
                   const SoPrimitiveVertex * v1,
                   const SoPrimitiveVertex * v2,
                   const SoPrimitiveVertex * v3)
       {
         const SbVec3f vtx[] = { v1->getPoint(), v2->getPoint(), v3->getPoint() };
         const SbMatrix mm = action->getModelMatrix();

         SbVec3f vx[3];
         for (int j=0; j < 3; j++) { mm.multVecMatrix(vtx[j], vx[j]); }

         // (This is sub-optimal -- should scan for the same vertex
         // coordinates already being present in the SoCoordinate3
         // node. We'll get lots of duplicate coordinates from this.)
         coord3->point.setNum(coord3->point.getNum() + 3);
         coord3->point.setValues(coord3idx, 3, vx);

         int32_t indices[] = { coord3idx, coord3idx + 1, coord3idx + 2, -1 };
         coord3idx += 3;

         int oldsize = ifs->coordIndex.getNum();
         ifs->coordIndex.setNum(oldsize + 4);
         ifs->coordIndex.setValues(oldsize, 4, indices);

         // (Note that it would likely be desirable to grab normal vectors,
         // materials and / or texture coordinates in a real-world
         // application. How to do this is not shown by the above code,
         // but it is not much different from the extraction of vertex
         // coordinates.)
       }

       int
       main(void)
       {
         SoDB::init();

         SoSeparator * root = new SoSeparator;
         root->addChild(new SoSphere);
         SoTranslation * trans = new SoTranslation;
         trans->translation.setValue(10, 0, 0);
         root->addChild(trans);
         SoSphere * ss = new SoSphere;
         ss->radius = 3;
         root->addChild(ss);

         root->ref();

         coord3 = new SoCoordinate3;
         coord3->point.setNum(0);
         ifs = new SoIndexedFaceSet;
         ifs->coordIndex.setNum(0);

         SoCallbackAction ca;
         ca.addTriangleCallback(SoShape::getClassTypeId(), triangle_cb, NULL);
         ca.apply(root);

         root->unref();

         // [the generated SoCoordinate3 and SoIndexedFaceSet nodes would now
         // typically be used in a scenegraph in a viewer, or written to disk
         // or something]

         return 0;
       }

Member Typedef Documentation

   Response SoCallbackAction::SoCallbackActionCB
       Callback functions need to be of this type. node is at the current traversal point in the
       scene graph.

Member Enumeration Documentation

   enum SoCallbackAction::Response
       Response values for callback function.

       Enumerator

       CONTINUE
              Continue traversal as usual.

       ABORT  Abort traversal immediately. No other callbacks are called after this has been
              returned.

       PRUNE  Don't do traversal of neither the current node (if returning from a pre-traversal
              callback) nor its children.

       If returned from a pre-callback, the post-callbacks will still be called. If returned from
       a post-callback, the behaviour will be the same as for returning CONTINUE.

Constructor & Destructor Documentation

   SoCallbackAction::SoCallbackAction (void)
       Default constructor. Will set the viewport to a standard viewport with size 640x512.

   SoCallbackAction::SoCallbackAction (const SbViewportRegion &vp)
       Constructor which lets you specify the viewport.

       This constructor is an extension versus the Open Inventor API.

   SoCallbackAction::~SoCallbackAction (void) [virtual]
       Destructor.

Member Function Documentation

   SoType SoCallbackAction::getTypeId (void) const [virtual]
       Returns the type identification of an action derived from a class inheriting SoAction.
       This is used for run-time 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 renderaction
       }

       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 pre-
       defined 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.

       Implements SoAction.

   void SoCallbackAction::addMethod (const SoTypetype, SoActionMethodmethod) [static]
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

   void SoCallbackAction::enableElement (const SoTypetype, const intstackindex) [static]
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

   const SoEnabledElementsList & SoCallbackAction::getEnabledElements (void) const [protected],
       [virtual]
       Returns a list of the elements used by action instances of this class upon traversal
       operations.

       Reimplemented from SoAction.

   void SoCallbackAction::setViewportRegion (const SbViewportRegion &vp)
       Sets the viewport region for this action. When set, the viewport element is initialized
       right before a traversal starts, making it the current viewport.

       This method is an extension versus the Open Inventor API.

   void SoCallbackAction::addPreCallback (const SoTypetype, SoCallbackActionCB *cb, void
       *userdata)
       Set a function cb to call before every node of type is traversed. cb will be called with
       userdata.

   void SoCallbackAction::addPostCallback (const SoTypetype, SoCallbackActionCB *cb, void
       *userdata)
       Set a function cb to call after every node of type has been traversed. cb will be called
       with userdata.

   void SoCallbackAction::addPreTailCallback (SoCallbackActionCB *cb, void *userdata)
       Set a function cb to call before the tail of a path is traversed. cb will be called with
       userdata.

   void SoCallbackAction::addPostTailCallback (SoCallbackActionCB *cb, void *userdata)
       Set a function cb to call after the tail of a path has been traversed. cb will be called
       with userdata.

   void SoCallbackAction::addTriangleCallback (const SoTypetype, SoTriangleCB *cb, void
       *userdata)
       Set a function cb to call when traversing a node of type which generates triangle
       primitives for rendering. cb will be called with userdata.

   void SoCallbackAction::addLineSegmentCallback (const SoTypetype, SoLineSegmentCB *cb, void
       *userdata)
       Set a function cb to call when traversing a node of type which generates line primitives
       for rendering. cb will be called with userdata.

   void SoCallbackAction::addPointCallback (const SoTypetype, SoPointCB *cb, void *userdata)
       Set a function cb to call when traversing a node of type which generates single point
       primitives for rendering. cb will be called with userdata.

   SoDecimationTypeElement::Type SoCallbackAction::getDecimationType (void) const
       Returns current decimation type setting.

   float SoCallbackAction::getDecimationPercentage (void) const
       Returns current decimation percentage setting.

   float SoCallbackAction::getComplexity (void) const
       Returns current complexity setting.

   SoComplexity::Type SoCallbackAction::getComplexityType (void) const
       Returns current complexity type setting.

   int32_t SoCallbackAction::getNumCoordinates (void) const
       Returns current number of coordinates in the state.

   const SbVec3f & SoCallbackAction::getCoordinate3 (const intindex) const
       Returns a coordinate triplet from the current state pool of coordinates.

   const SbVec4f & SoCallbackAction::getCoordinate4 (const intindex) const
       Returns a coordinate quartuplet from the current state pool of coordinates.

   SoDrawStyle::Style SoCallbackAction::getDrawStyle (void) const
       Returns current draw style setting.

   unsigned short SoCallbackAction::getLinePattern (void) const
       Returns current line pattern setting.

   float SoCallbackAction::getLineWidth (void) const
       Returns current line width setting.

   float SoCallbackAction::getPointSize (void) const
       Returns current point size setting.

   const SbName & SoCallbackAction::getFontName (void) const
       Returns current fontname setting.

   float SoCallbackAction::getFontSize (void) const
       Returns current fontsize setting.

   SoLightModel::Model SoCallbackAction::getLightModel (void) const
       Returns current lightmodel setting.

   const SbVec3f & SoCallbackAction::getLightAttenuation (void) const
       Returns current light attenuation setting.

   void SoCallbackAction::getMaterial (SbColor &ambient, SbColor &diffuse, SbColor &specular,
       SbColor &emission, float &shininess, float &transparency, const intindex = 0) const
       Returns current material settings.

   SoMaterialBinding::Binding SoCallbackAction::getMaterialBinding (void) const
       Returns current materialbinding setting.

   uint32_t SoCallbackAction::getNumNormals (void) const
       Returns current number of normals in the state.

   const SbVec3f & SoCallbackAction::getNormal (const intindex) const
       Returns the normal vectors at index from the current state.

   SoNormalBinding::Binding SoCallbackAction::getNormalBinding (void) const
       Returns current normalbinding setting.

   int32_t SoCallbackAction::getNumProfileCoordinates (void) const
       Returns current number of profile coordinates in the state.

   const SbVec2f & SoCallbackAction::getProfileCoordinate2 (const intindex) const
       Returns current number of SbVec2f profile coordinates in the state.

   const SbVec3f & SoCallbackAction::getProfileCoordinate3 (const intindex) const
       Returns current number of SbVec3f profile coordinates in the state.

   const SoNodeList & SoCallbackAction::getProfile (void) const
       Returns current list of profile nodes.

   SoShapeHints::VertexOrdering SoCallbackAction::getVertexOrdering (void) const
       Returns current vertexordering shapehint setting.

       Please note that this is the vertex ordering set by the SoShapeHints node. If you want to
       find the vertex ordering for VRML nodes you'll need to read this directly from the ccw
       field in those nodes.

   SoShapeHints::ShapeType SoCallbackAction::getShapeType (void) const
       Returns current shapetype hint setting.

       Please note that this is the shape type set by the SoShapeHints node. If you want to find
       the shape type for VRML nodes you'll need to read this directly from the solid field in
       those nodes.

   SoShapeHints::FaceType SoCallbackAction::getFaceType (void) const
       Returns current facetype hint setting.

       Please note that this is the face type set by the SoShapeHints node. If you want to find
       the face type for VRML nodes you'll need to read this directly from the convex field in
       those nodes.

   float SoCallbackAction::getCreaseAngle (void) const
       Returns current creaseangle setting. Please note that this is the crease angle value set
       by the SoShapeHints node. If you want to find the crease angle for VRML nodes you'll need
       to read this directly from the creaseAngle field in those nodes.

   int32_t SoCallbackAction::getNumTextureCoordinates (void) const
       Returns current number of texture coordinates in the traversal state.

   const SbVec2f & SoCallbackAction::getTextureCoordinate2 (const intindex) const
       Returns SbVec2f texture coordinate at index from the texture coordinate pool of the
       traversal state.

   const SbVec3f & SoCallbackAction::getTextureCoordinate3 (const intindex) const
       Returns SbVec3f texture coordinate at index from the texture coordinate pool of the
       traversal state.

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

       Since:
           Coin 2.0

   const SbVec4f & SoCallbackAction::getTextureCoordinate4 (const intindex) const
       Returns SbVec4f texture coordinate at index from the texture coordinate pool of the
       traversal state.

   SoTextureCoordinateBinding::Binding SoCallbackAction::getTextureCoordinateBinding (void) const
       Returns current texturecoordinate binding setting.

   const SbColor & SoCallbackAction::getTextureBlendColor (void) const
       Returns current texture blend color setting.

   const unsigned char * SoCallbackAction::getTextureImage (SbVec2s &size, int &numcomps) const
       Returns current texture image settings.

   const unsigned char * SoCallbackAction::getTextureImage (SbVec3s &size, int &numcomps) const
       Returns current 3D texture image settings.

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

       Since:
           Coin 2.0

   const SbMatrix & SoCallbackAction::getTextureMatrix (void) const
       Returns current texture transformation matrix setting.

   SoTexture2::Model SoCallbackAction::getTextureModel (void) const
       Returns current texturemapping model setting.

   SoTexture2::Wrap SoCallbackAction::getTextureWrapS (void) const
       Returns current texture wrapping setting for the S coordinate.

   SoTexture2::Wrap SoCallbackAction::getTextureWrapT (void) const
       Returns current texture wrapping setting for the T coordinate.

   SoTexture2::Wrap SoCallbackAction::getTextureWrapR (void) const
       Returns current texture wrapping setting for the R coordinate.

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

       Since:
           Coin 2.0

   const SbMatrix & SoCallbackAction::getModelMatrix (void) const
       Returns current model matrix.

   SoUnits::Units SoCallbackAction::getUnits (void) const
       Returns current units setting.

   float SoCallbackAction::getFocalDistance (void) const
       Returns current camera focal distance setting.

   const SbMatrix & SoCallbackAction::getProjectionMatrix (void) const
       Returns current projection matrix.

   const SbMatrix & SoCallbackAction::getViewingMatrix (void) const
       Returns current viewing matrix.

   const SbViewVolume & SoCallbackAction::getViewVolume (void) const
       Returns current view volume setting.

   const SbViewportRegion & SoCallbackAction::getViewportRegion (void) const
       Returns current viewport region setting.

       This method is an extension versus the Open Inventor API.

   SoPickStyle::Style SoCallbackAction::getPickStyle (void) const
       Returns current pickstyle setting.

   int32_t SoCallbackAction::getSwitch (void) const
       Returns last SoSwitch::whichChild setting during the traversal.

   SoCallbackAction::Response SoCallbackAction::getCurrentResponse (void) const
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

   void SoCallbackAction::invokePreCallbacks (const SoNode *constnode)
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Invoke all 'pre traversal' callbacks.

   void SoCallbackAction::invokePostCallbacks (const SoNode *constnode)
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Invoke all 'post traversal' callbacks.

   void SoCallbackAction::invokeTriangleCallbacks (const SoShape *constshape, const
       SoPrimitiveVertex *constv1, const SoPrimitiveVertex *constv2, const SoPrimitiveVertex
       *constv3)
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Invoke all 'triangle generation' callbacks.

   void SoCallbackAction::invokeLineSegmentCallbacks (const SoShape *constshape, const
       SoPrimitiveVertex *constv1, const SoPrimitiveVertex *constv2)
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Invoke all 'line segment generation' callbacks.

   void SoCallbackAction::invokePointCallbacks (const SoShape *constshape, const
       SoPrimitiveVertex *constv)
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Invoke all 'point' callbacks.

   SbBool SoCallbackAction::shouldGeneratePrimitives (const SoShape *shape) const
       This API member is considered internal to the library, as it is not likely to be of
       interest to the application programmer.

       Check from the shape nodes whether or not to generate primitives from the complex shapes.
       If there are no callbacks attached to the node types, making the primitives would only be
       a waste of CPU.

   SoNode * SoCallbackAction::getCurPathTail (void) [virtual]
       Returns the current tail of the traversal path for the callback action.

       Reimplemented from SoAction.

   void SoCallbackAction::setCurrentNode (SoNode *constnode)
       Used from nodes during traversal to keep a current node pointer in the action.

   void SoCallbackAction::beginTraversal (SoNode *node) [protected],  [virtual]
       This virtual method is called from SoAction::apply(), and is the entry point for the
       actual scenegraph 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 scenegraph traversal.

       Reimplemented from SoAction.

Author

       Generated automatically by Doxygen for Coin from the source code.