Member Functions

virtual IMdl_material_instance* mi::​neuraylib::​IMdl_material_definition::create_material_instance( const IAttribute_container* arguments, Sint32* errors = 0) const [pure virtual]

Creates a new material instance.

Parameters

arguments

The arguments of the created material instance. Arguments for parameters without default initializer are mandatory, otherwise optional. The type of an attribute in the attribute container must match the required type for the argument of that name (see get_argument_type()). Any argument not set by an attribute in the attribute container will be set to the default initializer of the corresponding parameter. Note that the values in arguments are copied; passing an attribute container obtained from another MDL interface does not create a link between both instances. NULL is a valid argument which is handled like an empty attribute container.

errors

An optional pointer to an mi::Sint32 to which an error code will be written. The error codes have the following meaning:

• 0: Success.
• -1: An argument for a non-existing parameter was provided in arguments.
• -2: The type of an argument in arguments does not have the correct type, see get_argument_type().
• -3: A parameter that has no default initializer was not provided with an argument value.
• -4: The definition can not be instantiated because it is not exported.

Returns

The created material instance, or NULL in case of errors.

virtual Sint32 mi::​neuraylib::​IMdl_material_definition::create_preset( const char* module_name, const char* preset_name, const IAttribute_container* defaults) const [pure virtual]

Creates a new material definition based on this material definition as prototype. Typically, such a preset is created to change the defaults of an existing material definition. The preset will become the only material definition of a new module.

See also:

mi::neuraylib::IMdl_factory::create_presets() for an alternative way to create presets. In contrast to this method here that method allows to create modules that contain more than one preset. In addition, it allows to attach annotations to presets.

Parameters

module_name

The fully-qualified MDL name of the new module (including package names, starts with "::").

preset_name

The name of the preset (non-qualified, without module prefix). The DB name of the preset is created by prefixing this name with the DB name of the new module plus "::".

defaults

The preset inherits the defaults from the prototype. This parameter allows to change the defaults and/or to add new defaults. The type of an attribute in the attribute container must match the type of the parameter of the same name of the prototype. Note that the values in defaults are copied; passing an attribute container obtained from another MDL interface does not create a link between both instances. NULL is a valid argument which is handled like an empty attribute container.

Returns

• 1: Success (module exists already, creation was skipped).
• 0: Success (module was actually created with the preset as its only material definition).
• -1: The module name module_name is invalid.
• -2: Failed to compile the module module_name.
• -3: The DB name for an imported module is already in use but is not an MDL module, or the DB name for a definition in this module is already in use.
• -4: Initialization of an imported module failed.
• -6: A default for a non-existing parameter was provided in defaults.
• -7: The type of a default in defaults does not have the correct type, see get_argument_type().
• -8: Unspecified error.

virtual const IAttribute_container* mi::​neuraylib::​IMdl_material_definition::get_annotations() const [pure virtual]

Returns the annotations of this material definition.

Returns

The material annotations.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_argument_type( Uint32 index) const [pure virtual]

Returns the type of the argument at index. The type of a given argument is an attachable of the corresponding parameter type. For example, if get_parameter_type() returns "Sint32", this method returns "Attachable<Sint32>".

If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index

The index of the argument.

Returns

The argument type, or NULL if index is out of range.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_argument_type( const char* name) const [pure virtual]

Returns the type of an argument. The type of a given argument is an attachable of the corresponding parameter type. For example, if get_parameter_type() returns "Sint32", this method returns "Attachable<Sint32>".

Parameters

name

The name of the argument.

Returns

The argument type, or NULL if name is invalid.

virtual const IAttachable* mi::​neuraylib::​IMdl_material_definition::get_default( Uint32 index) const [pure virtual]

Returns the default initializer of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index

The index of the parameter.

Returns

The default initializer, or NULL if index is out of range or if there is no default initializer.

template< class T>

const T* mi::​neuraylib::​IMdl_material_definition::get_default( Uint32 index) const [inline]

Returns the default initializer of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

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.

Parameters

index

The index of the parameter.

Returns

The default initializer, or NULL if index is out of range or if there is no default initializer.

virtual const IAttachable* mi::​neuraylib::​IMdl_material_definition::get_default( const char* name) const [pure virtual]

Returns the default initializer of a parameter.

Parameters

name

The name of the parameter.

Returns

The default initializer, or NULL if name is invalid or if there is no default initializer.

template< class T>

const T* mi::​neuraylib::​IMdl_material_definition::get_default( const char* name) const [inline]

Returns the default initializer of a parameter. 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.

Parameters

name

The name of the parameter.

Returns

The default initializer, or NULL if name is invalid or if there is no default initializer.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_module() const [pure virtual]

Returns the DB name of the module containing this material definition. The type of the module is mi::neuraylib::IMdl_module.

Returns

The DB name of the module containing the material definition.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_name() const [pure virtual]

Returns the MDL name of the material definition.

Note:

The MDL name of the material definition is different from the name of the DB element. Use mi::neuraylib::IMdl_compiler::name_of() to obtain the name of the DB element.

Returns

The MDL name of the material definition.

virtual const IAttribute_container* mi::​neuraylib::​IMdl_material_definition::get_parameter_annotations( Uint32 index) const [pure virtual]

Returns the annotations of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index

The index of the parameter.

Returns

The parameter annotations, or NULL if index is out of range.

virtual const IAttribute_container* mi::​neuraylib::​IMdl_material_definition::get_parameter_annotations( const char* name) const [pure virtual]

Returns the annotations of a parameter.

Parameters

name

The name of the parameter.

Returns

The parameter annotations, or NULL if name is invalid.

virtual Uint32 mi::​neuraylib::​IMdl_material_definition::get_parameter_count() const [pure virtual]

Returns the number of parameters.

Returns

The number of parameters.

virtual Sint32 mi::​neuraylib::​IMdl_material_definition::get_parameter_index( const char* name) const [pure virtual]

Returns the index position of a parameter.

Parameters

name

The name of the parameter.

Returns

The index of the parameter, or -1 if name is invalid.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_parameter_name( Uint32 index) const [pure virtual]

Returns the name of the parameter at index.

Parameters

index

The index of the parameter.

Returns

The name of the parameter, or NULL if index is out of range.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_parameter_type( Uint32 index) const [pure virtual]

Returns the type of the parameter at index. If a literal 0 is passed for index, the call is ambiguous. You need to explicitly cast the value to mi::Uint32.

Parameters

index

The index of the parameter.

Returns

The parameter type, or NULL if index is out of range.

virtual const char* mi::​neuraylib::​IMdl_material_definition::get_parameter_type( const char* name) const [pure virtual]

Returns the type of a parameter.

Parameters

name

The name of the parameter.

Returns

The parameter type, or NULL if name is invalid.

virtual bool mi::​neuraylib::​IMdl_material_definition::is_exported() const [pure virtual]

Indicates whether the material definition is exported by its module.

virtual bool mi::​neuraylib::​IMdl_material_definition::is_parameter_type_uniform( Uint32 index) const [pure virtual]

Indicates whether the type of a parameter is uniform.

Parameters

index

The index of the parameter.

Returns

true if the parameter is uniform, otherwise false (including invalid index ).

virtual bool mi::​neuraylib::​IMdl_material_definition::is_parameter_type_uniform( const char* name) const [pure virtual]

Indicates whether the type of a parameter is uniform.

Parameters

name

The name of the parameter.

Returns

true if the parameter is uniform, otherwise false (including invalid name ).