7.15 RIB Output

It is sometimes desirable to redirect the RIB stream into a file instead of sending it to the renderer. This is particularly useful for applications that link directly with the Ri client library (see section Linking with 3Delight). Some renderers come with a specialized library that is intended for such usage(61) while 3Delight provides the same functionality through the library that is used for rendering in three different ways:

1. By specifying an output file name to RiBegin (specifying an empty file name as in RiBegin("") outputs the RIB stream to `stdout'). This is the recommended way for exporting geometry from 3D packages. It is possible to concatenate a RIB stream to an existing file by using RiBegin(">>filename.rib"). It is also possible to pass the RIB stream to custom filters by using a command such as RiBegin("| filteringscript | gzip > final.rib.gz").
2. By specifying a file descriptor using the Option "rib" "pipe" option.
3. By setting the RISERVER environment variable to a valid file name before rendering (more precisely, before the first RiBegin call). This environment variable can be of great help when debugging since one can redirect the RIB stream to a file for analysis, without prior code modification. Binary RIB output is possible by setting the RIFORMAT environment variable to `binary'. Compressed output is possible by setting the RICOMPRESSION environment variable to `gzip'.

Additional controls on RIB output are provided through RiOption. One is for binary RIB output and the other is for procedurals expansion. When procedurals expansion is enabled, the output is a flat RIB, including the content of all accessed archives (read through ReadArchive) and procedurals (called by RiProcedural). The actual options are better illustrated through an example:

/* This one must be called before RiBegin or it will have no effect.
   With this option the output stream will be gzipped. */
RtString compression[1] = {"gzip"};
RiOption( "rib", "compression", (RtPointer) compression, RI_NULL );

RiBegin( "test.rib" );
    /* Set output format to binary */
    RtString format[1] = {"binary"};
    RiOption( "rib", "format", (RtPointer)format, RI_NULL );

    /* Enable procedurals expansion during output. */
    RtString expansion[1] = {"on"};
    RiOption( "rib", "callprocedurals", (RtPointer)expansion, RI_NULL );

    ... Scene description follows here ...
RiEnd( );

Some important remarks about procedurals expansion:

• It is disabled by default, so all standard procedural calls (such as RiProcDynamicLoad) are replaced by their RIB counterpart (e.g. Procedural "DelayedReadArchive"). User defined procedurals are always expanded.
• When calling a procedural (such as RiProcDynamicLoad) the level of detail is set to RI_INFINITY.
• Contrary to normal rendering, RIB output does not perform any kind of frustum culling or visibility checks; this means that procedurals are opened as soon as they are issued. This ensures that the entire scene is included.
• All used archives/executables must be present in default search paths.
• It is possible to cause procedurals to be turned into archives read with "DelayedReadArchive" by using the "rib" "callprocedurals" option (see section RIB Output Options).

/* Set output format to binary */
int fd = open( "test.rib", O_WRONLY );
RiOption( "rib", "pipe", &fd, RI_NULL );

/* Set output format to binary. Can also be done _inside_ the Begin/End
   block. */
RtString format[1] = {"binary"};
RiOption( "rib", "format", (RtPointer)format, RI_NULL );

/* Enable procedurals expansion during output. Can also be done _inside_ 
   the Begin/End block. */
RtString expansion[1] = {"on"};
RiOption( "rib", "callprocedurals", (RtPointer)expansion, RI_NULL );

RiBegin( RI_NULL );
	... Scene description follows here ...
RiEnd( );

close( fd ); /* don't forget to close that file! :> */

renderdl can also be used to redirect the RIB stream to a file by using the `catrib' option (see renderdl options). Redirecting a RIB into another RIB may sound useless but is in fact useful in many regards:

• renderdl can output binary encoded RIBs (using `-binary') which are much smaller in size than their ascii counterpart.
• renderdl can read binary RIBs so it can be used to convert those into a humanly readable ASCII format.
• It is sometimes desirable to "flatten" a RIB which includes many archives or procedurals, this can be done using the `-callprocedurals' option.
• The resulting RIB is nicely formatted!

EXAMPLES

Output the content of a RIB in "gzipped" binary format:

> renderdl -catrib -binary -gzip teapot.rib > teapot.binary.rib

Do the same using environment variables (working in a tcsh shell):

> setenv RIFORMAT binary
> setenv RISERVER teapot.binary.rib
> renderdl teapot.rib

Append the content of a RIB to an existing file, expanding all procedurals and including all archives:

> renderdl -catrib -callprocedurals frame12.rib >> sequence.rib 

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