dox.h

/** @file dox.h
 *  @brief General documentation built from a doxygen comment
 */

/**
@mainpage assimp - Open Asset Import Library

<img src="dragonsplash.png"></img>

@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):
<hr>
<br><tt>
<b>Collada</b> ( <i>*.dae;*.xml</i> )<br>
<b>Blender</b> ( <i>*.blend</i> ) <sup>3</sup><br>
<b>Biovision BVH </b> ( <i>*.bvh</i> ) <br>
<b>3D Studio Max 3DS</b> ( <i>*.3ds</i> ) <br>
<b>3D Studio Max ASE</b> ( <i>*.ase</i> ) <br>
<b>Wavefront Object</b> ( <i>*.obj</i> ) <br>
<b>Stanford Polygon Library</b> ( <i>*.ply</i> ) <br>
<b>AutoCAD DXF</b> ( <i>*.dxf</i> ) <br>
<b>IFC-STEP</b> ( <i>*.ifc</i> )<br>
<b>Neutral File Format</b> ( <i>*.nff</i> ) <br>
<b>Sense8 WorldToolkit</b> ( <i>*.nff</i> ) <br>
<b>Valve Model</b> ( <i>*.smd,*.vta</i> ) <sup>3</sup> <br>
<b>Quake I</b> ( <i>*.mdl</i> ) <br>
<b>Quake II</b> ( <i>*.md2</i> ) <br>
<b>Quake III</b> ( <i>*.md3</i> ) <br>
<b>Quake 3 BSP</b> ( <i>*.pk3</i> )  <sup>1</sup> <br>
<b>RtCW</b> ( <i>*.mdc</i> )<br>
<b>Doom 3</b> ( <i>*.md5mesh;*.md5anim;*.md5camera</i> ) <br>
<b>DirectX X </b> ( <i>*.x</i> ). <br>
<b>Quick3D </b> ( <i>*.q3o;*q3s</i> ). <br>
<b>Raw Triangles </b> ( <i>*.raw</i> ). <br>
<b>AC3D </b> ( <i>*.ac</i> ). <br>
<b>Stereolithography </b> ( <i>*.stl</i> ). <br>
<b>Autodesk DXF </b> ( <i>*.dxf</i> ). <br>
<b>Irrlicht Mesh </b> ( <i>*.irrmesh;*.xml</i> ). <br>
<b>Irrlicht Scene </b> ( <i>*.irr;*.xml</i> ). <br>
<b>Object File Format </b> ( <i>*.off</i> ). <br>
<b>Terragen Terrain </b> ( <i>*.ter</i> ) <br>
<b>3D GameStudio Model </b> ( <i>*.mdl</i> ) <br>
<b>3D GameStudio Terrain</b> ( <i>*.hmp</i> )<br>
<b>Ogre</b> (<i>*.mesh.xml, *.skeleton.xml, *.material</i>)<sup>3</sup> <br>
<b>Milkshape 3D</b> ( <i>*.ms3d</i> )<br>
<b>LightWave Model</b> ( <i>*.lwo</i> )<br>
<b>LightWave Scene</b> ( <i>*.lws</i> )<br>
<b>Modo Model</b> ( <i>*.lxo</i> )<br>
<b>CharacterStudio Motion</b> ( <i>*.csm</i> )<br>
<b>Stanford Ply</b> ( <i>*.ply</i> )<br>
<b>TrueSpace</b> ( <i>*.cob, *.scn</i> )<sup>2</sup><br><br>
</tt>
See the @link importer_notes Importer Notes Page @endlink for informations, what a specific importer can do and what not.
Note that although this paper claims to be the official documentation,
http://assimp.sourceforge.net/main_features_formats.html
<br>is usually the most up-to-date list of file formats supported by the library. <br>

<sup>1</sup>: Experimental loaders<br>
<sup>2</sup>: Indicates very limited support - many of the format's features don't map to Assimp's data structures.<br>
<sup>3</sup>: These formats support animations, but assimp doesn't yet support them (or they're buggy)<br>
<br>
<hr>

assimp is independent of the Operating System by nature, providing a C++ interface for easy integration
with game engines and a C interface to allow bindings to other programming languages. At the moment the library runs
on any little-endian platform including X86/Windows/Linux/Mac and X64/Windows/Linux/Mac. Special attention
was paid to keep the library as free as possible from dependencies.

Big endian systems such as PPC-Macs or PPC-Linux systems are not officially supported at the moment. However, most
formats handle the required endian conversion correctly, so large parts of the library should work.

The assimp linker library and viewer application are provided under the BSD 3-clause license. This basically means
that you are free to use it in open- or closed-source projects, for commercial or non-commercial purposes as you like
as long as you retain the license informations and take own responsibility for what you do with it. For details see
the LICENSE file.

You can find test models for almost all formats in the <assimp_root>/test/models directory. Beware, they're *free*,
but not all of them are *open-source*. If there's an accompagning '<file>\source.txt' file don't forget to read it.

@section main_install Installation

assimp can be used in two ways: linking against the pre-built libraries or building the library on your own. The former
option is the easiest, but the assimp distribution contains pre-built libraries only for Visual C++ 2005 and 2008. For other
compilers you'll have to build assimp for yourself. Which is hopefully as hassle-free as the other way, but needs a bit
more work. Both ways are described at the @link install Installation page. @endlink

@section main_usage Usage

When you're done integrating the library into your IDE / project, you can now start using it. There are two separate
interfaces by which you can access the library: a C++ interface and a C interface using flat functions. While the former
is easier to handle, the latter also forms a point where other programming languages can connect to. Up to the moment, though,
there are no bindings for any other language provided. Have a look at the @link usage Usage page @endlink for a detailed explanation and code examples.

@section main_data Data Structures

When the importer successfully completed its job, the imported data is returned in an aiScene structure. This is the root
point from where you can access all the various data types that a scene/model file can possibly contain. The
@link data Data Structures page @endlink describes how to interpret this data.

@section ext Extending the library

There are many 3d file formats in the world, and we're happy to support as many as possible. If you need support for
a particular file format, why not implement it yourself and add it to the library? Writing importer plugins for
assimp is considerably easy, as the whole postprocessing infrastructure is available and does much of the work for you.
See the @link extend Extending the library @endlink page for more information.



@section main_support Support & Feedback

If you have any questions/comments/suggestions/bug reports you're welcome to post them in our
<a href="https://sourceforge.net/forum/forum.php?forum_id=817653">forums</a>. Alternatively there's
a mailing list, <a href="https://sourceforge.net/mailarchive/forum.php?forum_name=assimp-discussions">
assimp-discussions</a>.


*/


