Instances

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;                    /* 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         select;                 /* selectable when picking? */
        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         hardware;               /* render inst. with hardware */
        miUint1         shadowmap;              /* casts shadowmap shadows? */
        char            spare;                  /* not used */
        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 retransform 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 and prev are used by mental ray internally to chain leaf instances created during preprocessing.

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

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 grammar.

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.

The visible, shadow, caustic, globillum, and select flags are inherited in the scene DAG. During scene preprocessing, the 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 and stored in internal raylib rendering data structures. In the merging operation these flags are treated as "fuzzy booleans", that is, a zero value means that the flag is ignored (the object flag is taken), 1 disables the flag (even if the object has enabled it) and 2 enables it (even if the object has not set the flag). The caustic bitmap has the same bit interpretation as the corresponding field in the miObject, but has three more bits defined here. Bit 2, if set, disables generation of caustics cast by this object. Bit 3, if set, disables receiving caustics. Bit 5, if set, enables photons to intersect with this object. In the merging, bit 0 and bit 1 of the leaf instance and object caustic bitmaps are logically combined with an OR operation followed by AND of the instance caustic bitmap bits 2 and 3, inverted and shifted right two times. Also in the merging, bit 4 of the leaf instance and object caustic bitmaps are logically ORed followed by an AND with bit 5 of the instance caustic bitmap inverted and shifted right one position. The globillum bitmap is similar to the caustic bitmap.

shadow flag is a bitmap that controls casting and receiving of shadows separately. Bit 0 enables shadows cast from this surface, and bit 1 allow shadows to be received by (fall onto) this object. By default, bit 0 is 0 and bit 1 is 1 ( mode 2).

reflection, refraction, and finalgather^3.4\ flags replace the trace flag. Code that writes to the trace field must now write to these three flag bitmaps instead. Again, bit 0 enables casting and bit 1 enables receiving, and the defaults are 0 and 1, respectively ( mode 2).

transparency^3.4 flag that enables visibility of the surface to transparency rays, again separately for casting (bit 0) and receiving (bit 1). Unlike the other flags, both bits are on (mode 3) by default to ensure backwards compatibility.

finalgather controls the final gathering mode: 1 enables final gather illumination casting, 2 enables final gather illumination receiving, 3 enables both, and 0 neither. Default is mode 0. off means that the object is invisible to final gather rays, and on (the default) enables final gathering illumination interactions with this object.

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 postprocessing that the material field contains a material that was created during preprocessing, and must be deleted on postprocessing. 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^3.1 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.

hardware specifies that the subtree must be rendered using OpenGL hardware.

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.

Copyright © 1986-2007 by mental images GmbH