Member Functions

virtual const IString* mi::​neuraylib::​IImport_api::convert_filename_to_uri( const char* filename) const [pure virtual]

Converts a filename into a URI. Returns NULL if filename is NULL. 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, 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.

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

virtual const IString* mi::​neuraylib::​IImport_api::convert_uri_to_filename( const char* uri) const [pure virtual]

Converts a URI into a filename. Returns NULL if

• uri is NULL,

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

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.

virtual const IString* mi::​neuraylib::​IImport_api::create_importer_directory( ITransaction* transaction) const [pure virtual]

Creates a unique directory that can be used by importers for temporary files. Note that multiple calls to this function will return different results even when called from the same importer. The created directory is in the directory for temporary files, see mi::neuraylib::IGeneral_configuration::set_temp_path().

Parameters

transaction

The transaction to be used.

Returns

The created directory, or NULL in case of failure.

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

Creates a random-access reader for a given buffer.

virtual const IString* mi::​neuraylib::​IImport_api::get_absolute_path( ITransaction* transaction, const char* path) const [pure virtual]

Returns the absolute path corresponding to the given path. Relative paths are resolved to absolute paths w.r.t. to the current working directory.

Note:

There are no checks whether path exists or not.

Parameters

transaction

The transaction to be used.

path

An absolute or relative path.

Returns

The absolute path corresponding to path in a normalized representation.

virtual const IImporter* mi::​neuraylib::​IImport_api::get_importer( Size index) const [pure virtual]

Returns a registered importer.

See also:

mi::neuraylib::IImport_api::get_importer_length(), mi::neuraylib::IExtension_api::register_importer()

Parameters

index

The index of the requested importer.

Returns

The requested importer, or NULL if index is out of bounds.

virtual Size mi::​neuraylib::​IImport_api::get_importer_length() const [pure virtual]

Returns the number of registered importers.

See also:

mi::neuraylib::IImport_api::get_importer(), mi::neuraylib::IExtension_api::register_importer()

Returns

The number of registered importers.

virtual IReader* mi::​neuraylib::​IImport_api::get_reader( const char* uri) const [pure virtual]

Returns a random-access reader that can be used to import the given resource.

Parameters

uri

The URI of the resource to get the reader for.

Returns

A reader that can be used to import the resource, or NULL in case of failures (e.g., the URI denotes a non-existing file).

virtual Sint32 mi::​neuraylib::​IImport_api::import_bsdf_data( const char* uri, IBsdf_isotropic_data** reflection, IBsdf_isotropic_data** transmission) const [pure virtual]

Imports BSDF data from a file on disk. See Importer and Exporter for the URI naming conventions supported for the uri parameter.

Parameters

uri

The URI of the BSDF data to import.

reflection

The imported BSDF data for the reflection. The incoming value of *reflection must be NULL. The reference count of the outgoing value of *reflection has already been increased for the caller (similar as for return values). Note that *reflection is NULL if there is no BSDF data for the reflection.

transmission

The imported BSDF data for the transmission. The incoming value of *transmission must be NULL. The reference count of the outgoing value of *transmission has already been increased for the caller (similar as for return values). Note that *transmission is NULL if there is no BSDF data for the transmission.

Returns

• 0: Success.
• -1: Invalid parameters (NULL pointer).
• -3: Invalid filename extension (only .mbsdf is supported).
• -5: Failure to open the file.
• -7: File format error.
• -16: *reflection or *transmission are not NULL.
• -17: Invalid URI.

virtual ICanvas* mi::​neuraylib::​IImport_api::import_canvas( const char* uri) const [pure virtual]

Imports a canvas from a file on disk. See Importer and Exporter for the URI naming conventions supported for the uri parameter.

Parameters

uri

The URI of the canvas to import. 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.

Returns

The imported canvas, or NULL in case of failure.

virtual const IImport_result* mi::​neuraylib::​IImport_api::import_elements( ITransaction* transaction, const char* uri, const IMap* importer_options = 0, const IImpexp_state* parent_state = 0) const [pure virtual]

Imports scene elements. This method reads the named file from uri and parses it with an importer. Importer selection is based on testing a file prefix (if available) or the uri filename extension. Elements will be put into the database as if they had been stored with mi::neuraylib::ITransaction::store().

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

• "prefix" of type mi::IString: This prefix is prepended to the names of all imported elements. Default: the empty string.

