The Developer Guide

Extending the Library


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/AssetLib/ 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 ImporterRegistry.cpp.cpp and include your header just below the (include_new_importers_here) line, guarded by a #define

#if (!defined assimp_BUILD_NO_FormatName_IMPORTER)

Wrap the same guard around your .cpp!

  • Now advance to the (register_new_importers_here) line in the ImporterRegistry.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:

  • 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. You can use our CI-build to check several platforms like Windows and Linux ( 32 bit and 64 bit ).

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