neuray API Programmer's Manual

mi::neuraylib::IType_factory Class Reference

[MDL type system]

Description

The interface for creating types. A type factory can be obtained from mi::neuraylib::IMdl_factory::create_type_factory().

See also:

mi::neuraylib::IValue_factory, mi::neuraylib::IExpression_factory

Struct categories

virtual IStruct_category_listclone( const IStruct_category_list* struct_category_list) const =0
Clones the given struct category list. More...
virtual Sint32 compare( const IStruct_category* lhs, const IStruct_category* rhs) const =0
Compares two instances of mi::neuraylib::IStruct_category. More...
virtual Sint32 compare( const IStruct_category_list* lhs, const IStruct_category_list* rhs) const =0
Compares two instances of mi::neuraylib::IStruct_category_list. More...
virtual const IStruct_categorycreate_struct_category( const char* symbol) const =0
Returns a registered struct category, or NULL if symbol is invalid or unknown.
virtual IStruct_category_listcreate_struct_category_list() const =0
Creates a new struct category list.
virtual const IStringdump( const IStruct_category* struct_category, Size depth = 0) const =0
Returns a textual representation of a struct category. More...
virtual const IStringdump( const IStruct_category_list* list, Size depth = 0) const =0
Returns a textual representation of a struct category list. More...
virtual const IStruct_categoryget_predefined_struct_category( IStruct_category::​Predefined_id id) const =0
Returns a registered struct category, or NULL if id is unknown.

Creation of struct categories, types, and type lists

virtual const IType_aliascreate_alias( const IType* type, Uint32 modifiers, const char* symbol) const =0
Creates a new instance of the type alias.
virtual const IType_boolcreate_bool() const =0
Creates a new instance of the type boolean.
virtual const IType_bsdfcreate_bsdf() const =0
Creates a new instance of the type bsdf.
virtual const IType_bsdf_measurementcreate_bsdf_measurement() const =0
Creates a new instance of the type bsdf_measurement.
virtual const IType_colorcreate_color() const =0
Creates a new instance of the type color.
virtual const IType_arraycreate_deferred_sized_array( const IType* element_type, const char* size) const =0
Creates a new instance of a deferred-sized array type. More...
virtual const IType_doublecreate_double() const =0
Creates a new instance of the double type.
virtual const IType_edfcreate_edf() const =0
Creates a new instance of the type edf.
virtual const IType_enumcreate_enum( const char* symbol) const =0
Returns a registered enum type, or NULL if symbol is invalid or unknown.
virtual const IType_floatcreate_float() const =0
Creates a new instance of the float type.
virtual const ITypecreate_from_mdl_type_name( const char* name) const =0
Creates a type based on its MDL type name. More...
template< class T>const T* create_from_mdl_type_name( const char* name) const
Creates a type based on its MDL type name. More...
virtual const IType_hair_bsdfcreate_hair_bsdf() const =0
Creates a new instance of the type hair_bsdf.
virtual const IType_arraycreate_immediate_sized_array( const IType* element_type, Size size) const =0
Creates a new instance of an immediate-sized array type.
virtual const IType_intcreate_int() const =0
Creates a new instance of the type int.
virtual const IType_light_profilecreate_light_profile() const =0
Creates a new instance of the type light_profile.
virtual const IType_matrixcreate_matrix( const IType_vector* column_type, Size columns) const =0
Creates a new instance of a matrix type. More...
virtual const IType_stringcreate_string() const =0
Creates a new instance of the string type.
virtual const IType_structcreate_struct( const char* symbol) const =0
Returns a registered struct type, or NULL if symbol is invalid or unknown.
virtual const IType_texturecreate_texture( IType_texture::​Shape shape) const =0
Creates a new instance of the type texture.
virtual IType_listcreate_type_list() const =0
Creates a new type list.
virtual const IType_vdfcreate_vdf() const =0
Creates a new instance of the type vdf.
virtual const IType_vectorcreate_vector( const IType_atomic* element_type, Size size) const =0
Creates a new instance of a vector type. More...
virtual const IType_enumget_predefined_enum( IType_enum::​Predefined_id id) const =0
Returns a registered enum type, or NULL if id is unknown.
virtual const IType_structget_predefined_struct( IType_struct::​Predefined_id id) const =0
Returns a registered struct type, or NULL if id is unknown.

Cloning of type lists

virtual IType_listclone( const IType_list* type_list) const =0
Clones the given type list. More...

Comparison of types and type lists

