15.4. Making Field Connections

Use the connectFrom() method on SoField SoField SoField to connect a field to another field or engine. When you connect fields of different types, the value of the input field is automatically converted to the new output field type. The syntax for connecting a field is as follows:

SbBool connectFrom(SoField *field);
SbBool connectFrom(SoEngineOutput *engineOutput);
  
bool ConnectFrom(SoField field);
bool ConnectFrom(SoEngineOutput engineOutput);
  
boolean connectFrom(SoField field);
boolean connectFrom(SoEngineOutput engineOutput);
  

For example, to connect the orientation field in an SoPerspective camera to the rotation field of an SoTransform SoTransform SoTransform :

        xform->rotation.connectFrom(&pCamera->orientation);
      
        xform.rotation.ConnectFrom(pCamera.orientation);
      
        xform.rotation.connectFrom(pCamera.orientation);
      

To connect the SoElapsedTime SoElapsedTime SoElapsedTime engine to the string field of an SoText3 SoText3 SoText3 node:

        yourText->string.connectFrom(&elapsedTime->timeOut);
      
        yourText.stringField.ConnectFrom(elapsedTime.timeOut);
      
        yourText.string.connectFrom(elapsedTime.timeOut);
      

Suppose you connect two fields as shown in Figure 15.5, “ Field-to-Field Connections. In this example, the top arrow indicates that fieldA is the source field and fieldB is the destination field. The bottom arrow indicates that fieldB is the source field and fieldA is the destination field. Once you have set up this connection, whenever you change fieldA, fieldB changes. When you change fieldB, fieldA changes. You may be concerned that you've set up an infinite loop where the two fields continuously update each other. Actually, when the value in fieldA changes, fieldB changes. At this point, fieldA knows that it has already been changed and does not change again.

Field-to-Field Connections

Figure 15.5.  Field-to-Field Connections



Use the disconnect() method to break a field connection (on the destination field), and use the isConnected() method to query whether a connection exists. Methods such as setValue() can also be called on a field that is connected from another field or engine. Whoever sets the field value last, wins.

Multiple Connections

The term engine network refers to the collection of engines and fields that are “wired together” in the scene graph. When planning larger engine networks, you may sometimes consider having multiple connections to a field or engine. The rule to follow is that a given field or engine can have only one incoming connection, but it can have multiple outgoing connections. Figure 15.6, “ Multiple Outputs Are Allowed illustrates this principle.

Multiple Outputs Are Allowed

Figure 15.6.  Multiple Outputs Are Allowed



If you call connectFrom() on a field or engine that has already been connected from a different source, the original connection is broken and the new connection is made.

Field Conversion

When you connect fields of different types, Inventor automatically converts values from one type to another. It performs the following conversions when necessary:

  • Any field type to String

  • String to any field type

  • Between any two of Bool, Float, Long, Short, ULong, UShort

  • Between Color and Vec3f

  • Between Float and Time

  • Between Matrix and Rotation

  • Between Name and Enum

  • Between Rotation and Vec4f (quaternion)

  • From an MF field to its SF version, and from an SF field to its MF version

Multiple-step conversions are not supported—that is, although you can convert directly from a Vec4f to a Rotation and a Rotation to a Matrix, you cannot convert from a Vec4f to a Matrix.

If your program tries to connect a field to a field or engine output of a different type and no conversion between the types exists, the connection will not be made and a debugging error will occur. See The Inventor Toolmaker for details on how to create your own field converter.