API component for MDL related import and export operations. More...

#include <imdl_impexp_api.h>

Inheritance diagram for mi::neuraylib::IMdl_impexp_api:

Public Member Functions
Import
virtual Sint32	load_module (ITransaction transaction, const char argument, IMdl_execution_context *context=nullptr)=0
	Loads an MDL module from disk (or a builtin module) into the database. More...

virtual Sint32	load_module_from_string (ITransaction transaction, const char module_name, const char module_source, IMdl_execution_context context=nullptr)=0
	Loads an MDL module from memory into the database. More...

Export
virtual Sint32	export_module (ITransaction transaction, const char module_name, const char filename, IMdl_execution_context context=nullptr)=0
	Exports an MDL module from the database to disk. More...

virtual Sint32	export_module_to_string (ITransaction transaction, const char module_name, IString exported_module, IMdl_execution_context context=nullptr)=0
	Exports an MDL module from the database to string. More...

virtual Sint32	export_canvas (const char filename, const ICanvas canvas, const IMap *export_options=nullptr) const =0
	Exports a canvas to a file on disk. More...

virtual Sint32	export_lightprofile (const char filename, const ILightprofile lightprofile) const =0
	Exports a light profile to disk. More...

virtual Sint32	export_bsdf_data (const char filename, const IBsdf_isotropic_data reflection, const IBsdf_isotropic_data *transmission) const =0
	Exports BSDF data to a file on disk. More...

Serialized names
virtual const ISerialized_function_name *	serialize_function_name (const char definition_name, const IType_list argument_types, const IType return_type, IMdle_serialization_callback mdle_callback, IMdl_execution_context *context) const =0
	Serializes the name of a function or material definition. More...

virtual const IDeserialized_function_name *	deserialize_function_name (ITransaction transaction, const char function_name, IMdle_deserialization_callback mdle_callback, IMdl_execution_context context) const =0
	Deserializes the serialized name of a function or material definition (first overload) More...

virtual const IDeserialized_function_name *	deserialize_function_name (ITransaction transaction, const char module_name, const char function_name_without_module_name, IMdle_deserialization_callback mdle_callback, IMdl_execution_context *context) const =0
	Deserializes the serialized name of a function or material definition (second overload). More...

virtual const IDeserialized_module_name *	deserialize_module_name (const char module_name, IMdle_deserialization_callback mdle_callback, IMdl_execution_context *context) const =0
	Deserializes the serialized name of a module. More...

Generic reader/writer support
virtual IReader *	create_reader (const IBuffer *buffer) const =0
	Creates a random-access reader for a given buffer. More...

virtual IReader *	create_reader (const char *filename) const =0
	Returns a random-access reader for a given file. More...

virtual IWriter *	create_writer (const char *filename) const =0
	Returns a random-access writer for a given file. More...

virtual Sint32	deprecated_export_canvas (const char filename, const ICanvas canvas, Uint32 quality, bool force_default_gamma) const =0

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

Convenience
enum	Search_option { SEARCH_OPTION_USE_FIRST = 0 , SEARCH_OPTION_USE_SHORTEST = 1 , SEARCH_OPTION_USE_LONGEST = 2 , SEARCH_OPTION_FORCE_32_BIT = 0xffffffffU }
	Controls the behavior of mi::neuraylib::IMdl_impexp_api::get_mdl_module_name(). More...

virtual const IString *	get_mdl_module_name (const char *filename, Search_option option=SEARCH_OPTION_USE_FIRST) const =0
	Returns the MDL name for an MDL module identified by its filename. More...

virtual const IString *	frame_uvtile_marker_to_string (const char *marker, Size f, Sint32 u, Sint32 v) const =0
	Replaces a frame and/or uv-tile marker by coordinates of a given uv-tile. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0xd8584ade, ... >
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< 0xd8584ade, ... >
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

API component for MDL related import and export operations.

Member Enumeration Documentation

^◆ Search_option

enum mi::neuraylib::IMdl_impexp_api::Search_option

Controls the behavior of mi::neuraylib::IMdl_impexp_api::get_mdl_module_name().

Enumerator
SEARCH_OPTION_USE_FIRST	Derive module name from the first search path that matches.
SEARCH_OPTION_USE_SHORTEST	Derive module name from the shortest search path that matches.
SEARCH_OPTION_USE_LONGEST	Derive module name from the longest search path that matches.

Member Function Documentation

^◆ create_reader() [1/2]

virtual IReader * mi::neuraylib::IMdl_impexp_api::create_reader ( const char * filename ) const

pure virtual

Returns a random-access reader for a given file.

Parameters

filename The filename of the file to get the reader for.

Returns: A reader that can be used to read the file, or nullptr in case of failures (e.g., there is no such file).

^◆ create_reader() [2/2]

virtual IReader * mi::neuraylib::IMdl_impexp_api::create_reader ( const IBuffer * buffer ) const

pure virtual

Creates a random-access reader for a given buffer.

^◆ create_writer()

virtual IWriter * mi::neuraylib::IMdl_impexp_api::create_writer ( const char * filename ) const

pure virtual

Returns a random-access writer for a given file.

Parameters

filename The filename of the file to get the writer for.

Returns: A writer that can be used to write to that file, or nullptr in case of failures (e.g., insufficient permissions).

^◆ deserialize_function_name() [1/2]

virtual const IDeserialized_function_name * mi::neuraylib::IMdl_impexp_api::deserialize_function_name	(	ITransaction *	transaction,
		const char *	function_name,
		IMdle_deserialization_callback *	mdle_callback,
		IMdl_execution_context *	context
	)		const

pure virtual

Deserializes the serialized name of a function or material definition (first overload)

See also: Serialized names

Parameters

transaction	The transaction to be used.
function_name	The serialized name of a function or material definition.
mdle_callback	A callback to map the filename of MDLE modules. Ignored for non-MDLE modules. Can be `nullptr` (which is treated like a callback implementing the identity transformation).
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: The deserialized function name, or nullptr in case of errors.

^◆ deserialize_function_name() [2/2]

virtual const IDeserialized_function_name * mi::neuraylib::IMdl_impexp_api::deserialize_function_name	(	ITransaction *	transaction,
		const char *	module_name,
		const char *	function_name_without_module_name,
		IMdle_deserialization_callback *	mdle_callback,
		IMdl_execution_context *	context
	)		const

pure virtual

Deserializes the serialized name of a function or material definition (second overload).

If the corresponding module has not been loaded, it will be loaded as a side effect. The method also performs an overload resolution on the deserialized function or material definition (as in mi::neuraylib::IModule::get_function_overloads(const char*,const IArray*)const).

See also: Serialized names

Parameters

transaction	The transaction to be used.
module_name	The serialized name of a module.
function_name_without_module_name	The serialized name of a function or material definition without the module name and `"::"` (as returned by mi::neuraylib::ISerialized_function_name::get_function_name_without_module_name()).
mdle_callback	A callback to map the filename of MDLE modules. Ignored for non-MDLE modules. Can be `nullptr` (which is treated like a callback implementing the identity transformation).
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: The deserialized function name, or nullptr in case of errors.

^◆ deserialize_module_name()

virtual const IDeserialized_module_name * mi::neuraylib::IMdl_impexp_api::deserialize_module_name	(	const char *	module_name,
		IMdle_deserialization_callback *	mdle_callback,
		IMdl_execution_context *	context
	)		const

pure virtual

Deserializes the serialized name of a module.

If the corresponding module has not been loaded, it will be loaded as a side effect. The method also performs an overload resolution on the deserialized function or material definition (as in mi::neuraylib::IModule::get_function_overloads(const char*,const IArray*)const).

See also: Serialized names

Parameters

module_name	The serialized name of a module.
mdle_callback	A callback to map the filename of MDLE modules. Ignored for non-MDLE modules. Can be `nullptr` (which is treated like a callback implementing the identity transformation).
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: The deserialized module name, or nullptr in case of errors.

