RIB.TXT

RIB.TXT


Remove Frame

The RenderMan Interface
Bytestream Protocol
File Format
Pixar
June, 1990

The Purpose of the RenderMan Interface

The RenderMan Interface is a standard interface between modeling programs 
and rendering programs capable of producing photorealistic quality images. 
A rendering program implementing the RenderMan Interface differs from 
an implementation of earlier graphics standards in that:

o  A photorealistic rendering program must simulate a 
real camera and its many attributes besides just position and 
direction of view. High quality implies that the simulation does not 
introduce artifacts from the computational process. Expressed in 
the terminology of computer graphics, this means that a photorealistic 
rendering program must be capable of:

-  hidden surface removal so that only visible objects appear 
   in the computed image,
-  spatial filtering so that aliasing artifacts are not present,
-  dithering so that quantization artifacts are not noticeable,
-  temporal filtering so that the opening and closing of the 
   shutter causes moving objects to be blurred,
-  and depth of field so that only objects at the current focal 
   distance are sharply in focus.

o  A photorealistic rendering program must also accept curved geometric 
primitives so that not only can geometry be accurately displayed, 
but also so that the basic shapes are rich enough to include the 
diversity of man-made and natural objects. This requires patches, 
quadrics, and representations of solids, as well as the ability 
to deal with complicated scenes containing on the order of 10,000 
to 1,000,000 geometric primitives.

o  A photorealistic rendering program must be capable of 
simulating the optical properties of different materials and 
light sources. This includes surface shading models that describe 
how light interacts with a surface made of a given material,
 volume shading models that describe how light is scattered as 
it traverses a region in space, and light source models that 
describe the color and intensity of light emitted in different 
directions. Achieving greater realism often requires that the surface 
properties of an object vary. These properties are often controlled 
by texture mapping an image onto a surface. Texture maps are 
used in many different ways: direct image mapping to change the 
surface's color, transparency mapping, bump mapping for changing 
its normal vector, displacement mapping for modifying position, environment 
or reflection mapping for efficiently calculating global illumination, 
and shadow maps for simulating the presence of shadows.

The RenderMan Interface is designed so that the information needed 
to specify a photorealistic image can be passed to different rendering 
programs compactly and efficiently. The interface itself is designed to 
drive different hardware devices, software implementations and rendering 
algorithms. Many types of rendering systems are accommodated by 
this interface, including z-buffer-based, scanline-based, ray 
tracing, terrain rendering, molecule or sphere rendering and the Reyes 
rendering architecture. In order to achieve this, the interface does 
not specify how a picture is rendered, but instead specifies what picture is 
desired. The interface is designed to be used by both batch-oriented 
and real-time interactive rendering systems. Real-time rendering 
is accommodated by ensuring that all the information needed to draw a 
particular geometric primitive is available when the primitive is 
defined. Both batch and real-time rendering is accommodated by making 
limited use of inquiry functions and call-backs.

The RenderMan Interface is meant to be complete, but minimal, 
in its transfer of scene descriptions from modeling programs to rendering 
programs. The interface usually provides only a single way to 
communicate a parameter; it is expected that the modeling front 
end will provide other convenient variations. An example is color 
coordinate systems - the RenderMan Interface supports multiple-
component color models because a rendering program intrinsically computes 
with an n-component color model. However, the RenderMan Interface 
does not support all color coordinate systems because there are 
so many and because they must normally be immediately converted to 
the color representation used by the rendering program. Another 
example is geometric primitives - the primitives defined by the RenderMan 
Interface are considered to be rendering primitives, not modeling 
primitives. The primitives were chosen either because special graphics 
algorithms or hardware is available to draw those primitives, or because 
they allow for a compact representation of a large database. 
The task of converting higher-level modeling primitives to rendering 
primitives must be done by the modeling program.

The RenderMan Interface is not designed to be a complete three-
dimensional interactive programming environment. Such an environment 
would include many capabilities not addressed in this interface. These 
include: 1) screen space or two-dimensional primitives such as 
annotation text, markers, and 2-D lines and curves, 2) non-surface 
primitives such as 3-D lines and curves, and 3) user-interface 
issues such as window systems, input devices, events, selecting, 
highlighting, and incremental redisplay.

The RenderMan Interface is a collection of procedures to transfer 
the description of a scene to the rendering program. A rendering 
program takes this input and produces an image. This image can be 
immediately displayed on a given display device or saved in an image 
file. The output image may contain color as well as coverage and 
depth information for postprocessing. Image files are also used to input 
texture maps. This document does not specify a "standard format" 
for image files.

The RenderMan Shading Language is a programming language for 
extending the predefined functionality of the RenderMan Interface. 
New materials and light sources can be created using this language. This 
language is also used to specify deformations, special camera projections, 
and simple image processing functions. All required shading functionality 
is also expressed in this language. A shading language is an 
essential part of a high-quality rendering program. No single 
material lighting equation can ever hope to model the complexity 
of all possible material models. The RenderMan Shading Language is described in 
Part II of the RenderMan Interface Specification.

The Relationship of This Document To Other Documents

This document is a summary of the syntax and semantics of RenderMan 
Interface Bytestream Protocol, as described in The RenderMan Interface, 
Version 3.1, published by Pixar in September, 1989. The 
RenderMan Interface Specification is a complete technical description 
of RenderMan, the procedural RenderMan Interface, the RenderMan 
Interface Bytestream ("RIB") Protocol, and the RenderMan Shading 
Language, and is the official reference for all information relevant 
to the RenderMan Interface. The RenderMan Interface Specification is 
available from Pixar. The RenderMan Companion: A Programmer's Guide 
to Realistic Computer Graphics, by Steve Upstill (Addison-Wesley, 
1989) describes in a more gentle manner the semantics of the 
procedural RenderMan Interface, but does not include a 
direct discussion of the equivalent RIB requests.

