Objects

All geometry is typically specified in object space. In object space mode, enabled with a setting in the options block, the camera location is determined by its instance, all objects are defined in local object coordinates and positioned in the scene with their object instances. Every object, camera, or light requires an instance to be established in the scene for rendering.

Deprecated In camera space mode, the camera is fixed and assumed to sit at the coordinate origin and point down the negative Z axis, all objects are defined using camera space coordinates. Camera space mode is supported only for backwards compatibility, and is not recommended.

The appearance of the object, such as color and transparency, is determined by naming materials in the object definition. Before a material can be used in an object, it must be defined. Naming the material determines all aspects of the object's appearance. No further parameters, textures, or lights need to be specified; they are all part of the material definition.

The two most common approaches to materials and objects are to name all materials first and then all objects, which may simplify the implementation of material editors because all materials may be put in a separate file and then included in the .mi file using a $include command; or materials and objects may be interspersed. Either way, each material definition precedes its first use.

All polygonal and free-form surface objects have the same common format in the .mi file:

    object "object_name"
        [ visible [on|off] ]
        [ shadow [on|off] ]
        [ shadow [mode] ]
        [ shadowmap [on|off] ]
        [ trace [on|off] ]
        [ reflection mode ]
        [ refraction mode ]
        [ transparency mode ]
        [ select [on|off] ]
        [ tagged [on|off] ]
        [ caustic on|off ]
        [ globillum on|off ]
        [ finalgather on|off ]
        [ caustic [mode] ]
        [ globillum [mode] ]
        [ finalgather mode ]
        [ finalgather file file (list) ]
        [ face [front|back|both] ]
        [ box [xmin ymin zmin xmax ymax zmax] ]
        [ motion box [xmin ymin zmin xmax ymax zmax] ]
        [ max displace value ]
        [ ray offset value ]
        [ samples min  max ]
        [ shading samples samplesscalar ]
        [ data null|"data_name" ]
        [ tag label_numberint ]
        [ file "file_name" ]
        [ basis list ]
        group
            vector list
            vertex list
            geometry list
            approximation list
        end group
    end object

The individual parameters are:

The visible, shadow, trace, reflection, refraction, transparency, caustic, globillum, finalgather and face flags can be overridden by the instance using the standard inheritance mechanism. Instances can specify that a flag in the instanced object is turned on or off, or that it is left unchanged. The object flags are used only if all the instances from the root of the scene DAG down to the object all leave the flag unchanged.

Object Group

Object groups contain the actual geometry. Common to all geometry are vector lists and vertex lists.

Vector List

The vector list contains 3D vectors which describe points in space, normals, texture vertices, basis vectors, motion vectors, and others. Vectors are anonymous, they are triples of floating-point numbers separated by whitespace without inherent meaning. They are numbered beginning with 0. Numbering restarts at 0 whenever a new object group starts.

mental ray also accepts a compressed binary format for vectors. Instead of three floating-point numbers, a sequence of 12 bytes enclosed in backquotes is accepted. These 12 bytes are the memory image of three floats in IEEE 854 format, using big-endian byte order. This format is intended to increase translation and parsing speed when ray is connected to a native translator; it should not be used in files to be modified with text editors or filters, since they may refuse to accept files containing binary data, or corrupt them.

Vertex List

