The API-Documentation

Common Datatypes

struct aiString

Represents an UTF-8 string, zero byte terminated.

The character set of an aiString is explicitly defined to be UTF-8. This Unicode transformation was chosen in the belief that most strings in 3d files are limited to ASCII, thus the character set needed to be strictly ASCII compatible.

Most text file loaders provide proper Unicode input file handling, special unicode characters are correctly transcoded to UTF8 and are kept throughout the libraries’ import pipeline.

For most applications, it will be absolutely sufficient to interpret the aiString as ASCII data and work with it as one would work with a plain char*. Windows users in need of proper support for i.e asian characters can use the MultiByteToWideChar(), WideCharToMultiByte() WinAPI functionality to convert the UTF-8 strings to their working character set (i.e. MBCS, WideChar).

We use this representation instead of std::string to be C-compatible. The (binary) length of such a string is limited to MAXLEN characters (including the the terminating zero).

Public Functions

aiString () AI_NO_EXCEPT

Default constructor, the string is set to have zero length.

aiString(const aiString &rOther)

Copy constructor.

aiString(const std::string &pString)

Constructor from std::string.

void Append(const char *app)

Append a string to the string.

const char *C_Str() const

Returns a pointer to the underlying zero-terminated array of characters.

void Clear()

Clear the string - reset its length to zero.

bool operator!=(const aiString &other) const

Inverse comparison operator.

aiString &operator=(const aiString &rOther)

Assignment operator.

aiString &operator=(const char *sz)

Assign a const char* to the string.

aiString &operator=(const std::string &pString)

Assign a cstd::string to the string.

bool operator==(const aiString &other) const

Comparison operator.

void Set(const char *sz)

Copy a const char* to the aiString.

void Set(const std::string &pString)

Copy a std::string to the aiString.

Public Members

char data[MAXLEN]

String buffer.

Size limit is MAXLEN

ai_uint32 length

Binary length of the string excluding the terminal 0.

This is NOT the logical length of strings containing UTF-8 multi-byte sequences! It’s the number of bytes from the beginning of the string to its end.

template<typename TReal>
class aiVector2t

Represents a two-dimensional vector.

template<typename TReal>
class aiVector3t

Represents a three-dimensional vector.

Public Functions

aiVector3t () AI_NO_EXCEPT

The default class constructor.

aiVector3t(const aiVector3t &o) = default

The copy constructor.

aiVector3t(TReal _x, TReal _y, TReal _z)

The class constructor with the components.

aiVector3t(TReal _xyz)

The class constructor with a default.

bool Equal(const aiVector3t &other, TReal epsilon = 1e-6) const

TReal Length() const

Get the length of the vector.

Return

length

aiVector3t &Normalize()

Normalize the vector.

aiVector3t &NormalizeSafe()

Normalize the vector with extra check for zero vectors.

aiVector3t &operator*=(const aiMatrix3x3t<TReal> &mat)

Transform vector by matrix.

const aiVector3t &operator+=(const aiVector3t &o)

combined operators

TReal &operator[](unsigned int i)

access a single element, non-const.

TReal operator[](unsigned int i) const

access a single element, const.

void Set(TReal pX, TReal pY, TReal pZ)

Set the components of a vector.

Parameters

• pX: X component

• pY: Y component

• pZ: Z component

TReal SquareLength() const

Get the squared length of the vector.

Return

Square length

const aiVector3t SymMul(const aiVector3t &o)

Componentwise multiplication of two vectors.

Note that vec*vec yields the dot product.

Parameters

• o: Second factor

template<typename TReal>
class aiColor4t

Represents a color in Red-Green-Blue space including an alpha component.

Color values range from 0 to 1.

Public Functions

bool IsBlack() const

check whether a color is (close to) black

template<typename TReal>
class aiQuaterniont

Represents a quaternion in a 4D vector.

Public Functions

aiQuaterniont(aiVector3t<TReal> axis, TReal angle)

Construct from an axis-angle pair.

aiQuaterniont(aiVector3t<TReal> normalized)

Construct from a normalized quaternion stored in a vec3.

aiQuaterniont(const aiMatrix3x3t<TReal> &pRotMatrix)

Construct from rotation matrix.

Result is undefined if the matrix is not orthonormal.

aiQuaterniont(TReal rotx, TReal roty, TReal rotz)

Construct from euler angles.

aiQuaterniont &Conjugate()

Compute quaternion conjugate.

aiMatrix3x3t<TReal> GetMatrix() const

Returns a matrix representation of the quaternion.

aiQuaterniont &Normalize()

Normalize the quaternion.

aiQuaterniont operator*(const aiQuaterniont &two) const

Multiply two quaternions.

aiVector3t<TReal> Rotate(const aiVector3t<TReal> &in) const

Rotate a point by this quaternion.

Public Members

TReal w

w,x,y,z components of the quaternion

Public Static Functions

void Interpolate(aiQuaterniont &pOut, const aiQuaterniont &pStart, const aiQuaterniont &pEnd, TReal pFactor)

Performs a spherical interpolation between two quaternions and writes the result into the third.

Parameters

• pOut: Target object to received the interpolated rotation.

• pStart: Start rotation of the interpolation at factor == 0.

• pEnd: End rotation, factor == 1.

• pFactor: Interpolation factor between 0 and 1. Values outside of this range yield undefined results.

template<typename TReal>
class aiMatrix3x3t

Represents a row-major 3x3 matrix.

There’s much confusion about matrix layouts (column vs. row order). This is always a row-major matrix. Not even with the aiProcess_ConvertToLeftHanded flag, which absolutely does not affect matrix order - it just affects the handedness of the coordinate system defined thereby.

Public Functions

aiMatrix3x3t(const aiMatrix4x4t<TReal> &pMatrix)

Construction from a 4x4 matrix.

The remaining parts of the matrix are ignored.

aiMatrix3x3t &Inverse()

Invert the matrix.

If the matrix is not invertible all elements are set to qnan. Beware, use (f != f) to check whether a TReal f is qnan.

aiMatrix3x3t &Transpose()

Transpose the matrix.

Public Static Functions

aiMatrix3x3t &FromToMatrix(const aiVector3t<TReal> &from, const aiVector3t<TReal> &to, aiMatrix3x3t &out)

A function for creating a rotation matrix that rotates a vector called “from” into another vector called “to”.

Input : from[3], to[3] which both must be normalized non-zero vectors Output: mtx[3][3] a 3x3 matrix in column-major form Authors: Tomas Möller, John Hughes “Efficiently Building a Matrix to Rotate One Vector to Another” Journal of Graphics Tools, 4(4):1-4, 1999

Input : from[3], to[3] which both must be normalized non-zero vectors Output: mtx[3][3] a 3x3 matrix in colum-major form Authors: Tomas Möller, John Hughes “Efficiently Building a Matrix to Rotate One Vector to Another” Journal of Graphics Tools, 4(4):1-4, 1999

aiMatrix3x3t &Rotation(TReal a, const aiVector3t<TReal> &axis, aiMatrix3x3t &out)

Returns a rotation matrix for a rotation around an arbitrary axis.

Parameters

• a: Rotation angle, in radians

• axis: Axis to rotate around

• out: To be filled

aiMatrix3x3t &RotationZ(TReal a, aiMatrix3x3t &out)

Returns a rotation matrix for a rotation around z.

Return

Reference to the output matrix

Parameters

• a: Rotation angle, in radians

• out: Receives the output matrix

aiMatrix3x3t &Translation(const aiVector2t<TReal> &v, aiMatrix3x3t &out)

Returns a translation matrix.

Return

Reference to the output matrix

Parameters

• v: Translation vector

• out: Receives the output matrix

template<typename TReal>
class aiMatrix4x4t

Represents a row-major 4x4 matrix, use this for homogeneous coordinates.

There’s much confusion about matrix layouts (column vs. row order). This is always a row-major matrix. Not even with the aiProcess_ConvertToLeftHanded flag, which absolutely does not affect matrix order - it just affects the handedness of the coordinate system defined thereby.

Public Functions

aiMatrix4x4t () AI_NO_EXCEPT

set to identity

aiMatrix4x4t(const aiMatrix3x3t<TReal> &m)

construction from 3x3 matrix, remaining elements are set to identity

aiMatrix4x4t(const aiVector3t<TReal> &scaling, const aiQuaterniont<TReal> &rotation, const aiVector3t<TReal> &position)

construction from position, rotation and scaling components

Parameters

• scaling: The scaling for the x,y,z axes

• rotation: The rotation as a hamilton quaternion

• position: The position for the x,y,z axes

aiMatrix4x4t(TReal _a1, TReal _a2, TReal _a3, TReal _a4, TReal _b1, TReal _b2, TReal _b3, TReal _b4, TReal _c1, TReal _c2, TReal _c3, TReal _c4, TReal _d1, TReal _d2, TReal _d3, TReal _d4)

construction from single values

void Decompose(aiVector3t<TReal> &pScaling, aiVector3t<TReal> &pRotation, aiVector3t<TReal> &pPosition) const

Decompose a trafo matrix into its original components.

Thx to good FAQ at http://www.gamedev.ru/code/articles/faq_matrix_quat

Parameters

• [out] pScaling: - Receives the output scaling for the x,y,z axes.

• [out] pRotation: - Receives the output rotation as a Euler angles.

• [out] pPosition: - Receives the output position for the x,y,z axes.

void Decompose(aiVector3t<TReal> &pScaling, aiVector3t<TReal> &pRotationAxis, TReal &pRotationAngle, aiVector3t<TReal> &pPosition) const

Decompose a trafo matrix into its original components Thx to good FAQ at http://www.gamedev.ru/code/articles/faq_matrix_quat.

Parameters

• [out] pScaling: - Receives the output scaling for the x,y,z axes.

• [out] pRotationAxis: - Receives the output rotation axis.

• [out] pRotationAngle: - Receives the output rotation angle for pRotationAxis.

• [out] pPosition: - Receives the output position for the x,y,z axes.

void Decompose(aiVector3t<TReal> &scaling, aiQuaterniont<TReal> &rotation, aiVector3t<TReal> &position) const

Decompose a trafo matrix into its original components.

Parameters

• scaling: Receives the output scaling for the x,y,z axes

• rotation: Receives the output rotation as a hamilton quaternion

• position: Receives the output position for the x,y,z axes

void DecomposeNoScaling(aiQuaterniont<TReal> &rotation, aiVector3t<TReal> &position) const

Decompose a trafo matrix with no scaling into its original components.

Parameters

• rotation: Receives the output rotation as a hamilton quaternion

• position: Receives the output position for the x,y,z axes

aiMatrix4x4t &FromEulerAnglesXYZ(TReal x, TReal y, TReal z)

Creates a trafo matrix from a set of euler angles.

Parameters

• x: Rotation angle for the x-axis, in radians

• y: Rotation angle for the y-axis, in radians

• z: Rotation angle for the z-axis, in radians

aiMatrix4x4t &Inverse()

Invert the matrix.

If the matrix is not invertible all elements are set to qnan. Beware, use (f != f) to check whether a TReal f is qnan.

bool IsIdentity() const

Returns true of the matrix is the identity matrix.

The check is performed against a not so small epsilon.

TReal *operator[](unsigned int p_iIndex)

Return

pointer to pointed row.

Parameters

• [in] p_iIndex: - index of the row.

aiMatrix4x4t &Transpose()

Transpose the matrix.

Public Static Functions

aiMatrix4x4t &FromToMatrix(const aiVector3t<TReal> &from, const aiVector3t<TReal> &to, aiMatrix4x4t &out)

A function for creating a rotation matrix that rotates a vector called “from” into another vector called “to”.

Input : from[3], to[3] which both must be normalized non-zero vectors Output: mtx[3][3] a 3x3 matrix in column-major form Authors: Tomas Mueller, John Hughes “Efficiently Building a Matrix to Rotate One Vector to Another” Journal of Graphics Tools, 4(4):1-4, 1999

Input : from[3], to[3] which both must be normalized non-zero vectors Output: mtx[3][3] a 3x3 matrix in colum-major form Authors: Tomas Möller, John Hughes “Efficiently Building a Matrix to Rotate One Vector to Another” Journal of Graphics Tools, 4(4):1-4, 1999

aiMatrix4x4t &Rotation(TReal a, const aiVector3t<TReal> &axis, aiMatrix4x4t &out)

Returns a rotation matrix for a rotation around an arbitrary axis.

Return

Reference to the output matrix

Parameters

• a: Rotation angle, in radians

• axis: Rotation axis, should be a normalized vector.

• out: Receives the output matrix

