RenderDotC Programs

The RenderDotC toolkit includes programs for processing various files in order to produce a final, rendered image. These tools are introduced below in terms of the file types they operate on.

RIB

RenderDotC eats RIB files. RIB stands for "RenderMan Interface Bytestream". All scene data, including geometry, is typically stored in one or more RIB files.

The most common flavor of RIB is ASCII. These files can be opened in a text editor and read by humans. However, ASCII RIB files can become quite large. One way to compress RIB is to use the binary form. These files are smaller but not human readable. Another form of compression is gzip. All of the programs below can read gzipped RIB transparently. There is no need to run "gzcat". Both ASCII and binary RIB may be compressed with gzip. For maximum compression, use gzipped binary RIB.

renderdc

The main command line tool for rendering RIB files is "renderdc". Pass one or more names of RIB files on the command line:

renderdc cubits.rib tetra.rib

wrendrdc

On Windows, "wrendrdc" provides a dialog box interface for selecting RIB files. It then launches renderdc.

catribdc

To convert between ASCII, binary, and gzipped RIB, use the catribdc program. For example, to achieve maximum compression of a large RIB file:

catribdc -g -b -o compressed.rib big.rib

Shaders

Compile shaders written in RenderMan shading language (SL) with "shaderdc". It takes one or more SL source files as command line arguments:

shaderdc plastic.sl paintedplastic.sl
shaderdc *light.sl

The output of shaderdc is a shared library that can be loaded and executed at render time. By default, the output file does not go into the current directory. Instead, it goes into a subdirectory of the current directory that indicates what architecture (operating system and CPU) the shader has been compiled for. This behavior may be overridden by setting the RMAN_ARCHITECTURE environment variable.

The -D option may be used to define preprocessor symbols:

shaderdc -DDEBUG erode.sl

The -I option adds a directory to the search path for files that are #included from the shader:

shaderdc -I/usr/local/lib/shaders diaknurl.sl

To convert shaders from SL to C++, use the -S flag. This will prevent shaderdc from compiling all the way to a shared library. It is useful only to advanced users who wish to inspect and/or modify the C++ form of the shader.

In order to use shaderdc, you need to have a C++ compiler capable of producing shared libraries. You tell the shader compiler which C++ compiler you have and how to use it with the file RDCROOT/etc/shaderdc.cfg. If you use the -g flag, shaderdc will look for RDCROOT/etc/dshaderdc.cfg instead. This can be used to generate compiled shaders that can be stepped through with a debugger.

On SGI platforms, choose mips3.cfg, or mips4.cfg, depending on which RenderDotC binaries you are running. The default is mips3.cfg and comes preconfigured. To reconfigure for n32 mips4, for example:

cd $RDCROOT/etc
cp mips4.cfg shaderdc.cfg

On Linux, a configuration file for g++ is provided and comes preinstalled:

cd $RDCROOT/etc
cp linux.cfg shaderdc.cfg

Likewise, on BSD/OS, g++ is preinstalled:

cd $RDCROOT/etc
cp bsd.cfg shaderdc.cfg

On HP-UX, the configuration file is also preinstalled:

cd $RDCROOT/etc
cp hpux.cfg shaderdc.cfg

For Windows, example configuration files are provided for Borland C++ 5.0 and 5.5, and Microsoft Visual C++ 5.0. As of June 2000, Borland C++ 5.5 is available as a free download. To configure the shader compiler to use Borland C++:

    c:
    cd \rdc\etc
    copy bc50.cfg shaderdc.cfg

To configure the shader compiler to use Visual C++:

    c:
    cd \rdc\etc
    copy vc50.cfg shaderdc.cfg
    vcvars32

The "vcvars32" command runs a batch file that sets up environment variables for running the Visual C++ compiler from the command line. If it can't be found, look in C:\Program Files\DevStudio\VC\bin. You must run this batch file every time you open a new DOS prompt in order to compile shaders with Visual C++.

For other C++ compilers, you will need to create a configuration file and the import library for sl.dll. This is a difficult task and should only be attempted by an expert user. If you succeed at supporting a new compiler, please contribute the configuration file.

The first line of the configuration file identifies the C preprocessor. It should begin with the full path name of the C preprocessor binary. On Windows, it must contain a flag to generate an output file named "sltemp.i". Other flags are optional. Note that the input file name is omitted. The shader compiler will fill that in. On all platforms, the first line of the configuration file defines "RDC" so that shaders may use conditional compilation for implementation specific SL code:

#if defined(RDC)

print("Using RenderDotC\n");

#elif defined(BMRT)

print("Using Blue Moon Rendering Tools\n");

#else

print("Using PhotoRealistic RenderMan or other\n");

#endif

The second line of the configuration file is a template for compiling a single C++ file into a shared library. It should begin with the full path name of the C++ compiler, set up the include path and library paths, and indentify the input and output file names. Three macros are available:

    %r expands to the value of RDCROOT
    %s expands to the name of the shader being compiled
    %a expands to the value of RMAN_ARCHITECTURE (or, if not set, the default subdirectory name)

