Site

Introduction

This documentation is intended to instruct developers in the authoring of custom patterns. Developers should also consult the RixPattern.h header file for complete details.

A RixPattern plugin is

Pattern Plugins

RiPattern is used to connect textures and procedurally generated patterns to RiBxdf parameters. The pattern behavior is controlled through a plugin written in C++. For example, a pattern plugin can be written to generate a fractal or noise pattern, or it can read a new texture file format and pass the output to Bxdfs. There are numerous pattern plugins included with RenderMan Pro Server and RenderMan for Mayato RiBxdf parameters, or to other patterns to create a shading graph. There are numerous pattern plugins included with the RenderMan software, but if none of the included plugins generate the pattern you want, then this guide will help you write your own pattern plugin. Source code for many of the RenderMan pattern plugins can be found in the PixarRenderMan-Examples-VERSION/plugins/pattern/ directory which is installed as part of the separate examples package.

For pattern generation using For pattern generation using the Open Shading Language (OSL), see the PxrOSL plugin documentation on Working with PxrOSL.Source code for pattern plugin examples can be found in the /lib/examples/RIS/plugins/pattern/ directory of your RenderMan Pro Server installation.

Implementing the RixPattern Interface

RixPattern.h defines the interface that all pattern plugins must implement. To start developing your own pattern, you can includeRixPattern.h and make sure your pattern class implements the four methods from the RixPattern interface: Init, GetParamTable,Finalize, and ComputeOutputParams. It can also be helpful to include RixShadingUtils.h if your pattern will use any of the RixShadingutility functions. The beginning structure of an example PxrCustomNoise plugin is described below, which you can use to model your own pattern plugin:

...

RixPattern is a subclass of RixShadingPlugin, and therefore shares the same initialization, synchronization, and parameter table logic as other shading plugins. Because a RixPattern is expected to be a lightweight object that may be created many times over the course of the render, RixPattern is expected to take advantage of the lightweight instancing services provided by RixShadingPlugin . Therefore to start developing your own pattern, you can #include "RixPattern.h" and make sure your pattern class implements the required methods inherited from the RixShadingPlugin interface: Init(), Finalize(), Synchronize(), GetParamTable(), and CreateInstanceData().

The RIX_PATTERNCREATE() macro defines the CreateRixPattern() method, which is called by the renderer to create an instance of the pattern plugin. Generally, the implementation of this method should simply return a new allocated copy of your pattern class. Similarly, the RIX_PATTERNDESTROY() macro defines the DestroyRixPattern() method called by the renderer to delete an instance of the pattern plugin; a typical implementation of this method is to delete the passed in pattern pointer:

Code Block

language	cpp

    RIX_PATTERNCREATE
    {
        return new MyPattern();
    }
    RIX_PATTERNDESTROY
    {

...

delete ((MyPattern*)pattern);
    }

Anchor
ComputeOutputParams
ComputeOutputParams
Computing Pattern Output

ComputeOutputParams() is the heart of a pattern plugin: it evaluates the input parameters, and computes the pattern output. It is called once per graph execution, and all outputs must be computed during this single invocation. The number and type of outputs should match the number and type of outputs declared in the parameter table. The domain of evaluation of this function is a shading context, which is of type RixShadingContext, defined in RixShading.h.

To read an input value, use the RixShadingContext::EvalParam() method. The desired input parameter to the pattern is selected by an integer paramId, which is the ordinal position of the parameter in the parameter table. Patterns are expected to know the paramId, the type of the associated parameter, and are expected to pass a pointer to a pointer of the appropriate type. As such, it is suggested that a private parameter enumeration is used to keep track of the order that the parameters are created in the parameter table. For more information, please consult the documentation for RixShadingContext::EvalParam() and RixShadingPlugin::GetParamTable().

After reading input values, output values need to be set up. First, memory buffers for the requested outputs should be allocated using the RixShadingContext memory allocation services. These buffers should then be bound to the requested OutputSpec outputs parameter passed to ComputeOutputParams(), and the type and detail information about those outputs filled in as well. This information should match the declarations from the parameter table. The following code is boilerplate that can be used: it reads the plugin's parameter table, loops through and allocates the appropriate buffers, and sets the detail and type assuming that the output is always a varying color or float (typical of most patterns).

Code Block

