Cutter
Slim Template Scripts


return to main index



Introduction

The Cutter text editor is can assist artists create, edit and test slim scripts. There are two types of slim scripts - those that define the UI for a precompiled shader (.slo) imported into HyperShade and those that implement a shading node for use in the Slim editor. The former are called appearance slim scripts; the latter are called template slim scripts - both use the .slim file extension. How Cutter handles appearance slim scripts is the subject of the tutorial Cutter: Slim Appearance Scripts.



Figure 1


Template .slim Scripts

A template script implements one or more nodes for use with Pixar's Slim shading editor. Similar to an appearance, a template slim file contains GUI information but in addition it also contains code that is used by Slim to generate a "chunk" of RSL that becomes part of a shader that is compiled "on-the-fly" by Slim.



Figure 2


Artists can take advantage of Cutter's Slim-related functionality to create custom nodes either in a manual or semi-automatic fashion. An explanation and example of the former can be found at Cutter: Manual Slim Template Scripting This tutorial demonstrates how Cutter can be used to generate a template script (custom node) directly from a RSL function.


Converting a RSL Function to a Node

To demonstrate Cutter's ability to generate a custom node (template) from a trivial RSL function called "Flame" implemented in a .h (header file) named flame.h.


Listing 1 (flame.h)


void Flame(color    tip, 
                    base; 
            float   noisiness, 
                    blur; 
    output varying float resultF;
    output varying color resultRGB;) 
{
resultRGB =  mix(tip, base, t);
resultF = 1 - smoothstep(t - blur, t + blur, noisiness);
}

An example of a simple shader that uses the function is given next. Note that flame.h and flame_test.sl must be in same directory.


Listing 2 (flame_test.sl)


#include "flame.h"
  
surface
flame_test(float  Kfb = 1,
             freq = 6,
             blur = 0.02;
      color  top = color(1,0,0),
             lower = color(1,1,0) )
{
color flamecolor;
float flameopacity;
point p = transform("shader", P);
  
Flame(top, lower, noise(p * freq), blur, 
      flameopacity, flamecolor);
Oi = flameopacity * Os;
Ci = Oi * flamecolor * Kfb;
}

Figure 1 shows the "flame" effect applied to a polygon.

    Surface "flame_test"
            "Kfb" 1.0
            "freq" 9.0
            "blur" 0.020
            "top" [1.0 0.0 0.0]
            "lower" [1.0 1.0 0.0]
            
    Polygon "P" [-0.5 0 -0.5  -0.5 0 0.5  0.5 0 0.5  0.5 0 -0.5]
            "st" [0 0  0 1  1 1  1 0]


Figure 1


Step 1
Select the code of the Flame function. Right-mouse click and from the popup menu select "Export as Slim Node" - figure 2. The Slim template generated by Cutter can be viewed here. The type of template generated by Cutter is known as a "multiple" because it has more than one output.



Figure 2


When used in a shading network the Flame node must have its "noisiness" parameter connected to one of Slim's noise related nodes, such as,
    Noise
    Fractal
    WaveletNoise or
    Worley
The "top" and "lower" color parameters will also require manual adjustment - figure 3.



Figure 6


Inputs

Unlike the node derived from the surface shader (listing 1) in which the noise function was "hard wired", the new node can receive "noise" values from a variety of different nodes such as brownian, wavelet, turbulance etc.



brownian


wavelet


turbulance


Outputs

Since the new node is of "type" multiple rather than shadingmodel it's outputs (color and float) can provide values for down-stream nodes such as GPSurface.


More Examples of Using ui-hints

To avoid the necessity of making manual connections and adjustments to parameters the following ui-hints can be added as comments to the function.


Listing 4


void Flame(color     tip,      /* [default "1 0 0"] */
                    base;      /* [default "1 1 0"] */
            float    dir,      /* [inline "pixar,RSLVarsF" label "Ramp Direction"] */
                    noisiness, /* [inline "pixar,Turbulence" label "Noise Input"] */
                    blur;      /* [default 0.02] */
    output varying float opacity_out;
    output varying color color_out;) 
{
color_out =  mix(tip, base, dir);
opacity_out = 1 - smoothstep(dir - blur, dir + blur, noisiness);
}

A new template generated from the edited function presents the following interface in Slim.



Figure 7


More information about ui-hints can be found at Cutter: Ui-Hints for Slim.


Step 1 - Creating a Custom Node from a Surface Shader

Copy and paste the following code, taken from the tutorial RSL: Flames and Opacity, into Cutter. Make sure the shader code compiles using the keyboard shortcut alt+e or control+e or apple+e. Cutter is not able to export a valid template slim script unless the original RSL source code can be compiled.


Listing 1 - flame.sl


surface
flame(float  Kfb = 1,
             freq = 6;
      color  top = color(1,0,0),
             lower = color(1,1,0);
      string spacename = "shader")
{
point p = transform(spacename, P);
color surfcolor = mix(top, lower, t);
  
if(t > noise(p * freq))
    Oi = Os;
else
    Oi = 0;
  
Ci = Oi * Cs * surfcolor * Kfb;
}

Select the shader code and use to the right mouse button to raise the popup menu as shown below.



Figure 1


An untitled slim script will open on Cutter's desktop. The script does not require saving before it is previewed. A copy of the slim script can be found here.



Step 2 - Previewing the Node in Slim

Cutter can help preview the template in Slim via a socket (port). The following steps outline the process.

  • in Maya load the RfM plugin
  • open Slim by clicking on the shelf button
       
  • in Maya run the Mel command commandPort -n ":2222";
  • in Cutter press alt+e or control+e to execute the template.

Cutter executes the template writing two files, temp.mel and temp.slim, in its installation directory. It then sends a Mel source command via a socket (port) to Maya. The temp.mel script sourced by Maya executes a number of statements that commands Slim to read the temp.slim file. The temp.slim file is a copy of the template file on Cutter's desktop. The port opened by the commandPort Mel command is important only in as much as it must match Cutter's port preference - figure 2.



Figure 2


To open a Maya port on Windows 7 commandPort must be used twice ie.
      commandPort -n "localhost:2222";
      commandPort -n ":2222";

This is similar to Vista. However, with Vista "localhost" is preceded with a colon ie.
      ":localhost:2222"
On Windows 7 the colon should be omitted. After executing the template script a Slim editor window for the node will appear - figure 3.



Figure 3


Figure 4


Unlike the original shader from which the template was exported, the parameters of the node in Slim can receive inputs from other nodes - figure 4. However, because Flame.slim implements a shadingmodel node it cannot pass values to other nodes. The notes accompanying step 5 show how a node that both receives values from, as well as sends values to other nodes can be created by Cutter from a RSL function rather than a shader.



Figure 5


Templates can also be loaded "manually" using Slim's console window using the slim ReadSlimFile command - figure 5.



Step 3 - Publishing a Template

Once a template has been pre-viewed and considered useful it should be saved in a directory that will be sourced by Slim when it starts up. Detailed notes on this subject can be found in the tutorial "RfM: Customizing". In essence, getting Slim to source custom templates is relatively easy. Pixar's RenderMan for Maya requires an environment variable, RMS_SCRIPT_PATHS, to point to a directory (RfM_ini) in which it can find an initialization file named slim.ini. That file tells Slim where the custom templates are located (RfM_slim) followed by a sequence of TCL statements each of which commands Slim to read (load) a template.

1.   In the Maya.env file (maya/2013-x64/Maya.env) save the following text,
      RMS_SCRIPT_PATHS=FULL_PATH_TO/RfM_ini
2.   In the RfM_ini directory save a file named slim.ini,
3.   Save the following text in the slim.ini file,
      set templates FULL_PATH_TO/RfM_slim
      LoadExtension slim [file join $templates flame.slim] slim




Step 4 - Controlling Parameter Widgets

Values for the spacename parameter of the Flame node can be "camera", "world", "object" or "shader". The name of a user defined coordinate system could also be used but that option will be ignored. Rather than presenting a plain text field to the user of the ndoe it would be preferable to have a dropdown menu - a selector in Slim-speak. To export a new version of the template that includes a dropdown menu the RSL of the flame shader should be modified as shown below.


Listing 2


surface
flame(float  Kfb = 1,
             freq = 6,
             blur = 0.02;
      color  top = color(1,0,0),
             lower = color(1,1,0);
      float spacename = 4 /* [camera world object shader 1 2 3 4] */)
{
string sp = "shader";
if(spacename == 1)
    sp = "camera";
else if(spacename == 2)
    sp = "world";
else if(spacename == 3)
    sp = "object";
  
point p = transform(sp, P);
color surfcolor = mix(top, lower, t);
Oi = 1 - smoothstep(t - blur, t + blur, noise(p * freq));
Ci = Oi * Cs * surfcolor * Kfb;
}

Specifying the type of UI widget for a parameter is done by embedding a ui-hint in the comment associated with a parameter. A ui-hint is text that begins and ends with square brackets. For example, this ui-hint,
      [camera world object shader 1 2 3 4]
tells Cutter to specify a selector with text labels that have values 1 to 4.



Figure 4







© 2002- Malcolm Kesson. All rights reserved.