Member Functions

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.

query_result

Indicates whether query_expr needs to be uniform (or false if query_expr is NULL, or in case of errors).

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.

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.

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.

See also:

mi::neuraylib::IBsdf_measurement::reset_file() if you are given a plain filename instead of 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.

virtual IMdl_execution_context* mi::​neuraylib::​IMdl_factory::create_execution_context() [pure virtual]

Creates an execution context.

virtual IExpression_factory* mi::​neuraylib::​IMdl_factory::create_expression_factory( ITransaction* transaction) [pure virtual]

Returns an MDL expression factory for the given transaction.

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.

See also:

mi::neuraylib::ILightprofile::reset_file() if you are given a plain filename instead of 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.

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.

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.

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.

See also:

mi::neuraylib::IImage::reset_file() if you are given a plain filename instead of 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.

virtual IType_factory* mi::​neuraylib::​IMdl_factory::create_type_factory( ITransaction* transaction) [pure virtual]

Returns an MDL type factory for the given transaction.

virtual IValue_factory* mi::​neuraylib::​IMdl_factory::create_value_factory( ITransaction* transaction) [pure virtual]

Returns an MDL value factory for the given transaction.

virtual const IString* mi::​neuraylib::​IMdl_factory::decode_name( const char* name) [pure virtual]

Decodes a DB or MDL name.

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.

Parameters

name

The encoded DB or MDL name to be decoded.

Returns

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

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.

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

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 .

virtual const IString* mi::​neuraylib::​IMdl_factory::encode_module_name( const char* name) [pure virtual]

Encodes a DB or MDL module name.

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

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 .

virtual const IString* mi::​neuraylib::​IMdl_factory::encode_type_name( const char* name) const [pure virtual]

Encodes an MDL type name.

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

Parameters

name

The decoded MDL name of a type.

Returns

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

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 check that the input is a valid material or 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 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 is invalid.

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 check that the input is a valid 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 is invalid.

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.