neuray API Programmer's Manual

mi::neuraylib::Mdl_definition_wrapper Class Reference

[Materials (MDL)]

Description

A wrapper around the interfaces for MDL material and function definitions. The purpose of the MDL definition wrapper is to simplify working with MDL material and function definitions. The key benefit is the unified treatment of material and function definitions which avoids duplication of code. For example, a GUI editor for the arguments can be essentially identical for materials and functions.

See mi::neuraylib::IMdl_material_definition and mi::neuraylib::IMdl_function_definition for the underlying interfaces. See also mi::neuraylib::Mdl_argument_editor for a similar wrapper for MDL material instances and function calls.

General methods

 Mdl_definition_wrapper( ITransaction* transaction, const char* name)
Constructs an MDL definition wrapper for a fixed material or function definition. More...
const char* get_argument_type( Uint32 index) const
Returns the type of the argument at index. More...
const char* get_argument_type( const char* name) const
Returns the type of an argument. More...
const char* get_module() const
Returns the DB name of the corresponding module.
const char* get_name() const
Returns the MDL name of the material or function definition.
Uint32 get_parameter_count() const
Returns the number of parameters.
Sint32 get_parameter_index( const char* name) const
Returns the index position of a parameter. More...
const char* get_parameter_name( Uint32 index) const
Returns the name of the parameter at index. More...
const char* get_parameter_type( Uint32 index) const
Returns the type of the parameter at index. More...
const char* get_parameter_type( const char* name) const
Returns the type of a parameter. More...
const char* get_return_type() const
Returns the return type. More...
Element_type get_type() const
Indicates whether the definition wrapper acts on a material definition or on a function definition. More...
bool  is_exported() const
Indicates whether the material or function definition is exported by its module.
bool  is_parameter_type_uniform( Uint32 index) const
Indicates whether the type of a parameter is uniform. More...
bool  is_parameter_type_uniform( const char* name) const
Indicates whether the type of a parameter is uniform. More...
bool  is_return_type_varying() const
Indicates whether the return type is varying. More...
bool  is_valid() const
Indicates whether the definition wrapper is in a valid state. More...

Methods related to argument defaults

template< class T>Sint32 get_default( Uint32 index, T& value) const
Returns the default initializer of a non-array parameter. More...
template< class T>Sint32 get_default( const char* name, T& value) const
Returns the default initializer of a non-array parameter. More...

Methods related to annotations

const IAttribute_container* get_annotations() const
Returns the annotations for a material or function definition.
const IAttribute_container* get_parameter_annotations( Uint32 index) const
Returns the annotations of the parameter at index. More...
const IAttribute_container* get_parameter_annotations( const char* name) const
Returns the annotations of a parameter. More...
const IAttribute_container* get_return_annotations() const
Returns the annotations for the return type. More...

Methods related to instantiation of definitions

IScene_element* create_instance( const IAttribute_container* arguments = 0, Sint32* errors = 0) const
Creates an instance of the material or function definition. More...
template< class T>T* create_instance( const IAttribute_container* arguments = 0, Sint32* errors = 0) const
Creates an instance of the material or function definition. More...

Constructors

mi::​neuraylib::​Mdl_definition_wrapper::Mdl_definition_wrapper( ITransaction* transaction, const char* name) [inline]

Constructs an MDL definition wrapper for a fixed material or function definition.

Parameters

transaction
The transaction to use for all DB interactions.
name
The name of the wrapped material or function definition.

Member Functions

IScene_element* mi::​neuraylib::​Mdl_definition_wrapper::create_instance( const IAttribute_container* arguments = 0, Sint32* errors = 0) const [inline]

Creates an instance of the material or function definition.

Parameters

arguments
If not NULL, then these arguments are used for the material instance or function call (all parameters without default initializer need to be present). If NULL, then the default initializer for a parameter is used, or the argument is default-constructed for parameters without default initializer.
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. If arguments is NULL, then the method always succeeds.
  • -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.

Returns

The constructed material instance or function call, or NULL in case of errors.

template< class T>

T* mi::​neuraylib::​Mdl_definition_wrapper::create_instance( const IAttribute_container* arguments = 0, Sint32* errors = 0) const [inline]

Creates an instance of the material or function definition.

Parameters

