Importer and Exporter

[Neuray API]

Description

Methods to import and to export scene data and MDL modules. All import and export methods use a common naming convention to identify files based on URIs as defined in [RFC3986]. Currently only the URI scheme file is supported. An empty URI scheme defaults to the file scheme. URI authorities are not supported, except for the empty URI authority, which is needed in some cases to resolve ambiguities (see below).

Within the file scheme relative and absolute URI paths are supported (see Section 4 in [RFC3986]). URI paths are mapped to filenames as follows:

On Linux and Mac OS, URI paths are treated as filenames paths without any translation.
On Windows, slashes in relative URI paths are replaced by backslashes to obtain the filename.
On Windows, absolute URI paths are mapped to filenames 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.

Filenames containing hashes or questions marks are not supported by methods dealing with URIs.

In addition, the following variable can be used in URI paths, which are expanded by .

"${shader}"

The URI path may start with the string "${shader}" followed by a slash and a relative path, in which case the relative path is resolved relative to the search path for MDL modules. If several directories for MDL modules have been configured, they are searched in turn. This variable is only supported for import methods, not for export methods.

See also:

The API components mi::neuraylib::IImport_api and mi::neuraylib::IExport_api offer methods to convert between filenames and URIs. The Iray Programmer's Manual describes [:ipmlink reference Scene file formats] that can import.

Classes

class mi::neuraylib::IExport_api: This interface is used to export files. More...
class mi::neuraylib::IExport_result: This interface represents the result of an export operation. More...
class mi::neuraylib::IExport_result_ext: This interface represents the result of an export operation. More...
class mi::neuraylib::IExporter: Abstract interface for exporters. More...
class mi::neuraylib::IImpexp_base: Abstract base interface common for importers and exporters. More...
class mi::neuraylib::IImpexp_state: This interface represents states that are passed to recursive calls of importers and exporters. More...
class mi::neuraylib::IImport_api: This interface is used to import files. More...
class mi::neuraylib::IImport_result: This interface represents the result of an import operation. More...
class mi::neuraylib::IImport_result_ext: This interface represents the result of an import operation. More...
class mi::neuraylib::IImporter: Abstract interface for importers. More...
class mi::neuraylib::IReader: A reader supports binary block reads and string-oriented line reads that zero-terminate the result. More...
class mi::neuraylib::IReader_writer_base: Base interface for readers and writers. More...
class mi::neuraylib::IStream_position: Represents the position in a data stream. More...
class mi::neuraylib::IWriter: A writer supports binary block writes and string-oriented line writes that accept a zero-terminated string as argument. More...

Enumerations

enum mi::neuraylib::Impexp_priority{ IMPEXP_PRIORITY_OVERRIDE = 4, IMPEXP_PRIORITY_WELL_DEFINED = 3, IMPEXP_PRIORITY_AMBIGUOUS = 2, IMPEXP_PRIORITY_GUESS = 1, IMPEXP_PRIORITY_FORCE_32_BIT = 0xffffffffU}: Confidence in capabilities of an importer or exporter. More...

Functions

