Skip to content

Commit

Permalink
- update README and INSTALL, slight doc fixes.
Browse files Browse the repository at this point in the history 
git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@1050 67173fc5-114c-0410-ac8e-9d2fd5bffc1f
  • Loading branch information
aramis_acg committed Jul 17, 2011
1 parent 969c2cc commit 5f341dc
Show file tree
Hide file tree
Showing 4 changed files with 141 additions and 132 deletions.
57 changes: 23 additions & 34 deletions INSTALL
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@

========================================================================
Open Asset Import Library (assimp) INSTALL
========================================================================

Open Asset Import Library (Assimp) Install
------------------------------------------------


=======================================================================
Please refer to the doxygen documentation for full install instructions
=======================================================================
------------------------------
Getting the documentation
------------------------------

A regularly-updated copy is available at
http://assimp.sourceforge.net/lib_html/index.html
Expand All @@ -20,38 +20,27 @@ c) navigate to ./doc
d) and run 'doxygen'

Open the generated HTML (AssimpDoc_Html/index.html) in the browser of your choice.
Windows only: To generate the CHM doc install the 'Microsoft HTML Workshop'
and configure the path to it in the DOXYFILE. Run doxygen again.

=======================================================================
For the inpatient:

Windows: go to ./workspaces/vc8 or ./workspaces/vc9, open the
VS Solution and build for your preferred build target ...
release-dll is usually the best choice. Adjust the runtime library to
your needs, multithreaded-dll is preconfigured by default.

These solutions are currently hand-maintained, they copy all
the resulting binaries to ./bin/config-name at the moment.

Unix & Family:

CMake is now our preferred build tool. Run cmake with your
favourite build script generator from *here* and have fun.
If you use cmake only to get a makefile, run
'make' and 'make install' afterwards.

NOTE: in order to use the assimp command line tools, you may
need to run ldconfig as root to make the so loader find
the assimp shared library --

Note that running make from ./code is deprecated, although there
is still a suitable makefile in it.

Windows only: To generate the CHM doc, install 'Microsoft HTML Workshop'
and configure the path to it in the DOXYFILE first.

------------------------------
Building Assimp
------------------------------

More detailed build instructions can be found in the documentation,
this section is just for the inpatient among you.

CMake is the preferred build system for Assimp. The minimum required version
is 2.6. If you don't have it yet, downloads for CMake can be found on
http://www.cmake.org/.

Building Assimp with CMake is 'business as usual' if you've used CMake
before. All steps can be done either on the command line / shell or
by using the CMake GUI tool, the choice is up to you.

First, invoke CMake to generate build files for a particular
toolchain (for standard GNU makefiles: cmake -G 'Unix Makefiles').
Afterwards, use the generated build files to perform the actual
build.


126 changes: 83 additions & 43 deletions README
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,40 @@
Open Asset Import Library (Assimp) Readme
-----------------------------------------

Here you can find information regarding Open Asset Import Library:


========================================================================
Open Asset Import Library (assimp) README
========================================================================


Table of Contents

1. Overview
1.1 Supported file formats
1.2 File structure
2. Build the Asset Import Library
1.1 Supported file formats
1.2 File structure
2. Build the library
3. Help
4. License


------------------------------
1. Overview
1.1 Supported file formats

The Asset Import Library provides a lot of model formats:
------------------------------

Open Asset Import Library is a Open Source library designed to load various 3d file
formats and convert them into a shared, in-memory format. It supports more than
30 file formats. Basically, it is like DevIL for 3D models.

Its short name is 'assimp', which is an unintended joke (the abbreviation is derived
from 'Asset Importer').


----------------
1.1 Supported file formats
----------------

The library provides importers for a lot of file formats, including:
- 3DS
- BLEND
- Collada
- IFC-STEP
- ASE
- DXF
- HMP
Expand All @@ -32,48 +50,70 @@ The Asset Import Library provides a lot of model formats:
- LWO
- OBJ
- SMD

- Collada

- LWO

- Ogre XML

- partly LWS
- .. + many more, see http://assimp.sourceforge.net/main_features_formats.html for a full list.

.. plus many more, see
http://assimp.sourceforge.net/main_features_formats.html for a more exhaustive list.


----------------
1.2 Repository structure

Open Asset Import Library is implemented in C++ and provides a C-interface. The directory structure is:

/bin Binaries of the Asset Import Library.
/code Code of the Asset Import Library.
/contrib Third-party-libraries used by the Asset Import Library.
/doc Documentation (doxygen generated and data structure as a xml file)
/include Public headers.
/lib Static library location for Windows.
/obj Object file location for Windows.
/port Ports to other languages.
----------------

Open Asset Import Library is implemented in C++ (but provides both a C and a C++ish interface).
The directory structure is:

/bin Binaries, onyl used on Windows.
/code Source code.
/contrib Third-party-libraries used by the Asset Import Library.
/doc Documentation (doxygen generated and data structure draft)
/include Public headers for you to #include.
/lib Static library location for Windows.
/obj Object file location for Windows.
/port Ports to other languages and scripts therefor.

/test Unit- and regression tests, model test suite.
/tools Tools (viewer, command line `assimp`).
/workspaces Build enviroments for vc,xcode,...
/test Unit- and regression tests, test suite of models.
/tools Tools (viewer, command line `assimp`).
/samples A small number of samples to illustrate possible use-cases.
/workspaces Build enviroments for vc,xcode,... (deprecated,
CMake has superseeded all legacy build options)



2. Build the Asset Import Library
------------------------------
2. Build the library
------------------------------

Take a look into the INSTALL file.


