mi::neuraylib::IAttribute_set Class Reference

The attribute set comprises all attributes attached to a database element. More...

#include <iattribute_set.h>

Inheritance diagram for mi::neuraylib::IAttribute_set:

Public Member Functions
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< 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< 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

The attribute set comprises all attributes attached to a database element.

Attributes are pieces of information that can be attached to any database element. Basically, an attribute set is a map from attribute names (strings) to attribute values (instances of mi::IData).

Attributes can be inherited in the scene graph. For details, see mi::neuraylib::Propagation_type.

Note

Setting an attribute value is done by value (or deep copy) and not by reference. This is relevant for types that usually follow reference semantics, for example, arrays or structures. Note that references to other DB elements (see mi::IRef) are still stored as reference.

See also

The mi::neuraylib::IOptions class has many attributes controlling global settings.

Attributes

• bool disable
  If set to true, the element is ignored. If the element references sub-elements in the scene graph, like instances or groups do, these references will be ignored as well. (Of course, there may be other references of non-disabled elements that can make shared sub-elements in their context visible.) This attribute is not supported for decals.
  
  This attribute, once set to true, cannot be reset to false by elements lower in the scene graph. This can be used to efficiently turn off objects, lights and groups by disabling their referencing instance element; it would be much more expensive to detach or attach them to the scene graph because that requires preprocessing the scene again.
• bool visible
  The object or light is visible to primary rays. This attribute is not supported for decals or volumes.
• bool picking_disabled
  The object, light, or volume is invisible to pick rays. This attribute does not have an effect on generated images and merely affects the behavior of mi::neuraylib::IRender_context::pick().
• bool matte
  The object or light is treated as a matte object.
• mi::Float32 matte_shadow_intensity
  Scaling factor to tune the artificial shadow cast on matte objects. The default is 1.0.
• bool matte_connect_to_environment
  Only effective if the backplate function or backplate color is set. Matte objects will then use the environment instead of the backplate for secondary interactions.
• bool matte_connect_from_camera
  Only effective if no backplate function and no backplate color is set, or if a backplate function or backplate color is set and in addition the matte_connect_to_environment flag. Matte objects will then use a local lookup into the real world photograph instead of a global one.
• bool backplate_mesh
  Only effective if the backplate function or backplate color is set. The object is then treated as a 3D-environment/backplate.
• mi::IRef backplate_mesh_function
  Reference to a texturing function (mi::neuraylib::IFunction_call) that may be used to override the main camera backplate for a backplate mesh
• bool movable
  The object may be subject to frequent transformation changes. Render modes might take that hint into account and use special data structures to speed up such transformation changes. This also controls instancing in user mode. See the "instancing-general" section for details.
• bool reflection_cast
  The object is visible as a reflection in reflective objects.
• bool reflection_recv
  The object is reflective.
• bool refraction_cast
  The object is visible through refractive objects.
• bool refraction_recv
  The object is refractive.
• bool shadow_cast
  The object casts shadows.
• bool shadow_recv
  The object can have shadows cast onto it.
• mi::Sint32 label
  An object ID that is useful in conjunction with render target canvases of type mi::neuraylib::TYPE_OBJECT_ID. See mi::neuraylib::IRender_target_base for details.
• mi::Sint32 material_id
  A material ID that is useful in conjunction with render target canvases of type mi::neuraylib::TYPE_MATERIAL_ID. See mi::neuraylib::IRender_target_base for details.
• const char* handle
  An object or light ID that is useful in conjunction with Light Path Expressions. See Section "Light path expressions" of the Iray Programmer's Manual for details.
• bool shadow_terminator_offset
  Controls the automatic shadow terminator handling. See the "Tessellating curved surfaces" section for details.
• mi::Sint8 volume_priority
  A priority value that drives the decision which object's volumetric material properties take precedence in case of overlap. The default is 0, vacuum corresponds to -128.

The following attribute is only meaningful for instances of mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, mi::neuraylib::IFreeform_surface, mi::neuraylib::IOn_demand_mesh, mi::neuraylib::ILight, mi::neuraylib::IDecal, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• mi::IRef material or mi::IArray material
  A reference to a material instance, or an array of such references.

For decals, the array is limited to length 1.

The following attribute is only meaningful for instances of mi::neuraylib::ILight, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• bool important
  A light flagged with this attribute will be given preference before other lights in the case that a render mode does not handle all lights.

