SoSwitch(3)

📦 version 3.1.3, in fedora 43, fedora 44

🎀 SoSwitch(3) 🎀

okay bestie, welcome to the Library Functions Manual page for SoSwitch — the Coin/Inventor node that's basically the group-chat admin of your scenegraph. she picks ONE child subgraph to walk, and she's iconic for it. let's get into it 💅

✨ NAME ✨

SoSwitch — the group node which selects one child subgraph for traversal. one. just one. she's decisive. 👑

🦋 SYNOPSIS 🦋

#include <Inventor/nodes/SoSwitch.h>
  • Inherits SoGroup.
  • Inherited by SoBlinker.

so she's a SoGroup girlie, and SoBlinker inherits from her. family tree is giving royal lineage 🌈

💖 Public Member Functions

  • virtual SoType getTypeId (void) const — the type-id getter, virtual as always.
  • SoSwitch (void) — default constructor, the classic.
  • SoSwitch (int numchildren) — constructor that takes a child count.
  • virtual SbBool affectsState (void) const — does she touch state? find out.
  • virtual void doAction (SoAction *action) — the action dispatcher.
  • virtual void callback (SoCallbackAction *action) — for SoCallbackAction.
  • virtual void GLRender (SoGLRenderAction *action) — for SoGLRenderAction.
  • virtual void pick (SoPickAction *action) — for SoPickAction.
  • virtual void getBoundingBox (SoGetBoundingBoxAction *action) — for SoGetBoundingBoxAction.
  • virtual void handleEvent (SoHandleEventAction *action) — for SoHandleEventAction.
  • virtual void getMatrix (SoGetMatrixAction *action) — for SoGetMatrixAction.
  • virtual void search (SoSearchAction *action) — for SoSearchAction.
  • virtual void write (SoWriteAction *action) — for SoWriteAction.
  • virtual void getPrimitiveCount (SoGetPrimitiveCountAction *action) — for SoGetPrimitiveCountAction.
  • virtual void audioRender (SoAudioRenderAction *action) — for SoAudioRenderAction.
  • virtual void notify (SoNotList *nl) — the notification handler.

💫 Public Member Functions inherited from SoGroup

  • SoGroup (void) — default constructor.
  • SoGroup (int nchildren) — constructor with a child-count hint.
  • virtual void addChild (SoNode *node) — add a child to the end.
  • virtual void insertChild (SoNode *child, int newchildindex) — slot a child in at a specific index.
  • virtual SoNode * getChild (int index) const — grab the child at index.
  • virtual int findChild (const SoNode *node) const — where's this child at?
  • virtual int getNumChildren (void) const — how many children do we have.
  • virtual void removeChild (int childindex) — bye bye child at childindex.
  • virtual void removeChild (SoNode *child) — bye bye this specific child.
  • virtual void removeAllChildren (void) — clear the whole roster.
  • virtual void replaceChild (int index, SoNode *newchild) — swap out the child at index.
  • virtual void replaceChild (SoNode *oldchild, SoNode *newchild) — swap oldchild for newchild.
  • virtual SoChildList * getChildren (void) const — hand over the whole child list.

💫 Public Member Functions inherited from SoNode

  • void setOverride (const SbBool state) — set the override flag.
  • SbBool isOverride (void) const — is override on?
  • void setNodeType (const NodeType type) — set the node type.
  • NodeType getNodeType (void) const — get the node type.
  • virtual SoNode * copy (SbBool copyconnections=FALSE) const — copy the node.
  • virtual void GLRenderBelowPath (SoGLRenderAction *action) — render below path.
  • virtual void GLRenderInPath (SoGLRenderAction *action) — render in path.
  • virtual void GLRenderOffPath (SoGLRenderAction *action) — render off path.
  • virtual void rayPick (SoRayPickAction *action) — ray pick handler.
  • virtual void grabEventsSetup (void) — set up event grabbing.
  • virtual void grabEventsCleanup (void) — tear down event grabbing.
  • virtual void startNotify (void) — kick off notification.
  • uint32_t getNodeId (void) const — the node's id.
  • virtual void writeInstance (SoOutput *out) — write the instance out.
  • virtual SoNode * addToCopyDict (void) const — add yourself to the copy dict.
  • virtual SoFieldContainer * copyThroughConnection (void) const — copy through a connection.

