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

#include <iinstance.h>

Inheritance diagram for mi::neuraylib::IInstance:

[legend]

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

Public Member Functions inherited from mi::neuraylib::IScene_element
virtual Element_type	get_element_type () const =0
	Indicates the actual scene element represented by interfaces derived from this interface. More...

Public Member Functions inherited from mi::neuraylib::IAttribute_set
virtual IData *	create_attribute (const char name, const char type)=0
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char name, const char type)
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char *name)
	Creates a new attribute `name` of the type `T`. More...

virtual bool	destroy_attribute (const char *name)=0
	Destroys the attribute `name`. More...

virtual const IData *	access_attribute (const char *name) const =0
	Returns a const pointer to the attribute `name`. More...

template<class T>
const T *	access_attribute (const char *name) const
	Returns a const pointer to the attribute `name`. More...

virtual IData *	edit_attribute (const char *name)=0
	Returns a mutable pointer to the attribute `name`. More...

template<class T>
T *	edit_attribute (const char *name)
	Returns a mutable pointer to the attribute `name`. More...

virtual bool	is_attribute (const char *name) const =0
	Indicates existence of an attribute. More...

virtual const char *	get_attribute_type_name (const char *name) const =0
	Returns the type of an attribute. More...

virtual Sint32	set_attribute_propagation (const char *name, Propagation_type value)=0
	Sets the propagation type of the attribute `name`. More...

virtual Propagation_type	get_attribute_propagation (const char *name) const =0
	Returns the propagation type of the attribute `name`. More...

virtual const char *	enumerate_attributes (Sint32 index) const =0
	Returns the name of the attribute indicated by `index`. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x11b46e5a, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

typedef Uuid_t< id1, ... >	IID
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>	IID
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x11b46e5a, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. 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);
 
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)).

Member Function Documentation

^◆ attach()

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:

structural nodes like mi::neuraylib::IGroup and mi::neuraylib::IInstance,
geometry like mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, mi::neuraylib::IFreeform_surface, and mi::neuraylib::IOn_demand_mesh,
other nodes like mi::neuraylib::ICamera, mi::neuraylib::ILight, mi::neuraylib::ISection_object, and mi::neuraylib::IAttribute_container,
and finally mi::neuraylib::IDecal and mi::neuraylib::IProjector.

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.

^◆ detach()

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.

^◆ evaluate()

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.

^◆ get_item()

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.

^◆ get_matrix()

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.

^◆ get_time_value()

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.

^◆ get_transformation_data()

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

^◆ get_transformation_type()

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.

^◆ resize_time_slots()

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

^◆ resize_transformation_sequences()

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.

^◆ set_matrix()

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

^◆ set_time_value()

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.

^◆ set_transformation_data()

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

^◆ set_transformation_type()

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.

^◆ srt_mode()

virtual bool mi::neuraylib::IInstance::srt_mode ( ) const

pure virtual

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

^◆ time_slots_size()

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

^◆ transformation_sequences_size()

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

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ attach()

◆ detach()

◆ evaluate()

◆ get_item()

◆ get_matrix()

◆ get_time_value()

◆ get_transformation_data()

◆ get_transformation_type()

◆ resize_time_slots()

◆ resize_transformation_sequences()

◆ set_matrix()

◆ set_time_value()

◆ set_transformation_data()

◆ set_transformation_type()

◆ srt_mode()

◆ time_slots_size()

◆ transformation_sequences_size()

^◆ attach()

^◆ detach()

^◆ evaluate()

^◆ get_item()

^◆ get_matrix()

^◆ get_time_value()

^◆ get_transformation_data()

^◆ get_transformation_type()

^◆ resize_time_slots()

^◆ resize_transformation_sequences()

^◆ set_matrix()

^◆ set_time_value()

^◆ set_transformation_data()

^◆ set_transformation_type()

^◆ srt_mode()

^◆ time_slots_size()

^◆ transformation_sequences_size()