Returning Values

What is a Return Value?

A return value is any value that a function sends back to the caller. This return value can be captured using the assignment operator (=) as demonstrated in the example below:

// Get the user path from the application object
var sPath = Application.InstallationPath( siUserPath );
LogMessage( sPath + " is the working path for the User." );

The InstallationPath method returned the path where Softimage was installed (for example, C:\Softimage\Softimage_2013) which the script writer captured in the sPath variable.

Many Autodesk Softimage commands and methods that create something also return it. You can use the return value to make your scripts reusable. For example, the following lines use functions that return numeric values that are saved into variables:

// XSIMath.DegreesToRadians returns a double
var iDegrees = 30;
var dRadians = XSIMath.DegreesToRadians( iDegrees );
LogMessage( "iDegrees = " + iDegrees + " as a " + typeof(iDegrees) );
LogMessage( "dRadians = " + dRadians + " as a " + typeof(dRadians) );

//GetNbTriangles returns a long
var sList = GetValue( "SelectionList" );
var lNumberOfTriangles = GetNbTriangles( sList );
LogMessage( "Selection contains " + lNumberOfTriangles + " triangles as a " 
	+ typeof(lNumberOfTriangles) );

In some cases, instead of using a string or numeric variable, you can save the return value as an object. For example, when you create a 3D object and store it an object variable, you can exploit the power of the object model to work with that object.

The following lines demonstrate how to create a primitive surface sphere and ask Autodesk Softimage to name it orb without returning the new sphere as an object:

// Using a native Softimage scripting command
CreatePrim( "Sphere", "NurbsSurface", "orb" );

' Using the Softimage object model
Set oRoot = ActiveProject.ActiveScene.Root
oRoot.AddGeometry "Sphere", "NurbsSurface", "orb" 

In this example, the command (CreatePrim) and method (AddGeometry) provide a Name parameter which allows you to influence what Softimage names it in the explorer. You can refer to this object by name later in your script, but it does not give you access to any object model functions.

There's another concern: the new sphere could be named orb, orb1, or orb127, depending on how many other objects with that name are already in the scene. Because of this, you cannot rely on an object's name when scripting.

For a more dependable way of referring to the objects you create through scripting, convert the return value to an object. This code snippet is nearly identical to the previous one, except that it creates an X3DObject with access to several useful methods and properties. For example, you can find out who the parent is or find out whether it is selected:

' Using the native Softimage scripting command
Set oSphere = CreatePrim( "Sphere", "NurbsSurface" )
LogMessage oSphere.Name & "Ôs parent is " & oSphere.Parent

' Using the Softimage object model
Set oRoot = ActiveProject.ActiveScene.Root
Set oSphere = oRoot.AddGeometry( "Sphere", "NurbsSurface", "orb" )
LogMessage "Is " & oSphere.Name & " selected?..." & oSphere.Selected

Some commands and methods provide an output argument (or output parameter) that can be used to capture that parameter's information in a variable:

In this example myParams is the variable you pass into the IsAnimated command. When the command runs, it stores the collection of parameters that are animated in the myParams variable so you can access and manipulate it later in the script.