Commands

Commands are instructions to mental ray that are executed the moment they are read from the input scene file. They do not add elements to the scene database. Since the scene file is only read by the master host in a network configuration, commands are never seen by slave hosts.

$include "filename"  
$include <filename>

The $ sign must appear in the first column of the line. The named file is included (pasted into) the .mi file in place of the $include statement. Includes can be nested. The main purpose is to include declarations (see below), but materials, light sources, even objects can be included. The only place where $include cannot be used is between $code and $end code; use the standard C #include statement there. The included file is read on the master host only. If the filename is enclosed in angle brackets, the standard include path is prepended, by default /usr/include. The standard path can be changed with the -I command-line option.

namespace "name"
...
end namespace

A namespace bracket can enclose any number of toplevel element definitions. Any toplevel element name defined and used in this bracket will be prefixed with "name ::". For example, a material named "mtl" defined in the bracket will be named "name::mtl". Inside the bracket it can be referenced as "mtl", but outside the bracket the full "name::mtl" name must be used. Inside the bracket, global toplevel elements outside the bracket can be referenced by prefixing the name with ::, as in "::mtl". Namespaces are useful to define subscenes that should not interfere with other subscenes or the main scene.

Note that all geometry created by a geometry shader is implicitly defined in a namespace with a unique namespace name that is automatically generated by mental ray. This is how two geometry shaders that both create toplevel elements with the same name avoid interfering with each other.

Note that the -echo command-line option does not reproduce the namespace statements, but instead generates the full :: names.

   [min] version "string"
    max version "string"

This command informs mental ray that this .mi file requires the given mental ray version. min means "at least" and max means "at most". Version strings consist of numbers separated with dots, such as "1.2.3.4". The string can underspecify the version, as in "3.6". Missing numbers are implicitly assumed to be 0 so "3.6" becomes "3.6.0.0". Each number, beginning with the first, is checked in turn. If the number in the string is greater ( min) or less than ( max) than the version number built into mental ray, an error message is printed and mental ray aborts; otherwise the next number is considered. If all given numbers pass the test, mental ray continues.

File version numbers are especially useful for declaration files, such as base.mi in the standard distribution. They are mainly useful for making sure that certain mental ray features and scene file syntax are present. For example, a scene file using demand-loaded assembly files may specify min version 3.6 because that feature was introduced in mental ray 3.6, and would cause a syntax error in earlier versions. Shaders have their own version numbers in declarations that are independent of mental ray version numbers.

verbose on|off|level_int

This command controls verbose messages. There are seven levels: fatal errors (0), errors (1), warnings (2), progress reports (3), informational messages (4), debugging messages (5), and verbose debugging messages (6). All message categories numerically less than level are printed. Verbose off is equivalent to level 2 (fatal errors and errors only); verbose on is equivalent to level 5 (everything except debugging messages). Verbose messages can slow down mental ray while parsing, especially on systems with poor I/O systems such as Windows NT because of slow scrolling. Verbose level 7 should generally be avoided; it prints information that is really only useful for debugging purposes. The verbose command can be overridden with the -verbose command-line option.

echo "message"

The named message, which must be enclosed in double quotes, is printed to stdout. The echo command is executed synchronously during parsing the .mi file. Echoing requires verbosity level 4 or higher.

call shader_list [, "camera_inst" "options"]

The given shader is called immediately, and parsing stops until the shader completes. Since the shader is called during parsing and not during tessellation or rendering, the entire state passed to the shader is filled with nulls, which limits what the shader can do (it cannot cast rays, for example). If the name of a camera instance element and the name of an options element is given, state→options and state→camera are set up for the shader. The return value is ignored. The call statement is intended for early initialization of shader packages, or even to start interactive front-end packages from inside a standalone mental ray. Shader init and exit functions are not called by the call statement. For shader initialization, shader init functions are more useful because they are called with a full state, and only if the corresponding shader is actually needed. Call statements are rarely used.

touch "element_name"

Mark the element as modified (or dirty), similar to an incremental change. This enforces a full re-evaluation of the element in a subsequent read access, disregarding any cached values like tessellations. This is useful when a displacement shader or a connected subshader changes (mental ray cannot discover this by itself), or when the content of a texture file has changed on disk and needs to be reloaded.

system "shell_command"

This command starts a shell, which executes the named shell_command. The shell command string must be enclosed in double quotes. The full shell scripting command syntax is available, including pipes, redirections, control structures, and environment variables. mental ray waits until the shell command has completed; this can be defeated by ending the command with a shell & command. The system command is executed while parsing, not during rendering. Its main purpose is writing finished pictures to an output device such as a film recorder. Shell commands are operating-system dependent and are much less useful on Windows NT because NT shells are severely limited. Note that shell commands, like shaders, are executed with the privilege of the user running mental ray.

delete "element_name"

Delete a named scene element, such as objects, materials, lights, textures, instances, and instance groups. Declarations cannot be deleted. It is possible to delete an element and recreate it with the same name, but this breaks all links. For example, if a light is created and then an instance is created for it, naming the light, the link between instance and light is broken when the light is deleted and recreated. The instance retains a dangling link that will cause havoc during later processing. The delete command should be used only for entities that disappear permanently. All instances and instance groups that contain the name must be updated before the name is deleted.

Instead of deleting and recreating an element, an incremental change should be used by prefixing the element definition with the incremental modifier. This has the additional advantage that the element retains all contents that are not modified during the new incremental definition. For example, an incremental change to a camera containing nothing but a new frame number specification will leave the camera unchanged except for the frame number. As an exception, objects and instgroups are cleared first because merging is not generally useful in these cases.

debug "mode" ["arg"]

Print debug information to the stderr. The verbosity ( -verbose) must be set to 4 or higher. Some modes print information on a specific database element arg. The following modes are supported:

mode	arg	operation
`sym`	-	print all symbol tables
`sym global`	-	print the main global symbol table
`sym declare`	-	print all declaration symbols
`sym variable`	-	print all variables from the `set` command
`sym hardware`	-	print all hardware shaders
`registry`	-	print all registry command entries
`mem summary`	-	print memory usage summary
`db statistics`	-	print scene database tag usage statistics
`db summary`	-	print scene database tags by module and type
`db dump`	-	print all tags in the scene database
`job statistics`	-	print summary of executed jobs
`img verbose`	-	turn on debugging for loaded image files
`scene check`	Y	check database consistency of tag
`scene dump`	Y	brief listing of tag hierarchy
`scene alldump`	Y	verbose listing of tag hierarchy
`echo`	Y	echo a tag, like `-echo`

render "root_instgroup_name" "camera_inst_name" "options_name"

This statement renders the scene.

The name of an options element, a camera instance element (which must also have been attached to the root instance group), and the root instance group must be given.