Assimp  v3.1.1 (June 2014)
Assimp.cpp File Reference

Implementation of the Plain-C API. More...

Classes

struct  Assimp::mpred
 Stores the LogStream objects for all active C log streams. More...
 
class  LogToCallbackRedirector
 

Namespaces

 Assimp
 MACHINE-GENERATED by scripts/ICFImporter/CppGenerator.py.
 

Typedefs

typedef std::map< aiLogStream, Assimp::LogStream *, mpredAssimp::LogStreamMap
 
typedef std::list< Assimp::LogStream * > Assimp::PredefLogStreamMap
 Stores the LogStream objects allocated by aiGetPredefinedLogStream. More...
 
typedef BatchLoader::PropertyMap Assimp::PropertyMap
 

Functions

ASSIMP_API const aiSceneaiApplyCustomizedPostProcessing (const aiScene *scene, BaseProcess *process, bool requestValidation)
 
ASSIMP_API const aiSceneaiApplyPostProcessing (const aiScene *pScene, unsigned int pFlags)
 Apply post-processing to an already-imported scene. More...
 
ASSIMP_API void aiAttachLogStream (const aiLogStream *stream)
 Attach a custom log stream to the libraries' logging system. More...
 
ASSIMP_API aiPropertyStoreaiCreatePropertyStore (void)
 Create an empty property store. More...
 
ASSIMP_API void aiCreateQuaternionFromMatrix (aiQuaternion *quat, const aiMatrix3x3 *mat)
 Construct a quaternion from a 3x3 rotation matrix. More...
 
ASSIMP_API void aiDecomposeMatrix (const aiMatrix4x4 *mat, aiVector3D *scaling, aiQuaternion *rotation, aiVector3D *position)
 Decompose a transformation matrix into its rotational, translational and scaling components. More...
 
ASSIMP_API void aiDetachAllLogStreams (void)
 Detach all active log streams from the libraries' logging system. More...
 
ASSIMP_API aiReturn aiDetachLogStream (const aiLogStream *stream)
 Detach a custom log stream from the libraries' logging system. More...
 
ASSIMP_API void aiEnableVerboseLogging (aiBool d)
 Enable verbose logging. More...
 
const char * aiGetErrorString ()
 Returns the error text of the last failed import process. More...
 
void aiGetExtensionList (aiString *szOut)
 Get a list of all file extensions supported by ASSIMP. More...
 
ASSIMP_API C_STRUCT const aiImporterDescaiGetImporterDesc (const char *extension)
 Returns the Importer description for a given extension. More...
 
size_t aiGetImportFormatCount (void)
 Returns the number of import file formats available in the current Assimp build. More...
 
const aiImporterDescaiGetImportFormatDescription (size_t pIndex)
 Returns a description of the nth import file format. More...
 
void aiGetMemoryRequirements (const C_STRUCT aiScene *pIn, C_STRUCT aiMemoryInfo *in)
 
ASSIMP_API aiLogStream aiGetPredefinedLogStream (aiDefaultLogStream pStream, const char *file)
 Get one of the predefine log streams. More...
 
ASSIMP_API void aiIdentityMatrix3 (aiMatrix3x3 *mat)
 Get a 3x3 identity matrix. More...
 
ASSIMP_API void aiIdentityMatrix4 (aiMatrix4x4 *mat)
 Get a 4x4 identity matrix. More...
 
const aiSceneaiImportFile (const char *pFile, unsigned int pFlags)
 Reads the given file and returns its content. More...
 
const aiSceneaiImportFileEx (const char *pFile, unsigned int pFlags, aiFileIO *pFS)
 Reads the given file using user-defined I/O functions and returns its content. More...
 
const aiSceneaiImportFileExWithProperties (const char *pFile, unsigned int pFlags, aiFileIO *pFS, const aiPropertyStore *props)
 Same as aiImportFileEx, but adds an extra parameter containing importer settings. More...
 
const aiSceneaiImportFileFromMemory (const char *pBuffer, unsigned int pLength, unsigned int pFlags, const char *pHint)
 Reads the given file from a given memory buffer,. More...
 