^◆ export_bsdf_data()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_bsdf_data	(	const char *	filename,
		const IBsdf_isotropic_data *	reflection,
		const IBsdf_isotropic_data *	transmission
	)		const

pure virtual

Exports BSDF data to a file on disk.

Parameters

filename	The file name of the resource to export the BSDF measurement to.
reflection	The BSDF data for reflection to export. Can be `nullptr`.
transmission	The BSDF data for transmission to export. Can be `nullptr`.

Returns

0: Success.
-1: Invalid file name.
-4: Unspecified failure.

^◆ export_canvas()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_canvas	(	const char *	filename,
		const ICanvas *	canvas,
		const IMap *	export_options = `nullptr`
	)		const

pure virtual

Exports a canvas to a file on disk.

If the image plugin that is selected for the export based on the filename parameter is not capable of handling the pixel type of canvas, the canvas is internally converted into one of the pixel types supported by that image plugin for export. If the image plugin supports multiple pixel types for export, the "best" of them (w.r.t. the pixel type of the canvas) is chosen.

The "best" pixel type is determined by attempting to apply the following conversions in the given order to the pixel type of the canvas:

use an equivalent pixel type ("Color" instead of "Float32<4>" and vice versa, similar for "Rgb_fp" / "Float32<3>" and "Rgba" / "Sint32"),
add an alpha channel (if not already present),
increase bits per channel (smaller increase preferred),
add additional channels (if possible),
decrease bits per channel (smaller decrease preferred), and
drop one or more channels.

Parameters

filename	The file name of the resource to export the canvas to. The ending of the file name determines the image format, e.g., `".jpg"`. Note that support for a given image format requires an image plugin capable of handling that format.
canvas	The canvas to export.
export_options	See Image export options for supported options.

Returns

0: Success.
-1: Invalid file name.
-2: Invalid canvas.
-4: Unspecified failure.

^◆ export_lightprofile()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_lightprofile	(	const char *	filename,
		const ILightprofile *	lightprofile
	)		const

pure virtual

Exports a light profile to disk.

Parameters

filename	The file name of the resource to export the light profile to.
lightprofile	The light profile to export.

Returns

0: Success.
-1: Invalid file name.
-2: Invalid light profile.
-4: Unspecified failure.

^◆ export_module()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_module	(	ITransaction *	transaction,
		const char *	module_name,
		const char *	filename,
		IMdl_execution_context *	context = `nullptr`
	)

pure virtual

Exports an MDL module from the database to disk.

The following options are supported:

bool "bundle_resources": If true, referenced resources are exported into the same directory as the module, even if they can be found via the module search path. Default: false.
bool "export_resources_with_module_prefix": If true, the name of the exported resources start with the module name as prefix. Default: true.
std::string "handle_filename_conflicts": Controls what to do in case of filename conflicts for resources during export. Possible values:
- "generate_unique": Always generates a unique filename that does not conflict with an existing resource file (adding a counter suffix if necessary).
- "fail_if_existing": The export fails if an existing resource file would be overwritten by the export operation.
- "overwrite_existing": The export operation silently overwrites existing resource files. Note that using this setting might destroy other modules. Setting the option "export_resources_with_module_prefix" (see above) to true reduces that risk (but does not eliminate it). Default: "generate_unique".

Parameters

transaction	The transaction to be used.
module_name	The DB name of the MDL module to export.
filename	The name of the file to be used for the export. Note that the context option "handle_filename_conflicts" affects only resources, not modules: if this file exists already, it will be overwritten.
context	The execution context can be used to pass options to control the behavior of the export operation. Messages like errors or warnings are stored in the context. Can be `nullptr`.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-2: Failed to open filename for write operations.
-6002: There is no MDL module in the database of the given name.
-6003: The export failed for unknown reasons.
-6004: The MDL module can not be exported since it is a builtin module.
-6005: The MDL module can not be exported since filename does not result in a valid MDL identifier.
-6010: Incorrect type for a referenced resource.
-6013: The export of a file-based resource failed.
-6014: The export of a memory-based resource failed.
-6016: The export of an container-based resource failed.

