Factory for various MDL interfaces and functions. More...

#include <imdl_factory.h>

Inheritance diagram for mi::neuraylib::IMdl_factory:

Public Member Functions
virtual IType_factory *	create_type_factory (ITransaction *transaction)=0
	Returns an MDL type factory for the given transaction. More...

virtual IValue_factory *	create_value_factory (ITransaction *transaction)=0
	Returns an MDL value factory for the given transaction. More...

virtual IExpression_factory *	create_expression_factory (ITransaction *transaction)=0
	Returns an MDL expression factory for the given transaction. More...

virtual IMdl_execution_context *	create_execution_context ()=0
	Creates an execution context. More...

virtual IMdl_execution_context *	clone (const IMdl_execution_context *context)=0
	Clones an execution context. More...

virtual IValue_texture *	create_texture (ITransaction transaction, const char file_path, IType_texture::Shape shape, Float32 gamma, const char selector, bool shared, IMdl_execution_context context)=0
	Creates a value referencing a texture identified by an MDL file path. More...

virtual IValue_light_profile *	create_light_profile (ITransaction transaction, const char file_path, bool shared, IMdl_execution_context *context)=0
	Creates a value referencing a light profile identified by an MDL file path. More...

virtual IValue_bsdf_measurement *	create_bsdf_measurement (ITransaction transaction, const char file_path, bool shared, IMdl_execution_context *context)=0
	Creates a value referencing a BSDF measurement identified by an MDL file path. More...

virtual IMdl_module_builder *	create_module_builder (ITransaction transaction, const char module_name, Mdl_version min_module_version, Mdl_version max_module_version, IMdl_execution_context *context)=0
	Creates a module builder for a given module. More...

virtual IMdl_module_transformer *	create_module_transformer (ITransaction transaction, const char module_name, IMdl_execution_context *context)=0
	Creates a module transformer for a given module. More...

virtual const IString *	get_db_module_name (const char *mdl_name)=0
	Returns the DB name for the MDL name of a module (or file path for MDLE modules). More...

virtual const IString *	get_db_definition_name (const char *mdl_name)=0
	Returns the DB name for the MDL name of an material or function definition. More...

virtual void	analyze_uniform (ITransaction transaction, const char root_name, bool root_uniform, const IExpression query_expr, bool &query_result, IString error_path, IMdl_execution_context *context) const =0
	Analyzes whether an expression graph violates the uniform constraints. More...

virtual const IString *	decode_name (const char *name)=0
	Decodes a DB or MDL name. More...

virtual const IString *	encode_module_name (const char *name)=0
	Encodes a DB or MDL module name. More...

virtual const IString *	encode_function_definition_name (const char name, const IArray parameter_types) const =0
	Encodes a DB or MDL function or material definition name. More...

virtual const IString *	encode_type_name (const char *name) const =0
	Encodes an MDL type name. More...

virtual bool	is_valid_mdl_identifier (const char *name) const =0
	Indicates whether the given string is a valid MDL identifier. 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< 0xba936279, ... >
typedef Interface_declare< id1, ... >	Self
	Own type. More...

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

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

Static Public Member Functions inherited from mi::base::Interface_declare< 0xba936279, ... >
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

Factory for various MDL interfaces and functions.

This interface gives access to the type, value, and expressions factories. It also allows to create material and function variants.

Member Function Documentation

^◆ analyze_uniform()

virtual void mi::neuraylib::IMdl_factory::analyze_uniform	(	ITransaction *	transaction,
		const char *	root_name,
		bool	root_uniform,
		const IExpression *	query_expr,
		bool &	query_result,
		IString *	error_path,
		IMdl_execution_context *	context
	)		const

pure virtual

Analyzes whether an expression graph violates the uniform constraints.

Note: This method can be used to check already created graphs, but it can also be used to check whether a hypothetical connection would observe the uniform constraints: First, invoke the method with the root of the existing graph, root_uniform set to false (at least for materials), and query_expr set to the graph node to be replaced. If the call returns with query_result set to false (and no errors in the context), then any (valid) subgraph can be connected. Otherwise, invoke the method again with the root of the to-be-connected subgraph, root_uniform set to true, and query_expr set to NULL. If there are no errors, then the subgraph can be connected.; Make sure that query_expr (if not NULL) can be reached from root_name, otherwise query_result is always false. In particular, arguments passed during call creation (or later for argument changes) are cloned, and the expression that is part of the graph is different from the one that was used to construct the graph (equal, but not identical).

