Rendering Images



Texture Files

Running PRMan

The prman executable

Renderer Output

Environment Variables

Configuration Files

To render an image, a complete scene description must be supplied. The majority of the information is given in a file that contains RenderMan Interface requests specified with the RenderMan Interface Bytestream protocol, RIB. For shading, however, this description may reference functions written in the RenderMan Shading Language. These functions are maintained separately, in ASCII files that must be compiled by the RenderMan Shading Language compiler shader before they can be used. In addition, if the shading calculations use texture files, these files must be made available to PhotoRealistic RenderMan. Many textures are created from previously rendered images, in which case the rendered images must first be converted to a format optimized for efficient access as a texture.


RenderMan Interface scene descriptions for PhotoRealistic RenderMan are specified with RIB. RIB is basically a language-independent specification mechanism for calls to the RenderMan Interface. This specification can be created in ASCII or, for efficiency, in a compressed binary format. The modeling system used to generate scene descriptions is expected to output RIB, usually by using the RIB client library, librib.a, that is described in The RenderMan Interface Bytestream Protocol Library.

PhotoRealistic RenderMan supports RIB files, in either binary or ascii forms, with or without gzip compression. See PRMan Options: RIB Output for details on controlling the format of RIB files.

One tool that can be useful in dealing with RIB files is the program catrib. Catrib can be used to convert between binary and ASCII formats, and as a means of transmitting RIB data to a rendering server. For example, if the file binary.rib contains binary RIB data, then the following will create an ASCII version of this data in the file ascii.rib:

catrib -ascii binary.rib > ascii.rib

By default the output generated by catrib is sent to the standard output. Thus the following might be used to compare the ASCII output to a previously created file:

catrib -ascii binary.rib | diff - oldascii.rib

The format of the output generated by catrib can be specified as binary or ASCII by using the -binary and -ascii options, respectively. Alternatively the environment variable RIFORMAT can be set to "binary" or "ascii". Beware, however, that this environment variable is also used by the client RIB library that applications use to generate RIB data. Thus setting this environment variable may also affect the operation of your modeling system.


Shaders are routines written in the RenderMan Shading Language. These routines have a number of functions in the rendering process. Shaders can be used to perturb geometry, describe light sources, define surface characteristics, etc.

Each shader must be compiled before it can be used by PhotoRealistic RenderMan in the rendering process. This is done with the shader program. For example, to compile the constant shader into a shading file suitable for use by PhotoRealistic RenderMan the following command would be used:


Each shader must be compiled into a separate file and the file that holds the compiled object must have a name that corresponds to the name of the enclosed shader. For example, the file constant.slo holds the shader named constant. A file named might contain the shader surface marble. Its corresponding output file (created by the compiler) would be marble.slo and not foo.slo. This file naming convention is automatically enforced by the shader compiler; you need only be aware of this if you have source files whose names do not match the name of the enclosed shader.

The standard shaders defined in the RenderMan Interface specification are located in the directory $RMANTREE/lib/shaders. (See Table 1.) PhotoRealistic RenderMan automatically searches this directory to find shaders that are referenced in a scene description. Any user-defined shaders must be referenced either through absolute path names (i.e., path names with a leading slash) or by using the PhotoRealistic RenderMan-specific searchpath option. See Configuration Files and PRMan Options: Search Paths for details about search paths.

Shader     Description
ambientlight ambient light source
constant constant-color surface without light effects
distantlight light source at infinity
defaultsurface the default surface shader
depthcue depth cueing atmosphere shader
fog foggy atmosphere shader
matte purely diffuse color surface
metal shiny metallic surface
null general null shader
plastic plastic-like surface
spotlight conical light source with exponential fall-off

Table 1. Standard Shaders.

Texture Files

Texture files contain data that may be used in the shading process through the texture, environment, bump and shadow operators. In order to allow for texture files that can optimize the access patterns typically seen during rendering, PhotoRealistic RenderMan requires that texture files be converted into one of two formats:

