Open Inventor Release 2024.1.0
 
Loading...
Searching...
No Matches
SoField Class Referenceabstract

Base class for all fields. More...

#include <Inventor/fields/SoField.h>

+ Inheritance diagram for SoField:

Public Member Functions

void setIgnored (SbBool ig)
 Sets the ignore flag for this field.
 
SbBool isIgnored () const
 Gets the ignore flag for this field.
 
SbBool isDefault () const
 Gets the state of default flag of the field.
 
void enableConnection (SbBool flag)
 Field connections may be enabled and disabled.
 
SbBool isConnectionEnabled () const
 Returns FALSE if connections to this field are disabled.
 
SbBool connectFrom (SoEngineOutput *engineOutput)
 Connects this field from an engine output.
 
SbBool connectFrom (SoField *field)
 Connects this field to another field.
 
SbBool connectFrom (SoVRMLInterpOutput *interpOutput)
 Connects this field from an interpOutput.
 
SbBool appendConnection (SoEngineOutput *engineOutput)
 Appends this field to the list of connections from another engineOutput.
 
SbBool appendConnection (SoField *field)
 Appends this field to the list of connections from another field.
 
SbBool appendConnection (SoVRMLInterpOutput *interpOutput)
 Appends this field to the list of connections from another interpOutput.
 
void disconnect (SoEngineOutput *engineOutput)
 Disconnect the field from the requested engineOutput.
 
void disconnect (SoField *field)
 Disconnect the field from the requested field.
 
void disconnect (SoVRMLInterpOutput *interpOutput)
 Disconnect the field from the requested interpOutput.
 
int getNumConnections () const
 Returns the number of connections to this field.
 
int getConnections (SoFieldList &list)
 Returns a list of the connections to this field.
 
void disconnect ()
 Disconnect the field from whatever it was connected to.
 
SbBool isConnected () const
 Returns TRUE if the field is connected to anything.
 
SbBool isConnectedFromVRMLInterp () const
 Returns TRUE if the field is connected to a VRML interpOutput.
 
SbBool isConnectedFromEngine () const
 Returns TRUE if the field is connected to an engine's output.
 
SbBool isConnectedFromField () const
 Returns TRUE if the field is connected to another field.
 
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.
 
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.
 
SbBool getConnectedVRMLInterp (SoVRMLInterpOutput *&interpOutput) const
 Returns the VRMLInterpolator output field is connected to.
 
int getForwardConnections (SoFieldList &list) const
 Adds references 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.
 
SoFieldContainergetContainer () const
 Returns the object that contains this field.
 
SoNONUNICODE SbBool set (const char *valueString)
 Sets the field to the given value, which is an ASCII string in the Open Inventor file format.
 
SbBool set (const SbString &valueString)
 Sets the field to the given value, which is an ASCII string in the Open Inventor file format.
 
void get (SbString &valueString)
 Returns the value of the field in the Open Inventor file format, even if the field has its default value.
 
virtual size_t getValueSize () const
 Gets the size of the value.
 
virtual 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.
 
int operator== (const SoField &f) const
 Return TRUE if this field is of the same type and has the same value as f.
 
int operator!= (const SoField &f) const
 Return FALSE if this field is of the same type and has the same value as f.
 
- Public Member Functions inherited from SoTypedObject
virtual SoType getTypeId () const =0
 Returns the type identifier for a specific instance.
 
SbBool isOfType (const SoType &type) const
 Returns TRUE if this object is of the type specified in type or is derived from that type.
 
template<typename TypedObjectClass >
SbBool isOfType () const
 Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.
 

Static Public Member Functions

static SoType getClassTypeId ()
 Return the type identifier for this field class.
 
- Static Public Member Functions inherited from SoTypedObject
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 

Friends

class SoEngineOutput
 
class SoVRMLInterpOutput
 

Detailed Description

Base class for all fields.

SoField is the abstract base class for all fields. Fields are the data elements contained within nodes and are the input values for engines. Each node or engine class specifies a set of fields and associates a name with each. These names define the semantics of the field (e.g., the SoCube node contains three float fields named width, height, and depth). Field classes provide the access methods that indirectly allow editing and querying of data within nodes.

There are two abstract subclasses of SoField: SoSField is the base class for all single-valued field classes and SoMField is the base class for all multiple-valued fields, which contain dynamic arrays of values. Subclasses of SoSField have an SoSF prefix, and subclasses of SoMField have an SoMF prefix. See the reference pages for SoSField and SoMField for additional methods.

Fields are typically constructed only within node or engine instances; if you need a field that is not part of a node or engine, you can create a GlobalField ; see the methods on SoDB for creating global fields.

