Keywords: main

Next: 2.7 Scene Entities Up: 2. Scene Description Language Previous: 2.5 Phenomena

# 2.6 Commands

Commands are instructions to 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 client host in a network configuration, commands are never seen by server 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 client host only. If the filenameis 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.

        set "name" ["value"]

Assign the value value to the variable name. Variables are not used by mental ray but provide a general syntax for passing parameters from translators to interactive 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.

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

This commands informs that this .mi file requires the given 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 `"2.1"`. Missing numbers are implicitly assumed to be 0 so `"2.1"` becomes `"2.1.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 , an error message is printed and aborts; otherwise the next number is considered. If all given numbers pass the test, continues. This command is recommended for declaration files included with `$include`2.3

        verbose on|off|levelint

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); verbose `on` is equivalent to level 5 (everything except debugging messages). Verbose messages can slow down while parsing, especially on systems with poor I/O systems such as Windows NT because of slow scrolling. 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. 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.

        system "shell_command"

This command starts a shell, which executes the named shell_command. The shell command must be enclosed in double quotes. waits until the shell command has completed; this can be defeated by ending the command with a shell `&` command. The system command, like echo, is executed while parsing, not during rendering. Its main purpose is writing finished pictures to an output device such as a film recorder.

        code "filename"

The named filename is interpreted as a C source file, ending with the extension ``.c'', is compiled and linked into . From this point on, the shaders it defines are available in as shading functions. For example, if the source defines a C function myshader, with the usual three parameters result, state, and paras (see chapter for details), the name myshader may be used in materials, lights, textures and so on as the quoted shader name. The command-line option `-code` provides an alternative way of compiling and linking C source. Multiple code commands are possible. This is intended mainly for debugging because linking precompiled shader libraries is much more efficient. Note that every shading function must also be declared; see section .

        $code
        C source text
        $end code

The $ signs must appear in column 1 of the line. This command also compiles and links C source code, but the code is read directly from the `.mi` file rather than from a separate source file. The C source text follows standard C syntax. In fact, it is written out to a temporary file, which is then compiled as if a `code` command had been used. Multiple $code commands are allowed. Note that every shading function must also be declared; see below.

        link "filename"

Like the code command, the link command attaches external shaders to , which can then be used as shading functions. While the code command accepts ``.c'' files as filename, the link command expects either object files ending in ``.o'', or dynamic shared object (DSO on Unix, DLL on Windows NT) files ending in ``.so''. Object files are linked, while DSOs are just attached without any preprocessing. DSOs are the fastest way of attaching an external shader, and require no compilers or development options, which are sometimes sold separately by system vendors2.4. However, certain old systems do not support DSOs. The `-link` command-line option provides an alternative way of linking object files and DSOs. Any number of files can be linked. Note that every shading function must also be declared; see section . If Dynamical Shared Objects are to be linked on Unix machines, the `LD_LIBRARY_PATH` or `LD_LIBRARYN32_PATH` (SGI) environment variable must include the path of the DSO file to be linked; see section .

        delete "element_name"

Delete a named scene element, such as objects, materials, lights, textures, instances, and instance groups. Declarations and shaders 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 contained 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.

        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.

#### Footnotes

... `$include`2.3
  Some versions of require that included files contain version limits because incorrect declarations can have severe consequences. However, shader versioning (see page ) provides an alternate and more flexible way of shader version verification.
... vendors2.4
  For system and development software requirements, see the Release and Installation Notes.

Next: 2.7 Scene Entities Up: 2. Scene Description Language Previous: 2.5 Phenomena