Output Arguments are used in certain scripting languages (such as VBScript) and compiled languages (such as C++) as an alternative to returning values with the assignment operator. One of the benefits of using output arguments is that functions that use them can pass back more than one value at a time. However, not all languages support output arguments (such as JScript and PerlScript) while others (such as Python) support output arguments in only some situations with Softimage.
Softimage uses output arguments in some of its scripting commands (AddProp, GetFCurveInfo, and SICreateImageClip) and for some methods (NurbsSurface.EvaluateNormalizedPosition, SIMatrix4.Get, and NurbsCurveList.Get). If you are using VBScript with these commands or methods, you can simply pass in a variable name as a placeholder for each output argument and then use it in the rest of your code:
' This VBScript example illustrates how to use the AddProp
' command to add an annotation property to a null object.
Set oNull = GetPrim("Null")
AddProp "Annotation", oNull, , "MyAnnonation", oRtn
' You can use an output argument in VBScript to avoid
' using the implicit return argument collection.
SetValue oRtn & ".text", "Hello World"
InspectObj oRtnHowever, for the other languages, it works a little differently.
Commands with Output Arguments
For an overview of how each language works in all scenarios, see Output Argument Support by Language. This section explains how each language works with commands that support output arguments but don't return a value.
Scripting commands return an ISIVTCollection, as long as there is no other return value specified. Use the argument name exactly as it appears (no spaces unless indicated and the exact same case) in the Commands and Scripting Reference for that command. For example, the SICreateImageClip command uses two output arguments: "FileName" and "Clip".
You can also query Softimage for the name of the argument using the Command and Argument objects. See the example on the ArgumentCollection reference page.
You need to use the XSIApplication.ExecuteCommand method to call commands from C#. The output arguments are packed into an Array which is returned from the ExecuteCommand method inside a generic C# Object.
When you use the Application::ExecuteCommand function, you populate the input argument array with CValue objects. Once the command is executed, you can convert those objects to the appropriate class. Check the Commands and Scripting Reference to see the order and type of each argument. For more information, see Dealing with Output Arguments.
For an overview of how each language works in all scenarios, see Output Argument Support by Language. Here is how each language works with commands that support output arguments but don't return a value:
All scripting languages except for Python treat methods that return output arguments the same way they treat commands that return output arguments. Python is unique in that it supports output arguments for methods, as long as you use the multiple-variable assignment syntax (see Getting Output Arguments from Methods).
Output arguments are supported for C# when using Softimage methods, but there are a couple of special restrictions. See Calling Object Model Methods.
Identifying Output Arguments from the Reference
Softimage uses output arguments in some of its scripting commands (AddProp, GetFCurveInfo, and SICreateImageClip) and for some methods (NurbsSurface.EvaluateNormalizedPosition, SIMatrix4.Get, and NurbsCurveList.Get).
An an example, the PickObject command uses three output arguments, which are: "PickedElement", "ButtonPressed", and "ModifierPressed".
To get the name of a specific output argument, check the Commands and Scripting Reference. The names of each parameter are listed in the Parameters table under the Parameter column. All output arguments are identified with [out] appearing after the name:
