The module builder allows to create new MDL modules. More...

#include <imdl_module_builder.h>

Inheritance diagram for mi::neuraylib::IMdl_module_builder:

Public Member Functions
virtual Sint32	add_variant (const char name, const char prototype_name, const IExpression_list defaults, const IAnnotation_block annotations, const IAnnotation_block return_annotations, bool is_exported, bool is_declarative, IMdl_execution_context context)=0
	Adds a variant to the module. More...

virtual Sint32	add_function (const char name, const IExpression body, const IExpression_list temporaries, const IType_list parameters, const IExpression_list defaults, const IAnnotation_list parameter_annotations, const IAnnotation_block annotations, const IAnnotation_block return_annotations, bool is_exported, bool is_declarative, IType::Modifier frequency_qualifier, IMdl_execution_context *context)=0
	Adds a material or function to the module. More...

virtual Sint32	add_annotation (const char name, const IType_list parameters, const IExpression_list defaults, const IAnnotation_list parameter_annotations, const IAnnotation_block annotations, bool is_exported, IMdl_execution_context context)=0
	Adds an annotation to the module. More...

virtual Sint32	add_struct_category (const char name, const IAnnotation_block annotations, bool is_exported, IMdl_execution_context *context)=0
	Adds a struct category the module. More...

virtual Sint32	add_enum_type (const char name, const IExpression_list enumerators, const IAnnotation_list enumerator_annotations, const IAnnotation_block annotations, bool is_exported, IMdl_execution_context *context)=0
	Adds an enum type to the module. More...

virtual Sint32	add_struct_type (const char name, const IType_list fields, const IExpression_list field_defaults, const IAnnotation_list field_annotations, const IAnnotation_block annotations, bool is_exported, bool is_declarative, const IStruct_category struct_category, IMdl_execution_context *context)=0
	Adds a struct type to the module. More...

virtual Sint32	add_constant (const char name, const IExpression expr, const IAnnotation_block annotations, bool is_exported, IMdl_execution_context context)=0
	Adds a constant to the module. More...

virtual Sint32	set_module_annotations (const IAnnotation_block annotations, IMdl_execution_context context)=0
	Sets the annotations of the module itself. More...

virtual Sint32	remove_entity (const char name, Size index, IMdl_execution_context context)=0
	Removes a material, function, enum or struct type from the module. More...

virtual Sint32	clear_module (IMdl_execution_context *context)=0
	Clears the module, i.e., removes all entities from the module. More...

virtual const IArray *	analyze_uniform (const IExpression root_expr, bool root_expr_uniform, IMdl_execution_context context)=0
	Analyzes which parameters need to be uniform. 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< 0x2357f2f8, ... >
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< 0x2357f2f8, ... >
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

The module builder allows to create new MDL modules.

See also: mi::neuraylib::IMdl_factory::create_module_builder()

Member Function Documentation

^◆ add_annotation()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_annotation	(	const char *	name,
		const IType_list *	parameters,
		const IExpression_list *	defaults,
		const IAnnotation_list *	parameter_annotations,
		const IAnnotation_block *	annotations,
		bool	is_exported,
		IMdl_execution_context *	context
	)

pure virtual

Adds an annotation to the module.

Parameters

name	The simple name of the annotation.
parameters	Types and names of the parameters. Can be `nullptr` (treated like an empty parameter list).
defaults	Default values. Can be `nullptr` or incomplete. Feasible sub-expression kinds: constants, calls, and direct calls.
parameter_annotations	Parameter annotations. Can be `nullptr` or incomplete.
annotations	Annotations of the annotation. Can be `nullptr`.
is_exported	Indicates whether the annotation will have the 'export' keyword.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_constant()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_constant	(	const char *	name,
		const IExpression *	expr,
		const IAnnotation_block *	annotations,
		bool	is_exported,
		IMdl_execution_context *	context
	)

pure virtual

Adds a constant to the module.

Parameters

