# Operator Class Reference

Related Scripting Object: Operator

The Operator object represents an operator in the scene graph. Objects or Parameters are connected to the operator via InputPorts or OutputPorts. These ports are organized into port groups. The port groups contain all ports that will be connected to parts of the selected or picked object. For example, when the Twist_op operator is applied to a selected object the operator has ports that read from the object's local KinematicState and Geometry and write to the result object's geometry. More...

`#include <xsi_operator.h>`

Inheritance diagram for Operator:

List of all members.

## Public Member Functions
| Operator ()
| ~Operator ()
| Operator (const CRef &in_ref)
| Operator (const Operator &in_obj)
bool | IsA (siClassID in_ClassID) const
siClassID | GetClassID () const
Operator & | operator= (const Operator &in_obj)
Operator & | operator= (const CRef &in_ref)
Port | GetPort (const CString &in_portname, const CString &in_groupname, LONG in_instance=0) const
Port | GetPortAt (LONG in_port, LONG in_group=0, LONG in_instance=0) const
CRefArray | GetInputPorts () const
CRefArray | GetOutputPorts () const
LONG | GetNumPortGroups () const
LONG | GetNumPortsInGroup (LONG in_index) const
LONG | GetNumInstancesInGroup (LONG in_index) const
bool | GetMute (void) const
CStatus | PutMute (bool in_mute)
CStatus | Disconnect (bool in_force)
CStatus | Connect (siConstructionMode in_mode=siConstructionModeDefault)
CStatus | Connect (const CRef &in_obj, siConstructionMode in_mode=siConstructionModeDefault)
CStatus | Connect (const CRefArray &in_objs, siConstructionMode in_mode=siConstructionModeDefault)
CStatus | Connect (const CString &in_objs, siConstructionMode in_mode=siConstructionModeDefault)
CRefArray | GetPortGroups () const
bool | IsConnected () const
bool | SupportsBranchGroup (LONG group=-1, LONG port=-1) const
CStatus | ConnectToGroup (LONG in_Group, CRef &in_obj, LONG &out_Instance)
CStatus | DisconnectGroup (LONG in_Group, LONG in_Instance, bool in_Force=false)
CValue | GetInputValue (LONG in_port, LONG in_group=0, LONG in_instance=0) const
CValue | GetInputValue (const CString &in_port, const CString &in_group=CString(), LONG in_instance=0) const

## Detailed Description

The Operator object represents an operator in the scene graph. Objects or Parameters are connected to the operator via InputPorts or OutputPorts. These ports are organized into port groups. The port groups contain all ports that will be connected to parts of the selected or picked object. For example, when the Twist_op operator is applied to a selected object the operator has ports that read from the object's local KinematicState and Geometry and write to the result object's geometry.

You can determine the number of port groups defined by an operator using Operator::GetNumPortGroups and determine of the number of ports in a group using Operator::GetNumPortsInGroup. To access individual ports, use either Operator::GetPort property or Operator::GetPortAt function.

Multiple objects connected to the same port group for example, the loft operator may read from many curves to generate the resulting mesh. Each of these input curves are connected to the same port group and each connection is called a port group instance. You can determine the number of objects connected to a port group by using Operator::GetNumInstancesInGroup.

From the port you can determine which port group a port belongs to using Port::GetGroupName or Port::GetGroupIndex. You can determine which port group instance a port belongs to using Port.GroupInstance.

Port::GetIndex refers to the index of the port within the port group and is different from the index used to access the list of InputPorts or OutputPorts (available through the Operator::GetInputPorts and Operator::GetOutputPorts).

Almost all Operators expose one or more Parameters which control the behavior of the operator. For example, the "subdivu" and "subdivv" parameters on a polygon mesh geometry operator control the number of polygons that a polygon mesh is generated with.

The most common way to create and connect an operator is by calling the ApplyOp command. However there are many specialized commands for creating operators, for example ApplyTopoOp, ApplyHairOp and ApplyGenOp. Operators are also often created indirectly, for example calling X3DObject::AddGeometry creates an operator that generates the geometry.

Selecting an operator in the "RV - SDK Explorer" view is a good way to learn more about its ports and parameters.

See also:
  UpdateContext, Port, InputPort, OutputPort