^◆ export_module_to_string()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_module_to_string	(	ITransaction *	transaction,
		const char *	module_name,
		IString *	exported_module,
		IMdl_execution_context *	context = `nullptr`
	)

pure virtual

Exports an MDL module from the database to string.

Note: See load_module_from_string() for limitations of string-based modules.

Parameters

transaction	The transaction to be used.
module_name	The DB name of the MDL module to export.
exported_module	The exported module source code is written to this string.
context	The execution context can be used to pass options to control the behavior of the export operation. Messages like errors or warnings are stored in the context. Can be `nullptr`.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-6002: There is no MDL module in the database of the given name.
-6003: The export failed for unknown reasons.
-6004: The MDL module can not be exported since it is a builtin module.
-6006: The option bundle_resources is not supported for string-based exports.
-6010: Incorrect type for a referenced resource.
-6011: The export of file-based resources is not supported for string-based exports.
-6012: The export of memory-based resources is not supported for string-based exports.
-6013: The export of a file-based resource failed.
-6014: The export of a memory-based resource failed.
-6015: The export of container-based resources is not supported for string-based exports.
-6016: The export of an container-based resource failed.

^◆ frame_uvtile_marker_to_string()

virtual const IString * mi::neuraylib::IMdl_impexp_api::frame_uvtile_marker_to_string	(	const char *	marker,
		Size	f,
		Sint32	u,
		Sint32	v
	)		const

pure virtual

Replaces a frame and/or uv-tile marker by coordinates of a given uv-tile.

Parameters

marker	String containing a valid frame and/or uv-tile marker.
f	The frame number of the uv-tile.
u	The u-coordinate of the uv-tile.
v	The v-coordinate of the uv-tile.

Returns: String with the frame and/or uv-tile marker replaced by the coordinates of the uv-tile, or nullptr in case of errors.

^◆ get_mdl_module_name()

virtual const IString * mi::neuraylib::IMdl_impexp_api::get_mdl_module_name	(	const char *	filename,
		Search_option	option = `SEARCH_OPTION_USE_FIRST`
	)		const

pure virtual

Returns the MDL name for an MDL module identified by its filename.

The return value can be passed to mi::neuraylib::IMdl_impexp_api::load_module() or mi::neuraylib::IMdl_factory::get_db_module_name().

Note: This method does not support MDLE modules. This is also not necessary, since in case of MDLEs the filename can be directly passed to mi::neuraylib::IMdl_impexp_api::load_module() or mi::neuraylib::IMdl_factory::get_db_module_name().

Parameters

filename	The filename of an MDL module (excluding MDLE modules).
option	Controls the algorithm's behavior if several overlapping search paths contain the given filename.

Returns: The MDL name of the given module, or nullptr in case of failures.

^◆ load_module()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::load_module	(	ITransaction *	transaction,
		const char *	argument,
		IMdl_execution_context *	context = `nullptr`
	)

pure virtual

Loads an MDL module from disk (or a builtin module) into the database.

The module is located on disk according to the module search paths (see mi::neuraylib::IMdl_configuration::add_mdl_path()), loaded, and compiled. If successful, the method creates DB elements for the module and all its imported modules, as well as for all material and function definitions contained in these modules.

The method can also be used for builtin modules for which the first step, locating the module on disk, is skipped.

Parameters

transaction	The transaction to be used.
argument	The MDL name of the module (for non-MDLE modules), or an MDLE file path (absolute or relative to the current working directory).
context	The execution context can be used to pass options to control the behavior of the MDL compiler. The following options are supported by this operation: string "internal_space" = "coordinate_object"\|"coordinate_world" (default = "coordinate_world") During module loading, compiler messages like errors or warnings are stored in the context. Can be `nullptr`.

Returns

1: Success (module exists already, loading from file was skipped).
0: Success (module was actually loaded from file or is a builtin module).
-1: The MDL module name/MDLE file path argument is invalid or a nullptr.
-2: Failed to find or to compile the module argument.
-3: The DB name for an imported module is already in use but is not an MDL module, or the DB name for a definition in this module is already in use.
-4: Initialization of an imported module failed.

