Material Definition Language API nvidia_logo_transpbg.gif Up
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
mi::neuraylib::IMdl_impexp_api Class Referenceabstract

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

Inheritance diagram for mi::neuraylib::IMdl_impexp_api:
mi::base::Interface_declare< 0xd8584ade, 0xa400, 0x486b, 0xab, 0x29, 0x39, 0xcd, 0x87, 0x55, 0x14, 0x5d > mi::base::IInterface

Public Member Functions

virtual Sint32 load_module (ITransaction *transaction, const char *module_name, 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...
 
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) 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...
 
Convenience
virtual const IStringuvtile_marker_to_string (const char *marker, Sint32 u, Sint32 v) const =0
 Resolves a string containing a UDIM/uv-tile marker and a corresponding u,v pair to a pattern as used in the filename of a UDIM/uv-tile sequence. More...
 
virtual const IStringuvtile_string_to_marker (const char *str, const char *marker) const =0
 Replaces the pattern describing the tile index of a UDIM/uv-tile image sequence by the given marker, if the pattern exists in the string. More...
 

Additional Inherited Members

- Public Types inherited from mi::base::Interface_declare< 0xd8584ade, 0xa400, 0x486b, 0xab, 0x29, 0x39, 0xcd, 0x87, 0x55, 0x14, 0x5d >
typedef Interface_declare< id1,
id2, id3, id4, id5, id6, id7,
id8, id9, id10, id11,
IInterface
Self
 Own type. More...
 
typedef Uuid_t< id1, id2, id3,
id4, id5, id6, id7, id8, id9,
id10, id11 > 
IID
 Declares the interface ID (IID) of this interface. More...
 
- Static Public Member Functions inherited from mi::base::Interface_declare< 0xd8584ade, 0xa400, 0x486b, 0xab, 0x29, 0x39, 0xcd, 0x87, 0x55, 0x14, 0x5d >
static bool compare_iid (const Uuid &iid)
 Compares the interface ID iid against the interface ID of this interface and of its ancestors. More...
 

Detailed Description

API component for MDL related import and export operations.

Member Function Documentation

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.
virtual Sint32 mi::neuraylib::IMdl_impexp_api::export_canvas ( const char *  filename,
const ICanvas canvas,
Uint32  quality = 100 
) 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.
Returns
  • 0: Success.
  • -1: Invalid URI.
  • -2: Invalid canvas.
  • -3: Invalid quality.
  • -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
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.
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.
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.
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.

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.
virtual Sint32 mi::neuraylib::IMdl_impexp_api::load_module ( ITransaction transaction,
const char *  module_name,
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.
module_nameThe fully-qualified MDL name of the MDL module (including package names, starting with "::") 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 module name module_name is invalid or a NULL pointer.
  • -2: Failed to find or 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 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.

Parameters
transactionThe transaction to be used.
module_nameThe fully-qualified MDL name of the MDL module (including package names, starting with "::").
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.
virtual const IString* mi::neuraylib::IMdl_impexp_api::uvtile_marker_to_string ( const char *  marker,
Sint32  u,
Sint32 
) const
pure virtual

Resolves a string containing a UDIM/uv-tile marker and a corresponding u,v pair to a pattern as used in the filename of a UDIM/uv-tile sequence.

Parameters
markerstring containing a valid MDL UDIM/uv-tile marker.
uuv-tile position in u-direction
vuv-tile position in v-direction
Returns
a string containing the resolved pattern.
virtual const IString* mi::neuraylib::IMdl_impexp_api::uvtile_string_to_marker ( const char *  str,
const char *  marker 
) const
pure virtual

Replaces the pattern describing the tile index of a UDIM/uv-tile image sequence by the given marker, if the pattern exists in the string.

Parameters
strstring containing the pattern, e.g. _u1_v1
markerthe marker to replace the pattern with
Returns
string with marker or NULL, if a corresponding pattern could not be found.