Operator Class Reference
 
 
 
Operator Class Reference

This reference page is linked to from the following overview topics: Common Build Problems, Checking Return Values for Type.


#include <xsi_operator.h>


Class 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 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"
Inheritance diagram for Operator:
ProjectItem SIObject CBase CustomOperator Envelope Expression

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

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: