RIB Binding

RIB Binding

The RenderMan Interface Bytestream Protocol, abbreviated RIB, is a byte-oriented protocol for specifying requests to the RenderMan Interface (RI) library. RIB permits clients of the RenderMan Interface to communicate requests to a remote rendering service, or to save requests in a file for later submission to a renderer. To satisfy the many different needs of clients, the protocol is designed to provide both

  • an understandable (potentially) interactive interface to a rendering server, and
  • a compact encoded format that minimizes transmission time (and space when stored in a file).

RIB also strives to minimize the amount of communication from a server to a client. This is particularly important in the situation where no communication is possible; e.g., when recording RIB in a file.

RIB is a byte stream protocol. That is, RIB interpreters work by scanning the input stream one byte at a time. This implies interpreters should make no assumptions about data alignment. The protocol is best thought of as a command language where tokens in the input stream can be transmitted either as 7-bit ASCII strings or, optionally, as compressed binary data. The ASCII interface provides a convenient interface for users to interactively communicate with a rendering server and for developers to debug systems that generate RIB. The binary encoding significantly compresses the data stream associated with an RI description with an associated savings in communication overhead and/or file storage cost.

Bytestream Protocol

This document also describes a byte stream representation of the RenderMan Interface, known as the RenderMan Interface Bytestream, or RIB. This byte stream serves as both a network transport protocol for modeling system clients to communicate requests to a remote rendering service, and an archive file format to save requests for later submission to a renderer.

The RIB protocol provides both an ASCII and binary encoding of each request, in order to satisfy needs for both an understandable (potentially) interactive interface to a rendering server and a compact encoded format which minimizes transmission time and file storage costs. Some requests have multiple versions, for efficiency or to denote special cases of the request.

The semantics of each RIB request are identical to the corresponding C entry point, except as specifically noted in the text. In the RenderMan Interface section of the documentation, each RIB request is presented in its ASCII encoding, using the following format:

RIB BINDING

Request parameter1 parameter2... parameterN

Explanation of the special semantics of the RIB protocol for this request.

At the top of the description, parameter1 through parameterN are the parameters that the request requires. A hyphen (-) in the parameter position indicates that the request expects no parameters. Normally the parameter names suggest their purpose, e.g., x, y, or angle.

In RIB, square brackets ([ and ]) delimit arrays. Integers will be automatically promoted if supplied for parameters which require floating point values. A parameter list is simply a sequence of string-array pairs. There is no explicit termination symbol as in the C binding. Example parameter lists are:

"P" [0 1 2 3 4 5 6 7 8 9 10 11]
"distance" [.5] "roughness" [1.2]

The details of the lexical syntax of both the ASCII and binary encodings of the RIB protocol are presented in the RIB Syntax Summary, below.


RIB Syntax Summary

RenderMan Interface Protocol requests are constructed from sequences of tokens. Tokens are formed by the input scanner by grouping characters according to the RIB syntax rules (described below). Other than requirements associated with delimiting tokens, RIB employs a free format syntax.

Character set

The standard character set is the printable subset of the ASCII character set, plus the characters space, tab, and newline (return or line-feed). Non-printing characters are accepted, but are discouraged as they impair portability.

The characters space, tab, and newline are referred to as white space characters and are treated equivalently (except when they appear in comments or strings). White space is used to delimit syntactic constructs such as identifiers or numbers. Any number of consecutive white space characters are treated as a single white space character.

The characters ", #, [, and ] are special: they delimit syntactic entities. All other characters are termed regular characters and may be used in constructing syntactic entities such as identifiers and numbers.

Comments

Any occurrence of the # character, except when in a string, indicates a comment. The comment consists of all characters between the # and the next newline character. Comments are treated as white space when they are encountered by the input scanner.

Numbers

Numbers include signed integers and reals. An integer consists of an optional sign (+, -) followed by one or more decimal digits. The number is interpreted as a signed decimal integer.

A real consists of an optional sign and one or more decimal digits, with an embedded period (decimal point), a trailing exponent, or both. The exponent, if present, consists of E or e followed by an optional sign and one or more decimal digits. The number is interpreted as a real number and converted to an internal floating point value.

Strings

