NVIDIA Iray API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Modules | Classes | Functions
Types
Iray API

Types are organized in a hierarchy based on the basic interface mi::IData. More...

Modules

  Simple Types
  This module lists all interfaces related to simple types.
 
  Collections
  This module and its submodule Compounds list all interfaces related to collections.
 

Classes

class   mi::ICall_decl
  A call declaration is used to describe call types. More...
 
class   mi::IData
  This interface is the base interface of all types. More...
 
class   mi::IEnum_decl
  An enum declaration is used to describe enum types. More...
 
class   mi::neuraylib::IFactory
  This API component allows the creation, assignment, and cloning of instances of types. More...
 
class   mi::IStructure_decl
  A structure declaration is used to describe structure types. More...
 

Functions

template<class T >
mi::Sint32  mi::set_value (mi::IData *data, const T &value)
  Simplifies setting the value of mi::IData from the corresponding classes from the base and math API. More...
 
mi::Sint32  mi::set_value (mi::IData *data, const char *value)
  This specialization handles mi::IString and mi::IRef (and corresponding attachables). More...
 
mi::Sint32  mi::set_value (mi::IData *data, const mi::base::Uuid &value)
  This specialization handles mi::IUuid. More...
 
template<class T , Size DIM>
mi::Sint32  mi::set_value (mi::IData *data, const mi::math::Vector< T, DIM > &value)
  This specialization handles the vector specializations of mi::ICompound (and corresponding attachables). More...
 
template<class T , Size ROW, Size COL>
mi::Sint32  mi::set_value (mi::IData *data, const mi::math::Matrix< T, ROW, COL > &value)
  This specialization handles the matrix specializations of mi::ICompound (and corresponding attachables). More...
 
mi::Sint32  mi::set_value (mi::IData *data, const mi::Color &value)
  This specialization handles mi::IColor and mi::IColor3 (and corresponding attachables). More...
 
mi::Sint32  mi::set_value (mi::IData *data, const mi::Spectrum &value)
  This specialization handles mi::ISpectrum (and corresponding attachables). More...
 
mi::Sint32  mi::set_value (mi::IData *data, const mi::Bbox3 &value)
  This specialization handles mi::IBbox3. More...
 
template<class T >
mi::Sint32  mi::set_value (mi::IData *data, mi::Size index, const T &value)
  This variant handles elements of collections identified via an additional index. More...
 
template<class T >
mi::Sint32  mi::set_value (mi::IData *data, const char *key, const T &value)
  This variant handles elements of collections identified via an additional key. More...
 
template<class T >
mi::Sint32  mi::get_value (const mi::IData *data, T &value)
  Simplifies reading the value of mi::IData into the corresponding classes from the base and math API. More...
 
mi::Sint32  mi::get_value (const mi::IData *data, const char *&value)
  This specialization handles mi::IString and mi::IRef (and corresponding attachables). More...
 
mi::Sint32  mi::get_value (const mi::IData *data, mi::base::Uuid &value)
  This specialization handles mi::IUuid. More...
 
template<class T , Size DIM>
mi::Sint32  mi::get_value (const mi::IData *data, mi::math::Vector< T, DIM > &value)
  This specialization handles the vector specializations of mi::ICompound (and corresponding attachables). More...
 
template<class T , Size ROW, Size COL>
mi::Sint32  mi::get_value (const mi::IData *data, mi::math::Matrix< T, ROW, COL > &value)
  This specialization handles the matrix specializations of mi::ICompound (and corresponding attachables). More...
 
mi::Sint32  mi::get_value (const mi::IData *data, mi::Color &value)
  This specialization handles mi::IColor and mi::IColor3 (and corresponding attachables). More...
 
mi::Sint32  mi::get_value (const mi::IData *data, mi::Spectrum &value)
  This specialization handles mi::ISpectrum (and corresponding attachables). More...
 
mi::Sint32  mi::get_value (const mi::IData *data, mi::Bbox3 &value)
  This specialization handles mi::IBbox3. More...
 
template<class T >
mi::Sint32  mi::get_value (const mi::IData *data, mi::Size index, T &value)
  This variant handles elements of collections identified via an additional index. More...
 
template<class T >
mi::Sint32  mi::get_value (const mi::IData *data, const char *key, T &value)
  This variant handles elements of collections identified via an additional key. More...
 

Detailed Description

Types are organized in a hierarchy based on the basic interface mi::IData.

The hierarchy of types based on mi::IData is split into two branches, simple types (derived from mi::IData_simple) and collections (derived from mi::IData_collection). Simple types are e.g. numbers and strings. Collections are e.g. arrays, structures, maps, vectors, and matrices.

Types are identified by type names. The method mi::IData::get_type_name() returns the type name of an instance of mi::IData. Most notably type names are used to create instances of types via mi::neuraylib::IFactory::create()and mi::neuraylib::ITransaction::create(), and to create attributes or to query their type.

Since there is a very high number of interfaces related to types they are not listed in this module. Rather they have been split into three submodules Simple Types, Collections, and Compounds (compounds are a subset of the collections).

The free functions mi::set_value() and mi::get_value() including the various specializations may help to write/read values to/from instances of mi::IData.

Simple types

Simple types are booleans, integral and floating-point numbers, strings, UUIDs, void, pointers, references, attachables and indices.All interfaces of the simple types are derived from mi::IData_simple. For most simple types there is an equivalent C++ class. With the exception of pointers, references, attachables, and enums the type name of simple types equals the interface name without the leading "I". See also the module Simple Types.

Type name Attribute type Interface C++ class Description
"Boolean" yes mi::IBoolean bool Boolean
"Sint8" yes mi::ISint8 mi::Sint8 Signed 8-bit integer
"Sint16" yes mi::ISint16 mi::Sint16 Signed 16-bit integer
"Sint32" yes mi::ISint32 mi::Sint32 Signed 32-bit integer
"Sint64" yes mi::ISint64 mi::Sint64 Signed 64-bit integer
"Uint8" no mi::IUint8 mi::Uint8 Unsigned 8-bit integer
"Uint16" no mi::IUint16 mi::Uint16 Unsigned 16-bit integer
"Uint32" no mi::IUint32 mi::Uint32 Unsigned 32-bit integer
"Uint64" no mi::IUint64 mi::Uint64 Unsigned 64-bit integer
"Float32" yes mi::IFloat32 mi::Float32 32-bit IEEE-754 single-precision floating-point number
"Float64" yes mi::IFloat64 mi::Float64 64-bit IEEE-754 double-precision floating-point number
"Difference no mi::IDifference mi::Difference Signed 32-bit or 64-bit integer, depending on the architecture
"Size" no mi::ISize mi::Size Unsigned 32-bit or 64-bit integer, depending on the architecture
"String" yes mi::IString const char* String representation in ISO-8859-1 encoding
"Uuid" no mi::IUuid mi::base::Uuid Universally unique identifier (UUID)
"Void" no mi::IVoid void Void type
"Pointer<T>" no mi::IPointer - Mutable pointer to an instance of type T
"Const_pointer<T>" no mi::IConst_pointer - Const pointer to an instance of type T
as registered (1) yes mi::IEnum - Subsets of mi::Sint32 values, identified by strings
"Ref" or "Ref<T>" yes mi::IRef - Reference to another database element
"Attachable<T>" yes mi::IAttachable - Alternative between a reference and another type
"Parameter" yes mi::IParameter - Unsigned 32-bit integer
"Temporary" yes mi::ITemporary - Unsigned 32-bit integer

(1) The type name of an enum is specific to the actual enum type. There is no naming pattern as for the other simple types. User-defined enum types require the registration of a corresponding enum declaration with a type name (see mi::neuraylib::IExtension_api::register_enum_decl()).

Collections