const aiSceneaiImportFileFromMemoryWithProperties (const char *pBuffer, unsigned int pLength, unsigned int pFlags, const char *pHint, const aiPropertyStore *props)
 Same as aiImportFileFromMemory, but adds an extra parameter containing importer settings. More...
 
aiBool aiIsExtensionSupported (const char *szExtension)
 Returns whether a given file extension is supported by ASSIMP. More...
 
ASSIMP_API void aiMultiplyMatrix3 (aiMatrix3x3 *dst, const aiMatrix3x3 *src)
 Multiply two 3x3 matrices. More...
 
ASSIMP_API void aiMultiplyMatrix4 (aiMatrix4x4 *dst, const aiMatrix4x4 *src)
 Multiply two 4x4 matrices. More...
 
void aiReleaseImport (const aiScene *pScene)
 Releases all resources associated with the given import process. More...
 
ASSIMP_API void aiReleasePropertyStore (aiPropertyStore *p)
 Delete a property store. More...
 
ASSIMP_API void aiSetImportPropertyFloat (aiPropertyStore *p, const char *szName, float value)
 Set a floating-point property. More...
 
ASSIMP_API void aiSetImportPropertyInteger (aiPropertyStore *p, const char *szName, int value)
 Set an integer property. More...
 
ASSIMP_API void aiSetImportPropertyMatrix (aiPropertyStore *p, const char *szName, const C_STRUCT aiMatrix4x4 *mat)
 
ASSIMP_API void aiSetImportPropertyString (aiPropertyStore *p, const char *szName, const C_STRUCT aiString *st)
 
ASSIMP_API void aiTransformVecByMatrix3 (aiVector3D *vec, const aiMatrix3x3 *mat)
 Transform a vector by a 3x3 matrix. More...
 
ASSIMP_API void aiTransformVecByMatrix4 (aiVector3D *vec, const aiMatrix4x4 *mat)
 Transform a vector by a 4x4 matrix. More...
 
ASSIMP_API void aiTransposeMatrix3 (aiMatrix3x3 *mat)
 Transpose a 3x3 matrix. More...
 
ASSIMP_API void aiTransposeMatrix4 (aiMatrix4x4 *mat)
 Transpose a 4x4 matrix. More...
 
void CallbackToLogRedirector (const char *msg, char *dt)
 
void Assimp::DeleteImporterInstanceList (std::vector< BaseImporter * > &out)
 will delete all registered importers. More...
 
void Assimp::GetImporterInstanceList (std::vector< BaseImporter * > &out)
 will return all registered importers. More...
 
void ReportSceneNotFoundError ()
 

Variables

static LogStreamMap Assimp::gActiveLogStreams
 Local storage of all active log streams. More...
 
static std::string Assimp::gLastErrorString
 Error message of the last failed import process. More...
 
static std::mutex gLogStreamMutex
 Global mutex to manage the access to the log-stream map. More...
 
static PredefLogStreamMap Assimp::gPredefinedStreams
 Local storage of LogStreams allocated by aiGetPredefinedLogStream. More...
 
static aiBool Assimp::gVerboseLogging = false
 Verbose logging active or not? More...
 

Detailed Description

Implementation of the Plain-C API.

Function Documentation

◆ aiApplyCustomizedPostProcessing()

ASSIMP_API const aiScene* aiApplyCustomizedPostProcessing ( const aiScene scene,
BaseProcess process,
bool  requestValidation 
)

◆ aiApplyPostProcessing()

ASSIMP_API const aiScene* aiApplyPostProcessing ( const aiScene pScene,
unsigned int  pFlags 
)

Apply post-processing to an already-imported scene.

This is strictly equivalent to calling aiImportFile()/aiImportFileEx with the same flags. However, you can use this separate function to inspect the imported scene first to fine-tune your post-processing setup.

