Appendix D - RenderMan Interface Bytestream Conventions

Version 1.1

File structuring conventions for RIB files are presented to facilitate the use of RIB as a file format for rendering interchange. A format for single User Entities is presented to allow importing external models into existing RIB streams. Finally, we describe a rendering services file format that will enable Render Managers to provide services to a specific renderer.

RIB File Structuring Conventions

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

This section lays out a set of RIB file format conventions which are patterned loosely after the model put forth in Adobe's “Document Structuring Conventions.”

Conforming files

The conventions outlined in this section are optional in the sense that they are not interpreted by a renderer and thus will not have any effect on the image produced. Although a Render Manager may require conformance to these conventions, it may choose to utilize or ignore any subset of the structural information present in the RIB file. A RIB file is said to be conforming if it observes the Pixar RIB File Structuring Conventions, and the conforming file can be expected to adhere to specific structuring constraints in that case.

Using RIB File structuring conventions

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

RIB File structure conventions

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


Indentation indicates the scope of the following command.

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

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

	Static camera transformations (camera location and orientation) 

	Frame block (if more than one frame) 

		Frame-specific variable declarations 

		Variable options and default attributes 

		Variable camera transforms 

		World block 

		  (scene description) 

		  User Entity (enclosed within AttributeBegin/AttributeEnd) 

		  User Entity (enclosed within AttributeBegin/AttributeEnd) 

		  User Entity 

	more frame blocks 

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

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

User Entities

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

The Scoping Conventions above prescribe the following User Entity Conventions:

Nonportable options and attributes

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

CropWindow ImagerPixelVariance
ExposureOption Quantize

Conventions for structural hints

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

Header information

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

##RenderMan RIB-Structure 1.1 [ keyword ]
This entry should be the first line in a conforming RIB file. Its inclusion indicates full conformance to these specifications. The addition of the special keyword, Entity, specifies that the file conforms to the User Entity conventions described in the Rib Entity Files section.
##Scene name
This entry allows a scene name to be associated with the RIB file.
##Creator name
Indicates the file creator (usually the name of the modeling or animation software).
##CreationDate time
Indicates the time that the file was created. It is expressed as a string of characters and may be in any format.
##For name
Indicates the user name or user identifier (network address) of the individual for whom the frames are intended.
##Frames number
Indicates the number of frames present in the file.
##Shaders shader1, shader2, ...
Indicates the names of nonstandard shaders required. When placed in the header of a RIB file, any nonstandard shaders that appear in the entire file should be listed. When placed within a frame block, any nonstandard shaders that appear in that frame must be listed.
##Textures texture1, texture2, ...
Lists any preexisting textures required in the file. When placed in the header of a RIB file, any preexisting textures that appear anywhere in the file should be listed. When placed within a frame block, any preexisting shaders that appear in that frame must be listed.
##CapabilitiesNeeded feature1, feature2, ...
Indicates any RenderMan Interface optional capabilites required in the file (when located in the header) or required in the frame (when located at the top of a frame block). The optional capabilities are:
Area Light SourcesMotion BlurSpecial Camera Projections
Bump MappingProgrammable ShadingSpectral Colors
DeformationsRadiosity Texture Mapping
DisplacementsRay TracingTrim Curves
Environment MappingShadow Depth MappinVolume Shading
Level Of DetailSolid Modeling

See Part I, Section 1, Introduction, for a description of these capabilities.

Frame information

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

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

Body information may be located anywhere in the RIB file.

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

RIB File structuring example

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


RIB Entity Files

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

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

RIB Entity File example

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


RenderMan Renderer Resource Files

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

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

Format of Renderer Resource Files

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

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

Renderer Resource File example

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

No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Pixar. The information in this publication is furnished for informational use only, is subject to change without notice and should not be construed as a commitment by Pixar. Pixar assumes no responsibility or liability for any errors or inaccuracies that may appear in this publication.


Pixar Animation Studios
(510) 752-3000 (voice)   (510) 752-3151 (fax)
Copyright © 1996- Pixar. All rights reserved.
RenderMan® is a registered trademark of Pixar.