neuray API Programmer's Manual

mi::neuraylib::IExporter Class Reference

[Importer and Exporter]

Description

Abstract interface for exporters.

Public Member Functions

virtual IExport_resultexport_elements( ITransaction* transaction, const char* extension, IWriter* writer, const IArray* elements, const IMap* exporter_options, IImpexp_state* state) const =0
Exports a set of named elements via a writer. More...
virtual IExport_resultexport_scene( ITransaction* transaction, const char* extension, IWriter* writer, const char* rootgroup, const char* caminst, const char* options, const IMap* exporter_options, IImpexp_state* state) const =0
Exports a scene via a writer. More...
virtual bool  test_file_type( const char* extension, const IWriter* writer) const =0
Indicates whether the exporter can handle the file type. More...

Member Functions

virtual IExport_result* mi::​neuraylib::​IExporter::export_elements( ITransaction* transaction, const char* extension, IWriter* writer, const IArray* elements, const IMap* exporter_options, IImpexp_state* state) const [pure virtual]

Exports a set of named elements via a writer. Writes the named elements to the writer in a format determined by the exporter and the given extension. Note that in contrast to export_scene() references are not followed recursively.

The exporter can expect that the elements array contains no duplicates and that elements that are referenced come before elements that reference them. It is possible that these two conditions on the elements array are violated, but the exporter may then have undefined behavior, for example, produce invalid files.

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

  • "strip_prefix" of type mi::IString: If present, this prefix is to be stripped from all names of database elements if they have the same prefix. Default: the empty string.

It is strongly recommended that names for exporter-specific options use a prefix related to the exporter to avoid name conflicts, e.g., the file name extension.

In the case of the .mi file format, the exported file will contain no render statement.

Parameters

transaction
The transaction to be used.
extension
The file name extension (which might influence the file format).
writer
The writer to write the byte stream to.
elements
The array of elements to be exported.
exporter_options
The options that control the way the exporter works (optional).
state
The current exporter state.

Returns

An instance of mi::neuraylib::IExport_result indicating success or failure.

virtual IExport_result* mi::​neuraylib::​IExporter::export_scene( ITransaction* transaction, const char* extension, IWriter* writer, const char* rootgroup, const char* caminst, const char* options, const IMap* exporter_options, IImpexp_state* state) const [pure virtual]

Exports a scene via a writer. Writes the scene identified by the root group, the camera instance, and the options to the writer in a format determined by the exporter and the given extension.

Any elements referenced by the three argument elements are written as well, recursively, in an order that allows re-importing (e.g., in .mi files, a referenced element must precede the reference). The scene graph cannot contain cyclic references and an exporter does not need to take any precautions to detect cycles.

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

  • "strip_prefix" of type mi::IString: This prefix is to be stripped from the names of all exported elements if they have the same prefix. Default: the empty string.

It is strongly recommended that names for exporter-specific options use a prefix related to the exporter to avoid name conflicts, e.g., the file name extension.

In the case of the .mi file format, the exported file will contain a render statement.

See also:

mi::neuraylib::IExport_api::get_export_dependencies()

Parameters

transaction
The transaction to be used.
extension
The file name extension (which might influence the file format).
writer
The writer to write the byte stream to.
rootgroup
The root group of the scene to be exported.
caminst
The camera instance of the scene to be exported (optional).
options
The options of the scene to be exported (optional).
exporter_options
The options that control the way the exporter works (optional).
state
The current exporter state.

Returns

An instance of mi::neuraylib::IExport_result indicating success or failure.

virtual bool mi::​neuraylib::​IExporter::test_file_type( const char* extension, const IWriter* writer) const [pure virtual]

Indicates whether the exporter can handle the file type. Returns true if the exporter can handle the file type determined by the file name extension and if the writer has sufficient capabilities for export (such as random access or availability of a file handle if that is required for this exporter). The extension is defined as the part of the filename after and including the first dot, for example, ".mi". In the case of missing capabilities the exporter shall return false immediately.