RfM - HyperShade & Cutter

Cutter
HyperShade Node Scripts

Introduction

The tutorial Cutter: Slim Template Scripts explaines how Cutter can automatically generate a Slim node from a RSL function implemented in a .h file. This tutorial outlines Cutters ability to also automatically produce a HyperShade node script from a RSL function. HyperShade node scripts, implemented in .h files, are explained in detail in the Pixar document,
"Custom RSL Code Generation".

It should be noted that Cutter can only generate scripts for HyperShade (up stream) function nodes.

Setting Up Cutter's Preferences

The most important preference to be set by the user is the path to the directory in which RenderMan_for_Maya.ini will source the users custom HyperShade node scripts. For example, suppose a directory named RfM_hypershade will store the custom (.h) node files, say,

    /Users/john_doe/Documents/maya/projects/RfM_hypershade

The same path should be entered into Cutter's Languages/Slim panel. The preference named "Base ID" will be explained later.

Figure 1

Although scripts for Slim nodes are not the same as those for HyperShade their structure is sufficiently similar to warrant the preferences for Cutter's HyperShape node capabilities to be "bundled" with the general Slim preferences.

Creating a Custom Node from a RSL Function

The RSL function given in listing 1 will be used to demonstrate Cutter's ability to automatically generate a HyperShade node script.

Listing 1 (SwapComponents.h)

void SwapComponents (
        color c;
        float comps;
        output varying color result)
{
if(comps == 0)
    result = color(c[0],c[2],c[1]);
else if(comps == 1)
    result = color(c[1],c[2],c[0]);
else if(comps == 2)
    result = color(c[2],c[0],c[1]);
else
    result = color(c[2],c[1],c[0]);
}

Step 1 - function selection

Select (only) the text of the function. Ignore any #includes that may be specified in the file - these will be recognized automatically by Cutter. Right mouse click and choose "Export as HyperShade Node".

Figure 2

Step 2 - function conversion

Cutter will open a window containing the text for the node - listing 2. The large commented block of XML code contains instructions that will be read by Pixar's code generator when cutrSwapComponents.h is sourced by RenderMan_for_Maya.ini.

Listing 2 (cutrSwapComponents.h)

/* Created by Cutter [6.4.4] on 7.29.2013 at 1:8:11.
   Source file:
   "/Users/mkesson/Documents/WebSite/FUNDZA_COM/rman_hypershade/SwapComponents.h"
*/
#ifndef cutrSwapComponents_h
#define cutrSwapComponents_h
/*
<rman id="rslt">
slim 1 extensions cutter {
    extensions fundza cutr {
        template void SwapComponents {
            userdata {
                rfm_nodeid 1053400
                rfm_classification rendernode/RenderMan/utility
                }
            parameter color c {
                label {c}
                }
            parameter float comps {
                label {comps}
                subtype {slider}
                range {0 1 0.05}
                }
            parameter {output color} result {
                detail mustvary
                }
            RSLPlugin RfMShadeops
            RSLInclude {/Users/mkesson/Documents/maya/projects/RfM_hypershade/cutrSwapComponents.h}
            RSLFunction {}
            }
        }
    }
</rman>
*/
void cutrSwapComponents(color c; float comps; output color result; ) {
if(comps == 0)
    result = color(c[0],c[2],c[1]);
else if(comps == 1)
    result = color(c[1],c[2],c[0]);
else if(comps == 2)
    result = color(c[2],c[0],c[1]);
else
    result = color(c[2],c[1],c[0]);
}
#endif

Step 3 - unique node ID

Edit the value of the item rfm_nodeid 1053400.

Warning: Values larger than 1053400 are intended to avoid node IDs that been registered by Pixar with AutoDesk. Ideally, the node IDs used by an artist should be within a range of values supplied by AutoDesk. For studios that do not share their custom HyperShade node scripts with other studios it should (hopefully) not be necessary to register their node IDs with AutoDesk.

It is important to ensure that each node script has a unique node ID. Cutter makes no attempt to assign unique node IDs.

Step 4 - deploying the node script

This section assumes the user has established a directory structure intended to store scripts that will be sourced by RfM. For details refer to,
RfM: Customizing

Save the cutrSwapComponents.h file, created in step 2, in the directory intended to store custom HyperShade node scripts - in my case a directory named RfM_hypershade. Add the following text to your custom RenderMan_for_Maya.ini file. Always provide a comment before the LoadExtension indicating the "rfm_nodeid" of the node.

    # rfm_nodeid 1053400
    LoadExtension rslt PATH_TO_/cutrSwapComponents.h
    RAT::LogMsg INFO "cutrSwapComponents has been loaded"

Step 5 - custominzing the node interface

Make sure the RfM plugin is loaded. In HyperShade locate the new node.

Figure 3

The interface for the node is artist-unfriendly because the UI widget for the parameter "comps" should be a dropdown menu, not a slider.

Figure 4

As explained for Slim nodes in the tutorial Cutter: Ui-Hints for Slim ui-hints can be used to adjust the UI. As an example, consider what happens when ui-hints are assigned to the comments of the parameters of the original SwapComponents.h.

void SwapComponents (
     color c;     /* [label "Input Color" default "0.2 0.7 0.4"] */
     float comps; /* [label "Reorder Components" rbg gbr brg bgr 0 1 2 3] */
     output color result)

When Cutter creates a new version of cutrSwapComponents.h it will write additional information into each parameter block. For example.

            parameter color c {
                label {Input Color}
                default {0.2 0.7 0.4}
                }
            parameter float comps {
                label {Reorder Components}
                subtype {selector}
                range {"rbg" 0 "gbr" 1 "brg" 2 "bgr" 3}
                }

The interface in Maya will reflect the changes.

Figure 5

Cutter HyperShade Node Scripts