💫 Public Member Functions inherited from SoFieldContainer

  • void setToDefaults (void) — reset all fields to defaults.
  • SbBool hasDefaultValues (void) const — everything still default?
  • SbBool fieldsAreEqual (const SoFieldContainer *container) const — compare fields with another container.
  • void copyFieldValues (const SoFieldContainer *container, SbBool copyconnections=FALSE) — copy field values over.
  • SbBool set (const char *const fielddata) — set fields from a string.
  • void get (SbString &fielddata) — read fields out into a string.
  • virtual int getFields (SoFieldList &l) const — collect the fields.
  • virtual int getAllFields (SoFieldList &l) const — collect all the fields.
  • virtual SoField * getField (const SbName &name) const — look up a field by name.
  • virtual SoField * getEventIn (const SbName &name) const — look up an event in by name.
  • virtual SoField * getEventOut (const SbName &name) const — look up an event out by name.
  • SbBool getFieldName (const SoField *const field, SbName &name) const — reverse lookup, field to name.
  • SbBool enableNotify (const SbBool flag) — turn notifications on/off.
  • SbBool isNotifyEnabled (void) const — are notifications on?
  • SbBool set (const char *fielddata, SoInput *input) — set fields from a string with an input.
  • void get (SbString &fielddata, SoOutput *out) — read fields out with an output.
  • virtual SbBool validateNewFieldValue (SoField *field, void *newval) — validate a new field value.
  • virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE) — add a write reference.
  • SbBool getIsBuiltIn (void) const — is this thing built-in?
  • virtual void getFieldsMemorySize (size_t &managed, size_t &unmanaged) const — memory size of fields.
  • void setUserData (void *userdata) const — stash your user data.
  • void * getUserData (void) const — get your user data back.

💫 Public Member Functions inherited from SoBase

  • void ref (void) const — bump the ref count.
  • void unref (void) const — drop the ref count.
  • void unrefNoDelete (void) const — unref, but don't delete.
  • int32_t getRefCount (void) const — what's the ref count rn.
  • void touch (void) — touch it.
  • SbBool isOfType (SoType type) const — type check.
  • virtual SbName getName (void) const — get the name.
  • virtual void setName (const SbName &newname) — set the name.
  • void addAuditor (void *const auditor, const SoNotRec::Type type) — add an auditor.
  • void removeAuditor (void *const auditor, const SoNotRec::Type type) — remove an auditor.
  • const SoAuditorList & getAuditors (void) const — get the auditor list.
  • SbBool shouldWrite (void) — should this be written?
  • void assertAlive (void) const — assert that you're alive.

🌟 Static Public Member Functions

  • static SoType getClassTypeId (void) — the class type id.
  • static void initClass (void) — initialize the class.

🌟 Static Public Member Functions inherited from SoGroup

  • static SoType getClassTypeId (void) — the class type id.
  • static void initClass (void) — initialize the class.

🌟 Static Public Member Functions inherited from SoNode

  • static uint32_t getCompatibilityTypes (const SoType &nodetype) — compatibility types for a node type.
  • static SoType getClassTypeId (void) — the class type id.
  • static SoNode * getByName (const SbName &name) — find a node by name.
  • static int getByName (const SbName &name, SoNodeList &l) — find nodes by name into a list.
  • static void initClass (void) — initialize the class.
  • static void initClasses (void) — initialize the classes.
  • static uint32_t getNextNodeId (void) — the next node id.
  • static int getActionMethodIndex (const SoType type) — action method index for a type.
  • static void getBoundingBoxS (SoAction *action, SoNode *node) — static bounding-box action.
  • static void GLRenderS (SoAction *action, SoNode *node) — static GL render action.
  • static void callbackS (SoAction *action, SoNode *node) — static callback action.
  • static void getMatrixS (SoAction *action, SoNode *node) — static get-matrix action.
  • static void handleEventS (SoAction *action, SoNode *node) — static handle-event action.
  • static void pickS (SoAction *action, SoNode *node) — static pick action.
  • static void rayPickS (SoAction *action, SoNode *node) — static ray-pick action.
  • static void searchS (SoAction *action, SoNode *node) — static search action.
  • static void writeS (SoAction *action, SoNode *node) — static write action.
  • static void audioRenderS (SoAction *action, SoNode *node) — static audio render action.
  • static void getPrimitiveCountS (SoAction *action, SoNode *node) — static primitive-count action.

