Upgrading from mental ray 3.5 to 3.6

Upgrading from mental ray 3.5 to 3.6

What's new in Version 3.6
Scene Description Language
Shader Writing and Integration
Incompatible Changes

What's new in Version 3.6

Here is a summary of some of the new features and feature improvements in version 3.6 of mental ray. Please refer to the release notes for more details and for other changes which are not mentioned here.

Assemblies

An assembly is a subscene attached to a bounding box, which is loaded on demand when the bounding box is hit by a ray, or is contained and not completely occluded in a rendering tile, if the rasterizer is used. In cases of insufficient memory, assemblies are unloaded automatically and reloaded the next time they are required.
An assembly may contain all scene DAG elements, such as objects, instances and groups, as well as textures, materials, shaders, phenomena, lightprofiles and other scene elements. Lights and cameras can be contained in an assembly, but they will be ignored in the rendering process. An assembly can be created procedurally as a result of geometry shadercall, or loaded from a .mi file.

New BSP Acceleration Technique

A new BSP acceleration technique (BSP2) has been developed for efficient rendering of large BSP trees. The new technique does not require manual tuning for BSP traversal performance and memory consumption improvements. The memory requirements are much lower compared to the traditional BSP. Thus, the new BSP2 is recommended for rendering of large scenes, like those which do not fit into the physical memory of a machine, and scenes containing assemblies.

New Subdivision Surface Support

This completely new subdivision surface implementation is based on a mixed triangle-quad subdivision scheme. The new implementation is several times faster than the previous one, at a reduced feature set compared to the full hierarchical subdivision surface support. The new code path is used for triangle-quad ccmesh input objects not containing features listed below:

semi-sharp creases
vertex features
arbitrary polygons (not only triangles and quads) in ccmesh.

For objects containing containing one of the above features or other types of approximations, the mental ray 3.5-based subdivision surface implementation is used.
The following approximation types are supported by the new implementation:

parametric
[fine] [view] length [min max]

Importons

Importons are "particles" similar to photons. However, they are shot from the camera and traverse the scene in the opposite order. Instead of "energy", they hold a quality which is an importance of the contribution to the final image. The information from importons is used by the kernel for distribution of rendering efforts according to the final contribution to the rendered image, i.e. so-called importance-driven sampling. Importons are thus a foundation for new view-dependent indirect illumination techniques. As a first of them, mental ray 3.6 adds an importance-driven photon map described below.

Importance-driven Photon Maps

A new technique based on the importon map described above has been implemented. This technique is superior to the photon merging introduced in mental ray 3.5. If importons are enabled, they are used to control the density of the globillum photon maps and to improve the lookup time.

Native Ambient Occlusion with Caching

A native implementation of ambient occlusion has been added, which can be used by shaders to replace custom probe ray tracing solutions and benefit from advanced features like caching.

MetaSL Support

MetaSL is a powerful shading language targeting current and future shading requirements. mental ray shading functionality has been extended to allow efficient support for the MetaSL shaders. It is possible to use a mixture of native and MetaSL shaders in the same scene. It is also possible to combine "native" software mental ray shaders and MetaSL shaders in a shader tree or in a mental ray Phenomena at rendering time.

Exact Final Gathering

Added new finalgather mode "force", where finalgather map creation and interpolation will be disabled. A set of finalgather ray will be shot each time mi_compute_irradiance or mi_compute_avg_radiance is called. The rendering speed would be much slower than in other finalgather modes, delivering a superior image quality.

Other improvements

Added support for the DDS image file format for single textures and cubemaps. Internally cubemaps are stored as a single texture containing all 6 faces.
For OpenEXR output files, allow to combine arbitrary frame buffers in the single output statement. Added the possibility to write any subset of the first 8 user framebuffers (i.e. "fb0" to "fb7") to such files. If an OpenEXR output file contains a user framebuffer and at least one other buffer, the user framebuffer channels are called "Rn", "Gn", "Bn", "An", where n if the index of the user framebuffer for color type outputs, "Zn" for Z-depth output etc.
For the rasterizer and scanline rendering, significantly improved performance for scenes with displacement, there a very conservative value for the maximal displacement value was given and the displace presample option was not used.
Significantly improved rasterizer performance for high depth complexity scenes (such as scenes with hair) rendered with the new transparency depth limit.
Fixed several issues with view dependent tessellation for orthographic cameras.
For finalgathering, significantly reduced the requirement for continuous memory block size. This may give memory usage benefits on 32-bit machines rendering with large finalgather maps.
For the rasterizer, increased the precision of the inversion of transformation matrices. This reduces the differences between images rendered on different platforms for transformations matrices close to degenerate ones.
For the rasterizer, improved the statistics output.
New standard shader packages are delivered with mental ray: architectural and production. They provide shaders for creation of common materials typically used in architectural and design applications, as well as shaders for typical workflows used in visual effects production.

Scene Description Language

The following changes were made in the .mi scene description syntax:

New interface for named framebuffers. The camera definition in the .mi file the following statement could be added:

    framebuffer "name"
        type string
        filename string
        filetype string
        filtering boolean
        colorprofile string
        compression string
        quality string
        dod boolean
        dpi int

The new syntax replaces file output statements. The old syntax is still supported.

Added binary format for hair objects using the following syntax:

    hair
        ...
        scalar [ <number of scalars> ]
        binary `...<binary block of scalars>...`
        hair   [ <number of offsets> ]
        binary `...<binary block of hair offsets>...`
        ...
    end hair

Adding a file assembly to the main scene uses the following syntax:
```
    assembly "assembly_name"
        box [min_x  min_y  min_z  max_x  max_y  max_z]
        [ motion box [min_x  min_y  min_z  max_x  max_y  max_z] ]
        file "file_name"
    end assembly
```
The individual parameters are:
- The box statement specifies a bounding box for the assembly, in the space of the assembly. It is the union of all bounding boxes of all geometric objects defined in the assembly transformed to the assembly space. The box parameter must always be specified since it is not possible to compute the bounding box without loading the assembly.
- The motion box is similar to the box, but contains the minimum and maximum components of all motion vectors. For assemblies with motion the motion box must be specified. Unlike object motion bounding boxes, the assembly motion bounding box should take into account not only object motion vectors, but also motion transforms inside of the assembly.
- The file statement specifies the name of the file where the subscene is stored. A list of directories for looking up the file can be specified with the -assembly_path path_list command line option, with the {_MI_REG_ASSEMBLY} registry, or with the MI_ASSEMBLY_PATH environment variable.
Assemblies files should contain a root statement at the end:
```
    root "group_name"
```
The group "group_name" would be attached to the main scene of the assembly.
The new BSP2 can be enabled with the "acceleration bsp2" option in the .mi file.
The following string options can be used to specify global defaults for ambient occlusion options:
- "ambient occlusion rays" sets the number of probe rays shot at a shading point. The default value is 256.
The following string options can be used for controlling the ambient occlusion cache:
- "ambient occlusion cache" enables the caching. If set to off, the ambient occlusion passes are skipped and the occlusion value is computed for each mi_ambient_occlusion function call. The default is off.
- "ambient occlusion cache density" specifies the maximal density of ambient occlusion points after all refinement passes, in points per pixel. The default is 1 ambient occlusion point per pixel.
- "ambient occlusion cache points" specifies the number of ambient occlusion points used for interpolation. The default value is 64.
For the rasterizer, added a new string option "rast motion factor", float value. If set, it adjusts the effective shading rate on moving objects. It can be used to improve rendering performance for motion scenes without a visual quality decrease.
For the rasterizer, added a string option "rast transparency depth" and the corresponded -rast_transparency_depth to limit the depth complexity. For high depth scenes this option may be used to significantly improve performance without noticeable changes to the rendered image.
Added new boolean string option "contrast all buffers". If set, the contrast oversampling test is done based on all color buffers, including user framebuffers.

Shader Writing and Integration

The following changes were made in the shader and integration interfaces.

Note: All shaders and integrations should be recompiled for mental ray version 3.6. Common data structures in the shader interface and integration API have been changed, especially with regard to assemblies. Shaders compiled for an earlier version of mental ray may crash without error indication if they access changed data structures in the shader interface.

Added a new mi_query mode miQ_STAGE. Shaders may use the resulting queried value to detect the current rendering stage. The shader.h file lists possible values: normal tile rendering, finalgather precomputing, ambient occlusion cache creation, photon and importon emission and lightmapping.
Added a new function
```
    miBoolean mi_api_framebuffer_add(
        miTag   buffertag,
        char   *datatypes,
        char   *filetype,
        float  *fileparams,
        char   *filename);
```
which should be used for the C-style framebuffer API. The functions mi_api_output_file_parameter and mi_api_output_file_def are deprecated. The parser is changed to use the new function.
For state shader called in miSHADERSTATE_STATE_INIT mode, miState::type is initialized correctly. This may be used by a state shader to detect photon emission, lightmap or output shader stage.
The miState::cache is no longer used for intersection optimization. The member is kept for compatibility reason, but should be considered deprecated. The marker functionality (setting miState::cache to 0 in order to allow certain shader types to call ray-tracing functions as documented in the manual) is still available. This change gives a small performance improvement.
The shader interface is extended with the Framebuffer class. In order to get the framebuffer index used by mi_fb_put and mi_fb_get functions, the Framebuffer::get_index method could be used. Framebuffer class allows accessing and editing of the framebuffer properties. In order to access or edit the framebuffer set, the smart pointers Access_fb and Edit_fb have been added.
A new mi_query mode miQ_FUNC_IS_ROOT is added. The miBoolean argument is set to miTRUE if the shader called called directly by the kernel as a "root" of the shader graph or phenomenon. A shader returning a large structure could use it to prevent a possible crash from attaching it directly to a material or light.

