version 2.3.6
revised 1 December 1997
Larry I. Gritz
gritzl@acm.org
Blue Moon Systems
200 Kimblewick Drive
Silver Spring, MD 20904
This document explains how to use the Blue Moon Rendering Tools (BMRT), which are a set of rendering programs and libraries which adhere to the RenderMan(TM) standard as set forth by Pixar. This document is intended for the reader who is familiar with the concepts of computer graphics and already is fluent in both the RenderMan procedural interface and the RIB archival format. It is not designed to teach the RenderMan interface, but to give the reader documentation on how to use this implementation of the standard. For more detailed information about the RenderMan standard, you should see The RenderMan Companion, by Steve Upstill, or the official RenderMan Interface Specification, available from Pixar. Both of these texts are fully detailed and clearly written, and no attempt will be made here to duplicate the information in these references.
The first version of the RenderMan standard described a procedural interface, i.e. the function calls for a library which could be linked to a modeling program. When the procedures are invoked, information is passed to the renderer. Later versions of the RenderMan interface also defined the RenderMan Interface Bytestream, or RIB protocol. RIB provides an ASCII interface to a renderer which supports the RIB protocol.
The Blue Moon Rendering Tools described in this document adhere to the RenderMan standard. The parts you'll most likely use are outlined below:
The RenderMan Interface Procedures and RIB Protocol are:
Copyright 1988, 1989, Pixar. All rights reserved. RenderMan is a registered trademark of Pixar.
Pixar's RenderMan Interface Specification document stipulates that you may write modeling programs that incorporate the RenderMan procedure calls or that output RIB, royalty-free, as long as you include the copyright notice above. Their document also allows for a no-charge license for anyone who wishes to write a renderer that executes the Pixar RenderMan procedure calls or RIB requests. Such a license exists for the BMRT.
Please note that all of the Blue Moon Rendering Tools described in this document are:
Copyright 1990-1996 by Larry I. Gritz. All rights reserved.
This software is not in the public domain, but it is "shareware". This means you can get a copy and evaluate it for free, and keep using it for free if you are a student or noncommercial user. If you decide that you want to use it for commercial purposes, you need to register. Please consult the "License" file that comes with the software for more information. I reserve the right to change the licensing of future versions of BMRT at any time and without notice.
Unregistered users may use the software for evaluation purposes for as long as they want. Unregistered users MAY NOT use this software for commercial gain of any kind, including profiting from any images or animations created by this software. Registered users may distribute any images or animations created by this software in any means desired (including for commercial gain), as long as each copy credits me as follows:
Rendering Software... Blue Moon Rendering Tools
I understand that this is often not practical (for example, for feature films). I trust you'll do your best to give proper credit where possible.
Nobody, not even registered users, may distribute this software in any way without written authorization from me. This is mostly so that I can ensure quality control and keep track of who is using the software.
You may wish to write a C or C++ program which makes calls to the procedural interface, resulting in the output of RIB. The resulting RIB may be piped directly to another process (such as a previewer), or redirected to a file for later rendering. The library libribout.a does this. This library provides a `C' language binding for the RenderMan Procedural Interface.
You can link libribout.a in the usual way to your `C' programs which make the various Ri procedure calls. The following example shows how to link with this library on a typical Unix machine:
cc myprog.c -o myprog -lribout -lm
This will result in an executable, myprog, which outputs RIB requests to standard output. This may be redirected to a specific RIB file as follows:
myprog > myfile.rib
Remember that the RiBegin statement usually only takes the argument RI_NULL:
RiBegin (RI_NULL);
The default of sending RIB to stdout can be overridden by providing a filename to the RiBegin statement in your program. For example, suppose your program contains the following statement instead:
RiBegin ("myfile.rib");
In this case, the RIB requests corresponding to the Ri procedure calls will be sent to the file "myfile.rib" rather than to standard output. In addition, if the filename you specify is one of "rendrib", "rendribv", or "rgl", the RIB output will be piped directly to the appropriate renderer without creating an intermediate RIB file.
Remember to tell the C compiler where the ri.h and
libribout.a files are, or it won't be able to find them.
On most platforms, BMRT is also distributed with a dynamic
library, libribout.so (or perhaps
libribout.so.2.3.6). This library performs the same
function as libribout.so, but is a dynamic library, which
means that it is shared by all programs that link against it, rather
than being separately copied into every resulting executable needs the
library. Please consult the manual pages to your C compiler, or your
local system administrator, for the fine points of using dynamic
libraries.
Once a RIB file is created, one may use rendribv to display a color wireframe preview of the scene. Geometric primitives are displayed as wire frame vectors, without shading or hidden surface removal performed. The rendribv program will display its preview on any system running the X11 windowing system. Obviously, the X11 system needs to be running.
The following command will display a wireframe preview of the animation in an X11 window:
rendribv myfile.rib
There are several command line options which can be given in any
order, but prior to the filename. The following sections describe
these options. The different options may be used together when they
are not contradictory.
If no filename is specified to rendribv, it will attempt to read RIB from standard input (stdin). This allows you to pipe output of a RIB process directly to rendribv. For example, suppose that myprog dumps RIB to its standard output. Then you could display RIB frames from myprog as they are being generated with the following command:
myprog | rendribv
The RIB file which you specify may contain either a single frame or
multiple frames (if it is an animation sequence). The rendribv
program is designed primarily for previewing animation sequences of
many RIB frames. The default is to display all of the frames
specified in the RIB file as quickly as possible. All of the frames
are displayed sequentially and in the same X11 window, so that it
gives the illusion of previewing the completed animation.
When the last frame is displayed, it will remain in the window. If you hit the ESC key (with the mouse in the drawing window), rendribv will terminate. If you click on the window with the left mouse button, the entire RIB sequence will be played again.
Format statement is given in the
RIB file. If you want a different size window, you can override the
default by using the -res command line argument. For
example, the following will display the myfile.rib file in a 320 x 240
pixel window:
rendribv -res 320 240 myfile.rib
The -res option requires two numerical arguments to specify the
horizontal and vertical resolutions, respectively.
Note that if the RIB file contains a Format statement which
explicitly specifies the image resolution, then the -res option will
be ignored and the window will be opened with the resolution specified
in the Format statement.
Sometimes you may want to preview only a subset of frames from a
multi-frame RIB file. You can do this by using the
-frames command line option. This option takes two
integer arguments: the first and last frame numbers to display. For
example,
rendribv -frames 10 20 myfile.rib
This example will preview only frame numbers 10 through 20. If you are going to use this option, it is recommended that your frames be numbered sequentially starting with 0 or 1.
-sync command line option. This option takes a single
numerical argument, the desired number of frames per second. The
following example instructs rendribv to display a RIB file as
closely as possible to 30 frames per second:
rendribv -sync 30 myfile.rib
The rendribv program checks the system clock at the beginning and
ending of its drawing of each frame. If it took less than the
allotted time to draw the frame, it will pause until it is time to
draw the next frame. If it took too long, it may choose to skip the
next frame in the RIB file. The result will be that the overall
motion will be timed properly, though it may appear jerky in places
due to the fact that some frames may be skipped in order to keep up
with the overall timing.
-nowait command line option to fix this:
rendribv -nowait myfile.rib
This command will open the window, display all frames in the RIB file,
and terminate immediately without waiting for you to hit the ESC key.
-sync option. One
way of speeding up the rendering time is to control how finely the
curved surface primitives are diced. You can do this with the
-rd command line option, which stands for "relative
detail." This option takes a single numerical argument between 0 and
1. For example:
rendribv -sync 30 -rd 0.75 myfile.rib
The lower the value, the fewer polygons will be used to
approximate curved surfaces. Using a value of 1 will result in
identical results as if you did not use the -rd option at
all. Good values to try are 0.75 and 0.5. If you go below 0.25, the
curved surface primitives may become unrecognizable, though they will
certainly be drawn quickly.
IMPORTANT NOTE: the -rd option can only speed up the
rendering of curved surface primitives (e.g. spheres, cylinders,
bicubic patches). It WILL NOT speed up the drawing of polygons. If
your model contains too many polygons to be drawn quickly, the
-rd option will not help you.
By default, rendribv displays geometric primitives as
colored vectors on a grey background. You can override the foreground
and background colors using the -fg and -bg
options. Each option is followed by three floating point numbers
ranging from 0 to 1. These numbers indicate the red, green, and blue
intensity of the color, respectively. The following example causes
the display to be black vectors on a white background:
rendribv -fg 0 0 0 -bg 1 1 1 myfile.rib
Note that the default is for all vectors to display using the colors
of the geometric primitives (as specified by Color directives or
shaders). Sometimes this is confusing, and you just want a black and
white display of the vectors. You can use the -nocolor
command line option to do this:
rendribv -nocolor myfile.rib
This results in all vectors being drawn in the default foreground
color. Note that this is a bit faster than the color display, so it
may speed up animation previews.
-ps command line option. This option is followed by
a single argument which gives the filename to which the PostScript is
dumped:
rendribv -ps dump.ps myfile.rib
-nocolor is used. Sometimes the colors aren't too smart,
so don't rely on them to be correct. It's just to make it easier to
tell objects apart.
Once a RIB file is created, one may use the rgl program to display a preview of the scene. Geometric primitives are displayed as Gouraud-shaded polygons with simple shading and hidden surface removal performed. Note that not all platforms will support rgl.
The following command will display a preview of the animation in an OpenGL window:
rgl myfile.rib
There are several command line options which can be given (listed in
any order, but prior to the filename). The following sections
describe these options. The different options may be used together
when they are not inherently contradictory.
If no filename is specified to rgl, it will attempt to read RIB from standard input (stdin). This allows you to pipe output of a RIB process directly to rgl. For example, suppose that myprog dumps RIB to its standard output. Then you could display RIB frames from myprog as they are being generated with the following command:
myprog | rgl
The RIB file which you specify may contain either a single frame or
multiple frames (if it is an animation sequence). The rgl
program is designed primarily for previewing animation sequences of
many RIB frames. The default is to display all of the frames
specified in the RIB file as quickly as possible.
When the last frame is displayed, it will remain in the window. If you hit the ESC key (with the mouse in the drawing window), rgl will terminate. If you click on the window with the left mouse button, the entire RIB sequence will be played again.
Though the output of rgl is in color, it is important to note that it is not designed to be a particularly accurate preview of a rendered image. It really cannot be, since there is no way for rgl to know very much about the types of shaders which you are using. It does a fairly good job of matching ambient, point, distant, and spot lights. But it can't figure out area lights or any nonstandard light source types. Also, every surface is displayed as if it were "matte", regardless of the actual surface specification. The colors for the polygons are given by the last RiColor call made, or can be specified on a per-vertex basis using the "Cs" parameter.
The default resolution of the window in which the preview is
displayed is 640 horizontal pixels by 480 vertical pixels. This
resolution is used when no explicit Format statement is
given in the RIB file. If you want a different size window, you can
override the default by using the -res command line
argument. For example, the following will display the myfile.rib file
in a 320 x 240 pixel window:
rgl -res 320 240 myfile.rib
The -res option requires two numerical arguments to
specify the horizontal and vertical resolutions, respectively. Note
that if the RIB file contains a Format statement which explicitly
specifies the image resolution, then the -res option will
be ignored and the window will be opened with the resolution specified
in the Format statement.
Sometimes you may only want to preview a subset of frames from a
multi-frame RIB file. You can do this by using the
-frames command line option. This option takes two
integer arguments: the first and last frame numbers to display. For
example,
rgl -frames 10 20 myfile.rib
This example will preview only frame numbers 10 through 20. If you are going to use this option, it is recommended that your frames be numbered sequentially starting with 0 or 1.
When previewing a series of frames for an animation, it is often
necessary to synchronize the display of frames to the clock in order
to check the timing of the animation when it is played back at a
particular number of frames per second. The default action of
rgl is to display the frames as fast as possible. You can
override this, causing rgl to try to display a particular
number of frames per second, by using the -sync command
line option. This option works just like the -sync
option for rendribv (see the rendribv section for
details). The following example displays a RIB file as closely as
possible to 30 frames per second:
rgl -sync 30 myfile.rib
By default, the last frame will stay in the drawing window until you hit the ESC key. Sometimes you may wish rgl to terminate immediately after displaying the last frame in the sequence (for example, if it is part of an automated demo). You can use the -nowait command line option to fix this:
rgl -nowait myfile.ribThis command will open the window, display all frames in the RIB file, and terminate immediately without waiting for you to hit the ESC key.
Curved surface primitives are displayed by rgl as grids of
polygons. Just like for rendribv, you can speed up
rgl by changing the refinement detail that it uses to convert
curved surfaces to polygons by using the -rd command line
option. This option takes a single numerical argument, generally
between 0 and 1. For example:
rgl -sync 30 -rd 0.5 myfile.ribThe lower the value, the fewer polygons will be used to approximate curved surfaces. Using a value of 1 will result in identical results as if you did not use the
-rd option at all. Good values
to try are 0.75 and 0.5. If you go below 0.25, the curved surface
primitives may become unrecognizable, though they will certainly be
drawn quickly. If you use values larger than 1, even more polygons
than usual will be used to approximate the curved surfaces.
IMPORTANT NOTE: the -rd option can only speed up the
rendering of curved surface primitives (e.g. spheres, cylinders,
bicubic patches). It WILL NOT speed up the drawing of polygons. If
your model contains too many polygons to be drawn quickly, the
-rd option will not help you.
The following command line options, which were introduced in release 2.3.6, alter the way in which rgl creates and displays images:
-dumprgba option
instead causes the resulting preview image to be saved to a TIFF file.
The filename of the TIFF file is taken from the Display
RIB command in the file itself, or ri.tif if no
Display command is present in the RIB file. The
-dumprgbaz option does the same thing as
-dumprgba, but also saves the z buffer values to a file.
The z values are saved in the same zfile format used by Pixar's
PhotoRealistic RenderMan, and the name of the file is also
taken from the Display RIB command, substituting "zfile"
for "tif" in the filename.
-dumprgba or
-dumprgbaz, causes the image file(s) to be created
without ever opening a window to the screen. This is handy for
using rgl as a low quality batch renderer.
Since rgl is an OpenGL-based polygon previewer, it cannot possibly support all the features of the RenderMan Interface which would be supported by other types of renders. This section outlines the features which are not fully supported by rgl.
The rendrib program is a high-quality renderer incorporating the techniques of ray tracing and radiosity to make (potentially) very realistic images. This renderer supports not only the required features of the RenderMan Interface, but also many of the more advanced Optional Capabilities, such as: ray tracing, radiosity, solid modeling, depth of field, motion blur, area light sources, texture mapping, environment mapping, displacements, volume and imager shading, and support of the RenderMan Shading Language.
The format for invoking rendrib is as follows:
rendrib [options] myfile.rib
Usually, this will result in one or more TIFF image files to be written to disk. If the RIB file specified framebuffer display (as opposed to file), or you override with the -d flag, the resulting image will be displayed as a window on your screen. When the rendering is complete, rendrib will pause. Hitting the ESC key will terminate. Alternately, if you hit the 'w' key, the image in the window will be written to a file (using the filename specified in the RIB file's Display command).
Format or
PixelSamples statements, then the values specified by
these statements will be used to determine the image resolution and
sampling rate for your image. If these statements are not in the RIB
files, the default values will be used (640x480 pixels and 2x2
sampling, respectively). You can change the defaults by using the
-res and -samples command line arguments.
Each take two arguments giving the x and y resolution or sampling
rates. For example, if you want your image to be rendered at 320x240
resolution with only 1 sample per pixel, you can invoke
rendrib in the following way:
rendrib -res 320 240 -samples 1 1 myfile.rib
Note that if the RIB file contains a Format or
PixelSamples statement which explicitly specifies the
image resolution, then the -res or -samples
options will be ignored and the image will be rendered using the
values in the RIB file.
An alternative to setting a fixed number of samples per pixel is to use variance-based sampling. This method samples highly only in regions with high variance. To invoke this option, you can either put the PixelVariance directive in your RIB file, or use the -var command line option. This option takes three arguments: the desired maximum variance, the minimum number of samples per pixel, and the maximum number of samples per pixel. Here is an example:
rendrib -res 320 240 -var 0.01 4 32 myfile.ribNote that this example set the maximum variance in a pixel to 0.01, which totally overrides the
PixelSamples directive or
-samples option. In this example, all pixels will have
at least 4, and at most 32 samples. For most effective variance-based
sampling, you need to properly set the minimum and maximum numbers of
samples per pixel. This is explained in the "implementation-specific
Options" section of this chapter.
You can specify only a crop window to be rendered using the -crop option. It takes four arguments which are the same as the arguments to the CropWindow RIB directive. This can be used to render only a portion of an image. The default is to render the entire image. Here is an example:
rendrib -res 320 240 -crop 0.25 0.6 0.5 1 myfile.rib
By default, rendrib creates image files, and the only text output that rendrib creates is a periodic update of the current scanline which is being rendered and a notice when the rendering is complete. Errors are of course output if there are problems with the RIB file. There are two command line switches which can increase the amount of feedback which rendrib provides.
The -v option (which stands for verbose) takes no
arguments. Its result is to inform you of all RIB files which are
read and all shaders which are loaded. For example:
rendrib -v myfile.rib
The -stats option will print rendering statistics
after the image is completed. Statistics include data such as total
number of rays cast, percentage of shadow rays which were occluded,
memory usage, and so on. For example:
rendrib -stats myfile.rib
You can combine the -v and -stats options
if you want.
Sometimes you may only want to render a subset of frames from a
multi-frame RIB file. You can do this by using the
-frames command line option. This option takes two
integer arguments: the first and last frame numbers to display. For
example,
rendrib -frames 10 10 myfile.rib
This example will render only frame number 10 from this RIB file. If you are going to use this option, it is recommended that your frames be numbered sequentially starting with 0 or 1.
By default, rendrib calculates images using the rendering technique of ray tracing. Ray tracing alone does no energy balancing of the scene. In other words, it does not account for interreflected light. However, rendrib supports radiosity, which is a method for performing these calculations. You can instruct rendrib to perform a radiosity pass prior to the ray tracing by using the -radio command line switch. This command is followed by a single numerical argument, which is the number of radiosity steps to perform. For example, the following command causes rendrib to perform 50 radiosity steps prior to forming its image:
rendrib -radio 50 myfile.ribIf the energy is balanced in fewer steps than you specify, rendrib will skip the remaining steps (saving time). Depending on your scene, the radiosity calculations can take a long time, but they are independent of the final resolution of your image.
By default, rendrib calculates the visibility between geometric elements by casting a minimum of one ray between the two elements. You can increase this number to get better accuracy (but at a big decrease in speed) by using the -rsamples option. This option takes a single integer argument. The minimum number of rays used to determine visibility will be the square of this argument. For example, the following command will perform a radiosity pass of 100 steps, using a minimum of 4 sample rays per visibility calculation:
rendrib -radio 100 -rsamples 2 myfile.rib
Several implementation-specific options and attributes alter the way in which radiosity is calculated. These are discussed in the following sections.
By default, any fully rendered frames are sent to a TIFF image file. However, you can override this and render directly to the display using the -d command line option. This option only works some platforms. Here is an example:
rendrib -d -res 256 256 -samples 1 1 myfile.ribYou can specify an optional integer argument to the -d switch, which causes the scanlines to be interleaved, giving you a kind of progressive refinement display. For example,
rendrib -d 8 -res 256 256 -samples 1 1 myfile.rib
will display every 8th scanline first (making a very quick, but blocky image), then compute every 4th scanline, then every 2nd, and so on, until you get the final image. This is extremely useful if you want to quickly see a rough version of the scene.
You can also specify the position of the window on your display using the -pos option. For example, to ensure that your window's upper left corner falls on pixel (300, 200), try:
rendrib -d 8 -pos 300 200 myfile.rib
When you submit a RIB file for rendering, the image files will have filenames as specified in the RIB file with the Display directive. If a file already exists with the same name, the original file will be overwritten with the new image. Sometimes you may want to avoid this. Using the -safe command line option will abort rendering of any frame which would overwrite an existing disk file. This is mostly useful if you are rendering many frames in a sequence, and do not want to overwrite any frames already rendered. Here is an example:
rendrib -safe -frames 100 200 myfile.ribThis example will render a block of 100 frames from the RIB file, but will skip over any frames which happen to already have been rendered.
Try this out for amusement:
rendrib -ascii myfile.rib
This will produce an ASCII (yes, exactly what you think) representation of your scene to the terminal window!
Option name paramsWhere name is the option name, and params is a list of token/value pairs which correspond to this option. Remember that options apply to an entire rendered frame, while attributes apply to specific pieces of geometry. Implementation-specific attributes are discussed in the following subsection. The various nonstandard options are listed below.
Remember that all of BMRT's renderers (rendrib, rendribv, and rgl) read from a file called .rendribrc both in the local directory where it is run, and also in your home directory. This file can be plain RIB, which means that if you want to set any defaults of the options discussed below, you can just put the Option or Attribute lines in this file in your home directory.
Option "render" "minsamples" [8] "maxsamples" [64]This sets the minimum and maximum number of samples per pixel, for scenes when the pixel variance metric is used. This only works if the RIB file contains a PixelVariance statement, but not a
PixelSamples statement. These numbers are both integers.
Option "render" "max_raylevel" [4]This sets the maximum number of recursive rays that will be cast between reflectors and refractors. This has no effect if there are no truly reflective or refractive objects in the scene (in other words, shaders which use the trace() function). This number is an integer.
Option "render" "minshadowbias" [0.01]The "minshadowbias" option is the minimum distance that one object has to be in order to shadow another object. This keeps objects from self-shadowing themselves. If there are serious problems with self-shadowing, this number can be increased. You may need to decrease this number if the scale of your objects is such that 0.01 is on the order of the size of your objects. In general, however, you will probably never need to use this option if you don't notice self-shadowing artifacts in your images.
Option "render" "prmanspecular" [1]Pixar's PRMan does not use the SL specular() function as listed in the RI standard. BMRT uses the standard function, which results in specular highlights looking very different in the two renderers. This option, which takes an integer, causes BMRT's specular function to behave much more like PRMan's with a value of 1, and uses the specular function from the standard when given a value of 0. The default used to be zero (standard), but starting with BMRT 2.3.4, the default is 1 (PRMan). Use this option with a value of 0 in order to revert to the old (RI standard) behavior.
Option "radiosity" "steps"In addition to using the -radio command line option to rendrib, you can specify the number of radiosity steps with this option. Setting steps to 0 indicates that radiosity should not be used. Nonzero indicates that radiosity should be used (with the given number of steps) even if the -radio command line switch is not given to rendrib.
Option "radiosity" "minpatchsamples"Just like the -rsamples command line option to rendrib, this option lets you set the minimum number of samples per patch to determine radiosity form factors. Actually, the minimum total number of samples per patch is this number squared (since it is this number in each direction). In some cases, the render will decide to use more samples, but this is the minimum.
Option "searchpath" "texture" "/usr/local/textures" Option "searchpath" "include" "path1:path2:path3" Option "searchpath" "shader" "/u0/lg/shaders"
Option "runtime" "verbosity" verbThis option controls the same output as the
-v and
-stats command line options. The verb parameter is a
string which controls the level of verbosity. Possible values, in
order of increasing output detail, are: "silent", "normal", "stats",
"debug".
Option "limits" "texturememory" [k]This option controls sets a texture cache size to k, which is an integer, measured in Kbytes. The renderer will try to keep no more than this amount of memory tied up with textures. Setting it low keeps memory consumption down if you use many textures. But setting it too low may cause thrashing if it just can't keep enough in cache. The default is 10000 (i.e. 10 Mbytes).
Option "limits" "geommemory" [k]Analogous to the texturememory option, this sets a limit to the amount of memory used to hold the diced pieces of NURBS, bicubics, and displaced geometry. It is an integer, giving a measurement in Kbytes. The default is 40000 (i.e. 40 Mbytes). This can keep your memory consumption down for large scenes, but setting it too low may cause you to continually be throwing out and regenerating your NURBS or displaced surfaces.
Attribute name paramsWhere name is the attribute name, and params is a list of token/value pairs which correspond to this attribute. Remember that options apply to an entire rendered frame, while attributes apply to specific pieces of geometry. The various nonstandard attributes are listed below.
Attribute "radiosity" "averagecolor" [color]By default, the radiosity renderer assumes that the diffuse reflectivity of a surface is the default color value (set by Color) times the Kd value sent to the shader for that surface. For the lighting calculations to be accurate, the reflective color should be the average color of the patch. For surfaces with a solid color, this is fine. However, some surface shaders create surfaces whose average colors have nothing to do with the color set by the Color directive. In this case, you should explicitly set the average color using the attribute above. You may have to guess what the average color is for a particular surface.
Attribute "radiosity" "emissioncolor" [color]All surfaces which are not light sources (Lightsource or AreaLightsource) are assumed to be reflectors only (i.e. they do not glow). If you want a piece of geometry to actually emit radiative energy into the environment, you can either declare it as an AreaLightSource, or you could declare it as regular geometry but give it an emission color (see above). The tradeoffs are discussed further in the radiosity section of this chapter.
Attribute "radiosity" "patchsize" ps "elemsize" es "minsize" msThis attribute tells rendrib how finely to mesh the environment for radiosity calculations. The statement above instructs to chop all geometry into patches no larger than ps units on a side. Each patch is then diced into elements no larger than es units on a side. As a result of analyzing the radiosity gradients, elements may be diced even finer, but a particular element will not be diced if its longest edge is shorter than ms units. The smaller these numbers, the longer the radiosity calculation will take (but it will be more accurate). This attribute can be used to set these numbers on a surface-by-surface basis (i.e. different surfaces in the scene may have different dicing rates). The units ps, es, and ms represent are measured in the current (i.e. local) coordinate system in effect at the time of this Attribute statement.
Attribute "radiosity" "zonal" zonalvalThis attribute controls which radiosity calculations are performed on surfaces. This can be set on a surface-by-surface basis. Possible values for zonalval are shown below, in order of increasing computational cost:
Attribute "render" "casts_shadows" shadowvalThis attribute controls how surfaces shadow other surfaces. Possible values for shadowval are shown below, in order of increasing computational cost:
Attribute "render" "truedisplacement" [onoff]Takes an integer argument, which if nonzero will make this primitive be diced and displaced using its displacement shader (if any). Only a displacement shader can move the diced geometry -- altering "P" in a surface shader will not move the surface, only the normals. Using a displacement shader without this attribute also only results in the normals being modified, but not the surface. Be sure to set displacement bounds if you displace! Please see the section on "limitations of rendrib" for details on the limitations placed on true displacements.
Attribute "displacementbound" "coordinatesystem" [space] "sphere" [rad]For truly displaced surfaces, specifies the amount that its bounding box should grow to account for the displacement. The box is grown rad (a float) units in all directions, expressed in the coordinate system space (a string). This works just like the nonstandard option of the same name in PRMan.
Attribute "render" "patch_maxlevel" [maxlevel] "patch_minlevel" [minlevel]Takes an integer argument giving the maximum (or minimum) subdivision level for bicubic and NURBS patches. These patches are subdivided based on the screen size of the patch and their curvature. This attribute will split the patches into at least (minlevel x minlevel) and at most (maxlevel x maxlevel) subpatches. The default is min=1, max=256. In general, you shouldn't ever need to change this, but occasionally you may need to set a specific subdivision rate for some reason.
Attribute "render" "patch_multiplier" [float]Takes an float argument giving a multiplier for the dicing rate that BMRT computes for displaced surfaces and for certain curved surfaces which are subdivided. The default is 1.0. Smaller values will make the scene render faster and using less memory, but may produce a more faceted appearance to certain curved surfaces. Larger values will make more accurate surfaces, but will take longer and more memory to render. The default is probably just right for 99% of scenes, but occasionally you may need to tweak this.
Attribute "light" "shadows" "on" Attribute "light" "shadows" "off"Turns the automatic ray cast shadow calculations on or off on a light-by-light basis. This attribute can be used for any LightSource or AreaLightSource which is declared. For example, the following RIB fragment declares a point light source which casts shadows:
Attribute "light" "shadows" "on" LightSource "pointlight" 1 "from" [ 0 10 0 ]
Attribute "light" "nsamples" [n]Sets the number of times to sample a particular light source to n, an integer (default = 1). This is only useful for an area light which is being undersampled -- i.e. its soft shadows are too noisy. By increasing the number of samples, you can reduce the noise by increasing sampling of this one light, independently of overall PixelSamples.
The renderer is extensible, allowing the addition of more surface, light, displacement, and volume shaders. The writing of shaders is beyond the scope of this document. Nonstandard shaders may be added by writing shaders in the Shading Language and using the Shading Language Compiler to compile the shaders. The next chapter describes how to use the Shading Language Compiler.
The purpose of the RenderMan standard is to allow one to specify the description of a scene without having to worry about how to render it. Thus, no mention is made in the standard of any particular rendering method. A particular implementation of the standard may support any one (or many) of the following: wireframe; flat shaded, Gouraud shaded, or Phong shaded z-buffered polygons; A-buffer; REYES; ray tracing; radiosity; or any other rendering method. Since this renderer stems largely from my own research in the area of illumination, it incorporates many of the latest advances in global illumination and rendering technology.
The default rendering method used by this renderer is ray tracing. Of course, if you only use standard surfaces and light sources, the results will not be very dramatic. But the shaders which use the trace() function can cast reflection and refraction rays. Light sources which cast ray-traced shadows can be added automatically, even from area light sources. However, ray tracing will still determine illumination only via direct paths from light sources to surfaces being shaded. No knowledge of interreflection between objects is available to the ray tracer.
That's where radiosity come into the picture. Radiosity will help to capture effects such as indirect illumination, soft shadows, and color bleeding. To render the scene using radiosity, just type:
rendrib -radio n myfile.ribThe parameter n is a number giving the maximum number of radiosity steps to perform. A typical number might be 50. Higher values of n will yield more accurate illumination solutions, but will also take much longer to compute. If the solution to the illumination equations converges in fewer steps, the program will simply terminate early, and not perform the additional steps. After the radiosity calculation ends, ray tracing will be used to form an image. This method of using radiosity followed by ray tracing is known as "two-pass" rendering. There are several advantages to the two-pass method:
If you want to use these features, you will need to make a few slight modifications to your RIB files, outlined below:
LightSource "bouncer"
The "bouncer" light source is actually a program which calculates these additional light paths for specular-to-diffuse illumination. In addition, any objects which you wish to act as specular reflectors, regardless of their shader type need to have the following additional attribute declared before the geometry is instanced:
Attribute "radiosity" "specularcolor" [ color ]
When rendering with radiosity, there are two ways to make area light sources. One way is to use the AreaLightSource directive, explicitly making area light sources. The second way is to declare regular geometry, but setting an emission color:
Attribute "radiosity" "emissioncolor" [color],The difference is subtle. Both ways will make these patches shoot light into their environment. However, only the geometry declared with AreaLightSource will be resampled again on the second pass. This results in more accurate shadows and nicer illumination, but at the expense of much longer rendering time on the second pass.
Please note that rendering full color frames can take a really long time! High quality rendering, especially ray tracing, is notoriously slow. Try a couple test frames first, to make sure you have everything right before you compute many frames. Multiply the time it takes for each frame by the total number of frames you need. If your total rendering time is prohibitive (say, 5 months), you'd better change something!
A good rule of thumb is that each frame in a 1 minute animation should take between 15 and 45 minutes to render on a typical machine in your computation arsenal. If your frames take less than 15 minutes each to render, you can probably afford to go ahead and use more features, more complex textures, higher sampling, or whatever. If your frames take much more than 45 minutes (and certainly if they take longer than an hour), you should really try to use some of the optimization methods outlined below. If you are computing only a single image, of course you can allow as much time as you want.
Don't bother praying or panicking: I have it on good authority that neither does much to increase rendering throughput. Some optimization hints are listed below. Obvious, effective, easy optimizations are listed first. Trickier or subtler optimizations are listed last.
Use low resolution when you can. You may want to do test frames at 320 x 240 resolution or lower. Remember that video resolution is only about 640 x 480 pixels. It's pointless to render at higher resolution if you intend to record onto videotape, since any higher resolution will be lost in the scan conversion.
Usually, 2x2 sampling is perfectly adequate to antialias geometric edges for video images. Higher than 3x3 does not usually give noticeable improvements for geometric edges. Motion blur, depth of field, and area light shadow penumbra tend to take lots of samples to antialias. There's not much you can do about that if you insist on using these effects.
If the source of your aliasing is blurry reflections or refractions from shaders which use the trace() function, you should consult the documentation for those shaders. There may be ways to increase the sampling rate for that surface only without increasing the sampling rate for the entire image (you can do this for my "shiny" and "glass" shaders).
Higher sampling rates should never be used to eliminate aliasing in shaders. Well written shaders should be smart enough to analytically antialias themselves by frequency clamping or other trickery. It's considered bad style to write shaders which alias badly enough to require high sampling at the image level.
Similarly, most objects can be treated as completely opaque (this assumption speeds rendering time). Some objects do not need to cast shadows at all (for example, floors or walls in a room). See the "nonstandard attributes" section of this chapter for information on giving the renderer shadowing hints.
Distribution of rays results in noise. The fewer samples per pixel, the higher the noise. So if you want to keep sampling rates low and reduce noise in the image, you should: avoid using the "blur'' parameter in the "shiny'' and "glass'' surfaces; do not use depth of field; use nonphysical lights ("pointlight'', "distantlight'', etc.) instead of physical and area lights.
The following list should delineate any implementation-specific limitations and incompatibilities with the published RenderMan standard.
True displacements are somewhat limited: (1) it only works for displacement shaders, not surface shaders; (2) it uses lots of memory, and also takes more time to render; (3) you cannot use "message passing" between the displacement and surface shaders; (4) you must remember to set displacement bounds; (5) you may get odd self-shadowing of surfaces during radiosity calculations if you use too small a shadow bias.
As I write this, the BMRT and Pixar's PhotoRealistic RenderMan ((R) Pixar) (sometimes called PRMan) are the only two widely available implementations of RenderMan. While rendrib uses ray tracing and radiosity, PRMan uses a scanline method called REYES. Though both renderers should take nearly the same input, the difference in their underlying methods necessarily results in different subsets of the RenderMan standard supported by the two programs. This section lists some of the incompatibilities of the two programs. These differences should not be construed as bugs in either program, but are mostly natural limitations of the two rendering methods. This list is for the user who uses both programs, or wishes to use one program to render output meant for the other.
If you are using rendrib, you are probably already used to one aspect of working with the RenderMan Interface: specifying scenes. In other words, using the procedural interface (the C library calls) or using RIB (the ASCII archival format).
There is another aspect to using the RenderMan Interface: writing your own shaders. You've already used some of the "standard" shaders such as "matte", "metal", "plastic", and so on. You may already have used some custom shaders that I wrote (such as "planks"). Part of the real power of the RenderMan interface is the ability to write your own shaders to control the appearance of your objects.
Shaders control the appearance of objects. There are several types of shaders:
The RenderMan interface specifies that there are several standard shaders available. Standard surface shaders include "constant", "matte", "metal", "plastic", "shiny", and "paintedplastic". Standard light source shaders are "ambientlight", "distantlight", "pointlight", and "spotlight". Standard volume shaders are "depthcue" and "fog". The only standard displacement shader is "bumpy", and there are no standard transformation or imager shaders.
Once you have written a shader, save it in a file whose name ends with the extension ".sl". To compile it, do the following:
slc myshader.sl
This will result either in a compiled shading language object file called myshader.so, or you will get error messages. Hopefully, the error message will direct you to the line in your file on which the error occurred, and some clue as to the type of error. slc only can compile one .sl file at a time.
IMPORTANT NOTE: slc uses the C preprocessor (cpp). This executable is usually kept in the /lib directory. Therefore, you need to have this directory in your execution PATH or slc will not be able to run properly.
Since .sl files are passed through the C preprocessor, you can use the #include directive, just as you would for C language source code. You can also give an explicit path for include files using the -I command line option to slc (just like you would for the C compiler). You can also use #ifdef and other C preprocessor directives in a shader. A variable named BMRT is defined, so you can do something like #ifdef BMRT.
Pixar's PhotoRealistic RenderMan implementation provides a linkable library which allows a developer to read a compiled shader file (.slo) to determine what type of shader it is and what parameter names and defaults belong to that shader. Since Pixar's .slo format is different from BMRT's .so format, a similar library is provided to parse the .so files. The library is libslcargs.a, and the C language header file is so.h. The so.h file should be fairly self-documenting, and certainly anybody with experience using Pixar's libsloargs.a library ought to have an easy time of using libslcargs.a.
slctell plasticreports:
surface shader plastic.so parameters: float Ka = 1; float Kd = .5; float Ks = .5; color specularcolor = [ 1 1 1 ]; float roughness = 1;
Starting with release 2.3.6, BMRT includes a program to perform elementary image compositing operations. If you render your images with alpha channels (i.e. "rgba"), then coverage information will be stored with every pixel in the image. For the purposes of composite, RGB images without alpha channels will be assumed to have an alpha of 1.0 at every pixel.
composite may be run as follows:
Hint for beginners: you probably want over.