Options

Frame Buffer Control

Search Paths

Hiders

Shadow Maps

Statistics

Imager Shaders

Bucket Size

Grid Size

Texture Memory

Opacity Threshold

Opacity Culling

Texture Filtering

RIB Output

Directory Mapping

Shutter Offset

User Specified Options

Pixel Filters

Ray Tracing

Clamping Shutter Motion

Shading


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.

Frame Buffer Control

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.

Arbitrary Bucket Order

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 vertical order. The option is specified via:

       Option "bucket" "string order" [ "horizontal" ]
       
The bucket orders that are currently supported are:
Display drivers that require scanline order will buffer all of the image data in memory if another order besides horizontal is used.

Search Paths

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:

 

shader
Used by the renderer to find all shader .slo files. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

texture
Used by the renderer to find all texture files. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

vfxmaster
Used by the renderer to find all Pixar Look master files. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

vfxinstance
Used by the renderer to find all Pixar Look instances files. (Usually to read an embedded texture out of the instance.) When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

archive
Used by the renderer to find RIB archives. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

procedural
Used by the renderer to find procedural primitive DSOs. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

display
Used by the renderer to find display drivers. When using netrender the path elements are all in the context of the netrender command and will be ignored by the render server.

 

resource
Used by the renderer as a “catchall” searchpath, incorporating all of the other searchpaths, with the exception of display.

 

servershader
Used by the renderer to find all shader .slo files. Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

servertexture
Used by the renderer to find all texture files. Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

servervfxmaster
Used by the renderer to find all Pixar Look master files. Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

servervfxinstance
Used by the renderer to find all Pixar Look instances files. (Usually to read an embedded texture out of the instance.) Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

serverarchive
Used by the renderer to find all RIB archives. Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

serverdisplay
Used by the renderer to find all display drivers. Only used when using netrender with the -f option; the path elements are interpreted in the context of the render server.

 

serverresource
Used by the renderer as a “catchall” searchpath, incorporating all of the other searchpaths, with the exception of serverdisplay.

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.

Hiders

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.

Null Hider

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.)

Paint Hider

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.

Z-Buffer Hider

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.

OpenGL Hider

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.

Stochastic Hider

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.

Photon Hider

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.

Depthmask Hider

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.

Shadow Maps

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.

Statistics

Statistics output is controlled by the following RIB option:
       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] 

Imager Shaders

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.

 

clamptoalpha
takes no parameters, and merely assures that all color values are less than the value of the alpha channel prior to output. This is true even if the display mode of the image being generated is not an rgba image. Shaders that produce color values greater than one, as well as the pixel dithering process, can occasionally produce color values greater than the alpha value, potentially resulting in errors when the image is later composited over another image by programs that do not anticipate this possibility.
RiImager("clamptoalpha", RI_NULL);

 

background
takes a single parameter, background, of type uniform color. The rendered image is merged over the specified background color and all the alpha values are set to one.
    	RtColor bg = {0.4, 0.4, 1.0};
		RiImager("background", "background", (RtPointer)bg, RI_NULL);

Bucket Size

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

Grid Size

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

Texture Memory

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

Opacity Threshold

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

Opacity Culling

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.

Texture Filtering

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.

 

enable gaussian
Enables the use of a gaussian filter when filtering the texture sample data from a texture or environment map. Takes a floating point value. A value of 0.0 disables the selection of the gaussian filter. A value of 1.0 enables the selection of the gaussian filter.

 

enable lerp
Enables the interpolation of two texture resolution levels to insure smooth transitions between resolution levels. The data will be interpolated between the resolutions above and below the ideal resolution for the shading sample. Takes a floating point value. A value of 0.0 disables the selection of interpolation. A value of 1.0 enables the selection of interpolation.
They are enabled by default. Here is an example of disabling high quality filtering:
		RtFloat off = 0.0;
		RiOption("texture", "enable gaussian", (RtPointer)&off,
        		            "enable lerp", (RtPointer)&off,
        		            RI_NULL);

RIB Output

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 style
where 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

RIB Authoring

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  
	  

Directory Mapping

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
    

Shutter Offset

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

User Specified Options

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

Pixel Filters

In addition to the standard pixel filter functions in the Specification, PRMan supports these additional pixel filters:

Ray Tracing

Option "trace" "int maxdepth" [10]
an absolute limit on the recursion depth of ray probes.
 
Option "trace" "float specularthreshold" [10]
an angular threshold used to distinguish between specular and diffuse ray sampling patterns.  For example, this threshold is used during caustic photon map generation to tag caustic photons.  This value is measured in degrees.
 
Option "trace" "int continuationbydefault" [1 | 0]
controls whether trace/gather rays automatically continue through partially transparent surfaces (1) or stop at the first hit (0). Default value is 1, but can be overridden in rendermn.ini by /prman/tracecontinuationbydefault.
 
Option "limits" "int geocachememory" [30720]
specifies the size of the geometry cache used for ray tracing. The default size is 30MB.

Clamping Shutter Motion

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.

 

Shading

Option "shading" "int debug" [1]
Shader debugging level. Level 1 (the default) enables inclusion of source file and line number information in shading error messages, which slightly increases memory usage. Level 0 disables these features (and in the future might disable certain run-time error checks).
 
Option "shading" "int checknans" [0]
If non-zero, the shading system warns if certain global variables (P, N, Ci, Oi, L, Cl) contain any NaNs (invalid floating point values) after shader execution.
 
Option "shading" "float objectcache" [1.5]
Specifies the size of the shader object cache as a multiple of the maximum "working set" size. A smaller cache might reduce the "shader object memory" reported in the statistics. A larger cache might reduce the "shading setup" time (and might also improve the object cache hit ratio shown in the statistics).
 

 

Pixar Animation Studios
(510) 752-3000 (voice)   (510) 752-3151 (fax)
Copyright © 1996- Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.