neuray API Programmer's Manual

Scene elements

[Neuray API]

Description

All the scene elements that make up the scene graph.

Modules

 
Leaf nodes of the scene graph, for example, geometry, lights, or cameras. More...
 
MDL-related elements comprise a set of interfaces related to the Material Definition Language (MDL). More...
 
Miscellaneous scene graph elements, for example, textures, light profiles, BSDF measurements, or decals. More...
 
Inner nodes of the scene graph defining its structure. More...

Classes

class 
The attribute set comprises all attributes attached to a database element. More...
class 
Common base interface for all scene elements. More...

Enumerations

enum mi::neuraylib::Element_type{ ELEMENT_TYPE_INSTANCE = 0, ELEMENT_TYPE_GROUP = 1, ELEMENT_TYPE_OPTIONS = 2, ELEMENT_TYPE_CAMERA = 3, ELEMENT_TYPE_LIGHT = 4, ELEMENT_TYPE_LIGHTPROFILE = 5, ELEMENT_TYPE_TEXTURE = 7, ELEMENT_TYPE_IMAGE = 8, ELEMENT_TYPE_TRIANGLE_MESH = 10, ELEMENT_TYPE_ATTRIBUTE_CONTAINER = 16, ELEMENT_TYPE_POLYGON_MESH = 18, ELEMENT_TYPE_SUBDIVISION_SURFACE = 23, ELEMENT_TYPE_FREEFORM_SURFACE = 24, ELEMENT_TYPE_FIBERS = 25, ELEMENT_TYPE_VOLUME = 26, ELEMENT_TYPE_VOLUME_DATA = 27, ELEMENT_TYPE_PARTICLES = 28, ELEMENT_TYPE_MODULE = 29, ELEMENT_TYPE_FUNCTION_DEFINITION = 30, ELEMENT_TYPE_FUNCTION_CALL = 31, ELEMENT_TYPE_MATERIAL_INSTANCE = 33, ELEMENT_TYPE_COMPILED_MATERIAL = 34, ELEMENT_TYPE_BSDF_MEASUREMENT = 35, ELEMENT_TYPE_IRRADIANCE_PROBES = 36, ELEMENT_TYPE_DECAL = 37, ELEMENT_TYPE_ON_DEMAND_MESH = 38, ELEMENT_TYPE_PROJECTOR = 39, ELEMENT_TYPE_SECTION_OBJECT = 40, ELEMENT_TYPE_PROXY = 41, ELEMENT_TYPE_FORCE_32_BIT = 0xffffffffU}
Distinguishes scene elements. More...
enum mi::neuraylib::Propagation_type{ PROPAGATION_STANDARD, PROPAGATION_OVERRIDE, PROPAGATION_FORCE_32_BIT = 0xffffffffU}
Propagation types for attribute inheritance. More...

Functions

template< class T>mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, T& value)
Simplifies reading the value of an attribute into the corresponding classes from the base and math API. More...
template< class T>mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, mi::​Size index, T& value)
Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant with an index for collections). More...
template< class T>mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const char* key, T& value)
Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant with a key for collections). More...
template< class T>mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, T* values, mi::​Size n)
Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant for entire arrays as C-like array). More...
template< class T>mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, std::​vector < T >& values)
Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant for entire arrays as std::vector). More...
template< class T>mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const T& value)
Simplifies setting the value of an attribute from the corresponding classes from the base and math API. More...
template< class T>mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, mi::​Size index, const T& value)
Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant with an index for collections). More...
template< class T>mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const char* key, const T& value)
Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant with a key for collections). More...
template< class T>mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const T* values, mi::​Size n)
Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant for entire arrays as C-like arrays). More...
template< class T>mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const std::​vector < T >& values)
Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant for entire arrays as std::vector). More...

Enums

enum mi::neuraylib::Element_type

Distinguishes scene elements.

See also:

mi::neuraylib::IScene_element::get_element_type()

Enumerator:

