Assimp  v3.0 (July 2012)
Classes | Public Types | Public Member Functions | Protected Attributes
Assimp::Exporter Class Reference

CPP-API: The Exporter class forms an C++ interface to the export functionality of the Open Asset Import Library. More...

List of all members.

Classes

struct  ExportFormatEntry
 Internal description of an Assimp export format option. More...

Public Types

typedef void(* fpExportFunc )(const char *, IOSystem *, const aiScene *)
 Function pointer type of a Export worker function.

Public Member Functions

aiReturn Export (const aiScene *pScene, const char *pFormatId, const char *pPath, unsigned int pPreprocessing=0u)
 Convenience function to export directly to a file.
aiReturn Export (const aiScene *pScene, const std::string &pFormatId, const std::string &pPath, unsigned int pPreprocessing=0u)
 Exporter ()
const aiExportDataBlobExportToBlob (const aiScene *pScene, const char *pFormatId, unsigned int pPreprocessing=0u)
 Exports the given scene to a chosen file format.
const aiExportDataBlobExportToBlob (const aiScene *pScene, const std::string &pFormatId, unsigned int pPreprocessing=0u)
void FreeBlob ()
 Frees the current blob.
const aiExportDataBlobGetBlob () const
 Return the blob obtained from the last call to ExportToBlob.
const char * GetErrorString () const
 Returns an error description of an error that occurred in Export or ExportToBlob.
size_t GetExportFormatCount () const
 Returns the number of export file formats available in the current Assimp build.
const aiExportFormatDescGetExportFormatDescription (size_t pIndex) const
 Returns a description of the nth export file format.
IOSystemGetIOHandler () const
 Retrieves the IO handler that is currently set.
const aiExportDataBlobGetOrphanedBlob () const
 Orphan the blob from the last call to ExportToBlob.
bool IsDefaultIOHandler () const
 Checks whether a default IO handler is active A default handler is active as long the application doesn't supply its own custom IO handler via SetIOHandler().
aiReturn RegisterExporter (const ExportFormatEntry &desc)
 Register a custom exporter.
void SetIOHandler (IOSystem *pIOHandler)
 Supplies a custom IO handler to the exporter to use to open and access files.
void UnregisterExporter (const char *id)
 Remove an export format previously registered with RegisterExporter from the Exporter instance (this can also be used to drop builtin exporters because those are implicitly registered using RegisterExporter).
 ~Exporter ()

Protected Attributes

ExporterPimpl * pimpl

Detailed Description

CPP-API: The Exporter class forms an C++ interface to the export functionality of the Open Asset Import Library.

Note that the export interface is available only if Assimp has been built with ASSIMP_BUILD_NO_EXPORT not defined.

The interface is modelled after the importer interface and mostly symmetric. The same rules for threading etc. apply.

In a nutshell, there are two export interfaces: Export, which writes the output file(s) either to the regular file system or to a user-supplied #IOSystem, and ExportToBlob which returns a linked list of memory buffers (blob), each referring to one output file (in most cases there will be only one output file of course, but this extra complexity is needed since Assimp aims at supporting a wide range of file formats).

ExportToBlob is especially useful if you intend to work with the data in-memory.


Member Typedef Documentation

typedef void(* Assimp::Exporter::fpExportFunc)(const char *, IOSystem *, const aiScene *)

Function pointer type of a Export worker function.


Constructor & Destructor Documentation

Assimp::Exporter::Exporter ( )
Assimp::Exporter::~Exporter ( )

Member Function Documentation

aiReturn Assimp::Exporter::Export ( const aiScene pScene,
const char *  pFormatId,
const char *  pPath,
unsigned int  pPreprocessing = 0u 
)

Convenience function to export directly to a file.

Use #SetIOSystem to supply a custom IOSystem to gain fine-grained control about the output data flow of the export process.

Parameters:
pBlobA data blob obtained from a previous call to aiExportScene. Must not be NULL.
pPathFull target file name. Target must be accessible.
pPreprocessingAccepts any choice of the #aiPostProcessing enumerated flags, but in reality only a subset of them makes sense here. Specifying 'preprocessing' flags is useful if the input scene does not conform to Assimp's default conventions as specified in the Data Structures Page . In short, this means the geometry data should use a right-handed coordinate systems, face winding should be counter-clockwise and the UV coordinate origin is assumed to be in the upper left. The aiProcess_MakeLeftHanded, aiProcess_FlipUVs and aiProcess_FlipWindingOrder flags are used in the import side to allow users to have those defaults automatically adapted to their conventions. Specifying those flags for exporting has the opposite effect, respectively. Some other of the aiPostProcessSteps enumerated values may be useful as well, but you'll need to try out what their effect on the exported file is. Many formats impose their own restrictions on the structure of the geometry stored therein, so some preprocessing may have little or no effect at all, or may be redundant as exporters would apply them anyhow. A good example is triangulation - whilst you can enforce it by specifying the aiProcess_Triangulate flag, most export formats support only triangulate data so they would run the step even if it wasn't requested.
Returns:
AI_SUCCESS if everything was fine.
aiReturn Assimp::Exporter::Export ( const aiScene pScene,
const std::string &  pFormatId,
const std::string &  pPath,
unsigned int  pPreprocessing = 0u 
)
inline
const aiExportDataBlob* Assimp::Exporter::ExportToBlob ( const aiScene pScene,
const char *  pFormatId,
unsigned int  pPreprocessing = 0u 
)

