From 1bd5efc1f820932c69b49de4740634d45e44554f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 31 Jan 2019 17:06:50 +0100 Subject: [PATCH] doc: initial file format support tables. Plus accompanying changes to plugin docs. --- doc/features.dox | 1 + doc/file-formats.dox | 333 ++++++++++++++++++ .../AnyImageImporter/AnyImageImporter.h | 3 +- .../AnySceneImporter/AnySceneImporter.h | 3 +- src/MagnumPlugins/ObjImporter/ObjImporter.h | 5 +- src/MagnumPlugins/TgaImporter/TgaImporter.h | 20 +- 6 files changed, 353 insertions(+), 12 deletions(-) create mode 100644 doc/file-formats.dox diff --git a/doc/features.dox b/doc/features.dox index cdf60989e..30c16c80c 100644 --- a/doc/features.dox +++ b/doc/features.dox @@ -37,6 +37,7 @@ necessary to read through everything, pick only what you need. - @subpage transformations --- @copybrief transformations - @subpage animation --- @copybrief animation - @subpage plugins --- @copybrief plugins +- @subpage file-formats --- @copybrief file-formats - @subpage opengl-wrapping --- @copybrief opengl-wrapping - @subpage shaders --- @copybrief shaders - @subpage scenegraph --- @copybrief scenegraph diff --git a/doc/file-formats.dox b/doc/file-formats.dox new file mode 100644 index 000000000..d02626286 --- /dev/null +++ b/doc/file-formats.dox @@ -0,0 +1,333 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 + Vladimír Vondruš + + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL + THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER + DEALINGS IN THE SOFTWARE. +*/ + +namespace Magnum { +/** @page file-formats File format support +@brief Support tables for widely used image, scene, audio and font formats + +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 +prioritize a particular plugin implementation. + +@section file-formats-image-importers Image importers + +@m_class{m-row m-container-inflate} + +@parblock + +@m_class{m-fullwidth m-flat} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FormatGeneric plugin aliasPlugin nameCaveatsDependenciesLicense
Basis Universal (`*.basis`)`BasisImporter`@ref Trade::BasisImporter "BasisImporter"@m_span{m-text m-dim} none @m_endspan external, tinyApache-2.0
BMP
(`*.bmp`)		`BmpImporter`@ref Trade::StbImageImporter "StbImageImporter"@ref Trade-StbImageImporter-behavior-bmp "minor"bundledpublic domain
@ref Trade::DevIlImageImporter "DevIlImageImporter"unknownexternalLGPLv2.1
DirectDraw Surface
(`*.dds`)		`DdsImporter`@ref Trade::DdsImporter "DdsImporter"@ref Trade-DdsImporter-behavior "some"@m_span{m-text m-dim} none @m_endspan
@ref Trade::DevIlImageImporter "DevIlImageImporter"@ref Trade-DevIlImageImporter-behavior-dds "severe"externalLGPLv2.1
GIF
(`*.gif`)		`GifImporter`@ref Trade::StbImageImporter "StbImageImporter"@ref Trade-StbImageImporter-behavior-animated-gifs "minor"bundledpublic domain
@ref Trade::DevIlImageImporter "DevIlImageImporter"@ref Trade-DevIlImageImporter-behavior-animated-gifs "some"externalLGPLv2.1
JPEG
(`*.jpg`, `*.jpe`, `*.jpeg`)		`JpegImporter`@ref Trade::JpegImporter "JpegImporter"@m_span{m-text m-dim} none @m_endspan external, tinyLibjpeg
@ref Trade::StbImageImporter "StbImageImporter"@ref Trade-StbImageImporter-behavior-arithmetic-jpeg "some"bundledpublic domain
@ref Trade::DevIlImageImporter "DevIlImageImporter"@m_span{m-text m-dim} none @m_endspan externalLGPLv2.1
PNG
(`*.png`)		`PngImporter`@ref Trade::PngImporter "PngImporter"@ref Trade-PngImporter-behavior "minor"external, tinylibPNG
@ref Trade::StbImageImporter "StbImageImporter"@m_span{m-text m-dim} none @m_endspan bundledpublic domain
@ref Trade::DevIlImageImporter "DevIlImageImporter"@ref Trade-DevIlImageImporter-behavior-cgbi "some"externalLGPLv2.1
Truevision TGA
(`*.tga`, `*.vda`, `*.icb`, `*.vst`)		`TgaImporter`@ref Trade::TgaImporter "TgaImporter"@ref Trade-TgaImporter-behavior "minor"@m_span{m-text m-dim} none @m_endspan
@ref Trade::StbImageImporter "StbImageImporter"@m_span{m-text m-dim} none @m_endspan bundledpublic domain
@ref Trade::DevIlImageImporter "DevIlImageImporter"unknownexternalLGPLv2.1
+ +@endparblock + +In addition to the above, @ref Trade::DevIlImageImporter "DevIlImageImporter" +and @ref Trade::StbImageImporter "StbImageImporter" support many more formats. + +@section file-formats-image-converters Image converters + +To be written. + +@section file-formats-scene-importers Scene importers + +@m_class{m-row m-container-inflate} + +@parblock + +@m_class{m-fullwidth m-flat} + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FormatGeneric plugin aliasPlugin nameCaveatsDependenciesLicense
COLLADA (`*.dae`)`ColladaImporter`@ref Trade::AssimpImporter "AssimpImporter"@ref Trade-AssimpImporter-behavior "severe"externalBSD 3-clause
Autodesk FBX (`*.fbx`)`FbxImporter`@ref Trade::AssimpImporter "AssimpImporter"unknownexternalBSD 3-clause
OBJ
(`*.obj`)		`ObjImporter`@ref Trade::ObjImporter "ObjImporter"@ref Trade-ObjImporter-behavior "severe"@m_span{m-text m-dim} none @m_endspan
@ref Trade::AssimpImporter "AssimpImporter"@ref Trade-AssimpImporter-behavior "some"externalBSD 3-clause
Open Game Engine Exchange
(`*.ogex`)		`OpenGexImporter`@ref Trade::OpenGexImporter "OpenGexImporter"@ref Trade-OpenGexImporter-behavior "some"@m_span{m-text m-dim} none @m_endspan
@ref Trade::AssimpImporter "AssimpImporter"unknownexternalBSD 3-clause
glTF
(`*.gltf`, `*.glb`)		`GltfImporter`@ref Trade::TinyGltfImporter "TinyGltfImporter"@ref Trade-TinyGltfImporter-behavior "some"bundledMIT
@ref Trade::AssimpImporter "AssimpImporter"@ref Trade-AssimpImporter-behavior "severe"externalBSD 3-clause
Stanford PLY
(`*.ply`)		`StanfordImporter`@ref Trade::StanfordImporter "StanfordImporter"@ref Trade-StanfordImporter-behavior "some"@m_span{m-text m-dim} none @m_endspan
@ref Trade::AssimpImporter "AssimpImporter"@ref Trade-AssimpImporter-behavior "severe"externalBSD 3-clause
STL
(`*.stl`)		`StlImporter`@ref Trade::StlImporter "StlImporter"@ref Trade-StlImporter-behavior "minor"@m_span{m-text m-dim} none @m_endspan
@ref Trade::AssimpImporter "AssimpImporter"unknownexternalBSD 3-clause
+ +@endparblock + +In addition to the above, @ref Trade::AssimpImporter "AssimpImporter" supports +many more formats. + +@section file-formats-scene-converters Scene converters + +To be written. + +@section file-formats-audio-importers Audio importers + +To be written. + +@section file-formats-fonts Fonts + +To be written. + +@section file-formats-font-converters Font converters + +To be written. +*/ +} diff --git a/src/MagnumPlugins/AnyImageImporter/AnyImageImporter.h b/src/MagnumPlugins/AnyImageImporter/AnyImageImporter.h index 4ddf5e923..110d172f3 100644 --- a/src/MagnumPlugins/AnyImageImporter/AnyImageImporter.h +++ b/src/MagnumPlugins/AnyImageImporter/AnyImageImporter.h @@ -123,7 +123,8 @@ find_package(Magnum REQUIRED AnyImageImporter) target_link_libraries(your-app PRIVATE Magnum::AnyImageImporter) @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_ANYIMAGEIMPORTER_EXPORT AnyImageImporter: public AbstractImporter { public: diff --git a/src/MagnumPlugins/AnySceneImporter/AnySceneImporter.h b/src/MagnumPlugins/AnySceneImporter/AnySceneImporter.h index 9b37b9499..7319f86a7 100644 --- a/src/MagnumPlugins/AnySceneImporter/AnySceneImporter.h +++ b/src/MagnumPlugins/AnySceneImporter/AnySceneImporter.h @@ -125,7 +125,8 @@ find_package(Magnum REQUIRED AnySceneImporter) target_link_libraries(your-app PRIVATE Magnum::AnySceneImporter) @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_ANYSCENEIMPORTER_EXPORT AnySceneImporter: public AbstractImporter { public: diff --git a/src/MagnumPlugins/ObjImporter/ObjImporter.h b/src/MagnumPlugins/ObjImporter/ObjImporter.h index 0f49c2590..924e97198 100644 --- a/src/MagnumPlugins/ObjImporter/ObjImporter.h +++ b/src/MagnumPlugins/ObjImporter/ObjImporter.h @@ -87,9 +87,10 @@ find_package(Magnum REQUIRED ObjImporter) target_link_libraries(your-app PRIVATE Magnum::ObjImporter) @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-ObjImporter-limitations Behavior and limitations +@section Trade-ObjImporter-behavior Behavior and limitations Meshes are imported as @ref MeshPrimitive::Triangles with @ref MeshIndexType::UnsignedInt indices, interleaved @ref VertexFormat::Vector3 diff --git a/src/MagnumPlugins/TgaImporter/TgaImporter.h b/src/MagnumPlugins/TgaImporter/TgaImporter.h index 386c9a80b..cad99fd8f 100644 --- a/src/MagnumPlugins/TgaImporter/TgaImporter.h +++ b/src/MagnumPlugins/TgaImporter/TgaImporter.h @@ -58,13 +58,7 @@ namespace Magnum { namespace Trade { @brief TGA importer plugin Supports Truevision TGA (`*.tga`, `*.vda`, `*.icb`, `*.vst`) BGR, BGRA or -grayscale images with 8 bits per channel. RLE compression is supported, -paletted images are not. - -The images are imported with @ref PixelFormat::RGB8Unorm, -@ref PixelFormat::RGBA8Unorm or @ref PixelFormat::R8Unorm, respectively. Images -are imported with default @ref PixelStorage parameters except for alignment, -which may be changed to `1` if the data require it. +grayscale images with 8 bits per channel. @section Trade-TgaImporter-usage Usage @@ -93,7 +87,17 @@ find_package(Magnum REQUIRED TgaImporter) target_link_libraries(your-app PRIVATE Magnum::TgaImporter) @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-TgaImporter-behavior Behavior and limitations + +The images are imported with @ref PixelFormat::RGB8Unorm, +@ref PixelFormat::RGBA8Unorm or @ref PixelFormat::R8Unorm, respectively. Images +are imported with default @ref PixelStorage parameters except for alignment, +which may be changed to `1` if the data require it. + +RLE compression is supported, paletted images are not. */ class MAGNUM_TGAIMPORTER_EXPORT TgaImporter: public AbstractImporter { public: