| RIB: | Defaults: |
| Option "limits" "bucketsize" [x y] | [16 16] |
| Option "limits" "gridsize" [i] | [256] |
| Option "limits" "texturememory" [k] | [2048] |
| Option "limits" "openmaps" [n] | [10] |
| Option "limits" "zthreshold" [r g b] | [1.0 1.0 1.0] |
| Option "limits" "eyesplits" [i] | [10] |
| Option "shadow" "bias0" [x] | [0.15] |
| Option "shadow" "bias1" [y] | [0.3] |
| Option "shadow" "bias" [x] | - none - |
| Option "searchpath" "shader" ["s"] | [".:$RDCROOT/shaders"] |
| Option "searchpath" "texture" ["s"] | [".:$RDCROOT/texture"] |
| Option "searchpath" "display" ["s"] | [.:$RDCROOT/etc] |
| Option "searchpath" "archive" ["s"] | [.] |
| Option "searchpath" "resource" ["s"] | - none - |
| Option "searchpath" "procedural" ["s"] | [.] |
| Option "statistics" "progress" [b] | [0] |
| Option "statistics" "endofframe" [i] | [0] |
| Option "statistics" "dynamic" [i] | [0] |
| Option "statistics" "filename" ["s"] | [""] |
| Option "statistics" "debug" [b] | [0] |
| Option "texture" "enable lerp" [x] | [1.0] |
| Option "texture" "enable gaussian" [x] | [1.0] |
| Option "render" "specularbrdf" ["s"] | ["prman"] |
| Option "render" "prmanspecular" [i] | [2] |
| Option "noise" "algorithm" ["s"]
"impulses" [i] |
["perlin"]
[4] |
| Display name,type,mode "origin" [x y] | - none - |
| Display name,type,mode "resolution" [x y] | [1 1] |
| Display name,type,mode "resolutionunit" ["s"] | - none - |
| Display name,type,mode "compression" ["s"] | "LZW" |
| Hider "hidden" "depthfilter" ["s"] | "min" |
| Attribute "dice" "binary" [b] | [0] |
| Attribute "dice" "rasterorient" [b] | [1] |
| Attribute "dice" "motionfactor" [x] | [0.0] |
| Attribute "bound" "displacement" [r] | [0.0] |
| Attribute "displacementbound" "sphere"
[r]
"coordinatesystem" ["s"] |
[0.0]
["object"] |
| Attribute "identifier" "name" ["s"] | - none - |
| Attribute "identifier" "shadinggroup" ["s"] | - none - |
| Attribute "trimcurve" "sense" ["s"] | ["inside"] |
| Attribute "trimcurve" "primitives" ["s"] | ["nupatch"] |
| GeometricApproximation "motionfactor" x | 0.0 |
| GeometricApproximation "subdivisionsteps" x | - none - |
| GeometricApproximation "subdivideonly" x | 0.0 |
| Option "rib" "server" ["s"] | - none - |
| Option "rib" "host" ["s"] | - none - |
| Option "rib" "pipe" [i] | - none - |
| Option "rib" "precision" [i] | [6] |
| Option "rib" "format" ["s"] | ["ascii"] |
| Option "rib" "compression" ["s"] | ["none"] |
| Option "rib" "indentstep" [i] | [4] |
| Option "rib" "balance" [b] | [1] |
| Option "rib" "outputalldeclares" [b] | [0] |
Option "limits" "bucketsize" [20 20]
Or, in C:
RtInt bucketsize[] = {20, 20};
RiOption(RI_LIMITS, RI_BUCKETSIZE, (RtPointer)bucketsize,
RI_NULL);
Increasing the bucket size can speed up rendering at the expense of increased memory requirements.
Option "limits" "gridsize" [400]
Increasing the grid size speeds up rendering but uses more memory. A good rule of thumb is that grid size should be no less than x bucket size times y bucket size divided by shading rate. For example, if the shading is set to 1 and bucket size is [20 20], then grid size should be at least 400. Smaller values wouldn't save much memory.
Option "limits" "texturememory" [1024]
Increasing the size may improve the performance of texture, environment, and shadow mapping. The tradeoff is a constant-sized piece of memory.
Option "limits" "openmaps" [15]
Unix systems sometimes have a limit of 20 open files per process, including standard in, standard out, and standard error. Be careful not to set openmaps so high that the system limit may be exceeded.
Option "limits" "zthreshold" [0.0 0.0 0.0]
In order to cast a shadow, the red, green, and blue components of opacity all must be greater than the corresponding channel in zthreshold.
object <unnamed> will not split at eye plane
To control the number of times a primitive can be split before before being discarded:
Option "limits" "eyesplits" [4]
Using a lower number causes the renderer to spend less time splitting such objects, but results in more geometry being thrown away. A good way to sidestep the problem is to use a near clipping plane that is further away than the default value of RI_EPSILON.
To cure self-shadowing, a small amount called a bias is added to the depth in the shadow map before the comparison. The actual bias value is the average of bias0 and bias1 (there are two values for historical reasons only). These two values may be set with:
Option "shadow" "bias0" [0.1]
Option "shadow" "bias1" [0.1]
Note that bias0 may equal bias1. A shortcut to set the final bias value is:
Option "shadow" "bias" [0.1]
If the biases are set too small, self-shadowing occurs. If the biases are too large, shadows appear "detached" from the objects which cast them.
The '@' character may be used as a shorthand for the standard path. The '&' symbol represents the previous value of the path. Some examples of setting paths are:
Option "searchpath" "shader" ["/usr/al/shaders:&"]
Option "searchpath" "texture" ["/usr/al/texture:&"]
Option "searchpath" "display" ["/usr/al/etc:&"]
Option "serachpath" "archive" ["/usr/al/ribs:&"]
Option "searchpath" "resource" ["/usr/al/shaders:/usr/al/texture:&"]
Option "searchpath" "procedural" ["/usr/al/dsos:&"]
The display searchpath is for locating custom display drivers. The archive searchpath tells RiReadArchive where to look for RIB files. The resource searchpath sets both the shader and texture search paths. Option "searchpath" "procedural" specifies where to look for procedural primitives.
When searching for a compiled shader, display driver, or procedural, the renderer takes the first name from the search path and looks in the architecture specific subdirectory RMAN_ARCHITECTURE. If not found there, it then looks in the directory name exactly as specified in the search path. If not found, it moves on to the next directory in the search path and repeats the two step process. The user can take more control of this process by explicitly putting $ARCH (or, equivalently, %ARCH) in the name of shader, display driver, or procedural.
There's an additional texture search feature. If the RIB says:
Surface "paintedplastic" "texturename" ["grid.tex"]
RenderDotC first searches the whole path for a file named "grid.tex.tdc". If that comes up empty, it starts over looking for "grid.tex". This way, RenderDotC textures can coexist in the same directory as those for another renderer without requiring modification to the RIB. Just name the RenderDotC texture "grid.tex.tdc".
Special notes for Windows users: Search paths under Windows traditionally used semicolons as delimiters, and colons to specify drives. To maximize portability of RIB files between UNIX and Windows systems, RenderDotC uses colons for both delimiters and to specify drives. Both forward slashes and backslashes are allowed under Windows, but be aware that backslashes must be doubled. Backslash is the escape character in both C and RIB.
An example path under Windows is:
Option "searchpath" "shader" ["D:/shaders:C:/al/shaders:&]
Note the dual use of the colon.
Option "statistics" "progress" [1]The argument is zero for off and non-zero for on. Progress is printed to standard out followed by a carriage return, but no newline, so that subsequent progress reports will overwrite the current one. An environment variable may also be used to turn on progress, but the Option can override that.
Option "statistics" "endofframe" [1]
For more detailed data structure statistics:
Option "statistics" "endofframe" [2]
To add texture mapping statistics:
Option "statistics" "endofframe" [3]
The end of frame statistics level may also be set with an environment variable, but the "Option" form will take precedence. To print statistics during the frame, replace "endofframe" with "dynamic":
Option "statistics" "dynamic" [2]This will dump the statistics once for every 10% of progress for a total of 10 times per frame (including the final report at the end of frame). To send the statistics to a named file:
Option "statistics" "filename" ["stats.out"]The default filename is the null string "", indicating standard out.
Option "statistics" "debug" [1]Acceptable values are zero for off and non-zero for on.
Option "texture" "enable lerp" [0.0]
Setting enable lerp to anything non-zero enables the trilinear mip-mapping option. Individual texture accesses may request bilinear or trilinear mip-mapping, but setting the enable lerp option to 0.0 will override.
Option "texture" "enable gaussian" [0.0]
Any value besides 0 enables the full set of interpolators, including triangle and catmull-rom. The desired interpolator may be specified in the shading language call to a texture function, but linear interpolation will always be used if enable gaussian is 0.
Option "render" "specularbrdf" ["torrance"]
Examples of each BRDF applied to a teapot are shown below. All
were rendered with RDC by exercising the "specularbrdf" option.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
For compatibility with BMRT, the specular BRDF may also be selected by number:
Option "render" "prmanspecular" [1]
The mapping from number to name is as follows:
0 = "standard"
1 = "bmrt"
2 = "prman"
3 = "rdcclassic"
4 = "torrance"
BMRT supports only 0 and 1. Therefore, a model which uses the "prmanspecular" option to select 0 or 1 will render with the same BRDF in both RenderDotC and BMRT.
Option "noise" "algorithm" ["perlin"]
The selected algorithm will then be used by the shading language functions noise() and pnoise(). The Perlin algorithm is based upon the paper "An Image Synthesizer" by Ken Perlin from the SIGGRAPH 1985 Proceedings. The actual functions used are adapted from SIGGRAPH 1992, course 23, by Ken Perlin. Here are some statistics on the Perlin algorithm gathered over a million samples:
Domain
Mean Min Max
Std. Dev
1-D: noise 0.5001
0.0527 0.9336 0.1393
2-D: noise 0.5000
0.0108 0.9807 0.1486
3-D: noise 0.5001
0.1144 0.9060 0.1043
4-D: noise 0.4999
0.2040 0.8032 0.0779
The Lewis algorithm is based on the sparse convolution method presented in "Algorithms for Solid Noise Synthesis" by J. P. Lewis from the SIGGRAPH 1989 Proceedings. It takes an additional parameter, the number of impulses per voxel:
Option "noise" "algorithm" ["lewis"] "impulses" [8]
The range of allowable impulses is 1 to 256. More impulses gives higher quality noise but takes longer to compute. Here are the statistics of the Lewis noise algorithm with 10 impulses per voxel, taken over a million samples:
Domain
Mean Min Max
Std. Dev
1-D: noise 0.5253
0.2475 0.7673 0.0900
2-D: noise 0.4820
0.1224 1.0013 0.1115
3-D: noise 0.4519
0.1081 0.9911 0.1072
4-D: noise 0.3367
0.0667 0.7890 0.1812
Note that Lewis noise sometimes exceeds 1.0 but never goes below 0.0.
Planar cross-sections of 3D noise generated by each algorithm are shown
below. While the Perlin algorithm is widely used and efficient to
generate, it suffers from directional artifacts and always returns 0.5
when passed whole numbers.
 |
 |
|
|
|
Display "pic.tif" "file" "rgba" "origin" [50 50]
This field may be picked up by a TIFF viewing program to know where to place the upper left corner of the image on the screen.
To set the resolution:
Display "pic.tif" "file" "rgba" "resolutionunit" ["inch"] "resolution" [72 72]
The resolution unit may be "inch", "centimeter", or "null". The resolution then specifies the number of pixels per resolution unit in both x and y. This information may be useful when printing out a hardcopy of a TIFF image.
Finally, the type of TIFF compression may be set with:
Display "pic.tif" "file" "rgba" "compression" ["packbits"]
Accepted values of compression are "LZW" (note: uppercase), "packbits", "jpeg", "deflate", "pixarlog", and "none".
The depth filter may be selected as follows:
Hider "hidden" "depthfilter" ["midpoint"]
Recognized depthfilters are "min", "max", "average", and "midpoint". The "min" depthfilter uses the minimum z value of all the samples within a pixel as the final z value for the whole pixel. Likewise, "max" uses the maximum z value and "average" uses the arithmetic mean.
The "midpoint" depthfilter is special. At every sample point, the average depth of the nearest two surfaces is recorded (instead of just the nearest surface). If the sample hits zero or one surfaces, the midpoint depth is infinity. If there is more than one sample per pixel, the minimum midpoint depth of all the samples in the pixel is recorded.
The recommended depth filters for generating shadow maps are midpoint
and min. Midpoint shadows take a little longer to render but are
free from bias artifacts. To generate a grayscale image for visual
inspection only, the average depthfilter may give the best looking results.
Attribute "dice" "binary" [1]
This can curtail patch cracks but requires additional processing.
Attribute "dice" "rasterorient" [0]Primitives with the rasterorient attribute turned off will be diced only on the basis of distance from the camera, shading rate, and raster resolution. The orientation of the camera and of the micropolygons themselves will be disregarded. Note that micropolygons at the far side of a primitive may still be larger (in world space) than those at the near side due to their difference in distance from the camera.
One situation where this non raster oriented dicing could be beneficial is when large displacements cause silhouette micropolygons to turn and face the camera, exposing their size. Another possibility is to use non raster oriented dicing along with binary dicing to minimize patch cracks.
The preferred form for setting displacement bounds is:
Attribute "displacementbound" "sphere" [.35] "coordinatesystem" ["shader"]
The "sphere" part specifies the maximum distance that a displacement shader may move a point in any direction. The "coordinatesystem" explains which space the distance is described in. Note that "sphere" and "coordinatesystem" must be specified in the same call to Attribute in order to work together. If Attribute were called twice, once with "sphere" and once with "coordinatesystem", RenderDotC would not put it together correctly.
The coordinatesystem may be any of the following:
For backward compatibility, another form is provided:
Attribute "bound" "displacement" [0.15]
This form should be avoided because the implied coordinate system is always "camera".
Attribute "identifier" "name" ["arm"]
Attribute "identifier" "shadinggroup" ["robot"]
Primitives may each have a unique name but be organized into shading groups. Management of the hierarchy is left up to the creator of the RIB.
Attribute "trimcurve" "sense" ["outside"]
By default, trim curves only apply to the NuPatch primitive. To make trim curves apply to other primitives, such as quadrics:
Attribute "trimcurve" "primitives" ["all"]
The other acceptable value is "nupatch" for the default behavior. Trim curves operate in parametric space. For most primitives, that is constrained to 0 - 1 in both u and v. NuPatches may cover any range in parametric space as specified by umin, umax, vmin, and vmax. The parametric space of polygons is defined by u = x and v = y. Care must be taken when applying trim curves to polygons. For instance, it is impossible to trim a polygon that is defined perpendicular to the x-y plane.
Motion factor takes care of the details:
GeometricApproximation "motionfactor" 1.0
Or, equivalently:
Attribute "dice" "motionfactor" [1.0]This sets up a sliding scale for shading rate depending on the approximate distance an object moves (measured in pixels). By default, motion factor is 0.0 which means that no adjustment to shading rate is made for motion blur. The value of 1.0 is appropriate for most situations. Values higher than 1.0 result in the shading rate being boosted even more.
GeometricApproximation "subdivideonly" 1.0
This will likely take more CPU and memory resources.
Another option is to subdivide the entire primitive a fixed number of times:
GeometricApproximation "subdivisionsteps" 4.0
Use this with caution as it defeats RenderDotC's adaptive tessellation scheme. Subdivision surfaces will be immediately diced by subdividing them exatly the number of times specified, regardless of aparent size on the screen. Remember that there are about four times as many faces at level n+1 than there are at level n, so memory requirements rise exponentially with subdivision steps. Values higher than 5.0 are discouraged because of the memory requirements.
Important note for Windows users: RiOption("rib", "pipe") is not available in the Windows version of RenderDotC. The reason is that Windows prohibits passing an open file handle across DLL boundaries. Instead, RiBegin("| programname") should be used when it is necessary to pipe RIB to an external program.
The highest priority is given to an open file descriptor. One can directly pipe the RIB output to another program (one which accepts RIB input from stdin) as follows:
#include <stdio.h>
...
FILE *fp = popen("renderdc", "w");
if (fp) {
RtInt fd = fileno(fp);
RiOption("rib", "pipe",
(RtPointer)&fd, RI_NULL);
}
RiBegin(RI_NULL);
...
RiEnd();
pclose(fp);
Second priority is given to the string passed to RiBegin:
RtString server = "file.rib";
RiOption("rib", "server", (RtPointer)&server,
RI_NULL);
The "host" option is synonymous with "server". The following does exactly the same thing as the example above:
RtString host = "file.rib";
RiOption("rib", "host", (RtPointer)&host,
RI_NULL);
Note that this overrides the value of the RISERVER environment variable, but can be overridden itself by the string passed to RiBegin().
RtInt sigdig = 8;
RiOption("rib", "precision", (RtPointer)&sigdig,
RI_NULL);
If this option is not specified, the value of the environment variable RIPRECISION is used. If no environment variable is set, the default value from the table above is used.
RtString binary = "binary";
RiOption("rib", "format", (RtPointer)&binary,
RI_NULL);
Valid values are "ascii" and "binary". If this option is not specified, the value of the environment variable RIFORMAT is used. If no environment variable is set, the default value from the table above is used.
RtString gzip = "gzip";
RiOption("rib", "compression", (RtPointer)&gzip,
RI_NULL);
Valid values are "none" and "gzip". If this option is not specified, the value of the environment variable RICOMPRESSION is used. If no environment variable is set, the default value from the table above is used.
To turn the RIB balancing feature on or off:
RtInt off = 0;
RtInt on = 1;
RiOption("rib", "outputalldeclares", (RtPointer)&on, RI_NULL);