Cutter
Automatic Conversion of Shaders and RSL Functions to Slim Files

return to main index

Introduction

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.

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 (RenderMan Artist Tools RAT) or HyperShade (RenderMan Studio RMS) appears as a "non-connectable/static" shading node. A template slim file when read by Slim appears as a "connectable/dynamic" shading node. When using RMS a template cannot be referenced directly by HyperShade. However, once Slim has used the template file to generate and compile a shader it can be added to the scene ie. HyperShade loads the newly compiled shader.

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

Refer to the tutorial "Slim Quick Reference" for examples of slim "parameter blocks". Cutter can assist an artist by automatically generating both appearance and template slim files.

Appearance Slim Files

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.

Figure 1

For example, if the source code for Pixar's classic cloth.sl shader 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.

Figure 2 - Setting the shaders directory

A users preferred shader directory, figure 2, can be set using the

By including user-interface hints within the comments that "accompany" the declaration of a shaders parameters (instance variables) an artist can easily take advantage of Cutters ability to "tune" the way a shader is presented by HyperShade (RMS) or Slim (RAT).

Template Slim Files

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

Cutter & Custom Templates

This section focuses on the loading and use of templates produced by Cutter. First, the procedure for RAT will be dealt with followed by RMS.

RenderMan Artist Tools

Make sure you have the "expert menu's" option activated in

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).

Figure 5

RenderMan Studio

Make sure the "expert menu's" option is activated in

A custom slim file can be read by Slim via its console - figure 4. To create a node from the custom template you will need to dig around the "floats" sub-menus (figure 6).

Figure 6

Cutter and Maya's Command Port

Cutter is able to communicate with Maya via a port. In Maya enter the following command,

There is no particular significance to the port number "2222" but its the one that Cutter uses by default. It can be changed in Preferences - figure 7.

Figure 7

Assuming you have a template slim file open on Cutter's desktop execute the file using the keyboard shortcut, alt+e, control+e or apple+e. Cutter will write a temporary mel script into its own directory and then send a mel source command to Maya on the users chosen port. Depending on whether you are using RAT or RMS, Cutter will write the appropriate mel script that will cause Slim to,

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

Cutter & UI Hints

When Cutter writes an appearance or template slim file it parses the data for each shader/function parameter. Cutter reads the datatype, name, default value and any commented text that accompanies a parameter. Converting a parameter datatype, name and value to the appropriate Slim file format is straight forward. However, Cutter uses certain items of information "embedded" within the comments as a guide to how it should define the GUI that Slim will present to the artist. Cutter determines what information to put into a slim file in a two step process.

Step 1

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

Step 2

Next, Cutter looks for a user-interface hint (ui-hint) within the comments associated with a parameter. 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.

Hybrid

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 table 2 ensures a parameter is pre-connected and that the connection cannot be broken.

Copies of Shaders & their Appearance Slim Files

A slim appearance file generated by Cutter specifies the full path to the shader that "accompanies" the slim file, 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 locally but an absolute path causes errors when a Maya project directory is moved to a render farm for remote rendering.

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.

Figure 8

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" {

Limitations

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

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.

Signatures

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

Figure 9