neuray API Programmer's Manual

mi::neuraylib::IMdl_impexp_api Class Reference

[Miscellaneous MDL-related Interfaces]

Description

API component for MDL related import and export operations.

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

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

Import

virtual Sint32 load_module( ITransaction* transaction, const char* argument, IMdl_execution_context* context = 0) =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 = 0) =0
Loads an MDL module from memory into the database. More...

Export

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...
virtual Sint32 export_canvas( const char* filename, const ICanvas* canvas, const IMap* export_options = 0) 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_module( ITransaction* transaction, const char* module_name, const char* filename, IMdl_execution_context* context = 0) =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 = 0) =0
Exports an MDL module from the database to string. More...

Serialized names

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

Generic reader/writer support

virtual IReader* create_reader( const IBuffer* buffer) const =0
Creates a random-access reader for a given buffer.
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...

Enums

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 = 0
Derive module name from the first search path that matches.
SEARCH_OPTION_USE_SHORTEST = 1
Derive module name from the shortest search path that matches.
SEARCH_OPTION_USE_LONGEST = 2
Derive module name from the longest search path that matches.
SEARCH_OPTION_FORCE_32_BIT = 0xffffffffU

Member Functions

virtual IReader* mi::​neuraylib::​IMdl_impexp_api::create_reader( const IBuffer* buffer) const [pure virtual]

Creates a random-access reader for a given buffer.

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 NULL in case of failures (e.g., there is no such file).

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 NULL in case of failures (e.g., insufficient permissions).

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

Returns

The deserialized function name, or NULL in case of errors.

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

Returns

The deserialized function name, or NULL in case of errors.

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

Returns

The deserialized module name, or NULL in case of errors.

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 NULL.
transmission
The BSDF data for transmission to export. Can be NULL.

Returns

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

virtual Sint32 mi::​neuraylib::​IMdl_impexp_api::export_canvas( const char* filename, const ICanvas* canvas, const IMap* export_options = 0) 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.

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.

virtual Sint32 mi::​neuraylib::​IMdl_impexp_api::export_module( ITransaction* transaction, const char* module_name, const char* filename, IMdl_execution_context* context = 0) [pure virtual]

Exports an MDL module from the database to disk. The following options are supported:

  • "bundle_resources" of type bool: 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.

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.
context
The execution context can be used to pass options to control the behavior of the MDL compiler. During module loading, compiler messages like errors or warnings are stored in the context. Can be NULL.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -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 archive-based resource failed.

virtual Sint32 mi::​neuraylib::​IMdl_impexp_api::export_module_to_string( ITransaction* transaction, const char* module_name, IString* exported_module, IMdl_execution_context* context = 0) [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 MDL compiler. During module loading, compiler messages like errors or warnings are stored in the context. Can be NULL.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -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 archive-based resources is not supported for string-based exports.
  • -6016: The export of an archive-based resource failed.

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 NULL in case of errors.

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 NULL in case of failures.

virtual Sint32 mi::​neuraylib::​IMdl_impexp_api::load_module( ITransaction* transaction, const char* argument, IMdl_execution_context* context = 0) [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.

See also:

mi::neuraylib::IMdl_impexp_api::get_mdl_module_name()

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: During module loading, compiler messages like errors or warnings are stored in the context. Can be NULL.
  • string "internal_space" = "coordinate_object"|"coordinate_world" (default = "coordinate_world")

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 NULL pointer.
  • -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.

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 = 0) [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).

See also:

mi::neuraylib::IMdl_impexp_api::get_mdl_module_name()

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: During module loading, compiler messages like errors or warnings are stored in the context. Can be NULL.
  • string "internal_space" = "coordinate_object"|"coordinate_world" (default = "coordinate_world")

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 NULL pointer.
  • -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.

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 NULL) in all other cases.
return_type
The arguments of the corresponding function call or material instance. Required for the cast operator, ignored (can be NULL) in all other cases.
mdle_callback
A callback to map the filename of MDLE modules. Ignored for non-MDLE modules. Can be NULL (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 NULL.

Returns

The serialized function name, or NULL in case of errors.