See also: mi::neuraylib::IMdl_impexp_api::get_mdl_module_name()

^◆ load_module_from_string()

virtual Sint32 mi::neuraylib::IMdl_impexp_api::load_module_from_string	(	ITransaction *	transaction,
		const char *	module_name,
		const char *	module_source,
		IMdl_execution_context *	context = `nullptr`
	)

pure virtual

Loads an MDL module from memory into the database.

The provided module source is compiled. If successful, the method creates DB elements for the module and all its imported modules, as well as for all material and function definitions contained in these modules.

Note

String-based module have limitations compared to regular modules loaded from disk:

no support for resources, and
string-based modules referenced in an import statement need to be loaded explicitly upfront (no automatic recursive loading as for file-based modules).

Parameters

transaction	The transaction to be used.
module_name	The MDL name of the module.
module_source	The MDL source code of the module.
context	The execution context can be used to pass options to control the behavior of the MDL compiler. The following options are supported by this operation: string "internal_space" = "coordinate_object"\|"coordinate_world" (default = "coordinate_world") During module loading, compiler messages like errors or warnings are stored in the context. Can be `nullptr`.

Returns

1: Success (module exists already, creating from module_source was skipped).
0: Success (module was actually created from module_source).
-1: The module name module_name is invalid, or module_name or module_source is a nullptr.
-2: Shadows a file-based module or failed to compile the module module_name.
-3: The DB name for an imported module is already in use but is not an MDL module, or the DB name for a definition in this module is already in use.
-4: Initialization of an imported module failed.

See also: mi::neuraylib::IMdl_impexp_api::get_mdl_module_name()

^◆ serialize_function_name()

virtual const ISerialized_function_name * mi::neuraylib::IMdl_impexp_api::serialize_function_name	(	const char *	definition_name,
		const IType_list *	argument_types,
		const IType *	return_type,
		IMdle_serialization_callback *	mdle_callback,
		IMdl_execution_context *	context
	)		const

pure virtual

Serializes the name of a function or material definition.

See also: Serialized names

Parameters

definition_name	The DB name of the function or material definition.
argument_types	The arguments of the corresponding function call or material instance. Required for template-like functions, ignored (can be `nullptr`) in all other cases.
return_type	The arguments of the corresponding function call or material instance. Required for the cast operator, ignored (can be `nullptr`) in all other cases.
mdle_callback	A callback to map the filename of MDLE modules. Ignored for non-MDLE modules. Can be `nullptr` (which is treated like a callback implementing the identity transformation).
context	The execution context can be used to pass options and to retrieve error and/or warning messages. Can be `nullptr`.

Returns: The serialized function name, or nullptr in case of errors.

Public Member Functions

Convenience

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Search_option

Member Function Documentation

◆ create_reader() [1/2]

◆ create_reader() [2/2]

◆ create_writer()

◆ deserialize_function_name() [1/2]

◆ deserialize_function_name() [2/2]

◆ deserialize_module_name()

◆ export_bsdf_data()

◆ export_canvas()

◆ export_lightprofile()

◆ export_module()

◆ export_module_to_string()

◆ frame_uvtile_marker_to_string()

◆ get_mdl_module_name()

◆ load_module()

◆ load_module_from_string()

◆ serialize_function_name()

^◆ Search_option

^◆ create_reader() [1/2]

^◆ create_reader() [2/2]

^◆ create_writer()

^◆ deserialize_function_name() [1/2]

^◆ deserialize_function_name() [2/2]

^◆ deserialize_module_name()

^◆ export_bsdf_data()

^◆ export_canvas()

^◆ export_lightprofile()

^◆ export_module()

^◆ export_module_to_string()

^◆ frame_uvtile_marker_to_string()

^◆ get_mdl_module_name()

^◆ load_module()

^◆ load_module_from_string()

^◆ serialize_function_name()