virtual Sint32 compare( const IType* lhs, const IType* rhs) const =0
Compares two instances of mi::neuraylib::IType. More...
virtual Sint32 compare( const IType_list* lhs, const IType_list* rhs) const =0
Compares two instances of mi::neuraylib::IType_list. More...
virtual Sint32 from_same_struct_category( const IType* lhs, const IType* rhs) const =0
Checks whether two types are from the same struct category, i.e., lhs can be decl-cast to rhs. More...
virtual Sint32 is_compatible( const IType* lhs, const IType* rhs) const =0
Checks whether two types are (cast-)compatible, i.e. More...

Dumping of types and type lists

virtual const IStringdump( const IType* type, Size depth = 0) const =0
Returns a textual representation of a type. More...
virtual const IStringdump( const IType_list* list, Size depth = 0) const =0
Returns a textual representation of a type list. More...

Miscellaneous methods

virtual const IStringget_mdl_module_name( const IType* type) const =0
Returns the MDL module name of the module which defines type. More...
virtual const IStringget_mdl_type_name( const IType* type) const =0
Returns the MDL type name of a type. More...

Member Functions

virtual IStruct_category_list* mi::​neuraylib::​IType_factory::clone( const IStruct_category_list* struct_category_list) const [pure virtual]

Clones the given struct category list.

Note:

There is no method clone a struct category itself. Struct categories themselves are always const and there is no scenario where cloning of a struct category makes sense.

virtual IType_list* mi::​neuraylib::​IType_factory::clone( const IType_list* type_list) const [pure virtual]

Clones the given type list.

Note:

There is no method clone a type itself. Types themselves are always const and there is no scenario where cloning of a type makes sense.

virtual Sint32 mi::​neuraylib::​IType_factory::compare( const IStruct_category* lhs, const IStruct_category* rhs) const [pure virtual]

Compares two instances of mi::neuraylib::IStruct_category. The result is determined by strcmp() on the corresponding symbol names.

Parameters

lhs
The left-hand side operand for the comparison.
rhs
The right-hand side operand for the comparison.

Returns

-1 if lhs < rhs , 0 if lhs == rhs , and +1 if lhs > rhs .

virtual Sint32 mi::​neuraylib::​IType_factory::compare( const IStruct_category_list* lhs, const IStruct_category_list* rhs) const [pure virtual]

Compares two instances of mi::neuraylib::IStruct_category_list. The comparison operator for instances of mi::neuraylib::IStruct_category_list is defined as follows:

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.

  • Next, the list sizes are compared using operator< () .

  • Next, the lists are traversed by increasing index and the names are compared using strcmp().

  • Finally, the list elements are enumerated by increasing index and the struct categories are compared.

Parameters

lhs
The left-hand side operand for the comparison.
rhs
The right-hand side operand for the comparison.

Returns

-1 if lhs < rhs , 0 if lhs == rhs , and +1 if lhs > rhs .

virtual Sint32 mi::​neuraylib::​IType_factory::compare( const IType* lhs, const IType* rhs) const [pure virtual]

Compares two instances of mi::neuraylib::IType. The comparison operator for instances of mi::neuraylib::IType is defined as follows:

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.

  • Otherwise, the kind of the types are compared. If they are different, the result is determined by operator< on the mi::neuraylib::IType::Kind values.

  • Finally, specific types are compared as follows:

Parameters

lhs
The left-hand side operand for the comparison.
rhs
The right-hand side operand for the comparison.

Returns

-1 if lhs < rhs , 0 if lhs == rhs , and +1 if lhs > rhs .

virtual Sint32 mi::​neuraylib::​IType_factory::compare( const IType_list* lhs, const IType_list* rhs) const [pure virtual]

Compares two instances of mi::neuraylib::IType_list. The comparison operator for instances of mi::neuraylib::IType_list is defined as follows:

  • If lhs or rhs is NULL, the result is the lexicographic comparison of the pointer addresses themselves.

  • Next, the list sizes are compared using operator< () .

  • Next, the lists are traversed by increasing index and the names are compared using strcmp().

  • Finally, the list elements are enumerated by increasing index and the types are compared.

Parameters

lhs
The left-hand side operand for the comparison.
rhs
The right-hand side operand for the comparison.

Returns

-1 if lhs < rhs , 0 if lhs == rhs , and +1 if lhs > rhs .

virtual const IType_alias* mi::​neuraylib::​IType_factory::create_alias( const IType* type, Uint32 modifiers, const char* symbol) const [pure virtual]

Creates a new instance of the type alias.

virtual const IType_bool* mi::​neuraylib::​IType_factory::create_bool() const [pure virtual]

Creates a new instance of the type boolean.

virtual const IType_bsdf* mi::​neuraylib::​IType_factory::create_bsdf() const [pure virtual]

Creates a new instance of the type bsdf.

virtual const IType_bsdf_measurement* mi::​neuraylib::​IType_factory::create_bsdf_measurement() const [pure virtual]

Creates a new instance of the type bsdf_measurement.

