Upgrading from mental ray 3.9 to 3.10

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

What's new in Version 3.10

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

Ptex Support

The Ptex texture mapping system and file format developed by Walt Disney Animation Studios is now supported for rendering of ccmesh subdivision surface geometry. The new base shader mib_ptex_lookup is provided that performs lookup of the texturing information at render time. Since it is utilizing third-party runtime implementation delivered with mental ray the shader comes as a separate package ptex.dll/.so/.dylib.

In order to enable Ptex per-face assignment the ccmesh surfaces need to carry additional data when computed. This can be enabled globally using a registry key, or per object with a new optional bary attribute.

iray 2.0

The iray version 2.0 is a major update of this rendering mode built into mental ray. It provides numerous improvements in performance and quality, like native support for BSDF layering in the rendering core. This version is using the latest release of CUDA, thus it is supporting, and will actually take benefit from, most recent GPU hardware, like the NVIDIA Fermi architecture.

Hair Ray Tracing Performance

Hair rendering with ray tracing uses a new acceleration structure, which results in significantly better performance and lower memory consumption. For backwards compatibility, the previous behavior can be enabled with a string option. The improvement is especially noticeable when computing shadows and detail shadow maps(10-30%). The image quality is increased at the same time by raising the intersection precision. In addition, a transparency depth limit of 250 has been implemented for hair ray tracing, similar to the the value used in the rasterizer, to avoid excessive computations for big chunks of hair.

Detail Shadow Map Features

The quality of detail shadow maps has been improved. The data size of high-depth detail shadow maps has been reduced. Furthermore, a new string option allows to optimize size and quality of a detail shadow map.

Unified Sampling Features

The support for unified sampling in mental ray and in shaders has been extended. The min/max sampling limits can now be specified per object. For convenience, the unified sampling feature can be controlled from the command line of a standalone mental ray.

TIFF Image Format Features

The support for TIFF image format has been extended with more features, like

reading LZW compressed images,
reading and writing in tiled format, suitable for texture caching.

The output of tiled images in mental ray can be enforced with a frame buffer attribute. Using the imf_copy tool, a tiled TIFF file can be created using the -p option. Note, that the resulting TIFF subformat is not compatible with mental ray 3.8 and earlier, including its image tools. Tiled TIFF images may not be supported by external image manipulation tools.

OpenEXR Stereo Support

The OpenEXR Multiview extension is now supported and used to create stereoscopic ("sxr") image files. This allows to store the images for left and right eye in a single .exr (or .sxr) file. This behavior can be enabled per frame buffer by specifying a datatype "sxr", or globally by using a registry setting. Note, that the imf_disp tool is able to display only mental ray generated multiview OpenEXR files. For other ones created with external tools, camera names may be interpreted as conventional layer names.

Texture Caching Features

This version improves control of texture caching as well as reporting of cache performance and statistics. mental ray now prints out texture cache mode and cache size limit in the options info banner before each frame rendering. For each cached image file, ie. cached texture or frame buffer, it prints statistics about the number of pixel accesses and per-thread local cache coherency rate. At end of rendering, mental ray prints accumulated statistics. The dynamically computed texture cache memory is based on the size of the uncompressed textures in memory instead of the file size as used in earlier versions. In particular, the memory used for rendering no longer depends on the type of texture compression used.

Subdivision Mesh Features

The ccmesh subdivision mesh geometry now supports approximation with the sharp property, to achieve faceted rendering look. In addition, per-face user data can now be attached to a ccmesh object. Finally, the previous limit of two texture spaces for ccmesh geometry has been lifted, and up to four texture spaces are now supported for texture seam computation.

Initial Alembic Support

The Alembic open source interchange framework and file format is supported in an initial form. A new shader abcimport is provided to read static or animated geometry like polygon or subdivision meshes and NURBS surfaces from Alembic files, including support for loading them on demand only during rendering.

Deprecated Scanline Features

This mental ray version deprecates scanline as its default rendering mode, but promotes ray tracing as the primary renderer instead. This allows to take benefit from greatly improved ray tracing speed using latest achievements in BSP2 acceleration, as well as noticeably reduced memory consumption especially for larger scenes by avoiding to keep extra rasterization data. To help transitioning, mental ray adds support for previous scanline-only functionality in ray tracing mode, like

clip rendering of geometry on camera hither/yon planes, enabled with a string option,
compute motion vectors including camera movement, enabled with a string option.

New Shader Package

The new shader package useribl comes with mental ray. It supports convenient workflows for lighting from environment maps or from textured area lights similar to the built-in IBL functionality, this time provided as separate shader nodes with extended functionality.

New Subsurface Shaders

Improved subsurface scattering shaders misss_fast_shader2(_x) have been added with extended features towards production purposes. Consequently, two skin phenomena misss_phen_skin2_mia_phen(_d) are available that are based on these shaders.

Scene Description Language

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

The bary keyword can be added to a ccmesh object before the actual data block. If present, ccmesh tessellation generates barycentric and face index information which can be retrieved with mi_query function. Such data is required when using ptex texturing. Example:
```
object "mesh"
    group
        ccmesh "mesh_data"
            ...
            bary
        end ccmesh
    end group
end object
```
For hair ray tracing, this new string option:
```
"hair acceleration" on|off
```
can be used to revert to previous ray tracing acceleration method by setting it to off.

For ccmesh objects, support for the approximation sharpoption, to achieve smooth vs. facetted shading normals, has been added. Example:

object "mesh"
    group
        ccmesh "mesh_data"
            ...
        end ccmesh
        approximate sharp 1.0 ...
    end group
end object

