Assimp  v2.0 (November 2010)
Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends
Assimp::BaseImporter Class Reference

FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface for all importer worker classes. More...

List of all members.

Public Member Functions

 BaseImporter ()
 Constructor to be privately used by Importer.
virtual bool CanRead (const std::string &pFile, IOSystem *pIOHandler, bool checkSig) const =0
 Returns whether the class can handle the format of the given file.
const std::stringGetErrorText () const
 Returns the error description of the last error that occured.
aiSceneReadFile (const Importer *pImp, const std::string &pFile, IOSystem *pIOHandler)
 Imports the given file and returns the imported data.
virtual void SetupProperties (const Importer *pImp)
 Called prior to ReadFile().
virtual ~BaseImporter ()
 Destructor, private as well.

Static Public Member Functions

static bool CheckMagicToken (IOSystem *pIOHandler, const std::string &pFile, const void *magic, unsigned int num, unsigned int offset=0, unsigned int size=4)
 Check whether a file starts with one or more magic tokens.
static void ConvertToUTF8 (std::vector< char > &data)
 An utility for all text file loaders.
static std::string GetExtension (const std::string &pFile)
 Extract file extension from a string.
static bool SearchFileHeaderForToken (IOSystem *pIOSystem, const std::string &file, const char **tokens, unsigned int numTokens, unsigned int searchBytes=200)
 A utility for CanRead().
static bool SimpleExtensionCheck (const std::string &pFile, const char *ext0, const char *ext1=NULL, const char *ext2=NULL)
 Check whether a file has a specific file extension.
static void TextFileToBuffer (IOStream *stream, std::vector< char > &data)
 Utility for text file loaders which copies the contents of the file into a memory buffer and converts it to our UTF8 representation.

Protected Member Functions

virtual void GetExtensionList (std::set< std::string > &extensions)=0
 Called by Importer::GetExtensionList() for each loaded importer.
virtual void InternReadFile (const std::string &pFile, aiScene *pScene, IOSystem *pIOHandler)=0
 Imports the given file into the given scene structure.

Protected Attributes

std::string mErrorText
 Error description in case there was one.
ProgressHandlerprogress
 Currently set progress handler.

Friends

class Importer

Detailed Description

FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface for all importer worker classes.

The interface defines two functions: CanRead() is used to check if the importer can handle the format of the given file. If an implementation of this function returns true, the importer then calls ReadFile() which imports the given file. ReadFile is not overridable, it just calls InternReadFile() and catches any ImportErrorException that might occur.


Constructor & Destructor Documentation

Assimp::BaseImporter::BaseImporter ( )

Constructor to be privately used by Importer.

virtual Assimp::BaseImporter::~BaseImporter ( ) [virtual]

Destructor, private as well.


Member Function Documentation

virtual bool Assimp::BaseImporter::CanRead ( const std::string pFile,
IOSystem pIOHandler,
bool  checkSig 
) const [pure virtual]

Returns whether the class can handle the format of the given file.

The implementation should be as quick as possible. A check for the file extension is enough. If no suitable loader is found with this strategy, CanRead() is called again, the 'checkSig' parameter set to true this time. Now the implementation is expected to perform a full check of the file structure, possibly searching the first bytes of the file for magic identifiers or keywords.

Parameters:
pFilePath and file name of the file to be examined.
pIOHandlerThe IO handler to use for accessing any file.
checkSigSet to true if this method is called a second time. This time, the implementation may take more time to examine the contents of the file to be loaded for magic bytes, keywords, etc to be able to load files with unknown/not existent file extensions.
Returns:
true if the class can read this file, false if not.
static bool Assimp::BaseImporter::CheckMagicToken ( IOSystem pIOHandler,
const std::string pFile,
const void *  magic,
unsigned int  num,
unsigned int  offset = 0,
unsigned int  size = 4 
) [static]

Check whether a file starts with one or more magic tokens.

Parameters:
pFileInput file
pIOHandlerIO system to be used
magicn magic tokens num Size of magic
offsetOffset from file start where tokens are located
Sizeof one token, in bytes. Maximally 16 bytes.
Returns:
true if one of the given tokens was found
Note:
For convinence, the check is also performed for the byte-swapped variant of all tokens (big endian). Only for tokens of size 2,4.
static void Assimp::BaseImporter::ConvertToUTF8 ( std::vector< char > &  data) [static]

An utility for all text file loaders.

It converts a file to our UTF8 character set. Errors are reported, but ignored.

Parameters:
dataFile buffer to be converted to UTF8 data. The buffer is resized as appropriate.
const std::string& Assimp::BaseImporter::GetErrorText ( ) const [inline]

Returns the error description of the last error that occured.

Returns:
A description of the last error that occured. An empty string if there was no error.
static std::string Assimp::BaseImporter::GetExtension ( const std::string pFile) [static]

Extract file extension from a string.