The following attribute is only meaningful for instances of mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, and mi::neuraylib::IFreeform_surface, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• struct Approx approx
  This attribute controls the refinement of triangle and polygon meshes with displacement, and the subdivision level of subdivision surfaces and freeform surfaces. The attribute is a struct and has the members described below. A corresponding structure declaration is registered under the type name Approx.
  • mi::Float32 const_u
    Stores the constant c or c_u for parametric or distance ratio approximation, or the length bound for length or UV length approximation.
  • mi::Float32 const_v
    Stores the constant c_v for parametric approximation.
  • mi::Sint8 method
    Five methods are available, parametric approximation (0), length approximation (1), UV length approximation (2), distance ratio approximation (3), and adaptive displacement approximation (4).
    Parametric approximation is available for triangle and polygon meshes with displacement, subdivision and freeform surfaces. For the first three object types it subdivides each primitive (triangle or quadrangle) into 4^c primitives for some parameter c (polygons are tessellated first). For freeform surfaces, assume that each surface patch has degrees deg_u and deg_v. Each surface patch is subdivided into deg_u * c_u times deg_v * c_v triangle pairs.
    Length approximation is available for triangle and polygon meshes with displacement, and for freeform surfaces, but not for subdivision surfaces. It subdivides the primitives until all edges have a length (in object space) below a specified bound.
    UV length approximation is available for triangle and polygon meshes with displacement. It subdivides the primitives until all edges have a length (in UV space) below a specified bound.
    Distance ratio approximation is available only for freeform surfaces. The parameter c is an upper bound for the ratio of the distance of the approximation to the original curve/surface and the length of the corresponding edge in the approximation. For example, a value of 0.01 means that the error is at most 1/100 of the edge length in the approximation. Typical values of the approximation constant for the distance ratio method are in the range [0.01,0.1].
    Adaptive displacement approximation is applicable on triangle and polygon meshes with displacement, subdivision and freeform surfaces and comprises two passes. The first pass is driven by the base_method parameter and specifies the initial subdivision. The second pass then adaptively refines the initial subdivision based on displacement values and is driven by the quality parameter. For subdivision and freeform surfaces the base_method defines the surface triangulation. Note that adaptive tessellation is currently not supported for meshes with more than one material region.
    The length bound as well as the parameter c are stored in the field const_u. The The parameters c_u and c_v are stored in the fields const_u and const_v, respectively.
  • mi::Sint8 base_method
    Specifies the initial approximation for the adaptive displacement approximation. Supported methods for triangle and polygon meshes are parametric (0), length (1) and UV length (2). For subdivision surfaces only parametric (0) is supported, for freeform surfaces one can use parametric (0), length (1) and distance ratio (3). For the controls, see method.
  • mi::Float32 quality
    Specifies the quality of the second pass of the adaptive displacement approximation. With higher quality, more displacement samples are taken and potentially more triangles are created. The default range is from zero (no additional triangles in second pass) to one (up to 32 subdivisions). Higher values are possible and may create more subdivisions.

The following attributes are only meaningful for instances of mi::neuraylib::ITriangle_mesh, and mi::neuraylib::IPolygon_mesh, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• mi::Sint32 approx_triangle_limit
  Specifies an upper bound for the number of triangles generated by a displacement approximation. By default, the limit is set to 10M triangles.
• mi::Float32 approx_geometry_from_shading_normals
  Specifies a factor by which vertices are offset according to their corresponding shading normal in order to make the tessellated mesh more smooth. Valid values are in the range [0.0,1.0]. By default the value is zero which means no offset.
• mi::Sint32 enable_tessellation_of_undisplaced_meshes
  If enabled, tessellation is being performed also in the case that there is no displacement function defined for the given mesh, which can be useful sometimes for meshes with a low triangle count, especially in conjunction with the attribute approx_geometry_from_shading_normals.

The following attribute is only meaningful for instances of mi::neuraylib::IFreeform_surface, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• struct Approx approx_curve
  This attribute controls the subdivision level of curve segments of freeform surfaces. The attribute is a struct and has the same structure as the "approx" attribute (see above). Note that there is only one attribute for all curve segments together.

The following attributes are only meaningful for instances of mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, mi::neuraylib::IFreeform_surface, mi::neuraylib::IOn_demand_mesh, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• mi::IArray decals
  An array of references (mi::IRef) that attaches the given decals or instances of decals to the scene element. This is similar to the material attribute, however, note that in contrast to the material attribute the scene element with the decals attribute influences the world-to-object transformation of the decal. This attribute is inherited as usual with the exception that when a parent node P and a child node C both have the decals attribute the rules detailed in mi::neuraylib::Propagation_type do not apply. Instead, the array elements of the decals attribute in P are appended to the array elements from C.
• mi::IArray enabled_decals
  An array of references (mi::IRef) that acts as filter to determine the active decals. Only decals in that array can be active. Defaults to the (inherited) value of the decals attribute.
• mi::IArray disabled_decals
  An array of references (mi::IRef) that acts as filter to determine the active decals. Decals in that array are never active. Defaults to the empty array.

The list of active decals at a geometry node is given by the intersection of decals and enabled_decals minus disabled_decals (taking attribute inheritance into account).

The element order in the decals attribute is used to break ties between decals of equal priority: if decal D1 is in front of decal D2 and both have equal priorities, decal D1 will appear on top of decal D2 (assuming both are overlapping, otherwise it is not relevant anyway).

The following attributes are only meaningful for instances of mi::neuraylib::ITriangle_mesh, mi::neuraylib::IPolygon_mesh, mi::neuraylib::ISubdivision_surface, mi::neuraylib::IFreeform_surface, mi::neuraylib::IOn_demand_mesh, and via inheritance for instances of mi::neuraylib::IGroup and mi::neuraylib::IInstance.

• mi::IArray projectors
  An array of references (mi::IRef) that attaches the given projectors or instances of projectors to the scene element. This is similar to the material attribute, however, note that in contrast to the material attribute the scene element with the projectors attribute influences the world-to-object transformation of the projector. This attribute is inherited as usual with the exception that the propagation type mi::neuraylib::PROPAGATION_OVERRIDE is not supported.
• mi::IRef active_projector
  Specifies the active projector. Defaults to the (inherited) first element of the projector attribute. This attribute allows to specify a projector different from the inherited default, or to disable the inherited default. Only projectors that appear in projectors attributes on the path from this node to the root are feasible.

See also

The free functions mi::set_value() and mi::get_value() including the various specializations may help to write/read values to/from attributes. Note that there are variants operating on attributes sets as well as directly on instances of mi::IData.

Example

The following code snippet is an example that shows how to copy all attributes from one attribute set to a different one. Three boolean flags allow to customize its behavior. Note that the function stops as soon as the assignment fails for one attribute (which might happen if adjust_attribute_types is false and the types are incompatible).

mi::Sint32 copy_attribute(
    mi::neuraylib::IFactory* factory,
    const mi::neuraylib::IAttribute_set* source,
    mi::neuraylib::IAttribute_set* target,
    bool create_missing_attributes,
    bool remove_excess_attributes,
    bool adjust_attribute_types)
{
    if( !factory || !source || !target)
        return -1;
 
     mi::Sint32 index = 0;
     const char* name;
     while( name = source->enumerate_attributes( index++)) {
 
         mi::base::Handle<const mi::IData> source_attr(
             source->access_attribute<mi::IData>( name));
         std::string source_type = source_attr->get_type_name();
 
         mi::base::Handle<mi::IData> target_attr;
         if( !target->is_attribute( name)) {
            if( !create_missing_attributes)
                continue; // skip attribute
            else
                target_attr = target->create_attribute<mi::IData>( name, source_type.c_str());
        } else {
            if( adjust_attribute_types
                && source_type != target->get_attribute_type_name( name)) {
                target->destroy_attribute( name);
                target_attr = target->create_attribute<mi::IData>( name, source_type.c_str());
            } else
                target_attr = target->edit_attribute<mi::IData>( name);
        }
 
        mi::Sint32 result = factory->assign_from_to( source_attr.get(), target_attr.get());
        if( result != 0)
            return -2;
     }
 
     if( !remove_excess_attributes)
         return 0;
 
     index = 0;
     std::vector<std::string> to_be_removed;
     while( name = target->enumerate_attributes( index++))
         if( !source->is_attribute( name))
             to_be_removed.push_back( name);
     for( mi::Size i = 0; i < to_be_removed.size(); ++i)
         target->destroy_attribute( to_be_removed[i].c_str());
 
     return 0;
}

Member Function Documentation

access_attribute() [1/2]

template<class T>

const T * mi::neuraylib::IAttribute_set::access_attribute ( const char *  name ) const

inline

Returns a const pointer to the attribute name.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the attribute.

Parameters

name	The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name or if T does not match the attribute's type.

access_attribute() [2/2]

virtual const IData * mi::neuraylib::IAttribute_set::access_attribute ( const char *  name ) const

pure virtual

Returns a const pointer to the attribute name.

Parameters

name	The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name.

create_attribute() [1/3]

template<class T>

T * mi::neuraylib::IAttribute_set::create_attribute ( const char *  name )

inline

Creates a new attribute name of the type T.

See Types for a list of supported attribute types.

Note that there are two versions of this templated member function, one that takes only one argument (the attribute name), and another one that takes two arguments (the attribute name and the type name). The version with one argument can only be used to create a subset of supported attribute types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays and structures. The version with two arguments can be used to create attributes of any supported type (but requires the type name as parameter, which is redundant for many types). Attempts to use the version with one argument with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the attribute.

Parameters