ELEMENT_TYPE_INSTANCE = 0
mi::neuraylib::IInstance
ELEMENT_TYPE_GROUP = 1
mi::neuraylib::IGroup
ELEMENT_TYPE_OPTIONS = 2
mi::neuraylib::IOptions
ELEMENT_TYPE_CAMERA = 3
mi::neuraylib::ICamera
ELEMENT_TYPE_LIGHT = 4
mi::neuraylib::ILight
ELEMENT_TYPE_LIGHTPROFILE = 5
mi::neuraylib::ILightprofile
ELEMENT_TYPE_TEXTURE = 7
mi::neuraylib::ITexture
ELEMENT_TYPE_IMAGE = 8
mi::neuraylib::IImage
ELEMENT_TYPE_TRIANGLE_MESH = 10
mi::neuraylib::ITriangle_mesh
ELEMENT_TYPE_ATTRIBUTE_CONTAINER = 16
mi::neuraylib::IAttribute_container
ELEMENT_TYPE_POLYGON_MESH = 18
mi::neuraylib::IPolygon_mesh
ELEMENT_TYPE_SUBDIVISION_SURFACE = 23
mi::neuraylib::ISubdivision_surface
ELEMENT_TYPE_FREEFORM_SURFACE = 24
mi::neuraylib::IFreeform_surface
ELEMENT_TYPE_FIBERS = 25
mi::neuraylib::IFibers
ELEMENT_TYPE_VOLUME = 26
mi::neuraylib::IVolume
ELEMENT_TYPE_VOLUME_DATA = 27
mi::neuraylib::IVolume_data
ELEMENT_TYPE_PARTICLES = 28
mi::neuraylib::IParticles
ELEMENT_TYPE_MODULE = 29
mi::neuraylib::IModule
ELEMENT_TYPE_FUNCTION_DEFINITION = 30
mi::neuraylib::IFunction_definition
ELEMENT_TYPE_FUNCTION_CALL = 31
mi::neuraylib::IFunction_call
ELEMENT_TYPE_MATERIAL_INSTANCE = 33
mi::neuraylib::IMaterial_instance
ELEMENT_TYPE_COMPILED_MATERIAL = 34
mi::neuraylib::ICompiled_material
ELEMENT_TYPE_BSDF_MEASUREMENT = 35
mi::neuraylib::IBsdf_measurement
ELEMENT_TYPE_IRRADIANCE_PROBES = 36
mi::neuraylib::IIrradiance_probes
ELEMENT_TYPE_DECAL = 37
mi::neuraylib::IDecal
ELEMENT_TYPE_ON_DEMAND_MESH = 38
mi::neuraylib::IOn_demand_mesh
ELEMENT_TYPE_PROJECTOR = 39
mi::neuraylib::IProjector
ELEMENT_TYPE_SECTION_OBJECT = 40
mi::neuraylib::ISection_object
ELEMENT_TYPE_PROXY = 41
mi::neuraylib::IProxy
ELEMENT_TYPE_FORCE_32_BIT = 0xffffffffU
enum mi::neuraylib::Propagation_type

Propagation types for attribute inheritance. Inheritance of attributes allows you to easily make changes to an entire subtree of the scene graph.

Assume the scene graph contains an inner node P (the parent) with a (possibly inherited) attribute A and a child node C. If the child node C does not have the attribute A, the child will inherit P's value of A (without actually storing an explicit copy). If the child node C has the attribute A, it will use its own value of the attribute without taking P's value into consideration. This is the standard propagation rule which is represented by the propagation type mi::neuraylib::PROPAGATION_STANDARD.

The outcome of the last case can be reverted by setting the override flag of the attribute A on the parent node (or at the node from where it was inherited to P): in this case P's value of A is inherited to the child node C, no matter whether the child has the attribute or not. This propagation mode is represented by mi::neuraylib::PROPAGATION_OVERRIDE.

Note:

  • There is one exception to these rules: If the child node C is a geometry object, then P's value of A is used, no matter whether the propagation mode was set to mi::neuraylib::PROPAGATION_OVERRIDE or mi::neuraylib::PROPAGATION_STANDARD. The rationale is that for geometry objects the attribute on the object itself should be a default that is only used if no value for that attribute is inherited.

  • Inherited attributes are made available to the render modes, but are not available via the neuray API.

See also:

mi::neuraylib::IAttribute_set::set_attribute_propagation()

mi::neuraylib::IAttribute_set::get_attribute_propagation()