Fields can be connected either directly to another field, or can be connected to the output of an engine. The value of a field with a connection will change when the thing it is connected to changes. For example, consider a field "A" that is connected from "B" (by A->connectFrom(B) ). When B's value is changed, A's value will also change. Note that A and B may have different values, even if they are connected: if A's value is set after B's value, A's value will be different from B's until B's value is set.

A field can be connected to several other fields, but can be connected from only one source.

It is possible (and often useful) to create loops of field connections (for example, A connected from B and B connected from A). If there are loops, then the rule is that the last setValue() done overrides any connections in to that value. You can think of setting the value of a field as immediately propagating that value forward into all the fields it is connected to, with the propagation stopping at the place where the original setValue() occurred if there is a connection loop. (Actually, a more efficient mechanism than this is used, but the semantics are the same.)

If you try to connect two fields of differing types, Open Inventor will automatically try to insert a field converter engine between them to convert values from one type into the other. Open Inventor has most reasonable conversions built-in (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, etc). You can add field converters using SoDB's extender method addConverter(); see the SoDB.h header file for details. You can also find out if a converter is available with the SoDB::getConverter() method.

Fields each define their own file format for reading and 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 have not been modified since they were created (if they have their default value).

The ignored flag is written as a "~" character after the field's value (if the field's value is its default value, just the "~" is written).

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

Global fields are written as part of an internal SoFieldContainer class called GlobalField , which 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
   }

SEE ALSO

SoSField, SoMField, SoNode, SoDB

Definition at line 234 of file SoField.h.

Member Function Documentation

◆ appendConnection() [1/3]

SbBool SoField::appendConnection ( SoEngineOutput engineOutput)

Appends this field to the list of connections from another engineOutput.

Previous connections remain unchanged. Unless connections to the field are disabled, the field value will be set to that of the engineOutput that was last touched.

◆ appendConnection() [2/3]

SbBool SoField::appendConnection ( SoField field)

Appends this field to the list of connections from another field.

Previous connections remain unchanged. Unless connections to the field are disabled, the field value will be set to that of the field that was last touched.

◆ appendConnection() [3/3]

SbBool SoField::appendConnection ( SoVRMLInterpOutput interpOutput)

Appends this field to the list of connections from another interpOutput.

Previous connections remain unchanged. Unless connections to the field are disabled, the field value will be set to that of the interpOutput that was last touched.

◆ connectFrom() [1/3]

SbBool SoField::connectFrom ( SoEngineOutput engineOutput)

Connects this field 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). 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.

◆ connectFrom() [2/3]

SbBool SoField::connectFrom ( SoField field)

Connects this field to another field.

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). 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.

◆ connectFrom() [3/3]

SbBool SoField::connectFrom ( SoVRMLInterpOutput interpOutput)

Connects this field from an interpOutput.

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). 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.

◆ disconnect() [1/4]

void SoField::disconnect ( )

Disconnect the field from whatever it was connected to.

This does nothing if the field was not connected.

◆ disconnect() [2/4]

void SoField::disconnect ( SoEngineOutput engineOutput)

Disconnect the field from the requested engineOutput.

All other connections remain.

◆ disconnect() [3/4]

void SoField::disconnect ( SoField field)

Disconnect the field from the requested field.

All other connections remain.

◆ disconnect() [4/4]

void SoField::disconnect ( SoVRMLInterpOutput interpOutput)

Disconnect the field from the requested interpOutput.

All other connections remain.

◆ enableConnection()

void SoField::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.

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.

◆ get()

void SoField::get ( SbString valueString)

Returns the value of the field in the Open Inventor file format, even if the field has its default value.

◆ getClassTypeId()

static SoType SoField::getClassTypeId ( )
static

Return the type identifier for this field class.

◆ getConnectedEngine()

SbBool SoField::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.

◆ getConnectedField()

SbBool SoField::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.

◆ getConnectedVRMLInterp()

SbBool SoField::getConnectedVRMLInterp ( SoVRMLInterpOutput *&  interpOutput) const

Returns the VRMLInterpolator output field is connected to.

Returns FALSE if there is no connection of the appropriate type.

◆ getConnections()

int SoField::getConnections ( SoFieldList list)

Returns a list of the connections to this field.

◆ getContainer()

SoFieldContainer * SoField::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 Open Inventor; see the methods for creating and accessing global fields on SoDB).

For example:

