This document describes the PhotoRealistic RenderMan client library and its use to output RenderMan Interface Bytestream data. Its motivation and alternatives to its use are discussed.
The RenderMan Interface consists of functionality that is specified by C procedure calls and the parameters associated with these calls. The intent of the RenderMan Interface was to provide a concise representation of all of the functionality required to describe a 3-D scene, with all of the geometric, viewing, lighting, and shading data.
The RenderMan Interface Specification V3.0, was first published in May 1988 after review internally at Pixar and after extensive review and comment by over 20 modeling, rendering, CAD, and computer companies. Pixar produced its first rendering system that adhered to the RenderMan Interface in the Fall of 1988 and distributed that package to parties interested in using the RenderMan Interface for rendering. Part of that initial system was a bytestream protocol (or RIB, as it has come to be known) that formed an alternate representation for the information specified by the 95 C procedure calls.
The RenderMan Interface Bytestream (RIB) protocol was initially considered an internal database format for Pixar's PhotoRealistic RenderMan product. However, after strong and overwhelming interest was expressed in RIB by the members of the RenderMan Advisory Council (an independent group of graphics industry specialists who meet regularly to advise Pixar on changes they would like to see made, or not made, to the RenderMan Interface), Pixar included a complete specification of RIB in a revised edition of the RenderMan Interface Specification, V3.1 and made it an alternate binding for the C procedure calls that make up the RenderMan Interface, V3.1.
Although RIB is an alternate binding of the RenderMan Interface, Pixar considers the C procedure calls to be the primary method for specifying the RenderMan Interface. RIB is formally considered to be a transmission protocol between a client modeler and a server renderer -- two programs that are running independently (and perhaps at different times on different computers and/or computer networks). How then, is RIB produced? And what is the relation of the C procedure calls to RIB? These questions are best answered by the PhotoRealistic RenderMan client library.
The PhotoRealistic RenderMan client library is a subroutine library containing C procedures that match those specified by the RenderMan Interface Specification. However, rather than actually implement the functions as described by the RenderMan Interface Specification, the client library procedures simply produce the RIB representation of the RenderMan Interface procedure call. That is, it outputs a stream of ASCII or ASCII/binary data that represents the RenderMan procedure call and all the supplied parameters. This data can be output to a file or piped directly to a program that can read and interpret the data.
It is important to understand that the client library interface is exactly the same as a normal RenderMan library. The subroutines, parameters, and global data are identical. The only difference is that a normal RenderMan library produces image pixels as its output; the client library produces a RIB file that is a description of the 3-D scene represented by the RenderMan calls.
For example, the RenderMan Interface procedure call:
would result in the following stream of characters being output by the client library:
Thus, the PhotoRealistic RenderMan client library can be used to output a complete 3-D scene description for rendering later or remotely rather than immediately and locally. The user of Pixar's PhotoRealistic RenderMan has the option of doing either, depending upon which library of procedures is used to link with their application program. If the renderer library (libprman) is used, rendering will occur immediately and locally as the RenderMan procedures are called. If the client library (librib*) is used, RIB will be output for storage in a file for later rendering, or even for transmission to a remote rendering system.
There are advantages and disadvantages to using the client library and RIB. In general, the advantages far outweigh the disadvantages. These points are summarized below.
There are several advantages that can be gained by using the client library to output RIB data:
Reduced memory size of the application's executable image. Since a rendering system that fully implements the RenderMan Interface is a very complicated software system, the resultant size of a library that contains fully functional RenderMan procedures can be quite large. Pixar's libprman consists of over 500,000 bytes of code and static data requiring at least that much memory to execute in, and other additional dynamic data storage required to perform the rendering. In high-powered virtual-memory workstations this may not be as big a concern as in a limited-memory non-virtual personal computer. Still, the resulting executable image size of an application can be considerably reduced by using the client library. Pixar's librib client library is implemented in less than 50,000 bytes of code and little or no dynamic memory requirements.
Flexibility. If the client library is used, the user may choose to link directly with libprman for direct rendering or to link with librib to output the RIB file. Note that this flexibility is gained without the need to change any code in the user's application program.
Compact representation for RIB data. The librib client library may also be used to select a binary mode for RIB data so that all subsequent RIB data output will be binary rather than ASCII data, reducing the overall size and interpretation overhead of a RIB file.
Use as a 3-D scene metafile. Since RIB can be used to specify all of the output data for a 3-D scene, a RIB file can be used as a 3-D scene metafile for transferring information between applications. However, since much of the information about the structure of the geometry has been lost in generating the RIB file, instructions must be added to allow surface information to be inferred from the geometry specified explicitly in the RIB data. Appendix D of the RenderMan Interface Specification V3.1 contains conventions that should be followed when generating RIB data to ensure that this inference of topology is possible.
Remote rendering. RIB can be communicated across a network, or on other media for rendering on a remote rendering system. Since RIB is a bytestream protocol, it is ideally suited for transmission over networks, or other communications methods, to a remote rendering system. A scene is specified completely, allowing rendering to be completed remotely with the resulting image transmitted back to the originator or displayed or stored where it is rendered.
Insulation from change. Should the RIB protocol be modified or enhanced, a new client library (one that supports the modified or enhanced RIB protocol) can simply be linked in to the user's application without any code changes required.
The disadvantages of using the client library to output RIB are:
Additional overhead involved in generating or interpreting RIB data. Since the parameters to the librib client library are turned into tokens, output to the RIB data stream, and eventually reinterpreted and turned into parameters to the corresponding RenderMan Interface call, overhead is incurred that could be eliminated if linked directly with libprman. The bigger the RIB file, the larger the overhead incurred in generating or interpreting RIB data.
Difficulty of implementing some RenderMan Interface functionality. Some RenderMan Interface functionality cannot be reasonably implemented using the client library and RIB. Certain calls of the RenderMan Interface require data to be returned from the procedure call, or that a user-specified procedure be supplied that can later be called from the RenderMan renderer. An example of this is RiProcedural, a call that allows a user-written procedure to be called to algorithmically define a geometric entity.
The alternatives to using the librib client library are few. A RIB data file could be generated by being edited directly with an ASCII text editor, or RIB data could be output by printf statements in a C program. Both of these methods are undesirable. No reasonable application program could or would rely on a user to edit RIB data directly, so only a few test models would ever be expected to be generated directly using a text editor. If an application program hand-coded printf statements that generate RIB data the work of generating all the correct RIB tokens would then, in practice, be hard coded into the user's application that used the printfs.
The only reasonable approach to outputting RIB data is to use the RenderMan Interface C procedure calls to output RIB. Objections to using the client library to do so include the following:
A particular application is written in a language other than C. In this case, the librib library should be ported to the appropriate language for integration into the application. Most computer systems today provide a C compiler that generates object code that can be linked and used with other languages.
Ignorance. Some developers have hard-coded printf statements into their applications to output RIB. Excuses for this include ignorance of the importance of using the librib client library, or even of its existence. This application note is intended to permanently dispel this ignorance.
The only reasonable approach to outputting RIB data is to use the RenderMan Interface C procedure calls of the librib client library to output RIB. Please USE THE CLIENT LIBRARY!
Appendix D of the RenderMan Interface Specification V3.1, presents some conventions that should be followed when using the client library to output RIB data. These conventions are more fully described in PhotoRealistic RenderMan Application Note #2, Creating A Properly Structured RIB File .
The RenderMan Interface V3.0, May 1988, Pixar.
RenderMan Developer's Toolkit, Reyes 2.0, October 1988, Pixar.
The RenderMan Interface V3.1, September 1989, Pixar.
PhotoRealistic RenderMan Application Note #2, Creating A Properly Structured RIB File, February, 1990, Pixar.
Pixar Animation Studios