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 behaviour is useful to separate the actual scene description from rendering options. For example:
renderdl slow_options.rib scene.rib renderdl fast_options.rib scene.rib
These render the scene scene.rib twice but with different rendering options. slow_options.rib contains options for high quality rendering such as low ShadingRate and high PixelSamples, and fast_options.rib 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
Command Line Options
| Option___________________________ | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
Multithreading Options | |||||||||
-t n | Specifies the number of threads to use for the rendering. "n" can take any of the following values:
| ||||||||
| -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 explicitly requested otherwise on the command line using the -p option.{{ | ||||||||
Multi Host Rendering Options | |||||||||
| 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. | ||||||||
-tiling | Specifies the tiling mode to use when splitting an image for multiprocess rendering. Four tiling modes are supported:
| ||||||||
| Use ssh instead of rsh to start remote renders. More about network rendering in Section 7.1 [Multithreading and Multiprocessing], page 120. | ||||||||
-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 | ||||||||
FrameBuffer Options | |||||||||
-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 | ||||||||
-idf | Same as | ||||||||
-rid | Replaces all the displays in the RIB by
| ||||||||
-nd | Ignores all framebuffer display drivers declared in the RIB file(s). This option overrides | ||||||||
-displayvar | Works in conjunction with renderdl -id -displayvar "color aov_occlusion" test.rib The default value for this option is ‘rgba’ | ||||||||
Image Output Options | |||||||||
-res x y | Specifies the resolution to use when rendering the specified RIB. This overrides any | ||||||||
-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 | ||||||||
Statistics Options | |||||||||
-stats | Output statistics after the render. Statistics are explained in more detail in Understanding 3Delight Statistics. | ||||||||
| Redirect statistics into the provided file name. | ||||||||
-progress | Prints a progress status after each rendered bucket. | ||||||||
RIB Output Options | |||||||||
-catrib | Print RIB commands instead of sending them into the renderer. An example usage is converting a binary (or compressed) RIB into an human readable ASCII version: renderdl -catrib binary.rib.gz > ascii.rib | ||||||||
-catrib -o output_file | Redirects RIB commands into the give file. For example: renderdl -catrib -o ascii.rib binary.rib.gz | ||||||||
-catrib -binary | Outputs the RIB commands in binary format. For example: renderdl -catrib -binary ascii.rib > binary.rib | ||||||||
-gzip | Outputs the RIB commands in compressed form. For example: renderdl -catrib -gzip ascii.rib > ascii.rib.gz | ||||||||
Procedurals | |||||||||
-catrib -callprocedurals | Call any procedural found in the RIB. This is useful to gather all the data produced by external procedurals into one single RIB file (e.g. for packaging purposes). | ||||||||
-catrib -archiveprocedurals | Transform any procedural found in the RIB into archives named archive0.rib, archive1.rib, etc ... | ||||||||
Message Filtering | |||||||||
-maxmessages n | Print at most n warnings and errors. For example, setting this option to 5 will print the first five messages and the first five warnings. | ||||||||
-filtermessages m | This option allows some error messages to be filtered out. It should be set to a comma separated list of unwanted error codes, such as A2037,P1168. | ||||||||
Ri Fitering | |||||||||
-rif plugin_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. | ||||||||
-rifargs ... paramerterts ... -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. | ||||||||
Other | |||||||||
-noinit | Disable reading of the .renderdl file. | ||||||||
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):
- The directory of the first RIB file passed on the command line.
- The current working directory.
- The user's home directory.
- The directory pointed to by the
DELIGHTenvironment variable.
Only the first .renderdl file found is loaded. Loading .renderdl may be bypassed using the-noinit option.
Return values
The renderdl executable can return one of the following values.
| Return Value | Description |
|---|---|
| 0 | No error. |
| 1 | Bad combination of parameters. An error message will explain why. |
| 199 | Option "licensing" "waitforlicense" 0 was used and no license was available |
| 255 | The RIB file specified on the command line could not be read. |