Configuration Settings

Configuration Settings 3.12

mental ray default behavior and special properties can be set with the help of configuration variables, which apply to all renderings that share this configuration, like all users on a machine, or all renderings for a certain project. Typically, such variables are set using the native registry of mental ray, a platform independent mechanism that is suitable for both standalone and embedded versions of the software. A prominent example is the rayrc startup configuration file used by standalone mental ray. Alternatively, certain variables may be set in the runtime environment of the running process using platform dependent commands. Such variables will override the related registry setting in case it was set.

Note The standalone mental ray allows to extend or override configuration options on the command line.

Environment Variables

Environment variables can be set from a command prompt with shell commands such as setenv (see the documentation of your shell) before mental ray, or the application that mental ray is built into, is started from the same shell. Environment variables that are set after mental ray was started, or which have been set from a different shell, have no effect. mental ray will generally work without setting environment variables.

Note The standard rayrc startup configuration file for standalone mental ray may not be found if the environment variable MI_ROOT is undefined.

HOME: Unix home directory, used to search for the user's local configuration files.
HOMEDRIVE: Windows NT home drive, such as C:.
HOMEPATH: Windows NT home directory. The concatenated path %HOMEDRIVE%%HOMEPATH% is used to search for the user's local configuration files.
MI_ASSEMBLY_PATH: A colon-separated or semicolon-separated list of paths to search for assembly .mi files.
MI_FBDIR: The default directory where temporary frame buffer files are stored.
MI_FBVIRTUAL: Set the default virtual frame buffer behavior. Values are "none"/"off", "mapped"/"on", or "cache", similar to the related command line option.
MI_LIBRARY_PATH: A colon-separated or semicolon-separated list of paths to search for files loaded with the link command.
MI_LIGHTPROFILE_PATH: A colon-separated or semicolon-separated list of paths to search for lightprofile files.
MI_MAP_PATH: A colon-separated or semicolon-separated list of paths to search for map data files.
MI_MAP_CACHE_SIZE: The size of the global cache for all maps currently present in memory, in Megabytes. Given as a number.
MI_RAY_HOSTSFILE: Use this file name instead of the default .rayhosts to read host configuration for distributed rendering.
MI_RAY_INCPATH: A colon-separated or semicolon-separated list of paths to search for files included with the $include command.
MI_RAY_OPTIONS: A string of default command line options that are read by mental ray standalone before the options given on the command line. This may be used for common options such as -xcolor.
MI_RAY3_SERVICE: The IP service that mental ray uses to contact slaves on other machines. The default is mi-ray3 for mental ray 3.x. On Unix, service names are defined in /etc/services or in the services NIS map.
MI_RAY_SERVICE: If the previous variable is not defined, this one is used instead. This makes mental ray 2.x compatible with mental ray 1.9 while allowing both to coexist on the same machine. The default is mi-ray.
MI_RAY_SUBSTITUTE: An optional list of blank-separated substitution instructions, each in the form /search/replace/. Any other character besides / will also work.
MI_ROOT: The directory that mental ray searches for the configuration file rayrc.
MI_STACKSIZE: New thread stacks will be created with this size in kilobytes if defined. The default is 16384 (16 MB) on Unix and 4096 on Windows. 4096 is nearly always sufficient except when very complex recursive shaders are used.
MI_TEX_LOOKUP_LOCAL: This variable can be set in network parallel rendering in order to look up and remap texture file paths on the individual rendering hosts instead of on the master host only. This allows to locate textures on the slave machines at a different file system path than on the master host.; Note MI_TEX_LOOKUP_LOCAL should be set on all rendering hosts, not just the master.; Note This will also causes file names to be echoed in the .mi format without performing file path substitutions.
SI_LOCATION: The directory of the linktab.ini file, which may be used by applications to customize file path mapping.
TMPDIR: A directory for temporary code or object files to be compiled or linked. The default is /usr/tmp on Unix and the current directory on Windows.
USER: The current user name. This is optional, and if it exists may be stored in image file headers, for example.

The mental ray registry supports lookups of environment variables. The form $var returns the value of the environment variable var, and $?var returns 1 if the environment variable var exists and 0 otherwise.

Registry Variables 3.12

Registry variables can be set from any .mi file. The special file .rayrc is automatically read by a standalone mental ray upon startup for configuration purposes.

mental ray recognizes and uses registry variables that begin with _MI_REG_ which have special meanings:

_MI_REG_ASSEMBLY: The directory where assembly files are stored, unless the -assembly command-line option has been specified.
_MI_REG_CCMESH_CHECK_TOPOLOGY: If set to "on", more expensive topology tests are done for ccmesh objects to reject potentially invalid geometry early and avoid failures during rendering later.
_MI_REG_CCMESH_PTEX: If set to "on", all ccmesh objects are tessellated with ptex support computed. This can be used to enable ptex support in existing scenes where the bary object flag to mark for ptex is not specified.
_MI_REG_FBDIR: The default directory where temporary frame buffer files are stored.
_MI_REG_FBVIRTUAL: Set the virtual frame buffer behavior. Values are "none"/"off", "mapped"/"on", or "cache", similar to the related command line option.
_MI_REG_INCLUDE: The search path where files included by $include commands are found, in addition to paths set with the -I command-line option.
_MI_REG_LIBRARY: The search path where shader libraries linked by link commands are found, in addition to paths set with the -L command-line option.
_MI_REG_LIGHTPROFILE: The search path where light profile files referenced by lightprofile statements are found, in addition to paths set with the -lightprofile_path command-line option.
_MI_REG_MAP: The search path where map data files are found, in addition to paths set with the -M command-line option.
_MI_REG_MAP_CACHE_SIZE: The size of the global cache for all maps currently present in memory, given as a number in Megabytes.
_MI_REG_MEMORY_LIMIT: The default memory limit in Megabytes, given as a number. May be overridden on the mental ray command line for a specific rendering.
_MI_REG_METASL_BACKEND: for MetaSL shaders, selects the back-end to use for compilation and execution of the shader code. Supported values are CPP or C++ for the C++ back-end using an external compiler, or LLVM for the integrated low-level virtual machine translation and execution engine.
_MI_OPENEXR_MULTI_PART 3.12: controls the use of the "multi-part" output in OpenEXR 2.0 used to store multiple layers within the same image file. If set to "off" then .exr images with more than one layer will be written in the original single-part format to retain compatibility with older OpenEXR tools. The default is "on".
_MI_REG_STEREO_LEFT_SUFFIX _MI_REG_STEREO_RIGHT_SUFFIX: the strings applied as file name suffixes for the images of the left and right eye in stereoscopic rendering mode.
_MI_REG_TEXTURE: an include path where texture image files referenced by texture statements are found, in addition to paths set with the -T command-line option.
_MI_REG_TEXTURE_CACHE: The value can be one of "on", "off", or "local". The value "local" means that only textures marked as local are cached, or any .map, which are always considered as local. This behavior matches previous mental ray, and is the default. 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 with image formats supporting caching are cached. This mode should not be used with multi-hosted rendering.
_MI_REG_TEXTURE_CACHE_SIZE: Set a memory limit for the texture cache in Megabytes. By default (value 0), the cache limit is determined dynamically based on the size of all textures loaded into mental ray, as in previous versions. The minimal value of the cache is 20 MB.
_MI_REG_TILE_SIZE: Set the tile size for the output of image files with tiling enabled. The value is a string with one or two numbers, like "X" (for quadratic tiles) or "X Y". The default is 128×128.

mental ray provides and sets registry variables that begin with _MI_RAY_ as follows:

_MI_RAY_VERSION: the full version number of mental ray, like "3.13.1.1".
_MI_RAY_MAJOR_VERSION: the major version number of mental ray, like "3".
_MI_RAY_MINOR_VERSION: the minor version number of mental ray, like "3.13".
_MI_RAY_BRANCH: the branch version number of mental ray, like "3.13.1".
_MI_RAY_REVISION: the revision version number of mental ray, like "85991".
_MI_RAY_SYSTEM: a general computer system name that mental ray has been compiled for. This is one of the strings "windows", "linux", or "macosx", and "unix" for all other systems.
_MI_RAY_PLATFORM: the compile platform string of mental ray. Common values are "nt-x64-vc11", "linux-x86-64-gcc4", and "macosx-x86-64".
_MI_RAY_DATE: a readable form of the build date of mental ray, like "Jan 03 2015".