Instances

Element type:	miSCENE_INSTANCE
Data type:	miInstance
Sizes:	int param_size
Defaults:	all nulls, two identity matrices, parameter size as given by size argument

enum miGenMotionType {
        miGM_INHERIT = 0,
        miGM_TRANSFORM,
        miGM_OFF
};

typedef struct miTransform {
        miTag           function;               /* function, may be null tag */
        float           time;                   /* the last evaluation time */
        miMatrix        global_to_local;        /* transformation in world */
        miMatrix        local_to_global;        /* transformation to world */
        miCBoolean      identity;               /* SCENE: matrices are ident.*/
        miCBoolean      spare[3];               /* SCENE: not used */
        int             id;                     /* SCENE: unique transform ID*/
} miTransform;

typedef struct miInstance {
        miTransform     tf;                     /* space transformation */
        miMatrix        motion_transform;       /* motion transformation */
        miTag           item;                   /* instanced item */
        miTag           material;               /* inherited material or list*/
        miTag           parent;                 /* SCENE: leaf inst. parent */
        miTag           boxes;                  /* SCENE: renderable repres. */
        miTag           next;                   /* SCENE: leaf instance list */
        miTag           prev;                   /* SCENE: leaf instance list */
        int             mtl_array_size;         /* if mtl array, array size */
        miTag           light_obj_ring;         /* SCENE: obj-light links */
        miTag           userdata;               /* optional user data blocks */
        miUint          label;                  /* optional label */
        miTag           geogroup;               /* SCENE: geomshader group */

        miCBoolean      off;                    /* hide, ignore this instance */
        miUint1         gen_motion;             /* motion information */

        miUint1         visible;                /* visible ? */
        miUint1         shadow;                 /* casts/receives shadow? */

        miUint1         reflection;             /* casts/receives reflections? */
        miUint1         refraction;             /* casts/receives refractions? */
        miUint1         transparency;           /* casts/receives transparency? */
        miUint1         caustic;                /* caustic bitmap */
        miUint1         globillum;              /* globillum bitmap */
        miUint1         finalgather;            /* finalgather bitmap */

        char            face;                   /* a=all, f=front, b=back */
        miCBoolean      temp_material;          /* SCENE: has inherited mtl */

        miUint1         spare;                  /* not used */
        miCBoolean      mtl_override;           /* inst mtl overrides obj mtl*/
        miUshort        history_size;           /* leaf inst: # of hist tags */

        miTag           approx_list;            /* 10 inherited miApprox's: */
                                                /* v,t,s,c,g, displ v,t,s,c,g*/
        miCBoolean      approx_override;        /* inst approx overr. obj app*/
        miUint1         spare2;                        /* not used */
        miUint1         shadowmap;              /* casts shadowmap shadows? */
        miCBoolean      exclusive;              /* light list is exclusive*/

        miTag           light_list;             /* list of instance light tags */

        miUint1         finalgather_force;      /* FG force mode on? */
        miUint1         spare3;                        /* not used */
        miCBoolean      builtin;                /* internally generated, do not echo */
        miCBoolean      shadow_excl;            /* shadow list is exclusive */

        miTag           shadow_list;            /* list of shadow light tags */
        miScalar        shading_samples;        /* rasterizer: tesselation */
        miScalar        sample_limits[2];       /* unified sampling limits */
        miTag           time_motion_transform;  /* extended motion transformation */
        miTag           attributes;             /* attributes (SCENE::Options) */
        miTag           param_decl;             /* parameter declaration */
        int             param_size;             /* parameter size in bytes */
        char            param[8];               /* arbitrary-sized parameters*/
} miInstance;

A translator must provide: either tf.function and time, or global_to_local and local_to_global; also item (using mi_scene_link), param_decl, param_size, and param.

All fields except the matrices, the material, and the parameters are reserved for Scene and may not be modified by other modules. The tags can be modified indirectly with the link and unlink functions, which take care of reference counts. The instance element has two variable parts; one for inherited shader parameters and one for the relation list. The latter is maintained internally by mental ray.

