Prev | Next

RenderMan Attributes

      The Anatomy of a RenderMan attribute
      How to figure out the name of an attribute
      Which attributes might you want to add to a node?
      How to add an attribute to a node
      How to add bunches of attributes to nodes 
      How to delete attributes
      How to set attribute values
      How to set Render Global values

The Anatomy of a RenderMan attribute

All RenderMan attributes are prefixed with "rman__" (that's two underscores), and all RenderMan attributes follow this naming convention:


But luckily, you don't need to remember that. There are ways to query the name of a setting which will be described in the next section.

Setting types include:

Translator options. These settings are used in the process of translating a maya scene. They apply across an entire rendering job.
Translator attributes. These settings are also used in the process of translating a maya scene. They can vary between passes, but they don't have to. For example, it's possible to render multiple passes for which only some have motionBlur enabled.
RenderMan Options are settings that affect the rendering of an entire image. The names of some riopts and riattrs may require a namespace.
RenderMan Attributes are settings that are part of the graphics state, and unlike Options can be associated with individual primitives.
Params can refer to either shader parameters or command parameters. In the case of shading parameters a simpler naming convention is followed: rman__param-name. Command parameters follow the same convention as other setting types.

How to figure out the name of an attribute

There are a couple ways you can find out the name of an attribute. The easiest is to select the node you want to add an attribute to, then open the RenderMan Attributes window (Attributes->RenderMan->Manage Attributes...) The window lists all the attributes that you can add to the selected node. These are listed as labels, because they're more readable that way. When you click on one of the labels, the corresponding name of the attribute appears in the description field at the bottom of the window. You can jot it down for future use.

Another way to find out the name of an attribute is to look in the DeclarationTable in RenderMan_for_Maya.ini. It lists all the known attributes, but their names aren't quite in the format you need. Here's are a couple example declarations:

    declare riattr {float ShadingRate} {
        label "Shading Rate"
        range {0 100 0.1}
        subtype slider
        description "Values from 5 to 100 allow for faster
                     renders, while a value of 1 is high quality and slower."
    declare riattr {int trace:maxspeculardepth} {
        label "Max Specular Depth"
        subtype slider
        range {0 10 1}
        description "Number of bounces for reflections and
                     refractions.  Value of 1 or 2 is sufficient unless you
                     need multi bounce effects."
The piece of this declaration that you can use to find out the corresonding attribute name in maya is the name of the setting -- the portion after the data type. In these two examples that's "ShadingRate" and "trace:maxspeculardepth". Note the latter has what's called a namespace, and the former doesn't. That's nothing you need to be particularly conscious of, just know that it takes part in the attribute name. You can pass the name of the setting to a MEL script called:
    global proc string rmanGetAttrName( string $declname )

For example:

    rmanGetAttrName "ShadingRate";
    // Result: rman__riattr___ShadingRate //
    rmanGetAttrName "trace:maxspeculardepth";
    // Result: rman__riattr__trace_maxspeculardepth //


Which attributes might you want to add to a node?

To get a list of the attributes you might want to add to a node, try this command:

    global proc string[] rmanGetOptionalAttrs( string $node )


    rmanGetOptionalAttrs nurbsSphereShape1;
    // Result: rman__riattr___ShadingRate rman__riattr___SmoothShade
    rman__riattr___MatteObject rman__riattr___DoubleSided
    rman__riattr___ReverseOrientation rman__riattr___MotionFactor 
    rman__riattr__cull_backfacing rman__riattr__cull_hidden
    rman__riattr__derivatives_centered rman__riattr__derivatives_extrapolate 
    rman__riattr__dice_binary rman__riattr__dice_hair
    rman__riattr__dice_rasterorient rman__riattr__grouping_membership 
    rman__riattr__identifier_name rman__riattr__identifier_objectid 
    rman__riattr__sides_backfacetolerance rman__riattr__sides_doubleshaded 
    rman__riattr__stitch_enable rman__riattr__stitch_newgroup
    rman__riattr__trace_bias rman__riattr__trace_displacements
    rman__riattr__trace_maxdiffusedepth rman__riattr__trace_maxspeculardepth 
    rman__riattr__trace_samplemotion rman__riattr__visibility_camera 
    rman__riattr__visibility_specular rman__riattr__visibility_diffuse
    rman__riattr__visibility_transmission rman__riattr__visibility_midpoint  
    rman__riattr__visibility_photon rman__torattr___outputSurfaceShaders
    rman__torattr___outputDisplacementShaders rman__torattr___outputLightShaders 
    rman__torattr___outputVolumeShaders rman__torattr___subdivScheme //


How to add an attribute to a node

Now that you know how to figure out the name of an attribute, the recommended way of adding it to a node is with a MEL script called "rmanAddAttr". Here's its definition:

    global proc rmanAddAttr( string $node, string $attr, string $val)

It takes three arguments, the node name, the attribute name, and the default value. RFM will figure out the appropriate type of attribute to add to the maya node, and will convert the value string to the expected type. The value can be an empty string if you want RFM to use its own default for the setting.

Some examples:

    rmanAddAttr nurbsSphereShape1 `rmanGetAttrName ShadingRate` "";
    rmanAddAttr nurbsSphereShape1 `rmanGetAttrName "trace:maxspeculardepth"` "4";


How to add bunches of attributes to nodes

The selection sensitive menu entries which appear in the Attribute Editor under the Attributes->RenderMan menu usually add more than one attribute. And some of them, like "Add Subsurface Scattering", even do more complex things like creating a new network of pass nodes. It might be handy to invoke these entries via MEL rather than from the menu. Here's how you can do that.

Note, it's also possible for you to add menu entries to the Attributes->RenderMan menu. These are defined toward the end of RenderMan_for_Maya.ini.

The command definition is:

    global proc rmanExecAEMenuCmd( string $node, string $menuItemLabel)

Here's an example which adds subsurface scattering to a material node:

    rmanExecAEMenuCmd blinn1 "Add Subsurface Scattering";


How to delete attributes

There's nothing special you need to know about deleting attributes. It's done in the same way as deleteing other maya attributes, with the deleteAttr command.


    deleteAttr nurbsSphereShape1.rman__riattr___ShadingRate


How to set attribute values

If you know the name of the node and attribute, you can use maya's setAttr command. RFM also provides a command that might make setting attributes a little easier in the respect that you don't need to know the data type of the attribute, and the value can be supplied as a string. Feel free to use whichever you prefer. This is its definition:

     global proc rmanSetAttr(string $node, string $attr, string $val)   

And some examples:

    rmanSetAttr nurbsSphereShape1 rman__riattr___ShadingRate 5;
    setAttr nurbsSphereShape1.rman__riattr___ShadingRate 5;

    rmanSetAttr renderManGlobals rman__riopt___PixelSamples "5 5";
    setAttr renderManGlobals.rman__riopt___PixelSamples 5 5;

    rmanSetAttr renderManGlobals rman__GDScheme occlusion;
    setAttr -type "string" renderManGlobals.rman__GDSchemeocclusion;


How to set Render Global values

The render globals nodes may not exist in your maya scene; they're typicaly created when the Render Globals window is raised. This command can be used to create them:


This command creates an environment light:


Render globals can be set like other attributes with the rmanSetAttr command; the trick is knowing which attribute each render global corresponds to. Here's a table...

Render Global node attribute type values
Image File Output
File Name Prefix defaultRenderGlobals imageFilePrefix
Frame/Animation Ext rmanFinalGlobals rman__torattr___passNameFormat
Image Format rmanFinalOutputGlobals0 rman__riopt__Display_type
Start Frame defaultRenderGlobals startFrame
End Frame defaultRenderGlobals endFrame
By Frame defaultRenderGlobals byFrameStep
Frame Padding defaultRenderGlobals extensionPadding
Renderable Objects defaultRenderGlobals renderAll int 0
Camera camera node renderable
RGB Channel (Color) camera node image
Alpha Channel (Mask) camera node mask
Depth Channel (Z Depth) camera node depth
Custom Extension
Use Custom Extension defaultRenderGlobals outFormatControl
Renumber Frames
Renumber Frames Using renderManGlobals rman__toropt___renumber
Start Frame renderManGlobals rman__toropt___renumberStart
By Frame renderManGlobals rman__toropt___renumberBy
Maintain Width/Height Ratio defaultRenderGlobals aspect
Width rmanFinalGlobals rman__riopt__Format_resolution0
Height renderManGlobals rman__riopt__Format_resolution1
Pixel Aspect Ratio renderManGlobals rman__riopt__Format_pixelaspectratio
Enable Default Light defaultRenderGlobals enableDefaultLight
Pre Render MEL rmanFinalGlobals rman__torattr___preRenderScript
Post Render MEL rmanFinalGlobals rman__torattr___postRenderScript
Shading Rate renderManGlobals rman__riattr___ShadingRate float  
Pixel Samples renderManGlobals rman__riopt___PixelSamples float[2]  
Filter rmanFinalOutputGlobals0 rman__riopt_Display_filter string box
Filter Size rmanFinalOutputGlobals0 rman__riopt_Display_filterwidth float[2]  
Motion Blur
Motion Blur renderManGlobals rman__torattr___motionBlur int 0
Camera Blur renderManGlobals rman__torattr___cameraBlur int 0
Shutter Angle renderManGlobals rman__torattr___shutterAngle float  
Shutter Timing renderManGlobals rman__toropt___shutterTiming string frameOpen
Motion Blur Type renderManGlobals rman__toropt___motionBlurType string frame
Ray Traced Motion Blur renderManGlobals rman__riattr__trace_samplemotion int 0
Ray Tracing
Ray Tracing renderManGlobals rman__torattr___rayTracing int 0
Trace Bias renderManGlobals rman__riattr__trace_bias float  
Max Ray Depth renderManGlobals rman__riopt__trace_maxdepth int  
Max Specular Depth renderManGlobals rman__riattr__trace_maxspeculardepth int  
Max Diffuse Depth renderManGlobals rman__riattr__trace_maxdiffusedepth int  
Environment Light
Environment Image RenderManEnvLightShape1 rman__EnvMap string occlusion
Environment Color RenderManEnvLightShape1 rman__EnvColor float[3]  
Intensity RenderManEnvLightShape1 rman__EnvStrength float  
Emit Specular RenderManEnvLightShape1 rman__EnvEmitSpecular int 0
Emit Diffuse RenderManEnvLightShape1 rman__EnvEmitDiffuse int 0
Primary Visibility RenderManEnvLightShape1 rman__LightPrimaryVisibility int 0
Shadowing RenderManEnvLightShape1 rman__EnvGIScheme string none
Shadow Bias RenderManEnvLightShape1 rman__EnvShadowBias float  
Shadow Gain RenderManEnvLightShape1 rman__EnvShadowGain float  
Occlusion Color RenderManEnvLightShape1 rman__EnvOcclusionColor float[3]  
Sampling Mode RenderManEnvLightShape1 rman__EnvMapScheme string filtered
Samples RenderManEnvLightShape1 rman__EnvSamples float  
Max Variation RenderManEnvLightShape1 rman__EnvGIMaxVariation float  
Diffuse Softness RenderManEnvLightShape1 rman__EnvGIHemisphere float  
Max Dist RenderManEnvLightShape1 rman__EnvGIMaxDist float  
Subset RenderManEnvLightShape1 rman__EnvGISubset string  
Color Correct RenderManEnvLightShape1 rman__EnvColorCorrect int 0
Saturation RenderManEnvLightShape1 rman__EnvColorSaturation float  
Bias RenderManEnvLightShape1 rman__EnvColorBias float[3]  
Gain RenderManEnvLightShape1 rman__EnvColorGain float[3]  
Bake RenderManEnvLightShape1 rman__GDMap string  
Enable Render Layers renderManGlobals rman__toropt___enableRenderLayers int 0
DeepShadow Globals
Phase rmanDeepShadowGlobals rman__torattr___phase    
Resulotion rmanDeepShadowGlobals rman__riopt__Format_resolution int[2]  
Shading Rate rmanDeepShadowGlobals rman__riattr___ShadingRate float  
Pixel Samples rmanDeepShadowGlobals rman__riopt___PixelSamples float[2]  
Motion Blur rmanDeepShadowGlobals rman__torattr___motionBlur int 0
Ray Tracing rmanDeepShadowGlobals rman__torattr___rayTracing int 0
Expand Surface Shaders rmanDeepShadowGlobals rman__torattr___outputSurfaceShaders int 0
Expand Displacement Shaders rmanDeepShadowGlobals rman__torattr___outputDisplacementShaders int 0
Expand Light Shaders rmanDeepShadowGlobals rman__torattr___outputLightShaders int 0
Expand Volume Shaders rmanDeepShadowGlobals rman__torattr___outputVolumeShaders int 0
Final Globals
Image Format rmanFinalOutputGlobals0 rman__riopt__Display_type string  
Channels rmanFinalOutputGlobals0 rman__riopt__Display_mode string  
Filter rmanFinalOutputGlobals0 rman__riopt__Display_filter string  
Filter Size rmanFinalOutputGlobals0 rman__riopt__Display_filterwidth float[2]  
Exposure rmanFinalOutputGlobals0 rman__riopt__Display_exposure float[2]  
Shadow Globals
Phase rmanShadowGlobals rman__torattr___phase string /Job/Preflight/Maps/Shadow
Resulotion rmanShadowGlobals rman__riopt__Format_resolution int[2]  
Shading Rate rmanShadowGlobals rman__riattr___ShadingRate float  
Pixel Samples rmanShadowGlobals rman__riopt___PixelSamples float[2]  
Ray Tracing rmanShadowGlobals rman__torattr___rayTracing int 0
Default Surface Shaders rmanShadowGlobals rman__torattr___defaultSurfaceShader string  
Depth Filter rmanShadowGlobals rman__riopt__Hider_depthfilter string  
Expand Displacement Shaders rmanShadowGlobals rman__torattr___outputDisplacementShaders int 0
Expand Light Shaders rmanShadowGlobals rman__torattr___outputLightShaders int 0
Expand Volume Shaders rmanShadowGlobals rman__torattr___outputVolumeShaders int 0
Depth Filter rmanShadowGlobals rman__riopt__Hider_depthfilter string min
Render Options
Output Statistics renderManGlobals rman__torattr___outputStatistics int  
Bucket Size renderManGlobals rman__riopt__limits_bucketsize int[2]  
Grid Size renderManGlobals rman__riopt__limits_gridsize int  
Extreme Displacement renderManGlobals rman__riopt__limits_extremedisplacement int  
Z Threshold renderManGlobals rman__riopt__limits_zthreshold float[3]  
O Threshold renderManGlobals rman__riopt__limits_othreshold float[3]  
Volume Shading Rate renderManGlobals rman__riopt__limits_vprelativeshadingrate float  
Reference Frame renderManGlobals rman__torattr___referenceFrame int  
Output Directories
Final Images renderManGlobals rman__toropt___imageOutputLoc string  
Texture Cache renderManGlobals rman__toropt___textureOutputLoc string  
Shaders renderManGlobals rman__toropt___shaderOutputLoc string  
Render Data renderManGlobals rman__toropt___renderDataOutputLoc string  
Job Cleanup renderManGlobals rman__toropt___jobCleanupPattern string None
Frame Cleanup renderManGlobals rman__toropt___frameCleanupPattern string None


Another place to look to figure out attribute names is in the mouse-over tooltip for each control in the Render Globals window.


Prev | Next



Pixar Animation Studios
Copyright© Pixar. All rights reserved.
Pixar® and RenderMan® are registered trademarks of Pixar.
All other trademarks are the properties of their respective holders.