@section intro Introduction
assimp is a library to load and process geometric scenes from various data formats. It is tailored at typical game
scenarios by supporting a node hierarchy, static or skinned meshes, materials, bone animations and potential texture data.
The library is *not* designed for speed, it is primarily useful for importing assets from various sources once and
storing it in a engine-specific format for easy and fast every-day-loading. assimp is also able to apply various post
processing steps to the imported data such as conversion to indexed meshes, calculation of normals or tangents/bitangents
or conversion from right-handed to left-handed coordinate systems.
assimp currently supports the following file formats (note that some loaders lack some features of their formats because
some file formats contain data not supported by assimp, some stuff would require so much conversion work
that it has not been implemented yet and some (most ...) formats lack proper specifications):
Please don't forget to also read the @ref assimp_stl section on MSVC and the STL. @section assimp_stl Microsoft Compilers and the C++ Standard Library In VC8 and VC9 Microsoft introduced some Standard Library debugging features. A good example are improved iterator checks and various useful debug checks. The problem is the performance penalty that incurs with those extra checks. Most of these security enhancements are active in release builds by default, rendering assimp several times slower. However, it is possible to disable them by setting @code _HAS_ITERATOR_DEBUGGING=0 _SECURE_SCL=0 @endcode in the preprocessor options (or alternatively in the source code, just before the STL is included for the first time). assimp's vc8 and vc9 configs enable these flags by default. If you're linking statically against assimp: Make sure your applications uses the same STl settings! If you do not, there are two binary incompatible STL versions mangled together and you'll crash. Alternatively you can disable the fast STL settings for assimp by removing the 'FastSTL' property sheet from the vc project file. If you're using assimp in a DLL/SO: It's ok. There's no STL used in the binary DLL/SO interface, so it doesn't care whether your application uses the same STL settings or not.
Another option is to build against a different STL implementation, for example STlport. There's a special @ref assimp_stlport section that has a description how to achieve this. @section install_own Building the library from scratch To build the library on your own you first have to get hold of the dependencies. Fortunately, special attention was paid to keep the list of dependencies short. Unfortunately, the only dependency is boost which can be a bit painful to set up for certain development environments. Boost is a widely used collection of classes and functions for various purposes. Chances are that it was already installed along with your compiler. If not, you have to install it for yourself. Read the "Getting Started" section of the Boost documentation for how to setup boost. VisualStudio users can use a comfortable installer from http://www.boost-consulting.com/products/free. Choose the appropriate version of boost for your runtime of choice. If you don't want to use boost, you can build against our "Boost-Workaround". It consists of very small implementations of the various boost utility classes used. However, you'll lose functionality (e.g. threading) by doing this. So, if you can use boost, you should use boost. Otherwise, See the @link use_noboost NoBoost-Section @endlink later on this page for the details of the workaround. Once boost is working, you have to set up a project for the assimp library in your favorite IDE. If you use VC2005 or VC2008, you can simply load the solution or project files in the workspaces/ folder, otherwise you have to create a new package and add all the headers and source files from the include/ and code/ directories. Set the temporary output folder to obj/, for example, and redirect the output folder to bin/. Then build the library - it should compile and link fine. The last step is to integrate the library into your project. This is basically the same task as described in the "Using the pre-built libraries" section above: add the include/ and bin/ directories to your IDE's paths so that the compiler can find the library files. Alternatively you can simply add the assimp project to your project's overall solution and build it inside your solution. @section use_noboost Building without boost. The Boost-Workaround consists of dummy replacements for some boost utility templates. Currently there are replacements for - boost.scoped_ptr - boost.scoped_array - boost.format - boost.random - boost.common_factor - boost.foreach - boost.tuple - boost.make_shared These implementations are very limited and are not intended for use outside assimp. A compiler with full support for partial template specializations is required. To enable the workaround, put the following in your compiler's list of predefined macros: @code #define ASSIMP_BUILD_BOOST_WORKAROUND @endcode
If you're working with the provided solutions for Visual Studio use the -noboost build configs.
assimp_BUILD_BOOST_WORKAROUND implies assimp_BUILD_SINGLETHREADED.
See the @ref assimp_st section for more details. @section assimp_dll Windows DLL Build assimp can be built as DLL. You just need to select a -dll config from the list of project configs and you're fine. NOTE: Theoretically, assimp-dll can be used with multithreaded (non-dll) runtime libraries, as long as you don't utilize any non-public stuff from the code folder. However, if you happen to encounter *very* strange problems, try changing the runtime to Multithreaded (Debug) DLL. @section assimp_stlport Building against STLport STLport is a free, fast and secure STL replacement that works with all major compilers and platforms. To get it, download the latest release from
In our testing, STLport builds tend to be a bit faster than builds against Microsoft's C++ Standard Library. */ /** @page usage Usage @section access_cpp Access by C++ class interface The assimp library can be accessed by both a class or flat function interface. The C++ class interface is the preferred way of interaction: you create an instance of class Assimp::Importer, maybe adjust some settings of it and then call Assimp::Importer::ReadFile(). The class will read the files and process its data, handing back the imported data as a pointer to an aiScene to you. You can now extract the data you need from the file. The importer manages all the resources for itsself. If the importer is destroyed, all the data that was created/read by it will be destroyed, too. So the easiest way to use the Importer is to create an instance locally, use its results and then simply let it go out of scope. C++ example: @code #include
- Include cfileio.h
- Fill an aiFileIO structure with custom file system callbacks (they're self-explanatory as they work similar to the CRT's fXXX functions)
- .. and pass it as parameter to #aiImportFileEx
11.24.09: We changed the orientation of our quaternions to the most common convention to avoid confusion. However, if you're a previous user of Assimp and you update the library to revisions beyond SVNREV 502, you have to adapt your animation loading code to match the new quaternion orientation.
@section hierarchy The Node Hierarchy Nodes are little named entities in the scene that have a place and orientation relative to their parents. Starting from the scene's root node all nodes can have 0 to x child nodes, thus forming a hierarchy. They form the base on which the scene is built on: a node can refer to 0..x meshes, can be referred to by a bone of a mesh or can be animated by a key sequence of an animation. DirectX calls them "frames", others call them "objects", we call them aiNode. A node can potentially refer to single or multiple meshes. The meshes are not stored inside the node, but instead in an array of aiMesh inside the aiScene. A node only refers to them by their array index. This also means that multiple nodes can refer to the same mesh, which provides a simple form of instancing. A mesh referred to by this way lives in the node's local coordinate system. If you want the mesh's orientation in global space, you'd have to concatenate the transformations from the referring node and all of its parents. Most of the file formats don't really support complex scenes, though, but a single model only. But there are more complex formats such as .3ds, .x or .collada scenes which may contain an arbitrary complex hierarchy of nodes and meshes. I for myself would suggest a recursive filter function such as the following pseudocode: @code void CopyNodesWithMeshes( aiNode node, SceneObject targetParent, Matrix4x4 accTransform) { SceneObject parent; Matrix4x4 transform; // if node has meshes, create a new scene object for it if( node.mNumMeshes > 0) { SceneObjekt newObject = new SceneObject; targetParent.addChild( newObject); // copy the meshes CopyMeshes( node, newObject); // the new object is the parent for all child nodes parent = newObject; transform.SetUnity(); } else { // if no meshes, skip the node, but keep its transformation parent = targetParent; transform = node.mTransformation * accTransform; } // continue for all child nodes for( all node.mChildren) CopyNodesWithMeshes( node.mChildren[a], parent, transform); } @endcode This function copies a node into the scene graph if it has children. If yes, a new scene object is created for the import node and the node's meshes are copied over. If not, no object is created. Potential child objects will be added to the old targetParent, but there transformation will be correct in respect to the global space. This function also works great in filtering the bone nodes - nodes that form the bone hierarchy for another mesh/node, but don't have any mesh themselves. @section meshes Meshes All meshes of an imported scene are stored in an array of aiMesh* inside the aiScene. Nodes refer to them by their index in the array and providing the coordinate system for them, too. One mesh uses only a single material everywhere - if parts of the model use a different material, this part is moved to a separate mesh at the same node. The mesh refers to its material in the same way as the node refers to its meshes: materials are stored in an array inside aiScene, the mesh stores only an index into this array. An aiMesh is defined by a series of data channels. The presence of these data channels is defined by the contents of the imported file: by default there are only those data channels present in the mesh that were also found in the file. The only channels guaranteed to be always present are aiMesh::mVertices and aiMesh::mFaces. You can test for the presence of other data by testing the pointers against NULL or use the helper functions provided by aiMesh. You may also specify several post processing flags at Importer::ReadFile() to let assimp calculate or recalculate additional data channels for you. At the moment, a single aiMesh may contain a set of triangles and polygons. A single vertex does always have a position. In addition it may have one normal, one tangent and bitangent, zero to AI_MAX_NUMBER_OF_TEXTURECOORDS (4 at the moment) texture coords and zero to AI_MAX_NUMBER_OF_COLOR_SETS (4) vertex colors. In addition a mesh may or may not have a set of bones described by an array of aiBone structures. How to interpret the bone information is described later on. @section material Materials See the @link materials Material System Page. @endlink @section bones Bones A mesh may have a set of bones in the form of aiBone structures.. Bones are a means to deform a mesh according to the movement of a skeleton. Each bone has a name and a set of vertices on which it has influence. Its offset matrix declares the transformation needed to transform from mesh space to the local space of this bone. Using the bones name you can find the corresponding node in the node hierarchy. This node in relation to the other bones' nodes defines the skeleton of the mesh. Unfortunately there might also be nodes which are not used by a bone in the mesh, but still affect the pose of the skeleton because they have child nodes which are bones. So when creating the skeleton hierarchy for a mesh I suggest the following method: a) Create a map or a similar container to store which nodes are necessary for the skeleton. Pre-initialise it for all nodes with a "no".
b) For each bone in the mesh:
b1) Find the corresponding node in the scene's hierarchy by comparing their names.
b2) Mark this node as "yes" in the necessityMap.
b3) Mark all of its parents the same way until you 1) find the mesh's node or 2) the parent of the mesh's node.
c) Recursively iterate over the node hierarchy
c1) If the node is marked as necessary, copy it into the skeleton and check its children
c2) If the node is marked as not necessary, skip it and do not iterate over its children.
Reasons: you need all the parent nodes to keep the transformation chain intact. For most file formats and modelling packages the node hierarchy of the skeleton is either a child of the mesh node or a sibling of the mesh node but this is by no means a requirement so you shouldn't rely on it. The node closest to the root node is your skeleton root, from there you start copying the hierarchy. You can skip every branch without a node being a bone in the mesh - that's why the algorithm skips the whole branch if the node is marked as "not necessary". You should now have a mesh in your engine with a skeleton that is a subset of the imported hierarchy. @section anims Animations An imported scene may contain zero to x aiAnimation entries. An animation in this context is a set of keyframe sequences where each sequence describes the orientation of a single node in the hierarchy over a limited time span. Animations of this kind are usually used to animate the skeleton of a skinned mesh, but there are other uses as well. An aiAnimation has a duration. The duration as well as all time stamps are given in ticks. To get the correct timing, all time stamp thus have to be divided by aiAnimation::mTicksPerSecond. Beware, though, that certain combinations of file format and exporter don't always store this information in the exported file. In this case, mTicksPerSecond is set to 0 to indicate the lack of knowledge. The aiAnimation consists of a series of aiNodeAnim's. Each bone animation affects a single node in the node hierarchy only, the name specifying which node is affected. For this node the structure stores three separate key sequences: a vector key sequence for the position, a quaternion key sequence for the rotation and another vector key sequence for the scaling. All 3d data is local to the coordinate space of the node's parent, that means in the same space as the node's transformation matrix. There might be cases where animation tracks refer to a non-existent node by their name, but this should not be the case in your every-day data. To apply such an animation you need to identify the animation tracks that refer to actual bones in your mesh. Then for every track:
a) Find the keys that lay right before the current anim time.
b) Optional: interpolate between these and the following keys.
c) Combine the calculated position, rotation and scaling to a tranformation matrix
d) Set the affected node's transformation to the calculated matrix.
If you need hints on how to convert to or from quaternions, have a look at the Matrix&Quaternion FAQ. I suggest using logarithmic interpolation for the scaling keys if you happen to need them - usually you don't need them at all. @section textures Textures Normally textures used by assets are stored in separate files, however, there are file formats embedding their textures directly into the model file. Such textures are loaded into an aiTexture structure.
There are two cases:
1) The texture is NOT compressed. Its color data is directly stored in the aiTexture structure as an array of aiTexture::mWidth * aiTexture::mHeight aiTexel structures. Each aiTexel represents a pixel (or "texel") of the texture image. The color data is stored in an unsigned RGBA8888 format, which can be easily used for both Direct3D and OpenGL (swizzling the order of the color components might be necessary). RGBA8888 has been chosen because it is well-known, easy to use and natively supported by nearly all graphics APIs.
2) This applies if aiTexture::mHeight == 0 is fulfilled. Then, texture is stored in a "compressed" format such as DDS or PNG. The term "compressed" does not mean that the texture data must actually be compressed, however the texture was found in the model file as if it was stored in a separate file on the harddisk. Appropriate decoders (such as libjpeg, libpng, D3DX, DevIL) are required to load theses textures. aiTexture::mWidth specifies the size of the texture data in bytes, aiTexture::pcData is a pointer to the raw image data and aiTexture::achFormatHint is either zeroed or contains the most common file extension of the embedded texture's format. This value is only set if assimp is able to determine the file format. */ /** @page materials Material System @section General Overview All materials are stored in an array of aiMaterial inside the aiScene. Each aiMesh refers to one material by its index in the array. Due to the vastly diverging definitions and usages of material parameters there is no hard definition of a material structure. Instead a material is defined by a set of properties accessible by their names. Have a look at assimp/material.h to see what types of properties are defined. In this file there are also various functions defined to test for the presence of certain properties in a material and retrieve their values. @section mat_tex Textures Textures are organized in stacks, each stack being evaluated independently. The final color value from a particular texture stack is used in the shading equation. For example, the computed color value of the diffuse texture stack (aiTextureType_DIFFUSE) is multiplied with the amount of incoming diffuse light to obtain the final diffuse color of a pixel. @code Stack Resulting equation ------------------------ | Constant base color | color ------------------------ | Blend operation 0 | + ------------------------ | Strength factor 0 | 0.25* ------------------------ | Texture 0 | texture_0 ------------------------ | Blend operation 1 | * ------------------------ | Strength factor 1 | 1.0* ------------------------ | Texture 1 | texture_1 ------------------------ ... ... @endcode @section keys Constants All material key constants start with 'AI_MATKEY' (it's an ugly macro for historical reasons, don't ask).
| Name | Data Type | Default Value | Meaning | Notes |
|---|---|---|---|---|
| NAME | aiString | n/a | The name of the material, if available. | Ignored by aiProcess_RemoveRedundantMaterials. Materials are considered equal even if their names are different. |
| COLOR_DIFFUSE | aiColor3D | black (0,0,0) | Diffuse color of the material. This is typically scaled by the amount of incoming diffuse light (e.g. using gouraud shading) | --- |
| COLOR_SPECULAR | aiColor3D | black (0,0,0) | Specular color of the material. This is typically scaled by the amount of incoming specular light (e.g. using phong shading) | --- |
| COLOR_AMBIENT | aiColor3D | black (0,0,0) | Ambient color of the material. This is typically scaled by the amount of ambient light | --- |
| COLOR_EMISSIVE | aiColor3D | black (0,0,0) | Emissive color of the material. This is the amount of light emitted by the object. In real time applications it will usually not affect surrounding objects, but raytracing applications may wish to treat emissive objects as light sources. | --- |
| COLOR_TRANSPARENT | aiColor3D | black (0,0,0) | Defines the transparent color of the material, this is the color to be multiplied with the color of translucent light to construct the final 'destination color' for a particular position in the screen buffer. T | --- |
| WIREFRAME | int | false | Specifies whether wireframe rendering must be turned on for the material. 0 for false, !0 for true. | --- |
| TWOSIDED | int | false | Specifies whether meshes using this material must be rendered without backface culling. 0 for false, !0 for true. | Some importers set this property if they don't know whether the output face oder is right. As long as it is not set, you may safely enable backface culling. |
| SHADING_MODEL | int | gouraud | One of the #aiShadingMode enumerated values. Defines the library shading model to use for (real time) rendering to approximate the original look of the material as closely as possible. | The presence of this key might indicate a more complex material. If absent, assume phong shading only if a specular exponent is given. |
| BLEND_FUNC | int | false | One of the #aiBlendMode enumerated values. Defines how the final color value in the screen buffer is computed from the given color at that position and the newly computed color from the material. Simply said, alpha blending settings. | - |
| OPACITY | float | 1.0 | Defines the opacity of the material in a range between 0..1. | Use this value to decide whether you have to activate alpha blending for rendering. OPACITY != 1 usually also implies TWOSIDED=1 to avoid cull artifacts. |
| SHININESS | float | 0.f | Defines the shininess of a phong-shaded material. This is actually the exponent of the phong specular equation | SHININESS=0 is equivalent to SHADING_MODEL=aiShadingMode_Gouraud. |
| SHININESS_STRENGTH | float | 1.0 | Scales the specular color of the material. | This value is kept separate from the specular color by most modelers, and so do we. |
| REFRACTI | float | 1.0 | Defines the Index Of Refraction for the material. That's not supported by most file formats. | Might be of interest for raytracing. |
| TEXTURE(t,n) | aiString | n/a | Defines the path to the n'th texture on the stack 't', where 'n' is any value >= 0 and 't' is one of the #aiTextureType enumerated values. | See the 'Textures' section above. |
| TEXBLEND(t,n) | float | n/a | Defines the strength the n'th texture on the stack 't'. All color components (rgb) are multiplied with this factor *before* any further processing is done. | - |
| TEXOP(t,n) | int | n/a | One of the #aiTextureOp enumerated values. Defines the arithmetic operation to be used to combine the n'th texture on the stack 't' with the n-1'th. TEXOP(t,0) refers to the blend operation between the base color for this stack (e.g. COLOR_DIFFUSE for the diffuse stack) and the first texture. | - |
| MAPPING(t,n) | int | n/a | Defines how the input mapping coordinates for sampling the n'th texture on the stack 't' are computed. Usually explicit UV coordinates are provided, but some model file formats might also be using basic shapes, such as spheres or cylinders, to project textures onto meshes. | See the 'Textures' section below. #aiProcess_GenUVCoords can be used to let Assimp compute proper UV coordinates from projective mappings. |
| UVWSRC(t,n) | int | n/a | Defines the UV channel to be used as input mapping coordinates for sampling the n'th texture on the stack 't'. All meshes assigned to this material share the same UV channel setup | Presence of this key implies MAPPING(t,n) to be #aiTextureMapping_UV. See @ref uvwsrc for more details. |
| MAPPINGMODE_U(t,n) | int | n/a | Any of the #aiTextureMapMode enumerated values. Defines the texture wrapping mode on the x axis for sampling the n'th texture on the stack 't'. 'Wrapping' occurs whenever UVs lie outside the 0..1 range. | - |
| MAPPINGMODE_V(t,n) | int | n/a | Wrap mode on the v axis. See MAPPINGMODE_U. | - |
| TEXMAP_AXIS(t,n) | aiVector3D | n/a | Defines the base axis to to compute the mapping coordinates for the n'th texture on the stack 't' from. This is not required for UV-mapped textures. For instance, if MAPPING(t,n) is #aiTextureMapping_SPHERE, U and V would map to longitude and latitude of a sphere around the given axis. The axis is given in local mesh space. | - |
| TEXFLAGS(t,n) | int | n/a | Defines miscellaneous flag for the n'th texture on the stack 't'. This is a bitwise combination of the #aiTextureFlags enumerated values. | - |
@section blender Blender This section contains implementation notes for the Blender3D importer. @subsection bl_overview Overview assimp provides a self-contained reimplementation of Blender's so called SDNA system (http://www.blender.org/development/architecture/notes-on-sdna/). SDNA allows Blender to be fully backward and forward compatible and to exchange files across all platforms. The BLEND format is thus a non-trivial binary monster and the loader tries to read the most of it, naturally limited by the scope of the #aiScene output data structure. Consequently, if Blender is the only modeling tool in your asset work flow, consider writing a custom exporter from Blender if assimps format coverage does not meet the requirements. @subsection bl_status Current status The Blender loader does not support animations yet, but is apart from that considered relatively stable. @subsection bl_notes Notes When filing bugs on the Blender loader, always give the Blender version (or, even better, post the file caused the error).
@section ifc IFC This section contains implementation notes on the IFC-STEP importer. @subsection ifc_overview Overview The library provides a partial implementation of the IFC2x3 industry standard for automatized exchange of CAE/architectural data sets. See http://en.wikipedia.org/wiki/Industry_Foundation_Classes for more information on the format. We aim at getting as much 3D data out of the files as possible. @subsection ifc_status Current status IFC support is new and considered experimental. Please report any bugs you may encounter. @subsection ifc_notes Notes - Only the STEP-based encoding is supported. IFCZIP and IFCXML are not (but IFCZIP can simply be unzipped to get a STEP file). - The importer leaves vertex coordinates untouched, but applies a global scaling to the root transform to convert from whichever unit the IFC file uses to metres. - If multiple geometric representations are provided, the choice which one to load is based on how expensive a representation seems to be in terms of import time. The loader also avoids representation types for which it has known deficits. - Not supported are arbitrary binary operations (binary clipping is implemented, though). - Of the various relationship types that IFC knows, only aggregation, containment and material assignment are resolved and mapped to the output graph. - The implementation knows only about IFC2X3 and applies this rule set to all models it encounters, regardless of their actual version. Loading of older or newer files may fail with parsing errors. @subsection ifc_metadata Metadata IFC file properties (IfcPropertySet) are kept as per-node metadata, see aiNode::mMetaData.
@section ogre Ogre *ATTENTION*: The Ogre-Loader is currently under development, many things have changed after this documentation was written, but they are not final enough to rewrite the documentation. So things may have changed by now! This section contains implementations notes for the OgreXML importer. @subsection overview Overview Ogre importer is currently optimized for the Blender Ogre exporter, because thats the only one that I use. You can find the Blender Ogre exporter at: http://www.ogre3d.org/forums/viewtopic.php?f=8&t=45922 @subsection what What will be loaded? Mesh: Faces, Positions, Normals and all TexCoords. The Materialname will be used to load the material. Material: The right material in the file will be searched, the importer should work with materials who have 1 technique and 1 pass in this technique. From there, the texturename (for 1 color- and 1 normalmap) and the materialcolors (but not in custom materials) will be loaded. Also, the materialname will be set. Skeleton: Skeleton with Bone hierarchy (Position and Rotation, but no Scaling in the skeleton is supported), names and transformations, animations with rotation, translation and scaling keys. @subsection export_Blender How to export Files from Blender You can find informations about how to use the Ogreexporter by your own, so here are just some options that you need, so the assimp importer will load everything correctly: - Use either "Rendering Material" or "Custom Material" see @ref material - do not use "Flip Up Axies to Y" - use "Skeleton name follow mesh" @subsection xml XML Format There is a binary and a XML mesh Format from Ogre. This loader can only Handle xml files, but don't panic, there is a command line converter, which you can use to create XML files from Binary Files. Just look on the Ogre page for it. Currently you can only load meshes. So you will need to import the *.mesh.xml file, the loader will try to find the appendant material and skeleton file. The skeleton file must have the same name as the mesh file, e.g. fish.mesh.xml and fish.skeleton.xml. @subsection material Materials The material file can have the same name as the mesh file (if the file is model.mesh or model.mesh.xml the loader will try to load model.material), or you can use Importer::Importer::SetPropertyString(AI_CONFIG_IMPORT_OGRE_MATERIAL_FILE, "materiafile.material") to specify the name of the material file. This is especially useful if multiply materials a stored in a single file. The importer will first try to load the material with the same name as the mesh and only if this can't be open try to load the alternate material file. The default material filename is "Scene.material". We suggest that you use custom materials, because they support multiple textures (like colormap and normalmap). First of all you should read the custom material sektion in the Ogre Blender exporter Help File, and than use the assimp.tlp template, which you can find in scripts/OgreImpoter/Assimp.tlp in the assimp source. If you don't set all values, don't worry, they will be ignored during import. If you want more properties in custom materials, you can easily expand the ogre material loader, it will be just a few lines for each property. Just look in OgreImporterMaterial.cpp @subsection Importer Properties - IMPORT_OGRE_TEXTURETYPE_FROM_FILENAME: Normally, a texture is loaded as a colormap, if no target is specified in the materialfile. Is this switch is enabled, texture names ending with _n, _l, _s are used as normalmaps, lightmaps or specularmaps.
Property type: Bool. Default value: false. - IMPORT_OGRE_MATERIAL_FILE: Ogre Meshes contain only the MaterialName, not the MaterialFile. If there is no material file with the same name as the material, Ogre Importer will try to load this file and search the material in it.
Property type: String. Default value: guessed. @subsection todo Todo - Load colors in custom materials - extend custom and normal material loading - fix bone hierarchy bug - test everything elaboratly - check for non existent animation keys (what happens if a one time not all bones have a key?) */ /** @page extend Extending the Library @section General Or - how to write your own loaders. It's easy. You just need to implement the #Assimp::BaseImporter class, which defines a few abstract methods, register your loader, test it carefully and provide test models for it. OK, that sounds too easy :-). The whole procedure for a new loader merely looks like this:
- Create a header (FormatNameImporter.h) and a unit (FormatNameImporter.cpp) in the <root>/code/ directory
- Add them to the following workspaces: vc8 and vc9 (the files are in the workspaces directory), CMAKE (code/CMakeLists.txt, create a new source group for your importer and put them also to ADD_LIBRARY( assimp SHARED))
- Include AssimpPCH.h - this is the PCH file, and it includes already most Assimp-internal stuff.
- Open Importer.cpp and include your header just below the (include_new_importers_here) line, guarded by a #define @code #if (!defined assimp_BUILD_NO_FormatName_IMPORTER) ... #endif @endcode Wrap the same guard around your .cpp!
- Now advance to the (register_new_importers_here) line in the Importer.cpp and register your importer there - just like all the others do.
- Setup a suitable test environment (i.e. use AssimpView or your own application), make sure to enable the #aiProcess_ValidateDataStructure flag and enable verbose logging. That is, simply call before you import anything: @code DefaultLogger::create("AssimpLog.txt",Logger::VERBOSE) @endcode
- Implement the Assimp::BaseImporter::CanRead(), Assimp::BaseImporter::InternReadFile() and Assimp::BaseImporter::GetExtensionList(). Just copy'n'paste the template from Appendix A and adapt it for your needs.
- For error handling, throw a dynamic allocated ImportErrorException (see Appendix A) for critical errors, and log errors, warnings, infos and debuginfos with DefaultLogger::get()->[error, warn, debug, info].
- Make sure that your loader compiles against all build configurations on all supported platforms. This includes -noboost! To avoid problems, see the boost section on this page for a list of all 'allowed' boost classes (again, this grew historically when we had to accept that boost is not THAT widely spread that one could rely on it being available everywhere).
- Provide some _free_ test models in <root>/test/models/<FormatName>/ and credit their authors. Test files for a file format shouldn't be too large (~500 KiB in total), and not too repetive. Try to cover all format features with test data.
- Done! Please, share your loader that everyone can profit from it!
- Try to make your parser as flexible as possible. Don't rely on particular layout, whitespace/tab style, except if the file format has a strict definition, in which case you should always warn about spec violations. But the general rule of thumb is be strict in what you write and tolerant in what you accept.
- Call Assimp::BaseImporter::ConvertToUTF8() before you parse anything to convert foreign encodings to UTF-8. That's not necessary for XML importers, which must use the provided IrrXML for reading.
- Take care of endianness issues! Assimp importers mostly support big-endian platforms, which define the AI_BUILD_BIG_ENDIAN constant. See the next section for a list of utilities to simplify this task.
- Don't trust the input data! Check all offsets!
- ByteSwapper (ByteSwapper.h) - manual byte swapping stuff for binary loaders.
- StreamReader (StreamReader.h) - safe, endianess-correct, binary reading.
- IrrXML (irrXMLWrapper.h) - for XML-parsing (SAX.
- CommentRemover (RemoveComments.h) - remove single-line and multi-line comments from a text file.
- fast_atof, strtoul10, strtoul16, SkipSpaceAndLineEnd, SkipToNextToken .. large family of low-level parsing functions, mostly declared in fast_atof.h, StringComparison.h and ParsingUtils.h (a collection that grew historically, so don't expect perfect organization).
- ComputeNormalsWithSmoothingsGroups() (SmoothingGroups.h) - Computes normal vectors from plain old smoothing groups.
- SkeletonMeshBuilder (SkeletonMeshBuilder.h) - generate a dummy mesh from a given (animation) skeleton.
- StandardShapes (StandardShapes.h) - generate meshes for standard solids, such as platonic primitives, cylinders or spheres.
- BatchLoader (BaseImporter.h) - manage imports from external files. Useful for file formats which spread their data across multiple files.
- SceneCombiner (SceneCombiner.h) - exhaustive toolset to merge multiple scenes. Useful for file formats which spread their data across multiple files.
- boost.scoped_ptr
- boost.scoped_array
- boost.format
- boost.random
- boost.common_factor
- boost.foreach
- boost.tuple
**/