An instance is a scene element that adds a transformation and attributes to another scene element. More...
Public Member Functions  
virtual Sint32  attach (const char *scene_element)=0 
Attaches a scene element to the instance. More...  
virtual void  detach ()=0 
Detaches the scene element from the instance. More...  
virtual const char *  get_item () const =0 
Returns the name of the referenced element. More...  
Methods to query the transformation mode  
virtual bool  srt_mode () const =0 
Indicates whether the transformation mode is SRT mode or matrix mode. More...  
Methods for matrix mode  
virtual void  set_matrix (const Float64_4_4_struct &matrix)=0 
Stores the given transformation matrix (and switches the transformation mode to matrix mode). More...  
virtual const Float64_4_4_struct &  get_matrix () const =0 
Returns the stored transformation matrix if the transformation mode is matrix mode, and the identity matrix otherwise. More...  
Methods for SRT mode  
virtual void  resize_time_slots (Size count)=0 
Sets the number of time slots to count (and switches the transformation mode to SRT mode). More...  
virtual Size  time_slots_size () const =0 
Returns the number of time slots (or 0 if the transformation mode is in matrix mode). More...  
virtual Sint32  set_time_value (Size time_index, Float64 value)=0 
Sets the time value associated with a particular time slot. More...  
virtual Sint32  get_time_value (Size time_index, Float64 &value) const =0 
Returns the time value associated with a particular time slot. More...  
virtual void  resize_transformation_sequences (Size count)=0 
Sets the number of transformations per time slot to count (and switches the object to SRT mode). More...  
virtual Size  transformation_sequences_size () const =0 
Returns the number of transformations per time slot (or 0 if the object is in matrix mode). More...  
virtual Sint32  set_transformation_type (Size sequence_index, Transformation_type type)=0 
Sets the transformation type of an elementary transformation for a given sequence index. More...  
virtual Sint32  get_transformation_type (Size sequence_index, Transformation_type &type) const =0 
Returns the transformation type of an elementary transformation for a given sequence index. More...  
virtual Sint32  set_transformation_data (Size time_index, Size sequence_index, const Float64 *data)=0 
Sets the transformation data of an elementary transformation for a given time slot and sequence index. More...  
virtual Sint32  get_transformation_data (Size time_index, Size sequence_index, Float64 *data) const =0 
Returns the transformation data of an elementary transformation for a given time slot and sequence index. More...  
Methods for evaluation of the transformation  
virtual Float64_4_4_struct  evaluate (Float64 time=0.0) const =0 
Computes the effective transformation for a given time value. More...  
Additional Inherited Members  
Public Types inherited from mi::base::Interface_declare< 0x11b46e5a, 0x577b, 0x4767, 0x8b, 0x35, 0x88, 0xd5, 0xa3, 0x3e, 0xd0, 0xe9, neuraylib::IScene_element >  
typedef Interface_declare< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11, neuraylib::IScene_element >  Self 
Own type. More...  
typedef Uuid_t< id1, id2, id3, id4, id5, id6, id7, id8, id9, id10, id11 >  IID 
Declares the interface ID (IID) of this interface. More...  
Static Public Member Functions inherited from mi::base::Interface_declare< 0x11b46e5a, 0x577b, 0x4767, 0x8b, 0x35, 0x88, 0xd5, 0xa3, 0x3e, 0xd0, 0xe9, neuraylib::IScene_element >  
static bool  compare_iid (const Uuid &iid) 
Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...  
An instance is a scene element that adds a transformation and attributes to another scene element.
Every instance references exactly one scene element (it is also possible not to reference a scene element at all but such instances are useless).
Instances can be used to share the geometry of multiple identical objects. For example, one could have only one scene element of type mi::neuraylib::ITriangle_mesh or mi::neuraylib::IPolygon_mesh that contains the actual geometry. Several scene elements of type mi::neuraylib::IInstance with different transformations can then be used to create all the instances of the object. Furthermore, each instance can have different attributes, e.g., the material, the label, approximation settings, or the disable or visible flag.
Note that all transformations in this class describe transformations from world space to object space.
There are two mutually exclusive ways to represent the transformation: the matrix mode and the SRT mode. In matrix mode, the class represents a single 4x4 transformation matrix, which is independent of time. This mode does not support motion blur.
In SRT mode the timedependent transformation is represented by a twodimensional array of elementary transformations. An elementary transformation is either a translation, rotation, or scaling (*). One dimension of the twodimensional array is time. For each time value there is an associated sequence of elementary transformations (the second array dimension). This sequence has the same length for all time values and the ith element in all sequences has the same type of elementary transformation. This mode does support motion blur.
(*) For backward compatibility, a general transformation given by a 4x4 matrix is supported as well (although in general such a matrix does not represent an elementary transformation). Using the matrix type of elementary transformation is not recommended for motion blur, even if the matrix actually encodes a real elementary transformation.
It is possible to compute the effective transformation for a given time value. In matrix mode simply the fixed matrix is returned. For the SRT mode the evaluation is done by linear interpolation of the elementary transformations in the transformation sequences of the corresponding interval boundaries.
The floating point values of an elementary transformations are converted into a matrix as follows: Let a
, b
, c
, and d
denote the floating point values for a particular type of elementary transformation (d
only for rotations) and m
the identity matrix of type mi::neuraylib::Float32_4_4.
m.set_translate(a,b,c)
.m.xx
, m.yy
, and m.zz
to a
, b
, and c
respectively.m.set_rotation(abc,d)
where abc
is a normalized vector constructed from a
, b
, and c
.While there are no restrictions in this interface w.r.t. the used time ranges, other parts of the scene description do not allow the same freedom. For example, motion vectors for geometry can only be specified for the time range [0, 1] (see mi::neuraylib::ATTR_MOTION).
Example: Create a transformation in SRT mode that translates the referenced scene element by (1,2,3) at time t=0 and by (4,5,6) at time t=1.