Collections are static and dynamic arrays, maps, structures, and compounds (for compounds see separate section below). All interfaces of collections are derived from mi::IData_collection. For all collection types there are similar constructs in C++, but there are no directly equivalent C++ classes as for the simple types. The type names of collections are typically constructed according to certain rules, typically involving the type name of the contained elements or values. See the table below for examples or the corresponding interfaces for an exact description. See also the module Collections.

Type name Attribute type Interface C++ class Description
"T[N]" yes (2) mi::IArray - Static array of N elements of type T, N > 0
"T[]" yes (2) mi::IDynamic_array - Dynamic array of elements of type T
"Map<T>" no mi::IMap - Set of key-value pairs, values are of type T
as registered (3) yes mi::IStructure - Ordered set of key-value pairs, values are of arbitrary types
as registered (4) yes mi::ICall - Call to an MDL function with specific arguments

(2) For attributes, the type of array elements must not be an array (but it can be a structure with arrays as members).
(3) The type name of a structure is specific to the actual structure type. There is no naming pattern as for arrays or maps. User-defined structure types require the registration of a corresponding structure declaration with a type name (see mi::neuraylib::IExtension_api::register_structure_decl()).
(4) The type name of a call is specific to the actual call type. There is no naming pattern as for arrays or maps.

Compounds

Compound types are vectors, matrices, colors, spectrums, and bounding boxes. Actually, compounds belong to the set of collections, they are not a third kind of type besides simple types and collections.In the documentation they are split into their own module due to the very high number of interfaces and typedefs for compounds. See also the module Compounds.

For all compound types there is a C++ class from the math API as counterpart. Type names for vectors and matrices are based on the type name of the element followed by the dimension in angle brackets ("<N>" or "<M,N>", N = 2, 3, or 4).

Type name Attribute type Interface C++ class Description
"Boolean<N>" yes mi::IBoolean_2, ... mi::Boolean_2, ... N x bool vector, N = 2, 3, or 4
"Sint32<N>" yes mi::ISint32_2, ... mi::Sint32_2, ... N x Sint32 vector, N = 2, 3, or 4
"Uint32<N>" no mi::IUint32_2, ... mi::Uint32_2, ... N x Uint32 vector, N = 2, 3, or 4
"Float32<N>" yes mi::IFloat32_2, ... mi::Float32_2, ... N x Float32 vector, N = 2, 3, or 4
"Float64<N>" yes mi::IFloat64_2, ... mi::Float64_2, ... N x Float64 vector, N = 2, 3, or 4
"Boolean<M,N>" no mi::IBoolean_2_2, ... mi::Boolean_2_2, ... M x N matrix of bool, M, N = 2, 3, or 4
"Sint32<M,N>" no mi::ISint32_2_2, ... mi::Sint32_2_2, ... M x N matrix of Sint32, M, N = 2, 3, or 4
"Uint32<M,N>" no mi::IUint32_2_2, ... mi::Uint32_2_2, ... M x N matrix of Uint32, M, N = 2, 3, or 4
"Float32<M,N>" yes mi::IFloat32_2_2, ... mi::Float32_2_2, ... M x N matrix of Float32, M, N = 2, 3, or 4
"Float64<M,N>" yes mi::IFloat64_2_2, ... mi::Float64_2_2, ... M x N matrix of Float64, M, N = 2, 3, or 4
"Color" yes mi::IColor mi::Color 4 x Float32 representing RGBA color
"Color3" yes mi::IColor3 mi::Color 3 x Float32 representing RGB color
"Spectrum" yes mi::ISpectrum mi::Spectrum 3 x Float32 representing three color bands
"Bbox3" no mi::IBbox3 mi::Bbox3 Bounding box, represented by two mi::Float32_3
Pixel types

Pixel types denote the type of the pixel of a canvas or image. The table below lists the valid pixel types. See also mi::IImage, mi::neuraylib::ICanvas and mi::neuraylib::ITile.

Type name Interface C++ class Description
"Sint8" mi::ISint8 mi::Sint8 Signed 8-bit integer
"Sint32" mi::ISint32 mi::Sint32 Signed 32-bit integer
"Float32" mi::IFloat32 mi::Float32 32-bit IEEE-754 single-precision floating-point number
"Float32<2>" mi::IFloat32_2 mi::Float32_2 2 x Float32
"Float32<3>" mi::IFloat32_3 mi::Float32_3 3 x Float32
"Float32<4>" mi::IFloat32_4 mi::Float32_4 4 x Float32
"Rgb" - - 3 x Uint8 representing RGB color
"Rgba" - - 4 x Uint8 representing RGBA color
"Rgbe" - - 4 x Uint8 representing RGBE color
"Rgbea" - - 5 x Uint8 representing RGBEA color
"Rgb_16" - - 3 x Uint16 representing RGB color
"Rgba_16" - - 4 x Uint16 representing RGBA color
"Rgb_fp" - - 3 x Float32 representing RGB color
"Color" mi::IColor mi::Color 4 x Float32 representing RGBA color

Function Documentation

template<class T >
mi::Sint32 mi::get_value ( const mi::IData *  data,
T &  value 
)

Simplifies reading the value of mi::IData into the corresponding classes from the base and math API.

Parameters
data The instance of mi::IData to read.
value The new value will be stored here.
Returns
  • 0: Success.
  • -1: The dynamic type of data does not match the static type of value.
Note
If data is of the type "Attachable<String>" and value is of the type a const char*, the method will always read the value, and never the reference (there is not enough context from the types to decide which case is intended). If you want to read the reference you need to use mi::IAttachable::get_reference_name() directly (this case is very rare in practice).
If data is of the type "Attachable<Ref>" and value is of the type a const char*, the method will always read the reference, and never the value (there is not enough context from the types to decide which case is intended). If you want to read the value you need to use mi::IAttachable::get_value() and then either use mi::get_value() on that pointer or use directly one of the methods offered by that pointer. Typically, this case occurs when getting material or function arguments that identify a texture or a light profile.

This general template handles mi::IValue, and expects one of the following types as second argument:

It also handles mi::IEnum and expects an mi::Sint32 argument in that case. Furthermore, it also handles mi::IParameter and mi::ITemporary and expects an mi::Uint32 argument in that case. Finally, it handles attachables.

mi::Sint32 mi::get_value ( const mi::IData *  data,
const char *&  value 
)
inline

This specialization handles mi::IString and mi::IRef (and corresponding attachables).

It expects a const char* argument. See mi::get_value() for details.

mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::base::Uuid &  value 
)
inline

This specialization handles mi::IUuid.

It expects an mi::base::Uuid argument. See mi::get_value() for details.

template<class T , Size DIM>
mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::math::Vector< T, DIM > &  value 
)
inline

This specialization handles the vector specializations of mi::ICompound (and corresponding attachables).

It expects one of the following specializations of mi::math::Vector as its second argument:

See mi::get_value() for details.

template<class T , Size ROW, Size COL>
mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::math::Matrix< T, ROW, COL > &  value 
)

This specialization handles the matrix specializations of mi::ICompound (and corresponding attachables).

It expects one of the following specializations of mi::math::Matrix as its second argument:

See mi::get_value() for details.

mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::Color &  value 
)
inline

This specialization handles mi::IColor and mi::IColor3 (and corresponding attachables).

It expects an mi::Color argument. See mi::get_value() for details.

mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::Spectrum &  value 
)
inline

This specialization handles mi::ISpectrum (and corresponding attachables).

It expects an mi::Spectrum argument. See mi::get_value() for details.

mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::Bbox3 &  value 
)
inline

This specialization handles mi::IBbox3.

It expects an mi::Bbox3 argument. See mi::get_value() for details.

template<class T >
mi::Sint32 mi::get_value ( const mi::IData *  data,
mi::Size  index,
T &  value 
)