On SGI, the name of the input file must be %s.c++ and the output file will always be %s.so. On Windows, the name of the input file is %s.cpp and the output file will be %s.dll.

The remainder of this section is Windows specific:

Each C++ compiler has a subdirectory under RDCROOT/lib that contains import libraries for the DLL's in RDCROOT/bin. The DLL's were compiled with Borland C++ 5.02 and the exported functions all have C binding. Borland prepends an underscore to each C function name but otherwise leaves the name unmangled.

Other compilers may expect a different naming convention. For example, Visual C++ strips the leading underscore when exporting and importing from a DLL. Examine the file RDCROOT/lib/vc50/sl.def to see how the names were aliased. For Visual C++, the import library sl.lib was created by running the following command:

lib /DEF:sl.def

Other compilers may have a similar facility. Use the information in sl.def to create import an library for other compilers.

Textures

RenderDotC can use practically any TIFF file as a plain texture map (i.e. one read from a shader with the texture() function). However, the practice of using plain TIFF files as texture maps is discouraged because of poor image quality. Instead, TIFF files should be converted to RDC texture files (a tiled, multiresolution TIFF format). This step is absolutely required for environment and shadow maps.

There are three equivalent ways to do this. From the command line:

texdc gravel.tif gravel.tex

in RIB:

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1

or with the procedural interface:

RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
RiBoxFilter, 1, 1, RI_NULL);

There are a number of options available when building RDC textures. All are possible regardless of which of the three interfaces is used. In the sections that follow, examples will be given using each of the three interfaces. Wherever called for, the filter and filter widths are ignored and may be set to anything convenient, such as"box" 1 1.

Plain textures

Plain textures are defined as those read with the built-in texture() function in the shading language, such as that found in the standard "paintedplastic" shader. They often have three channels (red, green and blue) but may have any number of channels from one to four.

While RenderDotC is capable of reading any TIFF file as a plain texture, the user is encouraged to convert all images to the texture file format using one of the three interfaces:

texdc gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1

RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
RiBoxFilter, 1, 1, RI_NULL);

The filter and filter widths are ignored and may be set to anything convenient, such as"box" 1 1. Make sure to put the texture map somewhere on the texture search path so that the renderer can find it.

Shadow maps

For a complete description of the process, please see the tutorial on creating shadows. Convert the zfile depth image to a shadow map using one of the following:

texdc -z lamp.z lamp.shd

MakeShadow "lamp.z" "lamp.shd"

RiMakeShadow("lamp.z", "lamp.shd", RI_NULL);

Put the shadow map on the texture search path. Use a shader that calls the shadow() function, such as the standard "shadowspot" shader.

Latitude-Longitude environment maps

Usually a artist needs to create these by hand in order to get the proper distortion. To use the renderer to create synthetic reflections, see cube face environment maps. To package a spherical map for reflections, use one of the three interfaces:

texdc -l world.tif world.env

MakeLatLongEnvironment world.tif world.env "box" 1 1

RiMakeLatLongEnvironment("world.tif", "world.env",
RiBoxFilter, 1, 1, RI_NULL);

The filter and filter widths are ignored and may be set to anything convenient, such as"box" 1 1. Put the environment map on the texture search path. Use a shader that calls the environment() function, such as the standard "shinymetal" shader.

Cube face environment maps

These are unique because it takes six source images to create one texture. They are the views from the center of the reflective object in the positive X, negative X, positive Y, negative Y, positive Z, and negative Z directions. The perspective field of view must be at least 90 degrees but should be a little larger to improve filtering around the seams. The field of view is also specified when converting the six images to a cube face map:

texdc -c -a 93 px.tif nx.tif py.tif ny.tif pz.tif nz.tif world.env

MakeCubeFaceEnvironment px.tif nx.tif py.tif ny.tif pz.tif nz.tif
world.env 93 "box" 1 1

RiMakeCuveFaceEnvironment("px.tif", "nx.tif", "py.tif", "ny.tif",
"pz.tif", "nz.tif", "world.env", 93, RiBoxFilter, 1, 1, RI_NULL);

Wrap modes

With plain textures, the user may specify the behavior when the texture coordinates (s and t) go outside of the unit square. The possibilities are "black", "periodic" and "clamp". The texdc interface defaults to "black". The other two interfaces don't have defaults because both wrap modes are required parameters. To set the s and t wrap modes to periodic, for example:

texdc -m periodic gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "periodic" "periodic" "box" 1 1

RiMakeTexture("gravel.tif", "gravel.tex", RI_PERIODIC, RI_PERIODIC,
RiBoxFilter, 1, 1, RI_NULL);

The -m option to texdc sets both the s and t wrap modes to the same thing. To set them independently, use the -s and -t options instead:

texdc -s black -t periodic gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "periodic" "box" 1 1

RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_PERIODIC,
RiBoxFilter, 1, 1, RI_NULL);

The wrap mode options have no effect on shadow and environment maps.

Channel list

By default, the number and order of the color channels in the input image determine the channels in the output texture (up to four). To reorder the channels, use the "chanlist" option. For example, to copy just the green and alpha channels from a four channel input to a two channel texture:

