This interface is used to export files. More...

#include <iexport_api.h>

Inheritance diagram for mi::neuraylib::IExport_api:

Public Member Functions
Export operations
virtual const IExport_result *	export_scene (ITransaction transaction, const char uri, const char rootgroup, const char caminst=nullptr, const char options=nullptr, const IMap exporter_options=nullptr) const =0
	Exports a scene. More...

virtual const IExport_result *	export_elements (ITransaction transaction, const char uri, const IArray elements, const IMap exporter_options=nullptr) const =0
	Exports scene elements. More...

virtual const IExport_result *	export_elements_to_string (ITransaction transaction, const IArray elements, const char file_extension, IString result_string, const IMap *exporter_options=nullptr) const =0
	Exports scene elements to string. More...

virtual Sint32	export_canvas (const char uri, 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 uri, const ILightprofile lightprofile) const =0
	Exports a light profile to disk. More...

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

virtual Sint32	export_volume_data (const char uri, const char selectors[], const IVolume_data *data[], Size count) const =0
	Exports a number of volume data sets to a file. More...

Exporter introspection
virtual Size	get_exporter_length () const =0
	Returns the number of registered exporters. More...

virtual const IExporter *	get_exporter (Size index) const =0
	Returns a registered exporter. More...

virtual const IExporter *	select_exporter_by_extension (const char *extension) const =0
	Returns the exporter that would be used for a particular file name extension. More...

virtual IWriter *	get_writer (const char *uri) const =0
	Returns a random-access writer that can be used to export to the given resource. More...

Utility methods
virtual const IString *	convert_filename_to_uri (const char *filename) const =0
	Converts a filename into a URI. More...

virtual const IString *	convert_uri_to_filename (const char *uri) const =0
	Converts a URI into a filename. More...

virtual const IArray *	get_export_dependencies (ITransaction transaction, const char rootgroup, const char caminst, const char options) const =0
	Returns scene dependencies suitable for an export operation. 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...