arguments
If not NULL, then these arguments are used for the material instance or function call (all parameters without default initializer need to be present). If NULL, then the default initializer for a parameter is used, or the argument is default-constructed for parameters without default initializer.
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. If arguments is NULL, then the method always succeeds.
  • -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.

Returns

The constructed material instance or function call, or NULL in case of errors.

const IAttribute_container* mi::​neuraylib::​Mdl_definition_wrapper::get_annotations() const [inline]

Returns the annotations for a material or function definition.

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_argument_type( Uint32 index) const [inline]

Returns the type of the argument 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 argument.

Returns

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

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_argument_type( const char* name) const [inline]

Returns the type of an argument.

Parameters

name
The name of the argument.

Returns

The argument type, or NULL if name is invalid.

template< class T>

Sint32 mi::​neuraylib::​Mdl_definition_wrapper::get_default( Uint32 index, T& value) const [inline]

Returns the default initializer of a non-array parameter. 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 the parameter in question.
value
The default initializer of the specified parameter.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: index is out of range, or there is no default initializer for this parameter.
  • -3: mi::get_value() failed.

template< class T>

Sint32 mi::​neuraylib::​Mdl_definition_wrapper::get_default( const char* name, T& value) const [inline]

Returns the default initializer of a non-array parameter.

Parameters

name
The name of the parameter in question.
value
The default initializer of the specified parameter.

Returns

  • 0: Success.
  • -1: is_valid() returns false.
  • -2: name is invalid, or there is no default initializer for this parameter.
  • -3: mi::get_value() failed.
const char* mi::​neuraylib::​Mdl_definition_wrapper::get_module() const [inline]

Returns the DB name of the corresponding module.

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_name() const [inline]

Returns the MDL name of the material or function definition.

const IAttribute_container* mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_annotations( Uint32 index) const [inline]

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.

const IAttribute_container* mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_annotations( const char* name) const [inline]

Returns the annotations of a parameter.

Parameters

name
The name of the parameter.

Returns

The parameter annotations, or NULL if name is invalid.

Uint32 mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_count() const [inline]

Returns the number of parameters.

Sint32 mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_index( const char* name) const [inline]

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.

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_name( Uint32 index) const [inline]

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.

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_type( Uint32 index) const [inline]

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.

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_parameter_type( const char* name) const [inline]

Returns the type of a parameter.

Parameters

name
The name of the parameter.

Returns

The parameter type, or NULL if name is invalid.

const IAttribute_container* mi::​neuraylib::​Mdl_definition_wrapper::get_return_annotations() const [inline]

Returns the annotations for the return type.

Returns

The annotation for the return type in case of function definitions, otherwise NULL .

const char* mi::​neuraylib::​Mdl_definition_wrapper::get_return_type() const [inline]

Returns the return type.

Returns

The return type in case of function definitions, otherwise NULL .

Element_type mi::​neuraylib::​Mdl_definition_wrapper::get_type() const [inline]

Indicates whether the definition wrapper acts on a material definition or on a function definition.

Returns

Either mi::neuraylib::ELEMENT_TYPE_MDL_MATERIAL_DEFINITION, or mi::neuraylib::ELEMENT_TYPE_MDL_FUNCTION_DEFINITION, or undefined if is_valid() returns false .

bool mi::​neuraylib::​Mdl_definition_wrapper::is_exported() const [inline]

Indicates whether the material or function definition is exported by its module.

bool mi::​neuraylib::​Mdl_definition_wrapper::is_parameter_type_uniform( Uint32 index) const [inline]

Indicates whether the type of a parameter is uniform. 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

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

bool mi::​neuraylib::​Mdl_definition_wrapper::is_parameter_type_uniform( const char* name) const [inline]

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 ).

bool mi::​neuraylib::​Mdl_definition_wrapper::is_return_type_varying() const [inline]

Indicates whether the return type is varying.

Returns

true if the return type is varying, otherwise false .

bool mi::​neuraylib::​Mdl_definition_wrapper::is_valid() const [inline]

Indicates whether the definition wrapper is in a valid state. The definition wrapper is valid if and only if the name passed in the constructor identifies a material or function definition. This method should be immediately called after invoking the constructor. If it returns false, no other methods of this class should be called.