Strings in RIB.TXT
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:
linefeed (newline)
carriage return
horizontal tab
backspace
form feed
backslash
double quote
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 [
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"
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" [
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.
