diff --git a/doc/file-formats.dox b/doc/file-formats.dox
index 55c55512c..9226d8e00 100644
--- a/doc/file-formats.dox
+++ b/doc/file-formats.dox
@@ -27,19 +27,27 @@ namespace Magnum {
/** @page file-formats File format support
@brief Support tables for widely used image, scene, audio and font formats
+@tableofcontents
+
The @ref Trade::AnyImageImporter "AnyImageImporter",
-@ref Trade::AnySceneImporter "AnySceneImporter" and other `Any*` plugins can be
-used for generic loading of any of the recognized formats, they'll proxy the
-loading to a concrete plugin implementation. The following tables list the most
-widely used formats with alternative plugin implementations and known caveats
-for each.
-
-When one format is supported by more than one plugin, you can use
-@ref Corrade::PluginManager::AbstractManager::setPreferredPlugins() to
+@ref Trade::AnySceneImporter "AnySceneImporter",
+@ref Trade::AnyImageConverter "AnyImageConverter",
+@ref Trade::AnySceneConverter "AnySceneConverter" and other `Any*` plugins can
+be used for generic handling of any of the recognized formats, they'll proxy
+the operation to a concrete plugin implementation. The following tables list
+the most widely used formats with alternative plugin implementations and known
+caveats for each. When one format is supported by more than one plugin, you
+can use @ref Corrade::PluginManager::AbstractManager::setPreferredPlugins() to
prioritize a particular plugin implementation.
+See the @ref file-formats-legend section at the bottom of the page for a
+detailed explanation of the color-coded columns.
+
@section file-formats-image-importers Image importers
+Together with @ref file-formats-scene-importers "scene importers" derived from
+@ref Trade::AbstractImporter.
+
@m_class{m-row m-container-inflate}
@parblock
@@ -62,7 +70,7 @@ prioritize a particular plugin implementation.
| `BasisImporter` |
@ref Trade::BasisImporter "BasisImporter" |
@m_span{m-text m-dim} none @m_endspan |
-external, tiny |
+bundleable, tiny |
Apache-2.0 |
|
@@ -78,7 +86,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
unknown |
-external |
+external |
LGPLv2.1 |
|
@@ -94,7 +102,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
@ref Trade-DevIlImageImporter-behavior-dds "severe" |
-external |
+external |
LGPLv2.1 |
|
@@ -110,7 +118,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
@ref Trade-DevIlImageImporter-behavior-animated-gifs "severe" |
-external |
+external |
LGPLv2.1 |
|
@@ -126,7 +134,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
@ref Trade-DevIlImageImporter-behavior-ico "severe" |
-external |
+external |
LGPLv2.1 |
|
@@ -136,7 +144,7 @@ prioritize a particular plugin implementation.
`JpegImporter` |
@ref Trade::JpegImporter "JpegImporter" |
@m_span{m-text m-dim} none @m_endspan |
-external, tiny |
+external, tiny |
Libjpeg |
@@ -148,7 +156,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
@m_span{m-text m-dim} none @m_endspan |
-external |
+external |
LGPLv2.1 |
|
@@ -158,7 +166,7 @@ prioritize a particular plugin implementation.
`PngImporter` |
@ref Trade::PngImporter "PngImporter" |
@ref Trade-PngImporter-behavior "minor" |
-external, tiny |
+external, tiny |
libPNG |
@@ -170,7 +178,7 @@ prioritize a particular plugin implementation.
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
@ref Trade-DevIlImageImporter-behavior-cgbi "some" |
-external |
+external |
LGPLv2.1 |
|
@@ -186,13 +194,13 @@ prioritize a particular plugin implementation.
| @ref Trade::StbImageImporter "StbImageImporter" |
@m_span{m-text m-dim} none @m_endspan |
-bundled |
+bundled |
public domain |
| @ref Trade::DevIlImageImporter "DevIlImageImporter" |
unknown |
-external |
+external |
LGPLv2.1 |
@@ -204,10 +212,103 @@ and @ref Trade::StbImageImporter "StbImageImporter" support many more formats.
@section file-formats-image-converters Image converters
-To be written.
+Derived from @ref Trade::AbstractImageConverter.
+
+@m_class{m-row m-container-inflate}
+
+@parblock
+
+@m_class{m-fullwidth m-flat}
+
+
+
+| Format |
+Generic plugin alias |
+Plugin name |
+Caveats |
+Dependencies |
+License |
+
+ |
+
+
+| Basis Universal (`*.basis`) |
+`BasisImageConverter` |
+@ref Trade::BasisImageConverter "BasisImageConverter" |
+@ref Trade-BasisImageConverter-behavior "some" |
+bundleable |
+Apache-2.0 |
+
+ |
+
+
+| OpenEXR (`*.exr`) |
+`OpenExrImageConverter` |
+@ref Trade::MiniExrImageConverter "MiniExrImageConverter" |
+@ref Trade-MiniExrImageConverter-behavior "minor" |
+bundled |
+public domain |
+
+ |
+
+
+JPEG
(`*.jpg`, `*.jpe`, `*.jpeg`) |
+`JpegImageConverter` |
+@ref Trade::JpegImageConverter "JpegImageConverter" |
+@ref Trade-JpegImageConverter-behavior "minor" |
+external, tiny |
+Libjpeg |
+
+
+| @ref Trade::StbImageConverter "StbImageConverter" |
+@ref Trade-StbImageConverter-behavior-arithmetic-jpeg "minor" |
+bundled |
+public domain |
+
+ |
+
+
+PNG
(`*.png`) |
+`PngImageConverter` |
+@ref Trade::PngImageConverter "PngImageConverter" |
+@m_span{m-text m-dim} none @m_endspan |
+external, tiny |
+libPNG |
+
+
+| @ref Trade::StbImageConverter "StbImageConverter" |
+@ref Trade-StbImageConverter-behavior-16bit-png "some" |
+bundled |
+public domain |
+
+ |
+
+
+Truevision TGA
(`*.tga`, `*.vda`, `*.icb`, `*.vst`) |
+`TgaImageConverter` |
+@ref Trade::TgaImageConverter "TgaImageConverter" |
+@ref Trade-TgaImageConverter-behavior "minor" |
+@m_span{m-text m-dim} none @m_endspan |
+ |
+
+
+| @ref Trade::StbImageConverter "StbImageConverter" |
+@m_span{m-text m-dim} none @m_endspan |
+bundled |
+public domain |
+
+
+
+@endparblock
+
+In addition to the above, @ref Trade::StbImageConverter "StbImageConverter"
+supports additional formats.
@section file-formats-scene-importers Scene importers
+Together with @ref file-formats-image-importers "image-importers" derived from
+@ref Trade::AbstractImporter.
+
@m_class{m-row m-container-inflate}
@parblock
@@ -230,7 +331,7 @@ To be written.
`ColladaImporter` |
@ref Trade::AssimpImporter "AssimpImporter" |
@ref Trade-AssimpImporter-behavior "severe" |
-external |
+bundleable |
BSD 3-clause |
|
@@ -240,7 +341,7 @@ To be written.
`FbxImporter` |
@ref Trade::AssimpImporter "AssimpImporter" |
unknown |
-external |
+bundleable |
BSD 3-clause |
|
@@ -256,7 +357,7 @@ To be written.
| @ref Trade::AssimpImporter "AssimpImporter" |
@ref Trade-AssimpImporter-behavior "some" |
-external |
+bundleable |
BSD 3-clause |
|
@@ -272,7 +373,7 @@ To be written.
| @ref Trade::AssimpImporter "AssimpImporter" |
unknown |
-external |
+bundleable |
BSD 3-clause |
|
@@ -282,13 +383,13 @@ To be written.
`GltfImporter` |
@ref Trade::TinyGltfImporter "TinyGltfImporter" |
@ref Trade-TinyGltfImporter-behavior "some" |
-bundled |
+bundled |
MIT |
| @ref Trade::AssimpImporter "AssimpImporter" |
@ref Trade-AssimpImporter-behavior "severe" |
-external |
+bundleable |
BSD 3-clause |
|
@@ -304,7 +405,7 @@ To be written.
| @ref Trade::AssimpImporter "AssimpImporter" |
@ref Trade-AssimpImporter-behavior "severe" |
-external |
+bundleable |
BSD 3-clause |
|
@@ -320,7 +421,7 @@ To be written.
| @ref Trade::AssimpImporter "AssimpImporter" |
unknown |
-external |
+bundleable |
BSD 3-clause |
@@ -332,7 +433,36 @@ many more formats.
@section file-formats-scene-converters Scene converters
-To be written.
+Derived from @ref Trade::AbstractImageConverter.
+
+@m_class{m-row m-container-inflate}
+
+@parblock
+
+@m_class{m-fullwidth m-flat}
+
+
+
+| Format |
+Generic plugin alias |
+Plugin name |
+Caveats |
+Dependencies |
+License |
+
+ |
+
+
+| Stanford PLY (`*.ply`) |
+`StanfordSceneConverter` |
+@ref Trade::StanfordSceneConverter "StanfordSceneConverter" |
+@ref Trade-StanfordSceneConverter-behavior "minor" |
+@m_span{m-text m-dim} none @m_endspan |
+ |
+
+
+
+@endparblock
@section file-formats-audio-importers Audio importers
@@ -345,5 +475,84 @@ To be written.
@section file-formats-font-converters Font converters
To be written.
+
+@section file-formats-shader-converters Shader converters
+
+To be written.
+
+@section file-formats-legend 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.
+
+- @m_class{m-label m-default} **none** means there are no known issues or
+ limitations.
+- @m_class{m-label m-success} **minor** means the known issues only affect
+ rare corner cases and shouldn't be a problem in practice.
+- @m_class{m-label m-warning} **some** means it has limitations affecting
+ certain use cases. You're encouraged to check the documentation to be
+ sure these don't affect you.
+- @m_class{m-label m-danger} **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.
+- @m_class{m-label m-dim} **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:
+
+- @m_class{m-label m-default} **none** means it's dependency-free, with all
+ its internals following Magnum standards of high test coverage, stability,
+ portability and documentation.
+- @m_class{m-label m-primary} **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.
+- @m_class{m-label m-success} **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.
+- @m_class{m-label m-warning} **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.
+- @m_class{m-label m-warning} **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.
+- @m_class{m-label m-danger} **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 @ref credits-third-party "3rd party components", each
+plugin has a color-coded block showing the license, linking to its text and
+mentioning requirements coming from the license:
+
+- @m_class{m-label m-primary} **light blue** marks public domain
+ dependencies, which don't require anything from you in order to use them
+ and put no restrictions on use
+- @m_class{m-label m-success} **green** marks licenses that make the
+ dependency safe to use in a commerical setting without having to release
+ your source code, usually requiring you to give attribution.
+- @m_class{m-label m-warning} **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.
+- @m_class{m-label m-danger} **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.
*/
}
diff --git a/src/MagnumPlugins/AnyImageConverter/AnyImageConverter.h b/src/MagnumPlugins/AnyImageConverter/AnyImageConverter.h
index 545e9bbe2..f603a3e71 100644
--- a/src/MagnumPlugins/AnyImageConverter/AnyImageConverter.h
+++ b/src/MagnumPlugins/AnyImageConverter/AnyImageConverter.h
@@ -102,7 +102,8 @@ find_package(Magnum REQUIRED AnyImageConverter)
target_link_libraries(your-app PRIVATE Magnum::AnyImageConverter)
@endcode
-See @ref building, @ref cmake and @ref plugins for more information.
+See @ref building, @ref cmake, @ref plugins and @ref file-formats for more
+information.
*/
class MAGNUM_ANYIMAGECONVERTER_EXPORT AnyImageConverter: public AbstractImageConverter {
public:
diff --git a/src/MagnumPlugins/AnySceneConverter/AnySceneConverter.h b/src/MagnumPlugins/AnySceneConverter/AnySceneConverter.h
index 992f2ab2b..7f1e5ff0e 100644
--- a/src/MagnumPlugins/AnySceneConverter/AnySceneConverter.h
+++ b/src/MagnumPlugins/AnySceneConverter/AnySceneConverter.h
@@ -89,7 +89,8 @@ find_package(Magnum REQUIRED AnySceneConverter)
target_link_libraries(your-app PRIVATE Magnum::AnySceneConverter)
@endcode
-See @ref building, @ref cmake and @ref plugins for more information.
+See @ref building, @ref cmake, @ref plugins and @ref file-formats for more
+information.
*/
class MAGNUM_ANYSCENECONVERTER_EXPORT AnySceneConverter: public AbstractSceneConverter {
public:
diff --git a/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h b/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h
index 5b80e550b..4322a9f55 100644
--- a/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h
+++ b/src/MagnumPlugins/TgaImageConverter/TgaImageConverter.h
@@ -86,7 +86,13 @@ find_package(Magnum REQUIRED TgaImageConverter)
target_link_libraries(your-app PRIVATE Magnum::TgaImageConverter)
@endcode
-See @ref building, @ref cmake and @ref plugins for more information.
+See @ref building, @ref cmake, @ref plugins and @ref file-formats for more
+information.
+
+@section Trade-TgaImageConverter-behavior Behavior and limitations
+
+The output is always uncompressed. If you want to make use of RLE compression
+and have the files smaller, use the @ref StbImageConverter plugin instead.
*/
class MAGNUM_TGAIMAGECONVERTER_EXPORT TgaImageConverter: public AbstractImageConverter {
public: