SoSurroundScale(3IV)

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
}

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