Usage and Command Line Options

When started from a shell command line, mental ray accepts a large number of options. Most of these correspond to similar commands or camera or options statements as described in the Scene Description chapter. The relevant explanations there are repeated in this chapter. When an option is given on the command line, it overrides the corresponding command or statement in the scene file, which in turn overrides the defaults. The defaults for certain options given in the option list below apply only if the corresponding command or statement is not present in the scene file.

For the option description, the same metasymbols as in the Scene Description chapter are used: a bar ``|'' denotes alternatives, items enclosed in tall square brackets ``[ ]'' are optional, and the ellipsis ``...'' denotes omission. Literal text is set in teletype, while variable metasymbols are set in italics. All other punctuation characters are literals. Strings are quoted with double quotes; this includes all names. The double quotes protect names from interpretation by the shell, they should be entered as shown here.

mental ray is started as

ray [options] [scenefile]

If no scene file is given, the scene is read from standard input. Scene file names should end in .mi; if the extension is missing mental ray will read the name as specified, and if this fails, retry with .mi added.

Options can be abbreviated as long as the given substring is unambiguous. mental ray checks for ambiguities and prints an error message listing the choices. For example, -resolution can be abbreviated as -res. For frequently-used options such as -verbose and -filename, short forms are available. The available options are:

-acceleration bsp

Selects the binary space partitioning (BSP) rendering algorithm. This algorithm is often, but not always, the fastest. It is controlled by the -bsp_size and -bsp_depth options.

-acceleration grid

Selects the grid rendering algorithm. It provides faster proprocessing especially on multiprocessor systems. Memory usage is more conservative than with the BSP algorithm. Speed is comparable to BSP but more scene-dependent. It is controlled by the -grid option.

-acceleration raycl

Selects the ray classification rendering algorithm. This algorithm is recommended for very large scenes. It operates with a constant acceleration memory size, controlled by the -subdivision_memory and -subdivision options.

-aperture aperture

The aperture is the width of the viewing plane. The height of the viewing plane is aperture divided by aspect. Together with the focal and aspect viewdefs, aperture defines the lens of the camera.

-aspect aspect

This is the aspect ratio of the camera. The default is 1.33. In camera space, aperture is the width of the viewing plane and aperture divided by aspect is the height. The viewing plane is divided into pixels as specified by the resolution viewdef, so the aspect will result in nonsquare pixels if it is not equal to the X resolution divided by the Y resolution. For example, to render a PAL image at a resolution of 720 *576 pixels (equivalent to CCIR 601, also called D1), at an image ratio of 3:4 as defined by the PAL standard, pixels are slightly wider than tall, by a factor of 576 /720 *4 /3 = 1.0667. If this number is specified as aspect, objects will appear undistorted on a PAL video display (but not on a computer display with square pixels). The NTSC standard has 486 instead of 576 lines.

-bsp_depth depth_int

The maximum number of levels in the BSP tree. This option is used only if binary space partitioning is enabled. Larger tree depths reduce rendering time but increase memory consumption, and also slightly increase preprocessing time. The default is 40.

-bsp_memory memory_int

The maximum memory in megabytes used in the BSP preprocessing. A value of zero indicates that there is no limit on the memory consumption, this is the default. This flag is useful only on multiprocessor machines since the memory consumption increases with the number of rendering threads. When the specified amount of allocated memory is reached, mental ray will prevent threads from being scheduled for preprocessing, thus reducing the memory requirements.

-bsp_size size_int

The maximum number of primitives in a leaf of the BSP tree. This option is used only if binary space partitioning is enabled, it has no effect on the ray classification algorithm. Larger leaf sizes reduce memory consumption but increase rendering time. The default is 10.

-caustic on|off

Enable or disable the generation of caustics defined in the scene. The default is on. To actually create caustics, objects in the scene must be marked as caustics casters and caustics receivers, lights must be given energy and other parameters, etc.

-clip hither yon

The hither (near) and yon (far) planes are planes parallel to the viewing plane that delimit the rendered scene. Points outside the space between the hither and yon planes will not be rendered (this does not apply to the infinite-radius environment maps because they are not geometric objects). The clip statement specifies the distance of the hither and yon planes from the camera.

-code "filename" ... --

The named filename is interpreted as a C source file, ending with the extension ``.c'', is compiled and linked into mental ray. The shaders it defines are available in mental ray as shading functions. Multiple file names can be given. The list must be terminated with a double minus sign.

-contrast r g b [ a ]

The contrast controls supersampling. If neighboring samples differ by more than the color r, g, b, a, supersampling is done as specified by the sampling options (see above). Default for a is the average of r, g, and b. The recursive supersampling algorithm controlled by -samples modifies the contrast based on the recursion level: at sample level 0, the contrast is used directly; at sample level 1, the contrast is doubled (effectively requiring a higher contrast to force another subdivision), and so on. Negative levels divide the contrast, i.e. use a fraction 1 /2, 1 /4, and so on. In general, the contrast is multiplied by 2^level at the supersampling level level, which is bounded by -samples. See the Scene Description chapter for more information on how to optimize performance and quality with contrast values.

-cut_window num_int [ expand ]

Cut a frame into num*num sub-frames, each of which is rendered individually. When all are finished, they are combined to the final image. This can greatly reduce memory consumption if the scene is built such that each sub-frame is much less complex than the entire frame, but it may take much longer to run all the extra rendering cycles. If the scene contains few polygons and many free-form surfaces and/or displacement maps, memory usage often goes down by factors of five or ten, while rendering time doubles. Mostly polygonal scenes usually do not benefit from cut windows, and in fact can behave worse. Tessellation caching in animations is disabled in cut window mode.

Before deciding whether geometry outside the cut window frustrum Before deciding whether geometry outside the cut window frustrum should be tessellated, the frustrum is enlarged by 10% all around to catch geometry outside the frustrum that is displaced into the frustrum. This value can be changed with the optional expand argument, which is a factor of the cut window size. 0.1 expands the cut window by 10% all around, which increases its area by a factor of 1.44.

This is a temporary feature in version 2.0 and 2.1 of mental This is a temporary feature in version 2.0 and 2.1 of mental ray and not supported in version 2.2 and later.

-c_compiler "filename"

If this option is given, the standard C compiler "cc" is replaced with filename.

-c_flags "options"

The options string replaces the standard options given to the C compiler. The defaults depend on the machine used; for example, the default option string for single-processor SGI IRIX machines is "-O2". The -c option is always inserted, as is -o if the compiler supports it.

-c_linker "filename"

If this option is given, the standard linker "ld" is replaced with filename. See the chapter on Writing Shaders for platform-specific information on compiling and linking.

-desaturate on|off

If a first-generation material shader returns a color whose RGB components are outside the range [0, 1], mental ray will clip the color to a legal range. Negative component values are clipped to 0. If any of R, G, and B exceed 1, they are either set to 1 (if desaturation is turned off), or R, G, and B are faded towards white (if desaturation is turned on). Alpha is always set to 1 if it exceeds 1, or to the maximum of R, G, and B if any of them exceed alpha. Desaturation is turned off by default.

-displace on|off

Ignore all displacement shaders if set to off. The default is on.

-dither on|off

mental ray supports both 8 and 16 bits per color component. In some cases, 8 bits per pixel, as supported by all popular picture file formats, can cause visible banding when the floating-point color values calculated by the material shader are quantized to the 8-bit values used in the picture file. Dithering mitigates the problem by introducing noise into the pixel such that the round-off errors are randomly distributed. Note that this can cause run-length encoded picture files to be larger than without dithering. Dithering is turned off by default.

-echo "filename" [ascii] [source]

[approx] [norendercommand] [textures] -- Echo the current scene to the file filename. The options specify the format of the echoed file. Allowed options are:

ascii uses ascii format for the vectors (default is binary), ascii uses ascii format for the vectors (default is binary),

source prefers source geometry over triangles if available source prefers source geometry over triangles if available (default),

approx prefers triangles over source geometry if available, approx prefers triangles over source geometry if available,

norendercommand disables the echo of the render command, norendercommand disables the echo of the render command,

textures includes texture pixel data verbatim. textures includes texture pixel data verbatim.

Note that triangle echos have displacement mapping already Note that triangle echos have displacement mapping already applied to the triangles, but the displacement shaders are not removed from the materials so the echoed file will get displaced twice when rendered. The echo option must be terminated with a double minus.

-face front|back|both

The front side of a geometric object in the scene is defined to be the side its normal vector points away from. By specifying that only front-facing triangles are to be rendered, speed can be improved because fewer triangles need to be tested for a ray. This works well unless there are objects whose back side is seen by refracted or reflected rays -- with face front, the back side would not be visible. The default is face both.

-field even|odd|off

Field rendering is a technique that allows smooth animations on interlaced video displays. To reduce flickering, video displays first display only every other scanline of the picture, and then the remaining scanlines in a second sweep. Each sweep is called a field. Two fields are one frame. Since sweeps occur at one half of the frame rate, animated objects may have moved between sweeps. Not taking this into account results in rough animations. By default, mental ray renders full frames, resulting in a non-interlaced output picture. If field rendering is set to even, every consecutive pair of rendered frames is combined such that the first frame contributes the even scanlines (counted from the top), and the second frame contributes the odd scanlines. This is reversed if field rendering is set to odd. The decision of which frame is the first or second is based on the frame number; the first field has an odd frame number (usually 1). If field rendering is enabled, there must be an even number of frames in the input file. Default is field off.

-file_name "filename"

Overrides the file name given by the first file output statement in the camera in the scene file. The full file or path name must be given, including extension if desired.

-file_type "format"

Overrides the file format given by the first file output statement in the camera in the scene file. File formats include "pic" for SOFTIMAGE image files, "rla" for Wavefront RLA files, "ps" for PostScript files if contour mode is enabled. For a complete list, see the Output Shaders subsection in the Functionality chapter.

-filter box|triangle|gauss width [height]

The -filter option specifies how multiple samples in recursive sampling mode are to be combined. The filter defaults to a box filter of width and height 1. The box filter can be replaced with a triangle filter or a gaussian filter centered on the pixel. The filter size in pixel units can also be specified; if no height is given the width is used. Larger filter sizes result in softer images. Typical values are 1.0 for box filters, 2.0 for triangle filters, and 3.0 for gaussian filters. For details on filtering, see the description of the filter statement in the Scene Description chapter.

-focal distance | infinity

The focal distance is set to distance. The focal distance is the distance from the camera to the viewing plane. The viewing plane is the plane in front of the camera that the rendered scene is projected onto; its edges correspond to the edges of the rendered image. However, objects between the camera and the viewing plane will still be rendered; a common approach is to place the viewing plane in the middle of the interesting objects in the scene and then set the aperture such that it is a bit larger than the horizontal extent of the objects in camera space. If infinity is used in place of the distance, an orthographic view is rendered. An orthographic view turns off perspective, all camera rays are parallel. View-dependent surface tessellation is not possible in orthogonal mode.

-gamma gamma_factor

Gamma correction can be applied to rendered color pixels to compensate for output devices with a nonlinear color response. All R, G, B, and alpha component values are raised to gamma_factor. The default gamma factor is 1.0, which turns gamma correction off.

-geometry on|off

Ignore all geometry shaders if set to off. The default is on.

-grid_size factor

Adjust the scene-dependent default grid voxel size. The default is 1.0. Larger values increase the number of voxels and shrink each voxel accordingly.

-help

Print a summary of all options with their allowed parameters, and terminate.

-hosts "hostname[:portnumber] [

remote parameters]" ... -- The host list overrides the host list taken from the .rayhosts file, if present. One slave is started on each host specified. Host names must be given as expected by the local name resolving method (such as /etc/hosts) or as a numeric internet address (nnn.nnn.nnn.nnn). Machines used as slaves must be correctly configured; see the installation notes. The host list must be terminated by a double minus.

-I path

Overrides the path used to resolve $include statements in the .mi scene file. The default path is /usr/include. Note that only one -I option can be specified. It may contain a colon-separated (Unix only) or semicolon-separated (Unix and NT) list of directory paths that are tried in sequence if a $include statement using angle brackets is used in the .mi scene file. Paths introduced with an exclamation point are special; they are applied to quoted $include paths too, and substitute the entire directory path. This can be used to force mental ray to use a specified path regardless of the path specified in the $include statement, for example because that path points to an obsolete (1.9) version of a declaration file. For example, -I /a:/b:!/new tries to find a path <x/y/z> first as /a/x/y/z, then /b/x/y/z, then /new/z.

-imgpipe fd_int

Normally mental ray prints connection information into the output image file that let programs like imf_disp connect and display pictures while being rendered. If -imgpipe is used, the relevant information is printed to the given file descriptor fd instead. This is mainly used by SOFTIMAGE 3D, but can be used for command lines such as ``ray -imgpipe 1 scene.mi | imf_disp -''. The imf_disp program is a viewer provided by mental images that supports image piping.

-jitter jitter

The jittering factor introduces systematic variations into sample locations. Without jittering, samples are taken at the corners of pixels or subpixels. Jittering displaces the samples by an amount calculated by lighting analysis, limited to jitter pixels. This is used to reduce artifacts. Jittering is turned off by default, or by specifying a jitter of 0.0. Jittering works best in ray tracing mode.
In Quasi-Monte Carlo mode (the default of the -smethod option) the
jitter value is always set to 1.0 if jittering is turned on.

-ld_libs "libraries"

The libraries string replaces the standard library options given to the linker. The defaults depend on the machine used, typically "-lm -lc". Linker options are highly machine dependent and operating system dependent and cannot be changed.

-ld_path "path1;path2;..."

Supply a list of paths that mental ray searches for dynamic shared objects (DSO) (see DSO (Dynamic Shared Object)) containing shader code. The paths given here precede those that can be given by an environment variable (MI_LIBRARY_PATH) and the built-in search path (/usr/local/mi/lib;.). -ld_path is synonymous with -L.

-lens on|off

Ignore all lens shaders if set to off. The default is on.

-link "filename" ... --

Like the code command, the link command attaches external shaders to mental ray, which can then be used as shading functions. While the code command accepts ``.c'' files as filename, the link command expects either object files ending in ``.o'', or dynamic shared object (DSO) files ending in ``.so''. Object files are linked, while DSOs are just attached without any preprocessing. DSOs are the fastest way of attaching an external shader, and require no compilers or development options, which are sometimes sold separately by system vendors. On Windows NT, .so extensions are automatically converted to .dll for cross-platform compatibility.For system and development software requirements, see the Release and Installation Notes. However, not all systems support DSOs; see ``Dynamic Linking of Shaders''. The file name list must be terminated with a double minus sign.

-merge on|off

Ignore all merge epsilons and all connections in the scene.

-message module class_list ... --

Enable or disable individual message classes, per module. The module names are printed at the beginning of every message printed by mental ray; all can be used to modify the message classes of all modules. The class_list is a comma-separated list of classes to print. Supported message classes are phase, progress, vprogress, time, scene, memory, render, vrender, resources, network, files, and debug. The special words default, all, and none are also supported. A class can be inverted by prepending an exclamation point. For example, to print less verbose RC progress messages and make all modules report every file accessed, specify

-message rc default,!vprogress all default,files -- -message rc default,!vprogress all default,files --

-o "filename"

This is an abbreviation for -file_name.

-output on|off

Ignore all output shaders if set to off. The default is on. File output statements are not affected.

-photon_depth reflect_int [refract_int

[sum_int]] photon_depth is similar to trace_depth except that it applies to photons. (see photon trace depth) (see photon tracing) reflect thus limits the number of recursive reflection photons. If it is set to 0, no photons will be reflected; if it is set to 1, one level is allowed but a photon cannot be reflected again, and so on. Similarly, refract controls the maximum depth of refracted photons. Additionally, it is possible to limit the sum of reflected and refracted photon levels with sum. Note that custom shaders may override these values. The default value is 5 5 5.

-photonmap_file "filename"

Use filename for the photon map, in all frames. If the photon map file does not exist, it is created and saved. If it exists, it is loaded and used. For multiple frames it is only created for the first frame and then loaded for the remaining frames.

-premultiply on|off

Premultiplication means that colors are stored with alpha multiplied to R, G, and B. For example, white at 10% opacity is not stored as (1, 1, 1, 0.1) but as (0.1, 0.1, 0.1, 0.1). This is the standard method in computer graphics to represent colors; mental ray always uses it internally and in all shaders. One implication is that R, G, and B can never exceed alpha, and mental ray enforces this when storing color values into frame buffers by increasing alpha the the maximum of R, G, and B. The premultiply option allows turning this checking off. mental ray still operates with premultiplied colors, but shaders are free to store colors that would normally be considered illegal.

-raycl_memory memory_int

This option sets the amount of memory to be used by the ray space subdivision algorithm for acceleration data structures to memory megabytes on each CPU. It has no effect if the BSP algorithm is used. mental ray allows presetting the amount of rendering acceleration memory independently of scene complexity without sacrificing speed. The default is set to 6 megabytes, which is sufficient for most scenes. Even for extremely large scenes, little can be gained from memory sizes greater than 12 megabytes. Note that this option does not affect the amount of memory used for the scene description, which depends on the complexity of the geometry in the current frame.

-raycl_subdivision subdiv_int subdiv_2d_int

mental ray uses a ray tracing algorithm that subdivides the space of all rays. The optimal subdivision is determined automatically by a built-in scene analysis. The -subdivision option can be used to modify the result of this analysis; arguments of 0 leave the calculated subdivision unchanged, positive numbers increase and negative numbers reduce the subdivision. subdiv controls general subdivision; subdiv_2d controls primary (eye) and shadow rays. This option has no effect if the BSP algorithm is used.

-resolution x_int y_int

Specifies the width and height of the output image in pixels.

-samples min_int max_int

This This option determines the minimum and maximum sample rate. Each pixel is sampled at least 2^{2 *min} times in each direction. If min is 0, each pixel is sampled at least once. Positive values increase the minimum sample rate; negative numbers reduce the sample rate to less than one initial sample per pixel (infrasampling). min must be at least -2, which means that at least one sample per 4 *4 pixels is taken. -2 is the default. If min is chosen too small, small features may be lost if all samples happen to miss it (if it is found just once in any pixel of a task, mental ray will analyze the feature and render it correctly). If a filter camera statement is used to set a filter other than box 1 1, min must be set to -1 or greater. If depth, normal, or label frame buffers are used by an appropriate output statement, the min parameter should be set to 0 or greater to avoid gaps. The corresponding .mi statement is samples.

The max value sets the maximum sample rate. If neighboring samples find a difference in contrast exceeding the contrast limit, the area that contains the contrast is subdivided until the maximum recursion depth specified by max is reached. At most 2^{2 *} max samples per pixel are taken. If a filter camera statement or option is used to set a filter other than box 1 1, max must be set to 1 or greater.

-scanline on|off

This statement allows turning off the scanline algorithm to force mental ray to rely exclusively on ray tracing. This will slow down rendering in most cases. By default, scanline is turned on.

-shadow off

All shadowing is disabled.

-shadow on

(see shadow sorting) This flag enables simple shadowing. Shadow shaders determine how much light from a light source passes through a shadow-casting object between the light source and an illuminated point on some other object. In shadow on mode (the default), shadows are computed. Shadow shaders are called in random order.

-shadow sort

(see shadow sorting) This flag also turns on shadowing, but alters the way shadow shaders are called. The shadow-casting objects are sorted such that the shadow shader of the object closest to the illuminated point is called first and the one closest to the light is called last (unless the sequence terminates early because light is completely blocked).

-shadow segments

Like with shadow sort, the shadow shaders are called in a sorted fashion. Shadows are computed by tracing the segments between the illumination point, the occluding objects and the light source and applying volume shaders to these segments (shadow segments). This slows down rendering, but is required if volume effects should cast shadows (as for certain complex shaders such as fur shaders).

-shadowmap [on] [off]

[only] [rebuild] [reuse] [motion] [nomotion] -- This option can be used to control shadow maps: The allowed options are:

on activates use of shadow maps. on activates use of shadow maps.

off disables use of shadow maps. This is the default. off disables use of shadow maps. This is the default.

only causes only shadow maps to be rendered, without rendering only causes only shadow maps to be rendered, without rendering a color image. By default the color image is rendered also.

rebuild causes all shadow maps to be recomputed, even if they rebuild causes all shadow maps to be recomputed, even if they are found on disk. By default shadowmaps are computed only if they are not found on disk.

reuse causes no shadow map to be recomputed. They must already reuse causes no shadow map to be recomputed. They must already exist on disk. By default shadowmaps are computed if they are not found on disk.

motion activates motion blurred shadow maps. This is the default. motion activates motion blurred shadow maps. This is the default.

nomotion disables motion blurred shadow maps. This improves nomotion disables motion blurred shadow maps. This improves rendering speed.

-shutter shutter

This option specifies the shutter open time. A shutter value of 0.0 turns motion blurring off, values greater than 0.0 turn motion blurring on. The shutter value scales the motion vectors attached to object vertices; if shutter is 1.0, each vertex moves the distance given by its motion vector, and is blurred in the image over this distance. Values less than 1.0 reduce this path.

-smethod mc|qmc

Use Monte Carlo method or Quasi-Monte Carlo method for jittering, sampling of area light sources, motion blur, and depth of field as implemented by the lens_depth_of_field shader. For details on the mc and qmc variants, see the Sampling Algorithms section in the Functionality chapter. The default sampling method is -smethod qmc.

-task_size task_size_int

This option specifies the size of the image tasks during rendering. Smaller task sizes are convenient for previewing, but also increase the overall rendering time. This option can also be used in order to optimize load balancing for parallel rendering. If the task_size is not specified, an appropriate default value is used.

-threads nthreads_int

Normally, mental ray starts one thread for each CPU in the system. In a single-processor host, the default is always 1. This option changes the number of threads. There is normally no advantage in increasing the number of threads, but it may be lowered to reserve CPUs for other users, to avoid monopolizing a multi-processor machine. Note that Convex machines do not make the number of CPUs in the system available to user programs, so -threads should always be used.

-time_contrast r g b [ a ]

The time contrast controls temporal supersampling for motion blurred scenes. It works similar to the spatial contrast parameter explained above: If neighboring samples in time differ by more than the color r, g, b, a, supersampling is done. Default for a is the average of r, g, and b; the default for r, g, and b is 0.2. Using values for -time_contrast that are higher than -contrast can speed up motion blur rendering at the price of more grainy images without degrading the quality of spatial antialiasing.

-trace on|off

Normally, mental ray will use a combination of a scanline algorithm and ray tracing to calculate samples of the scene. If -trace off is specified, ray tracing is disabled, and mental ray will rely exclusively on the scanline algorithm. Without ray tracing, reflection rays cannot be cast and refraction rays are computed like transparent rays, which do not allow control over the ray direction based on the index of refraction of the material. Lens shaders cannot alter ray origin and direction. However, environment maps will work when ray tracing is turned off. Ray tracing is turned on by default.

-trace_depth reflect_int [refract_int

[sum_int]] reflect limits the number of recursive reflection rays. If it is set to 0, no reflection rays will be cast; if it is set to 1, one level is allowed but a reflection ray can not be reflected again, and so on. Similarly, refract controls the maximum depth of refraction and transparency rays (which implement transparency with and without index of refraction). Additionally, it is possible to limit the sum of reflection and refraction rays with sum. For example, if 3 3 4 is given, an eye ray may be reflected 3 times, or refracted 3 times, or reflected twice and then refracted twice, or any other combination that sums up to at most 4. Shaders may override this setting. The default is 1 1 1.

-v on|off|level_int

An abbreviation for -verbose.

-verbose on|off|level_int

This command controls verbose messages. There are seven levels: fatal errors (0), errors (1), warnings (2), progress reports (3), informational messages (4), debugging messages (5), and verbose debugging messages (6). All message categories numerically less than level are printed. Verbose off is equivalent to level 2 (fatal errors and errors); verbose on is equivalent to level 5 (everything except debugging messages).

-volume on|off

Ignore all volume shaders if set to off. The default is on.

-window x_low_int y_low_int

x_high_int y_high_int Only the sub-rectangle of the image specified by the four bounds will be rendered. All pixels that fall outside the rectangle will be left black.

-xcolor ["control"]

Print colored messages. Error messages, for example, are printed in red, which makes them stand out much better in verbose reports. The control string allows customization; it consists of seven characters describing the severity level (fatal, error, warning, info, progress, debug, and vdebug). Each character is one of k (black), r (red), g (green), y (yellow), b (blue), m (magenta), c (cyan), w (white), or a dot (no color).

Startup File

When mental ray starts up, it automatically checks the following list of startup files:

    Unix: 
            .rayrc 
            $HOME/.rayrc 
            $MI_ROOT/rayrc 
            /usr/local/mi/rayrc 
 
    Windows NT: 
            rayrc 
            %MI_ROOT%\rayrc 
            %SystemDrive%\rayrc 
            %SystemDrive%\Program Files\mental images\rayrc 
 

If the startup file is found, it is read and parsed like a regular .mi scene file. After one such file was read, the search is terminated without searching in the remaining locations. HOME, MI_ROOT, and SystemDrive are environment variables.

The purpose of the startup file is portable initialization. For example, it may contain link statements that load commonly used shader libraries, or $include statement to load shader declarations (after the corresponding link statement). One important point is that different systems with different directory structures can be handled with different local startup files, such that paths built into scene files that could cause incompatibilities are no longer necessary. On Windows NT systems, for example, paths and library names are generally different than on Unix systems, and startup files can be used to hide the differences.

Remote rendering servers on other hosts also read the startup file, but they ignore all link and code statements. (It is not a good idea to put code statements into a startup file because running the compiler can make mental ray startup time unacceptable.) This is done to make sure that the shader library list on the server is consistent with the shader library list on the client.

Although startup files support the full .mi language, they should only be used for initialization and not to preload gemoetry or other scene database elements because this could cause conflicts with scenes that are loaded later. In particular, render statements may not be used in a startup file; mental ray will abort parsing the startup file at a render statement.

Stack Size

On highly parallel Unix machines, it is recommended to set the stack size with the following shell command before starting 32-bit versions of mental ray:

     limit  stacksize  8192

The default may be 64 MB or higher, which means that the virtual memory limit is reached with 8 or 16 CPUs (depending on the machine type) because the 32-bit address space is shared by all CPUs. If virtual memory runs out, the kernel may be forced to kill mental ray threads, which may freeze execution. A stack size of 8192 (KB) is generous, 4096 is usually sufficient also. Every thread needs one stack. For systems with a large number of processors, such as 64 or 128, the virtual memory limit can be avoided altogether by using the 64-bit version of mental ray.

When a 32-bit Unix version of mental ray sees a stack size greater than 16 MB, it limits the stack size to 16 MB for all threads except the first one (which is already running), and prints a warning.

The problem does not arise on Windows NT because PCs only have small numbers of processors. mental ray always chooses a stack size of 4 MB on NT because there is no way to set it from a shell. Windows NT is not a 64-bit operating system.

Note that one should not plan on using more than a quarter of available virtual memory on stacks because the executable, heap storage, and normal and memory-mapped textures must also fit into virtual memory.