aiMatrix4x4t &RotationX(TReal a, aiMatrix4x4t &out)

Returns a rotation matrix for a rotation around the x axis.

Return

Reference to the output matrix

Parameters

• a: Rotation angle, in radians

• out: Receives the output matrix

aiMatrix4x4t &RotationY(TReal a, aiMatrix4x4t &out)

Returns a rotation matrix for a rotation around the y axis.

Return

Reference to the output matrix

Parameters

• a: Rotation angle, in radians

• out: Receives the output matrix

aiMatrix4x4t &RotationZ(TReal a, aiMatrix4x4t &out)

Returns a rotation matrix for a rotation around the z axis.

Return

Reference to the output matrix

Parameters

• a: Rotation angle, in radians

• out: Receives the output matrix

aiMatrix4x4t &Scaling(const aiVector3t<TReal> &v, aiMatrix4x4t &out)

Returns a scaling matrix.

Return

Reference to the output matrix

Parameters

• v: Scaling vector

• out: Receives the output matrix

aiMatrix4x4t &Translation(const aiVector3t<TReal> &v, aiMatrix4x4t &out)

Returns a translation matrix.

Return

Reference to the output matrix

Parameters

• v: Translation vector

• out: Receives the output matrix

struct aiRay

Represents a ray.

Public Members

C_STRUCT aiVector3D pos

Position and direction of the ray.

struct aiPlane

Represents a plane in a three-dimensional, euclidean space.

Public Members

ai_real a

Plane equation.

struct aiMetadata

Container for holding metadata.

Metadata is a key-value store using string keys and values.

Public Functions

aiMetadata () AI_NO_EXCEPT

The default constructor, set all members to zero by default.

bool Get(size_t index, const aiString *&key, const aiMetadataEntry *&entry) const

Return metadata entry for analyzing it by user.

Return

false - if pIndex is out of range, else - true.

Parameters

• [in] pIndex: - index of the entry.

• [out] pKey: - pointer to the key value.

• [out] pEntry: - pointer to the entry: type and value.

bool HasKey(const char *key) const

Check whether there is a metadata entry for the given key.

Parameters

• [in] Key: - the key value value to check for.

~aiMetadata()

The destructor.

Public Members

C_STRUCT aiString * mKeys

Arrays of keys, may not be NULL.

Entries in this array may not be NULL as well.

unsigned int mNumProperties

Length of the mKeys and mValues arrays, respectively.

C_STRUCT aiMetadataEntry * mValues

Arrays of values, may not be NULL.

Entries in this array may be NULL if the corresponding property key has no assigned value.

Public Static Functions

aiMetadata *Alloc(unsigned int numProperties)

Allocates property fields + keys.

Parameters

• numProperties: Number of requested properties.

void Dealloc(aiMetadata *metadata)

Deallocates property fields + keys.

struct aiTexture

Helper structure to describe an embedded texture.

Normally textures are contained in external files but some file formats embed them directly in the model file. There are two types of embedded textures:

1. Uncompressed textures. The color data is given in an uncompressed format.

2. Compressed textures stored in a file format like png or jpg. The raw file bytes are given so the application must utilize an image decoder (e.g. DevIL) to get access to the actual color data.

Embedded textures are referenced from materials using strings like “*0”, “*1”, etc. as the texture paths (a single asterisk character followed by the zero-based index of the texture in the aiScene::mTextures array).

Public Functions

bool CheckFormat(const char *s) const

For compressed textures (mHeight == 0): compare the format hint against a given string.

Return

true if the given string matches the format hint

Parameters

• s: Input string. 3 characters are maximally processed. Example values: “jpg”, “png”

Public Members

char achFormatHint[HINTMAXTEXTURELEN]

A hint from the loader to make it easier for applications to determine the type of embedded textures.

If mHeight != 0 this member is show how data is packed. Hint will consist of two parts: channel order and channel bitness (count of the bits for every color channel). For simple parsing by the viewer it’s better to not omit absent color channel and just use 0 for bitness. For example:

1. Image contain RGBA and 8 bit per channel, achFormatHint == “rgba8888”;

2. Image contain ARGB and 8 bit per channel, achFormatHint == “argb8888”;

3. Image contain RGB and 5 bit for R and B channels and 6 bit for G channel, achFormatHint == “rgba5650”;

4. One color image with B channel and 1 bit for it, achFormatHint == “rgba0010”; If mHeight == 0 then achFormatHint is set set to ‘\0\0\0\0’ if the loader has no additional information about the texture file format used OR the file extension of the format without a trailing dot. If there are multiple file extensions for a format, the shortest extension is chosen (JPEG maps to ‘jpg’, not to ‘jpeg’). E.g. ‘dds\0’, ‘pcx\0’, ‘jpg\0’. All characters are lower-case. The fourth character will always be ‘\0’.

C_STRUCT aiString mFilename

Texture original filename.

Used to get the texture reference

unsigned int mHeight

Height of the texture, in pixels.

If this value is zero, pcData points to an compressed texture in any format (e.g. JPEG).

unsigned int mWidth

Width of the texture, in pixels.

If mHeight is zero the texture is compressed in a format like JPEG. In this case mWidth specifies the size of the memory area pcData is pointing to, in bytes.

C_STRUCT aiTexel * pcData

Data of the texture.

Points to an array of mWidth * mHeight aiTexel’s. The format of the texture data is always ARGB8888 to make the implementation for user of the library as easy as possible. If mHeight = 0 this is a pointer to a memory buffer of size mWidth containing the compressed texture data. Good luck, have fun!

struct aiAABB

template<typename T, unsigned int Capacity>
class Assimp::SmallVector

Small vector with inplace storage.

Reduces heap allocations when list is shorter. It uses a small array for a dedicated size. When the growing gets bigger than this small cache a dynamic growing algorithm will be used.

Public Functions

T *begin()

Returns a pointer to the first item.

Return

The first item as a pointer.

T *begin() const

Returns a const pointer to the first item.

Return

The first item as a const pointer.

T *end()

Returns a pointer to the end.

Return

The end as a pointer.

T *end() const

Returns a const pointer to the end.

Return

The end as a const pointer.

void push_back(const T &item)

Will push a new item.

The capacity will grow in case of a too small capacity.

Parameters

• item: [in] The item to push at the end of the vector.

void resize(size_t newSize)

Will resize the vector.

Parameters

• newSize: [in] The new size.

size_t size() const

Returns the current size of the vector.

Return

The current size.

SmallVector()

The default class constructor.

~SmallVector()

The class destructor.

Scene Datatypes

struct aiFace

A single face in a mesh, referring to multiple vertices.

If mNumIndices is 3, we call the face ‘triangle’, for mNumIndices > 3 it’s called ‘polygon’ (hey, that’s just a definition!). aiMesh::mPrimitiveTypes can be queried to quickly examine which types of primitive are actually present in a mesh. The aiProcess_SortByPType flag executes a special post-processing algorithm which splits meshes with different primitive types mixed up (e.g. lines and triangles) in several ‘clean’ submeshes. Furthermore there is a configuration option ( AI_CONFIG_PP_SBP_REMOVE) to force aiProcess_SortByPType to remove specific kinds of primitives from the imported scene, completely and forever. In many cases you’ll probably want to set this setting to

aiPrimitiveType_LINE|aiPrimitiveType_POINT

Together with the aiProcess_Triangulate flag you can then be sure that aiFace::mNumIndices is always 3.

Note

Take a look at the Data Structures page for more information on the layout and winding order of a face.

Public Functions

aiFace () AI_NO_EXCEPT

Default constructor.

aiFace(const aiFace &o)

Copy constructor. Copy the index array.

bool operator!=(const aiFace &o) const

Inverse comparison operator.

Checks whether the index array of two faces is NOT identical

aiFace &operator=(const aiFace &o)

Assignment operator. Copy the index array.

bool operator==(const aiFace &o) const

Comparison operator.

Checks whether the index array of two faces is identical

~aiFace()

Default destructor. Delete the index array.

Public Members

unsigned int *mIndices

Pointer to the indices array. Size of the array is given in numIndices.

unsigned int mNumIndices

Number of indices defining this face.

The maximum value for this member is AI_MAX_FACE_INDICES.

struct aiMesh

enum aiMorphingMethod

A mesh represents a geometry or model with a single material.

It usually consists of a number of vertices and a series of primitives/faces referencing the vertices. In addition there might be a series of bones, each of them addressing a number of vertices with a certain weight. Vertex data is presented in channels with each channel containing a single per-vertex information such as a set of texture coords or a normal vector. If a data pointer is non-null, the corresponding data stream is present. From C++-programs you can also use the comfort functions Has*() to test for the presence of various data streams.

A Mesh uses only a single material which is referenced by a material ID.

Note

The mPositions member is usually not optional. However, vertex positions could be missing if the AI_SCENE_FLAGS_INCOMPLETE flag is set in

aiScene::mFlags

Public Functions

aiMesh () AI_NO_EXCEPT

Default constructor. Initializes all members to 0.

unsigned int GetNumColorChannels() const

Get the number of vertex color channels the mesh contains.

unsigned int GetNumUVChannels() const

Get the number of UV channels the mesh contains.

bool HasBones() const

Check whether the mesh contains bones.

bool HasFaces() const

Check whether the mesh contains faces.

If no special scene flags are set this should always return true

bool HasNormals() const

Check whether the mesh contains normal vectors.

bool HasPositions() const

Check whether the mesh contains positions.

Provided no special scene flags are set, this will always be true

bool HasTangentsAndBitangents() const

Check whether the mesh contains tangent and bitangent vectors It is not possible that it contains tangents and no bitangents (or the other way round).

The existence of one of them implies that the second is there, too.

bool HasTextureCoords(unsigned int pIndex) const

Check whether the mesh contains a texture coordinate set.

Parameters

• pIndex: Index of the texture coordinates set

bool HasVertexColors(unsigned int pIndex) const

Check whether the mesh contains a vertex color set.

Parameters

• pIndex: Index of the vertex color set

~aiMesh()

Deletes all storage allocated for the mesh.

Public Members

C_STRUCT aiAnimMesh ** mAnimMeshes

Attachment meshes for this mesh, for vertex-based animation.

Attachment meshes carry replacement data for some of the mesh’es vertex components (usually positions, normals). Note! Currently only works with Collada loader.

C_STRUCT aiVector3D * mBitangents

Vertex bitangents.

The bitangent of a vertex points in the direction of the positive Y texture axis. The array contains normalized vectors, nullptr if not present. The array is mNumVertices in size.

Note

If the mesh contains tangents, it automatically also contains bitangents.

C_STRUCT aiBone ** mBones

The bones of this mesh.

A bone consists of a name by which it can be found in the frame hierarchy and a set of vertex weights.

C_STRUCT aiColor4D * mColors [AI_MAX_NUMBER_OF_COLOR_SETS]

Vertex color sets.

A mesh may contain 0 to AI_MAX_NUMBER_OF_COLOR_SETS vertex colors per vertex. nullptr if not present. Each array is mNumVertices in size if present.

C_STRUCT aiFace * mFaces

The faces the mesh is constructed from.

Each face refers to a number of vertices by their indices. This array is always present in a mesh, its size is given in mNumFaces. If the AI_SCENE_FLAGS_NON_VERBOSE_FORMAT is NOT set each face references an unique set of vertices.

unsigned int mMaterialIndex

The material used by this mesh.

A mesh uses only a single material. If an imported model uses multiple materials, the import splits up the mesh. Use this value as index into the scene’s material list.

unsigned int mMethod

Method of morphing when animeshes are specified.

C_STRUCT aiString mName

Name of the mesh.

Meshes can be named, but this is not a requirement and leaving this field empty is totally fine. There are mainly three uses for mesh names:

• some formats name nodes and meshes independently.

• importers tend to split meshes up to meet the one-material-per-mesh requirement. Assigning the same (dummy) name to each of the result meshes aids the caller at recovering the original mesh partitioning.

• Vertex animations refer to meshes by their names.

C_STRUCT aiVector3D * mNormals

Vertex normals.

