OptionsOptionsEvery implementation of a RenderMan-compliant rendering program has certain implementation-specific features which are accessed through the functions RiAttribute and RiOption.
Options are parameters that affect the rendering of an entire image. They must be set before calling RiWorldBegin, since at that point options for a specific frame are frozen.
The PRMan Quick Reference includes a table that summarizes summarizes the options available in PhotoRealistic RenderMan. Note that some of the defaults listed can be overridden by configuration files (see Section 2.8).
The following sections describe the options available to control the operation of PhotoRealistic RenderMan. Each section gives an example of the use of the option as it would appear in RenderMan Interface. In addition, PhotoRealistic RenderMan implements certain extensions to other parts of the RenderMan Interface, as described in the RenderMan Interface Specification Version 3.2. These extensions are described in Section 6.
There are several options which can be enabled through the parameter list of the RiDisplay call. These options, naturally enough, influence the use of the display device.
The origin of the output window on a frame buffer device can be set using the display origin option. For example, to place the origin of the output window at the point (512,384):
RtInt o[2] = {512, 384};
RiDisplay("name", "framebuffer", "rgba",
"origin", (RtPointer)o, RI_NULL);
Frame buffers can be configured to merge the generated image over an existing image with the display merge option:
RtInt flag = 1;
RiDisplay("name", "framebuffer", "rgba",
"merge", (RtPointer)&flag, RI_NULL);
The merge option works only if the selected display driver supports it.
Some file formats (e.g., TIFF, Postscript) support the concept of device resolution, meaning how many pixels appear per physical unit of measure (e.g., dots per inch). Two display options provide a way to document these values into files generated by PhotoRealistic RenderMan. A string specifying the physical unit of resolution can be set with the resolutionunit option. A pair of integers specifying the number of pixels per resolution unit in width and height can be set with the resolution option. For example, to set the resolution at 72 dpi:
RtString ru[1] = "inch";
RtInt r[2] = {72, 72};
RiDisplay("name", "TIFF", "rgba",
"resolution", (RtPointer)r,
"resolutionunit", (RtPointer)ru, RI_NULL);
Currently, the TIFF file driver considers both resolutionunit, which must be "inch" or "centimeter", and both resolution values. The PICT and Postscript drivers only consider the first resolution value, as images in these formats must have the same value in both directions, and implicitly assume inches as the resolution unit.
The TIFF driver also accepts an option to set the compression type, which may be "lzw", "packbits", "zip" (the default), "pixarlog", or "none":
RtString cmp[1] = "none";
RiDisplay("name", "TIFF", "rgba",
"compression", (RtPointer)cmp, RI_NULL );
Custom display drivers may also accept other display options, but they must be declared with RiDeclare before RiDisplay can accept them and pass them through to the custom driver.
Special formatting can be done on the filename parameter to RiDisplay. The "#" character is recognized as a special lead-in character in file names. The action taken depends on the character after the "#".
Example:
RiFrameBegin(15);
RiDisplay("test#f.#d", "tiff", ...);
Produces the file name: "test015.tiff".
PRMan supports the use of multiple simultaneous output displays for a single render. As described in the RenderMan Interface Specification, this allows rendering of a display mode which can be the name of a known geometric quantity, a comma separated list of channels all of which were specified with RiDisplayChannel, or the name of a shader output variable. Multiple display specifications may be specified by prepending the + character to the display name.
When using multiple output displays, PRMan will recognize the following special parameters when they occur in the RiDisplay parameter list:
As of PRMan 11, the special variable __CPUtime may also be used as a mode for an arbitrary display:
Display "+costfilename.tif" "tiff" "__CPUtime"
This mode will result in an image that profiles how long it
takes to shade each micropolygon as it renders. The data stored
will be the amount of time it took to shade each micropolygon in
seconds.
PhotoRealistic RenderMan as of version 13.5 allows the user to specify that the
image be rendered in other orders than the default left to right, top to bottom order. This
option can be used to decrease memory footprint for scenes that have a wide aspect ratio
by choosing the
Option "bucket" "string order" [ "horizontal" ]
The bucket orders that are currently supported are:
PhotoRealistic RenderMan searches specific paths for shader definitions, texture map files and Pixar Looks® masters and instances. The search path is a colon-separated list of directories that are used in searching for files that have names which do not begin with . or /. When a search path is set, the character “@” will be replaced by the standard shader or texture location and the character “&” will be replaced by the previous path description.
RtString tpath[] = { ".:/usr/me/ri/images" },
spath[] = { ".::/usr/me/ri" },
dpath[] = { ".::/usr/me/ri/dspy" };
RiOption("searchpath", "shader", (RtPointer)spath,
"texture", (RtPointer)tpath,
"vfxmaster", (RtPointer)spath,
"vfxinstance", (RtPointer)spath,
"archive", (RtPointer)spath,
"display", (RtPointer)dpath,
"procedural", (RtPointer)spath,
RI_NULL);
The valid search paths are:
Note that the server versions of the paths are processed only when using netrender -f, and only by the server. They are searched first, independently of the local equivalents; the local searchpaths will be searched afterwards.
PhotoRealistic RenderMan supports the standard hiders required by RiHider as defined in the RenderMan specification: the null, paint, and hidden hiders, with the hidden hider actually being an alias for the stochastic hider. PRMan also supplies four extra hiders: the zbuffer, opengl, photon, and depthmask hiders. The default hider if none is specified is the hidden (stochastic) hider.
Currently, there are three options that are supported by all PRMan hiders.
This option forces the hider to emit every subpixel into the final image, generating an image which is PixelSamples-times larger, but has every unfiltered color and depth available for perusal. For example, asking for a 640x480 image with PixelSamples 4x4, but with subpixel output, would generate a 2560x1920 unfiltered image.
Hider "stochastic" "int subpixel" [1]
Several hider options control micropolygon caching. Version 11.0 of PRMan now provides a new strategy for dealing with large amounts of in-memory transient micropolygons: it will cache these transient micropolygons to disk when it is detected that there are a relatively large number of them. First, the "mpcache" option, when set to 1, enables the micropolygon caching strategy.
Hider "stochastic" "int mpcache" [1]When the strategy is enabled, caching is activated once more than 6MB of transient micropolygons have been created. This can be controlled by the "mpmemory" option. Changing this number controls the number of KB of micropolygons which can be created before micropolygons begin to be cached to disk.
Cache files are written in the "mpcachedir" location under a directory named "mpc.hostname.n", where 'hostname' is the the name of the host, and 'n' is the process id of the prman process controlling the cache. The renderer will attempt to remove any 'orphaned' cache directories left behind by other invocations of prman. If "mpcachedir" is not specified then the default directory will be the current one; this may be overriden by altering the /prman/hider/mpcachedir directive specified in rendermn.ini.
The maxvpdepth option controls the maximum number of visible points considered for compositing or deep shadow map creation in the hider. By default, this hider option is disabled (set to -1), meaning that there is no limit on the number of visible points considered by the hider. Setting it to a number n forces the hider to trim visible point lists whenever they grow greater than n. This is useful for optimizing deep shadow maps in order to ensure that they have an upper bound on the length of the depth functions per pixel, and for keeping an upper bound on the memory consumed by visible point lists. Note that this option may have limited or no effect on any hider which does not output more than one visible point per subpixel (i.e. any hider which does not support transparency).
The null hider performs no visibility computations whatsoever. Any images produced by the renderer using this hider will be empty. (Image outputs can themselves be disabled by using the null display driver.)
The paint hider renders objects directly into a frame buffer in back to front order without using a z-buffer. (Note that this is counter to the specification; objects are not rendered in the order specified, but are sorted by depth first.) Motion blur, transparency, depth of field, arbitrary output variables, arbitrary clipping planes, level of detail, CSG, matte objects, deep shadow output, and visible point shading are not supported by this hider. This hider does not have any specific options other than those supported by all other hiders.
The z-buffer hider renders objects directly into a frame buffer in back to front order, using a pixel sample sized z-buffer to resolve hidden surface elimination. Motion blur, transparency, depth of field, arbitrary output variables, arbitrary clipping planes, level of detail, CSG, matte objects, deep shadow output, and visible point shading are not supported by this hider. This hider does not have any specific options other than those supported by all other hiders.
The opengl hider renders objects into an off-screen OpenGL buffer to resolve hidden surface elimination. It has limited (inaccurate) support for transparency, trim curves, and deep shadow output. Arbitrary output variable support may be limited by the operating system or graphics hardware. It currently does not support motion blur, jitter, depth of field, arbitrary clipping planes, CSG, matte objects, and visible point shading. This hider does not have any specific options other than those supported by all other hiders.
The PhotoRealistic RenderMan default hider, stochastic, supports all major features of the renderer. Note that the hidden hider is actually an alias for the stochastic hider. It has several parameter-list options described below.
The jitter option enables/disables stochastic sampling. Stochastic sampling should be enabled whenever motion blur or depth-of-field is being used, and in general improves the quality of antialiasing at a small cost in speed. For best results, the jitter option should be disabled when rendering shadow map values. This option is enabled by default, but can be disabled by:
RtInt flag = 0;
RiHider("stochastic", "jitter", (RtPointer)&flag, RI_NULL);
controls the shape of the lens aperture for special depth-of-field effects.
Hider "stochastic" "aperture" [nsides angle roundness density]
| Parameter Name | Meaning |
|---|---|
| nsides | The number of sides of the aperture. For backward compatibility, if this value is less than 3, prman reverts to its previous behavior, using a circular aperture with exactly the legacy stochastic sampling pattern. |
| angle | The polygon's orientation, in degrees from some arbitrary reference direction. (0 degrees puts a vertex on the X axis.) |
| roundness | A shape parameter. When 0, the aperture is a regular polygon with straight sides. When 1, it's a perfect circle. Intermediate values give polygons with curved edges bowed out. It can be negative, in which case the edges bow in. Legal values are from -1 to 1. |
| density | The density (brightness) of the aperture need not be constant. This parameter sets the slope of the (linearly varying) density. If it's zero, the density is constant. If it's negative (resp. positive), the aperture is brighter near the center (resp. near the rim.) Again, the range of legal values is from -1 to 1. |
specifies timing of opening and closing of the of the camera shutter. The two numbers a and b are fractions of the shutter interval specified in the RiShutter RIB call. Over the first part of the shutter interval (from 0 to a), the shutter gradually admits more light. From a to b it is fully open, and from b to 1 it gradually closes. If the "shutteropening" option is not specified, the default "shutteropening" [0 1] is used, resulting in instantaneous open/close timing.
The samplemotion option toggles the sampling of motion blurred micropolygon in the hider, and is thus only meaningful if motion blur is being used in your scene. By default, this hider option is enabled (set to 1), meaning that micropolygons will be blurred and sampled in the hider. When disabled (set to 0), micropolygons will no longer be blurred before sampling; however, the dPdtime variable will still be computed for all objects. This variable can be output into a separate image using an arbitrary output variable and used to perform motion blur as a postprocess.
In some cases where a large amount of motion blur is used with depth of field, sampling artifacts could cause an undesirable result. A new flag, "extrememotiondof," has been added to the hider to improve sampling accuracy in these cases. Usage of this parameter is as follows:
Hider "stochastic" "extrememotiondof" [1]
This flag causes a slower but more accurate sampling method to be used to alleviate the artifacts. Due to the performance degradations of this sampling method, this flag should only be used when necessary.
The sigma option, when used with geometry with the "stochastic" "sigma" attribute enabled, enables alternate hiding algorithms designed especially for use with very small, thin, or transparent geometry. When dealing with such geometry, the usage of sigma hiding generally has a better balance of antialiasing, speed, and memory properties than that achieved by simply raising the PixelSamples setting globally.
By default, sigma hiding is disabled globally. It can be enabled by passing "int sigma" [1] as an option to the stochastic hider:
Hider "stochastic" "int sigma" [1] "float sigmablur" [1.0]
Currently, only RiPoints with Attribute "stochastic" "int sigma" [1], or RiCurves with both Attribute "dice" "hair" [1] and Attribute "stochastic" "int sigma" [1], will undergo sigma hiding.
The quality of antialiasing can be controlled by changing the "float sigmablur" stochastic hider option. By default, this option has a value of 1.0, and has a useful range between 0 and 1. Setting it to lower values will create a sharper look that may alias more readily; higher values closer to 1.0 result in a softer, more filtered look.
The falloff of RiPoints with the "stochastic" "pointfalloff" attribute enabled can be shaped with a new option to the stochastic hider: Hider "stochastic" "float pointfalloffpower" [falloff] (falloff defaults to 1). This option controls the rate at which a RiPoint with "pointfalloff" [1] decays to zero. The hider option value falloff is fed into the equation cos(pi/2 * pow(r,falloff)), where r is 0 to 1 from center to edge of the disk. Consequently, to get a very sudden falloff from opaque to transparent, use a very large value of falloff, i.e. falloff approaching infinity is nearly equivalent to the old behaviour (a completely opaque disk). To get a softer fade, use values less than 1 (but note, even in the limit when f approaches zero, the exact center of the point remains opaque). Values equal to or less than zero are invalid.
The "photon" hider controls the generation of photon maps.
Hider
"photon"
"int emit" [100000] Puts the renderer into photon map calculation mode. Photon map generation is a separate rendering pass akin to shadow map generation, so photon map generation begins when RiWorldEnd is encountered and the Hider is set to "photon". Photons are tagged as global and/or caustic. Caustic photons are deposited into an optional caustic photon map and are specially tuned for use in calculating caustic effects. Global photons are deposited into the optional global photon map and are used to calculate soft indirect illumination. You can generate either or both types of photon maps in a single rendering pass, but if you need very high quality caustics, you'll probably want to increase the photon emission and compute them in a separate photon pass. A single photon pass can result in any number of photon map files. When a photon is "deposited" at a surface point, the standard photon map attributes are consulted to determine the name of the photon map file. To prevent the deposition of a photon on a specific object, specify the empty string for the photon map name.
The depthmask hider is identical to the stochastic hider, save that instead of computing visibility at the image plane, the depthmask hider computes visibility at a frontier defined by depths in a shadow map. Hence, the depthmask hider supports the same options as the stochastic hider, along with three new parameters.
Hider "depthmask" "string zfile" ["shadowmap.sm"] "int reversesign" [0] "float depthbias" [0.01]
NOTE: The shadowmap passed to the depthmask hider must be at sample resolution (See subpixel output above). This means the width of the shadow map must be the width of the image being produced by the hider times the x-component of PixelSamples. Similarly, the height of the shadow map must be the height of the image being produced by the hider times the y-component of PixelSamples. If these conditions are not met, the result is undefined.
In some cases shadow maps may exhibit a problem with surface self-shadowing. This manifests itself as small grey spots all over objects in shadow, and is caused by numerical inaccuracy in computing the depth of a particular surface. If a depth computed when generating the depth map is slightly less than that computed when rendering the image, a shadowing light source shader will interpret this as a shadow and produce a grey spot. This can be solved by using the shadow option to add a small bias value to the values in the depth map when rendering the final image. Care must be taken not to add too large a value since that would cause shadows to separate from the objects casting them. The bias parameter is set as follows:
RtFloat bias0 = 0.35;
RiOption("shadow", "bias", (RtPointer)&bias, RI_NULL);
Note that this bias value can be overridden by a parameterlist value supplied
in the shadow call of the shader.
Previously, shadow maps always contained the minimum depth value calculated from all depth values within the current pixel. The user now has control over the function that computes the output depth value for each pixel. This is controlled by a new Hider option called "depthfilter". You can now select between the minimum, maximum, or average of the pixel depth values to output.
Examples using the jitter hider:
Hider "hidden" "jitter" [0] "depthfilter" "min"
Hider "hidden" "jitter" [0] "depthfilter" "max"
Hider "hidden" "jitter" [0] "depthfilter" "average"
In addition, there is one special version of the depth filter that works a bit differently. For each sample position, it calculates the depth as the midpoint between the object that is closest to the viewpoint and the second closest object. This requires a bit more time than the other techniques, but generates z values that may require less tweaking and biasing. This method was proposed by Andrew Woo of Alias Research in Graphics Gems III, page 338.
This method is specified by the Hider statement:
Hider "hidden" "jitter" [0] "depthfilter" "midpoint"
PRMan 3.8 introduced an enhanced shadow shadeop supporting a new (at the time) method of generating soft shadows with true penumbral fadeout, simulating shadows of area light sources. The method uses multiple rendered shadow maps to infer visibility information from a light source whose extended geometry is also specified in the shadeop. For more details, see the Application Note on soft shadows.
Option "statistics" "endofframe" [level]
The value of level should be either 0 (off) or 1 (on). (Values greater than one no longer increase the level of detail. Level-of-detail is controlled by post-processing the statistics XML file.)
Summary statistics are reported in plain text, while detailed statistics are reported as XML. Output filenames are specified by the following options:
Option "statistics" "filename" [ "filename.txt" ]
Option "statistics" "xmlfilename" [ "filename.xml" ]
Either filename may be the empty string, which disables that kind of
output, or "stdout", in which case the output is displayed on
the console. (Note that XML written to stdout might not be well formed
if procedural or shader plugins also write to stdout.) The default
values of "filename" is "stdout", and the default
value of "xmlfilename" is the empty string. These defaults
can be changed by editing the RenderMan configuration file
(etc/rendermn.ini).
The "xmlfilename" can be set to a special value, "usefilename", which indicates that XML statistics should be written to the filename that would normally receive the plain-text statistics. Doing so can facilitate incorporating XML statistics into pipelines without requiring changes to RIB generators.
The XML file is linked to a stylesheet for viewing in a Web browser. Sometimes the Web browser is unable to locate the stylesheet. This commonly occurs if the statistics are generated on a renderfarm but viewed on workstation that does not have the stylesheet in the same location.
The location of the XML stylesheet can be specified by the following option:
Option "statistics" "stylesheet" [ "URL" ]
The URL can be relative (e.g. a filename). The default location of the
stylesheet can also be specified in the etc/rendermn.ini
configuration file. See the XML
Frame Statistics application note for more information.
Shader profiling is enabled with the following option, which specifies the location of the output file. See the Shader Profiling application note for more information.
Option "statistics" "shaderprofile" ["profile.xml"]
The following option suppresses reporting of displacements that, when divided by the max displacement, fall in the specified range (inclusive). The default thresholds are [.1 1] (e.g. don't report displacements between 10% and 100% of max).
Option "statistics" "displace_ratios" [.1 1]
General purpose imager shaders written in the RenderMan Shading Language are not supported by PhotoRealistic RenderMan. However, two built-in imager shaders are available through the RiImager call.
RiImager("clamptoalpha", RI_NULL);
RtColor bg = {0.4, 0.4, 1.0};
RiImager("background", "background", (RtPointer)bg, RI_NULL);
PhotoRealistic RenderMan subdivides the screen into blocks of pixels termed buckets when resolving the visible surface calculations. Large buckets are more efficient and permit larger grids to be used (see below). Large buckets however require more memory. The bucketsize option is used to specify the n-by-m size of a bucket, in pixels; for example:
RtInt bs[2] = {12, 12};
RiOption("limits", "bucketsize", (RtPointer)bs, RI_NULL);
The gridsize option determines the maximum number of micropolygons that can be shaded at one time. This is another option that can be used to control the tradeoff between computational efficiency and memory utilization. The number of active micropolygons directly affects the amount of memory required to render an image since the state of each active micropolygon must be maintained until it is resolved. Large grids in general are more efficient to shade since the shading machinery is invoked once for a large number of micropolygons, rather than many times for a fewer number of micropolygons. However, larger grids require larger temporary variable buffers for shading (particularly when textures are involved in the shading process) and produce large increases in the number of active micropolygons. A minimal value for this parameter can be calculated by dividing the bucket size by the micropolygon size set with the RiShadingRate request; e.g., a shading rate of 4.0 and a bucket size of 12×12 gives a gridsize of 12×12/4=36. This is minimal in the sense that values smaller than this don't save much memory. The following sets the maximum grid size to 36:
RtInt gs = 36;
RiOption("limits", "gridsize", (RtPointer)&gs, RI_NULL);
The texture system caches data that is read from texture files. The user can modify the limits on the total amount of memory devoted to cached texture data. Large caches increase texture mapping efficiency (particularly on a lightly-loaded host), but obviously can bloat the total memory usage. The texture-cache memory size is specified in kilobytes with the following option:
RtInt tm = 8192;
RiOption("limits", "texturememory", (RtPointer)&tm, RI_NULL);
Similarly, the 3D texture system caches bricks that are read from brick map files. The user can modify the limit on the amount of memory used for cached bricks. The brick cache memory size is specified in kilobytes with the following option:
RtInt tm = 8192;
RiOption("limits", "brickmemory", (RtPointer)&tm, RI_NULL);
Deep shadows are cached in a third data structure. Unlike the texture and brickmap caches, the size of this cache is controlled by limiting the number of tiles, not the maximum memory allocated. Since the size of a deep shadow tile varies with the depth complexity of the shadow, the memory used by the cache is not a linear function of the number of tiles. The deep shadow cache memory size is specified in the number of tiles with the following option:
RtInt numtiles = 100;
RiOption("limits", "deepshadowtiles", (RtPointer)&numtiles, RI_NULL);
Only objects with opacities greater than or equal to the opacity threshold will appear in shadow maps and other z files. The threshold is a color value (as is the shader opacity value Oi). Therefore, if any channel of opacity is greater than or equal to the threshold, the object will appear in shadow maps (and other zfiles). The default value for the opacity threshold is {0.996, 0.996, 0.996} (255/256) or almost completely opaque. This means that partially or completely transparent objects are not rendered into shadow maps or zfiles; only objects which are (almost) completely opaque are rendered. If the opacity threshold is set to {0.0, 0.0, 0.0} all objects will be rendered into the shadow map. The opacity threshold can be controlled with the following option:
RtColor thres = {0.30, 0.30, 0.30};
RiOption("limits", "zthreshold", (RtPointer)thres, RI_NULL);
When rendering scenes with a large number of semi-transparent layered objects (e.g. hair), the opacity culling threshold can be set for a significant time and memory savings. Essentially, a stack of visible points whose accumulated opacity is greater (in each channel) than the specified limit will be considered fully opaque by the hider, and objects behind the stack will be culled. This opacity limit is controlled with the following option:
RtColor thres = {0.995, 0.995, 0.995};
RiOption("limits", "othreshold", (RtPointer)thres, RI_NULL);
The opacity threshold is {0.996, 0.996, 0.996} by default.
This threshold also sets the ray termination criteria for automatic continuation rays. Trace/gather rays apply a scheme similar to the one described above camera samples (visible points), they continue through semi-transparent objects accumulating color and opacity, until the opacity threshold is reached. The gather "othreshold" parameter can be used to override the global threshold for special cases such as non-illuminance ray probes.
The default filter used by the texture shadeop can be set using the following RIB texture option:
Option "texture" "texturefilter" ["force:filtername"]
where filtername is one of: box, disk, gaussian,
lagrangian, or radial-bspline.
The keyword force: is optional. If set, the filter parameter of the
texture shadeop is ignored and the filter specified by the option is used.
Without the force:, only texture calls without a specified filter
will get the default. The default filter is box.
Two texture options control the use of high quality texture filtering options. These allow the selection of higher quality filtering in the shading language to be enabled or disabled. When disabled, the "filter" and "lerp" optional parameters to texture() and environment() have no effect.
RtFloat off = 0.0;
RiOption("texture", "enable gaussian", (RtPointer)&off,
"enable lerp", (RtPointer)&off,
RI_NULL);
The RIB output from a C program using the PhotoRealistic RenderMan client library librib.a can be controlled with the rib option. The format parameter specifies either ASCII output by:
RtString format[1] = {"ascii"};
RiOption("rib", "format", (RtPointer)format, RI_NULL);
or binary output by:
RtString format[1] = {"binary"};
RiOption("rib", "format", (RtPointer)format, RI_NULL);
There are additional simple controls over the style of the ASCII representation, using either a "C" function call:
RiOption("rib", "string asciistyle", &style, RI_NULL)
or an environment variable:
RIASCIISTYLE stylewhere style is a comma-separated list of flags controlling the style.
Currently two flags are supported:
"indented,wide" enables both features. (The default ASCII RIB representation is left-margin aligned, with approximate line-length enforced.)
The RiBegin call can be used to specify a specific RIB output file, as in:
RiBegin("foo.rib");
If RiBegin is not used to specify a file name, and RISERVER
is not defined (see Section 2.8), the standard
output will be used.
The compression format is derived from the freely available libzip.a library and is compatible with the GNU compression program gzip. You can tell the RIB client library to output compressed RIB by calling RiOption before the call to RiBegin:
RtString str = "gzip";
RiOption("rib", "compression", &str, RI_NULL);
or by setting the environment variable RICOMPRESSION to gzip:
setenv RICOMPRESSION gzip
Strings in RIB files may now contain “variables” that are expanded when the RIB is parsed by the renderer. These are references to Attributes and Options that are in scope at the time that the string is parsed. For example:
Attribute "user" "string mytexsuffix" ["daytime"]
...
Surface "mood_wall" "string texname" ["mood${user:mytexsuffix}.tex"]
The dollar-sign ($) in this example is the indication to the RIB parser that it should
look for an expandable name. The following variable styles are allowed:
| $name ${name} |
all attributes, then options, are searched for "name" ("$Frame" is the current frame) |
| $namespace:name ${namespace:name} |
attributes, then options, of the particular type are searched for "name" (e.g. "user:var") |
| $qualifier:namespace:name ${qualifier:namespace:name} |
the Attribute or Option qualifier specifies exactly which name to query (e.g. "Attribute:user:var") |
NOTE: Any and all attributes and options can be used.
Since the dollar-sign was not previously “reserved”
for this use, it is possible that existing RIB files may have have strings containing
it that should not be subjected to this kind of expansion. Therefore, this is an
optional behavior that must be enabled by specifying the distinguished
“name expansion” character in either rendermn.ini or as an Option at the
top of a particular RIB file:
rendermn.ini: /prman/ribvarsubstchar $
inline in RIB: Option "ribparse" "string varsubst" ["$"]
Note that the functionality of the varsubst option is similar to that of ifbegin.
Below is a simple example RIB file.
##RenderMan RIB
Option "user" "string film" ["toystory"]
Option "rib" "varsubst" ["$"]
FrameBegin 1
Format 128 128 1
Display "/tmp/t.tif" "tiff" "rgba"
Projection "perspective" "fov" [45]
WorldBegin
LightSource "ambientlight" 1 "intensity" .4
LightSource "distantlight" 2 "from" [1 1 -1]
AttributeBegin
Attribute "identifier" "name" ["sphere1"]
Translate 0 0 2.75
Surface "/production/${user:film}/plastic"
Sphere 1.0 -1.0 1.0 360.0
AttributeEnd
WorldEnd
FrameEnd
In version 3.9.2, a new Option was added which allows the renderer to apply a directory mapping to the absolute paths used to look up resources such as shaders and texture maps. It is specified as follows:
Option "searchpath" "dirmap" [ "[\"zone\" \"directory to map from\" \"directory to map to\"] [\"zone2\" \"from\" \"to\"]" (more mappings)]
Note in particular that the value of this option is a single RtString. Inside this string, multiple mappings can be defined, each delimited with a matched pair of square braces. Each mapping consists of three tokens, each themselves delimited with double quotes, which are the "zone", the "from" directory, and the "to" directory.
Directory mappings are defined for a "zone", which controls when the mapping should be used or ignored. The renderer determines the directory mapping zone that it is in via the /dirmap/zone directive specified in rendermn.ini. The renderer will use the value set for /dirmap/zone; if this does not exist, it will fall back to using /dirmap/zone/$ARCH, and if this does not exist it will default to the value "UNC" on the Windows platform, and "NFS" on Unix platforms.
Directory mappings are applied when the renderer encounters an absolute path, directly in the RIB stream (i.e. when /home/user/texture.tx is specified in the RIB), or when an absolute path is constructed from a relative filename combined with a searchpath entry. The first part of the absolute path is checked (via a case sensitive string compare) against the "from" part of the directory mapping; if it matches, that part of the path is replaced with the "to" part of the mapping.
As an example, suppose the following RIB statements are encountered:
Option "searchpath" "texture" "//smbhost/luxo://smbhost/tinny:@" Option "searchpath" "dirmap" [ "[\"NFS\" \"//smbhost/tinny\" \"/home/tintoy\"]" "[\"UNC\" \"/home/tintoy\" \"//smbhost/tinny\"]" ] Surface "//smbhost/tinny/myshader" "txname" ["images/mytexture.tx"]
Suppose that the renderer is in the "NFS" zone, i.e it has the /dirmap/zone set to NFS in rendermn.ini. This means that it will use the first mapping specified (from //smbhost/tinny to /home/tintoy), but will ignore the second mapping for "UNC" hosts (from /home/tintoy to //smbhost/tinny). When the renderer goes to look for the shader "myshader", it will note that the absolute path to the shader specified matches the directory map, and so it will apply the directory map:
//smbhost/tinny/myshader -> /home/tintoy/myshader
Now let's assume that the shader "myshader" also looks for the
texture "images/mytexture.tx". Note that this texture is
specified in a relative form, which means that it will look
through the searchpaths as defined in the "searchpath" "texture"
statement. The renderer will first construct the absolute path
"//smbhost/luxo/images/mytexture.tx" and check directly for this
file, since this doesn't match any mappings. If it fails to find
it there, it will next construt the path
"//smbhost/tinny/images/mytexture.tx" — but since this path
matches the directory mapping, the path will be changed:
//smbhost/tinny/images/mytexture.tx -> /home/tintoy/images/mytexture.tx
As of version 10, PRMan supports an option which allows an offset to be added to motion blur times:
Option "shutter" "offset" [float frameoffset]
The specified offset is added to all time values specified in subsequent RiShutter and RiMotionBegin calls. This is a useful Option to use when using a sequence of RIB files which change the shutter times, while repeatedly referring to the same RIB archive containing motion blurred geometry. Without the new Option this would be difficult because the MotionBegin times in the archive would need to match the Shutter times: either the archive would have to be regenerated with each frame, or the Shutter and MotionBegin would always need to be locked at the same range for all frames (which would mean that the time shading variable is identical for each frame as well).
With the new Option, you may now keep a single RIB archive with the MotionBegin times starting at zero, and then from each referring RIB define an offset, prior to ReadArchive:
Shutter 0 0.5
Option "shutter" "offset" [0]
FrameBegin 0
ReadArchive "geometry.rib"
FrameEnd
Shutter 1 1.5
Option "shutter" "offset" [1]
FrameBegin 2
ReadArchive "geometry.rib"
FrameEnd
PRMan 10.0 and higher support the use of arbitrarily defined token/value pairs for the user option. These token/value pairs may be arbitrarily defined and set, and then queried with the option shadeop or via the RxOption mechanism.
RtString myoption = "foo";
RiOption("user", "uniform string myoption", (RtPointer)&myoption, RI_NULL);
In RIB form:
Option "user" "uniform string myoption" [ "foo" ]
In addition to the standard pixel filter functions in the Specification, PRMan supports these additional pixel filters:
The recommended filter from Don Mitchell and Arun Netravali's 1988 Siggraph paper on reconstruction filters - the separable version of the (1/3, 1/3) filter.
A separable version of the catmull-rom filter.
A separable 4 term (-92 dB) Blackman-Harris filter.
Option
"trace" "int maxdepth" [10]
Option "trace" "float specularthreshold"
[10]
Option
"trace" "int continuationbydefault" [1 | 0]
Option
"limits" "int geocachememory" [30720]
As of version 12.5.1, PRMan supports an option that modifies the way motion blur is applied relative to shutter times.
Option "shutter" "clampmotion" [int clamp]
In previous releases, if a motion block specified times that did not match the shutter, for example, as shown here:
Shutter 0 0.5 MotionBegin [0 1] Translate 0 0 1 Translate 0 0 2 MotionEnd MotionBegin [0 1] Rotate 0 1 0 0 Rotate 90 1 0 0 MotionEnd
PRMan performed interpolations to clamp all motion data to the shutter time as soon as possible. In situations with nested transformations or deformations, some or all of which were within motion blocks, this could lead to inaccurate transformations and undesired motion blur. In the example shown, at time 0.5 PRMan would concatenate the interpolation of the two Translates (Translate 0 0 1.5) with the interpolation of the two Rotates (Rotate 45 1 0 0).
PRMan now supports a new way of performing motion interpolation that defers the motion interpolation to shutter boundaries as late as possible, improving motion blur accuracy. There is no performance penalty (in speed or memory) for this improved interpolation. In the example shown above, using the new method, at time 0.0 PRMan would concatenate Translate 0 0 1 with Rotate 0 1 0 0, at time 1.0 it would concatenate Translate 0 0 2 with Rotate 90 1 0 0, and at time 0.5 it would interpolate those two new computed concatenations.
For backwards compatibility, the old behavior is the default, and is enabled by setting Option "shutter" "int clampmotion" [1]. To enable the new behavior, the clampmotion flag should be set to 0.
Option "shading" "int debug" [1]Option "shading" "int checknans" [0]Option "shading" "float objectcache" [1.5]|
Pixar Animation Studios
|