Set up a searchpath for procedural plugins

It'll be handy to refer to our procedural plugin just by name, rather than with a full path. This MEL procedure outputs an RiOption that sets up a search path for plugins in the RenderMan for Maya devkit. You can paste it into the Script Editor, for now, or install it among your MEL scripts.

global proc rmanOutputProceduralSearchpath()
{
   // This proc sets up a searchpath for procedural plugins.

   // On windows its necessary to load a different version of the procedural
   // plugin depending on whether it'll be running internally in RfM or
   // in the standalone prman renderer.  We can find out if this script is
   // being called during ribgen or internal rendering, and
   // refer to a different procedural path based on that.
   string $subdir = "";
   if( `about -nt` ) {
       if( `eval("rman ctxIsRib")` ) {
           $subdir = "prman_plugins";
       } else {
           $subdir = "rfm_plugins";
       }
   }

   // Change this path to correspond to the location where you put your compiled plugin.
   // Note on windows the path needs to be in UNC format.
   string $pluginpath = "//C/Program Files/Pixar/RenderMan-Studio-1.0-Maya8.5/devkit/custom_geometry/";
   RiOption "searchpath" "string procedural" ($pluginpath+$subdir);
}

We can cause the searchpath option to be output into the RIB stream at the appropriate time, by invoking this procedure in the Default RiOptions MEL script, which is located in the Render Settings under the Advanced tab. Paste a call to the procedural above in the Default RiOptions MEL field:

rmanOutputProceduralSearchpath

Set up your build environment

Proper compilation of the quadric procedural assumes you have two variables set in your environment: RMANTREE and RMSTREE. RMSTREE should be set to the path of your RMS installation, and RMANTREE can be set to either the location of your RenderMan Pro Server installation or Path/to/RMS/rmantree.

Build the plugin

Open a shell and change to the directory of the RMS devkit. There's an example makefile for Windows, which you can execute by typing:

make -f Makefile.windows

Or you can compile using the standard RenderMan compilation method. Use the standard C++ compiler to generate an object (.o/.obj) file, then generate a shared object (.so/.dll) file from the object file. Remember that, though using C++, you must use C style linkage. You also must ensure that your C++ compiler and libraries are compatible with the compiler and runtime libraries used by PRMan (gcc for Linux and OS-X and Microsoft Visual C for Windows). Here are example commands for building the plugin on several architectures:

Linux:

g++ -fPIC -I$RMANTREE/include -c quadricProcedural.cpp
g++ -shared quadricProcedural.o -o quadricProcedural.so

Mac OS-X:

g++ -I$RMANTREE/include -c quadricProcedural.cpp
setenv MACOSX_DEPLOYMENT_TARGET 10.3
g++ -bundle -undefined dynamic_lookup quadricProcedural.o -o quadricProcedural.so

Windows:

cl -nologo -MT -I%RMANTREE%\include -c quadricProcedural.cpp
link -nologo -DLL -out:quadricProcedural.dll quadricProcedural.obj %RMANTREE%\lib\prman.lib

quadricProcedural.cpp

The code for the quadric is in quadricProcedural.cpp, located in the devkit directory. Procedural plugins must implement three entrypoints: ConvertParameters, Subdivide, and Free.

You'll see prototypes for these exported at the beginning of the file:

extern "C" {
       export RtPointer ConvertParameters(RtString paramstr);
       export RtVoid Subdivide(RtPointer data, RtFloat detail);
       export RtVoid Free(RtPointer data);
}

The ConvertParameters method takes the arg string that we passed in the RiProcedural call and stashes the values in a data structure, which it returns a blind pointer to. Our data goes into a struct with a value for each attr:

enum QuadricsType {
       kCylinder,
       kDisk,
       kPartialDisk,
       kSphere
};

struct quadricsData {
   QuadricsType shapeType;
   RtFloat radius1;
   RtFloat radius2;
   RtFloat height;
   RtFloat startAngle;
   RtFloat sweepAngle;
};

export RtPointer ConvertParameters(RtString paramstr) {
   struct quadricsData* data;
   char* parameters;
   char* token, *tokenstate;
   int i, j;

   parameters = strdup(paramstr);

data = reinterpret_cast<struct quadricsData*>(malloc(sizeof(struct quadricsData)));

token = strtok_r(parameters, " ", &tokenstate);
   data->shapeType = static_cast<QuadricsType>(atoi(token));

   token = strtok_r(0, " ", &tokenstate);
   data->radius1 = atof(token);

   token = strtok_r(0, " ", &tokenstate);
   data->radius2 = atof(token);

   token = strtok_r(0, " ", &tokenstate);
   data->height = atof(token);

   token = strtok_r(0, " ", &tokenstate);
   data->startAngle = atof(token);

   token = strtok_r(0, " ", &tokenstate);
   data->sweepAngle = atof(token);

   free(parameters);
   return (RtPointer)(data);
}

The Subdivide method is where the quadric shape gets rendered. The cylinder, disk, and partial disk can each be represented by an RiHyperboloid primitive, and the sphere by an RiSphere primitive. These look somewhat different than the quadricShape in the Maya render view because it uses OpenGL primitive calls. RenderMan's primitives aren't polygonal, so they'll appear smooth.

export RtVoid Subdivide(RtPointer datap, RtFloat detail) {
       struct quadricsData* data = reinterpret_cast<struct quadricsData*>(datap);
       int i, j;

       RiTransformBegin();

       RtPoint p1;
       RtPoint p2;
       p1[0] = data->radius1;
       p2[0] = data->radius2;
       p1[1] = 0;
       p1[2] = 0;
       p2[1] = 0;
       p2[2] = 0;

       switch (data->shapeType) {
       case kCylinder:
       p2[2] = data->height;
       RiHyperboloid(p1, p2, 360, RI_NULL);
       break;
       case kDisk:
       RiHyperboloid(p1, p2, 360, RI_NULL);
       break;
       case kPartialDisk:
       RiRotate(90, 0, 0, 1);
       RiRotate(-data->startAngle, 0, 0, 1);
       RiHyperboloid(p1, p2, -data->sweepAngle, RI_NULL);
       break;
       case kSphere:
       RiSphere(data->radius1, -data->radius1, data->radius1, 360, RI_NULL);
       break;
       }
       RiTransformEnd();
}

And finally, the Free method frees up the struct allocated in the ConvertParameters method.

export RtVoid Free(RtPointer datap) {
       struct quadricsData* data = reinterpret_cast<struct quadricsData*>(datap);
       free(data);
}

Cache Shape MEL Script

Normally, when RfM encounters deforming shapes, and motion blur is enabled, it will cache the state of the shape at Shutter Open and Shutter Close times. Then at render time both samples are output, surrounded by a motion block. RfM allows you to cache your own shape during those caching passes. You can specify a caching MEL script by adding an attribute called Cache Shape MEL to your shape. You may also need to add the Evaluation Frequency attribute, and change it to Frame. That lets RfM know your shape is deforming, even if its usual method of looking for upstream animated nodes isn't adequate for detecting deformation of the custom shape.