Keywords: main

Next: 2.1 Shader Declarations Up: No Title Previous: 1.29 Diagnostic modes.1

# 2. 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 2.x still supports the frame-based scene definition method supported by version 1.x of , 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. Names, such as material, light, or object names, need not be quoted, but it is highly recommended to avoid conflicts with reserved words2.1, 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 degreeint. 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 . 10m. 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 `2.0.28` or `2.1.30`. 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.

#### Footnotes

... words2.1
  Future versions may reserve more words than described here

- 2.1 Shader Declarations
  - 2.1.1 Parameter Types
  - 2.1.2 Shader Apply Flags
  - 2.1.3 Declaration Options
- 2.2 Shader Definitions
- 2.3 Shader Lists
- 2.4 Shader Graphs
- 2.5 Phenomena
  - 2.5.1 Phenomenon Interface Parameters
  - 2.5.2 Phenomenon Roots
- 2.6 Commands
- 2.7 Scene Entities
  - 2.7.1 Options
    - 2.7.1.1 Sampling Quality
    - 2.7.1.2 Tessellation Quality
    - 2.7.1.3 Motion Blur
    - 2.7.1.4 Trace Depth
    - 2.7.1.5 Shadows
    - 2.7.1.6 Rendering Algorithms
    - 2.7.1.7 Feature Disabling
    - 2.7.1.8 Caustics
    - 2.7.1.9 Global illumination2.1
    - 2.7.1.10 Frame Buffer Control
    - 2.7.1.11 Scene Geometry
    - 2.7.1.12 Contours
    - 2.7.1.13 Diagnostic Modes2.1
    - 2.7.1.14 Miscellaneous
  - 2.7.2 Cameras
  - 2.7.3 Textures
  - 2.7.4 Materials
  - 2.7.5 Lights
  - 2.7.6 Objects
  - 2.7.7 Polygonal Geometry
  - 2.7.8 Free-Form Surface Geometry
    - 2.7.8.1 Bases
    - 2.7.8.2 Surfaces
    - 2.7.8.3 Surface Derivatives
    - 2.7.8.4 Texture Surfaces
    - 2.7.8.5 Curves
    - 2.7.8.6 Trimming, Hole, and Special Curves; Special Points
    - 2.7.8.7 Space Curve Geometry
    - 2.7.8.8 Approximations
    - 2.7.8.9 Connections
    - 2.7.8.10 Example
  - 2.7.9 Instances
  - 2.7.10 Instance Groups
- 2.8 Contours
  - 2.8.1 Where to Place Contours
  - 2.8.2 Color and Width of Contours
  - 2.8.3 Contour Output
  - 2.8.4 Faster Contours
- 2.9 Scene Example

Next: 2.1 Shader Declarations Up: No Title Previous: 1.29 Diagnostic modes.1