Parameters

	transaction	The transaction to be used.
	root_name	DB name of the root node of the graph (material instance or function call).
	root_uniform	Indicates whether the root node should be uniform.
	query_expr	A node of the call graph for which the uniform property is to be queried. This expression is only used to identify the corresponding node in the graph, i.e., it even makes sense to pass constant expressions (which by themselves are always uniform) to determine whether a to-be-connected call expression has to be uniform. Can be `NULL`.
[out]	query_result	Indicates whether `query_expr` needs to be uniform (or `false` if `query_expr` is `NULL`, or in case of errors).
[out]	error_path	A path to a node of the graph that violates the uniform constraints, or the empty string if there is no such node (or in case of errors). Such violations are also reported via `context`. Can be `NULL`.
	context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `NULL`.

^◆ clone()

virtual IMdl_execution_context * mi::neuraylib::IMdl_factory::clone ( const IMdl_execution_context * context )

pure virtual

Clones an execution context.

Creates a new execution context if context is NULL (as in create_execution_context()). There is no deep copy of option values of type mi::base::IInterface, they are shared by both instances.

Useful to change options temporarily.

^◆ create_bsdf_measurement()

virtual IValue_bsdf_measurement * mi::neuraylib::IMdl_factory::create_bsdf_measurement	(	ITransaction *	transaction,
		const char *	file_path,
		bool	shared,
		IMdl_execution_context *	context
	)

pure virtual

Creates a value referencing a BSDF measurement identified by an MDL file path.

Parameters

transaction	The transaction to be used.
file_path	The absolute MDL file path that identifies the BSDF measurement. The MDL search paths are used to resolve the file path. See section 2.2 in [MDLLS] for details.
shared	Indicates whether you want to re-use the DB element for that BSDF measurement if it has already been loaded, or if you want to create a new DB element in all cases. Note that sharing is based on the location where the BSDF measurement is finally located and includes sharing with instances that have not explicitly been loaded via this method, e.g., BSDF measurements in defaults.
context	An execution context which can be queried for detailed error messages after the operation has finished. Can be `NULL`. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`NULL` pointer). -2: The file path is not an absolute MDL file path. -3: Invalid filename extension (only .mbsdf is supported). -4: Failure to resolve the given filename, e.g., the file does not exist. -5: Failure to open the resolved file. -7: Invalid file format.

Returns: The value referencing the BSDF measurement, or NULL in case of failure.

See also: mi::neuraylib::IBsdf_measurement::reset_file() if you are given a plain filename instead of an MDL file path.

^◆ create_execution_context()

virtual IMdl_execution_context * mi::neuraylib::IMdl_factory::create_execution_context ( )

pure virtual

Creates an execution context.

^◆ create_expression_factory()

virtual IExpression_factory * mi::neuraylib::IMdl_factory::create_expression_factory ( ITransaction * transaction )

pure virtual

Returns an MDL expression factory for the given transaction.

^◆ create_light_profile()

virtual IValue_light_profile * mi::neuraylib::IMdl_factory::create_light_profile	(	ITransaction *	transaction,
		const char *	file_path,
		bool	shared,
		IMdl_execution_context *	context
	)

pure virtual

Creates a value referencing a light profile identified by an MDL file path.

Parameters

transaction	The transaction to be used.
file_path	The absolute MDL file path that identifies the light profile. The MDL search paths are used to resolve the file path. See section 2.2 in [MDLLS] for details.
shared	Indicates whether you want to re-use the DB element for that light profile if it has already been loaded, or if you want to create a new DB element in all cases. Note that sharing is based on the location where the light profile is finally located and includes sharing with instances that have not explicitly been loaded via this method, e.g., light profiles in defaults.
context	An execution context which can be queried for detailed error messages after the operation has finished. Can be `NULL`. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`NULL` pointer). -2: The file path is not an absolute MDL file path. -3: Invalid filename extension (only .ies is supported). -4: Failure to resolve the given filename, e.g., the file does not exist. -5: Failure to open the resolved file. -7: File format error.

Returns: The value referencing the light profile, or NULL in case of failure.

See also: mi::neuraylib::ILightprofile::reset_file() if you are given a plain filename instead of an MDL file path.

^◆ create_module_builder()

virtual IMdl_module_builder * mi::neuraylib::IMdl_factory::create_module_builder	(	ITransaction *	transaction,
		const char *	module_name,
		Mdl_version	min_module_version,
		Mdl_version	max_module_version,
		IMdl_execution_context *	context
	)

