old-www/LDP/LG/issue15/bmrt-part1.html

1196 lines
46 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HEAD>
<TITLE>
Graphics Muse
</TITLE>
</HEAD>
<BODY text="#000000" bgcolor="#ffffff"
vlink="#fa3333" alink="#33CC33" link="#0000FA">
<!-- =============================================================
This Page Designed by Michael J. Hammel.
Permission to use all graphics and other content for private,
non-commerical use is granted provided you give me (or the
original authors/artists) credit for the work.
CD-ROM distributors and commercial ventures interested in
providing the Graphics Muse for a fee must contact me,
Michael J. Hammel (mjhammel@csn.net), for permission.
============================================================= !-->
<A NAME="musings">
<table>
<tr>
<td>
<H2>More...</H2>
<BR clear=both>
<IMG SRC="../gx/hammel/musings.gif" ALT="Musings" ALIGN="left"
HSPACE="0" VSPACE="0" WIDTH="247" HEIGHT="52">
</td>
</table>
</A>
<BR clear=both>
<table>
<tr><td>
<H3>BMRT</H3>
<tr><td>
<OL>
<LH><B> Part I:
Getting Started - Creating, Previewing, and Final Rendering of
Simple Images
<B></LH>
<LI><A HREF="#intro">Introduction</A>
<LI><A HREF="#user-tools">User Tools - Renderers and Previewers</A>
<LI><A HREF="#dev-tools">Developer Tools - libraries, compiler, etc</A>
<LI><A HREF="#examples">The Example Scenes</A>
<LI><A HREF="#rib">The Input File - RIB format</A>
<LI><A HREF="#basic-steps">Basic Steps</A>
<LI><A HREF="#shaders">Shaders</A>
<LI><A HREF="#closing">Closing</A>
</OL></td>
</table>
<IMG SRC="../gx/hammel/cleardot.gif" ALT="indent" ALIGN="left"
VSPACE="5" WIDTH="1" HEIGHT="1">
<BR clear=both>
<table width=100%>
<tr>
<td width="100%" align=right>
<FONT size=1>
&copy 1996 <A HREF="mailto:mjhammel@csn.net">Michael J. Hammel</A>
</FONT></td>
<tr>
<td bgcolor="#000000" cellpadding=0 cellspacing=0 valign=top>
<IMG SRC="../gx/hammel/cleardot.gif" ALT="indent" ALIGN="left"
HSPACE="0" WIDTH="0" HEIGHT="0"></td>
</table>
<P>
<A NAME="intro"></A>
<H2>1. Introduction</H2>
&nbsp; &nbsp; &nbsp;
A couple of years ago, right after Toy Story had been released, I began to
gather as much information on computer graphics as I could find.
At first I had been looking for general information. Later, when I
found out such tools existed for Windows and Mac systems, I began to look
around for various 3D rendering and modelling tools that would run on Unix systems.
The first tool I found was POV-Ray, a tool that has been ported to many
platforms including a number of Unix OS's. I also found a number of other
tools such as Polyray and Radiance.
Since I was very new to 3D tools I started with POV-Ray.
It had a large amount of online information (much of which has
been scaled back on the Internet), a large user base that frequented the
comp.graphics.rendering.raytracing
newsgroup, and it had printed texts available. This last item
was the most important element to me. I needed documentation I didn't have
to print off myself and that was fairly well organized. I tended to carry
it around to read at lunch on work days.
<P clear=both>
<CENTER>
<IMG SRC="../gx/hammel/gmuse.jpg" WIDTH=497 HEIGHT=242 >
<BR>
<B>Figure 1</B>: A sample scene created using BMRT. The
text was produced using the
<A HREF="./source/create_text">
<I>font3d</I></A>
tool, which can
output RIB files.
</CENTER>
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Not long after discovering POV-Ray I came across another tool called BMRT.
BMRT is actually a set of tools that are
compliant with the RenderMan Interface Specification. This
specification is the same one used by <I>PRMan</I>, the tool used by Pixar to
create Toy Story. Although I wanted to learn more about BMRT
I really didn't have the background to understand how to use such
tools. POV-Ray's documentation allowed me to learn some basics up front.
After about a year of working on POV-Ray, along with continued research
in other areas of computer graphics, I began to
look once again at BMRT. I now better understand what it does.
Its time to learn to use it.
&nbsp; &nbsp; &nbsp;
In this first of three articles on BMRT I'll
be describing the package contents and introduce you to the basics of
how to use the BMRT tools. You should keep
in mind that much of the terminology might be new to you and so
the early introductions and descriptions might not make too much sense.
I apologize for this, but describing such a powerful package as BMRT
and the RenderMan Specification in one introductory article is
not easy. Fear not, however.
I'll be explaining all of the package contents in some detail
further along in this article. This won't be a complete, all encompassing
tutorial. But it should be enough to get you started. After you get
done here, go
<A HREF="#ordering-info">
order the RenderMan Specification</A>
from Pixar. It
is a very well written and easy to follow description of what BMRT
implements. It also provides the reference guide necessary to
understand the C and RIB bindings to the RenderMan interface.
<H3>What is BMRT?</H3>
&nbsp; &nbsp; &nbsp;
BMRT stands for the
Blue Moon Rendering Tools. It is a set of tools and libraries created by
Larry Gritz, who now works at Pixar, that allow the previewing and
rendering of
3D models and scenes. The rendering engines (programs) and static
libraries (used to create applications that can output RIB files)
are all compatible with
the RenderMan Interface Standard developed by Pixar.
RenderMan is <B>not</B> an actual piece of software,
although many people use the terms <I>RenderMan</I>
and <I>PRMam</I> (Pixar's software implementation of the RenderMan
specification) interchangeably.
It is a specification stating how a modeling system
communicates with a rendering system. BMRT is an implementation
of the rendering system with a static library provided for use with
modeling systems, including stand-alone programs.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
BMRT's rendering tools support ray tracing, radiosity,
area light sources, texture and environment mapping, programmable shading
in the RenderMan Shading Language,
motion blur, automatic ray cast shadows,
CSG (Constructive Solid Geometry), depth of field,
support of imager and volume shaders,
and other advanced features. The toolkit also contains quick RIB
previewers (using OpenGL and X11) to allow "pencil tests" of scenes
and animations.
<H3>Current Release and Where to Get it</H3>
&nbsp; &nbsp; &nbsp;
At the time of this writing, February 22, 1997, the latest release
of BMRT is 2.3.5. It is available from the
<A HREF="http://www.seas.gwu.edu/student/gritz/bmrt.html">
BMRT Web site (http://www.seas.gwu.edu/student/gritz/bmrt.html)</A>.
This site also contains example images and pointers to other
RenderMan related sites on the Web. Larry only provides precompiled
versions of the renderers and the RIB and shader libraries. He does,
however, provide a set of shaders in source form along with their compiled
versions. We'll discuss shaders a little later. Versions of BMRT
are available for
<UL>
<LI>SGI running IRIX 5.2 and up (mips1, mips2, and mips4 available)
<LI>Linux (i386/486/Pentium)
<LI>FreeBSD (i386/486/Pentium)
<LI>HP 9000 8xx/7xx running HP-UX
<LI>NEXTSTEP (HP, Motorola, Intel, and SPARC processors)
<LI>Sun SPARC (running Solaris)
</UL>
Larry doesn't expect to port BMRT to non-Unix style operating systems
due to the logistics problems (access to machines, and so forth)
inherint with cross-platform development. There is no planned port for
the MkLinux distribution at this time. I don't know if he plans on
working on a Digital Alpha or any other non-Intel Linux ports.
<H3>What the package contains</H3>
&nbsp; &nbsp; &nbsp;
The distribution comes complete with what might be considered as a set
of user tools, a set of development tools, and documentation for both.
Its not quite correct to refer to these as user or development tools
due to the nature of the tools, but for this article such classification
will help organize things a little better.
<H4>User Tools - Renderers and Previewers</H4>
&nbsp; &nbsp; &nbsp;
These are the executable programs in the package that allow users
to render and preview images. There are 3 such programs:
<UL TYPE=circle>
<LI>rendribv - a wireframe previewer
<LI>rgl - a polygon previewer that uses OpenGL
<LI>rendrib - the RenderMan compliant renderer
</UL>
Its easiest to remember these tools as the ones you'll need to
render draft or final versions of your scenes. The first two
are generally used to render draft versions, the last to
render your final scene. However, you don't create the scene files with
these tools. Scene files contain the description of the objects
that make up the scene. These files use a format called RIB, the
RenderMan Interface Bytestream format.
Scene files can be created by hand (not a common practice),
by writing a C program that uses the developer
tools described in the next section, or by modellers that can output
files in the RIB format.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
RIB files describe the shape and positions of objects. They
provide the <I>geometry</I> of a scene. They do not describe
colors of objects, the texture on the surface of objects, nor
any aspect of lighting in the scene. This information is referenced
by the RIB by using <I>shaders</I>. Shaders
are external files that describe the
appearance of the objects in a scene. There are developer tools for
creating and examining shader files.
<H4>Developer Tools - libraries, compiler, etc</H4>
&nbsp; &nbsp; &nbsp;
The developer tools in BMRT are actually a set of
libraries and header files
that are provided for users to create C programs that output
RIB files or to parse shader source files.
The user programs can be specifically designed for a
given scene or set of frames or could be part of a more
generalized modelling system, such as AC3D or SCED.
Also included in the developer tools are programs for compiling
shader source files into their .so format and for examining compiled
shader files to find their types, parameters, and initial values.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Shader source files look like ordinary C code.
The source file is compiled into another format referred to as
the <I>.so</I> file.
The compiled .so versions are actually ASCII files. The .so
extension might be a little confusing to users who are familiar
with creating shared libraries, but these are not shared
object files. They are plain text files.
<BR clear=both>
<UL TYPE=circle>
<LH>The libraries and header files provided are:</LH>
<LI>libribout.a, ri.h - used for producing RIB files
<LI>libsoargs.a, so.h - used to parse compiled shaders
</UL>
<UL TYPE=circle>
<LH>The programs used for compiling and examing shader files are:</LH>
<LI>slc - shader compiler
<LI>sotell - command line program for parsing compiled shaders
</UL>
Note that the distribution does not come with linkable libraries for
the renderers.
<H4>Docs</H4>
&nbsp; &nbsp; &nbsp;
There are only two pieces of documentation that come with the
distribution, however both are quite well written and very
good refernces.
<UL TYPE=circle>
<LI>bmrt.html
<LI>poets.ps
</UL>
The first is a detailed description of all the tools and how to use them.
This is a very valuable reference for new users learning how to
get the most out of the programs by learning their command line
arguments.
The second is a quick introduction to the RenderMan API. It
contains a brief description of the RIB format. For more detailed
information on the RIB format you should contact Pixar to get the
official RenderMan Interface 3.1 Specification. Although the
specification document is not written as a
tutorial, it does contain detailed, reference-style
information on the RIB file format.
For more information on contacting Pixar, see the
<A HREF="http://www.seas.gwu.edu/student/gritz/cgr.renderman.faq">
<A HREF="http://www.cis.ohio-state.edu/hypertext/faq/usenet/graphics/renderman-faq/faq.html">
comp.graphics.renderman FAQ</A>
at
<FONT size=2><B>
http://www.cis.ohio-state.edu/hypertext/faq/usenet/graphics/renderman-faq/faq.html
</B></FONT>
<P>
<HR width="90%">
<A NAME="user-tools"></A>
<H2>2. User Tools - Renderers and Previewers</H2>
<H3>rendribv - wireframe previewer</H3>
&nbsp; &nbsp; &nbsp;
The first of the renderers, <I>rendribv</I>,
provides wireframe previews of the
input scene files. The previews show geometric primitives without
shading or removal of hidden lines. A wireframe display uses
"wire cages" to represent objects instead of representing them as
solid surfaced objects. The wireframe display requires the use
of the X11 windowing system. Rendribv has a number of command line
options, all of which are explained in the accompanying
documentation. One important aspect to keep in mind is that
<I>rendribv</I> was designed to display one or more frames of a RIB
file. It offers a good way to preview an animation without the
overhead that accompanies the shading of object surfaces.
The <I>limbo.rib</I> example scene provides a sample
animation. On my 486DX2/66 with 40M memory the wireframe animation
is fairly smooth using <I>rendribv</I>. Its even faster on my
P75 laptop with 8M of memory.
<H3>rgl - quick polygon previewer that uses OpenGL</H3>
&nbsp; &nbsp; &nbsp;
Another previewer provided in the distribution is the <I>rgl</I> program.
This renderer displays previews of scenes with simple
Gouraud shading of object surfaces using OpenGL
(OpenGL is a specification for a graphics interface from Silicon
Graphics - see this months review of Mark Kilgards
OpenGl Programming with the X Window System).
Gouraud shading is a method for
helping to eliminate large changes in color intensities that can cause
banding.
Hidden lines, those lines and
surfaces that should not be visible to the viewer because they are
blocked by other lines or surfaces, are also removed. Since
<I>rgl</I>
requires OpenGL, a port of an OpenGL library must be available
on a particular platform in order for Larry to port <I>rgl</I>
to that platform.
Fortunately, the MesaGL library is available for Linux, as well as
some commercial ports of the official OpenGL libraries, so there
is a working version of <I>rgl</I> available for Linux.
<I>rgl</I> is statically linked so you don't need any of the OpenGL
or MesaGL libraries to use it.
Other Unix distributions of BMRT may not have this program, however.
<H3>rendrib - hiqh quality renderer w/raytracing and radiosity</H3>
&nbsp; &nbsp; &nbsp;
This is the gravy on the potatoes. The <I>rendrib</I> program is a fully
featured, RenderMan compliant renderer that provides not only
the full feature set of the RenderMan Specification but also
provides such things as ray tracing, radiosity, solid modeling, depth of
field, motion blur, area light sources, texture mapping,
environment mapping, volume and imager shading, and support of the
RenderMan Shading Language. The latest version also supports
displacement mapping, a method of mapping an image to a surface that
not only changes the appearance of the surface but also the actual
shape of that surface. <I>Rendrib</I> is the tool to use when
rendering your final scene as it will produce the best, most
realistic results of all the renderers provided.
<H3>A word about compatibility with commercial Linux distributions</H3>
&nbsp; &nbsp; &nbsp;
Version 2.3.4 of the BMRT rendering tools were built against
version 26 of the g++ library. Version 2.3.5 is linked against
version 27. This is no problem if you're running one of the newer
commercial Linux distributions since I believe 27 has been out for awhile
and should be in most recent Linux distrubtions. However, my
laptop has an older Slackware 3.0 release which only has g++ v26.
which means I can't run the v2.3.5 renderers on my laptop. This
isn't a big deal for me, but it is something you should be aware of
when deciding to explore BMRT. I don't know if Larry supplies older
versions of BMRT so you may have to upgrade in order to use the
latest distribution of BMRT.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Note that the X and MesaGL/OpenGL libraries were statically linked
to the renderers. However, the C/C++ libraries are still
dynamically linked, which is why you need to be aware of which
versions of these libraries are required.
<P>
<HR width="90%">
<A NAME="dev-tools"></A>
<H2>3. Developer Tools - libraries, compiler, etc</H2>
<H3>slc - shader langauge compiler</H3>
&nbsp; &nbsp; &nbsp;
The shader language compiler is a program which takes
shader language source files, those files ending in .sl, and compiles
them into their compiled versions, those files ending in .so.
The compiled shader files appear to be code to a state machine used in the
<I>rendrib</I>
renderer that determines how shading is applied to a given object (I
don't know that for certain, but it seems a reasonable guess).
RenderMan is a procedural interface. The shaders are procedures
written in a C like language. The must be compiled to be used with
a RenderMan compliant renderer like BMRT. The shader compiler
turns the procedural shader into a format the renderer can handle.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Shaders come in many forms: <B>surface shaders</B> which define how light
<I>leaving</I> a point on an object will appear, <B>volume
shaders</B> which define how light is affected as it passes <I>through</I>
an object (such as the atmosphere), light shaders which describe the
lighting of a scene,
displacement shaders, transformation shaders, imager shaders, and so forth.
<I>rendrib</I> supports all of these shader types.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
The BMRT package comes with a fairly large number of shaders, some of
which are required by the RenderMan specification and some of which
Larry has provided as bonus shaders in conjunction with example scenes.
<P>
<center>
<table width=520 border=2>
<tr>
<th> <B> RenderMan required shaders</B></th>
<th> <B>Extra shaders provided for use with example scenes</B></th>
<tr>
<td valign=top>
constant, matte
metal, shinymetal
plastic, paintedplastic
ambientlight, distantlight
pointlight, spotlight
depthcue, fog
bumpy, null
<td valign=top>
background, clamptoalpha,
dented, funkyglass,
glass, gmarbltile_polish,
noisysmoke, parquet_plank,
plank, screen,
screen_aa, shiny, stucco,
wallpaper_2stripe, wood2,
<BR>
arealight - shader for area light sources
<tr><td align=center colspan=2>
Both compiled versions and source code are provided for
all of these shaders.
</table>
</center>
<P>
Note that the .so files provided are the precompiled versions of the .sl
files and that the .so files are <B>not</B> compatible with <I>PRMan</I>,
Pixar's
RenderMan program. The .sl source files are compatible, however.
The reason for this comes from the methods used internally to
<I>rendrib</I> and
<I>PRMan</I> to produce the 3D images.
For more information see the section on
<I>Incompatibilities with PRMan</I> in the bmrt.html document in the
doc directory of the distribution.
<H3>sotell - lists the arguments to a compiled shader</H3>
Another shader related tool is sotell. This program allows the user
to parse a shader object file for its type, list of parameters, and
default settings. What this is useful for will become more apparent in
the next article which will cover the writing of shaders. We'll touch
briefly on using predefined shaders a little later in this article.
<H3>libribout.a, ri.h - RenderMan library for producing RIB files</H3>
These two files are used by developers who need to write applications
to output their RIB files. Remember, RIB files are the input files
(including references to shaders) passed to the <I>rendrib</I> program.
There are two
modellers on Linux that can output RIB files for you, SCED and AC3D, but
you may find it convenient to write your own specialized application to
output a series of specific frames. In this case (or if you are ambitious
enough to write your own modeller) you can link your program to the
libribout.a library. Your application would use then be using the
C binding to the RenderMan API. This API
is described in limited detail in the poets.ps document in the
distribution. A much better description can be found in Steve Upstill's
<I>The RenderMan Companion</I>, published by Addison-Wesley.
Developer's who write applications that use the RenderMan API will also
need to include the ri.h header file in their source code.
<H3>libsoargs.a, so.h - argument parser for compiled shaders</H3>
According to Larry's documenation (which is all I have to go by - I've
never seen the <I>PRMan</I> application myself), Pixar's <I>PRMan</I>
distribution
also comes with a linkable library for parsing compiled shaders, much
like the sotell program does in the BMRT distribution. Since the
compiled versions of the shaders differ in format Larry has provided
a similar library for use by applications that need to parse his
version of the compiled shader files. Applications which need this
feature should include the so.h header file in their source code and
link against the libsoargs.a library.
<HR width="90%">
<A NAME="examples"></A>
<H2>4. The Example Scenes</H2>
There are 8 example scenes in the distribution. These are described in the
README file in the examples directory, but for completeness sake
I'll list and describe them briefly here. The 8 RIB files are:
<UL>
<LI>cornbox.rib - a simple radiosity test scene
<LI>disptest.rib - an example of the use of complex procedural textures
<LI>dresser.rib - raytracing combined with radiosity, showing light
rays bouncing off of mirrors
<LI>limbo.rib - very cool animation of Luxo Learning to Limbo
<LI>shadtest.rib - shows shadows using lighting instead of shadow maps
<LI>smokebox.rib - example of atmospheric effects using volume shaders
<LI>teapots.rib - familiar teapot example using raytracing to show
reflections and refractions.
<LI>tpdisp.rib - more complex procedural textures
</UL>
Some of these are good examples for learning the syntax and structure of a
RIB file, others are not. If you want to learn a little about the RIB
ASCII binding you should start by taking a look at the following examples:
<UL>
<LI>cornbox.rib - probably the most commented of the examples.
<LI>disptest.rib - short header comment and the file is well
formatted making it fairly easy to follow. Also a fairly short
example so its easy to look up and learn the commands if you
use the RenderMan Specification as a reference.
<LI>shadtest.rib - good header comment, formatted; no other comments
</UL>
The rest of the RIB examples are not well formatted (probably output from
a modeller or a program linked with libribout.a). You really wouldn't
want to examine the RIB file
in these cases anyway, as their main purpose is to show features of the
Shading Language. In these cases you should take a look at the shaders
which they use. You'll have to look in the RIB to learn which shaders are
important for a given example, however. For example, the tpdisp.rib file
is an example of displacement shaders so you would look for the
Displacement commands in the RIB file to find which displacement shader
source files to examine.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
In order to explain how to use these tools in more detail I'll be using two
examples in each of the rest of the sections of this article. In some
cases I'll use examples I found in the
<A HREF="#rend-companion">RenderMan Companion</A>.
In other
cases I'll use some of Larry's examples or some of my own extremely
primitive examples. They aren't very good - but this article was is as
much a learning experience for me as it is anyone else.
<HR width="90%">
<A NAME="rib"></A>
<H2>5. The Input File - RIB Format</H2>
<H3> What is it?</H3>
RIB stands for the RenderMan Interface Bytestream. It comes in both
ASCII and binary encodings. We'll only be discussing the ASCII
version since I have very little information about the binary encodings
and BMRT doesn't come with any binary examples. All the example RIB
files are ASCII formatted.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
A RIB file is nothing more than an ASCII text file made up of a series
of RIB commands. These commands match their RenderMan API C function
counterparts almost exactly (there a few exceptions according to the official
specification). When you write a C program that
makes calls to the RenderMan API via the libribout.a library
what you get as output
is the ASCII encoding of RIB. This is why its generally easier to use
the C binding for RenderMan than to write your own ASCII RIB file.
<H3> A little about the format</H3>
The semantics of the two bindings (C and ASCII RIB) are very similar.
Both take token/value pairs as arguments. The C binding requires that
paremeter lists to functions be NULL terminated. The ASCII RIB format
does not. The names of the C procedures are prefixed with <B>Ri</B>
but the equivalent RIB commands are not.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
RIB files Support single or multiple frames of an image, allowing
(as in the limbo.rib example) animations with a single scene
description. This is a good case for using the procedural interface
to RenderMan instead of hand coding the RIB file. Its much easier
to compute the scene descriptions through a programmed loop than
to hand compute each frame using the ASCII RIB commands.
<H3> How can you create RIB files?</H3>
There are three ways to create a RIB file for use as input to one
of BMRT's renderers:
<OL>
<LI> By hand
<LI> Write a C program using the RenderMan API and link
with libribout.a
<LI> Using a modeller
<BR>
There are three modellers currently available for Linux
that can output RIB formatted files:
<UL>
<LI> SCED - a constraint based modeller, with a quite
useful CSG (constructive solid geometry) feature,
that uses an Athena Widget interface
<LI> AC3D - a polygon based modeller with an easy to use
3D (Motif-looking) interface
<LI> AMAPI - an OpenGL based modeller
</UL>
</OL>
My impression is that few people create RIB files by hand except as
examples in order to test shaders or something similar. The use
of modellers on Linux is fairly new to the general public, so at this
point I'm guessing many models are created by writing scene-specific
programs linked with the libribout.a library. Note that
developmental support for AC3D is ongoing, while AMAPI is reported
to have dropped their Linux ports. SCED's status is unknown at this
time. I've not seen any updates to it for about a year.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Lets take a look at a couple of examples. The first is a simple
RIB file from Larry's set of examples. The second is a
simple animation in C source taken from the RenderMan Companion.
<H3> Working example 1a - A sample RIB file</H3>
The simplest example from the BMRT distribution to follow is
probably shadtest.rib. It contains 3 textured objects (two spheres
and a flat plane beneath them) along with a light source. The source is
given in Listing 1.
<HR width=75%>
<FONT size=2>
<PRE>
##RenderMan RIB-Structure 1.0
version 3.03
Display "balls1.tif" "file" "rgba"
Format 480 360 -1
PixelSamples 1 1
Projection "perspective" "fov" 45
Translate 0 -2 8
Rotate -110 1 0 0
WorldBegin
LightSource "ambientlight" 1 "intensity" 0.08
Declare "shadows" "string"
Attribute "light" "shadows" "on"
LightSource "distantlight" 1 "from" [0 1 4] "to" [0 0 0] "intensity" 0.8
AttributeBegin
# Attribute "render" "casts_shadows" "none"
Color [ 0.7 0.7 0.7 ]
Surface "matte"
Polygon "P" [ -5 -5 0 5 -5 0 5 5 0 -5 5 0 ]
AttributeEnd
AttributeBegin
Translate -2.25 0 2
Color [1 .45 .06]
Surface "screen" "Kd" 0.2 "Ks" 0.8 "roughness" 0.15 "specularcolor" [1 .5 .1]
Sphere 1 -1 1 360
AttributeEnd
AttributeBegin
Translate 0 0 2
Declare "casts_shadows" "string"
Attribute "render" "casts_shadows" "shade"
Color [1 .45 .06]
Surface "screen_aa" "Kd" 0.2 "Ks" 0.8 "roughness" 0.15 "specularcolor" [1 .5 .1]
Sphere 1 -1 1 360
AttributeEnd
AttributeBegin
Translate 2.25 0 2
Declare "casts_shadows" "string"
Attribute "render" "casts_shadows" "shade"
Surface "funkyglass" "roughness" 0.06
Sphere 1 -1 1 360
AttributeEnd
WorldEnd
</PRE>
<CENTER>
</FONT>
<B>Listing 1</B>: shadtest.rib example from BMRT distribution
</CENTER>
<HR width=75%>
Items of interest in this file include:
<OL>
<LI>The values set before the WorldBegin command are used to
set camera and display parameters. These global parameters are known as
<I>options</I>. The display options can be specific to the renderer being
used. Rendering options cannot be set inside
the WorldBegin/WorldEnd commands.
<LI>Values set inside the Attribute commands are referred to as
current parameters and are object specific parameters such as
lighting, opacity and surface colors and textures.
<LI>Objects (including lights) created inside the WorldBegin/WorldEnd
commands exist only inside those commands. They are not referencable
outside of these commands.
<LI>Notice how the RIB commands contain series of literal strings
and numeric values. For example, the surface command is followed
by the name of the surface (a string) followed by a series of
token/value pairs. These tokens are variables known to the shader
being called and the values are the ones we wish to set these
variables to when the shader is invoked.
<LI>The # sign is a comment, but the double # (ie ##) is a
hint to the specific renderer. For all practical
purposes, these are also comments, since no renderers use them for
anything.
I believe the format of the hint tag has changed for the 2.3.5 version
of the BMRT renderers but I don't know what has replaced it.
<LI>The commands to create the spheres are obvious. The command
to create the plane is "polygon". The RenderMan API and BMRT
provide support for a number of primitive shapes. BMRT also supports
the ability to combine primitive shapes into more complex ones
using what is known as Constructive Solid Geometry.
<LI>The WorldEnd() command causes the scene to be output to the
display.
<LI>RIB commands may span multiple lines, although it doesn't
show this in the example.
</OL>
I removed the comment at the start of the file just to save a little
space. You should read it and try rendering this example to get
a feel for what it does. All I really wanted to do with this example
is show you what an ASCII RIB file looks like. The format of the file
gives a little clue as to the hierarchy of the commands: WorldBegin/End
encompass the Attribute commands, which in turn encompass some objects
and their textures and other descriptions. Understanding this
hierarchy can help you see the scope of definitions such as objects
or projections. This hierarchy can be more
apparent when using the RenderMan API since the code is written in
a structured language, C.
<H3> Working example 2a- A simple animation in C</H3>
The RenderMan Companion by Steve Upstill contains a fair amount
of sample code that uses the C binding to the RenderMan Interface.
Lets take a look at the <A HREF="./source/example-1b.c">source</A>
for one of these examples:
<HR width=75%>
<FONT size=2>
<PRE>
#include <ri.h>"
#define NFRAMES 10 /* number of frames in the animation */
#define NCUBES 5 /* # of minicubes on a side of the color cube */
#define FRAMEROT 5.0 /* # of degress to rotate cube between frames */
main()
{
int frame;
float scale;
char filename[20];
RiBegin(RI_NULL); /* Start the renderer */
RiLightSource("distantlight", RI_NULL);
/* Viewing transformation */
RiProjection("perspective", RI_NULL);
RiTranslate(0.0, 0.0, 1.5);
RiRotate(40.0, -1.0, 1.0, 0.0);
for (frame = 1; frame <= NFRAMES; frame++)
{
sprintf(filename, "anim%d.pic", frame);
RiFrameBegin(frame);
RiDisplay(filename, RI_FILE, RI_RGBA, RI_NULL);
RiWorldBegin();
scale=(float)(NFRAMES-(frame-1))/(float)NFRAMES;
RiRotate(FRAMEROT * frame, 0.0, 0.0, 1.0);
RiSurface("matte", RI_NULL);
/* Define the cube */
ColorCube(NCUBES,scale);
RiWorldEnd();
RiFrameEnd();
}
RiEnd();
}
</PRE>
</FONT>
<CENTER>
<B>Listing 2</B>: shadtest.rib example from BMRT distribution
</CENTER>
<HR width=75%>
As you can see the hierarchy of commands is a little more evident.
Of course, being an animation this is a more complex example. A
distant light source is defined outside all frames of the animation.
The type of camera projection is defined along with the initial
viewing transformation. This is followed by the main loop which
produces the frames of the animation.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Inside the loop each frame is defined. The display is set to
write to a file and the format of the output is set with RI_RGBA,
meaning red, green, blue and alpha channels will be output (or
in simpler terms 3 colors and 1 opacity level). How this is done
is renderer specific.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
This particular example is simplified by the use of an external
routine, ColorCube(), which actually defines the object geometry
to be used. In this case a cube is being built by ColorCube()
with its sides being colored. I left this routine as
an exercise for the reader, mostly because I always wanted to
say that to someone. For those who can't wait to figure out
how to do it themselves, the code for ColorCube() is provided
in the RenderMan Companion.
<HR width="90%">
<A NAME="basic-steps"></A>
<H2>6. Basic Steps</H2>
So now we've seen what a RIB file looks like and how they can
be created. We know we need a RIB file as input to the renderers
provided in the BMRT distribution. We know that RIB files
provide the geometry of a scene or set of frames and that shaders
are referenced by the RIB files to provide texturing aspects to
objects in those scenes.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
Ok, so now what do we do? Well, lets run through a full example
of creating, shading, previewing, and final rendering of a single
scene.
<H3>Create the RIB file</H3>
Here is a
<A HREF="./source/example-2a.c">
simple example</A>
I created on my own. It is C source that
links with the libribout.a library. When run it produces a RIB file
of a scene with a blue ball over a gray plane, lit by a single
distant light source. The source is commented so you can see
exactly what I did to create this scene. The C source is in
the same directory as the examples (or any directory directly under
the main directory of the distribution).
To compile this program you would use the following command:
<CENTER>
<table>
<tr><td>
<FONT size=2><B>
gcc -o example-2a -O example-2a.c -I../include ../lib/libribout.a
</B></FONT>
</table>
</CENTER>
To run the command simply type
<CENTER>
<table>
<tr><td>
<FONT size=2><B>
example-2a > example-2a.rib
</B></FONT>
</table>
</CENTER>
At this point you have the ASCII RIB input file needed to feed to one
of the rendering programs.
<H3>Preview the scene with rendribv and rgl</H3>
The first thing to do is examime the scene as a wireframe display
to make sure all our objects are there. We won't really be able to
tell if they are aligned properly (in front of or next to each
other) but we'll be able to see if they have the correct basic shape and
if they are within the field of view.
To preview the scene use the following command:
<FONT size=2><B>
rendribv example-2a.rib
</B></FONT>
<table>
<tr>
<td valign=top rowspan=2>
OK, everything looks as it should. We've got a sphere and a plane.
Lets add some surfaces to the objects using rgl. The sphere
should be a solid blue and the plane should be grayish.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
To preview the scene with rgl use the following command:
<BR clear=both>
<FONT size=2><B>
rgl example-2a.rib
</B></FONT>
<td>
<IMG SRC="./gx/hammel/example-2a-rendribv.gif">
<tr>
<td align=center>
<FONT size=2>
<B>Figure 2:</B> wireframe output from rendribv
</FONT>
</table>
<H3>Full rendering with rendrib</H3>
<table>
<tr>
<td valign=top rowspan=2>
Again, this is about right. The image you're looking at isn't great
due to the way I captured the image and converted it to a GIF file.
But the image is about what I was expecting. The plane is a bit
dark. But lets see what we get from the high quality renderer.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
To preview the scene with rendrib use the following command:
<BR clear=both>
<FONT size=2><B>
rendrib example-2a.rib
</B></FONT>
<td>
<IMG SRC="./gx/hammel/example-2a-rgl.gif">
<tr>
<td align=center>
<FONT size=2>
<B>Figure 3:</B> output from rgl
</FONT>
</table>
<table>
<tr>
<td valign=top rowspan=2>
Oh oh. The ball is well lit on top, but the plane is
gone. Maybe it has someting to do with lighting.
<H3>Adjusting the lighting</H3>
In the sample source I set a distant light that
sat on a line that stretches from
&lt0.0, 10.5, -6.0&gt to &lt0.0, 0.0, 0.0&gt.
This is allowing light to fall on only the top half
of the ball, but doesn't explain why the plane isn't
visible. Thats a different problem.
The sample scene C source contains the following lines:
<BR><FONT size=2>
RiLightSource(RI_DISTANTLIGHT, RI_INTENSITY,
<BR> &nbsp; &nbsp; &nbsp;
&intensity, RI_FROM, (RtPointer)from,
<BR> &nbsp; &nbsp; &nbsp;
RI_TO, (RtPointer)to, RI_NULL);
</FONT>
<td>
<IMG SRC="./gx/hammel/example-2a-rendrib.gif">
<tr>
<td align=center>
<FONT size=2>
<B>Figure 4:</B> output from rendrib
</FONT>
</table>
The variables <I>from</I> and <I>to</I> define the line on which
the distant light exists. To make this light shine more on the front
of the ball we can move the to point out to -600 on the Z axis.
This lights up the ball much better, but the plane is still invisible.
We can also increase the value of the <I>intensity</I>
variable from 0.6 to 1.0.
<BR clear=both>
&nbsp; &nbsp; &nbsp;
But whats wrong with the plane? Where did it go? The answer lies
in the surface texture used.
<H3>Test with standard shaders</H3>
The original version of the sample scene used a <I>matte</I>
surface shader for the plane. When rendered with the single distant
light the reflectivity of the surface made it basically invisible
from the angle of view that we had set with our initial translation.
<table>
<tr>
<td valign=top rowspan=2>
A first guess was to try adding a spotlight above
the surface, which can be seen in the
<A HREF="./source/example-3a.c">updated version of the
sample source</A>.
This had no effect, so I tried another shader - the same matte
shader used on the sphere. Viola! The surface shows up,
including the newly added spotlight. Way cool.
<td>
<IMG SRC="./gx/hammel/example-3a-rendrib.gif">
<tr>
<td align=center>
<FONT size=2>
<B>Figure 5:</B> look boss - da plane! da plane!
</FONT>
</table>
<P>
<table>
<tr>
<td valign=top>
Lets look at two more examples:
<UL>
<LI>Another plain sphere over a plane with a back wall
<LI>Same scene with textured surfaces
</UL>
The RIB file for
<A HREF="./source/example-4a.rib">
example-4a</A>
is probably more simplistic than the example-2a
but with better results. The difference is the use of
well placed spotlights. Notice the way the spotlight is
defined:
<BR><Font size=2><B>
&nbsp;&nbsp;
LightSource "spotlight" 1 "from" [1 3 -4]
<BR>&nbsp;&nbsp;&nbsp;&nbsp;
"to" [0 0 0] "intensity" 15
</B></FONT>
<BR>
This is just like the distant light used in example-2a.
This time two lights are used, and they are spotlights
instead of a distant light. The effect of well placed
spotlight shows in the realism of this image.
<td valign=top>
<CENTER>
<IMG SRC="./gx/hammel/example_4a.jpg" WIDTH=263 HEIGHT=243>
<BR>
<B>Figure 6</B>: example 4a.jpg
</CENTER>
<P>
<tr>
<td valign=top>
The next image is a little hard to see. I didn't have
time to adjust the brightness (well I tried using xv
but it kinda mucked up the image and I didn't have time
to rerender Paul's RIB file). What it shows is the same
scene as Figure 6 except this time textures have been
applied to the sphere, the wall and the floor. The
texture on the sphere is a glass stucco. The floor has
a wood texture and the wall has a wallpaper effect.
The sphere is interesting in that it uses a glass surface
shader with a stucco displacement map. The displacement
map alters the actual shape of the sphere causing
the slightly bumpy effect that is (somewhat) visible in Figure 7.
All of the textures are apparent from examination of the
<A HREF="./source/example-4b.rib">RIB file</A>.
All of the shaders used in this example are available
in the 2.3.5 release of BMRT. It is left as an exercise
for the reader to rerender and adjust for the darkness
of the image. (Thats also something I always wanted to
say.)
<td valign=top>
<CENTER>
<IMG SRC="./gx/hammel/example_4b.jpg" WIDTH=241 HEIGHT=227>
<BR>
<B>Figure 7</B>: example 4b.jpg
</CENTER>
<P>
</table>
At this point there are only two things left to do:
<UL>
<LI>Write scene specific shaders
<LI>Render final version
</UL>
Simple enough. Except the first one of these will take up an entirely
seperate article. Next we'll introduce you to what shaders are without
going into depth on how to write them.
Stay tuned next month when we'll cover how to write shaders.
<HR width="90%">
<A NAME="shaders"></A>
<H2>7. Shaders</H2>
<H3> What exactly is a shader?</H3>
According to to the RenderMan Companion,
<BLOCKQUOTE>
A shader is the
part of the rendering program that calculates the appearance
of visible surfaces in the scene. In RenderMan, a shader
is a procedure written in the RenderMan Shading Language
used to compute a value or set of values (e.g., the
color of the surface) needed during rendering.
</BLOCKQUOTE>
In my language: a shader puts the surface on an object.
<H3> How does it fit into a RIB?</H3>
The shaders are external procedures referenced at rendering time
by the rendering engine (in BMRT that would be <I>rendrib</I>).
The C binding to RenderMan calls a shader with the <I>RiSurface</I>
call. The following lines in the sample source used in the previous
section apply the matte surface shader to the sphere and plane:
<CENTER>
<FONT size=2><B>
RiSurface("matte", RI_NULL);
</B></FONT>.
</CENTER>
This causes the following line to be added to the
ASCII RIB file output by the program when it is linked with libribout.a:
<CENTER>
<FONT size=2><B>
Surface "matte"
</B></FONT>.
</CENTER>
Obviously things can get much more complex than this. But at least
you'll have some way of identifying the shaders in the example
scene files.
<H3> Compiling a shader</H3>
You should keep in mind that the shaders you write in the
RenderMan Shading Language have to be compiled before they can
be used. Compiling shaders is very straightforward. To compile
the matte.sl shader into the matte.so file you would use a line
like:
<CENTER>
<FONT size=2><B>
slc matte.sl
</B></FONT>.
</CENTER>
<HR width="90%">
<A NAME="closing"></A>
<H2>7. Closing</H2>
There aren't that many resource devoted to BMRT or RenderMan on the
net just yet. Most can be found by starting at
<A HREF="http://pete.cs.caltech.edu/RMR/index.html">
The RenderMan Repository</A> -
(http://pete.cs.caltech.edu/RMR/index.html).
There is also a good collection of RenderMan shader information at
<A HREF="http://www.cgrg.ohio-state.edu/~smay/RManNotes/index.html">
RManNotes</A> -
(http://www.cgrg.ohio-state.edu/~smay/RManNotes/index.html).
<BR clear=both>
&nbsp; &nbsp; &nbsp;
So, thats about it. You've seen the basics. You've been introduced to the
tools. Now you just have to do something with them. Larry's
<A HREF="http://www.seas.gwu.edu/student/gritz/bmrt.html">
BMRT Web</A>
pages contain links to intersting images created with BMRT. That should
provide some motivation. I'll be playing with it all next month trying
to learn about the RenderMan Shading Language for the April Graphics Muse
column. If you come up with anything interesting feel free to drop me a
note.
<P>
<table width=100%>
<tr>
<td bgcolor="#000000" cellpadding=0 cellspacing=0 valign=top>
<IMG SRC="../gx/hammel/cleardot.gif" ALT="indent" ALIGN="left"
HSPACE="0" WIDTH="0" HEIGHT="0"></td>
<tr>
<td>
<A NAME="ordering-info"></A>
Ordering information:
<table>
<tr>
<td>Pixar Animation Studios
<BR>Attn: Katherine Emery
<BR>1001 W. Cutting Blvd.
<BR>Richmond, CA 94804
</table>
Specify you are ordering the "RenderMan Specification". It costs
$20US. Note: I have no association with Pixar (but I can dream, can't
I?).
<tr>
<td>
<A NAME="rend-companion"></A>
Upstill, Steve <I><B>The RenderMan Companion</B>
A Programmer's Guide to Realistic Computer Graphics</I>.
Addison-Wesley 1992
<tr>
<td>
<!-- Copyright notices for this article -->
The RenderMan&reg Interface Procedures and RIB Protocol are
&copy Copyright 1988, 1989, Pixar. All rights reserved.
RenderMan&reg is a registered trademark of Pixar.
<P>
Blue Moon Rendering Tools are
&copy Copyright 1990-1995 by Larry I. Gritz. All rights reserved.
</td>
<tr>
<td bgcolor="#000000" cellpadding=0 cellspacing=0 valign=top>
<IMG SRC="../gx/hammel/cleardot.gif" ALT="indent" ALIGN="left"
HSPACE="0" WIDTH="0" HEIGHT="0"></td>
</table>
<table width=100%>
<tr>
<td align=right>
<FONT size=1>
&copy 1996 by <A HREF="mailto:mjhammel@csn.net">Michael J. Hammel</A>
</FONT>
</table>
</BODY>
</HTML>