/**
@page install Installation


@section install_prebuilt Using the pre-built libraries with Visual C++ 8/9

If you develop at Visual Studio 2005 or 2008, you can simply use the pre-built linker libraries provided in the distribution.
Extract all files to a place of your choice. A directory called "assimp" will be created there. Add the assimp/include path
to your include paths (Menu-&gt;Extras-&gt;Options-&gt;Projects and Solutions-&gt;VC++ Directories-&gt;Include files)
and the assimp/lib/&lt;Compiler&gt; path to your linker paths (Menu-&gt;Extras-&gt;Options-&gt;Projects and Solutions-&gt;VC++ Directories-&gt;Library files).
This is necessary only once to setup all paths inside you IDE.

To use the library in your C++ project you have to include either &lt;assimp/Importer.hpp&gt; or &lt;assimp/cimport.h&gt; plus some others starting with &lt;types.h&gt;.
If you set up your IDE correctly the compiler should be able to find the files. Then you have to add the linker library to your
project dependencies. Link to <assimp_root>/lib/<config-name>/assimp.lib. config-name is one of the predefined
project configs. For static linking, use release/debug. See the sections below on this page for more information on the
other build configs.
If done correctly you should now be able to compile, link,
run and use the application. If the linker complains about some integral functions being defined twice you probably have
mixed the runtimes. Recheck the project configuration (project properties -&gt; C++ -&gt; Code generation -&gt; Runtime) if you use
static runtimes (Multithreaded / Multithreaded Debug) or dynamic runtimes (Multithreaded DLL / Multithreaded Debug DLL).
Choose the assimp linker lib accordingly.
<br><br>
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).
<b>assimp's vc8 and vc9 configs enable these flags by default</b>.

<i>If you're linking statically against assimp:</i> 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.

<i>If you're using assimp in a DLL/SO:</i> 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.
<br><br>
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 <a href="http://www.boost.org">boost</a> 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 <a href="http://www.boost-consulting.com/products/free">
http://www.boost-consulting.com/products/free</a>. Choose the appropriate version of boost for your runtime of choice.

<b>If you don't want to use boost</b>, you can build against our <i>"Boost-Workaround"</i>. 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