Resources Documentation RenderMan :Developers' Guide :The Tools :Scripting :

Tcl Scripting

Tcl Scripting

Introduction

RenderMan for Maya provides a powerful and flexible expression system using the simple syntax of Tcl expr and subst (see also http://www.tcl.tk/doc/). Many predefined as well as dynamically user-defined state variables and procedures can be accessed in expressions to control render settings and shader parameters.

Expressions are evaluated in RenderMan for Maya at different times during the execution of a job, allowing expressions to vary based on different contexts, like per frame, per object, per shading group, etc. Using expressions, artists can control settings in ways that may not be possible with Maya expressions, without requiring any connections. For example, given many instances of an object that share a shader, shader parameters that are controlled by expressions can behave differently based on a given attribute of the instances.

The expression system and its collection of factory procedures is vital to accomplishing many tasks that occur at every press of the render button, like computing output file names, referencing dynamically generated assets, logging the need for pre-passes (e.g. shadow maps) to be generated. These factory procedures are exposed to the user in the initialization files, allowing for customization via site-specific .ini files. (As always, we strongly discourage changing the shipped .ini files; for more information, please consult the Initialization documentation.

String Substitutions

Render settings and shader parameters of type string are automatically evaluated in Tcl by the subst command, which performs backslash, command, and variable substitutions. No special action needs to be taken, simply start using variables or Tcl procedures in string values.

There are a combination of predefined and user-defined variables available in the Tcl interpreter. All of these are available in string substitutions, and the numerical variables, like frame number, are available in numerical expressions.

サンプル

Accessing Maya Attributes in Tcl Expressions

Tcl expressions can access attributes in Maya, like this:

[getAttr $OBJPATH.mystring]

This is equivalent to, but more efficient than the MEL-style call:

[mel "getAttr $OBJPATH.mystring"]

Both versions execute a getAttr command and replace the $OBJPATH variable with the name of the object that the associated appearance is attached to. Presumably, a user has created the variable mystring and placed interesting information therein. Of course, any of the variables described herein, e.g. OBJNAME, are valid in this context.

Animating テクスチャ References

Typically, you'll use string substitutions to construct texture map references by embedding the frame number in your favorite representation. Here's a typical example:

$PROJPATH/sourceimages/flapping.$F4.tex

In this example we refer to two predefined variables to construct a string that looks like:

/puddle/users/carlf/maya/projects/default/sourceimages/flapping.0033.tex

Note that this substitution is made at RIB generation time. The key point to understand is that the string you enter will be passed to Tcl's subst command. You can embed numerical expressions in substitutions through the use of the bracket ([]) operators. Here's an example that remaps the current frame into a different frame:

$PROJPATH/sourceimages/flapping.[format %04.0f [expr fit($F,10,90,1,20)]].tex

This tricky example makes two nested function calls (first to expr, then to format) to create a string that is 4 digits, padded with zeros at the front. The fit function will remap the frame number ($F) into a different range. In this example, frames between 10 and 90 will be mapped to between 1 and 20. Frames outside this range will be 1 or 20. The format cmd will then convert the results of the fit.

Generating Output File Names and References

The procedure called PassFileName can be used to refer to outputs from other passes or to produce an output file name for the current pass. When referring to the outputs of other passes the -validate flag can be used to ensure that the file reference is valid in the current pass context, based on the PassValidityTable.

The PassFileName proc uses two pass settings, called passNameFormat and passExtFormat, which are simply strings of Tcl variables, like ${DSPYBASE${PASSID}${LAYER}. The PassFileName procedure uses these format strings along with some mappings embodied in the FileExtLookupTable and PassValidityTable prefs to compute a file name.

A typical render pass will specify its output file name by an RiDisplay:name setting with value [PassFileName $PASSID]. This causes the file name to be dynamically computed.

[PassFileName $PASSID]

Shader parameters need to be able to refer to these dynamically-generated file names, either because the shader performs baking itself and wants to know where to write data, or because it needs to load data from a previously generated map. The example below shows how a shader param might refer to a point cloud containing subsurface scattering information.

[PassFileName [SSFindRenderPass] -mapname $SHADERGROUP -validate]

In this example, the id of the pass that was responsible for creating the point cloud is computed by a helper procedure called SSFindRenderPass. In RfM this procedure looks for a connected explict pass node, and if it doesn't find one logs a request for a pass to be inferred based on an automatically generated pass id.

Note, there is not necessarily a one-to-one mapping between a render pass and an output file. For example, when a pass uses shaders that bake point clouds, a potentially different output file name can be supplied for each shader call. So variables updated during DAG traversal, like SHADERGROUP or OBJNAME, can be useful in file naming.

Numerical Expressions

Numerical expressions can be used to compute values for render settings or shader parameters with numerical types: int, float, point, color, matrix, etc. These computations are automatically vectorized for non-scalar data types. If writing mathematical expressions isn't your bag, you can use very simple expressions to gain access to animation curves specified in your animation environment. For example, you can create a parameter curve in Maya and refer to that curve in place of an appearance parameter value.

The following expression can be typed into an expression field in the Attribute Editor. It has the effect of linearly interpolating between 0 and 1 based on the percentage of frames that have completed rendering.

[expr lerp(0,1,$PCT)]

The basic form of all expressions is quite simple. An expression is made of a series of potentially nested function or procedure calls whose arguments either return values of other functions or procedures, or variable references. In Tcl, a variable's value is accessed by preceding the variable name with the $ symbol. RenderMan for Maya and Slim conspire to set up special variables that you can refer to in your expressions. In this example, $PCT is such a variable. Function calls can also be combined through the use of standard mathematics operators.

It's important to distinguish between Tcl procedures and functions because they can only be used in certain contexts. A Tcl function requires parentheses to enclose its comma separated argument list and is only meaningful within the scope of the expr command. In the example above, lerp must be a function. To invoke a Tcl procedure within the context of a Tcl expression we are required to enclose the procedure within square brackets, like so:

[expr lerp(0,1,$PCT)] * [myproc 2 3 4]

The Expression Manager

Numerical parameters of RenderMan shader nodes in Maya have a value provider widget (as does Slim) that can be changed to an expression, allowing users to substitute Tcl Expressions. Numerical paramters of native Maya materials can also be controlled with Tcl expressions, but since RfM doesn't have access to the UI for these attributes, users must define Tcl expressions to control them via the RenderMan TCL Expression Manager. When working in Maya's Attribute Editor (with a material selected), the RenderMan TCL Expression Editor can be raised from the Attributes menu: Attributes->RenderMan->Manage TCL Expressions....

images/expressionManager.jpg

The Expression Manager

The Expression Manager has two columns. On the left are all the numerical attributes on the node that can be controlled by expressions. On the right are all the attributes for which expressions have been created. Beneath the columns is a field for editing expressions. And at the bottom of the window are two buttons for creating and removing expressions. Note that different materials have different parameters that are controlled via a numerical expression, so the Expression Manager dynamically updates the attribute list depending on which material you are working with.

When attributes on the left are selected, the create button is enabled and the expression field is editable; its contents are used to initialize expressions for the attributes that have been selected when the create button is pushed (and the attribute is removed from the column on the left and added to the column on the right). When expressions on the right are selected, the remove button is enabled. The expression field is also editable, and any edits to the field apply to all selected expressions. Removing an attribute expression repopulates the attribute to the column on the left.

Once expressions have been added to the node, they appear, one per attribute, under the RenderMan Extra Attributes in the Attribute Editor. They can either be edited there or in the Expression Manager window.

Extending the System

You can extend the set of functions and variables available to your expressions by placing custom Tcl procs in a file that is loaded via a LoadExtension directive in the appropriate initialization files.

Startup スクリプト

The RMSExpression.tcl script defines the standard variables and procedures that will be available in the scripting interpreter. The script is loaded by the initialization file called RMS.ini, which is loaded by both RenderMan for Maya and Slim. Users who wish to extend the list of variables and procedures should load them in their own RMS.ini, referenced by the RMS_SCRIPT_PATHS environment variable or tucked away in the user's preferences directory, e.g.:

Linux
~/.pixarPrefs/RenderManStudio/[version]/
OS X
/Users/[user]/Library/Preferences/Pixar/RenderManStudio/[version]/
Windows Vista
C:\Users\[user]\AppData\Roaming\Pixar\RenderManStudio\[version\
Windows XP
C:\Documents and Settings\[user]\Application Data\Pixar\RenderManStudio\[version]\

For more information about initialization files, please consult the Initialization documentation.

Custom Scripting Variables

For site-specific variables, the pref SiteScriptingVars can be set in the RMSWorkspace.ini file. SiteScriptingVars can be used to enumerate the variables that you wish to add to the base scripting state. For example:

SetPref SiteScriptingVars {CINERES RENDERINGMODE}

We recommend adopting a naming convention that clarifies the site-specific nature of these variables.

SiteScriptingVars will be automatically synchronized with Slim periodically during RfM operation. Additionally, you can explicitly update Slim with the state (assuming it's running) via the MEL call rman("slim", "send", "status", "update") or rman slim send status update. Depending on your use of these variables, this may not be necessary.

Environment Variables

All variables from the environment in which Maya was launched are made available as Tcl variables with the same name. These are only initialized when the application is first started, so they cannot be changed. Nota Bene: variables from the environment do not override predefined Tcl variables with the same name!

Injection Points

Injection points are attributes that can exist in the render settings and arbitrarily throughout Maya's DAG. They are a powerful mechanism by which users can insert Ri calls into the RIB stream or evaluate Tcl expressions to prepare the context for shader parameter expressions.

Unlike other render settings of type string, Ri injection points are not evaluated in the Tcl interpreter. Instead, they are executed in Maya's MEL interpreter, where Ri bindings are available. Access to the Tcl interpreter is available from MEL via the command called rman subst.

The following injection points are available in the render settings and are independent of DAG traversal:

  • Render Begin - often a comment, at the very beginning of the RIB file.
  • FrameBegin - after FrameBegin
  • FrameEnd - after FrameEnd
  • Pre WorldBegin - before WorldBegin
  • Post WorldBegin - after WorldBegin
  • Default RiOptions - after the options emitted by RfM
  • Default RiAttributes - after the attributes emitted by RfM

The following injection points may be added in Maya's DAG or globally in the Render Settings:

  • TransformBegin - after AttributeBegin for a transform
  • Post Transform - after a Transform is emitted
  • TransformEnd - before AttributeEnd for a Transform
  • Pre Shape - before geometry, after its attributes and shading
  • Post Shape - after geometry for a shape

Reference

Expression Contexts

Expressions are evaluated in RenderMan for Maya at different times during the execution of a job. This allows expressions to access variables that may vary per frame, per object, etc. Furthermore, certain variables are only guaranteed to be valid within a particular expression context. The EXPRESSION_CONTEXT variable contains the current context during which expression evaluation is being performed.

Top level pass contexts:

  • populatephase - The job execution graph is assembled during this context.
  • cachepass - Per job or per frame updates are made to the cache.
  • compilepass - RenderMan shaders translated from Maya shaders are compiled.
  • renderpass - A render pass, like a shadow or final render.
  • commandpass - A command pass, like a txmake, ptfilter, or brickmake is executed.
  • clientscriptpass - Pre- or post-frame render scripts are executed.
  • cleanuppass - At the end of a frame or job, cleanup occurs.
  • txmakepass - A txmake pass.

The pass contexts above are not nested within each other, but the following contexts may be nested with a pass context:

  • riopt - Ri options are being interpolated.
  • toropt - TOR options are being interpolated.
  • shadergroup - A Maya shading group is in effect.
  • shader - A RenderMan shader call is being assembled.
  • prim - During cachepass or renderpass, the Maya scene DAG is traversed, and different prim contexts become active.
  • riattr - Ri attributes may be interpolated either in top level pass contexts or within prim contexts.
  • torattr - TOR attributes may be interpolated either in top level pass contexts or within prim contexts.
  • param - Params make up the parameter lists for all kinds of settings, so they may be valid in riopt, toropt, shader, riattr, or torattr.

The Tcl procedure called GetExpressionContextStack can be used to get a stack of the current contexts. For example, it might return renderpass riopt param. In this example, a parameter in the parameter list for an Ri Option call is being substituted during a render pass.

Predefined Tcl Variables

Certain Tcl variables are automatically updated at different points during scene translation and rendering. These are state variables that are defined and accessed by procedures in the RMSExpression.tcl initialization script.

Following is the list of predefined variables, and when they are updated:

Static Variables

Static variables are updated once when the application is loaded.

Application Variables

  • APPNAME - The name of the application, like RenderMan_for_Maya or Slim.
  • APPVERS - A verbose string indicating the version and timestamp of the application.
  • APPLOC- The name of the directory where the application is running from.
  • PID - The process ID number of the running application.
  • HOST - The name of the computer where the application is running.

User Variables

  • USER - The name of the user running the application.
  • HOME - The user's home directory.
Dynamic Variables

Dynamic variables are updated at different times throughout the execution of a job.

Job Variables

Job variables are updated once at the beginning of a job.

  • JOBID - A unique ID string for the current job.
  • JOBSTYLE - A value that is intended to be queried by user defined spooling or pre-render scripts. Its value is empty unless specified by the user.
  • TIMESTAMP - A string describing the date and time when the current job was launched.

Workspace Variables

Workspace variables are updated at the beginning of a job and at additional times thereafter for asset references, because workspace variables may require different values when computing cross-project asset references. The original state of the workspace variables is restored after an asset reference is computed.

  • WSCLASS - Has one of two values: primary indicates that job-wide workspace values are in effect; AssetRef indicates a reference to a file is being computed.
  • FILE - The full path name of the Maya scene file.
  • FILEBASE - The base name of the Maya scene file, without the extension.
  • DSPYBASE - The base name used for naming the primary output image. By default this is the same as FILEBASE, but it takes the image file prefix setting into consideration.
  • STAGE - A namespace that can be used to prevent asset-name collisions. Its value can be derived from any source, but by default it's based on the current scene file. (Users should consult the Asset Management documentation for more details about STAGE.)
  • PROJPATH - The path name of the current maya project.
  • LAYER - When rendering multiple render layers, this variable indicates the name of the current render layer.

Asset Output Variables

Asset output directory patterns are updated once at the beginning of a job. By default these are project-relative directory names.

  • RIBPATH - The output directory for rib files.
  • SHADERPATH - The output directory for shaders compiled by RfM.
  • IMAGEPATH - The output directory for final rendered images.
  • DATAPATH - The output directory for data from intermediate passes that contribute data to the final render pass.
  • TEXTUREPATH - The ouput directory for automatically converted texture files.

Animation Variables

These animation timing related variables are updated once, at the beginning of a job.

  • FIRSTFRAME - The first frame of the sequence being rendered.
  • LASTFRAME - The last frame of the sequence being rendered.
  • FPS - The frames per second.

Frame Variables

Frame variables are updated at the beginning of execution for each frame in the job, and also for the preflight, which runs before the frames at the beginning of the job itself.

  • F - The current frame number, with no padding.
  • F1, F2, F3, F4, etc. - The current frame number, with the indicated amout of padding.
  • FF - The floating point portion of the frame number. This value is set during subframe motion blur, when caching occurs at a non-integer time between frames.
  • PCT - This variable contains a number between 0 and 1 indicating the current frame's place in the entire job. Pass this value to functions that vary over the duration of your shot. See mathematical functions.

Pass Variables

Pass variables are updated at the beginning of each pass. There may be multiple passes per frame.

  • PASSID - A unique identifier for the current pass. For explicit passes, the name of the pass node in Maya is used as the PASSID. For implied passes a unique identifier is constructed with the Tcl procedure called PassID, which is based on the pass class, camera, camera flavor, and crew.
  • PASSCLASS - Each pass has a pass class that indicates the name of the template that describes its default settings and serves as a way to categorize passes, e.g. Shadow, Final, etc.
  • CAMERA - The name of the camera used by the pass.
  • CAMERAFLAVOR - Can be used to indicate that the camera should look down one of its axes: px, nx, py, ny, pz, nz. Used for point or area light shadows.
  • DEFAULTCAMERA - Contains the name of the first renderable camera in the scene.
  • CREW - The set of objects to be rendered by a pass.
  • FLAVOR - Can be used as a pass motidier, empty by default.

Command Pass Variables

  • CMD - When a command pass is run, this variable contains the command that will be run, like ptfilter, brickmake, or txmake.
  • CMDARGS - When a command pass is run, settings on the command pass are assembled into an argument list for the command and stashed in this variable.

Bake Pass Variables

  • BAKECHANNELS - When baking lighting to textures, the BAKECHANNELS variable contains the comma-delimited list of channels to be baked.
  • BAKECHAN - When baking lighting to textures, the BAKECHAN contains the current channel for which an output file name is being generated.

File Extension Variables

  • EXT - When an output file name is generated, the EXT var contains the value of the extension, including the dot, i.e. .tiff rather than just tiff.
  • EXT_NO_DOT - When an output file name is generated, the EXT_NO_DOT var contains the value of the extension, without a dot.

Display Variables

Updated per display.

  • DSPYCHAN - When outputting a RiDisplay call, the DSPYCHAN corresponds to the mode of the display.
  • DSPYTYPE - When outputting a RiDisplay call, the DSPYTYPE corresponds to the type of the disply, e.g. tiff, openexr.

Object Variables

Updated each time a DAG node is traversed.

  • OBJPATH - The Maya partial DAG path name of the current primitive.
  • OBJNAME - The name of the Maya shape node for the current primitive.

Shader Group Variables

Updated each time a shader group is emitted.

  • SHADERGROUP - The name of the current shading group.

Shader Variables

  • SHADERHANDLE - Corresponds to the name of a shading node in Maya.
  • SHADERNAME - The name of the RenderMan shader (.slo) on disk.
  • SHADERTYPE - The type of the RenderMan shader: light, surface, displacement, volume.

Parameter Variables

Updated before each setting or parameter is evaluated

  • PARMNAME - The name of the current setting or parameter in a paramter list.
  • PARMTYPE - The type of the current setting or parameter.
  • PARMSUBTYPE - The subtype of the current setting or parameter.
  • PARMVALUE - The value of the current setting or parameter.

Factory Functions, Procedures, and Operators

You can use standard functions and procedures in your expressions. Functions and procedures have different syntax and can be used in difference contexts. Procedure calls have this syntax, [procname arg1 arg2 ..], and functions have this syntax, funcname(arg1, arg2).

Waveform Generators, Interpolators
  • lerp(a,b,t) - Linearly interpolate between a and b using t, t in the range 0 to 1.
  • flerp(a,b,f,startf,endf) - Same as lerp but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf.
  • ease(a,b,t) - Cubic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at both ends.
  • fease(a,b,f,startf,endf) - Same as ease but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf.
  • easein(a,b,t) - Quadratic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at beginning.
  • feasein(a,b,f,startf,endf) - Same as easein but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf.
  • easeout(a,b,t) - Quadratic interpolation between a and b using t, t in the range 0 to 1. Tangent of zero at end.
  • feasout(a,b,f,startf,endf) - Same as easeout but more convenient for frame ranges. A value between a and b is returned when f is between startf and endf.
  • noise(t) - Perlin style noise, returns values between -1 and 1. t is the wave parameter representing pseudo periods of the noise function. If you want 5 periods of noise over your animation you can use: noise(5 * $PCT).
  • fit(x,a1,b1,a2,b2) (also map) - Takes a value x between a1 and b1 and remaps it into the range described by a2 and b2. The remapping is a linear function and values of x which lie outside the range (a1,b1) are clamped.

The following wave generation functions are presented in Waveform Generators for Computer Graphics by C. Schlick - Graphic Gems Vol V. The parameter t is as above, s is the shape factor in the range [-1,1], f is the frequency variance in the range [0,1] and a is the amplitude variance in the range [0,1].

  • rwave(t,s,f,a) - Generates rectangular-like waves.
  • twave(t,s,f,a) - Generates triangular-like waves.
  • swave(t,s,f,a) - Generates sinusoidal-like waves.
  • [spline1 $PCT {k1 v1} {k2 v2} {k3 v3}...] - Returns the evaluation of the 1-D spline given by the list of knots provided as arguments. Knots are x-y pairs where the x values are monotonically increasing parameter values and y is the function's value. The spline is deemed 1D because there's a single y value for each x.
  • [spline3 $PCT {k1 {r1 g1 b1}} {k2 {r2 g2 b2}}...] - Returns the evaluation of the 3-D spline given by the list of knots provided as arguments. Knots are x-y pairs where the x values are monotonically increasing parameter values and y is the function's value. The spline is deemed 3D because there're three y values for each x.
  • [fit args] (-pad %d, -in a b, -out c d) - A procedure version of the function described above.
カラー and Point Functions
  • rgb(r,g,b), rgbi(ir,ig,ib) - Allow the specification of color (vector) parameters. r,g,b in the range [0,1], ir,ig,ib in the range [0,255].
  • hsv(h,s,v), hsvi(ih,is,iv) - Allow the specification of color (vector) parameters in the HSV color space. h,s,v in the range [0,1], ih,is,iv in the range [0,255]. Note that this will immediately convert the hsv values to rgb values.
  • xyz(x,y,z) - Allow the specification of point (vector) parameters.
Math and ユーティリティ Functions
  • rad(d) - Convert degrees to radians.
  • deg(r) - Convert radians to degrees.
  • abs(x) - Absolute value of x.
  • acos(x) - Arc cosine of x, in the range 0 to pi.
  • asin(x) - Arc sine of x, in the range -pi/2 to pi/2.
  • atan(x) - Arc tangent of x, in the range -pi/2 to pi/2.
  • atan2(x,y) - Arc tangent of x/y, in the range -pi/2 to pi/2.
  • ceil(x) - Smallest integer not less than x.
  • cos(x) - Cosine of x (x in radians).
  • cosh(x) - Hyperbolic cosine of x.
  • double(i) - Real value equal to integer i.
  • exp(x) - e raised to the power x.
  • floor(x) - Largest integer not greater than x.
  • fmod(x,y) - Real remainder of x divided by y.
  • hypot(x,y) - Square root of (x*x + y*y).
  • int(x) - Integer value produced by truncating x toward 0.
  • log(x) - Natural logarithm of x.
  • log10(x) - Base 10 logarithm of x.
  • pow(x,y) - x raised to the power y.
  • rand(), srand(x) - return random values between 0 and 1. srand determines its value based on the provided integral seed.
  • round(x) - Integer value produced by rounding x.
  • sin(x) - Sine of x (x in radians).
  • sinh(x) - Hyperbolic sine of x.
  • sqrt(x) - Square root of x.
  • tan(x) - Tangent of x (x in radians).
  • tanx(x) - Hyperbolic tangent of x.
Operators
  • -a - Negative of a.
  • !a - Logical NOT:. 1 if a is zero, 0 otherwise.
  • ~a - Bit wise complement of a.
  • a * b - Multiply a by b.
  • a / b Divide a by b.
  • a % b - Remainder after dividing a by b.
  • a + b - Add a and b.
  • a - b - Subtract b from a.
  • a < b - 1 if a is less than b, 0 otherwise.
  • a > b - 1 if a is greater than b, 0 otherwise.
  • a <= b - 1 if a is less than or equal to b, 0 otherwise.
  • a >= b - 1 if a is greater than b, 0 otherwise.
  • a == b - 1 if a is equal to b, 0 otherwise.
  • a != b - 1 if a is not equal to b, 0 otherwise.
  • a ? b : c - Choice: if a is non zero then b, else c.
TM & © 1986 - Pixar. All Rights Reserved.