 
|
 
Version 3.1
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:
- Any nonstandard shaders, optional RenderMan features (motion
blur, CSG, level of detail) or textures should be flagged as special
resource requirements.
- Renderer-specific options or attributes should be specified
according to the special comment conventions described below.
- Display-dependent RenderMan options should not be included except
to indicate to Render Managers that such options are mandatory.
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.
Scope
Indentation indicates the scope of the following command.
Preamble and global variable declarations
(RIB requests: version, declare)
Static options and default attributes
(image and display options, camera options)
Static camera transformations
(camera location and orientation)
Frame block
(if more than one frame)
Frame-specific variable declarations
Variable options and default attributes
Variable camera transforms
World block
(scene description)
User Entity
(enclosed within AttributeBegin/AttributeEnd)
User Entity
(enclosed within AttributeBegin/AttributeEnd)
User Entity
more frame blocks
This structure results from the vigorous application of the following
Scoping Conventions:
- No attribute inheritance should be assumed unless implicit in
the definition of the User Entity (i.e., within a hierarchy).
- No attribute should be exported except to establish either global
or local defaults.
The RenderMan Specification provides block structuring to organize
the components of a RIB file. Although the use of blocks is only
required for frame and world constructs by the Specification, the
liberal use of attribute and transform blocks is encouraged. A modeler
enables a Render Manager to freely manipulate, rearrange, or delete
scene elements (frames, cameras, lights, User Entities) by carefully
bounding these elements in the RIB file according to scope. A Render
Manager might, for example, strip all of the frames out of a RIB
file and distribute them around a network of rendering servers.
This, of course, is only possible if the RIB file has been structured
in such a way as to bound those things pertaining to a given frame
within its frame block and those things pertaining to all frames
outside and before all frame blocks.
A User Entity couples a collection of geometric primitives and/or
User Entities with shading and geometric attributes. As such it
introduces a level of scope that is more local than that implied
by the RenderMan world block. Typically, the term User Entity refers
to a geometric element within a scene whose attributes or position
a user may wish to modify or tweak. Because there is some computational
expense associated with attribute block structuring, there is an
intrinsic trade-off between control over individual User Entities
and rendering time/memory requirements. At one extreme, the entire
scene is made up of one User Entity within one attribute block.
At the other extreme, each polygon is a User Entity and the renderer
is forced to spend most of its time managing the graphics state.
Modeling programs and their users may wish to carefully weigh this
trade-off.
The Scoping Conventions above prescribe the following User Entity
Conventions:
- All User Entities must be delimited by an attribute block.
- All User Entities must have an identifier attribute that uniquely
characterizes that Entity to the user. Two special identifier
attributes are provided to distinguish between Entities organized
by a geometric relationship (the name identifier) and Entities
organized according to material makeup (the shadinggroup identifier).
- A User Entity must be completely described within its attribute
block.
Nonportable options and attributes
The following list of RIB requests are restricted as they either
limit the device independence of the file or they control rendering
quality or speed parameters. Render managers should provide this
kind of control to users at render time. The inclusion of these
restricted requests by a modeler should indicate to a Render Manager
that they are, in some sense, mandatory. When including nonportable
options or attributes in the RIB file, they should be located contiguously
(according to scope) in a RIB file.
| Attribute |
Format |
PixelFilter |
ShadingRate |
| ColorSamples |
FrameAspectRatio |
PixelSamples |
|
| CropWindow |
Imager |
PixelVariance |
|
| Exposure |
Option |
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 must be located immediately beginning any conforming
RIB file. These hints should provide scene-global administrative
and resource information. Header entries should precede any RIB
requests and must be contiguous. If a header entry appears twice
in a file, the first occurrence should be considered to be the true
value.
- ##RenderMan RIB-Structure 1.1 [
keyword
]
- This entry should be the first line in a conforming RIB file.
Its inclusion indicates full conformance to these specifications.
The addition of the special keyword, Entity, specifies
that the file conforms to the User Entity conventions described
in the Rib Entity Files section.
- ##Scene
name
- This entry allows a scene name to be associated with the RIB
file.
- ##Creator
name
- Indicates the file creator (usually the name of the modeling
or animation software).
- ##CreationDate
time
- Indicates the time that the file was created. It is expressed
as a string of characters and may be in any format.
- ##For
name
- Indicates the user name or user identifier (network address)
of the individual for whom the frames are intended.
- ##Frames
number
- Indicates the number of frames present in the file.
- ##Shaders
shader1, shader2,
...
- Indicates the names of nonstandard shaders required. When placed
in the header of a RIB file, any nonstandard shaders that appear
in the entire file should be listed. When placed within a frame
block, any nonstandard shaders that appear in that frame must
be listed.
- ##Textures
texture1, texture2,
...
- Lists any preexisting textures required in the file. When placed
in the header of a RIB file, any preexisting textures that appear
anywhere in the file should be listed. When placed within a frame
block, any preexisting shaders that appear in that frame must
be listed.
- ##CapabilitiesNeeded
feature1, feature2,
...
- Indicates any RenderMan Interface optional capabilites required
in the file (when located in the header) or required in the frame
(when located at the top of a frame block). The optional capabilities
are:
| Area Light Sources |
Motion Blur |
Special Camera Projections |
| Bump Mapping |
Programmable Shading |
Spectral Colors |
| Deformations |
Radiosity |
Texture Mapping |
| Displacements |
Ray Tracing |
Trim Curves |
| Environment Mapping |
Shadow Depth Mappin |
Volume Shading |
| Level Of Detail |
Solid 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 fea
ture1, feature2,
...
- Lists the special capabilities required in the current frame
from among those listed under Header
Information.
Body Information
Body information may be located anywhere in the RIB file.
- ##Include
filename
- This entry allows the specification of a file name for inclusion
in the RIB stream. Note that the Include keyword itself does not
cause the inclusion of the specified file. As with all structural
hints, the Include keyword serves only as a special hint for render
management systems. As such, the Include keyword should only be
used if render management facilities are known to exist.
RIB File structuring example
##RenderMan RIB-Structure 1.1
##Scene Bouncing Ball
##Creator /usr/ucb/vi
##CreationDate 12:30pm 8/24/89
##For RenderMan Jones
##Frames 2
##Shaders PIXARmarble, PIXARwood, MyUserShader
##CapabilitiesNeeded ShadingLanguage Displacements
version 3.03
Declare "d" "uniform point"
Declare "squish" "uniform float"
Option "limits" "bucketsize" [6 6] #renderer specific
Option "limits" "gridsize" [18] #renderer specific
Format 1024 768 1 #mandatory resolution
Projection "perspective"
Clipping 10 1000.0
FrameBegin 1
##Shaders MyUserShader, PIXARmarble, PIXARwood
##CameraOrientation 10.0 10.0 10.0 0.0 0.0 0.0
Transform [.707107 -.408248 -.57735 0
0 .816497 -.57735 0
-.707107 -.408248 -.57735 0
0 0 17.3205 1 ]
WorldBegin
AttributeBegin
Attribute "identifier" "name" "myball"
Displacement "MyUserShader" "squish" 5
AttributeBegin
Attribute "identifier" "shadinggroup" ["tophalf"]
Surface "PIXARmarble"
Sphere .5 0 .5 360
AttributeEnd
AttributeBegin
Attribute "identifier" "shadinggroup" ["bothalf"]
Surface "plastic"
Sphere .5 -.5 0. 360
AttributeEnd
AttributeEnd
AttributeBegin
Attribute "identifier" "name" ["floor"]
Surface "PIXARwood" "roughness" [.3] "d" [1]
# geometry for floor
Polygon "P"
[-100. 0. -100. -100. 0. 100. 100. 0. 100. 10.0 0. -100.]
AttributeEnd
WorldEnd
FrameEnd
FrameBegin 2
##Shaders PIXARwood, PIXARmarble
##CameraOrientation 10.0 20.0 10.0 0.0 0.0 0.0
Transform [.707107 -.57735 -.408248 0
0 .57735
-.815447 0
-.707107 -.57735 -.408248 0
0 0 24.4949 1 ]
WorldBegin
AttributeBegin
Attribute "identifier" "name" ["myball"]
AttributeBegin
Attribute "identifier" "shadinggroup" ["tophalf"]
Surface "PIXARmarble"
ShadingRate .1
Sphere .5 0 .5 360
AttributeEnd
AttributeBegin
Attribute "identifier" "shadinggroup" ["bothalf"]
Surface "plastic"
Sphere .5 -.5 0 360
AttributeEnd
AttributeEnd
AttributeBegin
Attribute "identifier" "name" ["floor"]
Surface "PIXARwood" "roughness" [.3] "d" [1]
# geometry for floor
AttributeEnd
WorldEnd
FrameEnd
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:
- The header hint: ##RenderMan RIB-Structure 1.1 Entity must be
included as the first line of the file.
- The Entity must be built in an object coordinate system which
is centered about the origin.
- The Entity must have a RIB bound request to provide a single
bounding box of all geometric primitives in the User Entity.
RIB Entity File example
##RenderMan RIB-Structure 1.1 Entity
AttributeBegin #begin unit cube
Attribute "identifier" "name" "unitcube"
Bound -.5 .5 -.5 .5 -.5 .5
TransformBegin
# far face
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
Rotate 90 0 1 0
# right face
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
# near face
Rotate 90 0 1 0
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
# left face
Rotate 90 0 1 0
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
TransformEnd
TransformBegin
# bottom face
Rotate 90 1 0 0
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
TransformEnd
TransformBegin
# top face
Rotate -90 1 0 0
Polygon "P" [.5 .5 .5 -.5 .5 .5 -.5 -.5 .5 .5 -.5 .5]
TransformEnd
AttributeEnd #end unit cube
RenderMan Renderer Resource Files
Renderer Resource Files are intended to provide information to
Render Managers and modelers about the specific features, attributes,
options, and resources of a particular renderer. In an environment
where multiple renderers are available, a Render Manager can provide
the user with the ability to tailor RIB file to best suit the desired
renderer.
Renderer Resource Files should be shipped with any RenderMan renderer
and should be updated on-site by the local system administrator
to reflect the resources available to a renderer. Only those sections
containing site-specific information can be customized in this way.
The simple ASCII format of Renderer Resource Files makes them easy
to read, modify and parse.
Format of Renderer Resource Files
A Renderer Resource File is broken up into a series of sections
delimited by special keywords. Within each section, all related
information is provided using a section-specific predefined format.
A special include keyword is provided to simplify the task of customizing
Resource Files. The keywords are as follows:
- ##RenderMan Resource-1.0
- Must be included as the first line in any Renderer Resource
File.
- ##Renderer
name
- Requires the name of the renderer along with any revision or
date information.
- ##Include
file
- Allows the inclusion of a specified file. This keyword should
only be used in sections which are modifiable.
- ##RenderManCapabilitiesAvailable
- This keyword identifies the section enumerating the Capabilities
provided by the renderer. The list of capabilities are found in
the Header information section
and in Section 1. Each capability
implemented by the renderer must appear as one line in this section.
No entries in this section should be modified.
- ##RendererSpecificAttributes
- This keyword identifies the section which enumerates the Renderer
Specific Attributes. These attributes are invoked with the RIB
call Attribute. Each attribute implemented by the renderer must
appear as one line in this section with legal RIB syntax. The
class of all parameter identifiers must be declared previously
with a Declare RIB request. If arguments are required for a given
attribute, the entry should specify the default value for that
attribute. No entries in this section should be modified.
- ##RendererSpecificOptions
- This keyword identifies the section which enumerates Renderer
Specific Options. These attributes are invoked with the RIB call
Option. Each option implemented by the
renderer must appear as one line in this section with legal RIB
syntax. The class of all parameter identifiers must be declared
previously with a Declare RIB request. No entries in
this section should be modified.
- ##ShaderResources
- This keyword identifies the section which enumerates Shaders
available to the renderer. Both built-in and programmed shaders
should be listed here. A RenderMan Shading Language declaration
for each shader must be provided to enumerate the specific instantiated
variables. A declaration may cross line boundaries. This section
can be customized to a specific site.
- ##TextureResources
- This keyword identifies the section which enumerates the Textures
available to the renderer. The name of each texture may be followed
on the same line by an optional string which provides a short
description of the Texture. If included, the string should be
preceded by the `#' character. This section can be customized
to a specific site.
Renderer Resource File example
##RenderMan Resource-1.0
##Renderer TrayRacer 1.0
##RenderManCapabilitiesAvailable
Solid Modeling
Motion Blur
Programmable Shading
Displacements
Bump Mapping
Texture Mapping
Ray Tracing
Environment Mapping
##RendererSpecificAttributes
Declare "refractionindex" "uniform float"
Declare "displacement" "uniform float"
Attribute "volume" "refractionindex" [1.0]
Attribute "bound" "displacement" 3.5
##RendererSpecificOptions
Declare "bucketsize" "uniform integer[2]"
Declare "texturememory" "uniform integer"
Declare "shader" "string"
Declare "texture" "string"
Option "limits" "bucketsize" [12 12]
Option "limits" "texturememory" 1024
Option "searchpath" "shader" "/usr/local/prman/shaders"
Option "searchpath" "texture" "/usr/local/prman/textures"
##ShaderResources
surface wood(
float ringscale = 10;
color lightwood = color(.3, .12, 0.0);
darkwood = color(.05, .01, .005);
float Ka =.2,
Kd =.4,
Ks =.6,
roughness =.1)
displacement dented(float Km = 1.0)
light slideprojector (
float fieldofview=PI/32;
point from = {8,-4,10), to
= {0,0,0), up
= point "eye" (0,1,0);
string slidename = "" )
##Include othershaderfile
##TextureResources
brick
bluebrick
grass #kentucky bluegrass-1 square meter
moss #spanish moss
logo
##Include othertexturefile
|
