XSIFactory.CreateParamDef

Introduced

v4.0

Description

Creates a new custom parameter definition (ParamDef object).

ParamDef objects contain the definition of a parameter from which you can create new parameters on the fly for one or more property sets or operators. For example, you may want to use a double with the same min/max range and use it on multiple property sets or you may simply want a quick way to add parameters to a runtime scripted operator via scripting. You can create New ParamDef objects from the XSIFactory object.

Note: For a simplified version see XSIFactory.CreateParamDef2.

Scripting Syntax

oReturn = XSIFactory.CreateParamDef( ScriptName, Type, [Classification], [Capabilities], [Name], [Description], [DefaultValue], [Min], [Max], [SuggestedMin], [SuggestedMax] );

Return Value

The newly created ParamDef object.

Parameters

Parameter Type Description
ScriptName String This argument specifies the ScriptName of a parameter (see Parameter.ScriptName). If the short name or long name arguments are not specified then this name is also used as the short name and description.
Type siVariantType Type of the custom parameter. The recommended types are: siString, siBool, siInt4, siUByte, and siDouble. The supported types are: siString, siBool, siDouble, siFloat, siInt4, siInt2, siUInt4, siUInt2, siByte, siUByte (see Parameter.ValueType).
Classification siParamClassification Classification of the custom parameter.

Default Value: siClassifUnknown

Capabilities (see Integer) bitfield based on siCapabilities Capabilities of the custom parameter. If you create a custom operator parameter that is not inspectable, it does not appear in the interface, but is still available from scripting. If the parameter is read-only, it is greyed out in the interface, but is also available from scripting.

The siPersistable flag optional and assumed to be enabled for all custom parameters. This establishes the default capability flags for all instances of the parameter, but these flags can be overridden on a per-instance basis via Parameter.Capabilities.

Default Value: siPersistable+siAnimatable

Name String Short, user-friendly version of the custom parameter's name. This is the parameter name that appears in the Scene Explorer (unless Show Script Names is enabled). If this argument is not specified then the ScriptName argument is visible to users as the parameter's name (see SIObject.Name and Parameter.ScriptName).

Default Value: ""

Description String Description of the custom parameter. If specified, this is a more descriptive name that appears as the parameter label when the customer property is inspected. For example, the long name of a parameter might be the user-friendly "Use Light Color as Energy" while the name might be the more script-friendly "use_color" (see Parameter.Description).

Default Value: ""

DefaultValue Variant Default value of the custom parameter. A default value for numerical values (including boolean) is 0; the string default is "" (see Parameter.Default).
Min Variant Minimum value of the custom parameter. The types siString and siBool do not require a Min value. For all other numerical types the default is the minimum value possible for the type. For example, all unsigned values have a minimum value of 0 (see Parameter.Min).
Max Variant Maximum value of the custom parameter. The types siString and siBool do not require a Max value. For all other numerical types the default is the minimum value possible for the type. For example, the maximum value for siUByte is 255 (see Parameter.Max)
SuggestedMin Variant Suggested minimum value of the custom parameter. The types siString and siBool do not require a SuggestedMin value. The default suggested minimum value for numerical values is 0. The suggested minimum should be equal to or larger than the Min. This value is used to configure the range of UI controls (see Parameter.SuggestedMin).
SuggestedMax Variant Suggested maximum value of the custom parameter. The types siString and siBool do not require a SuggestedMax value. The default suggested maximum value for numerical values is 100. The suggested maximum should be equal to or smaller than the Max. This value is used to configure the range of UI controls (see Parameter.SuggestedMax).

Examples

JScript Example

/*
        This example illustrates how to add parameters to a custom operator
*/
var null1 = GetPrim( "null" );
var sop = XSIFactory.CreateScriptedOp( "MySOP", MySOP_Update.toString(), "JScript" );
sop.AddOutputPort( null1.posx );
// String 
var paramdef1 = XSIFactory.CreateParamDef( "text", siString, 0, siAnimatable, "Text", "a text parameter", "the text...");
var param1 = sop.AddParameter( paramdef1 );
// Boolean
var paramdef2 = XSIFactory.CreateParamDef("bool", siBool, 0, siAnimatable, "Boolean", "a boolean parameter", true);
var param2 = sop.AddParameter( paramdef2 );
// Integer
var paramdef3 = XSIFactory.CreateParamDef("int", siInt4, 0, siAnimatable, "Integer", "a integer parameter", -1, -5, 5);
var param3 = sop.AddParameter( paramdef3 );
// Double 
var paramdef4 = XSIFactory.CreateParamDef("dbl", siDouble, 0, siAnimatable && siReadOnly, "Double", "a double parameter", 0.69, 0.1, 10.9);
var param4 = sop.AddParameter( paramdef4 );
// Connect operator
sop.Connect();
// List operator's parameters
var eParams = new Enumerator( sop.Parameters );
for ( ; !eParams.atEnd(); eParams.moveNext() )
{
        var param = eParams.item();
         Application.LogMessage( param.Name + " = " + param.Value );
}
function MySOP_Update( ctx, out )
{
        out.Value = ctx.CurrentFrame;
}

See Also

XSIFactory.CreateParamDef2 CustomOperator.AddParameter Parameter