neuray API Programmer's Manual

mi::neuraylib::IInstance Class Reference

[Scene graph structure]

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);

 mi::base::Handle< mi::neuraylib::IInstance> instance(
     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)).

mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. Common base interface for all scene elements.Common base interface for all scene elements. mi::base::Interface_declare\< ..., neuraylib::IAttribute_set \>Mixin class template for deriving new interface declarations. The attribute set comprises all attributes attached to a database element.The attribute set comprises all attributes attached to a database element. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

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.

Methods for matrix mode

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...
virtual void set_matrix( const Float64_4_4_struct& matrix) =0
Stores the given transformation matrix (and switches the transformation mode to matrix mode).

Methods for SRT mode

virtual Sint32 get_time_value( Size time_index, Float64& value) const =0
Returns the time value associated with a particular time slot. 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...
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 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 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 Sint32 set_time_value( Size time_index, Float64 value) =0
Sets the time value associated with a particular time slot. 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 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 Size time_slots_size() const =0
Returns the number of time slots (or 0 if the transformation mode is in matrix mode).
virtual Size transformation_sequences_size() const =0
Returns the number of transformations per time slot (or 0 if the object is in matrix mode).

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

Member Functions

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_element
The 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_index
The index of the requested time slot.
value
The 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_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.

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_index
The index of the requested elementary transformation.
type
The 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_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).

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

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_index
The index of the elementary transformation to update.
type
The 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).