Assimp: cimport.h File Reference

Our own C boolean type.

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

pScene	Scene to work on.
pFlags	Provide 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.

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

stream

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

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.

Construct a quaternion from a 3x3 rotation matrix.

Parameters

quat	Receives the output quaternion.
mat	Matrix to 'quaternionize'.

See also

aiQuaternion(const aiMatrix3x3& pRotMatrix)

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

Parameters

mat	Matrix to decompose
scaling	Receives the scaling component
rotation	Receives the rotational component
position	Receives the translational component.

See also

aiMatrix4x4::Decompose (aiVector3D&, aiQuaternion&, aiVector3D&) const;

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

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

stream

The log stream to be detached.

Returns

AI_SUCCESS if the log stream has been detached successfully.

See also

aiDetachAllLogStreams

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

d	AI_TRUE or AI_FALSE, your decision.

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.

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

szOut

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

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

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

Returns a description of the nth import file format.

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

Parameters

pIndex

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

Get the approximated storage required by an imported asset.

Parameters

pIn	Input asset.
in	Data structure to be filled.

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

pStreams	One of the aiDefaultLogStream enumerated values.
file	Solely 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.

Get a 3x3 identity matrix.

Parameters

mat	Matrix to receive its personal identity

Get a 4x4 identity matrix.

Parameters

mat	Matrix to receive its personal identity

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

pFile	Path and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlags	Optional 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.

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

pFile	Path and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlags	Optional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags.
pFS	aiFileIO 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.

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

Parameters

pFile	Path and filename of the file to be imported, expected to be a null-terminated c-string. NULL is not a valid value.
pFlags	Optional post processing steps to be executed after a successful import. Provide a bitwise combination of the aiPostProcessSteps flags.
pFS	aiFileIO 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.
pProps	aiPropertyStore 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

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

pBuffer	Pointer to the file data
pLength	Length of pBuffer, in bytes
pFlags	Optional 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().
pHint	An 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.

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

Parameters

pBuffer	Pointer to the file data
pLength	Length of pBuffer, in bytes
pFlags	Optional 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().
pHint	An 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 ...
pProps	aiPropertyStore 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

Returns whether a given file extension is supported by ASSIMP.

Parameters

szExtension

Extension for which the function queries support for. Must include a leading dot '.'. Example: ".3ds", ".md3"

Returns

AI_TRUE if the file extension is supported.

Multiply two 3x3 matrices.

Parameters

dst	First factor, receives result.
src	Matrix to be multiplied with 'dst'.

Multiply two 4x4 matrices.

Parameters

dst	First factor, receives result.
src	Matrix to be multiplied with 'dst'.

Releases all resources associated with the given import process.

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

Parameters

pScene

The imported data to release. NULL is a valid value.

Delete a property store.

Parameters

p	Property store to be deleted.

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

store	Store to modify. Use aiCreatePropertyStore to obtain a store.
szName	Name of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
value	New value for the property

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

store	Store to modify. Use aiCreatePropertyStore to obtain a store.
szName	Name of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
value	New value for the property

Set a matrix property.

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

Parameters

store	Store to modify. Use aiCreatePropertyStore to obtain a store.
szName	Name of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
mat	New value for the property

Set a string property.

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

Parameters

store	Store to modify. Use aiCreatePropertyStore to obtain a store.
szName	Name of the configuration property to be set. All supported public properties are defined in the config.h header file (AI_CONFIG_XXX).
st	New value for the property

Transform a vector by a 3x3 matrix.

Parameters

vec	Vector to be transformed.
mat	Matrix to transform the vector with.

Transform a vector by a 4x4 matrix.

Parameters

vec	Vector to be transformed.
mat	Matrix to transform the vector with.

Transpose a 3x3 matrix.

Parameters

mat	Pointer to the matrix to be transposed

Transpose a 4x4 matrix.

Parameters

mat	Pointer to the matrix to be transposed