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; /* 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 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
select
- instance flags or modes to control rendering properties. A
simple flag is a boolean value to switch a single property
(visible, select). 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
select
- Simple flag to control primary visibility and selectability. 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 |
enable |
2 |
disable |
In other words, 0
means that just the object flag is
taken, 1
enables the property even if the object has
disabled it, and 2
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 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 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-2010 by
mental images GmbH