next up previous contents
Next: Photo-realistic rendering with rendrib Up: Blue Moon Rendering Tools Previous: Introduction   Contents


Previewing scene files with rgl

Once a scene 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.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 the scene from standard input (stdin). This allows you to pipe output of a scene-generating process directly to rgl. For example, suppose that myprog writes to its standard output. Then you could display frames from myprog as they are being generated with the following command:

         myprog | rgl

The scene file that 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 frames. The default is to display all of the frames specified in the 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.

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

Command Line Options

The following subsection details command line options alter the way in which rgl creates and/or displays images.

Window Size and Position

-res xres yres

Sets the resolution of the output window. Note that if the scene 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.

Drawing Styles


Rather than render the polygon preview to the ``back buffer'' and displaying frames as they finish (as you would want especially if you are previewing an animation), this option draws to the front buffer, thus allowing you to see the scene as rendering progresses. The -1buffer option may be used in combination with any of the other drawing style options.


Lights all geometry with a single light at the camera position. This is useful for using rgl to preview a scene that does not contain light sources. The -unlit option may be used in combination with any of the other drawing style options.


Rather than the default drawing mode of filled-in Gouraud-shaded polygons, this option causes the images to be rendered as lines. Note that this cannot be used in combination with -sketch.


It's not clear what the real use of this is, but it makes an image that looks a little like a human-drawn sketch of the objects. Note that this cannot be used in combination with -lines.

-rd multiplier

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, which takes a single numerical argument, generally between 0 and 1. 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. 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.

File Output Options


The default operation of rgl simply previews the scene to a window on your display. But using the -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 command in the file itself, or ri.tif if no Display command is present in the 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 command, substituting ``zfile'' for ``tif'' in the filename.


-frames first last

Sometimes you may only want to preview a subset of frames from a multi-frame 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. If you are going to use this option, it is recommended that your frames be numbered sequentially starting with 0 or 1.

-sync framespersecond

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.


By default, the last frame will stay in the drawing window until you hit the ESC key. The -nowait causes rgl to terminate immediately after displaying the last frame in the sequence (for example, if it is part of an automated demo).

Implementation-dependent Options and Attributes

Various implementation-specific behaviors of a renderer may be set using two commands: Option and Attribute. Options apply to the entire scene and should be specified prior to WorldBegin. Attributes apply to specific geometry, are generally set after the WorldBegin statement, and bind to subsequent geometry.

Search Paths

Various external files may be needed as the renderer is running, and unless they are specified as fully-qualified file paths, the renderer will need to search through directories to find those files. There exists an option to set the lists of directories in which to search for these files.

Option "searchpath" "archive" [pathlist]
Option "searchpath" "procedural" [pathlist]

Sets the search path that the renderer will use for files that are needed at runtime. The "archive" path specifies where to find files that are inclued using the ReadArchive directive. The "procedural" path specifies where to find programs and DSO's that are required by RiProcedural.

Search path types in BMRT are specified as colon-separated lists of directory names (much like an execution path for shell commands). There are two special strings that have special meaning in BMRT's search paths:

  • & is replaced with the previous search path (i.e., what was the search path before this statement).
  • $ARCH is replaced with the name of the machine architecture (such as linux, sgi_m3, etc.). This allows you to keep compiled software (like DSO's) for different platforms in different directories, without having to hard-code the platform name into your file.

For example, you may set your procedural path as follows:

  Option "searchpath" "procedural" 

The above statement will cause the renderer to find procedural DSO's by first looking in /usr/local/bmrt, then in a directory that is dependent on the architecture, then wherever the default (or previously set) path indicated.

Drawing Options

Option "limits" "curvethinning" [frequency]
Option "limits" "curvethinthreshold" [thresh]

When rgl draws many Curves primitives, it can turn into a big unshaded mess. It may be that you decide that drawing fewer curves actually makes a more understandable preview. The "curvethinning" frequency value tells how often a curve should be drawn: a value of 2 indicates to draw every other curve, a value of 100 means that only every 100th curve should be drawn. Furthermore, this thinning is only performed for Curves statements that have more individual hairs than is specified with the "curvethinthreshold" parameter. Both take integer arguments. If the "curvethinning" frequency is set to zero, no curve thinning will take place at all.

Attribute "division" "udivisions" [nu]
Attribute "division" "vdivisions" [nv]

rgl will dice curved primitives into flat polygons for OpenGL to draw. It basically guesses at how many polygons to subdivide into, and it usually chooses well enough for previews, but sometimes you may want to override the dicing criteria. This option allows you to explicitly specify how many subdivisions to make in subsequently curved surfaces. The arguments nu and nv are both integers.

Limitations of rgl

Since rgl is an OpenGL-based polygon previewer, it cannot possibly support all the features that would be supported by other types of renders. This section outlines the features which are not fully supported by rgl.

  • The following commands are ignored because they have no real meaning in an OpenGL previewer: ColorSamples, DepthOfField, Shutter, PixelVariance, PixelSamples, PixelFilter, Exposure, Imager, Quantize, Hider, Atmosphere, Bound, Opacity, TextureCoordinates, ShadingRate, ShadingInterpolation, Matte.

  • The LightSource directive works as expected for "ambientlight", "distantlight" and "pointlight". It isn't smart enough to know exactly what to do for custom light source shaders, but it will try to make its best guess by examining the parameters to the shader, looking for clues like "from", "to", "lightcolor", and so on. The AreaLightSource directive has no effect.

  • Shaders do nothing. All surfaces are displayed as if they were using the standard shader.

  • When motion blocks are given, only the first time key is used.

  • Multiple levels of detail are not supported.

  • Solids are all displayed as unions, i.e., all of the components of a CSG primitive are displayed.

  • Object instancing is not currently working. Instanced objects are ignored.

  • Texture map generation functions (e.g., MakeTexture) do nothing in rgl.

Odds and Ends

There are a bunch of other things you should know about rgl but we couldn't figure out where they should go in the manual. In no particular order:

  • Before rendering any file specified on the command line or commands piped to it, rgl will first read the contents of the file $BMRTHOME/.rendribrc. If there is no environment variable named $BMRTHOME, then the file $HOME/.rendribrc is read instead. In either case, by putting commands in one of these places, you can set various options for rgl before any other file is read.

next up previous contents
Next: Photo-realistic rendering with rendrib Up: Blue Moon Rendering Tools Previous: Introduction   Contents
Exluna, Inc.