Parameter

The Parameter section in a shader SPDL file defines an interface parameter or a phenomenon return value.

Parameter "property_name" input | output | unconnected
{
   guid = "guid" ;
   title = "label_text" ;
   flags = 0|1;
   writable = on|off ;
   readable = on|off ;
   animatable = on|off ;
   texturable = on|off ;
   persistable = on|off ;
   inspectable = on|off ;
   type = boolean | color | filename | integer | lens | light | material | matrix | model 
              | scalar | shader | string | texture | texturespace | vector | reference | rtrendercontext;
   type = array { Parameter {...} } ;
   type = struct { Parameter {...} ... } ;
   value = value ;
   value minimum = min ;
   value maximum = max ;
   ui "keyword" = "combo" | "rgb" | "rgba" | "LightList" | "ImageBrowser";
}

guid

Guid specifies the GUID that is used to identify the property.

Output ports use hardcoded GUIDs:

• ColorOutputGUID = "4C6879FF-7EC8-11D0-8E3B-00A0C90640EC";

• VectorOutputGUID = "1D58FA86-A96A-11D1-90DA-0000F804EB21"

• ScalarOutputGUID = "1D58FA87-A96A-11D1-90DA-0000F804EB21";

• IntegerOutputGUID = “1D58FA88-A96A-11D1-90DA-0000F804EB21”;

• MatrixOutputGUID = “1D58FA89-A96A-11D1-90DA-0000F804EB21”;

• BooleanOutputGUID = "1D58FA8D-A96A-11D1-90DA-0000F804EB21";.

 

Windows and Linux both include utilities for generating GUIDs. For more information, see Generating GUIDs.

title

Title consists of a concise, descriptive name for the parameter and must be enclosed in double quotes. It is currently used internally only and does not appear anywhere in the user interface.

 

This value is overridden by the Name keyword in Defaults.

flags

Flags controls what happens when a user changes the parameter value during a render.

• Set flags to 1 to allow incremental rendering while the parameter value changes.

• Set flags to 0 to completely rerender the render region when the parameter value changes.

If a parameter change requires _init and _exit to be executed, do not mark the parameter as incremental, since incremental rendering never forces the _init and _exit to be executed.

writable

Writable specifies whether the parameter is read-only or not. The default is on (which is the same as true or yes).

readable

The default setting for readable is on.

animatable

Animatable specifies whether the parameter value can be animated. The default is on.

texturable

Texturable specifies whether another phenomenon can be connected (assigned) to the parameter. The default is off.

When a parameter is texturable, users can apply a texture to the parameter by connecting a texture phenomenon to the parameter.

 

Note that for realtime shaders, only parameters defined as type rtrendercontext or as texture can be defined as texturable.

persistable

Persistable specifies whether the parameter value is saved. The default is on.

inspectable

Inspectable specifies whether the parameter appears on the property page. The default is on.

type

Type specifies the type of the parameter. It must match one of these types:

Type

Description

boolean

One of the following keywords: [Oo]n, [Oo]ff, [Tt]rue, [Ff]alse, [Yy]es, [Nn]o.

color

A sequence of scalars specifying the red, green, blue, and alpha components of a color. If the alpha is omitted, it defaults to 0.0.

filename

A character string.

integer

An integer value.

lens

Output type of a lens phenomenon.

light

Reference to a light in the scene. Typically used for the light and diffuse light lists obtained from the system. Also used as the output type of a light shader.

material

Output type.

matrix

A 4-by-4 matrix stored as an array of 16 scalars in row-major order.

For example, the following specifies that the default value of a property is the identify matrix:

type = matrix;
value = 1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 0.0 1.0;

model

Reference to a model in the scene. Typically used the output type for a geometry shader.

scalar

A floating point number.

shader

Reference to a shader. Typically used for objects picked by a user.

string

A character string.

type = string;
value = "RenderPic";

reference

Used when the data to be passed is an actual object in the scene, such as a polygon mesh or a light. Reference parameters cannot be textured, and the shader is passed miTags. Can also specify that a parameter to be an object list.

rtrendercontext

An input port (also called the previous port), which realtime shaders require to connect to other shaders. At least one parameter of this type must be specified for realtime shaders. This parameter uses a constant GUID: DC79F6A6-C6D9-49C5-85E3-A36FC4A402D8.

texture

Reference to a texture. Typically used for objects picked by a user in an image browser:

UIType = "ImageBrowserItem.ImageBrowserItem.1";

texturespace

Integer value calculated based on the scene. This integer represents an index into a table of texture spaces maintained internally by mental ray (state->tex_list).

vector

A sequence of three scalars. For example:

type = vector;
value = 1.0 1.0 1.0;

type = array

You can define an array of a given parameter type. For example, the syntax for defining an array is:

type = array
{
   Parameter "element" input
   {
       ...
   }
};

 

mental ray does not support arrays of arrays, but you can use arrays of structs containing arrays.

type = struct

You can define a structure of parameters. For example, the syntax for defining a struct is:

type = struct
{
   Parameter "member1" input
   {
       ...
   }

   ...

   Parameter "memberN" input
   {
       ...
   }
};

value

Value specifies the default value for the parameter.

value minimum

Specifies the minimum possible value for the parameter. For example:

value minimum = 0.0001;

value maximum

Specifies the maximum possible value for the parameter. For example:

value maximum = 255;

You can also use UIRange to restrict the values that users can enter through a property page, and to specify a step value so that the parameter value changes in fixed increments (for example, by increments of 0.1).

ui "keyword"

Specifies the type of control that appears on the property page.

Control

Syntax

combo box

 
value = 0; # Make "Item 1" the default.
ui "control" = "combo";
ui "enum" = "Item 1", 0, "Item 2", 1, "Item 3", 2;

The "enum" string specifies the text of the items that appear in the combo box, along with the integer values associated with each item. The integer values do not have to start with 0 or be in ascending or descending order.

light list

 
ui "control" = "LightList";

The LightList control allows the user to select lights from a scene.

image browser

 
ui "control" = "ImageBrowser";

The ImageBrowser control pops up a file browser that allows the user to select image files.

color slider

 
ui "control" = "rgb";
ui "control" = "rgba";

Color properties are automatically given RGBA sliders, so that specifying the control type of a color parameter is redundant (unless you don’t want the Alpha slider).

 

 

These UI properties are overridden by the UIType keyword in Defaults.

Autodesk Softimage v7.5