PhotoRealistic RenderMan is a rendering system that generates high-quality 2D images from 3D scene-description information. Scene descriptions are created through the RenderMan Interface and are typically comprised of:

The scene description may also specify the destination for the output image (e.g., a file or a frame buffer), as well as miscellaneous parameters that control the operation of the rendering system: how much effort to devote to avoiding aliasing, for instance.

A scene description is usually supplied to PhotoRealistic RenderMan in a file. This file is created by a modeling system that makes calls to the interface routines specified in the RenderMan Interface. The format of this file is defined by the RenderMan Interface Bytestream protocol, RIB, and can be a mix of ASCII and binary data.

The files and utilities described below, are defined in the Reference Documentation portion of this manual. Refer to that portion of the manual for further details and information.

The RenderMan Interface

The RenderMan Interface is currently specified in two forms: the C language binding, which was first published in Version 3.0 of the specification, and the RenderMan Interface Bytestream (RIB) protocol, which appears in Version 3.1. These two forms of RenderMan correspond directly wherever possible, except for a few limitations imposed by the one-way nature of RIB. PhotoRealistic RenderMan supports the latter usage directly - PRMan is run from the command line, and given a RIB stream as input. One advantage of the latter method is that it supports a client-server system model, making it easier to distribute rendering among machines. Furthermore, RIB streams can be stored in files, which facilitate rendering at later times or on different systems.

PRMan does support the C language binding, but only via shared objects that can be linked directly with the renderer.

Since PhotoRealistic RenderMan is to be run as a separate program, the user must have some way to create a RIB stream. Though it is possible to do this directly (with an editor, for example), we recommend using the RIB client library by linking your program with librib.a. This library links into a C program the same way the rendering library does, but instead of performing the rendering at run-time, it creates a file containing the RIB stream produced by the RenderMan calls in the program.

The RenderMan Interface Bytestream

The most compact form of the RenderMan Interface Bytestream is a binary encoded version of the human-readable ASCII form, which in turn translates directly to the C language binding. The renderer can use these forms interchangeably, but there is a utility shipped with PhotoRealistic RenderMan named catrib that converts RIB files from one version to the other for your convenience. Although there is no file-naming convention enforced by the software, we recommend that you use the suffix .rib to denote RIB files.

PhotoRealistic RenderMan

The executable renderer that takes a RIB file as input is called prman, and it is to be invoked directly. When the renderer runs, it sends output pixels to a display server, which contains a display device driver for the particular hardware device or file which should receive the pixels. Beginning in version 3.8, display servers can be in the form of dynamically-linked libraries, or DSOs. If you want to use a non-standard frame buffer or image file format, you will have to write and install your own display driver. See Custom Display Drivers for further information.

If you have, through the RenderMan Interface, set the renderer to output to an rgb or rgba image file, the default display driver will output a TIFF file. As with RIB files, there is no naming convention, but we recommend using .tif as a suffix. The renderer also knows how to display images in other file formats, and on the standard color framebuffer for each type of machine.

The RenderMan Shading Language

The RenderMan Interface contains a description of the Shading Language. Using the Shading Language, it is possible to write your own routines for several types of operations that take place during the rendering process. The source code for a shader is written in a file, which is then compiled using the utility shader. The compiler makes no assumptions about input file names, but we recommend using the suffix .sl to denote shading language source code. The compiler produces one file for each shader or function in the source. Each file is named with the name of the shader or function followed by the suffix .slo. Note that the name of the source file does not necessarily have anything to do with the name of the shading language object files.

During rendering, the renderer must be able to find a .slo file for every shader that is used. There is a PhotoRealistic RenderMan dependent RiOption called searchpath that tells the renderer where to look for shader object files. See PRMan Options: Search Paths for details. Configuration files can also control the shader search path. See Rendering Images: Configuration Files for details.

Texture Files

There are currently three shading language functions that are used to access texture data: texture, environment, and shadow. In order to use these functions, the renderer must be able to find the appropriate texture files. You can either provide the full path name of the file when you give it as an argument to the shader function, or you can give just a file name and use the RiOption searchpath or configuration file to tell the renderer where to look (see PRMan Options: Search Paths and Rendering Images: Configuration Files for more details).

Texture files are created with the utility txmake, which takes image files or zfiles as input. There are various command line options to txmake that specify the type of input and the type of texture file to be created (see Rendering Images: Texture Files for details). In general, a shadow map is produced from a zfile, a texture map is produced from a TIFF file, and an environment map is produced from either one or six TIFF files, depending on the environment type. Zfiles are produced by the renderer, but input TIFF files can either be produced by the renderer or brought in from some other software (such as a digitizer). Texture files contain a great deal of information and can easily become very large. However texture files are created using various data compression schemes to keep the files from getting too large. The size of the file depends on the data in the input image. Don't be surprised if you use up large amounts of disk space when you try to use txmake on a large image.

There are also RenderMan calls that create texture maps from inside the prman renderer, which is equivalent to calling txmake. Modeling programs which compute and create texture maps on the fly may wish to use these calls, but it is often more appropriate to create texture maps prior to running renderer.

Though there is no enforced naming convention for the different types of texture files, we recommend .tex, .env, and .shd for texture, environment, and shadow maps respectively. If you need to get information about a texture file, there is a command line utility called txinfo that prints out the type, size, and other useful information about a texture file.

Display Utilities

Previous releases of PhotoRealistic RenderMan had multiple applications that made use of the display server. In PhotoRealistic RenderMan version 3.8, most of these applications (such as bktdspy, picdspy, tiffdspy, txdspy, and tgadspy) have been replaced by an improved version of sho.

This utility automatically figures out what image file format is contained in a file and displays it. It can recognize all of the file formats supported by PhotoRealistic RenderMan and quite a few more.
This utility compares two TIFF files and outputs a graphic representation of the differences between them.

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