File format support
Support tables for widely used image, scene, audio and font formats.
The AnyAudioImporter, AnyImageImporter, AnySceneImporter, AnyImageConverter, AnySceneConverter and AnyShaderConverter plugins described on the previous page can be used for generic handling of any of the formats they recognize and they'll proxy the operation to a concrete plugin implementation.
To support diverse use cases, there's commonly more than one alternative implementation for given format. The following tables list the most widely used formats with corresponding plugin implementations and known caveats for each. When one format is supported by more than one plugin, you can use PluginManager::
See the Legend section at the bottom of the page for a detailed explanation of the color-coded columns.
Image importers
Together with scene importers derived from Trade::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
ASTC (*.astc) | AstcImporter | AstcImporter | none | none | |
Basis Universal (*.basis) | BasisImporter | BasisImporter | none | bundleable, tiny | Apache-2.0 |
| BMP ( *.bmp) | BmpImporter | StbImageImporter | minor | bundled | public domain |
| DevIlImageImporter | unknown | external | LGPLv2.1 | ||
| DirectDraw Surface ( *.dds) | DdsImporter | DdsImporter | none | none | |
| DevIlImageImporter | severe | external | LGPLv2.1 | ||
OpenEXR (*.exr) | OpenExrImporter | OpenExrImporter | some | bundleable | BSD 3-clause |
| DevIlImageImporter | severe | external | LGPLv2.1 | ||
| GIF ( *.gif) | GifImporter | StbImageImporter | minor | bundled | public domain |
| DevIlImageImporter | severe | external | LGPLv2.1 | ||
| Radiance HDR ( *.hdr) | HdrImporter | StbImageImporter | none | bundled | public domain |
| DevIlImageImporter | none | external | LGPLv2.1 | ||
| ICO ( *.ico, *.cur) | IcoImporter | IcoImporter | some | none | |
| DevIlImageImporter | severe | external | LGPLv2.1 | ||
| JPEG ( *.jpg, *.jpe, *.jpeg) | JpegImporter | JpegImporter | none | external, tiny | Libjpeg |
| StbImageImporter | some | bundled | public domain | ||
| DevIlImageImporter | none | external | LGPLv2.1 | ||
KTX2 (*.ktx2) | KtxImporter | KtxImporter | some | none | |
| PNG ( *.png) | PngImporter | PngImporter | minor | external, tiny | libPNG |
| SpngImporter | some | external, tiny | BSD 2-clause | ||
| StbImageImporter | none | bundled | public domain | ||
| DevIlImageImporter | some | external | LGPLv2.1 | ||
| PSD ( *.psd) | PsdImporter | StbImageImporter | severe | bundled | public domain |
| DevIlImageImporter | severe | external | LGPLv2.1 | ||
| Truevision TGA ( *.tga, *.vda, *.icb, *.vst) | TgaImporter | TgaImporter | minor | none | |
| StbImageImporter | none | bundled | public domain | ||
| DevIlImageImporter | unknown | external | LGPLv2.1 | ||
WebP (*.webp) | WebPImporter | WebPImporter | minor | external | BSD 3-clause |
In addition to the above, DevIlImageImporter and StbImageImporter support many more formats.
Image converters
Derived from Trade::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
Basis Universal (*.basis) | BasisImageConverter | BasisImageConverter | some | bundleable | Apache-2.0 |
Windows Bitmap (*.bmp) | BmpImageConverter | StbImageConverter | unknown | bundled | public domain |
OpenEXR (*.exr) | OpenExrImageConverter | OpenExrImageConverter | some | bundleable | BSD 3-clause |
| MiniExrImageConverter | severe | bundled | public domain | ||
Radiance HDR (*.hdr) | HdrImageConverter | StbImageConverter | none | bundled | public domain |
| JPEG ( *.jpg, *.jpe, *.jpeg) | JpegImageConverter | JpegImageConverter | minor | external, tiny | Libjpeg |
| StbImageConverter | minor | bundled | public domain | ||
KTX2 (*.ktx2) | KtxImageConverter | KtxImageConverter | some | none | |
| PNG ( *.png) | PngImageConverter | PngImageConverter | none | external, tiny | libPNG |
| StbImageConverter | some | bundled | public domain | ||
| Truevision TGA ( *.tga, *.vda, *.icb, *.vst) | TgaImageConverter | TgaImageConverter | none | none | |
| StbImageConverter | minor | bundled | public domain | ||
WebP (*.webp) | WebPImageConverter | WebPImageConverter | none | external | BSD 3-clause |
Scene importers
Together with image importers derived from Trade::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
COLLADA (*.dae) | ColladaImporter | AssimpImporter | severe | bundleable | BSD 3-clause |
Autodesk FBX (*.fbx) | FbxImporter | UfbxImporter | minor | bundled | public domain |
| AssimpImporter | unknown | bundleable | BSD 3-clause | ||
| OBJ ( *.obj) | ObjImporter | ObjImporter | severe | none | |
| UfbxImporter | unknown | bundled | public domain | ||
| AssimpImporter | some | bundleable | BSD 3-clause | ||
| Open Game Engine Exchange ( *.ogex) | OpenGexImporter | OpenGexImporter | some | none | |
| AssimpImporter | unknown | bundleable | BSD 3-clause | ||
| glTF ( *.gltf, *.glb) | GltfImporter | GltfImporter | minor | none | |
| TinyGltfImporter deprecated | some | bundled | MIT | ||
| AssimpImporter | severe | bundleable | BSD 3-clause | ||
| Stanford PLY ( *.ply) | StanfordImporter | StanfordImporter | minor | none | |
| AssimpImporter | severe | bundleable | BSD 3-clause | ||
| STL ( *.stl) | StlImporter | StlImporter | minor | none | |
| AssimpImporter | unknown | bundleable | BSD 3-clause | ||
In addition to the above, AssimpImporter supports many more formats.
Scene converters
Derived from Trade::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
Stanford PLY (*.ply) | StanfordSceneConverter | StanfordSceneConverter | minor | none | |
glTF (*.gltf, *.glb) | GltfSceneConverter | GltfSceneConverter | some | none | |
Audio importers
To be written.
Fonts
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
OpenType (*.otf) | OpenTypeFont | FreeTypeFont | some | external | FreeType |
| HarfBuzzFont | none | external | MIT | ||
| StbTrueTypeFont | some | bundled | public domain | ||
TrueType (*.ttf) | TrueTypeFont | FreeTypeFont | minor | external | FreeType |
| HarfBuzzFont | none | external | MIT | ||
| StbTrueTypeFont | some | bundled | public domain | ||
In addition to the above, FreeTypeFont supports many more formats.
Font converters
To be written.
Shader validators, preprocessors, optimizers and linkers
Together with shader converters derived from ShaderTools::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
| GLSL | GlslShaderConverter | GlslangShaderConverter | none | bundleable | Many |
| SPIR-V | SpirvShaderConverter | SpirvToolsShaderConverter | none | bundleable | Apache-2.0 |
| SPIR-V assembly | SpirvAssemblyShaderConverter | SpirvToolsShaderConverter | none | bundleable | Apache-2.0 |
Shader converters
Together with shader validators, preprocessors, optimizers and linkers derived from ShaderTools::
| Format | Generic plugin alias | Plugin name | Caveats | Dependencies | License |
|---|---|---|---|---|---|
| GLSL → SPIR-V | GlslToSpirvShaderConverter | GlslangShaderConverter | none | bundleable | Many |
| SPIR-V → SPIR-V assembly | SpirvToSpirvAssemblyShaderConverter | SpirvToolsShaderConverter | none | bundleable | Apache-2.0 |
| SPIR-V assembly → SPIR-V | SpirvAssemblyToSpirvShaderConverter | SpirvToolsShaderConverter | none | bundleable | Apache-2.0 |
Legend
The Caveats column lists known issues and limitations of each plugin, and is color-coded for easier understanding. Note the caveats might get updated over time as features get implemented, bugs fixed or new issues discovered.
- none means there are no known issues or limitations.
- minor means the known issues only affect rare corner cases and shouldn't be a problem in practice.
- some means it has limitations affecting certain use cases. You're encouraged to check the documentation to be sure these don't affect you.
- severe means it has known bugs and limitations and isn't guaranteed to be usable for generic file import. It might work for your concrete use case, but you're encouraged to pick an alternative, if possible.
- unknown means there were no documented issues for given file format and there isn't enough practical experience to say how well it works.
The Dependencies column shows what kind of dependencies the plugin relies on, highlighting potential portability issues:
- none means it's dependency-free, with all its internals following Magnum standards of high test coverage, stability, portability and documentation.
- bundled means the dependency is usually a single-file 3rd party library that's bundled in the repo, and thus with no extra work needed to get it running. It's also tested on all platforms as Magnum itself, which should mean no portability issues either.
- bundleable, tiny means the dependency is external to the repository, but it's relatively small and thus has no considerable impact on build times or deployment size. It can be either found externally or embedded as a CMake subproject, which may simplify the building procedure. While no guarantees on its portability are given, small libraries are generally rather portable.
- bundleable means the dependency is external to the repository and has a significant size that may have impact on build times and deployment size. However it's still possible to embed it as a CMake subproject, which could simplify the building a bit.
- external, tiny means the dependency is external to the repository, it's relatively small but cannot be (or isn't tested to be) embedded as a CMake subproject, which makes it slightly harder to get running.
- external means the dependency is external to the repository, has a significant size that may have impact on deployment size, and cannot be (or isn't tested to be) embedded as a CMake subproject. No guarantees on portability whatsoever.
The License column shows the license of the plugin dependency, if there's any. Like with all other 3rd party components, each plugin has a color-coded block showing the license, linking to its text and mentioning requirements coming from the license:
- light blue marks public domain dependencies, which don't require anything from you in order to use them and put no restrictions on use
- green marks licenses that make the dependency safe to use in a commercial setting without having to release your source code, usually requiring you to give attribution.
- yellow marks licenses that require you to either dynamically link to the software to be able to use it in a commercial setting or release your source code as well. Such plugins are safe to use in internal development tools and asset pipelines, but you might want to consider alternatives before bundling them in a deployed commercial product. In some cases there is an alternative commercial licensing option without this requirement.
- red label marks licenses that unconditionally require you to publish your software together with its source code. Such plugins are only safe to use in internal development tools and asset pipelines, consider alternatives for use in a deployed commercial product. In some cases there is an alternative commercial licensing option without this requirement.