From 1046e051b95788776ee074cc7b18faa4b8d313fa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sun, 29 Nov 2020 17:18:42 +0100 Subject: [PATCH] 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 | 267 ++++++++++++++++-- .../AnyImageConverter/AnyImageConverter.h | 3 +- .../AnySceneConverter/AnySceneConverter.h | 3 +- .../TgaImageConverter/TgaImageConverter.h | 8 +- 4 files changed, 249 insertions(+), 32 deletions(-) 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} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FormatGeneric plugin aliasPlugin nameCaveatsDependenciesLicense
Basis Universal (`*.basis`)`BasisImageConverter`@ref Trade::BasisImageConverter "BasisImageConverter"@ref Trade-BasisImageConverter-behavior "some"bundleableApache-2.0
OpenEXR (`*.exr`)`OpenExrImageConverter`@ref Trade::MiniExrImageConverter "MiniExrImageConverter"@ref Trade-MiniExrImageConverter-behavior "minor"bundledpublic domain
JPEG
(`*.jpg`, `*.jpe`, `*.jpeg`)		`JpegImageConverter`@ref Trade::JpegImageConverter "JpegImageConverter"@ref Trade-JpegImageConverter-behavior "minor"external, tinyLibjpeg
@ref Trade::StbImageConverter "StbImageConverter"@ref Trade-StbImageConverter-behavior-arithmetic-jpeg "minor"bundledpublic domain
PNG
(`*.png`)		`PngImageConverter`@ref Trade::PngImageConverter "PngImageConverter"@m_span{m-text m-dim} none @m_endspan external, tinylibPNG
@ref Trade::StbImageConverter "StbImageConverter"@ref Trade-StbImageConverter-behavior-16bit-png "some"bundledpublic 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 bundledpublic 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} + + + + + + + + + + + + + + + + + + + + +
FormatGeneric plugin aliasPlugin nameCaveatsDependenciesLicense
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: