RManNotes: PRMan Configuration

Introduction

PhotoRealistic RenderMan is highly configurable. Everything from where it looks for shaders to details about how surfaces are renderered is controllable using PhotoRealistic RenderMan's configuration files. The document describes the syntax of PRMans's configuration files and how to change some of the more commonly modified options.

Many other options, including those for tweaking rendering performance, are described in the PhotoRealistic RenderMan User's Manual in Section 3.9.

Understanding Configuration Files

RenderMan is a sophisticated rendering package and has many internal defaults which can be modified through configuration files. All configuration files are named "rendermn.ini." Users can specify their own option settings by having a file called "rendermn.ini" in their home directory and/or the current working directory. Options specified in configuration files will override the values specified in previously processed configuration files. Configuration files are processed in the following order from the following directories:

$RMANTREE/etc
home area (specified by the HOME environment variable)
current working directory

A configuration file is simply a list of default option settings. Each line in the configuration file changes the value of one option specified by name. The name of the option appears first followed by the new default value. For example, the option "/displaytype/file" specifies the default output image file format; therefore, the following line in a configuration file

/displaytype/file	tiff

sets the default file format to TIFF. To change the default file format to SGI's RGB format (generally not available on non-SGI platforms), you would have the following entry in a configuration file

/displaytype/file	sgif

In a configuration file, lines beginning with "#" are comments and are ignored, as are blank lines.

Sometimes it may be convenient to specify option default values using the value of environment variables. The following syntax can be used in configuration files to indicate that a specific environment variable value should be used:

${environment-variable-name} This syntax is commonly used in setting search paths.

ACCAD users can view ACCAD's configuration file.

Search Paths

Search paths are lists of directories which are searched in sequence whenever the renderer encounters a shader or texture name that does not begin with a slash ("/"). Syntactically, a search path is a colon-separated list of directory path names. When a search path is set, the character "@" is replaced by the standard search path and the character "&" is replaced by the previously set search path value. Separate search paths are used for shaders and texture files.

For example, the shader path specified in ACCAD's configuration (rendermn.ini) file

/shaderpath		.:/usr/local/accad/shaders:@

tells the renderer to look sequentially in the current working directory (signified by the period), the directory /usr/local/accad/shaders, and the directories specified by the option /standardshaderpath (signified by '@') for shader object files.

Telling PRMan Where To Look For Shaders

There are two defaults related to where the RenderMan renderer looks for shaders when generating an image:

/shaderpath
/standardshaderpath

Users should modify /shaderpath, a search path, to specify additional directories where user shaders can be found. /standardshaderpath is the location of "standard" RenderMan shaders and should not, in general, be changed.

As an example, if you want to append a shader directory in your home area called "RenderMan/shaders" to the list of already defined directories, you could specify the following in your own "rendermn.ini" file:

/shaderpath	&:/u0/smay/RenderMan/shaders

/u0/smay will be expanded to value of the environment variable HOME which specifies the full path name of your home area. The ampersand will be expanded to the previous value of /shaderpath.

Telling PRMan Where To Look For Textures

Like shaders, the directories searched by the RenderMan renderer for texture files is specified by two options:

/texturepath
/standardtexturepath

The /texturepath option should be modified to specify additional directories containing texture files. For example:

/texturepath	.:${HOME]/RenderMan/textures:@

specifies a search path that the RenderMan renderer should search for texture files. It includes the current working directory (signified by the period), a directory in the user's home area called "RenderMan/textures," and the directories specified by /standardtexturepath (signified by the '@') which contains distributed texture files.

Changing the Default Output File Format

The default output image file format can be changed by setting the option /displaytype/file. The table below summarizes some of the more frequently used file types.

*Available PRMan Output File Formats*
Value	Description
`tiff`	TIFF
`sgif`	Silicon Graphics RGB
`cpostscript`	color PostScript (EPS)
`postscript`	PostScript (EPS)
`tga`	Truevision targa (types 2 & 3)
`alias`	Alias
`cineon`	Kodak Cineon

Any comments or suggestions appreciated.

Steve May (smay@pixar.com)