Parameters
pSceneScene to work on.
pFlagsProvide a bitwise combination of the aiPostProcessSteps flags.
Returns
A pointer to the post-processed data. Post processing is done in-place, meaning this is still the same aiScene which you passed for pScene. However, if post-processing failed, the scene could now be NULL. That's quite a rare case, post processing steps are not really designed to 'fail'. To be exact, the aiProcess_ValidateDataStructure flag is currently the only post processing step which can actually cause the scene to be reset to NULL.

◆ aiAttachLogStream()

ASSIMP_API void aiAttachLogStream ( const aiLogStream stream)

Attach a custom log stream to the libraries' logging system.

Attaching a log stream can slightly reduce Assimp's overall import performance. Multiple log-streams can be attached.

Parameters
streamDescribes the new log stream.
Note
To ensure proper destruction of the logging system, you need to manually call aiDetachLogStream() on every single log stream you attach. Alternatively (for the lazy folks) aiDetachAllLogStreams is provided.

◆ aiCreatePropertyStore()

ASSIMP_API aiPropertyStore* aiCreatePropertyStore ( void  )

Create an empty property store.

Property stores are used to collect import settings.

Returns
New property store. Property stores need to be manually destroyed using the aiReleasePropertyStore API function.

◆ aiCreateQuaternionFromMatrix()

ASSIMP_API void aiCreateQuaternionFromMatrix ( aiQuaternion quat,
const aiMatrix3x3 mat 
)

Construct a quaternion from a 3x3 rotation matrix.

Parameters
quatReceives the output quaternion.
matMatrix to 'quaternionize'.
See also
aiQuaternion(const aiMatrix3x3& pRotMatrix)

◆ aiDecomposeMatrix()

ASSIMP_API void aiDecomposeMatrix ( const aiMatrix4x4 mat,
aiVector3D scaling,
aiQuaternion rotation,
aiVector3D position 
)

Decompose a transformation matrix into its rotational, translational and scaling components.

Parameters
matMatrix to decompose
scalingReceives the scaling component
rotationReceives the rotational component
positionReceives the translational component.
See also
aiMatrix4x4::Decompose (aiVector3D&, aiQuaternion&, aiVector3D&) const;

◆ aiDetachAllLogStreams()

ASSIMP_API void aiDetachAllLogStreams ( void  )

Detach all active log streams from the libraries' logging system.

This ensures that the logging system is terminated properly and all resources allocated by it are actually freed. If you attached a stream, don't forget to detach it again.

See also
aiAttachLogStream
aiDetachLogStream

◆ aiDetachLogStream()

ASSIMP_API aiReturn aiDetachLogStream ( const aiLogStream stream)

Detach a custom log stream from the libraries' logging system.

This is the counterpart of aiAttachLogStream. If you attached a stream, don't forget to detach it again.

Parameters
streamThe log stream to be detached.
Returns
AI_SUCCESS if the log stream has been detached successfully.
See also
aiDetachAllLogStreams

◆ aiEnableVerboseLogging()

ASSIMP_API void aiEnableVerboseLogging ( aiBool  d)

Enable verbose logging.

Verbose logging includes debug-related stuff and detailed import statistics. This can have severe impact on import performance and memory consumption. However, it might be useful to find out why a file didn't read correctly.

Parameters
dAI_TRUE or AI_FALSE, your decision.

◆ aiGetErrorString()

const char* aiGetErrorString ( )

Returns the error text of the last failed import process.

Returns
A textual description of the error that occurred at the last import process. NULL if there was no error. There can't be an error if you got a non-NULL aiScene from aiImportFile/aiImportFileEx/aiApplyPostProcessing.

◆ aiGetExtensionList()

void aiGetExtensionList ( aiString szOut)

Get a list of all file extensions supported by ASSIMP.

If a file extension is contained in the list this does, of course, not mean that ASSIMP is able to load all files with this extension.

Parameters
szOutString to receive the extension list. Format of the list: "*.3ds;*.obj;*.dae". NULL is not a valid parameter.

◆ aiGetImporterDesc()

