OptionsOptionsControl Over Printed Statistics
Every 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 Version 3.2, 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 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 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.
The PhotoRealistic RenderMan default hider, hidden, has several parameter-list options.
The first, jitter, 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("hidden", "jitter", (RtPointer)&flag, RI_NULL);
Starting with version 11, PRMan attempts to resolve visibility in its entirety before shading. In nearly all cases this causes a frame to render faster. Only in the case of displaced geometry will PRMan maintain the old behaviour. In order to turn on more aggressive hiding in this case, a new parameter "occlusionbound" passed to the hider allows one to specify how far a point in screen space can be displaced in screen space before it must be shaded prior to hiding. By default, it is set to zero, which causes all displaced objects to be shaded first before hiding. Setting it higher will lead to faster renders at the risk of possible errors on displaced objects.
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.
RtInt flag = 0;
RiHider("hidden", "mpcache", (RtPointer)&flag, RI_NULL);
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 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.
An option to force 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 "hidden" "subpixel" [1]
Note that this option does not work with arbitrary output variables.
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 "hidden" "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.
A hider, "photon" controls the generation of photon maps:
Hider
"photon"
"int emit" [100000] PRMan's normal hiders compute visibility at the image plane; the Depthmask hider computes visibility at a frontier defined by depths in a shadow map. The RIB syntax for using this new z-stencil hider is as follows:
Hider "depthmask" "zfile" ["shadowmap.sm"] "reversesign" [0] "depthbias" [0.01]
The "zfile" option, takes a shadow map file (created with txmake -shadow or RiMakeShadow ). This new hider will then cull surfaces which are nearer (or farther) than the frontier defined by the depth values in the shadowmap.
The parameter "reversesign" controls whether z-depths greater than or less than the depth mask are culled. The default value of 0 culls all geometry in front of the depth mask. Setting this parameter to 1 allows the depth mask to be used to cull geometry behind the mask.
The parameter "depthbias" controls the amount of bias applied to the mask. The default for this parameter is 0.01. Raising this value will prevent self-intersection problems in cases where two surfaces are extremely close.
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.
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.
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.
General end of frame statistics are controlled by the RIB statement:
Option "statistics" "endofframe" [level]
The value of level determines how much detail is printed:
Level 1 is probably the most useful. The information printed at higher levels, particularly level 3, are for debugging errant renders and can be hard to interpret.
A file logging statistic can be output when the RIB statement:
Option "statistics" "filelog" ["filename"]
is specified. When the render completes, filename will
contain a list of all files accessed by the renderer over the
course of image generation.
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.
When the displacement of an object on the screen is very large, that is, the displaced point is far from the original point, PhotoRealistic RenderMan invokes a special displacement procedure in order to save large amounts of memory at some additional computational cost. When this occurs, the error message:
Extreme displacement encountered (WARNING)is generated. The maximum permissible displacement before the special procedure is invoked is measured in vertical scanlines. If this value is increased, larger displacements are permitted to use memory rather than incur the additional computation. If this value is decreased, memory usage is minimized even for less severe displacements. The default for this value is 32 scanlines, and can be changed with the following option:
RtInt ed = 24;
RiOption("limits", "extremedisplacement", (RtPointer)&ed, RI_NULL);
Two texture options have been added for use with RiOption to 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);
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
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.
|
Pixar Animation Studios
|