virtual const char* mi::neuraylib::IExport_result::get_error_message() const =0: Returns the message of the first error. More...
virtual const char* mi::neuraylib::IExport_result::get_message( Size index) const =0: Returns a message from the array of messages. More...
virtual Uint32 mi::neuraylib::IExport_result::get_message_number( Size index) const =0: Returns the message number for a given message from the array of messages. More...
virtual base::Message_severity mi::neuraylib::IExport_result::get_message_severity( Size index) const =0: Returns the severity for a given message from the array of messages. More...
virtual Size mi::neuraylib::IExport_result::get_messages_length() const =0: Returns the number of messages.
virtual Sint32 mi::neuraylib::IExport_result_ext::append_messages( const IExport_result* export_result) =0: Appends all messages in export_result to this instance. More...
virtual void mi::neuraylib::IExport_result_ext::clear_messages() =0: Removes all messages.
virtual Sint32 mi::neuraylib::IExport_result_ext::message_push_back( Uint32 number, base::Message_severity severity, const char* message) =0: Appends a message number, severity, and message to the array of recorded message numbers, severities, and messages. More...
virtual Sint32 mi::neuraylib::IExport_result_ext::set_message( Size index, Uint32 number, base::Message_severity severity, const char* message) =0: Replaces a message number, severity, and message in the array of recorded message numbers, severities, and messages. More...
virtual const char* mi::neuraylib::IImpexp_base::get_author() const =0: Returns a concise single-line clear text description of the author of this importer or exporter. More...
virtual Uint32 mi::neuraylib::IImpexp_base::get_major_version() const =0: Returns the major version number of the importer or exporter. More...
virtual Uint32 mi::neuraylib::IImpexp_base::get_minor_version() const =0: Returns the minor version number of the importer or exporter. More...
virtual const char* mi::neuraylib::IImpexp_base::get_name() const =0: Returns a concise single-line clear text description of the importer or exporter. More...
virtual Impexp_priority mi::neuraylib::IImpexp_base::get_priority() const =0: Returns the priority of the importer or exporter. More...
virtual const char* mi::neuraylib::IImpexp_base::get_supported_extensions( Uint32 i) const =0: Returns the i -th supported file name extension. More...
virtual base::Uuid mi::neuraylib::IImpexp_base::get_uuid() const =0: Returns the unique identifier for the importer or exporter. More...
virtual bool mi::neuraylib::IImpexp_base::test_file_type( const char* extension) const =0: Indicates whether a file name extension is supported. More...
virtual Uint32 mi::neuraylib::IImpexp_state::get_line_number() const =0: Returns the line number after the last read or write operation. More...
virtual const IImpexp_state* mi::neuraylib::IImpexp_state::get_parent_state() const =0: Returns the state of the parent importer or exporter. More...
virtual void mi::neuraylib::IImpexp_state::incr_line_number() =0: Convenience function that increments the line number by one. More...
virtual void mi::neuraylib::IImpexp_state::set_line_number( Uint32 n) =0: Sets the line number to n. More...
virtual const char* mi::neuraylib::IImport_result::get_camera_inst() const =0: Returns the name of the camera instance. More...
virtual const char* mi::neuraylib::IImport_result::get_element( Size index) const =0: Returns the name of the element indicated by index.
virtual Size mi::neuraylib::IImport_result::get_elements_length() const =0: Returns the length of the element array.
virtual const char* mi::neuraylib::IImport_result::get_error_message() const =0: Returns the message of the first error. More...
virtual Uint32 mi::neuraylib::IImport_result::get_error_number() const =0: Returns the number of the first error. More...
virtual const char* mi::neuraylib::IImport_result::get_message( Size index) const =0: Returns a message from the array of messages. More...
virtual Uint32 mi::neuraylib::IImport_result::get_message_number( Size index) const =0: Returns the message number for a given message from the array of messages. More...
virtual base::Message_severity mi::neuraylib::IImport_result::get_message_severity( Size index) const =0: Returns the severity for a given message from the array of messages. More...
virtual Size mi::neuraylib::IImport_result::get_messages_length() const =0: Returns the number of messages.
virtual const char* mi::neuraylib::IImport_result::get_options() const =0: Returns the name of the options element. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::append_elements( const IImport_result* import_result) =0: Appends all elements in import_result to this instance. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::append_messages( const IImport_result* import_result) =0: Appends all messages in import_result to this instance. More...
virtual void mi::neuraylib::IImport_result_ext::clear_elements() =0: Removes all elements.
virtual void mi::neuraylib::IImport_result_ext::clear_messages() =0: Removes all messages.
virtual Sint32 mi::neuraylib::IImport_result_ext::element_push_back( const char* element) =0: Appends an element to the array of recorded elements. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::message_push_back( Uint32 number, base::Message_severity severity, const char* message) =0: Appends a message number, severity, and message to the array of recorded message numbers, severities, and messages. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::set_camera_inst( const char* camera) =0: Sets the name of the camera instance. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::set_element( Size index, const char* element) =0: Replaces an element in the array of recorded elements. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::set_message( Uint32 number, base::Message_severity severity, const char* message) =0: Replaces all messages by the given message number, severity, and message. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::set_message( Size index, Uint32 number, base::Message_severity severity, const char* message) =0: Replaces a message number, severity, and message in the array of recorded message numbers, severities, and messages. More...
virtual Sint32 mi::neuraylib::IImport_result_ext::set_options( const char* options) =0: Sets the name of the options. More...

