Imager Shaders

As of PRMan 15, arbitrary imager shaders are supported, in addition to the two built-in imager shaders that have been available through the RiImager call. For more on arbitrary imager shaders, please consult the Imager Shaders application note; the built-in imager shaders are described below.

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

RiImager ( RtToken name, parameterlist )

Imager name ...parameterlist...

RiImager ("cmyk," RI_NULL);

RiPixelSampleImager ( RtToken name, parameterlist )

PixelSampleImager name ...parameterlist...

RiPixelSampleImager ("combineAovs," RI_NULL);

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.

Display Origin

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

Display Merge

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.

Device Resolution

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

Output Compression

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 Driver Options

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.

Filename Formatting

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 "#".

Optional Formatting Prefixes

Prefix	Description
#f	Is replaced with the frame number as specified to RiFrameBegin. By default it is inserted into the filename as three digits with leading zeroes. The number of digits can be controlled using #*width*f, where *width* is a string of decimal digits.
#s	Replaced with the frame sequence number. This number is incremented for every frame block regardless of the frame number. Takes an optional width as with #f.
#n	Replaced with a running sequence number. This number is incremented every time the renderer outputs an image file, regardless of the frame number. Takes an optional width as with #f.
#d	Replaced with the requested display type.
#p	Is replaced with the processor number in a multiprocessor rendering. This should never be used in a file name during automatic multiprocessor rendering such as through netrender.
#P	Is replaced with the total processor count in a multiprocessor rendering. This should never be used in a file name during automatic multiprocessor rendering such as through netrender.
##	Is replaced with a single #. Example: RiFrameBegin(15); RiDisplay("test#f.#d", "tiff", ...); Produces the file name: ``"test015.tiff"``.

Arbitrary Output Variables

PRMan supports the use of multiple simultaneous output displays for a single render. As described in the RiDisplay section, this allows rendering of a display mode that 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 RiDisplay options enumerated above, as well as the following special parameters when they occur in the RiDisplay parameter list:

Option	Description
int[4] quantize	These four values (zeroval, oneval, minval, and maxval) control how the output display is quantized.
float dither	This single value controls the amplitude of the dither added to the values of the output display.
float[2] exposure	The two values required are gain and gamma. These control the exposure function applied to the pixel values of the output display in the same manner as RiExposure.
string filter	The name of the pixel filter to be used for the output display. The names of the standard pixel filters that may be passed to RiPixelFilter may be used here (see the Pixel Filters section below for PRMan extensions). In addition, five special filters may be used: min, max, average, zmin, and zmax. The first three filters mean instead of running a convolution filter across all samples, only a single value (the minimum, maximum, or average of all pixel samples) is returned and written into the final pixel value. The zmin and zmax filters operate like the min and max filters, except that the depth value of the pixel sample is used for comparison, and not the value implied by the mode itself. These filters are useful for arbitrary output variables where standard alpha compositing does not make sense, or where linear interpolation of values between disjoint pieces of geometry is nonsensical. Note that when these filters are used, opacity thresholding is also used on that output to determine which closest surface to sample.
float[2] filterwidth	The size in X and Y of the pixel filter to be used. Set to [0 0] to automatically use the standard size for the chosen pixel filter.

PRMan 11 introduced the special variable __CPUtime, which 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.

Pixel Filters

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

RiMitchellFilter

RiSeparableCatmullRomFilter

RiBlackmanHarrisFilter

RiLanczosFilter

RiBesselFilter

RiDiskFilter

Checkpointing

New in RPS 19 - PRMan 19 introduces new options for periodically writing checkpoints when the incremental path tracing mode is enabled.

Option "checkpoint" "uniform int interval" [i]
                    "uniform int exitat" [i]
                    "uniform int keepfiles" [b]

For the interval and exitat values, positive values will specify seconds, negative values will specify increments, and zero - [0] - will disable it. For convenience, strings will also be accepted, e.g.: "string exitat" "8.0h" where the suffix may be (i)ncrements, (s)econds, (m)inutes, (h)ours, or (d)ays. They are "off" by default. Users should also consult the prman manual for more information about the -checkpoint and -recover arguments.

Note: checkpointing requires a display driver that supports multi-channel images and floating point output. Of the built-in drivers, only the standard TIFF and OpenEXR driver are capable of this, and only OpenEXR can resume a checkpointed render. Note that the checkpoint option can generate significant amounts of I/O, especially if the interval is small.

For more information, see the Checkpointing & Recovery page of the RIS Users' Guide.

Bucket Size

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

Hair Length

Option "dice" "maxhairlength" [-1]

Hair Width

Option "hair" "float minwidth" [0]

Curve Orientation

Option "curve" "int orienttotransform" [-1]

Curve Cacheing

Option "curve" "int usegutcache" [0|1]

Stochastic Transparency

Option "curve" "int stochasticshadows" [0|1]

Arbitrary Bucket Order

PRMan, 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:

• horizontal: left to right, rendering scanlines from top to bottom(default)

• vertical: top to bottom, rendering vertical scanlines from left to right

• zigzag-x: the same as horizontal, except direction reverses at end of scanlines

• zigzag-y: the same as vertical, except direction reverses at end of scanlines

• spacefill: renders the buckets along a hilbert spacefilling curve

• spiral: renders in a spiral from the center of the image; "spiral" can take the optional parameter "orderorigin" to indicate where the spiral should begin, e.g.

  Option "bucket" "string order" [ "spiral" ] "orderorigin" [256 256]
  

  The default remains the center of the image (xRes/2, yRes/2).

• random: renders buckets in a random order (inefficient memory footprint)

If any of the display drivers in use require scanline order, then all display drivers will buffer all of the image data in memory if an order other than horizontal or zigzag-x is used.

Threads

There is an advanced Ri option that can be used to explicitly set the exact number of threads that the renderer uses for a RIB file.

Option "limits" "int threads" [0]

You can override the rib option with the following command line flag:

prman -t:N render.rib

where N is one of the supported settings below. The default setting is 0.

Supported settings:

• 1: just use 1 thread for computation. The renderer will not check to see how many cores/hyper-threads your machine has, it will just use 1.
• 2 - 128: use the specified number of threads for computation. The renderer will over-schedule if you specify a number higher than the number of threads on your machine.
• 0: query your machine to determine how many threads are on the machine and only use that many to avoid over-scheduling your machine.
• -1: query your machine and use all the threads on the machine except for one. This parameter is useful for interactive renders to leave a thread for the bridge product to use.
• -N: use all the threads on the machine minus N (where n is an integer)

Ray Tracing

Option "trace" "int maxraydepth" [25]

Pretessellation

Option "dice" "int pretessellate" [1]

Shade

Option "shade" "int debug" [1]

Option "shade" "int checknans" [0]

Option "shade" "float defcache" [0]

Option "shade" "float objectcache" [1.5]

Option "shade" "int directlightinglocalizedsampling" [-1]

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.

Shadow Maps

In some cases shadow maps may exhibit a problem with surface self-shadowing. This manifests itself as small gray 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 gray 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 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.

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

Deep Texture Compression

PRMan supports three optional methods of error tolerance for lossy compression of deep texture files (including traditional deep shadow maps, area shadow maps, and deep compositing outputs).

Option "limits" "float deepshadowerror" [0.01]

Option "limits" "float deepshadowsimplifyerror" [-1]

and

Option "limits" "float deepshadowdeptherror" [1.0]

deepshadowerror is essentially as described in Lokovic and Veach's "Deep Shadow Maps". Setting it to a high value will result in lower numbers of samples stored in each pixel function; this can be verified by using the dsview or txinfo utilities.

PRMan 16 added a secondary lossy compression method, based on the Ramer-Douglas-Peucker line simplification algorithm. Error tolerance for this secondary method is controlled by the deepshadowsimplifyerror option. The -1 default for tells the renderer to use the deepshadowerror value for both compression methods (i.e. both are run with the same value) and 0 disables the option. As with deepshadowerror, higher values will result in lower numbers of samples stored. Note that this compression method is applied in addition to the original algorithm (unless set to 0).

PRMan 16.5 introduced scale-adaptive deep file compression, enabled via deepshadowdeptherror. This is a multiplier on the diagonal length of a projected texel facing the map camera. Setting it to zero (the default) disables the new filtering, and adjusting it up or down makes it more or less agressive, respectively.

For more information about compressing deep texture files, please consult the Deep Compositing application note.

User LPE Output

RenderMan allows the user to create and output user lobes for AOVs. An example would be the user lobes used to generate the Denoise LPE data.

This can be enabled using an option.

Option "lpe" "int enableuserlobes" [0|1]

The default is 0 or Off. This option is experimental.

Memory

Option "limits" "int geocachememory" [204800]

Option "limits" "int opacitycachememory" [1024000]

Option "polygon" "int reducedmemory" [0]

/prman/polygon/reducedmemory 0

Option "polygon" "int nonplanar" [1]

/prman/polygon/nonplanar 1

Option "limits" "float rendermemory" [1.0]

RtInt tm = 8192;
RiOption("limits", "texturememory", (RtPointer)&tm, RI_NULL);

Option "limits" "int texturememory" [2048]

Option "limits" "int ptexturememory" [2048]

/prman/ptexturememory         2048

Option "limits" "int ptexturemaxfiles" [128]

/prman/ptexturemaxfiles         256

Option "limits" "int deepshadowmemory" [102400]

Option "limits" "int deepshadowtiles" [1000]

Option "limits" "int pointmemory" [51200]
Option "limits" "int octreememory" [51200]

/prman/pointmemory          51200
/prman/octreememory         51200

Option "limits" "int brickmemory" [10240]

Statistics

Statistics output is controlled by the following RIB option:

Option "statistics" "int 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" "string filename" [ "filename.txt" ]
Option "statistics" "string 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" "string 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" "string 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" "float[2] displace_ratios" [.1 1]

When reporting displacement issues, by default only 100 are reported. The following option modifies the maximum reported. If the value is set to 0, then all displacements issues are reported.

Option "statistics" "int maxdispwarnings" [100]

RIB Output

The RIB output from a C program using the PRMan 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": introduces a number of tab characters prior to Ri requests indicating the depth of block nesting.
• "wide": prevents introduction of intra-request newline characters. This results in a single ascii line per Ri request.

"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 an RISERVER variable is not defined, 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

The precision of floating point number representations can also be specified via the rib option:

RtInt prec = 6
RiOption("rib", "int precision", (RtPointer)&prec, RI_NULL);

or by setting the environment variable RIPRECISION to n:

setenv RIPRECISION 6

This sets the number of significant digits used in the mantissa of floating point numbers in ASCII-formatted RIB. The default value is 6.

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:

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:

/prman/ribvarsubstchar $

or as an Option at the top of a particular RIB file:

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

Search Paths

PRMan searches specific paths for shader definitions, texture map files, and other resources. The search path is a colon-separated list of directories that are used in searching for files that have names that 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,
                       "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.

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.

rixplugin

Used by the renderer to find Ri Shading (RIS) Pattern, Bxdf, and Integrator plugins.

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.

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.

Directory Mapping

In version 3.9.2, a new Option was added that 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 construct 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