Scene Entities

A .mi file contains commands and scene entities in any order, with the restriction that an element must be defined before it can be referenced. All entities are named; all references are done by name. The following entities can be defined:

`options`	global options
`camera`	camera: output files, aperture, resolution, etc.
`material`	shading, shadows, volumes, environments, contour, etc.
`texture`	procedural texture or texture image
`light`	light
`object`	polygonal or free-form surface geometry
`instance`	places objects, lights, cameras, and groups in 3D space
`instgroup`	for grouping instances; the nodes of the scene DAG
`assembly`	demand loaded subscene
`shader`	optional named shaders
`data`	arbitrary user data
`lightprofile`	light profile such as IES or Eulumdat
`map`	map data to store point information

All of these can be defined at any place, as long as they are not nested (the definition of an element must be completed before the next element can be defined). All these entities can also be incrementally changed by introducing the definition with the incremental keyword, which tells mental ray to re-define an existing element instead of starting a new one. The contents of the existing element become the defaults for the new one.

options

This element contains rendering options such as the shadow mode, tracing depth, sampling algorithm and its parameters, acceleration algorithm and its parameters, dithering and other modes.

camera

The camera is a description of the camera characteristics such as focal length and aperture that determine the field of view.

texture

Textures to apply

2D or 3D color, bump, transparency,

displacement and other maps to objects. Textures are referenced by other shaders that include the texture in their color or other computation. Textures may appear verbatim in the file, or may be read from a texture file, or may be fully procedural, or a combination of these.

material

Materials describe the

surface properties of objects, volumic properties of the space enclosed by objects, transparent shadow casting, environment mapping, and

displacement mapping, as well as a number of property flags.

light

Lights illuminate objects and volumes. Lights are referenced in materials only (through the light instance), they are not applied directly to objects.

All lights name a shading function; there are predefined shaders for points, spots, and directional lights, optionally in combination with various types of area light sources.

object

Objects describe the actual geometry. Objects may reference materials to determine the visual appearance of the surface. Various types of geometry descriptions are supported, such as polygonal objects and free-form surfaces. By default, all objects are defined in a local coordinate space (object space), usually with the origin at the center of the object. Options exist to switch to camera space instead.

instance

When an object, light, camera, or instance group is defined, it does not become part of the scene. It must be placed in 3D space with an instance, which contains a transformation matrix, inherited parameters, and several flags. It is possible to have more than one instance reference the same object, light, camera, or instance group; this is called "multiple instancing". The instanced entity then appears several times in the final processed scene. It is possible to specify a "geometry shader" as the instanced item instead of an object. The "geometry shader" is expected to create a scene element which is defined in the local coordinate space of the instance.

instgroup

Instance groups are used to group instances so they can be instanced as a unit. Instance groups form the nodes of the scene DAG (Directed Acyclic Graph), which contains all entities used during processing. The instance group at the root of the DAG is called the "root instance group." Since instance groups can themselves be instanced the scene DAG can be built with any number of levels and sub-DAGs, each with its own local coordinate space.

assembly

Assemblies provide on demand loading of entire subscenes, containing materials, objects, instances and groups. On demand loading reduces memory consumption and allows faster rendering depending on visibility. The subscenes can be defined in separate files or procedurally.

shader

Shaders are user-provided functions used for a variety of purposes. They are not normally named; they are defined where they are needed, like in a material. An unnamed shader is also called an "anonymous shader." The shader statement allows giving a name to a shader; a named shader can be used in any place where an anonymous shader is expected by giving its name, introduced by an equals sign.

data

User data blocks are independent named toplevel scene entities that hold structured or unstructured data of any kind. Structured data is declared much like shader parameters, while unstructured data is a raw byte stream with a fixed size. User data is useful for large amounts of shared scene data.

lightprofile

Light profiles such as IES or Eulumdat are files supplied by lamp vendors that describe the emission characteristics of physical lights. Light profile blocks can be defined in the scene file that reference the lamp vendor profile file, and passed to shaders as parameters of type lightprofile. Shaders can then look up the emission characteristics of the light.

map

Map data blocks are independent named toplevel scene entities that hold positional information with arbitrary data attached to such positions. Map data is useful to store large amounts of 3d point data, for example. It can actually be used to provide any custom data with a specific position in space. Shaders can use dedicated C++ API to access the individual elements of a map, or to perform common operations with native optimized implementation in mental ray, like nearest-neighbor searches.

All scene entities are described in more detail in the following subsections.

mental ray allows forward references from groups to instances; and instances to groups, objects, lights, and cameras. This means that it is possible to write a group block that names an instance that does not yet exist, for example; mental ray will resolve the connection when rendering begins. In all cases not listed above, an element must exist before it is used. Although forward references could be used to create cyclic dependencies, this is highly discouraged because it can lead to inconsistent scene graphs, and because the -echo command-line option cannot properly resolve such dependencies. Forward referencing is useful for systems that put together scene files from different sources.