Slim's Core Functions: Special Appearances

Special appearances perform unique roles and functions. These are generally MTOR concepts which provide an extra level of functionality for the user. These different special appearance types can provide a meta-level of control over scene management by supporting functionality beyond PRMan itself. MTOR supports these "meta concepts" and translates them for PRMan during RIB generation. For instance, in PRMan a single shader cannot contain surface, bump, and light shader information, but MTOR provides this functionality with the Ensemble, allowing multiple types of shader information to be attached to an object at once, instead of attaching each different shader individually. MTOR breaks down the ensemble into individual connections during RIB generation. Here is a list of the special case appearances:

Adaptor	Describe different appearance attachments for different rendering conditions.
AOV	Use Arbitrary Output Variables in a shader.
Archiver	Automatically cache and reference portions of your scene graph. This can result in dramatically faster rib gens. Animated cycles can even be archived.
Ensemble	Attach different shader types simultaneously.
Map Generator	Map Generators allow the calculation of many kinds of arbitrary maps.
RIB Box	Insert chunks of RIB to be added into the scene at different point in the RIB stream.
SL Box	Insert custom shading language code into your shaders.
TCLBox	Define chunks of Tcl to be evaluated prior to the per-object RIB encapsulation of other shaders. You can initialize values referred to in parameter expressions of other appearances.

The Adaptor

Description: There are a variety of adaptors for different appearance types. Adaptors allow you to attach different appearances under different rendering conditions, providing a system for selecting an appearance type based on an evaluation context. You can establish different shader connections under differing conditions. You might, for example, have different shaders for different lighting conditions. Available contexts are described under the Controller parameter.

Adapters are extremely powerful way to manage shader connections. The ordered list of conditions represent a simple program. The list is traversed from top to bottom and the resulting appearance is that associated with the first condition that matches the controller conditions.

Controller: The controlling variable against which Condition strings are compared. You can select from the pull-down menu:

Context is set up via the RenderMan Globals dialog or within a Map Generator. The context for a scene is defined in the Context setting of the RenderMan Globals.
Object Name is the brief name of the attached geometry. One ensemble can be attached to a character, for instance, and different shaders will be attached to different objects. Which shader is attached to which object is determined by the object name.
Object Path is the full dag path name.
Element Name is the name of the element.
Elements are the subframes (shadows, environments, reference images) that make up a frame and the element name is typically the object used to drive the subframe.
Element Type is the type of the element. Choices are: final, shadow, reflection, environment and reference. Display Name is the name entered in the RenderMan Globals Dialog.

Add Condition: Create a new adaptor connection. The double arrows return selected objects from the Maya scene. The pull-down menu describes the comparison algorithm. You have a choice of:

Match - simple glob-style pattern matches
Regexp - complicated regular expression matching
Lsearch - simple set membership matching. This setting is appropriate for results returned from the Maya scene, via the double arrows.

Using Adaptors: In our example, we have a context sensitive Ensemble Adaptor. Let's see how it works.

First of all, the controller is set to "Context." We can define the context of a scene in the context setting of the RenderMan Globals.

We have several Ensembles connected to this Adaptor, but which ensemble is attached to an object is determined by what is defined as the context in the RenderMan Globals. If the context is defined as "night" then Ensemble_0 will be used. If the context is "day" then Ensemble_1 will be used. If any other context is entered then Ensemble_2 will be used as its field contents, "*", will match anything. Notice that the conditions are evaluated in order, so if the third condition was moved to the top, it would always be attached since its field, "*", matches anything.

Conclusion: Now this adaptor can be attached to an object, and it's simple to assign different shaders for either daytime or night scenes. We don't need to create or delete connections. All that needs to be done is enter a new context. To get even more advanced, we can plug this adaptor into *another* adaptor, perhaps one set to "Object Name." Now imagine this: a single adaptor can be attached to all of the objects in a scene, and it will attach the appropriate appearance to each individual object based on the object name (attaching the hat shader to the hat, the jacket shader to the jacket). With the proper adaptors attached to the objects by name, the appropriate day or night version of a shader is then attached by the context setting.

Example Adaptor Shading Network
There's an example of an adaptor over in the shader recipes, where an adaptor is used to create special reflection effects. A complete Maya scene file is provided with a fully operational adaptor.

Archiver

Description: Attach AutoArchive appearances to nodes in your DAG to cause all child nodes to be written to an external RIB Archive file and automatically referenced for final RIB generation. This can greatly speed up your RIB generation process if Laziness is enabled or if an object doesn't change over the course of a shot.

Control:These parameters control how the archive is read.

Read Method:Use DelayedReadArchive to allow the renderer to determine when an archive should actually be loaded. If you always want your Archive to be loaded, choose ReadArchive.

Visibility: Controls the presence of the archive reference in various rendering passes.