The Semantics of the RenderMan Interface

The RenderMan Interface is similar to other graphics packages in 
that it maintains a graphics state. The graphics state contains all 
the information needed to render a geometric primitive. RenderMan Interface 
commands either change the graphics state or render a geometric primitive. 
The graphics state is divided into two parts: a global state that 
remains constant while rendering a single image or frame of a sequence, 
and a current state that changes from geometric primitive to 
geometric primitive. Parameters in the global state are referred 
to as options, whereas parameters in the current state are 
referred to as attributes. 

Options include the camera and display parameters, and other 
parameters that affect the quality or type of rendering in general 
(e.g., global level of detail, number of color samples, etc.). 
Attributes include the parameters controlling appearance or 
shading (e.g., color, opacity, surface shading model, light sources, 
etc.), how geometry is interpreted (e.g., orientation, subdivision 
level, bounding box, etc.), and the current modeling matrix. 
To aid in specifying hierarchical models, the attributes in the 
graphics state may be pushed and popped on a graphics state stack. 
The graphics state also maintains the interface mode. The 
different modes of the interface are entered and exited by matching 
Begin-End command sequences.  The current transformation is 
maintained as part of the graphics state. Commands exist to set and to 
concatenate specific transformations onto the current transformation. 
These include the basic linear transformations translation, 
rotation, skew, scale and perspective. Concatenating transformations 
implies that the current transformation is updated in such a way 
that the new transformation is applied to points before the 
old current transformation. Standard linear transformations are 
given by 4x4 matrices. These matrices are premultiplied by 
4-vectors in row format to transform them.  

The RenderMan Interface supports surface- and solid-defining 
geometric primitives and some non-surface-defining drawing 
primitives. Solid primitives are created from surfaces and combined using set 
operations. The geometric primitives include: 

o  planar convex polygons,
o  general planar concave polygons with holes,
o  collections of planar convex or general planar concave polygons 
   with holes which share vertices (polyhedra),
o  bilinear patches and patch meshes,
o  bicubic patches and patch meshes with arbitrary basis,
o  non-uniform rational B-spline surfaces of arbitrary degree (NURBS),
o  quadric surfaces, tori and disks.

Points are used to construct polygons, patches and NURBS. Point 
positions can be either an (x,y,z) triplet ("P") or an (x,y,z,w) 
4-vector ("Pw"). If the vertex is part of a patch mesh, the 
position may be used to define a height field. In this case the 
vertex point contains only a (z) coordinate ("Pz"), and the (x,y)s of 
points of the height field are set equal to the parametric surface 
parameters of the mesh. All primitives have well-defined geometric 
surface normals, so normals need not be provided with any 
primitive. The surface normal for a polygon is the perpendicular 
to the plane containing the polygon. The surface normal for a 
parametric curved surface is computed by taking the cross product of 
the surface's parametric derivatives: (dP/du)x(dP/dv).
The geometric plane normal of a polygon or bilinear patch can be 
supplied explicitly ("Np"), in which case that normal is used, 
and the normals are not computed. It is also possible to provide additional 
shading normals ("N") at polygon and bilinear patch vertices to 
help make the surface appear smooth. 

All primitives have well-defined two-dimensional surface parameters. 
All the points on the surface of each primitive are functions of 
these parameters (u,v). Except for NURBS and polygons, the domain of the 
surface parameters is the unit square from 0 to 1. Texture coordinates may 
be attached to primitives by assigning four sets of texture coordinates, 
one set to each corner of this unit square. This is done by setting 
the current set of texture coordinates or by defining texture coordinates 
with the geometric primitives as described below.
 
All geometric primitives normally inherit their color and opacity from 
the graphics state. However, explicit colors and opacities can be 
provided when defining the primitive ("Cs" and "Os"). Associated with 
each geometric primitive definition are additional primitive variables that 
are passed to their shaders. These variables may define quantities 
that are constant over the surface (class uniform), or are bilinearly 
interpolated (class varying). If the primitive variable is uniform, 
there is one value per surface facet. If the primitive variable is varying,
there are four values per surface facet, one for each corner of the 
unit square in parameter space (except polygons, which are a special 
case). On parametric primitives (quadrics and patches), varying 
primitive variables are bilinearly interpolated across the surface 
of the primitive. Colors, opacities, and shading normals are all 
examples of varying primitive variables. 

The Syntax of RenderMan Interface Bytestream Protocol

The RenderMan Interface Bytestream Protocol, abbreviated RIB, is a 
byte-oriented protocol for specifying requests to a RenderMan-
compatible image rendering program. RIB permits clients of RenderMan 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 

o  an understandable (potentially) interactive interface to a 
   rendering server, and 
