Upgrading from mental ray 3.12 to 3.13

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

What's new in Version 3.13

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

Light Importance Sampling by Default

The Light Importance Sampling optimization technique introduced in the previous version of mental ray is now enabled by default. It gives a significant speed / quality advantage out of the box especially with modern and complex lighting setups, emissive objects, and very many light sources. In addition, new heuristics have been incorporated that automatically determine which light sources in the scene are physically plausible and would benefit from importance sampling. This way, traditional idealized light sources and simple lighting setups can be detected and handled separately, like they may be excluded from importance sampling to retain an overall benefit even though this feature is generally enabled. Custom light shaders are fully supported and will be included in importance sampling if they adhere to physically plausible emission and distribution rules.

With Light Importance Sampling enabled, further optimizations in the rendering core are possible when BSDF based materials are used, referred to as Multiple Importance Sampling. The prior knowledge of both light and material properties allows the renderer to make smarter decisions about the sampling strategy and necessary shading calls, reducing noise and rendering time even more. The Multiple Importance Sampling feature is currently disabled by default. It can be enabled and controlled with string options and on the command line of standalone mental ray.

New Support for MDL Materials

mental ray can now load and render pre-packaged material designs provided in the NVIDIA MDL format. These materials ensure an identical look across its rendering modes: mental ray - CPU, and iray - GPU and CPU.

The NVIDIA Material Definition Language, MDL, is a language specification to describe physically plausible material designs independent of renderers. It is based on common standards like BSDF reflection properties that can be layered to define complex shading models, supplemented with effects like texture mapping, displacement, bump and normal mapping, and cut-outs. The standardized material definition enables sharing and re-use of final material designs across different renderers, or rendering modes. MDL materials can be exchanged with any NVIDIA Iray-based rendering product.

The MDL materials are typically provided as .mdl files organized in a folder like module structure, providing other referenced data like textures. Such files can simply be loaded into mental ray via regular include statements. This will auto-create named scene materials that can be applied to scene instances as usual. Both MDL materials and traditional shaders can be utilized side by side within the same scene and will render smoothly. However, MDL materials are closed entities for mental ray upon loading. Parameter connections to other shaders or other MDL materials are not supported.

New Global Illumination "Next" (Prototype)

This version of mental ray offers a new global illumination engine to compute indirect lighting efficiently, and without the restrictions of the previous experimental solution GI GPU. In particular, it supports motion blur and works well with custom shading effects, like lens distortion and depth-of-field, volume effects, and subsurface scattering. It covers all the indirect lighting features of the traditional Final Gathering approach, like "color bleed" diffuse-diffuse bounces even passing through transparent surfaces or seen in reflections. Caustics are currently not handled. In contrast to the traditional GI implementations, the new engine is utilizing a brute-force algorithm without any caching, to guarantee uncompromising and consistent quality in static images and in animations. This also makes it extremely easy to use.

The new global illumination engine is considered a prototype in this version because it is under continuous development. It currently runs only on CPU, but is planned to take advantage of the GPU going forward. It should work reliably with typical scenes and setups, and with most third-party shaders. It can be enabled and controlled with string options and on the command line of standalone mental ray.

Native Ambient Occlusion Pass, GPU Accelerated

A new, easy to use Ambient Occlusion Pass has been added that automatically computes AO in a separate render pass without the need to manipulate the scene or attach special shaders. This implementation can take advantage of a capable NVIDIA GPU for best possible speed, and otherwise uses the CPU with exactly the same algorithm to create identical results. It can be controlled with string options and on the command line of standalone mental ray.

iray 4

The iray version 4.0 is a major update of this rendering mode built into mental ray. It adds support for the most recent NVIDIA GPU architectures, while retaining compatibility to previous generations of GPUs. This version also uses the latest CUDA runtime for best performance. The iray rendering core has been further optimized towards stability and scalability in multi-GPU and CPU/GPU setups.

Native UV Tiling

mental ray provides a new and efficient UV Tiling implementation in a new shader mib_tiled_texture. The shader is able to resolve the individual tile texture files automatically by supporting established indexing conventions, like UDIM. It then auto-creates and loads the tile textures into mental ray on demand, making sure that only those tiles that are actually accessed get loaded into memory.

The shader is part of a new package called coreutil, which collects essential mental ray utilities and helper functions for easy integration with third-party systems and external libraries of developing industry standards.

"Deep" Data

mental ray adds support for generating "deep" data and output to OpenEXR files. If the boolean attribute "deep" is set to true on a frame buffer, then the resulting image is saved in DeepTile form of OpenEXR 2.0 file format, storing additional information of the pixel colors along the Z axis. It is possible to save deep and classic data into different frame buffers during the same rendering.

OpenEXR 2.2 Support

The mental ray OpenEXR integration is now based on version 2.2 of the OpenEXR library. It adds new lossy compression modes, called "dwaa" and "dwab". The compression ratio can be controlled, ranging from 45 to 2000, for highest image quality down to most lossy and smallest image size.

New Alembic Features

