Next: 7. Scene File Grammar
Up: 6. Upgrading from mental
Previous: 6.2 Scene Description Language
-
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
Copyright 2000 by mental images