Enumerator:

PROPAGATION_STANDARD
Standard inheritance of attributes without any special flags.
PROPAGATION_OVERRIDE
The override flag for attribute inheritance.
PROPAGATION_FORCE_32_BIT = 0xffffffffU

Functions

template< class T>

mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, T& value) [inline]

Simplifies reading the value of an attribute into the corresponding classes from the base and math API.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to read.
value
The new value will be stored here.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, mi::​Size index, T& value) [inline]

Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant with an index for collections).

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to read.
index
The index of the affected collection element.
value
The new value will be stored here.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -3: The index is not valid.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const char* key, T& value) [inline]

Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant with a key for collections).

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to read.
key
The key of the affected collection element.
value
The new value will be stored here.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -3: The key is not valid.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, T* values, mi::​Size n) [inline]

Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant for entire arrays as C-like array). See also mi::get_value(const mi::neuraylib::IAttribute_set*,const char*,std::vector<T>&) for std::vector support.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to read.
values
The new values will be stored here (as pointer to a C-like array).
n
The size of the C-like array (needs to match the size of the attribute).

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute is not an array, or the dynamic type of the array elements does not match the static type of values.
  • -2: At least one value of values is not valid (possibly incomplete operation)
  • -4: The attribute name does not exist.
  • -5: The array sizes do not match.

template< class T>

mi::​Sint32 mi::get_value( const mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, std::​vector < T >& values) [inline]

Simplifies reading the value of an attribute into the corresponding classes from the base and math API (variant for entire arrays as std::vector). See also mi::get_value(const mi::neuraylib::IAttribute_set*,const char*,T*,mi::Size) for C-like arrays.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to read.
values
The new values will be stored here. The vector will be resized accordingly.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute is not an array, or the dynamic type of the array elements does not match the static type of values.
  • -2: At least one value of values is not valid (possibly incomplete operation)
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const T& value) [inline]

Simplifies setting the value of an attribute from the corresponding classes from the base and math API.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to modify.
value
The new value to be set.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -2: The value of value is not valid.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, mi::​Size index, const T& value) [inline]

Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant with an index for collections).

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to modify.
index
The index of the affected collection element.
value
The new value to be set.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -2: The value of value is not valid.
  • -3: The index is not valid.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const char* key, const T& value) [inline]

Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant with a key for collections).

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to modify.
key
The key of the affected collection element.
value
The new value to be set.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute does not match the static type of value.
  • -2: The value of value is not valid.
  • -3: The key is not valid.
  • -4: The attribute name does not exist.

template< class T>

mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const T* values, mi::​Size n) [inline]

Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant for entire arrays as C-like arrays). See also mi::set_value(mi::neuraylib::IAttribute_set*,const char*,const std::vector<T>&) for std::vector support.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to modify.
values
The new values to be set (as pointer to a C-like array).
n
The size of the C-like array. If the attribute is a dynamic array, then it is resized accordingly. If the attribute is a static array, then its size needs to match n.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute is not an array, or the dynamic type of the array elements does not match the static type of values.
  • -2: At least one value of values is not valid (possibly incomplete operation)
  • -4: The attribute name does not exist.
  • -5: The array sizes do not match (if the attribute is a static array).

template< class T>

mi::​Sint32 mi::set_value( mi::​neuraylib::​IAttribute_set* attribute_set, const char* name, const std::​vector < T >& values) [inline]

Simplifies setting the value of an attribute from the corresponding classes from the base and math API (variant for entire arrays as std::vector). See also mi::set_value(mi::neuraylib::IAttribute_set*,const char*,const T*,mi::Size) for C-like arrays.

Parameters

attribute_set
The affected attribute set.
name
The name of the attribute to modify.
values
The new values to be set. If the attribute is a dynamic array, then it is resized accordingly. If the attribute is a static array, then its size needs to match the size of values.

Returns

  • 0: Success.
  • -1: The dynamic type of the attribute is not an array, or the dynamic type of the array elements does not match the static type of values.
  • -2: At least one value of values is not valid (possibly incomplete operation)
  • -4: The attribute name does not exist.
  • -5: The array sizes do not match (if the attribute is a static array).