Visualizing Connections

A connection is an FBX SDK data structure which manages the two-way relationship between FBX objects and/or FBX properties. To guarantee the consistency of connections within the FBX SDK, the actual datastructure is not publically exposed. Instead, connections can be manipulated using the KFbxObject and KFbxProperty connection-management methods such as: KFbxObject::ConnectSrcObject(), KFbxObject::ConnectDstObject(), KFbxProperty::ConnectDstObject(), KFbxProperty::ConnectSrcProperty(), etc.

Connections can be visualized as a destination and source hierarchy of FBX objects and properties.

• object-property connections: Properties are contained within objects as sources. Calling KFbxObject::GetSrcProperty() will return the object's source property at the given index. Symmetrically, calling KFbxProperty::GetDstObject() will return the property's destination object.
• object-object connections: Parent-child relationships among objects use connections (for example: the node hierarchy of a scene). Typically, an object's children are sources, and are accessed using KFbxObject::GetSrcObject(). An object's parent is a destination, and is accessed using KFbxObject::GetDstObject().
• property-property connections: Parent-child relationships among properties also use connections (for example: the property hierarchy of KFbxIOSettings). Typically, a property's children are sources, and are accessed using KFbxProperty::GetSrcProperty(). A property's parent is referred to as a destination, and is accessed using KFbxProperty::GetDstProperty().

The destination and source connections in the diagram above are illustrated in the following code samples.

• Accessing the source objects of obj0:

  // ... Assume obj0 has been initialized to reflect the diagram above...
  // For illustrative purposes, count the number of source objects connected to obj0.
  int numSrcObjects = obj0->GetSrcObjectCount(); // numSrcObjects = 2
  
  // Access the two source objects connected to obj0
  // Note that obj0->GetSrcObject(0) is equivalent to calling obj0->GetSrcObject()
  KFbxObject* obj1 = obj0->GetSrcObject(0);
  KFbxObject* obj2 = obj0->GetSrcObject(1);

• Accessing the source property of obj0:

  // ... Assume obj0 has been initialized to reflect the diagram above...
  KFbxProperty* prop0 = obj0->GetSrcProperty();

• Accessing the destination object of obj1:

  // ... assume obj1 has been initialized to reflect the diagram above...
  KFbxObject* obj0 = obj1->GetDstObject();

• Traversing the hierarchy in an ad-hoc manner starting from obj2:

  // ... Assume obj2 has been initialized to reflect the diagram above...
  // Access prop2 using obj2.
  KFbxProperty* prop2 = obj2->GetSrcProperty();
  
  // For illustrative purposes, count the number of source properties of prop2.
  int numSrcProperties = prop2->GetSrcPropertyCount(); // numSrcProperties = 2
  
  // Access prop3 and prop4, which are sources with respect to prop2, 
  // respectively indexed at 0 and 1.
  KFbxProperty* prop3 = prop2->GetSrcProperty(0);
  KFbxProperty* prop4 = prop2->GetSrcProperty(1);
  
  // Access obj0 using obj2.
  KFbxObject* obj0 = obj2->GetDstObject();
  
  // Access prop0 using obj0.
  KFbxProperty* prop0 = obj0->GetSrcProperty();
  
  // Access obj1 using obj0. 
  // Here, we assume obj1 is indexed at 0, whereas obj2 is indexed at 1.
  KFbxObject* obj1 = obj0->GetSrcObject(0);
  
  // Access prop1 using obj1.
  KFbxProperty* prop1 = obj1->GetSrcProperty();

Connecting Objects and Properties

The concept of connections in the FBX SDK allows for instances of KFbxProperty to be dynamically added to a KFbxObject. This gives you the flexibility of defining your own datatype, wrapping it into an FBX property via the KFbxProperty::SetUserDataPtr() member function , and binding that property to an FBX object via the KFbxObject::ConnectSrcProperty() member function.

The KFbxCollection class also relies on connections to organize groups of objects into a hierarchy. For example, the KFbxScene class contains a hierarchy of KFbxNode objects, accessible via KFbxScene::GetRootNode().

Before delving into the use of connections in relation to nodes (KFbxNode) and node attributes (KFbxNodeAttribute), it is recommended that you familiarize yourself with the scene graph organization of the FBX SDK. Consult the Nodes and the Scene Graph section for more information. However, if you are feeling adventurous, the concepts laid out below will give you an intuition of how the scene graph is structured using nodes and their attributes.

As a brief introduction, the hierarchy of KFbxNodes in a KFbxScene is used to specify the geometric transformation stack. The classes which inherit from KFbxNodeAttribute, for example, KFbxMesh, KFbxCamera, and KFbxLight describe all the elements in the scene. A KFbxNodeAttribute is connected to a KFbxNode to specify where the mesh, camera, or light exists in the 3D space.

"Object-Object" Connection Example: Parent-Child Relationships Between Nodes in a Scene

The parent-child relationships between nodes in a scene make use of object connections. Consider the KFbxNode::AddChild() method, which adds a child node to the parent node on which the method is called:

// ... Assume lScene has been initialized as a KFbxScene*,

// Obtain the root node of a scene.
KFbxNode* lParentNode = lScene->GetRootNode();

// Create a child node.
KFbxNode* lChildNode = KFbxNode::Create(lScene, "child");

// Add the child node to the root node.
lParentNode->AddChild(lChildNode);

The following connections will be made:

• The child node will be a source object of the parent node.
• The parent node will be the destination object of the child node.

"Object-Object" Connection Example: Nodes and Node Attributes

A KFbxNode's relationship to a KFbxNodeAttribute is normally created by invoking KFbxNode::SetNodeAttribute(). As such, an instance of KFbxMesh (which inherits from KFbxNodeAttribute) can be bound to a node in a scene. In this case:

• The KFbxNodeAttribute is a source object of the KFbxNode.
• The KFbxNode is a destination object of the KFbxNodeAttribute.

"Object-Property" Connection Example: Nodes and Transformations

As mentioned in the Property Data subsection, the local transformation data of a KFbxNode is defined as a KFbxTypedProperty, parametrized with the fbxDouble3 datatype. In this case:

• The KFbxTypedProperty returned by KFbxNode::LclTranslation is a source property of that KFbxNode.
• The KFbxNode is a destination object of that KFbxTypedProperty.