🌟 Static Public Member Functions inherited from SoFieldContainer

  • static void initClass (void) — initialize the class.
  • static SoType getClassTypeId (void) — the class type id.
  • static void cleanupClass (void) — clean up the class.
  • static void initCopyDict (void) — initialize the copy dict.
  • static void addCopy (const SoFieldContainer *orig, const SoFieldContainer *copy) — register a copy.
  • static SoFieldContainer * checkCopy (const SoFieldContainer *orig) — check for a copy.
  • static SoFieldContainer * findCopy (const SoFieldContainer *orig, const SbBool copyconnections) — find a copy.
  • static void copyDone (void) — copying is done, bestie.

🌟 Static Public Member Functions inherited from SoBase

  • static void initClass (void) — initialize the class.
  • static SoType getClassTypeId (void) — the class type id.
  • static void addName (SoBase *const base, const char *const name) — add a name.
  • static void removeName (SoBase *const base, const char *const name) — remove a name.
  • static void incrementCurrentWriteCounter (void) — bump the write counter.
  • static void decrementCurrentWriteCounter (void) — drop the write counter.
  • static SoBase * getNamedBase (const SbName &name, SoType type) — get a named base.
  • static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type) — get named bases into a list.
  • static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype) — read a base in.
  • static void setInstancePrefix (const SbString &c) — set the instance prefix.
  • static void setTraceRefs (SbBool trace) — set reference tracing.
  • static SbBool getTraceRefs (void) — get reference tracing.
  • static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname) — connect a route.
  • static SbBool readRoute (SoInput *input) — read a route.

🍓 Public Attributes

  • SoSFInt32 whichChild — THE field. this is the one that decides which child gets traversed. she's the main character here, no cap. 👑

🔒 Protected Member Functions

  • virtual const SoFieldData * getFieldData (void) const — get the field data.
  • virtual ~SoSwitch () — destructor, protected as ever.
  • void traverseChildren (SoAction *action) — traverse the children.

🔒 Protected Member Functions inherited from SoGroup

  • virtual ~SoGroup () — destructor.
  • virtual SbBool readInstance (SoInput *in, unsigned short flags) — read an instance.
  • virtual SbBool readChildren (SoInput *in) — read the children.
  • virtual void copyContents (const SoFieldContainer *from, SbBool copyconnections) — copy the contents.

🔒 Protected Member Functions inherited from SoNode

  • SoNode (void) — constructor.
  • virtual ~SoNode () — destructor.

🔒 Protected Member Functions inherited from SoFieldContainer

  • SoFieldContainer (void) — constructor.
  • virtual ~SoFieldContainer () — destructor.

🔒 Protected Member Functions inherited from SoBase

  • SoBase (void) — constructor.
  • virtual ~SoBase () — destructor.
  • virtual void destroy (void) — destroy it.
  • SbBool hasMultipleWriteRefs (void) const — multiple write refs?
  • SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const — write the header.
  • void writeFooter (SoOutput *out) const — write the footer.
  • virtual const char * getFileFormatName (void) const — get the file format name.

🧚 Static Protected Member Functions

  • static const SoFieldData ** getFieldDataPtr (void) — get the field data pointer.

🧚 Static Protected Member Functions inherited from SoGroup

  • static const SoFieldData ** getFieldDataPtr (void) — get the field data pointer.

