Iray SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::IAttribute_set Class Referenceabstract

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 IDatacreate_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 IDataaccess_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 IDataedit_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 IInterfaceget_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 IInterfaceget_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(
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++)) {
source->access_attribute<mi::IData>( name));
std::string source_type = source_attr->get_type_name();
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;
}
This interface is the base interface of all types.
Definition: idata.h:297
Handle class template for interfaces, automatizing the lifetime control via reference counting.
Definition: handle.h:113
The attribute set comprises all attributes attached to a database element.
Definition: iattribute_set.h:373
This API component allows the creation, assignment, and cloning of instances of types.
Definition: ifactory.h:35
virtual Uint32 assign_from_to(const IData *source, IData *target, Uint32 options=0)=0
Assigns the value(s) of source to target.
Interface * get() const
Access to the interface. Returns 0 for an invalid interface.
Definition: handle.h:294
Uint64 Size
Unsigned integral type that is large enough to hold the size of all types.
Definition: types.h:112
signed int Sint32
32-bit signed integer.
Definition: types.h:46

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
TThe interface type of the attribute.
Parameters
nameThe 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
nameThe 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
TThe interface type of the attribute.
Parameters
nameThe 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
TThe interface type of the attribute.
Parameters
nameThe name of the attribute. The name must not contain "[", "]", or "."
typeThe 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
nameThe name of the attribute. The name must not contain "[", "]", or "."
typeThe 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
nameThe 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
TThe interface type of the attribute.
Parameters
nameThe 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
nameThe 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
indexThe 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
nameThe 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
nameThe 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.