SoSurroundScale(3IV)

NAME
     SoSurroundScale (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_c/nodes/SoSurroundScale.h>

          Fields from class SoSurroundScale:

     SoSFInt32           numNodesUpToContainer
     SoSFInt32           numNodesUpToReset

          Functions from class SoSurroundScale:

     SoSurroundScale *   SoSurroundScaleCreate()
     void                SoSurroundScaleInvalidate(SoSurroundScale *this)
     SoType              SoSurroundScaleGetClassTypeId()

          Functions from class SoNode:

     void                SoSurroundScaleSetOverride(SoSurroundScale *this,
                              SbBool state)
     SbBool              SoSurroundScaleIsOverride(const SoSurroundScale
                              *this)
     SoNode *            SoSurroundScaleCopy(const SoSurroundScale *this,
                              SbBool copyConnections = FALSE)
     SbBool              SoSurroundScaleAffectsState(const SoSurroundScale
                              *this)
     SoNode *            SoSurroundScaleGetByName(const char *name)
     int                 SoSurroundScaleGetByNameList(const char *name,
                              SoNodeList *list)

          Functions from class SoFieldContainer:

     void                SoSurroundScaleSetToDflts(SoSurroundScale *this)
     SbBool              SoSurroundScaleHasDfltVals(const SoSurroundScale
                              *this)
     SbBool              SoSurroundScaleFldsAreEq(const SoSurroundScale *this,
                              const SoFieldContainer *fc)
     void                SoSurroundScaleCopyFieldVals(SoSurroundScale *this,
                              const SoFieldContainer *fc, SbBool
                              copyConnections = FALSE)
     SbBool              SoSurroundScaleSet(SoSurroundScale *this, const char
                              *fieldDataString)
     void                SoSurroundScaleGet(SoSurroundScale *this, SbString
                              *fieldDataString)
     int                 SoSurroundScaleGetFields(const SoSurroundScale *this,
                              SoFieldList *resultList)

     SoField *           SoSurroundScaleGetField(const SoSurroundScale *this,
                              const char *fieldName)
     SbBool              SoSurroundScaleGetFieldName(const SoSurroundScale
                              *this, const SoField *field, SbName *fieldName)
     SbBool              SoSurroundScaleIsNotifyEnabled(const SoSurroundScale
                              *this)
     SbBool              SoSurroundScaleEnableNotify(SoSurroundScale *this,
                              SbBool flag)

          Functions from class SoBase:

     void                SoSurroundScaleRef(SoSurroundScale *this)
     void                SoSurroundScaleUnref(const SoSurroundScale *this)
     void                SoSurroundScaleUnrefNoDelete(const SoSurroundScale
                              *this)
     void                SoSurroundScaleTouch(SoSurroundScale *this)
     SoType              SoSurroundScaleGetTypeId(const SoSurroundScale *this)
     SbBool              SoSurroundScaleIsOfType(const SoSurroundScale *this,
                              SoType type)
     void                SoSurroundScaleSetName(SoSurroundScale *this, const
                              char *name)
     SbName              SoSurroundScaleGetName(const SoSurroundScale *this)


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 SoSurroundScaleInvalidate() 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.


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

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

     SoType              SoSurroundScaleGetClassTypeId()
          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
     }

SEE ALSO
     SoTransformation, SoTransformManip, SoCenterballDragger,
     SoCenterballManip, SoHandleBoxDragger, SoHandleBoxManip, SoJackDragger,
     SoJackManip, SoTabBoxDragger, SoTabBoxManip, SoTrackballDragger,
     SoTrackballManip, SoTransformBoxDragger, SoTransformBoxManip