RenderDotC Environment Variables

Several environment variables can be used to control the operation of RenderDotC.  Among these, RDCROOT is the most important.

RDCROOT

Set this to the root directory of the RenderDotC installation.  On Unix systems, for example, RenderDotC is often installed in the /usr/local/rdc directory.  If this is the case, set RDCROOT to "/usr/local/rdc". It is always a good idea to set up RDCROOT correctly.  It is especially important if RenderDotC is installed in a directory other than the default.

LICENSE_FILE

By default, $RDCROOT/etc/license.dat is the full pathname of the encrypted license file.  If LICENSE_FILE is set, it overrides the default name.  It should contain the directory and file name.  For example, to use NFS to access a license file on a server named countach, set LICENSE_FILE to "/hosts/countach/usr/local/rdc/etc/license.dat"

The LICENSE_FILE environment variable is honored by both the server (licensedc) and the client (renderdc).

RMAN_ARCHITECTURE

Shader source code (SL) is platform independent.  Shaders compiled with shaderdc are unique to a particular operating system and CPU.  In order to keep things straight for users with more than one kind of computer on a network, compiled shaders are normally stored in subdirectories immediately below the directory where the shader source code resides.  The shader compiler puts the shared library in a subdirectory and then the renderer looks for the compiled shader in the appropriate subdirectory first.  This all happens automatically without assistance from the user.  It may come as a surprise that the shader compiler does not produce an output file in the current directory when the shader compiler is run.

The renderer also follows this RMAN_ARCHITECTURE convention when searching for display drivers and procedural primitives.

The following are the default subdirectory names for the various architectures supported by RenderDotC.  The names are self-explanatory:

    win_intel

    win_ia64
    linux_intel
    linux_ppc
    linux_ia64
    irix_mips3
    irix_mips4
    bsdi_intel
    freebsd_intel
    hpux_pa20

To understand the benefit of this convention, imagine a render farm consisting of both Windows/Intel and Irix/Mips3 computers.  One could put the shader source code in a directory on a network file system.  The next step would be to login to any Irix system and compile all the shaders.  Repeat that step from any Windows computer on the network.  Now a RIB file may be sent to any node on the network for rendering and the shaders will be available.  Just make sure that the network directory containing the shader source code is on the shader search path.  No platform specific modifications to the RIB are necessary for rendering on a heterogenous network.

One may override the default names by setting the RMAN_ARCHITECTURE environment variable.  If you only use one platform, you may choose to keep compiled shaders in the same directory as the shader source code.  In Bourne shell, this is achieved by:

    RMAN_ARCHITECTURE=.
    export RMAN_ARCHITECTURE

In C-Shell:

    setenv RMAN_ARCHITECTURE .

ARCH

ARCH is not an operating system environment variable.  Rather, it's a variable expanded by the renderer in names of shaders, display drivers, and procedural primitives.  For example, the following procedural primitive could appear in RIB:
Procedural "DynamicLoad" ["sphere.$ARCH" "0.35"] [-1 1 -1 1 -1 1]
The substring "$ARCH" will be expanded to the value of the RMAN_ARCHITECTURE environment variable (or to its default for the current platform, if not set).  On Irix, the renderer might look for a DSO named "sphere.irix_mips3.so".  This allows the user to exert more control over how platform-specific binaries are organized.

Equivalently, "%ARCH" may be used instead of "$ARCH".

SHADERS

The renderer looks for compiled shaders in a series of directories called a search path.  The standard shader search path is:

    .:$RDCROOT/shaders

To override the standard path, set SHADERS to a different list of directories, separated by colons:

    .:./shaders:/usr/local/shaders:/usr/local/rdc/shaders

In RIB files that use Option "searchpath" "shader" the '@' character is expanded to the value of SHADERS (or to the default standard path if SHADERS is not set).

MAPS

The renderer looks for texture maps in a series of directories called a search path.  The standard texture search path is:

    .:$RDCROOT/texture

To override the standard path, set MAPS to a different list of directories, separated by colons:

    .:./texture:/usr/local/texture:/usr/local/rdc/texture

In RIB files that use Option "searchpath" "texture" the '@' character is expanded to the value of MAPS (or to the default standard path if MAPS is not set).

ARCHIVES

The renderer looks for RIB archives in a series of directories called a search path.  The standard archive search path is simply the current directory. To override the standard path, set ARCHIVES to a different list of directories, separated by colons:

    .:./rib:/usr/local/rib

In RIB files that use Option "searchpath" "archive" the '@' character is expanded to the value of ARCHIVES (or to the default standard path if ARCHIVES is not set).

DISPLAYS

The renderer looks for display drivers in a series of directories called a search path.  The standard display driver search path is:

    .:$RDCROOT/etc

To override the standard path, set DISPLAYS to a different list of directories, separated by colons:

    .:./etc:/usr/local/etc:/usr/local/rdc/etc

In RIB files that use Option "searchpath" "display" the '@' character is expanded to the value of DISPLAYS (or to the default standard path if DISPLAYS is not set).

