SoField(3)

📦 version 2.5.0, in fedora 43, fedora 44

✨ SoField ✨

okay so. hi bestie 🫶 you just opened SoField(3), and ngl this one is kind of a big deal. it's the top-level abstract base class for every single field in Coin, and literally everything else is quietly built on top of it. this is part 1 of 4, so don't go anywhere. 💅

📛 NAME

SoField — The SoField class is the top-level abstract base class for fields. 👑

🎀 SYNOPSIS

#include <Inventor/fields/SoField.h>

Inherited by SoMField, and SoSField. 🌸

🔮 Public Types

enum FieldType { NORMAL_FIELD = 0, EVENTIN_FIELD, EVENTOUT_FIELD, EXPOSED_FIELD }

🧚 Public Member Functions

  • virtual ~SoField ()
  • void setIgnored (SbBool ignore)
  • SbBool isIgnored (void) const
  • void setDefault (SbBool def)
  • SbBool isDefault (void) const
  • virtual SoType getTypeId (void) const =0
  • SbBool isOfType (const SoType type) const
  • void enableConnection (SbBool flag)
  • SbBool isConnectionEnabled (void) const
  • SbBool connectFrom (SoEngineOutput *master, SbBool notnotify=0, SbBool append=0)
  • SbBool appendConnection (SoEngineOutput *master, SbBool notnotify=0)
  • void disconnect (SoEngineOutput *engineoutput)
  • SbBool isConnectedFromEngine (void) const
  • SbBool getConnectedEngine (SoEngineOutput *&master) const
  • SbBool connectFrom (SoField *master, SbBool notnotify=0, SbBool append=0)
  • SbBool appendConnection (SoField *master, SbBool notnotify=0)
  • void disconnect (SoField *field)
  • SbBool isConnectedFromField (void) const
  • SbBool getConnectedField (SoField *&master) const
  • int getNumConnections (void) const
  • int getForwardConnections (SoFieldList &slavelist) const
  • int getConnections (SoFieldList &masterlist) const
  • void disconnect (void)
  • SbBool isConnected (void) const
  • void setContainer (SoFieldContainer *cont)
  • SoFieldContainer * getContainer (void) const
  • SbBool set (const char *valuestring)
  • void get (SbString &valuestring)
  • SbBool shouldWrite (void) const
  • virtual void touch (void)
  • virtual void startNotify (void)
  • virtual void notify (SoNotList *nlist)
  • SbBool enableNotify (SbBool on)
  • SbBool isNotifyEnabled (void) const
  • void addAuditor (void *f, SoNotRec::Type type)
  • void removeAuditor (void *f, SoNotRec::Type type)
  • int operator== (const SoField &f) const
  • int operator!= (const SoField &f) const
  • virtual void connectionStatusChanged (int numconnections)
  • SbBool isReadOnly (void) const
  • virtual SbBool isSame (const SoField &f) const =0
  • virtual void copyFrom (const SoField &f)=0
  • virtual void fixCopy (SbBool copyconnections)
  • virtual SbBool referencesCopy (void) const
  • void copyConnection (const SoField *fromfield)
  • virtual SbBool read (SoInput *in, const SbName &name)
  • virtual void write (SoOutput *out, const SbName &name) const
  • virtual void countWriteRefs (SoOutput *out) const
  • void setFieldType (int type)
  • int getFieldType (void) const
  • SbBool getDirty (void) const
  • void setDirty (SbBool dirty)
  • void evaluate (void) const

⭐ Static Public Member Functions

  • static void initClass (void)
  • static void initClasses (void)
  • static SoType getClassTypeId (void)

🫶 Protected Member Functions

  • SoField (void)
  • void valueChanged (SbBool resetdefault=1)
  • virtual void evaluateConnection (void) const
  • virtual SbBool readValue (SoInput *in)=0
  • virtual void writeValue (SoOutput *out) const =0
  • virtual SbBool readConnection (SoInput *in)
  • virtual void writeConnection (SoOutput *out) const
  • SbBool isDestructing (void) const

🌸 Detailed Description

The SoField class is the top-level abstract base class for fields. say it with me now: top-level, abstract, base class. iconic. 💖

Fields is the mechanism used throughout Coin for encapsulating basic data types to detect changes made to them, and to provide conversion, import and export facilities.

Almost all public properties in nodes are stored in fields, and so are the inputs and outputs of engines. So fields can be viewed as the major mechanism for scenegraph nodes and engines to expose their public API. like, it's the way your nodes talk to the outside world, no cap.

Forcing data modification to go through a public function interface while hiding the data members makes it possible to automatically detect and react upon changes in the data structures set up by the application programmer.

E.g. the default behavior when changing the value of a field in a scenegraph node is that there'll automatically be a chain of notifications -- from the field to the owner node, from that node to it's parent node, etc all the way through to the top-most root node, where the need for a rendering update will be signalled to the application. the way that the notification just travels up the whole tree? lowkey gorgeous. 🌈

(This notification mechanism is the underlying feature that makes the Coin library classify as a so-called data-driven scenegraph API.

The practical consequences of this is that rendering and many other processing actions is default scheduled to only happen when something has changed in the retained data structures, making the Coin library under normal circumstances much less CPU intensive than so-called "application-driven" scenegraph API, like for instance SGI IRIS Performer, which are continuously re-rendering even when nothing has changed in the data structures or with the camera viewport.) so yeah, Coin only does the work when there's actually work to do. she's efficient. she's mindful. she's not burning your CPU for fun. 🔥

