Keywords: main

Next: 5.3 Upgrading from mental Up: 5. Upgrading Previous: 5.1 Upgrading from mental
Subsections

- 5.2.1 Scene Description Language
- 5.2.2 Shader Writing

# 5.2 Upgrading from mental ray 2.1 to 3.0

mental ray 3.0 is a new generation of mental ray, but the interface is very close to mental ray 2.1. It was designed to minimize porting requirements.

## 5.2.1 Scene Description Language

The scene description languages of mental ray 2.1 and 3.0 are the same, but a number of new features have become available. The changes were more evolutionary than revolutionary.

- Placeholder objects, where the object statement refers to a file or callback, allow demand-loading objects. This avoids the sequential scene loading bottleneck at the beginning of rendering because many threads can later load objects (which form the bulk of most scene files) simultaneously at different times during rendering. This is especially useful for objects that are hidden and may not be needed at all. If mental ray is used as part of a pipeline that supports ``pull mode'', where mental ray's object callback can start the operations that create the object, this is especially valuable because creating an object can be very expensive if complex particle animations, cloth simulations, or similar are involved. Loading objects on demand from files is less valuable because the file must have been written to disk before mental ray was started, but breaking up huge files into smaller portions can avoid long startup delays too.

- If placeholder objects are used with caustics or global illumination, make sure to use statements like `caustic off` or `globillum off` for objects that do not participate in caustics or global illumination, respectively. Since these algorithms are global in nature and tend to touch most geometry, excluding geometry from loading and tessellation at a very early point in time avoids a bottleneck very early during rendering.

- Make sure to use correct bounding box, motion bounding box, and maxdisplace statements in placeholder object definitions. Bounding boxes need not be supplied for non-placeholder objects, but if they are specified anyway, make sure they are correct. Incorrect values can cause truncated geometry.

- Cut windows are no longer supported.

## 5.2.2 Shader Writing

- mental ray 2.1 had a fixed set of threads that were active at all times. mental ray 3.0 starts and stops threads all the time, and even allows changing the number of render threads in the middle of rendering to adjust system load. This means that shaders can no longer use mi_par_nthreads2.1 to determine the required size of an array that is later indexed with state - > thread. A dummy version of mi_par_nthreads2.1 is still available, but it always returns 65, which is large enough to work on most systems. It is important to remove calls to this function!

- For the same reason, the following shader interface functions are no longer available:
  mi_par_localvpu2.1
  mi_par_nthreads2.1
  mi_msg_no_of_threads2.1
  mi_msg_no_of_hosts2.1

- The shader user pointer is no longer accessible through state - > shader - > user.p2.1. Instead, the user pointer must be obtained with mi_query:
  `struct mystruct **u;`
  `mi_query(miQ_FUNC_USERPTR, state, 0, &u);`

- Shader init functions are called when the shader is first called in a frame, and cause a call to the exit shader when the frame ends (assuming both exist). In certain configurations, mental ray may render multiple frames simultaneously, which could cause init(1) - init(2) - exit(1) - exit(2) sequences (with the frame number in parentheses). In this case the init and exit functions are merged such that redundant inits and exits are suppressed. In the example above init(2) and exit(1) would not be omitted. Shader instance init and exit calls are not affected.

- Contour store shaders collect information during rendering. This information must now be declared as the shader's return parameters. The size is no longer returned via its second argument. Since the return type declaration is usually missing in mental ray 2.1 contour store shaders, mental ray will print a warning ``contour store shader X may be declared incorrectly, claims to return a color only - shader may crash!

- Geometry shaders written for mental ray 2.1 will often not work with mental ray 3.0 because the `miBox` data structure was changed. It is now called `miGeoBox` and is no longer limited to 65536 vectors, vertices, and triangles. All short indices were replaced with int indices. It is usually sufficient to change index types in the shader to int, and recompile the shader without further changes. On the other hand, it may often be a good idea to let a geometry shader create placeholder objects (see above) to avoid creating large amounts of data very early during rendering.

Next: 5.3 Upgrading from mental Up: 5. Upgrading Previous: 5.1 Upgrading from mental