PRMan will transparently access texture files in either format. When creating these texture files, the default texture format is controlled by the /prman/textureformat option in the configuration file; this may be overridden by a parameter to RiMakeTexture, or a command line option to txmake.

To create a texture file from a picture file the standalone txmake utility can be used. For example:

txmake wood.tif wood.tex

A manual page for this program is provided in the PhotoRealistic RenderMan Reference Documentation section of this volume. This is a useful alternative to the RiMakeTexture routine. In either case, texture files must be created before they are used.

The source picture files that txmake and RiMakeTexture use to create texture maps can be in one of many image formats, including: TIFF, Alias, mayaiff, Radiance, JPEG, and SGI RGB. Source images for texture maps or environment maps can be any resolution; however, the texture making process causes these files to be resized into various other resolutions for fast filtered access, each being some even power of two resolution in both width and height. The user has some control of this filtering process with the -resize option of txmake (or equivalently, the resize parameter of RiMakeTexture). By default, the file is first resized up to the next highest power of two resolution in each direction, using a high-quality Catmull-Rom filter. Other possibilities include resize down to the next lower power of two resolution, and round the resolution to the closest power of two. In all three cases, information about the original image aspect ratio is retained within the file so that the texture is not stretched when it is applied to simple surfaces. (The behavior of previous releases of PhotoRealistic RenderMan to fill images with black pixels, rather than resize them, can be requested with resize value of none.)

Source images for shadow depth maps must be power of two resolution, as this resizing functionality is not implemented for shadow depth maps. If the source depth files do not have an even power of two resolution, the shadow maps will not produce correct shadows.

Texture file names should either be given as absolute path names or through the PhotoRealistic RenderMan-specific searchpath option. See Configuration Files and PRMan Options: Search Paths for details about search paths.

PhotoRealistic RenderMan provides two utility programs (in addition to txmake) to manipulate texture files. Manual pages for these programs are provided in the PhotoRealistic RenderMan Reference Documentation. The programs are: sho, used to display texture images using the PhotoRealistic RenderMan display server, and txinfo, used to print descriptive information about a texture file.

Running PhotoRealistic RenderMan

PhotoRealistic RenderMan is designed to be portable; it runs on a wide variety of machines and under a number of different operating systems. PhotoRealistic RenderMan typically functions as a single self-contained program, except for some display services. The rendering algorithm, texturing facilities, shading language interpreter, etc. are all integrated into a single program that runs as a single process and allocates memory through the standard system facilities.

The prman Executable

PhotoRealistic RenderMan is invoked using the prman executable. To render a model file containing RIB data, simply use:

prman model.rib

It is often convenient to store options, camera specification and the world block in separate files. prman can be given multiple file names and it will process them in the order given:

prman options.rib camera.rib world.rib

Note, however, that file is an optional argument; prman can take RIB from stdin (standard input).

The prman executable accepts several command-line options:

Causes the renderer to print out version information. This flag may be used without specifying a RIB file, in which case the renderer will print out the version and exit immediately.
-recover [0|1]
In conjunction with a display driver that supports the checkpointing facility, this parameter causes the renderer to check for a partially completed image and attempt to render only the remainder of that image. Use "-recover 1" to enable the restart, 0 to disable.
Causes the renderer to print out a percentage complete indicator during the rendering.
The same as -progress, except that the renderer will print out an indicator, which is useful when used in conjunction with Alfred.
Controls the degree of multithreading for single-host rendering, where n represents the target number of CPU cores consumed by the prman process. If no -t option is given, then the number of threads is controlled by a setting in rendermn.ini; by default, the number is chosen automatically to fully utilize the thread maximum allowed by a single license. Processor counts can be specified as follows:
     t -> use all available processors (potentially using several licenses)
     n -> use n parallel contexts
     0 -> use the number of CPUs (identical to "-p")
    -n -> use "all but n" of the available CPUs
