SPDL Overview

SPDL files are text files that use a proprietary file format invented by Softimage. They are normally used for Shaders and Custom Operators.

A SPDL declares an object and how it is created in XSI, how to uniquely identify it and how it appears to the user.

Table of contents

Sections

A SPDL is usually comprised of roughly three sections: PropertySet, a Layout and either a MetaShader (shaders) or a PortSet (operators) section. There are also a number of optional sections, such as Defaults and Logic.

Apart from the header, each section is written as a keyword, followed by a name and curly braces. Example:

PropertySet "PropertySetName"
{
   // List of Parameter items
}

Header

A SPDL is identified by the keyword SPDL which should appear by itself on the first line of the SPDL file. The keywords Version, which indicates which version of the SPDL file is in use, and Reference, which uniquely identifies the object the SPDL represents, are also required, in that order. An example header:

SPDL
Version = "2.0.0.0";
Reference = "{183009C7-B466-49C0-8B55-DB94E338B5AF}";

It is also recommended to add a Name parameter to indicate which name the object will be known as. This can also be done in the Plugin section.

Example:

Name = "My_Brand_New_Plugin";

PropertySet

The PropertySet section defines the input and output parameters for the object. Each input parameter declares the input data that the object this SPDL declares will receive and each output parameter declares the outputs expected from the object.

Image:Lightbulb.png
It is convenient to group the input and output parameters together so that the output parameters appear first, followed by the input parameters. The SPDL doesn't care either way but it gives a less cluttered view of the input/output structure.


Each parameter is declared by the keyword Parameter, and, as with sections, followed by a name and curly braces around the parameter's attributes. Example:

Parameter "MyParameter"
{
    GUID = {1655AC12-FCF9-4939-844D-48A3C8DA6D16};
    Type = VT_R8;
    // Other attributes...
}

The name appearing after the Parameter keyword is the name used for the parameter in scripting.

Shaders' parameters have a different set of attributes from custom property sets and operators, although they share the GUID attribute in common.

GUID 
A unique identifier for the parameter's definition (not the parameter itself).


Image:Exclamation.png
Each parameter in XSI has an associated parameter definition (http://softimage.wiki.avid.com/sdkdocs/ParamDef.htm) which defines the parameters type, default values, limits, flags and so forth. The parameter definition is identified by the GUID given by the SPDL's Parameter. If two SPDLs define an identical parameter (same name, type, value, everything), they can re-use the same GUID, otherwise it is extremely important that they remain distinct.


Shader Attributes

Title = "<string>"; 
The name to use in the user interface (as opposed to scripting name) for this parameter. This name will always be used by the scene explorer but can be overridden for the object's property page by the Defaults section.
Type = <type>; 
The type of the parameter to use. The types are listed below.
Value = <default value>; 
The default value to use for the parameter upon creation of the object. The value depends on the type. Some types do not use a default value.
UI "<property>" = "<value>"; 
A set of properties that can be applied to the parameter. The interpretation of this is often highly dependent on the type. The list of UI properties is listed below.
Animatable = <boolean>; 
If set to true the parameter is animatable and can be controlled through expressions, fcurves etc. If not, it can only be controlled via direct value input. The default is true.
Texturable = <boolean>; 
If set to true the parameter can have another shader's output connected to it. The default is false.
Persistable = <boolean>; 
If set to true the parameter's value will be saved when the object is saved. Otherwise the value will always be the default upon loading. The default is true.
Inspectable = <boolean>; 
If set to true the paramater will show up in the user interface, otherwise it'll remain hidden. The default is true.
Value Minimum = <value>; 
The minimum value that the parameter can be set to directly. This minimum does not apply when the parameter is controlled via animation. The default is the minimum allowed for the datatype. This attribute applies only to parameters of type Integer and Scalar.
Value Maximum = <value>; 
The maximum value that the parameter can be set to directly. As with the minimum, the maximum value does not apply when the parameter is controlled via animation. The default is the maximum allowed for the datatype. This attribute applies only to parameters of type Integer and Scalar.
UI Minimum = <value>; 
The minimum value used by a widget that allows the value to be controlled through the mouse (eg. a slider).
UI Maximum = <value>; 
The maximum value used by a widget that allows the value to be controlled through the mouse (eg. a slider).
Parameter Types
Type Description
Boolean The parameter is a two-state boolean value that can be either true or false. It is represented in the UI as a checkbox.
Integer The parameter is a 32-bit signed integer value with a range from -2147483648 to 2147483647. It is represented in the UI as a slider. It obeys the minimum/maximum value constraint (if controlled via animation) and the slider uses the UI minimum/maximum value as a range limit on the slider itself.
Scalar The parameter is a 32-bit floating point value. It maps exactly to a C/C++'s float data type. As with the Integer type, it is represented in the UI as a slider and obeys the same minimum/maximum limits for both data entry and slider range.
Color The parameter is a four-channel color value of red, green, blue and alpha. It is shown in the UI as a color chooser widget, with the alpha channel displayed optionally. For more details on how to display with or without alpha, see the Defaults section.
Vector The parameter is a 3-vector. It is shown in the UI as a group of three scalar sliders. The vector widget obeys the UI minimum/maximum settings but not the value minimum/maximum.
Matrix The parameter represents a 4 by 4 matrix. It is shown in the UI, by default, as a mini-kinestate with translation, rotation and scaling sliders for each of the X, Y and Z axes, on its own page. It can be embedded in the layout by using the SRTTexture widget.
Texturespace This parameter represents a texture space to use. It differs from a regular integer in that XSI will seek these parameter types out and, based on its value, figure out which cluster properties to push for a given object. It is by default shown as an integer input slider but should use the TextureSpaceItem widget for user-friendlier input.
Texture A parameter of this type enables picking a specific image clip to use for this parameter. It is shown in the UI as an embedded image clip viewer.
Shader This parameter type is not represented in the PPG in any way but allows the user to connect another shader to it.
Reference The reference parameter provides a filtered object list that can be passed to the rendering engine, where the properties of those objects can be used in some way. It is shown in the UI as a list box (for multiple object selection) or a single text box (for single object selection). For more information on how references are used on the rendering side, see Using references.


Custom Property Set and Operator Attributes

TBD

Defaults

MetaShader

PortSet

Logic

See PPGLayout

Layout

See PPGLayout

Plugin

This page was last modified 18:48, 2 Nov 2010.
This page has been accessed 186385 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy