Ubuntu Manpage: SoSurroundScale — transformation node that adjusts the current matrix so a default cube will surround

Provided by: inventor-doc_2.1.6+ds-2_all

NAME

       SoSurroundScale  —  transformation  node  that adjusts the current matrix so a default cube will surround
       other objects

INHERITS FROM

       SoBase > SoFieldContainer > SoNode > SoTransformation > SoSurroundScale

SYNOPSIS

       #include <Inventor/nodes/SoSurroundScale.h>

          Fields from class SoSurroundScale:

     SoSFInt32           numNodesUpToContainer
     SoSFInt32           numNodesUpToReset

          Methods from class SoSurroundScale:

                         SoSurroundScale()
     void                invalidate()
     static SoType       getClassTypeId()

          Methods from class SoNode:

     void                setOverride(SbBool state)
     SbBool              isOverride() const
     SoNode *            copy(SbBool copyConnections = FALSE) const
     virtual SbBool      affectsState() const
     static SoNode *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoNodeList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const SoFieldContainer *fc, SbBool copyConnections = FALSE)
     SbBool              set(const char *fieldDataString)
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const
     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName) const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const

DESCRIPTION

When traversed by an action, this node appends a transformation to the current transformation matrix so
that a default size cube will surround the objects specified by its fields. Transform manipulators, such
as SoHandleBoxManip, use these nodes to make themselves surround other objects.

This node only recalculates after the invalidate() method has been called. Otherwise it uses a saved
scale and translation.

When calculating what to surround, the SoSurroundScale looks at the current path in the action and at its
own field values. Then SoSurroundScale applies an SoGetBoundingBoxAction to the node that is
numNodesUpToContainer nodes above it on the path. SoSurroundScale also tells the action to reset the
bounding box upon traversal of the node located numNodesUpToReset nodes above it in the path. The
SoSurroundScale then appends a translation and scale to the current transformation so that a default size
SoCube will translate and scale to fit this bounding box.

For example, when an SoHandleBoxManip wants to surround the objects it is going to move, the scene graph
will look something like this:
RootNode
-------------------------
| |
handleBoxManip movingStuff
|
handleBoxDragger
|
separator
-----------------------------------
| | |
motionMatrix surroundScale cubeGeom
The SoHandleBoxDragger wants to transform the cubeGeom so that it surrounds the movingStuff. So it sets the
surroundScale fields to:

numNodesUpToContainer = 4;
numNodesUpToReset = 3;

The SoBoundingBoxAction will then be applied to RootNode, with a reset after traversing the
SoHandleBoxManip. So the SoSurroundScale will surround the objects below separator, and to the right of
handleBoxManip, producing the desired effect.

FIELDS

     SoSFInt32           numNodesUpToContainer
          When traversed by an action, if surroundScale needs to calculate a new box, surroundScale looks at the
          current path in the action. It travels up this path a distance of numNodesUpToContainer and applies an
          SoGetBoundingBoxAction to the node that it finds there.

     SoSFInt32           numNodesUpToReset
          Before   applying   the   SoGetBoundingBoxAction   (see  the  numNodesUpToContainer  field  aove)  the
          surroundScale node travels up the path a distance of numNodesUpToReset and tells the action  to  reset
          the bounding box upon traversal of that node.

METHODS

                         SoSurroundScale()
          Creates a surround scale node with default settings.

     void                invalidate()
          If  you  call  this,  then  next  time  an  action  is  applied the node will re-calculate it's cached
          translation and scale values.

     static SoType       getClassTypeId()
          Returns type identifier for this class.

ACTION BEHAVIOR

       SoGLRenderAction, SoCallbackAction, SoGetBoundingBoxAction, SoRayPickAction
          Accumulates scaling and translation transformations into the current transformation.

     SoGetMatrixAction
          Returns the matrix corresponding to the scaling and translation.

FILE FORMAT/DEFAULTS

       SurroundScale {
          numNodesUpToContainer  0
          numNodesUpToReset      0
     }