Next: 5.2 Upgrading from mental
Up: 5. Upgrading
Previous: 5. Upgrading
Subsections
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.
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.
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.
- 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
Copyright 2002 by mental images