Class 4: Slim, Part II

Manifolds and shader spaces

The MayaUV manifold is used to match Maya's texture coord assignments with RMan's. Assuming the Maya texture placement node is place2dTexture1, for the S and T values in the MayaUV node, enter these (Tcl) calls:

[st0 place3dTexture1]
[st1 place3dTexture1]

RIBBox, TclBox, SLBox

A RIBBox can contain arbitrary RIB statements. When attached to any node in the Maya scene hierarchy, MTOR will simply stream in (include) your RIBBox's RIB in the appropriate location in the overall generated RIB. A TclBox contains Tcl functions that are used in the associated RIBBox (assign both these to the same node in Maya).

This scene shows a TclBox/RIBBox combination.

An SLBox is used to hold arbitrary RSL code.. If you have a small chunk of code that you want to insert into the shade tree (eg. a float value derived from an occlusion brickmap), using an SLBox is the way to do so. For simpler code (eg. manipulating floats), the 'Combine' node (with 'Custom' for the 'Operation' parameter) is another option.

txmake, pointclouds, brickmaps, ptrender, ptfilter, ptviewer

HDR

'txmake' can also be used to convert .hdr images into .tex:
txmake -format tiff -envlatl -float hdr_image.hdr hdr_image.tex

point clouds

The 'Bakeable' appearance is under 'Color/Utility'. To the 'Color' attribute, hook up a color value to bake. "Bake Style" is "texturemap", and "BakeManifold" is "ST". Rendering this creates a .ptc pointcloud file, where the color is stored as a "_color" channel. Remember to attach a 'Bake' mapgen node to the camera.

'ptrender' can now be used to create a .tif (and 'ptviewer' to view the .ptc):

ptrender -size w h myimg.ptc _color myimg.tif
The .tif can be converted to a .tex as usual, using 'txmake'. Note that ptrender can directly output a .tex as well (using -dspy texture), but there is no way to specify flags for the .tex file generation.

To do baking in your own shader, use the bake3d() call, eg:

// 'c' contains the color value to bake..
bake3d("baked.ptc", "_color", point (s, t, 0), Nn, "coordsystem", "_disable", "_color", c);
The resulting baked.ptc can be used with ptrender to obtain a .tif file as shown above. Additional useful flags are "-project camera" or "-project uv", "-splat smooth" or "-splat diffusion", and "-depth float".

Here is a complete example of creating point-based occlusion brickmaps.


// By Hun, NIG-Imagestar (Korea)
// bake_areas.sl
surface
bake_areas(uniform string filename = "", displaychannels = "_area")
{
 normal Nn = normalize(N);
 float a = area(P, "dicing");
 float opacity = 0.333333 * (Os[0] + Os[1] + Os[2]);
 a *= opacity;
 if (a>0)
 bake3d(filename, displaychannels, P, Nn, "interpolate", 1, "_area", a);
 Ci = Cs * Os;
 Oi = Os;
}

ptfilter -filter occlusion -maxsolidangle 0.5 filename.ptc filename_occ.ptc
brickmake filename_occ.ptc filename_occ.bkm

brickmaps

'brickmake' is used to convert .ptc point clouds into .bkm brickmaps, eg.:
brickmake -maxerror 0 ptcloud.ptc brickmap.bkm
Here is a scene that employs 'brickmake'.

You can read in brickmaps in your own shader, like so:

// N0 is a normal, and c is the color variable which will contain the result
texture3d("brickmap.bkm", P, N0, "cs",c);

ptfilter

ptfilter can be used to process pointclouds, eg.
ptfilter -filter occlusion -maxsolidangle 0.05 -maxdist 20.0 -clamp 1 filename.ptc filename.tmp

// the brickmap will contain data in the "_occlusion" channel, and can be read 
// back like this (into 'occ', a float):
// texture3d("filename.bkm", P, Nn, "_occlusion", occ);
brickmake -maxerror 0.002 filename.tmp filename.bkm
Just like 'ptviewer' is used to view .ptc, 'brickviewer' is for brickmaps.

Slim templates

Slim templates are the preferred way of creating new shading blocks to use inside Slim. Reasons:

In addition to the notes below, see the RAT documentation for more details on writing templates. Also, the <PRManDistribution>/rat/lib/slim directory contains a lot of slim templates for you to study and learn from.

Before you load anything, under Renderman -> Slim -> Preferences -> Expert, turn 'Expert Menus' on. You can also turn expert mode on using this MEL call:

slimcmd SetPref ExpertMenus 1

Here is a really simple but functional .slim template, called basic.slim. Assuming it is in C:/temp, you can use the following MEL command to load it into Slim [note - another way to load your templates is to specify them in a slim.ini configuration file - see the Slim docs for details].

