Upgrading from mental ray 3.3 to 3.4

Upgrading from mental ray 3.3 to 3.4

What's new in Version 3.4
Scene Description Language
Shader Writing and Integration

What's new in Version 3.4

Here is a summary of some of the new features and feature improvements in version 3.4 of mental ray:

Rendering Algorithms

The rapid motion rendering method (also knowns as scanline rapid) has been replaced with a new renderer called rasterizer, which is an alternative to the regular scanline renderer. A key benefit of this algorithm is that it separates shading samples from visibility samples. It can therefore be more efficient for scense which do not requrire ray tracing, with or without motion blur.
For backwards compatibility, the existing controlling options were mostly retained. The rasterizer is enabled with the scanline rapid option. The approximation, and hence the sampling rate and antialiasing of shading, is controlled by the new option shading samples in the .mi syntax. The number of pixel samples is as before controlled by the samples collect option.
Several improvements of the speed and image quality of final gathering have been made. Note that it may be necessary to alter final gathering parameters in order to achive comparable render times (at mostly increased image quality).
In order to be able to render larger amounts of hair without running out of memory, large hair objects are now internally split up into smaller portions when using the rasterizer or when creating shadow maps.
Frame buffers are now stored on disk during rendering in order to be able to use arbitrarily many and arbitrarily large frame buffers. This is implemented using memory mapping. This new feature can be disabled using the option -fb_virtual off.
In the hardware rendering mode, motion blur has been implemented, intended for rough pre-visualization of motion.
When computing light maps in combination with network rendering, light maps are now no longer computed on rendering slave hosts, but only on the master host.
mental ray now support version 1.2.1 of the OpenEXR image file format. Mipmapping, texture tiling, and texture caching are now supported for OpenEXR textures, and multiple image types (i.e. frame buffers) can now be written to a single OpenEXR output image file.

Scene Description Language

The samples collect statement, which sets the number of samples filtered by the rasterizer, now defaults to 4 (16 samples) instead of defaulting to a number derived from the oversampling parameters. The shading samples statement sets the number of shading points per pixel taken by the rasterizer.
The hardware samples statement controls the supersampling and multisampling settings of the hardware renderer.
The finalgather trace depth statement has another parameter to control the diffuse trace depth. The optional parameters are now finalgather depth reflection refraction diffuse sum.
The caustic scale, globillum scale, and finalgather scale statements supply a scaling factor to the brightness of these effects.
The finalgather presample density statement adjusts the number of finalgather points during finalgather preprocessing, as a correction factor.
The colorspace statements, and their references in output and texture statements, control the color space (sRGB, CIE, etc) used for rendering, loading, and saving images.
The compress modifier on output statements selects OpenEXR compression modes none, piz, zip, rle, or pxr24.
The trace flag in instances and objects was replaced with separate reflection, refraction, transparency, and finalgather flags that follow the syntax of globillum. So does the shadow flag.
The shadowmap filter statement in a light definition controls shadowmap filtering.
A new variant of directional light can be specified by supplying both an origin and a direction, but not spread because that would turn the light into a spot light. A directional light with an origin does not illuminate points behind the plane defined by the origin and direction.
The volume group statement in an object ties together all objects with the same object group number such that autovolume mode treats them as belonging to the same object with a single inside volume.
The trilist toplevel element is an alternative to object definitions that allows very efficient definition of geometry consisting entirely of triangles.
The nosmoothing flag in approximations turns off normal interpolation during fine tessellation.
The contour and contour normal approximation modes were removed.
The new command-line option -fb_dir S specifies a directory where mental ray can save frame buffer files while rendering. Frame buffers can be very large, and mental ray 3.4 has no upper limit on the number of frame buffers, so they are no longer permanently stored in memory but can be paged out to disk.
Support for DPI information in IFF, TIFF, and JPG/JFIF image files has been added, by means of a new optional parameter in output statements.
Light maps can now be created in arbitrary image types, using the following .mi syntax extension: writable color texture "texName" "texfile.ext" "type" [ width height ].
Sequences of registry entries with mi statements to include shader declarations are now executed in the correct order.
Color profiles have been introduced.
In conditionals in the .mi input syntax, it is now possible to test whether a variable is defined using the syntax $?variable.
mental ray can now use different final gather maps for each object to optimize the global illumination workflow.
Options lightmap on | off | only and photonmap on | off | only have been added.
The option -texture_continue can now be specified for rendering slaves in network parallel rendering.

Shader Writing and Integration

Since the miOptions data structure, and the methods for accessing frame buffers have changed, all shaders that use the geometry shader interface must at least be recompiled. All output shaders need to be modified and recompiled.

New modes for mi_query were added:
miQ_INST_FINALGATHER
miQ_INST_PLACEHOLDER_ITEM
miQ_OBJ_FINALGATHER
miQ_SCENE_ROOT_GROUP
miQ_TEXTURE_DIM
Here is the preliminary list of new shader and integration interface functions:

mi_api_colorprofile_begin
mi_api_colorprofile_end
mi_api_colorprofile_space
mi_api_colorprofile_white
mi_api_data_callback
mi_api_object_placeholder_callback
mi_api_output_colorprofile
mi_api_primlist_approx
mi_api_primlist_begin
mi_api_primlist_border
mi_api_primlist_dimensions
mi_api_primlist_end
mi_api_primlist_topology
mi_api_texture_callback_def
mi_call_contour_material
mi_colorprofile_ciexyz_id
mi_colorprofile_ciexyz_to_internal
mi_colorprofile_ciexyz_to_render
mi_colorprofile_internal_to_ciexyz
mi_colorprofile_internal_to_render
mi_colorprofile_internalspace_id
mi_colorprofile_render_to_ciexyz
mi_colorprofile_render_to_internal
mi_colorprofile_renderspace_id
mi_continue_shadow_seg
mi_disp_fbmap
mi_disp_fbunmap
mi_mem_set_flush_failure_cb()
mi_msg_pipe_mode_enabled()
mi_output_image_close
mi_output_image_open
mi_reflection_dir_anisglossy_x
mi_reflection_dir_diffuse_x
mi_reflection_dir_glossy_x
mi_texture_interpolate
mi_transmission_dir_anisglossy_x
mi_transmission_dir_diffuse_x
mi_transmission_dir_glossy_x
The image pointer has been removed from the options. Output shaders must call mi_output_image_open and mi_output_image_close for frame buffer access.
The fields image_types, write_image and interp_image have been removed from the options. Frame buffers are now specified in a database array of type miFb_info, which is field images_info in the options.
The callback installed by the mi_disp_stream_cb_begin integration function receives a pointer of type miRc_mapfb instead of a tag array referring to miImg_image elements. A frame buffer can be accessed from the callback by using mi_disp_fbmap and mi_disp_fbunmap.
The mi_query mode miRCQ_IMAGE has been removed. A new mode miRCQ_FB has been introduced that allows access to frame buffers. mi_rc_run_query returns a pointer of type miRc_mapfb for this mode, which can be passed to mi_disp_fbmap and mi_disp_fbunmap for frame buffer access.
Incompatible changes to the miInstance and miObject data structures have been made. The trace field has been removed, reflection, refraction, it transparency and finalgather fields have been added. The shadow field is no longer treated as a boolean, it is interpreted as a bitmap which controls casting and receiving separately.
state->face is initialized with zero instead of using the value defined in the global options, allowing mental ray to distinguish between face flags set in the options, in the object or instance or overridden by the shader.
Some obsolete fields in the miGeoBox data structure have been removed.
For integrators, a new approximation style miAPPROX_STYLE_FINE_CONT_DISP has been added to the integration API. It enables the continuous displacement of unshared vertices for displaced polygons.
The implementation of the mi_noise_... utility functions for shaders has been improved. Note that this change may have a large effect on existing setups using noise.
Integrators must now call mi_api_texture_file_size() with the value miIMG_TYPE_ANY instead of 0 as the fourth argument in order to keep the old behaviour. This change is caused by added controls for light map creation.
The function mi_api_object_placeholder_callback has been added as an alternative to mi_api_object_callback.
For integrators, a macro miBOX_BORDER_MATERIAL() has been added to facilitate access to the materials at borders.
The mi_rc_run_query mode miRCQ_NEEDS_PREPROC has been added.