Keywords: main

Next: 5.2 Upgrading from mental Up: 5. Upgrading Previous: 5. Upgrading
Subsections

- 5.1.1 Rendering Algorithms
- 5.1.2 Scene Description Language
- 5.1.3 Shader Writing

# 5.1 Upgrading from mental ray 1.9 to 2.x

With mental ray 2.x 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.x requires some attention. mental ray 2.x 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.x.

mental ray 2.x 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.x.

## 5.1.1 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.x, 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.x 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.

## 5.1.2 Scene Description Language

mental ray 2.x 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`.

## 5.1.3 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.x. It is not possible to use the same shader object or library file for both mental ray 1.9 and 2.x. 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.x 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.x 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.x.

- 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.x 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.x 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.x. 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.x, 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.x. 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.x 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.x. It does not accept a null tag as argument, but mental ray 1.9 does not check this. mental ray 2.x 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.x 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.x 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_nthreads2.1instead. Note that some versions of mental ray 1.9 misspelled this function mi_par_nthread. mental ray 3.x does not support the notion of a fixed number of threads at all.

- 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.x supports a new feature called phenomena that automate the integration and installation of procedural geometry.

Next: 5.2 Upgrading from mental Up: 5. Upgrading Previous: 5. Upgrading