The mental ray shader for import of Alembic archives has been updated to the latest Alembic library release, and extended with new functions. The support for creation of mental ray "hair" from Alembic's ICurves has been added. Currently, linear segments and cubic curves with a uniform knot vector are supported. Also, custom vertex data on polymesh geometry are now respected. They get attached to the target trilist geometry in mental ray as one of the types color3, color4, point, normal, float, or int, respectively. Shaders may retrieve the values during rendering to create special effects.

Improved Human Hair Shader

The previously introduced Human Hair Shader has been further improved. It now adds contributions from indirect lighting to the shading. New parameters have been added to tune the tube shading look, as well as control the internal color noise effect. Both of these effects are now turned off by default, enhancing the performance and look of the hair when typically rendered at a distance.

Note, there is a new BSDF based version of a hair shader available as part of the Layering package, supporting new features like LPE render passes.

Improved Layering Shaders

The layering shaders have been developed further, and enhanced with new functionality. Its Light Path Expressions, or LPE, are now respecting the new dynamic string attribute "LPE" on mental ray frame buffers, rather than renaming the frame buffer itself, with an impact on final layer names in image files.

New LPE expressions for diffuse, glossy, and specular reflection that is transmitted have been added. A new set of preset phenomena has been created, delivered in the extra file layering_phen.mi. That includes, for example, a phenomenon for realistic hair shading constructed from layering nodes that is inspired by the Marschner hair shading model, called mila_layer_hair. The required hair utility shaders are all contained in the layering package.

Custom Color Profiles

mental ray adds Custom Color Profiles, opening its color management pipeline to third-party developers and integrators. A new type of shader has been introduced making fully programmable color transformations possible while taking benefit of mental ray's established color handling machinery. The existing .mi scene syntax for color profiles on textures and frame buffers is not affected by this change but can simply reference the new vendor profiles by name.

mental ray Dynamic Library

mental ray can now be delivered as a dynamic library instead of an inseparable component built into applications or integration plug-ins. Third-party vendors can guarantee to load only compatible or certified mental ray libraries by using a new authentication mechanism in the mental ray library.

This new delivery model allows to update mental ray core at any time, and independent of updates of the host application. It has other advantages, like avoiding symbol and version conflicts for common dependent libraries like zlib, and the possibility to use different compiler versions and options for building mental ray vs. the applications or plug-ins.

Scene Description Language

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

To enable and tune the New Global Illumination Engine prototype, these string options are supported:
```
"gi" "on"|"off"
"gi rays" rays_int
"gi depth" depth_int
```
Please see the scene options for more details.
For the MDL Material support, new .mi syntax is supported:
```
$mdl
    ...
$end
```
For the Ambient Occlusion Pass, these new string options are supported:
```
"ambient occlusion gpu devices"
"ambient occlusion gpu cpu threads"
```
The "devices" value is a bitmask which allows to specify which CUDA devices are to be used. The value 0 is interpreted as using CPU. (default: -1, all devices).
With OpenEXR 2.2, the following new compression modes are supported on a camera frame buffer:
```
compression "dwaa"
compression "dwab"
```
Note, that the compression ratio in these modes can be controlled. As of now, the values recommended by OpenEXR authors are in the range of 45 (least lossy, largest file size, highest image quality) to 2000 (most lossy, smallest image size). The compression ratio can be specified using the quality attribute on mental ray frame buffers. The default is 45.
For Native UV Tiling, a new core utility shader mib_tiled_texture has been added.
```
declare shader color texture "mib_tiled_texture" (
    integer "mode" default 0,
    integer "utiles" default 10,
    scalar  "filter",
    string  "colorprofile",
    vector  "uvCoord",
    string  "texture_dir",
    array struct "texture_info" {
        string    "filename",
        vector    "tile_coord"
    }
)
end declare
```
The parameters have the following meaning:

mode"
specifies which file naming and layout convention is used. The value 0 (default) is to be used for UDIM convention, the value 1 for compatibility with Autodesk's Mudbox, the value 2 for compatibility with Pixologic's Zbrush. The value 3 allows to specify the list of arbitrary image file names in the "texture_info" array.
In mode 0,1,2, the shader would parse the directory "texture_dir" looking for matching file names (such as uXX_vYY for modes 1 and 2), and derive the number of tiles in v dimension from that data. In mode 3, the array specifies a list of arbitrary file names and the pair of u / v coordinates (integers in the range from 0 to max u resp. max v), corresponding the the placement of the tile.
utiles
specifies the number of tiles in u dimension. Some tiles files are allowed to be omitted.
filter
colorprofile
parameters passed through to the internal creation of the individual textures.
uvCoord
x in [0, utiles) and y in [0, max_v), is passed to the shader to select the tile, and load the corresponding texture if it has not been loaded before.
Known limitations: in multi-hosted rendering, textures need to be accessible from all machines on the file system. Textures are always interpreted as color textures.
For Custom Color Profiles, a new shader type colorprofiles is available. Its declaration and instancing follows the regular shader declaration rules. A shader declaration can now contain apply colorprofile flag. A colorprofile may now specify a shader instance with the syntax:
```
colorprofile "profilename"
    ... 
    shader <shader instance> 
    ... 
end colorprofile
```
To enforce a dedicated internal image type representation for a given texture, the following new .mi syntax is supported:
```
[<flags> <type>] texture <texture_name> [<colorprofile>] <file_name> [<image_type>]
```
Note the optional image_type addition at the end. This way, a low dynamic range 8-bit "rgb" source texture that is used with a color profile can be enforced to be stored internally as "rgb_h" (half float), for example, to retain a higher precision resulting from color transformations into high dynamic range (HDR).

An integration may call mi_api_texture_file_size(0, 0, 0, image_type) where image_type is a result of calling mi_api_texture_type_identify(mi_mem_strdup("<image type string>")). Unlike for earlier versions of mental ray, the mi_api_texture_file_size() function works with non-writable textures.

Shader Writing and Integration

For MDL Materials Support the API has been extended with the new function
```
mi_api_mdl_load_module()
```
It allows to load a specific MDL module. All MDL materials are accessible in mental ray database. For convenience, they are kept in a separate scope "mdl::".
For Custom Color Profiles, the API has been extend. The new member miColor_profile.shader is added, and a shader instance tag can be assigned by translators.

In general, the shader calling interface follows the same rules and conventions as other shader types. Shader init, exit and version functions are supported. Shader first parameter is a miColor in-out pointer, and the shader is supposed to convert the color in the direction needed.

Two new "ray types" are added: miRAY_COLOR_TO_INTERNAL and miRAY_COLOR_FROM_INTERNAL. When a shader is called, the miState::type is set to one of these values. The former value is used when a texture or texture tile is loaded into memory. The latter one is used for output images, such as frame buffers.

For optimization purposes, a colorprofile shader may implement SIMD-style conversion. When a shader is called, its miColor* parameters points to array of colors, and miState::count is initialized with the number of elements in that array (at least one). A color profile may decide to convert more than one. In that case, it return value should be the number of element the shader has converted. In particular, a shader that is not aware, or not implementing this extension would convert a single color and return miTRUE. As miTRUE == 1, the kernel would interpret this as a single element conversion. This SIMD optimization is only available for C/C++ shaders/shading trees, not for phenomena.

Since textures may be loaded outside of frame rendering scope, color profile shaders should not access options or camera, which may be not available.

For Layering shaders, these LPE expressions are now supported:

"L.+<RD><TS>+E"
"indirect_diffuse_transmitted"

"L.+<RG><TS>+E"
"indirect_glossy_transmitted"

"L.+<RS><TS>+E"
"indirect_specular_transmitted"

For "echo", new capabilities have been added.

For standalone mental ray, the command line option -echo callgeoshader will force to call geometry shaders and echo the generated content instead of the reference to geoshader. This mode may be useful in analyzing procedural assets, or removing dependencies on the geoshader components.

For standalone mental ray, the command line option -echo callassembly will evaluate callbacks of procedural assemblies, and export the generated content to .mi files as one file per assembly.

For mental ray geometry shader API, a new function has been added.
```
miBoolean mi_geoshader_echo_tag_file(
    const char    *file_name, /* file name */
    miBoolean     append,     /* append or rewrite file */
    const char    *header,    /* optional string to be written to file */
    miTag         tag,        /* DB tag to echo */
    miEchoOptions *options)   /* echo options */
```
Unlike mi_geoshader_echo_tag() function, it takes file name and the file opening mode (append or overwrite). The file mode is only relevant if the file already exists. Note that his function supports UTF8 file names, including WIndows platform.

The function mi_geoshader_echo_tag() is deprecated as one of its arguments, the FILE* pointer, should not be passed across dynamic library boundaries. This may cause conflicts if different compiler versions or compiler options were used.
For the Alembic import shader, the Alembic core library has been updated to version 1.5.5.
For the Ptex texture shader, the Ptex core library has been updated to version 2.0.42.
The Core Utilities for mental ray come in new shader package called coreutil. It collects mental ray auxiliary shaders that extend the functionality of the core rather than doing actual shading. This package currently holds the shaders
- abcimport for on-demand loading of Alembic archives,
- mib_ptex_lookup_x shader and mib_ptex_lookup phenomenon to read Ptex textures,
- mib_tiled_texture shader to handle UV Tiling textures automatically.
For Procedural Geometry, the API has been extended to support proper memory management.

For procedural assemblies, placeholder objects and placeholder user data blocks: added new functions:
```
mi_api_texture_callback_def_x()
mi_api_object_placeholder_callback_x()
mi_api_data_callback_x()
```
which take thee callback arguments. The third optional callback function is called when assembly/object/data block is deleted. Note, that mental ray can re-create data multiple times, which leads to zero, one or multiple create callback calls (#1) interleaved by the flush callback (#2) calls. At the end of the frame or rendering, the delete callback (#3) is called once. Thus, the parameters to the callbacks should be first released in that newly added delete callback.

Note, that it was a common design issue in geometry shaders to release the callback parameters in the flush callback (#2), which could lead to a crash if the create callback (#1) was called multiple times, or to a memory leak if the create (#1) and flush (#2) callbacks were not called at all.