Example:
  Illustrates how to generate a mesh by using the loft operator and a number of input curves. The code also illustrates how to traverse the operator's port group, port group instances and ports and logs the name of the port, its type and the full path name of the object connected to the port.

            using namespace XSI;
            Application app;

            Model root = app.GetActiveSceneRoot();

            CValueArray args(2);
            CValue outArg;

            // Create an arc
            args[0] = CString(L"Arc");
            args[1] = CString(L"NurbsCurve");
            app.ExecuteCommand( L"CreatePrim", args, outArg );

            // Get arc from return value
            X3DObject arc(outArg);

            // Duplicate arc 4 times and translate in y
            args.Resize(19);
            args[0] = arc;                  // source object
            args[1] = (LONG)4;              // number of copies
            args[9] = (LONG)siApplyRepeatXForm; // Xform
            args[18] = (double)1;           // Ty
            app.ExecuteCommand( L"Duplicate", args, outArg );

            // Get array of duplicated arcs from return value
            CValueArray objs(outArg);

            // Create array containing arc and duplicates
            objs[0] = CValue(arc);

            // Apply loft operator
            args.Resize(2);
            args[0] = CString(L"Loft");
            args[1] = objs;
            app.ExecuteCommand( L"ApplyOp", args, outArg );

            // Get create operator from return value
            Operator op = ((const CValueArray&)outArg)[0];

            // Traverse port group, instances and ports and
            // log port connections

            // For each port group
            for ( LONG idxGroup = 0; idxGroup < op.GetNumPortGroups(); idxGroup++ )
            {
                // for each instance in a port group
                for ( LONG idxInstance = 0; idxInstance < op.GetNumInstancesInGroup( idxGroup ); idxInstance++ )
                {
                    // for each port in a  port group instance
                    for ( LONG idxPort = 0; idxPort < op.GetNumPortsInGroup( idxGroup ); idxPort++ )
                    {
                        // get a specific port
                        Port port = op.GetPortAt( idxPort, idxGroup, idxInstance );

                        // if the port is an input port
                        CString porttypestr;

                        if ( port.GetPortType() == siPortInput )
                            porttypestr = L"input";
                        else if ( port.GetPortType() == siPortOutput )
                            porttypestr = L"output";
                        else
                            porttypestr = L"error";

                        SIObject target = port.GetTarget();

                        // log details of port connection to target
                        CString msgstr;

                        msgstr += op.GetName();
                        msgstr += L" group:";
                        msgstr += CValue(port.GetGroupIndex()).GetAsText();
                        msgstr += L" instance:";
                        msgstr += CValue(port.GetGroupInstance()).GetAsText();
                        msgstr += L" ";
                        msgstr += porttypestr;
                        msgstr += L"port:";
                        msgstr += CValue(port.GetIndex()).GetAsText();
                        msgstr += L":";
                        msgstr += target.GetFullName();

                        app.LogMessage( msgstr );
                    }
                }
            }
            // 'INFO : "Loft group:0 instance:0 inputport:0:arc20.crvlist"
            // 'INFO : "Loft group:0 instance:0 inputport:1:arc20.kine.global"
            // 'INFO : "Loft group:0 instance:1 inputport:0:arc21.crvlist"
            // 'INFO : "Loft group:0 instance:1 inputport:1:arc21.kine.global"
            // 'INFO : "Loft group:0 instance:2 inputport:0:arc22.crvlist"
            // 'INFO : "Loft group:0 instance:2 inputport:1:arc22.kine.global"
            // 'INFO : "Loft group:0 instance:3 inputport:0:arc23.crvlist"
            // 'INFO : "Loft group:0 instance:3 inputport:1:arc23.kine.global"
            // 'INFO : "Loft group:0 instance:4 inputport:0:arc24.crvlist"
            // 'INFO : "Loft group:0 instance:4 inputport:1:arc24.kine.global"
            // 'INFO : "Loft group:1 instance:0 inputport:0:surfmsh.kine.global"
            // 'INFO : "Loft group:1 instance:0 outputport:1:surfmsh.surfmsh"

## Constructor & Destructor Documentation

Operator | ( |  | ) |

Default constructor.

~Operator | ( |  | ) |

Default destructor.

Operator | ( | const CRef & | in_ref | ) |

Constructor.

Parameters:

  | in_ref | constant reference object.

Operator | ( | const Operator & | in_obj | ) |

Copy constructor.

Parameters:

  | in_obj | constant class object.

