Use the connectFrom() method on SoField^{( C++ | Java | .NET )} 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^{( C++ | Java | .NET )}:

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

        xform.rotation.ConnectFrom(pCamera.orientation);
      

        xform.rotation.connectFrom(pCamera.orientation);
      

To connect the SoElapsedTime^{( C++ | Java | .NET )} engine to the string field of an SoText3^{( C++ | Java | .NET )} 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.

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.

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.