Scripting: AddCustomOp

AddCustomOp

Introduced

v5.1

Description

Creates an instance of a Self-Installed Custom Operator and connects it to the specified inputs and outputs.

This command is a convenient way to instantiate most self-installed custom operators, because it combines the functionality of calls to CustomOperator.AddInputPort, CustomOperator.AddOutputPort, CustomOperator.AddIOPort, and Operator.Connect in a single command.

The objects in the input and output lists must be the specific data that that the operator will read or write. For example it is illegal to specify an X3DObject as the input or output, but objects of type Cluster, Property, Parameter, Primitive or KinematicState can all be valid connections.

This command is only suitable for creating operators that are defined inside a self-installed plug-in. To instantiate a Preset-based operator use ApplyOp. To instantiate a runtime operator use AddScriptedOp.

This command creates all the connections by adding Ports to a single PortGroup and assumes that all the objects to be connected to the operator already exist in the scene.

Note: To define a more dynamic operator that uses more than one PortGroup, it is necessary to use the more advanced methods on the CustomOperator object rather than this command.

Scripting Syntax

oReturn = AddCustomOp( Type, OutputObjs, [InputObjs], [Name], [ConstructionMode] );

Return Value

The newly created CustomOperator.

Parameters

Parameter	Type	Description
Type	String	Name of the Self-Installed PluginItem that implements the Operator. This command will fail if the plug-in is not installed.
OutputObjs	List	The output connections for the operator. If nothing is specified the current Selection is used. Most operators only connect to a single Output object.
InputObjs	List	The input connections for the operator. If nothing is specified then the operator will have no inputs. Default Value: "" (empty list)
Name	String	The name of the new operator. Default Value: If not specified the Type argument will be used to name the operator.
ConstructionMode	siConstructionMode	Specifies under which construction mode 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. Default Value: Use the current construction mode

Examples

1. JScript Example

/*
        Create an operator called "DemoOp". The type of the operator is "EmptyOp", which 
        is a very basic operator that does nothing.
        This operator reads from a Local transform of a Null and the Geometry of a Sphere 
        and outputs to the Global transform of another Null
*/
NewScene( null, false );
var oOutput = ActiveSceneRoot.AddNull( "Out" ).Kinematics.Global ;
var oInput1 = ActiveSceneRoot.AddNull( "In1" ).Kinematics.Local ;
var oInput2 = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "In2" ).ActivePrimitive ;
var oOp = AddCustomOp(
                                "EmptyOp", 
                                oOutput, 
                                [oInput1,oInput2], 
                                "DemoOp" 
                        ) ;

2. JScript Example

/*
        Create an operator called DemoParamOp that outputs to the PosX parameter of
        the global transform of a null.
        This operator is of type "EmptyOp" and it has no inputs so its only effect 
        is to force the value of the parameter to remain at 0.0
*/
NewScene( null, false );
var oOutput = ActiveSceneRoot.AddNull( "Out" ).Kinematics.Global.Parameters( "posx" ) ;
var oOp = AddCustomOp( 
                                "EmptyOp", 
                                oOutput, 
                                null, 
                                "DemoParamOp" 
                        ) ;

3. JScript Example

/*
        Create an operator called DemoManyInputs that reads from the visibility 
        property of ten nulls and outputs to the geometry of a Grid. Because it 
        uses the EmptyOp operator, it does nothing.
*/
var oInputs = new ActiveXObject( "XSI.Collection" ) ;
for ( var i = 0 ; i < 10 ; i++ )
{
        var oNull = ActiveSceneRoot.AddNull( "Input" + i ) ;
        oInputs.Add( oNull.Properties( "Visibility" ) ) ;
}
var oGrid = ActiveSceneRoot.AddGeometry( "grid", "MeshSurface", "Output" ) ;
SelectObj( oGrid.ActivePrimitive ) ;
AddCustomOp( 
                "EmptyOp",
                null,                   // Softimage will use the selection
                oInputs, 
                "DemoManyInputs"        ) ;