Cutter - Automatic Conversion of Shaders and RSL Functions to Slim Files

return to main index

contents

• introduction
• appearance slim docs
• template slim docs
• custom templates
• ui-hints
• table 1 ui-guessing
• table 1 ui-specifics
• hybrid
• automatic copying of shaders & slims
• limitations

This tutorial provides a detailed description of Cutter's ability to automatically generate Slim™ template and appearance files. Although the tutorial includes a brief description of these files it is assumed the reader has some familiarity with Slim palettes and appearance editors. The tutorial is targeted at RenderMan ArtistTools™. However, these notes will require revision once Pixar's new high end product, RenderMan Studio™ is released.
   Malcolm Kesson. May 2007

Side Note: To avoid confusion, when this tutorial refers to the Slim application it will capitalize the first letter of the word Slim. Slim's text files, on the other hand, will be referred to in all lower case ie. slim.

Slim scripts are text files that come in two flavors - appearance slims and template slims. Both are built on top of Tcl and both are identified by their ".slim" file extension. An appearance slim file contains GUI information that defines the interface presented by a Slim editor to an artist for the purpose of adjusting the parameters of a shader. By itself an appearance slim file is useless - it must be accompanied by a pre-compiled shader. A template file, on the other hand, is not associated with a pre-compiled shader so in addition to having GUI information it also contains Tcl code that is used by Slim to write and compile a shader "on-the-fly".

A shader (plus an optional appearance slim file) imported into Slim appears as a "non-connectable/static" shading node. A node created from a template slim file appears as a "connectable/dynamic" shading node.

A full description of the slim file format can be found at within the Rat documentation at,

    programmingRAT/customizing_slim/slimfile.html
    programmingRAT/customizing_slim/templatesAdvanced.html

Fundza has a rudimentary, though quite handy, slim quick reference for those who wish to write slim files by hand. Cutter can assist a shader writer by automatically generating both appearance and template slim files.

a p p e a r a n c e    s l i m s
When the renderer in the RmanTools->Options->Environment popup menu (figure 1) is set to Pixar, Cutter automatically generates an appearance slim document for the RSL source code file being compiled. For example, if cloth.sl is compiled, Cutter will generate an appearance file called cloth.slim. Cutter saves its appearance slim files in the same directory as the compiled shader file. A users preferred shader directory, figure 2, can be set using the

    Edit->Show Preferences->Rman->User->shaders

By including user-interface hints within the comments that "accompany" the declaration of a shaders parameters (instance variables) a shader writer can easily take advantage of Cutters ability to "tune" the way a shader is presented by a slim editor.

t e m p l a t e    s l i m s
Cutter can generate a template slim document from most types of shaders or Rsl functions - but not functions that return void or an array. For example, figure 3 shows the code for an RSL function, taken from the Advanced RenderMan book, being exported as a slim template. After saving the slim document it must be loaded or read by Slim.

figure 3

figure 1

figure 2 - setting the shaders directory

This section focuses on the loading and use of templates produced by Cutter. First, make sure you have the "expert menu's" option activated in Slim->Preferences. Rat 6.5 has a bug that prevents the Preferences window displaying this option. To work-around, use the following command into a Mel script window,

    slimcmd SetPref ExpertMenus 1

A custom slim file can be read by Slim via its console - figure 4.

figure 4

To create a node from the custom template use the "Preloaded" menu item (figure 5). Alternatively, Cutter can "tell" Slim to read your template. In Maya enter the following command,

    commandPort -n ":2222"

Cutter's execute command (keyboard short cut alt+e or control+e) will send a Mel command to Maya that will cause Slim to,

1. open a palette window
2. add a node created from your template
3. open an editor for the node

figure 5

c u t t e r   :    u i - h i n t s
When converting a shader to an appearance or template, or a Rsl function to a template, Cutter uses each parameters or arguments data type, name, default value and commented text to define the GUI that Slim will present to the user. Cutter determines what information to put into a slim file in a two step process.

First, it guesses what each parameter/aguement should look like when they are displayed in a Slim editor. The guesses are based on the data type and name of each shader parameter or function argument.

Next, Cutter looks for a user-interface hint (ui-hint) within any comments associated with a parameter or argument. Cutter considers any text it finds within "[" and "]" brackets as possible sources of information that it can use to refine the "look" of the GUI.

Table 1 gives a full listing of the rules that it applies when making a guess about the "look" of a GUI. Table 2 lists what Cutter considers to be valid ui-hints.

float param
If param begins with "K",
for example, float Kz = 0;
or the param name is either,
  roughness, blend, mix,
  smooth or step
 
A guess is that a slider should
have a range 0 to 1.

string param
A guess is made about the type
of popup menu that should appear
beside the text field based on 
a partial match of param with
the following,
  tex, tra, 
  env, 
  filter,
  shad, 
  refl, 
  world, shader, 
  camera, current, coord

The list of partial names on
the left are associated with
the following Slim subtype's.
Subtypes configure the popup
menu that appears next to a
text field.
  "texture"
  "environment"
  "filter"
  "shadow"
  "reflection"
  "spacename"
  "spacename"                   

float param /* [range hint] */
examples
  /* [-2 5]   */
  /* [-2 5 1] */
  /* [0 or 1] */
  /* [low med high 1 2 3] */

 
"slider" range from -2 to 5
"slider" 1 unit increments
"switch" on or off
"selector" popup names/values

string param /* [string hint] */
examples
  /* [texture]     */
  /* [environment] */
  /* [filter]      */
  /* [shadow]      */
  /* [reflection]  */
  /* [spacename]   */

ANY param /* [collection hint] */
examples
 /*[collection foo]             */
 /*[collection foo 0 or 1]      */
 /*[collection foo pixar,FNoise]*/

ANY param /* [inline hint] */
examples
  /* [pixar,FNoise] */

ANY param /* [expression hint] */
examples
/*[exp {lerp(0.0,1,$pct}]*/
/*[expr {lerp(0.0,1,$pct}]*/
/*[expression {lerp(0.0,1,$pct}]*/

Defining shading nodes with template slim files provides an artist with the flexibility to connect its inputs to a shading network. On the other hand, limiting an artist to using pre-compiled shaders prevents them from using the node as part of a shading network. Between these two "extremes" there is a hybrid approach in which the artist is given a custom node, defined by a slim template, but some of its parameters are hard-wired ie. pre-connected, to specific nodes. Using the "inline hint" shown in the above table ensures a parameter is pre-connected and that the connection cannot be broken.

c o p i e s    o f    s h a d e r   &   s l i m    d o c s
The slim appearance documents include the full path to "their" shader, for example,

    slim 1 appearance slim {
       instance surface "foo" "//C/shaders/foo" {

This is fine when the shader (plus slim appearance file) is imported into Slim and the Maya scene is rendered on the users local computer but the absolute path causes errors when a Maya project directory is moved to a render farm.

The path to the shader can be relative if the shader (and its slim document) are stored in Maya's project "rmanshader" or "rib" directory. In addition to specifying a fixed "shaders" directory, users can nominate an additional (temporary) directory in which copies of their ".slo" and ".slim" files can be saved by Cutter - figure 6. For example, if the user selects the "rmanshader" directory the path to the shader in a slim appearance document would be of the form,

    slim 1 appearance slim {
       instance surface "foo" "rmanshader/foo" {

figure 6

There's probably lots of them, but here are the known ones!

#include's
If the include statement does not specify the full path to a header, Cutter applies a number of rules when determining what path to provide in the output template document

System headers ie. #include <foo.h>, appear in the template file prefixed with the full path to the lib/shaders directory of the Pixar installation. Cutter does not check the existence of the file.

Include statements such as #include "foo.h" cause Cutter to search for the header file in the following locations.

1. the same directory as the source document
2. the RSL source directory specified in the Preferences (figure 2)
3. the shaders directory specified in the Preferences (figure 2)
4. the system headers directory

The first location in which the file is found will be used as the specification of the full path given to the slim output document. If the include file cannot be found it is specified "as is" in the output slim document - this will almost certainly cause an error later if the template is loaded into slim.

While it is acceptable to use header files that reference other headers when compiling a shader, it appears that slim template documents cannot do the same. Therefore, you will have to edit your include files so that they do not reference "secondary" headers. There may be a work-around but I do not know what it is!

shader instance variables and their default values
Cutter can "read" these assignments,

float foo = 5,
      koo = radians(5);

but not these assignments,

float foo = 1/(2 * PI);
float pp  = PI;

Cutter can handle fixed length arrays but not the newer kind of variable length arrays. For example, this is acceptable,

color nnn[3] = {1, (1,2,3), color(1)};

#define's
These cannot appear in the document from which a slim template will be generated. They must be moved into an include file. This may change in later versions of Cutter.

custom functions implemented in an SL document
Custom functions must be moved to an include file.

The Languages->Slim preferences panel (figure 6) enables a user to set their "studio", "author" and "prefix" signatures. These items are used to identify the slim templates generated by Cutter.

figure 6