🧚 Static Protected Member Functions inherited from SoNode

  • static const SoFieldData ** getFieldDataPtr (void) — get the field data pointer.
  • static void setNextActionMethodIndex (int index) — set the next action method index.
  • static int getNextActionMethodIndex (void) — get the next action method index.
  • static void incNextActionMethodIndex (void) — increment the next action method index.
  • static void setCompatibilityTypes (const SoType &nodetype, const uint32_t bitmask) — set compatibility types.

🧚 Static Protected Member Functions inherited from SoBase

  • static uint32_t getCurrentWriteCounter (void) — get the current write counter.
  • static void staticDataLock (void) — lock the static data.
  • static void staticDataUnlock (void) — unlock the static data.

🌈 Additional Inherited Members

Public Types inherited from SoNode

enum NodeType { INVENTOR = 0x0000, VRML1 = 0x0001, VRML2 = 0x0002,
    INVENTOR_1 = 0x0004, INVENTOR_2_0 = 0x0008, INVENTOR_2_1 = 0x0010,
    INVENTOR_2_5 = 0x0020, INVENTOR_2_6 = 0x0040, COIN_1_0 = 0x0080,
    COIN_2_0 = 0x0100, EXTENSION = 0x0200, COIN_2_2 = 0x0400, COIN_2_3 =
    0x0800, COIN_2_4 = 0x1000, INVENTOR_5_0 = 0x2000, COIN_2_5 = 0x4000,
    COIN_3_0 = 0x8000, INVENTOR_6_0 = 0x10000 }

Protected Types inherited from SoBase

enum BaseFlags { IS_ENGINE = 0x01, IS_GROUP = 0x02 }

Protected Attributes inherited from SoGroup

  • SoChildList * children

Protected Attributes inherited from SoNode

  • uint32_t uniqueId

Protected Attributes inherited from SoFieldContainer

  • SbBool isBuiltIn

Static Protected Attributes inherited from SoNode

  • static uint32_t nextUniqueId = 1
  • static int nextActionMethodIndex = 0

💖 Detailed Description 💖

okay so here's the whole vibe: the SoSwitch class is a group node which selects one child subgraph for traversal. that's her whole thing. she's not doing the most, she's doing the right amount. ✨

Which child to traverse is controlled by the application programmer by using the SoSwitch::whichChild field. and bestie, it gets better — in addition to picking out a single child for traversal, it is also possible to flip all children on or off for traversal. so you can have everyone or no one. it's giving "everyone's invited / actually no one is coming" energy 😭

This node is very useful for conditionally turning on or off parts of the scenegraph based on the current application processing mode, visualizing mode, or whatever else the application can do. so like, whatever your app's whole deal is — she'll gatekeep the scenegraph accordingly. obsessed. 🫶

FILE FORMAT/DEFAULTS:

Switch {
    whichChild -1
}

🛠️ Constructor & Destructor Documentation 🛠️

SoSwitch::SoSwitch (void )

Default constructor. the classic, no args, just vibes. 💅

SoSwitch::SoSwitch (int numchildren)

Constructor.

The argument should be the approximate number of children which is expected to be inserted below this node. The number need not be exact, as it is only used as a hint for better memory resource allocation.

ngl bestie this is literally just a hint — she's not counting your children, she's just reserving a lil space for them. don't stress about getting it perfect. 🌸

SoSwitch::~SoSwitch () [protected], [virtual]

Destructor. protected and virtual, as the ancestors intended. 🦋

💖 Member Function Documentation 💖

SoType SoSwitch::getTypeId (void ) const [virtual]

Okay bestie, this one is literally the ✨identity check✨ of the whole type system. It hands you back the type identification of any object derived from a class that inherits SoBase. What's it for? Run-time type checking, and "downward" casting — you know, when you know a node is secretly a fancier type and you wanna peek inside. 👑

Usage example, take notes:

void foo(SoNode * node)
{
  if (node->getTypeId() == SoFile::getClassTypeId()) {
    SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
  }
}

Now, for the application programmers out there who wanna extend the library with new nodes, engines, nodekits, draggers or whatever else you dream up: this method needs to be overridden in all subclasses. Like, no skipping it, fr fr. You normally do that as part of setting up the full type system for your extension classes, and the usual way is the pre-defined macros — available through for instance Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes), Inventor/engines/SoSubEngine.h (for engine classes), and so on. The macros do the heavy lifting, you just show up. 💅

Want more? For the full tea on writing Coin extensions, go read the class documentation of the toplevel superclasses for the various class groups.

  • Reimplemented from SoGroup.
  • Reimplemented in SoBlinker.

const SoFieldData * SoSwitch::getFieldData (void ) const [protected], [virtual]

Returns a pointer to the class-wide field data storage object for this instance. And if there are, like, no fields at all? It returns NULL. Simple as that. 🎀

  • Reimplemented from SoGroup.
  • Reimplemented in SoBlinker.

SbBool SoSwitch::affectsState (void ) const [virtual]

Returns TRUE if the node could have any effect on the state during traversal. That's it, that's the vibe check.

But when it returns FALSE? Then no data in the traversal-state will change from the pre-traversal state to the post-traversal state. Iconic behaviour, honestly. For example, the SoSeparator node returns FALSE, because it pushes and pops the state before and after traversal of its children — in and out, clean, no mess. All SoShape nodes return FALSE too, since just pushing out geometry data to the rendering engine won't affect the actual rendering state. Sending the fit pics doesn't change who you are. ✨

The default method returns TRUE, on a "better safe than sorry" philosophy. Cautious queen behaviour. 🙈

  • Reimplemented from SoNode.

void SoSwitch::doAction (SoAction * action) [virtual]

This function performs the typical operation of a node for any action. The general-purpose girly. 💫

  • Reimplemented from SoGroup.

void SoSwitch::callback (SoCallbackAction * action) [virtual]

Action method for SoCallbackAction.

It just updates the state according to how the node behaves for the render action, so you, the application programmer, can use the SoCallbackAction for extracting information about the scene graph. Lowkey a spy mission, highkey useful. 🕵️‍♀️

  • Reimplemented from SoGroup.

void SoSwitch::GLRender (SoGLRenderAction * action) [virtual]

Action method for the SoGLRenderAction.

This is called during rendering traversals. Any node that influences the rendering state in any way — or who just wants to throw geometry primitives at OpenGL — overrides this method. Main character energy only. 👑

  • Reimplemented from SoGroup.

void SoSwitch::pick (SoPickAction * action) [virtual]

Action method for SoPickAction.

Does common processing for SoPickAction action instances. Nothing dramatic, just doing its little tasks. 🧚

  • Reimplemented from SoGroup.

void SoSwitch::getBoundingBox (SoGetBoundingBoxAction * action) [virtual]

Action method for the SoGetBoundingBoxAction.

Calculates bounding box and center coordinates for the node, and modifies the values of the action so it encompasses the bounding box for this node — and shifts the center point for the scene more towards the one for this node. Basically it's out here claiming space. 💅

Nodes that influence how geometry nodes calculate their bounding box also override this method, to change the relevant state variables.

  • Reimplemented from SoGroup.
  • Reimplemented in SoBlinker.

void SoSwitch::handleEvent (SoHandleEventAction * action) [virtual]

Action method for SoHandleEventAction.

It inspects the event data from action, and processes it if it's something this node should actually react to. Not everything is your business, bestie — know when to respond. 💖

Nodes that influence relevant state variables for how event handling is done also override this method.

  • Reimplemented from SoGroup.

void SoSwitch::getMatrix (SoGetMatrixAction * action) [virtual]

Action method for SoGetMatrixAction.

Updates action by accumulating with the transformation matrix of this node (if any). Only if any, though. No matrix, no accumulation. 🎀

  • Reimplemented from SoGroup.

void SoSwitch::search (SoSearchAction * action) [virtual]

Action method for SoSearchAction.

It compares the search criteria from the action to see if this node is a match. Searching is done by matching up all criteria set up in the SoSearchAction — so if any of the requested criteria is a miss, the search is not deemed successful for the node. All or nothing, periodt. 😤