Parameters:
pFileInput file
Returns:
Extension without trailing dot, all lowercase
virtual void Assimp::BaseImporter::GetExtensionList ( std::set< std::string > &  extensions) [protected, pure virtual]

Called by Importer::GetExtensionList() for each loaded importer.

Implementations are expected to insert() all file extensions handled by them into the extension set. A loader capable of reading certain files with the extension BLA would place the string bla (lower-case!) in the output set.

Parameters:
extensionsOutput set.
virtual void Assimp::BaseImporter::InternReadFile ( const std::string pFile,
aiScene pScene,
IOSystem pIOHandler 
) [protected, pure virtual]

Imports the given file into the given scene structure.

The function is expected to throw an ImportErrorException if there is an error. If it terminates normally, the data in aiScene is expected to be correct. Override this function to implement the actual importing.
The output scene must meet the following requirements:

  • At least a root node must be there, even if its only purpose is to reference one mesh.
  • aiMesh::mPrimitiveTypes may be 0. The types of primitives in the mesh are determined automatically in this case.
  • the vertex data is stored in a pseudo-indexed "verbose" format. In fact this means that every vertex that is referenced by a face is unique. Or the other way round: a vertex index may not occur twice in a single aiMesh.
  • aiAnimation::mDuration may be -1. Assimp determines the length of the animation automatically in this case as the length of the longest animation channel.
  • aiMesh::mBitangents may be NULL if tangents and normals are given. In this case bitangents are computed as the cross product between normal and tangent.
  • There needn't be a material. If none is there a default material is generated. However, it is recommended practice for loaders to generate a default material for yourself that matches the default material setting for the file format better than Assimp's generic default material. Note that default materials *should* be named AI_DEFAULT_MATERIAL_NAME if they're just color-shaded or AI_DEFAULT_TEXTURED_MATERIAL_NAME if they define a (dummy) texture.

If the AI_SCENE_FLAGS_INCOMPLETE-Flag is not set:

  • at least one mesh must be there
  • there may be no meshes with 0 vertices or faces

This won't be checked (except by the validation step): Assimp will crash if one of the conditions is not met!

Parameters:
pFilePath of the file to be imported.
pSceneThe scene object to hold the imported data. NULL is not a valid parameter.
pIOHandlerThe IO handler to use for any file access. NULL is not a valid parameter.
aiScene* Assimp::BaseImporter::ReadFile ( const Importer pImp,
const std::string pFile,
IOSystem pIOHandler 
)

Imports the given file and returns the imported data.

If the import succeeds, ownership of the data is transferred to the caller. If the import fails, NULL is returned. The function takes care that any partially constructed data is destroyed beforehand.

Parameters:
pImpImporter object hosting this loader.
pFilePath of the file to be imported.
pIOHandlerIO-Handler used to open this and possible other files.
Returns:
The imported data or NULL if failed. If it failed a human-readable error description can be retrieved by calling GetErrorText()
Note:
This function is not intended to be overridden. Implement InternReadFile() to do the import. If an exception is thrown somewhere in InternReadFile(), this function will catch it and transform it into a suitable response to the caller.
static bool Assimp::BaseImporter::SearchFileHeaderForToken ( IOSystem pIOSystem,
const std::string file,
const char **  tokens,
unsigned int  numTokens,
unsigned int  searchBytes = 200 
) [static]

A utility for CanRead().

The function searches the header of a file for a specific token and returns true if this token is found. This works for text files only. There is a rudimentary handling of UNICODE files. The comparison is case independent.

Parameters:
pIOSystemIO System to work with
fileFile name of the file
tokensList of tokens to search for
numTokensSize of the token array
searchBytesNumber of bytes to be searched for the tokens.
virtual void Assimp::BaseImporter::SetupProperties ( const Importer pImp) [virtual]

Called prior to ReadFile().

The function is a request to the importer to update its configuration basing on the Importer's configuration property list.

Parameters:
pImpImporter instance
static bool Assimp::BaseImporter::SimpleExtensionCheck ( const std::string pFile,
const char *  ext0,
const char *  ext1 = NULL,
const char *  ext2 = NULL 
) [static]

Check whether a file has a specific file extension.

Parameters:
pFileInput file
ext0Extension to check for. Lowercase characters only, no dot!
ext1Optional second extension
ext2Optional third extension
Note:
Case-insensitive
static void Assimp::BaseImporter::TextFileToBuffer ( IOStream stream,
std::vector< char > &  data 
) [static]

Utility for text file loaders which copies the contents of the file into a memory buffer and converts it to our UTF8 representation.

Parameters:
streamStream to read from.
dataOutput buffer to be resized and filled with the converted text file data. The buffer is terminated with a binary 0.

Friends And Related Function Documentation

friend class Importer [friend]

Member Data Documentation

Error description in case there was one.

Currently set progress handler.


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