virtual const IType_color* mi::​neuraylib::​IType_factory::create_color() const [pure virtual]

Creates a new instance of the type color.

virtual const IType_array* mi::​neuraylib::​IType_factory::create_deferred_sized_array( const IType* element_type, const char* size) const [pure virtual]

Creates a new instance of a deferred-sized array type.

Parameters

element_type
The type of the array elements.
size
The size symbol, e.g., "N". The actual value of the size symbol does not matter in most cases, e.g., for arguments. It does matter when constructing new functions and materials using the module builder (see mi::neuraylib::IMdl_module_builder).

Returns

The corresponding array type, or NULL in case of errors.

virtual const IType_double* mi::​neuraylib::​IType_factory::create_double() const [pure virtual]

Creates a new instance of the double type.

virtual const IType_edf* mi::​neuraylib::​IType_factory::create_edf() const [pure virtual]

Creates a new instance of the type edf.

virtual const IType_enum* mi::​neuraylib::​IType_factory::create_enum( const char* symbol) const [pure virtual]

Returns a registered enum type, or NULL if symbol is invalid or unknown.

virtual const IType_float* mi::​neuraylib::​IType_factory::create_float() const [pure virtual]

Creates a new instance of the float type.

virtual const IType* mi::​neuraylib::​IType_factory::create_from_mdl_type_name( const char* name) const [pure virtual]

Creates a type based on its MDL type name. Contrary to MDL source code, whitespace is meaningful. In other words, only the strings produced by get_mdl_type_name() are supported here. For enums and structs, the corresponding module must have been loaded, such that these types are registered.

Note:

Named aliases are not yet supported.

template< class T>

const T* mi::​neuraylib::​IType_factory::create_from_mdl_type_name( const char* name) const [inline]

Creates a type based on its MDL type name. Contrary to MDL source code, whitespace is meaningful. In other words, only the strings produced by get_mdl_type_name() are supported here. For enums and structs, the corresponding module must have been loaded, such that these types are registered.

Note:

Named aliases are not yet supported.

virtual const IType_hair_bsdf* mi::​neuraylib::​IType_factory::create_hair_bsdf() const [pure virtual]

Creates a new instance of the type hair_bsdf.

virtual const IType_array* mi::​neuraylib::​IType_factory::create_immediate_sized_array( const IType* element_type, Size size) const [pure virtual]

Creates a new instance of an immediate-sized array type.

virtual const IType_int* mi::​neuraylib::​IType_factory::create_int() const [pure virtual]

Creates a new instance of the type int.

virtual const IType_light_profile* mi::​neuraylib::​IType_factory::create_light_profile() const [pure virtual]

Creates a new instance of the type light_profile.

virtual const IType_matrix* mi::​neuraylib::​IType_factory::create_matrix( const IType_vector* column_type, Size columns) const [pure virtual]

Creates a new instance of a matrix type.

Parameters

column_type
The column type needs to be a vector of either mi::neuraylib::IType_float or mi::neuraylib::IType_double.
columns
The number of columns, either 2, 3, or 4.

Returns

The corresponding matrix type, or NULL in case of errors.

virtual const IType_string* mi::​neuraylib::​IType_factory::create_string() const [pure virtual]

Creates a new instance of the string type.

virtual const IType_struct* mi::​neuraylib::​IType_factory::create_struct( const char* symbol) const [pure virtual]

Returns a registered struct type, or NULL if symbol is invalid or unknown.

virtual const IStruct_category* mi::​neuraylib::​IType_factory::create_struct_category( const char* symbol) const [pure virtual]

Returns a registered struct category, or NULL if symbol is invalid or unknown.

virtual IStruct_category_list* mi::​neuraylib::​IType_factory::create_struct_category_list() const [pure virtual]

Creates a new struct category list.

virtual const IType_texture* mi::​neuraylib::​IType_factory::create_texture( IType_texture::​Shape shape) const [pure virtual]

Creates a new instance of the type texture.

virtual IType_list* mi::​neuraylib::​IType_factory::create_type_list() const [pure virtual]

Creates a new type list.

virtual const IType_vdf* mi::​neuraylib::​IType_factory::create_vdf() const [pure virtual]

Creates a new instance of the type vdf.

virtual const IType_vector* mi::​neuraylib::​IType_factory::create_vector( const IType_atomic* element_type, Size size) const [pure virtual]

Creates a new instance of a vector type.

Parameters

element_type
The element type needs to be either mi::neuraylib::IType_bool, mi::neuraylib::IType_int, mi::neuraylib::IType_float, or mi::neuraylib::IType_double.
size
The number of elements, either 2, 3, or 4.

Returns

The corresponding vector type, or NULL in case of errors.

virtual const IString* mi::​neuraylib::​IType_factory::dump( const IStruct_category* struct_category, Size depth = 0) const [pure virtual]

Returns a textual representation of a struct category.

Note:

The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

virtual const IString* mi::​neuraylib::​IType_factory::dump( const IStruct_category_list* list, Size depth = 0) const [pure virtual]

Returns a textual representation of a struct category list. The representation of the struct category list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note:

The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

virtual const IString* mi::​neuraylib::​IType_factory::dump( const IType* type, Size depth = 0) const [pure virtual]

Returns a textual representation of a type. The representation of the type might contain line breaks, for example for structures and enums. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note:

The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

virtual const IString* mi::​neuraylib::​IType_factory::dump( const IType_list* list, Size depth = 0) const [pure virtual]

Returns a textual representation of a type list. The representation of the type list will contain line breaks. Subsequent lines have a suitable indentation. The assumed indentation level of the first line is specified by depth.

Note:

The exact format of the textual representation is unspecified and might change in future releases. The textual representation is primarily meant as a debugging aid. Do not base application logic on it.

virtual Sint32 mi::​neuraylib::​IType_factory::from_same_struct_category( const IType* lhs, const IType* rhs) const [pure virtual]

Checks whether two types are from the same struct category, i.e., lhs can be decl-cast to rhs.

See also:

mi::neuraylib::IExpression_factory::create_decl_cast().

Parameters

lhs
The first type.
rhs
The second type.

Returns

  • 0: lhs and rhs are from the same struct category, but different types.
  • 1: lhs and rhs are identical types.
  • -1: lhs and rhs are from different struct categories (including struct types without struct category, or no struct types).

virtual const IString* mi::​neuraylib::​IType_factory::get_mdl_module_name( const IType* type) const [pure virtual]

Returns the MDL module name of the module which defines type. The module name is derived from the symbol of enum, struct, and alias types. For array types, the corresponding element type is considered. Frequency modifiers of alias types are ignored. Returns the name of the ::<builtins> module for all other types.

Use mi::neuraylib::IMdl_factory::get_db_module_name() to compute the corresponding DB name.

virtual const IString* mi::​neuraylib::​IType_factory::get_mdl_type_name( const IType* type) const [pure virtual]

Returns the MDL type name of a type. The MDL type name is:

  • for array types: the MDL type name of the element type followed by square brackets around the array size (for fixed-sized arrays) or the array size symbol (for deferred-sized arrays). Note that no additional angle brackets are used for deferred-sized arrays.

  • for enum and struct types: the corresponding symbol. This string is fully-qualified, except for enum and structs types from the ::<builtins> module, e.g., "material" or "intensity_mode".

  • for alias types: the MDL type name of the aliased type prefixed by "uniform " or "varying ". Note that named aliases are not yet supported.

  • for all other types: the corresponding reserved word from section 5.7 in [MDLLS].

See also:

create_from_mdl_type_name()

virtual const IType_enum* mi::​neuraylib::​IType_factory::get_predefined_enum( IType_enum::​Predefined_id id) const [pure virtual]

Returns a registered enum type, or NULL if id is unknown.

virtual const IType_struct* mi::​neuraylib::​IType_factory::get_predefined_struct( IType_struct::​Predefined_id id) const [pure virtual]

Returns a registered struct type, or NULL if id is unknown.

virtual const IStruct_category* mi::​neuraylib::​IType_factory::get_predefined_struct_category( IStruct_category::​Predefined_id id) const [pure virtual]

Returns a registered struct category, or NULL if id is unknown.

virtual Sint32 mi::​neuraylib::​IType_factory::is_compatible( const IType* lhs, const IType* rhs) const [pure virtual]

Checks whether two types are (cast-)compatible, i.e. that lhs can be cast to rhs.

lhs is compatible with and therefore can be cast to rhs, if

  • lhs and rhs are of identical type (see mi::neuraylib::IType_factory::compare()).

  • lhs and rhs are of type mi::neuraylib::IType_struct, are conventional structs, have the same number of fields and all fields are pairwise compatible. The names of the fields do not matter, only their order.

  • lhs and rhs are of type mi::neuraylib::IType_enum and both enumeration types have the same set of numerical enumeration values. The names of the enumeration values, their order, or whether multiple enumeration value names share the same numerical value do not matter.

  • lhs and rhs are of type mi::neuraylib::IType_array, both arrays are either immediate-sized or deferred-sized arrays, have the same size, and their element types are compatible.

See also:

mi::neuraylib::IExpression_factory::create_cast().

Parameters

lhs
The first type.
rhs
The second type.

Returns

  • 0: lhs and rhs are compatible, but different types.
  • 1: lhs and rhs are identical types (and therefore compatible).
  • -1: lhs and rhs are not compatible.