Next: 5.2 Startup File
Up: 5. Usage and Command
Previous: 5. Usage and Command
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
preprocessing 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 x 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
.
= 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 depthint
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 memoryint
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 sizeint
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 off. To actually create caustics,
lights must have an energy, and materials must have photon
shaders.
- -caustic_accuracy nphotonsint [radius]
Controls how caustics are estimated from the photon map during
rendering. nphotons is the maximum number of photons to
examine and radius the maximum radius to search. if
nphotons = 0, all photons are examined up to the radius limit. radius = 0.0 means that a scene-size dependent radius
will be used. The defaults are 100 and 0.0.
- -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.
- -colorclip rgb|alpha|raw2.1
This option controls how colors are clipped into a valid range
[0, 1] before being written to a non-floating point frame
buffer or file. The rgb mode is the default. In this
mode, RGB is first clipped to [0, 1] and alpha subsequently to
[max(R, G, B), 1]. In alpha mode,
alpha is first clipped to [0, 1] and RGB subsequently to
[0, A]. In raw mode, RGB and A are both clipped
to [0, 1] independently of each other. In all modes, the RGB
components are clipped as specified by the desaturate
option. The rgb and alpha modes ensure that the
resulting color is a valid premultiplied color. rgb
should be used if the alpha channel is considered less
important than preserving the RGB color and intensity. alpha mode is intended for alpha compositing, where the alpha
channel is more important than the absolute color value to
preserve correct transparencies. raw mode should only be
used if no layering based on alpha is going to take place.
This mode also forces the premultiply mode to on.
It should be used with care because shaders might receive
``illegal'' colors (colors that cannot be composited in
standard ways).
- -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 2level 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 numint [ expand ]
Cut a frame into num x 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 frustum
should be tessellated, the frustum is enlarged by 10% all
around to catch geometry outside the frustum that is displaced
into the frustum. 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
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 color is output to a frame buffer that does not have
32-bit (floating-point) precision, and its RGB components are
outside the range [0, max], mental ray will clip the color to
this legal range. If desaturation is
turned off, the individual components are simply clipped into
range. Otherwise, tries to maintain the brightness of
the color by moving it towards the grayscale axis of the color
cube, until the RGB components are in the legal range. max is determined by the colorclip2.1mode. Desaturation
is turned off by default.
- -diagnostic grid off|object|world|camera size2.1
This diagnostic mode is intended for scene debugging.
Unless set to off, it draws a colored grid on all objects
in the scene that indicate object,
world, or camera space coordinates. Steps
on the X, Y, and Z axes are shown with red, green, and blue
grid lines, respectively. The distance between grid lines is
size units. This is useful to estimate the size and
distances between objects in mental ray, or to visualize object
space coordinates. The off argument disables the grid.
The default is off.
- -diagnostic photon off|density|irradiance max2.1
When rendering caustics or global illumination, this
option disables all material shaders in the scene and produces
a false-color rendering of photon density, or the average of
the red, green, and blue irradiance components. Photon density
is the number of photons per unit surface area. max is the
density (or irradiance) that is assigned to 100%, or red. The
colors are, from 0% to 100%: Blue, cyan, green, yellow, and
red. Higher values fade to white. max can be given as zero
in which case the appropriate maximum is automatically found.
This is done after the whole image has been rendered. This
mode is useful when tuning the number of photons in a photonmap
and setting the various _accuracy options, since the
density (or irradiance) is estimated using those settings. The
default is off.
- -diagnostic samples on|off2.1 (p.
)
If set to on, switch to sampling visualization mode
and create grayscale images representing sampling densities
instead of color images. A black pixel has had no samples,
whereas a white pixel has had the maximum amount as specified
by the -samples option. In addition, a red grid is drawn
indicating task boundaries. The default is off.
- -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),
- source prefers source geometry over triangles if available
(default),
- approx prefers triangles over source geometry if available,
- norendercommand disables the echo of the render command,
- textures includes texture pixel data verbatim.
- 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.
- -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
rgb for SGI RGBA files, jpg for JPEG files, "pic" for SOFTIMAGE image files, "rla" for Wavefront RLA
files, and "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|mitchell|lanczos [width [height]]
The - filter option specifies how multiple samples are to
be combined into a single pixel value. The filter defaults to
a box filter of width and height 1.0, optimized for speed.
This option allows replacing the box filter, or its size (in
pixels). If the size of the filter is not specified, default
values are used. These are 1.0 for box, 2.0 for
triangle, 3.0 for Gauss and 4.0 for Mitchell2.1and
Lanczos2.1. If the height is omitted, it defaults to the
width. Other values can be specified: larger filter sizes
result in softer images. If the size is too small, artifacts
may appear. Filters must be larger than 0.0 but sizes
smaller than 1.0 are generally wasteful since they will
discard some samples. Filters larger than 1.0 can reduce
rendering speed. For further details on filtering, see the
description of the filter statement in the Scene
Description chapter.
- -finalgather on|off2.1
Enables or disables final gathering. It is
disabled by default. Final gathering is a rendering technique
used for computing indirect illumination with a
one-generation raytracing step.
- -finalgather_accuracy nraysint [maxdist [mindist]]2.1
nrays is the number of rays cast in a final gathering step
during rendering. The default is 1000. maxdist is the
maximum distance within which a final gather result can be
reused. The default is scene dependent. mindist is the
minimum distance within which final gather results must be
reused. The default is scene dependent.
- -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.
- -globillum on|off2.1
Enable or disable the computation of global illumination.
The default is off. To actually compute global
illumination, lights must have an energy, and materials must
have photon shaders.
- -globillum_accuracy nphotonsint [radius]2.1
Controls how global illumination is estimated from
the photon map during rendering. nphotons is the maximum
number of photons to examine and radius the maximum radius
to search. if nphotons = 0, all photons are examined up to the
radius limit. radius = 0.0 means that a scene-size dependent
radius will be used. The defaults are 500 and 0.0.
- -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 server 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 servers 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 fdint
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 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. 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) 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.5.1 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 moduleclass_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 -
- -o "filename"
This is an abbreviation for -file_name.
- -offset x y2.1
Specifies an offset for the rendered image. The
default is 0.0 for both values, which means that the image
will be centered on the camera's Z axis. Positive values
translate the image up and to the right. The offset is
measured in pixel units.
- -output on|off
Ignore all output shaders if set to off. The default
is on. File output statements are not affected.
- -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.
- -photonvol_accuracy nphotonsint [radius]
Controls how global illumination2.1or caustics in
participating media are estimated from the photon map during
rendering. nphotons is the maximum number of photons to
examine and radius the maximum radius to search. if
nphotons = 0, all photons are examined up to the radius limit. radius = 0.0 means that a scene-size dependent radius
will be used. The defaults are 30 and 0.0.
- -photon_depth reflectint [refractint [sumint]]
photon_depth is similar to trace_depth except that it applies to photons. 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.
- -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
A. mental ray normally enforces this when storing color values
into frame buffers. The -premultiply off option
instructs mental ray to always store colors unpremultiplied into frame buffers and files. It does this by
undoing the internally applied premultiplication. (mental ray
internally always works with premultiplied colors to present a
uniform interface to shaders; since this is done with
floating-point values there is no precision penalty.) This
option is ignored if the -colorclip raw2.1mode is in
effect.
- -raycl_memory memoryint
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 subdivint subdiv_2dint
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.
- -render beginint [endint [incint]]
Render only frames begin through end5.2. If end is
omitted, begin and all following frames are rendered. If
inc is given, only every inc-th frame is rendered. Frame 1
is considered the first render statement in the scene
file; camera frame specifiers are not considered. For example,
4 8 2 will skip the first three frames, then render frame
4, 6, and 8, and omit the rest. It is not an error if the scene
file has fewer frames than requested.
- -resolution xint yint
Specifies the width and height of the output
image in pixels.
- -samplelock on|off
Whether to let the sampling of area light sources, motion blur,
and depht-of-field be static or depend on the frame number.
The default is on, meaning static sampling.
- -samples minint maxint
This option determines the minimum and maximum sample rate.
Each pixel is sampled at least 22 . 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 has
default -2, which means that at least one sample per 4 x 4 pixels is taken. 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 (mental ray 2.1) or 1 or greater (mental ray 2.0).
- 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 22 . 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
0 or greater (mental ray 2.1) or 1 or greater (mental ray
2.0).
- -scanline on|off|opengl
This statement controls the scanline rendering algorithm.
By default, mental ray uses the scanline algorithm to compute
rays traveling in a straight line from the camera, such as
primary rays. In most cases this gives better performance than
pure ray tracing. Turning scanline off forces mental ray
to rely entirely on ray tracing. This will generally slow down
rendering but in some cases, for example when the task
size is very small, the overhead of initializing
the scanline algorithm may outweigh its benefit and turning it
off can result in a speed improvement.
- -scanline opengl2.1mode will cause mental ray to use
OpenGL hardware if available to further accelerate
rendering. OpenGL is not used to compute actual colors but
only projection and intersection information, so the full
mental ray shader feature set remains available. However,
there may be a precision loss. Since OpenGL rendering is
typically extremely fast compared to network transfer times,
only the client host uses its OpenGL hardware. The results are
broadcast to server hosts if present. Server hosts never use
their OpenGL hardware. Also see -task_size below.
- OpenGL rendering makes certain demands on the OpenGL
hardware present. If a 24 bit frame buffer with a Z buffer is
not present, OpenGL rendering may fail. OpenGL may also fail
or become slow if the image to be rendered is larger than the
workstation display. The max parameter to the -samples option should not be higher than 0, or image
artifacts may appear. During rendering with OpenGL, a window
may briefly appear containing seemingly random colors. On Unix
workstations, mental ray will need access to the X server
and OpenGL hardware for OpenGL rendering to work. This is
usually achieved through the use of the DISPLAY
environment variable. See your workstation manuals for
details. Finally, OpenGL rendering does not work with
motion blurring. If, for any reason, OpenGL rendering is
not possible on the client host, mental ray falls back on
regular scanline rendering.
- -shadow off
All shadowing is disabled.
- -shadow on
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
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] [opengl]
[only] [rebuild]
[reuse] [motion] [nomotion]
-
This option can be used to control shadow maps: The allowed
options are:
- on activates use of shadow maps.
- off disables use of shadow maps. This is the default.
- 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 are found in memory or on disk. By default reuse is
in effect, meaning that shadowmaps are computed only if they
are not found in memory or on disk.
- reuse causes shadowmaps to be reused. First, internal
memory is searched for shadowmaps from a previous frame. If
they are not found, a search is made on disk in the current
directory, according to the filenames specified in the .mi file
if given. If neither is found, the shadowmaps are recomputed.
- motion activates motion blurred shadow maps. This is the default.
- nomotion disables motion blurred shadow maps. This improves
rendering speed.
- opengl2.1causes mental ray to try to use OpenGL
acceleration when rendering shadow maps. The same
limitations apply as mentioned with the -scanline opengl
option. Additionally, because of the difference of the
rendering algorithm, shadow maps rendered with this option
contain slightly different information from those generated
with the regular algorithm, and the resulting shadows may look
different. In particular, soft areas of shadows tend to be
smaller and some areas may incorrectly be determined to be not
in shadow due to the lower precision of OpenGL
acceleration. When OpenGL rendering of shadow maps is enabled,
only the client host will participate, since the computation
cost of the map is so small that the network transfer time
would be prohibitive.
- -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.
- -task_size task_sizeint
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. Note that very small task sizes can cause the
scanline algorithm to perform poorly and in such cases it
may be desirable to turn it off. See -scanline above. If
the task_size is not specified, an appropriate default
value is used.
- -threads nthreadsint
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. Since the scanline algorithm can only compute
straight rays from the pinhole camera, 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, reflections onto environment
maps do work. Motion blurring and shadows are also affected if
ray tracing is turned off. Ray tracing is turned on by
default.
- -trace_depth reflectint [refractint [sumint]]
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|levelint
An abbreviation for -verbose.
- -verbose on|off|levelint
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).
- -view_samples on|off2.1
Toggles the sample view mode. When on, the rgb image
will be replaced with an image that shows where samples
were collected during rendering. This is useful for tuning the
-samples and -contrast parameters and identifying
troublesome areas in the image. A pixel's intensity reflects
the number of samples collected within the pixel and on its
lower and left edges. It is normalized to the maximum number
of samples per pixel. In addition, task boundaries are shown
as red in the image.
- -volume on|off
Ignore all volume shaders if set to off. The default
is on.
- -window x_lowint y_lowint x_highint y_highint
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).
Footnotes
- ... compatibility.5.1
- For system and
development software requirements, see the Release and
Installation Notes.
- ...end5.2
- The -render
option was introduced in mental ray 2.1.36.
Next: 5.2 Startup File
Up: 5. Usage and Command
Previous: 5. Usage and Command
Copyright 2000 by mental images