Slim File Format

Background
Global Context
Context Summary
Keyword Summary

Background

We use the Slim file format to encapsulate the state of Slim and to represent Slim extensions. The format is syntactically very simple and is based on the TCL programming language (see http://tcl.sourceforge.net/). A TCL based parser can be built up quite trivially given the knowledge that each context, described below, supports a predefined set of legal commands. This notion that a only a certain set of keywords is meaningful at a given point in the parsing process is fundamental to all file formats and can be represented in modern TCL (post 8.0) using TCL's namespace facility. To write a TCL parser for the .slim file format, one could simply construct a number of namespaces each of which represents a parsing context and is comprised of a set of procedures which embody the set of keywords available in that context. Each keyword is implemented as a procedure whose arguments can either be fixed or variable in number according to standard TCL practice. Now, in order to parse a file, one must simply source it into the appropriate TCL context. The implementations of the keyword procedure must simply pull the arguments from their argument list and do something with them. Where keywords are used to represent hierarchical structure, the implementation must also make recursive calls to TCL's namespace eval command.

But, hey, we've already written such a parser so why should you care about the details? Suffice it to say that, well, people ask. In any event, the syntactic structure of .slim files is so simple that it may not be necessary to actually parse them. Simple sed or perl scripts could also be used to process them in interesting and automated ways. In any event we've included a stripped down version of a .slim file parser here for your perusal. Note that to put this parser to useful purpose you'll need to implement objects that accept all the messages and build up appropriate state.

But back to the task at hand. What exactly is the .slim file format? The first thing to keep in mind is that its actually just a TCL script. As such it abides by all the standard TCL conventions for commenting, new lines, braces and quotes. A .slim file is parsed by simply sourcing it into an appropriately prepared TCL interpreter.

Global Context

At the outermost scope, a Slim file must contain one or more slim commands. All slim data is nested within in the body of the slim command. Here's the format of the slim command:

slim version type creator body

Here, type can be one of: extensions, palette or appearance.

And here's a skeleton of a .slim file containing an encapsulated palette:

slim 1 palette slim {
    palette plt1 {
        function shadingmodel "Blinn_80" "pixar,Blinn" {
            identity 0ZgCEW39ZIB00000
            description {Mimics the Maya Blinn shader.}
            master {$torShaders/$INSTANCENAME}
            previewinfo {
               shadingrate 5
               objectsize 1
               objectshape Sphere
               frame 1
            }
            parameter color SurfaceColor {
              default {0 .25 1}
              provider connection
              detail varying {}
              label {Surface Color}
              connection 0ZgCEW39Z-F00000
            }
           ... more parameters...
        }
        ... more functions and instances ...
    }
    ... more palettes ...
}

As you can glean from this example context is everything. For example, the identity command is only meaningful in the context of an object that has an identity. Palette commands are only meaningful in places where palettes are expected and not, for example, where parameters are expected.

The remainder of this document details the various parsing contexts and the commands, or keywords, that are meaningful in these contexts. Keep in mind that, while the .slim file format is rather general, it is used for three primary purposes:

To store Slim extensions - templates, custom UIs
To encapsulate the current Slim state
To encapsulate a single Slim appearance.

But the best place to learn about the .slim file format is to simply peruse existing files. Fortunately there's no shortage of these. See, for example:

the output of the toslim utility program. When you import a .slo file, Slim uses the toslim utility to generate temporary .slim files.
the templates that ship with the system. These can be found at $RATTREE/lib/slim.
the results of saving one of your palettes.

Context Summary

context description

global The outermost scope of a TCL file.

slim The slim context is the container for all Slim data. A small set of keywords are legal within the slim context and depend on the type field of the slim command.

extensions The extensions context is valid only within the slim context and is used to collect any number of customui, expressionui and templates.

palette The palette context is valid within the slim context and the palette context. Palettes are containers of appearances.

appearance - instance, template, function The appearance context is an abstract context representing the similarity between instances, templates and functions. Appearances are containers of properties.

instance The instance context is valid within palette contexts. An instance is an appearance that's based on an externally defined shader. Instances are containers of properties.

template The template context is valid within extensions contexts. A template is an appearance that's used to generate functions and is fundamental to Slim's shader creation features. Templates are containers of properties.

function The function context is valid within palette and function contexts. A function is an appearance that's based on a template.

property - parameter, collection, attribute, torattribute The property context is valid within appearance contexts and is an abstraction encompassing the parameter, collection, attribute and torattribute contexts.

parameter The parameter context is valid within the appearance and collection contexts. Parameters are used to collect all information associated with a single parameter of an appearance.

collection The collection context is valid within the appearance and collection contexts. Collections are containers for parameters and can have a custom UI. Collections are also used to represent higher order datatypes like shadingmodels and arrays.

attribute The attribute context is valid within appearance and collection contexts. Attributes are used to collect all information associated with a single RenderMan attribute. Attributes differ from parameters only in that they are not formal parameters to an appearance.

torattribute The torattribute context is valid within appearance and collection contexts. TORAttributes are used to collect all information associated with a single TOR attribute. TORAttributes differ from parameters and attributes only in that they are not formal parameters to an appearance and have no one-to-one RIB representation.

previewinfo The previewinfo context is valid only within appearance context. It's used to collect all information related to preview rendering.

cmdui The cmdui context is valid only within the extensions context. It is used to collect all information associated with a custom command user interface.

customui The customui context is valid only within extensions contexts. It's used to collect all information associated with a custom user interface.

expressionui The expressionui context is valid only within the extensions contexts. It is used to collect all information associated with a custom expression user interface.

Keyword Summary

keyword description context

access a sets a parameter's access mode. Value values are input (default) and output. parameter

attribute type nm body creates a new attribute in the current appearance. type is one of the primitive types: float, color, string, point, vector, normal, matrix. Nm is the name of the attribute. Additional characteristics of the attribute can be nested within the body. appearance, collection

cmdui nm body registers a new cmdui under the current vendor namespace name nm. The body argument is used to nest the TclTkSource and invocation keywords. A cmdui appears within Slim as a menu command which, when invoked, executes associated TCL extensions. extensions

collection type nm body creates a new collection property and adds it to the current appearance. type is the data type of the collection. nm is the collection's name and all other characteristics can be nested within the parameter. Collections are used to group parameters and attributes as well as to construct higher order data types. They should also be used to represent RenderMan array parameters. appearance, collection.

connection id establishes that a parameter is connected to the function whose id is id. collection, parameter

customui nm body registers a new custom ui under the current vendor namespace and named nm. The body argument is used to nest the TclTkSource keyword which contains the source for the customui widget. extensions

default d establishes a default value for a parameter. Non scalar data types should be embedded within braces or quotes according to standard TCL syntax. parameter, attribute, torattribute

description d sets the description for the current context. palette, appearance, property

detail d default flags sets the detail field for the current parameter. The detail is used to determine where a parameter can be connected to other functions. Valid values are: uniform, varying and mustvary. The default field can be used in the mustvary case to establish a default connection.   In this case the value should be the template ID of the default connection. You can optionally use the "inline" flag to specify that the connection should be an inline connection. parameter

display d sets the display mode field for the current property. Useful to hide parameters from the user. Valid values: hidden, visible. property

drawmode m sets the drawmode field for the current collection. Used to disable the drawing of the collection widget. Valid values: all, children. collection

expressionui type nm body registers a new expression ui. type is the data type that the expressionui can be used for, nm is a descriptive label for the expression ui. body is used to nest the definition of the expressionui and must contain a LaunchExpression keyword. extensions

frame f sets the frame for preview rendering purposes. previewinfo

function type nm template body creates a new function object in the current context. type is the function's return type, nm is function's descriptive name, template is the template ID of the template that the function is based on.   Body is used to nest all the properties of the function. palette, function

icon i sets the icon for an appearance. icons are represented in a special compressed ASCII form that can be easily parsed. appearance

identity id sets the identity for the current appearance. This identity is used to establish connections between functions within Slim and to establish a relationship between a client's geometric objects. appearance

index i sets the array index of a parameter. Parameters are deemed array elements when their index is not -1 and they are members of a collection. parameter

instance type nm master body creates a new instance object and adds it to the current palette. type is the instance's type - surface, displacement, volume, light. nm is the descriptive label for the appearance and master is a string representing the instance's master. It is this string that's used to invoke the shader via the RIB file. body is used to nest additional properties of the instance. palette

invocation menupath cmd registers an invocation for the current cmdui. You can have any number of invocations for a given cmdui and these will appear in Slim menus as provided by the menupath argument. Currently two root menus are supported: PaletteEditor and AppearanceEditor. cmdui

label l sets the label for the current object. Labels are used only for display purposes.   Property names are not editable and must uniquely represent a property within the context of an appearance. property

LaunchExpression l sets the launch expression for a custom expression ui. Slim automatically substitutes %f with the name of the temp file used to transmit the expression. expressionui

lighttype t sets the lighttype for a lightsource appearance. Valid values are: distance, spot, point and environment. appearance

master m sets the master reference for functions. This is used to both generate shaders as well as to reference the shaders in the RIB file. function

modified time sets the time when the appearance was last modified. This field is used to maintain shader dirty status between slim sessions. See this note for more details. function

msghandler body sets the list of handler actions for messages of a parameter. Body consists of messages (SetValueProvider, SetConnection, SetValue) and the handler code to be executed. Slim substitutes %obj for the parameter receiving the message. parameter

node id x y specifies the location of an appearance node within a graphArea. graphArea

objectshape s sets the object shape for preview rendering. Valid values are: Sphere, Cylinder, Torus, Cube, Teapot, Plane, previewinfo

objectsize s sets the object size for preview rendering. previewinfo

offset x y sets the x,y offset of the current graphArea graphArea

palette nm body creates a new palette object named nm and adds it to the current context. slim, palette

palettereference file causes the palette described in file to be loaded. The palette is marked external. slim

parameter type nm body creates a new parameter and adds it to the current context. type is the data type of the parameter and should be one of the RenderMan primitive data types: float, point, vector, normal, color, string, matrix. nm is the parameter's name and must be unique within the appearance. body is used to nest additional information about the parameter. appearance, collection

previewinfo body collects all information related to preview rendering for an appearance. appearance

provider p sets the provider for a property. The provider determines where the value of a parameter is obtained from. Valid values are: constant, variable, expression, connection. collection, parameter

range r sets the parameter's range for GUI purposes. The format of range depends on the subtype of the parameter. For scalar value the range is a vector comprised of a min, max and optional resolution field: {0 1 .01}. For selector subtypes, the range is a list of pairs representing the label and value for a menu of options:
{XYZ 0 X 1 Y 2 Z 3} parameter, attribute, torattribute.

RSLDefine expr registers expr as a preprocessor definition (#define) to be output in RSL code generation process. This is generally useful for templates of type StaticFunction only. For DynamicFunctions and DynamicShaders, we recommend the use of the new include & define keywords. template

RSLFunction body sets the RenderMan Shading Language source code for the current template. template

RSLInclude file registers file as a preprocessor include (#include) to be output in RSL code generation process. This is generally useful for templates of type StaticFunction only. For DynamicFunctions and DynamicShaders, we recommend the use of the new include & define keywords. template

RSLMain body sets the RenderMan Shading Language source code generator for the current template. template

RSLSource type body sets the RenderMan Shading Language source code for the current template. type determines whether the source is quoted verbatim or used to generate RSL. Valid values for type are:

StaticFunction

DynamicFunction

DynamicShader

template

shadingrate s sets the shadingrate for preview rendering purposes. previewinfo

slim version type creator body initializes the slim parsing context. version is used to control parsing behavior and should be set to 1. type is the file's type and should be set to one of: extensions, appearance or palette. global

state s sets the state of collection widgets. Valid values are: open, closed, locked. collection

subtype s sets the subtype for the current property. Valid values are: slider, vslider, switch, selector, bigstring, environment, reflection, shadow, depth, texture. property

userdata data sets user data for a property, appearance or palette. userdata consists of a list of name/value pairs as set by the user. property, palette, appearance

userrange range sets the range for a parameter with a value or precision that has gone beyond the recommended range as specified in a template. parameter

TclTkSource body sets the TCL/Tk source for the current custom ui or cmdui. customui, cmdui

torattribute type nm body creates a new torattribute and adds it to the current appearance. type is one of the primitive RenderMan data types. nm is the identifier for the torattribute and must be unique within the appearance. body is used to nest additional information about the torattribute. appearance, collection

value v sets the value of the current parameter. Non scalar data types should be embedded within braces or quotes according to standard TCL syntax. parameter, attribute, torattribute

Prev | Next

context	description
global	The outermost scope of a TCL file.
slim	The slim context is the container for all Slim data. A small set of keywords are legal within the slim context and depend on the type field of the slim command.
extensions	The extensions context is valid only within the slim context and is used to collect any number of customui, expressionui and templates.
palette	The palette context is valid within the slim context and the palette context. Palettes are containers of appearances.
appearance - instance, template, function	The appearance context is an abstract context representing the similarity between instances, templates and functions. Appearances are containers of properties.
instance	The instance context is valid within palette contexts. An instance is an appearance that's based on an externally defined shader. Instances are containers of properties.
template	The template context is valid within extensions contexts. A template is an appearance that's used to generate functions and is fundamental to Slim's shader creation features. Templates are containers of properties.
function	The function context is valid within palette and function contexts. A function is an appearance that's based on a template.
property - parameter, collection, attribute, torattribute	The property context is valid within appearance contexts and is an abstraction encompassing the parameter, collection, attribute and torattribute contexts.
parameter	The parameter context is valid within the appearance and collection contexts. Parameters are used to collect all information associated with a single parameter of an appearance.
collection	The collection context is valid within the appearance and collection contexts. Collections are containers for parameters and can have a custom UI. Collections are also used to represent higher order datatypes like shadingmodels and arrays.
attribute	The attribute context is valid within appearance and collection contexts. Attributes are used to collect all information associated with a single RenderMan attribute. Attributes differ from parameters only in that they are not formal parameters to an appearance.
torattribute	The torattribute context is valid within appearance and collection contexts. TORAttributes are used to collect all information associated with a single TOR attribute. TORAttributes differ from parameters and attributes only in that they are not formal parameters to an appearance and have no one-to-one RIB representation.
previewinfo	The previewinfo context is valid only within appearance context. It's used to collect all information related to preview rendering.
cmdui	The cmdui context is valid only within the extensions context. It is used to collect all information associated with a custom command user interface.
customui	The customui context is valid only within extensions contexts. It's used to collect all information associated with a custom user interface.
expressionui	The expressionui context is valid only within the extensions contexts. It is used to collect all information associated with a custom expression user interface.

keyword	description	context
access a	sets a parameter's access mode. Value values are input (default) and output.	parameter
attribute type nm body	creates a new attribute in the current appearance. type is one of the primitive types: float, color, string, point, vector, normal, matrix. Nm is the name of the attribute. Additional characteristics of the attribute can be nested within the body.	appearance, collection
cmdui nm body	registers a new cmdui under the current vendor namespace name nm. The body argument is used to nest the TclTkSource and invocation keywords. A cmdui appears within Slim as a menu command which, when invoked, executes associated TCL extensions.	extensions
collection type nm body	creates a new collection property and adds it to the current appearance. type is the data type of the collection. nm is the collection's name and all other characteristics can be nested within the parameter. Collections are used to group parameters and attributes as well as to construct higher order data types. They should also be used to represent RenderMan array parameters.	appearance, collection.
connection id	establishes that a parameter is connected to the function whose id is id.	collection, parameter
customui nm body	registers a new custom ui under the current vendor namespace and named nm. The body argument is used to nest the TclTkSource keyword which contains the source for the customui widget.	extensions
default d	establishes a default value for a parameter. Non scalar data types should be embedded within braces or quotes according to standard TCL syntax.	parameter, attribute, torattribute
description d	sets the description for the current context.	palette, appearance, property
detail d default flags	sets the detail field for the current parameter. The detail is used to determine where a parameter can be connected to other functions. Valid values are: uniform, varying and mustvary. The default field can be used in the mustvary case to establish a default connection. In this case the value should be the template ID of the default connection. You can optionally use the "inline" flag to specify that the connection should be an inline connection.	parameter
display d	sets the display mode field for the current property. Useful to hide parameters from the user. Valid values: hidden, visible.	property
drawmode m	sets the drawmode field for the current collection. Used to disable the drawing of the collection widget. Valid values: all, children.	collection
expressionui type nm body	registers a new expression ui. type is the data type that the expressionui can be used for, nm is a descriptive label for the expression ui. body is used to nest the definition of the expressionui and must contain a LaunchExpression keyword.	extensions
frame f	sets the frame for preview rendering purposes.	previewinfo
function type nm template body	creates a new function object in the current context. type is the function's return type, nm is function's descriptive name, template is the template ID of the template that the function is based on. Body is used to nest all the properties of the function.	palette, function
icon i	sets the icon for an appearance. icons are represented in a special compressed ASCII form that can be easily parsed.	appearance
identity id	sets the identity for the current appearance. This identity is used to establish connections between functions within Slim and to establish a relationship between a client's geometric objects.	appearance
index i	sets the array index of a parameter. Parameters are deemed array elements when their index is not -1 and they are members of a collection.	parameter
instance type nm master body	creates a new instance object and adds it to the current palette. type is the instance's type - surface, displacement, volume, light. nm is the descriptive label for the appearance and master is a string representing the instance's master. It is this string that's used to invoke the shader via the RIB file. body is used to nest additional properties of the instance.	palette
invocation menupath cmd	registers an invocation for the current cmdui. You can have any number of invocations for a given cmdui and these will appear in Slim menus as provided by the menupath argument. Currently two root menus are supported: PaletteEditor and AppearanceEditor.	cmdui
label l	sets the label for the current object. Labels are used only for display purposes. Property names are not editable and must uniquely represent a property within the context of an appearance.	property
LaunchExpression l	sets the launch expression for a custom expression ui. Slim automatically substitutes %f with the name of the temp file used to transmit the expression.	expressionui
lighttype t	sets the lighttype for a lightsource appearance. Valid values are: distance, spot, point and environment.	appearance
master m	sets the master reference for functions. This is used to both generate shaders as well as to reference the shaders in the RIB file.	function
modified time	sets the time when the appearance was last modified. This field is used to maintain shader dirty status between slim sessions. See this note for more details.	function
msghandler body	sets the list of handler actions for messages of a parameter. Body consists of messages (SetValueProvider, SetConnection, SetValue) and the handler code to be executed. Slim substitutes %obj for the parameter receiving the message.	parameter
node id x y	specifies the location of an appearance node within a graphArea.	graphArea
objectshape s	sets the object shape for preview rendering. Valid values are: Sphere, Cylinder, Torus, Cube, Teapot, Plane,	previewinfo
objectsize s	sets the object size for preview rendering.	previewinfo
offset x y	sets the x,y offset of the current graphArea	graphArea
palette nm body	creates a new palette object named nm and adds it to the current context.	slim, palette
palettereference file	causes the palette described in file to be loaded. The palette is marked external.	slim
parameter type nm body	creates a new parameter and adds it to the current context. type is the data type of the parameter and should be one of the RenderMan primitive data types: float, point, vector, normal, color, string, matrix. nm is the parameter's name and must be unique within the appearance. body is used to nest additional information about the parameter.	appearance, collection
previewinfo body	collects all information related to preview rendering for an appearance.	appearance
provider p	sets the provider for a property. The provider determines where the value of a parameter is obtained from. Valid values are: constant, variable, expression, connection.	collection, parameter
range r	sets the parameter's range for GUI purposes. The format of range depends on the subtype of the parameter. For scalar value the range is a vector comprised of a min, max and optional resolution field: `{0 1 .01}`. For selector subtypes, the range is a list of pairs representing the label and value for a menu of options: `{XYZ 0 X 1 Y 2 Z 3}`	parameter, attribute, torattribute.
RSLDefine expr	registers expr as a preprocessor definition (#define) to be output in RSL code generation process. This is generally useful for templates of type StaticFunction only. For DynamicFunctions and DynamicShaders, we recommend the use of the new include & define keywords.	template
RSLFunction body	sets the RenderMan Shading Language source code for the current template.	template
RSLInclude file	registers file as a preprocessor include (#include) to be output in RSL code generation process. This is generally useful for templates of type StaticFunction only. For DynamicFunctions and DynamicShaders, we recommend the use of the new include & define keywords.	template
RSLMain body	sets the RenderMan Shading Language source code generator for the current template.	template
RSLSource type body	sets the RenderMan Shading Language source code for the current template. type determines whether the source is quoted verbatim or used to generate RSL. Valid values for type are: StaticFunction DynamicFunction DynamicShader	template
shadingrate s	sets the shadingrate for preview rendering purposes.	previewinfo
slim version type creator body	initializes the slim parsing context. version is used to control parsing behavior and should be set to 1. type is the file's type and should be set to one of: extensions, appearance or palette.	global
state s	sets the state of collection widgets. Valid values are: open, closed, locked.	collection
subtype s	sets the subtype for the current property. Valid values are: slider, vslider, switch, selector, bigstring, environment, reflection, shadow, depth, texture.	property
userdata data	sets user data for a property, appearance or palette. userdata consists of a list of name/value pairs as set by the user.	property, palette, appearance
userrange range	sets the range for a parameter with a value or precision that has gone beyond the recommended range as specified in a template.	parameter
TclTkSource body	sets the TCL/Tk source for the current custom ui or cmdui.	customui, cmdui
torattribute type nm body	creates a new torattribute and adds it to the current appearance. type is one of the primitive RenderMan data types. nm is the identifier for the torattribute and must be unique within the appearance. body is used to nest additional information about the torattribute.	appearance, collection
value v	sets the value of the current parameter. Non scalar data types should be embedded within braces or quotes according to standard TCL syntax.	parameter, attribute, torattribute