------------------------------
3. Help

For more help go to http://assimp.sourceforge.net/ (or, for germans, http://www.zfx.info). Or take a look into the doc-folder, which contains the doxygen-generated documentation in HTMl format (CHMs for Windows are as well contained in some distributions and located right here in the root folder).


------------------------------

For more information go to http://assimp.sourceforge.net/. Or have a look into the ./doc-
folder, which contains the Doxygen-generated documentation in HTML format (CHMs for
Windows are also included in some distributions and should be located right here in
the root folder).

If reading the documentation doesn't solve your problems, try our forums at SF.net
Open Discussion: http://sourceforge.net/projects/assimp/forums/forum/817653)
Help: http://sourceforge.net/projects/assimp/forums/forum/817654

or our mailing list, assimp-discussions
archive: http://sourceforge.net/mailarchive/forum.php?forum_name=assimp-discussions,
subscribe: https://lists.sourceforge.net/lists/listinfo/assimp-discussions


------------------------------
4. License

The license of the Asset Import Library is based on the BSD-License. It is contained in the LICENSE file.
------------------------------

The license of the Asset Import Library is based on the modified, 3-clause BSD-License,
which is a very liberal license. An _informal_ summary of the license is: do whatever
you want, but include Assimp's license text with your product - and don't sue us
if it doesn't work.

For the formal details, see the LICENSE file.

Binary file modified doc/AssimpDoc_Html/AssimpDoc.chm
View file
Binary file not shown.
90 changes: 35 additions & 55 deletions doc/dox.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -130,6 +130,7 @@ 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.
Expand All @@ -148,18 +149,16 @@ run and use the application. If the linker complains about some integral functio
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><br>
Please don't forget to also read the @ref assimp_stl section on MSVC and the STL.
@section assimp_stl Microsoft Compilers & STL
@section assimp_stl Microsoft Compilers and the C++ Standard Library
In VC8 and VC9 Microsoft has introduced some STL debugging features. A good example are improved iterator checks and
various useful debug checks. Actually they are really helpful for debugging, but they're extremely slow. They're
so extremely slow that they can make the STL up to 100 times slower (imagine a <i>std::vector<T>::operator[] </i>
performing 3 or 4 single checks! scary ...).
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.
These security enhancements are - thanks MS! - also active in release builds, rendering ASSIMP several times
slower. However, it is possible to disable them by defining
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
Expand All @@ -174,11 +173,11 @@ If you do not, there are two binary incompatible STL versions mangled together a
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:</i> It's ok. There's no STL used in the DLL interface, so it doesn't care whether
<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 which describes how to achieve this.
@ref assimp_stlport section that has a description how to achieve this.
@section install_own Building the library from scratch
Expand All @@ -191,12 +190,12 @@ it for yourself. Read the "Getting Started" section of the Boost documentation f
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 (dummy)
<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 loose functionality (e.g. threading) by doing this.
So, if it is possible to use boost, you should use boost. See the @link use_noboost NoBoost-Section @endlink
later on this page for more details.
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 favourite IDE. If you use VC2005 or
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.
Expand All @@ -210,15 +209,16 @@ 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
<ul>
<li><i>boost.scoped_ptr</i></li>
<li><i>boost.scoped_array</i></li>
<li><i>boost.format</i> </li>
<li><i>boost.random</i> </li>
<li><i>boost.common_factor</i> </li>
<li><i>boost.foreach</i> </li>
<li><i>boost.tuple</i></li>
</ul>
- 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:
Expand All @@ -233,49 +233,29 @@ See the @ref assimp_st section
for more details.
@section assimp_make Build with MAKE
To build Assimp with MAKE, navigate to the <tt>code</tt> directory and run
@code
make
@endcode
respectively
@code
make -fmakefile.mingw
@endcode
for mingw-make. For a <i>-noboost</i>-Build, append
@code
NOBOOST=1
@endcode
@section assimp_st Single-threaded build
-- currently there is no difference between single-thread and normal builds --
@section assimp_dll DLL build
@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. Don't forget to copy the DLL to the directory of your executable :-)
configs and you're fine.
<b>NOTE:</b> 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 dir. However, if you happen
to encounter *very* strange problems try changing the runtime to multithreaded (Debug) DLL.
<b>NOTE:</b> 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 <i>Multithreaded (Debug) DLL</i>.
@section assimp_stlport Building against STLport
If your compiler's default implementation of the STL is too slow, lacks some features,
contains bugs or if you just want to tweak ASSIMP's performance a little try a build
against STLport. STLport is a free, fast and secure STL replacement that works with
all major compilers and platforms. To get it visit their website at
<a href="http://www.stlport.org"/><stlport.org></a> and download the latest STLport release.
Usually you'll just need to run 'configure' + a makefile (see the README for more details).
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
<a href="http://www.stlport.org"/><stlport.org></a>.
Usually you'll just need to run 'configure' + a makefile (see their README for more details).
Don't miss to add <stlport_root>/stlport to your compiler's default include paths - <b>prior</b>
to the directory where the compiler vendor's STL lies. Do the same for <stlport_root>/lib and
to the directory where your compiler vendor's headers lie. Do the same for <stlport_root>/lib and
recompile ASSIMP. To ensure you're really building against STLport see aiGetCompileFlags().
<br>
Usually building ASSIMP against STLport yields a better overall performance so it might be
worth a try if the library is too slow for you.
In our testing, STLport builds tend to be a bit faster than builds against Microsoft's
C++ Standard Library.
*/

Expand Down

0 comments on commit 5f341dc

Please sign in to comment.