pure virtual

Creates a module builder for a given module.

Parameters

transaction	The transaction to be used.
module_name	The DB name of the MDL module to build. If there is no such module, then an empty module with this name and `min_module_version` is created. Otherwise, the existing module is edited. Builtin modules or MDLE modules cannot be built or edited.
min_module_version	The initial MDL version of the new module. Ignored if the module exists already.
max_module_version	The maximal desired MDL version of the module. If higher than the current MDL version of the module, then the module builder will upgrade the MDL version as necessary to handle requests requiring newer features.
context	An execution context which can be queried for detailed error messages after the operation has finished. Can be `NULL`.

Returns: The module builder for the given module, or NULL in case of errors.

^◆ create_module_transformer()

virtual IMdl_module_transformer * mi::neuraylib::IMdl_factory::create_module_transformer	(	ITransaction *	transaction,
		const char *	module_name,
		IMdl_execution_context *	context
	)

pure virtual

Creates a module transformer for a given module.

Parameters

transaction	The transaction to be used.
module_name	The DB name of the MDL module to transform. Builtin modules cannot be transformed.
context	An execution context which can be queried for detailed error messages after the operation has finished. Can be `NULL`.

Returns: The module transformer for the given module, or NULL in case of errors.

^◆ create_texture()

virtual IValue_texture * mi::neuraylib::IMdl_factory::create_texture	(	ITransaction *	transaction,
		const char *	file_path,
		IType_texture::Shape	shape,
		Float32	gamma,
		const char *	selector,
		bool	shared,
		IMdl_execution_context *	context
	)

pure virtual

Creates a value referencing a texture identified by an MDL file path.

Parameters

transaction	The transaction to be used.
file_path	The absolute MDL file path that identifies the texture. The MDL search paths are used to resolve the file path. See section 2.2 in [MDLLS] for details.
shape	The value that is returned by mi::neuraylib::IType_texture::get_shape() on the type corresponding to the return value.
gamma	The value that is returned by mi::neuraylib::ITexture::get_gamma() on the DB element referenced by the return value.
selector	The selector, or `NULL`. See section 2.3.1 in [MDLLS] for details.
shared	Indicates whether you want to re-use the DB elements for that texture if it has already been loaded, or if you want to create new DB elements in all cases. Note that sharing is based on the location where the texture is finally located and includes sharing with instances that have not explicitly been loaded via this method, e.g., textures in defaults.
context	An execution context which can be queried for detailed error messages after the operation has finished. Can be `NULL`. The error codes have the following meaning: 0: Success. -1: Invalid parameters (`NULL` pointer). -2: The file path is not an absolute MDL file path. -3: No image plugin found to handle the file. -4: Failure to resolve the given filename, e.g., the file does not exist. -5: Failure to open the resolved file. -7: The image plugin failed to import the data. -10: Failure to apply the given selector.

Returns: The value referencing the texture, or NULL in case of failure.

See also: mi::neuraylib::IImage::reset_file() if you are given a plain filename instead of an MDL file path.

^◆ create_type_factory()

virtual IType_factory * mi::neuraylib::IMdl_factory::create_type_factory ( ITransaction * transaction )

pure virtual

Returns an MDL type factory for the given transaction.

^◆ create_value_factory()

virtual IValue_factory * mi::neuraylib::IMdl_factory::create_value_factory ( ITransaction * transaction )

pure virtual

Returns an MDL value factory for the given transaction.

^◆ decode_name()

virtual const IString * mi::neuraylib::IMdl_factory::decode_name ( const char * name )

pure virtual

Decodes a DB or MDL name.

Parameters

name	The encoded DB or MDL name to be decoded.

Returns: The decoded DB or MDL name, or NULL if name is NULL.

Note: This method should only be used for display purposes. Do not use the returned name to identify functions or materials since this representation is ambiguous. For modules, it is possible to re-encode their name without loss of information, see encode_module_name(). This is not possible for names of function or material definitions.; This method does not require the corresponding module to be loaded. The method does not check whether the given name is valid, nor whether it is defined in the corresponding module.

^◆ encode_function_definition_name()

virtual const IString * mi::neuraylib::IMdl_factory::encode_function_definition_name	(	const char *	name,
		const IArray *	parameter_types
	)		const

pure virtual

Encodes a DB or MDL function or material definition name.

Parameters

name	The decoded DB or MDL name of a function or material definition without signature.
parameter_types	A static or dynamic array with elements of type mi::IString representing decoded positional parameter type names. The value `NULL` can be used for functions or materials without parameters (treated like an empty array).

Returns: The encoded function or material definition name, or NULL if name or one of the array elements is NULL.

Note: This method does not require the corresponding module to be loaded. The method does not check whether the given name is valid, nor whether it is defined in the corresponding module.

See also: mi::neuraylib::IMdl_factory::encode_module_name(), mi::neuraylib::IMdl_factory::encode_type_name()

^◆ encode_module_name()

virtual const IString * mi::neuraylib::IMdl_factory::encode_module_name ( const char * name )

pure virtual

Encodes a DB or MDL module name.

Parameters

name	The decoded DB or MDL module name to be encoded.

Returns: The encoded DB or MDL module name, or NULL if name is NULL.

Note: This method does not require the corresponding module to be loaded. The method does not check whether the given name is valid.

See also: mi::neuraylib::IMdl_factory::encode_function_definition_name(), mi::neuraylib::IMdl_factory::encode_type_name()

^◆ encode_type_name()

virtual const IString * mi::neuraylib::IMdl_factory::encode_type_name ( const char * name ) const

pure virtual

Encodes an MDL type name.

Parameters

name	The decoded MDL name of a type.

Returns: The encoded MDL name of the type, or NULL if name is NULL.

Note: This method does not require the corresponding module to be loaded. The method does not check whether the given name is valid, nor whether it is defined in the corresponding module.

See also: mi::neuraylib::IMdl_factory::encode_function_definition_name(), mi::neuraylib::IMdl_factory::encode_module_name()

^◆ get_db_definition_name()

virtual const IString * mi::neuraylib::IMdl_factory::get_db_definition_name ( const char * mdl_name )

pure virtual

Returns the DB name for the MDL name of an material or function definition.

For example, given "::state::normal()", the method returns "mdl::state::normal()".

Note: This method does not check for existence of the corresponding DB element, nor does it necessarily reject an invalid material or function definition name.; Usage of this method is strongly recommended instead of manually prepending "mdl", since (a) the mapping is more complicated than that, e.g., for definitions from the ::<builtins> module or MDLE modules, and (b) the mapping might change in the future.

Parameters

mdl_name The MDL name of the material or function definition.

Returns: The DB name of that material or function definition, or NULL if mdl_name was detected as invalid.

^◆ get_db_module_name()

virtual const IString * mi::neuraylib::IMdl_factory::get_db_module_name ( const char * mdl_name )

pure virtual

Returns the DB name for the MDL name of a module (or file path for MDLE modules).

For example, given "::state", the method returns "mdl::state".

Note: This method does not check for existence of the corresponding DB element, nor does it necessarily reject an invalid module name.; Usage of this method is strongly recommended instead of manually prepending "mdl", since (a) the mapping is more complicated than that, e.g., for MDLE modules, and (b) the mapping might change in the future.

Parameters

mdl_name The MDL name of the module (non-MDLE and MDLE module), or the file path of an MDLE module.

Returns: The DB name of that module, or NULL if mdl_name was detected as invalid.

^◆ is_valid_mdl_identifier()

virtual bool mi::neuraylib::IMdl_factory::is_valid_mdl_identifier ( const char * name ) const

pure virtual

Indicates whether the given string is a valid MDL identifier.

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ analyze_uniform()

◆ clone()

◆ create_bsdf_measurement()

◆ create_execution_context()

◆ create_expression_factory()

◆ create_light_profile()

◆ create_module_builder()

◆ create_module_transformer()

◆ create_texture()

◆ create_type_factory()

◆ create_value_factory()

◆ decode_name()

◆ encode_function_definition_name()

◆ encode_module_name()

◆ encode_type_name()

◆ get_db_definition_name()

◆ get_db_module_name()

◆ is_valid_mdl_identifier()

^◆ analyze_uniform()

^◆ clone()

^◆ create_bsdf_measurement()

^◆ create_execution_context()

^◆ create_expression_factory()

^◆ create_light_profile()

^◆ create_module_builder()

^◆ create_module_transformer()

^◆ create_texture()

^◆ create_type_factory()

^◆ create_value_factory()

^◆ decode_name()

^◆ encode_function_definition_name()

^◆ encode_module_name()

^◆ encode_type_name()

^◆ get_db_definition_name()

^◆ get_db_module_name()

^◆ is_valid_mdl_identifier()