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 "18.104.22.168". The string can underspecify the version, as in "3.6". Missing numbers are implicitly assumed to be 0 so "3.6" becomes "22.214.171.124". 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.
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
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
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,
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.
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.
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 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:
|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.
Copyright © 1986, 2013 NVIDIA Corporation