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

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=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_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...
 
virtual Sint32 export_canvas (const char *filename, const ICanvas *canvas, Uint32 quality=100, bool force_default_gamma=false) 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_nameserialize_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_namedeserialize_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_namedeserialize_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_namedeserialize_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 IReadercreate_reader (const IBuffer *buffer) const =0
 Creates a random-access reader for a given buffer. More...
 
virtual IReadercreate_reader (const char *filename) const =0
 Returns a random-access reader for a given file. More...
 
virtual IWritercreate_writer (const char *filename) const =0
 Returns a random-access writer for a given file. More...
 
virtual const IString *MI_NEURAYLIB_DEPRECATED_METHOD_12_1() uvtile_string_to_marker (const char *str, const char *marker) const =0
 
virtual const IString *MI_NEURAYLIB_DEPRECATED_METHOD_12_1() frame_string_to_marker (const char *str, Size digits) 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 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...
 

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 IStringget_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 IStringframe_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, ... >
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< 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

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

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

 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
transactionThe transaction to be used.
function_nameThe serialized name of a function or material definition.
mdle_callbackA 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).
contextThe 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.

 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
transactionThe transaction to be used.
module_nameThe serialized name of a module.
function_name_without_module_nameThe 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_callbackA 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).
contextThe 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.

 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_nameThe serialized name of a module.
mdle_callbackA 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).
contextThe 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.

 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
filenameThe file name of the resource to export the BSDF measurement to.
reflectionThe BSDF data for reflection to export. Can be NULL.
transmissionThe BSDF data for transmission to export. Can be NULL.
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,
Uint32  quality = 100,
bool  force_default_gamma = false 
) 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
filenameThe 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.
canvasThe canvas to export.
qualityThe compression quality is an integer in the range from 0 to 100, where 0 is the lowest quality, and 100 is the highest quality.
force_default_gammaIf enabled, adjusts the gamma value of the exported pixel data according to the pixel type chosen for export (1.0 for HDR pixel types, 2.2 for LDR pixel types).
Returns
  • 0: Success.
  • -1: Invalid file name.
  • -2: Invalid canvas.
  • -3: Invalid quality.
  • -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
filenameThe file name of the resource to export the light profile to.
lightprofileThe 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 = 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
transactionThe transaction to be used.
module_nameThe DB name of the MDL module to export.
filenameThe name of the file to be used for the export.
contextThe 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.

 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 = 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
transactionThe transaction to be used.
module_nameThe DB name of the MDL module to export.
exported_moduleThe exported module source code is written to this string.
contextThe 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.

 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
markerString containing a valid frame and/or uv-tile marker.
fThe frame number of the uv-tile.
uThe u-coordinate of the uv-tile.
vThe 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.

 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
filenameThe filename of an MDL module (excluding MDLE modules).
optionControls 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.

 load_module()

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.

Parameters
transactionThe transaction to be used.
argumentThe MDL name of the module (for non-MDLE modules), or an MDLE file path (absolute or relative to the current working directory).
contextThe 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 NULL.
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.
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 = 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).
Parameters
transactionThe transaction to be used.
module_nameThe MDL name of the module.
module_sourceThe MDL source code of the module.
contextThe 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 NULL.
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.
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_nameThe DB name of the function or material definition.
argument_typesThe arguments of the corresponding function call or material instance. Required for template-like functions, ignored (can be NULL) in all other cases.
return_typeThe arguments of the corresponding function call or material instance. Required for the cast operator, ignored (can be NULL) in all other cases.
mdle_callbackA 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).
contextThe 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.