5.1 Options

Options are parameters of the graphic state that apply to the entire scene. All options are saved at each RiFrameBegin and restored at the corresponding RiFrameEnd call. It is important to set these options before the RiWorldBegin…RiWorldEnd block since it is a RenderMan assumption that rendering may begin any time after RiWorldBegin; all options must be fixed by then. Also, and contrary to transforms, the order in which options appear is not important.

The RenderMan API declares a standard set of options (which are used to control camera and image parameters) and opens a door to implementation specific options through the RiOption call. 3Delight supports all of the standard options and has some specific calls; both groups are described in the following sections. For added flexibility, many default option values are re-definable through a special initialization file as described in Configuration file (`rendermn.ini').

5.1.1 Image and Camera Options
5.1.2 Implementation Specific Options

5.1.1 Image and Camera Options

All the standard options are supported and are listed in Table 5.2 along with their default values. Some of those options have an extended behavior in 3Delight:

RiDisplay

Since the renderer uses floating point numbers internally, the colors are exposed and quantized using the values specified with the RiExposure and RiQuantize calls. However, one may want to expose and quantize colors differently for each RiDisplay. This is made possible by specifying exposure, quantization and dithering values directly to RiDisplay. Other settings can also be overridden for each display; see Table 5.1 for the full list. An extended RiDisplay command would look like:

Display "file" "driver" "variable"
    "exposure" [gain gamma]
    "string colorprofile" "colorprofile"
    "quantize" [zero one min max]
    "dither" [amplitude]
    "filter" "filtername"
    "filterwidth" [xwidth ywidth]

Note that there are four values given to quantize compared to three when calling RiQuantize. This extended syntax allows specifying a value for zero (black), whereas RiQuantize assumes this value to be `0'. Using this fourth parameter, colors are quantized using the following formula:

value = round(zero + value * (one - zero) + dithervalue)
value = clamp(value, min, max)

The "filter" parameter accepts all the same filters as RiPixelFilter but also "zmin" and "zmax". These are special filters as they also affect the compositing of visible surfaces: only the frontmost surface with an opacity exceeding that specified by the zthreshold option is retained (see zthreshold). The samples are then filtered by always picking the value of the one with the smallest z over the filtering area (for zmin, greatest z for zmax). These filters are useful for output variables which should not be composited, such as surface normals or object identifiers.

Table 5.1: Implementation specific RiDisplay parameters.

Parameter Default Value Description "float exposure[2]" RiExposure Overrides global exposure. "string colorprofile" "linear" This parameter accepts either "linear", "srgb" or "BT.709" and applies the specified profile to the output data. Note that the alpha channel doesn't get corrected with this profile. "string ociocolorspace" "" This parameter accepts an OpenColorIO color space to be applied to the output data. See OpenColorIO configuration. "float quantize[4]" RiQuantize Overrides global quantization. "float dither" RiQuantize Overrides global dithering. "string filter" RiPixelFilter Overrides global filter. Can also be `zmin' or `zmax' when outputting the `z' variable. "float filterwidth[2]" RiPixelFilter Overrides global filter width and height. "int associatealpha" 1 When set to 0, color is divided by alpha to provide an image with an unassociated alpha channel. With AOVs, an alpha channel should be explicitely added if it is not equal to the default alpha. "int matte" 1 When set to 0, the output will ignore the matte attribute (as set by RiMatte). Only works for AOVs. "int exclusive" 0 When set to 1 for an AOV, objects which do not output the variable will be transparent instead of the usual black. "string subset" "-" Allows each display to show only a subset of the scene objects. It has the same semantics as trace subsets. See section Trace Group Membership. "string mattesubset" "-" Allows each display to specify different matte objects. The objects not in the specified subset are seen as matte objects, with the same selection semantics as trace subsets. See section Trace Group Membership. "string lightcategory" "" Allows each display to show contribution only from lights which match the given category specification. See Light Categories. This feature works only with the raytrace hider. A special "__environment" category is supported and will display only the environment map contribution from the trace() shadeop. A single light can also be identified by handle by specifying "light:handle" here. Each different value for this parameter will add a little to the render time. This can often be improved by marking some coshaders as not light dependent, with a "float __lightdependent" parameter or member set to 0. "string namesuffix" "" If given, this suffix is added to the channel names passed to the display driver. It does not change the variable actually output.

Another useful feature supported by RiDisplay is file name formatting. It uses special codes starting with the special `#' character to indicate where to insert useful information in the file name. The accepted special codes are:

` #f'

Is replaced by current frame number, specified by RiFrameBegin

Display "frame#f.tif" "tiff" "rgb"

` #s'

Is replaced by the sequence number. This number is incremented at each RiFrameBegin, regardless of the frame number provided. Sequence numbering starts at "1".

` #n'

Is replaced by the "running sequence number", a counter that is incremented at each RiWorldBegin. First value is "1".

` #d'

Is replaced by the display type. The file name in the following example is set to `image.tiff':

Display "image.#d" "tiff" "rgb"

` #r'

Is replaced by "3delight" (renderer's name).

` ##'

Is replaced by a `#'.

Special codes which print numerical values can contain an alignment specifier after the `#', as in `frame#5f.tif' which would yield `frame00001.tif'. It is also possible to output only a single element of an output variable by using the following syntax:

Display "file.tif" "tiff" "color many_colors[6]:2"

This would output the element at position 2 in the array of 6 colors named many_colors. To compute an alpha channel specific to a given AOV, simply add the standard alpha variable:

Display "+foreground.tif" "tiff" "color foreground,alpha"

3Delight is able to output user attributes (see section User Attributes) directly, like this:

Display "attrib1.tif" "tiff" "float attribute:user:attrib1"

RiHider

RiHider supports the `hidden' hider as well as the `raytrace' and `photon' hiders (refer to Photon Mapping). The optional parameters are as follows:

Hider "hidden|raytrace"
    "integer jitter" [1]
    "integer samplemotion" [1]
    "float aperture[4]" [nsides angle roundness density]
    "float apertureaspectratio" [1]
    "integer extrememotiondof" [0]
    "string depthfilter" "min"
    "int maxvpdepth" [-1] 
    "float midpointratio" [0.5] 
    "int progressive" [0]
    "int samplelock" [1]

A description for each hider parameter follows (note that some of the parameters apply only to one particular hider):

Hider "hidden|raytrace" "jitter" [1]

Selects the sampling pattern to use. `0' uses a regular sampling grid and `1' uses a "jittered" grid.

Hider "hidden|raytrace" "samplemotion" [1]

Disables motion blur sampling when set to 0. Unlike setting the shutter open and close times to the same value by using RiShutter, this method will preserve the dPdtime vectors for use in shaders or as output variables.

Hider "hidden|raytrace" "float aperture[4]" [nsides angle roundness density]

This feature can be used to specify a polygonal bokeh in both REYES and ray-tracing modes. nsides specifies the number of sides (blades) in the aperture and angle is used to specify the rotation, in degrees, of the aperture. roundness and density are not supported yet. Note that if nsides is smaller than 3 then the bokeh is round. The default value for nsides is 0 which means that aperture is round.

Hider "hidden|raytrace" "float apertureaspectratio" [1]

This alters the aspect ratio of the bokeh, allowing it to look similar to what is produced by an anamorphic lens.

Hider "hidden" "extrememotiondof" [0]

The default algorithm used to sample depth of field and motion blur may cause sampling artifacts (commonly known as ghosting) when objects are out of focus and moving. Setting this parameter to 1 will use an alternate algorithm which produces higher quality for this particular case. This algorithm is slower so it should be used only if necessary. Values of 2 or greater allow for a speed vs. quality tradeoff, with larger values increasing quality.

Figure 5.1: An out of focus moving disk rendered with extrememotiondof set to 0 (top) and 1 (bottom).

Hider "hidden" "depthfilter" "filter name"

Sets a filter type for depth values filtering. The filter name may be one of the following:

` min'

The renderer takes the minimum z value of all the sub samples in a given pixel.

` max'

The renderer takes the maximum z value of all the sub samples in a given pixel.

` average'

The renderer averages all sub samples' z values in a given pixel.

` midpoint'

For each sub sample in a pixel, the renderer takes the average z value of the two closest surfaces (or as dictated by the `midpointratio' hider paramter). Depth associated with the pixel is then computed using a min filter of these averages. Note that midpoint filtering may slow down renders slightly.

Hider "hidden" "int maxvpdepth" [-1]

Sets a limit on the number of visible points for each sub-samples. This means that no more than `maxvpdepth' surfaces will be composited in the hider or included in deep shadow map creation. Putting a limit on the number of visible points can accelerate deep shadow map creation for depth complex scenes. The default value is `-1' which means that there is no limit on visibility lists lengths.

Hider "hidden" "float midpointratio" [0.5]

Allows control over the blending of the z values of the first two samples when using the midpoint depthfilter. A value of zero will use the depth of the first sample while a value of one will use the depth of the second sample. Values in between blend both depths.

Hider "raytrace" "int progressive" [0]

Setting this to 1 enables progressive rendering with the raytrace hider. The effect will only be visible with some display drivers (such as idisplay).

Hider "raytrace" "int samplelock" [1]

This option affects how the random number generator is initialized for some sampling shadeops (e.g. trace()). When `samplelock' is set to 1, the seed of the random number generator will be the same for any render, which means that any noise perceived in an animation will tend to look static. When set to 0, the seed of the random number generation is dependent on RiFrameBegin so the sampling noise will change from frame to frame.

More detail about the ray trace hider can be found in The Ray Tracing Hider. The `photon' hider accepts the `emit' parameters as described in Two Pass Photon Mapping.

Table 5.2: Standard RenderMan options and their default values.

Option Default Value Comments RiFormat 640 480 1 - RiFrameAspectRatio 1.0 Square pixels RiScreenWindow -1.3333 1.3333 -1 1 Default computed using RiFormat (640/480 = 1.333...). RiCropWindow 0 1 0 1 No cropping. RiProjection "orthographic" - RiClipping 0 1e30 - RiPixelSamples 2 2 If motion blur or depth of field are used, increase these values to at least 4 4. RiPixelFilter "box" 2 2 A high quality setting would be "sinc" 6 6. RiExposure 1.0 1.0 Gain = 1, Gamma = 1 RiDisplay "default.tif" "tiff" "rgba" Create a RGB TIFF named `default.tif'.

5.1.2 Implementation Specific Options

3Delight uses implementation specific options only when no standard option provides the desired functionnality. Even if we call them "implementation specific," most of the options described in the following section are commonly used and well defined in other RenderMan implementations. All the supported implementation specific options are listed in Table 5.3 along with their default values.

Rendering Options
Quality vs. Performance Options
Search Paths Options
Statistics Options
Messages Options
Network Cache Options
User Options
RIB Output Options
Other Options

Rendering Options

Option "shadow" "float bias0" [0.225]

Option "shadow" "float bias1" [0.3]

Option "shadow" "float bias" [0.225]

When using shadow maps, a surface may exhibit self-shadowing. This problem is caused by precision errors and quantization and appears as gray spots on the surface. This problem occurs when the distance of an object to a light source computed while rendering a shadow map is slightly less than the distance computed while rendering the image. To prevent self shadowing, specify a bias, which is a value that is added to the shadow map value. If `bias0' is different from `bias1', the renderer chooses a random value between them for each sample. Note that those parameters do not affect ray traced shadows. The value of `bias0' and `bias1' should be set to `0' if the "midpoint" algorithm is used to compute the shadow map, see Options for more details on how to use the "midpoint" algorithm.

Option "render" "integer nthreads" n

Specifies how many threads to use for the render. Specifying `0' tells 3Delight to use as many threads as there are processors. If the value is negative, it is added to the number of processors to compute the number of threads to use. Refer to Multithreading and Multiprocessing for a more thorough discussion about multi-threading.

Option "render" "string bucketorder" "horizontal"

In order to save memory, the image is rendered progressively in small groups of pixels refered to as "buckets." This option specifies the rendering order of the buckets. Valid values are:

` horizontal'

Rendered left to right, top to bottom (this is the default).

` zigzag'

Rendered left to right on even rows, right to left on odd rows. This ordering is slightly more memory efficient than `horizontal'.

` vertical'

Rendered from top to bottom, left to right.

` spiral'

Rendered in a clockwise spiral starting at the center of the image.

` circle'

Rendered in concentric circles starting at the center of the image.

` random'

Rendered in no particular order. Should not be used since it is not memory efficient.

Option "render" "integer standardatmosphere" [1]

Traditionnally, volume shaders are applied on top of surface shaders on a per surface basis. While this approach is fine for basic effects like the depthcue shader, it is very limiting for more complex volumetric effects which make use of ray marching. It suffers from a well known issue with transparent surfaces: parts of the volume are integrated several times leading to undesirable artifacts. It also becomes very slow as the geometric complexity of the scene increases.
This option, when set to `0', allows the use of an alternate algorithm better suited for volumetric effects. It handles transparent surfaces properly and provides better performance characteristics with complex scenes. However, it requires that volume shaders follow a few rules for proper composition.

1. The volume shader must be built so that it can be evaluated independently of the surface and later composited. Volume shaders are normally given the color and opacity of the surface as input but with this option they will receive only black. Thus, they must do their work without surface values.

   volume lazy_fog()
   {
       color Cv = 0; /* volume's color */
       color Ov = 0; /* volume's opacity */
   
       /* Main code here to compute Cv and Ov. */
   
       /* Composite the volume with the surface. */
       Ci = Cv + (1 - Ov) * Ci;
       Oi = Ov + (1 - Ov) * Oi;
   }
   

   That last composition step allows the same shader to work in both modes.
2. The volume shader must compute the atmospheric effect from P to P-I, not from P to E as is often done. Also, the shader must be built such that splitting the evaluation range in two at any point and compositing the result of the evaluation of both subranges yields the same values. This will enable partial evaluation of the volume when it is split by transparent surfaces. This condition can be ignored if no transparent surfaces are ever used. This requirement means that volume marching shaders are usually best written as a compositing loop:

   volume volumetric_smoke()
   {
       color Cv = 0; /* volume's color */
       color Ov = 0; /* volume's opacity */
   
       /* Main volume marching/integration loop. */
       while( ... )
       {
           color Ce = 0; /* volume element color */
           color Oe = 0; /* volume element opacity */
   
           /* Compute Ce and Oe here for one volume element. */
   
           /* Composite the volume element in front of the previous ones. */
           Cv = Ce + (1 - Oe) * Cv;
           Ov = Oe + (1 - Oe) * Ov;
       }
   
       /* Composite the volume with the surface. */
       Ci = Cv + (1 - Ov) * Ci;
       Oi = Ov + (1 - Ov) * Oi;
   }
   

Option "render" "float volumeshadingrate" [1.0]

This options controls the frequency of shading for interior shaders. It also applies to atmosphere shaders if the "standardatmosphere" option is set to 0. Its meaning is similar to the ShadingRate attribute: it represents the area in pixels of a shading element for volumes.

RiOption( "render", "stopcallback", &function_ptr, RI_NULL )

This option, only available through a direct RiOption call, accepts a pointer to a function which will be called at each rendered bucket or more often to allow user code to stop the render. The function prototype and option call are as follows:

int StopRender( void *data )
{
    ...
}

RtPointer callback = (RtPointer) &StopRender;
RiOption( "render", "stopcallback", &callback, RI_NULL );

Returning a value of 0 will let the render continue while a value of 1 will stop it. The function may be called from a different thread than the one which started the render. Some care should be taken to make the function execute quickly (eg. avoid calling into a UI toolkit). It should ideally simply test a flag which the application will set when it wants the render to abort. "stopper_function" is an alias to "stopcallback" for backward compatibility. It is also possible to use this callback to pause a render by delaying the return from the function.

RiOption( "render", "stopcallbackdata", &data, RI_NULL );

This option allows specification of the data parameter passed to the callback set with the "stopcallback" option above.

Option "shutter" "efficiency" [1.0 1.0]

These two values control the shape of the shutter opening and closing for motion blur. Smaller values provide a softer look.

Option "shutter" "offset" [0.0]

The specified value will be added to all subsequent RiMotionBegin calls. The main utility of this option is to write "canonical" RIB archives that always have the same motion range but are loaded from master RIBs that specify the current shutter time using this option. That way, an RIB archive is independent from shutter time and thus re-usable in each frame: no need to regenerate an archive because of shutter time change, only specify the current "offset" in the master RIB before loading the archive. See also the shutter offset attribute.

Option "shutter" "integer shuffle" [0]

With the raytrace hider, setting this option to 1 will use a different sampling of motion blur which will avoid some artifacts, at a cost in overall quality.

Option "trace" "specularthreshold" [-1]

This angle, specified in degrees, is used to determine if ray sampling patterns are of specular or diffuse nature. Patterns with an angle smaller than the value of this option are considered specular. This is used by the occlusion() and indirectdiffuse() shadeops as well as the gather statement. A value of -1 (default) disables this attribute completely.

IMPORTANT

Don't use this attribute since it can affect the visibility of objects since varying the angle in the tracing functions can change ray's type and hence the selection of visibility attributes. More about this attribute in visibility. The safe way to override the default ray type for each ray-tracing function is to use the `raytype' option as shown in Table 6.10. The only reason this attribute is provided is to keep compatibility with another RenderMan-compliant renderer.

Option "photon" "emit" [n]

Enables automatic photon map generation and specifies the total number of photons to cast in the scene. In this mode, the photon maps are not saved to disk by default. More about this option in Single Pass Photon Mapping.

Option "photon" "writemaps" [n]

If automatic photon map is generated, photon maps can still be written to disk if this option is set to `1'. Default is `0'.

Option "photon" "maxdiffusedepth" [10]

Option "photon" "maxspeculardepth" [10]

Specifies the maximum diffuse and specular bounces for photons when using the automatic photon map approach. In the two-pass approach (see section Two Pass Photon Mapping) the renderer will honour the maximums specified by "maxdiffusedepth" and "maxspeculardepth" trace attributes.

Quality vs. Performance Options

Option "limits" "integer bucketsize[2]" [16 16]

This option specifies the dimension of a bucket, in pixels. Using smaller buckets may reduce memory use at the expense of slight performance loss. In our experience, this default value is the best compromise for 3Delight.

Option "limits" "integer gridsize" [256]

During the rendering process, geometry is split into small grids of micropolygons. Shading is performed on one grid at a time. This option specifies the maximum number of such micropolygons per grid. The default value ensures that one grid covers approximately one bucket. Since by default RiShadingRate is one and buckets are 16 by 16 pixels wide, the default grid size is 16*16/1 = 256.

Option "limits" "integer eyesplits" [6] (14)

Specifies the number of times a primitive crossing the eye plane is split before being discarded.

Option "limits" "integer texturememory" [131072]

The memory needed to hold the texture for a scene may exceed the amount of core physical memory available. To render such scenes efficiently, 3Delight uses a memory caching system to keep the texture memory footprint below a predefined threshold. This option specifies the amount of memory, in kilobytes, dedicated to texture mapping algorithms. Increasing this parameter may improve texture, shadow and environment map access performance. Note that 3Delight also offers a texture file caching mechanism over networks, see Network Cache.

Option "limits" "integer geometrymemory" [500000]

This specifies the size of the displaced geometry cache for the ray tracer, in kilobytes.

Option "limits" "integer texturesample" [1]

Specifies the default oversampling value for texture() and environment() lookups. Note that texture() honors this value only if the `box' filter is selected (see Table 6.16) since the `gaussian' filter is an analytical anisotropic filter which doesn't use super sampling. Also, specifying a `samples' parameter to either texture() or environment() overrides this value.

Option "limits" "color othreshold" [0.99608 0.99608 0.99608]

Sets the limit opacity value above which surfaces or layers of surfaces are considered fully opaque. This cutoff value enables the renderer to cull geometry more aggressively. This threshold can provide significant time and memory savings especially for scenes with a large number of layered and semi-translucent surfaces. An example is shown in Figure 5.2. Setting this threshold to [1 1 1] disables opacity culling.

Figure 5.2: A patch of 50000 curves rendered with (top) and without (bottom) opacity culling. The difference is not perceivable (less than 0.4%). The full top image took 119 seconds and 63 MB of RAM to render. The bottom image took 151 seconds and 80 MB of RAM.

Option "limits" "color zthreshold" [0.99608 0.99608 0.99608]

Sets the limit opacity value above which surfaces are considered for depth calculations. For any given surface, the threshold is checked against the accumulated opacity from the camera up to that surface. The default value will cause surfaces to appear in shadow maps only when surfaces behind it are nearly hidden from the camera (ie. the surface itself or combined with surfaces in front of it is nearly opaque). Setting a lower value will make partially transparent surfaces also visible in shadow maps. If an object is marked as a matte, it will only cause depth to be set to infinity if it meets this threshold.

Option "limits" "integer volumegroupsize" [256]

Controls how many points are shaded together for interior shaders and atmosphere shaders if the "standardatmosphere" option is set to 0. There should not be any need to change this except for debugging shaders.

Option "shadow" "integer sample" [16]

Specifies the default oversampling value for shadow map and deep shadow map lookups. This only applies if the shadow call does not contain an oversampling value (see section Texture Mapping). This option does not affect ray traced shadows.

Option "trace" "integer maxdepth" [2]

This option sets the maximum recursion level for the ray tracer. Valid values are between 0 and 32, inclusively. Any value outside of this range is interpreted as 32 and a value of 0 turns off ray tracing. The default value is 2.

Option "trace" "float approximation"

This option sets a relative detail threshold below which ray intersections may be approximated. The number specifies the ratio between the area of the intersected primitive and the area of the ray at the intersection point(15). If the ratio is smaller or equal to the specified value, the intersection is performed on approximate geometry. The default value of 4 is a safe compromise between quality and speed (meaning that an object which is only 4 times larger than the footprint of the intersection point will be replaced by a more efficient proxy). A value of 0 can be used to turn this feature off completely. This optimization is especially beneficial for higher order surfaces such as subdivisions and NURBS.

Option "trace" "float depthaffectsptc" [1]

Specifies if ray depths should be checked when using point-based occlusion and color bleeding. For example, setting Option "trace" "maxdepth" [0] will, somewhat counter-intuitively, also disable point-based occlusion. To enable occlusion/indirectdiffuse even in this case one should set this option to 0.

Search Paths Options

A search path is a colon or semi-colon separated list of directories. The directories should be separated using a slash (`/') character. On WINDOWS platforms, it is possible to use cygwin's convention: `//c/dir1/...'.

Some symbols have a special meaning in a search path string:

• The `@' symbol specifies the default path. Default paths for each resource are settable through the configuration file (see section Configuration file (`rendermn.ini')) or through environment variables (see section Environment Variables). Environment variables overrides any value set in the configuration file.
• The `&' symbol specifies the previous path list.
• A word starting with a `$' and followed by uppercase letters (e.g. $HOME) is considered as an environment variable and is replaced by its value. If the specified variable does not exist, it is left untouched in the string.
• The `~' symbol, when placed at the beginning of a path, is equivalent to $HOME.

Search paths are specified using the following commands:

Option "searchpath" "string shader" "path-list"

Sets `shader' and DSO shadeops search path.

Option "searchpath" "string texture" "path-list"

Sets `texture' search path.

Option "searchpath" "string display" "path-list"

Sets `display' search path.

Option "searchpath" "string archive" "path-list"

Sets `archive' search path.

Option "searchpath" "string procedural" "path-list"

Sets `procedural' search path.

Option "searchpath" "string resource" "path-list"

Sets `resource' search path. This is equivalent to adding this path to all the above search paths.

Option "searchpath" "string dirmap" "[\"zone\" \"map-from\" \"map-to\"] [\"zone\" ... ] ... "

Sets a mapping table for all paths. Only entries where zone matches the current dirmap zone are used. Then, whenever a path begins with one of the map-from entries, this part is replaced by the corresponding map-to. The current dirmap zone defaults to UNC on Windows and NFS on all other platforms. It can be overridden in `rendermn.ini' (see section Configuration file (`rendermn.ini')). Note the quotes which are escaped here for the RIB syntax. In the `rendermn.ini' file, this is not necessary.

Option "searchpath" "string rslpluginmap" "[\"map-from\" \"map-to\"] [\"map-from\" \"map-to\"] ... "

Sets a mapping table for rsl plugin names. This can be used to make a shader use a different plugin than the one it was compiled with, as long as it contains the required functions.

Default values are shown in Table 5.3.

An environment variable can be set to track down searchpath related problems (see section Environment Variables).

Statistics Options

Statistics can prove useful when fine-tuning the renderer's behavior (for quality or performance reasons).

Option "statistics" "integer endofframe" [0]

Specifies the desired statistics level. The level ranges from 0 to 3, with 0 meaning no statistics at all and 3 meaning all possible statistics. A level of `2' is enough for most uses.

Option "statistics" "string filename" [""]

By default, statistics are dumped to the console (more specifically, to `stdout'); this option can be used to specify an output file name instead. If the file name has the `.html' or `.htm' extension, statistics are dumped in HTML format. Note: If specified, the file name should be on the same line as the "endofframe" statistic option in order to get statistics at all.

Option "statistics" "int progress" [0]

Turning this option on forces 3Delight to output a progress status (16) to the console. Output text looks like this:

0.33 %

Each line is printed after a bucket is done rendering.

RiOption( "statistics", "progresscallback", &function_ptr, RI_NULL )

This option, only available through a direct RiOption call, accepts a pointer to a function which will be called at each rendered bucket to indicate renderer's progress. The function prototype and option call are as follows:

void RenderProgress( float i_progress, void *data )
{
    ...
}

RtPointer callback = (RtPointer) &RenderProgress;
RiOption( "statistics", "progresscallback", &callback, RI_NULL );

The i_progress parameter will hold a real value in the range [0..100]. The function may be called from a different thread than the one which started the render.

RiOption( "statistics", "progresscallbackdata", &data, RI_NULL );

This option specifies the data parameter passed to the progress callback function set with the "progresscallback" above.

Messages Options

The following options can be used to control the output of various messages by 3Delight.

Option "messages" "string filter" ""

This option allows some error messages to be filtered out. It should be set to a comma separated list of unwanted error codes, such as "A2037,P1168". The values are not cumulative, meaning that setting the option to "" will cause all messages to appear again.

Option "messages" "float mindispbound" [50]

When a displacement bound is specified for an object and that object is displaced by far less than the specified value, 3Delight emits an informational message. This option controls the percentage below which the message is shown. The default value causes it to be shown when an object uses less than half its displacement bound.

Network Cache Options

3Delight has a network caching system for texture files located on "slow access" media (such as NFS and CD-ROM drives). Refer to Network Cache for a detailed description.

Option "netcache" "string cachedir" [""]

Specifies a directory for data caching. The directory should be locally mounted, such as `/tmp/3delight_cache' and should be dedicated solely to 3Delight. Do not use `/tmp' as a cache directory (`/tmp/3delight_cache/' is a better choice).

Option "netcache" "integer cachesize" [1000]

Specifies cache size in megabytes with one megabyte being 1024 Kbytes. To fully take advantage of this performance feature, specify a size big enough to hold many textures, ideally all the textures used in a given scene.

Option "netcache" "integer minfreespace" [0]

Specifies a minimum amount of free space in megabytes to leave on the drive where the netcache is located. This can effectively reduce the set cache size.

Option "netcache" "integer writecache" [0]

This can be set to 1 to enable write caching of the various output files produced by 3Delight.

Option "netcache" "string includepaths"

Specifies a colon or semicolon separated list of paths which are always cached even if they are not considered slow access.

Option "netcache" "string excludepaths"

Specifies a colon or semicolon separated list of paths which are never cached even if they are considered slow access.

User Options

Option "user" "type variable" value

Sets a user defined option. Such an option can then be read from inside a shader using the option() shadeop. See option shadeop. A simple example:

Option "user" "float shadow_pass" 1  # rendering a shadow

It is also possible to define user attributes, as explained in User Attributes.

RIB Output Options

These options are only meaningful when using the C API. More details and code snippets can be found in RIB Output.

RiOption( "rib", "archiveprocedurals", namepattern, RI_NULL )

When this is set to a non-empty string and RIB output is used, all RiProcedural calls are modified to use RiProcDelayedReadArchive. The required archive is generated and named according to namepattern which should contain the "#a" string to be replaced by a unique number for each archive.

RiOption( "rib", "callprocedurals", onoff, RI_NULL )

Enables or disables procedurals expansion during RIB output. onoff is a string and can be set to either `on' or `off'.

RiOption( "rib", "compression", compression, RI_NULL )

Specifies a compression for RIB output. The only supported compression is `gzip'. This option must be called before RiBegin.

RiOption( "rib", "format", format, RI_NULL )

Specifies the format of the output stream. format can either be `ascii' or `binary'.

RiOption( "rib", "header", onoff, RI_NULL )

Specifies if a header is written at the beginning of RIB output. This option must be called before RiBegin. onoff is a string and can be set to either `on' or `off'.

RiOption( "rib", "ident", onoff, RI_NULL )

Specifies if ascii RIB output is to be formatted nicely. onoff is a string and can be set to either `on' or `off'.

RiOption( "rib", "pipe", fd, RI_NULL )

Specifies a file descriptor to be used when outputing RIB. This option must be called before RiBegin.

Other Options

Option "licensing" "integer waitforlicense" 1

When this option is set to 1, 3Delight will wait for a license when none is available to render. If the option is set to 0, 3Delight will return immediately if no license is available and renderdl will return an error code of 99 (see renderdl return values). This is useful when managing a renderfarm and other work could be scheduled instead of the waiting 3Delight process.

Option "licensing" "integer holdlicense" 0

By default, 3Delight will get new licenses for every render and release them once the render is done. This can be undesirable if several frames are rendered from the same RIB or application session. If this option is set to 1, the licenses obtained for the first render are held until RiEnd() is called. For renderdl, this means until the last RIB is done processing.

Option "licensing" "string server" ""

Allows specification of the license server to use as an option. If this is left empty, the /3delight/licserver key from `rendermn.ini' is used instead. Note that this option must be set before the first world block to have any effect.

Option "limits" "float processmemory" 0

The render will abort with error R5060 if the process memory use in bytes exceeds the specified value. A value of zero disables the feature.

Option "ocio" "string configfilename" ""

This specifies the path to the OpenColorIO configuration file. If it is left empty, the OCIO environment variable is used to locate the configuration file.

Table 5.3: Implementation specific options and their default values.

Option Default Value Comments "shadow" "bias0" 0.225 - "shadow" "bias1" 0.300 - "render" "bucketorder" ["horizontal"] - "render" "standardatmosphere" 1 old behavior by default "render" "volumeshadingrate" 1.0 shades for every pixel "shutter" "efficiency" [1.0 1.0] The shutter opens and closes sharply. "shutter" "offset" 0.0 No offset. "limits" "bucketsize" [16 16] - "limits" "gridsize" 256 One grid is approximately as large as a bucket when RiShadingRate=1. "limits" "eyesplits" 6 Enough for most cases, larger values may slow down rendering. "limits" "othreshold" [0.99608 .. ..] - "limits" "texturememory" 131072 128 megabytes "limits" "geometrymemory" 500000 500 megabytes "limits" "texturesample" 1 - "limits" "zthreshold" [1.0 1.0 1.0] Consider only opaque objects for z. "limits" "volumegroupsize" 256 - "shadow" "sample" 16 - "trace" "maxdepth" 1 - "trace" "specularthreshold" 10 - "searchpath" "shader" `$DELIGHT/shaders' - "searchpath" "texture" `$DELIGHT/textures' - "searchpath" "display" `$DELIGHT/displays' - "searchpath" "archive" `$DELIGHT/archive' - "searchpath" "procedural" "" - "searchpath" "resource" "" - "searchpath" "dirmap" "" - "searchpath" "rslpluginmap" "" - "netcache" "cachedir" [""] No network caching. "netcache" "cachesize" 1000 1 gigabyte of disk space. Has no effect if caching is disabled. "netcache" "minfreespace" 0 - "netcache" "writecache" 0 Output files are not cached. "netcache" "includepaths" "" - "netcache" "excludepaths" "" - "statistics" "endofframe" 0 No stats. "statistics" "file" "" Outputs statistics to console (`stdout'). "statistics" "mindispbound" 50.0 -

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