name	The name of the attribute. The name must not contain "[", "]", or "."

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

• name or type is invalid,
• there is already an attribute with the name name, or
• name is the name of a reserved attribute and T does not match the required type(s) of such an attribute.

create_attribute() [2/3]

template<class T>

T * mi::neuraylib::IAttribute_set::create_attribute ( const char *  name, const char *  type  )

inline

Creates a new attribute name of the type type.

See Types for a list of supported attribute types.

Note that there are two versions of this templated member function, one that takes only one argument (the attribute name), and another one that takes two arguments (the attribute name and the type name). The version with one argument can only be used to create a subset of supported attribute types: it supports only those types where the type name can be deduced from the template parameter, i.e., it does not support arrays and structures. The version with two arguments can be used to create attributes of any supported type (but requires the type name as parameter, which for redundant for many types). Attempts to use the version with one argument with a template parameter where the type name can not be deduced results in compiler errors.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the attribute.

Parameters

name	The name of the attribute. The name must not contain "[", "]", or "."
type	The type of the attribute. See Types for a list of supported attribute types.

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

• name or type is invalid,
• there is already an attribute with the name name,
• name is the name of a reserved attribute and type does not match the required type(s) of such an attribute, or
• T does not match type.

create_attribute() [3/3]

virtual IData * mi::neuraylib::IAttribute_set::create_attribute ( const char *  name, const char *  type  )

pure virtual

Creates a new attribute name of the type type.

Parameters

name	The name of the attribute. The name must not contain "[", "]", or "."
type	The type of the attribute. See Types for a list of supported attribute types.

Returns

A pointer to the created attribute, or NULL in case of failure. Reasons for failure are:

• name or type is invalid,
• there is already an attribute with the name name, or
• name is the name of a reserved attribute and type does not match the required type(s) of such an attribute.

destroy_attribute()

virtual bool mi::neuraylib::IAttribute_set::destroy_attribute ( const char *  name )

pure virtual

Destroys the attribute name.

Parameters

name	The name of the attribute to destroy.

Returns

Returns true if the attribute has been successfully destroyed, and false otherwise (there is no attribute with the name name).

edit_attribute() [1/2]

template<class T>

T * mi::neuraylib::IAttribute_set::edit_attribute ( const char *  name )

inline

Returns a mutable pointer to the attribute name.

This templated member function is a wrapper of the non-template variant for the user's convenience. It eliminates the need to call mi::base::IInterface::get_interface(const Uuid &) on the returned pointer, since the return type already is a pointer to the type T specified as template parameter.

Template Parameters

T	The interface type of the attribute.

Parameters

name	The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name or if T does not match the attribute's type.

edit_attribute() [2/2]

virtual IData * mi::neuraylib::IAttribute_set::edit_attribute ( const char *  name )

pure virtual

Returns a mutable pointer to the attribute name.

Parameters

name	The name of the attribute. In addition, you can also access parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

A pointer to the attribute, or NULL if there is no attribute with the name name.

enumerate_attributes()

virtual const char * mi::neuraylib::IAttribute_set::enumerate_attributes ( Sint32  index ) const

pure virtual

Returns the name of the attribute indicated by index.

Parameters

index

The index of the attribute.

Returns

The name of the attribute indicated by index, or NULL if index is out of bounds.

get_attribute_propagation()

virtual Propagation_type mi::neuraylib::IAttribute_set::get_attribute_propagation ( const char *  name ) const

pure virtual

Returns the propagation type of the attribute name.

Note

This method always returns PROPAGATION_STANDARD in case of errors.

get_attribute_type_name()

virtual const char * mi::neuraylib::IAttribute_set::get_attribute_type_name ( const char *  name ) const

pure virtual

Returns the type of an attribute.

See Types for a list of supported attribute types.

Parameters

name	The name of the attribute. In addition, you can also query parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

The type name of the attribute (or part thereof), or NULL if there is no attribute with the name name.

Note

The return value of this method is only valid until the next call of this method or any non-const methods on this instance.

is_attribute()

virtual bool mi::neuraylib::IAttribute_set::is_attribute ( const char *  name ) const

pure virtual

Indicates existence of an attribute.

Parameters

name	The name of the attribute. In addition, you can also checks for parts of array or structure attributes directly. For an array element add the index in square brackets to the attribute name. For a structure member add a dot and the name of the structure member to the attribute name.

Returns

true if the attribute set contains this attribute (and the attribute contains the requested array element or struct member), false otherwise

set_attribute_propagation()

virtual Sint32 mi::neuraylib::IAttribute_set::set_attribute_propagation ( const char *  name, Propagation_type  value  )

pure virtual

Sets the propagation type of the attribute name.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer or invalid enum value).
• -2: There is no attribute with name name.