language	cpp

    // Find the number of outputs
    RixSCParamInfo const* paramTable = GetParamTable();
    int numOutputs = -1;
    while (paramTable[++numOutputs].access == k_RixSCOutput) {}

    // Allocate and bind our outputs
    RixShadingContext::Allocator pool(sctx);
    OutputSpec* out = pool.AllocForPattern<OutputSpec>(numOutputs);
    *outputs = out;
    *noutputs = numOutputs;
    
    // looping through the different output ids
    for (int i = 0; i < numOutputs; ++i)
    {
        out[i].paramId = i;
        out[i].detail = k_RixSCInvalidDetail;
        out[i].value = NULL;
        type = paramTable[i].type; // we know this
     
        sctx->GetParamInfo(i, &type, &cinfo);
        if(cinfo == k_RixSCNetworkValue)
        {
            if( type == k_RixSCColor )

The methods and functions in the code above are defined as:

Init: Called when the plugin is first loaded by the renderer. The plugin will remain loaded for the lifetime of the render. Any global work that would be shared by all instances of a plugin should be done here. Init returns 0 if there was no error initializing the plugin.
GetParamTable: Creates an array (table) of RixSCParamInfo objects, where each object in the array defines an input or output parameter for the pattern plugin. Guidance for defining these objects is provided in the Defining Inputs and Outputs section below.
Finalize: Called when the plugin is unloaded from memory by the renderer.
ComputeOutputParams: This is the heart of a pattern plugin; it reads the input parameters and computes the output parameters. It is called once per graph execution. All outputs must be computed during this one call. The renderer provides a list of the outputs it expects the plugin to compute. Most often, this is exactly the same as the outputs declared in the parameter table.
RIX_PATTERNCREATE: Called by the renderer to create an instance of the pattern plugin.
RIX_PATTERNDESTROY: Called by the renderer to delete an instance of the pattern plugin.

Defining Inputs and Outputs

Now that the basic structure of your pattern plugin is defined, we can define the plugin input and output parameters in the GetParamTable method. An example of this can be found in PxrTextureAtlas.cpp:

...

out[i].detail = k_

...

RixSCVarying;

...

    out[i].value = pool.AllocForPattern<RtColorRGB>(sctx->numPts);

...

}
            else

...

if( type == k_

...

RixSCFloat )

...

         out[i].detail = k_RixSCVarying;

...

      out[i].value = pool.AllocForPattern<RtFloat>(sctx->numPts);

...

}
    }

Finally, the pattern can now actually compute the values that go into the output buffers. This is typically done by using the inputs and looping through the number of shaded points RixShadingContext::numPts to compute some values that are stored in the allocated output buffers.

Code Block

language	cpp

RtColorRGB* outColor = (RtColorRGB*) out[k_resultRGB].value; 
for (int i=0; i<sctx->numPts; i++)
{
    // Compute some output values based on your input. Here we assume
    // outColor is the memory buffer allocated for an output parameter,
    // and inputColor and inputFloat are two inputs that were returned from
    //

...

EvalParam.
    if (style

...

== 1)
    {

...

outColor[i] = inputColor[i] * inputFloat[i];
    }
}

In the simple example above, outColor is assigned the buffer that was allocated corresponding to the private enumeration value k_resultRGB, which matches the position of that output in the parameter table. (So long as the output parameters are at the beginning of the parameter table, reuse of this enumeration is valid for this purpose.) We assume the style variable was a uniform RtInt input value, so there is only one value for all the points in the shading context. Meanwhile, the inputColor and inputFloat variable were varying instead of uniform, so they are pointers to an array of RtColorRGB values and array of RtFloat values respectively, one for each shaded point in the shading context.

The ComputeOutputParams() method should return 0 if no error occurred while calculating the output, otherwise it should return a non-zero integer value.

Testing Your Pattern Plugin

After you have implemented the code for your pattern plugin, you can build it using the commands listed in the Compiling Plugins page. The next step is to test your plugin. To test it, you'll need to make sure prman can find your plugin in the standardrixpluginpath list of directories, which is defined in $RMANTREE/etc/rendermn.ini as:

/standardrixpluginpath

Each input and output parameter is defined as a RixSCParamInfo object. The RixSCParamInfo struct is defined in RixShading.h:

