doc: expand the File Formats tables, add "bundleability" info for each.

Providing a legend describing what each color-code means and listing
image and scene converters as well.

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
+@ref Trade::AnySceneImporter "AnySceneImporter",
-used for generic loading of any of the recognized formats, they'll proxy the
+@ref Trade::AnyImageConverter "AnyImageConverter",
-loading to a concrete plugin implementation. The following tables list the most
+@ref Trade::AnySceneConverter "AnySceneConverter" and other `Any*` plugins can
-widely used formats with alternative plugin implementations and known caveats
+be used for generic handling of any of the recognized formats, they'll proxy
-for each.
+the operation to a concrete plugin implementation. The following tables list
-
+the most widely used formats with alternative plugin implementations and known
-When one format is supported by more than one plugin, you can use
+caveats for each. When one format is supported by more than one plugin, you
-@ref Corrade::PluginManager::AbstractManager::setPreferredPlugins() to
+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.
 <td>`BasisImporter`</td>
 <td>@ref Trade::BasisImporter "BasisImporter"</td>
 <td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
-<td class="m-text-center m-success">external, tiny</td>
+<td class="m-text-center m-success">bundleable, tiny</td>
 <td class="m-text-center m-success">Apache-2.0</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -78,7 +86,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-dim">unknown</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -94,7 +102,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-DevIlImageImporter-behavior-dds "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -110,7 +118,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-DevIlImageImporter-behavior-animated-gifs "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -126,7 +134,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-DevIlImageImporter-behavior-ico "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -136,7 +144,7 @@ prioritize a particular plugin implementation.
 <td rowspan="3">`JpegImporter`</td>
 <td>@ref Trade::JpegImporter "JpegImporter"</td>
 <td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
-<td class="m-text-center m-success">external, tiny</td>
+<td class="m-text-center m-warning">external, tiny</td>
 <td class="m-text-center m-success">Libjpeg</td>
 </tr>
 <tr>
@@ -148,7 +156,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -158,7 +166,7 @@ prioritize a particular plugin implementation.
 <td rowspan="3">`PngImporter`</td>
 <td>@ref Trade::PngImporter "PngImporter"</td>
 <td class="m-text-center m-success">@ref Trade-PngImporter-behavior "minor"</td>
-<td class="m-text-center m-success">external, tiny</td>
+<td class="m-text-center m-warning">external, tiny</td>
 <td class="m-text-center m-success">libPNG</td>
 </tr>
 <tr>
@@ -170,7 +178,7 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-warning">@ref Trade-DevIlImageImporter-behavior-cgbi "some"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -186,13 +194,13 @@ prioritize a particular plugin implementation.
 <tr>
 <td>@ref Trade::StbImageImporter "StbImageImporter"</td>
 <td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
-<td class="m-text-center m-success">bundled</td>
+<td class="m-text-center m-primary">bundled</td>
 <td class="m-text-center m-primary">public domain</td>
 </tr>
 <tr>
 <td>@ref Trade::DevIlImageImporter "DevIlImageImporter"</td>
 <td class="m-text-center m-dim">unknown</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-danger">external</td>
 <td class="m-text-center m-warning">LGPLv2.1</td>
 </tr>
 </table>
