RenderMan Repository  
Home Index Search FAQ Offsite Shaders Examples Pubs Utils

sl2slim

What's on this page?


Introduction

Slim is a shader management tool from Pixar. It is part of RenderMan Artist Tools.

sl2slim just works on the subset of Slim that deals with shader parameter control. sl2slim is a Perl script that allows encoding Pixar slim parameter controls directly inside a RenderMan shader. It should work fine on surface, displacement, light, and imager shaders. It should with the following types: float, string, point, normal, vector, color, and matrix. Pretty much everything that was available as of prman3.9.

Example simple shader : 


surface simpleshader (
   float useSimple = 0;
   float simpleType = 0;
)
{
   /* perform some calculations for surface */
}


Example simple shader with slim encodings: 


surface simpleshader (
  float useSimple = 0;   /* type switch
                           desc { Turn on to use. A simple example shader
                                  parameter switch. } */
  float simpleType = 0;  /* type selector
                           range { "spot" 0
                                   "omni" 1
                                   "directional" 3 }
                           desc  { An example of encoding a slim selector} */
)
{
    /* perform some calculations for surface */
}

Example of sl2slim output with slim encodings :


Encode

Here are the following encodings (and their slim expansions) that are available:
def     default
desc    description
expr    expression
name    label
provider        provider
range   range
type    subtype
vis     display
cat     Allows grouping of parameters with same name under a single chicklet

Description

sl2slim works by placing the encoding in comments at the end of a parameter statement. More precisely, the encodings must be in the first comment just after the semi-colon (';') completing a parameter statement.
surface myshader (
   float myparm1 = 0; /* desc { Example parameter showing how to encode
                                   a description for slim } */
   float flag = 0;    /* type switch 
                         desc { Example flag parameter } def 1 */
Take note of the paramter 'flag', it has one default behavior when in Mtor and another when not using Mtor. . .

Only one parameter declaration is allowed per statement.

float parmA;         // will make sl2slim happy
float parmB;         // will make sl2slim happy

float parm1, parm2;  // will produce a bad slim file

More Examples

Excerpts from l_uber:

/* Shadow mapped shadows */
string shadowname = "";   /* type shadow desc {Under MTOR the common
                            setting for this is [shdname $OBJNAME].} */

The above example sets the subtype to shadow and a description.

float shadowblur = 0.01; /* range {0 1 .001} type slider
      desc {how soft to make the shadow edge, expressed as a percentage of the width of the entire shadow map.} cat miscShadow */

This example sets up a slider range 0-1 in .001 increments. This parameter is grouped with other parameters that belong to the miscShadow category.

  float shadownsamps = 16;  /* range {
        "1" 1
        "4" 4
        "9" 9
        "16" 16
        "25" 25
        "36" 36
        "64" 64
      }

      type selector desc {Controls supersampling of the shadowmap.}
      cat miscShadow */

This example sets up a selector with a default of 16 and a selector range from 1 to 64.

color shadowcolor = 0; /* provider expression
     expr {[mattr $OBJNAME.shadowColor $f]}
     desc {Shadows (i.e. those regions with occlusion as defined by any or all of the shadow map, ray cast, or blocker) don't actually have to block light. In fact, in this shader, shadowed regions actually just change the color of the light to shadowcolor. If this color is set to (0,0,0), it effectively blocks all light. But if you set it to, say (.25,.25,.25), it will make the shadowed regions lose their full brightness, but not go completely dark. Another use is if you are simulating sunlight: set the lightcolor to something yellowish, and make the shadowcolor dark but somewhat bluish. Another effect of shadows is to set the __nonspecular flag, so that the shadowed regions are lit only diffusely, without highlights.}
     cat miscShadow */

This example has tcl expressions allowing it to get its settings from Maya. In this case it sets the shadow color to whatever the Maya light shadow color is set to. This parameter also belongs to the miscShadow category.

   /* Basic intensity and color of the light */
  uniform float lighttype = 0;  /* type selector
                                range {
                                "spot" 0
                                "omni(point)" 1
                                "area(BMRT)" 2
                                "directional" 3
                                }
                                def {0}
                                provider expression
                                expr {[if {[mel "objectType $OBJNAME"] == "pointLight"}
                                {return 1}
                                else
                                {[if {[mel "objectType $OBJNAME"] == "spotLight"}
                                {return 0}
                                else
                                {return 3}]}
                                ]}

        desc {The type of light source. Use spot for lights that point in a particular direction, from a particular position (ie. spot). Use omni for light to cast light in all directions (ie. point). Use distant for lights that point in a particular direction, from any position (ie. distant).} */
  float parallelrays = 0;  /* range {0 1} type switch
                             provider expression
                             expr {[if {[mel "objectType $OBJNAME"] ==
                             "directionalLight"} {return 1} else {return 0}]}
                             desc {when off, the light apepar to eminate from 
                             a single point (i.e. the rays diverge). When on, 
                             the light rays are parallel, as if from an 
                             infinitely distant source (like the sun).} */

Disclaimer

The script isn't very robust and can be broken very easily. If I had realized how detailed I would have had to correctly parse the shading language, I would have started with a Bison grammar so the parsing would be more robust.

1) Most of the standard RC shaders won't work. Remember one parameter per statement.

2) The first comment after the ';' ending a parameter statement must contain slim encodings. Any comments after that one can contain, well, comments. You don't have to have an encoding comment after a parameter statement. But if for some reason you want to have some regular comments after one, then you must preceede that comment with with an encoding comment or an empty comment.

Other known problems


Util

sl2slim.tar contains:
sl2slim.displacement_dat
sl2slim.light_dat
sl2slim.surface_dat
sl2slim.perl (file saved as .perl instead of .pl so web-browser's won't try to execute it.)

Usage: sl2slim.pl [-IcppDir|...] SLFILES

cppDir is the directory to search for include files.
SLFILES is one or more shader files to process.
sl2slim.pl will read through a shader source file optional 
    slim encodings to create a .slim file with the 
    same base name as the shader.
In order for the script to work, it will need to be modified to give the C processor is.

Typically I just have something like the following file in my Makefiles

.sl.slim:

Example shader and .slim files. l_uber.sl l_uber.slim s_pplastic.sl s_pplastic.slim


RenderMan is a registered trademark of Pixar. The RenderMan Repository is maintained by Pixar's RenderMan Products Group
Last modified: Sat Aug 4 22:46:14 PDT 2001