Vertices build on vectors. In the .mi format, there is no syntactical difference between polygon vertices and control points vertices for free-form surfaces; both are collectively referred to as vertices in this discussion. All vertices define a point in space and optional vertex normals, motion vectors, derivatives, zero or more textures and basis vectors, and optional user vectors: 

    v indexint  
    [ n indexint ]  
    [ d indexint indexint [ indexint [ indexint indexint ] ] ]  
    [ t indexint [ indexint indexint ] ]  
    [ m indexint ]  
    [ u indexint  
    ...

Polygon vertices may use all of these. Free-form surface control points may use v and m only; the others are either computed analytically or are specified in other ways as part of the surface definition.

v
specifies the point in space,
n
specifies the vertex normal vector (ignored when the vertex is used as a curve or surface control point). A normal vector defines the orientation (vertical) of the surface at this vertex.
m
specifies the motion vector. mental ray permits up to 15 m statements per v statement for nonlinear motion paths. If multiple motion vectors are specified, the shutter time interval 0..1 is equally subdivided, and each motion vector specifies the motion from the origin specified by the v vector to the corresponding point on the path. In other words, multiple motion vectors do not form a connected chain but a bundle of "rays" originating at the same point v.
t
specifies a texture vertex with an optional X/Y basis vector pair for bump map calculation. There can be up to 64 t lines for any given v vertex. The texture and basis vectors are ignored when the vertex is used as a curve or surface control point. Texture and basis information for surfaces is defined using a "texture surface", described below.
d
specifies a first and/or second surface derivative. First derivatives describe the UV parametric gradient of a surface; second derivatives describe the curvature. mental ray can compute surface derivatives analytically for free-form surfaces but not for polygons because polygons have no inherent UV coordinate space. Therefore, the d keyword must be used to define explicit surface derivatives for polygons. If d is followed by two indices they are taken to reference the first derivative d P du and d P dv (with P being the point in space); if three indices follow they are taken to reference the second derivative d^2 P du^2, d^2 P dv^2, and d^2 P du dv; and if five indices follow the first two describe the first derivatives and the next three the second derivatives. Derivatives are not used by mental ray, they are made available to shaders only.
u
specifies a user vector. No constraints are imposed on user vectors. mental ray does not operate on them in any way, they are passed through with the vertex and can be picked up by the shader.

Every vertex begins with a v statement and ends with the next v statement or with the start of the geometry description. All occurrences of index above reference the vector list; 0 is the first vector in this group. References of different types (for example, v and n) may not reference the same vector. As stated before, all vectors are 3D. If the third coordinate is not used (as is the case for 2D texture vertices, for 2D curve control points, and for 2D surface special points) it should be set to 0.0 by convention. If both the second and third coordinates are unused (as is the case for 1D curve special points), they should both be set to 0.0.

Vertices themselves are numbered independently of vectors. The first vertex in every group is numbered 0. The geometry description is referencing vertices by vertex index, just like vertices are referencing vectors by vector index. This results in a three-stage definition of geometry:

  1. List of vectors
  2. List of vertices
  3. List of geometry

The reason for this three-stage process is that it allows both sharing vectors and sharing vertices. This is best illustrated with the following examples.

Example

The examples will use the simplest form of polygon syntax that will be described later in this section.

Consider two triangles ABC and ABD sharing an edge AB. The simplest definition of this two-triangle object is:

    object "twotri"
        visible
        group
            0.0  0.0  0.0
            1.0  0.0  0.0
            0.0  1.0  0.0
            1.0  0.0  0.0
            1.0  1.0  0.0
            0.0  1.0  0.0
     
            v 0
            v 1
            v 2
            v 3
            v 4
            v 5
     
            p "material_name" 0 1 2
            p 3 4 5
        end group
    end object

The first three vectors are used to build the first three vertices, which are used in the first triangle. The remaining three vectors build the next three vertices, which are used for the second triangle. Two vectors are listed twice and can be shared:

    object "twotri"
        visible
        group
            0.0  0.0  0.0
            1.0  0.0  0.0
            0.0  1.0  0.0
            1.0  1.0  0.0
     
            v 0
            v 1
            v 2
            v 1
            v 3
            v 2
     
            p "material_name" 0 1 2
            p 3 4 5
        end group
    end object

The order of vector references is noncontiguous to ensure that the second triangle is in counter-clockwise order. Two vertices are redundant and can also be removed by sharing:

    object "twotri"
        visible
        group
            0.0  0.0  0.0
            1.0  0.0  0.0
            0.0  1.0  0.0
            1.0  1.0  0.0
     
            v 0
            v 1
            v 2
            v 3
     
            p "material_name" 0 1 2
            p 1 3 2
        end group
    end object

The need for sharing both vectors and vertices can be shown by specifying vertex normals:

    object "twotri"
        visible
        group
            0.0  0.0  0.0
            1.0  0.0  0.0
            0.0  1.0  0.0
            1.0  1.0  0.0
            0.0  0.0  1.0
     
            v 0  n 4
            v 1  n 4
            v 2  n 4
            v 3  n 4
     
            p "material_name" 0 1 2
            p 1 3 2
        end group
    end object

In this last example, both vector sharing and vertex sharing takes place. The normal in this example is actually redundant: if no normal is specified, mental ray uses the polygon normal. Defaulting to the polygon normal is slightly more efficient than interpolating vertex normals, if vertex normals are explicitly specified.

Geometry List

Various types of geometry can be contained in the geometry list, like polygonal geometry, triangle lists, free-from and subdivision surfaces. In the next sections the syntax of these definitions is described in detail.

Approximation List

At the end of each object group several approximation statements may be given which control the tessellation of the geometry. In polygonal object groups, the approximation is used only for polygons whose material contains a displacement shader. Free-form and subdivision surfaces are always controlled by their approximations. See approxomations for details.

An object group permits only one type of geometry, either polygons or surfaces but not both. It is recommended that objects contain only a single object group, so normally objects are either polygonal or surface objects but not both at the same time. Also, vector sharing is supported only for vectors of similar types (point in space, normal, motion, texture, basis vector, derivative, or user vector. A vector may not be referenced by vertices once as a point in space and once as a normal, for example.

Copyright © 1986-2009 by mental images GmbH