3.1 Using the RIB Renderer - renderdl

renderdl reads a file containing scene description commands and "executes" them. Such files are commonly called RIB files (RIB stands for RenderMan Interface Bytestream). There are two kinds of RIB files: ASCII encoded RIB files and binary encoded RIB files. A binary RIB file is smaller than its ASCII encoded equivalent, but an ASCII RIB file has the advantage of being editable in any text editor or word processor.

To render a RIB named `file.rib', just type:

% renderdl file.rib

It is possible to render more than one file:

% renderdl file1.rib file2.rib file3.rib

In this case, renderdl reads each file one after the other, and the graphic state is retained from one file to another (in other words, the graphic state at the end of one file is the starting graphic state for the next file). If a file cannot be found, it is simply skipped. This behavior is useful to separate the actual scene description from rendering options. For example:

% renderdl fast.opt scene.rib
% renderdl slow.opt scene.rib

These render the scene `scene.rib' twice but with different rendering options (note that `fast.opt' and `slow.opt' are normal RIB files). `slow.opt' contains options for high quality rendering such as low ShadingRate and high PixelSamples, and `fast.opt' contains low quality (speedy) option settings.

If no file name is specified, renderdl reads scene description commands from the standard in. This feature enables piping commands directly in renderdl. For example, to enter scene description commands interactively (which is not really practical), do the following:

% renderdl
Reading (stdin)
<enter commands here>

If you wish to pipe the content of `file.rib' in renderdl, type:

% cat file.rib | renderdl

renderdl options are described in the following sub-section.

Command Line Options

` -t n'

` -p n'

Specifies the number of threads to use for the rendering. `n' can take any of the following values:

n>0

Use `n' processors.

n=0

Use maximum number of processors available.

n<0

Use all but `-n' processors.

It is also possible to use this option with a separator, like this:

renderdl -t:2 -d cubits.rib

` -P n'

Specifies the number of processes to use for the render. `n' can take the same values as in the `-p' option. The way 3Delight cuts the image is controlled using the `-tiling' option. Note that each process will run with a single thread unless explicitely requested otherwise on the command line.

` -hosts host1,host1,...,hostn'

Specifies a list of machines to use for rendering. It is also possible to specify a file (instead of a host name) that contains a list of machines to use. The format of the file is very simple: one machine name per line. This option is not yet functional on Windows platforms.

` -tiling'

Specifies the tiling mode to use when splitting an image for multiprocess rendering. Four tiling modes are supported:

` b'

For balanced tiling (default). Uses feedback from the previous multiprocess render to improve the split.

` m'

For mixed tiling. Splits the image into almost identical squares.

` v'

For vertical tiling. Splits the image into vertical stripes.

` h'

For horizontal tiling. Splits the image into horizontal stripes.

` -ssh'

Use ssh instead of rsh to start remote renders. More about network rendering in Multithreading and Multiprocessing.

` -jobscript script'

Use script to start remote renders. The script receives the command to run as its first argument and is responsible for choosing a machine and executing the command there in a proper environment.

` -jobscriptparam param'

When used with -jobscript, renderdl will pass 'param' as the first argument of the script. The command to run then becomes the second argument.

` -d'

Forces a display to the `framebuffer' display driver. Note that a `framebuffer' display driver is added to the displays declared inside the RIB so those are still called. If there is already a `framebuffer' display driver declared in the RIB it is ignored.

` -D'

Has the same effect as `-d' but automatically closes the framebuffer display driver when rendering ends.

` -id'

Starts i-display and launches the render, enabling the user to send multiple renders into a centralized application. See section The idisplay display driver.

` -nd'

Ignores all framebuffer display drivers declared in the RIB file(s). This option overrides `-id', `-d' and `-D'.

` -res x y'

Specifies the resolution to use when rendering the specified RIB. This overrides any RiFormat command specified in the RIB file(3).

` -frames f1 f2'

Renders the frames between f1 and f2, inclusively. This options enables you to render some specific frames inside one RIB file. Frames outside the specified interval are skipped.

` -crop l r t b'

Sets a crop window defined by <l r t b> (left right top bottom). The values should be given in screen coordinates, which means that all values are between 0.0 and 1.0 inclusively. This command line option overrides any RiCropWindow command present in the RIB file.

` -noinit '

Doesn't read the `.renderdl' file. See the .renderdl file.

` -stats[1-3]'

This is equivalent to adding the following line in the RIB file (`n' being a number between 1 and 3):

Option "statistics" "endofframe" n

The higher the level, the more statistics you get at a slight performance cost. The default statistics level is 3. Note that there is no space between `-stats' and the number.

` -statsfile file'

Prints statistics in `file' instead of `stdout'. Has the same effect as putting the following line in the RIB file:

Option "statistics" "endofframe" 3 "filename" "file"

This option may be combined with the `-stat' in order to reduce the statistic level.

` -progress'

Prints a progress status after each bucket. May also be enabled from the RIB file. See progress option.

` -catrib'

Doesn't render the specified file(s), only outputs the RIB to `stdout'. More about RIB output in RIB Output.

` -o file'

Output the RIB to the specified `file' instead of stdout. `stdout' and `stderr' are two special file names which output to standard output and error respectively. Only meaningful with `-catrib'.

` -binary'

Output RIB in binary format. Only meaningful with `-catrib'.

` -gzip'

Compress RIB using gzip format. This is valid in both ASCII and binary format. Only meaningful with `-catrib'.

` -callprocedurals'

Calls any procedurals found in the RIB when outputting. Only meaningful with `-catrib'. More about procedurals and RIB output in RIB Output.

` -archiveprocedurals'

Only meaningful with `-catrib'. Turns any procedurals found in the input RIB into archives named archive0.rib, archive1.rib, etc.

` -maxmessages n'

Print out at most `n' warnings and errors to the console. For example, setting `n' to five will only show the first five warnings and the first five errors.

` -filtermessages m'

Filter out the messages specified in the comma separated list m. Note that this simply sets the message filtering option so it can be overriden by a RIB file. See also filtering messages.

` -rif plug-in name'

Loads the specified Ri plug-in filter. 3DELIGHT will look for the file in the current directory as well as in paths specified in DL_RESOURCES_PATH and DL_PROCEDURALS_PATH. More about Ri plug-in filters in Using Ri Plug-in Filters.

` -rifargs ... parameters ... -rifend'

Encloses a set of parameters that are meant for the previously declared Ri plug-in filters (loaded using `-rif'). This set of parameters is not interpreted in any way by renderdl and is directly passed to the Ri plug-in filter.

` -beep'

Beeps when all RIBs are rendered.

` -beeps'

Beeps after each RIB is rendered.

` -v'

Prints 3Delight's version number and name.

` -h'

Prints a short help screen.

The `.renderdl' File

When started, renderdl immediately looks for an initialization file named `.renderdl'. This file is a normal RIB which may contain any standard RIB command, enabling the user to specifiy whatever default options are needed for rendering, such as variable declarations, standard screen format, performance options, etc. The locations in which 3Delight looks for this file are (in order):

1. The directory of the first RIB file passed on the command line.
2. The current working directory.
3. The user's home directory(4).
4. The directory pointed to by the DELIGHT environment variable.

Only the first `.renderdl' file found is loaded. Loading `.renderdl' may be bypassed using the `-noinit' option (see renderdl options).

3Delight 8.5. Copyright 2000-2009 The 3Delight Team. All Rights Reserved.