SOFIELD(3iv)

💖 SoField — the manual page, but make it make sense 💖

okay so welcome to SoField(3IV), bestie. This is the part 1 of the page, so don't go anywhere, there's more coming. ✨

---

🌸 NAME 🌸

SoField — the base class for all fields. Like, the mother of every field. The blueprint. The blueprint-est blueprint. 👑

---

🦋 INHERITS FROM 🦋

SoField

(yes she's the root of it all, she inherits from nobody, she IS the moment)

---

✨ SYNOPSIS ✨

#include <Inventor/fields/SoField.h>

🎀 Methods from class SoField 🎀

void                setIgnored(SbBool ignore)
SbBool              isIgnored() const
SbBool              isDefault() const
static SoType       getClassTypeId()
virtual SoType      getTypeId() const
virtual SbBool      isOfType(SoType type) const
SbBool              set(const char *valueString)
void                get(SbString &valueString)
int                 operator ==(const SoField &f) const
int                 operator !=(const SoField &f) const
void                touch()
SbBool              connectFrom(SoField *fromField)
SbBool              connectFrom(SoEngineOutput *fromEngine)
void                disconnect()
SbBool              isConnected() const
SbBool              isConnectedFromField() const
SbBool              getConnectedField(SoField *&writingField) const
SbBool              isConnectedFromEngine() const
SbBool              getConnectedEngine(SoEngineOutput *&engineOutput)
                         const
void                enableConnection(SbBool flag)
SbBool              isConnectionEnabled() const
int                 getForwardConnections(SoFieldList &list) const
SoFieldContainer *  getContainer() const

that's the whole roster, no gatekeeping 💅

---

💜 DESCRIPTION 💜

Okay so. SoField is the abstract base class for every single field. Fields are the data elements that live inside nodes, and they're also the input values for engines. Every node class or engine class declares its own set of fields and gives each one a name. Those names are what define the semantics of the field — like, for example, the SoCube node has three float fields named width, height, and depth. (Iconic naming honestly.) Field classes hand you the access methods that let you indirectly edit and query the data inside nodes. 🫶

There are two abstract subclasses of SoField:

• SoSField — the base class for all single-valued field classes.
• SoMField — the base class for all multiple-valued fields, which hold dynamic arrays of values.

Subclasses of SoSField get the SoSF prefix, and subclasses of SoMField get the SoMF prefix. If you want the extra methods, go read the reference pages for SoSField and SoMField. 📚

Fields are normally constructed only inside node or engine instances. If you need a field that isn't part of a node or engine, you can make a GlobalField — check the methods on SoDB for creating global fields. 🌍

---

🔗 connections, the whole vibe 🔗

Fields can be connected directly to another field, or they can be connected to the output of an engine. Once a field has a connection, its value changes whenever the thing it's connected to changes.

Example time, because examples ate: say field "A" is connected from "B" (done via A->connectFrom(B)). When B's value changes, A's value changes too. 😌

BUT. Here's the catch, and it's important: A and B may have different values even while they're connected. If A's value gets set after B's value, then A's value will be different from B's until B's value gets set again. That's just how it is, no cap.

A field can be connected to several other fields, but it can be connected from only one source. One source only. Monogamous from-direction. 💀

---

🌀 loops, yes really 🌀

It is possible — and honestly often useful — to create loops of field connections (like, A connected from B and B connected from A). When there are loops, the rule is: the last setValue() done overrides any connections in to that value.

The way to picture it: setting a field's value immediately propagates that value forward into all the fields it's connected to, and the propagation stops at the place where the original setValue() happened, if there's a connection loop. 🛑

fun fact: actually a more efficient mechanism than that is used, but the semantics are the same. So don't come for the vibes, the vibes are accurate.

---

🧚 field converters 🧚

If you try to connect two fields of differing types, Inventor will automatically try to insert a field converter engine between them to convert values from one type into the other. Slay, honestly.

Inventor has most reasonable conversions built-in, including:

• multiple-valued field to single-valued, and vice versa
• anything to SoSFString
• anything to SoSFTrigger
• float / short / unsigned short / int32_t / uint32_t / etc numeric conversions

(and more, etc.)

You can add your own field converters using SoDB's extender method addConverter() — see the SoDB.h header file for the details. You can also check whether a converter is available with the SoDB::getConverter() method. 🔍

---

📝 file format, the rules 📝

Each field defines its own file format for reading and for being written to files, but all fields follow the same conventions:

• Fields in a node or engine are written as the name of the field followed by the field's value.
• Fields are not written if they haven't been modified since they were created (i.e. if they have their default value). Not modified = not written. Simple as. ✨

---

🫧 the ignored flag 🫧

The ignored flag is written as a "~" character after the field's value. And if the field's value is its default value, then just the "~" gets written. That's it, that's the whole rule. 🎀

---

🔌 writing connections 🔌

Field connections are written as an "=" followed by the container of the field or engine output that the field is connected to, followed by a "." and the name of the field or engine output.

For example:

DEF node1 Transform { translation 1 1 1 }
DEF node2 Scale { scaleFactor 1 1 1 = USE node1.translation }

look at that, gorgeous, no notes 💅

---

🌍 global fields 🌍

Global fields are written as part of an internal SoFieldContainer class called GlobalField. That class writes out an SoSFName field named type whose value is the type of the global field, followed by a field of that type whose name is the name of the global field.

For example, a global uint32_t field called "FrameCounter" whose value is 494 would be written as:

GlobalField {
                    type SoSFUInt32
                    FrameCounter 494
}

---

okay that's part 1 bestie, keep scrolling, there's more 👀

💅 METHODS 💅

okay bestie, this is the part where the field actually does stuff. buckle up 🎀

---

• void setIgnored(SbBool ignore) / SbBool isIgnored() const — sets/gets the ignore flag for this field. When a field's ignore flag is TRUE, the field is not used during traversal for rendering and other actions. default value of this flag is FALSE, no cap.
• SbBool isDefault() const — gets the state of the default flag of the field. This flag will be TRUE for any field whose value is not modified after construction, and FALSE for the ones that have changed (each node or engine determines what the default values for its fields are, so it's giving very "ask your node" energy).

⚠️ note: the state of this flag should not be set explicitly from within applications. like, don't touch it. hands off. 🙈

• static SoType getClassTypeId() — return the type identifier for this field class. classic. iconic.
• virtual SoType getTypeId() const — return the type identifier for this field instance (SoField *).
• virtual SbBool isOfType(SoType type) const — returns TRUE if this field is the given type or derived from that type. This is typically used with the getClassTypeId() method to figure out the type of an SoField * at run-time, and it's literally the main character move of runtime type checking:

SoField *field = ....;
if (field->isOfType(SoSFFloat::getClassTypeId())) {
    SoSFFloat *floatField = (SoSFFloat *)field);
    floatField->setValue(4.5);
}

• SbBool set(const char *valueString) — sets the field to the given value, which is an ASCII string in the Inventor file format. Each field subclass defines its own file format, so go check their reference pages for the tea on that. ✨ The string should contain only the field's value, not the field's name (like "1.0", not "width 1.0" — no name-dropping bestie). This method returns TRUE if the string is valid, FALSE if it is not.
• void get(SbString &valueString) — returns the value of the field in the Inventor file format, even if the field has its default value. yeah, even then. it's that committed.
• int operator ==(const SoField &f) const / int operator !=(const SoField &f) const — return TRUE (FALSE) if this field is of the same type and has the same value as f. twin check 👯
• void touch() — simulates a change to the field, causing attached sensors to fire, connected fields and engines to be marked as needing evaluation, and so forth. so dramatic for no reason, we love her. 💅 Calling touch() on an instance of a derived field class is equivalent to calling setValue(getValue()) using the derived class's methods, except that the field's isDefault() status remains unchanged. subtle but important, iykyk.
• SbBool connectFrom(SoField *fromField) / SbBool connectFrom(SoEngineOutput *fromEngine) — connects this field to another field or from an engine output. If the field was connected to something before, it will be automatically disconnected (a field may have only one connection writing into it at a time — monogamous fr fr). Unless connections to the field are disabled (see enableConnection()), the field's value will be set to the value of the thing it is connected to.
• void disconnect() — disconnect the field from whatever it was connected to. This does nothing if the field was not connected. no connection, no problem. 🦋
• SbBool isConnected() const — returns TRUE if the field is connected to anything. anything at all. we don't judge.
• SbBool isConnectedFromField() const — returns TRUE if the field is connected to another field.
• SbBool getConnectedField(SoField *&writingField) const — returns TRUE if this field is being written into by another field, and returns the field it is connected to in writingField. Returns FALSE and does not modify writingField if it is not connected to a field. respectful. doesn't touch what isn't hers. 🫶
• SbBool isConnectedFromEngine() const — returns TRUE if the field is connected to an engine's output.
• SbBool getConnectedEngine(SoEngineOutput *&engineOutput) const — returns TRUE if this field is being written into by an engine, and returns the engine output it is connected to in engineOutput. Returns FALSE and does not modify engineOutput if it is not connected to an engine.
• void enableConnection(SbBool flag) — field connections may be enabled and disabled. Disabling a field's connection is almost exactly like disconnecting it; the only difference is that you can later re-enable the connection by calling enableConnection(TRUE). 🎀

⚠️ Note that disconnecting an engine output can cause the engine's reference count to be decremented and the engine to be deleted, but disabling the connection does not decrement its reference count. so like. know the difference. this is the serious part. 💀

Re-enabling a connection will cause the value of the field to be changed to the engine output or field to which it is connected.

A field's connection-enabled status is maintained even if the field is disconnected or reconnected. By default, connections are enabled.

• SbBool isConnectionEnabled() const — returns FALSE if connections to this field are disabled. Note that this may return FALSE even if the field is not connected to anything. confusing? a little. true? absolutely. 🌸
• int getForwardConnections(SoFieldList &list) const — adds pointers to all of the fields that this field is writing into (either fields in nodes, global fields or engine inputs) to the given field list, and returns the number of forward connections. it's giving ✨networking✨
• SoFieldContainer *getContainer() const — returns the object that contains this field. The type of the object will be either SoNode, SoEngine, or will be a global field container (note that the global field container class is internal to Inventor; see the methods for creating and accessing global fields on SoDB). For example:

SoFieldContainer *f = field->getContainer();
if (f->isOfType(SoNode::getClassTypeId())) {
     ... do something ...
} else if (f->isOfType(SoEngine::getClassTypeId())) {
     ... do someting else ...
} else {
     ... it must be a global field.  We can figure out its name, but
                    that is about it:
     const SbName &globalFieldName = f->getName();
}

---

🌈 SEE ALSO 🌈

• SoSField
• SoMField
• SoNode
• SoDB

---

and that's the whole page bestie, we ate and left no crumbs 👑 the footer on this one is the SoField(3IV) source/version tag (the date slot is just sitting there empty, lowkey mysterious of her 🫶). go forth and field responsibly 💖✨🎀