Before you begin, you should understand some basic concepts about scripted operators, connections, and variables.
Scripted operators are object-model scripts that are called to update data in a scene. A scripted operator can be applied to one or more animatable parameters, to properties, or even to geometric objects to deform their shapes.
Scripted operators have several uses:
As an alternative to expressions on parameters, scripted operators have several advantages.
You can use multiple text lines, indents, local script variables, and comments to keep the code more understandable than the equivalent expression.
You can use programming loops, subroutines, and other script language features that are not available when using expressions.
You can apply scripted operators on top of a previously-applied function curve or expression.
You can apply multiple scripted operators to the same parameter, with the output of one operator being the input of the next.
You can also apply a single scripted operator to multiple parameters or properties (like local transformations). This is easier to set up, maintain, and copy than many expressions on separate parameters.
Scripted operators can also be used for quick custom deformations that you don't plan to reuse. If you intend to reuse a deformation, it may be worthwhile to create a compiled plug-in instead.
Even if you are developing a compiled plug-in deformation, you can use a scripted operator to quickly prototype your design and test its logic before converting the code to C++ or another language.
At the same time, scripted operators have some disadvantages:
When you first create a scripted operator, it is stored in the scene rather than as a separate file.
Although you can create presets of scripted operators and reuse them in other scenes, it can be awkward to install and register a preset on all machines that require it, such as on a render farm.
For these reasons you may prefer to use scripted or compiled self-installing custom operators instead of scripted operators — see Custom Operators [SDK Guide]. You can think of scripted operators as providing an intermediate solution between expressions and self-installing custom operators.
Connections represent the points at which your scripted operator communicates data with Softimage. You do not have any access to data unless you create a connection.
You can connect a scripted operator to animatable parameters, properties, objects, or a combination. Each connection is one of two types: input or output. A single scripted operator can have any number of connections, almost anywhere in the scene.
Parameter, Property, and Geometry Connections
You can connect a scripted operator to animatable parameters, properties, 3D geometry, or a combination.
A scripted operator connected to a parameter is similar to an expression. One important difference is that a scripted operator can be connected to multiple parameters so that a single script can be used to update several parameters with different values.
You can also connect a scripted operator to a property like Visibility or Local Transform. This means you can access any of the property's parameters without the need to define multiple connections to individual parameters.
In addition, scripted operators can be connected directly to geometry such as polygon meshes, surfaces, curves, particle clouds, and hair. This lets you modify a 3D object's shape to create your own custom deformation.
There are two types of connection:
Output connections are those elements that your script is responsible for updating. When the scene needs to be updated, your script is called to calculate the new values.
Input connections let your script access data from the scene. You can create an input connection for any scene data that your script requires in its calculations.
The connections must be properly defined for the operator to be evaluated correctly. Any scene data that is used in the computation should be added as an input connection; otherwise, the operator will not be called to update when the input changes. Similarly, any scene data that is set by the script should be added as an output connection; otherwise, the operator will not be called when an updated value is required.
The same element can be connected as both an input and an output in the same operator. For example, if you create a custom deformation, you must get a 3D object's geometry to get its list of points (input) and then update the geometry with the new positions of those points (output).
In the case of a parameter input connection, the scripted operator is passed the final value of that parameter for the appropriate frame including the effect of animation from any other source (function curve, expression, action, constraint, or inverse kinematics).
If a parameter is both an input and an output connection, then the scripted operator is passed the current value of that parameter. This could be the last value set, or it could be the value from a previously-applied function curve or expression. If there are multiple scripted operators, then the output of one is the input of the next in the order in which they were applied (not the order in which they were created).
If there are multiple parameters that are connected as both inputs and outputs to a single scripted operator, the scripted operator is called to update them individually as needed. In particular, the order in which they are updated may change; when your operator is called to update one parameter, you cannot be certain which, if any, of the other inputs have already been updated.
Scripted operators can have variables as well as connections. Variables are custom parameters that belong to the scripted operator and can be used to control its effect. You can edit and animate variables just like any other custom parameter in a scene. In addition, the variable is available to the scripted operator in its calculations.
For example, if you create a custom deformation, you could define a variable to control the amplitude of the deformation. You can then animate the amplitude using keys, expressions, actions, and so on.
The main update routine is where you write the code to calculate new values for all your output connections. It is contained in the middle panel of the scripted operator editor. This code is parsed when you apply a scripted operator as well as when a scene with a scripted operator is loaded.
You can write scripted operators in any language supported by Softimage. The language that is used to parse a particular scripted operator is the language that is set on the Scripting page in the Preferences window when the scripted operator is first created.
You cannot use scripting commands in your code. You are restricted to a subset of object model statements. The properties and methods that you are allowed to use in scripted operator code are listed in the SDK Guide.
The scripted operator editor manages the header of the main update routine automatically for you, so the Sub Update() and End Sub lines are read-only. The following arguments are passed to the main update routine:
In_UpdateContext is a transitory UpdateContext object that gives your scripted operator information about the context in which it is being called.
For more information about this and the object model in general, refer to the SDK Guide as described in Getting More Information Objects, Properties, and Methods.
Out is the single output connection that your operator is being called on to evaluate. Your operator is called separately to update each output connection, one at a time.
If your operator has multiple output connections, then your update routine must test Out.Name to determine what to return and then set Out.Value accordingly.
The input connections are all passed as arguments every time your scripted operator is called. In the previous illustration there are four input connections: InGeom, InGPosX, InGPosY,and InGPosZ.
The bottom pane of the scripted operator editor can be used to hold extra code needed by your scripted operator, such as helper routines and global variable declarations. In addition, it can be used to define Init and Term procedures that allow you to access private user data — see Using Private User Data in Scripted Operators.
As with the main update routine, this code is parsed when you apply a scripted operator as well as when a scene with a scripted operator is loaded.
