MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::IMdl_factory Class Referenceabstract

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

#include <imdl_factory.h>

Inheritance diagram for mi::neuraylib::IMdl_factory:

Public Member Functions

virtual IType_factorycreate_type_factory (ITransaction *transaction)=0
 Returns an MDL type factory for the given transaction. More...
 
virtual IValue_factorycreate_value_factory (ITransaction *transaction)=0
 Returns an MDL value factory for the given transaction. More...
 
virtual IExpression_factorycreate_expression_factory (ITransaction *transaction)=0
 Returns an MDL expression factory for the given transaction. More...
 
virtual IMdl_execution_contextcreate_execution_context ()=0
 Creates an execution context. More...
 
virtual IMdl_execution_contextclone (const IMdl_execution_context *context)=0
 Clones an execution context. More...
 
virtual IValue_texturecreate_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_profilecreate_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_measurementcreate_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_buildercreate_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_transformercreate_module_transformer (ITransaction *transaction, const char *module_name, IMdl_execution_context *context)=0
 Creates a module transformer for a given module. More...
 
virtual const IStringget_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 IStringget_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 IStringdecode_name (const char *name)=0
 Decodes a DB or MDL name. More...
 
virtual const IStringencode_module_name (const char *name)=0
 Encodes a DB or MDL module name. More...
 
virtual const IStringencode_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 IStringencode_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 IInterfaceget_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 IInterfaceget_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
transactionThe transaction to be used.
root_nameDB name of the root node of the graph (material instance or function call).
root_uniformIndicates whether the root node should be uniform.
query_exprA 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_resultIndicates whether query_expr needs to be uniform (or false if query_expr is NULL, or in case of errors).
[out]error_pathA 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.
contextThe 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
transactionThe transaction to be used.
file_pathThe 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.
sharedIndicates 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.
contextAn 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
transactionThe transaction to be used.
file_pathThe 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.
sharedIndicates 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.
contextAn 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
transactionThe transaction to be used.
module_nameThe 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_versionThe initial MDL version of the new module. Ignored if the module exists already.
max_module_versionThe 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.
contextAn 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
transactionThe transaction to be used.
module_nameThe DB name of the MDL module to transform. Builtin modules cannot be transformed.
contextAn 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
transactionThe transaction to be used.
file_pathThe 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.
shapeThe value that is returned by mi::neuraylib::IType_texture::get_shape() on the type corresponding to the return value.
gammaThe value that is returned by mi::neuraylib::ITexture::get_gamma() on the DB element referenced by the return value.
selectorThe selector, or NULL. See section 2.3.1 in [MDLLS] for details.
sharedIndicates 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.
contextAn 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
nameThe 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
nameThe decoded DB or MDL name of a function or material definition without signature.
parameter_typesA 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
nameThe 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
nameThe 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_nameThe 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_nameThe 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.