home << prev next >> contents  


Objects

All geometry is specified in either camera space or object space, depending on the corresponding statement in the options statement (see section options). In camera space mode, the camera is assumed to sit at the coordinate origin and point down the negative Z axis, and objects are defined using camera space coordinates. In object space mode, the camera location is determined by its instance, and objects are defined in local object coordinates that are positioned in the scene with its object instance. Every object, camera, and light requires an instance. Camera space mode is only used for backwards compatibility with mental ray 1.x, and is now obsolete and not recommended. All existing integrations of mental ray on the market use object space exclusively.

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] ]3.4  
        [ shadowmap [on|off] ]  
        [ trace [on|off] ]  
        [ reflection mode ]3.4  
        [ refraction mode ]3.4  
        [ transparency mode ]3.4  
        [ select [on|off] ]  
        [ tagged [on|off] ]  
        [ caustic on|off ]  
        [ globillum on|off ]  
        [ finalgather on|off ]  
        [ caustic [mode] ]  
        [ globillum [mode] ]  
        [ finalgather mode ]3.4  
        [ finalgather file file (list) ]3.4  
        [ face [front|back|both] ]3.4  
        [ box [min_x  min_y  min_z  max_x  max_y  max_z] ]  
        [ motion box [min_x  min_y  min_z  max_x  max_y  max_z] ]  
        [ max displace value ]  
        [ ray offset value ]
        [ samples min  max ]  
        [ 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 groups contain the actual geometry. All geometry needs vector lists and vertex lists. The vector list contains 3D vectors that can 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 for increasing translation and parsing speed when ray is connected to a native translator; it should not be used in files modified with text filters. Many filters and editors refuse to accept files containing binary data, or corrupt them.

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 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 3.1 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 an example. Consider two triangles ABC and ABD sharing an edge AB. (This example will use the simplest form of polygon syntax that will be described later in this section.) 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.

Two types of geometry can be contained in the geometry list, polygonal geometry and free-from surfaces. In the next sections the syntax of the definitions of polygonal geometry and free-form surfaces is described and illustrated by examples.

If the optional mental matter product is available, objects can also contain subdivision surface geometry. Although part of the standard mental ray grammar (see the appendix), subdivision surfaces are not described in here. Refer to the mental matter manual instead.

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.

home << prev next >> contents  


Copyright © 1986-2006 by mental images GmbH