name	The simple name of the constant.
expr	The value of the constant. Feasible sub-expression kinds: constants and direct calls.
annotations	Annotations of the constant. Can be `nullptr`.
is_exported	Indicates whether the constant will have the 'export' keyword.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_enum_type()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_enum_type	(	const char *	name,
		const IExpression_list *	enumerators,
		const IAnnotation_list *	enumerator_annotations,
		const IAnnotation_block *	annotations,
		bool	is_exported,
		IMdl_execution_context *	context
	)

pure virtual

Adds an enum type to the module.

Note: Changing a particular enum type, i.e., removing it and re-adding it differently, is not supported.

Parameters

name	The simple name of the enum type.
enumerators	Enumerators of the enum type. Must not be empty. Feasible sub-expression kinds: constants and direct calls.
enumerator_annotations	Enumerator annotations. Can be `nullptr` or incomplete.
annotations	Annotations of the enum type. Can be `nullptr`.
is_exported	Indicates whether the enum type will have the 'export' keyword.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_function()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_function	(	const char *	name,
		const IExpression *	body,
		const IExpression_list *	temporaries,
		const IType_list *	parameters,
		const IExpression_list *	defaults,
		const IAnnotation_list *	parameter_annotations,
		const IAnnotation_block *	annotations,
		const IAnnotation_block *	return_annotations,
		bool	is_exported,
		bool	is_declarative,
		IType::Modifier	frequency_qualifier,
		IMdl_execution_context *	context
	)

pure virtual

Adds a material or function to the module.

Parameters

name	The simple name of the material or function.
body	The body of the new material or function (a constant, direct call, or parameter reference). Feasible sub-expression kinds: constants, direct calls, parameter references, and temporary references.
temporaries	Temporaries referenced by the body. Feasible sub-expression kinds: constants, direct calls, parameter references, and temporary references with smaller index. The names associated with the expressions in the expressions list are not relevant (but need to unique as usual). Can be `nullptr` (treated like an empty expression list).
parameters	Types and names of the parameters. Can be `nullptr` (treated like an empty parameter list).
defaults	Default values. Can be `nullptr` or incomplete. Feasible sub-expression kinds: constants, calls, and direct calls.
parameter_annotations	Parameter annotations. Can be `nullptr` or incomplete.
annotations	Annotations of the material or function. Can be `nullptr`.
return_annotations	Return annotations of the function. Can be `nullptr` for functions, must be `nullptr` for materials.
is_exported	Indicates whether the material or function will have the 'export' keyword.
is_declarative	Indicates whether the material or function will have the 'declarative' keyword.
frequency_qualifier	The frequency qualifier for functions, or mi::neuraylib::IType::MK_NONE for materials.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_struct_category()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_struct_category	(	const char *	name,
		const IAnnotation_block *	annotations,
		bool	is_exported,
		IMdl_execution_context *	context
	)

pure virtual

Adds a struct category the module.

Parameters

name	The simple name of the struct category.
annotations	Annotations of the struct category. Can be `nullptr`.
is_exported	Indicates whether the struct category will have the 'export' keyword.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_struct_type()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_struct_type	(	const char *	name,
		const IType_list *	fields,
		const IExpression_list *	field_defaults,
		const IAnnotation_list *	field_annotations,
		const IAnnotation_block *	annotations,
		bool	is_exported,
		bool	is_declarative,
		const IStruct_category *	struct_category,
		IMdl_execution_context *	context
	)

pure virtual

Adds a struct type to the module.

Note: Changing a particular struct type, i.e., removing it and re-adding it differently, is not supported.

Parameters

name	The simple name of the enum type.
fields	Fields of the struct type. Must not be empty.
field_defaults	Defaults of the struct fields. Can be `nullptr` or incomplete. Feasible sub-expression kinds: constants and direct calls.
field_annotations	Field annotations of the struct type. Can be `nullptr` or incomplete.
annotations	Annotations of the struct type. Can be `nullptr`.
is_exported	Indicates whether the struct type will have the 'export' keyword.
is_declarative	Indicates whether the struct type will have the 'declarative' keyword.
struct_category	The corresponding struct category. Can be `nullptr`.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ add_variant()

