Prev | Next

      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:

rman__setting-type__namespace_setting-name

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:

toropt

Translator options. These settings are used in the process of translating a maya scene. They apply across an entire rendering job.

torattr

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.

riopt

RenderMan Options are settings that affect the rendering of an entire image. The names of some riopts and riattrs may require a namespace.

riattr

RenderMan Attributes are settings that are part of the graphics state, and unlike Options can be associated with individual primitives.

param

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.

(top)

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 //

(top)

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 )

Example:

    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 //

(top)

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";

(top)

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";

(top)

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.

Example:

    deleteAttr nurbsSphereShape1.rman__riattr___ShadingRate

(top)

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;

(top)

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:

      rmanCreateGlobals;

This command creates an environment light:

      rmanCreateEnvLight;

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
Common
Image File Output
File Name Prefix	defaultRenderGlobals	imageFilePrefix
Frame/Animation Ext	rmanFinalGlobals	rman__torattr___passNameFormat rman__torattr___passExtFormat
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 1
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
Resolution
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
Quality
Shading Rate	renderManGlobals	rman__riattr___ShadingRate	float
Pixel Samples	renderManGlobals	rman__riopt___PixelSamples	float[2]
Filter	rmanFinalOutputGlobals0	rman__riopt_Display_filter	string	box triangle catmull-rom sinc gaussian mitchell seperable-catmull-rom blackman-harris
Filter Size	rmanFinalOutputGlobals0	rman__riopt_Display_filterwidth	float[2]
Features
Motion Blur
Motion Blur	renderManGlobals	rman__torattr___motionBlur	int	0 1
Camera Blur	renderManGlobals	rman__torattr___cameraBlur	int	0 1
Shutter Angle	renderManGlobals	rman__torattr___shutterAngle	float
Shutter Timing	renderManGlobals	rman__toropt___shutterTiming	string	frameOpen frameCenter frameClose
Motion Blur Type	renderManGlobals	rman__toropt___motionBlurType	string	frame subframe
Ray Traced Motion Blur	renderManGlobals	rman__riattr__trace_samplemotion	int	0 1
Ray Tracing
Ray Tracing	renderManGlobals	rman__torattr___rayTracing	int	0 1
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 irradiance
Environment Color	RenderManEnvLightShape1	rman__EnvColor	float[3]
Intensity	RenderManEnvLightShape1	rman__EnvStrength	float
Emit Specular	RenderManEnvLightShape1	rman__EnvEmitSpecular	int	0 1
Emit Diffuse	RenderManEnvLightShape1	rman__EnvEmitDiffuse	int	0 1
Primary Visibility	RenderManEnvLightShape1	rman__LightPrimaryVisibility	int	0 1
Shadowing	RenderManEnvLightShape1	rman__EnvGIScheme	string	none occlusion colorbleeding
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 sampled baked
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 1
Saturation	RenderManEnvLightShape1	rman__EnvColorSaturation	float
Bias	RenderManEnvLightShape1	rman__EnvColorBias	float[3]
Gain	RenderManEnvLightShape1	rman__EnvColorGain	float[3]
Bake	RenderManEnvLightShape1	rman__GDMap	string
Passes
Enable Render Layers	renderManGlobals	rman__toropt___enableRenderLayers	int	0 1
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 1
Ray Tracing	rmanDeepShadowGlobals	rman__torattr___rayTracing	int	0 1
Expand Surface Shaders	rmanDeepShadowGlobals	rman__torattr___outputSurfaceShaders	int	0 1
Expand Displacement Shaders	rmanDeepShadowGlobals	rman__torattr___outputDisplacementShaders	int	0 1
Expand Light Shaders	rmanDeepShadowGlobals	rman__torattr___outputLightShaders	int	0 1
Expand Volume Shaders	rmanDeepShadowGlobals	rman__torattr___outputVolumeShaders	int	0 1
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 /Job/Frames/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 1
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 1
Expand Light Shaders	rmanShadowGlobals	rman__torattr___outputLightShaders	int	0 1
Expand Volume Shaders	rmanShadowGlobals	rman__torattr___outputVolumeShaders	int	0 1
Depth Filter	rmanShadowGlobals	rman__riopt__Hider_depthfilter	string	min max average midpoint
Advanced
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
Cleanup
Job Cleanup	renderManGlobals	rman__toropt___jobCleanupPattern	string	None Shadows All
Frame Cleanup	renderManGlobals	rman__toropt___frameCleanupPattern	string	None Shadows All

---

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

---

(top)

Prev | Next