SoState(3)

💖 SoState(3) — Library Functions Manual 💖

ok so bestie, welcome to the SoState page, it lives in the Library Functions Manual and it's giving ✨core Coin energy✨. Buckle up, this one's a long one (part 1 of 2, we're not even done yet).

---

🌸 NAME 🌸

SoState — the SoState class manages the Coin scenegraph traversal state data.

---

🎀 SYNOPSIS 🎀

#include <Inventor/misc/SoState.h>

🦋 Public Member Functions 🦋

SoState (SoAction *action, const SoTypeList &enabledelements)
~SoState (void)
SoAction * getAction (void) const
SoElement * getElement (const int stackindex)
const SoElement * getConstElement (const int stackindex) const
void push (void)
void pop (void)
void print (FILE *const file=stdout) const
SbBool isElementEnabled (const int stackindex) const
int getDepth (void) const
void setCacheOpen (const SbBool flag)
SbBool isCacheOpen (void) const
SoElement * getElementNoPush (const int stackindex) const

---

✨ Detailed Description ✨

The SoState class manages the Coin scenegraph traversal state data. periodt.

So here's the tea: the SoState class is used by actions derived from the SoAction class. It manages the scenegraph state as stacks of elements — and by elements we mean instances of classes derived from SoElement. It's stacks on stacks on stacks, no cap 🫶

If you want the full deep lore on how traversal states work inside Coin, the manual is literally recommending the book «The Inventor Toolmaker» (ISBN 0-201-62493-1), which is also available at SGI's online library. Just search for "Toolmaker". iykyk 📚

---

👑 Constructor & Destructor Documentation 👑

💅 SoState::SoState (SoAction * theAction, const SoTypeList & enabledelements)

The constructor, bestie. The theAction argument is the action object that this state is part of, and the enabledElements argument is an SoTypeList of the elements that are enabled for this action.

The constructor pushes a default element onto the indexes of all the enabled element stacks. Lowkey important: SoElement::push() is not called on the initial elements in the SoState stacks — instead, SoElement::init() is. So don't get it twisted 💀

References SoType::canCreateInstance(), SoType::createInstance(), SbPList::getLength(), SoElement::getNumStackIndices(), SoElement::getStackIndex(), SoElement::init(), SoType::isBad(), and SoElement::setDepth().

---

🧚 SoState::~SoState (void )

The destructor. Say bye bye 🥲

Heads up: when destruction happens, lagging events caused by lazy evaluation won't be performed. So like, if you were counting on those… no you weren't 🙈

---

ok that's part 1, don't go anywhere, more is coming ✨

💖 Member Function Documentation 💖

🎯 SoAction * SoState::getAction(void) const

Okay bestie, this one is the simplest slay on the whole page. It just hands you back the pointer to the action instance that was given to the constructor. That's it. That's the whole vibe. 🫶

---

🧚 SoElement * SoState::getElement(const int stackindex)

This one returns a modifyable instance of the element sitting on top of the stack with the given stackindex. But here's the tea: because of lazy programming, this function might have to do a lil work to get you there — so SoState::getConstElement() should be used instead whenever possible. ✨

ngl, if you don't actually need to write, use the const version. Save the effort, queen. 💅

References: SoType::createInstance(), SoElement::getDepth(), SoType::getName(), SbName::getString(), SoElement::getTypeId(), isElementEnabled(), SoDebugError::postInfo(), SoElement::push(), and SoElement::setDepth().

Referenced by: SoElement::getElement().

---

🔒 const SoElement * SoState::getConstElement(const int stackIndex) const

[inline] This returns a pointer to the top element of the given element stack. The element is read-only and must not be changed under any circumstances, or strange side-effects will occur. 🚫

Also lowkey important: this function will assert if the element with the given stack identity value is not presently on the state stack. Wanna check whether or not an element is present in the stack? Use SoState::isElementEnabled(). 💖

References: isElementEnabled().

Referenced by: SoElement::getConstElement().

---

⬇️ void SoState::push(void)

This pushes the state one level down. It saves the state so it can be changed and later restored back to this state by calling SoState::pop(). 🎀

The push and pop mechanism is performed lazily for efficiency reasons (it avoids a whole lot of memory allocation and copying). Only when a state element is actually going to be changed does that element get pushed for real. Efficiency? Obsessed. 👑

References: SoElement::depth.

Referenced by: SoSeparator::audioRender(), SoVRMLGroup::audioRender(), SoShape::beginSolidShape(), SoHandleEventAction::beginTraversal(), SoPickAction::beginTraversal(), SoRayPickAction::beginTraversal(), SoDragger::callback(), SoGeoSeparator::callback(), SoSeparator::callback(), SoVRMLGroup::callback(), SoVRMLTransform::callback(), SoArray::doAction(), SoMultipleCopy::doAction(), SoSeparator::doAction(), SoVRMLBillboard::doAction(), SoVRMLGroup::doAction(), SoVRMLShape::doAction(), SoVRMLTransform::doAction(), SoVertexShape::generateAndReadLockNormalCache(), SoVRMLVertexShape::generateAndReadLockNormalCache(), SoFaceSet::generatePrimitives(), SoImage::generatePrimitives(), SoIndexedFaceSet::generatePrimitives(), SoIndexedTriangleStripSet::generatePrimitives(), SoLineSet::generatePrimitives(), SoPointSet::generatePrimitives(), SoQuadMesh::generatePrimitives(), SoTriangleStripSet::generatePrimitives(), SoVRMLExtrusion::generatePrimitives(), SoVRMLIndexedFaceSet::generatePrimitives(), SoVRMLIndexedLineSet::generatePrimitives(), SoArray::getBoundingBox(), SoGeoSeparator::getBoundingBox(), SoLevelOfDetail::getBoundingBox(), SoSeparator::getBoundingBox(), SoVRMLBillboard::getBoundingBox(), SoVRMLGroup::getBoundingBox(), SoVRMLShape::getBoundingBox(), SoVRMLTransform::getBoundingBox(), SoSeparator::getMatrix(), SoVRMLTransform::getMatrix(), SoDragger::getPrimitiveCount(), SoGeoSeparator::getPrimitiveCount(), SoMarkerSet::getPrimitiveCount(), SoVRMLGroup::getPrimitiveCount(), SoVRMLTransform::getPrimitiveCount(), SoDragger::GLRender(), SoFaceSet::GLRender(), SoIndexedFaceSet::GLRender(), SoIndexedLineSet::GLRender(), SoIndexedNurbsCurve::GLRender(), SoIndexedTriangleStripSet::GLRender(), SoLineSet::GLRender(), SoMarkerSet::GLRender(), SoNurbsCurve::GLRender(), SoPointSet::GLRender(), SoQuadMesh::GLRender(), SoShape::GLRender(), SoText2::GLRender(), SoTriangleStripSet::GLRender(), SoVRMLBackground::GLRender(), SoVRMLCollision::GLRender(), SoVRMLElevationGrid::GLRender(), SoVRMLExtrusion::GLRender(), SoVRMLIndexedFaceSet::GLRender(), SoVRMLIndexedLineSet::GLRender(), SoVRMLInline::GLRender(), SoVRMLShape::GLRender(), SoWWWInline::GLRender(), SoExtSelection::GLRenderBelowPath(), SoGeoSeparator::GLRenderBelowPath(), SoLocateHighlight::GLRenderBelowPath(), SoSeparator::GLRenderBelowPath(), SoVRMLBillboard::GLRenderBelowPath(), SoVRMLGroup::GLRenderBelowPath(), SoVRMLTransform::GLRenderBelowPath(), SoGeoSeparator::GLRenderInPath(), SoLocateHighlight::GLRenderInPath(), SoSeparator::GLRenderInPath(), SoVRMLBillboard::GLRenderInPath(), SoVRMLGroup::GLRenderInPath(), SoVRMLTransform::GLRenderInPath(), SoVRMLAnchor::handleEvent(), SoDragger::rayPick(), SoGeoSeparator::rayPick(), SoIndexedNurbsCurve::rayPick(), SoIndexedNurbsSurface::rayPick(), SoNurbsCurve::rayPick(), SoNurbsSurface::rayPick(), SoVRMLTransform::rayPick(), SoArray::search(), SoMultipleCopy::search(), SoVertexShape::setNormalCache(), and SoShape::shouldGLRender().

---

⬆️ void SoState::pop(void)

This pops the state to restore it to a previous state. Pops are performed eagerly, but the code is very tight so there is no reason to worry about efficiency. It's giving optimized. 🔥

References: SoElement::pop().

Referenced by: SoSeparator::audioRender(), SoVRMLGroup::audioRender(), SoHandleEventAction::beginTraversal(), SoPickAction::beginTraversal(), SoRayPickAction::beginTraversal(), SoDragger::callback(), SoGeoSeparator::callback(), SoSeparator::callback(), SoVRMLGroup::callback(), SoVRMLTransform::callback(), SoArray::doAction(), SoMultipleCopy::doAction(), SoSeparator::doAction(), SoVRMLBillboard::doAction(), SoVRMLGroup::doAction(), SoVRMLShape::doAction(), SoVRMLTransform::doAction(), SoShape::endSolidShape(), SoVertexShape::generateAndReadLockNormalCache(), SoVRMLVertexShape::generateAndReadLockNormalCache(), SoFaceSet::generatePrimitives(), SoImage::generatePrimitives(), SoIndexedFaceSet::generatePrimitives(), SoIndexedTriangleStripSet::generatePrimitives(), SoLineSet::generatePrimitives(), SoPointSet::generatePrimitives(), SoQuadMesh::generatePrimitives(), SoTriangleStripSet::generatePrimitives(), SoVRMLExtrusion::generatePrimitives(), SoVRMLIndexedFaceSet::generatePrimitives(), SoVRMLIndexedLineSet::generatePrimitives(), SoArray::getBoundingBox(), SoGeoSeparator::getBoundingBox(), SoLevelOfDetail::getBoundingBox(), SoSeparator::getBoundingBox(), SoVRMLBillboard::getBoundingBox(), SoVRMLGroup::getBoundingBox(), SoVRMLShape::getBoundingBox(), SoVRMLTransform::getBoundingBox(), SoSeparator::getMatrix(), SoVRMLTransform::getMatrix(), SoDragger::getPrimitiveCount(), SoGeoSeparator::getPrimitiveCount(), SoMarkerSet::getPrimitiveCount(), SoVRMLGroup::getPrimitiveCount(), SoVRMLTransform::getPrimitiveCount(), SoDragger::GLRender(), SoFaceSet::GLRender(), SoIndexedFaceSet::GLRender(), SoIndexedLineSet::GLRender(), SoIndexedNurbsCurve::GLRender(), SoIndexedTriangleStripSet::GLRender(), SoLineSet::GLRender(), SoMarkerSet::GLRender(), SoNurbsCurve::GLRender(), SoPointSet::GLRender(), SoQuadMesh::GLRender(), SoShape::GLRender(), SoText2::GLRender(), SoTriangleStripSet::GLRender(), SoVRMLBackground::GLRender(), SoVRMLCollision::GLRender(), SoVRMLElevationGrid::GLRender(), SoVRMLExtrusion::GLRender(), SoVRMLIndexedFaceSet::GLRender(), SoVRMLIndexedLineSet::GLRender(), SoVRMLInline::GLRender(), SoVRMLShape::GLRender(), SoWWWInline::GLRender(), SoExtSelection::GLRenderBelowPath(), SoGeoSeparator::GLRenderBelowPath(), SoLocateHighlight::GLRenderBelowPath(), SoSeparator::GLRenderBelowPath(), SoVRMLBillboard::GLRenderBelowPath(), SoVRMLGroup::GLRenderBelowPath(), SoVRMLTransform::GLRenderBelowPath(), SoGeoSeparator::GLRenderInPath(), SoLocateHighlight::GLRenderInPath(), SoSeparator::GLRenderInPath(), SoVRMLBillboard::GLRenderInPath(), SoVRMLGroup::GLRenderInPath(), SoVRMLTransform::GLRenderInPath(), SoVRMLAnchor::handleEvent(), SoDragger::rayPick(), SoGeoSeparator::rayPick(), SoIndexedNurbsCurve::rayPick(), SoIndexedNurbsSurface::rayPick(), SoNurbsCurve::rayPick(), SoNurbsSurface::rayPick(), SoVRMLTransform::rayPick(), SoArray::search(), SoMultipleCopy::search(), SoVertexShape::setNormalCache(), and SoShape::shouldGLRender().

---

🖨️ void SoState::print(FILE *const file = stdout) const

This method is just for debugging purposes. That's the whole job, bestie. 🐛

References: SoType::getName(), SbName::getString(), and SoElement::getTypeId().

---

✅ SbBool SoState::isElementEnabled(const int stackindex) const

[inline] Returns TRUE if the element with the given element stack index is enabled, and FALSE otherwise. Simple as that. 💖

Referenced by: SoBaseColor::doAction(), SoMaterial::doAction(), SoPackedColor::doAction(), SoVRMLColor::doAction(), SoVRMLShape::doAction(), getConstElement(), getElement(), SoAsciiText::GLRender(), SoText3::GLRender(), and SoSurroundScale::updateMySurroundParams().

---

📏 int SoState::getDepth(void) const

Returns the current depth of the state stack. 🌈

Heads up tho: the depth is "virtual", not necessarily physical. It's giving main character energy but make it abstract. ✨

Referenced by: SoSceneManager::processEvent().

---

🗄️ void SoState::setCacheOpen(const SbBool open)

Controls whether a cache is open. 🫶

---

🔍 SbBool SoState::isCacheOpen(void) const

[inline] Returns whether a cache is open. 💅

Referenced by: SoElement::capture(), SoSceneTexture2::GLRender(), SoTexture2::GLRender(), SoTextureCubeMap::GLRender(), SoVRMLImageTexture::GLRender(), SoVRMLPixelTexture::GLRender(), SoSeparator::GLRenderBelowPath(), SoVRMLGroup::GLRenderBelowPath(), SoGLRenderAction::handleTransparency(), and SoShape::shouldGLRender().

---

✨ Author ✨

Generated automatically by Doxygen for Coin from the source code. 🤖

---

And that's a wrap on the SoState(3) girlies! This whole glow-up came straight from the Coin source code, page SoState(3), Version 2.5.0 — no date on this one, just vibes and reference lists. Stay lazy, stay pushed, and always pop() what you push(). 💜🦋