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 cubits.rib tetra.rib
catribdc -g -b -o compressed.rib big.rib
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:
%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.
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.
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.
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.
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.
texdc -c -v 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);
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.
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.
texdc -b "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.
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.
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.
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.
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.
texdc -w 4095 gravel.tif gravel.tex
MakeTexture "gravel.tif" "gravel.tex" "black"
"black" "box" 1 1
"refwhite" [4095]
RtInt white = 4095;
RiMakeTexture("gravel.tif", "gravel.tex", RI_BLACK,
RI_BLACK,
RiBoxFilter, 1, 1, RI_REFWHITE,
(RtPointer)&white, RI_NULL);
If the input TIFF was created by RenderDotC with RiQuantize set for headroom, then reference 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.
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.
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).
The LICENSE_FILE environment variable is honored by both the server (licensedc) and the client (renderdc).
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
linux_intel
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 .
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".
.:$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).
.:$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).
.:./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).
.:$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:/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).
Option "statistics" "progress" [1]
This Option takes precedence over the state of the environment variable.
Option "statistics" "endofframe" [1]
This Option takes precedence over the state of the environment variable.
Option "statistics" "debug" [1]
This Option takes precedence over the state of the environment variable.
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.
RtString none = "none";
RtString gzip = "gzip";
RiOption("rib",
"compression", (RtPointer)&gzip, RI_NULL);
This must be called before RiBegin() to be effective.
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.