tf.function

optionally points to a transformation function that computes a matrix from the current time. If present, this function is called during preprocessing with three parameters: a pointer to the result global-to-local matrix, the instance tag, and the time as given in the preprocessing control structure.

tf.time

is the time the evaluation function, if present, was last called with. If it matches the current time, the matrices need not be calculated by calling the function again.

tf.global_to_local

transforms the parent space to the local space of the instanced subtree. If a transformation functions exists, it writes its result here; if not, the translator must store an appropriate matrix here.

tf.local_to_global

is the inverse matrix, set by Scene after the transformation function (if it exists) has returned the tf.global_to_local matrix.

tf.identity

is miTRUE if the transformation matrices in this instance are identity transforms (this saves the renderer unnecessary ray transformations).

tf.id

is a unique transformation ID. Scene creates it during preprocessing, trying to assign identical IDs to identical transformations. This is especially important for leaf instances: the renderer does not have to re-transform the current ray if the new box has the same transformation (same ID) as the previous.

motion_transform

specifies the transformation from parent space to local space for motion blur transforms. If this is a null matrix, the instance transformation tf is used.

item

is the tag of the element being instanced. Only groups, cameras, lights, objects, or functions can be referenced. If a function (or function list) is supplied, mental ray will call them during scene preprocessing as geometry shader. They must return a single object tag, which may (and often should) be a placeholder object.

material

is either a material (if mtl_array_size is 0) or a material list (if mtl_array_size is nonzero) used for material inheritance (as opposed to parameter inheritance). During scene preprocessing, the non-null material tag closest to a geometrical object (lowest in the DAG hierarchy) becomes the default material for any polygon or surface in the object that does not have its own non-null material tag. If the tag references a list (type miSCENE_TAG) or materials, it is expected to contain mtl_array_size tags, which will be indexed with the polygon or surface label during rendering. (The mtl_override flag modifies the inheritance rules, see below.)

mtl_array_size

specifies the number of tags in the material tag list if nonzero. If the material tag specifies a material directly, it must be zero. This number is used during rendering as a flag that tells mental ray that the material tag references a list, and also how many items there are in the list to prevent array bounds overflows.

boxes

is used by mental ray internally to store tessellation results in leaf instances created during preprocessing.

next prev

are used by mental ray internally to chain leaf instances created during preprocessing.

light_obj_ring

is used internally by mental ray to keep track of geometric area light sources.

userdata

allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders can retrieve the data with mi_query.

label

stores an opaque integer set by the scene file with a tag statement.

geogroup

is used internally to point to the group element which contains all the geometry-shader created scene elements for this instance.

off

if true, stops the recursive descent during preprocessing as if the instance and its instanced item didn't exist. This is useful for temporarily suspending subtrees without deleting them. It implements the hide flag in the .mi scene language.

gen_motion

specifies that motion blur should be generated for the instance. Setting this field to miGM_OFF switches off motion blur for this instance. Motion blur is always generated when this field is set to miGM_TRANSFORM. The parent instance determines whether motion blur is active or not when gen_motion is set to miGM_INHERIT here.

visible shadow transparency reflection refraction finalgather caustic globillum

instance flags or modes to control rendering properties. A simple flag is a boolean value to switch a single property (visible). Most of the flags provide control of sub-properties like cast and receive, which is encoded in a mode bitmap. See below for details on the individual flags.

Note, that "cast this effect" typically means to "be visible to this type of ray", and "receive this effect" means "cast this type of ray".

The flags are inherited down the scene DAG in such a way that flags in lower DAG instances take precedence. During scene pre-processing, any non-null flag in the DAG instance closest to a geometrical object (lowest in the DAG hierarchy) is put into the leaf instance. Before rendering starts the leaf instance flags are merged with the object flags to define the final properties; and they are stored in internal raylib rendering data structures. Note, that for all the flags the value 0 means "nothing set" or "no override", which is the default.

visible

Simple flag to control primary visibility. In the merging operation of the instance with object flags, the boolean flag is treated as a "tri-state boolean", hence represented as an integer (with only 2 lowest bits recognized) with the values:

value	meaning
`0`	not set (but use inherited value)
`1`	disable
`2`	enable

In other words, 0 means that just the object flag is taken, 2 enables the property even if the object has disabled it, and 1 disables it even if the object has the flag set.

shadow reflection refraction transparency

These flags are mode bitmaps which control cast and receive properties of the rendering effect separately. The lowest 4 bits of the integer field are recognized as follows:

bit	meaning
`0`	enables casting (from this object)
`1`	enables receiving (from other objects)
`2`	disables casting
`3`	disables receiving

If no bit is set then this instance does not enforce any changes of flags on the object. Typical values are:

value	force
`1`	cast
`2`	receive
`3`	all (cast and receive)
`4`	no cast
`6`	receive-only (no cast but receive)
`8`	no receive
`9`	cast-only (no receive but cast)
`12`	none (no cast nor receive)

finalgather caustic globillum

Similar to above, but these effects support two more bits that are recognized as follows:

bit	meaning
`0`	enables casting (from this object)
`1`	enables receiving (from other objects)
`2`	disables casting
`3`	disables receiving
`4`	hide object from effect
`5`	make visible to effect

The extra bits allow to completely hide objects from final gathering or photon tracing without touching the other bits; they have higher priority and will be checked first by mental ray. In other words, the lower bits only take effect if the higher bits are enabling and not disabling the object at all. Bit masking operations can be used to set these higher bits only, like:

inst→finalgather |= hide ? 0x10 : 0x20;

This implements the on|off syntax in the .mi scene language for these flags.

The reflection, refraction, and finalgather flags replace the former trace flag. Code that used to write to the trace field must now write to these three flag bitmaps instead.

face

controls face culling. The possible values are 'f' (front), 'b' (back), and 'a' (all). If not specified, the culling flag given in the options or in the state is used.

temp_material

is an internal flag that tells SCENE post-processing that the material field contains a material that was created during preprocessing, and must be deleted on post-processing. This happens if the inheritance function sets one or more of the material fields in its material argument, to implement CATIA aspect inheritance.

mtl_override

changes the inheritance rules for the material or material list stored in this instance. If true, and materials exist, this instance will override materials in instances lower in the DAG and in the object, instead of allowing lower materials to override higher ones. This is useful for implementing highlighting selections.

history_size

is set in leaf instances, so that the inheritance function or traversal function can use the miLEAFHISTORY macro to access the inheritance history, beginning at the scene root group (0), followed by the instance in the root group that led to the current location in the DAG (1), all the way to the current instance (history_size - 1). The macro accepts one integer argument (0 for root group etc.) and returns a tag. For example, this is useful in inheritance functions for comparisons to a selection list and then setting a highlight material and mtl_override on a match.

approx_list

implements flagged approximation inheritance. If nonzero, it is a tag of an element of type miSCENE_APPROX_LIST holding up to 10 approximations, in the order visible, trace, shadow, caustic, globillum, displace visible, displace trace, displace shadow, displace caustic, and displace globillum. Approximations with multiple flags are stored in multiple slots. Unused slots have style miAPPROX_STYLE_NONE (see miApprox below).

approx_override

, if set, causes instances higher in the scene graph (closer to the root group) to override lower instances and object approximations.

shadowmap

specifies that the object casts shadows into shadowmaps, if the shadow flag is enabled as well.

param_decl

points to a parameter declaration that describes the parameters. If parameters exist, this tag must be set by the translator to allow data exchange with other hosts. If it is missing, no data will be swapped regardless of the remote host's byte order. In leaf instances, Scene stores the most recent parent instance's parameter declaration tag here.

param_size

is the size of the parameters in bytes. It is taken from the first and only argument of the create and resize calls. In the leaf instance, the inheritance function determines the size.

param

is an arbitrary-sized array of parameters stored by the translator. During preprocessing, the DAG is traversed, and the parameters are passed to an inheritance function that is called for every instance found during traversal. The end result is stored in the leaf instance by Scene.