Light lists, when created, may specify the sampling cone by providing an axis of the sampling cone and a cosine of the spread angle, like in the code sample below:

    mi::shader::Interface* iface;
    mi_query(miQ_RAY_INTERFACE, state, 0, (void*)&iface);
    auto_ptr<MI::RAY::LightList> llist(iface->createLightList(
                                          state, state->normal, 0.5));
    for (mi::shader::LightIterator light = llist->begin();
         light != llist->end(); ++light) {
        while (light->sample()) {
            miColor c = light->get_contribution();
            // ...
        }
        if (light->get_number_of_samples()) {
            // ...
        }
    }

This could be used for sampling lights from both sides of the surface without the state->pri=0 trick.

For the rasterizer, added new shading_samples field to miObject and miInstance, which allows overriding the global shading samples specified in the options. The corresponded syntax in .mi file: shading samples float.
Added the new importance field to miState. It is propagated to child rays. For rendering quality/performance improvements, a shader written for scenes using indirect illumination may multiply this field by a certain factor before calling mi_compute_irradiance or mi_trace_... function. The factor may be chosen as an intensity of the color with which the result of the function call would be added to the result of the shader, or, in case of tracing multiple (glossy) rays, as the inverse of the number of rays shot.
Added the new boolean field photons_only to the miLight structure. If set, the illumination from the light is treated as indirect. Light sampling of the light would return black. To compensate, photons emitted from the light would stored on the first bounce in addition to the second and further bounces. For a physically correct scene, the illumination model is thus the same.
This option can be used for significant performance improvement for scenes with a high number of low intensity lights: the length of the light lists, and thus the number of light shader calls and shadow rays is reduced significantly at the price of a larger photon map.

The corresponding .mi syntax in the light section: photons only boolean.
Restored mi_img_type_query function in the shader interface. For a given image type this convenience function returns the number of component, and the number of bits per component. It also fills the optional array of 4 booleans with flags for the components if
For raylib integration: changed mi_disp_fbmap function to return 0 if called with out of range index. In particular this should simplify integration of the display callback in the finalgather precomputing preview mode.

Incompatible Changes

The following changes were made in mental ray 3.6 which are not backwards compatible or which may cause different results than previous versions of mental ray:

The miState->pri_idx, the index of triangle in the sub-object box, is removed. With the changes done for assembly support, the miState->pri completely identifies a primitive in a scene. Lightmap and some contour shaders should use the new miQ_PRI_INDEX query mode to obtain the triangle index. Lightmap shaders should use the new mi_state_set_pri function to set the current triangle index.
Some missing const qualifiers were added to the interface functions. Compiler warnings or errors would indicated unintentional usage and should be taken seriously. There is at least one exception though: If GCC 4 is used, it may print out warning on the mi_tri_vectors, which should be ignored.
The mi::shader:Interface class now has the new version 2. The new class is incompatible with the version 1 used in mental ray 3.5. However, the interface version 1 is still supported and can be obtained with mi_ray_interface_version, so mental ray 3.5 shader will not need a recompilation due to this change.
The camera space (in particular used in the the old .mi1 files) is no longer supported. The geometry will be loaded correctly, but the texture spaces and other coordinate systems may be wrong.
Grid acceleration is no longer supported. The main advantage of grid was the low memory footprint in heavily multiply-instanced scenes. The BSP2 acceleration technique with assemblies is a superior replacement.
In the miOptions, the fields rapid_shading_samples, rapid_collect_rate and rapid_motion_resample are renamed to more intuitive rast_shading_samples, rast_collect_rate and rast_motion_resample respectively.
For the integrators on Windows: setting binary mode on the stdin is no longer applied. If raylib is integrated into a standalone-style product which could be used in the pipe mode, the mode must be set in the integrated code explicitly with the call: _setmode( _fileno(stdin), _O_BINARY).
mental ray 3.6 keeps file outputs and output statements separately. All output image files are written out after all output shaders are applied. Writing out a frame buffer to one file, applying an output shader to that framebuffer and writing the modified buffer to a different file is not possible.