Magnum::Trade::AssimpImporter class

#include <MagnumPlugins/AssimpImporter/AssimpImporter.h>

Usage

This plugin depends on the Trade and Assimp libraries and the AnyImageImporter plugin and is built if WITH_ASSIMPIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "AssimpImporter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins and assimp repositories and do the following. If you want to use system-installed Assimp, omit the first part and point CMAKE_PREFIX_PATH to its installation dir if necessary.

# Add Assimp with unwanted parts disabled, help Magnum find everything needed
set(ASSIMP_BUILD_ASSIMP_TOOLS OFF CACHE BOOL "" FORCE)
set(ASSIMP_BUILD_TESTS OFF CACHE BOOL "" FORCE)
set(ASSIMP_INCLUDE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/assimp/include CACHE STRING "" FORCE)
set(ASSIMP_LIBRARY_DEBUG assimp CACHE STRING "" FORCE)
set(ASSIMP_LIBRARY_RELEASE assimp CACHE STRING "" FORCE)
# The following is important to avoid Assimp appending `d` to all your
# binaries. You need Assimp >= 5.0.0 for this to work, also note that after
# 5.0.1 this option is prefixed with ASSIMP_, so better set both variants.
set(INJECT_DEBUG_POSTFIX OFF CACHE BOOL "" FORCE)
set(ASSIMP_INJECT_DEBUG_POSTFIX OFF CACHE BOOL "" FORCE)
add_subdirectory(assimp EXCLUDE_FROM_ALL)
add_library(Assimp::Assimp ALIAS assimp)

set(WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

set(WITH_ASSIMPIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::AssimpImporter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake and FindAssimp.cmake into your modules/ directory, request the AssimpImporter component of the MagnumPlugins package and link to the MagnumPlugins::AssimpImporter target:

find_package(MagnumPlugins REQUIRED AssimpImporter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::AssimpImporter)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.

Behavior and limitations

The plugin supports ImporterFeature::OpenData and ImporterFeature::FileCallback features. The Assimp library loads everything during initial import, meaning all external file loading callbacks are called with InputFileCallbackPolicy::LoadTemporary and the resources can be safely freed right after the openData() / openFile() function exits. In some cases, Assimp will explicitly call InputFileCallbackPolicy::Close on the opened file and then open it again. In case of images, the files are loaded on-demand inside image2D() calls with InputFileCallbackPolicy::LoadTemporary and InputFileCallbackPolicy::Close is emitted right after the file is fully read.

Import of animation data is not supported at the moment.

The importer recognizes ImporterFlag::Verbose, enabling verbose logging in Assimp when the flag is enabled. However please note that since Assimp handles logging through a global singleton, it's not possible to have different verbosity levels in each instance.

Plugin-specific configuration

Assimp has a versatile set of configuration options and processing operations applied on imported scenes. A subset of these is exposed via configuration(), the full form shown below. The first group of options matches the AI_CONFIG_* macros and has to be applied before opening first file with given plugin instance; to change them again you need to create a new importer instance.

The [postprocess] subgroup contains boolean toggles that correspond to the aiPostProcessSteps enum. Some of them are enabled by default, some not; options for not yet supported features are omitted. These are passed to Assimp when opening a file, meaning a change in these will be always applied to the next opened file.

[configuration]
# AI_CONFIG_* values, can be changed only before the first file is opened
ImportColladaIgnoreUpDirection=false

# Allow non-default texture coordinate sets. If disabled, materials with
# non-zero texture coordinate sets (which need explicit support in shaders)
# will fail to import.
allowMaterialTextureCoordinateSets=false

# aiPostProcessSteps, applied to each opened file
[configuration/postprocess]
JoinIdenticalVertices=true
Triangulate=true
GenNormals=false
GenSmoothNormals=false
SplitLargeMeshes=false
PreTransformVertices=false
ValidateDataStructure=false
ImproveCacheLocality=false
RemoveRedundantMaterials=false
FixInfacingNormals=false
SortByPType=true
FindDegenerates=false
FindInvalidData=false
GenUVCoords=false
TransformUVCoords=false
FindInstances=false
OptimizeMeshes=false
OptimizeGraph=false
FlipUVs=false
FlipWindingOrder=false

Access to internal importer state

The Assimp structures used to import data from a file can be accessed through importer state methods:

• Calling importerState() returns pointer to the imported aiScene
• Calling *importerState() on data class instances returned from this importer return pointers to matching assimp structures:
  • AbstractMaterialData::importerState() returns aiMaterial
  • CameraData::importerState() returns aiCamera
  • TextureData::importerState() returns std::pair<const aiMaterial*, aiTextureType>, in which the first texture of given type in given material is referred to.
  • MeshData::importerState() returns aiMesh
  • ObjectData3D::importerState() returns aiNode
  • LightData::importerState() returns aiLight
  • ImageData2D::importerState() may return aiTexture, if texture was embedded into the loaded file.
• openState() expects a pointer to an Assimp scene (i.e., const aiScene*) and optionally a path (in order to be able to load textures, if needed)

Base classes

class AbstractImporter

Base for importer plugins.

Constructors, destructors, conversion operators

AssimpImporter() explicit

Default constructor.

AssimpImporter(PluginManager::Manager<AbstractImporter>& manager) explicit

Constructor.

AssimpImporter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit

Plugin manager constructor.

Function documentation