Exports the given scene to a chosen file format.

Returns the exported data as a binary blob which you can write into a file or something. When you're done with the data, simply let the Exporter instance go out of scope to have it released automatically.

Parameters:
pSceneThe scene to export. Stays in possession of the caller, is not changed by the function.
pFormatIdID string to specify to which format you want to export to. Use GetExportFormatCount / GetExportFormatDescription to learn which export formats are available.
pPreprocessingSee the documentation for Export
Returns:
the exported data or NULL in case of error.
Note:
If the Exporter instance did already hold a blob from a previous call to ExportToBlob, it will be disposed. Any IO handlers set via SetIOHandler are ignored here.
const aiExportDataBlob * Assimp::Exporter::ExportToBlob ( const aiScene pScene,
const std::string &  pFormatId,
unsigned int  pPreprocessing = 0u 
)
inline
void Assimp::Exporter::FreeBlob ( )

Frees the current blob.

The function does nothing if no blob has previously been previously produced via ExportToBlob. FreeBlob is called automatically by the destructor. The only reason to call it manually would be to reclain as much storage as possible without giving up the Exporter instance yet.

const aiExportDataBlob* Assimp::Exporter::GetBlob ( ) const

Return the blob obtained from the last call to ExportToBlob.

const char* Assimp::Exporter::GetErrorString ( ) const

Returns an error description of an error that occurred in Export or ExportToBlob.

Returns an empty string if no error occurred.

Returns:
A description of the last error, an empty string if no error occurred. The string is never NULL.
Note:
The returned function remains valid until one of the following methods is called: Export, ExportToBlob, FreeBlob
size_t Assimp::Exporter::GetExportFormatCount ( ) const

Returns the number of export file formats available in the current Assimp build.

Use #Exporter::GetExportFormatDescription to retrieve infos of a specific export format

const aiExportFormatDesc* Assimp::Exporter::GetExportFormatDescription ( size_t  pIndex) const

Returns a description of the nth export file format.

Use # #Exporter::GetExportFormatCount to learn how many export formats are supported.

Parameters:
pIndexIndex of the export format to retrieve information for. Valid range is 0 to #Exporter::GetExportFormatCount
Returns:
A description of that specific export format. NULL if pIndex is out of range.
IOSystem* Assimp::Exporter::GetIOHandler ( ) const

Retrieves the IO handler that is currently set.

You can use IsDefaultIOHandler() to check whether the returned interface is the default IO handler provided by ASSIMP. The default handler is active as long the application doesn't supply its own custom IO handler via SetIOHandler().

Returns:
A valid IOSystem interface, never NULL.
const aiExportDataBlob* Assimp::Exporter::GetOrphanedBlob ( ) const

Orphan the blob from the last call to ExportToBlob.

This means the caller takes ownership and is thus responsible for calling the C API function aiReleaseExportBlob to release it.

bool Assimp::Exporter::IsDefaultIOHandler ( ) const

Checks whether a default IO handler is active A default handler is active as long the application doesn't supply its own custom IO handler via SetIOHandler().

Returns:
true by default
aiReturn Assimp::Exporter::RegisterExporter ( const ExportFormatEntry desc)

Register a custom exporter.

Custom export formats are limited to to the current Exporter instance and do not affect the library globally.

Parameters:
descExporter description.
Returns:
aiReturn_SUCCESS if the export format was successfully registered. A common cause that would prevent an exporter from being registered is that its format id is already occupied by another format.
void Assimp::Exporter::SetIOHandler ( IOSystem pIOHandler)

Supplies a custom IO handler to the exporter to use to open and access files.

If you need Export to use custom IO logic to access the files, you need to supply a custom implementation of IOSystem and IOFile to the exporter.

Exporter takes ownership of the object and will destroy it afterwards. The previously assigned handler will be deleted. Pass NULL to take again ownership of your IOSystem and reset Assimp to use its default implementation, which uses plain file IO.

Parameters:
pIOHandlerThe IO handler to be used in all file accesses of the Importer.
void Assimp::Exporter::UnregisterExporter ( const char *  id)

Remove an export format previously registered with RegisterExporter from the Exporter instance (this can also be used to drop builtin exporters because those are implicitly registered using RegisterExporter).

Parameters:
idFormat id to be unregistered, this refers to the 'id' field of aiExportFormatDesc.
Note:
Calling this method on a format description not yet registered has no effect.

Member Data Documentation

ExporterPimpl* Assimp::Exporter::pimpl
protected

The documentation for this class was generated from the following file: