next up previous contents
Next: 2.7 Scene Entities Up: 2. Scene Description Language Previous: 2.5 Phenomena

2.6 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 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 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 "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 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 sscene file syntax are present. For example, a scene file using demand-loaded  placeholder objects may specify min version 3.0 because that feature was introduced in mental ray 3.0, and would cause a syntax error in mental ray 2.x. Shaders have their own version numbers in declarations that are independent of mental ray version numbers.


    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 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 mental images. 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.


    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, execute with the privilege of the user running mental ray.


    code "filename" 

The named filename is interpreted as a C source file, ending with the extension ``.c'', is compiled and linked into mental ray. From this point on, the shaders it defines are available in mental ray 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 [*].

Compiling C++ code requires that the shader function prototypes and any included mental ray headers such as shader.h are included in extern "C". It may also be necessary to switch the compiler using the -c_compiler and -c_linker command-line options.


    $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. C++ requires the same steps as for the code command.


    link "filename" 

Like the code command, the link command attaches external shaders to mental ray, 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.3. 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 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.


    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

... vendors2.3
For system and development software requirements, see the Release and Installation Notes.

next up previous contents
Next: 2.7 Scene Entities Up: 2. Scene Description Language Previous: 2.5 Phenomena
Copyright 2002 by mental images