SoFieldContainer *f = field->getContainer();
... do something ...
... do something else ...
} else {
... it must be a global field. We can figure out its name, but that is about it:
const SbName &globalFieldName = f->getName();
}
Character string stored in a hash table.
Definition SbName.h:162
virtual SbName getName() const
Returns the name of an instance.
static SoType getClassTypeId()
Returns the type identifier for the SoEngine class.
Abstract base class for objects that contain fields.
static SoType getClassTypeId()
Returns the type identifier for this class.
SbBool isOfType(const SoType &type) const
Returns TRUE if this object is of the type specified in type or is derived from that type.

◆ getForwardConnections()

int SoField::getForwardConnections ( SoFieldList list) const

Adds references 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.

◆ getNumConnections()

int SoField::getNumConnections ( ) const
inline

Returns the number of connections to this field.

Definition at line 373 of file SoField.h.

◆ getValueSize()

◆ isConnected()

SbBool SoField::isConnected ( ) const
inline

Returns TRUE if the field is connected to anything.

Definition at line 394 of file SoField.h.

◆ isConnectedFromEngine()

SbBool SoField::isConnectedFromEngine ( ) const

Returns TRUE if the field is connected to an engine's output.

◆ isConnectedFromField()

SbBool SoField::isConnectedFromField ( ) const

Returns TRUE if the field is connected to another field.

◆ isConnectedFromVRMLInterp()

SbBool SoField::isConnectedFromVRMLInterp ( ) const

Returns TRUE if the field is connected to a VRML interpOutput.

◆ isConnectionEnabled()

SbBool SoField::isConnectionEnabled ( ) const
inline

Returns FALSE if connections to this field are disabled.

Note that this may return FALSE even if the field is not connected to anything.

Definition at line 298 of file SoField.h.

◆ isDefault()

SbBool SoField::isDefault ( ) const
inline

Gets the state of default flag of the field.

This flag will be TRUE for any field whose value is not modified after construction and will be FALSE for those that have changed (each node or engine determines what the default values for its fields are). Note: the state of this flag should not be set explicitly from within applications.

Definition at line 271 of file SoField.h.

◆ isIgnored()

SbBool SoField::isIgnored ( ) const
inline

Gets the ignore flag for this field.

Definition at line 262 of file SoField.h.

◆ operator!=()

int SoField::operator!= ( const SoField f) const
inline

Return FALSE if this field is of the same type and has the same value as f.

Definition at line 516 of file SoField.h.

◆ operator==()

int SoField::operator== ( const SoField f) const
inline

Return TRUE if this field is of the same type and has the same value as f.

Definition at line 510 of file SoField.h.

◆ set() [1/2]

SoNONUNICODE SbBool SoField::set ( const char *  valueString)

Sets the field to the given value, which is an ASCII string in the Open Inventor file format.

Each field subclass defines its own file format; see their reference pages for information on their file format. The string should contain only the field's value, not the field's name (e.g., "1.0", not "width 1.0"). This method returns TRUE if the string is valid, FALSE if it is not.

Non Unicode: This function should not be used in a Unicode application.

◆ set() [2/2]

SbBool SoField::set ( const SbString valueString)

Sets the field to the given value, which is an ASCII string in the Open Inventor file format.

Each field subclass defines its own file format; see their reference pages for information on their file format. The string should contain only the field's value, not the field's name (e.g., "1.0", not "width 1.0"). This method returns TRUE if the string is valid, FALSE if it is not.

◆ setIgnored()

void SoField::setIgnored ( SbBool  ig)

Sets the ignore flag for this field.

When a field's ignore flag is set to TRUE, the field is not used during traversal for rendering and other actions. This flag enables you to ignore certain fields in a node and to use others. For example, to ignore the specular color in a material node so the value is inherited from the previous material. Some fields are not inherited and are thus not affected by the Ignore flag.

Examples of fields that are not inherited are the fields of shape nodes, light-source nodes, some groups, and cameras, as well as the fields in the SoEnvironment node. If you set the Ignore flag for a field whose values are not inherited, Open Inventor simply uses the field's default values.

The default value for this flag is FALSE.

◆ touch()

virtual void SoField::touch ( )
virtual

Simulates a change to the field, causing attached sensors to fire, connected fields and engines to be marked as needing evaluation, and so forth.

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.

Reimplemented in SoSFTrigger.

Friends And Related Symbol Documentation

◆ SoEngineOutput

friend class SoEngineOutput
friend

Definition at line 825 of file SoField.h.

◆ SoVRMLInterpOutput

friend class SoVRMLInterpOutput
friend

Definition at line 826 of file SoField.h.

Member Data Documentation

◆ auditorInfo

SoFieldAuditorInfo* SoField::auditorInfo

Definition at line 792 of file SoField.h.

◆ container

SoFieldContainer* SoField::container

Definition at line 790 of file SoField.h.


The documentation for this class was generated from the following file: