Scene Description Language

The mental images 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 that set options such as verbosity or external shaders to be linked. Scene entities describe geometrical objects 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.

This book describes version 2 of the .mi format, abbreviated as .mi2. Although mental ray 2.x and 3.x still support the frame-based scene definition method supported by version 1.x of mental ray, this is not recommended for future designs and not described here. Both versions of the format can easily be distinguished: .mi1 files contain frame statements, while .mi2 files contain instance statements.

The recommended file extension is .mi regardless of the version.

This section discusses the parts that make up an .mi file. A less formal syntax is used for the syntax description: a bar "|" denotes alternatives, items enclosed in tall square brackets "[ ]" are optional, and the ellipsis "..." denotes omission, as in "zero or more repetitions of the preceding construct." Literal text is set in teletype, while variable metasymbols are set in italics. All other punctuation characters are literals. 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 n e m, 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.

The "#" character introduces comments, unless quoted, 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 book this is 3.1.1, 3.2.1, 3.3.1, or 3.4.1. 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.