Parameter

The Parameter section in a SPDL file defines a specific parameter for the property set described in the SPDL file. For example, the definition might include the type (boolean, string, long). The syntax for a parameter definition is as follows:

    Parameter "paramter_scripting_name"
    {
       Name = "parameter_name";
       Description = "description";
       Guid = "guid";
       Caps = capabilities;
       Type = type;
       Range = min_to_max;
       UIRange = uirange
       Class = class;
       Value = default_value;
       UIType = uitype
       Items
       {
           item list
       }
    }

| Don’t use spaces or hyphens in the name of your property (identified as parameter_scripting_name in the example above).

Parameters

Name

Name consists of a concise, descriptive name for the parameter (optional)

Description

Description is a brief sentence fragment. It does not appear anywhere in the user interface (optional).

Guid

GUID is the unique identifier for the parameter. It appears as a string in the following format:

       {07C5EDE4-52A4-11D0-8298-00A0243E366B}

| The GUID shown here is just an example; you need to create a unique GUID for each parameter. For information about generating GUIDs, see Generating GUIDs.

Caps

Caps contains a comma-separated list of capability flags:

• Animatable (only applies to numeric types)

• Persistable (even if not specified, the parameter is by default persistable)

• ReadOnly

• UnInspectable (hides the parameter even if it in the Layout)

Type

The Type specifies the data type of the parameter matching one of the following type specifiers:

| Type specifier | Description
Text | VT_BSTR | Length-prefixed string
Float (Single) | VT_R4 | 4-byte real value
Float (Double) | VT_R8 | 8-byte real value
Integer | VT_I2 | 2-byte signed integer
| VT_I4 | 4-byte signed integer
Small Integer | VT_UI1 | 1-byte unsigned integer
Boolean | VT_BOOL | Boolean

Range

Range describes the range of possible values for the parameter. For example:

       Range = 0 to 10;
       Range = 0.0 to 10.0;
       Range = -2.0 to 2.0;

If a parameter has no specific range, use the following syntax:

       Range = min to max;

UIRange

The UIRange allows you to specify a range of values for the numeric slider of a parameter that is smaller than the Range. This is a suggested range but the user can type a value outside range to experiment. When Range = min to max, the default UIRange for the numeric slider is 0.0 to 100.0. For the components of a color, the UIRange must always be 0 to 1;You can override the default by explicitly setting UIRange:

       UIRange = -360 to 360;

Value

Value is the default value for the parameter.

Class

This optional attribute provides extra information about what type of effect the parameter has on a scene. The default value is 0x00008000. For parameters that change the actual geometry of an object, the value should be 0x00004041, this ensures that any render region on the object will redraw when the parameter is changed.

UIType

Specifies the type of control that appears on the property page. For some controls, the UIType may be followed by a list of attributes, for example:

    UIType= "Number"
    {
    NumbEdit = True;
    }

UIType is optional for most parameters. When it is not specified, XSI will pick the following controls:

• Boolean parameters get True and False radio buttons.

• Float, double, and integer parameters get a numeric control.

• String parameters get a text box.

Control type | Description
Bool | Displays a radio buttons. Assigned by default to Boolean parameters.
BitmapWidget | Displays a bitmap. The file path name can be absolute or relative to the directory which contains the SPDL file. Only .bmp files are supported. Must use “/” and not “\” slashes. The name of the file must be specified with its extension (<myfile>.bmp). See Bitmaps for more information.
Check | Check box. For multiple items, use the Items keyword to specify the check box contents. See Check Boxes.
Combo | Combo box. Use the Items keyword to specify the combo box contents. See Combo Boxes.
Iconlist | Displays iconic radio buttons. The following optional attributes control their behavior: • nocol - arrange the bitmaps in this number of columns as much as possible (default = as much as line space allows). • noline - arranges the bitmaps in this number of lines as much as possible (default = 1). • colgap - specifies number of pixels to leave horizontally between bitmaps (default = 3). • linegap - specifies number of pixels to leave vertically between bitmaps (default = 3). • selcolor - specifies color of the selection box highlight (default = 0x00FFFFFF, white). • useselicon - uses alternate selection bitmap files instead of the selection box highlight when set to True (default = False). Use the Items keyword to specify the radio button bitmap files and values. See Bitmaps for more information.
Number | Numeric entry control. Assigned by default to integer and float parameters. • syncslider true|false: Number control updated while you move slider (Default: True) • log = true|false: Logarithmic number control, range must be positive only (Default: False) • decimals = integer: Number of decimal places to display (0 for integer values) (Default: 3) • numbedit true|false: No slider, just a number control (Default: False) See Number Control for more information.
Radio | Use the Items keyword to specify radio buttons. See Radio Buttons.
RGB | Color control with no Alpha slider. Use the following syntax:
    UIType = "RGB", 3;
See Color Widgets.
RGBA | Color control with Red, Green, Blue, and Alpha sliders. Use the following syntax:
    UIType = "RGBA", 4;
See Color Widgets.
String | Text entry control. Assigned by default to text string parameters.

Items

List of items to display in the control. Used to define radio buttons, iconic buttons, and combo boxes.

An item list is defined like this:

    Items
    {
       "name1" = value1
       "name2" = value2
                   ...
    }

In the example above, nameN is the text that appears in the control and valueN is the value assigned to the property when the item is chosen. For example, if you have defined an iconic radio button, you need to specify the location of the BMP file and the value of the button it is associated to:

    Items
       {
           "S:/Application/spdl/bitmaps/BitmapA.bmp" = 1
           "S:/Application/spdl/bitmaps/BitmapB.bmp" = 2
           "S:/Application/spdl/bitmaps/BitmapC.bmp" = 3
           "S:/Application/spdl/bitmaps/BitmapD.bmp" = 4
       }

| Make sure you use a forward slash (“/”) in the path and that you include the “.bmp” extension in the file name. You can use one of the following types of paths: • An absolute path name. • A relative path name in the directory containing the SPDL file. • A dummy path name to leave a hole in the displayed arrangement of iconic radio buttons. Bitmaps are the only supported file format for iconic radio buttons.