ASSIMP_API C_STRUCT const aiImporterDesc* aiGetImporterDesc ( const char *  extension)

Returns the Importer description for a given extension.

Will return a NULL-pointer if no assigned importer desc. was found for the given extension

Parameters
extension[in] The extension to look for
Returns
A pointer showing to the ImporterDesc,
See also
aiImporterDesc.

◆ aiGetImportFormatCount()

size_t aiGetImportFormatCount ( void  )

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

Use aiGetImportFormatDescription() to retrieve infos of a specific import format.

◆ aiGetImportFormatDescription()

const aiImporterDesc* aiGetImportFormatDescription ( size_t  pIndex)

Returns a description of the nth import file format.

Use aiGetImportFormatCount() to learn how many import formats are supported.

Parameters
pIndexIndex of the import format to retrieve information for. Valid range is 0 to aiGetImportFormatCount()
Returns
A description of that specific import format. NULL if pIndex is out of range.

◆ aiGetMemoryRequirements()

void aiGetMemoryRequirements ( const C_STRUCT aiScene pIn,
C_STRUCT aiMemoryInfo in 
)

◆ aiGetPredefinedLogStream()

ASSIMP_API aiLogStream aiGetPredefinedLogStream ( aiDefaultLogStream  pStreams,
const char *  file 
)

Get one of the predefine log streams.

This is the quick'n'easy solution to access Assimp's log system. Attaching a log stream can slightly reduce Assimp's overall import performance.

