NVIDIA Iray SDK API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IInstance Class Referenceabstract

An instance is a scene element that adds a transformation and attributes to another scene element. More...

Inheritance diagram for mi::neuraylib::IInstance:
mi::base::Interface_declare< 0x11b46e5a, 0x577b, 0x4767, 0x8b, 0x35, 0x88, 0xd5, 0xa3, 0x3e, 0xd0, 0xe9, neuraylib::IScene_element > mi::neuraylib::IScene_element mi::base::Interface_declare< 0x8a2a4da9, 0xe323, 0x452c, 0xb8, 0xda, 0x92, 0x45, 0x67, 0x85, 0xd7, 0x78, neuraylib::IAttribute_set > mi::neuraylib::IAttribute_set mi::base::Interface_declare< 0x1bcb8d48, 0x10c1, 0x4b3e, 0x9b, 0xfa, 0x06, 0x23, 0x61, 0x81, 0xd3, 0xe1 > mi::base::IInterface

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

Detailed Description

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 time-dependent transformation is represented by a two-dimensional array of elementary transformations. An elementary transformation is either a translation, rotation, or scaling (*). One dimension of the two-dimensional 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 i-th 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.

  • For translations, call m.set_translate(a,b,c).
  • For scalings, set m.xx, m.yy, and m.zz to a, b, and c respectively.
  • For rotations, call 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).

See Also
mi::neuraylib::IOptions::get_shutter_open(), mi::neuraylib::IOptions::get_shutter_close(), 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.

// The two translation vectors
mi::Float64_3 t0( 1.0, 2.0, 3.0);
mi::Float64_3 t1( 4.0, 5.0, 6.0);
transaction->create<mi::neuraylib::IInstance>( "Instance"));
// Set up the time slots
instance->resize_time_slots( 2);
instance->set_time_value( 0, 0.0);
instance->set_time_value( 1, 1.0);
// Set up the transformation types
instance->resize_transformation_sequences( 1);
instance->set_transformation_type( 0, mi::neuraylib::TRANSLATION);
// Set up the actual transformation data
instance->set_transformation_data( 0, 0, &t0.x);
instance->set_transformation_data( 1, 0, &t1.x);
// For example, instance->evaluate( 0.5) now returns a transformation matrix that describes a
// translation by (2.5,3.5,4.5) (the midpoint of (1,2,3) and (4,5,6)).

Member Function Documentation

virtual Sint32 mi::neuraylib::IInstance::attach ( const char *  scene_element)
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:

Parameters
scene_elementThe element to attach.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: There is no element with that name.
  • -3: The element can not be attached to the instance because it is in a more private scope than the instance.
  • -4: This type of scene element can not be attached to instances.
virtual void mi::neuraylib::IInstance::detach ( )
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.

virtual Float64_4_4_struct mi::neuraylib::IInstance::evaluate ( Float64  time = 0.0) const
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 left-most, the next one is the matrix for index 1, and so on.

virtual const char* mi::neuraylib::IInstance::get_item ( ) const
pure virtual

Returns the name of the referenced element.

Returns
The referenced element, or NULL if no element is referenced.
virtual const Float64_4_4_struct& mi::neuraylib::IInstance::get_matrix ( ) const
pure virtual

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

See Also
Use evaluate() to evaluate the transformation independent of the transformation mode.
virtual Sint32 mi::neuraylib::IInstance::get_time_value ( Size  time_index,
Float64 value 
) const
pure virtual

Returns the time value associated with a particular time slot.

Parameters
time_indexThe index of the requested time slot.
valueThe current time value.
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: time_index is out of bounds.
virtual Sint32 mi::neuraylib::IInstance::get_transformation_data ( Size  time_index,
Size  sequence_index,
Float64 data 
) const
pure virtual

Returns the transformation data of an elementary transformation for a given time slot and sequence index.

Parameters
time_indexThe index of the requested time slot.
sequence_indexThe index of the requested elementary transformation.
dataA 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.
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: time_index or sequence_index is out of bounds.
  • -3: Invalid parameters (NULL pointer).
virtual Sint32 mi::neuraylib::IInstance::get_transformation_type ( Size  sequence_index,
Transformation_type type 
) const
pure virtual

Returns the transformation type of an elementary transformation for a given sequence index.

Parameters
sequence_indexThe index of the requested elementary transformation.
typeThe current type of elementary transformation.
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: sequence_index is out of bounds.
virtual void mi::neuraylib::IInstance::resize_time_slots ( Size  count)
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).

virtual void mi::neuraylib::IInstance::resize_transformation_sequences ( Size  count)
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.

virtual void mi::neuraylib::IInstance::set_matrix ( const Float64_4_4_struct matrix)
pure virtual

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

virtual Sint32 mi::neuraylib::IInstance::set_time_value ( Size  time_index,
Float64  value 
)
pure virtual

Sets the time value associated with a particular time slot.

See Also
mi::neuraylib::IOptions::get_shutter_open(), mi::neuraylib::IOptions::get_shutter_close()
Parameters
time_indexThe index of the time slot to update.
valueThe 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).
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: time_index is out of bounds.
  • -3: The new value is not within the open interval of times defined by the previous and next time index.
virtual Sint32 mi::neuraylib::IInstance::set_transformation_data ( Size  time_index,
Size  sequence_index,
const Float64 data 
)
pure virtual

Sets the transformation data of an elementary transformation for a given time slot and sequence index.

Parameters
time_indexThe index of the time slot to update.
sequence_indexThe index of the elementary transformation to update.
dataA 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.
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: time_index or sequence_index is out of bounds.
  • -3: Invalid parameters (NULL pointer).
virtual Sint32 mi::neuraylib::IInstance::set_transformation_type ( Size  sequence_index,
Transformation_type  type 
)
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.

Parameters
sequence_indexThe index of the elementary transformation to update.
typeThe new type of elementary transformation.
Returns
  • 0: Success.
  • -1: The transformation mode is not SRT mode.
  • -2: sequence_index is out of bounds.
virtual bool mi::neuraylib::IInstance::srt_mode ( ) const
pure virtual

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

virtual Size mi::neuraylib::IInstance::time_slots_size ( ) const
pure virtual

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

virtual Size mi::neuraylib::IInstance::transformation_sequences_size ( ) const
pure virtual

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