Scene Description Language

The mental ray scene description language allows reading a scene from an ASCII or binary file called the .mi file. It contains a list of commands and scene entities. Commands are instructions for the renderer, for example to set options such as verbosity, or to link external libraries and shader packages. Scene entities describe the properties and relations of geometrical objects, light sources, cameras, materials and other components, which and shaders and other components.

Animations are rendered by setting up the first frame and rendering it, followed by scene modifications and another render command for every successive frame. These scene modifications are called incremental changes.

The recommended file extension is .mi.

This section discusses the parts that make up an .mi file.

Conventions

The following type-setting conventions and special symbols are used in scene language or command line fragments:

Regular: is used for explanations.
Literal: denotes scene language or command line fragments that should be entered verbatim, as shown.
Variable: denotes variable items that stand for certain application dependent text or other insertions described in the explanation.

|: the vertical bar separates alternatives ( "x|y" means "either x or y" ).
…: an ellipsis denotes repetition ( "x..." means "x, or x x, or x x x, or more ).
[ ]: square brackets enclose optional parts ("x[y]" means "either x, or x followed by y" ).
( ): parenthesis are used to group items together ("x(y|z)" means "either x y, or x z" ).

Strings are quoted with double quotes; this includes all names. mental ray permits strings containing literal double quotes if they are prefixed with a backslash. Names, such as material, light, or object names, need not be quoted, but it is highly recommended to avoid conflicts with reserved words [8], and to allow non-alphabetic characters. Without quotes, only lowercase and uppercase letters, underscores, and digits may be used; a digit may not be the first character of an unquoted name. No such restrictions apply to quoted names.

Integers are distinguished from floating-point numbers by appending the suffix int, as in degree_int. Integers are an optional "+" or "−" sign followed by a sequence of digits "0" through "9".

Floating-point numbers follow the same rules, but may optionally contain a decimal point "." and an optional exponent. If the number begins with a decimal point, a leading zero is assumed. Exponential notation has the form "nem", which is interpreted as n * 10^m. Strings can be distinguished from numbers because the grammar always requires them to be enclosed in double quotes.

Comments are introduced with the "#" character, unless quoted, and except between $code and $end code. Comments extend to the end of the line.

Unquoted whitespace acts as a separator but is otherwise ignored. Line breaks and indentation have no syntactical relevance, except where otherwise noted (commands beginning with a dollar sign, for example, must appear at the beginning of the line).

By convention, the first line of any .mi file should begin with the three characters #mi, followed by a blank (not a tab), followed by the partial or full version number of the earliest required mental ray version number. For the syntax described in this manual this is 3.6 or higher. This comment serves as a "magic number" that helps interactive programs or utilities like file to decide whether this is a .mi file or something else. It is not parsed by mental ray itself.

[8] Future versions may reserve more words than described here.