RMS - Ri Scripting I

RMS
Ri Scripting

Introduction

RenderMan Studio (RMS) allows extra rib statements to be added to the rib files generated by the Rfm Pro plugin. Extra rib can be generated by one or more mel scripts that have been assigned to the transform and/or shape nodes in the Maya scene.

When Rfm Pro traverses the Maya scene graph, gathering data that it converts to rib, it recognizes seven "insertion-points" from which it can call custom mel procs that have been implemented by a user. Such procs can add their own rib statements to the output rib stream through the use of a library of Pixar procedures, each of which has the prefix Ri. For example,

    RiSphere(1, -1, 1, 360);

would cause this rib statement,

    Sphere 1.0 -1.0 1.0 360.0

to appear in the final rib file. During the traversal of the scene graph, Rfm Pro looks for attributes with very specific names. The value of the attribute will be the name of a users mel proc. For example, if the following attribute,

    rman__torattr___postTransformScript

is found on a transform node, and its value is,

    myPTproc

then the proc will be called by Rfm Pro. The first illustration shows where a users mel procs can be called. I have omitted transformEndScript because it seems Rfm Pro (version 1) does not recognize this attribute.

Scene Graph

Rib File

AttributeBegin 
   # transformBeginScript rib statements are
   # added here...
   Attribute "identifier" "string name" ["pCube1"]
   ConcatTransform [1 0 0 0  0 1 0 0  0 0 1 0  0 0 0 1]
   # postTransformScript rib statements are
   # added here...
   AttributeBegin 
       AttributeBegin 
           Attribute "identifier" "name" ["pCubeShape1"]
           Surface ...
           # preShapeScript rib statements are
           # added here...
           TransformBegin 
               ReadArchive ... 
               Procedural "DelayedReadArchive"...
           TransformEnd 
           # postShapeScript rib statements are
           # added here...
       AttributeEnd 
   AttributeEnd 
AttributeEnd

The data from a transform node appears in the rib file with the ConcatTransform statement. The data from the shape node is written into an archive rib file and is accessed via the Procedural statement.

There are also two other insertion-points, defaultRiOptionsScript and defaultRiAttributesScript, where custom mel procs will be called. The reader should refer to Pixar's RMS documentation for information about them.

Adding a Post Transform Proc

In this example a postTransformScript mel proc will be added the the transform node of a cube. Before continuing you should check if the RenderMan Studio Rfm Pro plugin has been loaded by Maya.

Step 1

Select the pCube1 tab and choose "Manage Attributes..." (figure 1).

Figure 1

Step 2

From the list of attributes (figure 2) choose Post Transform MEL and click the Add button.

Figure 2

Step 3

An Extra RenderMan Attributes panel will be added to the Attribute Editor. In the text field add the name of your mel proc (figure 3)

Figure 3

Step 4

Because the addSquashySphereRI proc adds a sphere to the scene that that is intended to replace the cube to which it is "attached", the Primary Visibility of the shape node should be switched off (figure 4).

Figure 4

A Sample User Proc

The following mel proc adds a quadric sphere as a replacement to the cube to which it is attached. The cube merely acts as a proxy object. The mel script adds arbitary scalings to the sphere so that it squashes and stretches on its y-axis.

global proc addSquashySphereRI()
{
string $objs[] = `ls -sl`;
if(size($objs) == 0) {
    print("Error: must have an object or objects selected");
    return;
    }
for($n = 0; $n < size($objs); $n++)
    {
    string $shp[] = `listRelatives -shapes $objs[$n]`;
    RiAttributeBegin();
        RiSurface("plastic");
        RiTranslate(0, -1, 0);
        float $frame = `currentTime -q`;
        RiScale(0.2, noise($frame/3), 0.2);
        RiTransformBegin();
            RiTranslate(0, 1, 0);
            RiSphere(1, -1, 1, 360);
        RiTransformEnd();
    RiAttributeEnd();
    }
}

The script should be saved in your favorite scripts directory. For example, it might be saved in the maya/scripts directory as "addSquashySphereRI.mel". If the script was saved in the scripts directrory after Maya was launched it will require sourcing ie.

    source "addSquashySphereRI.mel";

Script Naming Conventions

Naming conventions are either a subject of personal preference or are imposed on an artist by the established practices of the studio in which they work. Depending on your circumstances you may prefer to ignore this section. Mel scripts that play some role in adding rib to the final output rib stream may be considered, by their functionality, to fall into two groups.

UI front-end

These procs setup what an artist will see in the Extra RenderMan Attributes panel ie. its user interface. Procs in this group are generally activated by buttons added to the Maya custom shelf. Such procs automate the task of assigning, say, a postTransformScript to an object. They typically also add some UI (user interface) widgets that provide additional controls such as text fields, check-boxes and drop-down menus etc.

RI back-end

The second group of procs determines what an artist wants based on the "state" of any UI widgets as well as calling the Ri procedures that do the actual work of adding rib statements to the output rib stream.

Since both groups, or types, of procs are implemented by mel scripts located in one of Maya's scripts directories it seems appropriate that the names chosen for them should indicate their purpose ie.

    addSquashySphereRI.mel

In the next section a "front-end" proc will be implemented. An additional file will alse provide additional UI information. Depending on the complexity of what we are trying to achieve with our Ri/Mel scripting we will have one, two or three scripts.

    addSquashySphereUI.mel
    addSquashySphereUI.rman

As a final note on the subject of naming conventions. The sample mel scripts in this and other sections will always use the name of the script as the name of its main proc.


	Script name		Main proc
	addSquashySphereUI.mel addSquashySphereRI.mel		global proc addSquashySphereUI() global proc addSquashySphereRI()

RMS Ri Scripting