@@ -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}
+
+<table>
+<tr>
+<th>Format</th>
+<th>Generic plugin alias</th>
+<th>Plugin name</th>
+<th class="m-text-center">Caveats</th>
+<th class="m-text-center">Dependencies</th>
+<th class="m-text-center">License</th>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th>Basis Universal (`*.basis`)</th>
+<td>`BasisImageConverter`</td>
+<td>@ref Trade::BasisImageConverter "BasisImageConverter"</td>
+<td class="m-text-center m-warning">@ref Trade-BasisImageConverter-behavior "some"</td>
+<td class="m-text-center m-warning">bundleable</td>
+<td class="m-text-center m-success">Apache-2.0</td>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th>OpenEXR (`*.exr`)</th>
+<td>`OpenExrImageConverter`</td>
+<td>@ref Trade::MiniExrImageConverter "MiniExrImageConverter"</td>
+<td class="m-text-center m-success">@ref Trade-MiniExrImageConverter-behavior "minor"</td>
+<td class="m-text-center m-primary">bundled</td>
+<td class="m-text-center m-primary">public domain</td>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th rowspan="2">JPEG<br/>(`*.jpg`, `*.jpe`, `*.jpeg`)</th>
+<td rowspan="2">`JpegImageConverter`</td>
+<td>@ref Trade::JpegImageConverter "JpegImageConverter"</td>
+<td class="m-text-center m-success">@ref Trade-JpegImageConverter-behavior "minor"</td>
+<td class="m-text-center m-warning">external, tiny</td>
+<td class="m-text-center m-success">Libjpeg</td>
+</tr>
+<tr>
+<td>@ref Trade::StbImageConverter "StbImageConverter"</td>
+<td class="m-text-center m-success">@ref Trade-StbImageConverter-behavior-arithmetic-jpeg "minor"</td>
+<td class="m-text-center m-primary">bundled</td>
+<td class="m-text-center m-primary">public domain</td>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th rowspan="2">PNG<br/>(`*.png`)</th>
+<td rowspan="2">`PngImageConverter`</td>
+<td>@ref Trade::PngImageConverter "PngImageConverter"</td>
+<td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
+<td class="m-text-center m-warning">external, tiny</td>
+<td class="m-text-center m-success">libPNG</td>
+</tr>
+<tr>
+<td>@ref Trade::StbImageConverter "StbImageConverter"</td>
+<td class="m-text-center m-warning">@ref Trade-StbImageConverter-behavior-16bit-png "some"</td>
+<td class="m-text-center m-primary">bundled</td>
+<td class="m-text-center m-primary">public domain</td>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th rowspan="2">Truevision TGA<br/>(`*.tga`, `*.vda`, `*.icb`, `*.vst`)</th>
+<td rowspan="2">`TgaImageConverter`</td>
+<td>@ref Trade::TgaImageConverter "TgaImageConverter"</td>
+<td class="m-text-center m-success">@ref Trade-TgaImageConverter-behavior "minor"</td>
+<td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
+<td class="m-text-center"></td>
+</tr>
+<tr>
+<td>@ref Trade::StbImageConverter "StbImageConverter"</td>
+<td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
+<td class="m-text-center m-primary">bundled</td>
+<td class="m-text-center m-primary">public domain</td>
+</tr>
+</table>
+
+@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.
 <td>`ColladaImporter`</td>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-AssimpImporter-behavior "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -240,7 +341,7 @@ To be written.
 <td>`FbxImporter`</td>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-dim">unknown</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -256,7 +357,7 @@ To be written.
 <tr>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-warning">@ref Trade-AssimpImporter-behavior "some"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -272,7 +373,7 @@ To be written.
 <tr>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-dim">unknown</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -282,13 +383,13 @@ To be written.
 <td rowspan="2">`GltfImporter`</td>
 <td>@ref Trade::TinyGltfImporter "TinyGltfImporter"</td>
 <td class="m-text-center m-warning">@ref Trade-TinyGltfImporter-behavior "some"</td>
-<td class="m-text-center m-success">bundled</td>
+<td class="m-text-center m-primary">bundled</td>
 <td class="m-text-center m-success">MIT</td>
 </tr>
 <tr>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-AssimpImporter-behavior "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -304,7 +405,7 @@ To be written.
 <tr>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-danger">@ref Trade-AssimpImporter-behavior "severe"</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 <tr><td colspan="6"></td></tr>
@@ -320,7 +421,7 @@ To be written.
 <tr>
 <td>@ref Trade::AssimpImporter "AssimpImporter"</td>
 <td class="m-text-center m-dim">unknown</td>
-<td class="m-text-center m-warning">external</td>
+<td class="m-text-center m-warning">bundleable</td>
 <td class="m-text-center m-success">BSD 3-clause</td>
 </tr>
 </table>
@@ -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}
+
+<table>
+<tr>
+<th>Format</th>
+<th>Generic plugin alias</th>
+<th>Plugin name</th>
+<th class="m-text-center">Caveats</th>
+<th class="m-text-center">Dependencies</th>
+<th class="m-text-center">License</th>
+</tr>
+<tr><td colspan="6"></td></tr>
+
+<tr>
+<th>Stanford PLY (`*.ply`)</th>
+<td>`StanfordSceneConverter`</td>
+<td>@ref Trade::StanfordSceneConverter "StanfordSceneConverter"</td>
+<td class="m-text-center m-success">@ref Trade-StanfordSceneConverter-behavior "minor"</td>
+<td class="m-text-center">@m_span{m-text m-dim} none @m_endspan </td>
+<td class="m-text-center"></td>
+</tr>
+</table>
+
+@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.
 */
 }

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:

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:

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: