Upgrading from mental ray 1.9 to 2.0

With mental ray 2.0 a new generation of mental ray has become available. Its internal design greatly differs from mental ray 1.9; it incorporates many new features like networking based on a global shared database, incremental changes support, Phenomena, new rendering techniques for caustics and contour rendering, an improved approach to parallelization, and enhanced extensibility. At the same time, obsolete features such as nonrecursive sampling have been removed.

For the mental ray 1.9 user, this means that the transition from mental ray 1.9 to 2.0 requires some attention. mental ray 2.0 has been designed for maximum compatibility with mental ray 1.9, so in general no additional work will be required by the user to render existing scenes that do not use contour rendering or custom shaders. However, the mental ray installation procedure is slightly different, and shader writers need to make adjustments to the shader sources. This chapter summarizes all changes required when switching from version 1.9 to 2.0.

mental ray 2.0 also introduces a number of new features. Some of them improve on 1.9 features and are recommended for future shader designs; these are also listed in this chapter. However, this is not a complete list of improvements in mental ray 2.0.

Installation

The built-in SOFTIMAGE shaders have changed. For this reason, the new softimage.mi shader declaration file must be installed and used. Any attempt to use the old softimage.mi file that works with mental ray 1.9 will cause one of three errors: the resulting image contains only ambient light, rendering aborts with an error message stating that a light instance could not be found, or another fatal error message.

: For this reason, mental ray 2.0 now requires that every included file such as softimage.mi must contain version information, Commands section in the Scene Description chapter). In the softimage.mi case, mental ray will abort if this version information is not present; for all other files a warning is printed.

: To render a scene file that was created for mental ray 1.9 with mental ray 2.0, it is necessary to ensure that the $include statements in the scene file use the correct version of the include files. If the included file name is enclosed in angle brackets, as in $include <softimage.mi>, this can be achieved with the -I command line option. If the include files for mental ray 2.0 are in /usr/include/mi2, for example, -I /usr/include/mi2 will look there first. If the $include statement contains a full path enclosed in double quotes, as is the case in scene files created by the SOFTIMAGE Creative Environment, this will not work. In these cases it is necessary to override the given path instead of locating it. This can also be done with the -I command-line option by introducing the override path with an exclamation point, as in -I !/usr/include/mi2. This will look for include files in the given directory regardless of which path was given in the $include statement. Note that some shells require giving ! as \!. Multiple paths can be specified with -I; they must be separated with colons and are tried in sequence until the file is found. Turn on verbose mode (-v on) to verify that the correct file was included.

: Declaration files other than softimage.mi are generally compatible and need not be replaced, unless their parameter lists were reordered too (see below).

mental ray 2.0 first tries the mi-ray2 IP service, then the mi-ray service to find mental ray servers. The latter is also used by mental ray 1.9. To allow both 1.9 and 2.0 servers to coexist on the network, the mi-ray2 service can be added to the /etc/inetd.conf file instead of modifying the mi-ray service.

If a rendering operation fails due to network or other problems, mental ray 1.9 was unable in some cases to pass error messages from remote server hosts back to the client host, because the client has terminated or the network connection was severed. mental ray 2.0 slaves add important error messages into a local log file, /tmp/raylib.log, if regular message transmission is not possible. The number of messages is small but should be checked periodically to identify problems.

mental ray 2.0 requires a license upgrade.

Rendering Algorithms

If incompatible options are given to mental ray, some of them are overridden to return to a consistent state. In mental ray 1.9.9.20 and higher, including mental ray 2.0, the strategy was changed: instead of re-enabling ray tracing if any other feature such as lenses are used and ray tracing was explicitly turned off, the newer versions do not turn ray tracing back on but change the operation of the feature normally requiring ray tracing. The following features are affected:

If ray tracing is turned off, lens shaders cannot modify the ray origin and direction. Lens shaders are still useful in this mode because they can modify the color returned by the eye ray, or decide to not sample points in certain directions.

A new algorithm was introduced in mental ray 2.0 that supports fast motion blur in scanline mode. Turning ray tracing off no longer disables motion blurring.

Similarly, shadow maps were introduced that support shadows in scanline mode. Only opaque shadows are supported in this mode; transparent and transparency-mapped shadows still require ray tracing. Shadow maps do support motion-blurred shadows.

Scene Description Language

mental ray 2.0 supports a new generation of the mental images scene description language, called .mi2. The language version supported by mental ray 1.9, called .mi1, is still available for backwards compatibility. New translator designs should always use .mi2 because only .mi2 supports instancing, inheritance, incremental changes, and many other features. Here are some rules for using .mi2:

Use object space coordinates instead of camera coordinates.

Use options, cameras, instances and groups instead of frames and views.

Use incremental changes wherever possible.

Do not use the following statements: red, green, blue, white, recursive, adaptive, memory.

Double-quote names to avoid clashes with new keywords.

Contour rendering has been rewritten completely. The new algorithms offer much higher flexibility, programmability, and features such as colored contours, varying line widths and styles, parallelism, and contour generation concurrently with color image generation, and compositing. The contour modes of mental ray 1.9 are no longer supported, any .mi1 scene file containing contour features must be modified.

Use contour contrast, contour store, contour output, and contour shaders.

Do not use: contour line width, contour depth, and paper transform.

Shader Writing

Even if none of the following points apply, shaders must be recompiled with the shader.h file that comes with mental ray 2.0. It is not possible to use the same shader object or library file for both mental ray 1.9 and 2.0. A shader compiled with the wrong shader.h file will not be able to access state variables correctly. shader.h contains #define RAY2 to allow shader sources to make sure that the correct file is included.

The shader.h file that comes with mental ray 2.0 is fully ANSI-compliant. Old-style K&R compilers cannot be used any longer.

Always put min version 2.0 into all shader declaration $include files used by mental ray 2.0 but not by mental ray 1.9. Add max version 1.99 for shader declaration files used by mental ray 1.9 but not 2.0.

If shader declarations rely on structure definitions from mi_softshade.h, these must be adapted to the new version of mi_softshade.h. Such dependencies are not recommended because Softimage shaders change every once in a while, which may require recompilation of shaders using mi_softshade.h.

All shaders that accept arrays as parameters must be modified. mental ray 1.9 required that arrays are given as *array in the parameter struct, with array being the name of the array. This must be changed to array[1] for mental ray 2.0 shaders. The i_array and n_array integers remain unchanged. This change has been announced in the mental ray 1.9 User's Manual, [RAY1 97]; see the discussion there

Shaders using the mi_trace_light function should be rewritten to use mi_sample_light. The new function has been available in mental ray 1.9 for upward compatibility but was functionally identical to mi_trace_light; in mental ray 2.0 it was reimplemented to allow correct behavior in cases where the illuminated surface is close to an area light source. In these cases, only mi_sample_light correctly increases the size of the highlight.

A tag to a light instance is now accessible through state-> light_instance. In 1.9 it was state->instance, but this field is now reserved for other purposes.

The state->contour field is not available in 2.0. If a shader wants to test whether there is contours or not, test if (state-> options->contour_contrast != 0) and (state->options ->contour_store != 0) instead.

Do not use state->shadow_sort. This variable is still available for backwards compatibility reasons, but may be dropped in future versions of mental ray. Instead, check whether the state->shadow variable has the character value 'l' (lower-case L).

Shadow shaders and material shaders used as shadow shaders should be written to support shadow segment mode. If this mode is enabled, state->shadow_sort has the character value 's'.

In both mental ray 1.9 and 2.0, tags are used to identify scene components such as instances and shaders. A tag is an opaque data type that is not normally used directly, but can be converted to a pointer using the mi_db_access function. In mental ray 1.9, the tag value happens to be bit-wise identical to the pointer; this is not the case in mental ray 2.0. Also, mental ray 1.9 does not fail if there is not a mi_db_unpin call for every mi_db_access call; mental ray 2.0 may fail with a pin overflow error. Both of these effects are a problem only for shaders that do not comply with the mental ray shader interface as specified in the 1.9 User's Manual.

The mi_db_access function was a dummy function in mental ray 1.9, but is implemented in mental ray 2.0. It does not accept a null tag as argument, but mental ray 1.9 does not check this. mental ray 2.0 does, and fails with a fatal error in this case.

Shaders that use the (undocumented) transformation fields in the state (state ! ->! world_transform, state !->! inv_world_transform, state ! ->! object_transform and state ! ->! inv_object_transform) have to be rewritten. mental ray version 2.0 provides the mi_query function that can be called with the miQ_TRANS_CAMERA_TO_WORLD, miQ_TRANS_OBJECT_TO_WORLD and similar codes in order to provide the appropriate transformations. Note that mi_query returns a pointer to the matrix, not the matrix itself, to reduce data copying. See the description of the mi_query function.

Shaders that access opaque data structures by ``knowing'' that the n-th integer or pointer in undocumented structures contain a certain value will no longer work. All internal data structures have changed. Features not documented in the User's Manual are not portable. Use mi_query to access internal data.

Many shaders use an init shader to set up private data that is later used during shading. In mental ray 1.9 it was common to declare dummy parameters to have a place to store the pointer to the private data. This was dangerous because of alignment problems on systems with 64-bit pointers and is not recommended. mental ray 2.0 supports a user pointer for storing the private data pointer; it can be obtained with mi_query's miQ_FUNC_USERPTR mode.

Exit shaders now have state as parameter. This was not the case with 1.9 exit shaders. Failing to add this parameter can cause severe problems.

A number of image access functions are renamed for more consistent use of function names. Every call to these functions must be replaced with the renamed functions as they are defined in shader.h. These functions were available but undocumented in mental ray 1.9.

get_no_procs is no longer available. Use mi_par_nthreads instead. Note that some versions of mental ray 1.9 misspelled this function mi_par_nthread.

Some effects require a large number of scene modifications to install various types of shaders, dummy geometry, and rendering options, resulting in lengthy procedures for integrating the effect. mental ray 2.0 supports a new feature called phenomena that automate the integration and installation of procedural geometry.

Table of Contents