Making Connections

For a general understanding of operator connections for built-in Softimage operators, read About Connection Sets.

Understanding Ports

Each operator has at least one output port and zero or more input ports. Each port has a direction, so to read from and write to a particular object requires two ports (an input and an output). Deformers are examples of operators that read an existing geometry and deform it via an input and output port.

Port connections are made to the specific data that needs to be read or written. Valid objects to connect with include any Property or Property, ClusterProperty or ClusterProperty, KinematicState or KinematicState, Primitive or Primitive or Parameter or Parameter. The connection needs to go to the specific data within the X3DObject or X3DObject, not to the X3DObject itself. To help enforce this rule the object model or C++ API prevents access to certain methods and properties designed to traverse through the nested data of an X3DObject or X3DObject. For example, Geometry.Clusters or Geometry::GetClusters is blocked inside Custom Operators because the operator is expected to connect to each cluster that it wants to access.

One of the main tasks of building a custom operator is to define the ports so that all the necessary input data can be read and the result of the calculations used to update the output object(s).

Port Indexing

To access ports within the Update function, you can use OperatorContext.GetInputValue or OperatorContext::GetInputValue which allows you to specify the port by name or index. Accessing ports by index is much faster than by name, and you can figure out the index by the order in which the ports were added:

If the operator was created by the AddCustomOp command or Parameter.AddCustomOp or Parameter::AddCustomOp method then the index is easy to determine based on the order of the inputs in the input argument.
If the operator was built manually then the index can be determined based on the order of calls to CustomOperator.AddInputPort or CustomOperator::AddInputPort or CustomOperator.AddIOPort or CustomOperator::AddIOPort.

To access ports outside of the Update function, you can use Operator.InputPorts or Operator::GetInputPorts and Operator.OutputPorts or Operator::GetOutputPorts.

Note

There are other methods you can use to retrieve a port by its index, Operator.PortAt or Operator::GetPortAt. However it is important to understand how this method reads indexes: regardless of the order in which they were implemented, all input ports precede the output ports.

It is recommended (and much safer) to use OperatorContext.GetInputValue or OperatorContext::GetInputValue (or Operator.GetInputValue or Operator::GetInputValue) and Operator.InputPorts or Operator::GetInputPorts or Operator.OutputPorts or Operator::GetOutputPorts instead.

Port Groups

A port group is a sophisticated tool for organizing the ports of an Operator. Each port must belong to a single group, and an operator can define multiple groups.

Tip

The word Group in this context has nothing to do with the Group or Group object in Softimage.

There are two main purposes for port groups:

To make it easier to connect to an operator when it is created.
To allow an arbitrary number of objects to connect to a single operator.

Unless you are creating an advanced operator, such as a dynamic operator or a complex operator that reads from an arbitrary number of inputs, you do not have to worry about port groups, which are explained in Static versus Dynamic Operators.

What is a Target?

A target is an object (Primitive or Primitive, KinematicState or KinematicState, Property or Property, Parameter or Parameter, etc.) that is connected, via a port, to the operator. If the connection is to a parameter then you get the current value of the parameter (for example, a double value), otherwise, you get the connected object (for example, a Primitive or Primitive object):

Member to use	Parameter connection	Non-parameter connection
OperatorContext.GetInputValue or OperatorContext::GetInputValue	Returns the parameter value	Returns the object.
OperatorContext.OutputTarget or OperatorContext::GetOutputTarget		Returns the object connected to the output port.
OperatorContext.OutputPort or OperatorContext::GetOutputPort	Returns the port object itself. You can then write a new value to the parameter connected to the port with OutputPort.Value or OutputPort::PutValue.

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License