// loads the nodes found in basic.slim - after executing this line of MEL, you will be able to
// access these nodes under File -> Create Appearance -> Preloaded in any Slim palette
slimcmd slim ReadSlimFile "C:/temp/basic.slim"; 
There is also a third way to load .slim files. Do 'Renderman -> Slim -> Console' to get a Slim console window, and in it, type:
slim ReadSlimFile C:/temp/basic.slim

The following snapshot shows another template being loaded and instantiated:

After you load the basic.slim file, create a 'Const' appearance (File -> Create Appearance -> Preloaded -> Const) contained in the file. Open up the 'Const' appearance just created, then do File -> View RSL Source. You can see the Slim-generated .sl RSL source for this template. When you render, it is this source that gets compiled (using shader.exe) into a .slo. In principle, you could have typed up this RSL by hand.. It looks fancier than a typical human-created .sl. Eg. instead of

surface Ceramic_1()
{
we see
/* defines ----------------------------------*/
#define SLIM_TYPEID_surface 0
#define SLIM_TYPEID_displacement 1
#define SLIM_TYPEID_volume 2
#define SLIM_TYPEID_light 3
#define SLIM_VERSION 350
#define SLIM_SHADERTYPE surface
#define SLIM_SHADERTYPEID SLIM_TYPEID_surface
#define SLIM_INSTANCETYPE shadingmodel
#define SLIM_INSTANCENAME Ceramic_1

/* shader body ------------------------------*/
SLIM_SHADERTYPE
SLIM_INSTANCENAME (
)
{
Next, connect a 'Fractal' appearance to our Const's surface color ('Fractal' will feed a color to Const). Now view the RSL source again. You'll see that the code is now expanded to include Fractal's RSL too - Fractal's RSL gets called first (as a function), and its output color is in turn used as an input to Const. So what looks like arrow connections in the Slim palette are really RSL function calls that get chained.

The Const template in basic.slim can be simplified even more as follows:

### verybasic.slim - a minimal template definition
### the foll. template has a single input and two ouputs
slim 1 extensions gnomonsr {
 extensions gnomon gnosl {
  template shadingmodel Const {
       description "A barebones 'constant.sl' simplification"
       parameter color SurfaceColor {
   label "Surface Color"
   detail varying
   default ".5 .5 .5"
       }
   parameter color CI {
   detail varying
   default ".5 .5 .5"
   access output
   display hidden
       }
   parameter color OI {
   detail varying
   default ".5 .5 .5"
   access output
   display hidden
       }

       RSLFunction {
   void
   gnoslConst(
       color SurfaceColor;
               output color CI;
               output color OI;

           )
   {
     CI = SurfaceColor;
     OI = 1;
           } 
       } 
   } 
  } 
} 

Here's a workflow for developing .slim templates:
Now it is time to look at the contents of .slim files. There are two parts to any .slim template file:
In addition to templates being able to be hooked up to each other by the user, they can also be used inside other template definitions by the template writer. The way to do this is using 'detail mustvary". For example, in 'displacements.slim' is this parameter declaration:
parameter float Displacement {
	    detail mustvary
	    default 0
	}
The 'Displacement' float parameter (which will be used as a displacement amount) *has* to come from another 'float' template, eg. noise. The 'Displacement' parameter does not come with a preset float template hooked up to it, the user needs to supply one.

In the 'Warp' manifold template is this block of code:

template manifold Warp {
	    description "Returns points additively warped by vector-value
	    	Unless you choose to map the Surface Point parameter, the
		default behavior is to use ST coordinates."
	    parameter vector warper {
		label "Warp Function"
		detail mustvary "pixar,VBrownian"
		default 0
	    }
Here, the 'warper' vector-valued parameter will be supplied by a vector-valued template. But unlike the 'Displacement' above, here a default vector template is hooked up to get the user started. That is done by appending a template name (of the proper type) right next to 'detail mustvary'. In our example it is the string "pixar,VBrownian".

This way of being able to use pre-existing templates is very cool, since you can use existing vector providers, color providers etc. inside your own template definitions.

Examine as many .slim files as you can, to get ideas on how to write a variety of templates. As mentioned earlier, the RAT distribution includes a LOT of templates (for almost all the appearance choices available in the Slim menus), so that should be your starting point.

Here's a .slim file by ZJ, who's very active in the RMan/MEL community. It contains a bunch of GI-related templates.

This is an autogenerated .slim template from Malcolm Kesson's Cutter.


In addition to the static RSL code that you embed in a template, you can also use Tcl to dynamically alter what is being embedded, based on end-user's condition. Here's an example that comapares the two approaches:
static version
dynamic version

In addition to the static/dynamic variations shown above, you can also use RSLSource:
'switch' template