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. Note that each process will run with a single thread explicitly 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.

` -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.

` -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.

` -idf'

Same as `-id' but sets the display to output floating point data.

` -rid'

Replaces all the displays in the RIB by i-display without changing any output or quantize parameters.

` -nd'

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

` -displayvar var'

Works in conjunction with `-id', `-d' or `-D' to specify which display variable to render. For example:

renderdl -id -displayvar "color aov_occlusion" test.rib

The default value for this option is `rgba'.

` -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.

` -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.

Return values

The renderdl executable can return one of the following values.

0

No error.

1

Bad combination of parameters. An error message will explain why.

99

Option "licensing" "waitforlicense" 0 was used and no license was available.

255

The RIB file specified on the command line could not be read.

3Delight 10.0. Copyright 2000-2011 The 3Delight Team. All Rights Reserved.