Part 4: Previewing RIB files with rgl
revised 27 August 1998
Larry I. Gritz
gritzl@acm.org
Once a RIB file is created, one may use the rgl program to display a preview of the scene. Geometric primitives are displayed either as Gouraud-shaded polygons with simple shading and hidden surface removal performed, or as a wireframe image.
The following command will display a preview of the animation in an OpenGL window:
rgl myfile.ribThere 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 | rglThe 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. Note that rgl can also display primitives as lines. This is done by invoking:
rgl -lines myfile.rib
This completely replaces the old rendribv program.
The following subsection details command line options alter the way in which rgl creates and/or displays images.
-res
xres yres
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.
-1buffer
-1buffer
option may be used in combination with any of the other drawing style
options.
-unlit
-unlit
option may be used in combination with any of the other drawing style
options.
-lines
-sketch
.
-sketch
-lines
.
-dumprgba -dumprgbaz
-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.
-offscreen
-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.
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. 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. 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, NURBS). 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.
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.
This document last updated 27 Aug 98 by gritzl@acm.org
All BMRT components are Copyright 1990-1998 by Larry I. Gritz. All rights reserved.
The RenderMan Interface Procedures and RIB Protocol are: Copyright 1988, 1989, Pixar. All rights reserved. RenderMan is a registered trademark of Pixar.