For ccmesh objects, the syntax has been extended to provide custom data. Example:
```
ccmesh "s"
    polygon 1 vertex 6 data 1 3
    p 0 1 2 3 4 5 6    data [ 1234 ] [ 0 1 2 ]
end ccmesh
```
The first data statements specifies the expected count of arbitrary integer values per mesh (1), and per face (3). The second data line provides the actual data, starting with the per mesh data (1234) followed by the per face or polygon data (0 1 2). The custom data for additional faces need to be added to the end of the second list within the brackets.
For ray tracing, the camera hither and yon planes are typically not respected, but scanline and rasterizer do. These algorithms always need to clip geometry falling outside the depth range of the viewing frustum, to avoid precision problems and z-depth artifacts. This new string option enables such clipping also in ray tracing mode for eye rays (primary visible objects):
```
"trace camera clip" on|off
```
If set to on, the near and far clipping planes are respected for primary rays shot from the camera. This string option should be used with care in combination with lens shaders perturbing eye ray directions (like fisheye lens shaders) as it may lead to unexpected results: clipping is done based on the camera distance only. The default value is off.
For ray tracing, motion vectors were computed without taking camera movement into account, in contrast to scanline and rasterizer, which always generate motion vectors including camera motion. A new string option enables this known scanline behavior also for ray tracing:
```
"trace camera motion vectors" on|off
```
If on it will enforce to add camera motion effect to the computed motion vectors. The default is: off.

Shader Writing and Integration

The new registry key {_MI_REG_CCMESH_PTEX} is supported accepting a boolean value. If set to on, then all ccmesh objects are tessellated with ptex support capability, even if the bary flag is not specified on such objects. Example:
```
registry "{_MI_REG_CCMESH_PTEX}" value "on" end registry
```
Added mi_query() modes in order to improve support for per-face data:
```
miQ_PRI_NUM_DATA
```
returns per-face data size and layout information. A pointer to a miPri_data data structure should be passed as the parameter to the function, which will fill it with the data. Sizes are counted in 32-bit integers/floats. The query call is supported both for regular and displacement shaders.
```
miQ_NUM_USERS
```
returns the number of user vectors per vertex.
```
miQ_USER_DIM
```
returns the dimension (number of scalars) of the user vector. The current user vector is selected based on the additional selector parameter passed to mi_query(), with the valid range from zero to the return of miQ_NUM_USERS query mode.
For detail shadow maps, a new string option has been added:
```
"detail shadowmap contrast" color
```
The default value is 0 0 0. If set, the value is used to determine if multiple depth steps can be merged into a single final value stored in the map. If the difference of consecutive values falls below this threshold then just a single value is actually stored. With moderate positive values, like 0.15 0.15 0.15, a very deep falloff of the visibility can be stored in a much more compact form compared to previous versions.
For frame buffer output, a new string attribute option is available to enforce output of a tiled version of the image, currently supported by TIFF and OpenEXR image formats:
```
framebuffer "image"
    filetype "tif"
    attribute boolean "tiled" on|off
```
Image tiling is disabled by default, which is preferred to store final images that are compatible with most external tools. If set to on then the tiled variant is written, most suitable for texture caching purposes of large resolution images.
For OpenEXR, the output of stereoscopic OpenEXR files can be enabled globally by using the registry setting:
```
{_MI_REG_STEREO_EXR_MULTIVIEW}
```
with the value "on".
For mental ray standalone, added new command line options:
```
-unified_sampling on|off
```
to enable or disable unified sampling.
```
-unified sampling min max [ quality [ error_cutoff ]]
```
to enable unified sampling and set the min/max samples parameters, and optionally, the quality and error cutoff.
```
-texture_cache_size size
-texture_cache mode
```
For texture cache, new registry settings are supported offering better control:
```
{_MI_REG_TEXTURE_CACHE_SIZE}
```
If set, the value is taken as a limit of texture cache in MBs. By default, with a value of 0, the dynamic texture cache limit is based on the size of all textures loaded into mental ray, as in older mental ray versions. The minimal value of the cache is 20 MB.
```
{_MI_REG_TEXTURE_CACHE}
```
The value can be one of "on", "off", or "local". The default value is "local", meaning that only textures flagged as local (and all .map textures, which are automatically local) will be cached. This is the default behavior. With "off", texture caching is disabled and textures are always loaded/memory-mapped in full resolution. With "on", the local texture modifier is ignored and all textures in suitable image formats (currently .map, tiled .exr, tiled .tif, .iff, .bmp) are cached. This mode should not be used with multi-hosted rendering. Custom applications based on raylib should make sure that all non-local textures are deleted before this mode is enabled.
For For texture cache, mental ray standalone supports new command line options with similar meaning as the registry settings:
```
-texture_cache_size size
-texture_cache mode
```
For Alembic support, added import of Alembic files with a new shader library abcimport.dll/.mi containing a single geometry shader:
```
declare shader geometry "abcimport" (
    string  "filename",
    scalar  "time"      default -1.0,
    boolean "assembly"  default off 
    )
    version 1
    apply   geometry
end declare
```
filename
The shader searches for the Alembic file specified by this parameter using the assemblies search path set (-assembly_path command line option).
time
If this parameter value is not negative, the geometry for that time is selected. If it is negative, mental ray's miCamera::frame_time is used instead (default).
assembly
If this parameter is set to on, the geometry shader itself locates .abc file, computes bounding boxes and creates a procedural assembly. The actual geometry including possible hierarchy is generated on demand when the bounding box is hit. If this parameter is set to off, geometry is loaded immediately during scene preprocessing. This is the default mode.
Properties like materials, approximations and flags will be inherited from the instance the geometry shader is attached to.

Incompatible Changes

The accuracy parameter for detail shadow maps is deprecated and is no longer used.
The detail shadow map bias parameter is now respected exactly. If not set, the value computed based on the scene box is used.