Instances

    instance "name" "element" | geometry function
        [ hide on|off ]
        [ visible on|off ]
        [ shadow on|off ]
        [ shadow mode ]
        [ shadowmap on|off ]
        [ trace on|off ]
        [ reflection mode ]
        [ refraction mode ]
        [ transparency mode ]
        [ caustic on|off ]
        [ caustic [mode] ]
        [ globillum on|off ]
        [ globillum [mode] ]
        [ finalgather [mode] ]
        [ transform [matrix]]
        [ motion transform [matrix]]
        [ face [front|back|both]]
        [ 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 ...]] ]
        [ shading samples samples_scalar ]
        [ 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, face flags, and reflection, refraction, transparency, caustic, globillum, finalgather modes (further referred to as flags) are used to control the rendering properties of the final object instance. They are inherited down the scene DAG, so that flags in instances lower (or closer) to the objects override those in instances higher up. The ones 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 description.

The shadow, reflection, refraction, and transparency mode bitmaps contain four relevant bits, which are represented by the following mode values:

[1] to enable casting the effect,
[2] to enable receiving the effect,
[4] to disable casting the effect,
[8] to disable receiving the effect.

If no bit is set then this instance does not enforce any changes of flags on the object, potential flags from instances higher up in the DAG hierarchy will be taken. Multiple bits in the bitmap may be set; the final mode value of this bitmap is the sum of the individual values listed above. Obviously, some combinations don't make sense, like both enable+disable either cast [5] or receive [10]. Typical values are:

[1] force cast,
[2] force receive,
[3] force all (cast and receive),
[4] force no cast,
[6] force receive-only (no cast but receive),
[8] force no receive,
[9] force cast-only (no receive but cast),
[12] force no effect (no cast nor receive).

Note, that "cast the effect" here means "cast shadows" or "cast reflections" onto other objects (or, become visible in reflections on other objects). This is the opposite sense of "cast a ray". For example, a material shader attached to an object will "cast reflection rays" only if the object has the receive reflection flag enabled.

For backwards compatibility, the reflection and refraction casting and receiving bits can be overwritten simultaneously with the trace on|off flag.

The caustic and globillum mode bitmaps contains four bits in the mode mask, as well as 2 more bits to store on and off switches, which can be used to hide the object completely from the photon tracing effects. The switch bits can only be controlled using the on and off syntax in .mi scene files. However, shaders can access these bits in a single bit field. The desired behavior is a combination of:

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

Note, that the enable bits are contained in the two lowest and the highest bits. Obviously, the values 1 and 4, 2 and 8, and 16 and 32 cannot be mixed, respectively. If the mode value is omitted, the default is 3 (enable casting and receiving). The fifth and sixth bits control "visibility to photons"; if disabled then 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 then objects outside that area should be marked as invisible to caustic photons to tell mental ray it should not waste time tracing photons there.

The finalgather bitmap and switches work in the same way as caustic and globillum ones, they just control the behavior for final gathering rays. Note that the deprecated trace flag, which is supported for backwards compatibility reasons, will also control some of the final gathering properties.

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

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.

Instance transformations are ignored if camera space is in effect in a scene. This is deprecated and not recommended.

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 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
    ]

When rendering with the rasterizer mode, it is possible to specify the number of shading samples to be used on a per-instance basis. This will locally override the setting in the render options. It is also possible to specify this setting per-object if needed, but the instance setting will override the object setting when both are present. Overriding the option setting would normally be done to keep the scene settings low, to keep rendering times down, but boost the quality of the rendering of one or more objects or instances, to achieve the required quality in the final image.

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 supprts 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 ^3.5

Light lists allow to store relations between instances of lights and objects in the mental ray scene database, instead of passing this information through shaders. Separate light lists for shadow casting are supported. This offers the flexibility to share a single material on multiple objects with different lights. However, cooperation by shaders is required to utilize these 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 convenient way to attach sets of lights to instances.

The regular light list (without shadow keyword) is intended to specify the lights to be used for illumination in shaders. Shaders access the instance light lists with the light iterators which have been added to the shader API. The light iterators may also be used to read the light lists in the shader for other purposes.

The standard mental ray shader packages make use of 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 light shadow list specifies the lights for which the geometry instance casts shadows, which is independent of the regular light list. This affects both ray traced shadows as well as shadow maps. If no shadow light list is specified then the regular light relations will control shadow relations as well. Note, that a slight performance impact is expected when shadow light lists are used together with ray traced shadows.

Instances

Light Lists 3.5

Light Lists ^3.5