struct RixSCParamInfo
{
    // most common constructor of POD parameters.
    RixSCParamInfo(char const *nm, RixSCType t,
                   RixSCAccess a = k_RixSCInput,
                   int len = -1) :
        name(nm),
        customtype(NULL),
        type(t),
        access(a),
 ${RMANTREE}/lib/RIS/pattern:${RMANTREE}/lib/RIS/bxdf:${RMANTREE}/lib/RIS/integrator:${RMANTREE}/lib/RIS/projection

You can add a rendermn.ini file to your HOME directory and modify the standardrixpluginpath value to contain the directory where your pattern plugin is located.

Then you can try to render this RIB file after you have replaced "PxrCustomPattern" with the name of your pattern plugin and connect your pattern's output parameter to one of the input parameters of the PxrDiffuse Bxdf:

Display "patternTest" "framebuffer" "rgba"
Quantize "rgba" 255 0 255 0
Format 128 128 1
Projection "perspective" "fov" [45]
Hider "raytrace" "string integrationmode" ["path"]
Integrator "PxrPathTracer" "integrator"
WorldBegin
    AttributeBegin
       arraylen(len)
 Attribute "identifier"  {
"name" ["sphere1"]
     }

   Translate //0 full0 constructor2.75
     RixSCParamInfo(char const *structnm, charPattern const *nm,"PxrCustomPattern" "customPattern"
        Bxdf "PxrDiffuse" "smooth"
        RixSCType t, RixSCAccess a = k_RixSCInput,
  "reference color diffuseColor" "customPattern:outColor"
        Sphere 1.0 -1.0 1.0 360.0
    int len = -1) :
        name(nm),
        customtype(structnm),
        type(t),
        access(a),
  AttributeEnd
WorldEnd

Texture Baking

RenderMan can optionally bake pattern outputs to 2D or 3D textures by evaluating those patterns over an output manifold. Pattern plug-ins that wish to bake outputs should provide custom implementations of the RixPattern::Bake2dOutput or RixPattern::Bake3dOutput methods that return true. When in bake mode, RenderMan queries these methods to describe the output manifold and to initialize display drivers. For 2d atlas/UDIM outputs that set RixPattern::Bake2dSpec::atlas to true, RenderMan will query RixPattern::Bake2dOutput once for each UV tile.

It is possible to write a generalized baking node that bakes the output of arbitrary upstream pattern graphs. For example, see PxrBakeTexture and PxrBakePointCloud pattern plug-ins:

Code Block

language	text

Hider "bake"
Format 512 512 1
Display "render.exr" "openexr" "rgba"
Projection "perspective" "fov" [30]
Translate 0 0 5
WorldBegin
    AttributeBegin

...

  Pattern

...

"PxrFractal" "pattern"

...

Pattern "PxrBakeTexture" "baked" "reference color inputRGB" ["pattern:resultRGB"]

...

  "string filename" ["bake.tif"] "string

...

display" ["tiff"]

...

