Assimp  v4.1. (December 2018)
Assimp::BaseImporter Class Referenceabstract

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

Inherited by Assimp::AC3DImporter, Assimp::AMFImporter, Assimp::ASEImporter, Assimp::AssbinImporter, Assimp::B3DImporter, Assimp::BlenderImporter, Assimp::BVHLoader, Assimp::C4DImporter, Assimp::COBImporter, Assimp::ColladaLoader, Assimp::CSMImporter, Assimp::D3MFImporter, Assimp::Discreet3DSImporter, Assimp::DXFImporter, Assimp::FBXImporter, Assimp::glTF2Importer, Assimp::glTFImporter, Assimp::IFCImporter, Assimp::IRRImporter, Assimp::IRRMeshImporter, Assimp::LWOImporter, Assimp::LWSImporter, Assimp::MD2Importer, Assimp::MD3Importer, Assimp::MD5Importer, Assimp::MDCImporter, Assimp::MDLImporter, Assimp::MMDImporter, Assimp::MS3DImporter, Assimp::NDOImporter, Assimp::NFFImporter, Assimp::ObjFileImporter, Assimp::OFFImporter, Assimp::Ogre::OgreImporter, Assimp::OpenGEX::OpenGEXImporter, Assimp::PLYImporter, Assimp::Q3BSPFileImporter, Assimp::Q3DImporter, Assimp::RAWImporter, Assimp::SIBImporter, Assimp::SMDImporter, Assimp::STLImporter, Assimp::TerragenImporter, Assimp::UnrealImporter, Assimp::X3DImporter, Assimp::XFileImporter, and Assimp::XGLImporter.

Public Types

enum  TextFileMode { ALLOW_EMPTY, FORBID_EMPTY }
 Enum to define, if empty files are ok or not. More...
 

Public Member Functions

 BaseImporter ()
 Constructor to be privately used by Importer. More...
 
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. More...
 
const std::string & GetErrorText () const
 Returns the error description of the last error that occurred. More...
 
void GetExtensionList (std::set< std::string > &extensions)
 Called by #Importer::GetExtensionList for each loaded importer. More...
 
virtual const aiImporterDescGetInfo () const =0
 Called by #Importer::GetImporterInfo to get a description of some loader features. More...
 
aiSceneReadFile (const Importer *pImp, const std::string &pFile, IOSystem *pIOHandler)
 Imports the given file and returns the imported data. More...
 
virtual void SetupProperties (const Importer *pImp)
 Called prior to ReadFile(). More...
 
virtual ~BaseImporter ()
 Destructor, private as well. More...
 

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. More...
 
static void ConvertToUTF8 (std::vector< char > &data)
 An utility for all text file loaders. More...
 
static void ConvertUTF8toISO8859_1 (std::string &data)
 An utility for all text file loaders. More...
 
template<typename T >
static AI_FORCE_INLINE void CopyVector (std::vector< T > &vec, T *&out, unsigned int &outLength)
 Utility function to move a std::vector into a aiScene array. More...
 
static std::string GetExtension (const std::string &pFile)
 Extract file extension from a string. More...
 
static bool SearchFileHeaderForToken (IOSystem *pIOSystem, const std::string &file, const char **tokens, unsigned int numTokens, unsigned int searchBytes=200, bool tokensSol=false)
 A utility for CanRead(). More...
 
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. More...
 
static void TextFileToBuffer (IOStream *stream, std::vector< char > &data, TextFileMode mode=FORBID_EMPTY)
 Utility for text file loaders which copies the contents of the file into a memory buffer and converts it to our UTF8 representation. More...
 

Protected Member Functions

virtual void InternReadFile (const std::string &pFile, aiScene *pScene, IOSystem *pIOHandler)=0
 Imports the given file into the given scene structure. More...
 

Protected Attributes

std::string m_ErrorText
 Error description in case there was one. More...
 
ProgressHandlerm_progress
 Currently set progress handler. More...
 

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.

Member Enumeration Documentation

◆ TextFileMode

Enum to define, if empty files are ok or not.

Enumerator
ALLOW_EMPTY 
FORBID_EMPTY 

Constructor & Destructor Documentation

◆ BaseImporter()

BaseImporter::BaseImporter ( )

Constructor to be privately used by Importer.

◆ ~BaseImporter()

BaseImporter::~BaseImporter ( )
virtual

Destructor, private as well.

Member Function Documentation

◆ CanRead()

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.

Implemented in Assimp::X3DImporter, Assimp::AMFImporter, Assimp::BVHLoader, Assimp::XGLImporter, Assimp::XFileImporter, Assimp::UnrealImporter, Assimp::TerragenImporter, Assimp::STLImporter, Assimp::SMDImporter, Assimp::SIBImporter, Assimp::RAWImporter, Assimp::Q3DImporter, Assimp::Q3BSPFileImporter, Assimp::PLYImporter, Assimp::Ogre::OgreImporter, Assimp::OFFImporter, Assimp::ObjFileImporter, Assimp::NFFImporter, Assimp::NDOImporter, Assimp::MS3DImporter, Assimp::MMDImporter, Assimp::MDLImporter, Assimp::MDCImporter, Assimp::MD5Importer, Assimp::MD3Importer, Assimp::MD2Importer, Assimp::LWSImporter, Assimp::LWOImporter, Assimp::IRRMeshImporter, Assimp::IRRImporter, Assimp::IFCImporter, Assimp::HMPImporter, Assimp::glTFImporter, Assimp::glTF2Importer, Assimp::FBXImporter, Assimp::DXFImporter, Assimp::D3MFImporter, Assimp::CSMImporter, Assimp::ColladaLoader, Assimp::COBImporter, Assimp::C4DImporter, Assimp::BlenderImporter, Assimp::B3DImporter, Assimp::AssbinImporter, Assimp::ASEImporter, Assimp::AC3DImporter, Assimp::Discreet3DSImporter, and Assimp::OpenGEX::OpenGEXImporter.

◆ CheckMagicToken()

bool 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 @params 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 convenience, the check is also performed for the byte-swapped variant of all tokens (big endian). Only for tokens of size 2,4.

◆ ConvertToUTF8()

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

◆ ConvertUTF8toISO8859_1()

void BaseImporter::ConvertUTF8toISO8859_1 ( std::string &  data)
static

An utility for all text file loaders.

It converts a file from our UTF8 character set back to ISO-8859-1. Errors are reported, but ignored.

Parameters
dataFile buffer to be converted from UTF8 to ISO-8859-1. The buffer is resized as appropriate.

◆ CopyVector()

template<typename T >
static AI_FORCE_INLINE void Assimp::BaseImporter::CopyVector ( std::vector< T > &  vec,
T *&  out,
unsigned int &  outLength 
)
inlinestatic

Utility function to move a std::vector into a aiScene array.

Parameters
vecThe vector to be moved
outThe output pointer to the allocated array.
numOutThe output count of elements copied.

◆ GetErrorText()

const std::string& Assimp::BaseImporter::GetErrorText ( ) const
inline

Returns the error description of the last error that occurred.

Returns
A description of the last error that occurred. An empty string if there was no error.

◆ GetExtension()

std::string BaseImporter::GetExtension ( const std::string &  pFile)
static

Extract file extension from a string.

Parameters
pFileInput file
Returns
Extension without trailing dot, all lowercase

◆ GetExtensionList()

void BaseImporter::GetExtensionList ( std::set< std::string > &  extensions)

Called by #Importer::GetExtensionList for each loaded importer.

Take the extension list contained in the structure returned by GetInfo and insert all file extensions into the given set.

Parameters
extensionset to collect file extensions in

◆ GetInfo()

◆ InternReadFile()

virtual void Assimp::BaseImporter::InternReadFile ( const std::string &  pFile,
aiScene pScene,
IOSystem pIOHandler 
)
protectedpure 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.

Implemented in Assimp::XGLImporter, Assimp::XFileImporter, Assimp::X3DImporter, Assimp::UnrealImporter, Assimp::TerragenImporter, Assimp::STLImporter, Assimp::SMDImporter, Assimp::SIBImporter, Assimp::RAWImporter, Assimp::Q3DImporter, Assimp::PLYImporter, Assimp::Ogre::OgreImporter, Assimp::OFFImporter, Assimp::NFFImporter, Assimp::NDOImporter, Assimp::MS3DImporter, Assimp::MDLImporter, Assimp::MDCImporter, Assimp::MD5Importer, Assimp::MD3Importer, Assimp::MD2Importer, Assimp::LWSImporter, Assimp::LWOImporter, Assimp::IRRMeshImporter, Assimp::IRRImporter, Assimp::IFCImporter, Assimp::HMPImporter, Assimp::glTFImporter, Assimp::glTF2Importer, Assimp::FBXImporter, Assimp::DXFImporter, Assimp::D3MFImporter, Assimp::CSMImporter, Assimp::ColladaLoader, Assimp::COBImporter, Assimp::C4DImporter, Assimp::BVHLoader, Assimp::BlenderImporter, Assimp::B3DImporter, Assimp::AssbinImporter, Assimp::ASEImporter, Assimp::AMFImporter, Assimp::AC3DImporter, Assimp::Discreet3DSImporter, and Assimp::OpenGEX::OpenGEXImporter.

◆ ReadFile()

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

◆ SearchFileHeaderForToken()

bool BaseImporter::SearchFileHeaderForToken ( IOSystem pIOSystem,
const std::string &  file,
const char **  tokens,
unsigned int  numTokens,
unsigned int  searchBytes = 200,
bool  tokensSol = false 
)
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.

◆ SetupProperties()

◆ SimpleExtensionCheck()

bool 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

◆ TextFileToBuffer()

void BaseImporter::TextFileToBuffer ( IOStream stream,
std::vector< char > &  data,
TextFileMode  mode = FORBID_EMPTY 
)
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.
modeWhether it is OK to load empty text files.

Friends And Related Function Documentation

◆ Importer

friend class Importer
friend

Member Data Documentation

◆ m_ErrorText

std::string Assimp::BaseImporter::m_ErrorText
protected

Error description in case there was one.

◆ m_progress

ProgressHandler* Assimp::BaseImporter::m_progress
protected

Currently set progress handler.


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