diff --git a/doc/cmake.dox b/doc/cmake.dox index ae37c4cc5..7ce68f46e 100644 --- a/doc/cmake.dox +++ b/doc/cmake.dox @@ -47,7 +47,7 @@ variables: (e.g. set it to `.` when deploying on Windows with plugins stored relatively to the executable), the following `MAGNUM_PLUGINS_*_DIR` variables depend on it. -- `MAGNUM_PLUGINS_INCLUDE_DIR -- Include dir with plugins +- `MAGNUM_PLUGINS_INCLUDE_DIR` -- Include dir with plugins - `MAGNUM_PLUGINS_FONT_DIR` -- Directory with font plugins - `MAGNUM_PLUGINS_FONTCONVERTER_DIR` -- Directory with font converter plugins - `MAGNUM_PLUGINS_IMAGECONVERTER_DIR` -- Directory with image converter diff --git a/doc/features.dox b/doc/features.dox index bd0ba5ff9..6ef0a5f13 100644 --- a/doc/features.dox +++ b/doc/features.dox @@ -30,6 +30,7 @@ namespace Magnum { - @subpage types -- @copybrief types - @subpage matrix-vector -- @copybrief matrix-vector - @subpage transformations -- @copybrief transformations +- @subpage plugins -- @copybrief plugins - @subpage scenegraph -- @copybrief scenegraph - @subpage shapes -- @copybrief shapes - @subpage debug-tools -- @copybrief debug-tools diff --git a/doc/namespaces.dox b/doc/namespaces.dox index d24c2076a..1bd43d68a 100644 --- a/doc/namespaces.dox +++ b/doc/namespaces.dox @@ -33,9 +33,10 @@ Contains classes for interacting with OpenGL. -This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and -@ref cmake for more information. +This library is built as part of %Magnum by default. To use it, you need to +find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more +information. */ /** @dir Platform @@ -46,13 +47,14 @@ to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and Base classes for creating applications with various toolkits. -Parts of this namespace are built if `WITH_*APPLICATION` is enabled in CMake, -with each library having specific toolkit dependencies and platform -requirements. To use particular application library, you need to request given -`*Application` component in CMake, add `${MAGNUM_*APPLICATION_INCLUDE_DIRS}` to -include path and link to `${MAGNUM_*APPLICATION_LIBRARIES}`. See particular -`*Application` class documentation, @ref building, @ref cmake and @ref platform -for more information. +Parts of this namespace are built if `WITH_*APPLICATION` is enabled when +building %Magnum, with each library having specific toolkit dependencies and +platform requirements. To use particular application library, you need to +request given `*Application` component of `%Magnum` package in CMake, add +`${MAGNUM_*APPLICATION_INCLUDE_DIRS}` to include path and link to +`${MAGNUM_*APPLICATION_LIBRARIES}`. See particular `*Application` class +documentation, @ref building, @ref cmake and @ref platform for more +information. */ /** @dir Math @@ -63,9 +65,10 @@ for more information. Template classes for matrix and vector calculations. -This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building, -@ref cmake, @ref matrix-vector and @ref transformations for more information. +This library is built as part of %Magnum by default. To use it, you need to +find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +to `${MAGNUM_LIBRARIES}`. See @ref building, @ref cmake, @ref matrix-vector and +@ref transformations for more information. */ /** @dir Math/Algorithms @@ -76,9 +79,10 @@ to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building, Various matrix and vector algorithms. -This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and -@ref cmake for more information. +This library is built as part of %Magnum by default. To use it, you need to +find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more +information. */ /** @dir Math/Geometry @@ -89,9 +93,10 @@ to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and Functions for computing intersections, distances, areas and volumes. -This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and -@ref cmake for more information. +This library is built as part of %Magnum by default. To use it, you need to +find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more +information. */ /** @dir Audio @@ -103,12 +108,12 @@ to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and Audio import, playback and integration with @ref SceneGraph. This library depends on **OpenAL** library. It is built if `WITH_AUDIO` is -enabled in CMake. To use this library, you need to request `%Audio` component -in CMake, add `${MAGNUM_AUDIO_INCLUDE_DIRS}` to include path and link to -`${MAGNUM_AUDIO_LIBRARIES}`. See @ref building and @ref cmake for more -information. Additional plugins are part of plugin repository, see particular -`*Importer` class documentation, @ref building-plugins and @ref cmake-plugins -for more information. +enabled when building %Magnum. To use this library, you need to request +`%Audio` component of `%Magnum` package in CMake, add `${MAGNUM_AUDIO_INCLUDE_DIRS}` +to include path and link to `${MAGNUM_AUDIO_LIBRARIES}`. See @ref building and +@ref cmake for more information. Additional plugins are enabled separately, see +particular `*Importer` class documentation, @ref building-plugins, +@ref cmake-plugins and @ref plugins for more information. */ /** @dir DebugTools @@ -119,10 +124,10 @@ for more information. Debugging helpers, renderers and profilers. -This library is built if `WITH_DEBUGTOOLS` is enabled in CMake. To use this -library, you need to request `%DebugTools` component in CMake and link to -`${MAGNUM_DEBUGTOOLS_LIBRARIES}`. See @ref building, @ref cmake and -@ref debug-tools for more information. +This library is built if `WITH_DEBUGTOOLS` is enabled when building %Magnum. To +use this library, you need to request `%DebugTools` component of `%Magnum` +package in CMake and link to `${MAGNUM_DEBUGTOOLS_LIBRARIES}`. See +@ref building, @ref cmake and @ref debug-tools for more information. */ /** @dir MeshTools @@ -133,10 +138,10 @@ library, you need to request `%DebugTools` component in CMake and link to Tools for generating, optimizing and cleaning meshes. -This library is built if `WITH_MESHTOOLS` is enabled in CMake. To use this -library, you need to request `%MeshTools` component in CMake and link to -`${MAGNUM_MESHTOOLS_LIBRARIES}`. See @ref building and @ref cmake for more -information. +This library is built if `WITH_MESHTOOLS` is enabled when building %Magnum. To +use this library, you need to request `%MeshTools` component of `%Magnum` +package in CMake and link to `${MAGNUM_MESHTOOLS_LIBRARIES}`. See @ref building +and @ref cmake for more information. */ /** @dir Plugins @@ -151,10 +156,10 @@ information. Basic primitives for testing purposes. -This library is built if `WITH_PRIMITIVES` is enabled in CMake. To use this -library, you need to request `%Primitives` component in CMake and link to -`${MAGNUM_PRIMITIVES_LIBRARIES}`. See @ref building and @ref cmake for more -information. +This library is built if `WITH_PRIMITIVES` is enabled when building %Magnum. To +use this library, you need to request `%Primitives` component of `%Magnum` +package in CMake and link to `${MAGNUM_PRIMITIVES_LIBRARIES}`. See +@ref building and @ref cmake for more information. */ /** @dir SceneGraph @@ -166,10 +171,10 @@ information. Managing object hierarchy, transformations and interactions. -This library is built if `WITH_SCENEGRAPH` is enabled in CMake. To use this -library, you need to request `%SceneGraph` component in CMake and link to -`${MAGNUM_SCENEGRAPH_LIBRARIES}`. See @ref building, @ref cmake and -@ref scenegraph for more information. +This library is built if `WITH_SCENEGRAPH` is enabled when building %Magnum. To +use this library, you need to request `%SceneGraph` component of `%Magnum` +package in CMake and link to `${MAGNUM_SCENEGRAPH_LIBRARIES}`. See +@ref building, @ref cmake and @ref scenegraph for more information. */ /** @dir Shaders @@ -180,10 +185,10 @@ library, you need to request `%SceneGraph` component in CMake and link to Collection of shaders for easy prototyping and basic usage. -This library is built if `WITH_SHADERS` is enabled in CMake. To use this -library, you need to request `%Shaders` component in CMake and link to -`${MAGNUM_MESHTOOLS_SHADERS}`. See @ref building and @ref cmake for more -information. +This library is built if `WITH_SHADERS` is enabled when building %Magnum. To +use this library, you need to request `%Shaders` component of `%Magnum` package +in CMake and link to `${MAGNUM_MESHTOOLS_SHADERS}`. See @ref building and +@ref cmake for more information. */ /** @dir Shapes @@ -194,10 +199,10 @@ information. Collision detection system. -This library is built if `WITH_SHAPES` is enabled in CMake. To use this -library, you need to request `%Shapes` component in CMake and link to -`${MAGNUM_SHAPES_LIBRARIES}`. See @ref building, @ref cmake and @ref shapes for -more information. +This library is built if `WITH_SHAPES` is enabled when building %Magnum. To use +this library, you need to request `%Shapes` component of `%Magnum` package in +CMake and link to `${MAGNUM_SHAPES_LIBRARIES}`. See @ref building, @ref cmake +and @ref shapes for more information. */ /** @dir Text @@ -208,12 +213,12 @@ more information. Font texture creation and text layouting. -This library is built if `WITH_TEXT` is enabled in CMake. To use this library, -you need to request `%Text` component in CMake and link to `${MAGNUM_TEXT_LIBRARIES}`. -See @ref building and @ref cmake for more information. Additional plugins are -part of plugin repository, see particular `*Font` and `*FontConverter` class -documentation, @ref building-plugins and @ref cmake-plugins for more -information. +This library is built if `WITH_TEXT` is enabled when building %Magnum. To use +this library, you need to request `%Text` component of `%Magnum` package in +CMake and link to `${MAGNUM_TEXT_LIBRARIES}`. See @ref building and @ref cmake +for more information. Additional plugins are enabled separately, see particular +`*Font` and `*FontConverter` class documentation, @ref building-plugins, +@ref cmake-plugins and @ref plugins for more information. */ /** @dir TextureTools @@ -224,10 +229,10 @@ information. Tools for generating, compressing and optimizing textures. -This library is built if `WITH_TEXTURETOOLS` is enabled in CMake. To use this -library, you need to request `%TextureTools` component in CMake and link to -`${MAGNUM_TEXTURETOOLS_LIBRARIES}`. See @ref building and @ref cmake for more -information. +This library is built if `WITH_TEXTURETOOLS` is enabled when building %Magnum. +To use this library, you need to request `%TextureTools` component of `%Magnum` +package in CMake and link to `${MAGNUM_TEXTURETOOLS_LIBRARIES}`. See +@ref building and @ref cmake for more information. */ /** @dir Trade @@ -239,10 +244,10 @@ information. Contains plugin interfaces for importing data of various formats and classes for direct access to the data. -This library is built by default. To use it, you need to add `${MAGNUM_INCLUDE_DIRS}` -to include path and link to `${MAGNUM_LIBRARIES}`. See @ref building and -@ref cmake for more information. Additional plugins are part of plugin -repository, see particular `*Importer` and `*ImageConverter` class -documentation, @ref building-plugins and @ref cmake-plugins for more -information. +This library is built as part of %Magnum by default. To use it, you need to +find `%Magnum` package, add `${MAGNUM_INCLUDE_DIRS}` to include path and link +to `${MAGNUM_LIBRARIES}`. See @ref building and @ref cmake for more +information. Additional plugins are enabled separately, see particular +`*Importer` and `*ImageConverter` class documentation, @ref building-plugins, +@ref cmake-plugins and @ref plugins for more information. */ diff --git a/doc/plugins.dox b/doc/plugins.dox new file mode 100644 index 000000000..add928560 --- /dev/null +++ b/doc/plugins.dox @@ -0,0 +1,205 @@ +/* + This file is part of Magnum. + + Copyright © 2010, 2011, 2012, 2013 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 plugins Loading and using plugins +@brief Extending %Magnum with additional functionality + +- Previous page: @ref transformations +- Next page: @ref scenegraph + +The base %Magnum library contains math support, scene graph implementation and +is able to interact with graphics and audio hardware. However, the base library +doesn't provide any functions for dealing with specific file formats, as there +are simply too many formats to have them included directly in the library. +Instead, the library provides plugin API and you can load plugin which will +then be able to read or write the particular file format. + +@tableofcontents + +The @ref building "Magnum repository" contains a few basic plugins for opening +the some formats, such as TGA images or WAV audio files. These plugins are +included because the file formats are so simple that no external library is +needed for loading their contents and thus they are suitable for quick demos +and prototyping without dealing with additional dependencies. + +Additional plugins (such as importers for PNG and JPEG images, FreeType fonts +etc.) are available in @ref building-plugins "Magnum Plugins" repository. +Majority of these plugins depends on external libraries, thus some of them +might not be available on all platforms. + +@section plugins-types Plugin interfaces + +%Magnum contains these plugin interfaces: + +- @ref Trade::AbstractImporter -- importers for general 2D and 3D scene, + mesh, material, texture and image data. See `*Importer` classes in + @ref Trade namespace for available importer plugins. These are installed in + `MAGNUM_PLUGINS_IMPORTER_DIR` directory. +- @ref Trade::AbstractImageConverter -- conversion among various image + formats. See `*ImageConverter` classes in @ref Trade namespace for list of + available image converter plugins. These are installed in + `MAGNUM_PLUGINS_IMAGECONVERTER_DIR` directory. +- @ref Text::AbstractFont -- font loading and glyph layouting. See `*Font` + classes in @ref Text namespace for available font plugins. These are + installed in `MAGNUM_PLUGINS_FONT_DIR` directory. +- @ref Text::AbstractFontConverter -- font and glyph cache conversion. See + `*FontConverter` classes in @ref Text namespace for available font + converter plugins. These are installed in `MAGNUM_PLUGINS_FONTCONVERTER_DIR` + directory. +- @ref Audio::AbstractImporter -- importers for audio formats. See + `*Importer` classes in @ref Audio namespace for available audio importer + plugins. These are installed in `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR` + directory. + +@section plugins-loading Loading and instantiating the plugins + +To load the plugins, you need to instantiate @ref Corrade::PluginManager::Manager +for given plugin interface, for example @ref Trade::AbstractImporter. You must +set particular plugin directory, from which the manager will load and +instantiate the plugins. To save you from hardcoding the value into your +application source, the plugin directory is provided as `MAGNUM_PLUGINS_DIR` +CMake variable. The default is set to %Magnum install location, but you can +change it through CMake to anything else. The `MAGNUM_PLUGINS_IMPORTER_DIR`, +`MAGNUM_PLUGINS_IMAGECONVERTER_DIR`, `MAGNUM_PLUGINS_FONT_DIR`, +`MAGNUM_PLUGINS_FONTCONVERTER_DIR`, `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR` +variables depend on `MAGNUM_PLUGINS_DIR`, so if you modify that variable, the +changes will be reflected in these variables too. See @ref cmake for additional +information. + +You can provide the variable to your sources using CMake configuration file. +Create `configure.h.cmake` file in your source directory with contents similar +to these: +@code +#define MAGNUM_PLUGINS_IMPORTER_DIR "${MAGNUM_PLUGINS_IMPORTER_DIR}" +@endcode + +Then process the file in your `CMakeLists.txt`. The result +(`${MAGNUM_PLUGINS_IMPORTER_DIR}` gets replaced with the actual value) is put +into build directory, so don't forget to add it to include path: +@code +configure_file(${CMAKE_CURRENT_SOURCE_DIR}/configure.h.cmake + ${CMAKE_CURRENT_BINARY_DIR}/configure.h) +include_directories(${CMAKE_CURRENT_BINARY_DIR}) +@endcode + +Then you can instantiate the manager, load particular plugin and create an +instance of it. Keep in mind that the manager instance must exist for whole +lifetime of all plugin instances created from it. +@code +#include "configure.h" + +// ... + +{ + PluginManager::Manager manager(MAGNUM_PLUGINS_IMPORTER_DIR); + if(!(manager.load("TgaImporter") & PluginManager::LoadState::Loaded)) { + Error() << "Cannot load TgaImporter plugin from" << manager.pluginDirectory(); + std::exit(1); + } + std::unique_ptr tgaImporter = manager.instance("TgaImporter"); + if(!tgaImporter) { + Error() << "Cannot instantiate TgaImporter plugin"; + std::exit(2); + } + + // Use the plugin... + + // At the end of the scope the tgaImporter instance gets deleted and then + // the manager automatically unloads the plugin on destruction +} +@endcode + +@section plugins-dependencies Plugin dependencies + +Some plugins have dependencies, for example the @ref Text::MagnumFont "MagnumFont" +plugin needs to load the glyph atlas using @ref Trade::TgaImporter "TgaImporter" +plugin. The dependency loading is done automatically, but you need to create +instance of corresponding plugin manager in particular plugin dir so the +dependency can be found. Example: +@code +PluginManager::Manager importerManager(MAGNUM_PLUGINS_IMPORTER_DIR); +PluginManager::Manager fontManager(MAGNUM_PLUGINS_FONT_DIR); + +// As a side effect TgaImporter is loaded by importerManager +fontManager.load("MagnumFont"); +@endcode + +@section plugins-static Static plugins + +By default all plugins are built as dynamic ones, i.e. they are separate +binary which gets linked in at runtime. This is good for reducing memory +consumption, as the code is loaded in memory only for the time it is needed. +However, if you want to port to platform which does not support dynamic linking +or you simply want to have the plugin loaded at all times, you can use static +plugins. + +The plugins are built as static if `BUILD_STATIC` CMake parameter is enabled +(see @ref building and @ref building-plugins for more information). The actual +usage is basically the same as above, but you need to explicitly find the +plugin and link it into the executable in your `CMakeLists.txt`. See @ref cmake +and @ref cmake-plugins for additional information. +@code +find_package(Magnum REQUIRED TgaImporter) + +add_executable(MyApp ...) +target_link_libraries(MyApp ... ${MAGNUM_TGAIMPORTER_LIBRARIES}) +@endcode + +The only user-visible behavioral change will be that +@ref Corrade::PluginManager::AbstractManager::load() "PluginManager::Manager::load()" +will return @ref Corrade::PluginManager::LoadState::Static "PluginManager::LoadState::Static" +instead of @ref Corrade::PluginManager::LoadState::Loaded "PluginManager::LoadState::Loaded", +but there is no need to change the above code, as it will work for both dynamic +and static case. + +If you link the plugin into dynamic library or executable, it will register +itself automatically, but if you want to link the plugin into static library, +you need to register it yourself with @ref CORRADE_PLUGIN_IMPORT() in some +function which will be executed before you use the plugin. See the macro +documentation for information about automatic importing and namespace issues. +@code +int main(int argc, char** argv) { + CORRADE_PLUGIN_IMPORT(TgaImporter) + + // ... +} +@endcode + +@section plugins-develop Developing your own plugins + +See class documentation of particular plugin interfaces for more information +about subclassing. The %Corrade's @ref plugin-management "plugin management tutorial" +contains more information about plugin compilation and registering. + +If you want to develop a plugin which depends on another, you need to find the +original plugin, add its include dirs to include path and link to it, similarly +to how static plugins are found above. See @ref cmake and @ref cmake-plugins +for more information. + +- Previous page: @ref transformations +- Next page: @ref scenegraph + +*/ +} diff --git a/doc/scenegraph.dox b/doc/scenegraph.dox index 739d52ce8..f14731ea2 100644 --- a/doc/scenegraph.dox +++ b/doc/scenegraph.dox @@ -26,7 +26,7 @@ namespace Magnum { namespace SceneGraph { /** @page scenegraph Using scene graph @brief Overview of scene management capabilities. -- Previous page: @ref transformations +- Previous page: @ref plugins - Next page: @ref shapes %Scene graph provides way to hiearchically manage your objects, their @@ -304,7 +304,7 @@ On destruction, Object3D destructor is called first, deleting MyFeature, which is wrong, because MyFeature is in the same object. After that (if the program didn't already crash) destructor of MyFeature is called (again). -- Previous page: @ref transformations +- Previous page: @ref plugins - Next page: @ref shapes */ }} diff --git a/doc/transformations.dox b/doc/transformations.dox index 730ce9b25..2971e0bea 100644 --- a/doc/transformations.dox +++ b/doc/transformations.dox @@ -27,7 +27,7 @@ namespace Magnum { namespace Math { @brief Introduction to essential operations on vectors and points. - Previous page: @ref matrix-vector -- Next page: @ref scenegraph +- Next page: @ref plugins Transformations are essential operations involved in scene management -- object relations, hierarchies, animations etc. They extend basic vectors and matrices @@ -318,6 +318,6 @@ transformation = transformation.normalized(); @endcode - Previous page: @ref matrix-vector -- Next page: @ref scenegraph +- Next page: @ref plugins */ }} diff --git a/src/Audio/AbstractImporter.h b/src/Audio/AbstractImporter.h index 45b92a3a4..ca0c3ff1b 100644 --- a/src/Audio/AbstractImporter.h +++ b/src/Audio/AbstractImporter.h @@ -38,6 +38,10 @@ namespace Magnum { namespace Audio { /** @brief Base for audio importer plugins +Provides interface for importing various audio formats. See @ref plugins for +more information and `*Importer` classes in @ref Audio namespace for available +importer plugins. + @section Audio-AbstractImporter-subclassing Subclassing Plugin implements function doFeatures(), doIsOpened(), one of or both diff --git a/src/Plugins/MagnumFont/MagnumFont.h b/src/Plugins/MagnumFont/MagnumFont.h index 99fc3de5f..a9e69b1c3 100644 --- a/src/Plugins/MagnumFont/MagnumFont.h +++ b/src/Plugins/MagnumFont/MagnumFont.h @@ -37,11 +37,12 @@ namespace Magnum { namespace Text { @brief Simple bitmap font plugin This plugin depends on @ref Trade::TgaImporter "TgaImporter" plugin and is -built if `WITH_MAGNUMFONT` is enabled in CMake. To use dynamic plugin, you need -to load `%MagnumFont` plugin from `fonts/` subdirectory of your plugin dir. To -use static plugin or use this as a dependency of another plugin, you need to -request `%MagnumFont` component in CMake and link to `${MAGNUM_MAGNUMFONT_LIBRARIES}`. -See @ref building and @ref cmake for more information. +built if `WITH_MAGNUMFONT` is enabled when building %Magnum. To use dynamic +plugin, you need to load `%MagnumFont` plugin from `MAGNUM_PLUGINS_FONT_DIR`. +To use static plugin or use this as a dependency of another plugin, you need to +request `%MagnumFont` component of `%Magnum` package in CMake and link to +`${MAGNUM_MAGNUMFONT_LIBRARIES}`. See @ref building, @ref cmake and +@ref plugins for more information. The font consists of two files, one text file containing character and glyph info and one TGA file containing the glyphs in distance field format. The font diff --git a/src/Plugins/MagnumFontConverter/MagnumFontConverter.h b/src/Plugins/MagnumFontConverter/MagnumFontConverter.h index 808c3be4e..64a074b17 100644 --- a/src/Plugins/MagnumFontConverter/MagnumFontConverter.h +++ b/src/Plugins/MagnumFontConverter/MagnumFontConverter.h @@ -41,12 +41,13 @@ Expects filename prefix, creates two files, `prefix.conf` and `prefix.tga`. See This plugin is available only on desktop OpenGL, as it uses @ref Texture::image() to read back the generated data. It depends on @ref Trade::TgaImageConverter "TgaImageConverter" plugin and is built if -`WITH_MAGNUMFONTCONVERTER` is enabled in CMake. To use dynamic plugin, you need -to load `%MagnumFontConverter` plugin from `fontconverters/` subdirectory of -your plugin dir. To use static plugin or use this as a dependency of another -plugin, you need to request `%MagnumFontConverter` component in CMake and link -to `${MAGNUM_MAGNUMFONTCONVERTER_LIBRARIES}`. See @ref building and @ref cmake -for more information. +`WITH_MAGNUMFONTCONVERTER` is enabled when building %Magnum. To use dynamic +plugin, you need to load `%MagnumFontConverter` plugin from +`MAGNUM_PLUGINS_FONTCONVERTER_DIR`. To use static plugin or use this as a +dependency of another plugin, you need to request `%MagnumFontConverter` +component of `%Magnum` package in CMake and link to +`${MAGNUM_MAGNUMFONTCONVERTER_LIBRARIES}`. See @ref building, @ref cmake and +@ref plugins for more information. */ class MagnumFontConverter: public Text::AbstractFontConverter { public: diff --git a/src/Plugins/TgaImageConverter/TgaImageConverter.h b/src/Plugins/TgaImageConverter/TgaImageConverter.h index 1b5e9e02e..300bb2912 100644 --- a/src/Plugins/TgaImageConverter/TgaImageConverter.h +++ b/src/Plugins/TgaImageConverter/TgaImageConverter.h @@ -51,12 +51,13 @@ namespace Magnum { namespace Trade { Supports images with format @ref ColorFormat::BGR, @ref ColorFormat::BGRA or @ref ColorFormat::Red and type @ref ColorType::UnsignedByte. -This plugin is built if `WITH_TGAIMAGECONVERTER` is enabled in CMake. To use -dynamic plugin, you need to load `%TgaImageConverter` plugin from -`imageconverters/` subdirectory of your plugin dir. To use static plugin or use -this as a dependency of another plugin, you need to request `%TgaImageConverter` -component in CMake and link to `${MAGNUM_TGAIMAGECONVERTER_LIBRARIES}`. See -@ref building and @ref cmake for more information. +This plugin is built if `WITH_TGAIMAGECONVERTER` is enabled when building +%Magnum. To use dynamic plugin, you need to load `%TgaImageConverter` plugin +from `MAGNUM_PLUGINS_IMAGECONVERTER_DIR`. To use static plugin or use this as a +dependency of another plugin, you need to request `%TgaImageConverter` +component of `%Magnum` package in CMake and link to +`${MAGNUM_TGAIMAGECONVERTER_LIBRARIES}`. See @ref building, @ref cmake and +@ref plugins for more information. */ class MAGNUM_TRADE_TGAIMAGECONVERTER_EXPORT TgaImageConverter: public AbstractImageConverter { public: diff --git a/src/Plugins/TgaImporter/TgaImporter.h b/src/Plugins/TgaImporter/TgaImporter.h index dfdcfc5b5..7dc87c3d8 100644 --- a/src/Plugins/TgaImporter/TgaImporter.h +++ b/src/Plugins/TgaImporter/TgaImporter.h @@ -52,12 +52,12 @@ namespace Magnum { namespace Trade { Supports uncompressed BGR, BGRA or grayscale images with 8 bits per channel. -This plugin is built if `WITH_TGAIMPORTER` is enabled in CMake. To use dynamic -plugin, you need to load `%TgaImporter` plugin from `importers/` subdirectory -of your plugin dir. To use static plugin or use this as a dependency of another -plugin, you need to request `%TgaImporter` component in CMake and link to -`${MAGNUM_TGAIMPORTER_LIBRARIES}`. See @ref building and @ref cmake for more -information. +This plugin is built if `WITH_TGAIMPORTER` is enabled when building %Magnum. To +use dynamic plugin, you need to load `%TgaImporter` plugin from +`MAGNUM_PLUGINS_IMPORTER_DIR`. To use static plugin or use this as a dependency +of another plugin, you need to request `%TgaImporter` component of `%Magnum` +package in CMake and link to `${MAGNUM_TGAIMPORTER_LIBRARIES}`. See +@ref building, @ref cmake and @ref plugins for more information. The images are imported with @ref ColorType::UnsignedByte and @ref ColorFormat::BGR, @ref ColorFormat::BGRA or @ref ColorFormat::Red, respectively. Grayscale images diff --git a/src/Plugins/WavAudioImporter/WavImporter.h b/src/Plugins/WavAudioImporter/WavImporter.h index 12fae4634..42365daf5 100644 --- a/src/Plugins/WavAudioImporter/WavImporter.h +++ b/src/Plugins/WavAudioImporter/WavImporter.h @@ -42,12 +42,12 @@ Supports mono and stereo PCM files with 8 or 16 bits per channel. The files are imported with @ref Buffer::Format::Mono8, @ref Buffer::Format::Mono16, @ref Buffer::Format::Stereo8 or @ref Buffer::Format::Stereo16, respectively. -This plugin is built if `WITH_WAVAUDIOIMPORTER` is enabled in CMake. To use -dynamic plugin, you need to load `%WavAudioImporter` plugin from `audioimporters/` -subdirectory of your plugin dir. To use static plugin or or use this as a +This plugin is built if `WITH_WAVAUDIOIMPORTER` is enabled when building +%Magnum. To use dynamic plugin, you need to load `%WavAudioImporter` plugin +from `MAGNUM_PLUGINS_AUDIOIMPORTER_DIR`. To use static plugin or use this as a dependency of another plugin, you need to request `%WavAudioImporter` component -in CMake and link to `${MAGNUM_WAVAUDIOIMPORTER_LIBRARIES}`. See @ref building -and @ref cmake for more information. +of `%Magnum` package in CMake and link to `${MAGNUM_WAVAUDIOIMPORTER_LIBRARIES}`. +See @ref building, @ref cmake and @ref plugins for more information. */ class WavImporter: public AbstractImporter { public: diff --git a/src/Text/AbstractFont.h b/src/Text/AbstractFont.h index a32a7ef70..24d8ecdea 100644 --- a/src/Text/AbstractFont.h +++ b/src/Text/AbstractFont.h @@ -43,6 +43,10 @@ namespace Magnum { namespace Text { /** @brief Base for font plugins +Provides interface for opening fonts, filling glyph cache and layouting the +glyphs. See @ref plugins for more information and `*Font` classes in @ref Text +namespace for available font plugins. + @section AbstractFont-usage Usage First step is to open the font using @ref openData(), @ref openSingleData() or diff --git a/src/Text/AbstractFontConverter.h b/src/Text/AbstractFontConverter.h index efde20b8f..fad9254da 100644 --- a/src/Text/AbstractFontConverter.h +++ b/src/Text/AbstractFontConverter.h @@ -40,7 +40,9 @@ namespace Magnum { namespace Text { /** @brief Base for font converter plugins -Provides functionality for converting arbitrary font to different format. +Provides functionality for converting arbitrary font to different format. See +@ref plugins for more information and `*FontConverter` classes in @ref Text +namespace for available font converter plugins. @section AbstractFontConverter-subclassing Subclassing diff --git a/src/Trade/AbstractImageConverter.h b/src/Trade/AbstractImageConverter.h index b084420c5..2bb7d8e22 100644 --- a/src/Trade/AbstractImageConverter.h +++ b/src/Trade/AbstractImageConverter.h @@ -40,7 +40,8 @@ namespace Magnum { namespace Trade { @brief Base for image converter plugins Provides functionality for converting images between various internal formats -or compressing them. +or compressing them. See @ref plugins for more information and `*ImageConverter` +classes in @ref Trade namespace for available image converter plugins. @section AbstractImageConverter-subclassing Subclassing diff --git a/src/Trade/AbstractImporter.h b/src/Trade/AbstractImporter.h index 2590b284b..baf72f080 100644 --- a/src/Trade/AbstractImporter.h +++ b/src/Trade/AbstractImporter.h @@ -43,8 +43,9 @@ namespace Magnum { namespace Trade { /** @brief Base for importer plugins -Importer is used for importing data like scenes, lights, objects, images, -textures etc. +Provides interface for importing 2D/3D scene, mesh, material, texture and image +data. See @ref plugins for more information and `*Importer` classes in +@ref Trade namespace for available importer plugins. @section AbstractImporter-subclassing Subclassing