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
(or libribout.lib on Windows)
does this. This library provides a `C' language binding for the
RenderMan Procedural Interface.
The libribout library has all its public routines use the
C language binding, but its implementation contains C++ code, so
it is important to either use a C++ compiler to link with it,
or else to manually include the standard C++ libraries.
If your program is written in C++, you can link libribout in
the usual way. The following example shows how to link with this
library on a typical Unix machine:
CC myprog.c -o myprog -lribout -lm
If your program is written in ordinary C, then you could
compile with C, then link with C++:
cc -c myprog.c
CC myprog.o -o myprog -lribout -lm
On an SGI, it's apparently important to include -lC on
the linkage line, to ensure that the C++ standard library is linked
properly.
In any case, 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 starts with the `|'
character, the library will open a pipe to the program specified
after the `|' symbol. For example, RiBegin ("|rgl"); will
cause the RIB you produce to be piped directly to a running rgl
process 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.
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 .slc format, similar functionality is provided to
parse the .slc files. The C language
header file for these is slc.h. This file should be fairly self-documenting,
and certainly anybody with experience using Pixar's libsloargs.a
library ought to have an easy time using it.
These routines are all contained in libribout.a, so you should
link your software against libribout.a if you are outputting
RIB or parsing shader arguments or both.
However, if you want to parse BMRT shader arguments but use some
other RIB client library (such as PRMan's librib.a), then
there is an additional library you can use, libslcargs.a,
which contains only the routines for .slc file parsing, but none
of the symbols which are also expected to be in a RIB client library.
iv - an Image Viewer
Once you render images, you need to view them. There are dozens,
or possibly hundreds, of programs that can display your ordinary
TIFF images that BMRT produces. But probably none of them can display
the tiled TIFF images used for textures, environment maps, and shadow
maps. Nor can most of them handle 16-bit and floating point images.
And even for ordinary images, many image viewers are lacking in certain
features that you may find handy. So we have provided iv, the Image
Viewer tool.
Invoking iv is very simple:
iv [options] file1 ... filen
Any number of files may be specified on the command line. Several
options may also be specified before the files are listed:
-g gamma
Sets the gamma correction for subsequent images. The gamma
parameter is a floating point number, which default to 1.0. Without
the -g option, the gamma correction will be taken from the
$GAMMA environment variable. If no such environment variable
exists, no gamma correction will be performed. Note that you can have
multiple -g options on the command line, interspersed with
image file names (this lets you correct different images with different
gamma values).
-info
When this flag is used, the name and resolution of each file will
be printed to stdout.
-sb
Normally, you can use the middle mouse button to ``drag'' the image
around if the image resolution is greater than your display window.
If you use the -sb command line option, iv will also display
scroll bars at the edge of the window.
Once you are running iv and viewing images, there are several keyboard
and mouse commands that you may find useful:
PgUp PgDn
The PgUp and PgDn keys cycle you to the previous and next
images in the list of images.
ENTER
The ENTER key will reload the current image from disk.
r g b a c
The r, g, b, and a keys will cause iv to
display just the red, green, blue, or alpha channels of images.
The c key will display full color again.
f
The f key reframes the window. That is, it will readjust the
size of the display window to match the resolution of the currently
viewed image.
p
The p key opens a pixel view window that shows you a
zoomed view of the pixels surrounding the mouse position, and numeric
values for the pixel under the cursor. Hitting ESC with the
cursor in the pixel view window will close the pixel view window
(but not the main window).
q
The q key causes iv to close its windows and exit.
s
The s invokes pixel select mode. In this mode, a single pixel
is selected for the pixel view window. The selected pixel no longer
follows the mouse cursor, but can be moved with the four arrow keys.
Hitting s again returns to the usual mouse cursor.
Left-click
Clicking the left mouse button inside the image window zooms in (makes
the pixels bigger on screen).
Right-click
Clicking the right mouse button inside the image window zooms out (makes
the pixels smaller on screen).
Middle-drag
Moving the mouse with the middle button held down will drag the image
around the window, if the image resolution is greater than the window
size.
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:
composite file1 over file2 -o output
composite file1 in file2 -o output
composite file1 out file2 -o output
composite file1 atop file2 -o output
composite file1 xor file2 -o output
Composite images file1 and file2 using one of
the standard image compositing operators described in (Porter & Duff,
"Digital Image Compositing", Proceedings of SIGGRAPH '84,
pp. 253-259), storing the composited image in file output.
composite file1 plus file2 -o output
composite file1 minus file2 -o output
Add or subtract two files, storing the results in file
output. Pixels are clamped to [0,maxval], where maxval==255
for 8 bit images, maxval==65535 for 16 bit images.
composite file1 scale float -o output
composite file1 dissolve float -o output
composite file1 opaque float -o output
These three unary operators take a floating point number, rather
than a filename, as their second operand. They all scale the channels
of the image, but in slightly different ways. The scale
operator multiples the RGB channels, but leaves the alpha alone -
i.e. it can brighten or darken an image without changing its
transparency. The dissolve operator scales the alpha along
with the RGB. Finally, the opaque operator will scale
only the alpha channel.
Hint for beginners: you probably want over.
Remember that both of BMRT's renderers (rendrib
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 (default resolution, shader
search path, texture cache size, etc.) you can just put the Option or
Attribute lines in this file in your home directory.
Many people ask how they can divide rendering of a single frame among
several processors or machines. The simple Perl
script farm accomplishes this task, in a relatively rudimentary
way.
- Set the environment variable BMRT_FARM to be a
blank-separated list of the names of machines which can be
used as render servers. Machines with multiple processors should
be listed multiple times. For example, if you have a machine
named "fred" with two processors, and one named "wilma" with
one processor, then run:
setenv BMRT_FARM "fred fred wilma"
if you use csh. If you use sh, try:
export BMRT_FARM="fred fred wilma"
- Make sure that rendrib is in the default path of each
remote machine, and that mkmosaic is in the path
on the local machine.
- Run farm:
farm myfile.rib
First, farm will look at your RIB file to figure out the
resolution and the name of the TIFF file that it will render. It will
choose an appropriate number of subwindows to render.
One by one, it will send the frame to machines on your
BMRT_FARM list, using the -crop and
-of flags to make rendrib render particular
crop windows. Machines whose load averages are too high will
automatically refuse the frames.
When farm sees that all the subsections are finished (each
will leave a little file indicating that it's done), it will assemble
all the pieces using the mkmosaic program, and clean up all
the cruft files.
- Because farm relies on rsh, you can only use
it on UNIX (or UNIX-like) operating systems.
- You can't use farm to render to the display (the -d flag).
It must be rendering to a TIFF file.
- Don't try using any other rendrib command line flags. Request
all image options (like radiosity options) in the RIB file with
Option and Attribute statements.
- Hitting Control-C to interrupt farm will kill only
farm, but will leave the individual crop windows rendering
on the remote machines. Beware.
|