Enums

enum mi::neuraylib::Impexp_priority

Confidence in capabilities of an importer or exporter. If there is more than one importer or exporter that accepts a certain file format, the importer or exporter with the highest priority is taken. Tie-breaking is unspecified.

Enumerator:

IMPEXP_PRIORITY_OVERRIDE = 4: The highest priority, reserved for importers and exporters from user plugins.
IMPEXP_PRIORITY_WELL_DEFINED = 3: The highest possible priority for importers or exporters in plugins provided in . Use only for importers or exporters whose test function cannot fail and whose support for the format is complete.
IMPEXP_PRIORITY_AMBIGUOUS = 2: The test function might fail, or the format might not be fully supported.
IMPEXP_PRIORITY_GUESS = 1: The importer or exporter does not have a good way of detecting the format or the support is very preliminary or incomplete.
IMPEXP_PRIORITY_FORCE_32_BIT = 0xffffffffU

Functions

virtual const char* mi::neuraylib::IExport_result::get_error_message() const [pure virtual]

Returns the message of the first error. A message describing the error condition corresponding to the error reported from get_error_number().

It is possible to query the all messages, see get_messages_length() and get_message( mi::Size)const. This method just reports the the first message of severity mi::base::details::MESSAGE_SEVERITY_ERROR or above, or NULL if there is no such message.

virtual const char* mi::neuraylib::IExport_result::get_message( Size index) const [pure virtual]

Returns a message from the array of messages. see get_messages_length()

virtual Uint32 mi::neuraylib::IExport_result::get_message_number( Size index) const [pure virtual]

Returns the message number for a given message from the array of messages. see get_messages_length()

virtual base::Message_severity mi::neuraylib::IExport_result::get_message_severity( Size index) const [pure virtual]

Returns the severity for a given message from the array of messages. see get_messages_length()

virtual Size mi::neuraylib::IExport_result::get_messages_length() const [pure virtual]

Returns the number of messages.

virtual Sint32 mi::neuraylib::IExport_result_ext::append_messages( const IExport_result* export_result) [pure virtual]

Appends all messages in export_result to this instance.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual void mi::neuraylib::IExport_result_ext::clear_messages() [pure virtual]

Removes all messages.

virtual Sint32 mi::neuraylib::IExport_result_ext::message_push_back( Uint32 number, base::Message_severity severity, const char* message) [pure virtual]

Appends a message number, severity, and message to the array of recorded message numbers, severities, and messages.

See also:

mi::neuraylib::IExport_result_ext for valid message numbers

Parameters

number: The message number to append.
severity: The message severity to append.
message: The message to append.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IExport_result_ext::set_message( Size index, Uint32 number, base::Message_severity severity, const char* message) [pure virtual]

Replaces a message number, severity, and message in the array of recorded message numbers, severities, and messages.

See also:

mi::neuraylib::IExport_result_ext for valid message numbers

Parameters

index: The index of the message to be replaced.
number: The message number to append.
severity: The message severity to append.
message: The message to append.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: index is out of bounds.

virtual const char* mi::neuraylib::IImpexp_base::get_author() const [pure virtual]

Returns a concise single-line clear text description of the author of this importer or exporter. This description may be used to support user interaction, such as in command-line help or selection boxes of graphical user interfaces. This method must return a valid string.

This description is also used in the importer or exporter selection algorithm, which selects among importers and exporters of the same name and same author the one that has the highest version number.

virtual Uint32 mi::neuraylib::IImpexp_base::get_major_version() const [pure virtual]

Returns the major version number of the importer or exporter. If you register multiple importers or exporters with equal name and author, the importer or exporter with the higher version number will be taken. A version number is higher if the version number is higher, or if it is equal and the minor version number is higher major (lexicographic order).

