SOSURROUNDSCALE(3iv)

💖 SoSurroundScale — the manual page, but make it cute 💖

okay bestie, gather round, because today we're talking about SoSurroundScale, a member of the <rainbow>SoSurroundScale(3IV)</rainbow> family of manual pages. It's a transformation node that adjusts the current matrix so a default cube will surround other objects. yes literally. it's the node that makes things ✨fit✨. 🎀

---

🌸 INHERITS FROM 🌸

SoBase > SoFieldContainer > SoNode > SoTransformation > SoSurroundScale

the whole ancestry, no skips. it's giving noble bloodline. 👑

---

✨ 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 💅

so. when this node gets traversed by an action, it appends a transformation to the current transformation matrix so that a default size cube will surround the objects specified by its fields. that's the whole vibe. 🧊

transform manipulators — like SoHandleBoxManip — use these nodes to make themselves surround other objects. yes, they're using surroundScale as their little helper. besties supporting besties. 🫶

⚠️ important: this node only recalculates after the invalidate() method has been called. otherwise it just uses a saved scale and translation. no recalc, no drama. it's coasting on old data. 😭

when it's calculating what to surround, 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. it also tells the action to reset the bounding box upon traversal of the node located numNodesUpToReset nodes above it in the path. then SoSurroundScale appends a translation and scale to the current transformation so that a default size SoCube will translate and scale to fit this bounding box. slay. 💖

for example, when an SoHandleBoxManip wants to surround the objects it's 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. we love a plan that comes together. 🌈

---

🎀 FIELDS 🎀

• SoSFInt32 numNodesUpToContainer — when it gets traversed by an action, if surroundScale needs to calculate a new box, it 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. it's going up the tree to find its target, basically. 🦋
• SoSFInt32 numNodesUpToReset — before applying the SoGetBoundingBoxAction (see the numNodesUpToContainer field above 👀) 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. that's the reset point, bestie. 🎯

---

⭐ METHODS ⭐

• SoSurroundScale() — creates a surround scale node with default settings. brand new, fresh out the box, defaults everywhere. ✨
• void invalidate() — if you call this, then next time an action is applied the node will re-calculate its cached translation and scale values. it's the "okay bestie, recalculate" button. 🫶
• static SoType getClassTypeId() — returns the type identifier for this class. iykyk. 💅

---

🔥 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. the receipts, basically. 🧾

---

🌈 FILE FORMAT/DEFAULTS 🌈

SurroundScale {
   numNodesUpToContainer  0
   numNodesUpToReset      0
}

zero and zero. starting from nothing, building a whole cube-sized vibe. we love an origin story. 💀✨

---

💜 SEE ALSO 💜

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

the whole friend group, honestly. go say hi. 🫶

---

and that's the page!! 🌸 this was SoSurroundScale(3IV), brought to you by the good people behind this source and version, and stamped with whatever date it was stamped with. mwah. 💅🎀 go surround something.