virtual Sint32	deprecated_export_canvas (const char uri, 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...

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

This interface is used to export files.

Member Function Documentation

^◆ convert_filename_to_uri()

virtual const IString * mi::neuraylib::IExport_api::convert_filename_to_uri ( const char * filename ) const

pure virtual

Converts a filename into a URI.

Returns nullptr if filename is nullptr. Otherwise returns a URI without URI scheme and URI authority. The URI path is constructed from the filename according to the following rules.

On Linux and MacOS X, the URI path equals the filename. On Windows, slashes in relative URI paths are replaced by backslashes to obtain the filename. Absolute URI paths are mapped to file system paths according to the following table.

Filename	URI path	Comment
C:\dir1\dir2\file	/C:/dir1/dir2/file	-
\dir1\dir2\file	/dir1/dir2/file	-
\\share\dir1\dir2\file	//share/dir1/dir2/file	Note that an empty URI authority (`//`) is prepended since otherwise the share name is interpreted as URI authority.

Note: There are no checks whether filename identifies an existing file, or whether that file is readable. The filename is simply converted to a URI according to some fixed rules.; This method does not support filenames with hashes or question marks.; This method does not understand the special variable "${shader}".

See also: Importer and Exporter for general information about URIs.

^◆ convert_uri_to_filename()

virtual const IString * mi::neuraylib::IExport_api::convert_uri_to_filename ( const char * uri ) const

pure virtual

Converts a URI into a filename.

Returns nullptr if

uri is nullptr,
the URI scheme is non-empty and different from "file",
the URI authority is non-empty, or
the URI path is empty.

In all other cases the URI path is converted into a filename according to the following rules.

On Linux and MacOS X, the filename equals the URI path. On Windows, backslashes in relative filenames are converted to slashes to obtain the URI path. Absolute filenames are mapped to URI paths according to the following table.

URI path	Filename	Comment
/C:/dir1/dir2/file	C:\dir1\dir2\file	-
/C/dir1/dir2/file	C:\dir1\dir2\file	This mapping is supported in addition to the first one since a colon is a reserved character in URIs.
/dir1/dir2/file	\dir1\dir2\file	This mapping is only supported for top-level directory names not consisting of a single letter.
//share/dir1/dir2/file	\\share\dir1\dir2\file	This mapping requires an (otherwise optional) empty URI authority (`//`) since otherwise the share name is interpreted as URI authority.

Note: There are no checks whether uri identifies an existing file, or whether that file is readable. The URI is simply converted to a filename according to some fixed rules.; This method does not support filenames with hashes or question marks.; This method does not understand the special variable "${shader}".

See also: Importer and Exporter for general information about URIs.

^◆ export_bsdf_data()

virtual Sint32 mi::neuraylib::IExport_api::export_bsdf_data	(	const char *	uri,
		const IBsdf_isotropic_data *	reflection,
		const IBsdf_isotropic_data *	transmission
	)		const

pure virtual

Exports BSDF data to a file on disk.

See Importer and Exporter for the URI naming conventions supported for the uri parameter.

Parameters

uri	The URI of the resource to export the BSDF data 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 URI.
-4: Unspecified failure.

^◆ export_canvas()

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

pure virtual

Exports a canvas to a file on disk.

See Importer and Exporter for the URI naming conventions supported for the uri parameter.

If the image plugin that is selected for the export based on the uri 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

uri	The URI of the resource to export the canvas to. The ending of the URI 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 URI.
-2: Invalid canvas.
-4: Unspecified failure.

^◆ export_elements()

virtual const IExport_result * mi::neuraylib::IExport_api::export_elements	(	ITransaction *	transaction,
		const char *	uri,
		const IArray *	elements,
		const IMap *	exporter_options = `nullptr`
	)		const

pure virtual

Exports scene elements.

This method is equivalent to export_scene(), except that all named elements in the string array elements are exported to the file. If the recurse option is true, any elements referenced by those elements are written as well.

In addition to exporter-specific options, every exporter supports the following standard options:

"strip_prefix" of type mi::IString: This prefix is stripped from the names of all exported elements if they have the same prefix. This option can be used to undo the effect of the "prefix" option for import operations. Default: the empty string.
"recurse" of type mi::IBoolean: If true, any elements referenced by the elements in the elements array are exported as well, similar to the automatic recursion applied by export_scene(). Default: true.
"time_stamp" of type mi::IString: If not empty only the passed list of elements along with elements referenced by those that have been changed or added since the time identified by the time stamp are written. Other elements are omitted from the file, but not from recursion: an old element referencing an edited sub-element is not written, but the sub-element is. You can use the method mi::neuraylib::ITransaction::get_time_stamp() to get a time stamp. Default: the empty string.

You can use export_elements() to write incremental changes to be appended to an existing file, which is for example supported with the .mi file format. The elements listed in the elements array are supposed to be independent entry points into the scene graph that need to be visited for the export. In the case that the "recurse" option is true, the export can handle duplicate entries and possible dependencies correctly. If the "recurse" option is false, the export cannot detect duplicates or dependencies automatically, in which case you should avoid duplicates and list in the elements array elements that are referenced before the elements that reference them.

Parameters

transaction	The transaction to be used.
uri	The URI of the file to export to. See Importer and Exporter for the supported URI naming conventions.
elements	A static or dynamic array of strings containing the names of elements to be exported.
exporter_options	The exporter options (see above).

Returns

The export result uses the following error codes.

0: The export operation was successful.
1: The passed URI is invalid (malformed).
2: The Iray SDK failed to create an instance of mi::neuraylib::IWriter for the given URI, most probably because it was unable to open the specified file, e.g., because the directory does not exist, or the user has insufficient permissions.
3: There is no appropriate exporter for the requested file format.
4: The exporter failed to create the instance of mi::neuraylib::IImpexp_state.
5: The exporter did not return a valid instance of mi::neuraylib::IExport_result.
6: The option '...' has an invalid type.
7: The option '...' has an invalid value.
8: The array elements is empty, contains elements that are not strings, or for at least one of the given names there is no DB element with that name.
6000-7999: Reserved for exporter-specific error codes.

The severity of all listed errors (excluding the exporter-specific error codes) is mi::base::details::MESSAGE_SEVERITY_ERROR. There might be other undocumented error codes.

^◆ export_elements_to_string()

virtual const IExport_result * mi::neuraylib::IExport_api::export_elements_to_string	(	ITransaction *	transaction,
		const IArray *	elements,
		const char *	file_extension,
		IString *	result_string,
		const IMap *	exporter_options = `nullptr`
	)		const

pure virtual

Exports scene elements to string.

This method is equivalent to export_elements(), except that the exported elements are not exported to a file, but to a string in memory.

Parameters

transaction	The transaction to be used.
elements	A static or dynamic array of strings containing the names of elements to be exported.
file_extension	The file extension. Since there is no file name/URI in this variant, this string is used to select the exporter, e.g., `".mdl"`.
result_string	The string that holds the exported scene elements.
exporter_options	The exporter options (see export_elements()).

Returns: See export_elements().

^◆ export_lightprofile()

virtual Sint32 mi::neuraylib::IExport_api::export_lightprofile	(	const char *	uri,
		const ILightprofile *	lightprofile
	)		const

pure virtual

Exports a light profile to disk.

See Importer and Exporter for the URI naming conventions supported for the uri parameter.

Parameters

uri	The URI of the resource to export the light profile to.
lightprofile	The light profile to export.

Returns

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

^◆ export_scene()

virtual const IExport_result * mi::neuraylib::IExport_api::export_scene	(	ITransaction *	transaction,
		const char *	uri,
		const char *	rootgroup,
		const char *	caminst = `nullptr`,
		const char *	options = `nullptr`,
		const IMap *	exporter_options = `nullptr`
	)		const

pure virtual

Exports a scene.

Exports the scene identified by the root group, an optional camera instance, and optional scene options to a file. Any elements directly or indirectly referenced by these three elements are also exported.

In addition to exporter-specific options, every exporter supports the following standard option:

"strip_prefix" of type mi::IString: This prefix is stripped from the names of all exported elements if they have the same prefix. This option can be used to undo the effect of the "prefix" option for import operations. Default: the empty string.

Parameters

transaction	The transaction to be used.
uri	The URI of the file to export to. See Importer and Exporter for the supported URI naming conventions.
rootgroup	The root group.
caminst	The camera instance (optional), or `nullptr`.
options	The scene options (optional), or `nullptr`.
exporter_options	The exporter options (see above).

Returns

The export result uses the following error codes.

0: The export operation was successful.
1: The passed URI is invalid (malformed).
2: The Iray SDK failed to create an instance of mi::neuraylib::IWriter for the given URI, most probably because it was unable to open the specified file, e.g., because the directory does not exist, or the user has insufficient permissions.
3: There is no appropriate exporter for the requested file format.
4: The exporter failed to create the instance of mi::neuraylib::IImpexp_state.
5: The exporter did not return a valid instance of mi::neuraylib::IExport_result.
6: The option '...' has an invalid type.
7: The option '...' has an invalid value.
6000-7999: Reserved for exporter-specific error codes.

The severity of all listed errors (excluding the exporter-specific error codes) is mi::base::details::MESSAGE_SEVERITY_ERROR. There might be other undocumented error codes.

^◆ export_volume_data()

virtual Sint32 mi::neuraylib::IExport_api::export_volume_data	(	const char *	uri,
		const char *	selectors[],
		const IVolume_data *	data[],
		Size	count
	)		const

pure virtual

Exports a number of volume data sets to a file.

This function writes each of the data sets in data to the file specified by uri and stores it under the appropriate selector in selectors.

Note that mi::neuraylib::IVolume_data::export_file() provides simpler functionality for cases where only one data set is to be exported.

See also: mi::neuraylib::IVolume_data::export_file()

Parameters

uri	The URI of the resource to export the volume data to.
selectors	An array of `count` selectors, one for each data set.
data	The data sets to be written to `uri`.
count	The number of data sets.

Returns

0: Success.
-1: Invalid URI.
-4: Failure to export.

^◆ frame_uvtile_marker_to_string()

virtual const IString * mi::neuraylib::IExport_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_export_dependencies()

virtual const IArray * mi::neuraylib::IExport_api::get_export_dependencies	(	ITransaction *	transaction,
		const char *	rootgroup,
		const char *	caminst,
		const char *	options
	)		const

pure virtual

Returns scene dependencies suitable for an export operation.

This method is intended for implementers of mi::neuraylib::IExporter::export_scene(). Given a root group, a camera instance, and the scene options, it computes the list of dependent scene elements. The list is ordered such that referenced scene elements appear before they are referenced.

The result is similar to the result of mi::neuraylib::ITransaction::list_elements(), except that the result is ordered (see above) and might be optimized for export operations. For example, dependencies of mi::neuraylib::IModule are not reported since an exporter does not have to deal with them -- importing the module itself is sufficient. Similarly, MDL material and function definitions are replaced by the corresponding module.

Parameters

transaction	The transaction to be used.
rootgroup	The root group, or `nullptr` to ignore this parameter.
caminst	The camera instance, or `nullptr` to ignore this parameter.
options	The scene options, or `nullptr` to ignore this parameter.

Returns: The ordered list of dependencies of rootgroup, caminst, and options, or nullptr in case of errors (invalid transaction or non-existing rootgroup, caminst, or options).

^◆ get_exporter()

virtual const IExporter * mi::neuraylib::IExport_api::get_exporter ( Size index ) const

pure virtual

Returns a registered exporter.

See also: mi::neuraylib::IExport_api::get_exporter_length(), mi::neuraylib::IExtension_api::register_exporter()

Parameters

index The index of the requested exporter.

Returns: The requested exporter, or nullptr if index is out of bounds.

^◆ get_exporter_length()

virtual Size mi::neuraylib::IExport_api::get_exporter_length ( ) const

pure virtual

Returns the number of registered exporters.

See also: mi::neuraylib::IExport_api::get_exporter(), mi::neuraylib::IExtension_api::register_exporter()

Returns: The number of registered exporters.

^◆ get_writer()

virtual IWriter * mi::neuraylib::IExport_api::get_writer ( const char * uri ) const

pure virtual

Returns a random-access writer that can be used to export to the given resource.

Parameters

uri	The URI of the resource to get the writer for.

Returns: A writer that can be used to export to the resource, or nullptr in case of failures.

^◆ select_exporter_by_extension()

virtual const IExporter * mi::neuraylib::IExport_api::select_exporter_by_extension ( const char * extension ) const

pure virtual

Returns the exporter that would be used for a particular file name extension.

This method needs a writable directory for temporary files (see mi::neuraylib::IGeneral_configuration::set_temp_path()).

Parameters

extension The file name extension of the resource to return an exporter for.

Returns: The exporter for the given file name extension, or nullptr in case of failures (e.g. there is no exporter that is able to export files with the given file name extension, or the user data directory is not writable).

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ convert_filename_to_uri()

◆ convert_uri_to_filename()

◆ export_bsdf_data()

◆ export_canvas()

◆ export_elements()

◆ export_elements_to_string()

◆ export_lightprofile()

◆ export_scene()

◆ export_volume_data()

◆ frame_uvtile_marker_to_string()

◆ get_export_dependencies()

◆ get_exporter()

◆ get_exporter_length()

◆ get_writer()

◆ select_exporter_by_extension()

^◆ convert_filename_to_uri()

^◆ convert_uri_to_filename()

^◆ export_bsdf_data()

^◆ export_canvas()

^◆ export_elements()

^◆ export_elements_to_string()

^◆ export_lightprofile()

^◆ export_scene()

^◆ export_volume_data()

^◆ frame_uvtile_marker_to_string()

^◆ get_export_dependencies()

^◆ get_exporter()

^◆ get_exporter_length()

^◆ get_writer()

^◆ select_exporter_by_extension()