virtual Uint32 mi::neuraylib::IImpexp_base::get_minor_version() const [pure virtual]

Returns the minor version number of the importer or exporter. If you register multiple importers or exporters with equal name and author, the importer or exporter with the higher version number will be taken. A version number is higher if the version number is higher, or if it is equal and the minor version number is higher major (lexicographic order).

virtual const char* mi::neuraylib::IImpexp_base::get_name() const [pure virtual]

Returns a concise single-line clear text description of the importer or exporter. The description should name, besides maybe a product or brand name, the supported file format and, if applicable, the major file type version or versions that are supported. If a file format differs sufficiently from version to version, you may as well register different importers or exporters for each version.

This description may be used to support user interaction, such as in command-line help or selection boxes of graphical user interfaces. This method must return a valid string. This description is also used in the importer or exporter selection algorithm, which selects among importers and exporters of the same name and same author the one that has the highest version number.

virtual Impexp_priority mi::neuraylib::IImpexp_base::get_priority() const [pure virtual]

Returns the priority of the importer or exporter. The priority expresses the confidence of the importer or exporter that its test_file_type() method can identify the file and that the file format is fully supported.

virtual const char* mi::neuraylib::IImpexp_base::get_supported_extensions( Uint32 i) const [pure virtual]

Returns the i -th supported file name extension.

Returns

The file name extension including the separating dot, or NULL if i is out of range.

virtual base::Uuid mi::neuraylib::IImpexp_base::get_uuid() const [pure virtual]

Returns the unique identifier for the importer or exporter. You can register only one importer or exporter for a particular UUID. If you wish to support installations with multiple versions of your importer or exporter, you have to change the UUID for each minor and major version number change.

virtual bool mi::neuraylib::IImpexp_base::test_file_type( const char* extension) const [pure virtual]

Indicates whether a file name extension is supported. Returns true if the importer or exporter can handle the file type determined by the file name extension. The extension is defined as the part of the file name after and including the first dot, for example, ".mi".

These more specific versions also pass an mi::neuraylib::IReader or mi::neuraylib::IWriter as argument, which can be used to look at lookahead data for magic file headers (readers only) or to decide if the reader or writer capabilities are sufficient to do the import or export (for example, random access capability).

virtual Uint32 mi::neuraylib::IImpexp_state::get_line_number() const [pure virtual]

Returns the line number after the last read or write operation. Line number counting starts with 1 for the first line. Only applicable for line oriented file formats.

virtual const IImpexp_state* mi::neuraylib::IImpexp_state::get_parent_state() const [pure virtual]

Returns the state of the parent importer or exporter. The parent importer or exporter is the one that called the current importer or exporter. Returns NULL if there is no parent importer or exporter.

virtual void mi::neuraylib::IImpexp_state::incr_line_number() [pure virtual]

Convenience function that increments the line number by one. Line number counting starts with 1 for the first line.

virtual void mi::neuraylib::IImpexp_state::set_line_number( Uint32 n) [pure virtual]

Sets the line number to n. Line number counting starts with 1 for the first line.

virtual const char* mi::neuraylib::IImport_result::get_camera_inst() const [pure virtual]

Returns the name of the camera instance. If the scene file has a scene root (like a render statement in a .mi file) containing a camera instance, the method returns the name of the camera instance element.

virtual const char* mi::neuraylib::IImport_result::get_element( Size index) const [pure virtual]

Returns the name of the element indicated by index.

virtual Size mi::neuraylib::IImport_result::get_elements_length() const [pure virtual]

Returns the length of the element array.

virtual const char* mi::neuraylib::IImport_result::get_error_message() const [pure virtual]

Returns the message of the first error. A message describing the error condition corresponding to the error reported from get_error_number().

virtual Uint32 mi::neuraylib::IImport_result::get_error_number() const [pure virtual]

Returns the number of the first error. The error number indicates the status of the import operation: 0 means success, all other values indicate failures, in which case get_error_message() provides a diagnostic message. Numbers in the range 4000-5999 are reserved for custom importers. All other numbers are reserved for other purposes.

