Variables and the Registry

Variables

Variables provide a general syntax for passing custom parameters using .mi files. Such variables are not used by mental ray. They may be used by other programs that read scene files without actually parsing any geometric data. For example, translators can store the translator version and name, source scene name, frame range, and other useful information in variables. Such variables can be used to control .mi parsing using conditionals.

set "name" ["value"]

Assign the value value to the variable name.

Registry

The registry is a storage for named entries, each of which contains an ordered list of key/value pairs. The names and values are strings. The registry is actively maintained and evaluated by mental ray. It is not related to native registry facilities found on operating systems.

Typically, registry commands are used in the rayrc startup file to customize mental ray. This file is typically stored in the mental ray program directory, or in a directory where the MI_ROOT environment variable points to.

All file path searches and accesses in mental ray go through registry substitution. Note, that conditionals can use registry keys as well.

registry "name"
    [value "value"]
    [link "library.so/dll"]
    [code "sourcefile.c"]
    [mi "scenefile.mi"]
    [spdl "scenefile.spdl"]
    [echo "string"]
    [system "shell command"]
    ["key" "value"]
end registry

Create a mental ray registry entry.

In general, any string can be used as name. However, it is common in mental ray to enclose the string in curly braces {name}. The braces allow mental ray to detect registry keys in any string and will enable automatic and recursive registry substitutions without explicit lookup commands.

The value of a registry entry is specified with the value statement, which defines the value returned from registry substitution. There can only be a single value, any secondary value command issued for on an already existing registry key will overwrite. The other optional fields of a registry entry can be used to execute side effects upon lookup, or to define custom fields.

$lookup "name"

This command looks up a registry name previously defined with a registry command, and executes the statements found there: link loads a library; code compiles and links source code; mi reads a scene file like $include; spdl reads a scene file in Softimage SPDL syntax; echo prints a string to the console; and system executes a shell command. Lookup statements are useful as facility macros. For example, to make a set of features available to mental ray, a single lookup statement can load the library, load .mi declarations for it, and print a message to the screen.

mental ray recognizes registry variables with the prefix _MI_REG_ and uses them for internal configuration purposes, and it provides and sets registry variables with _MI_RAY prefix for customization, see Registry Variables.

Registry Substitution

mental ray performs auto-expansion of registry keys when resolving file pathes. A registry key is identified by a non-empty string in curly braces, like in {mykey}. The expansion procedure is supporting recursions, when a registry value is using other registry keys itself as in the example below.

registry "{root}" value "/home" end registry
registry "{path}" value "{root}/users" end registry

If the registry key name is prefixed with an underline character as in {_mykey} then this will suppress the usual error condition and error message in mental ray when the registry entry does not exist. No expansion is performed in this case.

Registry expansion can also lookup environment variables. The form {$var} expands to the string value of the environment variable varif existing, otherwise it returns the empty string. With the help of conditionals, this can be used to customize mental ray by writing a common rayrc with default settings but is reacting to temporary overrides using environment variables, like this:

$ifdef "${?USER_PATH}"
        registry "{USRPATH}" value "{$USER_PATH}" end registry
$else
        registry "{USRPATH}" value "/home/shaders" end registry
$endif

registry "{_MI_REG_LIBRARY}"
    value "{USRPATH};/usr/local/mi/shaders"
end registry