o  a compact encoded format that minimizes transmission time (and 
   space when stored 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 a 
RIB description, with an associated savings in communication overhead 
and/or file storage cost. The binary version of RIB is not discussed 
in this document, but is detailed in Appendix C of Pixar's The 
RenderMan Interface, Version 3.1.

RIB syntax rules 

RenderMan Interface Bytestream 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. Some 
application programs which use RIB archives may parse and act 
on comments and structure comments, as defined in Appendix D of 
The RenderMan Interface, "RenderMan Interface Bytestream 
Conventions". All comments are ignored when they are encountered by 
the RIB 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. 
Integers are automatically converted to reals, if necessary.

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. 

Parameterlists 

Many RIB requests described below include a parameter known as a 
parameterlist. parameterlist is short-hand notation for an optional, 
arbitrary length list of name-value pairs, which provide optional, 
extensible information associated with the request. The name is always 
a quoted string, which is either predefined by RenderMan, or has 
been defined in the RIB stream with the use of a Declare request. 
The value is always an array (as described above), whose semantics 
are determined by the name and its declaration.

Alphabetical Listing of All RenderMan Interface Requests

This section lists all the RenderMan Interface Bytestream requests 
alphabetically. Each request includes syntax information, and is 
followed by one or more examples and page references to Pixar's The 
RenderMan Interface, Version 3.1 (September 1989) and to The 
RenderMan Companion: A Programmer's Guide to Realistic Computer 
Graphics, by Steve Upstill (Addison-Wesley, 1989). Spec refers 
to the former, and Book to the latter.

# anything
##variousthings

The # character begins a comment, which continues until the end of line. 
Two # characters at the beginning of a line indicate a special comment 
known as a Structure Comment, which is used to document various 
features of the RIB file. The set of standard Structure Comments 
is described in Appendix D of the Spec.

EXAMPLES:
# This is a comment.
##CapabilitiesNeeded ProgrammableShading

AreaLightSource name serialnumber parameterlist

Begins the definition of an area light source. name is the name 
of a light shader programmed in the RenderMan Shading Language. 
Light sources each have an integer serialnumber which can be used later 
in Illuminate requests. Subsequent geometry will become part of 
this area light source. See page 41 of the Spec and page 225 of the Book.

EXAMPLES:
AreaLightSource "finitelight" 1 "decayexponent" [.5]
AreaLightSource "glowlight" 2 "color" [.5 0 0] "intensity" [.6]

Atmosphere name parameterlist

Sets the current atmosphere shader attribute. name is the name of 
an atmosphere shader programmed in the RenderMan Shading Language. 
See page 44 of the Spec and page 235 of the Book.

EXAMPLE:
Atmosphere "fog" "background" [.2 .2 .3] "distance" [39.4]

Attribute name parameterlist

Sets any additional implementation-specific attributes of the rendering 
program which control parameters that affect primitive appearance 
or interpretation. See page 58 of the Spec and page 46 of the Book.

EXAMPLE:
Attribute "displacementbound" "sphere" [2.0]

AttributeBegin

Push the current set of attributes onto the attribute stack. Pushing 
attributes also pushes the current transformation. See page 36 of 
the Spec and page 50 of the Book.

EXAMPLE:
AttributeBegin

AttributeEnd

Pop the current set of attributes from the attribute stack. Popping 
attributes also pops the current transformation. See page 36 of 
the Spec and page 50 of the Book.

EXAMPLE:
AttributeEnd

Basis uname ustep vname vstep
Basis uname ustep vbasis vstep
Basis ubasis ustep vname vstep
Basis ubasis ustep vbasis vstep

Set the current u-basis attribute to ubasis and the current v-basis 
attribute to vbasis. For each basis, either the name of a predefined 
basis (as a string) or a matrix may be supplied. If a basis name 
specified, it must be one of: "bezier", "b-spline", "catmull-rom", 
"hermite", or "power". See page 65 of the Spec and page 93 of the Book.

EXAMPLE:
Basis "catmull-rom" 1 "catmull-rom" 1

Bound xmin xmax ymin ymax zmin zmax

The bounding box is specified in the current object coordinate system. 
Subsequent geometric primitives should all lie within this bounding 
box. See page 47 of the Spec and page 125 of the Book.

EXAMPLE:
Bound 0 .5 0 .5 .9 1

Clipping near far

Sets the position of the near and far clipping planes along the 
direction of view. See page 25 of the Spec and page 145 of the Book.

EXAMPLE:
Clipping .1 1000

Color color

Set the current color attribute to color. Normally there are 
three components in the color (red, green, and blue), but this may 
be changed with ColorSamples. See page 37 of the Spec and page 213 of the Book.

EXAMPLE:
Color [.2 .3 .9]

ColorSamples n2RGB RGB2n

This function controls the number of color components or samples 
to be used in specifying colors, and the matrices to transform 
between the new color space and RGB. By default, three component RGB color 
values are used. See page 34 of the Spec and page 43 of the Book.

EXAMPLE:

ColorSamples [1 1 1 .956 -.272 -1.108 .620 -.647 1.705] 
[.299 .596 .212 .587 -.275 -.528 .144 -.321 .311]

ConcatTransform transform

Concatenate the transformation matrix transform onto the current 
transformation. The transformation is applied before all previously 
applied transformations, that is, before the current transformation. See 
page 53 of the Spec and page 116 of the Book.

EXAMPLE:
ConcatTransform [2 0 0 0 0 2 0 0 0 0 2 0 0 0 0 1]

Cone height radius thetamax parameterlist

Creates a cone, as seen in Figure 1. See 73 of the Spec and page 
62 of the Book.

EXAMPLE:
Cone .5 .5 270 "Cs" [1 0 0 1 1 1 1 0 0 1 1 1]

CoordinateSystem space

This function marks the coordinate system defined by the current 
transformation with the name space and saves it. This coordinate 
system can then be referred to by name in subsequent shaders. See 
page 57 of the Spec and page 123 of the Book.

EXAMPLE:
CoordinateSystem "Endor"

CropWindow xmin xmax ymin ymax

Render only a subrectangle of the image, as seen in Figure 3. 
See page 24 of the Spec and page 162 of the Book.

EXAMPLE:
CropWindow 0 .3 0 .5

Cylinder radius zmin zmax thetamax parameterlist

Creates a cylinder, as seen in Figure 1. See page 74 of the Spec 
and page 62 of the Book.

EXAMPLE:
Cylinder .5 .2 1 360

Declare name declaration

Declare the name and type of a parameterlist variable. The 
declaration indicates the size and semantics of values associated 
with the variable. The syntax of declaration is: 

[class] type [ �[� n �]� ]

where class is either uniform (the default) or varying (only 
required for primitive variables) and type is float, point, 
color, integer, or string. The optional bracket notation indicates an 
array of n items of type, where n is a positive integer. If no 
array is specified, one item is assumed. See page 13 of the Spec and 
page 242 of the Book.

EXAMPLE:
Declare "centerpoint" "uniform point"

Deformation name parameterlist

Concatenate the named transformation onto the current transformation. 
name is the name of a deformation shader provided by the rendering 
program and parameterlist contains variables determining 
the transformation. See page 56 of the Spec and page 117 of the Book.

EXAMPLE:
Deformation "warpit"

DepthOfField fstop focallength focaldistance
DepthOfField

focaldistance sets the distance along the direction of view at 
which objects will be in focus. focallength sets the focal length 
of the camera. These two parameters should have the units of distance 
along the view direction in camera coordinates. fstop, or aperture 
number, determines the lens diameter. If the parameters 
are not provided, a pin-hole camera is used and depth of field 
is turned off. See page 26 of the Spec and page 185 of the Book.

EXAMPLE:
DepthOfField 22 1 26.7

Detail minx maxx miny maxy minz maxz

The bounding box is specified in the current coordinate system. The 
current detail is set to the area of this bounding box as projected 
into the raster coordinate system, times the relative detail. 
See page 48 of the Spec and page 195 of the Book.

EXAMPLE:
Detail -1 1 -1 1 -1 1

DetailRange minvisible lowertransition uppertransition maxvisible

Set the current detail range attribute. Primitives are never drawn 
if the current detail is less than minvisible or greater than 
maxvisible. Primitives are always drawn if the current detail is between 
lowertransition and uppertransition. See page 49 of the Spec and 
page 197 of the Book.

EXAMPLE:
DetailRange 160 320 10000 10000

Disk height radius thetamax parameterlist

Create a disk, as seen in Figure 2. See page 75 of the Spec and 
page 62 of the Book.

EXAMPLE:
Disk 1 .5 270

Displacement name parameterlist

Set the current displacement shader attribute. name is the name 
of a displacement shader programmed in the RenderMan Shading Language. 
See page 56 of the Spec and page 260 of the Book.

EXAMPLE:
Displacement "displaceit" "amplitude" [2.5]

Display name type mode parameterlist

Choose a display by name and set the type of output being generated. 
The type of the display is either "file" or "framebuffer". name is 
either the name of the image file or the name of the framebuffer (or 
window), depending on type. A rendering program may output any combination 
of color, opacity (alpha) and depth (z) values. Output image mode selection 
is controlled by giving any combination (string concatenation) of: 
"rgb" for color; "a" for alpha; and "z" for depth values; in that 
order. Display options or device-dependent display modes or functions may 
be set using the parameterlist. See page 32 of the Spec and page 155 
of the Book.

EXAMPLE:
Display "fb" "framebuffer" "rgba" "origin" [512 384]

ErrorHandler "ignore"
ErrorHandler "print"
ErrorHandler "abort"

This procedure sets the error handling procedure invoked by the renderer 
when an error is detected. If "- ignore" is specified, all errors 
are silently ignored and the rendering system will attempt to continue 
rendering. If "print" is specified, a diagnostic message is generated for 
each warning and error.  The rendering system will attempt to ignore 
the erroneous information and continue rendering. If "abort" is 
specified, the error will cause a diagnostic message to be generated 
and the rendering system will immediately abort the rendering of 
the current image. See page 92 of the Spec and page 38 of the Book.

EXAMPLE:
ErrorHandler "print"

Exposure gain gamma

This function controls the sensitivity and gamma correction of the 
image exposure process. Each color component of output pixels is 
passed through the following function.  See page 31 of 
the Spec and page 180 of the Book.

EXAMPLE:
Exposure 1.5 2.3

Exterior name parameterlist

This procedure sets the current exterior volume shader attribute. 
name is the name of a volume shader programmed in the RenderMan 
Shading Language. See page 45 of the Spec and page 235 of the Book.

EXAMPLE:
Exterior "fog"

Format xresolution yresolution pixelaspectratio

Set the horizontal (xresolution) and vertical (yresolution) 
resolution (in pixels) of the image to be rendered, as seen in 
Figure 3. The upper left hand corner of the image has coordinates (0,0) 
and the lower right hand corner of the image has coordinates 
(xresolution, yresolution). See page 21 of the Spec and page 156 
of the Book.

EXAMPLE:
Format 512 384 1

FrameAspectRatio frameaspectratio

Adjusts the image format so that the ratio of the width to the height 
of the desired image is frameaspectratio, as seen in Figure 3. 
See page 22 of the Spec and page 159 of the Book.

EXAMPLE:
FrameAspectRatio 1.33333

FrameBegin frame

Marks the beginning of a single frame of an animated sequence. frame 
is the number of this frame. The values of all of the rendering 
options are saved. See page 15 of the Spec and page 51 of the Book.

EXAMPLE:
FrameBegin 14

FrameEnd

Marks the end of a single frame of an animated sequence. The values 
of all of the rendering options are restored. See page 15 of the 
Spec and page 51 of the Book.

EXAMPLE:
FrameEnd

GeneralPolygon nvertices parameterlist

Create a single general planar concave polygon with holes. This polygon 
is specified by giving a list of vertices. The first loop is the outer 
boundary of the polygon; all additional loops are holes. The array 
nvertices contains the number of vertices in each loop. The vertices 
in all the loops are concatenated into a single vertex array in the 
parameterlist. The length of this array, n, is equal to the sum of 
all the values in the array nvertices. See page 62 of the Spec 
and page 78 of the Book.

EXAMPLE:
GeneralPolygon [4 3] "P" [-1 -1 0 -1 1 0 1 1 0 1 -1 0 -.5 -.5 0 0 .5 0 .5 -.5 0]

GeometricApproximation "flatness" value
GeometricApproximation type value

Regulates the approximation of geometric primitives by small surface 
elements or polygons. See page 50 of the Spec and page 172 of the Book.

EXAMPLE:
GeometricApproximation "flatness" 2.5

Geometry name parameterlist

A standard way of defining an implementation-specific geometric 
primitive. The values supplied in the parameter list for each 
primitive is implementation specific. See page 79 of the Spec

EXAMPLE:
Geometry "teapot"

Hider type parameterlist

Specifies the type of hidden surface calculations to be done to render 
an image. type is either "hidden" (standard depth-based hidden surface 
elimination), or "paint" (first object on bottom, last object on top). 
See page 33 of the Spec and page 54 of the Book.

EXAMPLE:
Hider "hidden"

Hyperboloid x1 y1 z1 x2 y2 z2 thetamax parameterlist

Creates a hyperboloid, as seen in Figure 2. See page 74 of the Spec and 
page 63 of the Book.

EXAMPLE:
Hyperboloid 1 -1 -1 1 1 1 360

Identity

Sets the current transformation to the identity matrix. See page 52 
of the Spec and page 117 of the Book.

EXAMPLE:
Identity

Illuminate serialnumber onoff

If onoff is 1, turns on the light source referred to by the serialnumber. 
If onoff is 0, turns off the light source. See page 42 of the Spec 
and page 217 of the Book.

EXAMPLE:
Illuminate 2 1

Imager name parameterlist

Sets the pixel imager shader option. name is the name of an imager 
shader programmed in the RenderMan Shading Language or provided by 
the rendering program. See page 31 of the Spec and page 181 of the Book.

EXAMPLE:
Imager "cymk"

Interior name parameterlist
Sets the current interior volume shader attribute. name is the name 
of a volume shader programmed in the RenderMan Shading Language. 
See page 44 of the Spec and page 235 of the Book.

EXAMPLE:
Interior "water"

LightSource name serialnumber parameterlist

Define a light source. name is the name of a light source shader 
programmed in the RenderMan Shading Language. Light sources each 
have a serialnumber which can be used later in Illuminate requests. See 
page 40 of the Spec and page 216 of the Book.

EXAMPLE:
LightSource "ambientlight" 2 "intensity" [10]

MakeBump picturename texturename swrap twrap filter swidth twidth parameterlist

Convert a height field image in a standard picture file whose name 
is picturename into a bump map file whose name is texturename. The 
swrap and twrap modes are one of: "periodic", "clamp" or "black". See 
page 88 of the Spec and page 259 of the Book.

EXAMPLE:
MakeBump "hills.pic" "hills.tx" "periodic" "clamp" "catmull-rom" 2 2

MakeCubeEnvironment px nx py ny pz nz texturename fov 
  filter swidth twidth parameterlist

Convert six images in standard picture files representing six viewing 
directions into an environment map whose name is texturename. See 
page 90 of the Spec and page 263 of the Book.

EXAMPLE:
MakeCubeEnvironment "foo.x" "foo.nx" "foo.y "foo.ny" "foo.z" 
  "foo.nz" "foo.env" 95 "triangle" 3.0 3.0

MakeLatLongEnvironment picturename texturename filter swidth twidth parameterlist

Convert an image in a standard picture file representing a latitude-
longitude map whose name is picturename into an environment map 
whose name is texturename. See page 89 of the Spec and page 263 
of the Book.

EXAMPLE:
MakeLatLongEnvironment "long.pic" "long.tx" "catmull-rom" 2 2

MakeShadow picturename texturename parameterlist

Create a depth image file named picturename into a shadow map whose 
name is texturename. See page 92 of the Spec and page 269 of the Book.

EXAMPLE:
MakeShadow "shadow.pic" "shadow.tx"

MakeTexture picturename texturename swrap twrap filter swidth twidth

Convert an image in a standard picture file whose name is picturename 
into a texture file whose name is texturename. The swrap and twrap modes 
are one of: "periodic", "clamp" or "black". See page 88 of the 
Spec and page 256 of the Book.

EXAMPLE:
MakeTexture "globe.pic" "globe.tx" "periodic" "clamp" "gaussian" 2 2
Matte onoff

Matte objects are not shaded and are set to be completely opaque so 
that they hide objects behind them. However, regions in the output 
image where a matte object is visible are treated as transparent. See page 
46 of the Spec and page 216 of the Book.

EXAMPLE:
Matte 1

MotionBegin timearray 

To specify objects, transformations or attributes that vary over time, 
several copies of the same RIB request are made, each with different 
parameters at different times within a frame. MotionBegin starts the 
definition of a moving primitive and lists the times at which each following 
version is to occur. See page 83 of the Spec and page 189 of the Book.

EXAMPLE:
MotionBegin [0 0.0333]

MotionEnd

Ends the series of motion specifications. See page 83 of the Spec and 
page 189 of the Book.

EXAMPLE:
MotionEnd

NuPatch nu uorder uknot umin umax nv vorder vknot vmin vmax parameterlist

Creates a tensor product rational or polynomial non-uniform B-spline 
surface patch mesh, commonly known as a NURB surface. The number of 
control points in the u direction equals nu and the number in 
the v direction equals nv. The order must be positive and is equal to 
the degree of the polynomial basis plus 1. The knot vectors associated 
with each control point (uknot, vknot) must also be specified. The 
surface is defined in the range umin to umax and vmin to vmax. 
See page 69 of the Spec and page 104 of 
the Book.

EXAMPLE:
NuPatch 9 3 [0 0 0 1 1 2 2 3 3 4 4 4] 0 4 2 2 [0 0 1 1] 0 1 "Pw"
		[1	0	0	1	1	1	0	1	0	2
	0	2
		-1	1	0	1	-1	0	0	1	-1	-1
	0	1
		0	-2	0	2	1	-1	0	1	1	0
	0	1
		1	0	-3	1	1	1	-3	1	0	2
	-6	2
		-1	1	-3	1	-1	0	-3	1	-1	-1
	-3	1
		0	-2	-6	2	1	-1	-3	1	1	0
	-3	1]

ObjectBegin serialnumber

Begins the storage of a single geometric primitive or a set of geometric 
primitives, which is retained for future duplication by ObjectInstance. 
See page 81 of the Spec and page 133 of the Book.

EXAMPLE:
ObjectBegin 4

ObjectEnd

Terminates the storage of a retained object. See page 81 of the Spec 
and page 133 of the Book.

EXAMPLE:
ObjectEnd

ObjectInstance serialnumber

Create an instance of a previously defined object. The object inherits 
the current set of attributes defined in the graphics state. See 
page 82 of the Spec and page 134 of the Book.

EXAMPLE:
ObjectInstance 4

Opacity color

Set the current opacity to color. Normally there are three components in 
the color (red, green, and blue), but this may be changed with 
ColorSamples. If the opacity is 1, the object is completely opaque; if the 
opacity is 0, the object is completely transparent. See page 38 of 
the Spec and page 213 of the Book.

EXAMPLE:
Opacity [.5 1 1]

Option name parameterlist

Sets any additional implementation-specific options of the rendering 
program which control parameters that affect either their performance 
or operation. See page 35 of the Spec and page 46 of the Book.

EXAMPLE:
Option "limits" "bucketsize" [24 24]

Orientation orientation

Sets the current orientation attribute to be either "outside" 
(to match the current coordinate system, "inside" (to be the 
inverse of the current coordinate system), "lh" (for explicit left-
handed orientation) or "rh" (for explicit right-handed orientation). 
See page 50 of the Spec and page 121 of the Book.

EXAMPLE:
Orientation "inside"

Paraboloid rmax zmin zmax thetamax parameterlist

Creates a paraboloid, as seen in Figure 1. See page 75 of the Spec 
and page 66 of the Book.

EXAMPLE:
Paraboloid .5 .2 .7 270 "Cs" [1 .1 .1 1 .1 0 1 0 .1 1 0 0]

Patch type parameterlist

Create a single patch. type can be either "bilinear" or "bicubic". 
The parameter list must include at least position ("P", "Pw" or "Pz") 
information. Four points define a bilinear patch, and 16 define a bicubic 
patch. Patch arrays are specified such that u varies faster than v. 
See page 66 of the Spec and page 87 of the Book.

EXAMPLE:
Patch "bilinear" "P" [-0.08 0.04 0.05 0.0 0.04 0.05 -0.08 0.03 0.05 0.0 0.03 0.05]

PatchMesh type nu uwrap nv vwrap parameterlist

This primitive is a compact way of specifying a quadrilateral mesh 
of patches. Each individual patch behaves as if it had been specified 
with Patch. type can be either "bilinear" or "bicubic". The parameter 
list must include at least position ("P", "Pw" or "Pz") information. 
Patch mesh vertex data is supplied in first u and then v order just 
as for patches. Meshes can wrap around in the u or v direction, or in both 
directions. If meshes wrap, they close upon themselves at the ends and 
the first control points will be automatically repeated. The way in 
which meshes wrap is indicated by giving a wrap mode value of either 
"periodic" or "nonperiodic". See page 67 of the Spec and page 98 of the Book.

EXAMPLE:
Basis "catmull-rom" 1 "catmull-rom" 1
PatchMesh "bicubic" 5 "nonperiodic" 4 "nonperiodic" "P" [
		0	-1	.2	.5	-1	.9	1	-1	.7	1.5
	-1	.1	2	-1	.5
		0	1	.7	.5	1	.3	1	1	.6	1.5
	1	.8	2	1	.4
		0	3	.4	.5	3	.6	1	3	.4	1.5
	3	.7	2	3	.9
		0	7	.1	.5	7	.8	1	7	.5	1.5
	7	.3	2	7	.6	]

Perspective fov

Concatenate a perspective transformation onto the current transformation.
The focal point of the perspective is at the origin and its direction 
is along the z-axis. The field of view angle, fov, specifies the 
full horizontal field of view. See page 53 of the Spec and page 114 
of the Book.

EXAMPLE:
Perspective 90

PixelFilter filter xwidth ywidth

Antialiasing is usually performed by supersampling and then filtering 
down to pixel locations. The filter controls the type of filter, 
while xwidth and ywidth specify the width of the filter in pixels. 
type is one of: "box", "triangle", "catmull-rom", "gaussian" or "sinc". 
See page 30 of the Spec and page 176 of the Book.

EXAMPLE:
PixelFilter "gaussian" 2 1

PixelSamples xsamples ysamples

Set the effective hider supersampling rate in the horizontal and 
vertical directions. See page 30 of the Spec and page 176 of the Book.

EXAMPLE:
PixelSamples 2 2

PixelVariance variation

Sets the upper bound on the acceptable estimated variance of the computed 
pixel values from the true pixel values. See page 28 of the Spec and 
page 179 of the Book.

EXAMPLE:
PixelVariance .01

PointsGeneralPolygon nloops nvertices vertices parameterlist

Create a set of general planar concave polygons, with holes, that 
share vertices. The array nloops indicates the number of loops 
comprising each polygon. The array nvertices contains the number of 
vertices in each loop and has a length equal to the sum of all the 
values in the array nloops. The array vertices contains, for each 
loop vertex, an index into the primitive variable arrays in the 
parameterlist. vertices has a length equal to the sum of all the values 
in the array nvertices. Individual vertices in the parameterlist are thus 
accessed indirectly through the indices in the array vertices. All 
of the arrays are 0-based. See page 64 of the Spec and page 82 of the Book.

EXAMPLE:
PointsGeneralPolygon [2 2] [4 3 4 3] [0 1 3 4 6 7 8 1 2 5 4 9 10 11] 
  "P" [0 0 1  0 1 1  0 2 1  0 0 0  0 1 0 0 2 0
  0 0.25 0.5  0 .75 .75  0 1.75 .25 0 1.25 0.5  0 1.75 .75  0 1.75 .25] 

PointsPolygons nvertices vertices parameterlist

Create a set of planar convex polygons that share vertices. The 
array nvertices contains the number of vertices in each polygon. The 
array vertices contains, for each polygon vertex, an index into the varying 
primitive variable arrays. vertices has length equal to the sum of 
all of the values in the nvertices array. Individual vertices in 
the parameterlist are thus accessed indirectly through the indices in the 
array vertices. All arrays are 0-based. See page 63 of the Spec and page 79 
of the Book.  

EXAMPLE:
PointsPolygons [3 3 3] [0 3 2 0 1 3 1 4 3] 
  "P" [0 1 1  0 3 1  0 0 0  0 2 0  0 4 0] "Cs" [0 .3 .4  0 .3 .9  .2 .2
  .2  .5 .2 0  .9 .8 0]

Polygon parameterlist

Create a single closed planar convex polygon. See page 61 of the Spec 
and page 70 of the Book.

EXAMPLE:
Polygon "P" [0 1 0 0 1 1 0 0 1 0 0 0]

Projection name parameterlist

The projection determines how camera coordinates are converted 
to screen coordinates, as seen in Figure 3. "perspective" builds a 
projection matrix that does a perspective projection along the z-axis. 
"perspective" takes one optional parameter, "fov", a single floating-point 
number that indicates the full angle perspective field of view (in 
degrees) between screen space coordinates (-1,0) and (1,0) (equivalently 
between (0,-1) and (0,1)). The default is 90 degrees. "orthographic" 
builds a simple orthographic projection. "orthographic" takes no parameters. 
See page 24 of the Spec and page 149 of the Book.

EXAMPLE:
Projection "perspective" "fov" [30.0]

Quantize type one min max ditheramplitude

Set the quantization parameters for colors or depth. If type is "rgba", 
then color and opacity quantization are set. If type is "z", then 
depth quantization is set. The value one defines the mapping from floating- 
point values to fixed point values. If one is 0, then quantization is 
not done and values are output as floating point numbers. Dithering is 
performed by adding a random number between plus and minus the 
ditheramplitude to the floating-point values before they are rounded 
to the nearest integer. See page 31 of the Spec and page 183 of the Book.

EXAMPLE:
Quantize "rgba" 255 0 255 0.5

RelativeDetail relativedetail

Scales the results of all level of detail calculations. The level of 
detail is used to select between different representations of an 
object. See page 35 of the Spec and page 196 of the Book.

EXAMPLE:
RelativeDetail .6

ReverseOrientation

Causes the current orientation to be toggled. If the orientation 
was right-handed it is now left-handed, and vice versa. See page 51 
of the Spec and page 122 of the Book.

EXAMPLE:
ReverseOrientation

Rotate angle dx dy dz

Concatenate a rotation of angle degrees about the given axis onto the current 
transformation. See page 54 of the Spec and page 112 of the Book.

EXAMPLE:
Rotate 90 0 1 0

Scale sx sy sz

Concatenate a scaling onto the current transformation. See page 54 
of the Spec and page 113 of the Book.

EXAMPLE:
Scale .5 1 1

ScreenWindow left right bottom top

Defines a rectangle in the image plane that gets mapped to the raster 
coordinate system and that corresponds to the display area selected, 
as seen in Figure 3. The rectangle specified is in the screen 
coordinate system. The values left, right, bottom, and top are mapped to 
the respective edges of the display. See page 23 of the Spec and page 
150 of the Book.

EXAMPLE:
ScreenWindow -1 1 -1 1

ShadingInterpolation type

Controls how values are interpolated between shading samples (usually 
across a polygon). If type is "constant", the color and opacity of all 
the pixels inside the polygon are the same. This is often referred to 
as flat or faceted shading. If type is "smooth", the color and opacity of 
all the pixels between shaded values are interpolated from the calculated 
values. This is often referred to as Gouraud shading. See page 46 of 
the Spec and page 215 of the Book.

EXAMPLE:
ShadingInterpolation "constant"

ShadingRate size

The current shading rate attribute is specified as an area in pixels. 
A huge shading rate specifies that shading need only be done once per 
polygon. A shading rate of 1 specifies that shading is done at least 
once per pixel. This second case is often referred to as Phong shading. 
See page 45 of the Spec and page 214 of the Book.

EXAMPLE:
ShadingRate 1

Shutter opentime closetime
This procedure sets the times at which the shutter opens and closes 
for motion blur. See page 26 of the Spec and page 190 of the Book.

EXAMPLE:
Shutter 0 0.0333

Sides nsides

If nsides is 2, subsequent surfaces are considered two-sided and 
both the inside and the outside of the surface will be visible. If 
nsides is 1, subsequent surfaces are considered one-sided and only 
the outside of the surface will be visible. See page 51 of the Spec and 
page 119 of the Book.

EXAMPLE:
Sides 2

Skew angle dx1 dy1 dz1 dx2 dy2 dz2

Concatenate a skew onto the current transformation. This operation 
shifts all points along lines parallel to the axis vector (dx2, dy2, dz2
). Points along the axis vector (dx1, dy1, dz1) are mapped onto the vector 
(x, y, z), where angle specifies the angle (in degrees) between the vectors 
(dx1, dy1, dz1) and (x, y, z). See page 55 of the Spec and page 113 of the 
Book.

EXAMPLE:
Skew 45 0 1 0 1 0 0

SolidBegin operation

Begins the definition of a constructive solid geometry (CSG) layer. 
operation may be one of the following tokens: "primitive", 
"intersection", "union", "difference". Intersection and union operations
form the set intersection and union of the subordinate solids. 
Difference operations require at least 2 subordinate solids 
and subtract the last n-1 solids from the first (where n is the 
number of primitive solids). See page 80 of the Spec and page 126 of the Book.

EXAMPLE:
SolidBegin "union"

SolidEnd

Ends the definition of the current CSG layer. See page 80 of the Spec 
and page 126 of the Book.

EXAMPLE:
SolidEnd

Sphere radius zmin zmax thetamax parameterlist

Creates a sphere, as seen in Figure 1. See page 72 of the Spec and 
page 62 of the Book.

EXAMPLE:
Sphere .5 0 .5 360

Surface name parameterlist

Sets the current surface shader attribute. name is the name of a 
surface shader programmed in the RenderMan Shading Language. See 
page 42 of the Spec and page 231 of the Book.

EXAMPLE:
Surface "wood" "roughness" [.3] "Kd" [1]

TextureCoordinates s1 t1 s2 t2 s3 t3 s4 t4)

Set the current set of texture coordinates, by assigning the texture 
coordinates for the four parametric corners of parametric primitives. 
See page 39 of the Spec and page 251 of the Book.

EXAMPLE:
TextureCoordinates 0 0 2 -.5 -.5 1.75 3 3

Torus rmajor rminor phimin phimax thetamax parameterlist

Creates a torus, as seen in Figure 2. See page 76 of the Spec and 
page 66 of the Book.

EXAMPLE:
Torus 3.5 .25 0 180 300

Transform transform

Set the current transformation to the transformation matrix transform. 
See page 52 of the Spec and page 117 of the Book.

EXAMPLE:
Transform [.5 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1]

TransformBegin

Pushes the current transformation onto the transformation stack. Note 
that pushing the attributes also pushes the current transformation. See 
page 58 of the Spec and page 111 of the Book.

EXAMPLE:
TransformBegin

TransformEnd
Pops the current transformation off of the transformation stack. 
Note that popping the attributes also pops the current transformation. 
See page 58 of the Spec and page 111 of the Book.

EXAMPLE:
TransformEnd

Translate dx dy dz

Concatenate a translation onto the current transformation. See page 
54 of the Spec and page 112 of the Book.

EXAMPLE:
Translate 0 1 0

TrimCurve ncurves order knot min max n u v w

NURBS may contain holes that are specified by giving a single closed 
curve in parameter space. The trim curve contains multiple loops, 
and each of these loops contains ncurves curves. The total number of curves 
is equal to the sum of all the values in ncurves. Each of the trimming 
curves is a non-uniform rational B-spline curve in homogeneous parameter 
space (u,v,w). The curves of a loop connect in head-to-tail fashion 
and must be explicitly closed. All the trim curve parameters are 
concatenated together into single large arrays. The meanings of 
these parameters are the same as the corresponding meanings for a non-uniform 
B-spline surface. See page 71 of the Spec and page 249 of the Book.

EXAMPLE:
TrimCurve [1] [3] [0 0 0 1 1 2 2 3 3 4 4 4] [0] [4] [9] 
[1 1 1 0 0 0 1 1 1] [.5 1 2 1 .5 0 0 0 .5] [1 1 2 1 1 1 2 1 1]

version num

Specifies the protocol version number of the RIB stream. The stream 
specified in this document is version 3.03.

EXAMPLE:
version 3.03

WorldBegin

Signals the start of the geometric scene description for the contents 
of a single rendered image. The camera transformation and all 
rendering options are frozen, and cannot be changed until the picture is 
finished. See page 16 of the Spec and page 48 of the Book.

EXAMPLE:
WorldBegin

WorldEnd

Completes the geometric description of an image, and causes the image 
to be rendered. See page 16 of the Spec and page 48 of the Book.

EXAMPLE:
WorldEnd



Statement of Copyright and Trademark Rights

Pixar owns the copyrights in the RenderMan Interface and RenderMan 
Interface Bytestream Protocol ("RIB") including the Procedures List, 
Binary Encoding table and the RenderMan written specifications 
and manuals. These may not be copied without Pixar's permission. 
Pixar also owns the registered trademark "RenderMan". 
Any program that incorporates any of the RenderMan procedures calls or 
RIB requests must include the proper copyright notice on each program 
copy. The copyright notice should appear in a manner and location to 
give reasonable notice of Pixar's copyrights, as follows: 

The RenderMan  Interface Procedures and Bytestream Protocol are: 

Copyright 1988-1990, Pixar All Rights Reserved

The trademark "RenderMan" should refer only to the scene description 
interface created by Pixar. Anyone that creates a routine or computer 
program that includes any of the procedures calls from the RenderMan 
Procedures List statement or RIB requests from the Binary Encoding table 
may refer to the computer program as "using" or "adhering to" or 
"compatible with" the RenderMan Interface, if that statement is 
accurate. Any such reference must be accompanied by the following legend: 

RenderMan  is a registered trademark of Pixar

No-one may refer to or call a product or program which did not 
originate with Pixar a "RenderMan program" or "RenderMan modeler" 
or "RenderMan renderer". 

Use of the trademark "RenderMan" should follow the trademark use 
procedure guidelines of Pixar. Refer to the statement on page 193 of 
the RenderMan Interface Specification for more information. Any use of the 
RenderMan Interface, RIB and related materials other than as described in 
this statement is an unauthorized use and violates Pixar's proprietary 
rights, and Pixar will enforce its rights to prevent such use. 

The RenderMan Interface procedures and Bytestream Protocol are Copyright  
1988-1990 Pixar. 

RenderMan is a registered trademark of Pixar. PhotoRealistic 
RenderMan, RIB, and the bouncing ball device are trademarks of Pixar. 



ED. NOTE:  The figures referenced in this document are too complex
to be shown in a text file.  

Figure 1 shows a cone, cylinder, sphere, and paraboloid.

Figure 2 shows a disk, hyperboloid, and torus.

Figure 3 shows an illustration of camera-to-raster projection geometry.

To see these figures, refer to the Frame file in this directory.