Usage is rather simple (this will stream the log to a file, named log.txt, and the stdout stream of the process:

Parameters
pStreamsOne of the aiDefaultLogStream enumerated values.
fileSolely for the aiDefaultLogStream_FILE flag: specifies the file to write to. Pass NULL for all other flags.
Returns
The log stream. callback is set to NULL if something went wrong.

◆ aiIdentityMatrix3()

ASSIMP_API void aiIdentityMatrix3 ( aiMatrix3x3 mat)

Get a 3x3 identity matrix.

Parameters
matMatrix to receive its personal identity

◆ aiIdentityMatrix4()

ASSIMP_API void aiIdentityMatrix4 ( aiMatrix4x4 mat)

Get a 4x4 identity matrix.

Parameters
matMatrix to receive its personal identity

◆ aiImportFile()

const aiScene* aiImportFile ( const char *  pFile,
unsigned int  pFlags 
)

Reads the given file and returns its content.

If the call succeeds, the imported data is returned in an aiScene structure. The data is intended to be read-only, it stays property of the ASSIMP library and will be stable until aiReleaseImport() is called. After you're done with it, call aiReleaseImport() to free the resources associated with this file. If the import fails, NULL is returned instead. Call aiGetErrorString() to retrieve a human-readable error text.

Parameters
pFilePath and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlagsOptional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags.
Returns
Pointer to the imported data or NULL if the import failed.

◆ aiImportFileEx()

const aiScene* aiImportFileEx ( const char *  pFile,
unsigned int  pFlags,
aiFileIO pFS 
)

Reads the given file using user-defined I/O functions and returns its content.

If the call succeeds, the imported data is returned in an aiScene structure. The data is intended to be read-only, it stays property of the ASSIMP library and will be stable until aiReleaseImport() is called. After you're done with it, call aiReleaseImport() to free the resources associated with this file. If the import fails, NULL is returned instead. Call aiGetErrorString() to retrieve a human-readable error text.

Parameters
pFilePath and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlagsOptional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags.
pFSaiFileIO structure. Will be used to open the model file itself and any other files the loader needs to open. Pass NULL to use the default implementation.
Returns
Pointer to the imported data or NULL if the import failed.
Note
Include <aiFileIO.h> for the definition of aiFileIO.

◆ aiImportFileExWithProperties()

const aiScene* aiImportFileExWithProperties ( const char *  pFile,
unsigned int  pFlags,
aiFileIO pFS,
const aiPropertyStore pProps 
)

Same as aiImportFileEx, but adds an extra parameter containing importer settings.

Parameters
pFilePath and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlagsOptional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags.
pFSaiFileIO structure. Will be used to open the model file itself and any other files the loader needs to open. Pass NULL to use the default implementation.
pPropsaiPropertyStore instance containing import settings.
Returns
Pointer to the imported data or NULL if the import failed.
Note
Include <aiFileIO.h> for the definition of aiFileIO.
See also
aiImportFileEx

◆ aiImportFileFromMemory()

const aiScene* aiImportFileFromMemory ( const char *  pBuffer,
unsigned int  pLength,
unsigned int  pFlags,
const char *  pHint 
)

Reads the given file from a given memory buffer,.

If the call succeeds, the contents of the file are returned as a pointer to an aiScene object. The returned data is intended to be read-only, the importer keeps ownership of the data and will destroy it upon destruction. If the import fails, NULL is returned. A human-readable error description can be retrieved by calling aiGetErrorString().

Parameters
pBufferPointer to the file data
pLengthLength of pBuffer, in bytes
pFlagsOptional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags. If you wish to inspect the imported scene first in order to fine-tune your post-processing setup, consider to use aiApplyPostProcessing().
pHintAn additional hint to the library. If this is a non empty string, the library looks for a loader to support the file extension specified by pHint and passes the file to the first matching loader. If this loader is unable to completely the request, the library continues and tries to determine the file format on its own, a task that may or may not be successful. Check the return value, and you'll know ...
Returns
A pointer to the imported data, NULL if the import failed.
Note
This is a straightforward way to decode models from memory buffers, but it doesn't handle model formats that spread their data across multiple files or even directories. Examples include OBJ or MD3, which outsource parts of their material info into external scripts. If you need full functionality, provide a custom IOSystem to make Assimp find these files and use the regular aiImportFileEx()/aiImportFileExWithProperties() API.

◆ aiImportFileFromMemoryWithProperties()

const aiScene* aiImportFileFromMemoryWithProperties ( const char *  pBuffer,
unsigned int  pLength,
unsigned int  pFlags,
const char *  pHint,
const aiPropertyStore pProps 
)

Same as aiImportFileFromMemory, but adds an extra parameter containing importer settings.

Parameters
pBufferPointer to the file data
pLengthLength of pBuffer, in bytes
pFlagsOptional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags. If you wish to inspect the imported scene first in order to fine-tune your post-processing setup, consider to use aiApplyPostProcessing().
pHintAn additional hint to the library. If this is a non empty string, the library looks for a loader to support the file extension specified by pHint and passes the file to the first matching loader. If this loader is unable to completely the request, the library continues and tries to determine the file format on its own, a task that may or may not be successful. Check the return value, and you'll know ...
pPropsaiPropertyStore instance containing import settings.
Returns
A pointer to the imported data, NULL if the import failed.
Note
This is a straightforward way to decode models from memory buffers, but it doesn't handle model formats that spread their data across multiple files or even directories. Examples include OBJ or MD3, which outsource parts of their material info into external scripts. If you need full functionality, provide a custom IOSystem to make Assimp find these files and use the regular aiImportFileEx()/aiImportFileExWithProperties() API.
See also
aiImportFileFromMemory

◆ aiIsExtensionSupported()

aiBool aiIsExtensionSupported ( const char *  szExtension)

Returns whether a given file extension is supported by ASSIMP.

Parameters
szExtensionExtension for which the function queries support for. Must include a leading dot '.'. Example: ".3ds", ".md3"
Returns
AI_TRUE if the file extension is supported.

◆ aiMultiplyMatrix3()

ASSIMP_API void aiMultiplyMatrix3 ( aiMatrix3x3 dst,
const aiMatrix3x3 src 
)

Multiply two 3x3 matrices.

Parameters
dstFirst factor, receives result.
srcMatrix to be multiplied with 'dst'.

◆ aiMultiplyMatrix4()

ASSIMP_API void aiMultiplyMatrix4 ( aiMatrix4x4 dst,
const aiMatrix4x4 src 
)

Multiply two 4x4 matrices.

Parameters
dstFirst factor, receives result.
srcMatrix to be multiplied with 'dst'.

◆ aiReleaseImport()

void aiReleaseImport ( const aiScene pScene)

Releases all resources associated with the given import process.

Call this function after you're done with the imported data.

Parameters
pSceneThe imported data to release. NULL is a valid value.

◆ aiReleasePropertyStore()

ASSIMP_API void aiReleasePropertyStore ( aiPropertyStore p)

Delete a property store.

Parameters
pProperty store to be deleted.

◆ aiSetImportPropertyFloat()

ASSIMP_API void aiSetImportPropertyFloat ( aiPropertyStore store,
const char *  szName,
float  value 
)

Set a floating-point property.

This is the C-version of Assimp::Importer::SetPropertyFloat(). In the C interface, properties are always shared by all imports. It is not possible to specify them per import.

Parameters
storeStore to modify. Use aiCreatePropertyStore to obtain a store.
szNameName of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
valueNew value for the property

◆ aiSetImportPropertyInteger()

ASSIMP_API void aiSetImportPropertyInteger ( aiPropertyStore store,
const char *  szName,
int  value 
)

Set an integer property.

This is the C-version of Assimp::Importer::SetPropertyInteger(). In the C interface, properties are always shared by all imports. It is not possible to specify them per import.

Parameters
storeStore to modify. Use aiCreatePropertyStore to obtain a store.
szNameName of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
valueNew value for the property

◆ aiSetImportPropertyMatrix()

ASSIMP_API void aiSetImportPropertyMatrix ( aiPropertyStore p,
const char *  szName,
const C_STRUCT aiMatrix4x4 mat 
)

◆ aiSetImportPropertyString()

ASSIMP_API void aiSetImportPropertyString ( aiPropertyStore p,
const char *  szName,
const C_STRUCT aiString st 
)

◆ aiTransformVecByMatrix3()

ASSIMP_API void aiTransformVecByMatrix3 ( aiVector3D vec,
const aiMatrix3x3 mat 
)

Transform a vector by a 3x3 matrix.

Parameters
vecVector to be transformed.
matMatrix to transform the vector with.

◆ aiTransformVecByMatrix4()

ASSIMP_API void aiTransformVecByMatrix4 ( aiVector3D vec,
const aiMatrix4x4 mat 
)

Transform a vector by a 4x4 matrix.

Parameters
vecVector to be transformed.
matMatrix to transform the vector with.

◆ aiTransposeMatrix3()

ASSIMP_API void aiTransposeMatrix3 ( aiMatrix3x3 mat)

Transpose a 3x3 matrix.

Parameters
matPointer to the matrix to be transposed

◆ aiTransposeMatrix4()

ASSIMP_API void aiTransposeMatrix4 ( aiMatrix4x4 mat)

Transpose a 4x4 matrix.

Parameters
matPointer to the matrix to be transposed

◆ CallbackToLogRedirector()

void CallbackToLogRedirector ( const char *  msg,
char *  dt 
)

◆ ReportSceneNotFoundError()

void ReportSceneNotFoundError ( )

Variable Documentation

◆ gLogStreamMutex

std::mutex gLogStreamMutex
static

Global mutex to manage the access to the log-stream map.

aiAttachLogStream
ASSIMP_API void aiAttachLogStream(const aiLogStream *stream)
Attach a custom log stream to the libraries' logging system.
Definition: Assimp.cpp:381
aiDefaultLogStream_STDOUT
@ aiDefaultLogStream_STDOUT
Stream the log to std::cout.
Definition: types.h:433
aiDefaultLogStream_FILE
@ aiDefaultLogStream_FILE
Stream the log to a file.
Definition: types.h:430
aiLogStream
C-API: Represents a log stream.
Definition: cimport.h:66
aiGetPredefinedLogStream
ASSIMP_API aiLogStream aiGetPredefinedLogStream(aiDefaultLogStream pStream, const char *file)
Get one of the predefine log streams.
Definition: Assimp.cpp:361