From 14914153792aff48b347fd352ab44620bead98f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Tue, 27 Mar 2018 19:13:46 +0200 Subject: [PATCH] Doc++ --- doc/getting-started.dox | 2 +- doc/platforms-windows.dox | 1 + doc/plugins.dox | 37 ++++++++++++++++------------- doc/snippets/plugins.cpp | 12 +++++++--- src/Magnum/Trade/AbstractImporter.h | 2 +- 5 files changed, 33 insertions(+), 21 deletions(-) diff --git a/doc/getting-started.dox b/doc/getting-started.dox index 0bb9d4560..2ed042020 100644 --- a/doc/getting-started.dox +++ b/doc/getting-started.dox @@ -138,7 +138,7 @@ find_package(Magnum REQUIRED Sdl2Application) set_directory_properties(PROPERTIES CORRADE_USE_PEDANTIC_FLAGS ON) add_executable(MyApplication MyApplication.cpp) -target_link_libraries(MyApplication +target_link_libraries(MyApplication PRIVATE Magnum::Magnum Magnum::Application) @endcode diff --git a/doc/platforms-windows.dox b/doc/platforms-windows.dox index 08ade06b5..3c39f8802 100644 --- a/doc/platforms-windows.dox +++ b/doc/platforms-windows.dox @@ -39,6 +39,7 @@ See @ref Platform::Sdl2Application for more information about WinRT. @todoc mingw, clang, clang/c2... @todoc "unicode" @todoc colored console output +@todoc lcov on mingw (ugh) */ } diff --git a/doc/plugins.dox b/doc/plugins.dox index f5854670e..9068d5a9d 100644 --- a/doc/plugins.dox +++ b/doc/plugins.dox @@ -116,10 +116,14 @@ explicitly find the plugin and link it into the executable. If you use CMake, it would look like this: @code{.cmake} -find_package(MagnumPlugins REQUIRED PngImporter) - -add_executable(MyApp ...) -target_link_libraries(MyApp ... MagnumPlugins::PngImporter) +find_package(MagnumPlugins REQUIRED + TinyGltfImporter + StbTrueTypeFont) + +add_executable(my-app my-app.cpp) +target_link_libraries(my-app PRIVATE + MagnumPlugins::TinyGltfImporter + MagnumPlugins::StbTrueTypeFont) @endcode The only user-visible behavioral change in the code will be that @@ -141,20 +145,20 @@ application. The static import file contains just a simple call to @section plugins-aliases Plugin aliases and "any" plugins -There's usually more than one plugin available to achieve a particular thing ---- for example in order to open a PNG file, you can choose among +There's usually more than one plugin available to achieve a particular goal --- +for example in order to open a PNG file, you can choose among @ref Trade::PngImporter "PngImporter", @ref Trade::StbImageImporter "StbImageImporter" or @ref Trade::DevIlImageImporter "DevIlImageImporter" plugins. Rather than -this being an unnecessary redundancy, it allows you to choose among different -performance / portability / feature tradeoffs --- choose a plugin with no -external dependencies or on the other hand pick the fastest possible -implementation. +this being an unnecessary redundancy, it allows you to pick a particular +performance / portability / feature tradeoff --- a plugin with no external +dependencies for a web build or, on the other hand, the fastest possible +implementation for a tool that does heavy image processing. -The decision what plugin to use is usually done in the buildsystem or during -the deploy. To make this simpler in the code itself, all plugins that support a -particular format provide a common *alias*. In the case of PNG images, you can -just load a @cpp "PngImporter" @ce plugin and if @ref Trade::PngImporter "PngImporter" -is not available, it will pick up any of the other candidates. +To make this simpler in the code and defer the decision to the buildsystem or +app deployment, all plugins that support a particular format provide a common +*alias* --- in case of PNG images, you can just load a @cpp "PngImporter" @ce +plugin and if @ref Trade::PngImporter "PngImporter" is not available, it will +pick up any of the other candidates. For greater control you can also use @ref Corrade::PluginManager::AbstractManager::setPreferredPlugins() "setPreferredPlugins()", @@ -196,7 +200,8 @@ all possible knobs and switches that a file format could support, the plugins have a possibility to supply additional configuration via the @ref Corrade::PluginManager::AbstractPlugin::configuration() "configuration()" function. For example, in the @ref Trade-AssimpImporter-configuration "AssimpImporter" -plugin you can toggle various postprocessing modules: +plugin you can toggle various postprocessing steps that are applied to loaded +scene files: @snippet plugins.cpp configuration diff --git a/doc/snippets/plugins.cpp b/doc/snippets/plugins.cpp index 7b8f92717..318e0583d 100644 --- a/doc/snippets/plugins.cpp +++ b/doc/snippets/plugins.cpp @@ -4,10 +4,16 @@ #include "Magnum/Text/AbstractFont.h" #include "Magnum/Trade/AbstractImporter.h" +#ifdef __has_include +#if __has_include() && \ + __has_include() /* [static-import] */ /* No need to do this if you use CMake */ -#include +#include +#include /* [static-import] */ +#endif +#endif using namespace Magnum; @@ -39,8 +45,8 @@ fontManager.load("MagnumFont"); { /* [aliases] */ -PluginManager::Manager fontManager; -fontManager.setPreferredPlugins("TrueTypeFont", {"HarfBuzzFont", "FreeTypeFont"}); +PluginManager::Manager manager; +manager.setPreferredPlugins("TrueTypeFont", {"HarfBuzzFont", "FreeTypeFont"}); /* [aliases] */ } diff --git a/src/Magnum/Trade/AbstractImporter.h b/src/Magnum/Trade/AbstractImporter.h index 0fc875dab..daf925346 100644 --- a/src/Magnum/Trade/AbstractImporter.h +++ b/src/Magnum/Trade/AbstractImporter.h @@ -54,7 +54,7 @@ data. See @ref plugins for more information and `*Importer` classes in @section Trade-AbstractImporter-subclassing Subclassing The plugin needs to implement the @ref doFeatures(), @ref doIsOpened() -functions, at least one of @ref doOpenData() / @ref doOpenFile() @ref doOpenState() +functions, at least one of @ref doOpenData() / @ref doOpenFile() / @ref doOpenState() functions, function @ref doClose() and one or more tuples of data access functions, based on what features are supported in given format.