A string is an arbitrary sequence of characters delimited by double quote marks ("). Within a string the only special characters are " and the \ (back-slash) character. The \ character is used as an escape to include the " character, non-printing characters, and the \ character itself. The character immediately following the \ determines the precise interpretation, as follows:

\n    linefeed (newline)
\r    carriage return
\t    horizontal tab
\b    backspace
\f    form feed
\\  backslash
\"    double quote
\ddd    character code ddd (octal)
\newline    no character -- both are ignored

If the character following the is not one of the above, the is ignored.

The \ddd form may be used to include any 8-bit character constant in a string. One, two, or three octal digits may be specified (with high-order overflow ignored).

The \newline form is used to break a string into a number of lines but not have the newlines be part of the string.

Names

Any token that consists entirely of regular characters and that cannot be interpreted as a number is treated as a name. All characters except specials and white space can appear in names.

Arrays

The characters [ and ] are self-delimiting tokens that specify the construction of an array of numbers or strings. An array cannot contain both numbers and strings. If an array contains at least one floating point value, all integer values in the array are converted to floating point. Arrays of numbers are used, for example, to specify matrices and points. Arrays of strings are used in specifying options.

Binary encoding

For efficiency, compressed binary encodings of many types of data are also supported. These encodings may be freely intermixed with the normal ASCII strings. The two encodings are differentiated by the top bit of the eight-bit bytes in the input stream. If the top bit is zero, then the byte is interpreted as a 7-bit ASCII character. Otherwise, if the top bit is one, the byte is interpreted as a compressed token according to the rules given below. This differentiation is not applied within string constants or the parameter bytes that follow the initial byte of a compressed token. The table below shows the encoding for compressed tokens with all byte values displayed in octal.

Binary Encoding
Values Span Interpreted as...
0-0177 128 ASCII characters
0200-0217 16 encoded integers and fixed-point numbers
0220-0237 16 encoded strings of no more than 15 characters
0240-0243 4 encoded strings longer than 15 characters
0244 1 encoded single precision IEEE floating point value
0245 1 encoded double precision IEEE floating point value
0246 1 encoded RI request
0247-0307 32 nothing (reserved)
0310-0313 4 encoded single precision array (length follows)
0314 1 define encoded request
0315-0316 2 define encoded string token
0317-0320 2 interpolate defined string
0321-0377 46 nothing

Four separate data types are supported: signed integers, signed fixed-point numbers, strings, and floating-point numbers. Integers and fixed-point numbers are encoded using a single format while strings are encoded with two different formats according to the length of the string. Both single- and double-precision IEEE format floating-point numbers are supported. Strings that are used repeatedly can be defined and then subsequently referenced with a compact form that is usually more space efficient.

Arrays of floating-point values are directly supported for efficiency (they can also be specified using the array definition symbols). Single-precision matrices (arrays of 16 floating-point values) can be specified in a total of 66 bytes, while other arrays may require slightly more.

In the following sections the syntax for each encoding is presented as a sequence of bytes separated by | symbols. Numeric values should interpreted as octal values (base 8) if they have a leading 0 digit, otherwise as decimal values. Items shown in angle brackets - < > - represent varying items, such as a numeric value or string that is being encoded.

Integers and fixed-point numbers

Integer and fixed-point values can be transmitted in 2-5 bytes. The encoded token has the form:

0200 + (d.4) + w< | <value>

where the next w*+1 bytes form a signed integer taken from the most significant byte to the least significant byte, and the bottom *d bytes are after the decimal point.

Strings

Strings shorter than 16 bytes, say w bytes, can be transmitted with a prefixing token:

0220 + w  | <string>

Other strings must use a prefixing token followed by a variable length string length, and then followed by the string itself:

0240 + l | <length>  | <string>

where l + 1 is the number of bytes needed to specify the length of the string, 0 <= l <= 3. The string length is an unsigned value and is transmitted from most significant byte to least significant byte. Unlike unencoded strings, there are no escape or special characters in an encoded string.

Defining strings

For strings that are to be transmitted repeatedly, a string token can be defined with:

0315 + w | <token> | <string>

where w + 1 is the number of bytes needed to specify the token, (1 or 2), and the string being defined is transmitted in an encoded or unencoded form. The token is an unsigned value and is transmitted from most significant byte to least significant byte. For efficiency, the range of tokens defined should be as compact as possible.

Referencing defined strings

To interpolate a string that has previously been defined (as described above), the following is used:

0317 + w | <token>

where the token refers to the string to be interpolated.

Floating-point values
Floating-point values are transmitted in single-precision or double-precision IEEE format from most significant byte to least significant byte. Single-precision floating-point values occupy four bytes in the input stream and double-precision values occupy eight bytes.
Floating point arrays

Aggregates of single-precision floating-point values can be transmitted with a prefixing token byte. Variable sized arrays are transmitted as a token byte followed by a variable length array size, and then followed by the array itself:

0310 + l | <length> | <array of floats>

The array length is an unsigned value, l+1 bytes long, and is transmitted from most significant byte to least significant byte.

Defining RI requests

Before an encoded request can be used, it must first be bound to its ASCII equivalent with:

0314 | <code> | <string>

where the code is one byte and string is the ASCII form of the request.

Referencing defined RI requests

A previously defined RI request is referenced with two bytes; a prefixing token, 0246, followed by a request code.

0246 | <code>

This means that no more than 256 RI requests can be directly encoded in the binary protocol.

Example

Consider the following sequence of RIB commands:

version 3.03
ErrorHandler "print"
Display "test.25.pic" "file" "rgba"
Format 512 307 1
Clipping 0.1 10000
WorldBegin
Declare "direction" "point"
LightSource "windowlight" 0 "direction" [1 0 -0.1]
Color [1 1 1]
Orientation "lh"
Sides 1
AttributeBegin
MotionBegin [0 1]
Translate 1.91851 0.213234 1.55
Sphere 2 -0.3 1.95 175
MotionEnd
AttributeEnd

This could translate into the encoded sequence of bytes shown in the figure below.


Example encoded RIB byte stream

v     e     r     s     i     o     n     212   # version
003   007   256   E     r     r     o     r     # 3.03 Error
H     a     n     d     l     e     r     225   # Handler "
p     r     i     n     t     D     i     s     # print" Dis
p     l     a     y     315   \0    233   t     # play <defstr 0 "t
e     s     t     .     2     5     .     p     # est.25.p
i     c     317   \0    315   001   224   f     # ic"> <str 0> <defstr 1 "f
i     l     e     317   001   315   002   224   # ile"> <str 1> <defstr 2 "
r     g     b     a     317   002   F     o     # rgba"> <str 2> Fo
r     m     a     t     201   002   \0    201   # rmat 512
001   3     200   001   C     l     i     p     # 307 1 Clip
p     i     n     g     211   031   231   201   # ping 0.1
'     020   314   272   232   W     o     r     # 10000 <defreq 0272 "Wor
l     d     B     e     g     i     n     246   # ldBegin"> <req
272   314   207   227   D     e     c     l     # 0272> <defreq 0207 "Decl
a     r     e     246   207   315   003   231   # are"> <req 0207> <defstr 3 "
d     i     r     e     c     t     i     o     # directio
n     317   003   315   004   225   p     o     # n"> <str 3> <defstr 4 "po
i     n     t     317   004   314   224   233   # int"> <str 4> <defreq 0224 "
L     i     g     h     t     S     o     u     # LightSou
r     c     e     246   224   315   005   233   # rce"> <req 0224> <defstr 5 "
w     i     n     d     o     w     l     i     # windowli
g     h     t     317   005   200   001   317   # ght"> <str 5> 1 <str
003   310   003   ?     200   \0    \0    \0    # 3> [1
\0    \0    \0    275   314   314   315   314   # 0 -0.1] <defreq
203   225   C     o     l     o     r     246   # 0203 "Color"> <req
203   310   003   ?     200   \0    \0    ?     # 0203> [1
200   \0    \0    ?     200   \0    \0    314   # 1 1] <defreq
237   233   O     r     i     e     n     t     # 0237 "Orient
a     t     i     o     n     246   237   315   # ation"> <req 0237> <defstr
006   222   l     h     317   006   314   254   # 6 "lh"> <str 6> <defreq 0254
225   S     i     d     e     s     246   254   # "Sides"> <req 0254>
200   001   314   177   236   A     t     t     # 1 <defreq 0177 "Att
r     i     b     u     t     e     B     e     # ributeBe
g     i     n     246   177   314   227   233   # gin"> <req 0177> <defreq 0227 "
M     o     t     i     o     n     B     e     # MotionBe
g     i     n     246   227   310   002   \0    # gin"> <req 0227> [
\0    \0    \0    ?     200   \0    \0    314   # 0 1] <defreq
270   231   T     r     a     n     s     l     # 0270 "Transl
a     t     e     246   270   212   001   353   # ate"> <req 0270> 1.91851
#     211   6     226   212   001   214   314   # 0.213234 1.55
314   260   226   S     p     h     e     r     # <defreq 0260 "Spher
e     246   260   200   002   211   263   4     # e"> <req 0260> 2 -0.3
212   001   363   3     201   \0    257   314   # 1.95 1.75 <defreq
230   231   M     o     t     i     o     n     # 0230 "Motion
E     n     d     246   230   314   200   234   # End"> <req 0230> <defreq 0200 "
A     t     t     r     i     b     u     t     # Attribut
e     E     n     d     246   200               # eEnd"> <req 0200>

Version Number

The RIB stream supports a special version request that is used internally to ensure that the syntax of the stream is compatible with the parser being used.

version num
Specifies the protocol version number of the RIB stream. The stream specified in this document is version 3.03. A RIB parser may refuse to parse streams with incompatible version numbers.

RIB String Handles

The RIB binding for handles associated with Lights, Objects and Archives can be either numbers or strings. When using the RIB client library, unique string handles will be automatically generated by default. In order to override the string handle selected, RiLightSource, RiObjectBegin and RiArchiveBegin now recognize the special string __handleid parameter that may be passed in via the parameter list. The value of this parameter will be used to override the handleid that appears in the RIB binding.

RtString id = "mylight";
RiLightSource("spotlight", "__handleid", &id);

For backwards compatibility, integer handles are supported, and are equivalent to their string representations. Thus, the following RIB statements are equivalent:

LightSource 57 "spotlight"
LightSource "57" "spotlight"

Starting with PRMan 11.5, RtLightHandles and RtObjectHandles can be cast directly to RtStrings in all contexts. In the case of lights, the value of the RtString will be the same as the string handle supplied in RIB (if the light was created that way). In addition, an RtLightHandle can be synthesized from an RtString; the string value (not the blind handle address) will be used to decide which light is illuminated. This is useful for being able to call RiIlluminate on a light in a DSO without requiring the actual RtLightHandle returned from RiLightSource.

Also, when a string value in RI_HANDLEID is passed to RiLightSource in a DSO context, the RtLightHandle returned is guaranteed to have the same string value.


RIB File Structuring Conventions

The RenderMan Interface Bytestream (RIB) is a complete specification of the required interface between modelers and renderers. In a distributed modeling and rendering environment RIB serves well as a rendering file format. As RIB files are passed from one site to another, utilities for shader management, scene editing, and rendering job dispatching (referred to hereafter as Render Managers) can benefit from additional information not strictly required by rendering programs. Additional information relating to User Entities, resource requirements and accounting can be embedded in the RIB file by a modeler through the "proper" use of RIB in conjunction with some simple file structuring conventions.

This section lays out a set of RIB file format conventions which are patterned loosely after the model put forth in Adobe's "Document Structuring Conventions." These conventions are optional in the sense that they are not interpreted by a renderer and thus will not have any effect on the image produced. Although a Render Manager may require conformance to these conventions, it may choose to utilize or ignore any subset of the structural information present in the RIB file. A RIB file is said to be conforming if it observes the Pixar RIB File Structuring Conventions, and the conforming file can be expected to adhere to specific structuring constraints in that case.

These conventions are designed to facilitate communication between modeling/animation systems and network rendering management systems. In a distributed environment many decisions relating to the final appearance of rendered frames may need to be deferred until the selection of a particular renderer can be made. A render management system should provide the ability to tailor the scene to the resources and capabilities of the available rendering and output systems. Unfortunately, a modeling/animation system cannot, in general, assume that any particular render management services are available. The following strategies should thus be adopted with the goal of making a RIB file reasonably self-contained and renderer-independent:

  • Any nonstandard shaders, optional RenderMan features (motion blur, CSG, level of detail) or textures should be flagged as special resource requirements.
  • Renderer-specific options or attributes should be specified according to the special comment conventions described below.
  • Display-dependent RenderMan options should not be included except to indicate to Render Managers that such options are mandatory.

Structural Overview

In order for a Render Manager to perform tasks such as these, incoming RIB files must be predictable and logically structured. The problem of organizing a RIB file falls directly onto the shoulders of the modeler developer and the data structures within his program. The good news is that the modeler can then off-load certain rendering-related tasks downstream. Simply stated, a well-structured RIB file identifies the boundaries of those entities which are, in the mind of the user, logically distinct. Additionally, information pertaining to the resource requirements of the rendering job should be flagged.

Only a few conceptual elements must be provided in the RIB file in order to enable a Render Manager to do its job. Most important in a modeled scene are what we call user entities. The kinds of last minute changes that designers require often involve individual objects in the scene. For example, in order for a designer to assign new wallpaper to the interior walls of a model, the data for the walls must be easily identified in the RIB file. Two commonly employed organizational principles are Geometry and Material Composition.

Geometric Grouping
A user entity based on the geometric principle might be the collection of all primitives (polygons, patches, etc.) that make up a piece of furniture in a house. Because we can gather all of, say, a chair's primitives, it is possible to move and re-orient the chair in space.
Material Grouping
A user entity organized on the principle of material composition might consist of all the primitives representing the parts of a chair that are made of fabric. Another user entity might be all the primitives in the same chair representing the wood. When the designer identifies objects based on this principle, he is usually interested in changing the appearance of the entity. It should be possible to try out many different combinations of woods and fabrics in some render management system. Individual primitives can obviously be members of both the “fabric” grouping and the “chair” grouping. Moreover, we can imagine unrelated geometric entities organized into the same material grouping. Here, the designer may wish to change the fabric on all the chairs and sofas in the living room.
Structural "Blocks"

The strategy promoted herein is quite simple. It suggests that the block structuring mechanisms of the RenderMan Interface are sufficient to encapsulate the geometric and material groupings discussed above. Just as in modern block-structured programming languages, clarity can be enhanced by localizing the scope of requests and variable definitions. Global state should be used sparingly and changes to the global state should only affect known entities. In the RenderMan Interface five kinds of blocks provide these benefits of structured programming and allow the developer to build the logical structure of a modeling database into the RIB file.

Global Block
The global block is the outermost block in the RenderMan Interface. It is bounded by calls to RiBegin and RiEnd. Because a RIB file is bounded by the file boundaries, no specific RIB requests are required to encapsulate this block. Global attributes, options and variable declarations should be located at this level. Because any valid RenderMan requests will affect the default behavior throughout, it is advised to place requests that do not change at this level. For example, if a modeler puts many frames into a single RIB file, it should establish frame resolution, aspect ratio, quantization and global variable declarations in the global block. The alternative would be to specify these things within each frame of the animation. By placing these global declarations in the global block, a Render Manager can effectively change the resolution of the entire animation without parsing through the complete RIB file. The reader is referred to Appendix D for a more detailed discussion on guidelines and restrictions for global attributes and options.
Frame Block
The frame block identifies the individual frames of an animation. All of the information required to render a given frame should either be present in the graphics state (set previously in the global block) or be located within the frame block itself. By using frame blocks, the modeler enables the Render Manager to pull individual frames out of the file and render them independently. The RIB File Structuring Conventions section, below, specifies that any frame-specific global options, attributes and declarations should be set immediately following the FrameBegin request. Thus, a Render Manager need only find a frame block and search the first several RenderMan requests to determine frame block settings. There should be no difficulty in changing any of these settings as the scope of their influence is well defined.
World Block
The world block is provided to encapsulate all of the geometric elements of a particular frame. Any transformations applied externally during the current frame are frozen and associated with the camera. RIB requests that affect every element in a scene should directly follow the WorldBegin request and precede any geometric requests. Typically, global defaults for the graphic state are set here. Global light source requests should generally follow the WorldBegin request and precede any geometry declarations.
Attribute Block

The attribute block is the fundamental block for encapsulating user entities. The geometry and attributes for any object a user can identify should be located in a block of this kind. For example, if a chair is made up of 500 polygons, all of these polygons and any attributes (color, opacity, surface, etc.) that are linked to the chair should be found within this block. If we remove the block from the world or relocate the block in the RIB file, no undesirable effects can occur since any changes within the block are undone at its end. A Render Manager will interpret calls to RiAttributeBegin and RiAttributeEnd as entity delimiters. By tagging an attribute block with an identifier attribute, the modeler establishes an organizational principle for an entity.

Within an attribute block, the structure is simple. All attribute settings should follow immediately after the RiAttributeBegin request. Geometric transformations are considered attributes in the RenderMan Interface and should also precede any geometry. Depending on the internal architecture of the modeling software, user entities may be described around a local origin. In this case, a modeling transformation commonly transforms the entity from object space to world space. If this is not the case, the modeler will probably be working entirely in world space and no modeling transform will be present.

After setting all of the attributes for the entity, the geometry should immediately follow. Appendix D identifies two special identifier attributes to allow the modeler to tag a user entity with a name. These calls are invoked as follows:

RiAttribute("identifier","name",
             (RtPointer) &objectname,RI_NULL);
RiAttribute("identifier","shadinggroup",
             (RtPointer) &shadinggroupname,RI_NULL);

Because the modeler tags all entity blocks with an identifier, a Render Manager can differentiate between collections of geometry that are organized according to a geometric relationship (like all the primitives of the chair) and geometry organized by a material relationship (like all the primitives made of fabric). To allow for hierarchically defined models, attribute blocks may be arbitrarily nested.

Transform Block
Because geometric transformations are considered attributes by the RenderMan Interface, the transform block is a weaker form of the attribute block. Since transform blocks do not protect the global state from changes to appearance attributes, they cannot be used to identify user entities. They still play a useful function in hierarchical models.

Components

Following is a structured list of components for a conforming RIB file that diagrams the "proper" use of RIB. Some of the components are optional and will depend greatly on the resource requirements of a given scene.

Scope

Indentation indicates the scope of the following command.

 Preamble and global variable declarations (RIB requests: version, declare)

 Static options and default attributes (image and display options, camera options)

 Static camera transformations (camera location and orientation)

 Frame block (if more than one frame)

     Frame-specific variable declarations

     Variable options and default attributes

     Variable camera transforms

     World block

       (scene description)

       User Entity (enclosed within AttributeBegin/AttributeEnd)

       User Entity (enclosed within AttributeBegin/AttributeEnd)

       User Entity

 more frame blocks

This structure results from the vigorous application of the following Scoping Conventions:

  • No attribute inheritance should be assumed unless implicit in the definition of the User Entity (i.e., within a hierarchy).
  • No attribute should be exported except to establish either global or local defaults.

The RenderMan Specification provides block structuring to organize the components of a RIB file. Although the use of blocks is only required for frame and world constructs by the Specification, the liberal use of attribute and transform blocks is encouraged. A modeler enables a Render Manager to freely manipulate, rearrange, or delete scene elements (frames, cameras, lights, User Entities) by carefully bounding these elements in the RIB file according to scope. A Render Manager might, for example, strip all of the frames out of a RIB file and distribute them around a network of rendering servers. This, of course, is only possible if the RIB file has been structured in such a way as to bound those things pertaining to a given frame within its frame block and those things pertaining to all frames outside and before all frame blocks.

User Entities

A User Entity couples a collection of geometric primitives and/or User Entities with shading and geometric attributes. As such it introduces a level of scope that is more local than that implied by the RenderMan world block. Typically, the term User Entity refers to a geometric element within a scene whose attributes or position a user may wish to modify or tweak. Because there is some computational expense associated with attribute block structuring, there is an intrinsic trade-off between control over individual User Entities and rendering time/memory requirements. At one extreme, the entire scene is made up of one User Entity within one attribute block. At the other extreme, each polygon is a User Entity and the renderer is forced to spend most of its time managing the graphics state. Modeling programs and their users may wish to carefully weigh this trade-off.

The Scoping Conventions above prescribe the following User Entity Conventions:

  • All User Entities must be delimited by an attribute block.
  • All User Entities must have an identifier attribute that uniquely characterizes that Entity to the user. Two special identifier attributes are provided to distinguish between Entities organized by a geometric relationship (the name identifier) and Entities organized according to material makeup (the shadinggroup identifier).
  • A User Entity must be completely described within its attribute block.
Nonportable options and attributes

The following list of RIB requests are restricted as they either limit the device independence of the file or they control rendering quality or speed parameters. Render managers should provide this kind of control to users at render time. The inclusion of these restricted requests by a modeler should indicate to a Render Manager that they are, in some sense, mandatory. When including nonportable options or attributes in the RIB file, they should be located contiguously (according to scope) in a RIB file.

 Attribute
 ColorSamples
 CropWindow
 Exposure
 Format
 FrameAspectRatio
 Imager
 Option
 PixelFilter
 PixelSamples
 PixelVariance
 Quantize
 ShadingRate

Conventions for structural hints

The ## character sequence is used to designate structural hints. Any characters found after these special characters and before the next newline character are construed as special hints intended for Render Managers. Such hints should conform to the conventions outlined herein and should provide structural, resource, or administrative information which cannot easily be incorporated into or derived from the standard RIB stream. The same scoping considerations which apply to RIB should also be applied toward special comments.

Header information

Header information must be located immediately beginning any conforming RIB file. These hints should provide scene-global administrative and resource information. Header entries should precede any RIB requests and must be contiguous. If a header entry appears twice in a file, the first occurrence should be considered to be the true value.

##RenderMan RIB-Structure 1.1 [ keyword ]
This entry should be the first line in a conforming RIB file. Its inclusion indicates full conformance to these specifications. The addition of the special keyword, Entity, specifies that the file conforms to the User Entity conventions described in the RIB Entity Files section.
##Scene name
This entry allows a scene name to be associated with the RIB file.
##Creator name
Indicates the file creator (usually the name of the modeling or animation software).
##CreationDate time
Indicates the time that the file was created. It is expressed as a string of characters and may be in any format.
##For name
Indicates the user name or user identifier (network address) of the individual for whom the frames are intended.
##Frames number
Indicates the number of frames present in the file.
##Shaders shader1, shader2, ...
Indicates the names of nonstandard shaders required. When placed in the header of a RIB file, any nonstandard shaders that appear in the entire file should be listed. When placed within a frame block, any nonstandard shaders that appear in that frame must be listed.
##Textures texture1, texture2, ...
Lists any preexisting textures required in the file. When placed in the header of a RIB file, any preexisting textures that appear anywhere in the file should be listed. When placed within a frame block, any preexisting shaders that appear in that frame must be listed.
##CapabilitiesNeeded feature1, feature2, ...

Indicates any RenderMan Interface optional capabilites required in the file (when located in the header) or required in the frame (when located at the top of a frame block). The optional capabilities are:

Area Light Sources Motion Blur Special Camera Projections
Bump Mapping Programmable Shading Spectral Colors
Deformations Radiosity Texture Mapping
Displacements Ray Tracing Trim Curves
Environment Mapping Shadow Depth Mapping Volume Shading
Level Of Detail Solid Modeling

See the RenderMan Interface documentation for a description of these capabilities.

Frame information

Frame-local information must be located directly after a FrameBegin RIB request and be contiguous. These comments should provide frame-local information that contains administrative and resource hints

##CameraOrientation eyex eyey eyez atx aty atz [ upx upy upz ]
Indicates the location and orientation of the camera for the current frame in World Space coordinates. The up vector is optional and the default value is [0 1 0].
##Shaders shader1, shader2, ...
Lists the nonstandard shaders required in the current frame.
##Textures texture1, texture2, ...
Lists the nonstandard textures required in the current frame.
##CapabilitiesNeeded feature1, feature2, ...
Lists the special capabilities required in the current frame from among those listed under Header Information.
Body Information

Body information may be located anywhere in the RIB file.

##Include filename
This entry allows the specification of a file name for inclusion in the RIB stream. Note that the Include keyword itself does not cause the inclusion of the specified file. As with all structural hints, the Include keyword serves only as a special hint for render management systems. As such, the Include keyword should only be used if render management facilities are known to exist.

RIB File structuring example

##RenderMan RIB-Structure 1.1
##Scene Bouncing Ball
##Creator /usr/ucb/vi
##CreationDate 12:30pm 8/24/89
##For RenderMan Jones
##Frames 2
##Shaders PIXARmarble, PIXARwood, MyUserShader
##CapabilitiesNeeded ShadingLanguage Displacements
version 3.03
Declare "d" "uniform point"
Declare "squish" "uniform float"
Option "limits" "bucketsize" [6 6]  #renderer specific
Option "limits" "gridsize" [18]  #renderer specific
Format 1024 768 1  #mandatory resolution
Projection "perspective"
Clipping 10 1000.0
FrameBegin 1
##Shaders MyUserShader, PIXARmarble, PIXARwood
##CameraOrientation 10.0 10.0 10.0 0.0 0.0 0.0
Transform  [.707107  -.408248  -.57735 0
            0  .816497  -.57735  0
            -.707107  -.408248  -.57735  0
            0  0  17.3205  1 ]
WorldBegin
AttributeBegin
Attribute "identifier" "name" "myball"
Displacement "MyUserShader" "squish" 5
AttributeBegin
Attribute "identifier" "shadinggroup" ["tophalf"]
Surface "PIXARmarble"
Sphere .5 0 .5 360
AttributeEnd
AttributeBegin
Attribute "identifier" "shadinggroup" ["bothalf"]
Surface "plastic"
Sphere .5 -.5 0. 360
AttributeEnd
AttributeEnd
AttributeBegin
Attribute "identifier" "name" ["floor"]
Surface "PIXARwood" "roughness" [.3] "d" [1]
# geometry for floor
Polygon "P" [-100. 0. -100.  -100. 0. 100.  100. 0. 100.  10.0 0. -100.]
AttributeEnd
WorldEnd
FrameEnd
FrameBegin 2
##Shaders PIXARwood, PIXARmarble
##CameraOrientation 10.0 20.0 10.0 0.0 0.0 0.0
Transform [.707107  -.57735  -.408248  0
           0   .57735
           -.815447 0
           -.707107  -.57735  -.408248  0
           0  0  24.4949 1 ]
WorldBegin
AttributeBegin
Attribute "identifier" "name" ["myball"]
AttributeBegin
Attribute "identifier" "shadinggroup" ["tophalf"]
Surface "PIXARmarble"
ShadingRate .1
Sphere .5 0 .5 360
AttributeEnd
AttributeBegin
Attribute "identifier" "shadinggroup" ["bothalf"]
Surface "plastic"
Sphere .5 -.5 0 360
AttributeEnd
AttributeEnd
AttributeBegin
Attribute "identifier" "name" ["floor"]
Surface "PIXARwood" "roughness" [.3] "d" [1]
# geometry for floor
AttributeEnd
WorldEnd
FrameEnd

RIB Entity Files

A RIB Entity File contains a single User Entity. RIB Entity Files are incomplete since they do not contain enough information to describe a frame to a renderer. RIB Entity Files depend on Render Management services for integration into "legal," or complete, RIB Files. These files provide the mechanism for 3-D "clip-art" by allowing Render Managers to insert objects into preexisting scenes.

RIB Entity Files must conform to the User Entity Conventions described in the User Entities section. To summarize, a User Entity must be delimited by an attribute block, must have a name attribute, and must be completely contained within a single attribute block. Three additional requirements must also be met:

  • The header hint: ##RenderMan RIB-Structure 1.1 Entity must be included as the first line of the file.
  • The Entity must be built in an object coordinate system which is centered about the origin.
  • The Entity must have a RIB bound request to provide a single bounding box of all geometric primitives in the User Entity

RIB Entity File example

##RenderMan RIB-Structure 1.1 Entity
AttributeBegin  #begin unit cube
Attribute "identifier" "name" "unitcube"
Bound -.5 .5 -.5 .5 -.5 .5
TransformBegin
# far face
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
Rotate 90  0 1 0
# right face
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
# near face
Rotate 90  0 1 0
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
# left face
Rotate 90  0 1 0
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
TransformEnd
TransformBegin
# bottom face
Rotate 90  1 0 0
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
TransformEnd
TransformBegin
# top face
Rotate -90  1 0 0
Polygon "P" [.5 .5 .5  -.5 .5 .5  -.5 -.5 .5  .5 -.5 .5]
TransformEnd
AttributeEnd  #end unit cube

RenderMan Renderer Resource Files

Renderer Resource Files are intended to provide information to Render Managers and modelers about the specific features, attributes, options, and resources of a particular renderer. In an environment where multiple renderers are available, a Render Manager can provide the user with the ability to tailor RIB file to best suit the desired renderer.

Renderer Resource Files should be shipped with any RenderMan renderer and should be updated on-site by the local system administrator to reflect the resources available to a renderer. Only those sections containing site-specific information can be customized in this way. The simple ASCII format of Renderer Resource Files makes them easy to read, modify and parse.

Format of Renderer Resource Files

A Renderer Resource File is broken up into a series of sections delimited by special keywords. Within each section, all related information is provided using a section-specific predefined format. A special include keyword is provided to simplify the task of customizing Resource Files. The keywords are as follows:

##RenderMan Resource-1.0
Must be included as the first line in any Renderer Resource File.
##Renderer name
Requires the name of the renderer along with any revision or date information.
##Include file
Allows the inclusion of a specified file. This keyword should only be used in sections which are modifiable.
##RenderManCapabilitiesAvailable
This keyword identifies the section enumerating the Capabilities provided by the renderer. The list of capabilities are found in the Header information section and in the RenderMan Interface documentation. Each capability implemented by the renderer must appear as one line in this section. No entries in this section should be modified.
##RendererSpecificAttributes
This keyword identifies the section which enumerates the Renderer Specific Attributes. These attributes are invoked with the RIB call Attribute. Each attribute implemented by the renderer must appear as one line in this section with legal RIB syntax. The class of all parameter identifiers must be declared previously with a Declare RIB request. If arguments are required for a given attribute, the entry should specify the default value for that attribute. No entries in this section should be modified.
##RendererSpecificOptions
This keyword identifies the section which enumerates Renderer Specific Options. These attributes are invoked with the RIB call Option. Each option implemented by the renderer must appear as one line in this section with legal RIB syntax. The class of all parameter identifiers must be declared previously with a Declare RIB request. No entries in this section should be modified.
##ShaderResources
This keyword identifies the section which enumerates Shaders available to the renderer. Both built-in and programmed shaders should be listed here. A RenderMan Shading Language declaration for each shader must be provided to enumerate the specific instantiated variables. A declaration may cross line boundaries. This section can be customized to a specific site.
##TextureResources
This keyword identifies the section which enumerates the Textures available to the renderer. The name of each texture may be followed on the same line by an optional string which provides a short description of the Texture. If included, the string should be preceded by the # character. This section can be customized to a specific site.

Renderer Resource File example

##RenderMan Resource-1.0
##Renderer TrayRacer 1.0
##RenderManCapabilitiesAvailable
Solid Modeling
Motion Blur
Programmable Shading
Displacements
Bump Mapping
Texture Mapping
Ray Tracing
Environment Mapping
##RendererSpecificAttributes
Declare "refractionindex" "uniform float"
Declare "displacement" "uniform float"
Attribute "volume" "refractionindex" [1.0]
Attribute "bound" "displacement" 3.5
##RendererSpecificOptions
Declare "bucketsize" "uniform integer[2]"
Declare "texturememory" "uniform integer"
Declare "shader" "string"
Declare "texture" "string"
Option "limits" "bucketsize" [12 12]
Option "limits" "texturememory" 1024
Option "searchpath" "shader" "/usr/local/prman/shaders"
Option "searchpath" "texture" "/usr/local/prman/textures"
##ShaderResources
surface wood(
              float ringscale = 10;
              color lightwood = color(.3, .12, 0.0);
              darkwood = color(.05, .01, .005);
              float   Ka =.2,
                      Kd =.4,
                      Ks  =.6,
                      roughness =.1)
displacement dented(float Km = 1.0)
light slideprojector (
              float fieldofview=PI/32;
              point from = {8,-4,10), to = {0,0,0), up = point "eye" (0,1,0);
              string slidename = "" )
##Include othershaderfile
##TextureResources
brick
bluebrick
grass #kentucky bluegrass-1 square meter
moss  #spanish moss
logo
##Include othertexturefile

Error handling

There are two types of errors that may be encountered while processing a RIB input stream: syntactic errors and semantic errors. Syntactic errors occur when the stream of tokens fails to form a syntactically legal statement or request. For example, a syntactic error occurs when a required parameter is missing, or when a string is left unterminated. Semantic errors occur when a syntactically legal statement contains incorrect data; e.g., when a parameter that must be non-negative is specified to be -1.

RIB defines a number of syntactic errors and a limited number of semantic errors. In theory RIB should be responsible only for syntactic errors. However, due to the weak typing of programming languages such as C, semantic errors that can not be easily recognized within the RenderMan Interface software are checked at the RIB level. For example, RIB checks arrays that are to be converted to matrices to be sure they have 16 values.

The set of errors recognized by RIB are listed below.

All errors encountered by a RIB interpreter require some associated action to be performed. In the case of syntax errors, if input processing is to be continued, the input scanner must resynchronize itself with the input stream. This synchronization is done by reading and discarding tokens from the input stream until a valid RIB request token is encountered. That is, any tokens between the point of the syntax error and the next request token are discarded. The protocol has been designed so that no more than one request (along with any associated parameters) must be discarded when recovering from an error.

Errors are handled in one of three ways:

  • They are ignored and the rendering process will proceed to its completion no matter what input stream is provided.
  • They cause diagnostic messages to be generated on the renderer's standard error stream, but they are otherwise ignored (the default).
  • The first error causes a diagnostic message to be generated and the renderer terminates immediately without creating an image.

If the RIB interpreter is acting as a network server, in direct communication with a client application, the interpreter may send parsing error signals back to the client. These signals take the form of the following RIB requests, though they are not valid in the client-to-server stream. None of these error requests have arguments. Note that some errors may not be recognized immediately by a RIB interpreter upon parsing a request. This may be due to buffering or queuing built into the interface between the intepreter and the renderer. In a client-server environment this may have implications for the client application.

arraytoobig
The interpreter was unable to allocate sufficient memory to store an array specified in the input stream. This error is dependent on the interpreter's implementation. Good implementations of a RIB interpreter support arrays as large as memory will permit.
badargument

The RIB interpreter encountered an invalid parameter value in parsing a request.

EXAMPLE

Polygon "N" [...]            # no "P" specified
PointsGeneralPolygons [2 2] [4 3 4]...    # bad nloops
badarray

The number of items in an array is inappropriate for the specified parameter, or an array has both string and number elements.

EXAMPLE

Basis [0 1 2 3] Cone [1.5] Bound [0 1 0 "oops"]
badbasis

The basis matrix name specified in a basis request is not known by the RIB interpreter.

EXAMPLE

Basis "my-favorite-basis"
badcolor

An invalid color was supplied as a parameter to a request. That is, an array was specified with an incorrect number of elements.

EXAMPLE

Opacity [.5 1]        # with 3-channel colors
badhandle

An invalid light, object or archive handle was supplied as a parameter to an Illuminate, ObjectInstance, LightSource, AreaLightSource, ArchiveBegin, or ObjectBegin request. For Illuminate, the light handle must be an integer or string value specified in a previous LightSource or AreaLightSource request. For ObjectInstance, the object handle must be an integer or string value specified in a previous ObjectBegin request. For LightSource, AreaLightSource, and ObjectBegin this error is raised if the integer number specified for a light handle is significantly larger than any previous handle; for example, specifying 3000 when the largest previous handle was 10 (this is used as a "sanity check" to guard against corrupted input data.)

EXAMPLE

LightSource "finite" 1
Illuminate 99999
badparamlist

In a token-value pair of a parameter list, the type of a value did not agree with the declared type of the token.

EXAMPLE

Declare "gridsize" "uniform float[2]"
Option "limits" "gridsize" "not a number"
badripcode
A binary encoded token that specified a RIB request used an undefined request code. Request codes must be defined, prior to their use, with the binary encoding protocol; see the section on Binary Encoding.
badstringtoken
A binary encoded string token referenced a string that had not previously been defined. The binary encoding scheme is described in Binary encoding.
badtoken

A byte with the most significant bit set was not recognized as a valid binary encoding. The binary encoding scheme is described in Binary encoding.

EXAMPLE

300
badversion

The RIB protocol version number specified in a version request was greater than the protocol version number of the interpreter.

SEE ALSO

version

limitcheck
An internal limit was encountered during normal operation of the interpreter. Implementers of RIB interpreters are expected to avoid imposing arbitrary limits. Some implementations may, however, need to limit the maximum size of strings, arrays, etc. due to memory constraints.
outofmemory
The interpreter ran out of memory in the normal course of operation. Interpreters are expected to utilize whatever memory is available in their operating environment. If only a limited amount of memory is present on the machine they are operating on, they may restrict their use. If memory is arbitrarily limited, however, running out of space should result in a limitcheck error, not outofmemory.
protocolbotch
A protocol error was encountered while parsing binary encoded data in the input stream. In particular, when defining a string or request code, an expected string was not encountered. The binary encoding scheme is described in Binary encoding.
stringtoobig

The interpreter ran out of space while parsing a string. This error is a specific instance of the outofmemory error.

SEE ALSO

outofmemory, limitcheck

syntaxerror

The interpreter recognized a syntax error of indeterminate nature. Syntax errors can occur from unterminated strings or invalid numbers.

EXAMPLE

"this is an unterminated string
01a3    # invalid integer
unregistered

The interpreter encountered a name token that was not a valid request. This is usually due to misspelling a request name, or not enclosing a string in quotation marks (").

EXAMPLE

Basis power