See also

  • SoSearchAction
  • Reimplemented from SoGroup.

void SoSwitch::write (SoWriteAction * action) [virtual]

Action method for SoWriteAction.

Writes out a node object, and any connected nodes, engines etc — if necessary. Only if necessary, mind you. Don't write things that don't need writing. ✍️

  • Reimplemented from SoGroup.
  • Reimplemented in SoBlinker.

void SoSwitch::getPrimitiveCount (SoGetPrimitiveCountAction * action) [virtual]

Action method for the SoGetPrimitiveCountAction.

It calculates the number of triangle, line segment and point primitives for the node, and adds these to the counters of the action. Counting all the little pieces, one by one. 🔢

Nodes that influence how geometry nodes calculate their primitive count also override this method, to change the relevant state variables.

  • Reimplemented from SoGroup.

void SoSwitch::audioRender (SoAudioRenderAction * action) [virtual]

Action method for SoAudioRenderAction.

Does common processing for SoAudioRenderAction action instances. Turn it up. 🎧

  • Reimplemented from SoGroup.

void SoSwitch::notify (SoNotList * l) [virtual]

Notifies all auditors for this instance when changes are made. Like a group chat blast — everyone who's watching gets the update. 📣

  • Reimplemented from SoNode.
  • Reimplemented in SoBlinker.

void SoSwitch::traverseChildren (SoAction * action) [protected]

Okay so, real talk: this function was part of the original SGI Inventor API, but it is not supported in Coin, as it looks like it should probably have been private in Inventor. So... yeah. It's giving "left in the API by accident". 💀 Don't rely on it.

🌸 Member Data Documentation 🌸

SoSFInt32 SoSwitch::whichChild

Selects which child to traverse during rendering (and some other) actions. This is the field, the one that decides everything. 👑

The value should be either:

  • SO_SWITCH_NONE — for traversing no children, like it was an empty SoGroup node
  • SO_SWITCH_ALL — for traversing like if we were an SoGroup node
  • SO_SWITCH_INHERIT — for traversing the same child as the last SoSwitch node
  • or an index value for a child

Now, when you're using SO_SWITCH_INHERIT, it is important to understand how the SoSwitch-node is affected by other SoSwitch-nodes. Pay attention bestie, this one's tricky.

If you have several switches in the scenegraph, the last switch with its whichChild field set to anything but SO_SWITCH_INHERIT will be used. And here's the plot twist: the switch does not only inherit from its parent switch node, but also from its siblings, located anywhere before it in the scenegraph. Family drama. 😭

An example will help clarify this:

#Inventor V2.1 ascii

Separator {
  Switch {
    whichChild 0

    Group {
      Switch {
        whichChild 1
        BaseColor { rgb 1 0 0 } # red
        BaseColor { rgb 1 1 0 } # yellow
      }
      Switch {
        whichChild -2 # SO_SWITCH_INHERIT
        BaseColor { rgb 0 1 0 } # green
        BaseColor { rgb 0 0 1 } # blue
      }
      Cube { }
    }
  }
}

This results in a blue cube on the screen. The reason being that the value of the previous whichChild field was inherited by the final switch, making it select child 1 — the blue BaseColor. Inheritance ate, honestly. 💙

When constructing ascii Inventor files, the integer values for the keywords must be used instead of their names. They are -1 for SO_SWITCH_NONE, -2 for SO_SWITCH_INHERIT, and -3 for SO_SWITCH_ALL. No names in ascii files, only numbers, fr fr.

Default value for the field is SO_SWITCH_NONE.

✨ Author ✨

Generated automatically by Doxygen for Coin from the source code. (Not a human author — the robot did it. 🤖)

And that's a wrap on SoSwitch(3), bestie! 🦋 Thanks for reading all the way to the bottom, you absolute legend. This page came from Coin, version 3.1.3, and the manual page itself is SoSwitch(3). Go forth and switch responsibly. 💖✨🎀

📦 where this page comes from