pure virtual 
Attaches a scene element to the instance.
Any previously attached element is automatically detached.
Only the following types of scene elements can be attached to instances:
scene_element  The element to attach. 
NULL
pointer).

pure virtual 
Detaches the scene element from the instance.
Afterwards, the instance will not reference any element, and will have no effect on rendering. To temporarily disable an instance, also consider the disable
attribute, see mi::neuraylib::IAttribute_set.

pure virtual 
Computes the effective transformation for a given time value.
If the transformation mode is matrix mode, the effective transformation is given by this matrix, independent of time. If the transformation mode is SRT mode, the effective transformation for a given time value is computed by elementwise linear interpolation of the transformation sequences of the corresponding interval boundaries:
First, the corresponding interval of time indices is computed. Next, a sequence of elementary transformations for the given time value is computed by linear interpolation of the two corresponding elementary transformations of the interval boundaries. Finally, the new sequence is folded into a single 4x4 transformation matrix by multiplication of transformation matrices that represent the elementary transformations: The matrix representing the elementary transformation with index 0 is the leftmost, the next one is the matrix for index 1, and so on.

pure virtual 
Returns the name of the referenced element.
NULL
if no element is referenced.

pure virtual 
Returns the stored transformation matrix if the transformation mode is matrix mode, and the identity matrix otherwise.

pure virtual 
Returns the time value associated with a particular time slot.
time_index  The index of the requested time slot. 
value  The current time value. 
time_index
is out of bounds.

pure virtual 
Returns the transformation data of an elementary transformation for a given time slot and sequence index.
time_index  The index of the requested time slot. 
sequence_index  The index of the requested elementary transformation. 
data  A pointer to three (translation and scaling), four (rotation), or 16 (general transformation) elements of type mi::Float64. In case of rotations, the axis is given by the first three elements, and the angle (in radians) by the fourth element. 
time_index
or sequence_index
is out of bounds.NULL
pointer).

pure virtual 
Returns the transformation type of an elementary transformation for a given sequence index.
sequence_index  The index of the requested elementary transformation. 
type  The current type of elementary transformation. 
sequence_index
is out of bounds.

pure virtual 
Sets the number of time slots to count
(and switches the transformation mode to SRT mode).
Each additional time slot is a copy of the previous time slot, or a time slot with identity transformations if there were no time slots before this operation.
No time slots at all is equivalent to the identity transformation (independent of time).

pure virtual 
Sets the number of transformations per time slot to count
(and switches the object to SRT mode).
Additional transformations are set to an identity transformation.
An empty transformation sequence is equivalent to the identity transformation.

pure virtual 
Stores the given transformation matrix (and switches the transformation mode to matrix mode).

pure virtual 
Sets the time value associated with a particular time slot.
time_index  The index of the time slot to update. 
value  The new time value. The time value needs to be larger than the the value in the previous slot (if existing) and smaller than the value in the next slot (if existing). 
time_index
is out of bounds.

pure virtual 
Sets the transformation data of an elementary transformation for a given time slot and sequence index.
time_index  The index of the time slot to update. 
sequence_index  The index of the elementary transformation to update. 
data  A pointer to three (translation and scaling), four (rotation), or 16 (general transformation) elements of type mi::Float64. In case of rotations, the axis is given by the first three elements, and the angle (in radians) by the fourth element. 
time_index
or sequence_index
is out of bounds.NULL
pointer).

pure virtual 
Sets the transformation type of an elementary transformation for a given sequence index.
Transformation types do not have to be unique, several occurrences of the same transformation type in the transformation sequences are feasible. Transformation types do not have to appear in a particular fixed order (but note that the order affects the represented transformation, see evaluate() for details).
This method also changes for all time slots the transformation data associated with this sequence index to values representing the identity for the given transformation type.
sequence_index  The index of the elementary transformation to update. 
type  The new type of elementary transformation. 
sequence_index
is out of bounds.

pure virtual 
Indicates whether the transformation mode is SRT mode or matrix mode.

pure virtual 
Returns the number of time slots (or 0 if the transformation mode is in matrix mode).

pure virtual 
Returns the number of transformations per time slot (or 0 if the object is in matrix mode).