Motion Blur:Controls the motion blur attribute for the entire archive at the time the archive is included. If you wish to use the DAG node to move a rigid archive around AND you want motion blur, make sure this attribute is enabled.

Writing: These parameters control how the archive is written.

Base Name:The name to be prepended onto all RIB archive files. The default value $JOBNAME is the name entered in the Display Name field of RenderMan Globals. If you want to share auto-archives across jobs, you should enter your own base name here.

Frequency: Controls how often you want to archive your objects. If your object is rigid, select "Once Per Job" otherwise select "Every Frame".

Recylcing After: Use this setting to archive animated cycles.

Laziness: Controls how often the RIB Archive is constructed. When Laziness is enabled, the mere existence of the target RIB file will prevent the construction of a new Archive. In this case, it's up to you to ensure that the existing Archive is up to date.

Archive Contents: The selected components will appear in the Archived RIB.

Base Light Handles: The Base Light Handle can be used to help prevent light handle collisions and only comes into play when archiving lights.

Ensemble

Description: An ensemble provides controls over many aspects of the RenderMan shading state, including important overrides for ray traced shaders. Note: both shader networks and regular RenderMan shaders (.sl .slo) can be attached to ensembles.

The Ensemble's Ray Tracing Controls

Rays
In the Rays collection tab there are attributes associated with surfaces. These are the very same controls located in the lower portion of RenderMan controls. The settings at right are such that the values specified there are inherited. Changing the settings in the ensemble allows you to associate independent behavior on a per-surface basis.

Sample Motion
Controls whether motion blurred objects appear in ray traced results. If your reflective object is moving or deforming you should disable this parameter to avoid self-intersection artifacts. If your mirror isn't moving, set this to 1 to see the reflected objects properly blurred.

Trace Displacements
Controls whether to run displacement shaders to determine ray intersection points. Disabling this option will result in a bump-mapped appearance and make your renders faster. Only enable this if you need to run displacements on the associated primitives.

Trace Bias
Specifies a "fudge factor" for ray intersections. This bias value is added to the ray origin (and endpoint for shadows) to reduce artifacts pertaining to numerial precision limitations and self-intersection.

Max Specular Depth
Limits the number of reflection and refraction ray bounces relative to the associated primitive. The behavior of this setting can be confusing when you consider that it might have different settings along a particular ray path. Lower numbers result in fewer bounces and faster renders. Usually you'll want to set this value to 1 or 2 but you should set this value to the lowest number that gives you the inter-reflection effects you need. Setting this value to -1 results in the default specular ray depth limit

Max Diffuse Depth
Limits the number of soft indirect ray bounces relative to the associated primitive. The soft indirect rays are used to estimate color bleeding and similar effects. The default limit of 1 implies that we should only look a single bounce away to determine color bleeding. The behavior of this setting can be confusing when you consider that there might be different settings along a particular ray path. Lower numbers result in fewer bounces and faster renders. Usually you'll want to set this value to 1 but you should set this value to the lowest number that gives you the inter-reflection effects you need. When used with global photon maps you should never need to set this to a value greater than 1. Setting this value to -1 results in the default diffuse ray depth limit.

Irradiance Cache
These parameters govern the caching of irradiance which is required to obtain indirect diffuse lighting effects. The phrase, indirect diffuse, refers to global illumination that follows diffuse ray paths. This indirect, diffuse lighting is responsible for color bleeding and other subtle effects.

Max Error
An error metric to control quality / speed tradeoff for irradiance cache accesses.. Larger values result in a courser approximation but render faster. Set this value to 0 to disable the irradiance cache. Set this value to a negative number to inherit Max Error.

Max Pixel Distance
A backup error metric governing the use of the irradiance cache. Large values result in course approximations but render faster. Max Pixel Distance is measured in pixels and is usually useful to ensure that the Max Error metric doesn't result in too much work in areas which are large in world space but small on screen. Set this value to 0 to disable the irradiance cache. Set this value to a negative number to inherit the Max Pixel Distance.

Cache File
Usually, it's sufficient to use a single scene-wide irradiance cache and this is specified in the RenderMan Controls dialog. In the case where you wish to "bake" irradiance, it may be desireable to control the irradiance cache settings on a per-primitive or per-object-set basis. In these cases, this attribute can be used to specify the per-object irradiance cache file whose use depends on the File Mode. The easiest way to specify a filename relative to the current project is with an expression of the form: [irradiancecache name] Refer to the description of the Cache File Mode for other usage details. Set this value to (inherited) to inherit the scene-wide default.

