This interface represents a function call. More...

#include <ifunction_call.h>

Inheritance diagram for mi::neuraylib::IFunction_call:

[legend]

Public Member Functions
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 bool	is_declarative () const =0
	Indicates whether the corresponding function definition is declarative. More...

virtual bool	is_material () const =0
	Indicates whether the call represents a material instance. More...

bool	is_array_constructor () const
	Indicates whether this call is an instance of the array constructor. More...

virtual const IType *	get_return_type () const =0
	Returns the return type of the corresponding function definition. More...

virtual Size	get_parameter_count () const =0
	Returns the number of parameters. More...

virtual const char *	get_parameter_name (Size index) const =0
	Returns the name of the parameter at `index`. More...

virtual Size	get_parameter_index (const char *name) const =0
	Returns the index position of a parameter. More...

virtual const IType_list *	get_parameter_types () const =0
	Returns the types of all parameters. More...

virtual const IExpression_list *	get_arguments () const =0
	Returns all arguments. More...

virtual Sint32	set_arguments (const IExpression_list *arguments)=0
	Sets multiple arguments. 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	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 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_valid (IMdl_execution_context *context) const =0
	Returns `true` if this function call is valid, `false` otherwise. More...

virtual Sint32	repair (Uint32 flags, IMdl_execution_context *context)=0
	Attempts to repair an invalid function call. More...

Public Member Functions inherited from mi::neuraylib::IScene_element
virtual Element_type	get_element_type () const =0
	Indicates the actual scene element represented by interfaces derived from this interface. More...

Public Member Functions inherited from mi::neuraylib::IAttribute_set
virtual IData *	create_attribute (const char name, const char type)=0
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char name, const char type)
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char *name)
	Creates a new attribute `name` of the type `T`. More...

virtual bool	destroy_attribute (const char *name)=0
	Destroys the attribute `name`. More...

virtual const IData *	access_attribute (const char *name) const =0
	Returns a const pointer to the attribute `name`. More...

template<class T>
const T *	access_attribute (const char *name) const
	Returns a const pointer to the attribute `name`. More...

virtual IData *	edit_attribute (const char *name)=0
	Returns a mutable pointer to the attribute `name`. More...

template<class T>
T *	edit_attribute (const char *name)
	Returns a mutable pointer to the attribute `name`. More...

virtual bool	is_attribute (const char *name) const =0
	Indicates existence of an attribute. More...

virtual const char *	get_attribute_type_name (const char *name) const =0
	Returns the type of an attribute. More...

virtual Sint32	set_attribute_propagation (const char *name, Propagation_type value)=0
	Sets the propagation type of the attribute `name`. More...

virtual Propagation_type	get_attribute_propagation (const char *name) const =0
	Returns the propagation type of the attribute `name`. More...

virtual const char *	enumerate_attributes (Sint32 index) const =0
	Returns the name of the attribute indicated by `index`. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0x67b29f5f, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x67b29f5f, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed 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

Member Function Documentation

^◆ get_arguments()

virtual const IExpression_list * mi::neuraylib::IFunction_call::get_arguments ( ) const

pure virtual

Returns all arguments.

^◆ get_function_definition()

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

^◆ 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()).

^◆ get_parameter_count()

virtual Size mi::neuraylib::IFunction_call::get_parameter_count ( ) const

pure virtual

Returns the number of parameters.

^◆ get_parameter_index()

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.

^◆ get_parameter_name()

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 nullptr if index is out of range.

^◆ get_parameter_types()

virtual const IType_list * mi::neuraylib::IFunction_call::get_parameter_types ( ) const

pure virtual

Returns the types of all parameters.

^◆ get_return_type()

virtual const IType * mi::neuraylib::IFunction_call::get_return_type ( ) const

pure virtual

Returns the return type of the corresponding function definition.

^◆ is_array_constructor()

bool mi::neuraylib::IFunction_call::is_array_constructor ( ) const

inline

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

See also: Arrays

^◆ is_declarative()

virtual bool mi::neuraylib::IFunction_call::is_declarative ( ) const

pure virtual

Indicates whether the corresponding function definition is declarative.

Note: This includes, in addition to functions definitions that are explicitly marked as declarative, also function definitions that have been analyzed by the MDL compiler

^◆ is_default()

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.

^◆ is_material()

virtual bool mi::neuraylib::IFunction_call::is_material ( ) const

pure virtual

Indicates whether the call represents a material instance.

This value might differ from the result of mi::neuraylib::IFunction_definition::is_material() in case of the Template-like function definitions .

^◆ is_valid()

virtual bool mi::neuraylib::IFunction_call::is_valid ( IMdl_execution_context * context ) const

pure virtual

Returns true if this function call is valid, false otherwise.

A function call is valid if the call itself and all its arguments point to valid definitions. It can become invalid if one of the involved modules or their (direct or indirect) imports has been reloaded.

Note: This method does not return a static property, but performs a potentially expensive computation.

See also: mi::neuraylib::IModule::is_valid(), mi::neuraylib::IModule::reload(), mi::neuraylib::IModule::reload_from_string(), mi::neuraylib::IFunction_definition::is_valid(), mi::neuraylib::IFunction_call::repair()

Parameters

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

Returns

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

^◆ repair()

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 `nullptr`.

Returns

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

^◆ reset_argument() [1/2]

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

^◆ reset_argument() [2/2]

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

^◆ set_argument() [1/2]

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

pure virtual

Sets an argument identified by name.

This index-based overload set_argument(const char*,const IExpression*) is faster than this name-based overload and should be preferred if the index is known.

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

-10: The definition is non-declarative, but the argument is a declarative call.

^◆ set_argument() [2/2]

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

pure virtual

Sets the argument at index.

This index-based overload is faster than the name-based overload set_argument(const char*,const IExpression*) and should be preferred if the index is known.

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

-10: The definition is non-declarative, but the argument is a declarative call.

^◆ set_arguments()

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 (nullptr).
-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.
-10: The definition is non-declarative, but at least one of the arguments is a declarative call.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ get_arguments()

◆ get_function_definition()

◆ get_mdl_function_definition()

◆ get_parameter_count()

◆ get_parameter_index()

◆ get_parameter_name()

◆ get_parameter_types()

◆ get_return_type()

◆ is_array_constructor()

◆ is_declarative()

◆ is_default()

◆ is_material()

◆ is_valid()

◆ repair()

◆ reset_argument() [1/2]

◆ reset_argument() [2/2]

◆ set_argument() [1/2]

◆ set_argument() [2/2]

◆ set_arguments()

^◆ get_arguments()

^◆ get_function_definition()

^◆ get_mdl_function_definition()

^◆ get_parameter_count()

^◆ get_parameter_index()

^◆ get_parameter_name()

^◆ get_parameter_types()

^◆ get_return_type()

^◆ is_array_constructor()

^◆ is_declarative()

^◆ is_default()

^◆ is_material()

^◆ is_valid()

^◆ repair()

^◆ reset_argument() [1/2]

^◆ reset_argument() [2/2]

^◆ set_argument() [1/2]

^◆ set_argument() [2/2]

^◆ set_arguments()