## Member Function Documentation

bool IsA | ( | siClassID | in_ClassID | ) | const`[virtual]`

Returns true if a given class type is compatible with this API class.

Parameters:

  | in_ClassID | class type.

Returns:
  true if the class is compatible, false otherwise.

Reimplemented from ProjectItem.

Reimplemented in CustomOperator, Envelope, and Expression.

siClassID GetClassID | ( |  | ) | const`[virtual]`

Returns the type of the API class.

Returns:
  The class type.

Reimplemented from ProjectItem.

Reimplemented in CustomOperator, Envelope, and Expression.

Operator& operator= | ( | const Operator & | in_obj | ) |

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

  | in_obj | constant class object.

Returns:
  The new Operator object.

Operator& operator= | ( | const CRef & | in_ref | ) |

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

  | in_ref | constant class object.

Returns:
  The new Operator object.

Reimplemented from ProjectItem.

Reimplemented in CustomOperator, Envelope, and Expression.

Port GetPort | ( | const CString & | in_portname,
|  | const CString & | in_groupname,
|  | LONG | in_instance = `0` |
| ) |  |  | const

Returns an individual Port object. The port group name and index arguments are optional. If both arguments are not provided, the first port with the given name will be returned.

Parameters:

  | in_portname | port name.
  | in_groupname | port group name.
  | in_instance | port group instance index.

Returns:
  The Port object.

Port GetPortAt | ( | LONG | in_port,
|  | LONG | in_group = `0`,
|  | LONG | in_instance = `0` |
| ) |  |  | const

Returns the specified Port object.

Note:
  Regardless of the order that ports are added to a PortGroup, input ports are always indexed before output ports. For example, if a custom operator is built with two output ports A and B and two input ports C and D then port 0 will be C, port 1 will be D, port 2 will be A and port 3 will be B.

Parameters:

  | in_port | Index of the port within the group
  | in_group | PortGroup index.
  | in_instance | PortGroup instance index.

Returns:
  The Port object.

CRefArray GetInputPorts | ( |  | ) | const

Returns an array of InputPort reference objects.

Returns:
  Array of Port reference objects.

CRefArray GetOutputPorts | ( |  | ) | const

Returns an array of OutputPort reference objects. If this function is accessed from within the scope of an operator update then an empty array be returned.

Returns:
  Array of Port reference objects.

LONG GetNumPortGroups | ( |  | ) | const

Returns the number of port groups.

Returns:
  LONG > 0 success

  -1 failure

LONG GetNumPortsInGroup | ( | LONG | in_index | ) | const

Returns the number of ports in port group.

Parameters:

  | in_index | port group index.

Returns:
  LONG > 0 success

  -1 failure

LONG GetNumInstancesInGroup | ( | LONG | in_index | ) | const

Returns the number of port group instances in port group.

Parameters:

  | in_index | port group index.

Returns:
  LONG > 0 success

  -1 failure

bool GetMute | ( | void |  | ) | const

Returns true if the operator is muted.

Returns:
  true if the operator is muted; false otherwise.

Since:
  4.0

CStatus PutMute | ( | bool | in_mute | ) |

Sets the muted state of the operator. Not all XSI operators can be muted, but all Custom Operators support this function.

Parameters:

  | in_mute | mute state, pass true to mute.

Returns:
  CStatus::OK success

  CStatus::Fail failure

Since:
  4.0

CStatus Disconnect | ( | bool | in_force | ) |

Disconnects all ports. This function is not undoable.

Parameters:

  | in_force | Force disconnection of operator even if connected to created output objects ( Not Implemented - will always delete )

Returns:
  CStatus::OK success

  CStatus::False operator doesn't support muting

  CStatus::Fail failure

Since:
  4.0

CStatus Connect | ( | siConstructionMode | in_mode = `siConstructionModeDefault` | ) |

Connects operator ports using objects specified through calls to Operator::AddInputPort and Operator::AddOutputPort.

Parameters:

  | in_mode | Specifies the construction mode in which the operator will be applied. This only applies to output connections made to Geometry objects, the mode will be ignored for all other types of connections.

Returns:
  CStatus::OK success

  CStatus::Fail failure

Since:
  4.0

CStatus Connect | ( | const CRef & | in_obj,
|  | siConstructionMode | in_mode = `siConstructionModeDefault` |
| ) |  |  |