This variant handles elements of collections identified via an additional index.

Parameters
data The instance of mi::IData 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 data does not match the static type of value.
  • -3: The index is not valid.
template<class T >
mi::Sint32 mi::get_value ( const mi::IData *  data,
const char *  key,
T &  value 
)

This variant handles elements of collections identified via an additional key.

Parameters
data The instance of mi::IData 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 data does not match the static type of value.
  • -3: The key is not valid.
template<class T >
mi::Sint32 mi::set_value ( mi::IData *  data,
const T &  value 
)

Simplifies setting the value of mi::IData from the corresponding classes from the base and math API.

Parameters
data The instance of mi::IData to modify.
value The new value to be set.
Returns
  • 0: Success.
  • -1: The dynamic type of data does not match the static type of value.
  • -2: The value of value is not valid.
Note
If data is of the type "Attachable<String>" and value is of the type a const char*, the method will always set the value, and never the reference (there is not enough context from the types to decide which case is intended). If you want to set the reference you need to use mi::IAttachable::set_reference() directly (this case is very rare in practice).
If data is of the type "Attachable<Ref>" and value is of the type a const char*, the method will always set the reference, and never the value (there is not enough context from the types to decide which case is intended). If you want to set the value you need to use mi::IAttachable::get_value() and then either use mi::set_value() on that pointer or use directly one of the methods offered by that pointer. Typically, this case occurs when setting material or function arguments that identify a texture or a light profile.

This general template handles mi::IValue and expects one of the following types as second argument:

It also handles mi::IEnum and expects an mi::Sint32 argument in that case. Furthermore, it also handles mi::IParameter and mi::ITemporary and expects an mi::Uint32 argument in that case. Finally, it handles attachables.

mi::Sint32 mi::set_value ( mi::IData *  data,
const char *  value 
)
inline

This specialization handles mi::IString and mi::IRef (and corresponding attachables).

It expects a const char* argument. See mi::set_value() for details.

mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::base::Uuid &  value 
)
inline

This specialization handles mi::IUuid.

It expects an mi::base::Uuid argument. See mi::set_value() for details.

template<class T , Size DIM>
mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::math::Vector< T, DIM > &  value 
)
inline

This specialization handles the vector specializations of mi::ICompound (and corresponding attachables).

It expects one of the following specializations of mi::math::Vector as its second argument:

See mi::set_value() for details.

template<class T , Size ROW, Size COL>
mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::math::Matrix< T, ROW, COL > &  value 
)

This specialization handles the matrix specializations of mi::ICompound (and corresponding attachables).

It expects one of the following specializations of mi::math::Matrix as its second argument:

See mi::set_value() for details.

mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::Color &  value 
)
inline

This specialization handles mi::IColor and mi::IColor3 (and corresponding attachables).

It expects an mi::Color argument. See mi::set_value() for details.

mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::Spectrum &  value 
)
inline

This specialization handles mi::ISpectrum (and corresponding attachables).

It expects an mi::Spectrum argument. See mi::set_value() for details.

mi::Sint32 mi::set_value ( mi::IData *  data,
const mi::Bbox3 &  value 
)
inline

This specialization handles mi::IBbox3.

It expects an mi::Bbox3 argument. See mi::set_value() for details.

template<class T >
mi::Sint32 mi::set_value ( mi::IData *  data,
mi::Size  index,
const T &  value 
)

This variant handles elements of collections identified via an additional index.

Parameters
data The instance of mi::IData 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 data does not match the static type of value.
  • -2: The value of value is not valid.
  • -3: The index or key is not valid for the collection.
template<class T >
mi::Sint32 mi::set_value ( mi::IData *  data,
const char *  key,
const T &  value 
)

This variant handles elements of collections identified via an additional key.

Parameters
data The instance of mi::IData 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 data does not match the static type of value.
  • -2: The value of value is not valid.
  • -3: The key is not valid.