Instances

instance "name" "element" | geometry function
    [ hide on|off ]
    [ 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
    [ caustic on|off ]
    [ caustic [ mode ]]
    [ globillum on|off ]
    [ finalgather [ mode ]]^3.4
    [ transform [ matrix ]]
    [ motion transform [ matrix ]]
    [ face [ front|back|both ]]^3.4
    [ motion off ]
    [ override ]
    [ material "material_name" ]
    [ material [ "material_name" [, "material_name" ... ] ]
    [ light ["exclusive"] [ "light_name" [, "light_name ... ] ] ]
    [ light shadow ["exclusive"] [ "light_name" [, "light_name ... ] ] ]
    [ approximate [ approximation [, approximation ... ] ] ]
    [ tag label_int ]
    [ data [ "data_name" ]]
    [ ( parameters ) ]
end instance

Instances place cameras, lights, objects, and instance groups into the scene. Without instances, these entities have no effect; they are not tessellated and are not scheduled for processing. An instance has a name that identifies the instance when it is placed into an instance group (see below). Every instance references exactly one element element, which must be the name of a camera, a light, an object, or an instance group. If the instanced item is a geometry shader function, the scene element created by this special shader is actually used as the instanced item.

The hide flag can be set to on to disable the instance and the element it references. This is useful to temporarily suspend an instance to evaluate a subset of the scene, without deleting and later recreating suspended parts. hide is off by default.

The visible, shadow, shadowmap, trace, reflection^3.4, refraction^3.4, transparency^3.4, caustic, globillum, finalgather^3.4 and face flag^3.4 on|off switches and modes are inherited down the scene DAG. Flags in instances lower (closer to the objects) override flags in instances higher up. The flags from the instance closest to the object are merged with the corresponding object flags. The resulting values become the effective flags for rendering. If no flags are specified in the relevant instances, only the object flags are used. For the exact definition of these flags refer to the Object section.

The caustics mode bitmap contains four bits in the mode mask, as well as 2 more bits to store on and off switches. The switch bits cannot be provided in the scene description file as numbers, only in the on and off form. However, shaders can access these bits in the same bitmask. The desired behavior is the sum of:

[1] to enable caustic casting,
[2] to enable caustic receiving,
[4] to disable caustic casting,
[8] to disable caustic receiving,
[off(16)] to disable interaction of caustic photons with the geometry, and
[on(32)] to enable interaction of caustic photons with the geometry.

Note that the enable bits are two lowest and one highest among these six. Obviously, 1 and 4, 2 and 8, and 16 and 32 cannot be mixed, respectively. If mode after caustic is omitted, the default is 3 (enable casting and receiving). The fifth and sixth bits control "invisibility to photons", that is, if visibility is disabled photons do not intersect this object and fly right through. This also affects the portion of the scene where photons have an effect and will be traced by mental ray. For example, if caustics occur only in a small part of the scene, objects outside that area should be made invisible to caustic photons to tell mental ray it should not waste time tracing photons there. The globillum mode bitmap and globillum on|off works the same way and has the same bit layout, but controls global illumination instead of caustics. Finalgather bitmaps and switches work the same way as caustic and globillum one, but may be overwritten with the trace on|off.

The reflection, refraction, transparency and shadow contain four bits:

[1] to enable casting
[2] to enable receiving
[4] to disable casting
[8] to disable receiving

The reflection and refraction casting and receiving bits can be overwritten simultaneously with the trace on|off.

The transform statement is followed by 16 numbers that define a matrix in row-major order. The matrix establishes the transformation from the parent coordinate space to the object space of the instanced element. If the instance is directly attached to the root instance group (see below), the parent coordinate space is world space. For example, the following matrix translates the instanced element to the coordinate (x, y, z):

    transform 1 0 0 0  
        0 1 0 0  
        0 0 1 0  
        x y z 1

Note that "casting" here means "cast a shadow" or "cast a reflection" (that is, become visible in reflecting objects). This is the opposite sense of "casting a ray". A material shader attached to an object can send out reflection rays only if the object has the reflection receive flag set (or inherits it).

Instance transformations are ignored if the options element explicitly sets the coordinate space to camera space, using the camera space statement. This is not recommended. The parent-to-local space transformation direction has the effect that in order to move an instanced object one (local) unit in the (local) +X direction, x must be decremented by 1.

The motion transform matrix specifies a transformation from parent space to local space for motion blurred geometry. If not specified, the instance transformation is used for the motion blur transformation. In this case the parent instance determines whether motion blur is active or not. Motion blur is activated by specifying a motion transformation in the scene DAG. This transformation is propagated through the scene DAG in the same way as the instance transformations. The motion off statement turns off all motion information inherited up to this point, as if the camera and all instances above did not have motion transforms. This can be used to disable motion transformations for a scene subtree. The motion steps^3.1 option in the options block controls the number of segments of the curved motion path resulting from evaluating the transformation at different times in the interval 0..1.

If a motion transformation is specified in an object instance, the triangle vertex points of the tessellated geometry are transformed by the matrix product of the accumulated instance matrix and the inverse accumulated motion transformation matrix. The difference vector between the transformed and the untransformed triangle vertex point is used as a motion vector in local object space. If an object has motion vectors attached to the vertices, the motion vector calculated as described above is combined with the object motion vector. A motion transformation can be given for both object and camera instances. If a motion transformation is specified in a camera instance, the effective motion transformation for the triangle vertices is the matrix product of the relative instance and relative camera motion transformation.

The override keyword is a prefix for material and approximate statements. It causes the material, material list, or approximation list to override the materials and approximations in instances and objects lower in the tree. Without overriding, lower instances and objects take precedence.

The material_name is the name of a previously defined material. It is stored along with the instance. Instance materials are inherited down the scene DAG. Materials in instances lower in the scene DAG (closer to the leaves) override materials in instances higher up. The material defined lowest becomes the default material for any polygon or surface in a geometrical object that has no material of its own.

If a bracketed, comma-separated list of material_names is given, mental ray will use the n-th material in the list if the polygon or surface label is n. If the label exceeds the length of the list, the first material in the list is used. Polygon and surface labels can be specified in the object definition that have the tagged flag set. If this flag is not set, the first material in the list is used. The list may not be empty.

The light and light shadow constructs can be used to specify light lists for illumination and shadow casting, see below.

The approximation list provides default approximations for objects. It is a comma-separated list of approximation statements, including displacement approximations, and all flags if applicable (visible, trace, shadow, caustic, globillum). See page approx for syntax details. Like approximations in options blocks, the surface name must be all. For example, this approximation list overrides all approximations in the subtree below the instance, such that visible objects are tessellated moderately fine, traced and shadow objects are very coarse, and visible displacements are very detailed:

    override approximate [
        visible approximate fine view length 0.5 all,
        trace shadow approximate regular parametric 3 3 all,
        visible approximate displace fine view length 0.25 all
    ]

A label integer can be attached to an instance using the tag statement. Labels are not used by mental ray in any way, but a shader can use the mi_query function to obtain the label and perform instance-specific operations.

Also, user data can be attached with a data statement. The argument must be the name of a previously defined data element in the scene file. If the argument is missing, a previously existing data reference is removed.

An instance may define parameters. Instance parameters are evaluated during scene preprocessing during preprocessing. Whenever the initial scene traversal finds an instance, it calls the inheritance function defined in the options element with the parent instance parameters and the parameters of the new instance. The inheritance function must then compute a new parameter set, which becomes the parent parameters for any future instances found in the element subtree below the new instance, if element is an instance group (if not, no sub-instances can exist and recursion ends). The inheritance function is also called if there is no parent instance yet or if the new instance contains no parameters. The final parameter set created by the inheritance function called for the bottom-level instance (which instances a camera, light, or object) is made available to shaders, in addition to the regular shader parameters.

mental ray 3.1.2 introduces traversal functions in the options block, which are called like inheritance functions but have more control over the inheritance process. For example, they can control not only instance parameters but also flags, materials, and transformation matrices.

The instance parameters must be declared just like shader parameters. The declare command must name the inheritance function, as specified in the options element. All instances share the same declaration. Note that this limits the portability of the scene - it is difficult to merge it with another scene that uses a different parameter inheritance function.

If transform, motion transform, and material are given without arguments, the respective feature is turned off. This is useful for incremental changes. It is not relevant for the initial definition because these features are off by default when an instance is created.

The element may be named in more than one instance. This is called "multiple instancing." If two instances name the same object, the object appears twice in the scene, even though it is stored only once in the scene database. This greatly reduces memory consumption. For example, it is sufficient to create one wheel object for a car, and then instance it four times. Each of the four instances will contain a different transformation matrix to place the wheels in four different locations. (This implies that multiple instancing is not useful in camera space mode because in this mode the transformations are ignored.) It is also possible to apply multiple instancing to object groups to replicate entire sub-scenes.

If the instanced item is a "geometry shader", the function is called with shader parameters and the scene element created by the shader is defined in the local coordinate space of the instance. The geometry shader is called just before tessellation takes place. The following example uses a geometry shader mib_geo_sphere:

    instance "sphere"
        geometry "mib_geo_sphere" ()
    end instance

This example creates a spherical object procedurally. It uses the syntax for anonymous shader; as usual the named shader syntax using the shader keyword and named shader assignments using the " =" sign can also be used. As usual, shader lists may be used; if the shader is correctly written all created objects are put in a group and instanced together. Named shaders created inside or outside procedural object definitions are in global scope and can be shared with other objects.

For a complete example for building scene graphs with instances and instance groups, see below.

Light lists

Light lists3.5 provide an alternative method to pass lights to material shaders, and to specify lights for shadow casting. They offer the flexibility to use the same material on multiple geometries with different lights, and provide a standard method to specify lights for illumination in shaders. They require, however, cooperation by the shaders to use the light lists.

Light lists are bracketed, comma separateds list of light instances. The lists may optionally be flagged as "exclusive", in which case all lights except the named ones are used. An empty exclusive list results in all lights being used; if no light list is specified then all lights are usually used as well. The lists may also contain the names of instance groups besides the names of light instances. In this case, all lights in the instance groups are used. This offers a way to share light lists among instances.

The first light list (without a shadow keyword) is intended to specify the lights to be used for illumination in shaders. This requires cooperation by the shader; the shader must be coded to use the instance light lists with the light iterators which have been added to the shader API. If it doesn't then the instance light lists will be ignored (the light iterators can also be used to read the light lists in the shader for any other purposes).

The base and physics shaders provided by mental images have been modified to use light lists: if lights are specified as parameters to the shaders directly then these lights are used; otherwise, if a light list is present in the geometry instance, the light list will be used; otherwise, all lights in the scene are used.

The shadow light list specifies the lights for which the instanced geometry casts shadows. This gives additional flexibility in shadow setups; there might, however, be a slight performance impact when using shadow light lists with ray traced shadows.