  "string primVar" ["st"] "int resolutionX" [512] "int

...

resolutionY" [512]

...

Bxdf "PxrDiffuse" "default" "reference color diffuseColor" ["baked:resultRGB"]

...

Sphere

...

-1 1 360

...

In the PxrTextureAtlas::GetParamTable() method example, the resultC output parameter is a color, so it is defined as:

RixSCParamInfo("resultC", k_RixSCColor, k_RixSCOutput)

A float input parameter named density can be defined as:

RixSCParamInfo("density", k_RixSCFloat)

While a float[16] input parameter named placementMatrix can be defined as:

RixSCParamInfo("placementMatrix", k_RixSCFloat, k_RixSCInput, 16)

Every parameter table must be null-terminated by an empty RixSCParamInfo object, which is created by adding RixSCParamInfo() to the end of the array returned by GetParamTable.

After you define the parameter table in GetParamTable it is recommended that you create a parameter enumeration to keep track of the order that your parameters were created in the table. The order will be used later on when you are reading in the parameters in the ComputeOutputParams method. An example of this can be found in PxrTextureAtlas.cpp:

enum paramId
{
    k_resultC=0, // output
    k_resultF,   // output
    k_atlas,
    k_style,
    k_channelOffset,
    k_linearize,
    k_filter,
    k_blur,
    k_numParams
};

Reading Inputs in ComputeOutputParams()

Now that the plugin input and output parameters are defined, it is time to read the inputs and compute the output values in the ComputOutputParams method. To read an input value, use the RixShadingContext::EvalParam method, which is defined in RixShading.h. EvalParam takes the following arguments:

id: The integer value that defines the order the parameter was defined in the table from GetParamTableA. This should correspond to one of the paramId enum values mentioned earlier.
arrayIndex: If the parameter is an array of values, then this defines the array index from which to start reading values. If the parameter is not an array, then set arrayIndex to -1.
result: The result buffer to store the parameter values in.
dflt: The default value to use for the parameter if it was not specified in the RiPattern call.
promoteToVarying: A boolean value that tells the plugin to evaluate the input as a varying or uniform value. Varying values can have a separate value for each shaded point, and they can be connected to the output of other Pattern plugins. A uniform value will only have one value for each shaded point, so it will use less memory than varying inputs.

Some examples for reading different types of input parameters are listed below:

int
PxrCustomNoise::ComputeOutputParams(RixShadingContext const *sctx,
                                RtInt *noutputs, OutputSpec **outputs,
                                RixSCParamInfo const *ignored)
{
    bool varying = true;
    bool uniform = false;
    RixSCType type;
    bool isconnected;

    // read a uniform integer value, and store the result in the
    // RtInt noiseType variable. m_noiseType is a PxrCustomNoise
    // member variable that contains the default noiseType value.
    RtInt *noiseTypePtr;
    sctx->EvalParam(k_noiseType, -1, &noiseTypePtr,
        &m_noiseType, uniform);
    RtInt const noiseType(*noiseTypePtr);

    // read a varying float value for the threshold input parameter.
    // m_threshold is a PxrCustomNoise member variable that contains
    // the default value.
    RtFloat *threshold;
    sctx->EvalParam(k_threshold, -1, &threshold, &m_threshold, varying);

    // read one value from a varying float[2] array
    RtFloat *repeatUV0, *repeatUV1;
    sctx->EvalParam(k_repeatUV, 0, &repeatUV0, &m_repreatUV, varying);
    // read the other value from a varying float[2] array. Note that
    // the arrayIndex parameter is set to 1 to read the second value.
    sctx->EvalParam(k_repeatUV, 1, &repeatUV1, &m_repreatUV, varying);

    // read in a float[3] array of values into a RtFloat3 variable.
    RtFloat3 *scale;
    sctx->EvalParam(k_scale, -1, &scale, &m_scale, varying);

    // check for manifold input
    RtPoint3 *Q = (RtPoint3*)RixAlloca(sizeof(RtPoint3)*sctx->numPts);
    RtFloat *Qradius = (RtFloat*)RixAlloca(sizeof(RtFloat)*sctx->numPts);
    sctx->GetParamInfo(k_manifoldBegin, &type, &isconnected);
    if(isconnected)
    {
        sctx->EvalParam(k_manifoldQ, -1, &Q);
        sctx->EvalParam(k_manifoldQradius, -1, &Qradius);
    }
    else
    {
        // allocate space for our remapped P
        RtFloat const *pvWidth;
        RtPoint3 const *pv;
        char const *primvarNm = "P";
        RtFloat3 fill(0.f, 0.f, 0.f);
        sctx->GetPrimVar(primvarNm, fill, &pv, &pvWidth);
        *Qradius = *pvWidth;
        memcpy(Q, pv, sizeof(RtPoint3) * sctx->numPts);
    }

    // read in the placementMatrix float values and
    // default the to the identity matrix
    RtFloat *placementMatrix = (RtFloat*)RixAlloca(sizeof(RtFloat)*16);
    const RtFloat zero = 0.0f;
    const RtFloat one = 1.0f;
    RtFloat* placementInput;
    for (int i=0; i< 16; i++)
    {
        if ( i % 5 == 0)
            sctx->EvalParam(k_placementMatrix, i,
                &placementInput, &one, uniform);
        else
            sctx->EvalParam(k_placementMatrix, i,
                &placementInput, &zero, uniform);
        placementMatrix[i] = *placementInput;
    }

    // read in a varying color value.
    RtColorRGB* defaultColor;
    sctx->EvalParam(k_defaultColor, -1, &defaultColor,
        &m_defaultColor, varying);

Writing the Output

Now that you have read in the input parameter values, you can start to write the output values in ComputeOutputParams. First, you will need to allocate memory for the outputs using a RixShadingContext::Allocator object, and then bind the output parameters to the outputs parameter of ComputeOutputParams:

int
PxrCustomNoise::ComputeOutputParams(RixShadingContext const *sctx,
                                RtInt *noutputs, OutputSpec **outputs,
                                RixSCParamInfo const *ignored)
{
    // read in the inputs
    // ...

    // Allocate and bind the output parameters.
    // In this example, there are two output parameters: outColor and outAlpha
    RixShadingContext::Allocator pool(sctx);
    OutputSpec *o = pool.AllocForPattern<OutputSpec>(2);
    *outputs = o;
    *noutputs = 2;
    RtColorRGB* outColor = NULL;
    RtFloat* outAlpha = NULL;

    outColor = pool.AllocForPattern<RtColorRGB>(sctx->numPts);
    outAlpha = pool.AllocForPattern<RtFloat>(sctx->numPts);

    // define the param ID, detail, and value for each
    // output parameter.
    o[0].paramId = k_outColor;
    o[0].detail = k_RixSCVarying;
    o[0].value = (RtPointer) outColor;

    o[1].paramId = k_outAlpha;
    o[1].detail = k_RixSCVarying;
    o[1].value = (RtPointer) outAlpha;

The next step is to start calculating your output. This is done by looping through the number of shaded points given by the RixShadingContext parameter of ComputeOutputParams so that you are assigning an output value for each shaded point.

for (int i=0; i<sctx->numPts; i++)
{
    // Compute some output values based on your input.
    if (style == 1)
    {
        outColor[i] = defaultColor[i];
    }
}

In the simple example above, the style variable was a uniform RtInt input value, so there is only one value for all the points in the shading context. The defaultColor variable was varying instead of uniform, so it a pointer to an array of RtColorRGB values (one for each shaded point in the shading context).

The ComputeOutputParams method should return 0 if no error occurred while calculating the output, otherwise it should return a non-zero integer value.

For more examples of how input and output parameters are handled in the ComputeOutputParams method, see the pattern plugin examples in the /lib/examples/RIS/plugins/pattern/ directory of your RenderMan Pro Server installation.

Testing Your Pattern Plugin

After you have implemented the code for your pattern plugin, you can build it using the commands listed in the Compiling Plugins page. The next step is to test your plugin. To test it, you'll need to make sure prman can find your plugin in the standardrixpluginpath list of directories, which is defined in $RMANTREE/etc/rendermn.ini as:

/standardrixpluginpath          ${RMANTREE}/lib/RIS/pattern:${RMANTREE}/lib/RIS/bxdf:${RMANTREE}/lib/RIS/integrator:${RMANTREE}/lib/RIS/projection

You can add a rendermn.ini file to your HOME directory and modify the standardrixpluginpath value to contain the directory where your pattern plugin is located.

Then you can try to render this RIB file after you have replaced "PxrCustomPattern" with the name of your pattern plugin and connect your pattern's output parameter to one of the input parameters of the PxrDiffuse Bxdf:

Display "patternTest" "framebuffer" "rgba"
Quantize "rgba" 255 0 255 0
Format 128 128 1
Projection "perspective" "fov" [45]
Hider "raytrace" "string integrationmode" ["path"]
Integrator "PxrPathTracer" "integrator"

WorldBegin

    AttributeBegin
        Attribute "identifier" "name" ["sphere1"]
        Translate 0 0 2.75

        Pattern "PxrCustomPattern" "customPattern"

        Bxdf "PxrDiffuse" "smooth"
            "reference color diffuseColor" "customPattern:outColor"
        Sphere 1.0 -1.0 1.0 360.0
    AttributeEnd

WorldEnd

Creating a Pattern args File

If you would like RenderMan for Maya or Katana to recognize your pattern plugin and provide a user interface for changing input parameters and connecting output parameters to other nodes, then you will need to create an args file for your pattern. The args file defines the input and output parameters in XML so that tools like RMS or Katana can easily read them, discover their type, default values, and other information used while creating the user interface for the pattern node.

...

"varying float[2] st" [0 0 1 0 0 1 1 1]
    AttributeEnd
WorldEnd

Page tree

Versions Compared

Old Version 1

New Version Current

Key

Introduction

Pattern Plugins

Implementing the RixPattern Interface

Anchor
ComputeOutputParams
ComputeOutputParams
Computing Pattern Output

Defining Inputs and Outputs

Testing Your Pattern Plugin

Texture Baking

Reading Inputs in ComputeOutputParams()

Writing the Output

Testing Your Pattern Plugin

Creating a Pattern args File

Pixar Animation Studios

Site

Resources

Company

Connect

Page tree

Versions Compared

Old Version 1

New Version Current

Key

Introduction

Pattern Plugins

Implementing the RixPattern Interface

AnchorComputeOutputParamsComputeOutputParamsComputing Pattern Output

Defining Inputs and Outputs

Testing Your Pattern Plugin

Texture Baking

Reading Inputs in ComputeOutputParams()

Writing the Output

Testing Your Pattern Plugin

Creating a Pattern args File

Pixar Animation Studios

Site

Resources

Company

Connect

Anchor
ComputeOutputParams
ComputeOutputParams
Computing Pattern Output