|
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
IInterface > |
Self |
|
Own type. More...
|
|
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > |
IID |
|
Declares the interface ID (IID) of this interface. More...
|
|
static bool |
compare_iid (const Uuid &iid) |
|
Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
|
|
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, 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.
- 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 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.
- 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 the canvas name object_id
. See mi::neuraylib::IRender_target_base::get_canvas_name() for details.
-
mi::Sint32 material_id
A material ID that is useful in conjunction with the canvas name material_id
. See mi::neuraylib::IRender_target_base::get_canvas_name() for details.
- const char* handle
An object or light ID that is useful in conjunction with Light Path Expressions. See mi::neuraylib::IRender_target_base::get_canvas_name() for details.
- bool instancing
Controls instancing in user mode. See the manual for details.
- bool shadow_terminator_offset
Controls the automatic shadow terminator handling. See the manual for details.
- 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.
-
bool light_portal
A light flagged with this attribute does not emit any light by itself but acts as hint that light is coming from its direction.
- 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 approximation.
-
mi::Float32 const_v
Stores the constant c_v
for parametric approximation.
-
mi::Sint8 method
Three methods are available, parametric approximation (0), length approximation (1), and distance ratio approximation (3).
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.
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].
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 sharp
Unused.
- 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).
- 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).
bool create_missing_attributes,
bool remove_excess_attributes,
bool adjust_attribute_types)
{
if( !factory || !source || !target)
return -1;
const char* name;
std::string source_type = source_attr->get_type_name();
if( !create_missing_attributes)
continue;
else
} else {
if( adjust_attribute_types
} else
}
if( result != 0)
return -2;
}
if( !remove_excess_attributes)
return 0;
index = 0;
return 0;
}
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 match the required type(s) of such an attribute, or
-
T
does not match type
.
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 match the required type(s) of such an attribute.