#include <BaseImporter.h>

Public Types
enum	ImporterUnits { M, MM, CM, INCHES, FEET }

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

Public Member Functions
	BaseImporter () AI_NO_EXCEPT

virtual	~BaseImporter ()

virtual bool	CanRead (const std::string &pFile, IOSystem *pIOHandler, bool checkSig) const =0

aiScene *	ReadFile (Importer pImp, const std::string &pFile, IOSystem pIOHandler)

const std::string &	GetErrorText () const

const std::exception_ptr &	GetException () const

virtual void	SetupProperties (const Importer *pImp)

virtual const aiImporterDesc *	GetInfo () const =0

virtual void	SetFileScale (double scale)

virtual double	GetFileScale () const

virtual void	SetApplicationUnits (const ImporterUnits &unit)

virtual const ImporterUnits &	GetApplicationUnits ()

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

Static Public Member Functions
static bool	SearchFileHeaderForToken (IOSystem pIOSystem, const std::string &file, const char *tokens, unsigned int numTokens, unsigned int searchBytes=200, bool tokensSol=false, bool noAlphaBeforeTokens=false)

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 std::string	GetExtension (const std::string &pFile)
	Extract file extension from a string. More...

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)

static void	ConvertUTF8toISO8859_1 (std::string &data)

static void	TextFileToBuffer (IOStream *stream, std::vector< char > &data, TextFileMode mode=FORBID_EMPTY)

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

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

Public Attributes
std::map< ImporterUnits, double >	importerUnits

Protected Member Functions
virtual void	InternReadFile (const std::string &pFile, aiScene pScene, IOSystem pIOHandler)=0

Protected Attributes
ImporterUnits	applicationUnits = ImporterUnits::M

double	importerScale = 1.0

double	fileScale = 1.0

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

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

ProgressHandler *	m_progress
	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

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

pFile	Path and file name of the file to be examined.
pIOHandler	The IO handler to use for accessing any file.
checkSig	Set 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.

◆ CheckMagicToken()

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

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,
		unsigned int	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()

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

inlinevirtual

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.

Member Data Documentation

◆ importerUnits

std::map<ImporterUnits, double> Assimp::BaseImporter::importerUnits

Assimp Importer unit conversions available NOTE: Valid options are initialised in the constructor in the implementation file to work around a VS2013 compiler bug if support for that compiler is dropped in the future initialisation can be moved back here

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

BaseImporter.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

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()

Member Data Documentation

◆ importerUnits