Keywords: main

Next: 7. Scene File Grammar Up: 6. Upgrading from mental Previous: 6.2 Scene Description Language

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

Next: 7. Scene File Grammar Up: 6. Upgrading from mental Previous: 6.2 Scene Description Language