Downloading and building plugins
Guide how to download and build plugins for the Magnum engine.
Plugins provide additional capability for the Magnum engine in terms of importing and exporting various media file formats. They are not needed for essential usage, but you might want them sooner or later when you would want to use an image as a texture or render text on the screen.
The easiest way to install Magnum Plugins is to use one of the ready-made packages for your platform of choice. See Manual build if you want to have more control. Cross-compiling is very similar to cross-compiling of Magnum itself.
- Vcpkg package
- ArchLinux packages
- MSYS2 packages
- Packages for Debian, Ubuntu and derivatives
- Gentoo Linux ebuilds
- Homebrew formulas for macOS
Magnum Plugins are available as a Vcpkg package. See the Magnum Vcpkg documentation for a more detailed introduction and a troubleshooting guide. Installing latest stable version of Magnum Plugins with all its dependencies is done like this:
vcpkg install magnum-plugins
Note that just a subset of plugins is installed by default. To opt-in or opt-out of additional features, you can use the following syntax; feature names are simply names of CMake
MAGNUM_WITH_* options from the Enabling or disabling features section but lowercase, e.g.:
vcpkg install magnum-plugins[assimpimporter,ddsimporter]
To install all features of a package, use
vcpkg install magnum-plugins[*]
Package for the latest stable release is maintained in the
community repo. Installing is as simple as this:
sudo pacman -S magnum-plugins
There are also a few development packages for native builds, cross-compilation for Emscripten, Android and MinGW or various sanitizer/coverage builds. See the PKGBUILD files in the
package/archlinux directory. They allow you to build and install the package directly from source tree. Example usage:
git clone https://github.com/mosra/magnum-plugins && cd magnum-plugins cd package/archlinux makepkg -fp PKGBUILD # or any other PKGBUILD file
In most cases the development PKGBUILDs also contain a
check() function which will run all unit tests before packaging. That might sometimes fail or take too long, pass
makepkg to skip that.
Once built, install the package using
sudo pacman -U magnum-plugins-*.pkg.tar.zst
Edit the PKGBUILDs if you want to pass additional flags to CMake or enable / disable additional features.
MSYS2 package for the latest stable release is mantained in the official repos. Installing is as simple as this:
pacman -S mingw-w64-x86_64-magnum-plugins # or mingw-w64-i686-magnum-plugins
Similarly to ArchLinux, there is one package in the
package/msys/magnum-plugins directory, which will download and package latest stable release; and then a development
package/msys, allowing you to package and install the currently checked out source tree. Both depend on corresponding Corrade and Magnum MSYS2 packages. Example usage:
git clone https://github.com/mosra/magnum-plugins && cd magnum-plugins cd package/msys makepkg -fp PKGBUILD
The above works in a 32/64bit MinGW shell, from a MSYS shell the equivalent command is
makepkg-mingw -fp PKGBUILD
which will build both a 32bit and a 64bit version. See the MSYS2 Wiki for more information.
There are also MSYS2 packages for Magnum Integration.
package/debian/ directory contains all files needed for building Debian packages. You need the Corrade and Magnum Debian packages installed and in addition also the
debhelper packages. Building is easy, just change directory to package root, link or copy the
package/debian directory there and run
git clone https://github.com/mosra/magnum-plugins && cd magnum-plugins ln -s package/debian . dpkg-buildpackage --no-sign
This will compile binary and development packages, which will then appear in a parent directory. Install them using
sudo dpkg -i ../magnum-plugins*.deb
If you want to pass additional flags to CMake or enable / disable additional features, add them to
dh_auto_configure at the bottom of
package/debian/rules. Watch out, as indentation has to be done using tabs, not spaces.
git clone https://github.com/mosra/magnum-plugins && cd magnum-plugins cd package/gentoo sudo ebuild dev-libs/magnum-plugins/magnum-plugins-9999.ebuild manifest clean merge
If you want to pass additional flags to CMake or enable / disable additional features, add them to
mycmakeargs in the
macOS Homebrew formulas building the latest Git revision are in the
package/homebrew directory. Either use the
*.rb files directly or use the tap at https:/
brew install mosra/magnum/magnum-plugins
But often you may want to install the latest Git revision of all Magnum projects instead:
brew install --HEAD mosra/magnum/corrade brew install --HEAD mosra/magnum/magnum brew install --HEAD mosra/magnum/magnum-plugins # If already installed, use the following to upgrade, in the same order brew upgrade --fetch-HEAD mosra/magnum/corrade brew upgrade --fetch-HEAD mosra/magnum/magnum brew upgrade --fetch-HEAD mosra/magnum/magnum-plugins
When installing from the
*.rb files you need to install the Corrade and Magnum Homebrew packages first. If you want to pass additional flags to CMake or enable / disable additional features, edit the
The source is available on GitHub: https:/
By default no plugins are built and you need to select them manually:
MAGNUM_WITH_ASSIMPIMPORTER— Build the AssimpImporter plugin. Depends on Assimp.
MAGNUM_WITH_ASTCIMPORTER— Build the AstcImporter plugin.
MAGNUM_WITH_BASISIMAGECONVERTER— Build the BasisImageConverter plugin. Depends on Basis Universal.
MAGNUM_WITH_BASISIMPORTER— Build the BasisImporter plugin. Depends on Basis Universal — if you are on Vcpkg, it will "just work", otherwise you need to download the sources and point
BASIS_UNIVERSAL_DIRto their directory so CMake can find them.
MAGNUM_WITH_BCDECIMAGECONVERTER— Build the BcDecImageConverter plugin.
MAGNUM_WITH_CGLTFIMPORTERdeprecated — Build the CgltfImporter plugin.
MAGNUM_WITH_DDSIMPORTER— Build the DdsImporter plugin.
MAGNUM_WITH_DEVILIMAGEIMPORTER— Build the DevIlImageImporter plugin. Depends on DevIL.
MAGNUM_WITH_DRFLACAUDIOIMPORTER— Build the DrFlacAudioImporter plugin.
MAGNUM_WITH_DRMP3AUDIOIMPORTER— Build the DrMp3AudioImporter plugin.
MAGNUM_WITH_DRWAVAUDIOIMPORTER— Build the DrWavAudioImporter plugin.
MAGNUM_WITH_ETCDECIMAGECONVERTER— Build the EtcDecImageConverter plugin.
MAGNUM_WITH_FAAD2AUDIOIMPORTER— Build the Faad2AudioImporter plugin. Depends on FAAD2.
MAGNUM_WITH_FREETYPEFONT— Build the FreeTypeFont plugin. Depends on FreeType.
MAGNUM_WITH_GLSLANGSHADERCONVERTER— Build the GlslangShaderConverter plugin. Depends on Glslang.
MAGNUM_WITH_GLTFIMPORTER— Build the GltfImporter plugin.
MAGNUM_WITH_GLTFSCENECONVERTER— Build the GltfSceneConverter plugin.
MAGNUM_WITH_HARFBUZZFONT— Build the HarfBuzzFont plugin. Enables also building of the FreeTypeFont plugin. Depends on HarfBuzz.
MAGNUM_WITH_ICOIMPORTER— Build the IcoImporter plugin.
MAGNUM_WITH_JPEGIMAGECONVERTER— Build the JpegImageConverter plugin.
MAGNUM_WITH_JPEGIMPORTER— Build the JpegImporter plugin. Depends on libJPEG.
MAGNUM_WITH_KTXIMAGECONVERTER— Build the KtxImageConverter plugin.
MAGNUM_WITH_KTXIMPORTER— Build the KtxImporter plugin.
MAGNUM_WITH_MESHOPTIMIZERSCENECONVERTER— Build the MeshOptimizerSceneConverter plugin.
MAGNUM_WITH_MINIEXRIMAGECONVERTER— Build the MiniExrImageConverter plugin.
MAGNUM_WITH_OPENEXRIMAGECONVERTER— Build the OpenExrImageConverter plugin. Depends on OpenEXR.
MAGNUM_WITH_OPENEXRIMPORTER— Build the OpenExrImporter plugin. Depends on OpenEXR.
MAGNUM_WITH_OPENGEXIMPORTER— Build the OpenGexImporter plugin. Enables also building of the OpenDdl library.
MAGNUM_WITH_PNGIMAGECONVERTER— Build the PngImageConverter plugin. Depends on libPNG.
MAGNUM_WITH_PNGIMPORTER— Build the PngImporter plugin. Depends on libPNG.
MAGNUM_WITH_PRIMITIVEIMPORTER— Build the PrimitiveImporter plugin.
MAGNUM_WITH_SPIRVTOOLSSHADERCONVERTER— Build the SpirvToolsShaderConverter plugin. Depends on SPIRV-Tools.
MAGNUM_WITH_SPNGIMPORTER— Build the SpngImporter plugin. Depends on libspng.
MAGNUM_WITH_STANFORDIMPORTER— Build the StanfordImporter plugin.
MAGNUM_WITH_STANFORDSCENECONVERTER— Build the StanfordSceneConverter plugin.
MAGNUM_WITH_STBDXTIMAGECONVERTER— Build the StbDxtImageConverter plugin.
MAGNUM_WITH_STBIMAGECONVERTER— Build the StbImageConverter plugin.
MAGNUM_WITH_STBIMAGEIMPORTER— Build the StbImageImporter plugin. Enabled automatically if
MAGNUM_WITH_STBRESIZEIMAGECONVERTER— Build the StbResizeImageConverter plugin.
MAGNUM_WITH_STBTRUETYPEFONT— Build the StbTrueTypeFont plugin.
MAGNUM_WITH_STBVORBISAUDIOIMPORTER— Build the StbVorbisAudioImporter plugin.
MAGNUM_WITH_TINYGLTFIMPORTERdeprecated — Build the TinyGltfImporter plugin.
MAGNUM_WITH_UFBXIMPORTER— Build the UfbxImporter plugin.
MAGNUM_WITH_WEBPIMPORTER— Build the WebPImporter plugin.
Some plugins expose their internal state through separate libraries and you can control their build separately:
MAGNUM_WITH_OPENDDL— Build the OpenDdl library. Enabled automatically if
Options controlling the build are a subset of the options used by Magnum:
MAGNUM_BUILD_STATIC— Build all libraries as static. Default is shared, except on platforms such as Android or Emscripten that don't support dynamic linking.
MAGNUM_BUILD_STATIC_PIC— Build static libraries with position-independent code. Enabled by default when building static libraries, disable if you don't need this feature. On Emscripten this option is always off.
MAGNUM_BUILD_PLUGINS_STATIC— Build plugins as static. By default, plugins are built as dynamic. Independent of the
MAGNUM_BUILD_STATICoption to allow having static libraries with dynamic plugins and vice versa. To some extent it's also possible to have only a subset of plugins built as static — set
MAGNUM_<PLUGIN>_BUILD_STATICfor particular plugins to
OFFto override this option.
- Additional options are inherited from the CORRADE_
BUILD_ MULTITHREADED and MAGNUM_ BUILD_ STATIC_ UNIQUE_ GLOBALS options specified when building Magnu,
Note that each plugin class / library namespace documentation contains more detailed information about its dependencies, availability on particular platforms and also a guide how to enable given plugin for building and how to use it with CMake.
Libraries and static plugins built in the
Debug configuration (e.g. with
CMAKE_BUILD_TYPE set to
Debug) have a
-d suffix, dynamic plugins in
Debug configuration are installed to the
magnum-d subdirectory, similarly to what is done when building Magnum itself.
The documentation for plugins is built as part of of the main Magnum documentation. Clone the projects next to each other and continue as described in Building documentation.
package/ci/ there is a
circle.yml file with Linux GCC 4.8, Linux ARM64, macOS, Emscripten, AddressSanitizer, ThreadSanitizer, Android x86 and iOS x86_64 configuration. Online at https:/
package/ci/ there is an
appveyor.yml file with Windows desktop MSVC, MinGW and Windows RT configuration. Online at https:/
Linux, Linux GLES, macOS and Windows MinGW builds contribute to a combined code coverage report, available online at https:/