The array contains normalized vectors, nullptr if not present. The array is mNumVertices in size. Normals are undefined for point and line primitives. A mesh consisting of points and lines only may not have normal vectors. Meshes with mixed primitive types (i.e. lines and triangles) may have normals, but the normals for vertices that are only referenced by point or line primitives are undefined and set to QNaN (WARN: qNaN compares to inequal to everything, even to qNaN itself. Using code like this to check whether a field is qnan is:

#define IS_QNAN(f) (f != f)

still dangerous because even 1.f == 1.f could evaluate to false! ( remember the subtleties of IEEE754 artithmetics). Use stuff like fpclassify instead.

Note

Normal vectors computed by Assimp are always unit-length. However, this needn’t apply for normals that have been taken directly from the model file.

unsigned int mNumAnimMeshes

The number of attachment meshes.

Note! Currently only works with Collada loader.

unsigned int mNumBones

The number of bones this mesh contains.

Can be 0, in which case the mBones array is nullptr.

unsigned int mNumFaces

The number of primitives (triangles, polygons, lines) in this mesh.

This is also the size of the mFaces array. The maximum value for this member is AI_MAX_FACES.

unsigned int mNumUVComponents[AI_MAX_NUMBER_OF_TEXTURECOORDS]

Specifies the number of components for a given UV channel.

Up to three channels are supported (UVW, for accessing volume or cube maps). If the value is 2 for a given channel n, the component p.z of mTextureCoords[n][p] is set to 0.0f. If the value is 1 for a given channel, p.y is set to 0.0f, too.

Note

4D coords are not supported

unsigned int mNumVertices

The number of vertices in this mesh.

This is also the size of all of the per-vertex data arrays. The maximum value for this member is AI_MAX_VERTICES.

unsigned int mPrimitiveTypes

Bitwise combination of the members of the aiPrimitiveType enum.

This specifies which types of primitives are present in the mesh. The “SortByPrimitiveType”-Step can be used to make sure the output meshes consist of one primitive type each.

C_STRUCT aiVector3D * mTangents

Vertex tangents.

The tangent of a vertex points in the direction of the positive X texture axis. The array contains normalized vectors, nullptr if not present. The array is mNumVertices in size. A mesh consisting of points and lines only may not have normal vectors. Meshes with mixed primitive types (i.e. lines and triangles) may have normals, but the normals for vertices that are only referenced by point or line primitives are undefined and set to qNaN. See the mNormals member for a detailed discussion of qNaNs.

Note

If the mesh contains tangents, it automatically also contains bitangents.

C_STRUCT aiVector3D * mTextureCoords [AI_MAX_NUMBER_OF_TEXTURECOORDS]

Vertex texture coords, also known as UV channels.

A mesh may contain 0 to AI_MAX_NUMBER_OF_TEXTURECOORDS per vertex. nullptr if not present. The array is mNumVertices in size.

C_STRUCT aiString mTextureCoordsNames [AI_MAX_NUMBER_OF_TEXTURECOORDS]

Vertex stream names.

C_STRUCT aiVector3D * mVertices

Vertex positions.

This array is always present in a mesh. The array is mNumVertices in size.

struct aiScene

The root structure of the imported data.

Everything that was imported from the given file can be accessed from here. Objects of this class are generally maintained and owned by Assimp, not by the caller. You shouldn’t want to instance it, nor should you ever try to delete a given scene on your own.

Public Functions

ASSIMP_API aiScene()

Default constructor - set everything to 0/nullptr.

const aiTexture *GetEmbeddedTexture(const char *filename) const

Returns an embedded texture.

std::pair<const aiTexture*, int> GetEmbeddedTextureAndIndex(const char *filename) const

Returns an embedded texture and its index.

bool HasAnimations() const

Check whether the scene contains animations.

bool HasCameras() const

Check whether the scene contains cameras.

bool HasLights() const

Check whether the scene contains lights.

bool HasMaterials() const

Check whether the scene contains materials Unless no special scene flags are set this will always be true.

bool HasMeshes() const

Check whether the scene contains meshes Unless no special scene flags are set this will always be true.

bool HasTextures() const

Check whether the scene contains textures.

ASSIMP_API ~aiScene()

Destructor.

Public Members

C_STRUCT aiAnimation ** mAnimations

The array of animations.

All animations imported from the given file are listed here. The array is mNumAnimations in size.

C_STRUCT aiCamera ** mCameras

The array of cameras.

All cameras imported from the given file are listed here. The array is mNumCameras in size. The first camera in the array (if existing) is the default camera view into the scene.

unsigned int mFlags

Any combination of the AI_SCENE_FLAGS_XXX flags.

By default this value is 0, no flags are set. Most applications will want to reject all scenes with the AI_SCENE_FLAGS_INCOMPLETE bit set.

C_STRUCT aiLight ** mLights

The array of light sources.

All light sources imported from the given file are listed here. The array is mNumLights in size.

C_STRUCT aiMaterial ** mMaterials

The array of materials.

Use the index given in each aiMesh structure to access this array. The array is mNumMaterials in size. If the AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always be at least ONE material.

C_STRUCT aiMesh ** mMeshes

The array of meshes.

Use the indices given in the aiNode structure to access this array. The array is mNumMeshes in size. If the AI_SCENE_FLAGS_INCOMPLETE flag is not set there will always be at least ONE material.

C_STRUCT aiMetadata * mMetaData

The global metadata assigned to the scene itself.

This data contains global metadata which belongs to the scene like unit-conversions, versions, vendors or other model-specific data. This can be used to store format-specific metadata as well.

C_STRUCT aiString mName

The name of the scene itself.

unsigned int mNumAnimations

The number of animations in the scene.

unsigned int mNumCameras

The number of cameras in the scene.

Cameras are fully optional, in most cases this attribute will be 0

unsigned int mNumLights

The number of light sources in the scene.

Light sources are fully optional, in most cases this attribute will be 0

unsigned int mNumMaterials

The number of materials in the scene.

unsigned int mNumMeshes

The number of meshes in the scene.

unsigned int mNumTextures

The number of textures embedded into the file.

void *mPrivate

Internal data, do not touch.

C_STRUCT aiNode * mRootNode

The root node of the hierarchy.

There will always be at least the root node if the import was successful (and no special flags have been set). Presence of further nodes depends on the format and content of the imported file.

C_STRUCT aiTexture ** mTextures

The array of embedded textures.

Not many file formats embed their textures into the file. An example is Quake’s MDL format (which is also used by some GameStudio versions)

Public Static Functions

const char *GetShortFilename(const char *filename)

Returns a short filename from a full path.

struct aiNode

A node in the imported hierarchy.

Each node has name, a parent node (except for the root node), a transformation relative to its parent and possibly several child nodes. Simple file formats don’t support hierarchical structures - for these formats the imported scene does consist of only a single root node without children.

Public Functions

void addChildren(unsigned int numChildren, aiNode **children)

Will add new children.

Parameters

• numChildren: Number of children to add.

• children: The array with pointers showing to the children.

aiNode()

Constructor.

aiNode(const std::string &name)

Construction from a specific name.

const aiNode *FindNode(const aiString &name) const

Searches for a node with a specific name, beginning at this nodes.

Normally you will call this method on the root node of the scene.

Return

nullptr or a valid Node if the search was successful.

Parameters

• name: Name to search for

~aiNode()

Destructor.

Public Members

C_STRUCT aiNode ** mChildren

The child nodes of this node.

nullptr if mNumChildren is 0.

unsigned int *mMeshes

The meshes of this node.

Each entry is an index into the mesh list of the aiScene.

C_STRUCT aiMetadata * mMetaData

Metadata associated with this node or nullptr if there is no metadata.

Whether any metadata is generated depends on the source file format. See the importer_notes page for more information on every source file format. Importers that don’t document any metadata don’t write any.

C_STRUCT aiString mName

The name of the node.

The name might be empty (length of zero) but all nodes which need to be referenced by either bones or animations are named. Multiple nodes may have the same name, except for nodes which are referenced by bones (see aiBone and aiMesh::mBones). Their names must be unique.

Cameras and lights reference a specific node by name - if there are multiple nodes with this name, they are assigned to each of them.

There are no limitations with regard to the characters contained in the name string as it is usually taken directly from the source file.

Implementations should be able to handle tokens such as whitespace, tabs, line feeds, quotation marks, ampersands etc.

Sometimes assimp introduces new nodes not present in the source file into the hierarchy (usually out of necessity because sometimes the source hierarchy format is simply not compatible). Their names are surrounded by

<>

e.g.

<DummyRootNode>

.

unsigned int mNumChildren

The number of child nodes of this node.

unsigned int mNumMeshes

The number of meshes of this node.

C_STRUCT aiNode * mParent

Parent node.

nullptr if this node is the root node.

C_STRUCT aiMatrix4x4 mTransformation

The transformation relative to the node’s parent.

struct aiCamera

Helper structure to describe a virtual camera.

Cameras have a representation in the node graph and can be animated. An important aspect is that the camera itself is also part of the scene-graph. This means, any values such as the look-at vector are not absolute, they’re relative to the coordinate system defined by the node which corresponds to the camera. This allows for camera animations. For static cameras parameters like the ‘look-at’ or ‘up’ vectors are usually specified directly in aiCamera, but beware, they could also be encoded in the node transformation. The following (pseudo)code sample shows how to do it:

// Get the camera matrix for a camera at a specific time
// if the node hierarchy for the camera does not contain
// at least one animated node this is a static computation
get-camera-matrix (node sceneRoot, camera cam) : matrix
{
   node   cnd = find-node-for-camera(cam)
   matrix cmt = identity()

   // as usual - get the absolute camera transformation for this frame
   for each node nd in hierarchy from sceneRoot to cnd
     matrix cur
     if (is-animated(nd))
        cur = eval-animation(nd)
     else cur = nd->mTransformation;
     cmt = mult-matrices( cmt, cur )
   end for

   // now multiply with the camera's own local transform
   cam = mult-matrices (cam, get-camera-matrix(cmt) )
}

Note

some file formats (such as 3DS, ASE) export a “target point” - the point the camera is looking at (it can even be animated). Assimp writes the target point as a subnode of the camera’s main node, called “<camName>.Target”. However this is just additional information then the transformation tracks of the camera main node make the camera already look in the right direction.

Public Functions

void GetCameraMatrix(aiMatrix4x4 &out) const

Get a right-handed camera matrix from me.

Parameters

• out: Camera matrix to be filled

Public Members

float mAspect

Screen aspect ratio.

This is the ration between the width and the height of the screen. Typical values are 4/3, 1/2 or 1/1. This value is 0 if the aspect ratio is not defined in the source file. 0 is also the default value.

float mClipPlaneFar

Distance of the far clipping plane from the camera.

The far clipping plane must, of course, be further away than the near clipping plane. The default value is 1000.f. The ratio between the near and the far plane should not be too large (between 1000-10000 should be ok) to avoid floating-point inaccuracies which could lead to z-fighting.

float mClipPlaneNear

Distance of the near clipping plane from the camera.

The value may not be 0.f (for arithmetic reasons to prevent a division through zero). The default value is 0.1f.

float mHorizontalFOV

Horizontal field of view angle, in radians.

The field of view angle is the angle between the center line of the screen and the left or right border. The default value is 1/4PI.

C_STRUCT aiVector3D mLookAt

‘LookAt’ - vector of the camera coordinate system relative to the coordinate space defined by the corresponding node.

This is the viewing direction of the user. The default value is 0|0|1. The vector may be normalized, but it needn’t.

C_STRUCT aiString mName

The name of the camera.

There must be a node in the scenegraph with the same name. This node specifies the position of the camera in the scene hierarchy and can be animated.

float mOrthographicWidth

Half horizontal orthographic width, in scene units.

The orthographic width specifies the half width of the orthographic view box. If non-zero the camera is orthographic and the mAspect should define to the ratio between the orthographic width and height and mHorizontalFOV should be set to 0. The default value is 0 (not orthographic).

C_STRUCT aiVector3D mPosition

Position of the camera relative to the coordinate space defined by the corresponding node.

The default value is 0|0|0.

C_STRUCT aiVector3D mUp

‘Up’ - vector of the camera coordinate system relative to the coordinate space defined by the corresponding node.

The ‘right’ vector of the camera coordinate system is the cross product of the up and lookAt vectors. The default value is 0|1|0. The vector may be normalized, but it needn’t.

struct aiLight

Helper structure to describe a light source.

Assimp supports multiple sorts of light sources, including directional, point and spot lights. All of them are defined with just a single structure and distinguished by their parameters. Note - some file formats (such as 3DS, ASE) export a “target point” - the point a spot light is looking at (it can even be animated). Assimp writes the target point as a subnode of a spotlights’s main node, called “<spotName>.Target”. However, this is just additional information then, the transformation tracks of the main node make the spot light already point in the right direction.

Public Members

float mAngleInnerCone

Inner angle of a spot light’s light cone.

The spot light has maximum influence on objects inside this angle. The angle is given in radians. It is 2PI for point lights and undefined for directional lights.

float mAngleOuterCone

Outer angle of a spot light’s light cone.

The spot light does not affect objects outside this angle. The angle is given in radians. It is 2PI for point lights and undefined for directional lights. The outer angle must be greater than or equal to the inner angle. It is assumed that the application uses a smooth interpolation between the inner and the outer cone of the spot light.

float mAttenuationConstant

Constant light attenuation factor.

The intensity of the light source at a given distance ‘d’ from the light’s position is

Atten = 1/( att0 + att1 * d + att2 * d*d)

This member corresponds to the att0 variable in the equation. Naturally undefined for directional lights.

float mAttenuationLinear

Linear light attenuation factor.

The intensity of the light source at a given distance ‘d’ from the light’s position is

Atten = 1/( att0 + att1 * d + att2 * d*d)

This member corresponds to the att1 variable in the equation. Naturally undefined for directional lights.

float mAttenuationQuadratic

Quadratic light attenuation factor.

The intensity of the light source at a given distance ‘d’ from the light’s position is

Atten = 1/( att0 + att1 * d + att2 * d*d)

This member corresponds to the att2 variable in the equation. Naturally undefined for directional lights.

C_STRUCT aiColor3D mColorAmbient

Ambient color of the light source.

The ambient light color is multiplied with the ambient material color to obtain the final color that contributes to the ambient shading term. Most renderers will ignore this value it, is just a remaining of the fixed-function pipeline that is still supported by quite many file formats.

C_STRUCT aiColor3D mColorDiffuse

Diffuse color of the light source.

The diffuse light color is multiplied with the diffuse material color to obtain the final color that contributes to the diffuse shading term.

C_STRUCT aiColor3D mColorSpecular

Specular color of the light source.

The specular light color is multiplied with the specular material color to obtain the final color that contributes to the specular shading term.

C_STRUCT aiVector3D mDirection

Direction of the light source in space.

Relative to the transformation of the node corresponding to the light.

The direction is undefined for point lights. The vector may be normalized, but it needn’t.

C_STRUCT aiString mName

The name of the light source.

There must be a node in the scenegraph with the same name. This node specifies the position of the light in the scene hierarchy and can be animated.

C_STRUCT aiVector3D mPosition

Position of the light source in space.

Relative to the transformation of the node corresponding to the light.

The position is undefined for directional lights.

C_STRUCT aiVector2D mSize

Size of area light source.

C_ENUM aiLightSourceType mType

The type of the light source.

aiLightSource_UNDEFINED is not a valid value for this member.

C_STRUCT aiVector3D mUp

Up direction of the light source in space.

Relative to the transformation of the node corresponding to the light.

The direction is undefined for point lights. The vector may be normalized, but it needn’t.

struct aiMaterial

Data structure for a material.

Material data is stored using a key-value structure. A single key-value pair is called a ‘material property’. C++ users should use the provided member functions of aiMaterial to process material properties, C users have to stick with the aiMaterialGetXXX family of unbound functions. The library defines a set of standard keys (AI_MATKEY_XXX).

Public Functions

aiReturn AddBinaryProperty(const void *pInput, unsigned int pSizeInBytes, const char *pKey, unsigned int type, unsigned int index, aiPropertyTypeInfo pType)

Add a property with a given key and type info to the material structure.

Parameters

• pInput: Pointer to input data

• pSizeInBytes: Size of input data

• pKey: Key/Usage of the property (AI_MATKEY_XXX)

• type: Set by the AI_MATKEY_XXX macro

• index: Set by the AI_MATKEY_XXX macro

• pType: Type information hint

aiReturn AddProperty(const aiString *pInput, const char *pKey, unsigned int type = 0, unsigned int index = 0)

Add a string property with a given key and type info to the material structure.

Parameters

• pInput: Input string

• pKey: Key/Usage of the property (AI_MATKEY_XXX)

• type: Set by the AI_MATKEY_XXX macro

• index: Set by the AI_MATKEY_XXX macro

template<class TYPE>
aiReturn AddProperty(const TYPE *pInput, unsigned int pNumValues, const char *pKey, unsigned int type = 0, unsigned int index = 0)

Add a property with a given key to the material structure.

Parameters

• pInput: Pointer to the input data

• pNumValues: Number of values in the array

• pKey: Key/Usage of the property (AI_MATKEY_XXX)

• type: Set by the AI_MATKEY_XXX macro

• index: Set by the AI_MATKEY_XXX macro

void Clear()

Removes all properties from the material.

The data array remains allocated so adding new properties is quite fast.

template<typename Type>
aiReturn Get(const char *pKey, unsigned int type, unsigned int idx, Type &pOut) const

Retrieve a Type value with a specific key from the material.

Parameters

• pKey: Key to search for. One of the AI_MATKEY_XXX constants.

• type: Specifies the type of the texture to be retrieved ( e.g. diffuse, specular, height map …)

• idx: Index of the texture to be retrieved.

• pOut: Reference to receive the output value

template<typename Type>
aiReturn Get(const char *pKey, unsigned int type, unsigned int idx, Type *pOut, unsigned int *pMax) const

Retrieve an array of Type values with a specific key from the material.

Parameters

• pKey: Key to search for. One of the AI_MATKEY_XXX constants.

• type: .. set by AI_MATKEY_XXX

• idx: .. set by AI_MATKEY_XXX

• pOut: Pointer to a buffer to receive the result.

• pMax: Specifies the size of the given buffer, in Type’s. Receives the number of values (not bytes!) read. NULL is a valid value for this parameter.

aiString GetName() const

Returns the name of the material.

Return

The name of the material.

aiReturn GetTexture (aiTextureType type, unsigned int index, C_STRUCT aiString *path, aiTextureMapping *mapping=NULL, unsigned int *uvindex=NULL, ai_real *blend=NULL, aiTextureOp *op=NULL, aiTextureMapMode *mapmode=NULL) const

Helper function to get all parameters pertaining to a particular texture slot from a material.

This function is provided just for convenience, you could also read the single material properties manually.

Parameters

• type: Specifies the type of the texture to be retrieved ( e.g. diffuse, specular, height map …)

• index: Index of the texture to be retrieved. The function fails if there is no texture of that type with this index. GetTextureCount() can be used to determine the number of textures per texture type.

• path: Receives the path to the texture. Use aiScene::GetEmbeddedTexture() method to determine if returned path is an image file to be opened or a string key of embedded texture stored in the corresponding scene (could be a ‘*’ followed by the id of the texture in case of no name) NULL is a valid value.

• mapping: The texture mapping. NULL is allowed as value.

• uvindex: Receives the UV index of the texture. NULL is a valid value.

• blend: Receives the blend factor for the texture NULL is a valid value.

• op: Receives the texture operation to be performed between this texture and the previous texture. NULL is allowed as value.

• mapmode: Receives the mapping modes to be used for the texture. The parameter may be NULL but if it is a valid pointer it MUST point to an array of 3 aiTextureMapMode’s (one for each axis: UVW order (=XYZ)).

unsigned int GetTextureCount(aiTextureType type) const

Get the number of textures for a particular texture type.

Return

Number of textures for this type.

Note

A texture can be easily queried using GetTexture()

Parameters

• type: Texture type to check for

aiReturn RemoveProperty(const char *pKey, unsigned int type = 0, unsigned int index = 0)

Remove a given key from the list.

The function fails if the key isn’t found

Parameters

• pKey: Key to be deleted

• type: Set by the AI_MATKEY_XXX macro

• index: Set by the AI_MATKEY_XXX macro

Public Members

unsigned int mNumAllocated

Storage allocated.

unsigned int mNumProperties

Number of properties in the data base.

C_STRUCT aiMaterialProperty ** mProperties

List of all material properties loaded.

Public Static Functions

void CopyPropertyList(aiMaterial *pcDest, const aiMaterial *pcSrc)

Copy the property list of a material.

Parameters

• pcDest: Destination material

• pcSrc: Source material

Animation Datatypes

struct aiAnimation

An animation consists of key-frame data for a number of nodes.

For each node affected by the animation a separate series of data is given.

Public Members

C_STRUCT aiNodeAnim ** mChannels

The node animation channels.

Each channel affects a single node. The array is mNumChannels in size.

double mDuration

Duration of the animation in ticks.

C_STRUCT aiMeshAnim ** mMeshChannels

The mesh animation channels.

Each channel affects a single mesh. The array is mNumMeshChannels in size.

C_STRUCT aiMeshMorphAnim ** mMorphMeshChannels

The morph mesh animation channels.

Each channel affects a single mesh. The array is mNumMorphMeshChannels in size.

C_STRUCT aiString mName

The name of the animation.

If the modeling package this data was exported from does support only a single animation channel, this name is usually empty (length is zero).

unsigned int mNumChannels

The number of bone animation channels.

Each channel affects a single node.

unsigned int mNumMeshChannels

The number of mesh animation channels.

Each channel affects a single mesh and defines vertex-based animation.

unsigned int mNumMorphMeshChannels

The number of mesh animation channels.

Each channel affects a single mesh and defines morphing animation.

double mTicksPerSecond

Ticks per second.

0 if not specified in the imported file

struct aiAnimMesh

An AnimMesh is an attachment to an aiMesh stores per-vertex animations for a particular frame.

You may think of an aiAnimMesh as a patch for the host mesh, which replaces only certain vertex data streams at a particular time. Each mesh stores n attached attached meshes (aiMesh::mAnimMeshes). The actual relationship between the time line and anim meshes is established by aiMeshAnim, which references singular mesh attachments by their ID and binds them to a time offset.

Public Functions

bool HasNormals() const

Check whether the anim mesh overrides the vertex normals of its host mesh.

bool HasPositions() const

Check whether the anim mesh overrides the vertex positions of its host mesh.

bool HasTangentsAndBitangents() const

Check whether the anim mesh overrides the vertex tangents and bitangents of its host mesh.

As for aiMesh, tangents and bitangents always go together.

bool HasTextureCoords(unsigned int pIndex) const

Check whether the anim mesh overrides a particular set of texture coordinates on his host mesh.

Parameters

• pIndex: 0<index<AI_MAX_NUMBER_OF_TEXTURECOORDS

bool HasVertexColors(unsigned int pIndex) const

Check whether the anim mesh overrides a particular set of vertex colors on his host mesh.

Parameters

• pIndex: 0<index<AI_MAX_NUMBER_OF_COLOR_SETS

Public Members

C_STRUCT aiVector3D * mBitangents

Replacement for aiMesh::mBitangents.

C_STRUCT aiColor4D * mColors [AI_MAX_NUMBER_OF_COLOR_SETS]

Replacement for aiMesh::mColors.

C_STRUCT aiString mName

Anim Mesh name.

C_STRUCT aiVector3D * mNormals

Replacement for aiMesh::mNormals.

unsigned int mNumVertices

The number of vertices in the aiAnimMesh, and thus the length of all the member arrays.

This has always the same value as the mNumVertices property in the corresponding aiMesh. It is duplicated here merely to make the length of the member arrays accessible even if the aiMesh is not known, e.g. from language bindings.

C_STRUCT aiVector3D * mTangents

Replacement for aiMesh::mTangents.

C_STRUCT aiVector3D * mTextureCoords [AI_MAX_NUMBER_OF_TEXTURECOORDS]

Replacement for aiMesh::mTextureCoords.

C_STRUCT aiVector3D * mVertices

Replacement for aiMesh::mVertices.

If this array is non-nullptr, it must contain mNumVertices entries. The corresponding array in the host mesh must be non-nullptr as well - animation meshes may neither add or nor remove vertex components (if a replacement array is nullptr and the corresponding source array is not, the source data is taken instead)

float mWeight

Weight of the AnimMesh.

struct aiNodeAnim

Describes the animation of a single node.

The name specifies the bone/node which is affected by this animation channel. The keyframes are given in three separate series of values, one each for position, rotation and scaling. The transformation matrix computed from these values replaces the node’s original transformation matrix at a specific time. This means all keys are absolute and not relative to the bone default pose. The order in which the transformations are applied is

• as usual - scaling, rotation, translation.

Note

All keys are returned in their correct, chronological order. Duplicate keys don’t pass the validation step. Most likely there will be no negative time values, but they are not forbidden also ( so implementations need to cope with them! )

Public Members

C_STRUCT aiString mNodeName

The name of the node affected by this animation.

The node must exist and it must be unique.

unsigned int mNumPositionKeys

The number of position keys.

unsigned int mNumRotationKeys

The number of rotation keys.

unsigned int mNumScalingKeys

The number of scaling keys.

C_STRUCT aiVectorKey * mPositionKeys

The position keys of this animation channel.

Positions are specified as 3D vector. The array is mNumPositionKeys in size.

If there are position keys, there will also be at least one scaling and one rotation key.

C_ENUM aiAnimBehaviour mPostState

Defines how the animation behaves after the last key was processed.

The default value is aiAnimBehaviour_DEFAULT (the original transformation matrix of the affected node is taken).

C_ENUM aiAnimBehaviour mPreState

Defines how the animation behaves before the first key is encountered.

The default value is aiAnimBehaviour_DEFAULT (the original transformation matrix of the affected node is used).

C_STRUCT aiQuatKey * mRotationKeys

The rotation keys of this animation channel.

Rotations are given as quaternions, which are 4D vectors. The array is mNumRotationKeys in size.

If there are rotation keys, there will also be at least one scaling and one position key.

C_STRUCT aiVectorKey * mScalingKeys

The scaling keys of this animation channel.

Scalings are specified as 3D vector. The array is mNumScalingKeys in size.

If there are scaling keys, there will also be at least one position and one rotation key.

struct aiMeshKey

Binds a anim-mesh to a specific point in time.

Public Functions

aiMeshKey(double time, const unsigned int value)

Construction from a given time and key value.

Public Members

double mTime

The time of this key.

unsigned int mValue

Index into the aiMesh::mAnimMeshes array of the mesh corresponding to the aiMeshAnim hosting this key frame.

The referenced anim mesh is evaluated according to the rules defined in the docs for aiAnimMesh.

struct aiBone

A single bone of a mesh.

A bone has a name by which it can be found in the frame hierarchy and by which it can be addressed by animations. In addition it has a number of influences on vertices, and a matrix relating the mesh position to the position of the bone at the time of binding.

Public Functions

aiBone () AI_NO_EXCEPT

Default constructor.

aiBone(const aiBone &other)

Copy constructor.

aiBone &operator=(const aiBone &other)

Assignment operator.

~aiBone()

Destructor - deletes the array of vertex weights.

Public Members

C_STRUCT aiString mName

The name of the bone.

unsigned int mNumWeights

The number of vertices affected by this bone.

The maximum value for this member is AI_MAX_BONE_WEIGHTS.

C_STRUCT aiMatrix4x4 mOffsetMatrix

Matrix that transforms from bone space to mesh space in bind pose.

This matrix describes the position of the mesh in the local space of this bone when the skeleton was bound. Thus it can be used directly to determine a desired vertex position, given the world-space transform of the bone when animated, and the position of the vertex in mesh space.

It is sometimes called an inverse-bind matrix, or inverse bind pose matrix.

C_STRUCT aiVertexWeight * mWeights

The influence weights of this bone, by vertex index.

Exceptions

class DeadlyImportError : public DeadlyErrorBase

FOR IMPORTER PLUGINS ONLY: Simple exception class to be thrown if an unrecoverable error occurs while importing.

Loading APIs return nullptr instead of a valid aiScene then.

Public Functions

template<typename ...T>
DeadlyImportError(T&&... args)

Constructor with arguments.

class DeadlyExportError : public DeadlyErrorBase

Public Functions

template<typename ...T>
DeadlyExportError(T&&... args)

Constructor with arguments.

Logging API

class Assimp::Logger : public Intern::AllocateFromAssimpHeap

CPP-API: Abstract interface for logger implementations.

Assimp provides a default implementation and uses it for almost all logging stuff (‘DefaultLogger’). This class defines just basic logging behavior and is not of interest for you. Instead, take a look at #DefaultLogger.

Subclassed by Assimp::DefaultLogger, Assimp::NullLogger

Public Types

enum ErrorSeverity

Description for severity of a log message.

Every LogStream has a bitwise combination of these flags. A LogStream doesn’t receive any messages of a specific type if it doesn’t specify the corresponding ErrorSeverity flag.

Values:

enumerator Debugging

Debug log message.

enumerator Info

Info log message.

enumerator Warn

Warn log message.

enumerator Err

Error log message.

enum LogSeverity

Log severity to describe the granularity of logging.

Values:

enumerator NORMAL

Normal granularity of logging.

enumerator DEBUGGING

Debug messages will be logged, but not verbose debug messages.

enumerator VERBOSE

All messages will be logged.

Public Functions

bool attachStream(LogStream *pStream, unsigned int severity = Debugging | Err | Warn | Info) = 0

Attach a new log-stream.

The logger takes ownership of the stream and is responsible for its destruction (which is done using ::delete when the logger itself is destroyed). Call detachStream to detach a stream and to gain ownership of it again.

Return

true if the stream has been attached, false otherwise.

Parameters

• pStream: Log-stream to attach

• severity: Message filter, specified which types of log messages are dispatched to the stream. Provide a bitwise combination of the ErrorSeverity flags.

void debug(const char *message)

Writes a info message.

Parameters

• message: Info message

bool detachStream(LogStream *pStream, unsigned int severity = Debugging | Err | Warn | Info) = 0

Detach a still attached stream from the logger (or modify the filter flags bits)

Return

true if the stream has been detached, false otherwise.

Parameters

• pStream: Log-stream instance for detaching

• severity: Provide a bitwise combination of the ErrorSeverity flags. This value is &~ed with the current flags of the stream, if the result is 0 the stream is detached from the Logger and the caller retakes the possession of the stream.

void error(const char *message)

Writes an error message.

Parameters

• message: Info message

LogSeverity getLogSeverity() const

Get the current log severity.

void info(const char *message)

Writes a info message.

Parameters

• message: Info message

void setLogSeverity(LogSeverity log_severity)

Set a new log severity.

Parameters

• log_severity: New severity for logging

void verboseDebug(const char *message)

Writes a debug message.

Parameters

• message: Debug message

void warn(const char *message)

Writes a warning message.

Parameters

• message: Warn message

~Logger()

Virtual destructor.

class Assimp::LogStream : public Intern::AllocateFromAssimpHeap

CPP-API: Abstract interface for log stream implementations.

Several default implementations are provided, see aiDefaultLogStream for more details. Writing your own implementation of LogStream is just necessary if these are not enough for your purpose.

Public Functions

void write(const char *message) = 0

Overwrite this for your own output methods.

Log messages may consist of multiple lines and you shouldn’t expect a consistent formatting. If you want custom formatting (e.g. generate HTML), supply a custom instance of Logger to #DefaultLogger:set(). Usually you can expect that a log message is exactly one line and terminated with a single

character.

Parameters

• message: Message to be written

~LogStream()

Virtual destructor

Public Static Functions

LogStream *createDefaultStream(aiDefaultLogStream stream, const char *name = "AssimpLog.txt", IOSystem *io = nullptr)

Creates a default log stream.

Return

New LogStream instance.

Parameters

• streams: Type of the default stream

• name: For aiDefaultLogStream_FILE: name of the output file

• io: For aiDefaultLogStream_FILE: IOSystem to be used to open the output file. Pass nullptr for the default implementation.

class Assimp::DefaultLogger : public Assimp::Logger

CPP-API: Primary logging facility of Assimp.

The library stores its primary Logger as a static member of this class. get() returns this primary logger. By default the underlying implementation is just a #NullLogger which rejects all log messages. By calling create(), logging is turned on. To capture the log output multiple log streams (#LogStream) can be attach to the logger. Some default streams for common streaming locations (such as a file, std::cout, OutputDebugString()) are also provided.

If you wish to customize the logging at an even deeper level supply your own implementation of Logger to set().

Note

The whole logging stuff causes a small extra overhead for all imports.

Public Functions

bool attachStream(LogStream *pStream, unsigned int severity)

Attach a new log-stream.

The logger takes ownership of the stream and is responsible for its destruction (which is done using ::delete when the logger itself is destroyed). Call detachStream to detach a stream and to gain ownership of it again.

Return

true if the stream has been attached, false otherwise.

Parameters

• pStream: Log-stream to attach

• severity: Message filter, specified which types of log messages are dispatched to the stream. Provide a bitwise combination of the ErrorSeverity flags.

bool detachStream(LogStream *pStream, unsigned int severity)

Detach a still attached stream from the logger (or modify the filter flags bits)

Return

true if the stream has been detached, false otherwise.

Parameters

• pStream: Log-stream instance for detaching

• severity: Provide a bitwise combination of the ErrorSeverity flags. This value is &~ed with the current flags of the stream, if the result is 0 the stream is detached from the Logger and the caller retakes the possession of the stream.

Public Static Functions

Logger *create(const char *name = ASSIMP_DEFAULT_LOG_NAME, LogSeverity severity = NORMAL, unsigned int defStreams = aiDefaultLogStream_DEBUGGER | aiDefaultLogStream_FILE, IOSystem *io = nullptr)

Creates a logging instance.

Parameters

• name: Name for log file. Only valid in combination with the aiDefaultLogStream_FILE flag.

• severity: Log severity, DEBUG turns on debug messages and VERBOSE turns on all messages.

• defStreams: Default log streams to be attached. Any bitwise combination of the aiDefaultLogStream enumerated values. If aiDefaultLogStream_FILE is specified but an empty string is passed for ‘name’, no log file is created at all.

• io: IOSystem to be used to open external files (such as the log file). Pass nullptr to rely on the default implementation. This replaces the default #NullLogger with a #DefaultLogger instance.

Logger *get()

Getter for singleton instance.

Return

Only instance. This is never null, but it could be a NullLogger. Use isNullLogger to check this.

bool isNullLogger()

Return whether a #NullLogger is currently active.

Return

true if the current logger is a #NullLogger. Use create() or set() to setup a logger that does actually do something else than just rejecting all log messages.

void kill()

Kills the current singleton logger and replaces it with a #NullLogger instance.

void set(Logger *logger)

Setup a custom Logger implementation.

Use this if the provided #DefaultLogger class doesn’t fit into your needs. If the provided message formatting is OK for you, it’s much easier to use create() and to attach your own custom output streams to it.

Parameters

• logger: Pass NULL to setup a default NullLogger

class Assimp::NullLogger : public Assimp::Logger

CPP-API: Empty logging implementation.

Does nothing! Used by default if the application hasn’t requested a custom logger via #DefaultLogger::set() or #DefaultLogger::create();

Public Functions

bool attachStream(LogStream *pStream, unsigned int severity)

Detach a still attached stream from logger.

bool detachStream(LogStream *pStream, unsigned int severity)

Detach a still attached stream from logger.

void OnDebug(const char *message)

Logs a debug message.

void OnError(const char *message)

Logs an error message.

void OnInfo(const char *message)

Logs an info message.

void OnVerboseDebug(const char *message)

Logs a verbose debug message.

void OnWarn(const char *message)

Logs a warning message.

IO-System API

class Assimp::IOSystem : public Intern::AllocateFromAssimpHeap

CPP-API: Interface to the file system.

Derive an own implementation from this interface to supply custom file handling to the importer library. If you implement this interface, you also want to supply a custom implementation for IOStream.

See

Importer::SetIOHandler()

Subclassed by Assimp::BlobIOSystem, Assimp::DefaultIOSystem, Assimp::MemoryIOSystem, Assimp::ZipArchiveIOSystem

Public Functions

bool ChangeDirectory(const std::string &path)

Will change the current directory to the given path.

Return

True, when the directory has changed successfully.

Parameters

• path: [in] The path to change to.

void Close(IOStream *pFile) = 0

Closes the given file and releases all resources associated with it.

Parameters

• pFile: The file instance previously created by Open().

bool ComparePaths(const char *one, const char *second) const

Compares two paths and check whether the point to identical files.

The dummy implementation of this virtual member performs a case-insensitive comparison of the given strings. The default IO system implementation uses OS mechanisms to convert relative into absolute paths, so the result can be trusted.

Return

true if the paths point to the same file. The file needn’t be existing, however.

Parameters

• one: First file

• second: Second file

bool ComparePaths(const std::string &one, const std::string &second) const

For backward compatibility.

See

ComparePaths(const char*, const char*)

bool CreateDirectory(const std::string &path)

CReates an new directory at the given path.

Return

True, when a directory was created. False if the directory cannot be created.

Parameters

• path: [in] The path to create.

const std::string &CurrentDirectory() const

Returns the top directory from the stack.

Return

The directory on the top of the stack. Returns empty when no directory was pushed to the stack.

bool Exists(const char *pFile) const = 0

Tests for the existence of a file at the given path.

Return

true if there is a file with this path, else false.

Parameters

• pFile: Path to the file

AI_FORCE_INLINE bool Exists (const std::string &pFile) const

For backward compatibility.

See

Exists(const char*)

char getOsSeparator() const = 0

Returns the system specific directory separator.

Return

System specific directory separator

IOSystem () AI_NO_EXCEPT

Default constructor.

Create an instance of your derived class and assign it to an Assimp::Importer instance by calling Importer::SetIOHandler().

IOStream *Open(const char *pFile, const char *pMode = "rb") = 0

Open a new file with a given path.

When the access to the file is finished, call Close() to release all associated resources (or the virtual dtor of the IOStream).

Return

New IOStream interface allowing the lib to access the underlying file.

Note

When implementing this class to provide custom IO handling, you probably have to supply an own implementation of IOStream as well.

Parameters

• pFile: Path to the file

• pMode: Desired file I/O mode. Required are: “wb”, “w”, “wt”, “rb”, “r”, “rt”.

IOStream *Open(const std::string &pFile, const std::string &pMode = std::string("rb"))

For backward compatibility.

See

Open(const char*, const char*)

bool PopDirectory()

Pops the top directory from the stack.

Return

True, when a directory was on the stack. False if no directory was on the stack.

bool PushDirectory(const std::string &path)

Pushes a new directory onto the directory stack.

Return

True, when push was successful, false if path is empty.

Parameters

• path: Path to push onto the stack.

size_t StackSize() const

Returns the number of directories stored on the stack.

Return

The number of directories of the stack.

~IOSystem()

Virtual destructor.

It is safe to be called from within DLL Assimp, we’re constructed on Assimp’s heap.

class Assimp::IOStream : public Intern::AllocateFromAssimpHeap

CPP-API: Class to handle file I/O for C++.

Derive an own implementation from this interface to provide custom IO handling to the Importer. If you implement this interface, be sure to also provide an implementation for IOSystem that creates instances of your custom IO class.

Subclassed by Assimp::BlobIOStream, Assimp::DefaultIOStream, Assimp::MemoryIOStream

Public Functions

size_t FileSize() const = 0

Returns filesize Returns the filesize.

void Flush() = 0

Flush the contents of the file buffer (for writers) See fflush() for more details.

size_t Read(void *pvBuffer, size_t pSize, size_t pCount) = 0

Read from the file.

See fread() for more details This fails for write-only files

aiReturn Seek(size_t pOffset, aiOrigin pOrigin) = 0

Set the read/write cursor of the file.

Note that the offset is negative for aiOrigin_END. See fseek() for more details

size_t Tell() const = 0

Get the current position of the read/write cursor.

See ftell() for more details

size_t Write(const void *pvBuffer, size_t pSize, size_t pCount) = 0

Write to the file.

See fwrite() for more details This fails for read-only files

~IOStream()

Destructor.

Deleting the object closes the underlying file, alternatively you may use IOSystem::Close() to release the file.

template<class T>
class Assimp::IOStreamBuffer

Implementation of a cached stream buffer.

Public Functions

size_t cacheSize() const

Returns the cache size.

Return

The cache size.

bool close()

Will close the cached access.

Return

true if successful.

size_t getCurrentBlockIndex() const

Returns the current block index.

Return

The current block index.

size_t getFilePos() const

Returns the current file pos.

Return

The current file pos.

bool getNextBlock(std::vector<T> &buffer)

Will read the next block.

Return

true if successful.

Parameters

• buffer: The buffer for the next block.

bool getNextDataLine(std::vector<T> &buffer, T continuationToken)

Will read the next line.

Return

true if successful.

Parameters

• buffer: The buffer for the next line.

bool getNextLine(std::vector<T> &buffer)

Will read the next line ascii or binary end line char.

Return

true if successful.

Parameters

• buffer: The buffer for the next line.

size_t getNumBlocks() const

Returns the number of blocks to read.

Return

The number of blocks.

IOStreamBuffer(size_t cache = 4096 * 4096)

The class constructor.

bool open(IOStream *stream)

Will open the cached access for a given stream.

Return

true if successful.

Parameters

• stream: The stream to cache.

bool readNextBlock()

Will read the next block.

Return

true if successful.

size_t size() const

Returns the file-size.

Return

The file-size.

~IOStreamBuffer()

The class destructor.

class Assimp::MemoryIOStream : public Assimp::IOStream

Implementation of IOStream to read directly from a memory buffer.

Public Functions

size_t FileSize() const

Returns filesize Returns the filesize.

void Flush()

Flush the contents of the file buffer (for writers) See fflush() for more details.

size_t Read(void *pvBuffer, size_t pSize, size_t pCount)

Read from the file.

See fread() for more details This fails for write-only files

aiReturn Seek(size_t pOffset, aiOrigin pOrigin)

Set the read/write cursor of the file.

Note that the offset is negative for aiOrigin_END. See fseek() for more details

size_t Tell() const

Get the current position of the read/write cursor.

See ftell() for more details

size_t Write(const void*, size_t, size_t)

Write to the file.

See fwrite() for more details This fails for read-only files

class Assimp::DefaultIOSystem : public Assimp::IOSystem

Default implementation of IOSystem using the standard C file functions.

Public Functions

void Close(IOStream *pFile)

Closes the given file and releases all resources associated with it.

bool ComparePaths(const char *one, const char *second) const

Compare two paths.

bool Exists(const char *pFile) const

Tests for the existence of a file at the given path.

char getOsSeparator() const

Returns the directory separator.

IOStream *Open(const char *pFile, const char *pMode = "rb")

Open a new file with a given path.

Public Static Functions

std::string absolutePath(const std::string &path)

get the path of a full filepath example: /tmp/archive.tar.gz -> /tmp/

std::string completeBaseName(const std::string &path)

get the complete base name of a full filepath example: /tmp/archive.tar.gz -> archive.tar

std::string fileName(const std::string &path)

get the file name of a full filepath example: /tmp/archive.tar.gz -> archive.tar.gz

class Assimp::DefaultIOStream : public Assimp::IOStream

Default IO implementation, use standard IO operations.

Note

An instance of this class can exist without a valid file handle attached to it. All calls fail, but the instance can nevertheless be used with no restrictions.

Public Functions

size_t FileSize() const

Get size of file.

void Flush()

Flush file contents.

size_t Read(void *pvBuffer, size_t pSize, size_t pCount)

Read from stream.

aiReturn Seek(size_t pOffset, aiOrigin pOrigin)

Seek specific position.

size_t Tell() const

Get current seek position.

size_t Write(const void *pvBuffer, size_t pSize, size_t pCount)

Write to stream.

~DefaultIOStream()

Destructor public to allow simple deletion to close the file.

class Assimp::MemoryIOSystem : public Assimp::IOSystem

Dummy IO system to read from a memory buffer.

Public Functions

bool ChangeDirectory(const std::string &path) override

Will change the current directory to the given path.

Return

True, when the directory has changed successfully.

Parameters

• path: [in] The path to change to.

void Close(IOStream *pFile) override

Closes the given file and releases all resources associated with it.

bool ComparePaths(const char *one, const char *second) const override

Compare two paths.

bool CreateDirectory(const std::string &path) override

CReates an new directory at the given path.

Return

True, when a directory was created. False if the directory cannot be created.

Parameters

• path: [in] The path to create.

const std::string &CurrentDirectory() const override

Returns the top directory from the stack.

Return

The directory on the top of the stack. Returns empty when no directory was pushed to the stack.

bool Exists(const char *pFile) const override

Tests for the existence of a file at the given path.

char getOsSeparator() const override

Returns the directory separator.

MemoryIOSystem(const uint8_t *buff, size_t len, IOSystem *io)

Constructor.

IOStream *Open(const char *pFile, const char *pMode = "rb") override

Open a new file with a given path.

bool PopDirectory() override

Pops the top directory from the stack.

Return

True, when a directory was on the stack. False if no directory was on the stack.

bool PushDirectory(const std::string &path) override

Pushes a new directory onto the directory stack.

Return

True, when push was successful, false if path is empty.

Parameters

• path: Path to push onto the stack.

size_t StackSize() const override

Returns the number of directories stored on the stack.

Return

The number of directories of the stack.

~MemoryIOSystem()

Destructor.

class Assimp::MemoryIOStream : public Assimp::IOStream

Implementation of IOStream to read directly from a memory buffer.

Public Functions

size_t FileSize() const

Returns filesize Returns the filesize.

void Flush()

Flush the contents of the file buffer (for writers) See fflush() for more details.

size_t Read(void *pvBuffer, size_t pSize, size_t pCount)

Read from the file.

See fread() for more details This fails for write-only files

aiReturn Seek(size_t pOffset, aiOrigin pOrigin)

Set the read/write cursor of the file.

Note that the offset is negative for aiOrigin_END. See fseek() for more details

size_t Tell() const

Get the current position of the read/write cursor.

See ftell() for more details

size_t Write(const void*, size_t, size_t)

Write to the file.

See fwrite() for more details This fails for read-only files

class Assimp::BlobIOStream : public Assimp::IOStream

Redirect IOStream to a blob.

Public Functions

size_t FileSize() const

Returns filesize Returns the filesize.

void Flush()

Flush the contents of the file buffer (for writers) See fflush() for more details.

size_t Read(void*, size_t, size_t)

Read from the file.

See fread() for more details This fails for write-only files

aiReturn Seek(size_t pOffset, aiOrigin pOrigin)

Set the read/write cursor of the file.

Note that the offset is negative for aiOrigin_END. See fseek() for more details

size_t Tell() const

Get the current position of the read/write cursor.

See ftell() for more details

size_t Write(const void *pvBuffer, size_t pSize, size_t pCount)

Write to the file.

See fwrite() for more details This fails for read-only files

class Assimp::BlobIOSystem : public Assimp::IOSystem

Redirect IOSystem to a blob.

Public Functions

void Close(IOStream *pFile)

Closes the given file and releases all resources associated with it.

Parameters

• pFile: The file instance previously created by Open().

bool Exists(const char *pFile) const

Tests for the existence of a file at the given path.

Return

true if there is a file with this path, else false.

Parameters

• pFile: Path to the file

char getOsSeparator() const

Returns the system specific directory separator.

Return

System specific directory separator

IOStream *Open(const char *pFile, const char *pMode)

Open a new file with a given path.

When the access to the file is finished, call Close() to release all associated resources (or the virtual dtor of the IOStream).

Return

New IOStream interface allowing the lib to access the underlying file.

Note

When implementing this class to provide custom IO handling, you probably have to supply an own implementation of IOStream as well.

Parameters

• pFile: Path to the file

• pMode: Desired file I/O mode. Required are: “wb”, “w”, “wt”, “rb”, “r”, “rt”.

Import/Export API

class Assimp::BaseImporter

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.

Public Types

enum TextFileMode

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

Values:

enumerator ALLOW_EMPTY

enumerator FORBID_EMPTY

Public Functions

BaseImporter () AI_NO_EXCEPT

Constructor to be privately used by Importer.

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

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.

Return

true if the class can read this file, false if not.

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.

const std::string &GetErrorText() const

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

Return

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

const std::exception_ptr &GetException() const

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.

Return

The last exception that occurred.

void 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

const aiImporterDesc *GetInfo() const = 0

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

Importers must provide this information.

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

Return

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.

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.

void SetFileScale(double scale)

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

void SetupProperties(const Importer *pImp)

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

~BaseImporter()

Destructor, private as well.

Public Static Functions

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.

Return

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.

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.

void ConvertToUTF8(std::vector<char> &data)

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.

void ConvertUTF8toISO8859_1(std::string &data)

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.

template<typename T> 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.

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.

template<typename T> 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.

Parameters

• vec: The vector to be moved

• out: The output pointer to the allocated array.

• numOut: The output count of elements copied.

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

Extract file extension from a string.

Return

Extension without trailing dot, all lowercase

Parameters

• pFile: Input file

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

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.

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.

Note

Case-insensitive

Parameters

• pFile: Input file

• ext0: Extension to check for. Lowercase characters only, no dot!

• ext1: Optional second extension

• ext2: Optional third extension

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.

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.

class Assimp::Importer

CPP-API: The Importer class forms an C++ interface to the functionality of the Open Asset Import Library.

Create an object of this class and call ReadFile() to import a file. If the import succeeds, the function returns a pointer to the imported data. The data remains property of the object, it is intended to be accessed read-only. The imported data will be destroyed along with the Importer object. If the import fails, ReadFile() returns a nullptr pointer. In this case you can retrieve a human-readable error description be calling GetErrorString(). You can call ReadFile() multiple times with a single Importer instance. Actually, constructing Importer objects involves quite many allocations and may take some time, so it’s better to reuse them as often as possible.

If you need the Importer to do custom file handling to access the files, implement IOSystem and IOStream and supply an instance of your custom IOSystem implementation by calling SetIOHandler() before calling ReadFile(). If you do not assign a custion IO handler, a default handler using the standard C++ IO logic will be used.

Note

One Importer instance is not thread-safe. If you use multiple threads for loading, each thread should maintain its own Importer instance.

Public Functions

const aiScene *ApplyPostProcessing(unsigned int pFlags)

Apply post-processing to an already-imported scene.

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

Return

A pointer to the post-processed data. This is still the same as the pointer returned by ReadFile(). However, if post-processing fails, the scene could now be nullptr. That’s quite a rare case, post processing steps are not really designed to ‘fail’. To be exact, the #aiProcess_ValidateDS flag is currently the only post processing step which can actually cause the scene to be reset to nullptr.

Note

The method does nothing if no scene is currently bound to the Importer instance.

Parameters

• pFlags: Provide a bitwise combination of the aiPostProcessSteps flags.

void FreeScene()

Frees the current scene.

The function does nothing if no scene has previously been read via ReadFile(). FreeScene() is called automatically by the destructor and ReadFile() itself.

const char *GetErrorString() const

Returns an error description of an error that occurred in ReadFile().

Returns an empty string if no error occurred.

Return

A description of the last error, an empty string if no error occurred. The string is never nullptr.

Note

The returned function remains valid until one of the following methods is called: ReadFile(), FreeScene().

const std::exception_ptr &GetException() const

Returns an exception if one occurred during import.

Return

The last exception which occurred.

Note

The returned value remains valid until one of the following methods is called: ReadFile(), FreeScene().

void GetExtensionList(aiString &szOut) const

Get a full 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 it simply means there is an importer loaded which claims to handle files with this file extension.

Parameters

• szOut: String to receive the extension list. Format of the list: “*.3ds;*.obj;*.dae”. This is useful for use with the WinAPI call GetOpenFileName(Ex).

void GetExtensionList(std::string &szOut) const

Get a full list of all file extensions supported by ASSIMP.

This function is provided for backward compatibility. See the aiString version for detailed and up-to-date docs.

See

GetExtensionList(aiString&)

BaseImporter *GetImporter(const char *szExtension) const

Find the importer corresponding to a specific file extension.

This is quite similar to IsExtensionSupported except a BaseImporter instance is returned.

Return

nullptr if no importer is found

Parameters

• szExtension: Extension to check for. The following formats are recognized (BAH being the file extension): “BAH” (comparison is case-insensitive), “.bah”, “*.bah” (wild card and dot characters at the beginning of the extension are skipped).

BaseImporter *GetImporter(size_t index) const

Find the importer corresponding to a specific index.

Return

Importer instance. nullptr if the index does not exist.

Parameters

• index: Index to query, must be within [0,GetImporterCount())

size_t GetImporterCount() const

Get the number of importers currently registered with Assimp.

size_t GetImporterIndex(const char *szExtension) const

Find the importer index corresponding to a specific file extension.

Return

(size_t)-1 if no importer is found

Parameters

• szExtension: Extension to check for. The following formats are recognized (BAH being the file extension): “BAH” (comparison is case-insensitive), “.bah”, “*.bah” (wild card and dot characters at the beginning of the extension are skipped).

const aiImporterDesc *GetImporterInfo(size_t index) const

Get meta data for the importer corresponding to a specific index.

For the declaration of aiImporterDesc, include <assimp/importerdesc.h>.

Return

Importer meta data structure, nullptr if the index does not exist or if the importer doesn’t offer meta information ( importers may do this at the cost of being hated by their peers).

Parameters

• index: Index to query, must be within [0,GetImporterCount())

IOSystem *GetIOHandler() const

Retrieves the IO handler that is currently set.

You can use IsDefaultIOHandler() to check whether the returned interface is the default IO handler provided by ASSIMP. The default handler is active as long the application doesn’t supply its own custom IO handler via SetIOHandler().

Return

A valid IOSystem interface, never nullptr.

void GetMemoryRequirements(aiMemoryInfo &in) const

Returns the storage allocated by ASSIMP to hold the scene data in memory.

This refers to the currently loaded file, see ReadFile().

Note

The returned memory statistics refer to the actual size of the use data of the aiScene. Heap-related overhead is (naturally) not included.

Parameters

• in: Data structure to be filled.

aiScene *GetOrphanedScene()

Returns the scene loaded by the last successful call to ReadFile() and releases the scene from the ownership of the Importer instance.

The application is now responsible for deleting the scene. Any further calls to GetScene() or GetOrphanedScene() will return nullptr - until a new scene has been loaded via ReadFile().

Return

Current scene or nullptr if there is currently no scene loaded

Note

Use this method with maximal caution, and only if you have to. By design, aiScene’s are exclusively maintained, allocated and deallocated by Assimp and no one else. The reasoning behind this is the golden rule that deallocations should always be done by the module that did the original allocation because heaps are not necessarily shared. GetOrphanedScene() enforces you to delete the returned scene by yourself, but this will only be fine if and only if you’re using the same heap as assimp. On Windows, it’s typically fine provided everything is linked against the multithreaded-dll version of the runtime library. It will work as well for static linkage with Assimp.

ProgressHandler *GetProgressHandler() const

Retrieves the progress handler that is currently set.

You can use IsDefaultProgressHandler() to check whether the returned interface is the default handler provided by ASSIMP. The default handler is active as long the application doesn’t supply its own custom handler via SetProgressHandler().

Return

A valid ProgressHandler interface, never nullptr.

bool GetPropertyBool(const char *szName, bool bErrorReturn = false) const

Get a boolean configuration property.

Boolean properties are stored on the integer stack internally so it’s possible to set them via SetPropertyBool and query them with GetPropertyBool and vice versa.

See

GetPropertyInteger()

ai_real GetPropertyFloat(const char *szName, ai_real fErrorReturn = 10e10) const

Get a floating-point configuration property.

See

GetPropertyInteger()

int GetPropertyInteger(const char *szName, int iErrorReturn = 0xffffffff) const

Get a configuration property.

Return

Current value of the property

Note

Property of different types (float, int, string ..) are kept on different lists, so calling SetPropertyInteger() for a floating-point property has no effect - the loader will call GetPropertyFloat() to read the property, but it won’t be there.

Parameters

• szName: Name of the property. All supported properties are defined in the aiConfig.g header (all constants share the prefix AI_CONFIG_XXX).

• iErrorReturn: Value that is returned if the property is not found.

aiMatrix4x4 GetPropertyMatrix(const char *szName, const aiMatrix4x4 &sErrorReturn = aiMatrix4x4()) const

Get a matrix configuration property.

The return value remains valid until the property is modified.

See

GetPropertyInteger()

std::string GetPropertyString(const char *szName, const std::string &sErrorReturn = std::string()) const

Get a string configuration property.

The return value remains valid until the property is modified.

See

GetPropertyInteger()

const aiScene *GetScene() const

Returns the scene loaded by the last successful call to ReadFile()

Return

Current scene or nullptr if there is currently no scene loaded

Importer()

Constructor.

Creates an empty importer object.

Call ReadFile() to start the import process. The configuration property table is initially empty.

Importer(const Importer &other) = delete

Copy constructor.

This copies the configuration properties of another Importer. If this Importer owns a scene it won’t be copied. Call ReadFile() to start the import process.

bool IsDefaultIOHandler() const

Checks whether a default IO handler is active A default handler is active as long the application doesn’t supply its own custom IO handler via SetIOHandler().

Return

true by default

bool IsDefaultProgressHandler() const

Checks whether a default progress handler is active A default handler is active as long the application doesn’t supply its own custom progress handler via SetProgressHandler().

Return

true by default

bool IsExtensionSupported(const char *szExtension) const

Returns whether a given file extension is supported by ASSIMP.

Return

true if the extension is supported, false otherwise

Parameters

• szExtension: Extension to be checked. Must include a trailing dot ‘.’. Example: “.3ds”, “.md3”. Cases-insensitive.

bool IsExtensionSupported(const std::string &szExtension) const

Returns whether a given file extension is supported by ASSIMP.

This function is provided for backward compatibility. See the const char* version for detailed and up-to-date docs.

See

IsExtensionSupported(const char*)

Importer &operator=(const Importer&) = delete

Assignment operator has been deleted.

ImporterPimpl *Pimpl()

Private, do not use.

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

Reads the given file and returns its contents if successful.

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 object keeps ownership of the data and will destroy it upon destruction. If the import fails, nullptr is returned. A human-readable error description can be retrieved by calling GetErrorString(). The previous scene will be deleted during this call.

Return

A pointer to the imported data, nullptr if the import failed. The pointer to the scene remains in possession of the Importer instance. Use GetOrphanedScene() to take ownership of it.

Note

Assimp is able to determine the file format of a file automatically.

Parameters

• pFile: Path and filename to the file to be imported.

• 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 ApplyPostProcessing().

const aiScene *ReadFile(const std::string &pFile, unsigned int pFlags)

Reads the given file and returns its contents if successful.

class Importer

This function is provided for backward compatibility. See the const char* version for detailed docs.

See

ReadFile(const char*, pFlags)

const aiScene *ReadFileFromMemory(const void *pBuffer, size_t pLength, unsigned int pFlags, const char *pHint = "")

Reads the given file from a memory buffer and returns its contents if successful.

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 object keeps ownership of the data and will destroy it upon destruction. If the import fails, nullptr is returned. A human-readable error description can be retrieved by calling GetErrorString(). The previous scene will be deleted during this call. Calling this method doesn’t affect the active IOSystem.

Return

A pointer to the imported data, nullptr if the import failed. The pointer to the scene remains in possession of the Importer instance. Use GetOrphanedScene() to take ownership of it.

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 ReadFile() API.

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

• 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 …

aiReturn RegisterLoader(BaseImporter *pImp)

Registers a new loader.

Return

AI_SUCCESS if the loader has been added. The registration fails if there is already a loader for a specific file extension.

Parameters

• pImp: Importer to be added. The Importer instance takes ownership of the pointer, so it will be automatically deleted with the Importer instance.

aiReturn RegisterPPStep(BaseProcess *pImp)

Registers a new post-process step.

At the moment, there’s a small limitation: new post processing steps are added to end of the list, or in other words, executed last, after all built-in steps.

Return

AI_SUCCESS if the step has been added correctly.

Parameters

• pImp: Post-process step to be added. The Importer instance takes ownership of the pointer, so it will be automatically deleted with the Importer instance.

void SetExtraVerbose(bool bDo)

Enables “extra verbose” mode.

‘Extra verbose’ means the data structure is validated after every single post processing step to make sure everyone modifies the data structure in a well-defined manner. This is a debug feature and not intended for use in production environments.

void SetIOHandler(IOSystem *pIOHandler)

Supplies a custom IO handler to the importer to use to open and access files.

If you need the importer to use custom IO logic to access the files, you need to provide a custom implementation of IOSystem and IOFile to the importer. Then create an instance of your custom IOSystem implementation and supply it by this function.

The Importer takes ownership of the object and will destroy it afterwards. The previously assigned handler will be deleted. Pass nullptr to take again ownership of your IOSystem and reset Assimp to use its default implementation.

Parameters

• pIOHandler: The IO handler to be used in all file accesses of the Importer.

void SetProgressHandler(ProgressHandler *pHandler)

Supplies a custom progress handler to the importer.

This interface exposes an #Update() callback, which is called more or less periodically (please don’t sue us if it isn’t as periodically as you’d like it to have …). This can be used to implement progress bars and loading timeouts.

Note

Progress handlers can be used to abort the loading at almost any time.

Parameters

• pHandler: Progress callback interface. Pass nullptr to disable progress reporting.

bool SetPropertyBool(const char *szName, bool value)

Set a boolean configuration property.

Boolean properties are stored on the integer stack internally so it’s possible to set them via SetPropertyBool and query them with GetPropertyBool and vice versa.

See

SetPropertyInteger()

bool SetPropertyFloat(const char *szName, ai_real fValue)

Set a floating-point configuration property.

See

SetPropertyInteger()

bool SetPropertyInteger(const char *szName, int iValue)

Set an integer configuration property.

Return

true if the property was set before. The new value replaces the previous value in this case.

Note

Property of different types (float, int, string ..) are kept on different stacks, so calling SetPropertyInteger() for a floating-point property has no effect - the loader will call GetPropertyFloat() to read the property, but it won’t be there.

Parameters

• szName: Name of the property. All supported properties are defined in the aiConfig.g header (all constants share the prefix AI_CONFIG_XXX and are simple strings).

• iValue: New value of the property

bool SetPropertyMatrix(const char *szName, const aiMatrix4x4 &sValue)

Set a matrix configuration property.

See

SetPropertyInteger()

bool SetPropertyString(const char *szName, const std::string &sValue)

Set a string configuration property.

See

SetPropertyInteger()

aiReturn UnregisterLoader(BaseImporter *pImp)

Unregisters a loader.

Return

AI_SUCCESS if the loader has been removed. The function fails if the loader is currently in use (this could happen if the Importer instance is used by more than one thread) or if it has not yet been registered.

Parameters

• pImp: Importer to be unregistered.

aiReturn UnregisterPPStep(BaseProcess *pImp)

Unregisters a post-process step.

Return

AI_SUCCESS if the step has been removed. The function fails if the step is currently in use (this could happen if the Importer instance is used by more than one thread) or if it has not yet been registered.

Parameters

• pImp: Step to be unregistered.

bool ValidateFlags(unsigned int pFlags) const

Check whether a given set of post-processing flags is supported.

Some flags are mutually exclusive, others are probably not available because your excluded them from your Assimp builds. Calling this function is recommended if you’re unsure.

Return

true if this flag combination is fine.

Parameters

• pFlags: Bitwise combination of the aiPostProcess flags.

~Importer()

Destructor.

The object kept ownership of the imported data, which now will be destroyed along with the object.

Public Static Attributes

const unsigned int MaxLenHint = 200

The upper limit for hints.

class Assimp::Exporter

Public Types

typedef void (*fpExportFunc)(const char*, IOSystem*, const aiScene*, const ExportProperties*)

Function pointer type of a Export worker function.

Public Functions

aiReturn Export(const aiScene *pScene, const char *pFormatId, const char *pPath, unsigned int pPreprocessing = 0u, const ExportProperties *pProperties = nullptr)

Convenience function to export directly to a file.

Use #SetIOSystem to supply a custom IOSystem to gain fine-grained control about the output data flow of the export process.

If assimp detects that the input scene was directly taken from the importer side of the library (i.e. not copied using aiCopyScene and potentially modified afterwards), any post-processing steps already applied to the scene will not be applied again, unless they show non-idempotent behavior (

aiProcess_MakeLeftHanded, aiProcess_FlipUVs and aiProcess_FlipWindingOrder).

Return

AI_SUCCESS if everything was fine.

Note

Use aiCopyScene() to get a modifiable copy of a previously imported scene.

Parameters

• pBlob: A data blob obtained from a previous call to aiExportScene. Must not be nullptr.

• pPath: Full target file name. Target must be accessible.

• pPreprocessing: Accepts any choice of the aiPostProcessSteps enumerated flags, but in reality only a subset of them makes sense here. Specifying ‘preprocessing’ flags is useful if the input scene does not conform to Assimp’s default conventions as specified in the Data Structures Page . In short, this means the geometry data should use a right-handed coordinate systems, face winding should be counter-clockwise and the UV coordinate origin is assumed to be in the upper left. The aiProcess_MakeLeftHanded, aiProcess_FlipUVs and aiProcess_FlipWindingOrder flags are used in the import side to allow users to have those defaults automatically adapted to their conventions. Specifying those flags for exporting has the opposite effect, respectively. Some other of the aiPostProcessSteps enumerated values may be useful as well, but you’ll need to try out what their effect on the exported file is. Many formats impose their own restrictions on the structure of the geometry stored therein, so some preprocessing may have little or no effect at all, or may be redundant as exporters would apply them anyhow. A good example is triangulation - whilst you can enforce it by specifying the aiProcess_Triangulate flag, most export formats support only triangulate data so they would run the step even if it wasn’t requested.

Exporter()

The class constructor.

const aiExportDataBlob *ExportToBlob(const aiScene *pScene, const char *pFormatId, unsigned int pPreprocessing = 0u, const ExportProperties *pProperties = nullptr)

Exports the given scene to a chosen file format.

Returns the exported data as a binary blob which you can write into a file or something. When you’re done with the data, simply let the Exporter instance go out of scope to have it released automatically.

Return

the exported data or nullptr in case of error.

Note

If the Exporter instance did already hold a blob from a previous call to ExportToBlob, it will be disposed. Any IO handlers set via SetIOHandler are ignored here.

Note

Use aiCopyScene() to get a modifiable copy of a previously imported scene.

Parameters

• pScene: The scene to export. Stays in possession of the caller, is not changed by the function.

• pFormatId: ID string to specify to which format you want to export to. Use GetExportFormatCount / GetExportFormatDescription to learn which export formats are available.

• pPreprocessing: See the documentation for Export

void FreeBlob()

Frees the current blob.

The function does nothing if no blob has previously been previously produced via ExportToBlob. FreeBlob is called automatically by the destructor. The only reason to call it manually would be to reclaim as much storage as possible without giving up the Exporter instance yet.

const aiExportDataBlob *GetBlob() const

Return the blob obtained from the last call to ExportToBlob.

const char *GetErrorString() const

Returns an error description of an error that occurred in Export or ExportToBlob.

Returns an empty string if no error occurred.

Return

A description of the last error, an empty string if no error occurred. The string is never nullptr.

Note

The returned function remains valid until one of the following methods is called: Export, ExportToBlob, FreeBlob

size_t GetExportFormatCount() const

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

Use #Exporter::GetExportFormatDescription to retrieve infos of a specific export format.

This includes built-in exporters as well as exporters registered using RegisterExporter.

const aiExportFormatDesc *GetExportFormatDescription(size_t pIndex) const

Returns a description of the nth export file format.

Use # #Exporter::GetExportFormatCount to learn how many export formats are supported.

The returned pointer is of static storage duration if the pIndex pertains to a built-in exporter (i.e. one not registered via #RegistrerExporter). It is restricted to the life-time of the Exporter instance otherwise.

Return

A description of that specific export format. NULL if pIndex is out of range.

Parameters

• pIndex: Index of the export format to retrieve information for. Valid range is 0 to #Exporter::GetExportFormatCount

IOSystem *GetIOHandler() const

Retrieves the IO handler that is currently set.

You can use IsDefaultIOHandler() to check whether the returned interface is the default IO handler provided by ASSIMP. The default handler is active as long the application doesn’t supply its own custom IO handler via SetIOHandler().

Return

A valid IOSystem interface, never NULL.

const aiExportDataBlob *GetOrphanedBlob() const

Orphan the blob from the last call to ExportToBlob.

This means the caller takes ownership and is thus responsible for calling the C API function aiReleaseExportBlob to release it.

bool IsDefaultIOHandler() const

Checks whether a default IO handler is active A default handler is active as long the application doesn’t supply its own custom IO handler via SetIOHandler().

Return

true by default

aiReturn RegisterExporter(const ExportFormatEntry &desc)

Register a custom exporter.

Custom export formats are limited to to the current Exporter instance and do not affect the library globally. The indexes under which the format’s export format description can be queried are assigned monotonously.

Return

aiReturn_SUCCESS if the export format was successfully registered. A common cause that would prevent an exporter from being registered is that its format id is already occupied by another format.

Parameters

• desc: Exporter description.

void SetIOHandler(IOSystem *pIOHandler)

Supplies a custom IO handler to the exporter to use to open and access files.

If you need Export to use custom IO logic to access the files, you need to supply a custom implementation of IOSystem and IOFile to the exporter.

Exporter takes ownership of the object and will destroy it afterwards. The previously assigned handler will be deleted. Pass NULL to take again ownership of your IOSystem and reset Assimp to use its default implementation, which uses plain file IO.

Parameters

• pIOHandler: The IO handler to be used in all file accesses of the Importer.

void SetProgressHandler(ProgressHandler *pHandler)

Supplies a custom progress handler to the exporter.

This interface exposes an #Update() callback, which is called more or less periodically (please don’t sue us if it isn’t as periodically as you’d like it to have …). This can be used to implement progress bars and loading timeouts.

Note

Progress handlers can be used to abort the loading at almost any time.

Parameters

• pHandler: Progress callback interface. Pass nullptr to disable progress reporting.

void UnregisterExporter(const char *id)

Remove an export format previously registered with RegisterExporter from the Exporter instance (this can also be used to drop built-in exporters because those are implicitly registered using RegisterExporter).

Note

Calling this method on a format description not yet registered has no effect.

Parameters

• id: Format id to be unregistered, this refers to the ‘id’ field of aiExportFormatDesc.

~Exporter()

The class destructor.

struct ExportFormatEntry

Internal description of an Assimp export format option.

Public Members

aiExportFormatDesc mDescription

Public description structure to be returned by aiGetExportFormatDescription()

Parsing API

template<class TNodeType>
class Assimp::TXmlParser

The Xml-Parser class.

Use this parser if you have to import any kind of xml-format.

An example:

TXmlParser<XmlNode> theParser;
if (theParser.parse(fileStream)) {
    auto node = theParser.getRootNode();
    for ( auto currentNode : node.children()) {
        // Will loop over all children
    }
}

Template Parameters

• TNodeType:

Public Functions

void clear()

Will clear the parsed xml-file.

TNodeType *findNode(const std::string &name)

Will search for a child-node by its name.

Return

The node instance or nullptr, if nothing was found.

Parameters

• name: [in] The name of the child-node.

pugi::xml_document *getDocument() const

Will return the document pointer, is nullptr if no xml-file was parsed.

Return

The pointer showing to the document.

TNodeType getRootNode()

Will return the root node, non-const version.

Return

The root node.

const TNodeType getRootNode() const

Will return the root node, const version.

Return

The root node.

bool hasNode(const std::string &name)

Will return true, if the node is a child-node.

Return

true, if the node is a child-node or false if not.

Parameters

• name: [in] The name of the child node to look for.

bool hasRoot() const

Will return truem if a root node is there.

Return

true in case of an existing root.

bool parse(IOStream *stream)

Will parse an xml-file from a given stream.

Return

true, if the parsing was successful, false if not.

Parameters

• stream: The input stream.

TXmlParser()

The default class constructor.

~TXmlParser()

The class destructor.

Public Static Functions

bool getBoolAttribute(XmlNode &xmlNode, const char *name, bool &val)

Will try to get a bool attribute value.

Return

true, if the node contains an attribute with the given name and if the value is a bool.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The bool value from the attribute.

bool getDoubleAttribute(XmlNode &xmlNode, const char *name, double &val)

Will try to get a double attribute value.

Return

true, if the node contains an attribute with the given name and if the value is a double.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The double value from the attribute.

bool getFloatAttribute(XmlNode &xmlNode, const char *name, float &val)

Will try to get a float attribute value.

Return

true, if the node contains an attribute with the given name and if the value is a float.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The float value from the attribute.

bool getIntAttribute(XmlNode &xmlNode, const char *name, int &val)

Will try to get an int attribute value.

Return

true, if the node contains an attribute with the given name and if the value is an int.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The int value from the attribute.

bool getRealAttribute(XmlNode &xmlNode, const char *name, ai_real &val)

Will try to get a real attribute value.

Return

true, if the node contains an attribute with the given name and if the value is a real.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The real value from the attribute.

bool getStdStrAttribute(XmlNode &xmlNode, const char *name, std::string &val)

Will try to get a std::string attribute value.

Return

true, if the node contains an attribute with the given name and if the value is a std::string.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The std::string value from the attribute.

bool getUIntAttribute(XmlNode &xmlNode, const char *name, unsigned int &val)

Will try to get an unsigned int attribute value.

Return

true, if the node contains an attribute with the given name and if the value is an unsigned int.

Parameters

• xmlNode: [in] The node to search in.

• name: [in] The attribute name to look for.

• val: [out] The unsigned int value from the attribute.

bool getValueAsFloat(XmlNode &node, ai_real &v)

Will try to get the value of the node as a float.

Return

true, if the value can be read out.

Parameters

• node: [in] The node to search in.

• text: [out] The value as a float.

bool getValueAsString(XmlNode &node, std::string &text)

Will try to get the value of the node as a string.

Return

true, if the value can be read out.

Parameters

• node: [in] The node to search in.

• text: [out] The value as a text.

bool hasAttribute(XmlNode &xmlNode, const char *name)

Will check if an attribute is part of the XmlNode.

Return

true, if the was found, false if not.

Parameters

• xmlNode: [in] The node to search in.

• name: [in} The attribute name to look for.

bool hasNode(XmlNode &node, const char *name)

Will check if a node with the given name is in.

Return

true, if node was found, false if not.

Parameters

• node: [in] The node to look in.

• name: [in] The name of the child-node.