virtual Sint32 mi::neuraylib::IMdl_module_builder::add_variant	(	const char *	name,
		const char *	prototype_name,
		const IExpression_list *	defaults,
		const IAnnotation_block *	annotations,
		const IAnnotation_block *	return_annotations,
		bool	is_exported,
		bool	is_declarative,
		IMdl_execution_context *	context
	)

pure virtual

Adds a variant to the module.

Parameters

name	The simple name of the material or function variant.
prototype_name	The DB name of the prototype of the new variant.
defaults	Additional/new default expressions to set. These defaults are used as arguments in the call expression that defines the variant. An empty expression list implicitly uses the existing defaults, whereas `nullptr` explicitly replicates the existing defaults of the original material or function. Feasible sub-expression kinds: constants and calls.
annotations	Annotations to set. If `nullptr`, the annotations of the original material or function are used. Pass an empty block to remove all annotations.
return_annotations	Return annotations to set. If `nullptr`, the annotations of the original material or function are used. Pass an empty block to remove all annotations. Materials require `nullptr` or an empty annotation block here.
is_exported	Indicates whether the variant will have the 'export' keyword.
is_declarative	Indicates whether the variant will have the 'declarative' keyword.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: 0 in case of success, or -1 in case of failure.

^◆ analyze_uniform()

virtual const IArray * mi::neuraylib::IMdl_module_builder::analyze_uniform	(	const IExpression *	root_expr,
		bool	root_expr_uniform,
		IMdl_execution_context *	context
	)

pure virtual

Analyzes which parameters need to be uniform.

Note that the method can fail if the graph to be analyzed is invalid and/or never uniform independent of uniform modifiers of parameter types.

root_expr_uniform is `false`	root_expr_uniform is `true`	Interpretation
failure	failure	The graph is invalid.
failure	success	This case is not possible.
success	failure	The graph is never uniform.
success	success	The graph is uniform if the parameters returned in the `true` case are made uniform.

If the graph should be uniform, and you cannot rule out invalid graphs, then you might want to invoke this method first with root_expr_uniform set to false to check for validity. If that method succeeds, you can then call it again with root_expr_uniform set to true to obtain the constraints on the parameters.

Parameters

root_expr	Root expression of the graph, i.e., the body of the new material or function. Feasible sub-expression kinds: constants, direct calls, and parameter references.
root_expr_uniform	Indicates whether the root expression should be uniform.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: Returns an array of boolean values indicating which parameters need to be uniform (or nullptr in case of errors). The array indices match the indices of the parameter references. The array might be shorter than expected if trailing parameters are not referenced by root_expr.

^◆ clear_module()

virtual Sint32 mi::neuraylib::IMdl_module_builder::clear_module ( IMdl_execution_context * context )

pure virtual

Clears the module, i.e., removes all entities from the module.

^◆ remove_entity()

virtual Sint32 mi::neuraylib::IMdl_module_builder::remove_entity	(	const char *	name,
		Size	index,
		IMdl_execution_context *	context
	)

pure virtual

Removes a material, function, enum or struct type from the module.

Parameters

name	The simple name of material, function, enum or struct type to be removed.
index	The index of the function with the given name to be removed. Used to distinguish overloads of functions. Zero for materials, enum or struct types.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

^◆ set_module_annotations()

virtual Sint32 mi::neuraylib::IMdl_module_builder::set_module_annotations	(	const IAnnotation_block *	annotations,
		IMdl_execution_context *	context
	)

pure virtual

Sets the annotations of the module itself.

Parameters

annotations	Annotations of the module. Pass `nullptr` to remove existing annotations.
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ add_annotation()

◆ add_constant()

◆ add_enum_type()

◆ add_function()

◆ add_struct_category()

◆ add_struct_type()

◆ add_variant()

◆ analyze_uniform()

◆ clear_module()

◆ remove_entity()

◆ set_module_annotations()

^◆ add_annotation()

^◆ add_constant()

^◆ add_enum_type()

^◆ add_function()

^◆ add_struct_category()

^◆ add_struct_type()

^◆ add_variant()

^◆ analyze_uniform()

^◆ clear_module()

^◆ remove_entity()

^◆ set_module_annotations()