texdc -o "ga" gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"chanlist" ["ga"]

    RtString chans = "ga";
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_CHANLIST, (RtPointer)&chans, RI_NULL);

The four input channels are always referred to as "r", "g", "b", and "a", respectively. Use those letters to create a string specifying the desired order of the output.

Data types

By default, the data type of the input image determines the data type of the output texture. To force a different type for the texture, use the "type" option. For example, to guarantee 16 bit integer textures:

texdc -2 gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"type" ["short"]

    RtString type = "short";
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_TYPE, (RtPointer)&type, RI_NULL);

The complete set of possibilities are "byte", "short", "word", and "float". The corresponding arguments to texdc are "-1", "-2", "-4", and "-f", respectively. The "word" format is a 32 bit integer and the "float" type is 32-bit IEEE floating point.

Pattern

RenderDotC's texture file format is multiresolution TIFF. Besides the base image at full resolution, other lower resolution versions are filtered and stored. The default method, called "diagonal", is to reduce both the width and height by half at each step. The other patterns are "single" and "all". The "single" pattern stores just the base resolution, resulting in a small file but inferior image quality. The "all" pattern stores every combination of width and height which results in large texture files but may give better quality than "diagonal".

To changed the pattern from "diagonal" to "single", for example:

texdc -p single gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"pattern" ["single"]

    RtString pat = "single";
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_PATTERN, (RtPointer)&pat, RI_NULL);

Shadow maps are always "single", so setting the pattern has no effect on them.

Uncompressed textures

All texture, shadow, and environment maps are compressed by default. This results in smaller texture files at a minor cost in access speed. To turn off compression:

texdc -u gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"compression" ["0"]

    RtString comp = "0";
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_COMPRESSION, (RtPointer)&comp, RI_NULL);

Note that the value is a string, not an integer. If converting the string to an integer results in anything non-zero, compression is turned on.

Signed data

Integer data types are unsigned by default, even if the input TIFF is signed. To force signed integer data:

texdc -g gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"signed" [1]

    RtInt issigned = 1;
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_SIGNED, (RtPointer)&issigned, RI_NULL);

If the input image is signed and the output texture is unsigned, negative values are clamped to zero. When going from unsigned to signed, large values may get clamped to the largest signed value.

One application of signed textures is displacement mapping, where a single channel texture file holds vertical offsets from surface level. Positive offsets represent bumps and negative offsets are gouges.

Reference black and white

For a thorough treatement of headroom, see the tutorial on quantizing for film. Texture and environment maps can carry reference black and white points. If none are present, reference black is zero and the maximum integer data value is assumed to be reference white. The texture() and environment() functions in SL automatically subtract reference black and divide by reference white when converting texture samples to floating point colors. To explicitly set reference black and white when building a texture or environment map:

texdc -b 16 -w 235 gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"refblack" [16] "refwhite" [235]

    RiInt black = 16;
    RtInt white = 235;
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK, RiBoxFilter, 1, 1,
        RI_REFBLACK, (RtPointer)&black, RI_REFWHITE, (RtPointer)&white, RI_NULL);

If the input TIFF was created by RenderDotC with RiQuantize set for headroom, then reference black and white will already be set up and automatically transferred to the texture file by default.

Warning: reference white is not automatically adjusted if the data type of the input and output files do not match.

Conditional build

If a TIFF file has already been converted to a texture map and hasn't changed since that time, it makes no sense to convert it again. To prevent wasting time rebuilding the same texture, use the "newer" feature:

texdc -n gravel.tif gravel.tex

MakeTexture "gravel.tif" "gravel.tex" "black" "black" "box" 1 1
"newer" [1]

    RtInt cond = 1;
    RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK, RI_BLACK,
        RiBoxFilter, 1, 1, RI_NEWER, (RtPointer)&cond, RI_NULL);

Before building a texture, the newer feature checks if the texture file already exists and, if so, if it's file time is newer than the input TIFF. If so, it immediately exits without rebuilding. If the output file does not exist or if the input has a more recent file time, then the texture is built as normal.

This feature can be useful in an automated toolstream with scripts or makefiles.

TIFF

Every distribution of RenderDotC comes with two built-in display drivers: one for rendering to the framebuffer and one for creating files in the TIFF format. Which one gets used depends on the RiDisplay function. In RIB:

Display "gears.tif" "file" "rgb"

will send the image to a TIFF file. The "tiff" token is synonymous with "file", so this does exactly the same thing as the example above:

Display "gears.tif" "tiff" "rgb"

View TIFF files with your favorite image viewing program. On some platforms, RenderDotC comes with a simple tool called "tiffgt" that displays files on the screen.

Notes for Windows users: Adobe Photoshop is a great program for manipulating TIFF files, but beware that the C++ compilers used by shaderdc may not work while Photoshop is running. The default image display program on Windows NT, Imaging by Wang, is a rather inferior program. It cannot handle TIFF files with an alpha channel (i.e. "rgba" files).

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.