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

#include <BaseImporter.h>

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

Public Member Functions
	BaseImporter () AI_NO_EXCEPT
	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...

const std::exception_ptr &	GetException () const
	Returns the exception of the last exception that occurred. More...

void	GetExtensionList (std::set< std::string > &extensions)
	Called by #Importer::GetExtensionList for each loaded importer. More...

virtual const aiImporterDesc *	GetInfo () const =0
	Called by #Importer::GetImporterInfo to get a description of some loader features. More...

aiScene *	ReadFile (Importer pImp, const std::string &pFile, IOSystem pIOHandler)
	Imports the given file and returns the imported data. More...

void	SetFileScale (double scale)
	Will be called only by scale process when scaling is requested. 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, std::size_t 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< std::unique_ptr< T > > &vec, T **&out, unsigned int &outLength)
	Utility function to move a std::vector of unique_ptrs into a aiScene array. 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, std::size_t numTokens, unsigned int searchBytes=200, bool tokensSol=false, bool noAlphaBeforeTokens=false)
	A utility for CanRead(). More...

static bool	SimpleExtensionCheck (const std::string &pFile, const char ext0, const char ext1=nullptr, const char *ext2=nullptr)
	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
double	fileScale = 1.0

double	importerScale = 1.0

std::string	m_ErrorText
	Error description in case there was one. More...

std::exception_ptr	m_Exception
	The exception, in case there was one. More...

ProgressHandler *	m_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 Assimp::BaseImporter::TextFileMode

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

Enumerator
ALLOW_EMPTY
FORBID_EMPTY

Constructor & Destructor Documentation

◆ BaseImporter()

Assimp::BaseImporter::BaseImporter ( )

Constructor to be privately used by Importer.

◆ ~BaseImporter()

virtual Assimp::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 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

pFile	Path and file name of the file to be examined.
pIOHandler	The IO handler to use for accessing any file.
checkSig	Legacy; do not use.

Returns: true if the class can read this file, false if not or if unsure.

◆ CheckMagicToken()

static bool Assimp::BaseImporter::CheckMagicToken	(	IOSystem *	pIOHandler,
		const std::string &	pFile,
		const void *	magic,
		std::size_t	num,
		unsigned int	offset = `0`,
		unsigned int	size = `4`
	)

static

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

Parameters

pFile	Input file
pIOHandler	IO system to be used
magic	n magic tokens @params num Size of magic
offset	Offset from file start where tokens are located
Size	of 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()

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

data	File buffer to be converted to UTF8 data. The buffer is resized as appropriate.

◆ ConvertUTF8toISO8859_1()

static void Assimp::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

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

◆ CopyVector() [1/2]

template<typename T >

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

inlinestatic

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

Parameters

vec	The vector of unique_ptrs to be moved
out	The output pointer to the allocated array.
numOut	The output count of elements copied.

◆ CopyVector() [2/2]

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

vec	The vector to be moved
out	The output pointer to the allocated array.
numOut	The output count of elements copied.

◆ GetErrorText()

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

inline

Returns the error description of the last error that occurred.

If the error is due to a std::exception, this will return the message. Exceptions can also be accessed with GetException().

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

◆ GetException()

const std::exception_ptr & Assimp::BaseImporter::GetException ( ) const

inline

Returns the exception of the last exception that occurred.

Note: Exceptions are not the only source of error details, so GetErrorText should be consulted too.

Returns: The last exception that occurred.

◆ GetExtension()

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

static

Extract file extension from a string.

Parameters

pFile Input file

Returns: Extension without trailing dot, all lowercase

◆ GetExtensionList()

void Assimp::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

extension set to collect file extensions in

◆ GetInfo()

virtual const aiImporterDesc * Assimp::BaseImporter::GetInfo ( ) const

pure virtual

Called by #Importer::GetImporterInfo to get a description of some loader features.

Importers must provide this information.

◆ 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 nullptr 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

pFile	Path of the file to be imported.
pScene	The scene object to hold the imported data. nullptr is not a valid parameter.
pIOHandler	The IO handler to use for any file access. nullptr is not a valid parameter.

◆ ReadFile()

aiScene * Assimp::BaseImporter::ReadFile	(	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, nullptr is returned. The function takes care that any partially constructed data is destroyed beforehand.

Parameters

pImp	Importer object hosting this loader.
pFile	Path of the file to be imported.
pIOHandler	IO-Handler used to open this and possible other files.

Returns: The imported data or nullptr 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()

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

pIOSystem	IO System to work with
file	File name of the file
tokens	List of tokens to search for
numTokens	Size of the token array
searchBytes	Number of bytes to be searched for the tokens.

◆ SetFileScale()

void Assimp::BaseImporter::SetFileScale ( double scale )

inline

Will be called only by scale process when scaling is requested.

◆ SetupProperties()

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

pImp	Importer instance

◆ SimpleExtensionCheck()

static bool Assimp::BaseImporter::SimpleExtensionCheck	(	const std::string &	pFile,
		const char *	ext0,
		const char *	ext1 = `nullptr`,
		const char *	ext2 = `nullptr`
	)

static

Check whether a file has a specific file extension.

Parameters

pFile	Input file
ext0	Extension to check for. Lowercase characters only, no dot!
ext1	Optional second extension
ext2	Optional third extension

Note: Case-insensitive

◆ TextFileToBuffer()

static void Assimp::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

stream	Stream to read from.
data	Output buffer to be resized and filled with the converted text file data. The buffer is terminated with a binary 0.
mode	Whether it is OK to load empty text files.

Friends And Related Function Documentation

◆ Importer

friend class Importer

friend

Member Data Documentation

◆ fileScale

double Assimp::BaseImporter::fileScale = 1.0

protected

◆ importerScale

double Assimp::BaseImporter::importerScale = 1.0

protected

◆ m_ErrorText

std::string Assimp::BaseImporter::m_ErrorText

protected

Error description in case there was one.

◆ m_Exception

std::exception_ptr Assimp::BaseImporter::m_Exception

protected

The exception, 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 file:

BaseImporter.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ TextFileMode

Constructor & Destructor Documentation

◆ BaseImporter()

◆ ~BaseImporter()

Member Function Documentation

◆ CanRead()

◆ CheckMagicToken()

◆ ConvertToUTF8()

◆ ConvertUTF8toISO8859_1()

◆ CopyVector() [1/2]

◆ CopyVector() [2/2]

◆ GetErrorText()

◆ GetException()

◆ GetExtension()

◆ GetExtensionList()

◆ GetInfo()

◆ InternReadFile()

◆ ReadFile()

◆ SearchFileHeaderForToken()

◆ SetFileScale()

◆ SetupProperties()

◆ SimpleExtensionCheck()

◆ TextFileToBuffer()

Friends And Related Function Documentation

◆ Importer

Member Data Documentation

◆ fileScale

◆ importerScale

◆ m_ErrorText

◆ m_Exception

◆ m_progress