• "list_elements" of type mi::IBoolean: If true, the name of each imported element is stored in the returned instance of mi::neuraylib::IImport_result. All elements can be directly looked up using these names via mi::neuraylib::ITransaction::access() and mi::neuraylib::ITransaction::edit(). Default: false.

The method stores a non-zero status code in the returned instance of mi::neuraylib::IImport_result if an error occurred. The database and mi::neuraylib::IImport_result contain all elements read up to that point. The element that caused the error might be incomplete or inconsistent. If the "list_elements" options is selected, every changed or added element, even if it caused an error, is reported in the elements array of mi::neuraylib::IImport_result. In case of an error, the database can be returned to a safe state that does not contain incompletely defined elements by calling the mi::neuraylib::ITransaction::abort() method, which will return the database to the state it was in when the current transaction started. (This is not specific to scene importing, any operation that modifies the database can be reversed in this way.)

Parameters

transaction

The transaction to be used.

uri

The URI of the file to import from. See Importer and Exporter for the supported URI naming conventions.

importer_options

The importer options (see above).

parent_state

An optional state that can be passed by a parent importer, or NULL. Such a state is used to resolve relative URIs w.r.t. to the URI of the parent state. In addition, the parent state can be used by the importer for better diagnostics in case of errors.

Returns

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

• 0: The import operation was successful.
• 1: The passed URI is invalid (malformed).
• 2: failed to create an instance of mi::neuraylib::IReader for the given URI, most probably because it was unable to open the specified file, e.g., because the file does not exist, or the user has insufficient permissions.
• 3: There is no appropriate importer for this file format (and file content).
• 4: The importer failed to create the instance of mi::neuraylib::IImpexp_state.
• 5: The importer did not return a valid instance of mi::neuraylib::IImport_result.
• 6: The option '...' has an invalid type.
• 7: The option '...' has an invalid value.
• 4000-5999: Reserved for importer-specific error codes.

virtual const IImport_result* mi::​neuraylib::​IImport_api::import_elements_from_string( ITransaction* transaction, const char* data, const char* file_extension, const IMap* importer_options = 0, const IImpexp_state* parent_state = 0) const [pure virtual]

Imports scene data from a string into the database. In all other respects it behaves like the import_elements() method. However, this function can only handle non-binary data, since the data is passed in as a zero-terminated string.

This method supports following options:

• "list_elements" of type mi::IBoolean: If true, the name of each imported element is stored in the returned instance of mi::neuraylib::IImport_result. All elements can be directly looked up using these names via mi::neuraylib::ITransaction::access() and mi::neuraylib::ITransaction::edit(). Default: false.

When used to import MDL modules, the following options are also supported:

• "module_name" of type mi::IString: The MDL name of the module that is represented by data. Note that there must be no file-based MDL module of that name in the configured search path, otherwise the method will fail. That is, this method can not be used to shadow file-based MDL modules. It is also not possible to use this method to change already imported MDL modules. This option is mandatory if file_extension is ".mdl".

When used to import MDL modules, the following error codes are possible:

• 8: The option 'module_name' is mandatory for MDL modules.

Parameters

transaction

The transaction to be used.

data

The string that holds the scene elements to import.

file_extension

The file extension. Since there is no file name/URI in this variant, this string is used to select the importer, e.g., ".mdl".

importer_options

The importer options (see above).

parent_state

An optional state that can be passed by a parent importer, or NULL. Such a state is used to resolve relative URIs w.r.t. to the URI of the parent state. In addition, the parent state can be used by the importer for better diagnostics in case of errors.

Returns

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

• 0: The import operation was successful.
• 1: The data was invalid (data is NULL or the empty string).
• 2: The data format is invalid (file_extension is NULL or the empty string).
• 3: There is no appropriate importer for this file extension (and data).
• 4: The importer failed to create the instance of mi::neuraylib::IImpexp_state.
• 5: The importer did not return a valid instance of mi::neuraylib::IImport_result.
• 6: The option '...' has an invalid type.
• 7: The option '...' has an invalid value.
• 4000-5999: Reserved for importer-specific error codes.

virtual const IImporter* mi::​neuraylib::​IImport_api::select_importer_by_uri( const char* uri) const [pure virtual]

Returns the importer that would be used for a particular resource.

Parameters

uri

The URI of the resource to return an importer for.

Returns

The importer for the resource uri , or NULL in case of failures (e.g. there is no importer that is able to import the given resource).