PROCEDURALS

The renderer looks for procedural primitives in a series of directories called a search path.  The standard procedural search path is simply the current directopry. To override the standard path, set PROCEDURALS to a different list of directories, separated by colons:

    .:./procedurals:/usr/local/procedurals

In RIB files that use Option "searchpath" "procedural" the '@' character is expanded to the value of PROCEDURALS (or to the default standard path if PROCEDURALS is not set).

RIPROGRESS

When the progress flag is turned on, RenderDotC will report the percentage of rendering completed in one percent increments.  By default, progress reporting is turned off.  To turn it on, set RIPROGRESS to any value. Regardless of whether RIPROGRESS is defined or not, progress reporting may be turned on (or off) in RIB by:

    Option "statistics" "progress" [1]

This Option takes precedence over the state of the environment variable.

RISTATS

RenderDotC may be configured to print out various rendering statistics at the end of each frame.  To turn on statistics, define RISTATS to 1 for brief CPU/memory statistics, 2 for detailed data structure statistics, and 3 for additional texture mapping statistics.  Another way to turn on statistics from RIB is:

    Option "statistics" "endofframe" [1]

This Option takes precedence over the state of the environment variable.

RIDEBUG

For really detailed debugging information, define RIDEBUG to any value. Warning: this produces a huge amount text output which slows down rendering substantially.  Debugging may be turned on in RIB by:

    Option "statistics" "debug" [1]

This Option takes precedence over the state of the environment variable.

RISERVER

The RIB client library looks at the RISERVER environment variable in determining the name of the file it creates.  The value may be a simple file name like "scene.rib" or it may start with a pipe character like "| renderdc" which would indicate that the RIB stream should be piped directly to another program.  If RISERVER is not set, the default destination of the RIB stream is stdout.  For complete details on the heuristic, see RIB Options: Server

RIFORMAT

When using the RIB client library, RIFORMAT specifies whether to output RIB in the ASCII format or the binary format.  The default is ASCII.  To change the default to binary, set RIFORMAT to "binary".  The default may always be overridden in the C program with:

    RtString ascii = "ascii";
    RtString binary = "binary";
    RiOption("rib", "format", (RtPointer)&ascii, RI_NULL);

Be sure to call this before RiBegin() in order for it to be effective.

RICOMPRESSION

When generating RIB with the client library, it is uncompressed by default. To use gzip compression, define RICOMPRESSION to be "gzip".  This may be overridden in the C program with:

    RtString none = "none";
    RtString gzip = "gzip";
    RiOption("rib", "compression", (RtPointer)&gzip, RI_NULL);

This must be called before RiBegin() to be effective.

RIPRECISION

By default, ASCII RIB generated by the client library uses 6 places of precision for floating point values.  This default may be changed by defining RIPRECISION to the desired number of places.  Regardless of the default, the precision may be changed in C with:

    RtInt precision = 4;
    RiOption("rib", "precision", (RtPointer)&precision, RI_NULL);

This Option may be changed at any point in the program and subsequent floating point numbers will be printed with the specified precision.

DSPYBACKGROUNDPIXELVALUE

When using the X11 or Windows display driver, DSPYBACKGROUNDPIXELVALUE may contain a color value to use for pixels which have not yet been rendered in the framebuffer.  The format of the value is ABGR, with 8 bits for each channel.  For example, setting DSPYBACKGROUNDPIXELVALUE to 255 will fill the display with red pixels prior to rendering.  If the image is subsequently saved to a TIFF file (by pressing 's' or 'S') pixels still showing the background color will be saved as black and transparent.  In other words, the background color is for display only and doesn't affect the actual rendered pixels.

DSPYGAMMA

The default gamma correction value for the X11 and Windows display drivers is 2.0 (1.0 on SGI).  To change this setting, define DSPYGAMMA to the desired value.

DSPYBITSPERPIXEL

The X11 and Windows display drivers attempt to use the highest bit depth offered by the display device, usually 24 or 32.  On devices with fewer bits per pixel, the framebuffer drivers make the image look as good as possible (applying Floyd-Steinberg dithering).  The DSPYBITSPERPIXEL environment variable can force the display driver to use fewer bits than are available.  Typical values are 1 (black and white) and 8 (palette mode).  Setting the environment variable to a higher bit depth than is supported by the device has no effect.

DSPYPAUSE

When doing a rendering demo, it is often desirable to render to the framebuffer, pause for a few seconds, and then close the frame. The X11 display driver can be configured to automatically close a frame a certain number of seconds after rendering completes.  Set DSPYPAUSE to the desired number of seconds.

Copyright © 1999-2006 Dot C Software, Inc. All rights reserved.
Dot C Software, Inc., 182 Kuuhale St., Kailua, HI 96734
(808) 262-6715 (voice) (808) 261-2039 (fax)
The RenderMan® Interface Procedure and RIB Protocol are:
Copyright © 1988, 1989, Pixar.  All rights reserved.
RenderMan® is a registered trademark of Pixar.