Retur ning Values

For each Softimage function that uses an explicit return value, it indicates what is returned under the Return Value section of its reference entry. If there is no Return Value section, the function does not explicitly return a value.

| For experienced scripters, there are some issues with using return values and output arguments that you need to know about: Working with Return Values and Output Arguments. For novice scripters you should also read the next few sections: • Returning Data Values • Returning Objects • Simple Objects versus Collections

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_7.5) 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) );

| For more information on using data value variables, see Returning Data Values.

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

| For more information on using object variables, see Returning Objects.

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

    IsAnimated , siFcurveSource, , myParams

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.

| For more information on using output arguments, see Working with Return Values and Output Arguments.

Autodesk Softimage v7.5