neuray API Programmer's Manual

mi::neuraylib::IFunction_call Class Reference

[MDL-related elements]

Description

This interface represents a function call. A function call is an instance of a formal function definition, with a fixed set of arguments (possibly the defaults of the function definition). Function calls can be created from function definitions using mi::neuraylib::IFunction_definition::create_function_call().

Note:

This interface also supports material instances, which are considered as a special kind of function calls, namely function calls with the return type "material". The interface mi::neuraylib::IMaterial_instance should only be used to create compiled materials.

See also:

mi::neuraylib::IFunction_definition, mi::neuraylib::Argument_editor

mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. Common base interface for all scene elements.Common base interface for all scene elements. mi::base::Interface_declare\< ..., neuraylib::IAttribute_set \>Mixin class template for deriving new interface declarations. The attribute set comprises all attributes attached to a database element.The attribute set comprises all attributes attached to a database element. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Public Member Functions

virtual const IExpression_list* get_arguments() const =0
Returns all arguments.
virtual const char* get_function_definition() const =0
Returns the DB name of the corresponding function definition. More...
virtual const char* get_mdl_function_definition() const =0
Returns the MDL name of the corresponding function definition. More...
virtual Size get_parameter_count() const =0
Returns the number of parameters.
virtual Size get_parameter_index( const char* name) const =0
Returns the index position of a parameter. More...
virtual const char* get_parameter_name( Size index) const =0
Returns the name of the parameter at index. More...
virtual const IType_list* get_parameter_types() const =0
Returns the types of all parameters.
virtual const IType* get_return_type() const =0
Returns the return type of the corresponding function definition.
bool  is_array_constructor() const
Indicates whether this call is an instance of the array constructor. More...
virtual bool  is_default() const =0
Indicates, if this function call acts as a default argument of a material or function definition. More...
virtual bool  is_material() const =0
Indicates whether the call represents a material instance.
virtual bool  is_valid( IMdl_execution_context* context) const =0
Returns true if this function call and all its arguments point to valid material and function definitions, false otherwise. More...
virtual Sint32 repair( Uint32 flags, IMdl_execution_context* context) =0
Attempts to repair an invalid function call. More...
virtual Sint32 reset_argument( Size index) =0
Resets the argument at index. More...
virtual Sint32 reset_argument( const char* name) =0
Resets an argument identified by name. More...
virtual Sint32 set_argument( Size index, const IExpression* argument) =0
Sets the argument at index. More...
virtual Sint32 set_argument( const char* name, const IExpression* argument) =0
Sets an argument identified by name. More...
virtual Sint32 set_arguments( const IExpression_list* arguments) =0
Sets multiple arguments. More...

Member Functions

virtual const IExpression_list* mi::​neuraylib::​IFunction_call::get_arguments() const [pure virtual]

Returns all arguments.

virtual const char* mi::​neuraylib::​IFunction_call::get_function_definition() const [pure virtual]

Returns the DB name of the corresponding function definition. The type of the function definition is mi::neuraylib::IFunction_definition.

Note:

The DB name of the function definition is different from its MDL name (see get_mdl_function_definition()).

virtual const char* mi::​neuraylib::​IFunction_call::get_mdl_function_definition() const [pure virtual]

Returns the MDL name of the corresponding function definition.

Note:

The MDL name of the function definition is different from the name of the DB element (see get_function_definition()).

virtual Size mi::​neuraylib::​IFunction_call::get_parameter_count() const [pure virtual]

Returns the number of parameters.

virtual Size mi::​neuraylib::​IFunction_call::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::​IFunction_call::get_parameter_name( Size 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 IType_list* mi::​neuraylib::​IFunction_call::get_parameter_types() const [pure virtual]

Returns the types of all parameters.

virtual const IType* mi::​neuraylib::​IFunction_call::get_return_type() const [pure virtual]

Returns the return type of the corresponding function definition.

bool mi::​neuraylib::​IFunction_call::is_array_constructor() const [inline]

Indicates whether this call is an instance of the array constructor.

See also:

Arrays

virtual bool mi::​neuraylib::​IFunction_call::is_default() const [pure virtual]

Indicates, if this function call acts as a default argument of a material or function definition. Defaults are immutable, their arguments cannot be changed and they cannot be used in call expressions.

Returns

true , if this function call is a default, false otherwise.

virtual bool mi::​neuraylib::​IFunction_call::is_material() const [pure virtual]

Indicates whether the call represents a material instance.

virtual bool mi::​neuraylib::​IFunction_call::is_valid( IMdl_execution_context* context) const [pure virtual]

Returns true if this function call and all its arguments point to valid material and function definitions, false otherwise. Material and function definitions can become invalid due to a module reload.

See also:

mi::neuraylib::IModule::reload(), mi::neuraylib::IFunction_call::repair()

Parameters

context
Execution context that can be queried for error messages after the operation has finished. Can be NULL.

Returns

  • true: The instance is valid.
  • false: The instance is invalid.

virtual Sint32 mi::​neuraylib::​IFunction_call::repair( Uint32 flags, IMdl_execution_context* context) [pure virtual]

Attempts to repair an invalid function call.

Parameters

flags
Repair options, see mi::neuraylib::Mdl_repair_options.
context
Execution context that can be queried for error messages after the operation has finished. Can be NULL.

Returns

  • 0: Success.
  • -1: Repair failed. Check the context for details.

virtual Sint32 mi::​neuraylib::​IFunction_call::reset_argument( Size index) [pure virtual]

Resets the argument at index. If the function definition has a default for this parameter (and it does not violate a potential uniform requirement), then a clone of it is used as new argument. Otherwise, a constant expression is created, observing range annotations if present (see the overload of mi::neuraylib::IValue_factory::create() with two arguments).

Parameters

index
The index of the argument.

Returns

  • 0: Success.
  • -2: Parameter index does not exist.
  • -4: The function call is immutable (because it appears in a default of a function or material definition).
  • -9: The function call is not valid (see is_valid()).

virtual Sint32 mi::​neuraylib::​IFunction_call::reset_argument( const char* name) [pure virtual]

Resets an argument identified by name. If the function definition has a default for this parameter (and it does not violate a potential uniform requirement), then a clone of it is used as new argument. Otherwise, a constant expression is created, observing range annotations if present (see the overload of mi::neuraylib::IValue_factory::create() with two arguments).

Parameters

name
The name of the parameter.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Parameter name does not exist.
  • -4: The function call is immutable (because it appears in a default of a function or material definition).
  • -9: The function call is not valid (see is_valid()).

virtual Sint32 mi::​neuraylib::​IFunction_call::set_argument( Size index, const IExpression* argument) [pure virtual]

Sets the argument at index.

Parameters

index
The index of the argument.
argument
The argument. Note that the expression is copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. The exception are (immutable) defaults, for which a deep copy is performed.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Parameter index does not exist.
  • -3: The argument type does not match the parameter type.
  • -4: The function call is immutable (because it appears in a default of a function or material definition).
  • -5: The parameter type is uniform, but the argument type is varying.
  • -6: The argument expression is not a constant nor a call.
  • -7: The argument contains references to DB elements in a scope that is more private scope than the scope of this material instance.
  • -8: The parameter types is uniform, but the argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.

virtual Sint32 mi::​neuraylib::​IFunction_call::set_argument( const char* name, const IExpression* argument) [pure virtual]

Sets an argument identified by name.

Parameters

name
The name of the parameter.
argument
The argument. Note that the expression is copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. The exception are (immutable) defaults, for which a deep copy is performed.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Parameter name does not exist.
  • -3: The argument type does not match the parameter type.
  • -4: The function call is immutable (because it appears in a default of a function or material definition).
  • -5: The parameter type is uniform, but the argument type is varying.
  • -6: The argument expression is not a constant nor a call.
  • -7: The argument contains references to DB elements in a scope that is more private scope than the scope of this material instance.
  • -8: The parameter types is uniform, but the argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.

virtual Sint32 mi::​neuraylib::​IFunction_call::set_arguments( const IExpression_list* arguments) [pure virtual]

Sets multiple arguments.

Parameters

arguments
The arguments. Note that the expressions are copied. This copy operation is a shallow copy, e.g., DB elements referenced in call expressions are not copied. The exception are (immutable) defaults, for which a deep copy is performed.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: One of the parameters in arguments does not exist.
  • -3: One of the argument types does not match the corresponding parameter type.
  • -4: The function call is immutable (because it appears in a default of a function or material definition).
  • -5: One of the parameter types is uniform, but the corresponding argument type is varying.
  • -6: One of the arguments is not a constant nor a call.
  • -7: One of the arguments contains references to DB elements in a scope that is more private scope than the scope of this material instance.
  • -8: One of the parameter types is uniform, but the corresponding argument is a call expression and the return type of the called function definition is effectively varying since the function definition itself is varying.