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] ]
[ finalgather force on|off ]
[ 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 samplesscalar ]
[ tag labelint ]
[ 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.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).
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.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):
transform
1 0 0 0
0 1 0 0
0 0 1 0
x y z 1
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 supports 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 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 separated 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.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.