The rendermn.ini "/prman/nthreads" setting can be n, 0, or -n, as above (if unspecified, the default is 0). The current license utilization rate is one license per pair of processors
Enables multi-processor mode, for single-host, bucket-parallel rendering. Frame processing will be subdivided into chunks that are rendered simultaneously. The number of concurrent contexts is set to the number of CPUs on the system. An explicit context count can be specified using "-p:n" where
     n -> use n parallel contexts
     0 -> use the number of CPUs (identical to "-p")
    -n -> use "all but n" of the available CPUs
If the "-p" option isn't supplied, then the value is taken from the rendermn.ini "/prman/nprocessors" setting. The ini setting can be n, 0, or -n as above (if unspecified it currently defaults to 1).
-catrib [outfile|-] [-ascii] [-binary] [-gzip]
Copies ASCII and/or binary RIB data from the specified file to an output file, possibly converting its format. The format of the output file is specified by command line options, -ascii and -binary, or by the RIFORMAT environment variable. Compression is enabled on the output file by the command line option -gzip, or by the RICOMPRESSION environment variable. For more information, see the Manual Page for CATRIB(1).
-rif plugin [-rifargs arg arg... -rifend]
Instructs the renderer to load a chain of Rif plugins. Arguments can be passed to the plugins via the -rifarg command line argument, where -rifend delineates the end of the arguments for a given plugin. For more information, please consult the User's Manual page for Plug-in Ri Filters.
Turns off Xcpt warnings (e.g. prman -woff R50006 test.rib).
file [file...]
Specifies a file to execute prman on.).

Renderer Output

The images created by PhotoRealistic RenderMan can be placed into a file or onto a frame buffer device via an appropriate display driver. PhotoRealistic RenderMan is shipped with display drivers that support image output in various file formats and display devices. These drivers are described in Display Drivers. The default file format is TIFF. The default framebuffer is either the x11 or windows, which render to a window on the local system display. To select one a driver that is not the default file or framebuffer driver use RiDisplay as follows:

RiDisplay("filename", "driver", ...);

where driver is the name of the display driver. The driver may or may not use the filename argument. When output is directed to a file, the name of the file is the name specified in the RiDisplay command. If the file name is not an absolute path name, the file is created in the directory in which rendering is performed.

RGBA, RGB, or single channel (R) pixels can be generated with the precision selected by the appropriate RiQuantize request. For example, to output 8-bit RGB data in a file named foo.tif:

RiQuantize(RI_RGBA, 255, 0, 255, .5);
RiDisplay("foo.tif", RI_FILE, RI_RGB, RI_NULL);

Extensions to the RiDisplay call beyond the RenderMan Specification are documented in PRMan Options: Frame Buffer Control.

Environment Variables

Several environment variables are used to control the operation of the PhotoRealistic RenderMan system. The values of these variables are modified with the UNIX setenv command. The following is a list of these variables and how they are interpreted.

This specifies the root of the file tree that contains the RenderMan Toolkit release. All programs in the RenderMan Toolkit check this variable to search for executables, shell scripts, data files, etc. If this variable is undefined, the software tries to fall back to the installed location of the running binary, typically in /opt/pixar/.... If the release is installed at some other location, this variable must be set to point at its new location.
This controls whether the output of the RIB library is in compressed. Setting RICOMPRESSION to gzip causes gzip compression to be applied to the output. The default is to not use gzip compression.
This controls whether the output of the RIB library is in binary or ASCII. Setting RIFORMAT to binary causes binary output and setting it to ascii causes ASCII output. If RIFORMAT is undefined, the output is in ASCII.
This specifies the name of the file to which the RIB library will write its output. If RISERVER is undefined, and no name is specified to RiBegin (see PRMan Options: RIB Output), the output is written to standard output.
If set, PRMan will display the default configuration files while they are read from rendermn.ini. This is a useful debugging tool.
This overrides the name of the default framebuffer device. By default, RiDisplay "framebuffer" will use either the x11 or windows device driver. This variable can be used to force the default framebuffer device to be a machine-specific or site-specific device driver, instead.

Some of the display drivers also use environment variables. See the documentation for the individual drivers in the Reference Documentation.

Configuration Files

Many of the internal defaults of PhotoRealistic RenderMan can be controlled by configuration files named rendermn.ini. These configuration files are read at the time of the call to RiBegin, before any other Ri calls are processed. For defaults that correspond to an Ri call, the Ri call, if present, will override the default value.

The initial configuration file rendermn.ini is found in the directory ${RMANTREE}/etc. After the initial configuration file has been scanned, additional configuration files will be scanned their settings will override any values set in the initial configuration file. These additional files are named rendermn.ini and they are searched for in both the directory defined by the environment HOME and in the current directory, in that order. (The file in the HOME directory can optionally have a leading "." to make it a hidden file.)

The configuration file format is a set of lines containing strings. The first string on the line is the name of the default and the rest of the line specify its default value. Environment variables may be referenced inside the configuration file using the following special syntax:


Undefined environment variables default to the empty string, except for ${RMANTREE}, which defaults to /usr/local/prman. Lines beginning with a # are ignored. The following is a list of the defaults that can be set in configuration files that are relevant to PhotoRealistic RenderMan. Note that there are also various display drivers that also read defaults from this file, and those defaults are documented in the Reference Documentation.

Sets the directory where the error message files are to be found. The renderer and tools will look in this directory when reporting errors. If set, this directory overrides the compiled default of ${RMANTREE}/etc/messages.
Specifies a fully qualified name of the license file. Modern usage of /licensefile should be restricted to the form 7498@hostname, where "hostname" is the name of the license server.
Allows a one level translation of the display type framebuffer or file, as specified in an RiDisplay call, to an alternate display type. The default translations for file is tiff, and the default translation for framebuffer is to use the value of the RMANFB environment variable if set, otherwise it will use x11 or windows depending on the system.
Overrides the default x resolution (width) of the display type displaytype.
Overrides the default y resolution (height) of the display type displaytype.
Overrides the default pixel aspect ratio of the display type displaytype.
Now obsolete. For backwards compatibility, if this specifies the name of an external display driver (something other than internal), the new display system will attempt to open it and write to it using the old display protocol.
Translation from a driver name to a file name before the search paths for the display driver DSOs are used. %s is replaced with the driver name.
Path to the display driver DSOs.
Secondary path to the display driver DSOs.
Overrides the /display/dsopath with the path name for a specific DSO display driver.
Sets the compression algorithm to be used for the internal tiff driver. The default value is zip. Alternate values are packbits, pixarlog, lzw or none. Note: At this time many third party software packages do not support the default, zip, compression scheme. Packbits or no compression may be most convenient for images for use with these other software packages (PhotoShop, DeBabelizer, etc). Files that are rendered using the zip compression scheme can be converted using the utility program tiffcopy to change the compression.
provides compression with the algorithm used by the popular gzip program. Output files are usually smaller than those produced using lzw compression. zip is purported to be unencumbered by patents and is supported by the libtiff library available for free from Silicon Graphics. The actual zip compression is implemented using a freely available library written by Jean-loup Gailly and Mark Adler. 
If TIFF files with more than eight bits per pixel are required and portability is not an issue, sixteen bit or floating point pixel data can be written using pixarlog compression. pixarlog compands the input data preserving more data that is usually detectable by the human eye while creating files that compress much better than regular sixteen bit data. Pixar is donating pixarlog compression to the libtiff library maintained at Silicon Graphics so it will be available for use in other software.
provides Macintosh PackBits compression as defined in the TIFF 6.0 specification Section 9. This compression very portable. It is handled by most readers of TIFF files. Its drawback is that it does not compress as well as the other compression choices.
provides Lempel-Ziv & Welch compression as defined in TIFF 6.0 specification Section 13.
stores the file without compression. Output files can be quite large, but virtually any valid TIFF reader should be able to read them.
When using an external file driver that requires the image in scan line order, the dspyserver requires a temporary file whose size depends on the size of the image being rendered. This configuration value sets the directory location for this file, which defaults to /usr/tmp.
Sets the file search path for shader files. This is equivalent to the call:
RiOption("searchpath", "shader", (RtPointer)&spath, RI_NULL);
except that the configuration file changes the search path before any shaders (including defaultsurface) are loaded. See PRMan Options: Search Paths for details of the path format.
Sets the string that will be the translation of the `@' character for the /shaderpath default or RiOption call. The default value is ${RMANTREE}/lib/shaders. See PRMan Options: Search Paths for details of the path format.
Sets the file search path for texture files. This is equivalent to the call:
RiOption("searchpath", "texture", (RtPointer)&tpath, RI_NULL);
See PRMan Options: Search Paths for details of the path format.
Sets the string that will be the translation of the `@' character for the /texturepath default or RiOption call. The default value is ${RMANTREE}/lib/textures. See PRMan Options: Search Paths for details of the path format.
Sets the default bucketsize used by the renderer. The value should be two decimal numbers separated by a space. This is equivalent to the call:
RiOption("limits", "bucketsize", (RtPointer)&bs, RI_NULL);
See PRMan Options: Limits: Bucket Size for more details.
Sets the default maximum gridsize used by the renderer. This is equivalent to the call:
RiOption("limits", "gridsize", (RtPointer)&gs, RI_NULL);
See PRMan Options: Limits: Grid Size for more details.
Sets the default size in kilobytes of the texture memory cache used by the renderer. This is equivalent to the call:
RiOption("limits", "texturememory", (RtPointer)&tm, RI_NULL);
See PRMan Options: Limits: Texture Memory for more details.
Sets the default size in kilobytes of the brick cache used by the renderer. This is equivalent to the call:
RiOption("limits", "brickmemory", (RtPointer)&tm, RI_NULL);
See PRMan Options: Limits: Texture Memory for more details.
Sets the default size in kilobytes of the geometry cache used by the renderer for ray tracing. This is equivalent to the call:
RiOption("limits", "geocachememory", (RtPointer)&tm, RI_NULL);
See PRMan Options: Ray Tracing for more details.
Sets the default output texture format used by the RiMakeTexture, RiMakeEnvironment, and RiMakeShadow interface calls as well as the standalone txmake utility. May be one of: "tiff" or "pixar".
Indirectly sets the maximum number of file descriptors used by the texture subystem of the renderer. The renderer will use the maximum of current operating system limit or the maxfiles setting (see below), minus the sum of the filesmargin setting and /prman/brickmap/maxfiles. In other words, this setting reserves a number of file descriptors for use by DSOs or other parts of the renderer. The default setting is twenty.
Sets the maximum number of file descriptors used by the texture subsystem of the renderer, minus the filesmargin setting (see above) and /prman/brickmap/maxfiles (see below).
Sets the maximum number of file descriptors used by the brickmap subsystem of the renderer. If unset, the default setting is 64.
Sets the default shading rate used by the renderer. This is equivalent to the RiShadingRate call. See Helpful Hints: Quick Renderings for more information about RiShadingRate.

Following is an example configuration file:

            /displaytype/file           tiff
            /display/tiff/compression   zip
            /display/tiff/xres          640
            /display/tiff/yres          480
            /display/tiff/par           1
            /errorpath                  ${RMANTREE}/etc/messages
            /dspyserver                 ${RMANTREE}/etc/dspyserver
            /licensefile                ${RMANTREE}/etc/license.dat
            /standardshaderpath         ${RMANTREE}/lib/shaders
            /standardtexturepath        ${RMANTREE}/lib/textures
            /shaderpath                 .:@
            /texturepath                .:@
            /prman/bucketsize           12 12
            /prman/gridsize             512
            /prman/texturememory        8192
            /prman/shadingrate          1

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