Cache File Mode
When the irradiance cache handle is set, this file mode determines how to interpret and update the cache's contents. When the file mode is read-only, we use the given file to seed the run-time irradiance cache. Now during rendering the cache is updated as needed and these updates will be lost when rendering completes. If you set the mode to read-write, the cached results will be stored back into the specified file. If you choose the write-only mode the contents of the file will not be loaded (if it exists) but the file will be updated on completion of rendering.

Photon Maps
These parameters control the creation and access to photon maps. Photons maps come in two flavors - global and caustic. Caustic maps are used on the surfaces where the caustics appear while global photon maps are usually referenced for the sole purpose of estimate light "over there".

Shading Model
Specifies a simplified shading model to employ when tracing photons. If empty, the attached surface shader will be analyzed to determine photon scattering.

Estimator
Controls the number of photons considered when estimating global illumination with photon maps. Also used when precomputing radiance estimates for global photon maps. When used with caustic photon maps, you should set this value to the smallest number you can. This will result in crisp caustics. Higher numbers will make the caustics blurrier. For soft indirect illuminance (color bleeding, etc.) you'll need larger values to get acceptable results. Set this value to -1 to accept the default.

Caustic Map
Specifies the caustic photonmap to use if a shader with the caustic shade-op is provided. Set this value to (inherited) to inherit the value from the global RIB state. Set the value to the empty string to cause no caustic lookups on associated primitives.

Global Map
Specifies the global photonmap to use if a shader which needs to esimate soft indirect illumination at points on the associated primitive. Set this value to (inherited) to inherit the value from the global RIB state. Set the value to the empty string to cause no global lookups on associated primitives.

The Ensemble's General Parameters

Shading Rate
Controls the quality of the shader evaluation on a per-ensemble basis. If 0, the global value will be used. Generally you'll only want to use this value in the rare case that you want to override the global behavior.

Shader Space
The coordinate system in which a shader is defined. Most shaders perform important calculations relative to this space and so transforming it affects their appearance. If empty, the shader space is the object space associated with the attached primitive. Place the name of a coordinate system object here to set the shader space for the shader. If you're using file referencing, use the "coordsys" function to translate the name of the coordinate system (eg: [coordsys mtorCoordSysShape10].

Scale
An additional uniform scale factor applied on top of the optional coordinate system.

Cast Shadows
Controls how surfaces shadow other surfaces. Possible values for shadow eval are shown below, in order of increasing computational cost. You can optimize rendering time by making surfaces known to be opaque "opaque". To take an object out of consideration during shadow generation, disable the per-object attribute in your modeler. It is important, however, to use "shade" for any surfaces whose shaders modify the opacity of the surface in any patterned way.

Cs
The RenderMan Surface Color Attribute. Note that some shaders don't automatically use this value. You may need to explicitly choose Surface Color as the parameter value.

Os
The RenderMan Surface Opacity Attribute. Note that some shaders don't automatically use this value. You may need to explicitly choose Surface Opacity as the parameter value.

Displacement Bound
This number represents the maximum displacement in shaderspace that your surface will undergo. Be very careful with this parameter as it can dramatically influence rendering times. In particular, make SURE to set this to 0 (zero) if you aren't performing any displacement.

Surface
Attach a shading model

Displacement
Attach a bump or displacement

Atmosphere
Attach an atmosphere effect

RIB Box
Attach a RIB box

Light1
Attach a light

Light2
Attach a second light

Tcl Box
Attach a Tcl box

SL Box

Description: SL Boxes are a class of shader construction functions that allow you to define your own shading language code. SL Box templates are defined for types float, color, vector, manifold, and shadingmodel.

Parameters
This is the list of parameters to your SL Code. No parameters will be here when you first create your SL Box. Parameters can be added using the + button. Parameters of atomic types like float and color are all varying by default and can be connected. Parameter collections (manifold, shadingmodel) will be created with detail "mustvary", i.e. they must be connected.

Includes
List any files you need to include here. Just list the file, you do not need to use the #include directive, e.g.:

  pxslRemap.h

Primvars
The Primvars section allows you to declare any primvars you may wish to reference. In this case, write valid RSL code, e.g.:

  uniform float gprimType = 1;

SL Code
With your parameters in place, write the RSL code to manipulate them. By default, parameters will appear with names like v1, v2, v3,etc. You can use these names, or you can edit the labels of your parameters and refer to them using (the RSL-safe versions of) those. (Note that editing these labels will create new temporary variables in your function.)

You should save the results of your computations in the result variable(s) created for you and listed in the "SL Code." Each variable will be preceded by a comment reminding you of its type.

The triangular widgets associated with Includes, Primvars, and SL Code present small textboxes that allow you to edit these within the Appearance Editor. The Edit... button allows you to edit the values in your preferred text editor. Doing so will disable the textbox.

Slim's Core Functions

The Core Set of Functions

Special Appearances

The Adaptor

AOV

Archiver

Ensemble

RIBBox

SL Box

TCLBox