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
Known Limitations

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.

Irradiance Particles

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. See also Known Limitations.

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. See also Known Limitations.

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. See also Known Limitations.

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 frame buffer file caching, to store only fragments of frame buffers in disk files on demand. See also Known Limitations.
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 files, any number of buffers can be written to a single file, including an arbitrary number of user buffers. All files with the same output filename will be added to the same EXR file. The primary buffer channels are named "R", "G", "B", and "A", and all other buffers retain their buffer names, and get RGBA or XYZ extensions, as appropriate. For example, a rgba buffer named "diffuse" will have channels named "diffuse.R", "diffuse.G", "diffuse.B" and "diffuse.A". If the camera is defined with output statements instead of the new framebuffer statements, then mental ray will automatically assign names to the channels.
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 frame buffers. The camera definition in the .mi file the following statement could be added:

    framebuffer "name"
        datatype "string"
        filtering boolean
        primary boolean
        user boolean
        filename "string"
        filetype "string"
        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 frame buffers.

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 to support backwards compatible frame buffer interface.

    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. It is not using the new named frame buffers. The functions mi_api_output_file_parameter and mi_api_output_file_def are deprecated. The parser has been changed to use the new function. Here is an example how the new code should look like.

    void camera_set_output(
        miCamera*   camera,
        const char* datatype,   /* like "+rgba" */
        const char* filetype,   /* like "tif"  */
        const char* filename)   /* like "myfile.tif" */
    {
        float file_options[8] = {
                0.0f, // QUALITY [jpg] or COMPRESS [exr]
                0.0f, // EVEN or ODD
                0.0f, // spare
                0.0f, // spare
                0.0f, // DOD
                0.0f, // spare
                75f,  // DPI
                0.0f  // spare
                };

        mi_api_framebuffer_add(
                        camera->buffertag,
                        mi_mem_strdup(datatype),
                        mi_mem_strdup(filetype),
                        file_options,
                        mi_mem_strdup(filename));
    }

The shader/integration interface is extended with the Framebuffer class for the new named frame buffers. The convenient wrapper classes Access_fb and Edit_fb allow easy reading and manipulation of the frame buffers though smart pointers.
For shaders, in order to get the frame buffer index needed for mi_fb_put and mi_fb_get functions, the Framebuffer::get_index method should be used in shaders as follows.

    const char* bufferName = ...;

    if (bufferName) {

        mi::shader::Access_fb fb(state->camera->buffertag);

        size_t bufferIndex(0);

        if (fb->get_index(bufferName, bufferIndex)) {
            miUint index = (miUint) bufferIndex;

            mi_fb_put(state, index, ...);
            ...
            }
        } // invalidates scope of smart pointer

For integrations, here is an example for iterating through frame buffers.

    miCamera* camera = ...;

    if (camera) { // print the filename of all framebuffers

        mi::shader::Access_fb fb(cam->buffertag);

        size_t n_fbs(0);

        fb->get_buffercount(n_fbs);

        for (miUint i=0; i < n_fbs; i++) {
            const char* bname;
            const char* filename;
            fb->get_buffername(i, bname);
            fb->get(bname, "filename", filename);
            mi_info("filename %s", filename);
            }
        } // invalidating the scope of the smart pointer

    if (camera) { // remove all framebuffers, and
                  // create new primary frame buffer with file output

        mi::shader::Edit_fb fb(camera->buffertag);

        fb->reset();    // delete all buffers
        fb->set("first", "datatype", "rgba");
        fb->set("first", "filtering", true);
        fb->set("first", "primary", true);
        fb->set("first", "filetype", "tif");
        fb->set("first", "filename", "/tmp/image.tif");
        ...
        } // invalidating the scope of the smart pointer

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.
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 components, and the number of bits per component. It also sets values in the optional array of 4 booleans with miTRUE or miFALSE if the related component is used or not.
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 functions mi_api_output_file_parameter and mi_api_output_file_def are deprecated, and the new function mi_api_framebuffer_add should be used instead. The original functions are still existing but don't perform any operations.
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 frame buffer and writing the modified buffer to a different file is not possible.

Known Limitations

Assemblies: Hair objects in assembly files are not supported.; Scene DAG inheritance from master to assembly scene is limited, including most instance flags and motion transformation.
New Subdivision Surface Support: The current implementation uses a non-adaptive tessellator even for "fine view length" approximation. A final subdivision level is estimated for the whole object, taking into account camera distance, approximation settings and bounding box information. It is important to note that bounding boxes as well as "max displace" are set as small as possible to avoid wrong estimates resulting in generation of too many triangles, bad performance or unexpected visual results. Large objects are especially prone to this limitation.
Native Ambient Occlusion: There is currently no scene selection mechanism supported to exclude certain objects from ambient occlusion computation.; The ambient occlusion cache can not be stored in disk files.
MetaSL Support: This feature is under development. Both the software and hardware rendering support for MetaSL shaders is limited. Missing features include advanced ray tracing effects, global illumination, and BRDF support.
Frame Buffer File Caching: The temporary frame buffer files are saved in 'tiled' .map format which is limited to a file size of 2GB. Therefore, a single frame buffer may not exceed this 2GB size limit. For example, the resolution of a square 8-bit RGBA frame buffer is limited to about 23000x23000 pixels.