Storing data members as fields also provides other conveniences for the application programmer:

  • Fields can be connected to other fields. This makes it for instance possible to have "self-updating" scenes, ie you can set up scenes where entities automatically react to changes in other entities. This also provides a necessary mechanism for having "auto-animating" scenes, as it is possible to connect any field to the global field named realTime, providing a wall-clock timer. 🕰️
  • When connecting fields to each other, Coin has built-in mechanisms for automatically converting between different field types. bestie it just converts, you don't even have to ask.
  • Fields provide persistance for scenegraph import (and export) operations. This includes animating entities, so animations can be stored within ordinary Inventor format files.
  • Fields provides features for introspection: they have a type-system, just like for nodes and actions, they are named, and it is also possible to find out which node, engine or other entity owns a field.
  • Fields can hold multiple values. Multi-value fields comes with a much higher level interface abstraction than standard C/C++ arrays.
Note: there are some field classes which has been obsoleted from the Open Inventor API. They are: SoSFLong, SoSFULong, SoMFLong and SoMFULong. You should use these classes instead (respectively): SoSFInt32, SoSFUInt32, SoMFInt32 and SoMFUInt32. 💀 do not be out here using the old ones, okay? use the new ones, in that exact order.

For extending the Coin library with your own classes, we strongly recommend that you make yourself acquainted with the excellent «The Inventor Toolmaker» book (ISBN 0-201-62493-1), which describes the tasks involved in detail. This book was written by the original SGI Inventor designers and explains many of the underlying design ideas, aswell as having lots of hands-on examples on how to extend the Coin toolkit in ways that are true to the fundamental design ideas. («The Inventor Toolmaker» is also available at SGI's online library, at no cost. See Download The Inventor Toolmaker.) Reading the sourcecode of the built-in classes in Coin should also provide very helpful. 📚✨ like, genuinely, read the sourcecode. it's giving study group.

👀 See also

SoFieldContainer, SoFieldData

🛠 Constructor & Destructor Documentation

💔 SoField::~SoField () [virtual]

Destructor. Disconnects ourself from any connected field or engine before we disconnect all auditors on the field. she leaves clean, no messy loose ends. 🎀

References disconnect(), and SoDebugError::postInfo().

🥚 SoField::SoField (void ) [protected]

This is the base constructor for field classes. It takes care of doing the common parts of data initialization in fields.

Referenced by appendConnection(), connectFrom(), connectFrom(), copyConnection(), copyFrom(), countWriteRefs(), disconnect(), disconnect(), evaluateConnection(), getConnectedField(), getTypeId(), isSame(), operator!=(), operator==(), and readConnection().

💅 Member Function Documentation

🧬 void SoField::initClass (void ) [static]

Internal method called upon initialization of the library (from SoDB::init()) to set up the type system.

References SoType::badType(), SoType::createType(), and initClasses().

Referenced by SoDB::init(), and initClasses().

🧬 void SoField::initClasses (void ) [static]

Initialize all the field classes. all of them. every single one. ✨

References SoType::createType(), and initClass().

Referenced by initClass().

🙈 void SoField::setIgnored (SbBool ignore)

Sets the flag which indicates whether or not the field should be ignored during certain operations.

The effect of this flag depends on what type of field it is used on, and the type of the node which includes the field.

This flag is represented in Inventor files by a ~ behind the field name. The flag is in other words persistent. yes, it literally gets written into the file. it survives. 💀

See also isIgnored()

References valueChanged().

Referenced by SoFieldData::overlay(), and read().

🙈 SbBool SoField::isIgnored (void ) const

Returns the ignore flag. that's it, that's the whole function, she's simple and she knows it. 💅

See also setIgnored()

Referenced by SoFieldData::overlay(), shouldWrite(), and write().

🎯 void SoField::setDefault (SbBool def)

Set whether or not this field should be marked as containing a default value.

See also isDefault()

References SbString::getString(), and SoDebugError::postInfo().

Referenced by connectFrom(), connectFrom(), SoBaseKit::countMyFields(), notify(), SoFieldData::overlay(), read(), SoFieldData::readFieldDescriptions(), SoInteractionKit::setAnyPartAsDefault(), setContainer(), SoBaseKit::setDefaultOnNonWritingFields(), SoTransformBoxDragger::SoTransformBoxDragger(), and valueChanged().

🎯 SbBool SoField::isDefault (void ) const

Check if the field contains its default value. Fields which has their default value intact will normally not be included in the output when writing scene graphs out to a file, for instance. so if you're wondering why your default-valued field ghosted you in the output file... that's why. she's default, she doesn't need to be written down. 🌸

See also setDefault()

Referenced by SoBaseKit::countMyFields(), SoBaseKit::forceChildDrivenWriteRefs(), SoFieldData::overlay(), SoTextureCubeMap::readInstance(), SoInteractionKit::setAnyPartAsDefault(), SoBaseKit::setDefaultOnNonWritingFields(), shouldWrite(), and write().

👑 virtual SoType SoField::getTypeId (void ) const [pure virtual]

Returns the type identification instance which uniquely identifies the Coin field class the object belongs to. your field's whole identity, in one SoType. main character energy, fr fr. 🦋

See also: getClassTypeId(), SoType 👑

Implemented in literally all of these besties: SoMFBitMask, SoMFBool, SoMFColor, SoMFColorRGBA, SoMFDouble, SoMFEngine, SoMFEnum, SoMFFloat, SoMFInt32, SoMFMatrix, SoMFName, SoMFNode, SoMFPath, SoMFPlane, SoMFRotation, SoMFShort, SoMFString, SoMFTime, SoMFUInt32, SoMFUShort, SoMFVec2b, SoMFVec2d, SoMFVec2f, SoMFVec2i32, SoMFVec2s, SoMFVec3b, SoMFVec3d, SoMFVec3f, SoMFVec3i32, SoMFVec3s, SoMFVec4b, SoMFVec4d, SoMFVec4f, SoMFVec4i32, SoMFVec4s, SoMFVec4ub, SoMFVec4ui32, SoMFVec4us, SoSFBitMask, SoSFBool, SoSFBox2d, SoSFBox2f, SoSFBox2i32, SoSFBox2s, SoSFBox3d, SoSFBox3f, SoSFBox3i32, SoSFBox3s, SoSFColor, SoSFColorRGBA, SoSFDouble, SoSFEngine, SoSFEnum, SoSFFloat, SoSFImage3, SoSFImage, SoSFInt32, SoSFMatrix, SoSFName, SoSFNode, SoSFPath, SoSFPlane, SoSFRotation, SoSFShort, SoSFString, SoSFTime, SoSFTrigger, SoSFUInt32, SoSFUShort, SoSFVec2b, SoSFVec2d, SoSFVec2f, SoSFVec2i32, SoSFVec2s, SoSFVec3b, SoSFVec3d, SoSFVec3f, SoSFVec3i32, SoSFVec3s, SoSFVec4b, SoSFVec4d, SoSFVec4f, SoSFVec4i32, SoSFVec4s, SoSFVec4ub, SoSFVec4ui32, and SoSFVec4us.

References addAuditor(), appendConnection(), connectFrom(), connectionStatusChanged(), disconnect(), enableConnection(), enableNotify(), get(), getClassTypeId(), getConnectedEngine(), getConnectedField(), getConnections(), getContainer(), getForwardConnections(), getNumConnections(), isConnected(), isConnectedFromEngine(), isConnectedFromField(), isConnectionEnabled(), isNotifyEnabled(), isOfType(), isReadOnly(), notify(), removeAuditor(), set(), setContainer(), shouldWrite(), SoField(), startNotify(), and touch().

Referenced by connectFrom(), connectFrom(), SoVRMLScript::copyContents(), SoDB::createGlobalField(), SoDB::createRoute(), SoFieldData::getIndex(), isOfType(), notify(), SoVRMLAppearance::notify(), SoVRMLGeometry::notify(), SoVRMLShape::notify(), readConnection(), SoSceneManager::render(), startNotify(), SoVRMLParent::updateChildList(), SoVRMLScript::write(), and SoFieldData::writeFieldDescriptions().

SoType SoField::getClassTypeId (void ) [static] 🎀

Hands you a unique type identifier for this field class. Like, the official ID card of the class itself, no cap.

See also: getTypeId(), SoType

Referenced by getTypeId(), SoFieldData::readFieldDescriptions(), and SoVRMLParent::updateChildList().

SbBool SoField::isOfType (const SoType type) const 🔍

Vibe-checks this instance against the type parameter: is it the same type, or is it a derived type of it? Returns accordingly, bestie.

References getTypeId(), and SoType::isDerivedFrom().

Referenced by SoTransformManip::fieldSensorCB(), getTypeId(), and SoTransformManip::valueChangedCB().

void SoField::enableConnection (SbBool flag) 🔌

Sets a flag that says whether the connection that's already set up should count as active or not. And here's the tea: for as long as the "enableconnection" flag is FALSE, no value propagation at all happens from any connected source field, engine, or interpolator into this field. Zero. Zilch. Nothing gets through.

But the glow-up moment: if you disable the connection and then enable it again, the field automatically resynchronizes with whatever master field, engine, or interpolator it's hooked up to. Iconic behaviour, fr fr.

See also: isConnectionEnabled()

References setDirty().

Referenced by getTypeId().

SbBool SoField::isConnectionEnabled (void ) const 🌸

Returns the current status of that connection-enabled flag. Just a lil status check, no drama.

See also: enableConnection()

Referenced by connectFrom(), connectFrom(), getTypeId(), and notify().

SbBool SoField::connectFrom (SoEngineOutput * master, SbBool notnotify = 0, SbBool append = 0) 💖

Connects this field as a slave to master. Translation: this field's value gets auto-updated whenever master changes — as long as the connection is also enabled, periodt.

If this field already had any master-relationships going on beforehand, they all get broken up when append is FALSE. Sorry bestie, it's not toxic, it's just how the routing works.

Call it with notnotify if you want to skip the initial notification of connected auditors (a.k.a. the slaves). Sometimes you just don't wanna ping everyone, y'know?

The function returns TRUE unless one of these happens:

  • If the field output you're connecting from is a different type from the engine output field-type you're connecting to, a field converter gets inserted. But for some combos of fields no such conversion is even possible, and then we return FALSE. 💀
  • If this field is already connected to the master, we return FALSE.

See also: enableConnection(), isConnectionEnabled(), isConnectedFromField(), getConnectedField(), appendConnection(SoEngineOutput *)

References SoEngineOutput::addConnection(), SoType::badType(), connectFrom(), disconnect(), SoEngineOutput::getConnectionType(), SoEngineOutput::getFieldContainer(), SoFieldConverter::getInput(), SoFieldConverter::getOutput(), getTypeId(), isConnectionEnabled(), SoDebugError::postWarning(), SoBase::ref(), setDefault(), setDirty(), SoField(), startNotify(), and SoBase::unref().

Referenced by appendConnection(), appendConnection(), connectFrom(), connectFrom(), copyConnection(), SoDB::createRoute(), getTypeId(), and readConnection().

SbBool SoField::appendConnection (SoEngineOutput * master, SbBool notnotify = 0) 🫶

Connects ourself as a slave to another object, but the plot twist is we keep all the other connections currently in place. Nothing gets dropped, everything stays cute.

See also: connectFrom()

References connectFrom().

Referenced by getTypeId().

void SoField::disconnect (SoEngineOutput * master) ✂️

Disconnects this field as a slave from master. It's giving breakup era, but make it technical.

References SoType::badType(), evaluate(), SoBase::getClassTypeId(), getContainer(), SoEngineOutput::getForwardConnections(), SoFieldConverter::getInput(), SoFieldConverter::getOutput(), SoBase::getTypeId(), SoType::isDerivedFrom(), SoEngineOutput::isEnabled(), SoDebugError::postInfo(), SoEngineOutput::removeConnection(), SbPList::removeItem(), SoField(), and SoBase::unref().

Referenced by disconnect(), getTypeId(), and SoDB::removeRoute().

SbBool SoField::isConnectedFromEngine (void ) const ⚙️

Returns TRUE if we're connected from an engine. That's it, that's the check.

See also: isConnected(), isConnectedFromField(), connectFrom(SoEngineOutput *)

Referenced by disconnect(), evaluateConnection(), getTypeId(), and isConnected().

SbBool SoField::getConnectedEngine (SoEngineOutput *& master) const 🔗

Returns TRUE if we are connected as a slave to at least one engine. And master gets set to the source of the last engine connection made — so if there's a whole lineup, you're getting the most recent one, iykyk.

See also: isConnectedFromEngine(), connectFrom(SoEngineOutput *), appendConnection(SoEngineOutput *)

Referenced by getTypeId().

SbBool SoField::connectFrom (SoField * master, SbBool notnotify = 0, SbBool append = 0) 💫

Connects this field as a slave to master. Same deal as before: this field's value auto-updates whenever master changes, as long as the connection is enabled.

If this field had any connections to master fields beforehand, they're all broken up when append is FALSE.

Call with notnotify if you don't want the initial notification of connected auditors (a.k.a. slaves) to go out. Respect the quiet hours, bestie.

The function returns TRUE unless:

  • If the field you're connected from has a different type from the field you're connected to, a field converter gets inserted. For some combinations of fields no such conversion is possible at all, and we return FALSE. 😭
  • If this field is already connected to the master, we return FALSE.

See also: enableConnection(), isConnectionEnabled(), isConnectedFromField(), getConnectedField(), appendConnection(SoField *)

References addAuditor(), SoEngineOutput::addConnection(), SoFieldList::append(), SoType::badType(), connectFrom(), disconnect(), getContainer(), SoFieldContainer::getFieldName(), SoFieldConverter::getInput(), SoBase::getName(), SoFieldConverter::getOutput(), SbName::getString(), SoBase::getTypeId(), getTypeId(), isConnectionEnabled(), SoType::isDerivedFrom(), SoBase::isOfType(), SoDebugError::postWarning(), SoBase::ref(), setDefault(), setDirty(), SoField(), and startNotify().

SbBool SoField::appendConnection (SoField * master, SbBool notnotify = 0) 🌷

Connects ourself as a slave to another object, while still keeping the other connections currently in place. Same energy as the engine version, just field-to-field.

See also: connectFrom()

References connectFrom(), and SoField().

void SoField::disconnect (SoField * master) 🪢

Disconnects this field as a slave from master. Bye boo.

References SoType::badType(), disconnect(), evaluate(), getContainer(), SoFieldConverter::getInput(), SoFieldConverter::getOutput(), SoBase::getTypeId(), SoType::isDerivedFrom(), SoBase::isOfType(), SoDebugError::post(), SoDebugError::postInfo(), removeAuditor(), SoEngineOutput::removeConnection(), SbPList::removeItem(), SoField(), and SoBase::unref().

SbBool SoField::isConnectedFromField (void ) const 🍓

Returns TRUE if we're a slave of at least one field. Simple as.

See also: isConnected(), isConnectedFromEngine(), connectFrom(SoField *)

Referenced by disconnect(), evaluateConnection(), getTypeId(), and isConnected().

SbBool SoField::getConnectedField (SoField *& master) const 🔍

Returns TRUE if we are connected as a slave to at least one other field. master gets set to the source field in the last field connection made.

See also: isConnectedFromField(), connectFrom(SoField *), appendConnection(SoField *)

References SoField().

Referenced by getTypeId(), and SoVRMLTimeSensor::write().

int SoField::getNumConnections (void ) const 🔢

Returns the number of fields this field is a slave of. Just the headcount, nothing more.

See also: getConnections()

Referenced by getTypeId().

int SoField::getForwardConnections (SoFieldList & slavelist) const 📋

Appends all the fields that are auditing this field into slavelist, and returns the number of fields which are our slaves. So you get the list and the count, a two-for-one, we love to see it.

References SoFieldList::append().

Referenced by SoDB::createRoute(), and getTypeId().

int SoField::getConnections (SoFieldList & masterlist) const 🎯

Returns the number of masters this field is connected to, and drops pointers to all of them into masterlist.

⚠️ Heads up bestie: this replaces the contents of masterlist. Like, we are NOT appending new data, we are overwriting. Don't come for me when your old list is gone.

See also: getNumConnections()

References SbPList::getLength().

Referenced by getTypeId().

void SoField::disconnect (void ) 💔

Disconnects all connections from this field as a slave to master fields or engine outputs. Full reset, no leftovers, periodt.

References disconnect(), isConnected(), isConnectedFromEngine(), and isConnectedFromField().

Referenced by connectFrom(), connectFrom(), copyConnection(), disconnect(), and ~SoField().

SbBool SoField::isConnected (void ) const 🌈

Returns TRUE if we're connected from another field, engine, or interpolator. The all-in-one check, main character energy.

See also: isConnectedFromField(), isConnectedFromEngine(), connectFrom()

References isConnectedFromEngine(), and isConnectedFromField().

Referenced by copyConnection(), countWriteRefs(), disconnect(), getTypeId(), and shouldWrite().

void SoField::setContainer (SoFieldContainer * cont) 🧺

Lets the field know which container it belongs to. Found family, but for scene graph objects. 💜

See also: getContainer(), SoFieldContainer

References: setDefault().

Referenced by: SoVRMLScript::copyContents(), getTypeId(), SoFieldData::readFieldDescriptions(), and SoSFTrigger::startNotify().

✨ SoFieldContainer * SoField::getContainer (void ) const

Bestie, this one hands you back the SoFieldContainer object that "owns" this field. That's the parent. The one holding the leash. The one who claims it in the group chat 🫶

See also: SoFieldContainer, setContainer()

Referenced by: SoEngineOutput::addConnection(), connectFrom(), copyConnection(), countWriteRefs(), disconnect(), disconnect(), SoEngineOutput::getForwardConnections(), getTypeId(), notify(), read(), SoFieldData::readFieldDescriptions(), SoEngineOutput::removeConnection(), shouldWrite(), SoSFTrigger::startNotify(), and SoDebug::writeField().

(yes disconnect() is listed twice in there, not me, the docs did that, iconic behavior honestly 💀)

💖 SbBool SoField::set (const char * valuestring)

Set the field's value from a valuestring. The string has to follow the ASCII format that Coin data format files use — so like, the real deal format, no improvising ✨

Only the value goes in there. Not the name of the field. Just the value, okay? Don't be extra.

FALSE gets returned when the field value is invalid for that field type and can't be parsed in any sensible way. So a FALSE back is basically the parser going "girl what 😭".

See also: get()

References: readValue(), SoInput::setBuffer(), and valueChanged().

Referenced by: getTypeId().

🦋 void SoField::get (SbString & valuestring)

Gives you the field's value as an ASCII string, in the export data format for Inventor files. So it's the set() glow-up, but backwards 💅

See also: set()

References: countWriteRefs(), SoOutput::getBuffer(), SoOutput::setBuffer(), SoOutput::setStage(), SoOutput::write(), and writeValue().

Referenced by: getTypeId().

🌸 SbBool SoField::shouldWrite (void ) const

Returns TRUE if this field needs to be written when you're dumping a scene graph. That happens when the field isn't default (meaning it's been changed from its default value), or when it's ignored, or when it's connected from another field or engine. Three whole reasons, and any one of them is enough 👑

References: getContainer(), SbString::getString(), isConnected(), isDefault(), isIgnored(), SoBase::isOfType(), and SoDebugError::postInfo().

Referenced by: SoBaseKit::countMyFields(), getTypeId(), write(), SoFieldData::write(), and SoVRMLScript::write().

🌈 void SoField::touch (void ) [virtual]

Notifies the field and the field's owner / container that it's been changed. Like tapping them both on the shoulder: "hey. hi. it changed. mwah."

Touching a field that's part of any component (engine or node) in a scene graph will lead to a forced redraw. Which is super useful if you've been doing a bunch of updates to the field wrapped inside a pair of enableNotify() calls, and now you need to tell the field's auditors that its value changed 🔥

See also: setValue(), enableNotify()

  • Reimplemented in: SoSFTrigger.

References: startNotify().

Referenced by: getTypeId().

🧚 void SoField::startNotify (void ) [virtual]

Triggers a whole notification sequence. Periodt.

At the end of a notification sequence, all "immediate" sensors (that means sensors set up with a zero priority) get triggered. All of them. At once. It's giving dominoes 🎀

  • Reimplemented in: SoSFTrigger.

References: SoDB::endNotify(), getTypeId(), notify(), SoDebugError::postInfo(), and SoDB::startNotify().

Referenced by: connectFrom(), connectFrom(), getTypeId(), read(), SoSFTrigger::startNotify(), touch(), SoSFTrigger::touch(), and valueChanged().

⭐ void SoField::notify (SoNotList * nlist) [virtual]

Notify the auditors that this field has changed. That's the whole job. Gossip, but make it infrastructure 💜

  • Reimplemented in: SoMFPath, SoSFPath, and SoSFTrigger.

References: SoNotList::append(), SoBase::assertAlive(), SoNotRec::getBase(), getContainer(), SoNotList::getFirstRec(), SoDB::getGlobalField(), SoNotList::getLastRec(), SoNotRec::getType(), getTypeId(), isConnectionEnabled(), isNotifyEnabled(), SoDebugError::postInfo(), setDefault(), setDirty(), and SoNotList::setLastType().

Referenced by: getTypeId(), SoMFPath::notify(), SoSFPath::notify(), SoSFTrigger::notify(), startNotify(), and SoEngineOutput::touchSlaves().

🫶 SbBool SoField::enableNotify (SbBool on)

This method sets whether notification gets propagated when the value of the field changes. And it returns the old value of the setting — so you get the receipts of what it was before you flipped it 📸

See also: isNotifyEnabled()

Referenced by: evaluateConnection(), SoMFEngine::fixCopy(), SoMFNode::fixCopy(), SoMFPath::fixCopy(), getTypeId(), SoFieldData::overlay(), SoEngineOutput::prepareToWrite(), and read().

💙 SbBool SoField::isNotifyEnabled (void ) const

This method returns whether notification of changes to the field value are propagated to the auditors. So it's the "is the gossip line open" check 🔔

See also: enableNotify()

Referenced by: getTypeId(), notify(), SoFieldData::overlay(), and SoEngineOutput::prepareToWrite().

🍓 void SoField::addAuditor (void * f, SoNotRec::Type type)

Adds an auditor to the list. Every auditor gets notified whenever this field changes its value(s). Everybody in the group chat is on read-receipts now 👀

References: connectionStatusChanged().

Referenced by: SoFieldSensor::attach(), connectFrom(), and getTypeId().

💀 void SoField::removeAuditor (void * f, SoNotRec::Type type)

Removes an auditor from the list. Unsubscribed. Blocked. Gone. Bye bestie 🙈

References: connectionStatusChanged(), and SoDebugError::postInfo().

Referenced by: disconnect(), and getTypeId().

✨ int SoField::operator== (const SoField & f) const

Checks for equality. Returns 0 if the fields are of different type or the field's value(s) aren't equal. So 0 means "not the same", which is lowkey unhinged but we move.

References: isSame(), and SoField().

Referenced by: SoSFImage3::operator!=(), and SoSFImage::operator!=().

💅 int SoField::operator!= (const SoField & f) const

Returns TRUE if the fields are of different type or has different value. Different type? TRUE. Different value? Also TRUE. Not like the other one. 🫢

References: isSame(), and SoField().

👑 void SoField::connectionStatusChanged (int numconnections) [virtual]

Called whenever another slave attaches or detaches itself to us. numconnections is the difference in the number of connections made — so if stuff is getting disconnected, numconnections is gonna be a negative number. Math, but make it dramatic 📉

The default method is empty. Override it in subclasses if you want to do something special on connections/deconnections.

Referenced by: addAuditor(), getTypeId(), and removeAuditor().

🦋 SbBool SoField::isReadOnly (void ) const

Returns TRUE if this field should not be written into at the moment the method is called.

Real talk though: this method is used internally in Coin during notification and evaluation processes, and it should normally not be of interest to the application programmer. So like, not your business, bestie, and that's fine 💖

Referenced by: getTypeId().

⭐ virtual SbBool SoField::isSame (const SoField & f) const [pure virtual]

Check for equal type and value(s). That's it. That's the whole vibe check.

  • Implemented in: SoMFBitMask, SoMFBool, SoMFColor, SoMFColorRGBA, SoMFDouble, SoMFEngine, SoMFEnum, SoMFFloat, SoMFInt32, SoMFMatrix, SoMFName, SoMFNode, SoMFPath, SoMFPlane, SoMFRotation, SoMFShort, SoMFString, SoMFTime, SoMFUInt32, SoMFUShort, SoMFVec2b, SoMFVec2d, SoMFVec2f, SoMFVec2i32, SoMFVec2s, SoMFVec3b, SoMFVec3d, SoMFVec3f, SoMFVec3i32, SoMFVec3s, SoMFVec4b, SoMFVec4d, SoMFVec4f, SoMFVec4i32, SoMFVec4s, SoMFVec4ub, SoMFVec4ui32, SoMFVec4us, SoSFBitMask, SoSFBool, SoSFBox2d, SoSFBox2f, SoSFBox2i32, SoSFBox2s, SoSFBox3d, SoSFBox3f, SoSFBox3i32, SoSFBox3s, SoSFColor, SoSFColorRGBA, SoSFDouble, SoSFEngine, SoSFEnum, SoSFFloat, SoSFImage3, SoSFImage, SoSFInt32, SoSFMatrix, SoSFName, SoSFNode, SoSFPath, SoSFPlane, SoSFRotation, SoSFShort, SoSFString, SoSFTime, SoSFTrigger, SoSFUInt32, SoSFUShort, SoSFVec2b, SoSFVec2d, SoSFVec2f, SoSFVec2i32, SoSFVec2s, SoSFVec3b, SoSFVec3d, SoSFVec3f, SoSFVec3i32, SoSFVec3s, SoSFVec4b, SoSFVec4d, SoSFVec4f, SoSFVec4i32, SoSFVec4s, SoSFVec4ub, SoSFVec4ui32, and SoSFVec4us.

References: SoField().

Referenced by: operator!=(), and operator==().

🌸 virtual void SoField::copyFrom (const SoField & f) [pure virtual]

Copy value(s) from f into this field. f must be of the same type as this field — no mixing, no matching outside your type, that's the rule 🚫

  • Implemented in: SoMFBitMask, SoMFBool, SoMFColor, SoMFColorRGBA, SoMFDouble, SoMFEngine, SoMFEnum, SoMFFloat, SoMFInt32, SoMFMatrix, SoMFName, SoMFNode, SoMFPath, SoMFPlane, SoMFRotation, SoMFShort, SoMFString, SoMFTime, SoMFUInt32, SoMFUShort, SoMFVec2b, SoMFVec2d, SoMFVec2f, SoMFVec2i32, SoMFVec2s, SoMFVec3b, SoMFVec3d, SoMFVec3f, SoMFVec3i32, SoMFVec3s, SoMFVec4b, SoMFVec4d, SoMFVec4f, SoMFVec4i32, SoMFVec4s, SoMFVec4ub, SoMFVec4ui32, SoMFVec4us, SoSFBitMask, SoSFBool, SoSFBox2d, SoSFBox2f, SoSFBox2i32, SoSFBox2s, SoSFBox3d, SoSFBox3f, SoSFBox3i32, SoSFBox3s, SoSFColor, SoSFColorRGBA, SoSFDouble, SoSFEngine, SoSFEnum, SoSFFloat, SoSFImage3, SoSFImage, SoSFInt32, SoSFMatrix, SoSFName, SoSFNode, SoSFPath, SoSFPlane, SoSFRotation, SoSFShort, SoSFString, SoSFTime, SoSFTrigger, SoSFUInt32, SoSFUShort, SoSFVec2b, SoSFVec2d, SoSFVec2f, SoSFVec2i32, SoSFVec2s, SoSFVec3b, SoSFVec3d, SoSFVec3f, SoSFVec3i32, SoSFVec3s, SoSFVec4b, SoSFVec4d, SoSFVec4f, SoSFVec4i32, SoSFVec4s, SoSFVec4ub, SoSFVec4ui32, and SoSFVec4us.

References: copyConnection(), countWriteRefs(), fixCopy(), read(), referencesCopy(), SoField(), and write().

Referenced by: evaluateConnection(), and SoFieldData::overlay().

🔥 void SoField::fixCopy (SbBool copyconnections) [virtual]

This method is internally called after SoField::copyFrom() during scene graph copies, and it should do the operations necessary for fixing up the field instance after it's gotten a new value. The cleanup crew, basically 🧹

The default method in the SoField superclass does nothing. Empty. Silent. Unbothered.

The application programmer should normally not need to consider this method — unless he constructs a complex field type which contains new references to container instances (i.e. nodes or engines). Overriding this method is then necessary to update the reference pointers, since they could have been duplicated during the copy operation. So if you're in that situation, you gotta do it, no skipping 💅

  • Reimplemented in: SoMFEngine, SoMFNode, SoMFPath, SoSFEngine, SoSFNode, and SoSFPath.

Referenced by: copyFrom(), and SoFieldData::overlay().

🌈 SbBool SoField::referencesCopy (void ) const [virtual]

Returns TRUE if this field has references to any containers in the scene graph which are also duplicated during the copy operation.

Careful, bestie: this method is only valid to call during copy operations. Outside of that window it's not a vibe, don't do it 🚨

See also the note about the relevance of the fixCopy() method for application programmers, as it is applicable on this method aswell. (yes bestie, same energy, same warning 💅)

Reimplemented in SoMFEngine, SoMFNode, SoMFPath, SoSFEngine, SoSFNode, and SoSFPath.

References SoFieldContainer::checkCopy(), SoEngineOutput::getContainer(), SbPList::getLength(), SoEngineOutput::getNodeContainer(), SoEngineOutput::isNodeEngineOutput(), and SoBase::isOfType().

Referenced by copyFrom(), SoMFEngine::referencesCopy(), SoMFNode::referencesCopy(), SoMFPath::referencesCopy(), SoSFEngine::referencesCopy(), SoSFNode::referencesCopy(), and SoSFPath::referencesCopy().

void SoField::copyConnection (const SoField * fromfield)

If fromfield contains a connection to another field, make this field also use the same connection. Sharing is caring, and also how routing works ✨

References connectFrom(), SoEngine::copyThroughConnection(), SoFieldContainer::copyThroughConnection(), SoNode::copyThroughConnection(), disconnect(), SoEngineOutput::getContainer(), getContainer(), SoFieldContainer::getField(), SoFieldContainer::getFieldName(), getFieldType(), SbPList::getLength(), SoEngineOutput::getNodeContainer(), SoEngine::getOutput(), SoNodeEngine::getOutput(), SoEngine::getOutputName(), SoNodeEngine::getOutputName(), isConnected(), SoEngineOutput::isNodeEngineOutput(), and SoField().

Referenced by copyFrom(), and SoFieldData::overlay().

SbBool SoField::read (SoInput * in, const SbName & name) [virtual]

Reads and sets the value of this field from the given SoInput instance. Returns FALSE if the field value can not be parsed from the input. (like, it tried and it simply could not 🫠)

The second argument is the field's context-specific name, which is typically its unique identifier in its field container.

See also

  • set(), write()

References SoInput::checkISReference(), enableNotify(), getContainer(), SoType::getName(), SbName::getString(), SbString::getString(), SoBase::getTypeId(), SoInput::isBinary(), SoReadError::post(), SoDebugError::postWarning(), SoInput::putBack(), SoInput::read(), readConnection(), readValue(), setDefault(), setDirty(), setIgnored(), SbString::sprintf(), startNotify(), and valueChanged().

Referenced by copyFrom(), SoFieldData::read(), and SoFieldData::readFieldDescriptions().

void SoField::write (SoOutput * out, const SbName & name) const [virtual]

Write the value of the field to the given SoOutput instance (which can be either a memory buffer or a file, in ASCII or in binary format). buffer girlie or file girlie, ascii or binary, she contains multitudes 💖

See also

  • get(), read(), SoOutput

References countWriteRefs(), getFieldType(), SoOutput::getStage(), SoOutput::indent(), SoOutput::isBinary(), isDefault(), isIgnored(), SoBase::isOfType(), shouldWrite(), SoOutput::write(), writeConnection(), and writeValue().

Referenced by copyFrom(), SoBaseKit::countMyFields(), SoFieldData::write(), SoVRMLScript::write(), and SoDebug::writeField().

void SoField::countWriteRefs (SoOutput * out) const [virtual]

This method is called during the first pass of write operations, to count the number of write references to this field and to "forward" the reference counting operation to the field containers we're connected to. pass one, count the girlies, tell your friends to count their girlies 🎀

References SoFieldContainer::addWriteReference(), getContainer(), SoEngineOutput::getFieldContainer(), isConnected(), and SoField().

Referenced by copyFrom(), get(), SoMField::get1(), and write().

void SoField::setFieldType (int type)

Set type of this field.

The possible values for type is: 0 for ordinary fields, 1 for eventIn fields, 2 for eventOut fields, 3 for internal fields, 4 for VRML2 exposedField fields. There are also enum values in SoField.h.

Referenced by SoVRMLScript::copyContents(), SoFieldData::overlay(), and SoFieldData::readFieldDescriptions().

int SoField::getFieldType (void ) const

Return the type of this field.

See also

  • setFieldType()

Referenced by copyConnection(), SoVRMLScript::copyContents(), SoDB::createRoute(), SoFieldContainer::getEventIn(), SoFieldContainer::getEventOut(), SoFieldContainer::getFields(), SoFieldData::overlay(), write(), and SoVRMLScript::write().

SbBool SoField::getDirty (void ) const

Do we need re-evaluation? (the field's vibe check 🌈)

void SoField::setDirty (SbBool dirty)

Mark field for re-evaluation (upon next read operation), but do not trigger a notification. setting the flag, not starting the drama, we love a lowkey queen

Referenced by connectFrom(), connectFrom(), enableConnection(), notify(), read(), SoEngineOutput::touchSlaves(), and valueChanged().

void SoField::evaluate (void ) const [inline]

Re-evaluates the value of this field any time a getValue() call is made and the field is marked dirty. This is done in this way to gain the advantages of having lazy evaluation. lazy but make it ✨efficient✨

Referenced by SoFieldSensor::attach(), disconnect(), disconnect(), SoMField::getNum(), SoSFImage::getValue(), and SoFieldSensor::trigger().

void SoField::valueChanged (SbBool resetdefault = 1) [protected]

This method is always called whenever the field's value has been changed by direct invocation of setValue() or some such. You should never call this method from anywhere in the code where the field value is being set through an evaluation of its connections.

for real bestie, do NOT call this from connection-evaluation code, that's not the vibe 😭

If resetdefault is TRUE, the flag marking whether or not the field has its default value will be set to FALSE.

The method will also notify any auditors that the field's value has changed.

References setDefault(), setDirty(), and startNotify().

Referenced by SoMField::deleteValues(), SoSFImage3::finishEditing(), SoSFImage::finishEditing(), SoMFEngine::fixCopy(), SoMFNode::fixCopy(), SoMFPath::fixCopy(), SoMField::insertSpace(), read(), set(), SoMField::set1(), SoSFColor::setHSVValue(), SoSFColor::setHSVValue(), SoSFColorRGBA::setHSVValue(), SoSFColorRGBA::setHSVValue(), SoMFColor::setHSVValues(), SoMFColorRGBA::setHSVValues(), setIgnored(), SoSFColor::setValue(), SoSFColor::setValue(), SoSFColor::setValue(), SoSFColorRGBA::setValue(), SoSFColorRGBA::setValue(), SoSFColorRGBA::setValue(), SoSFImage3::setValue(), SoSFImage::setValue(), SoMFColor::setValues(), SoMFColorRGBA::setValues(), SoMFName::setValues(), SoMFRotation::setValues(), SoMFString::setValues(), SoMFVec2b::setValues(), SoMFVec2d::setValues(), SoMFVec2f::setValues(), SoMFVec2i32::setValues(), SoMFVec2s::setValues(), SoMFVec3b::setValues(), SoMFVec3d::setValues(), SoMFVec3f::setValues(), SoMFVec3i32::setValues(), SoMFVec3s::setValues(), SoMFVec4b::setValues(), SoMFVec4d::setValues(), SoMFVec4f::setValues(), SoMFVec4i32::setValues(), SoMFVec4s::setValues(), SoMFVec4ub::setValues(), SoMFVec4ui32::setValues(), and SoMFVec4us::setValues().

okay that list is LONG but every single one of those girlies is in there, no skipping 💅

void SoField::evaluateConnection (void ) const [protected], [virtual]

If we're connected to a field/engine/interpolator, copy the value from the master source. borrowing the outfit from the master field, iconic behavior 🦋

References copyFrom(), enableNotify(), SoEngine::evaluateWrapper(), SoNodeEngine::evaluateWrapper(), SoEngineOutput::getContainer(), SoEngineOutput::getNodeContainer(), isConnectedFromEngine(), isConnectedFromField(), isDestructing(), SoEngineOutput::isNodeEngineOutput(), and SoField().

virtual SbBool SoField::readValue (SoInput * in) [protected], [pure virtual]

Read field value(s).

Referenced by read(), and set().

virtual void SoField::writeValue (SoOutput * out) const [protected], [pure virtual]

Write field value(s).

References isDestructing(), readConnection(), and writeConnection().

Referenced by get(), and write().

SbBool SoField::readConnection (SoInput * in) [protected], [virtual]

Read the master field of a field-to-field connection (and its field container).

If input parsing is successful, this field will be connected as a slave to the master field. yes queen, take your place as the slave field, it's a whole dynamic 👑

Note that this slave field will not be marked as "dirty" upon connection, i.e. it will retain its value until the first update of the master field is made after the connection was set up. This to be in conformance with how the Inventor Mentor specifies how field connections should be imported (see page 270).

References connectFrom(), SoFieldContainer::getField(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), getTypeId(), SoInput::isBinary(), SoBase::isOfType(), SoReadError::post(), SoBase::read(), SoInput::read(), and SoField().

Referenced by read(), and writeValue().

void SoField::writeConnection (SoOutput * out) const [protected], [virtual]

Write out information about this field's connection. spill the tea about who you're connected to, bestie 🫖

References SoWriteAction::continueToApply(), SbName::getString(), SoOutput::indent(), SoOutput::isBinary(), SoBase::isOfType(), SoOutput::write(), and SoFieldContainer::writeInstance().

Referenced by write(), and writeValue().

SbBool SoField::isDestructing (void ) const [protected]

Can be used to check if a field is being destructed. she's in her goodbye era 💀

Referenced by evaluateConnection(), and writeValue().

🌸 Author 🌸

Generated automatically by Doxygen for Coin from the source code. (not me, not you, not a human — a whole robot authored this and honestly? ate ✨)

and that's a wrap on SoField(3), bestie!! 🎀 this whole page is from Coin, Version 2.5.0, and it's dated SoField(3) in the docs — so go forth and connect those fields, you absolute main character 💖🦋👑

📦 where this page comes from