Connect operators using object specified. The object will be matched to the port group.

Parameters:

  | in_obj | object to connect.
  | in_mode | Specifies the construction mode in which the operator will be applied. This only applies to output connections made to Geometry objects, the mode will be ignored for all other types of connections.

Returns:
  CStatus::OK success

  CStatus::Fail failure

Since:
  4.0

CStatus Connect | ( | const CRefArray & | in_objs,
|  | siConstructionMode | in_mode = `siConstructionModeDefault` |
| ) |  |  |

Connects operator using objects specified. The objects will be matched to the port groups.

Parameters:

  | in_objs | objects to connect.
  | in_mode | Specifies the construction mode in which the operator will be applied. This only applies to output connections made to Geometry objects, the mode will be ignored for all other types of connections.

Returns:
  CStatus::OK success

  CStatus::Fail failure

Since:
  4.0

CStatus Connect | ( | const CString & | in_objs,
|  | siConstructionMode | in_mode = `siConstructionModeDefault` |
| ) |  |  |

Connects operator using the specified StringExpression. The string expression must be a valid connection set specification.

Parameters:

  | in_objs | objects to connect.
  | in_mode | Specifies the construction mode in which the operator will be applied. This only applies to output connections made to Geometry objects, the mode will be ignored for all other types of connections.

Returns:
  CStatus::OK success

  CStatus::Fail failure

Since:
  4.0

CRefArray GetPortGroups | ( |  | ) | const

Returns an array of PortGroup reference objects.

Returns:
  Array of PortGroup reference objects.

Since:
  4.0

bool IsConnected | ( |  | ) | const

Returns true if the operator is connected to at least 1 output port.

Returns:
  true if operator is connected.

Since:
  4.0

bool SupportsBranchGroup | ( | LONG | group = `-1`,
|  | LONG | port = `-1` |
| ) |  |  | const

Returns true if the operator has ports that support branch and group connections.

Parameters:

  | group | index of group to check, pass group==-1 to check all groups and port==-1 to check
  | port | index of port to check, pass port==-1 to check all port within the specified group.

Returns:
  true if the operator has ports that support branch and group connections.

Since:
  4.0

CStatus ConnectToGroup | ( | LONG | in_Group,
|  | CRef & | in_obj,
|  | LONG & | out_Instance |
| ) |  |  |

Connects an object to a new instance of a PortGroup. This function is useful for dynamic operators, where optional or multi-instance connections are made after the object is already connected.

Note:
  This function only works for Self-Installed Custom Operators if there is a single Port inside the port group. This limitation exists because you can only pass a single object in the in_obj argument.

Parameters:

  | in_Group | Index of the port group.
  | in_obj | The object to connect to the new port group instance

Return values:

  | out_Instance | Returns the index of new port group instance.

Returns:
  CStatus::OK if successful, and CStatus::Fail otherwise.

Since:
  5.1

CStatus DisconnectGroup | ( | LONG | in_Group,
|  | LONG | in_Instance,
|  | bool | in_Force = `false` |
| ) |  |  |

Removes a port group instance from a port group.

Parameters:

  | in_Group | Index of the port group.
  | in_Instance | Index of the instance to remove
  | in_Force | True to disconnect the object even if the port is not optional.

Returns:
  Returns CStatus::OK if successful, and CStatus::Fail otherwise.

Since:
  5.1

CValue GetInputValue | ( | LONG | in_port,
|  | LONG | in_group = `0`,
|  | LONG | in_instance = `0` |
| ) |  |  | const

Returns the value of an input port specified by index.

Note:
  For Self-Installed Custom Operators the OperatorContext::GetInputValue function is often more convenient.

Parameters:

  | in_port | Port index.
  | in_group | PortGroup index.
  | in_instance | PortGroup instance index.

Returns:
  Value of the Port.

Since:
  5.1

CValue GetInputValue | ( | const CString & | in_port,
|  | const CString & | in_group = `CString()`,
|  | LONG | in_instance = `0` |
| ) |  |  | const

Returns the value of an input port specified by name.

Note:
  For Self-Installed Custom Operators the OperatorContext::GetInputValue function is often more convenient.

Parameters:

  | in_port | Port name.
  | in_group | PortGroup name.
  | in_instance | PortGroup instance index.

Returns:
  Value of the Port.

Since:
  5.1

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

- xsi_operator.h