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.