diff --git a/INSTALL b/INSTALL index b94af6f4b..97cdf181f 100644 --- a/INSTALL +++ b/INSTALL @@ -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 @@ -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. diff --git a/README b/README index a88fbb4ed..a9538db54 100644 --- a/README +++ b/README @@ -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 +------------------------------ + +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 Asset Import Library provides a lot of model formats: +The library provides importers for a lot of file formats, including: - 3DS + - BLEND + - Collada + - IFC-STEP - ASE - DXF - HMP @@ -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: +Open Asset Import Library is implemented in C++ (but provides both a C and a C++ish 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. + /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. + diff --git a/doc/AssimpDoc_Html/AssimpDoc.chm b/doc/AssimpDoc_Html/AssimpDoc.chm index 6d5445944..cf24f43d0 100644 Binary files a/doc/AssimpDoc_Html/AssimpDoc.chm and b/doc/AssimpDoc_Html/AssimpDoc.chm differ diff --git a/doc/dox.h b/doc/dox.h index 8416ed6e2..2c5ec222b 100644 --- a/doc/dox.h +++ b/doc/dox.h @@ -130,6 +130,7 @@ assimp-discussions. /** @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. @@ -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 -> C++ -> Code generation -> Runtime) if you use static runtimes (Multithreaded / Multithreaded Debug) or dynamic runtimes (Multithreaded DLL / Multithreaded Debug DLL). Choose the ASSIMP linker lib accordingly. -
+

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 std::vector::operator[] -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 @@ -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. -If you're using ASSIMP in a DLL: It's ok. There's no STL used in the DLL interface, so it doesn't care whether +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 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 @@ -191,12 +190,12 @@ it for yourself. Read the "Getting Started" section of the Boost documentation f 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 (dummy) +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 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. @@ -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 - + + - 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: @@ -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 code directory and run -@code -make -@endcode -respectively -@code -make -fmakefile.mingw -@endcode -for mingw-make. For a -noboost-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. -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 dir. However, if you happen -to encounter *very* strange problems try changing the runtime to multithreaded (Debug) DLL. +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 -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 - 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 +. +Usually you'll just need to run 'configure' + a makefile (see their README for more details). Don't miss to add /stlport to your compiler's default include paths - prior -to the directory where the compiler vendor's STL lies. Do the same for /lib and +to the directory where your compiler vendor's headers lie. Do the same for /lib and recompile ASSIMP. To ensure you're really building against STLport see aiGetCompileFlags().
-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. */