Appendix
D - RenderMan Interface Bytestream ConventionsAppendix
D - RenderMan Interface Bytestream ConventionsVersion 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.
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.”
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.
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:
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.
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:
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 |
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.
keyword
]namenametimename number shader1, shader2,
...texture1, texture2,
...feature1, feature2,
...| 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-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.
eyex eyey eyez atx
aty atz [ upx upy upz ]shader1, shader2,
... texture1, texture2,
...
ture1, feature2,
...Body information may be located anywhere in the RIB file.
filename##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:
##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
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.
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:
namefile##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
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
|