It is possible to query the message numbers of all messages, see get_messages_length() and get_message_number( mi::Size)const. This method just reports the number of the first message of severity mi::base::details::MESSAGE_SEVERITY_ERROR or above, or 0 if there is no such message.

virtual const char* mi::neuraylib::IImport_result::get_message( Size index) const [pure virtual]

Returns a message from the array of messages.

See also:

get_messages_length()

virtual Uint32 mi::neuraylib::IImport_result::get_message_number( Size index) const [pure virtual]

Returns the message number for a given message from the array of messages.

See also:

get_messages_length()

virtual base::Message_severity mi::neuraylib::IImport_result::get_message_severity( Size index) const [pure virtual]

Returns the severity for a given message from the array of messages.

See also:

get_messages_length()

virtual Size mi::neuraylib::IImport_result::get_messages_length() const [pure virtual]

Returns the number of messages.

virtual const char* mi::neuraylib::IImport_result::get_options() const [pure virtual]

Returns the name of the options element. If the scene file has a scene root (like a render statement in a .mi file) containing an options element, the method returns the name of the options element.

virtual Sint32 mi::neuraylib::IImport_result_ext::append_elements( const IImport_result* import_result) [pure virtual]

Appends all elements in import_result to this instance.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IImport_result_ext::append_messages( const IImport_result* import_result) [pure virtual]

Appends all messages in import_result to this instance.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual void mi::neuraylib::IImport_result_ext::clear_elements() [pure virtual]

Removes all elements.

virtual void mi::neuraylib::IImport_result_ext::clear_messages() [pure virtual]

Removes all messages.

virtual Sint32 mi::neuraylib::IImport_result_ext::element_push_back( const char* element) [pure virtual]

Appends an element to the array of recorded elements.

Parameters

element: The name of the element to append.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IImport_result_ext::message_push_back( Uint32 number, base::Message_severity severity, const char* message) [pure virtual]

Appends a message number, severity, and message to the array of recorded message numbers, severities, and messages.

See also:

mi::neuraylib::IImport_result_ext for valid message numbers

Parameters

number: The message number to append.
severity: The message severity to append.
message: The message to append.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IImport_result_ext::set_camera_inst( const char* camera) [pure virtual]

Sets the name of the camera instance.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IImport_result_ext::set_element( Size index, const char* element) [pure virtual]

Replaces an element in the array of recorded elements. The operation is skipped if index is out of bounds.

Parameters

index: The index of the element to be replaced.
element: The name of the element element to be replaced.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: index is out of bounds.

virtual Sint32 mi::neuraylib::IImport_result_ext::set_message( Uint32 number, base::Message_severity severity, const char* message) [pure virtual]

Replaces all messages by the given message number, severity, and message. Equivalent to clear_messages(), followed by message_push_back().

See also:

mi::neuraylib::IImport_result_ext for valid message numbers

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

virtual Sint32 mi::neuraylib::IImport_result_ext::set_message( Size index, Uint32 number, base::Message_severity severity, const char* message) [pure virtual]

Replaces a message number, severity, and message in the array of recorded message numbers, severities, and messages.

See also:

mi::neuraylib::IImport_result_ext for valid message numbers

Parameters

index: The index of the message to be replaced.
number: The message number to append.
severity: The message severity to append.
message: The message to append.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).
-2: index is out of bounds.

virtual Sint32 mi::neuraylib::IImport_result_ext::set_options( const char* options) [pure virtual]

Sets the name of the options.

Returns

0: Success.
-1: Invalid parameters (NULL pointer).

RealityServer® 6.4 Document Center

neuray API Programmer's Manual

Importer and Exporter

[Neuray API]

Description

Classes

Enumerations

Functions

Enums

Enumerator:

Functions

Returns

Parameters

Returns

Parameters

Returns

Returns

Returns

Returns

Parameters

Returns

Parameters

Returns

Returns

Parameters

Returns

Returns

Parameters

Returns

Returns