mirror of https://github.com/mosra/magnum.git
Vladimír Vondruš
13 years ago
16 changed files with 328 additions and 102 deletions
@ -0,0 +1,205 @@
|
||||
/* |
||||
This file is part of Magnum. |
||||
|
||||
Copyright © 2010, 2011, 2012, 2013 Vladimír Vondruš <mosra@centrum.cz> |
||||
|
||||
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<Trade::AbstractImporter> 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<Trade::AbstractImporter> 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<Trade::AbstractImporter> importerManager(MAGNUM_PLUGINS_IMPORTER_DIR); |
||||
PluginManager::Manager<Text::AbstractFont> 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 |
||||
|
||||
*/ |
||||
} |
||||
Loading…
Reference in new issue