Feature guide » Loading and using plugins

Plugin interfaces

Plugin functionality is exposed via an interface that's common for all plugins of given type. Magnum provides these plugin interfaces:

• Trade::AbstractImporter — importers for general 2D and 3D scene, mesh, material, texture and image data. See *Importer classes in the Trade namespace for available importer plugins.
• Trade::AbstractImageConverter — conversion among various image formats. See *ImageConverter classes in the Trade namespace for available image converter plugins.
• Text::AbstractFont — font loading and glyph layouting. See *Font classes in the Text namespace for available font plugins.
• Text::AbstractFontConverter — font and glyph cache conversion. See *FontConverter classes in the Text namespace for available font converter plugins.
• Audio::AbstractImporter — importers for audio formats. See *Importer classes in the Audio namespace for available audio importer plugins.

Loading and instantiating plugins

To load a plugin, you need to instantiate Corrade::PluginManager::Manager for given plugin interface, for example for the Trade::AbstractImporter. In order to find plugins on the filesystem, plugin interfaces have a bunch of plugin search paths hardcoded — see documentation of the pluginSearchPaths() functions provided by each plugin interface. It usually just works, but you can also pass a plugin directory to the manager constructor explicitly.

Once the plugin manager is instantiated, you can start creating instances of particular plugins. Keep in mind that the manager instance has to exist for whole lifetime of all plugin instances created using it.

{
    PluginManager::Manager<Trade::AbstractImporter> manager;
    std::unique_ptr<Trade::AbstractImporter> importer =
        manager.loadAndInstantiate("TgaImporter");
    if(!importer) Fatal{} << "Cannot load the TgaImporter plugin";

    // Use the plugin...

    /* At the end of the scope the importer instance gets deleted and then
       the manager automatically unloads the plugin on destruction */
}

Plugin dependencies

Some plugins have dependencies, for example the OpenGexImporter plugin uses AnyImageImporter to load texture data. The dependency loading is done automatically, but in some cases it's across plugin types (for example the MagnumFont plugin depends on the TgaImporter plugin, which is of a different type) — there you need to create manager instances for all required plugin interfaces:

PluginManager::Manager<Trade::AbstractImporter> importerManager;
PluginManager::Manager<Text::AbstractFont> fontManager;

// As a side effect TgaImporter is loaded by importerManager
fontManager.load("MagnumFont");

Static plugins

By default, on desktop systems at least, all plugins are built as dynamic ones, i.e. they are a separate binary which gets linked in at runtime. This is good for reducing memory consumption, as the code is loaded in memory only for the time it is actually needed. However, if you need to port to a platform which does not support dynamic linking or you simply want to have the plugin loaded at all times, you can use static plugins.

The plugins are built as static if the BUILD_PLUGINS_STATIC CMake parameter is enabled (see Downloading and building and Downloading and building plugins for more information). The actual usage in the code is basically the same as above, but you need to explicitly find the plugin and link it into the executable. If you use CMake, it would look like this:

find_package(MagnumPlugins REQUIRED
    TinyGltfImporter
    StbTrueTypeFont)

add_executable(my-app my-app.cpp)
target_link_libraries(my-app PRIVATE
    MagnumPlugins::TinyGltfImporter
    MagnumPlugins::StbTrueTypeFont)

The only user-visible behavioral change in the code will be that PluginManager::Manager::load() will return PluginManager::LoadState::Static instead of PluginManager::LoadState::Loaded, but there is no need to change the above code, as it will work for both dynamic and static case.

The static plugin needs to be explicitly registered so the plugin manager is aware it's there. If you use CMake 3.1 and newer it's done automatically. Otherwise, you can achieve the same if you explicitly #include the static plugin import file (named importStaticPlugin.cpp, residing in plugin's include directory) in a source file that gets compiled into your main application. The static import file contains just a simple call to CORRADE_PLUGIN_IMPORT(), see its documentation for further information.

/* No need to do this if you use CMake */
#include <MagnumPlugins/TinyGltfImporter/importStaticPlugin.cpp>
#include <MagnumPlugins/StbTrueTypeFont/importStaticPlugin.cpp>

Plugin aliases and "any" plugins

There's usually more than one plugin available to achieve a particular goal — for example in order to open a PNG file, you can choose among PngImporter, StbImageImporter or DevIlImageImporter plugins. Rather than this being an unnecessary redundancy, it allows you to pick a particular performance / portability / feature tradeoff — a plugin with no external dependencies for a web build or, on the other hand, the fastest possible implementation for a tool that does heavy image processing.

To make this simpler in the code and defer the decision to the buildsystem or app deployment, all plugins that support a particular format provide a common alias* — in case of PNG images, you can just load a "PngImporter" plugin and if PngImporter is not available, it will pick up any of the other candidates.

For greater control you can also use setPreferredPlugins(), giving a prioritized candidate list for a particular alias. This is especially useful in case of font plugins, where you can get advanced layout capabilities if the HarfBuzzFont plugin is available or at least a faster and smoother glyph rendering if you can get the FreeTypeFont plugin. If none of the suggestions is available, it falls back to whatever is left (which can be, for example, the StbTrueTypeFont plugin).

PluginManager::Manager<Text::AbstractFont> manager;
manager.setPreferredPlugins("TrueTypeFont", {"HarfBuzzFont", "FreeTypeFont"});

To make your life even simpler, there are various "any format" plugins — these detect format based on file extension, map it to a plugin alias and then proxy the rest of the work to a corresponding plugin:

std::unique_ptr<Trade::AbstractImporter> importer =
    manager.instantiate("AnyImageImporter");
importer->openFile("texture.dds"); /* Delegates to the DdsImporter plugin */

Besides convenience for the end user, this allows for example the scene importer plugins to load any image formats without needing to have a knowledge about them or having an explicit dependency on multitude of image importer plugins.

So far, the following plugins have the "any format" ability:

• AnyImageImporter — imports any image format
• AnyImageConverter — converts to any image format
• AnySceneImporter — imports any scene format
• AnyImporter — imports any audio format

Plugin-specific configuration

Because it's not possible for a general statically typed plugin API to expose all possible knobs and switches that a file format could support, the plugins have a possibility to supply additional configuration via the configuration() function. For example, in the AssimpImporter plugin you can toggle various postprocessing steps that are applied to loaded scene files:

std::unique_ptr<Trade::AbstractImporter> importer =
    manager.instantiate("AssimpImporter");
importer->configuration().group("postprocess")->setValue("PreTransformVertices", true);

Developing your own plugins

See class documentation of particular plugin interfaces for more information about subclassing. The Corrade's plugin management tutorial contains more information about plugin compilation and registering.